fhevm

The @cli-fhevm-sdk/load-test is a protocol load-testing tool designed for both legacy and v2 relayers. It provides model-aware load generation using the workspace toolkit and @fhevm/sdk. The tool supports pre-generated payload pools, implementation-agnostic client evidence, Prometheus metrics, and machine-readable reports.

The standard execution lifecycle is: plan → explicit prepare (when needed) → execute → collect → report.

The FHEVM Gateway is a suite of smart contracts designed to enable the decryption of FHE ciphertexts from various host chains. It serves as a central intermediary between host chains, the Key Management Service (KMS), and protocol coprocessors.

Its primary responsibilities include:

• Verifying decryption request legitimacy.
• Centralizing access to multi-chain ciphertexts and their commitments.
• Orchestrating KMS materials and protocol payments.

The Relayer acts as the bridge between FHEVM host chains (such as Ethereum) and the Gateway. It provides an HTTP interface to interact with FHE operations and exposes essential key material.

Core Capabilities:

• Public Decryption: Relays HTTP requests for public decryption and returns plaintext responses.
• Input Proof Verification: Relays HTTP requests for input-proof verification and returns validity attestations.
• User Decryption: Relays HTTP requests to re-encrypt data under a user-provided public key (subject to ciphertext-handle access control).
• Key Material: Exposes URLs for the FHE public key and Common Reference String (CRS).

FHEVM is the core framework of the Zama Confidential Blockchain Protocol. It enables the creation of confidential smart contracts on EVM-compatible blockchains by using Fully Homomorphic Encryption (FHE). This allows encrypted data to be processed directly on-chain while maintaining confidentiality and composability.

Key guarantees include:

• End-to-end encryption: Transactions and state data are encrypted and never visible to unauthorized parties.
• On-chain composability: Encrypted states can be updated and composed with other states while remaining encrypted.
• Co-existence: Encrypted state lives alongside public state without impacting existing non-confidential dApps.

The mock-coprocessor is a long-running TypeScript daemon designed for mocked testnet experimentation. It imitates the production FHEVM coprocessor by polling deployed FHEVMExecutor and ConfidentialBridge contracts on configured chains.

Key behaviors:

• It replays FHE operations in plaintext.
• It stores results in a shared SQLite database.
• It uses event logs and arithmetic to simulate behavior.

Warning: This tool uses no real cryptography, no FHE, and no MPC. It is intended for end-to-end integration smoke tests and is not suitable for any security-sensitive context or as a replacement for a real coprocessor in production.

The FHEVM Relayer JavaScript SDK allows developers to interact with FHEVM smart contracts without needing to manage direct interactions with the Gateway Chain.

Key Workflow:

• Simplified Client Requirements: FHEVM clients only require a wallet on the FHEVM host chain.
• Relayer Abstraction: All interactions with the Gateway chain are abstracted into HTTP calls to Zama's Relayer.
• Gas Management: The Relayer handles the gas payments on the Gateway chain on behalf of the user.

The @fhevm/sdk is the JavaScript/TypeScript SDK designed for building applications on FHEVM (Fully Homomorphic Encryption Virtual Machine) chains.

It enables developers to build privacy-preserving applications by handling the following lifecycle in the browser:

1. Encrypting values: Encrypting data locally before it is sent to the blockchain.
2. Sending encrypted handles: Passing encrypted references to smart contracts.
3. Decrypting results: Retrieving and decrypting data from the chain.

Crucially, the SDK abstracts the underlying Zama Protocol, so users do not need to interact with the protocol directly to achieve privacy.

These examples demonstrate how to build privacy-preserving auction mechanisms using FHEVM.

### Auction Examples:
- **Sealed-Bid Auction**: A complete implementation of an auction where bids are kept private until the auction concludes.
  - Includes a detailed **Tutorial** for implementation.

The KMSGeneration contract is used to orchestrate the generation of public materials required for the fhevm Gateway protocol. It manages the creation of FHE keys and Common Reference Strings (CRSs).

Access Control: All non-view functions in this contract are restricted. Only the owner of the contract or the KMS nodes' transaction senders can execute state-changing operations.