Merge pull request #4 from zama-ai/docs/fhevm

docs: add overview

README.md

@@ -0,0 +1,109 @@
+<p align="center">
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://github.com/zama-ai/fhevm/assets/157474013/b07e7e65-12b2-4048-b5de-35e169ed96e4">
+  <source media="(prefers-color-scheme: light)" srcset="https://github.com/zama-ai/fhevm/assets/157474013/c0fab5b1-adef-4db4-9607-fa0a793acaf8">
+  <img width=600 alt="Zama fhEVM">
+</picture>
+</p>
+
+<!-- markdown-link-check-disable -->
+
+<hr/>
+
+<p align="center">
+<a href="https://github.com/zama-ai/fhevm/blob/main/fhevm-whitepaper.pdf"> 📃 Read white paper</a> |<a href="https://docs.zama.ai/fhevm-backend"> 📒 Documentation</a> | <a href="https://zama.ai/community"> 💛 Community support</a> | <a href="https://github.com/zama-ai/awesome-zama"> 📚 FHE resources by Zama</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/zama-ai/fhevm/releases">
+    <img src="https://img.shields.io/github/v/release/zama-ai/fhevm?style=flat-square"></a>
+  <a href="https://github.com/zama-ai/fhevm/blob/main/LICENSE">
+    <!-- markdown-link-check-disable-next-line -->
+    <img src="https://img.shields.io/badge/License-BSD--3--Clause--Clear-%23ffb243?style=flat-square"></a>
+  <a href="https://github.com/zama-ai/bounty-program">
+    <!-- markdown-link-check-disable-next-line -->
+    <img src="https://img.shields.io/badge/Contribute-Zama%20Bounty%20Program-%23ffd208?style=flat-square"></a>
+  <a href="https://slsa.dev"><img alt="SLSA 3" src="https://slsa.dev/images/gh-badge-level3.svg" /></a>
+</p>
+
+### 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 [email protected].
+
+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!
+<br></br>
+
+### License
+
+This software is distributed under the **BSD-3-Clause-Clear** license. Read [this](LICENSE) for more details.
+
+#### FAQ
+
+**Is Zama’s technology free to use?**
+
+> Zama’s libraries are free to use under the BSD 3-Clause Clear license only for development, research, prototyping, and experimentation purposes. However, for any commercial use of Zama's open source code, companies must purchase Zama’s commercial patent license.
+>
+> Everything we do is open source and we are very transparent on what it means for our users, you can read more about how we monetize our open source products at Zama in [this blog post](https://www.zama.ai/post/open-source).
+
+**What do I need to do if I want to use Zama’s technology for commercial purposes?**
+
+> To commercially use Zama’s technology you need to be granted Zama’s patent license. Please contact us at [email protected] for more information.
+
+**Do you file IP on your technology?**
+
+> Yes, all Zama’s technologies are patented.
+
+**Can you customize a solution for my specific use case?**
+
+> We are open to collaborating and advancing the FHE space with our partners. If you have specific needs, please email us at [email protected].
+
+<p align="right">
+  <a href="#table-of-contents" > ↑ Back to top </a>
+</p>
+
+## Support
+
+<a target="_blank" href="https://community.zama.ai">
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://github.com/zama-ai/fhevm/assets/157474013/e249e1a8-d724-478c-afa8-e4fe01c1a0fd">
+  <source media="(prefers-color-scheme: light)" srcset="https://github.com/zama-ai/fhevm/assets/157474013/a72200cc-d93e-44c7-81a8-557901d8798d">
+  <img alt="Support">
+</picture>
+</a>
+
+🌟 If you find this project helpful or interesting, please consider giving it a star on GitHub! Your support helps to grow the community and motivates further development.
+
+<p align="right">
+  <a href="#about" > ↑ Back to top </a>
+</p>

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

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.

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.
+
 ![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.
+
+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.

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)

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/).