Update solidity docs (#37)

* update solidity docs

* fix wording and examples

* Revert "fix wording and examples"

This reverts commit a7478ae.

* fix wording

* fix(docs): typos

* feat(docs): add second example for decryption.

* fix(docs): fix summary

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
 

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.

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.

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