doc: add input mechanism for native and coprocessor

docs/fundamentals/coprocessor/inputs.md

@@ -0,0 +1,101 @@
+# Inputs
+
+Inputs are handled particularly because the corresponding ciphertext is stored off-chain. This implies a secure mechanism which starts on user side, 
+cross the KMS and finaly is managed by the coprocessor. 
+
+This document will explain how inputs works on Solidity level, the second part will give an overview of the full flow of an input. 
+
+
+## Compact Input Lists
+
+TODO.
+
+## Overview of input mechanism
+
+Handling inputs requires a few steps. The first one is to retrieve public key material from the Gateway. The second point is to encrypt them and computing the associated proof. Last step is to use them as "usual" inputs in the smart contract. 
+
+### Public key material and CRS retrieval
+
+The very first step to prepare input is to have the blockchain related public key material. The Gateway is the component reached by the user to get those material. 
+
+The Gateway is exposing a `/keys` endpoint that returns the public key and CRS alongside the signature. Users are able to verify them using KMSVerifier smart contract. 
+
+### Initialiazation phase
+
+In this first part we need to encrypt the input with the blockchain public key to get the `ciphertext` `C`, and compute the `ZkPok`. `C` 
+is bounded to be used with a `contractAddress` and by a `callerAddress`. The goal is to make it signed by the KMS to enable the usage of the input
+within smart contract further. 
+
+C == ciphertext - Encrypted with the blockchain public key
+
+h == handle - keccak of C with some info appended
+
+ZkPok == Zero-knowledge proof - Computed on client side as proof of knowledge of input
+
+S ==  Signature
+
+    struct CVerificationStructForKMS {
+        address contractAddress;
+        bytes32 hashOfCiphertext;
+        address callerAddress;
+    }
+
+        struct CVerificationStructFromCopro {
+        uint256[] handlesList;
+        address contractAddress;
+        bytes32 hashOfCiphertext;
+        address callerAddress;
+    }
+
+    struct InputProof {
+        bytes COPRO_S;
+        bytes KMS_S;
+        bytes32 hashOfCiphertext;
+        uint256[] handlesList;
+
+    }
+
+Note: we can add handleList in **CVerificationStructForKMS**
+
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Gateway
+    participant KMS_BC as KMS BC
+    participant KMS_Core as KMS Core
+    participant Copro as Coprocessor
+
+    User->>Gateway: (C, contractAddr, callerAddr, ZKPoK)
+    Gateway->>KMS_BC: VerifyInput(C, contractAddr, callerAddr, ZKPoK)
+    KMS_BC->>KMS_Core: VerifyInput(C, contractAddr, callerAddr, ZKPoK)
+    Note over KMS_Core: Verify ZkPoK
+    Note over KMS_Core: KMS_S = Sign(CVerificationStructForKMS)
+    KMS_Core->>KMS_BC: KMS_S
+    KMS_BC->>Gateway: KMS_S
+    Gateway->>Copro: contractAddr, callerAddr, C
+    Note over Copro: Verify public values as callerAddr and contractAddr ?
+    Note over Copro: Store C in DB
+    Note over Copro: COPRO_S = Sign(CVerificationStructFromCopro)
+    Copro->>Gateway: COPRO_S, handlesList
+
+    Gateway->>User: COPRO_S, KMS_S, handlesList
+
+```
+
+### Usage
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Host BC
+    participant Coprocessor
+
+    User->>Host BC: InputProof
+    Note over Host BC: Reconstruct CVerificationStructFromCopro
+    Note over Host BC: Verify COPRO_S in CoprocessorVerifier solidity contract
+    Note over Host BC: Reconstruct CVerificationStructFromKMS
+    Note over Host BC: Verify KMS_S in KMSVerifier solidity contract
+
+
+```

docs/fundamentals/fhevm/inputs.md

@@ -16,7 +16,7 @@ Therefore, we employ zero-knowledge proofs of knowledge (ZKPoK) of input FHE cip
 * the user knows the plaintext value
 * the input ciphertext can only be used in a particular smart contract
 
-The ZKPoK is verified by validator nodes when the input byte array is passed to an `TFHE.asEuintXX()` function to convert from a ciphertext to a handle that can be used in smart contracts for FHE operations.
+The ZKPoK is verified by the KMS which delivers a signature (KMS_S) to the user. When the input byte array is passed to an `TFHE.asEuintXX()` function to convert from a ciphertext to a handle that can be used in smart contracts for FHE operations, the KMS_S is verified. 
 
 ## Compact Input Lists
 
@@ -44,3 +44,72 @@ contract Adder {
 ```
 
 Note that `inputProof` also contains the ZKPoK.
+
+
+## Overview of input mechanism
+
+Handling inputs requires a few steps. The first one is to retrieve public key material from the Gateway. The second point is to encrypt them and computing the associated proof. Last step is to use them as "usual" inputs in the smart contract. 
+
+### Public key material and CRS retrieval
+
+The very first step to prepare input is to have the blockchain related public key material. The Gateway is the component reached by the user to get those material. 
+
+The Gateway is exposing a `/keys` endpoint that returns the public key and CRS alongside the signature. Users are able to verify them using KMSVerifier smart contract. 
+
+
+
+### Initialization phase
+
+In this first part we need to encrypt the input with the blockchain public key to get the `ciphertext` `C`, and compute the `ZkPok`. `C` 
+is bounded to be used with a `contractAddress` and by a `callerAddress`. The goal is to make it signed by the KMS to enable the usage of the input
+within smart contract further. 
+
+C == ciphertext - Encrypted with the blockchain public key
+
+ZkPok == Zero-knowledge proof - Computed on client side as proof of knowledge of input
+
+eInput == types + index
+
+S ==  Signature 
+
+    struct CVerificationStructForKMS {
+        address contractAddress;
+        bytes32 hashOfCiphertext;
+        address callerAddress;
+    }
+
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Gateway
+    participant KMS_BC as KMS BC
+    participant KMS_Core as KMS Core
+
+    User->>Gateway: 1. (C, contractAddr, callerAddr, ZKPoK)
+    Gateway->>KMS_BC: 2. VerifyInput(C, contractAddr, callerAddr, ZKPoK)
+    KMS_BC->>KMS_Core: 3. VerifyInput(C, contractAddr, callerAddr, ZKPoK)
+    Note over KMS_Core: 4. Verify ZkPoK
+    Note over KMS_Core: 5. KMS_S = Sign(CVerificationStructForKMS)
+    KMS_Core->>KMS_BC: 6. KMS_S
+    KMS_BC->>Gateway: 7. KMS_S
+    Gateway->>User: 8. KMS_S
+
+```
+
+### Usage
+
+The user has received the KMS signature, this means that the proof has been verified and the input could be legitimately used within fhEVM. 
+This is quite useful because in fhEVM, only the KMS signature will be verified which is faster than verifying a ZkPoK proof. 
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant fhEVM
+
+    User->>fhEVM: (eInput, C, KMS_S)
+     Note over fhEVM: Reconstruct CVerificationStructFromKMS
+    Note over fhEVM: Verify KMS_S
+
+
+```

docs/fundamentals/gateway/decryption.md

@@ -10,8 +10,8 @@ After reaching the end of the auction, one need to discover (only) the winner, h
 
 The Gateway acts as an oracle service: it will listen to decryption request events and return the decrypted value through a callback function.
 The responsabilities of the Gateway are:
-- Listening decryption request from fhEVM that contains a handle `h` to the associated ciphertext `C`
-- Computing a storage proof `P` to attest C is decryptable
+- Listening decryption request from fhEVM that contains a handle `h` that corresponds to a  ciphertext `C`
+- Computing a storage proof `P` to attest h (i.e. C)  is decryptable
 - Retrieve C from fhEVM using `h` as key
 - Send a decyption request to TKMS which in turn is running an internal blockchain aka `KMS BC`
 - Wait and listen for `decyptionResponse` (containing the plaitext and a few signatures from KMS to attest the integrity of the palintext) event from `KMS BC`

docs/fundamentals/gateway/proof.md

@@ -1 +1,13 @@
-# Inclusion proof
+# Inclusion Proof
+
+The execution layer in fhEVM can perform computations on ciphertexts. At some point, it becomes necessary to reveal the actual values of these ciphertexts. However, the private key is managed by the KMS (Key Management System). The question arises: how can we perform asynchronous decryption requests (which make the values public) and re-encryptions (for personal information) when the execution layer and the KMS are decoupled?
+This is where inclusion proofs come into play.
+
+
+## How to Compute an Inclusion Proof
+
+## Verification of the Proof in KMS BC ISC
+
+## Notes on Root Hash Verification
+
+This section will be elaborated upon in the future to explain the validation of root hash integrity.