zama-ai · poppyseedDev · Nov 29, 2024 · Nov 20, 2024 · Nov 21, 2024 · Nov 22, 2024
diff --git a/docs/.gitbook/assets/architecture.png b/docs/.gitbook/assets/architecture.png
diff --git a/docs/fundamentals/asyncDecrypt.png → docs/.gitbook/assets/asyncDecrypt.png b/docs/fundamentals/asyncDecrypt.png → docs/.gitbook/assets/asyncDecrypt.png
diff --git a/docs/.gitbook/assets/computation.png b/docs/.gitbook/assets/computation.png
diff --git a/docs/.gitbook/assets/decryption.png b/docs/.gitbook/assets/decryption.png
diff --git a/docs/.gitbook/assets/encrypt.png b/docs/.gitbook/assets/encrypt.png
diff --git a/docs/.gitbook/assets/keys_fhe.png b/docs/.gitbook/assets/keys_fhe.png
diff --git a/docs/.gitbook/assets/reencryption.png b/docs/.gitbook/assets/reencryption.png
diff --git a/docs/README.md b/docs/README.md
@@ -27,7 +27,7 @@ Learn the basics of fhEVM, set it up, and make it run with ease.
 
 Start developing fhEVM smart contracts in Solidity by exploring its core features, discovering essential guides, and learning more with user-friendly tutorials.
 
-<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><strong>Fundamentals</strong></td><td>Explore core features.</td><td><ul><li><a href="getting_started/write_contract/">Write contract</a></li><li><a href="fundamentals/types/README.md">Use encrypted types</a></li></ul></td><td><a href=".gitbook/assets/build1.png">build1.png</a></td></tr><tr><td><strong>Guides</strong></td><td>Deploy your project.</td><td><ul><li><a href="guides/gas.md">Gas estimation</a></li><li><a href="guides/pitfalls.md">Common pitfalls and best practices</a></li></ul></td><td><a href=".gitbook/assets/build2.png">build2.png</a></td></tr><tr><td><strong>Tutorials</strong></td><td>Learn more with tutorials.</td><td><ul><li><a href="tutorials/see-all-tutorials.md#start-here">Start here</a></li><li><a href="tutorials/see-all-tutorials.md#go-further">Go further</a></li></ul></td><td><a href=".gitbook/assets/build3.png">build3.png</a></td></tr></tbody></table>
+<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><strong>Fundamentals</strong></td><td>Explore core features.</td><td><ul><li><a href="getting_started/write_contract/">Write contract</a></li><li><a href="fundamentals/first_step/types.md">Use encrypted types</a></li></ul></td><td><a href=".gitbook/assets/build1.png">build1.png</a></td></tr><tr><td><strong>Guides</strong></td><td>Deploy your project.</td><td><ul><li><a href="guides/gas.md">Gas estimation</a></li><li><a href="guides/pitfalls.md">Common pitfalls and best practices</a></li></ul></td><td><a href=".gitbook/assets/build2.png">build2.png</a></td></tr><tr><td><strong>Tutorials</strong></td><td>Learn more with tutorials.</td><td><ul><li><a href="tutorials/see-all-tutorials.md#start-here">Start here</a></li><li><a href="tutorials/see-all-tutorials.md#go-further">Go further</a></li></ul></td><td><a href=".gitbook/assets/build3.png">build3.png</a></td></tr></tbody></table>
 
 ## Explore more
 
@@ -38,7 +38,7 @@ Access to additional resources and join the Zama community.
 Refer to the API and access additional resources for in-depth explanations while working with fhEVM.
 
 - [API function specifications](references/functions.md)
-- [Repositories](references/repositories.md)
+- [Repositories](getting_started/repositories.md)
 
 ### Supports
 

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -4,55 +4,59 @@
 
 ## Getting Started
 
-- [What is fhEVM](getting_started/overview.md)
-- Write contract
+- [Quick overview](getting_started/overview.md)
+  - [Key concepts and features](getting_started/key_concepts.md)
+  - [Repositories](getting_started/repositories.md)
+  - [Whitepaper](https://github.com/zama-ai/fhevm/blob/main/fhevm-whitepaper.pdf)
+- [Get started](getting_started/ethereum.md)
+- [Create a smart contract]()
   - [Using Hardhat](getting_started/write_contract/hardhat.md)
   - [Using Remix](getting_started/write_contract/remix.md)
   - [Other development environment](getting_started/write_contract/others.md)
-  - [Installing packages](getting_started/write_contract/installation.md)
-- [Deploy on fhEVM native](getting_started/devnet.md)
-- [Deploy on Ethereum](getting_started/ethereum.md)
-- [Whitepaper](https://github.com/zama-ai/fhevm/blob/main/fhevm-whitepaper.pdf)
 
 ## Fundamentals
 
-- Encrypted types
-  - [Supported types](fundamentals/types/README.md)
-  - [Operations on encrypted types](fundamentals/types/operations.md)
-  - [Branching in FHE](fundamentals/types/conditions.md)
-  - [Generate random number](fundamentals/types/random.md)
-- [Encrypted inputs](fundamentals/inputs.md)
-- [Access Control List](fundamentals/acl.md)
-- [Decrypt and reencrypt](fundamentals/decrypt.md)
-- [Contracts standard library](fundamentals/contracts.md)
+- [Architecture overview](fundamentals/architecture_overview.md)
+  - [Encryption, decryption, re-encryption, and computation](fundamentals/d_re_ecrypt_compute.md)
+  - [Access control list](fundamentals/acl.md)
+- [Configuration](fundamentals/first_step/configure.md)
+  - [First smart contract](fundamentals/first_step/start.md)
+  - [Supported types](fundamentals/first_step/types.md)
+  - [Operations on encrypted types](fundamentals/first_step/operations.md)
+  - [Encryption](fundamentals/first_step/inputs.md)
+  - [Decryption](fundamentals/first_step/decrypt.md)
+  - [Decryption in depth](fundamentals/first_step/decrypt_details.md)
+  - [Reencryption](fundamentals/first_step/reencryption.md)
+  - [ACL examples](fundamentals/first_step/acl_examples.md)
 
 ## Guides
 
-- [Decryption](guides/decrypt.md)
-- [Reencryption](guides/reencryption.md)
-- [Build a web application](guides/webapp.md)
-- [Build with Node](guides/node.md)
-- [Common pitfalls and best practises](guides/pitfalls.md)
-- [How can I break a loop ?](guides/loop.md)
-- [Gas estimation on devnet](guides/gas.md)
-- [Use the CLI](guides/cli.md)
-- [Common webpack errors](guides/webpack.md)
+- Smart Contracts
+  - [Common pitfalls and best practises](guides/pitfalls.md)
+  - [If sentances](guides/loop.md)
+  - [Branching in FHE](guides/conditions.md)
+  - [Generate random numbers](guides/random.md)
+  - [Gas estimation on devnet](guides/gas.md)
+  - [Error handling](guides/error_handling.md)
+- Frontend
+  - [Build a web application](guides/frontend/webapp.md)
+  - [Build with Node](guides/frontend/node.md)
+  - [Using the CLI](guides/frontend/cli.md)
+  - [Common webpack errors](guides/frontend/webpack.md)
 
 ## Tutorials
 
 - [See all tutorials](tutorials/see-all-tutorials.md)
-- [Write confidential smart contract with fhEVM](https://www.zama.ai/post/video-tutorial-how-to-write-confidential-smart-contracts-using-zamas-fhevm)
 
 ## References
 
-- [API function specifications](references/functions.md)
-- [fhevmjs function specifications](references/fhevmjs.md)
-- [Repositories](references/repositories.md)
+- [Smart contracts - fhEVM API](references/functions.md)
+- [Frontend - fhevmjs lib](references/fhevmjs.md)
 
 ## Developer
 
 - [Contributing](developer/contribute.md)
 - [Development roadmap](developer/roadmap.md)
 - [Release note](https://github.com/zama-ai/fhevm/releases)
-- [Feature request](https://github.com/zama-ai/fhevm/issues/new)
-- [Bug report](https://github.com/zama-ai/fhevm/issues/new)
+- [Feature request](https://github.com/zama-ai/fhevm/issues/new?assignees=&labels=enhancement&projects=&template=feature-request.md&title=)
+- [Bug report](https://github.com/zama-ai/fhevm/issues/new?assignees=&labels=bug&projects=&template=bug_report_fhevm.md&title=)
diff --git a/docs/developer/contribute.md b/docs/developer/contribute.md
@@ -6,3 +6,9 @@ There are two ways to contribute to the Zama fhEVM:
 - Request to become an official contributor by emailing [hello@zama.ai](mailto: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!
+
+## Bounty Program
+
+Contribute and earn rewards:
+
+- [bounty-program](https://github.com/zama-ai/bounty-program) - Zama's FHE Bounty Program
diff --git a/docs/developer/roadmap.md b/docs/developer/roadmap.md
@@ -2,26 +2,22 @@
 
 ## Features
 
-| name                 | description                                | ETA    |
-| -------------------- | ------------------------------------------ | ------ |
-| 128bits (scalar)     | Add euint128 for scalar operations         | Q3 '24 |
-| Proof for inputs     | Generate a proof for every encrypted input | Q3 '24 |
-| Threshold decryption | Use threshold decryption                   | Q3 '24 |
+| name             | description                                                 | ETA    |
+| ---------------- | ----------------------------------------------------------- | ------ |
+| Foundry template | [ Forge ](https://book.getfoundry.sh/reference/forge/forge) | Q1 '25 |
 
 ## Operations
 
-| name                  | function name       | type               | ETA             |
-| --------------------- | ------------------- | ------------------ | --------------- |
-| Random unsigned int   | `TFHE.randEuintX()` | Random             | Q3 '24          |
-| Add w/ overflow check | `TFHE.safeAdd`      | Binary, Decryption | Coming soon (1) |
-| Sub w/ overflow check | `TFHE.safeSub`      | Binary, Decryption | Coming soon (1) |
-| Mul w/ overflow check | `TFHE.safeMul`      | Binary, Decryption | Coming soon (1) |
-| Random signed int     | `TFHE.randEintX()`  | Random             | -               |
-| Div                   | `TFHE.div`          | Binary             | -               |
-| Rem                   | `TFHE.rem`          | Binary             | -               |
-| Set inclusion         | `TFHE.isIn()`       | Binary             | -               |
+| name                  | function name      | type               | ETA         |
+| --------------------- | ------------------ | ------------------ | ----------- |
+| Signed Integers       | `eintX`            |                    | Coming soon |
+| Add w/ overflow check | `TFHE.safeAdd`     | Binary, Decryption | Coming soon |
+| Sub w/ overflow check | `TFHE.safeSub`     | Binary, Decryption | Coming soon |
+| Mul w/ overflow check | `TFHE.safeMul`     | Binary, Decryption | Coming soon |
+| Random signed int     | `TFHE.randEintX()` | Random             | -           |
+| Div                   | `TFHE.div`         | Binary             | -           |
+| Rem                   | `TFHE.rem`         | Binary             | -           |
+| Set inclusion         | `TFHE.isIn()`      | Binary             | -           |
 
-> **_NOTE 1:_** Methods prefixed with `safe` will do an overflow check by decrypting an overflow bit and revert if that bit is true.
-
-> **_NOTE 2:_** Random encrypted integers that are generated fully on-chain. Currently, implemented as a mockup by using a PRNG in the plain.
+> **_NOTE 1:_** Random encrypted integers that are generated fully on-chain. Currently, implemented as a mockup by using a PRNG in the plain.
 > Not for use in production!
diff --git a/docs/fundamentals/acl.md b/docs/fundamentals/acl.md
@@ -1,112 +1,71 @@
-# Access Control List
+# Access control list (ACL) overview
 
-This document explains how to prevent unauthorized addresses from accessing the contents of unauthorized ciphertexts.
-This is enabled by the Access Control List (ACL) system in fhEVM, which defines which addresses have the right to manipulate the ciphertext.
+This document describes the Access Control List (ACL) system in fhEVM, a core feature that governs access to encrypted data. The ACL ensures that only authorized accounts or contracts can interact with specific ciphertexts, preserving confidentiality while enabling composable smart contracts. This overview provides a high-level understanding of what the ACL is, why it's essential, and how it works.
 
-## How it works?
+## What is the ACL?
 
-You can configure the ACLs in two ways:
+The ACL is a permission management system designed to control who can access, compute on, or decrypt encrypted values in fhEVM. By defining and enforcing these permissions, the ACL ensures that encrypted data remains secure while still being usable within authorized contexts.
 
-- **Permanent allowance**: `TFHE.allow(ciphertext, address)` allows a ciphertext to be used by a specific address at any time.
-- **Transient allowance**: `TFHE.allowTransient(ciphertext, address)` authorizes access to the ciphertext only for the duration of the transaction.
+## Why is the ACL important?
 
-Additionally, you can use `TFHE.allowThis(ciphertext)` as syntactic sugar for `TFHE.allow(ciphertext, address(this))`. This function is commonly used within dApp smart contracts to authorize the same contract to reuse a newly computed ciphertext handle in a future transaction.
+Encrypted data in fhEVM is entirely confidential, meaning that without proper access control, even the contract holding the ciphertext cannot interact with it. The ACL enables:
 
-Permanent allowance will store the ACL in a dedicated contract, while a temporary allowance will store it in [transient storage](https://eips.ethereum.org/EIPS/eip-1153), allowing developers to save gas. Transient allowance is particularly useful when calling an external function using a ciphertext as a parameter.
+- **Granular Permissions**: Define specific access rules for individual accounts or contracts.
+- **Secure Computations**: Ensure that only authorized entities can manipulate or decrypt encrypted data.
+- **Gas Efficiency**: Optimize permissions using transient access for temporary needs, reducing storage and gas costs.
 
-To illustrate, here is a simple example where one function calls another:
+## How does the ACL work?
 
-```solidity
-import "fhevm/lib/TFHE.sol";
+### Types of access
 
-contract SecretGiver {
-  SecretStore public secretStore;
+1. **Permanent Allowance**:
 
-  constructor() {
-    secretStore = new SecretStore();
-  }
+   - Configured using `TFHE.allow(ciphertext, address)`.
+   - Grants long-term access to the ciphertext for a specific address.
+   - Stored in a dedicated contract for persistent storage.
 
-  function giveMySecret() public {
-    // Create my secret - asEuint16 gives automatically transient allowance for the resulting handle (note: an onchain trivial encryption is not secret)
-    euint16 mySecret = TFHE.asEuint16(42);
+2. **Transient Allowance**:
+   - Configured using `TFHE.allowTransient(ciphertext, address)`.
+   - Grants access to the ciphertext only for the duration of the current transaction.
+   - Stored in transient storage, reducing gas costs.
+   - Ideal for temporary operations like passing ciphertexts to external functions.
 
-    // Allow temporarily the SecretStore contract to manipulate `mySecret`
-    TFHE.allowTransient(mySecret, address(secretStore));
+**Syntactic sugar**:
 
-    // Call `secretStore` with `mySecret`
-    secretStore.storeSecret(mySecret);
-  }
-}
+- `TFHE.allowThis(ciphertext)` is shorthand for `TFHE.allow(ciphertext, address(this))`. It authorizes the current contract to reuse a ciphertext handle in future transactions.
 
-contract SecretStore {
-  euint16 public secretResult;
+### Transient vs. permanent allowance
 
-  function storeSecret(euint16 callerSecret) public {
-    // Verify that the caller has also access to this ciphertext
-    require(TFHE.isSenderAllowed(callerSecret), "The caller is not authorized to access this secret.");
+| **Allowance Type** | **Purpose**                                    | **Storage Type**                                                        | **Use Case**                                                                                        |
+| ------------------ | ---------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| **Transient**      | Temporary access during a transaction.         | [Transient storage](https://eips.ethereum.org/EIPS/eip-1153) (EIP-1153) | Calling external functions or computations with ciphertexts. Use when wanting to save on gas costs. |
+| **Permanent**      | Long-term access across multiple transactions. | Dedicated contract storage                                              | Persistent ciphertexts for contracts or users requiring ongoing access.                             |
 
-    // do some FHE computation (result is automatically put in the ACL transient storage)
-    euint16 computationResult = TFHE.add(callerSecret, 3);
+## Granting and verifying access
 
-    // then store the resulting ciphertext handle in the contract storage
-    secretResult = computationResult;
+### Granting access
 
-    // Make the temporary allowance for this ciphertext permanent to let the contract able to reuse it at a later stage or request a decryption of it
-    TFHE.allowThis(secretResult); // this is strictly equivalent to `TFHE.allow(secretResult, address(this));``
-  }
-}
-```
+Developers can use functions like `allow`, `allowThis`, and `allowTransient` to grant permissions:
 
-## Automatic (transient) allowance
+- **`allow`**: Grants permanent access to an address.
+- **`allowThis`**: Grants the current contract access to manipulate the ciphertext.
+- **`allowTransient`**: Grants temporary access to an address for the current transaction.
 
-To simplify matters, a number of functions automatically generate temporary access (using `TFHE.allowTransient` under the hood) for the contract that calls the function. This applies to:
+### Verifying access
 
-- `TFHE.asEuintXX()`, `TFHE.asEaddress()`, `TFHE.asEbool()`
-- `TFHE.randXX()`
-- All results from computations (`TFHE.add()`, `TFHE.select()`, ...)
+To check if an entity has permission to access a ciphertext, use functions like `isAllowed` or `isSenderAllowed`:
 
-```solidity
-function randomize() {
-  // Store this random value. This value is temporarily allowed.
-  random = TFHE.randEuint64();
+- **`isAllowed`**: Verifies if a specific address has permission.
+- **`isSenderAllowed`**: Simplifies checks for the current transaction sender.
 
-  // Permanently store the temporary access for this ciphertext.
-  TFHE.allowThis(random);
-}
-```
+---
 
-## Security best practice: isSenderAllowed()
+## Practical uses of the acl
 
-When a function receives a ciphertext (such as `ebool`, `euint8`, `eaddress`, ...), it needs to verify that the sender also has access to this ciphertext. This verification is crucial for security.
+- **Confidential Parameters**: Pass encrypted values securely between contracts, ensuring only authorized entities can access them.
+- **Secure Stte Management**: Store encrypted state variables while controlling who can modify or read them.
+- **Privacy-Preserving Computations**: Enable computations on encrypted data with confidence that permissions are enforced.
 
-Without this check, a contract could send any ciphertext authorized for the contract and potentially exploit the function to retrieve the value. For example, an attacker could transfer someone's balance as an encrypted amount.
+---
 
-If the function does not include `require(TFHE.isSenderAllowed(encryptedAmount))`, an attacker who doesn't have access to this balance could determine the value by transferring the balance between two well-funded accounts.
-
-## ACL for reencryption
-
-If a ciphertext must be reencrypted by a user, then explicit access must be granted to them. If this authorization is not given, the user will be unable to request a reencryption of this ciphertext.
-
-Due to the reencryption mechanism, a user signs a public key associated with a specific contract; therefore, the ciphertext also needs to be allowed for the contract.
-
-Let's take, for example, a transfer in an ERC20:
-
-```solidity
-function transfer(address to, euint64 encryptedAmount) public {
-  require(TFHE.isSenderAllowed(encryptedAmount), "The caller is not authorized to access this encrypted amount.");
-  euint64 amount = TFHE.asEuint64(encryptedAmount);
-  ebool canTransfer = TFHE.le(amount, balances[msg.sender]);
-
-  euint64 newBalanceTo = TFHE.add(balances[to], TFHE.select(canTransfer, amount, TFHE.asEuint64(0)));
-  balances[to] = newBalanceTo;
-  // Allow this new balance for both the contract and the owner.
-  TFHE.allowThis(newBalanceTo);
-  TFHE.allow(newBalanceTo, to);
-
-  euint64 newBalanceFrom = TFHE.sub(balances[from], TFHE.select(canTransfer, amount, TFHE.asEuint64(0)));
-  balances[from] = newBalanceFrom;
-  // Allow this new balance for both the contract and the owner.
-  TFHE.allowThis(newBalanceFrom);
-  TFHE.allow(newBalanceFrom, from);
-}
-```
+For a detailed explanation of the ACL's functionality, including code examples and advanced configurations, see [working with the acl](./first_step/acl_examples.md).