+
+
+ 📃 Read white paper | 📒 Documentation | 💛 Community support | 📚 FHE resources by Zama +
+ + + +### Documentation + +Full, comprehensive documentation is available here: [https://docs.zama.ai/fhevm-backend](https://docs.zama.ai/fhevm-backend). + +### Citations + +To cite fhEVM or the whitepaper in academic papers, please use the following entries: + +```text +@Misc{fhEVM, +title={{Private smart contracts on the EVM using homomorphic encryption}}, +author={Zama}, +year={2023}, +note={\url{https://github.com/zama-ai/fhevm}}, +} +``` + +```text +@techreport{fhEVM, +author = "Morten Dahl, Clément Danjou, Daniel Demmler, Tore Frederiksen, Petar Ivanov, +Marc Joye, Dragos Rotaru, Nigel Smart, Louis Tremblay Thibault +", +title = "Confidential EVM Smart Contracts using Fully Homomorphic Encryption", +institution = "Zama", +year = "2023" +} +``` + +### Contributing + +There are two ways to contribute to the Zama fhEVM: + +- [Open issues](https://github.com/zama-ai/fhevm-backend/issues/new/choose) to report bugs and typos, or to suggest new ideas +- Request to become an official contributor by emailing hello@zama.ai. + +Becoming an approved contributor involves signing our Contributor License Agreement (CLA)). Only approved contributors can send pull requests, so please make sure to get in touch before you do! ++ ↑ Back to top +
+ +## Support + + ++ ↑ Back to top +
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 58a5968b..4d6e8e4a 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -28,7 +28,6 @@ - [Execution](fundamentals/fhevm/execution.md) - [Storage](fundamentals/fhevm/storage.md) - [Inputs](fundamentals/fhevm/inputs.md) - - [Data Availability Layer](fundamentals/fhevm/dal.md) - [Genesis](fundamentals/fhevm/genesis.md) - Gateway - [Decryption](fundamentals/gateway/decryption.md) @@ -44,7 +43,7 @@ ## Guides -- [Node hardware](guides/hardware.md) +- [Node and gateway hardware](guides/hardware.md) - [Run a benchmark](guides/benchmark.md) ## References diff --git a/docs/fundamentals/fhevm/contracts.md b/docs/fundamentals/fhevm/contracts.md index 97404c22..49100405 100644 --- a/docs/fundamentals/fhevm/contracts.md +++ b/docs/fundamentals/fhevm/contracts.md @@ -1 +1,37 @@ # 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. + +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. + +## Coprocessor 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: + +``` +H = keccak256(2, 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. + +## ACL + +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. + +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. + +### 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. + +## Gateway contract + +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. + +## 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. + +Verifier addresses are stored and updated in the contract. diff --git a/docs/fundamentals/fhevm/dal.md b/docs/fundamentals/fhevm/dal.md deleted file mode 100644 index 536f5e14..00000000 --- a/docs/fundamentals/fhevm/dal.md +++ /dev/null @@ -1 +0,0 @@ -# Data Availability Layer diff --git a/docs/fundamentals/overview.md b/docs/fundamentals/overview.md index 7ecd9cf0..cf40416a 100644 --- a/docs/fundamentals/overview.md +++ b/docs/fundamentals/overview.md @@ -1,3 +1,32 @@ # Overview +At the highest level, the system consists of two subsystems: an fhEVM blockchain and a KMS. + +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. + +These two systems are not directly connected; instead, a component called a gateway handles communication between them. +  + +## 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. + +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. + +## Gateway + +The Gateway handles the decryption and the reencryption process. + +- 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 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. + +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 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. + +## (T)KMS + +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. diff --git a/docs/getting_started/quick_start.md b/docs/getting_started/quick_start.md index 754bef8a..d7e50c8a 100644 --- a/docs/getting_started/quick_start.md +++ b/docs/getting_started/quick_start.md @@ -1 +1,3 @@ # Quick start + +To start the setup, you can use our [demo repository](https://github.com/zama-ai/fhevm-L1-demo) diff --git a/docs/guides/hardware.md b/docs/guides/hardware.md index 84abdd13..3b74ca85 100644 --- a/docs/guides/hardware.md +++ b/docs/guides/hardware.md @@ -1 +1,9 @@ -# Node hardware +# Node and gateway hardware + +## fhEVM validator + +Validators perform all operations on ciphertext, which requires powerful machines. FHE computations benefit from multi-threading, so we recommend using [hpc7a](https://aws.amazon.com/fr/ec2/instance-types/hpc7a/) instances or equivalent, with at least 48 physical cores. + +## Gateway + +The gateway can run on a medium machine with 4 cores and 8 GB of RAM, such as a [t3.xlarge](https://aws.amazon.com/fr/ec2/instance-types/t3/).
