Zama 백서

bitpro가 원문에서 글자만 모은 내용이에요. 표·그림·수식은 빠지거나 깨질 수 있어요. 전체 75쪽 중 1쪽

# Welcome **Welcome to the Zama Confidential Blockchain Protocol Docs.** The docs aim to guide you to build confidential dApps using Fully Homomorphic Encryption (FHE). ## Where to go next If you're completely new to FHE or the Zama Protocol, we suggest first checking out the [**Litepaper**](https://docs.zama.ai/protocol/zama-protocol-litepaper)**,** which offers a thorough overview of the protocol. Otherwise: 🟨 Go to [**Quick Start**](https://docs.zama.ai/protocol/solidity-guides/getting-started/quick-start-tutorial) to learn how to write your first confidential smart contract using FHEVM. 🟨 Go to [**Solidity Guides**](https://docs.zama.ai/protocol/solidity-guides) to explore how encrypted types, operations, ACLs, and other core features work in smart contracts. 🟨 Go to[ **Zama SDK** ](/protocol/sdk)to build a confidential dApp that can shield, transfer, and unshield tokens with Fully Homomorphic Encryption. 🟨 Go to [**Protocol Apps**](/protocol/protocol-apps) to understand governance, staking, confidential wrappers, and registry contracts for operators and token holders. 🟨 Go to [**FHE on Blockchain**](/protocol/protocol/overview) to learn the architecture in depth and understand how encrypted computation flows through both onchain and off-chain components. 🟨 Go to [**Examples**](https://docs.zama.org/protocol/examples/) to find reference and inspiration from smart contract examples and dApp examples. ## Help center Ask technical questions and discuss with the community. * [Community forum](https://community.zama.ai/c/fhevm/15) * [Discord channel](https://discord.com/invite/zama) * Reach us at <zama@support.org> # FHE on blockchain This section explains in depth the Zama Confidential Blockchain Protocol (Zama Protocol) and demonstrates how it can bring encrypted computation to smart contracts using Fully Homomorphic Encryption (FHE). FHEVM is the core technology that powers the Zama Protocol. It is composed of the following key components. <figure><img src="https://73267259-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvQCWCZ0z8Z2qor6JCa5P%2Fuploads%2FSB60dOWTlQGALOlVduAX%2FfhEVM%20(1).png?alt=media&amp;token=850a9280-e59f-41e2-8a58-4b7c2914a8dd" alt=""><figcaption></figcaption></figure> * [**FHEVM Solidity library**](/protocol/protocol/overview/library): Enables developers to write confidential smart contracts in plain Solidity using encrypted data types and operations. * [**Host contracts**](/protocol/protocol/overview/hostchain) : Trusted on-chain contracts deployed on EVM-compatible blockchains. They manage access control and trigger off-chain encrypted computation. * [**Coprocessors**](/protocol/protocol/overview/coprocessor) – Decentralized services that verify encrypted inputs, run FHE computations, and commit results. * [**Gateway**](/protocol/protocol/overview/gateway) **–** The central orchestrator of the protocol. It validates encrypted inputs, manages access control lists (ACLs), bridges ciphertexts across chains, and coordinates coprocessors and the KMS. * [**Key Management Service (KMS)**](/protocol/protocol/overview/kms) – A threshold MPC network that generates and rotates FHE keys, and handles secure, verifiable decryption. * **Relayer** – A lightweight off-chain service that helps users interact with the Gateway by forwarding encryption or decryption requests. # FHE library This document offers a high-level overview of the **FHEVM library**, helping you understand how it fits into the broader Zama Protocol. To learn how to use it in practice, see the [Solidity Guides](https://docs.zama.ai/protocol/solidity-guides). ## What is FHEVM library? The FHEVM library enables developers to build smart contracts that operate on encrypted data—without requiring any knowledge of cryptography. It extends the standard Solidity development flow with: * Encrypted data types * Arithmetic, logical, and conditional operations on encrypted values * Fine-grained access control * Secure input handling and attestation support This library serves as an **abstraction layer** over Fully Homomorphic Encryption (FHE) and interacts seamlessly with off-chain components such as the **Coprocessors** and the **Gateway**. ## Key features ### Encrypted data types The library introduces encrypted variants of common Solidity types, implemented as user-defined value types. Internally, these are represented as `bytes32` handles that point to encrypted values stored off-chain. | Category | Types | | ----------------- | ------------------------------------ | | Booleans | `ebool` | | Unsigned integers | `euint8`, `euint16`, ..., `euint256` | | Signed integers | `eint8`, `eint16,` ..., `eint256` | | Addresses | `eaddress` | → See the full guide of [Encrypted data types](https://docs.zama.ai/protocol/solidity-guides/smart-contract/types). ### FHE operations Each encrypted type supports operations similar to its plaintext counterpart: * Arithmetic: `add`, `sub`, `mul`, `div`, `rem`, `neg` * Logic: `and`, `or`, `xor`, `not` * Comparison: `lt`, `gt`, `le`, `ge`, `eq`, `ne`, `min`, `max` * Bit manipulation: `shl`, `shr`, `rotl`, `rotr` These operations are symbolically executed on-chain by generating new handles and emitting events for coprocessors to process the actual FHE computation off-chain. Example: ```solidity function compute(euint64 x, euint64 y, euint64 z) public returns (euint64) { euint64 result = FHE.mul(FHE.add(x, y), z); return result; } ``` → See the full guide of [Operations on encrypted types](https://docs.zama.ai/protocol/solidity-guides/smart-contract/operations). ### Branching with encrypted Conditions Direct if or require statements are not compatible with encrypted booleans. Instead, the library provides a `select`operator to emulate conditional logic without revealing which branch was taken: ```solidity ebool condition = FHE.lte(x, y); euint64 result = FHE.select(condition, valueIfTrue, valueIfFalse); ``` This preserves confidentiality even in conditional logic. → See the full guide of [Branching](https://docs.zama.ai/protocol/solidity-guides/smart-contract/logics/conditions). ### Handling external encrypted inputs When users want to pass encrypted inputs (e.g., values they’ve encrypted off-chain or bridged from another chain), they provide: * external values * A list of coprocessor signatures (attestation) The function `fromExternal` is used to validate the attestation and extract a usable encrypted handle: ```solidity function handleInput(externalEuint64 param1, externalEbool param2, bytes calldata attestation) public { euint64 val = FHE.fromExternal(param1, attestation); ebool flag = FHE.fromExternal(param2, attestation); } ``` This ensures that only authorized, well-formed ciphertexts are accepted by smart contracts. → See the full guide of [Encrypted input](https://docs.zama.ai/protocol/solidity-guides/smart-contract/inputs). ### Access control The FHE library also exposes methods for managing access to encrypted values using the ACL maintained by host contracts: * `allow(handle, address)`: Grant persistent access * `allowTransient(handle, address)`: Grant access for the current transaction only * `allowForDecryption(handle)`: Make handle publicly decryptable * `isAllowed(handle, address)`: Check if address has access * `isSenderAllowed(handle)`: Shortcut for checking msg.sender permissions These `allow` methods emit events consumed by the coprocessors to replicate the ACL state in the Gateway. → See the full guide of [ACL](https://docs.zama.ai/protocol/solidity-guides/smart-contract/acl). ### Pseudo-random encrypted values The library allows generation of pseudo-random encrypted integers, useful for games, lotteries, or randomized logic: * `randEuintXX()` * `randEuintXXBounded`(uint bound) These are deterministic across coprocessors and indistinguishable to external observers. → See the full guide of [Generate random number](https://docs.zama.ai/protocol/solidity-guides/smart-contract/operations/random). # Host contracts This document explains one of the key components of the Zama Protocol - Host contracts. ## What are host contracts? Host contracts are smart contracts deployed on any supported blockchain (EVM or non-EVM) that act as trusted bridges between on-chain applications and the FHEVM protocol. They serve as the minimal and foundational interface that confidential smart contracts use to: * Interact with encrypted data (handles) * Perform access control operations * Emit events for the off-chain components (coprocessors, Gateway) These host contracts are used indirectly by developers via the FHEVM Solidity library, abstracting away complexity and integrating smoothly into existing workflows. ## Responsibilities of host contracts ### Trusted interface layer Host contracts are the only on-chain components that: * Maintain and enforce Access Control Lists (ACLs) for ciphertexts. * Emit events that trigger coprocessor execution. * Validate access permissions (persistent, transient, or decryption-related). They are effectively the on-chain authority for: * Who is allowed to access a ciphertext * When and how they can use it * These ACLs are mirrored on the Gateway for off-chain enforcement and bridging. ### Access Control API Host contracts expose access control logic via standardized function calls (wrapped by the FHEVM library): * `allow(handle, address)`: Grants persistent access. * `allowTransient(handle, address)`: Grants temporary access for a single transaction. * `allowForDecryption(handle)`: Marks a handle as publicly decryptable. * `isAllowed(handle, address)`: Returns whether a given address has access. * `isSenderAllowed(handle)`: Checks if msg.sender is allowed to use a handle. They also emit: * `Allowed(handle, address)` * `AllowedForDecryption(handle)` These events are crucial for triggering coprocessor state updates and ensuring proper ACL replication to the Gateway. → See the full guide of [ACL](https://docs.zama.ai/protocol/solidity-guides/smart-contract/acl). ### Security role Although the FHE computation happens off-chain, host contracts play a critical role in protocol security by: * Enforcing ACL-based gating * Ensuring only authorized contracts and users can decrypt or use a handle * Preventing misuse of encrypted data (e.g., computation without access) Access attempts without proper authorization are rejected at the smart contract level, protecting both the integrity of confidential operations and user privacy. # Coprocessor This document explains one of the key components of the Zama Protocol - Coprocessor, the Zama Protocol’s off-chain computation engine. ## What is the Coprocessor? Coprocessor performs the heavy cryptographic operations—specifically, fully homomorphic encryption (FHE) computations—on behalf of smart contracts that operate on encrypted data. Acting as a decentralized compute layer, the coprocessor bridges symbolic on-chain logic with real-world encrypted execution. Coprocessor works together with the Gateway, verifying encrypted inputs, executing FHE instructions, and maintaining synchronization of access permissions, in particular: * Listens to events emitted by host chains and the Gateway. * Executes FHE computations (`add`, `mul`, `div`, `cmp`, etc.) on ciphertexts. * Validates encrypted inputs and ZK proofs of correctness. * Maintains and updates a replica of the host chain’s Access Control Lists (ACLs). * Stores and serves encrypted data for decryption or bridging. Each coprocessor independently executes tasks and publishes verifiable results, enabling a publicly auditable and horizontally scalable confidential compute infrastructure . ## Responsibilities of the Coprocessor ### Encrypted input verification When users submit encrypted values to the Gateway, each coprocessor: * Verifies the associated Zero-Knowledge Proof of Knowledge (ZKPoK). * Extracts and unpacks individual ciphertexts from a packed submission. * Stores the ciphertexts under derived handles. * Signs the verified handles, embedding user and contract metadata. * Sends the signed data back to the Gateway for consensus. This ensures only valid, well-formed encrypted values enter the system . ### FHE computation execution When a smart contract executes a function over encrypted values, the on-chain logic emits symbolic computation events.\ Each coprocessor: * Reads these events from the host chain node it runs. * Fetches associated ciphertexts from its storage. * Executes the required FHE operations using the TFHE-rs library (e.g., add, mul, select). * Stores the resulting ciphertext under a deterministically derived handle. * Optionally publishes a commitment (digest) of the ciphertext to the Gateway for verifiability. This offloads expensive computation from the host chain while maintaining full determinism and auditability . ### ACL replication Coprocessors replicate the Access Control List (ACL) logic from host contracts. They: * Listen to Allowed and AllowedForDecryption events. * Push updates to the Gateway. This ensures decentralized enforcement of access rights, enabling proper handling of decryptions, bridges, and contract interactions . ### Ciphertext commitment To ensure verifiability and mitigate misbehavior, each coprocessor: * Commits to ciphertext digests (via hash) when processing Allowed events. * Publishes these commitments to the Gateway. * Enables external verification of FHE computations. This is essential for fraud-proof mechanisms and eventual slashing of malicious or faulty operators . ### Bridging & decryption support Coprocessors assist in: * Bridging encrypted values between host chains by generating new handles and signatures. * Preparing ciphertexts for public and user decryption using operations like Switch-n-Squash to normalize ciphertexts for the KMS. These roles help maintain cross-chain interoperability and enable privacy-preserving data access for users and smart contracts . ## Security and trust assumptions Coprocessors are designed to be minimally trusted and publicly verifiable. Every FHE computation or input verification they perform is accompanied by a cryptographic commitment (hash digest) and a signature, allowing anyone to independently verify correctness. The protocol relies on a majority-honest assumption: as long as more than 50% of coprocessors are honest, results are valid. The Gateway aggregates responses and accepts outputs only when a majority consensus is reached. To enforce honest behavior, coprocessors must stake $ZAMA tokens and are subject to slashing if caught misbehaving—either through automated checks or governance-based fraud proofs. This model ensures correctness through transparency, resilience through decentralization, and integrity through economic incentives. ## Architecture & Scalability The coprocessor architecture includes: * Event listeners for host chains and the Gateway * A task queue for FHE and ACL update jobs * Worker threads that process tasks in parallel * A public storage layer (e.g., S3) for ciphertext availability This modular setup supports horizontal scaling: adding more workers or machines increases throughput. Symbolic computation and delayed execution also ensure low gas costs on-chain . # Gateway This document explains one of the key components of the Zama Protocol - Gateway, the central orchestrator within Zama’s FHEVM protocol, coordinates interactions between users, host chains, coprocessors, and the Key Management Service (KMS), ensuring that encrypted data flows securely and correctly through the system. ## What is the Gateway? The Gateway is a specialized blockchain component (implemented as an Arbitrum rollup) responsible for managing: * Validation of encrypted inputs from users and applications. * Bridging of encrypted ciphertexts across different blockchains. * Decryption orchestration via KMS nodes. * Consensus enforcement among decentralized coprocessors. * Staking and reward distribution to operators participating in FHE computations. It is designed to be trust-minimized: computations are independently verifiable, and no sensitive data or decryption keys are stored on the Gateway itself. ## Responsibilities of the Gateway ### Encrypted input validation The Gateway ensures that encrypted values provided by users are well-formed and valid. It does this by: * Accepting encrypted inputs along with Zero-Knowledge Proofs of Knowledge (ZKPoKs). * Emitting verification events for coprocessors to validate. * Aggregating signatures from a majority of coprocessors to generate attestations, which can then be used on-chain as trusted external values. ### Access Control coordination The Gateway maintains a synchronized copy of Access Control Lists (ACLs) from host chains, enabling it to independently determine if decryption or computation rights should be granted for a ciphertext. This helps enforce: * Access permissions (allow) * Public decryption permissions (allowForDecryption) These ACL updates are replicated by coprocessors and pushed to the Gateway for verification and enforcement. ### Decryption orchestration When a smart contract or user requests the decryption of an encrypted value: 1. The Gateway verifies ACL permissions. 2. It then triggers the KMS to decrypt (either publicly or privately). 3. Once the KMS returns signed results, the Gateway emits events that can be picked up by an oracle (for smart contract decryption) or returned to the user (for private decryption). This ensures asynchronous, secure, and auditable decryption without the Gateway itself knowing the plaintext. ### Cross-chain bridging The Gateway also handles bridging of encrypted handles between host chains. It: * Verifies access rights on the source chain using its ACL copy. * Requests the coprocessors to compute new handles for the target chain. * Collects signatures from coprocessors. Issues attestations allowing these handles to be used on the destination chain. ### Consensus and slashing enforcement The Gateway enforces consensus across decentralized coprocessors and KMS nodes. If discrepancies occur: * Coprocessors must provide commitments to ciphertexts. * Fraudulent or incorrect behavior can be challenged and slashed. * Governance mechanisms can be triggered for off-chain verification when necessary. ### Protocol administration The Gateway runs smart contracts that administer: * Operator and participant registration (coprocessors, KMS nodes, host chains) * Key management and rotation * Bridging logic * Input validation and decryption workflows ## Security and trust assumptions The Gateway is designed to operate without requiring trust: * It does not perform any computation itself—it merely orchestrates and validates. * All actions are signed, and cryptographic verification is built into every step. The protocol assumes no trust in the Gateway for security guarantees—it can be fully audited and replaced if necessary. # KMS This document explains one of the key components of the Zama Protocol - The Key Management Service (KMS), responsible for the secure generation, management, and usage of FHE keys needed to enable confidential smart contracts. ## What is the KMS? The KMS is a decentralized network of several nodes (also called "parties") that run an MPC (Multi-Party Computation) protocol: * Securely generate global FHE keys * Decrypt ciphertexts securely for public and user-targeted decryptions * Support zero-knowledge proof infrastructure * Manage key lifecycles with NIST compliance It works entirely off-chain, but is orchestrated through the Gateway, which initiates and tracks all key-related operations. This separation of powers ensures strong decentralization and auditability. ## Key responsibilities ### FHE threshold key generation * The KMS securely generates a global public/private key pair used across all host chains. * This key enables compo
프로젝트로 돌아가기