This document provides guidance on using the new Zama plugin for the the official Remix IDE, which replaces the deprecated Remix fork. This allows you to develop and manage contracts directly in Remix by simply loading the fhEVM plugin.

Installing the Zama plugin

1. Go to the "Plugin Manager" page

2. Click on "Connect to a Local Plugin"

3. Fill the name with "Zama" and the "Url" with "https://remix.zama.ai/"

4. Keep "Iframe" and "Side panel" and validate

Configuring the Zama plugin

After connecting to the Zama plugin, follow the steps to configure it:

1. Click on the plugin button located on the left of the screen

2. Use the Zama Coprocessor - Sepolia settings or use a custom gateway and contracts settings.

Afterwards, you will be able to deploy and use any contract that you chose to compile via this plugin interface.

This document introduces the fundamentals of writing confidential smart contracts using the fhEVM. You'll learn how to create contracts that can perform computations on encrypted data while maintaining data privacy.

In this guide, we'll walk through creating a basic smart contract that demonstrates core fhEVM concepts and encrypted operations.

Your first smart contract

Let’s build a simple Encrypted Counter smart contract to demonstrate the configuration process and the use of encrypted state variables.

Writing the contract

Create a new file called EncryptedCounter.sol in your contracts/ folder and add the following code:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import "fhevm/lib/TFHE.sol";
import { SepoliaZamaFHEVMConfig } from "fhevm/config/ZamaFHEVMConfig.sol";

/// @title EncryptedCounter1
/// @notice A basic contract demonstrating the setup of encrypted types
/// @dev Uses TFHE library for fully homomorphic encryption operations
/// @custom:experimental This is a minimal example contract intended only for learning purposes
/// @custom:notice This contract has limited real-world utility and serves primarily as a starting point
/// for understanding how to implement basic FHE operations in Solidity
contract EncryptedCounter1 is SepoliaZamaFHEVMConfig {
  euint8 internal counter;
  euint8 internal immutable CONST_ONE;

  constructor() {
    // Initialize counter with an encrypted zero value
    counter = TFHE.asEuint8(0);
    TFHE.allowThis(counter);
    // Save on gas by computing the constant here
    CONST_ONE = TFHE.asEuint8(1);
    TFHE.allowThis(CONST_ONE);
  }

  function increment() public {
    // Perform encrypted addition to increment the counter
    counter = TFHE.add(counter, CONST_ONE);
    TFHE.allowThis(counter);
  }
}

How it works

1. Configuring fhEVM: The contract inherits from SepoliaZamaFHEVMConfig which provides the necessary configuration for local development and testing. This configuration includes the addresses of the TFHE library and Gateway contracts.

   When deploying to different networks, you can use the appropriate configuration:

   Copy

   // For Sepolia testnet
   import { SepoliaZamaFHEVMConfig } from "fhevm/config/ZamaFHEVMConfig.sol";
   contract MyContract is SepoliaZamaFHEVMConfig { ... }

   The configuration handles setting up:

   • TFHE library address for encrypted operations

   • Network-specific parameters

2. Initializing encrypted variables:

   • The counter variable is set to an encrypted 0 using TFHE.asEuint8(0).

   • Permissions are granted to the contract itself for the counter ciphertext using TFHE.allowThis(counter).

   • A constant CONST_ONE is initialized as an encrypted value to represent the number 1.

3. Encrypted operations: The increment() function adds the encrypted constant CONST_ONE to the counter using TFHE.add.

Limitations:

There are two notable issues with this contract:

1. Counter value visibility: Since the counter is incremented by a fixed value, observers could deduce its value by analyzing blockchain events. To address this, see the documentation on:

   • encryption and secure inputs

2. Access control for counter: The counter is encrypted, but no access is granted to decrypt or view its value. Without proper ACL permissions, the counter remains inaccessible to users. To resolve this, refer to:

   • decryption

   • re-encryption

Testing

With any contracts that you write you will need to write tests as well. You can start by using something like this as a template:

import { createInstance } from "../instance";
import { getSigners, initSigners } from "../signers";
import { ethers } from "hardhat";

describe("EncryptedCounter1", function () {
  before(async function () {
    await initSigners(); // Initialize signers
    this.signers = await getSigners();
  });

  beforeEach(async function () {
    const CounterFactory = await ethers.getContractFactory("EncryptedCounter1");
    this.counterContract = await CounterFactory.connect(this.signers.alice).deploy();
    await this.counterContract.waitForDeployment();
    this.contractAddress = await this.counterContract.getAddress();
    this.instances = await createInstance();
  });

  it("should increment the counter", async function () {
    // Perform the increment action
    const tx = await this.counterContract.increment();
    await tx.wait();
  });
});

How the tests work

The test file demonstrates key concepts for testing fhEVM smart contracts:

1. Test setup:

   • before: Initializes test signers (users) that will interact with the contract

   • beforeEach: Deploys a fresh instance of the contract before each test

   • Creates FHE instances for each signer to handle encryption/decryption

2. Test structure:

   Copy

   describe("Contract Name", function() {
     // Setup hooks
     before(async function() { ... })
     beforeEach(async function() { ... })
   
     // Individual test cases
     it("should do something", async function() { ... })
   });

3. Key components:

   • createInstance(): Sets up FHE instances for each signer to handle encrypted operations

   • getSigners(): Provides test accounts to interact with the contract

   • contractFactory.deploy(): Creates a new contract instance for testing

   • tx.wait(): Ensures transactions are mined before continuing

Best practices

General best practices

• Deploy fresh contract instances for each test to ensure isolation

• Use descriptive test names that explain the expected behavior

• Handle asynchronous operations properly with async/await

• Set up proper encryption instances for testing encrypted values

Next steps

Congratulations! You’ve configured and written your first confidential smart contract. Here are some ideas to expand your knowledge:

• Explore advanced configurations: Customize the FHEVMConfig to suit specific encryption requirements.

• Add functionalities: Extend the contract by adding decrement functionality or resetting the counter.

• Integrate frontend: Learn how to decrypt and display encrypted data in a dApp using the fhevmjs library.

Introduction

fhEVM is a protocol enabling confidential smart contracts on EVM-compatible blockchains. By leveraging Fully Homomorphic Encryption (FHE), fhEVM ensures complete data privacy without sacrificing composability or usability.

Core principles

The design of fhEVM is guided by the following principles:

1. Preserving security: No impact on the underlying blockchain's security guarantees.

2. Public verifiability: All computations are publicly verifiable while keeping data confidential.

3. Developer accessibility: Build confidential smart contracts using familiar Solidity tooling, without requiring cryptographic expertise.

4. Composability: Confidential smart contracts are fully interoperable with each other and public contracts.

Key features

Encrypted data types

fhEVM introduces encrypted data types compatible with Solidity:

• Booleans: ebool

• Unsigned Integers: euint4, euint8, euint16, euint32, euint64, euint128, euint256

• Addresses: eaddress

• Bytes: ebytes64, ebytes128, ebytes256

• Input: einput for handling encrypted input data

Encrypted data is represented as ciphertext handles, ensuring secure computation and interaction.

For more information see use of encrypted types.

Casting types

fhEVM provides functions to cast between encrypted types:

• Casting between encrypted types: TFHE.asEbool converts encrypted integers to encrypted booleans

• Casting to encrypted types: TFHE.asEuintX converts plaintext values to encrypted types

• Casting to encrypted addresses: TFHE.asEaddress converts plaintext addresses to encrypted addresses

• Casting to encrypted bytes: TFHE.asEbytesX converts plaintext bytes to encrypted bytes

For more information see use of encrypted types.

Confidential computation

fhEVM enables symbolic execution of encrypted operations, supporting:

• Arithmetic: TFHE.add, TFHE.sub, TFHE.mul, TFHE.min, TFHE.max, TFHE.neg, TFHE.div, TFHE.rem

  • Note: div and rem operations are supported only with plaintext divisors

• Bitwise: TFHE.and, TFHE.or, TFHE.xor, TFHE.not, TFHE.shl, TFHE.shr, TFHE.rotl, TFHE.rotr

• Comparison: TFHE.eq, TFHE.ne, TFHE.lt, TFHE.le, TFHE.gt, TFHE.ge

• Advanced: TFHE.select for branching on encrypted conditions, TFHE.randEuintX for on-chain randomness.

For more information on operations, see Operations on encrypted types.

For more information on conditional branching, see Conditional logic in FHE.

For more information on random number generation, see Generate Random Encrypted Numbers.

Access control mechanism

fhEVM enforces access control with a blockchain-based Access Control List (ACL):

• Persistent access: TFHE.allow, TFHE.allowThis grants permanent permissions for ciphertexts.

• Transient access: TFHE.allowTransient provides temporary access for specific transactions.

• Validation: TFHE.isSenderAllowed ensures that only authorized entities can interact with ciphertexts.

For more information see ACL.

Architectural overview

The fhEVM architecture provides the foundation for confidential smart contracts on EVM-compatible blockchains. At its core is FHE, a cryptographic technique enabling computations directly on encrypted data, ensuring privacy at every stage.

This system relies on three key types:

• The public key: used for encrypting data.

• The private key: used for decryption and securely managed by the Key Management System or KMS

• The evaluation key: enabling encrypted computations performed by the coprocessor.

The fhEVM leverages Zama's TFHE library, integrating seamlessly with blockchain environments to address transparency, composability, and scalability challenges. Its hybrid architecture combines:

• On-chain smart contracts for encrypted state management and access controls.

• Off-chain coprocessors for resource-intensive FHE computations.

• The Gateway to coordinate between blockchain, KMS, and coprocessors.

• The KMS for secure cryptographic key management and proof validation.

This architecture enables developers to write private, composable smart contracts using symbolic execution and zero-knowledge proofs, ensuring data confidentiality and computational integrity.

For a detailed exploration of the fhEVM architecture, including components, workflows, and deployment models, see Architecture Overview.

Get started

Learn the basics of fhEVM, set it up, and make it run with ease.

Develop a fhEVM smart contract

Start developing fhEVM smart contracts in Solidity by exploring its core features, discovering essential guides, and learning more with user-friendly tutorials.

Explore more

Access to additional resources and join the Zama community.

References

Refer to the API and access additional resources for in-depth explanations while working with fhEVM.

Supports

Ask technical questions and discuss with the community. Our team of experts usually answers within 24 hours in working days.

Developers

Collaborate with us to advance the FHE spaces and drive innovation together.

This guide walks you through developing secure and efficient confidential smart contracts using fhEVM. Whether you're new to Fully Homomorphic Encryption (FHE) or an experienced blockchain developer, we'll cover everything you need to know - from setting up your development environment to deploying your first encrypted contract.

Network information

If you need access to a Sepolia node and aren’t sure how to proceed, consider using a node provider like , Infura, or similar services. These providers offer easy setup and management, allowing you to create an API key to connect to the network seamlessly.

Getting test ETH

You can get test ETH for Sepolia from these faucets:

• Alchemy Sepolia Faucet - https://www.alchemy.com/faucets/ethereum-sepolia

• QuickNode Sepolia Faucet - https://faucet.quicknode.com/ethereum/sepolia

Configuring Sepolia on your wallet

Most Ethereum wallets have built-in support for testnets like Sepolia. You can add Sepolia to your wallet in two ways:

• Automatic configuration: Many wallets like MetaMask have Sepolia pre-configured. Simply open your network selector and choose "Show/hide test networks" to enable testnet visibility.

• Manual configuration: The exact steps for manual configuration will vary by wallet, but generally involve:

1. Opening network settings

2. Selecting "Add Network" or "Add Network Manually"

3. Filling in the above information

4. Saving the configuration

Step-by-step workflow

1. (Optional) Learn the overall architecture

Before diving into development, we recommend understanding the overall architecture of fhEVM:

This knowledge will help you make better design decisions when building your confidential smart contracts.

2. Use the Hardhat template

• Why Hardhat?: It is a powerful Solidity development environment, offering tools for writing, testing, and deploying contracts to the fhEVM using TypeScript.

• Benefit: The template provides a pre-configured setup tailored to confidential smart contracts, saving development time and ensuring compatibility.

3. Configure the contract

Choose and inherit the correct configuration based on the environment:

• Mock network: For local testing and development.

• Testnets (e.g., Sepolia): For deploying to public test networks.

• Mainnet: When deploying to production.

4. Begin with unencrypted logic

Develop your contract as you would for a traditional EVM chain:

• Use cleartext variables and basic logic to simplify debugging and reasoning about the contract’s behavior.

• Focus on implementing core functionality without adding encryption initially.

• Creating a basic encrypted counter contract

• Understanding the configuration process

• Working with encrypted state variables

Key resources for working with encrypted types:

5. Add encryption

Once the logic is stable, integrate the TFHE Solidity library to enable encryption:

• Convert sensitive variables: Replace plaintext types like uintX with encrypted types such as euintX.

• Enable confidentiality: Encrypted variables and operations ensure sensitive data remains private while still being processed.

Learn how to implement core encryption operations:

6. Follow best practices

Throughout the documentation, you'll find sections marked with 🔧 that highlight important best practices. These include:

• Optimized data types: Use appropriately sized encrypted types (euint8, euint16, etc.) to minimize gas costs.

• Scalar operands: Whenever possible, use scalar operands in operations to reduce computation and gas usage.

• Overflow handling: Manage arithmetic overflows in encrypted operations using conditional logic (TFHE.select).

• Secure access control: Use TFHE.allow and TFHE.isSenderAllowed to implement robust ACL (Access Control List) mechanisms for encrypted values.

• Reencryption patterns: Follow the recommended approaches for reencryption to share or repurpose encrypted data securely.

7. Leverage example templates

• Why templates?: They demonstrate common patterns and best practices for encrypted operations, such as governance, token standards, and utility contracts.

• How to use: Extend or customize these templates to suit your application’s needs.

Contract examples

Throughout the documentation you will encounter many Counter contract examples. These examples are designed to guide you step-by-step through the development of confidential smart contracts, introducing new concepts progressively to deepen your understanding of fhEVM.

The primary example, Counter.sol, is enhanced in stages to demonstrate a variety of features and best practices for encrypted computations.

Each iteration of the counter will build upon previous concepts while introducing new functionality, helping you understand how to develop robust confidential smart contracts.

Table of all addresses

Save this in your .env file:

This document provides guidance on using the fhEVM in other development environments.

Foundry

The fhEVM does not work with Foundry as Foundry employs its own EVM, preventing us from incorporating a mock for our precompiled contract. An is exploring the possibility of incorporating a plugin system for precompiles, which could potentially pave the way for the utilization of Foundry at a later stage.

However, you could still use Foundry with the mocked version of the fhEVM, but please be aware that this approach is NOT recommended, since the mocked version is not fully equivalent to the real fhEVM node's implementation (see warning in ). In order to do this, you will need to rename your TFHE.sol imports from fhevm/lib/TFHE.sol to fhevm/mocks/TFHE.sol in your solidity source files.

This document guides you to start with fhEVM by using our Hardhat template.

This template allows you to launch an fhEVM Docker image and run your smart contract on it. For more information, refer to the README.

Features of the hardhat template

The Hardhat template comes pre-configured with tools and libraries to streamline the development process:

• Frameworks and libraries:

  • Hardhat: Compile, deploy, and test smart contracts.

  • TypeChain: Generate TypeScript bindings for contracts.

  • Ethers.js: Ethereum library for interactions.

  • Solhint: Linter for Solidity code.

  • Solcover: Code coverage analysis.

  • Prettier Plugin Solidity: Solidity code formatter.

• Default configurations: Includes sensible default configurations for tools like Prettier, Solhint, and ESLint.

• GitHub actions: Pre-configured for CI/CD pipelines to lint and test contracts on every push or pull request.

Getting started

Prerequisites

1. Install pnpm for dependency management.

2. Set up a mnemonic: Create a .env file by copying .env.example:

   Copy

   cp .env.example .env

   Generate a mnemonic using this tool if needed.

3. Install dependencies: Ensure you’re using Node.js v20 or later:

   Copy

   pnpm install

Commands overview

Here’s a list of essential commands to work with the Hardhat template:

Mocked mode vs non-mocked mode

Mocked mode

Mocked mode allows faster testing by simulating FHE operations. This mode runs tests on a local Hardhat network without requiring a real fhEVM node. Use the following commands:

• Run tests:

  Copy

  pnpm test

• Analyze coverage:

  Copy

  pnpm coverage

Note: Mocked mode approximates gas consumption for FHE operations but may slightly differ from actual fhEVM behavior.

Non-mocked mode

Non-mocked mode uses a real fhEVM node, such as the coprocessor on the Sepolia test network.

• Run tests on Sepolia:

  Copy

  npx hardhat test [PATH_TO_TEST] --network sepolia

• Requirements:

  1. Fund test accounts on Sepolia.

  2. Pass the correct FHEVMConfig struct in your smart contract’s constructor.

Note: Refer to the fhEVM documentation for configuring FHEVMConfig.

Development tips

Syntax highlighting

For Solidity syntax highlighting, use the Hardhat Solidity extension for VSCode.

Important note

Due to limitations in the solidity-coverage package, coverage computation in fhEVM does not support tests involving the evm_snapshot Hardhat testing method. However, this method is still supported when running tests in mocked mode. If you are using Hardhat snapshots, we recommend to end your your test description with the [skip-on-coverage] tag to to avoid coverage issues. Here is an example:

import { expect } from 'chai';
import { ethers, network } from 'hardhat';

import { createInstances, decrypt8, decrypt16, decrypt32, decrypt64 } from '../instance';
import { getSigners, initSigners } from '../signers';
import { deployRandFixture } from './Rand.fixture';

describe('Rand', function () {
  before(async function () {
    await initSigners();
    this.signers = await getSigners();
  });

  beforeEach(async function () {
    const contract = await deployRandFixture();
    this.contractAddress = await contract.getAddress();
    this.rand = contract;
    this.instances = await createInstances(this.signers);
  });

  it('64 bits generate with upper bound and decrypt', async function () {
    const values: bigint[] = [];
    for (let i = 0; i < 5; i++) {
      const txn = await this.rand.generate64UpperBound(262144);
      await txn.wait();
      const valueHandle = await this.rand.value64();
      const value = await decrypt64(valueHandle);
      expect(value).to.be.lessThanOrEqual(262141);
      values.push(value);
    }
    // Expect at least two different generated values.
    const unique = new Set(values);
    expect(unique.size).to.be.greaterThanOrEqual(2);
  });

  it('8 and 16 bits generate and decrypt with hardhat snapshots [skip-on-coverage]', async function () {
    if (network.name === 'hardhat') {
      // snapshots are only possible in hardhat node, i.e in mocked mode
      this.snapshotId = await ethers.provider.send('evm_snapshot');
      const values: number[] = [];
      for (let i = 0; i < 5; i++) {
        const txn = await this.rand.generate8();
        await txn.wait();
        const valueHandle = await this.rand.value8();
        const value = await decrypt8(valueHandle);
        expect(value).to.be.lessThanOrEqual(0xff);
        values.push(value);
      }
      // Expect at least two different generated values.
      const unique = new Set(values);
      expect(unique.size).to.be.greaterThanOrEqual(2);

      await ethers.provider.send('evm_revert', [this.snapshotId]);
      const values2: number[] = [];
      for (let i = 0; i < 5; i++) {
        const txn = await this.rand.generate8();
        await txn.wait();
        const valueHandle = await this.rand.value8();
        const value = await decrypt8(valueHandle);
        expect(value).to.be.lessThanOrEqual(0xff);
        values2.push(value);
      }
      // Expect at least two different generated values.
      const unique2 = new Set(values2);
      expect(unique2.size).to.be.greaterThanOrEqual(2);
    }
  });
});

In this snippet, the first test will always run, whether in "real" non-mocked mode (pnpm test), testing mocked mode (pnpm test) or coverage (mocked) mode (pnpm coverage). On the other hand, the second test will be run only in testing mocked mode(pnpm test), because snapshots only works in that specific case. Actually, the second test will be skipped if run in coverage mode, since its description string ends with [skip-on-coverage] and similarly, we avoid the test to fail in non-mocked mode since we check that the network name is hardhat.

Limitations

By using this Hardhat template, you can streamline your fhEVM development workflow and focus on building robust, privacy-preserving smart contracts. For additional details, visit the fhevm-hardhat-template README.

This document explains how to enable encrypted computations in your smart contract by setting up the fhEVM environment. Learn how to integrate essential libraries, configure encryption, and add secure computation logic to your contracts.

Core configuration setup

To utilize encrypted computations in Solidity contracts, you must configure the TFHE library and Gateway addresses. The fhevm package simplifies this process with prebuilt configuration contracts, allowing you to focus on developing your contract’s logic without handling the underlying cryptographic setup.

Key components configured automatically

1. TFHE library: Sets up encryption parameters and cryptographic keys.

2. Gateway: Manages secure cryptographic operations, including reencryption and decryption.

3. Network-specific settings: Adapts to local testing, testnets (Sepolia for example), or mainnet deployment.

By inheriting these configuration contracts, you ensure seamless initialization and functionality across environments.

ZamaFHEVMConfig.sol

This configuration contract initializes the fhEVM environment with required encryption parameters.

Import based on your environment:

// For Ethereum Sepolia
import { SepoliaZamaFHEVMConfig } from "fhevm/config/ZamaFHEVMConfig.sol";

Purpose:

• Sets encryption parameters such as cryptographic keys and supported ciphertext types.

• Ensures proper initialization of the FHEVM environment.

Example: using Sepolia configuration

// SPDX-License-Identifier: BSD-3-Clause-Clear
pragma solidity ^0.8.24;

import { SepoliaZamaFHEVMConfig } from "fhevm/config/ZamaFHEVMConfig.sol";

contract MyERC20 is SepoliaZamaFHEVMConfig {
  constructor() {
    // Additional initialization logic if needed
  }
}

ZamaGatewayConfig.sol

To perform decryption or reencryption, your contract must interact with the Gateway, which acts as a secure bridge between the blockchain, coprocessor, and Key Management System (KMS).

Import based on your environment

// For Ethereum Sepolia
import { SepoliaZamaGatewayConfig } from "fhevm/config/ZamaGatewayConfig.sol";

Purpose

• Configures the Gateway for secure cryptographic operations.

• Facilitates reencryption and decryption requests.

Example: Configuring the gateway with Sepolia settings

import "fhevm/lib/TFHE.sol";
import { SepoliaZamaFHEVMConfig } from "fhevm/config/ZamaFHEVMConfig.sol";
import { SepoliaZamaGatewayConfig } from "fhevm/config/ZamaGatewayConfig.sol";
import "fhevm/gateway/GatewayCaller.sol";

contract Test is SepoliaZamaFHEVMConfig, SepoliaZamaGatewayConfig, GatewayCaller {
  constructor() {
    // Gateway and FHEVM environment initialized automatically
  }
}

Using isInitialized

The isInitialized utility function checks whether an encrypted variable has been properly initialized, preventing unexpected behavior due to uninitialized values.

Function signature

function isInitialized(T v) internal pure returns (bool)

Purpose

• Ensures encrypted variables are initialized before use.

• Prevents potential logic errors in contract execution.

Example: Initialization Check for Encrypted Counter

require(TFHE.isInitialized(counter), "Counter not initialized!");

Summary

By leveraging prebuilt configuration contracts like ZamaFHEVMConfig.sol and ZamaGatewayConfig.sol, you can efficiently set up your smart contract for encrypted computations. These tools abstract the complexity of cryptographic initialization, allowing you to focus on building secure, confidential smart contracts.

Explore our curated list of repositories to jumpstart your FHE development, contribute to the community, and access essential libraries and implementations.

Development templates

Quickly set up your development environment with these ready-to-use templates:

IDE plugins

Zama Bounty Program

Contribute to the development of FHE technologies and earn rewards through Zama’s bounty program:

• bounty-program - Explore open challenges and submit contributions to earn rewards.

Core libraries

Access the essential libraries for building and integrating FHE-enabled applications:

Core implementations

Explore the foundational implementations enabling FHE integration with blockchain systems:

Use these repositories to accelerate your development, integrate FHE into your applications, or contribute to the growing ecosystem.

This page gives an overview of Fully Homomorphic Encryption (FHE) and its implementation on the blockchain by fhEVM. It provides the essential architectural concepts needed to start building with fhEVM.

FHE overview

FHE is an advanced cryptographic technique that allows computations to be performed directly on encrypted data, without the need for decryption. This ensures that data remains confidential throughout its entire lifecycle, even during processing.

With FHE:

• Sensitive data can be securely encrypted while still being useful for computations.

• The results of computations are encrypted, maintaining end-to-end privacy.

FHE operates using three types of keys, each playing a crucial role in its functionality:

Private key

• Purpose: - for securely decrypting results - Decrypts ciphertexts to recover the original plaintext.

• Usage in fhEVM: Managed securely by the Key Management System (KMS) using a threshold MPC protocol. This ensures no single entity ever possesses the full private key.

Public key

• Purpose: - for encrypting data. - Encrypts plaintexts into ciphertexts.

• Usage in fhEVM: Shared globally to allow users and smart contracts to encrypt inputs or states. It ensures that encrypted data can be processed without revealing the underlying information.

Evaluation key

• Purpose: - for performing encrypted computations - Enables efficient homomorphic operations (e.g., addition, multiplication) on ciphertexts.

• Usage in fhEVM: Provided to FHE nodes (on-chain validators or off-chain coprocessors) to perform computations on encrypted data while preserving confidentiality.

These three keys work together to facilitate private and secure computations, forming the foundation of FHE-based systems like fhEVM.

FHE to Blockchain: From library to fhEVM

Building on Zama's FHE library

At its core, the fhEVM is built on Zama's high-performance FHE library, TFHE-rs, written in Rust. This library implements the TFHE (Torus Fully Homomorphic Encryption) scheme and is designed to perform secure computations on encrypted data efficiently.

Info: For detailed documentation and implementation examples on the tfhe-rs library, visit the TFHE-rs documentation.

However, integrating a standalone FHE library like TFHE-rs into a blockchain environment involves unique challenges. Blockchain systems demand efficient processing, public verifiability, and seamless interoperability, all while preserving their decentralized nature. To address these requirements, Zama designed the fhEVM, a system that bridges the computational power of TFHE-rs with the transparency and scalability of blockchain technology.

Challenges in blockchain integration

Integrating FHE into blockchain systems posed several challenges that needed to be addressed to achieve the goals of confidentiality, composability, and scalability:

1. Transparency and privacy: Blockchains are inherently transparent, where all on-chain data is publicly visible. FHE solves this by keeping all sensitive data encrypted, ensuring privacy without sacrificing usability.

2. Public verifiability: On-chain computations need to be verifiable by all participants. This required a mechanism to confirm the correctness of encrypted computations without revealing their inputs or outputs.

3. Composability: Smart contracts needed to interact seamlessly with each other, even when operating on encrypted data.

4. Performance and scalability: FHE computations are resource-intensive, and blockchain systems require high throughput to remain practical.

To overcome these challenges, Zama introduced a hybrid architecture for fhEVM that combines:

• On-chain functionality for managing state and enforcing access controls.

• Off-chain processing via a coprocessor to execute resource-intensive FHE computations.

This document describes the Access Control List (ACL) system in fhEVM, a core feature that governs access to encrypted data. The ACL ensures that only authorized accounts or contracts can interact with specific ciphertexts, preserving confidentiality while enabling composable smart contracts. This overview provides a high-level understanding of what the ACL is, why it's essential, and how it works.

What is the ACL?

The ACL is a permission management system designed to control who can access, compute on, or decrypt encrypted values in fhEVM. By defining and enforcing these permissions, the ACL ensures that encrypted data remains secure while still being usable within authorized contexts.

Why is the ACL important?

Encrypted data in fhEVM is entirely confidential, meaning that without proper access control, even the contract holding the ciphertext cannot interact with it. The ACL enables:

• Granular permissions: Define specific access rules for individual accounts or contracts.

• Secure computations: Ensure that only authorized entities can manipulate or decrypt encrypted data.

• Gas efficiency: Optimize permissions using transient access for temporary needs, reducing storage and gas costs.

How does the ACL work?

Types of access

• Permanent allowance:

  • Configured using TFHE.allow(ciphertext, address).

  • Grants long-term access to the ciphertext for a specific address.

  • Stored in a dedicated contract for persistent storage.

• Transient allowance:

  • Configured using TFHE.allowTransient(ciphertext, address).

  • Grants access to the ciphertext only for the duration of the current transaction.

  • Stored in transient storage, reducing gas costs.

  • Ideal for temporary operations like passing ciphertexts to external functions.

Syntactic sugar:

• TFHE.allowThis(ciphertext) is shorthand for TFHE.allow(ciphertext, address(this)). It authorizes the current contract to reuse a ciphertext handle in future transactions.

Transient vs. permanent allowance

Granting and verifying access

Granting access

Developers can use functions like allow, allowThis, and allowTransient to grant permissions:

• allow: Grants permanent access to an address.

• allowThis: Grants the current contract access to manipulate the ciphertext.

• allowTransient: Grants temporary access to an address for the current transaction.

Verifying access

To check if an entity has permission to access a ciphertext, use functions like isAllowed or isSenderAllowed:

• isAllowed: Verifies if a specific address has permission.

• isSenderAllowed: Simplifies checks for the current transaction sender.

Practical uses of the ACL

• Confidential parameters: Pass encrypted values securely between contracts, ensuring only authorized entities can access them.

• Secure state management: Store encrypted state variables while controlling who can modify or read them.

• Privacy-preserving computations: Enable computations on encrypted data with confidence that permissions are enforced.

This documentation covers the asEbool, asEuintXX, asEaddress and asEbytesXX operations provided by the TFHE library for working with encrypted data in the fhEVM. These operations are essential for converting between plaintext and encrypted types, as well as handling encrypted inputs.

The operations can be categorized into three main use cases:

1. Trivial encryption: Converting plaintext values to encrypted types

2. Type casting: Converting between different encrypted types

3. Input handling: Processing encrypted inputs with proofs

1. Trivial encryption

Trivial encryption simply put is a plain text in a format of a ciphertext.

Overview

Trivial encryption is the process of converting plaintext values into encrypted types (ciphertexts) compatible with TFHE operators. Although the data is in ciphertext format, it remains publicly visible on-chain, making it useful for operations between public and private values.

This type of casting involves converting plaintext (unencrypted) values into their encrypted equivalents, such as:

• bool → ebool

• uint → euintXX

• bytes → ebytesXX

• address → eaddress

Note: When doing trivial encryption, the data is made compatible with FHE operations but remains publicly visible on-chain unless explicitly encrypted.

Example

euint64 value64 = TFHE.asEuint64(7262);  // Trivial encrypt a uint64
ebool valueBool = TFHE.asEbool(true);   // Trivial encrypt a boolean

Trivial encryption of ebytesXX types

The TFHE.padToBytesXX functions facilitate this trivial encryption process for byte arrays, ensuring compatibility with ebytesXX types. These functions:

• Pad the provided byte array to the appropriate length (64, 128, or 256 bytes).

• Prevent runtime errors caused by improperly sized input data.

• Work seamlessly with TFHE.asEbytesXX for trivial encryption.

Important: Trivial encryption does NOT provide any privacy guarantees. The input data remains fully visible on the blockchain. Only use trivial encryption when working with public values that need to interact with actual encrypted data.

Workflow

1. Pad Input Data: Use the padToBytesXX functions to ensure your byte array matches the size requirements.

2. Encrypt the Padded Data: Use TFHE.asEbytesXX to encrypt the padded byte array into the corresponding encrypted type.

3. Grant Access: Use TFHE.allowThis and TFHE.allowoptionally, if you want to persist allowance for those variables for later use.

Example: Trivial Encryption with ebytesXX

Below is an example demonstrating how to encrypt and manage ebytes64, ebytes128, and ebytes256 types:

function trivialEncrypt() public {
  // Encrypt a 64-byte array
  ebytes64 yBytes64 = TFHE.asEbytes64(
    TFHE.padToBytes64(
      hex"19d179e0cc7e816dc944582ed4f5652f5951900098fc2e0a15a7ea4dc8cfa4e3b6c54beea5ee95e56b728762f659347ce1d4aa1b05fcc5"
    )
  );
  TFHE.allowThis(yBytes64);
  TFHE.allow(yBytes64, msg.sender);

  // Encrypt a 128-byte array
  ebytes128 yBytes128 = TFHE.asEbytes128(
    TFHE.padToBytes128(
      hex"13e7819123de6e2870c7e83bb764508e22d7c3ab8a5aee6bdfb26355ef0d3f1977d651b83bf5f78634fa360aa14debdc3daa6a587b5c2fb1710ab4d6677e62a8577f2d9fecc190ad8b11c9f0a5ec3138b27da1f055437af8c90a9495dad230"
    )
  );
  TFHE.allowThis(yBytes128);
  TFHE.allow(yBytes128, msg.sender);

  // Encrypt a 256-byte array
  ebytes256 yBytes256 = TFHE.asEbytes256(
    TFHE.padToBytes256(
      hex"d179e0cc7e816dc944582ed4f5652f5951900098fc2e0a15a7ea4dc8cfa4e3b6c54beea5ee95e56b728762f659347ce1d4aa1b05fcc513e7819123de6e2870c7e83bb764508e22d7c3ab8a5aee6bdfb26355ef0d3f1977d651b83bf5f78634fa360aa14debdc3daa6a587b5c2fb1710ab4d6677e62a8577f2d9fecc190ad8b11c9f0a5ec3138b27da1f055437af8c90a9495dad230"
    )
  );
  TFHE.allowThis(yBytes256);
  TFHE.allow(yBytes256, msg.sender);
}

2. Casting between encrypted types

This type of casting is used to reinterpret or convert one encrypted type into another. For example:

• euint32 → euint64

• ebytes128 → ebytes256

Casting between encrypted types is often required when working with operations that demand specific sizes or precisions.

Important: When casting between encrypted types:

• Casting from smaller types to larger types (e.g. euint32 → euint64) preserves all information

• Casting from larger types to smaller types (e.g. euint64 → euint32) will truncate and lose information

The table below summarizes the available casting functions:

Workflow for encrypted types

// Casting between encrypted types
euint32 value32 = TFHE.asEuint32(value64); // Cast to euint32
ebool valueBool = TFHE.asEbool(value32);   // Cast to ebool

3. Encrypted input

Overview

Encrypted input casting is the process of interpreting a handle (ciphertext reference) and its proof as a specific encrypted type. This ensures the validity of the input before it is used in computations.

Example

euint64 encryptedValue = TFHE.asEuint64(einputHandle, inputProof); // Interpret einputHandle as euint64

Details

Encrypted input casting validates:

1. The input handle references a valid ciphertext.

2. The accompanying proof matches the expected type.

Overall operation summary

This document introduces the core cryptographic operations in the fhEVM system, including how data is encrypted, decrypted, re-encrypted and computed upon while maintaining privacy.

The fhEVM system ensures end-to-end confidentiality by leveraging Fully Homomorphic Encryption (FHE). The encryption, decryption, re-encryption, and computation processes rely on a coordinated flow of information and cryptographic keys across the fhEVM components. This section details how these operations work and outlines the role of the FHE keys in enabling secure and private processing.

FHE keys and their locations

1. Public Key:

   • Location: Directly accessible from the frontend or the smart contract.

   • Role: Used to encrypt plaintext data before submission to the blockchain or during contract execution.

2. Private Key:

   • Location: Stored securely in the Key Management System (KMS).

   • Role: Used for decrypting ciphertexts when necessary, either to verify results or enable user-specific plaintext access.

3. Evaluation Key:

   • Location: Stored on the coprocessor.

   • Role: Enables operations on ciphertexts (e.g., addition, multiplication) without decrypting them.

Workflow: encryption, decryption, and processing

Encryption

Encryption is the starting point for any interaction with the fhEVM system, ensuring that data is protected before it is transmitted or processed.

• How It Works:

  1. The frontend or client application uses the public key to encrypt user-provided plaintext inputs.

  2. The encrypted data (ciphertext) is submitted to the blockchain as part of a transaction or stored for later computation.

• Data Flow:

  • Source: Frontend or smart contract.

  • Destination: Blockchain (for storage and symbolic execution) or coprocessor (for processing).

You can read about the implementation details in our encryption guide.

Computation

Encrypted computations are performed using the evaluation key on the coprocessor.

• How it works:

  1. The blockchain initiates symbolic execution, generating a set of operations to be performed on encrypted data.

  2. These operations are offloaded to the coprocessor, which uses the evaluation key to compute directly on the ciphertexts.

  3. The coprocessor returns updated ciphertexts to the blockchain for storage or further use.

• Data flow:

  • Source: Blockchain smart contracts (via symbolic execution).

  • Processing: Coprocessor (using the evaluation key).

  • Destination: Blockchain (updated ciphertexts).

Decryption

Decryption is used when plaintext results are required for contract logic or for presentation to a user. After the decryption in preformed on the blockchain, the decrypted result is exposed to everyone who has access to the blockchain.

• How it works: Validators on the blockchain do not possess the private key needed for decryption. Instead, the Key Management System (KMS) securely holds the private key. If plaintext values are needed, the process is facilitated by a service called the Gateway, which provides two options:

  1. For Smart contract logic: The Gateway acts as an oracle service, listening for decryption request events emitted by the blockchain. Upon receiving such a request, the Gateway interacts with the KMS to decrypt the ciphertext and sends the plaintext back to the smart contract via a callback function.

  2. For dApps: If a dApp needs plaintext values, the Gateway enables re-encryption of the ciphertext. The KMS securely re-encrypts the ciphertext with the dApp's public key, ensuring that only the dApp can decrypt and access the plaintext.

• Data flow:

  • Source: Blockchain or dApp (ciphertext).

  • Processing: KMS performs decryption or re-encryption via the Gateway.

  • Destination: Plaintext is either sent to the smart contract or re-encrypted and delivered to the dApp.

You can read about the implemention details in our decryption guide.

4. Re-encryption

Re-encryption enables encrypted data to be securely shared or reused under a different encryption key without ever revealing the plaintext. This process is essential for scenarios where data needs to be accessed by another contract, dApp, or user while maintaining confidentiality.

• How it work: Re-encryption is facilitated by the Gateway in collaboration with the Key Management System (KMS).

  1. The Gateway receives a re-encryption request, which includes details of the original ciphertext and the target public key.

  2. The KMS securely decrypts the ciphertext using its private key and re-encrypts the data with the recipient's public key.

  3. The re-encrypted ciphertext is then sent to the intended recipient.

• Data flow:

  1. Source:

     1. The process starts with an original ciphertext retrieved from the blockchain or a dApp.

  2. Processing:

     1. The Gateway forwards the re-encryption request to the KMS.

     2. The KMS handles decryption and re-encryption using the appropriate keys.

  3. Destination:

     1. The re-encrypted ciphertext is delivered to the target entity, such as a dApp, user, or another contract.

Client-side implementation

Re-encryption is initiated on the client side via the Gateway service using the fhevmjs library. Here’s the general workflow:

1. Retrieve the ciphertext:

   • The dApp calls a view function (e.g., balanceOf) on the smart contract to get the handle of the ciphertext to be re-encrypted.

2. Generate and sign a keypair:

   • The dApp generates a keypair for the user.

   • The user signs the public key to ensure authenticity.

3. Submit re-encryption request:

   • The dApp calls the Gateway, providing the following information:

     • The ciphertext handle.

     • The user’s public key.

     • The user’s address.

     • The smart contract address.

     • The user’s signature.

4. Decrypt the re-encrypted ciphertext:

   • The dApp receives the re-encrypted ciphertext from the Gateway.

   • The dApp decrypts the ciphertext locally using the private key.

You can read our re-encryption guide explaining how to use it.

Tying It All Together

The flow of information across the fhEVM components during these operations highlights how the system ensures privacy while maintaining usability:

This architecture ensures that sensitive data remains encrypted throughout its lifecycle, with decryption or re-encryption only occurring in controlled, secure environments. By separating key roles and processing responsibilities, fhEVM provides a scalable and robust framework for private smart contracts.

This document gives an detail explanantion of each components of fhEVM and illustrate how they work together to perform compuations.

Overview

The fhEVM architecture is built around four primary components, each contributing to the system's functionality and performance. These components work together to enable the development and execution of private, composable smart contracts on EVM-compatible blockchains. Below is an overview of these components and their responsibilities:

Developer workflow:

As a developer working with fhEVM, your workflow typically involves two key elements:

1. Frontend development: You create a frontend interface for users to interact with your confidential application. This includes encrypting inputs using the public FHE key and submitting them to the blockchain.

2. Smart contract development: You write Solidity contracts deployed on the same blockchain as the fhEVM smart contracts. These contracts leverage the TFHE.sol library to perform operations on encrypted data. Below, we explore the major components involved.

fhEVM smart contracts

fhEVM smart contracts include the Access Control List (ACL) contract, TFHE.sol library, and related FHE-enabled contracts.

Symbolic execution in Solidity

fhEVM implements symbolic execution to optimize FHE computations:

• Handles: Operations on encrypted data return "handles" (references to ciphertexts) instead of immediate results.

• Lazy Execution: Actual computations are performed asynchronously, offloading resource-intensive tasks to the coprocessor.

This approach ensures high throughput and flexibility in managing encrypted data.

Zero-Knowledge proofs of knowledge (ZKPoKs)

fhEVM incorporates ZKPoKs to verify the correctness of encrypted inputs and outputs:

• Validation: ZKPoKs ensure that inputs are correctly formed and correspond to known plaintexts without revealing sensitive data.

• Integrity: They prevent misuse of ciphertexts and ensure the correctness of computations.

By combining symbolic execution and ZKPoKs, fhEVM smart contracts maintain both privacy and verifiability.

Coprocessor

The coprocessor is the backbone for handling computationally intensive FHE tasks.

Key functions:

1. Execution: Performs operations such as addition, multiplication, and comparison on encrypted data.

2. Ciphertext management: Stores encrypted inputs, states, and outputs securely, either off-chain or in a dedicated on-chain database.

Gateway

The Gateway acts as the bridge between the blockchain, coprocessor, and KMS.

Key functions:

• API for developers: Exposes endpoints for submitting encrypted inputs, retrieving outputs, and managing ciphertexts.

• Proof validation: Forwards ZKPoKs to the KMS for verification.

• Off-chain coordination: Relays encrypted data and computation results between on-chain and off-chain systems.

The Gateway simplifies the development process by abstracting the complexity of cryptographic operations.

Key management system (KMS)

The KMS securely manages the cryptographic backbone of fhEVM by maintaining and distributing the global FHE keys.

Key functions:

• Threshold decryption: Uses Multi-Party Computation (MPC) to securely decrypt ciphertexts without exposing the private key to any single entity.

• ZKPoK validation: Verifies proofs of plaintext knowledge to ensure that encrypted inputs are valid.

• Key distribution: Maintains the global FHE keys, which include:

  • Public key: Used for encrypting data (accessible to the frontend and smart contracts).

  • Private key: Stored securely in the KMS and used for decryption.

  • Evaluation key: Used by the coprocessor to perform FHE computations.

The KMS ensures robust cryptographic security, preventing single points of failure and maintaining public verifiability.

In the next section, we will dive deeper into encryption, re-encryption, and decryption processes, including how they interact with the KMS and Gateway services. For more details, see Decrypt and re-encrypt.

This document introduces the encrypted integer types provided by the TFHE library in fhEVM and explains their usage, including casting, state variable declarations, and type-specific considerations.

Introduction

The TFHE library offers a robust type system with encrypted integer types, enabling secure computations on confidential data in smart contracts. These encrypted types are validated both at compile time and runtime to ensure correctness and security.

Key features of encrypted types

• Encrypted integers function similarly to Solidity’s native integer types, but they operate on Fully Homomorphic Encryption (FHE) ciphertexts.

• Arithmetic operations on e(u)int types are unchecked, meaning they wrap around on overflow. This design choice ensures confidentiality by avoiding the leakage of information through error detection.

• Future versions of the TFHE library will support encrypted integers with overflow checking, but with the trade-off of exposing limited information about the operands.

Encrypted integers in fhEVM are represented as FHE ciphertexts, abstracted using ciphertext handles. These types, prefixed with e (for example, euint64) act as secure wrappers over the ciphertext handles.

List of encrypted types

The TFHE library currently supports the following encrypted types:

This page provides detailed instructions and examples on how to use and implement the ACL (Access Control List) in fhEVM. For an overview of ACL concepts and their importance, refer to the .

Controlling access: permanent and transient allowances

The ACL system allows you to define two types of permissions for accessing ciphertexts:

Permanent allowance

• Function: TFHE.allow(ciphertext, address)

• Purpose: Grants persistent access to a ciphertext for a specific address.

• Storage: Permissions are saved in a dedicated ACL contract, making them available across transactions.

Transient allowance

• Function: TFHE.allowTransient(ciphertext, address)

• Purpose: Grants temporary access for the duration of a single transaction.

• Storage: Permissions are stored in transient storage to save gas costs.

• Use Case: Ideal for passing encrypted values between functions or contracts during a transaction.

Syntactic sugar

• Function: TFHE.allowThis(ciphertext)

• Equivalent To: TFHE.allow(ciphertext, address(this))

• Purpose: Simplifies granting permanent access to the current contract for managing ciphertexts.

Example: granting permissions in a multi-contract setup

import "fhevm/lib/TFHE.sol";
import { SepoliaZamaFHEVMConfig } from "fhevm/config/ZamaFHEVMConfig.sol";

contract SecretGiver is SepoliaZamaFHEVMConfig {
  SecretStore public secretStore;

  constructor() {
    secretStore = new SecretStore();
  }

  function giveMySecret() public {
    // Create my secret - asEuint16 gives automatically transient allowance for the resulting handle (note: an onchain trivial encryption is not secret)
    euint16 mySecret = TFHE.asEuint16(42);

    // Allow temporarily the SecretStore contract to manipulate `mySecret`
    TFHE.allowTransient(mySecret, address(secretStore));

    // Call `secretStore` with `mySecret`
    secretStore.storeSecret(mySecret);
  }
}

contract SecretStore is SepoliaZamaFHEVMConfig {
  euint16 public secretResult;

  function storeSecret(euint16 callerSecret) public {
    // Verify that the caller has also access to this ciphertext
    require(TFHE.isSenderAllowed(callerSecret), "The caller is not authorized to access this secret.");

    // do some FHE computation (result is automatically put in the ACL transient storage)
    euint16 computationResult = TFHE.add(callerSecret, 3);

    // then store the resulting ciphertext handle in the contract storage
    secretResult = computationResult;

    // Make the temporary allowance for this ciphertext permanent to let the contract able to reuse it at a later stage or request a decryption of it
    TFHE.allowThis(secretResult); // this is strictly equivalent to `TFHE.allow(secretResult, address(this));``
  }
}

Automatic transient allowance

Some functions automatically grant transient allowances to the calling contract, simplifying workflow. These include:

• Type Conversion:

  • TFHE.asEuintXX(), TFHE.asEbool(), TFHE.asEaddress()

• Random Value Generation:

  • TFHE.randXX()

• Computation Results:

  • TFHE.add(), TFHE.select()

Example: random value generation

function randomize() public {
  // Generate a random encrypted value with transient allowance
  euint64 random = TFHE.randEuint64();

  // Convert the transient allowance into a permanent one
  TFHE.allowThis(random);
}

🔧 Best practices

Verifying sender access

When processing ciphertexts as input, it’s essential to validate that the sender is authorized to interact with the provided encrypted data. Failing to perform this verification can expose the system to inference attacks where malicious actors attempt to deduce private information.

Example scenario: Encrypted ERC20 attack

Consider an Encrypted ERC20 token. An attacker controlling two accounts, Account A and Account B, with 100 tokens in Account A, could exploit the system as follows:

1. The attacker attempts to send the target user's encrypted balance from Account A to Account B.

2. Observing the transaction outcome, the attacker gains information:

   • If successful: The target's balance is equal to or less than 100 tokens.

   • If failed: The target's balance exceeds 100 tokens.

This type of attack allows the attacker to infer private balances without explicit access.

To prevent this, always use the TFHE.isSenderAllowed() function to verify that the sender has legitimate access to the encrypted amount being transferred.

Example: secure verification

function transfer(address to, euint64 encryptedAmount, bytes calldata inputProof) public {
  // Ensure the sender is authorized to access the encrypted amount
  require(TFHE.isSenderAllowed(encryptedAmount), "Unauthorized access to encrypted amount.");

  // Proceed with further logic
  euint64 amount = TFHE.asEuint64(encryptedAmount);
  ...
}

By enforcing this check, you can safeguard against inference attacks and ensure that encrypted values are only manipulated by authorized entities.

ACL for reencryption

If a ciphertext can be reencrypted by a user, explicit access must be granted to them. Additionally, the reencryption mechanism requires the signature of a public key associated with the contract address. Therefore, a value that needs to be reencrypted must be explicitly authorized for both the user and the contract.

Due to the reencryption mechanism, a user signs a public key associated with a specific contract; therefore, the ciphertext also needs to be allowed for the contract.

Example: Secure Transfer in Encrypted ERC-20

function transfer(address to, euint64 encryptedAmount) public {
  require(TFHE.isSenderAllowed(encryptedAmount), "The caller is not authorized to access this encrypted amount.");
  euint64 amount = TFHE.asEuint64(encryptedAmount);
  ebool canTransfer = TFHE.le(amount, balances[msg.sender]);

  euint64 newBalanceTo = TFHE.add(balances[to], TFHE.select(canTransfer, amount, TFHE.asEuint64(0)));
  balances[to] = newBalanceTo;
  // Allow this new balance for both the contract and the owner.
  TFHE.allowThis(newBalanceTo);
  TFHE.allow(newBalanceTo, to);

  euint64 newBalanceFrom = TFHE.sub(balances[from], TFHE.select(canTransfer, amount, TFHE.asEuint64(0)));
  balances[from] = newBalanceFrom;
  // Allow this new balance for both the contract and the owner.
  TFHE.allowThis(newBalanceFrom);
  TFHE.allow(newBalanceFrom, from);
}

This document outlines the operations supported on encrypted types in the TFHE library, enabling arithmetic, bitwise, comparison, and more on Fully Homomorphic Encryption (FHE) ciphertexts.

Arithmetic operations

The following arithmetic operations are supported for encrypted integers (euintX):

Bitwise operations

The TFHE library also supports bitwise operations, including shifts and rotations:

The shift operators TFHE.shr and TFHE.shl can take any encrypted type euintX as a first operand and either a uint8or a euint8 as a second operand, however the second operand will always be computed modulo the number of bits of the first operand. For example, TFHE.shr(euint64 x, 70) is equivalent to TFHE.shr(euint64 x, 6) because 70 % 64 = 6. This differs from the classical shift operators in Solidity, where there is no intermediate modulo operation, so for instance any uint64 shifted right via >> would give a null result.

Comparison operations

Encrypted integers can be compared using the following functions:

Ternary operation

The TFHE.select function is a ternary operation that selects one of two encrypted values based on an encrypted condition:

Random operations

You can generate cryptographically secure random numbers fully on-chain:

Overload operators

Example Overloaded operators make code more concise:

euint64 a = TFHE.asEuint64(42);
euint64 b = TFHE.asEuint64(58);
euint64 sum = a + b; // Calls TFHE.add under the hood

Best Practices

Here are some best practices to follow when using encrypted operations in your smart contracts:

Use the appropriate encrypted type size

Choose the smallest encrypted type that can accommodate your data to optimize gas costs. For example, use euint8 for small numbers (0-255) rather than euint256.

❌ Avoid using oversized types:

// Bad: Using euint256 for small numbers wastes gas
euint64 age = TFHE.euint256(25);  // age will never exceed 255
euint64 percentage = TFHE.euint256(75);  // percentage is 0-100

✅ Instead, use the smallest appropriate type:

// Good: Using appropriate sized types
euint8 age = TFHE.asEuint8(25);  // age fits in 8 bits
euint8 percentage = TFHE.asEuint8(75);  // percentage fits in 8 bits

Use scalar operands when possible to save gas

Some TFHE operators exist in two versions : one where all operands are ciphertexts handles, and another where one of the operands is an unencrypted scalar. Whenever possible, use the scalar operand version, as this will save a lot of gas.

❌ For example, this snippet cost way more in gas:

euint32 x;
...
x = TFHE.add(x,TFHE.asEuint(42));

✅ Than this one:

euint32 x;
// ...
x = TFHE.add(x,42);

Despite both leading to the same encrypted result!

Beware of overflows of TFHE arithmetic operators

TFHE arithmetic operators can overflow. Do not forget to take into account such a possibility when implementing fhEVM smart contracts.

❌ For example, if you wanted to create a mint function for an encrypted ERC20 tokens with an encrypted totalSupply state variable, this code is vulnerable to overflows:

function mint(einput encryptedAmount, bytes calldata inputProof) public {
  euint32 mintedAmount = TFHE.asEuint32(encryptedAmount, inputProof);
  totalSupply = TFHE.add(totalSupply, mintedAmount);
  balances[msg.sender] = TFHE.add(balances[msg.sender], mintedAmount);
  TFHE.allowThis(balances[msg.sender]);
  TFHE.allow(balances[msg.sender], msg.sender);
}

✅ But you can fix this issue by using TFHE.select to cancel the mint in case of an overflow:

function mint(einput encryptedAmount, bytes calldata inputProof) public {
  euint32 mintedAmount = TFHE.asEuint32(encryptedAmount, inputProof);
  euint32 tempTotalSupply = TFHE.add(totalSupply, mintedAmount);
  ebool isOverflow = TFHE.lt(tempTotalSupply, totalSupply);
  totalSupply = TFHE.select(isOverflow, totalSupply, tempTotalSupply);
  euint32 tempBalanceOf = TFHE.add(balances[msg.sender], mintedAmount);
  balances[msg.sender] = TFHE.select(isOverflow, balances[msg.sender], tempBalanceOf);
  TFHE.allowThis(balances[msg.sender]);
  TFHE.allow(balances[msg.sender], msg.sender);
}

Notice that we did not check separately the overflow on balances[msg.sender] but only on totalSupply variable, because totalSupply is the sum of the balances of all the users, so balances[msg.sender] could never overflow if totalSupply did not.

Additional Resources

This document explains how to handle loops when working with Fully Homomorphic Encryption (FHE), specifically when a loop break is based on an encrypted condition.

Breaking a loop

❌ In FHE, it is not possible to break a loop based on an encrypted condition. For example, this would not work:

euint8 maxValue = TFHE.asEuint(6); // Could be a value between 0 and 10
euint8 x = TFHE.asEuint(0);
// some code
while(TFHE.lt(x, maxValue)){
    x = TFHE.add(x, 2);
}

If your code logic requires looping on an encrypted boolean condition, we highly suggest to try to replace it by a finite loop with an appropriate constant maximum number of steps and use TFHE.select inside the loop.

Suggested approach

✅ For example, the previous code could maybe be replaced by the following snippet:

euint8 maxValue = TFHE.asEuint(6); // Could be a value between 0 and 10
euint8 x;
// some code
for (uint32 i = 0; i < 10; i++) {
    euint8 toAdd = TFHE.select(TFHE.lt(x, maxValue), 2, 0);
    x = TFHE.add(x, toAdd);
}

In this snippet, we perform 10 iterations, adding 4 to x in each iteration as long as the iteration count is less than maxValue. If the iteration count exceeds maxValue, we add 0 instead for the remaining iterations because we can't break the loop.

Best practises

Obfuscate branching

The previous paragraph emphasized that branch logic should rely as much as possible on TFHE.select instead of decryptions. It hides effectively which branch has been executed.

However, this is sometimes not enough. Enhancing the privacy of smart contracts often requires revisiting your application's logic.

For example, if implementing a simple AMM for two encrypted ERC20 tokens based on a linear constant function, it is recommended to not only hide the amounts being swapped, but also the token which is swapped in a pair.

✅ Here is a very simplified example implementations, we suppose here that the the rate between tokenA and tokenB is constant and equals to 1:

// typically either encryptedAmountAIn or encryptedAmountBIn is an encrypted null value
// ideally, the user already owns some amounts of both tokens and has pre-approved the AMM on both tokens
function swapTokensForTokens(einput encryptedAmountAIn, einput encryptedAmountBIn, bytes calldata inputProof) external {
  euint32 encryptedAmountA = TFHE.asEuint32(encryptedAmountAIn, inputProof); // even if amount is null, do a transfer to obfuscate trade direction
  euint32 encryptedAmountB = TFHE.asEuint32(encryptedAmountBIn, inputProof); // even if amount is null, do a transfer to obfuscate trade direction

  // send tokens from user to AMM contract
  TFHE.allowTransient(encryptedAmountA, tokenA);
  IConfidentialERC20(tokenA).transferFrom(msg.sender, address(this), encryptedAmountA);

  TFHE.allowTransient(encryptedAmountB, tokenB);
  IConfidentialERC20(tokenB).transferFrom(msg.sender, address(this), encryptedAmountB);

  // send tokens from AMM contract to user
  // Price of tokenA in tokenB is constant and equal to 1, so we just swap the encrypted amounts here
  TFHE.allowTransient(encryptedAmountB, tokenA);
  IConfidentialERC20(tokenA).transfer(msg.sender, encryptedAmountB);

  TFHE.allowTransient(encryptedAmountA, tokenB);
  IConfidentialERC20(tokenB).transferFrom(msg.sender, address(this), encryptedAmountA);
}

Notice that to preserve confidentiality, we had to make two inputs transfers on both tokens from the user to the AMM contract, and similarly two output transfers from the AMM to the user, even if technically most of the times it will make sense that one of the user inputs encryptedAmountAIn or encryptedAmountBIn is actually an encrypted zero.

This is different from a classical non-confidential AMM with regular ERC20 tokens: in this case, the user would need to just do one input transfer to the AMM on the token being sold, and receive only one output transfer from the AMM on the token being bought.

Avoid using encrypted indexes

Using encrypted indexes to pick an element from an array without revealing it is not very efficient, because you would still need to loop on all the indexes to preserve confidentiality.

However, there are plans to make this kind of operation much more efficient in the future, by adding specialized operators for arrays.

For instance, imagine you have an encrypted array called encArray and you want to update an encrypted value x to match an item from this list, encArray[i], without disclosing which item you're choosing.

❌ You must loop over all the indexes and check equality homomorphically, however this pattern is very expensive in gas and should be avoided whenever possible.

euint32 x;
euint32[] encArray;

function setXwithEncryptedIndex(einput encryptedIndex, bytes calldata inputProof) public {
    euint32 index = TFHE.asEuint32(encryptedIndex, inputProof);
    for (uint32 i = 0; i < encArray.length; i++) {
        ebool isEqual = TFHE.eq(index, i);
        x = TFHE.select(isEqual, encArray[i], x);
    }
    TFHE.allowThis(x);
}

This document introduces the concept of encrypted inputs in the fhEVM, explaining their role, structure, validation process, and how developers can integrate them into smart contracts and applications.

Encrypted inputs are a core feature of fhEVM, enabling users to push encrypted data onto the blockchain while ensuring data confidentiality and integrity.

What are encrypted inputs?

Encrypted inputs are data values submitted by users in ciphertext form. These inputs allow sensitive information to remain confidential while still being processed by smart contracts. They are accompanied by Zero-Knowledge Proofs of Knowledge (ZKPoKs) to ensure the validity of the encrypted data without revealing the plaintext.

Key characteristics of encrypted inputs:

1. Confidentiality: Data is encrypted using the public FHE key, ensuring that only authorized parties can decrypt or process the values.

2. Validation via ZKPoKs: Each encrypted input is accompanied by a proof verifying that the user knows the plaintext value of the ciphertext, preventing replay attacks or misuse.

3. Efficient packing: All inputs for a transaction are packed into a single ciphertext in a user-defined order, optimizing the size and generation of the zero-knowledge proof.

Parameters in encrypted functions

When a function in a smart contract is called, it may accept two types of parameters for encrypted inputs:

1. einput: Refers to the index of the encrypted parameter, representing a specific encrypted input handle.

2. bytes: Contains the ciphertext and the associated zero-knowledge proof used for validation.

Here’s an example of a Solidity function accepting multiple encrypted parameters:

function myExample(
  address account,
  uint id,
  bool isAllowed,
  einput param1,
  einput param2,
  einput param3,
  bytes calldata inputProof
) public {
  // Function logic here
}

In this example, param1, param2, and param3 are encrypted inputs, while inputProof contains the corresponding ZKPoK to validate their authenticity.

Client-Side implementation

To interact with such a function, developers can use the fhevmjs library to create and manage encrypted inputs. Below is an example implementation:

import { createInstances } from "../instance";
import { getSigners, initSigners } from "../signers";

await initSigners(); // Initialize signers
const signers = await getSigners();

const instance = await createInstances(this.signers);
// Create encrypted inputs
const input = instance.createEncryptedInput(contractAddress, userAddress);
const inputs = input.add64(64).addBool(true).add8(4).encrypt(); // Encrypt the parameters

// Call the smart contract function with encrypted inputs
contract.myExample(
  "0xa5e1defb98EFe38EBb2D958CEe052410247F4c80", // Account address
  32, // Plaintext parameter
  true, // Plaintext boolean parameter
  inputs.handles[0], // Handle for the first parameter
  inputs.handles[1], // Handle for the second parameter
  inputs.handles[2], // Handle for the third parameter
  inputs.inputProof, // Proof to validate all encrypted inputs
);

In this example:

• add64, addBool, and add8: Specify the types and values of inputs to encrypt.

• encrypt: Generates the encrypted inputs and the zero-knowledge proof.

Validating encrypted inputs

Smart contracts process encrypted inputs by verifying them against the associated zero-knowledge proof. This is done using the TFHE.asEuintXX, TFHE.asEbool, or TFHE.asEaddress functions, which validate the input and convert it into the appropriate encrypted type.

Example validation that goes along the client-Side implementation

This example demonstrates a function that performs multiple encrypted operations, such as updating a user's encrypted balance and toggling an encrypted boolean flag:

  function myExample(
    einput encryptedAmount,
    einput encryptedToggle,
    bytes calldata inputProof
  ) public {
    // Validate and convert the encrypted inputs
    euint64 amount = TFHE.asEuint64(encryptedAmount, inputProof);
    ebool toggleFlag = TFHE.asEbool(encryptedToggle, inputProof);

    // Update the user's encrypted balance
    balances[msg.sender] = TFHE.add(balances[msg.sender], amount);

    // Toggle the user's encrypted flag
    userFlags[msg.sender] = TFHE.not(toggleFlag);
  }

  // Function to retrieve a user's encrypted balance
  function getEncryptedBalance() public view returns (euint64) {
    return balances[msg.sender];
  }

  // Function to retrieve a user's encrypted flag
  function getEncryptedFlag() public view returns (ebool) {
    return userFlags[msg.sender];
  }
}

Example validation in the encyrptedERC20.sol smart contract

Here’s an example of a smart contract function that verifies an encrypted input before proceeding:

function transfer(
  address to,
  einput encryptedAmount,
  bytes calldata inputProof
) public {
  // Verify the provided encrypted amount and convert it into an encrypted uint64
  euint64 amount = TFHE.asEuint64(encryptedAmount, inputProof);

  // Function logic here, such as transferring funds
  ...
}

How validation works

1. Input verification: The TFHE.asEuintXX function ensures that the input is a valid ciphertext with a corresponding ZKPoK.

2. Type conversion: The function transforms the einput into the appropriate encrypted type (euintXX, ebool, etc.) for further operations within the contract.

Best Practices

• Input packing: Minimize the size and complexity of zero-knowledge proofs by packing all encrypted inputs into a single ciphertext.

• Frontend encryption: Always encrypt inputs using the FHE public key on the client side to ensure data confidentiality.

• Proof management: Ensure that the correct zero-knowledge proof is associated with each encrypted input to avoid validation errors.

Encrypted inputs and their validation form the backbone of secure and private interactions in the fhEVM. By leveraging these tools, developers can create robust, privacy-preserving smart contracts without compromising functionality or scalability.

Upgrade of our Counter contract

Now that we have new knowledge on how to add encrypted inputs, let's upgrade our counter contract.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import "fhevm/lib/TFHE.sol";
import { SepoliaZamaFHEVMConfig } from "fhevm/config/ZamaFHEVMConfig.sol";

/// @title EncryptedCounter2
/// @notice A contract that maintains an encrypted counter and is meant for demonstrating how to add encrypted types
/// @dev Uses TFHE library for fully homomorphic encryption operations
/// @custom:experimental This contract is experimental and uses FHE technology
contract EncryptedCounter2 is SepoliaZamaFHEVMConfig {
  euint8 internal counter;

  constructor() {
    // Initialize counter with an encrypted zero value
    counter = TFHE.asEuint8(0);
    TFHE.allowThis(counter);
  }

  function incrementBy(einput amount, bytes calldata inputProof) public {
    // Convert input to euint8 and add to counter
    euint8 incrementAmount = TFHE.asEuint8(amount, inputProof);
    counter = TFHE.add(counter, incrementAmount);
    TFHE.allowThis(counter);
  }
}

Tests of for the Counter contract

import { createInstance } from "../instance";
import { getSigners, initSigners } from "../signers";
import { ethers } from "hardhat";

describe("EncryptedCounter2", function () {
  before(async function () {
    await initSigners(); // Initialize signers
    this.signers = await getSigners();
  });

  beforeEach(async function () {
    const CounterFactory = await ethers.getContractFactory("EncryptedCounter2");
    this.counterContract = await CounterFactory.connect(this.signers.alice).deploy();
    await this.counterContract.waitForDeployment();
    this.contractAddress = await this.counterContract.getAddress();
    this.instances = await createInstance(); // Set up instances for testing
  });

  it("should increment by arbitrary encrypted amount", async function () {
    // Create encrypted input for amount to increment by
    const input = this.instances.createEncryptedInput(this.contractAddress, this.signers.alice.address);
    input.add8(5);
    const encryptedAmount = await input.encrypt();

    // Call incrementBy with encrypted amount
    const tx = await this.counterContract.incrementBy(encryptedAmount.handles[0], encryptedAmount.inputProof);
    await tx.wait();
  });
});

How it works

The EncryptedCounter2 contract builds on the previous example by adding support for encrypted inputs. Here's how it works:

1. Encrypted state: Like before, the contract maintains an encrypted counter state variable of type euint8.

2. Encrypted input handling: The incrementBy function accepts two parameters:

   • einput amount: An encrypted input handle representing the increment value

   • bytes calldata inputProof: The zero-knowledge proof validating the encrypted input

3. Input processing: Inside incrementBy:

   • The encrypted input is converted to a euint8 using TFHE.asEuint8()

   • This conversion validates the proof and creates a usable encrypted value

   • The value is then added to the counter using homomorphic addition

Limitations

While we have resolved our problem with the Counter value visibility, there is still the problem with the Access Control for the counter. The counter is encrypted, but no access is granted to decrypt or view its value. Without proper ACL permissions, the counter remains inaccessible to users. To resolve this, refer to:

• Decryption

• Re-encryption

This guide explains how to use the fhEVM Contracts standard library. This library provides secure, extensible, and pre-tested Solidity templates designed for developing smart contracts on fhEVM using the TFHE library.

Overview

The fhEVM Contracts standard library streamlines the development of confidential smart contracts by providing templates and utilities for tokens, governance, and error management. These contracts have been rigorously tested by ZAMA's engineers and are designed to accelerate development while enhancing security.

Installation

Install the library using your preferred package manager:

# Using npm
npm install fhevm-contracts

# Using Yarn
yarn add fhevm-contracts

# Using pnpm
pnpm add fhevm-contracts

Example

Local testing with the mock network

When testing your contracts locally, you can use the SepoliaZamaFHEVMConfig which provides a mock configuration for local development and testing. This allows you to test your contracts without needing to connect to a real network:

// SPDX-License-Identifier: BSD-3-Clause-Clear
pragma solidity ^0.8.24;

import { SepoliaZamaFHEVMConfig } from "fhevm/config/ZamaFHEVMConfig.sol";
import { ConfidentialERC20 } from "fhevm-contracts/contracts/token/ERC20/ConfidentialERC20.sol";

contract MyERC20 is SepoliaZamaFHEVMConfig, ConfidentialERC20 {
  constructor() ConfidentialERC20("MyToken", "MYTOKEN") {
    _unsafeMint(1000000, msg.sender);
  }
}

Deploying to Ethereum Sepolia

When deploying to Sepolia, you can use the SepoliaZamaFHEVMConfig which provides the correct configuration for the Sepolia testnet:

// SPDX-License-Identifier: BSD-3-Clause-Clear
pragma solidity ^0.8.24;

import { SepoliaZamaFHEVMConfig } from "fhevm/config/ZamaFHEVMConfig.sol";
import { ConfidentialERC20 } from "fhevm-contracts/contracts/token/ERC20/ConfidentialERC20.sol";

contract MyERC20 is SepoliaZamaFHEVMConfig, ConfidentialERC20 {
  constructor() ConfidentialERC20("MyToken", "MYTOKEN") {
    _unsafeMint(1000000, msg.sender);
  }
}

Best practices for contract inheritance

When inheriting from configuration contracts, the order of inheritance is critical. Since constructors are evaluated from left to right in Solidity, you must inherit the configuration contract first to ensure proper initialization.

✅ Correct Order:

contract MyERC20 is SepoliaZamaFHEVMConfig, ConfidentialERC20 { ... }

❌ Wrong order:

contract MyERC20 is ConfidentialERC20, SepoliaZamaFHEVMConfig { ... }

Available contracts

For a list of all available contracts see the page See all tutorials

This document provides a detailed guide on implementing decryption in your smart contracts using the GatewayContract in fhEVM. It covers the setup, usage of the Gateway.requestDecryption function, and testing with Hardhat.

GatewayContract set up

The GatewayContract is pre-deployed on the fhEVM testnet. It uses a default relayer account specified in the PRIVATE_KEY_GATEWAY_RELAYER or ADDRESS_GATEWAY_RELAYER environment variable in the .env file.

Relayers are the only accounts authorized to fulfill decryption requests. The role of the GatewayContract, however, is to independently verify the KMS signature during execution. This ensures that the relayers cannot manipulate or send fraudulent decryption results, even if compromised. However, the relayers are still trusted to forward decryption requests on time.

Gateway.requestDecryption function

The interface of the Gateway.requestDecryption function from previous snippet is the following:

  function requestDecryption(
      uint256[] calldata ctsHandles,
      bytes4 callbackSelector,
      uint256 msgValue,
      uint256 maxTimestamp,
      bool passSignaturesToCaller
  ) external virtual returns (uint256 initialCounter) {

Parameters

The first argument, ctsHandles, should be an array of ciphertexts handles which could be of different types, i.e uint256 values coming from unwrapping handles of type either ebool, euint4, euint8, euint16, euint32, euint64 or eaddress.

ct is the list of ciphertexts that are requested to be decrypted. Calling requestDecryption will emit an EventDecryption on the GatewayContract contract which will be detected by a relayer. Then, the relayer will send the corresponding ciphertexts to the KMS for decryption before fulfilling the request.

callbackSelector is the function selector of the callback function which will be called by the GatewayContract contract once the relayer fulfils the decryption request. Notice that the callback function should always follow this convention, if passSignaturesToCaller is set to false:

function [callbackName](uint256 requestID, XXX x_0, XXX x_1, ..., XXX x_N-1) external onlyGateway

Or, alternatively, if passSignaturesToCaller is set to true:

function [callbackName](uint256 requestID, XXX x_0, XXX x_1, ..., XXX x_N-1, bytes[] memory signatures) external onlyGateway

Notice that XXX should be the decrypted type, which is a native Solidity type corresponding to the original ciphertext type, following this table of conventions:

Here callbackName is a custom name given by the developer to the callback function, requestID will be the request id of the decryption (could be commented if not needed in the logic, but must be present) and x_0, x_1, ... x_N-1 are the results of the decryption of the ct array values, i.e their number should be the size of the ct array.

msgValue is the value in native tokens to be sent to the calling contract during fulfilment, i.e when the callback will be called with the results of decryption.

maxTimestamp is the maximum timestamp after which the callback will not be able to receive the results of decryption, i.e the fulfilment transaction will fail in this case. This can be used for time-sensitive applications, where we prefer to reject decryption results on too old, out-of-date, values.

passSignaturesToCaller determines whether the callback needs to transmit signatures from the KMS or not. This is useful if the dApp developer wants to remove trust from the Gateway service and prefers to check the KMS signatures directly from within his dApp smart contract. A concrete example of how to verify the KMS signatures inside a dApp is available here in the requestBoolTrustless function.

WARNING: Notice that the callback should be protected by the onlyGateway modifier to ensure security, as only the GatewayContract contract should be able to call it.

Finally, if you need to pass additional arguments to be used inside the callback, you could use any of the following utility functions during the request, which would store additional values in the storage of your smart contract:

function addParamsEBool(uint256 requestID, ebool _ebool) internal;

function addParamsEUint4(uint256 requestID, euint4 _euint4) internal;

function addParamsEUint8(uint256 requestID, euint8 _euint8) internal;

function addParamsEUint16(uint256 requestID, euint16 _euint16) internal;

function addParamsEUint32(uint256 requestID, euint32 _euint32) internal;

function addParamsEUint64(uint256 requestID, euint64 _euint64) internal;

function addParamsEAddress(uint256 requestID, eaddress _eaddress) internal;

function addParamsAddress(uint256 requestID, address _address) internal;

function addParamsUint256(uint256 requestID, uint256 _uint) internal;

With their corresponding getter functions to be used inside the callback:

function getParamsEBool(uint256 requestID) internal;

function getParamsEUint4(uint256 requestID) internal;

function getParamsEUint8(uint256 requestID) internal;

function getParamsEUint16(uint256 requestID) internal;

function getParamsEUint32(uint256 requestID) internal;

function getParamsEUint64(uint256 requestID) internal;

function getParamsEAddress(uint256 requestID) internal;

function getParamsAddress(uint256 requestID) internal;

function getParamsUint256(uint256 requestID) internal;

For example, see this snippet where we add two uint256s during the request call, to make them available later during the callback:

pragma solidity ^0.8.24;

import "fhevm/lib/TFHE.sol";
import { SepoliaZamaFHEVMConfig } from "fhevm/config/ZamaFHEVMConfig.sol";
import { SepoliaZamaGatewayConfig } from "fhevm/config/ZamaGatewayConfig.sol";
import "fhevm/gateway/GatewayCaller.sol";

contract TestAsyncDecrypt is SepoliaZamaFHEVMConfig, SepoliaZamaGatewayConfig, GatewayCaller {
  euint32 xUint32;
  uint32 public yUint32;

  constructor() {
      xUint32 = TFHE.asEuint32(32);
      TFHE.allowThis(xUint32);
  }

  function requestUint32(uint32 input1, uint32 input2) public {
      uint256[] memory cts = new uint256[](1);
      cts[0] = Gateway.toUint256(xUint32);
      uint256 requestID = Gateway.requestDecryption(cts, this.callbackUint32.selector, 0, block.timestamp + 100, false);
      addParamsUint256(requestID, input1);
      addParamsUint256(requestID, input2);
  }

  function callbackUint32(uint256 requestID, uint32 decryptedInput) public onlyGateway returns (uint32) {
    uint256[] memory params = getParamsUint256(requestID);
    unchecked {
        uint32 result = uint32(params[0]) + uint32(params[1]) + decryptedInput;
        yUint32 = result;
        return result;
    }
}

When the decryption request is fufilled by the relayer, the GatewayContract contract, when calling the callback function, will also emit the following event:

event ResultCallback(uint256 indexed requestID, bool success, bytes result);

The first argument is the requestID of the corresponding decryption request, success is a boolean assessing if the call to the callback succeeded, and result is the bytes array corresponding the to return data from the callback.

In your hardhat tests, if you sent some transactions which are requesting one or several decryptions and you wish to await the fulfilment of those decryptions, you should import the two helper methods initGateway and awaitAllDecryptionResults from the asyncDecrypt.ts utility file. This would work both when testing on an fhEVM node or in mocked mode. Here is a simple hardhat test for the previous TestAsyncDecrypt contract (more examples can be seen here):

import { initGateway, awaitAllDecryptionResults } from "../asyncDecrypt";
import { getSigners, initSigners } from "../signers";
import { expect } from "chai";
import { ethers } from "hardhat";

describe("TestAsyncDecrypt", function () {
  before(async function () {
    await initGateway();
    await initSigners(3);
    this.signers = await getSigners();
  });

  beforeEach(async function () {
    const contractFactory = await ethers.getContractFactory("TestAsyncDecrypt");
    this.contract = await contractFactory.connect(this.signers.alice).deploy();
  });

  it("test async decrypt uint32", async function () {
    const tx2 = await this.contract.connect(this.signers.carol).requestUint32(5, 15, { gasLimit: 500_000 }); // custom gasLimit to avoid gas estimation error in fhEVM mode
    await tx2.wait();
    await awaitAllDecryptionResults();
    const y = await this.contract.yUint32();
    expect(y).to.equal(52); // 5+15+32
  });
});

You should initialize the gateway by calling initGateway at the top of the before block - more specifically, before doing any transaction which could involve a decryption request. Notice that when testing on the fhEVM, a decryption is fulfilled usually 2 blocks after the request, while in mocked mode the fulfilment will always happen as soon as you call the awaitAllDecryptionResults helper function. A good way to standardize hardhat tests is hence to always call the awaitAllDecryptionResults function which will ensure that all pending decryptions are fulfilled in both modes.

This document explains how to perform re-encryption. Re-encryption is required when you want a user to access their private data without it being exposed to the blockchain.

Re-encryption in fhEVM enables the secure sharing or reuse of encrypted data under a new public key without exposing the plaintext. This feature is essential for scenarios where encrypted data must be transferred between contracts, dApps, or users while maintaining its confidentiality.

When to use re-encryption

Re-encryption is particularly useful for allowing individual users to securely access and decrypt their private data, such as balances or counters, while maintaining data confidentiality.

Overview

The re-encryption process involves retrieving ciphertext from the blockchain and performing re-encryption on the client-side. In other words we take the data that has been encrypted by the KMS, decrypt it and encrypt it with the users private key, so only he can access the information.

This ensures that the data remains encrypted under the blockchain’s FHE key but can be securely shared with a user by re-encrypting it under the user’s NaCl public key.

Re-encryption is facilitated by the Gateway and the Key Management System (KMS). The workflow consists of the following:

1. Retrieving the ciphertext from the blockchain using a contract’s view function.

2. Re-encrypting the ciphertext client-side with the user’s public key, ensuring only the user can decrypt it.

Step 1: retrieve the ciphertext

To retrieve the ciphertext that needs to be re-encrypted, you can implement a view function in your smart contract. Below is an example implementation:

import "fhevm/lib/TFHE.sol";

contract ConfidentialERC20 {
  ...
  function balanceOf(account address) public view returns (bytes euint64) {
    return balances[msg.sender];
  }
  ...
}

Here, balanceOf allows retrieval of the user’s encrypted balance stored on the blockchain.

Step 2: re-encrypt the ciphertext

Re-encryption is performed client-side using the fhevmjs library. Refer to the guide to learn how to include fhevmjs in your project. Below is an example of how to implement reencryption in a dApp:

import { createInstances } from "../instance";
import { getSigners, initSigners } from "../signers";
import abi from "./abi.json";
import { Contract, BrowserProvider } from "ethers";
import { createInstance } from "fhevmjs/bundle";

const CONTRACT_ADDRESS = "";

const provider = new BrowserProvider(window.ethereum);
const accounts = await provider.send("eth_requestAccounts", []);
const USER_ADDRESS = accounts[0];

await initSigners(); // Initialize signers
const signers = await getSigners();

const instance = await createInstances(this.signers);
// Generate the private and public key, used for the reencryption
const { publicKey, privateKey } = instance.generateKeypair();

// Create an EIP712 object for the user to sign.
const eip712 = instance.createEIP712(publicKey, CONTRACT_ADDRESS);

// Request the user's signature on the public key
const params = [USER_ADDRESS, JSON.stringify(eip712)];
const signature = await window.ethereum.request({ method: "eth_signTypedData_v4", params });

// Get the ciphertext to reencrypt
const ConfidentialERC20 = new Contract(CONTRACT_ADDRESS, abi, signer).connect(provider);
const encryptedBalance = ConfidentialERC20.balanceOf(userAddress);

// This function will call the gateway and decrypt the received value with the provided private key
const userBalance = instance.reencrypt(
  encryptedBalance, // the encrypted balance
  privateKey, // the private key generated by the dApp
  publicKey, // the public key generated by the dApp
  signature, // the user's signature of the public key
  CONTRACT_ADDRESS, // The contract address where the ciphertext is
  USER_ADDRESS, // The user address where the ciphertext is
);

console.log(userBalance);

This code retrieves the user’s encrypted balance, re-encrypts it with their public key, and decrypts it on the client-side using their private key.

Key additions to the code

• instance.generateKeypair(): Generates a public-private keypair for the user.

• instance.createEIP712(publicKey, CONTRACT_ADDRESS): Creates an EIP712 object for signing the user’s public key.

• instance.reencrypt(): Facilitates the re-encryption process by contacting the Gateway and decrypting the data locally with the private key.

Applying re-encryption to the counter example

Here’s an enhanced Encrypted Counter example where each user maintains their own encrypted counter. Re-encryption is used to securely share counter values with individual users.

Encrypted counter with re-encryption

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import "fhevm/lib/TFHE.sol";
import { SepoliaZamaFHEVMConfig } from "fhevm/config/ZamaFHEVMConfig.sol";

/// @title EncryptedCounter4
/// @notice A contract that maintains encrypted counters for each user and is meant for demonstrating how re-encryption works
/// @dev Uses TFHE library for fully homomorphic encryption operations
/// @custom:security Each user can only access and modify their own counter
/// @custom:experimental This contract is experimental and uses FHE technology
contract EncryptedCounter4 is SepoliaZamaFHEVMConfig {
  // Mapping from user address to their encrypted counter value
  mapping(address => euint8) private counters;

  function incrementBy(einput amount, bytes calldata inputProof) public {
    // Initialize counter if it doesn't exist
    if (!TFHE.isInitialized(counters[msg.sender])) {
      counters[msg.sender] = TFHE.asEuint8(0);
    }

    // Convert input to euint8 and add to sender's counter
    euint8 incrementAmount = TFHE.asEuint8(amount, inputProof);
    counters[msg.sender] = TFHE.add(counters[msg.sender], incrementAmount);
    TFHE.allowThis(counters[msg.sender]);
    TFHE.allow(counters[msg.sender], msg.sender);
  }

  function getCounter() public view returns (euint8) {
    // Return the encrypted counter value for the sender
    return counters[msg.sender];
  }
}

Frontend code of re-encryption / tests for EncryptedCounter4

Here’s a sample test to verify re-encryption functionality:

import { createInstance } from "../instance";
import { reencryptEuint8 } from "../reencrypt";
import { getSigners, initSigners } from "../signers";
import { expect } from "chai";
import { ethers } from "hardhat";

describe("EncryptedCounter4", function () {
  before(async function () {
    await initSigners(); // Initialize signers
    this.signers = await getSigners();
  });

  beforeEach(async function () {
    const CounterFactory = await ethers.getContractFactory("EncryptedCounter4");
    this.counterContract = await CounterFactory.connect(this.signers.alice).deploy();
    await this.counterContract.waitForDeployment();
    this.contractAddress = await this.counterContract.getAddress();
    this.instances = await createInstance();
  });

  it("should allow reencryption and decryption of counter value", async function () {
    const input = this.instances.createEncryptedInput(this.contractAddress, this.signers.alice.address);
    input.add8(1); // Increment by 1 as an example
    const encryptedAmount = await input.encrypt();

    // Call incrementBy with encrypted amount
    const tx = await this.counterContract.incrementBy(encryptedAmount.handles[0], encryptedAmount.inputProof);
    await tx.wait();

    // Get the encrypted counter value
    const encryptedCounter = await this.counterContract.getCounter();

    const decryptedValue = await reencryptEuint8(
      this.signers,
      this.instances,
      "alice",
      encryptedCounter,
      this.contractAddress,
    );

    // Verify the decrypted value is 1 (since we incremented once)
    expect(decryptedValue).to.equal(1);
  });

  it("should allow reencryption of counter value", async function () {
    const input = this.instances.createEncryptedInput(this.contractAddress, this.signers.bob.address);
    input.add8(1); // Increment by 1 as an example
    const encryptedAmount = await input.encrypt();

    // Call incrementBy with encrypted amount
    const tx = await this.counterContract
      .connect(this.signers.bob)
      .incrementBy(encryptedAmount.handles[0], encryptedAmount.inputProof);
    await tx.wait();

    // Get the encrypted counter value
    const encryptedCounter = await this.counterContract.connect(this.signers.bob).getCounter();

    const decryptedValue = await reencryptEuint8(
      this.signers,
      this.instances,
      "bob",
      encryptedCounter,
      this.contractAddress,
    );

    // Verify the decrypted value is 1 (since we incremented once)
    expect(decryptedValue).to.equal(1);
  });
});

Key additions in testing

• setupReencryption(): Prepares the re-encryption process by generating keys and a signature for the user.

• instance.reencrypt(): Facilitates re-encryption and local decryption of the data for testing purposes.

• Validation: Confirms that the decrypted counter matches the expected value.

This section explains how to handle decryption in fhEVM. Decryption allows plaintext data to be accessed when required for contract logic or user presentation, ensuring confidentiality is maintained throughout the process.

Decryption is essential in two primary cases:

1. Smart contract logic: A contract requires plaintext values for computations or decision-making.

2. User interaction: Plaintext data needs to be revealed to all users, such as revealing the decision of the vote.

To learn how decryption works see Encryption, Decryption, Re-encryption, and Computation

Overview

Decryption in fhEVM is an asynchronous process that involves the Gateway and Key Management System (KMS). Contracts requiring decryption must extend the GatewayCaller contract, which imports the necessary libraries and provides access to the Gateway.

Here’s an example of how to request decryption in a contract:

Example: asynchronous decryption in a contract

pragma solidity ^0.8.24;

import "fhevm/lib/TFHE.sol";
import { SepoliaZamaFHEVMConfig } from "fhevm/config/ZamaFHEVMConfig.sol";
import { SepoliaZamaGatewayConfig } from "fhevm/config/ZamaGatewayConfig.sol";
import "fhevm/gateway/GatewayCaller.sol";

contract TestAsyncDecrypt is SepoliaZamaFHEVMConfig, SepoliaZamaGatewayConfig, GatewayCaller {
  ebool xBool;
  bool public yBool;

  constructor() {
      xBool = TFHE.asEbool(true);
      TFHE.allowThis(xBool);
  }

  function requestBool() public {
    uint256[] memory cts = new uint256[](1);
    cts[0] = Gateway.toUint256(xBool);
    Gateway.requestDecryption(cts, this.myCustomCallback.selector, 0, block.timestamp + 100, false);
  }

  function myCustomCallback(uint256 /*requestID*/, bool decryptedInput) public onlyGateway returns (bool) {
    yBool = decryptedInput;
    return yBool;
  }

Key additions to the code

1. Configuration imports: The configuration contracts are imported to set up the FHEVM environment and Gateway.

   Copy

   import { SepoliaZamaFHEVMConfig } from "fhevm/config/ZamaFHEVMConfig.sol";
   import { SepoliaZamaGatewayConfig } from "fhevm/config/ZamaGatewayConfig.sol";

2. GatewayCaller import: The GatewayCaller contract is imported to enable decryption requests.

   Copy

   import "fhevm/gateway/GatewayCaller.sol";

Applying decryption to the counter example

Remember our Encrypted Counter contract from before? Here’s an improved version of it, upgraded to support decryption:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import "fhevm/lib/TFHE.sol";
import { SepoliaZamaFHEVMConfig } from "fhevm/config/ZamaFHEVMConfig.sol";
import { SepoliaZamaGatewayConfig } from "fhevm/config/ZamaGatewayConfig.sol";
import "fhevm/gateway/GatewayCaller.sol";

/// @title EncryptedCounter3
/// @notice A contract that maintains an encrypted counter and is meant for demonstrating how decryption works
/// @dev Uses TFHE library for fully homomorphic encryption operations and Gateway for decryption
/// @custom:experimental This contract is experimental and uses FHE technology with decryption capabilities
contract EncryptedCounter3 is SepoliaZamaFHEVMConfig, SepoliaZamaGatewayConfig, GatewayCaller {
    /// @dev Decrypted state variable
    euint8 internal counter;
    uint8 public decryptedCounter;

    constructor() {
        Gateway.setGateway(Gateway.defaultGatewayAddress());

        // Initialize counter with an encrypted zero value
        counter = TFHE.asEuint8(0);
        TFHE.allowThis(counter);
    }

    function incrementBy(einput amount, bytes calldata inputProof) public {
        // Convert input to euint8 and add to counter
        euint8 incrementAmount = TFHE.asEuint8(amount, inputProof);
        counter = TFHE.add(counter, incrementAmount);
        TFHE.allowThis(counter);
    }

    /// @notice Request decryption of the counter value
    function requestDecryptCounter() public {
        uint256[] memory cts = new uint256[](1);
        cts[0] = Gateway.toUint256(counter);
        Gateway.requestDecryption(cts, this.callbackCounter.selector, 0, block.timestamp + 100, false);
    }

    /// @notice Callback function for counter decryption
    /// @param decryptedInput The decrypted counter value
    /// @return The decrypted value
    function callbackCounter(uint256, uint8 decryptedInput) public onlyGateway returns (uint8) {
        decryptedCounter = decryptedInput;
        return decryptedInput;
    }

    /// @notice Get the decrypted counter value
    /// @return The decrypted counter value
    function getDecryptedCounter() public view returns (uint8) {
        return decryptedCounter;
    }
}

Tests for EncryptedCounter3

Here’s a sample test for the Encrypted Counter contract using Hardhat:

import { awaitAllDecryptionResults, initGateway } from "../asyncDecrypt";
import { createInstance } from "../instance";
import { getSigners, initSigners } from "../signers";
import { expect } from "chai";
import { ethers } from "hardhat";

describe("EncryptedCounter3", function () {
  before(async function () {
    await initSigners(); // Initialize signers
    this.signers = await getSigners();
    await initGateway(); // Initialize the gateway for decryption
  });

  beforeEach(async function () {
    const CounterFactory = await ethers.getContractFactory("EncryptedCounter3");
    this.counterContract = await CounterFactory.connect(this.signers.alice).deploy();
    await this.counterContract.waitForDeployment();
    this.contractAddress = await this.counterContract.getAddress();
    this.instances = await createInstance(); // Set up instances for testing
  });

  it("should increment counter and decrypt the result", async function () {
    // Create encrypted input for amount to increment by
    const input = this.instances.createEncryptedInput(this.contractAddress, this.signers.alice.address);
    input.add8(5); // Increment by 5 as an example
    const encryptedAmount = await input.encrypt();

    // Call incrementBy with encrypted amount
    const tx = await this.counterContract.incrementBy(encryptedAmount.handles[0], encryptedAmount.inputProof);
    await tx.wait();

    const tx4 = await this.counterContract.connect(this.signers.carol).requestDecryptCounter();
    await tx4.wait();

    // Wait for decryption to complete
    await awaitAllDecryptionResults();

    // Check decrypted value (should be 3: initial 0 + three increments)
    const decryptedValue = await this.counterContract.getDecryptedCounter();
    expect(decryptedValue).to.equal(5);
  });
});

Key additions in testing

1. Initialize the Gateway:

   Copy

   await initGateway(); // Initialize the gateway for decryption

2. Request decryption and wait for results:

   Copy

   const decryptTx = await this.counterContract.requestDecryptCounter({ gasLimit: 5_000_000 });
   await decryptTx.wait();
   await awaitAllDecryptionResults();

3. Verify the decrypted value:

   Copy

   const decryptedValue = await this.counterContract.getDecryptedCounter();
   expect(decryptedValue).to.equal(5);

Next steps

Explore advanced decryption techniques and learn more about re-encryption:

• Decryption in depth

• Re-encryption

This guide explains how to use the debug.decrypt[XX] functions for debugging encrypted data in mocked environments during development with fhEVM.

[!WARNING] The debug.decrypt[XX] functions should not be used in production as they rely on private keys.

Overview

The debug.decrypt[XX] functions allow you to decrypt encrypted handles into plaintext values. This feature is useful for debugging encrypted operations such as transfers, balance checks, and other computations involving FHE-encrypted data.

Key points

• Environment: The debug.decrypt[XX] functions work only in mocked environments (e.g., hardhat network).

• Production limitation: In production, decryption is performed asynchronously via the Gateway and requires an authorized onchain request.

• Encrypted types: The debug.decrypt[XX] functions supports various encrypted types, including integers, booleans, and ebytesXX.

• Bypass ACL authorization: The debug.decrypt[XX] functions allow decryption without ACL authorization, useful for verifying encrypted operations during development and testing.