From a811acb956fea28b87338a9c6f1e4900c1198b9b Mon Sep 17 00:00:00 2001 From: Petar Ivanov <29689712+dartdart26@users.noreply.github.com> Date: Tue, 13 Aug 2024 16:58:20 +0300 Subject: [PATCH] docs: add fhevm/fundamentals --- docs/README.md | 2 +- docs/SUMMARY.md | 5 +-- docs/fundamentals/fhevm/architecture.md | 56 +++++++++++++++++++++++++ docs/fundamentals/fhevm/backend.md | 1 - docs/fundamentals/fhevm/contracts.md | 34 ++++++++------- docs/fundamentals/fhevm/execution.md | 51 ++++++++++++++++++++++ docs/fundamentals/fhevm/genesis.md | 10 +++++ docs/fundamentals/fhevm/inputs.md | 45 ++++++++++++++++++++ docs/fundamentals/fhevm/storage.md | 53 +++++++++++++++++++++++ docs/fundamentals/glossary.md | 24 +++++++++-- docs/fundamentals/overview.md | 24 +++++------ 11 files changed, 269 insertions(+), 36 deletions(-) delete mode 100644 docs/fundamentals/fhevm/backend.md diff --git a/docs/README.md b/docs/README.md index 39e8d635..56b9544f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -21,7 +21,7 @@ layout: Learn the basics of fhEVM, set it up, and make it run with ease. -
Quick startUnderstand the basic concepts of fhEVM library.start1.pngquick_start.md
geth integrationUse fhEVM with go-ethereumstart4.pnggeth.md
Setup a GatewayConfigure a Gateway to handle decryption and reecryptionstart2.pngconfiguration.md
Use TKMSUse Zama's KMS with fhEVMstart5.pngzama.md
+
Quick startUnderstand the basic concepts of fhEVM library.start1.pngquick_start.md
geth integrationUse fhEVM with go-ethereumstart4.pnggeth.md
Setup a GatewayConfigure a Gateway to handle decryption and reecryptionstart2.pngconfiguration.md
Use TKMSUse Zama's TKMS with fhEVMstart5.pngzama.md
### References diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 4d6e8e4a..91979c76 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -16,15 +16,14 @@ - [Use Zama's TKMS](getting_started/tkms/zama.md) - [Request the creation of a new private key](getting_started/tkms/create.md) - [Application Smart Contract](getting_started/tkms/contract.md) - - [Run a KMS](getting_started/tkms/run.md) + - [Run a TKMS](getting_started/tkms/run.md) ## Fundamentals -- [Architecture](fundamentals/overview.md) +- [Overview](fundamentals/overview.md) - fhEVM - [Architecture](fundamentals/fhevm/architecture.md) - [Contracts](fundamentals/fhevm/contracts.md) - - [Backend](fundamentals/fhevm/backend.md) - [Execution](fundamentals/fhevm/execution.md) - [Storage](fundamentals/fhevm/storage.md) - [Inputs](fundamentals/fhevm/inputs.md) diff --git a/docs/fundamentals/fhevm/architecture.md b/docs/fundamentals/fhevm/architecture.md index c79bec1a..d4f24a52 100644 --- a/docs/fundamentals/fhevm/architecture.md +++ b/docs/fundamentals/fhevm/architecture.md @@ -1 +1,57 @@ # Architecture + +The following diagram shows an fhEVM-native blockchain with 4 validators. + +```mermaid +graph LR; + Validator1{{Validator1 Node}} + Validator1-- execution API ---Executor1 + Executor1(Executor1) + + Validator2{{Validator2 Node}} + Validator2-- execution API ---Executor2 + Executor2(Executor2) + + Validator3{{Validator3 Node}} + Validator3-- execution API ---Executor3 + Executor3(Executor3) + + Validator4{{Validator4 Node}} + Validator4-- execution API ---Executor4 + Executor4(Executor4) + + FullNode{{Full Node}} + FullNode-- execution API ---ExecutorFull + ExecutorFull(Executor F) + + dApp[dApp] + fhevmjs[fhevmjs] + dApp-- uses ---fhevmjs + fhevmjs-- HTTP ---Gateway + fhevmjs-- RPC ---FullNode + + Gateway(((Gateway))) + Gateway-- TKMS txns, events ---TKMS + Gateway-- RPC/WebSocket ---FullNode + TKMS[[TKMS]] +``` + +_Note:_ For brevity, we don't show P2P connections between validators and the full node in the diagram. + +Each validator has two components: + * the validator node software that executes blocks and connects to other validators over the blockchain's P2P network + * the Executor that is responsible for the actual FHE computation + +The Executor exposes an API that the validator node uses to send FHE computation requests. + +A full node is similar to validators in the sense that it executes all blocks. The difference is that the full node doesn't have stake in the network and, therefore, cannot propose blocks. The full node has all the blockchain data locally. It can be used by the Gateway over RPC or WebSocket endpoints, allowing the Gateway to fetch storage proofs, fetch ciphertexts, listen for events on the fhEVM blockchain, etc. + +The Gateway is a client from the TKMS' perspective and sends decryption/reencryption transactions, listens for "decryption ready" events, etc. + +A dApp uses the **fhevmjs** library to interact with the fhEVM. Some examples are: + * connect over HTTP to the Gateway for reencryptions + * encrypt and decrypt data from the blockchain + * send transactions via a full node + * get the FHE public key from a full node + +The TKMS is used to manage secret FHE key material and securely execute decryptions, reencryptions, key generation, etc. The TKMS is itself a blockchain. See [TKMS](../tkms/architecture.md). diff --git a/docs/fundamentals/fhevm/backend.md b/docs/fundamentals/fhevm/backend.md deleted file mode 100644 index 781894a4..00000000 --- a/docs/fundamentals/fhevm/backend.md +++ /dev/null @@ -1 +0,0 @@ -# Backend diff --git a/docs/fundamentals/fhevm/contracts.md b/docs/fundamentals/fhevm/contracts.md index 49100405..5ffddc1b 100644 --- a/docs/fundamentals/fhevm/contracts.md +++ b/docs/fundamentals/fhevm/contracts.md @@ -1,37 +1,39 @@ # Contracts -The fhEVM runs totally on chain symbolically. Essentially, inputs to FHE operations are symbolic values (also called handles) that refer to ciphertexts. We check constraints on these handles, but ignore their actual values. +The fhEVM employs symbolic execution - essentially, inputs to FHE operations are symbolic values (also called handles) that refer to ciphertexts. We check constraints on these handles, but ignore their actual values. -On the coprocessor, we actually execute the FHE operations on the ciphertexts the handles refer to. If a new ciphertext is generated in the coprocessor as a result of an FHE operation, it is inserted into the blockchain under a handle that is deterministically generated on both the blockchain and the coprocessor. +On the Executor, we actually execute the FHE operations on the ciphertexts the handles refer to. If a new ciphertext is generated in the Executor as a result of an FHE operation, it is inserted into the blockchain (into the ciphertext storage contract, see [Storage](storage.md)) under a handle that is deterministically generated in the TFHEExecutor contract. -## Coprocessor contract +## TFHEExecutor Contract -Symbolic execution on the blockchain is implemented via the [Coprocessor](https://github.com/zama-ai/fhevm/blob/main/lib/TFHEExecutor.sol) contract. One of the main responsibilites of the Coprocessor contract is to deterministically generate ciphertext handles. For this, we hash the FHE operation requested and the inputs to produce the result handle H: +Symbolic execution on the blockchain is implemented via the [TFHEExecutor](https://github.com/zama-ai/fhevm/blob/main/lib/TFHEExecutor.sol) contract. One of the main responsibilites of the TFHEExecutor contract is to deterministically generate ciphertext handles. For this, we hash the FHE operation requested and the inputs to produce the result handle H: ``` -H = keccak256(2, fheOperation, input1, input2, ..., inputN) +H = keccak256(fheOperation, input1, input2, ..., inputN) ``` -We use 2 as a domain separator for result handles. -Note that inputs can either be other handles or plaintext values. as described in FHE Execution and implemented in the newHandle() functions. +Inputs can either be other handles or plaintext values. -## ACL +_Note:_ As of now, TFHEExecutor emloys precompiles and not symbolic execution. It will soon be migrated to symbolic execution. -The [ACL](https://github.com/zama-ai/fhevm/blob/main/lib/ACL.sol) Contract enforces access control for ciphertexts. The model we adopt is very simple - a ciphertext is either allowed for an address or not. An address can be any address - either an EOA address or a contract address. We implement that via the pairs member variable. Essentially, it is a set of keccak256(handle, address) values, where the handle refers to a ciphertext. If a (handle, address) pair is in the set, the ciphertext the handle refers to can be used by the address. In Solidity, we implement the set as a mapping such that all values already in the mapping are true. Access control applies to both passing ciphertexts from one contract to another, for decryption and for reencryption of a ciphertext to a user-provided key. +## ACL Contract -We use keccak256(handle, address) in order to both save space by persisting only one value instead of two and, also, to allow for a single storage slot proof for reencryption. +The [ACL](https://github.com/zama-ai/fhevm/blob/main/lib/ACL.sol) contract enforces access control for ciphertexts. The model we adopt is very simple - a ciphertext is either allowed for an address or not. An address can be any address - either an EOA address or a contract address. Essentially, it is a mapping from handle to a set of addresses that are allowed to use the handle. + +Access control applies to passing ciphertexts from one contract to another, for FHE computation on ciphertexts, for decryption and for reencryption of a ciphertext to a user-provided key. ### Garbage Collection of Allowed Ciphertexts Data -The pairs field in the ACL contract grows indefinitely as new ciphertexts are produced. We might want to expose ways for developers to reclaim space by marking that certain ciphertexts are no longer needed and, consequently, zeroing the slot in pairs. A future effort will look into that. +Data in the ACL contract grows indefinitely as new ciphertexts are produced. We might want to expose ways for developers to reclaim space by marking that certain ciphertexts are no longer needed and, consequently, zeroing the slot in the ACL. A future effort will look into that. + +## Gateway Contract -## Gateway contract +The [Gateway](https://github.com/zama-ai/fhevm/blob/main/gateway/GatewayContract.sol) contract is an onchain contract designed to interact with an offchain Gateway component that handles decryption requests. When a dApp calls the `requestDecryption` function, the Gateway contract emits an event that is caught by the Gateway service. -The [Gateway](https://github.com/zama-ai/fhevm/blob/main/gateway/GatewayContract.sol) contract is an on-chain contract designed to interact with an off-chain oracle that handles decryption requests. When a dApp calls the `requestDecryption` function, the contract emits an event that is caught by the Gateway service. -Note: It is possible to have multiple Gateways, so multiple Gateway contracts can also be deployed. +_Note_: It is possible to have multiple Gateways, so multiple Gateway contracts can also be deployed. -## KMSVerifier contract +## KMSVerifier Contract -The [KMSVerifier](https://github.com/zama-ai/fhevm/blob/main/lib/KMSVerifier.sol) contract allows any dapp to verify a received decryption. This contract exposes a function `verifySignatures` which receives the decryption and signatures coming from the KMS. +The [KMSVerifier](https://github.com/zama-ai/fhevm/blob/main/lib/KMSVerifier.sol) contract allows any dApp to verify a received decryption. This contract exposes a function `verifySignatures` which receives the decryption and signatures coming from the TKMS. Verifier addresses are stored and updated in the contract. diff --git a/docs/fundamentals/fhevm/execution.md b/docs/fundamentals/fhevm/execution.md index a2e753b6..3ef866e4 100644 --- a/docs/fundamentals/fhevm/execution.md +++ b/docs/fundamentals/fhevm/execution.md @@ -1 +1,52 @@ # Execution + +Block execution in fhEVM-native is split into two parts: + * symbolic execution + * FHE computation + +Symbolic execution happens onchain, inside the TFHEExecutor contract (inside the EVM). Essentially, the EVM accumulates all requested FHE operations in a block with their input handles and the corresponding result handles. It also remembers which result handles are stored via the SSTORE opcode. No FHE computations are done inside the EVM itself. + +At the end of the block, the EVM sends a networking call to the Executor with the accumulated FHE computations. The Executor is free to do the FHE computations via any method, e.g. in parallel, on a cluster of compute nodes, via CPUs, GPUs, FPGAs or ASICs. The EVM waits until FHE computation for the block is done. + +Finally, when results are returned to the EVM, it persists onchain the ciphertexts whose handles have been SSTOREd during symbolic execution. That way the EVM can avoid persisting ciphertexts that are intermediate results and are never actually stored by the smart contract developer. + +```mermaid +sequenceDiagram + participant Node + participant Executor + + loop Block Execution - Symbolic + Note over Node: Symbolic Execution on handles in Solidity + Note over Node: Inside EVM: computations.add(op, [inputs], [result_handles], [input_ciphertexts]) + Note over Node: Inside EVM: if SSTORE(location, result) then sstored.add(result) + end + + Note over Node: End of Block Execution + Node->>+Executor: SyncCompute (SyncComputeRequest(computations)) + loop FHE Computation + Note over Executor: Read Inputs from SyncComputeRequest + Note over Executor: FHE Computation + end + Executor->>-Node: SyncComputeResponse (results) + + Note over Node: Persist `sstored` Ciphertexts from `results` onchain + Note over Node: Commit Block +``` + +## Symbolic Execution + +As mentioned, symbolic execution doesn't do any FHE computations. Instead, it only operates on input handles, checking constraints on them and deterministically producing result handles based on the input ones. + +For more information on what symbolic execution does, please look at the [TFHEExecutor](https://github.com/zama-ai/fhevm/blob/main/lib/TFHEExecutor.sol) contract. + +## Interaction with the TFHEExecutor Contract + +The TFHEExecutor contract is deployed when the chain is created and is at a well-known address that is also known by blockchain nodes. When a node (validator or full node) detects a call to this address (a CALL or STATITCCALL opcode), the EVM running in the node looks at the function signature and determines which FHE computation is being requested. The result handle is the result of this particular call to the TFHEExecutor contract and the EVM can accumulate it in the computations list for the block. + +## FHE Computation Data Dependencies + +Note that the EVM sends both input handles and result handles to the Executor. It is able to do that, because result handles are computed symbolically in the TFHEExecutor contract. That allows the Executor to do parallel FHE computation by analysing which computations are independent. + +The Executor can detect a conflict if an output of computation A (or the output of another computation depending on the output of A) is also used as an input in a subsequent computation B. We call these computations `dependent` and we need to execute them in order. + +On the other hand, if two computations have inputs that are not related to their outputs, we call them `independent` and the Executor can schedule them to run in parallel. diff --git a/docs/fundamentals/fhevm/genesis.md b/docs/fundamentals/fhevm/genesis.md index 3b3fdac9..f92eb354 100644 --- a/docs/fundamentals/fhevm/genesis.md +++ b/docs/fundamentals/fhevm/genesis.md @@ -1 +1,11 @@ # Genesis + +## Contracts + +For an fhEVM-native blockchain to operate and execute FHE computations, certain contracts need to be available when creating the chain - see [Contracts](contracts.md). Strictly speaking, these contracts don't have to be available in the genesis block and can be deployed in the second block of the chain, at runtime. + +## Keys + +FHE-related keys need to available for the chain to operate properly. For example, a public FHE execution key is needed at the Executor to be able to compute on encrypted data. + +As a convenience, the FHE public key can also be stored on validators/full nodes. diff --git a/docs/fundamentals/fhevm/inputs.md b/docs/fundamentals/fhevm/inputs.md index 345ade04..297c0a43 100644 --- a/docs/fundamentals/fhevm/inputs.md +++ b/docs/fundamentals/fhevm/inputs.md @@ -1 +1,46 @@ # Inputs + +When we talk about inputs, we refer to encrypted data the users send to the fhEVM-native blockchain. Data is in the form of FHE ciphertexts. An example would be the amount to be transferred when calling an ERC20 transfer function. + +## ZKPoK +It is important that confidential data sent by users cannot be seen by anyone. Without measures, there are multiple ways that could happen, for example: + * anyone decrypting the ciphertext + * anyone doing arbitrary computations via the ciphertext (e.g. adding 0 to it), producing a new ciphertext that itself is decrypted (including malicious actors using ciphertexts of other users) + * using the ciphertext in a malicious contract that leads to decryption + +Furthermore, if users are allowed to send arbitrary ciphertexts (including malformed ones or maliciously-crafted ones), that could lead to revealing data about the FHE secret key. + +Therefore, we employ zero-knowledge proofs of knowledge (ZKPoK) of input FHE ciphertexts that guarantee: + +* ciphertext is well-formed (i.e. encryption has been done correctly) +* the user knows the plaintext value +* the input ciphertext can only be used in a particular smart contract + +The ZKPoK is verified by validator nodes when the input byte array is passed to an `TFHE.asEuintXX()` function to convert from a ciphertext to a handle that can be used in smart contracts for FHE operations. + +## Compact Input Lists + +To greatly reduce the size of FHE ciphertexts inputs, we utilize a feature called compact lists. It allows us to pack multiple values efficiently. It is useful when there is only one input and even more so when the are multiple inputs in a call to a smart contract. + +We define the `einput` type that refers to a particular ciphertext in the list. The list itself is serialized and passed as a byte array. For example, `inputA` and `inputB` refer to ciphertexts in the list and the serialized list is `inputProof`: + +```solidity +// SPDX-License-Identifier: BSD-3-Clause-Clear + +pragma solidity ^0.8.24; + +import "fhevm/lib/TFHE.sol"; + +contract Adder { + euint32 result; + + function add(einput inputA, einput inputB, bytes calldata inputProof) public { + euint32 a = TFHE.asEuint32(inputA, inputProof); + euint32 b = TFHE.asEuint32(inputB, inputProof); + result = TFHE.add(a, b); + TFHE.allow(result, address(this)); + } +} +``` + +Note that `inputProof` also contains the ZKPoK. diff --git a/docs/fundamentals/fhevm/storage.md b/docs/fundamentals/fhevm/storage.md index e0e8ac41..c0595c0f 100644 --- a/docs/fundamentals/fhevm/storage.md +++ b/docs/fundamentals/fhevm/storage.md @@ -1 +1,54 @@ # Storage + +Ciphertexts in fhEVM-native are stored onchain in the storage of a predefined contract that has no code and is used just for ciphertexts. At the time of writing, its address is **0x5e**. + +Contract storage in the EVM is a key-value store. For ciphertexts, we use the handle as a key and the value is the actual ciphertext. + +Furthermore, stored ciphertexts are immutable, making ciphertext storage append-only. + +Ciphertexts can be read by anyone. We expose the `GetCiphertext` function on the `FheLib` precompiled contract. Nodes/validators must support it. + +## GetCiphertext Function (selector: ff627e77) + +The `GetCiphertext` function returns a serialized TFHE ciphertext given: + * the ebool/e(u)int value (also called a handle) for which the ciphertext is requested + +GetCiphertext only works via the `eth_call` RPC. + +To call GetCiphertext via `eth_call`, the following Python can serve as an example: + +```python +import http.client +import json + +# This is the address of the FheLib precompile. This value is hardcoded per blockchain. +fhe_lib_precompile_address = "0x000000000000000000000000000000000000005d" + +# The ebool/e(u)int value for which the ciphertext is requested. +handle = "f038cdc8bf630e239f143abeb039b91ec82ec17a8460582e7a409fa551030c06" + +# The function selector of GetCiphertext. +get_ciphertext_selector = "ff627e77" + +# Call the FheLib precompile with `data` being the handle to the ciphertext. +payload = { + "jsonrpc": "2.0", + "method": "eth_call", + "params": [ + { + "to": fhe_lib_precompile_address, + "data": "0x" + handle + }, + "latest" + ], + "id": 1, +} + +con = http.client.HTTPConnection("localhost", 8545) +con.request("POST", "/", body=json.dumps(payload), + headers={"Content-Type": "application/json"}) +resp = json.loads(con.getresponse().read()) + +# Remove leading "0x" and decode hex to get a byte buffer with the ciphertext. +ciphertext = bytes.fromhex(resp["result"][2:]) +``` \ No newline at end of file diff --git a/docs/fundamentals/glossary.md b/docs/fundamentals/glossary.md index 26c739cd..2b6e441f 100644 --- a/docs/fundamentals/glossary.md +++ b/docs/fundamentals/glossary.md @@ -1,14 +1,32 @@ # Glossary +- _Executor_: A component that runs alongside the fhEVM blockchain node/validator and does the FHE computation. The node/validator and the Executor communicate over a network connection. + +- _FheLib_: A precompiled contract that is available on nodes/validators. Exposes a number of functions, e.g. getting ciphertexts, verifying inputs, etc. At the time of writing, it exists at address **0x000000000000000000000000000000000000005d**. + +- _fhevmjs_: A JavaScript library that allows dApps to interact with the fhEVM. + +- _handle_: A handle refers to (or is a pointer to) a ciphertext in the fhEVM. A handle uniquely refers to a single ciphertext from the user's perspective. + +- _KMS_: Key Management Service. Used for managing secret FHE key material. + +- _Symbolic Execution_: Onchain execution where inputs to FHE operations are symbolic values (also called handles) that refer to ciphertexts. We check constraints on these handles, but ignore their actual values. + +- _TFHE_: An Fully Homomorphic Encryption scheme used in fhEVM and TKMS. + +- _TKMS_: Threshold Key Management Service. Uses threshold cryptography and multi-party computation. See _KMS_. + +- _ZKPoK_: Zero-knowledge proof of knowledge of an input FHE ciphertext. + ## Smart Contracts ### fhEVM -- _ACL smart contract_: Smart contract deployed on the fhEVM blockchain to manage access control of ciphertexts. dApp contracts use this to persists their own access rights and to delegate access to other contracts. +- _ACL Smart Contract_: Smart contract deployed on the fhEVM blockchain to manage access control of ciphertexts. dApp contracts use this to persists their own access rights and to delegate access to other contracts. -- _Gateway smart contract_: Smart contract deployed on the fhEVM blockchain that is used by a dApp smart contract to request a decrypt. This emits an event that triggers the gateway. +- _Gateway Smart Contract_: Smart contract deployed on the fhEVM blockchain that is used by a dApp smart contract to request a decrypt. This emits an event that triggers the gateway. -- _KMS smart contract_: Smart contract running on the fhEVM blockchain that is used by a dApp contract to verify decryption results from the KMS. To that end, it contains the identity of the KMS and is used to verify its signatures. +- _KMS Smart Contract_: Smart contract running on the fhEVM blockchain that is used by a dApp contract to verify decryption results from the TKMS. To that end, it contains the identity of the TKMS and is used to verify its signatures. ### TKMS diff --git a/docs/fundamentals/overview.md b/docs/fundamentals/overview.md index cf40416a..abda39a0 100644 --- a/docs/fundamentals/overview.md +++ b/docs/fundamentals/overview.md @@ -1,32 +1,32 @@ # Overview -At the highest level, the system consists of two subsystems: an fhEVM blockchain and a KMS. +At the highest level, the system consists of two subsystems: an fhEVM blockchain and a TKMS. -An fhEVM blockchain consists of a set of validator nodes running a coprocessor, a configuration referred to as _fhEVM native_. A Key Management System (KMS) is a component that integrates a blockchain as the communication layer and a threshold protocol to handle decryption and reencryption. +An fhEVM blockchain consists of a set of validator nodes with each one running an **Executor**, a configuration referred to as _fhEVM-native_. A Threshold Key Management System (TKMS) is a component that runs a blockchain as a communication layer for a threshold protocol to manage the secret FHE key and handle decryption and reencryption. -These two systems are not directly connected; instead, a component called a gateway handles communication between them. +These two subsystems are not directly connected; instead, a component called a **Gateway** handles communication between them. ![Overview](../assets/overview.png) ## fhEVM -A blockchain using fhEVM processes all transactions, including those involving operations on encrypted data types. These transactions are symbolically executed, meaning that any operation on these encrypted types returns a new handle. A handle can be seen as a pointer to a ciphertext, similar to an identifier. After the transactions are executed, the coprocessor performs the operations on the ciphertexts, and the results are stored on-chain. +A blockchain using fhEVM processes all transactions, including those involving operations on encrypted data types. Operations on encrypted data are executed symbolically, meaning that the actual FHE computation is not done - instead, only constraints on symbolic inputs (handles) are checked and the returned result is just a new handle. A handle can be seen as a pointer to a ciphertext, similar to an identifier. After the operations are executed symbolically, the Executor performs the actual FHE computation on the ciphertexts and, if a result handle is stored in a smart contract, the corresponding result ciphertext is stored on-chain. -An fhEVM validator doesn't own the private key; instead, they have a _bootstrap key_ that allows them to perform computations on ciphertext. This key does not permit any node to decrypt anything. +An fhEVM validator doesn't have access to the secret FHE key; instead, it has a _bootstrap key_ that allows it to perform computations on ciphertexts. The bootstrap key itself does not allow any validotor to decrypt any ciphertexts (the secret FHE key is managed by the TKMS). ## Gateway -The Gateway handles the decryption and the reencryption process. +The Gateway takes part in decryption and the reencryption, interacting with both the fhEVM and the TKMS. -- A decryption can be requested from a smart contract. In this case, the Gateway acts as an Oracle: the dApp calls the Gateway contract with the necessary materials for decryption. The contract will then emit an event that is monitored by the Gateway service. +- A decryption can be requested from any smart contract. In this case, the Gateway acts as an Oracle: the dApp calls the Gateway contract with the necessary materials for decryption. The Gateway contract will then emit an event that is monitored for by the Gateway service. -- A user can directly request a reencryption through a HTTP call. In this case, the Gateway acts as a web2 service: the user provides a public key for the reencryption, a signature, and the handle of the ciphertext to be reencrypted. +- A user can directly request a reencryption through an HTTP call. In this case, the Gateway acts as a Web2 service: the user provides a public key for the reencryption, a signature, and the handle of the ciphertext to be reencrypted. -The Gateway will then emit a transaction on the KMS blockchain, which serves as the communication layer, to request the decryption or reencryption. When the KMS responds with a transaction, the Gateway will transmit the decryption either through a callback function on-chain or the reencryption directly by responding synchronously to the HTTP call. +The Gateway sends transactions to the TKMS blockchain, which serves as the communication layer, to request the decryption or reencryption. When the TKMS responds with a TKMS blockchain event, the Gateway will transmit the decryption either through a Solidity callback function on-chain (on the fhEVM blockchain) or the reencryption by responding synchronously to the HTTP call from the user. -The gateway is designed not to be required to be trusted, thus a malicious gateway will not be able to compromise correctness or privacy of the system, but at most be able to block requests and responses between the fhEVM and the TKMS. However, this can be prevented by simply deploying multiple gateways. +The Gateway is not a trusted party, meaning that a malicious Gateway will not be able to compromise correctness or privacy of the system. At most, it would be able to ignore requests between the fhEVM and the TKMS, impacting the liveness of decryption and reencryption. However, that can be prevented by deploying multiple Gateways and assuming at least one is honest. -## (T)KMS +## TKMS The TKMS is a full key management solution for TFHE, more specifically [TFHE-rs](https://github.com/zama-ai/tfhe-rs), based on a maliciously secure and robust [MPC Protocol](https://eprint.iacr.org/2023/815). -It leverages a blockchain as its communication layer and utilizes a threshold protocol to manage decryption and reencryption requests securely. When a decryption or reencryption is requested, the TKMS processes the request using its cryptographic mechanisms, ensuring that no single entity has access to the full decryption key. Instead, the decryption or reencryption is carried out in a distributed manner, which enhances security by minimizing the risk of key exposure. +It leverages a blockchain as its communication layer and utilizes a threshold protocol to manage decryption and reencryption requests securely. When a decryption or reencryption is requested, the TKMS processes the request using its cryptographic mechanisms, ensuring that no single entity has access to the full decryption (FHE secret) key. Instead, the decryption or reencryption is carried out in a distributed manner, which enhances security by minimizing the risk of key exposure.