docs: fix due to change in hardhat-templates + README #642
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,156 @@ | ||
| # asEbool, asUintXX and asEbytesXX operations | ||
poppyseedDev marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| This documentation covers the `asEbool`, `asEuintXX`, and `asEbytesXX` operations provided by the TFHE library for working with encrypted data in the fhEVM. These operations are essential for converting between plaintext and encrypted types, as well as handling encrypted inputs. | ||
poppyseedDev marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| The operations can be categorized into three main use cases: | ||
|
|
||
| 1. **Trivial encryption**: Converting plaintext values to encrypted types | ||
| 2. **Type casting**: Converting between different encrypted types | ||
| 3. **Input handling**: Processing encrypted inputs with proofs | ||
|
|
||
| ## 1. Trivial input | ||
|
There was a problem hiding this comment. Should be "Trivial Encryption" everywhere, not trivial input There was a problem hiding this comment. we had a discussion with Levent on this it's a bit easier to clasify There was a problem hiding this comment. or you know what yeah will just convert to trivial encrypt There was a problem hiding this comment. as you wish, but I think Trivial encryption makes more sense because few lines earlier you already used trivial encryption, so let's not use different terminologies for same concept |
||
|
|
||
| Trivial input simply put is a plain text in a format of a ciphertext. | ||
|
|
||
| ### Overview | ||
|
|
||
| Trivial input is the process of converting plaintext values into encrypted types (ciphertexts) compatible with TFHE operators. Although the data is in ciphertext format, it remains publicly visible on-chain, making it useful for operations between public and private values. | ||
|
|
||
| This type of casting involves converting plaintext (unencrypted) values into their encrypted equivalents, such as: | ||
|
|
||
| - `bool` → `ebool` | ||
| - `uint` → `euintXX` | ||
| - `bytes` → `ebytesXX` | ||
|
|
||
poppyseedDev marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| > **Note**: When doing trivial encrypt, the data is made compatible with FHE operations but remains publicly visible on-chain unless explicitly encrypted. | ||
jatZama marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| #### **Example** | ||
|
|
||
| ```solidity | ||
| euint64 value64 = TFHE.asEuint64(7262); // Trivial encrypt a uint64 | ||
| ebool valueBool = TFHE.asEbool(true); // Trivial encrypt a boolean | ||
| ``` | ||
|
|
||
| ### Trivial encryption of `ebytesXX` types | ||
|
|
||
| The `TFHE.padToBytesXX` functions facilitate this trivial encryption process for byte arrays, ensuring compatibility with `ebytesXX` types. These functions: | ||
|
|
||
| - Pad the provided byte array to the appropriate length (`64`, `128`, or `256` bytes). | ||
| - Prevent runtime errors caused by improperly sized input data. | ||
| - Work seamlessly with `TFHE.asEbytesXX` for trivial encryption. | ||
|
|
||
| > **Important**: Trivial encryption does NOT provide any privacy guarantees. The input data remains fully visible on the blockchain. Only use trivial encryption when working with public values that need to interact with actual encrypted data. | ||
|
|
||
| #### Workflow | ||
|
|
||
| 1. **Pad Input Data**: | ||
| Use the `padToBytesXX` functions to ensure your byte array matches the size requirements. | ||
| 2. **Encrypt the Padded Data**: | ||
| Use `TFHE.asEbytesXX` to encrypt the padded byte array into the corresponding encrypted type. | ||
| 3. **Grant Access**: | ||
| Use `TFHE.allowThis` and `TFHE.allow` to define access control for the encrypted data. | ||
poppyseedDev marked this conversation as resolved.
Show resolved
Hide resolved
jatZama marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ### Example: Trivial Encryption with `ebytesXX` | ||
|
|
||
| Below is an example demonstrating how to encrypt and manage `ebytes64`, `ebytes128`, and `ebytes256` types: | ||
|
|
||
| ```solidity | ||
| function trivialEncrypt() public { | ||
| // Encrypt a 64-byte array | ||
| ebytes64 yBytes64 = TFHE.asEbytes64( | ||
| TFHE.padToBytes64( | ||
| hex"19d179e0cc7e816dc944582ed4f5652f5951900098fc2e0a15a7ea4dc8cfa4e3b6c54beea5ee95e56b728762f659347ce1d4aa1b05fcc5" | ||
| ) | ||
| ); | ||
| TFHE.allowThis(yBytes64); | ||
| TFHE.allow(yBytes64, msg.sender); | ||
|
|
||
| // Encrypt a 128-byte array | ||
| ebytes128 yBytes128 = TFHE.asEbytes128( | ||
| TFHE.padToBytes128( | ||
| hex"13e7819123de6e2870c7e83bb764508e22d7c3ab8a5aee6bdfb26355ef0d3f1977d651b83bf5f78634fa360aa14debdc3daa6a587b5c2fb1710ab4d6677e62a8577f2d9fecc190ad8b11c9f0a5ec3138b27da1f055437af8c90a9495dad230" | ||
| ) | ||
| ); | ||
| TFHE.allowThis(yBytes128); | ||
| TFHE.allow(yBytes128, msg.sender); | ||
|
|
||
| // Encrypt a 256-byte array | ||
| ebytes256 yBytes256 = TFHE.asEbytes256( | ||
| TFHE.padToBytes256( | ||
| hex"d179e0cc7e816dc944582ed4f5652f5951900098fc2e0a15a7ea4dc8cfa4e3b6c54beea5ee95e56b728762f659347ce1d4aa1b05fcc513e7819123de6e2870c7e83bb764508e22d7c3ab8a5aee6bdfb26355ef0d3f1977d651b83bf5f78634fa360aa14debdc3daa6a587b5c2fb1710ab4d6677e62a8577f2d9fecc190ad8b11c9f0a5ec3138b27da1f055437af8c90a9495dad230" | ||
| ) | ||
| ); | ||
| TFHE.allowThis(yBytes256); | ||
| TFHE.allow(yBytes256, msg.sender); | ||
| } | ||
| ``` | ||
|
|
||
| ## 2. Casting between encrypted types | ||
|
|
||
| This type of casting is used to reinterpret or convert one encrypted type into another. For example: | ||
|
|
||
| - `euint32` → `euint64` | ||
| - `ebytes128` → `ebytes256` | ||
|
|
||
| Casting between encrypted types is often required when working with operations that demand specific sizes or precisions. | ||
|
|
||
| > **Important**: When casting between encrypted types: | ||
| > | ||
| > - Casting from smaller types to larger types (e.g. `euint32` → `euint64`) preserves all information | ||
| > - Casting from larger types to smaller types (e.g. `euint64` → `euint32`) will truncate and lose information | ||
|
|
||
| The table below summarizes the available casting functions: | ||
|
|
||
| | From type | To type | Function | | ||
| | --------- | -------- | ---------------- | | ||
| | `euintX` | `euintX` | `TFHE.asEuintXX` | | ||
| | `ebool` | `euintX` | `TFHE.asEuintXX` | | ||
| | `euintX` | `ebool` | `TFHE.asEboolXX` | | ||
poppyseedDev marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| {% hint style="info" %} | ||
| Casting between encrypted types is efficient and often necessary when handling data with differing precision requirements. | ||
| {% endhint %} | ||
|
|
||
| ### **Workflow for encrypted types** | ||
|
|
||
| ```solidity | ||
| // Casting between encrypted types | ||
| euint32 value32 = TFHE.asEuint32(value64); // Cast to euint32 | ||
| ebool valueBool = TFHE.asEbool(value32); // Cast to ebool | ||
| ``` | ||
|
|
||
| ## 3. Encrypted input | ||
|
|
||
| ### Overview | ||
|
|
||
| Encrypted input casting is the process of interpreting a handle (ciphertext reference) and its proof as a specific encrypted type. This ensures the validity of the input before it is used in computations. | ||
|
|
||
| Encrypted inputs is in depth explained in the following section: [encrypted inputs](./inputs.md) | ||
|
|
||
| #### Example | ||
|
|
||
| ```solidity | ||
| euint64 encryptedValue = TFHE.asEuint64(einputHandle, inputProof); // Interpret einputHandle as euint64 | ||
| ``` | ||
|
|
||
| #### Details | ||
|
|
||
| Encrypted input casting validates: | ||
|
|
||
| 1. The input handle references a valid ciphertext. | ||
| 2. The accompanying proof matches the expected type. | ||
|
|
||
| For more information, see the [Encrypetd inputs documentation](./inputs.md) | ||
|
|
||
| ## Overall operation summary | ||
|
|
||
| | Casting Type | Function | Input Type | Output Type | | ||
| | ------------------------ | ----------------------- | ----------------- | ----------- | | ||
| | Trivial input | `TFHE.asEuintXX(x)` | `uintX` | `euintX` | | ||
poppyseedDev marked this conversation as resolved.
Show resolved
Hide resolved
poppyseedDev marked this conversation as resolved.
Show resolved
Hide resolved
jatZama marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| | | `TFHE.asEbool(x)` | `bool` | `ebool` | | ||
| | | `TFHE.asEbytesXX(x)` | `bytesXX` | `ebytesXX` | | ||
| | Conversion between types | `TFHE.asEuintXX(x)` | `euintXX`/`ebool` | `euintYY` | | ||
| | | `TFHE.asEbool(x)` | `euintXX` | `ebool` | | ||
poppyseedDev marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| | Encrypted input | `TFHE.asEuintXX(x, y)` | `einput`, proof | `euintX` | | ||
jatZama marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| | | `TFHE.asEbool(x, y)` | `einput`,proof | `ebool` | | ||
jatZama marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| | | `TFHE.asEbytesXX(x, y)` | `einput`,proof | `ebytesXX` | | ||
poppyseedDev marked this conversation as resolved.
Show resolved
Hide resolved
|
||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
can you put the last part with the arrow in bold and italic? I think it would make it even clearer. We really want to avoid many support questions from new devs not understanding how to start and trying directly to run tests from fhevm repo instead of hardhat-template.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
but the README is not the primary entry point
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
if https://github.com/zama-ai/fhevm -> is the primary entry point we have communication issues elsewhere