docs: further details on the KMS architecture

docs/fundamentals/tkms/architecture.md

@@ -24,7 +24,7 @@ We now briefly outline each of these components along with their constituents:
 
 - *KMS Engine*: The actual computational engine carrying out the FHE cryptographic key operations in a Nitro enclave
 
-- *S3*: Public S3 instance storing the public keys for the FHE schemes for easy access. 
+- *S3*: Public S3 instance storing the public keys for the FHE schemes for easy access.
 
 ## Frontend
 
@@ -39,22 +39,22 @@ The frontend makes up the public interface of the KMS, through which all request
 
 It consists of the following components:
 
-- Smart contracts: ASC and Config SC.
+- Smart contracts: ISC, ASC and Config SC.
   - Responsible for receiving, validating and processing requests and updates from the fhEVM. Including decryption, reencryption, validator updates, key generation and setup.
 - KMS validators (realized through CometBFT).
   - The entities realizing the KMS blockchain. There may, or may not, be a 1-1 mapping between each validator and a threshold party in the KMS backend.
 
-Multiple application smart contracts (ASC) are deployed on the blockchain, typically one for each application (e.g. fhEVM blockchain) or application type (e.g. EVM blockchain). Each of these can keep application-specific state in order to verify requests from the application. For instance, an ASC for an fhEVM blockchain holds the identity of the current set of validators, so that access controls lists (ACLs) in decryption and reencryption requests can be validated by checking state inclusion proofs against the state roof of the fhEVM blockchain.
+Multiple ISCs are deployed on the blockchain, typically one for each application (e.g. fhEVM blockchain) or application type (e.g. EVM blockchain). Each of these can keep application-specific state in order to verify requests from the application. For instance, an ISC for an fhEVM blockchain holds the identity of the current set of validators, so that access controls lists (ACLs) in decryption and reencryption requests can be validated by checking state inclusion proofs against the state roof of the fhEVM blockchain.
 
-All decryption and reencryption requests are submitted as transactions to an ASC. If approved then the ASC calls the backend by emitting an event that will trigger the backend to actually fulfill the request. Once the request has been fulfilled, the backend submits a fulfillment transaction back to the ASC.
+All decryption and reencryption requests are submitted as transactions to an ASC. The ASC performs universal validation and forwards ACL validation to the appropriate ISC. If all validations are ok then the ASC calls the backend by emitting an event that will trigger the backend to actually fulfill the request. Once the request has been fulfilled, the backend submits a fulfillment transaction back to the ASC.
 
 All payments to the KMS is also handled through the ASC to which the transaction is submitted. These payments are used to incentivize the KMS operators.
 
 Note that the KMS blockchain may be operated by a single validator if decentralization is not needed, or either in a permissioned or permissionless fashion for the decentralized setting.
 
 ### Backend
 
-The backend consists of the KMS core. 
+The backend consists of the KMS core.
 It is the most security critical component of the entire system and a compromise of this could lead to breakage of both correctness, confidentiality and robustness.
 Because of this we have designed it to support threshold security and Enclave support, along with isolation of the security critical _Engine_ from the general Internet.
 
@@ -118,8 +118,8 @@ The storage component is used to make available public material that is not suit
 
 The storage component can be entirely untrusted from a security perspective, and comes in two flavors with different availability properties:
 
-- Centralized using AWS S3 buckets.
-- Decentralized using for instance IPFS.
+- AWS S3 buckets.
+- The local file system.
 
 The storage component is expected to have high availability, although all material stored therein can easily be replicated without security risk.
 

docs/fundamentals/tkms/blockchain.md

@@ -1 +1,17 @@
 # Blockchain
+The KMS blochhain is implemented using the Cosmos framework. More specifically with [Comet BFT](https://cosmos.network/cometbft/).
+This is a permissioned blockchain that is based on BFT consensus that allows for high throughput and low latency, but only supports a small number of validators (since consensus requires mutual interaction between all validator).
+
+The blockchain handles all decryption, reencryption, and key management operations between _all_ fhEVM chains, co-processors etc. and the KMS engine.
+
+## Smart contracts
+
+- *ISC (Inclusion proof Smart Contract)*: Smart contract which handles validation of decryption/re-encryption requests for a specific fhEVM. Thus is contains custom logic for validation for a single fhEVM.
+
+- *ASC (Application Smart Contract)*: A single smart contract to which transaction from the gateway (connector) are submitted to for all fhEVM's. All requests will pass through this contract and decryption and re-encryption requests will be validated by the appropriate ISC contract. 
+
+## Payment
+All operations must be paid for with tokens. Currently the tokenomics is not implemented and hence tokens can be constructed freely using a focet.
+
+## Deployment
+The KMS blockchain is deployed using `n` servers where `n` is the number of MPC parties. Each run their own validator docker image but is depoyed on the same machine as each of the MPC parties.

docs/fundamentals/tkms/centralized.md

@@ -1 +1,8 @@
-# Centralized
+# Centralized
+
+The centralized realization is part of the same binary as the KMS Core. That is, it has very low overhead. However, it also means that to compromise the secret FHE key that is able to decrypt all ciphertexts, one would only need to compromise the key storage of the KMS Core. This may simply involve compromising the local file-system if Nitro is not used.
+
+Public and private key storage may be done on the local filesystem, or it may be outsourced to an S3 instance.
+Observe that there is a different strategy for the public, respectively the private key material. This is because the public key material is _never_ loaded again after construction by the KMS Core, but is required to be easily accessible to other systems. On the other hand, the private key material is only used by the KMS Core and is never exposed to other systems. Furthermore, it is loaded into RAM during each booting of the KMS Core.
+
+The cryptographic operations carried out by the centralized back=end are carried out directly through the usage of [tfhe-rs](https://github.com/zama-ai/tfhe-rs).

docs/fundamentals/tkms/threshold.md

@@ -1 +1,15 @@
-# Threshold 
+# Threshold
+
+The threshold realization is part of the same binary as the KMS Core, but `n` KMS Cores are running independently of each other, hosted by different companies. This means that in order to compromise the secret FHE key that is able to decrypt all ciphertexts, one would only need to compromise the key storage of _at least_ `t` KMS Cores administered by distinct companies on distinct servers.
+More specifically this may simply involve compromising more than `t` local file-systems if Nitro is not used, more than `t` Nitro enclaves.
+
+Public and private key storage may be done on the local filesystem, or it may be outsourced to an S3 instance.
+Observe that there is a different strategy for the public, respectively the private key material. This is because the public key material is _never_ loaded again after construction by the KMS Core, but is required to be easily accessible to other systems. On the other hand, the private key material is only used by the KMS Core and is never exposed to other systems. Furthermore, it is loaded into RAM during each booting of the KMS Core.
+
+The cryptographic operations carried out by the threshold back=end are fulfilled by an MPC implementation of the necessary operations of the [tfhe-rs](https://github.com/zama-ai/tfhe-rs) library.
+The underlying MPC protocol is what is known as a _statistically maliciously robust_ and _proactively_ secure MPC protocol. Specifically this implies the following:
+- Statistically: the underlying protocols cannot be “broken” by an adversary regardless of the amount of computation power. This also means that they do not rely on any exotic cryptographic assumptions. (For practical reasons standard security of hash functions is still required.)
+- Maliciously Robust: the protocol can finish execution _correctly_ with up to `t` parties misbehaving by running rogue software or not participating.
+- Proactive: it is possible to "undo" a leakage of key material of at most `t` parties byt refreshing their key shares. That is, if a few servers are compromised it is possible to make the stolen material 100% useless without the need to regenerate a new public key.
+
+The MPC protocol is based on peer-reviewed cryptographic core protocols and peer reviewed modifications. For more modifications see [this paper](https://eprint.iacr.org/2023/815).

docs/guides/hardware.md

@@ -6,4 +6,8 @@ Validators perform all operations on ciphertext, which requires powerful machine
 
 ## Gateway
 
-The gateway can run on a medium machine with 4 cores and 8 GB of RAM, such as a [t3.xlarge](https://aws.amazon.com/fr/ec2/instance-types/t3/).
+The gateway can run on a medium machine with 4 cores and 8 GB of RAM, such as a [t3.xlarge](https://aws.amazon.com/ec2/instance-types/t3/).
+
+## TKMS
+
+The TKMS needs to carry out heavy cryptographic operations on the ciphertexts. We recommend using at least a [c5.4xlarge](https://aws.amazon.com/ec2/instance-types/c5/) instance or equivalent, with at least 16 physical cores.