Skip to content

Commit c3fbab8

Browse files
immortal-tofuimmortal-tofu
authored
docs(common): update architecture content (#350)
1 parent 9b09517 commit c3fbab8

8 files changed

Lines changed: 497 additions & 135 deletions

File tree

‎docs/protocol/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
## Protocol
44

55
- [FHE on Blockchain](architecture/overview.md)
6+
- [FHE library](architecture/library.md)
67
- [Coprocessor](architecture/coprocessor.md)
78
- [Gateway](architecture/gateway.md)
89
- [KMS](architecture/kms.md)

‎docs/protocol/architecture/coprocessor.md‎

Lines changed: 99 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,107 @@
11
# Coprocessor
22

3-
The coprocessor is the compute engine of FHEVM, designed to handle resource-intensive homomorphic operations.
3+
The Coprocessor is the FHEVM protocol’s off-chain computation engine. It performs the heavy cryptographic
4+
operations—specifically, fully homomorphic encryption (FHE) computations—on behalf of smart contracts that operate on
5+
encrypted data. Acting as a decentralized compute layer, the coprocessor bridges symbolic on-chain logic with real-world
6+
encrypted execution.
47

5-
### **Key functions**:
8+
It works in tandem with the Gateway, verifying encrypted inputs, executing FHE instructions, and maintaining
9+
synchronization of access permissions.
610

7-
1. **Execution**: Performs encrypted operations (e.g., _add_, _mul_) on ciphertexts using the evaluation key.
8-
2. **Ciphertext management**: Stores and retrieves ciphertexts securely in an off-chain database. Only handles are
9-
returned on-chain.
11+
## What is the Coprocessor?
1012

11-
## **Computation**
13+
The Coprocessor is an off-chain service that:
1214

13-
Encrypted computations are performed using the **evaluation key** on the coprocessor.
15+
- Listens to events emitted by host chains and the Gateway.
16+
- Executes FHE computations (`add`, `mul`, `div`, `cmp`, etc.) on ciphertexts.
17+
- Validates encrypted inputs and ZK proofs of correctness.
18+
- Maintains and updates a replica of the host chain’s Access Control Lists (ACLs).
19+
- Stores and serves encrypted data for decryption or bridging.
1420

15-
- **How it works**:
16-
1. The smart contract emits FHE operation events as symbolic instructions.
17-
2. These events are picked up by the coprocessor, which evaluates each operation individually using the evaluation
18-
key, without ever decrypting the data.
19-
3. The resulting ciphertext is persisted in the coprocessor database, while only a handle is returned on-chain.
20-
- **Data flow**:
21-
- **Source**: Blockchain smart contracts (via symbolic execution).
22-
- **Processing**: Coprocessor (using the evaluation key).
23-
- **Destination**: Blockchain (updated ciphertexts).
21+
Each coprocessor independently executes tasks and publishes verifiable results, enabling a publicly auditable and
22+
horizontally scalable confidential compute infrastructure .
2423

25-
<figure><img src="../.gitbook/assets/computation.png" alt="computation"><figcaption></figcaption></figure>
24+
## Responsibilities of the Coprocessor
25+
26+
### Encrypted Input Verification
27+
28+
When users submit encrypted values to the Gateway, each coprocessor:
29+
30+
- Verifies the associated Zero-Knowledge Proof of Knowledge (ZKPoK).
31+
- Extracts and unpacks individual ciphertexts from a packed submission.
32+
- Stores the ciphertexts under derived handles.
33+
- Signs the verified handles, embedding user and contract metadata.
34+
- Sends the signed data back to the Gateway for consensus.
35+
36+
This ensures only valid, well-formed encrypted values enter the system .
37+
38+
### FHE Computation Execution
39+
40+
When a smart contract executes a function over encrypted values, the on-chain logic emits symbolic computation events.
41+
Each coprocessor:
42+
43+
- Reads these events from the host chain node it runs.
44+
- Fetches associated ciphertexts from its storage.
45+
- Executes the required FHE operations using the TFHE-rs library (e.g., add, mul, select).
46+
- Stores the resulting ciphertext under a deterministically derived handle.
47+
- Optionally publishes a commitment (digest) of the ciphertext to the Gateway for verifiability.
48+
49+
This offloads expensive computation from the host chain while maintaining full determinism and auditability .
50+
51+
### ACL Replication
52+
53+
Coprocessors replicate the Access Control List (ACL) logic from host contracts. They:
54+
55+
- Listen to Allowed and AllowedForDecryption events.
56+
- Push updates to the Gateway.
57+
58+
This ensures decentralized enforcement of access rights, enabling proper handling of decryptions, bridges, and contract
59+
interactions .
60+
61+
### Ciphertext Commitment
62+
63+
To ensure verifiability and mitigate misbehavior, each coprocessor:
64+
65+
- Commits to ciphertext digests (via hash) when processing Allowed events.
66+
- Publishes these commitments to the Gateway.
67+
- Enables external verification of FHE computations.
68+
69+
This is essential for fraud-proof mechanisms and eventual slashing of malicious or faulty operators .
70+
71+
### Bridging & Decryption Support
72+
73+
Coprocessors assist in:
74+
75+
- Bridging encrypted values between host chains by generating new handles and signatures.
76+
- Preparing ciphertexts for public and user decryption using operations like Switch-n-Squash to normalize ciphertexts
77+
for the KMS.
78+
79+
These roles help maintain cross-chain interoperability and enable privacy-preserving data access for users and smart
80+
contracts .
81+
82+
## Security and Trust Assumptions
83+
84+
Coprocessors are designed to be minimally trusted and publicly verifiable. Every FHE computation or input verification
85+
they perform is accompanied by a cryptographic commitment (hash digest) and a signature, allowing anyone to
86+
independently verify correctness.
87+
88+
The protocol relies on a majority-honest assumption: as long as more than 50% of coprocessors are honest, results are
89+
valid. The Gateway aggregates responses and accepts outputs only when a majority consensus is reached.
90+
91+
To enforce honest behavior, coprocessors must stake $ZAMA tokens and are subject to slashing if caught
92+
misbehaving—either through automated checks or governance-based fraud proofs.
93+
94+
This model ensures correctness through transparency, resilience through decentralization, and integrity through economic
95+
incentives.
96+
97+
## Architecture & Scalability
98+
99+
The coprocessor architecture includes:
100+
101+
- Event listeners for host chains and the Gateway
102+
- A task queue for FHE and ACL update jobs
103+
- Worker threads that process tasks in parallel
104+
- A public storage layer (e.g., S3) for ciphertext availability
105+
106+
This modular setup supports horizontal scaling: adding more workers or machines increases throughput. Symbolic
107+
computation and delayed execution also ensure low gas costs on-chain .

‎docs/protocol/architecture/gateway.md‎

Lines changed: 82 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,87 @@
11
# Gateway
22

3-
The Gateway acts as the communication hub between the blockchain, the coprocessor, the KMS, and user-facing
4-
applications.
3+
The Gateway is a central orchestrator within Zama’s FHEVM protocol, playing a critical role in enabling secure,
4+
composable, and confidential smart contracts across multiple blockchains. It coordinates interactions between users,
5+
host chains, coprocessors, and the Key Management Service (KMS), ensuring that encrypted data flows securely and
6+
correctly through the system.
57

6-
### **Key functions**:
8+
## What is the Gateway?
79

8-
- **API for developers**: Exposes endpoints to submit encrypted inputs, request decryption, and manage user decryption.
9-
- **Proof validation**: Forwards ZKPoKs to the Coprocessor for verification.
10-
- **Off-chain coordination**: Handles smart contract and user decryption workflows in a verifiable and secure manner.
10+
The Gateway is a specialized blockchain component (implemented as an Arbitrum rollup) responsible for managing:
1111

12-
The Gateway abstracts complex cryptographic flows, simplifying developer integration.
12+
- Validation of encrypted inputs from users and applications.
13+
- Bridging of encrypted ciphertexts across different blockchains.
14+
- Decryption orchestration via KMS nodes.
15+
- Consensus enforcement among decentralized coprocessors.
16+
- Staking and reward distribution to operators participating in FHE computations.
17+
18+
It is designed to be trust-minimized: computations are independently verifiable, and no sensitive data or decryption
19+
keys are stored on the Gateway itself.
20+
21+
## Responsibilities of the Gateway
22+
23+
### Encrypted Input Validation
24+
25+
The Gateway ensures that encrypted values provided by users are well-formed and valid. It does this by:
26+
27+
- Accepting encrypted inputs along with Zero-Knowledge Proofs of Knowledge (ZKPoKs).
28+
- Emitting verification events for coprocessors to validate.
29+
- Aggregating signatures from a majority of coprocessors to generate attestations, which can then be used on-chain as
30+
trusted external values.
31+
32+
### Access Control Coordination
33+
34+
The Gateway maintains a synchronized copy of Access Control Lists (ACLs) from host chains, enabling it to independently
35+
determine if decryption or computation rights should be granted for a ciphertext. This helps enforce:
36+
37+
- Access permissions (allow)
38+
- Public decryption permissions (allowForDecryption)
39+
40+
These ACL updates are replicated by coprocessors and pushed to the Gateway for verification and enforcement.
41+
42+
### Decryption Orchestration
43+
44+
When a smart contract or user requests the decryption of an encrypted value:
45+
46+
1. The Gateway verifies ACL permissions.
47+
2. It then triggers the KMS to decrypt (either publicly or privately).
48+
3. Once the KMS returns signed results, the Gateway emits events that can be picked up by an oracle (for smart contract
49+
decryption) or returned to the user (for private decryption).
50+
51+
This ensures asynchronous, secure, and auditable decryption without the Gateway itself knowing the plaintext.
52+
53+
### Cross-Chain Bridging
54+
55+
The Gateway also handles bridging of encrypted handles between host chains. It:
56+
57+
- Verifies access rights on the source chain using its ACL copy.
58+
- Requests the coprocessors to compute new handles for the target chain.
59+
- Collects signatures from coprocessors.
60+
61+
Issues attestations allowing these handles to be used on the destination chain.
62+
63+
### Consensus and Slashing Enforcement
64+
65+
The Gateway enforces consensus across decentralized coprocessors and KMS nodes. If discrepancies occur:
66+
67+
- Coprocessors must provide commitments to ciphertexts.
68+
- Fraudulent or incorrect behavior can be challenged and slashed.
69+
- Governance mechanisms can be triggered for off-chain verification when necessary.
70+
71+
### Protocol Administration
72+
73+
The Gateway runs smart contracts that administer:
74+
75+
- Operator and participant registration (coprocessors, KMS nodes, host chains)
76+
- Key management and rotation
77+
- Bridging logic
78+
- Input validation and decryption workflows
79+
80+
## Security and Trust Assumptions
81+
82+
The Gateway is designed to operate without requiring trust:
83+
84+
- It does not perform any computation itself—it merely orchestrates and validates.
85+
- All actions are signed, and cryptographic verification is built into every step.
86+
87+
The protocol assumes no trust in the Gateway for security guarantees—it can be fully audited and replaced if necessary.

‎docs/protocol/architecture/hostchain.md‎

Lines changed: 50 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,58 @@
1-
# Host chain
1+
# Host contracts
22

3-
FHEVM smart contracts are Solidity contracts that interact with encrypted values through symbolic execution.
3+
## What Are Host Contracts?
44

5-
### **Symbolic execution in Solidity**
5+
Host contracts are smart contracts deployed on any supported blockchain (EVM or non-EVM) that act as trusted bridges
6+
between on-chain applications and the FHEVM protocol. They serve as the minimal and foundational interface that
7+
confidential smart contracts use to:
68

7-
- **Handles**: Smart contract operations return handles (references to ciphertexts), rather than directly manipulating
8-
encrypted data.
9-
- **Lazy Execution**: Actual computation is done off-chain by the coprocessor after the contract emits symbolic
10-
instructions.
9+
- Interact with encrypted data (handles)
10+
- Perform access control operations
11+
- Emit events for the off-chain components (coprocessors, Gateway)
1112

12-
This allows efficient, gas-minimized interaction with encrypted data, while preserving EVM compatibility.
13+
These host contracts are used indirectly by developers via the FHEVM Solidity library, abstracting away complexity and
14+
integrating smoothly into existing workflows.
1315

14-
### **Zero-Knowledge proofs of knowledge (ZKPoKs)**
16+
## Responsibilities of Host Contracts
1517

16-
FHEVM incorporates ZKPoKs to verify the correctness of encrypted inputs and outputs:
18+
### Trusted Interface Layer
1719

18-
- **Validation**: ZKPoKs ensure that inputs are correctly formed and correspond to known plaintexts without revealing
19-
sensitive data.
20-
- **Integrity**: They prevent misuse of ciphertexts and ensure the correctness of computations.
20+
Host contracts are the only on-chain components that:
2121

22-
By combining symbolic execution and ZKPoKs, FHEVM smart contracts maintain both privacy and verifiability.
22+
- Maintain and enforce Access Control Lists (ACLs) for ciphertexts.
23+
- Emit events that trigger coprocessor execution.
24+
- Validate access permissions (persistent, transient, or decryption-related).
25+
26+
They are effectively the on-chain authority for:
27+
28+
- Who is allowed to access a ciphertext
29+
- When and how they can use it
30+
- These ACLs are mirrored on the Gateway for off-chain enforcement and bridging.
31+
32+
### Access Control API
33+
34+
Host contracts expose access control logic via standardized function calls (wrapped by the FHEVM library):
35+
36+
- `allow(handle, address)`: Grants persistent access.
37+
- `allowTransient(handle, address)`: Grants temporary access for a single transaction.
38+
- `allowForDecryption(handle)`: Marks a handle as publicly decryptable.
39+
- `isAllowed(handle, address)`: Returns whether a given address has access.
40+
- `isSenderAllowed(handle)`: Checks if msg.sender is allowed to use a handle.
41+
42+
They also emit:
43+
44+
- `Allowed(handle, address)`
45+
- `AllowedForDecryption(handle)`
46+
47+
These events are crucial for triggering coprocessor state updates and ensuring proper ACL replication to the Gateway.
48+
49+
### Security Role
50+
51+
Although the FHE computation happens off-chain, host contracts play a critical role in protocol security by:
52+
53+
- Enforcing ACL-based gating
54+
- Ensuring only authorized contracts and users can decrypt or use a handle
55+
- Preventing misuse of encrypted data (e.g., computation without access)
56+
57+
Access attempts without proper authorization are rejected at the smart contract level, protecting both the integrity of
58+
confidential operations and user privacy.

0 commit comments

Comments
 (0)