From f190c30c2881de30b4ed95040a304fe5d17f8edd Mon Sep 17 00:00:00 2001 From: Louis Tremblay Thibault Date: Tue, 19 Sep 2023 17:46:32 +0200 Subject: [PATCH] Update solidity docs (#37) * update solidity docs * fix wording and examples * Revert "fix wording and examples" This reverts commit a7478aeb94a45e92aa7a4eeaad5e1e44fbe06de7. * fix wording * fix(docs): typos * feat(docs): add second example for decryption. * fix(docs): fix summary --- docs/SUMMARY.md | 2 +- docs/solidity/decryption.md | 38 ++++++++++++++++++++++++++++++ docs/solidity/functions.md | 17 ++++++++++++-- docs/solidity/library.md | 1 + docs/solidity/requires.md | 46 ------------------------------------- 5 files changed, 55 insertions(+), 49 deletions(-) create mode 100644 docs/solidity/decryption.md delete mode 100644 docs/solidity/requires.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 4a5fad3..7484d6a 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -7,7 +7,7 @@ * [Getting Started](solidity/getting\_started.md) * [TFHE Library](solidity/library.md) * [Function specifications](solidity/functions.md) -* [Decryption and control structures](solidity/requires.md) +* [Decryption and control structures](solidity/decryption.md) ## fhevmjs diff --git a/docs/solidity/decryption.md b/docs/solidity/decryption.md new file mode 100644 index 0000000..2687c0c --- /dev/null +++ b/docs/solidity/decryption.md @@ -0,0 +1,38 @@ +# Decryption and control structures + +## Decryptions + +We allow explicit decryption requests for any encrypted type. +The values are decrypted through the distributed decryption protocol and are stored on-chain. + +### Examples + +```solidity +function decryptAmount(euint8 amount) public view returns (uint8) { + return TFHE.decrypt(amount); +} + +function revertIfConditionIsFalse(ebool condition) public { + bool plaintextCondition = TFHE.decrypt(condition); + require(plaintextCondition, "Condition was not met"); + // ... continue execution if `condition` is true +} +``` + +## Booleans + +The result of [comparison operations](functions.md#comparison-operation-eq-ne-ge-gt-le-lt) is of type `ebool`. Typical boolean operations are not currently supported for this type. + +The purpose of the `ebool` type is two-fold: + +1. control bit for the [`cmux`](functions.md#multiplexer-operator-cmux) operator; +2. input for optimistic encrypted require (`optReq`) statements. + +## Optimistic encrypted require statements + +The decryption statements described above may lead to important delays during the transaction execution as several of them may need to be processed in a single transaction. +Given that those decryptions might be used for control flow by using the Solidity `require` function, we introduce optimistic require statements (`optReq`). +These require statements take as input a value to type `ebool` and are accumulated throughout the execution of the transaction. +The accumulated boolean value is decrypted via the threshold decryption protocol either when an explicit decryption is executed, or at the very end of a transaction execution. +If the decryption returns `false`, the transaction is reverted. Otherwise, state changes are persisted as usual. +Optimistic requires may be more efficient, but this efficiency comes at the price of paying the full transaction gas cost if one of the boolean predicates is false. diff --git a/docs/solidity/functions.md b/docs/solidity/functions.md index 4bca14c..5980bb8 100644 --- a/docs/solidity/functions.md +++ b/docs/solidity/functions.md @@ -35,7 +35,7 @@ The `asEuint` functions serve three purposes: 2. cast a `euintX` typed ciphertext to a `euintY` typed ciphertext, where `X != Y`; 3. trivially encrypt a plaintext value. -The first case is used to process encrypted inputs, e.g. user-provided ciphertexts. Those generally comes from a wallet. +The first case is used to process encrypted inputs, e.g. user-provided ciphertexts. Those are generally included in a transaction payload. The second case is self-explanatory. When `X > Y`, the most significant bits are dropped. When `X < Y`, the ciphertext is padded to the left with trivial encryptions of `0`. @@ -63,7 +63,7 @@ The `asEbool` functions behave similarly to the `asEuint` functions, but for enc The reencrypt functions takes as inputs a ciphertext and a public encryption key (namely, a [NaCl box](https://nacl.cr.yp.to/index.html)). -During reencryption, the ciphertext is decrypted using the network private key (threshold decryption protocol in the works). +During reencryption, the ciphertext is decrypted using the network private key (the threshold decryption protocol is in the works). Then, the decrypted result is encrypted under the user-provided public encryption key. The result of this encryption is sent back to the caller as `bytes memory`. @@ -146,6 +146,19 @@ function gt(uint32 a, euint16 b) internal view returns (ebool) function gt(euint16 a, uint32 b) internal view returns (ebool) ``` +## Multiplexer operator (`cmux`) + +This operator takes three inputs. The first input `b` is of type `ebool` and the two others of type `euintX`. +If `b` is an encryption of `true`, the first integer parameter is returned. Otherwise, the second integer parameter is returned. + +### Example +```solidity +// if (b == true) return val1 else return val2 +function cmux(ebool b, euint8 val1, euint8 val2) internal view returns (euint8) { + return TFHE.cmux(b, val1, val2); +} +``` + ## `min`, `max` Returns the minimum (resp. maximum) of the two given values. diff --git a/docs/solidity/library.md b/docs/solidity/library.md index 8b1ae0f..14f2888 100644 --- a/docs/solidity/library.md +++ b/docs/solidity/library.md @@ -50,5 +50,6 @@ The list of supported operations is presented below. | Max | `TFHE.max` | Binary | | Neg | `TFHE.neg` | Unary | | Not | `TFHE.not` | Unary | +| Cmux | `TFHE.cmux` | Ternary| More information about the supported operations can be found at the [TFHE-rs docs](https://docs.zama.ai/tfhe-rs/getting-started/operations#arithmetic-operations.). diff --git a/docs/solidity/requires.md b/docs/solidity/requires.md deleted file mode 100644 index ecf3b7c..0000000 --- a/docs/solidity/requires.md +++ /dev/null @@ -1,46 +0,0 @@ -# Decryption and control structures - -## Booleans - -The result of [comparison operations](functions.md#comparison-operation-eq-ne-ge-gt-le-lt) is of type `ebool`. Typical boolean operations are not currently supported for this type. - -The purpose of the `ebool` type is three-fold: - -1. control bit for the `cmux` operator; -2. input for encrypted require (`req`) statements; -3. input for optimistic encrypted require (`optReq`) statements. - -## Encrypted require statements - -Encrypted require statements (`req`) are analogous the usual Solidity `require` statements: given an encrypted boolean predicate `b`, the statement will force the transaction execution to halt if `b` evaluates to false. -Evaluating the encrypted boolean predicate implies a (threshold) decryption. - -### Examples - -```solidity -// A transcation calling this function will revert. -function failingRequire(euint8 a) public { - euint8 val = TFHE.asEuint8(4); - TFHE.req(TFHE.eq(val, TFHE.not(val))); -} -``` - -## Optimistic encrypted require statements - -The require statements described above may lead to important delays during the transaction execution as several of them may need to be processed in a single transaction. -This is why we introduce optimistic encrypted statements (`optReq`). -These require statements are accumulated throughout the execution of the transaction and are only decrypted at the end of execution. -Optimistic requires may be more efficient, but this efficiency comes at the price of paying more gas if it so happens that one of the predicates is false. - -## Decryptions - -We also allow explicit decryptions requests for any type encrypted type. -The values are decrypted in the same way requires are, that is through the distributed decryption protocol. - -### Examples - -```solidity -function decryptAmount(euint8 amount) public view returns (uint8) { - return TFHE.decrypt(amount); -} -```