This tutorial covers the essentials steps to quickly write and deploy confidential ERC20 smart contract using the Zama Plug in.

Remix is a powerful in-browser IDE for Ethereum smart contract development. It offers a fast, intuitive way to write and deploy confidential ERC20 contracts using Zama’s fhEVM plugin—no local setup required.

In this tutorial, you will learn to:

1. Set up Remix for fhEVM development.

2. Connect your wallet (e.g., MetaMask) to Remix.

3. Deploy a ConfidentialERC20 contract.

4. Interact with your deployed contract directly in the Remix interface.

By the end, you’ll have a working confidential ERC20 token on Sepolia network and know how to perform encrypted transactions.

In this guide, you'll learn how to connect your wallet and the Zama Plugin in Remix IDE to interact with fhEVM smart contracts.

Prerequisites

Before starting, ensure you have the following:

• MetaMask or another Ethereum-compatible wallet installed.

Step 1. Setting up Sepolia testnet

If you're using Metamask, the Sepolia testnet should be pre-configured. Follow the steps to set it up:

1. Open MetaMask.

2. Click the network dropdown at the top left corner, and select Sepolia Test Network.

3. Ensure you have Sepolia ETH available. If you don’t have enough ETH, use a Sepolia faucet to request free SepoliaETH for testing:

Step 2. Connecting to Zama Plugin

Zama Plugin provides the Zama Coprocessor - Sepolia configuration that ensures Remix and the wallet are properly set up to interact with fhEVM smart contracts.

To complete the configuration:

1. Open the Zama Plugin in Remix from the side pannel.

2. Click Connect your wallet.

3. Confirm the connection in MetaMask.

4. In the Zama Plugin, select Zama Coprocessor - Sepolia.

5. Click Use this configuration to finalize the setup.

Once successful, you should see the green text in the terminal indicating that the configuration is ready.

Step 3. Connecting wallet to Remix

Follow the steps to connect your wallet to Remix:

1. Open Remix and navigate to Deploy & run transactions.

2. Under Environment, select Injected Provider - MetaMask.

3. MetaMask will prompt a connection request. Click Connect to proceed.

4. Choose your wallet address in Account.

Now that your wallet is connected and your SepoliaETH balance is ready, you can proceed to deploy the ConfidentialERC20Mintable contract!

fhEVM is a suite of solutions that enables confidential smart contracts on the EVM using Fully Homomorphic Encryption (FHE). This document provides a high-level overview of the fhEVM suite along with onboarding guidance tailored to specific audiences.

For dApp developers

The fhEVM Protocol provides a TFHE Solidity library for building confidential smart contracts, a fhevm.js Javascript library to enable front‐end FHE interactions, and a range of developer tools, examples, and templates to streamline the usage for developers.

Smart contract development

Frontend development

Examples & Resources

For network builders

To integrate FHE at the protocol level or operate an FHE‐enabled network, fhEVM offers the fhevm backend modules. These repositories include the foundational implementations that enables FHE in blockchain systems, ensuring that privacy remains at the core of your network architecture.

After deploying your first fhEVM contract using Remix, this guide shows you how to interact with it directly in Remix using the Zama Plugin.

Prerequisite

Before interacting with your deployed contract, ensure the following:

Step 1. Connecting the deployed contract

To perform transactions directly in Remix, your contract needs to be connected to the Zama Plugin:

1. Open Deploy & run transaction from the side bar

2. In "Deployed Contract", copy the address of the MYCONFIDENTIALERC20 contract that you just deployed.

3. Open the Zama Plugin from the side menu.

4. Paste the contract address into the "At address" field under the Deploy section.

5. Click At address.

If the address was entered correctly, the MyConfidentialERC20.sol contract will be displayed in the "Deployed Contract" inside the Zama Plugin.

Click to expand the contract, you'll see the interface to interact with all the functions of your contract. ConfidentialERC20Mintable supports all standard ERC-20 functions, but adapted for encrypted values, including:

• transfer: Securely transfers encrypted tokens.

• approve: Approves encrypted amounts for spending.

• transferFrom: Transfers tokens on behalf of another address.

• balanceOf: Returns the encrypted balance of an account.

• totalSupply: Returns the total token supply.

Step 2. Mint tokens to your account

From here, you can mint confidential ERC20 token to your account:

1. Copy your wallet address from MetaMask.

2. Inside Zama Plugin, click to expand the mint function of your contract.

3. Enter your wallet address and the amount of tokens to mint (e.g., 1000).

4. Click Submit.

5. Confirm the transaction in MetaMask.

Once sccussful, you should see the message in the terminal.

Step 3. Verify total supply

After a successful mint transaction, click the totalSupply to reflect the minted tokens (e.g., 1000).

Step 4. Check your balance

To verify your account balance:

1. Click to expand the balanceOf function.

2. Enter your wallet address.

3. Click Submit to verify your account balance.

Your balance is stored as encrypted data using FHE. No one else can view if except you.

To view the balance in plaintext:

• Click the re-encrypt option

• Confirm the transaction in Metamask

You can see that the ciphertext is decrypted and your balance is the amount that you just minted.

Step 5. Transfer tokens

To transfer confidential ERC20 tokens to another account:

1. Copy the address of the receiver's wallet.

2. Click transfer to expand the function, set the following parameters:

   • To: Enter the wallet address of reveiver.

   • encryptedAmount: Specify the amount that you want to transfer (e.g.1000). Choose euint64.

   • inputProof: Check the input box.

3. Click Submit to proceed.

4. Confirm the transaction in MetaMask.

If successful, you should see the message in the terminal.

Step 6. Verify updated balance

After making a transfer, you can verify your updated account balance:

2. Perform re-encryption to confirm the changes, you should see the remaining token in your account.(e.g., 900 tokens remaining).

Next steps

🎉 Congratulations on completing this tutorial! You’ve taken the first step in building confidential smart contracts using fhEVM. It's time now to take the next step and build your own confidential dApps!

1. Resources

To continue your journey and deepen your knowledge, explore the resources below.

2. Tools

Use out-of-box templates and frameworks designed for developers to build confidential dapps easily.

Smart contract development

Frontend development

3. Community

Join the community to shape the future of blockchain together with us.

In this tutorial, you'll learn how to deploy a confidential token contract using Zama's fhEVM. We'll create MyConfidentialERC20.sol to demonstrate the essential features.

Prerequisites

Ensure the following before deploying the smart contract:

Step 1. Setting up the contract file

First, let's create a file for our confidential ERC20 contract:

1. Open the File explorer from the side menu.

2. Navigate to the contracts folder.

3. Click the Create new file icon.

4. Name the file MyConfidentialERC20.sol and press Enter.

Step 2. Writing contract

Step 2.1 Basic contract structure

The foundational structure includes importing Zama's libraries and connecting to Sepolia's fhEVM configuration.

Copy the following code in the MyConfidentialERC20.sol that you just created:

It should appear as follows:

Remix automatically saves any changes as you type. Upon saving, it imports the following libraries:

• TFHE.sol: The core Solidity library of Zama's fhEVM. It enables encrypted data type like euint64, secures encrypted operations, such as addition and comparison and allows access control.

• SepoliaZamaFHEVMConfig: A configuration contract that automatically sets up the required configurations for real-time encrypted operations on the Sepolia testnet.

Step 2.2 Enhancing the functionality

Next, we'll enhance our contract by importing the fhevm-contracts library.

The fhevm-contracts library includes the ConfidentialERC20Mintable contract, which is an extention of ConfidentialERC20 with minting capabilities, providing:

• Private token transfers and encrypted balances

• Minting functionality for authorized addresses

• Full ERC20 compatibility

It inherits all base ConfidentialERC20 features while adding secure token creation and distribution capabilities.

To use ConfidentialERC20Mintable contract, simply update your MyConfidentialERC20.sol with the following code:

It should appear as follows:

Step 3. Compiling the contract

Now the contract is ready, the next step is to compile it:

1. Select MyConfidentialERC20.sol.

2. Go to Solidity compiler in Remix.

3. Click Compile.

If successful, you will see a green checkmark on the Solidity Compiler, indicating "Compilation successful"

Step 4. Deploying the contract

Now the contract is ready to be deployed:

1. Make sure that the envrionment is set up properly

   1. Envrionment: Injected Provider - Metamask

   2. Account: Your wallet address

2. Expand the Deploy section.

3. Fill the constructor parameters:

   • Name: Your token’s name (e.g., "My Private Token").

   • Symbol: Token symbol (e.g., "MPT").

4. Click Transact and confirm the transaction in MetaMask.

Once successfully deployed, your contract will appear under Deployed Contracts. You can also view your contract on Etherscan by clicking the contract address.

By following these steps, you’ve successfully created and deployed an confidential ERC-20 token using Zama's fhEVM!🎉 Let's see how the transaction works in the next chapter.

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.

Explanations

Explore the technical architecture of the fhEVM protocol and the underlying cryptographic principles that power it.

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 helps you set up the Zama Plugin in the official Remix IDE, enabling seamless development and management of smart contracts using the fhEVM.

Prerequisites

Before starting, make sure you have the following:

• A web browser (such as Chrome, Firefox).

• Basic familiarity with Ethereum smart contracts.

• A crypto wallet (we recommend using MetaMask for this tutorial).

Step 1. Connecting to the Zama Plugin in Remix

Zama Plugin allows you to interact with confidential contracts directly within Remix. To set it up:

2. In the left sidebar, click on the Plugin Manager.

3. In the Plugin Manager, select Connect to a Local Plugin.

Step 2. Installing the Zama Plugin

Use the following configurations:

• Plugin Name (required) : Enter Zama.

• URL(required): Enter https://remix.zama.ai/.

• Type of connection(required): Select Iframe

• Location in remix (required):Select Side Panel

• Click OK.

Now that you've configured the plugin, you are able to deploy and interact with fhEVM encrypted contracts directly directly via Remix interface. Next, let's dive into the contract deployment.

Hardhat is a flexible, extensible development environment for Ethereum, providing a robust toolkit for compiling, testing, and deploying smart contracts. With Zama’s fhEVM integration, you can develop confidential ERC20 contracts locally and then seamlessly deploy them to a real fhEVM node.

In this tutorial, you will learn to:

2. Write confidential contracts utilizing encrypted data types.

3. Test your contracts in mocked mode (for rapid feedback and coverage).

4. Deploy your confidential ERC20 contract to the Sepolia test network.

5. Interact with your deployed contract, including performing encrypted transfers.

By following these steps, you’ll get familiar with the complete development workflow using Hardhat, and be able to build, test and deploy confidential ERC20 smart contracts on Sepolia testnet.

This tutorial walks you through performing tests in the mocked mode provided by the fhEVM Hardhat template.

Prerequisites

Before proceeding, ensure you have:

Running your tests

To run tests in mocked mode, open a terminal in your project's root directory and execute:

# Using npm
npm run test

# Using yarn
yarn test

# Using pnpm
pnpm test

This command runs all tests locally in mocked mode. You should see the test results in your console.

Next steps

This guide will walk you through installing all necessary dependencies from scratch, preparing you for developing and deploying fhEVM smart contracts using Hardhat.

To use Hardhat to build and deploy confidential smart contract, you need to have the following:

• Node.js (v20 or later)

• A package manager: npm, yarn, or pnpm

• Git for version control

• Foundry for using the command cast

Step 1: Open your terminal

To run the installation commands, open a terminal:

• Use your system's built-in terminal (e.g., Terminal on macOS, Command Prompt or PowerShell on Windows, or a Linux shell).

Step 2. Install Node.js and a package manager

Instead of installing Node.js directly, we recommend using Node Version Manager (nvm), which allows you to manage multiple versions of Node.js:

1. Install nvm following the recommended tutorials:
2. Install Node.js using nvm. This installs the latest version of Node.js:

nvm install node

1. Install pnpm (optional but recommended for better speed and efficiency). After installing Node.js, you automatically have npm, so run:

npm install -g pnpm

Alternatively, you can continue using npm or yarn if you prefer.

Step 3. Install Git

Git is required for managing source code, cloning repositories, and handling version control. Install Git based on your operating system:

• Linux: Use your distribution's package manager (e.g., sudo apt-get install git on Ubuntu/Debian).

Step 4. Install Foundry

We will need the command cast in our tutorial. This command is available with installing Foundry.

1. Install Foundry using the official installer:

curl -L https://foundry.paradigm.xyz | bash

1. Reload your terminal configuration:

source ~/.bashrc  # Linux/WSL
# or
source ~/.zshrc   # macOS/zsh

1. Run the Foundry installer:

foundryup

This will install all Foundry components, including cast, forge, anvil, and chisel.

To verify the installation, run:

cast --version

Next Steps

This guide walks you through setting up your Hardhat environment using Zama's fhEVM Hardhat template.

Step 1: Clone the Hardhat template

2. Click "Use this template" to create a new repository under your GitHub account.

3. Clone the repository you have created to your local environment

4. Copy the repository URL of your newly created repository.

5. Open a terminal and run:

git clone <your-new-repo-url>
cd <your-new-repo-name>

Step 2: Configure the environment

1. Copy the environment configuration template:

   Copy

   cp .env.example .env

2. Install project dependencies: Depending on your package manager, run one of the following:

   Copy

   # Using npm
   npm install
   
   # Using yarn
   yarn install
   
   # Using pnpm
   pnpm install

Project structure overview

• contracts/: Write your Solidity smart contracts here.

• test/: Place your test scripts for smart contract testing.

• deploy/: Deployment scripts for deploying your contracts.

• hardhat.config.js: The pre-configured Hardhat setup file for deploying on Sepolia.

• .env: The environment file that stores sensitive or environment-specific variables such as private keys and API keys.

You are now ready to start building your confidential smart contracts with fhEVM!

This document explains how to write confidential smart contract using fhEVM in Hardhat projects.

Prerequisites

Before proceeding, ensure you have:

• Basic knowledge of Solidity.

• An understanding of ERC20 tokens.

Understanding the example contract

The Hardhat template includes an example contract in the contracts/ folder - MyConfidentialERC20.sol. This contract enables:

• Private ERC20 token transfers.

• Encrypted balances.

• Minting functionality for authorized addresses.

Let's break down the contract.

Step 1. Importing required libraries and contracts.

pragma solidity ^0.8.24;

import "fhevm/lib/TFHE.sol";
import "fhevm/config/ZamaFHEVMConfig.sol";
import "fhevm-contracts/contracts/token/ERC20/extensions/ConfidentialERC20Mintable.sol";

• TFHE.sol: The core Solidity library of Zama's fhEVM. It enables encrypted data type like euint64, secures encrypted operations, such as addition and comparison and allows access control.

• SepoliaZamaFHEVMConfig: A configuration contract that automatically sets up the required configurations for real-time encrypted operations on the Sepolia testnet.

• ConfidentialERC20Mintable.sol : The confidential smart contract that allows for full ERC20 compatibility with FHE encryption.

Step 2. Contract construction

contract MyConfidentialERC20 is SepoliaZamaFHEVMConfig, ConfidentialERC20Mintable {
  constructor(string memory name_, string memory symbol_) ConfidentialERC20Mintable(name_, symbol_, msg.sender) {}
}

• This contract inherits SepoliaZamaFHEVMConfig and ConfidentialERC20Mintable.

• The constructor initializes the ERC20 token with a name and symbol, setting the deployer as the initial owner.

Going further

This is a simple basic contract that we will deploy and use in this tutorial. To write more complex confidential smart contracts or customize your own functions:

• Use the fhevm-contracts library and extend from the basic contract templates.

Your contract is ready! Let's move on to testing and deployment.

Solidity smart contracts templates - fhevm-contracts

Token

Governance

Utils

Code examples on GitHub

Frontend examples

Blog tutorials

Video tutorials

Legacy - Not compatible with latest fhEVM

This guide walks you through deploying your Confidential ERC20 smart contract on the Sepolia test network.

Prerequisites

Before proceeding, ensure you have:

• A configured Hardhat project using the fhEVM Hardhat Template (see previous sections).

• A crypto wallet installed (e.g., Metamask).

• Some Sepolia ETH available for testing. If you don’t have enough ETH, use a Sepolia faucet to request free SepoliaETH for testing:

Step 1. Preparing for deployment

1. Generate a mnemonic seed for accounts using cast:

   • (cast is a Foundry function. If you don't have Foundry installed, run curl -L https://foundry.paradigm.xyz | bash first):

1. Obtain a Sepolia RPC URL:

   • Sign up for a node provider such as Alchemy - https://www.alchemy.com/ or Infura - https://infura.io/. Copy your Sepolia RPC URL.

2. Open the .env file:

   • Past your mnemonic in the code:

     • MNEMONIC=<Your mnemonic generated>

   • Paste a Sepolia RPC URL:

     • SEPOLIA_RPC_URL=<Your node provider URL>

3. Verify generated accounts:

Step 2. Funding your wallet

1. Open your wallet (e.g, MetaMask)

2. Import the first 2 accounts (e.g., Alice and Bob) into your wallet with their private keys.

3. Fund these 2 accounts with some Sepolia ETH.

Step 3. Deploying the contract

In the deploy/ directory, there is a preconfigured deploy.ts file that handles the deployment process. You can customize it or add your own scripts.

To deploy the contracts to Sepolia, run:

Step 4. Verify the deployment

Once deployment is successful, you should see a console output that includes the contract address such as:

Congratulations! 🎉 You have deployed your first confidential ERC20 smart contract. Let's mint a few tokens and perform some encrypted transactions!

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:

Purpose:

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

• Ensures proper initialization of the FHEVM environment.

Example: using Sepolia configuration

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

Purpose

• Configures the Gateway for secure cryptographic operations.

• Facilitates reencryption and decryption requests.

Example: Configuring the gateway with Sepolia settings

Using isInitialized

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

Function signature

Purpose

• Ensures encrypted variables are initialized before use.

• Prevents potential logic errors in contract execution.

Example: Initialization Check for Encrypted Counter

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.

After deploying your first fhEVM contract using Hardhat, this guide shows you how to interact with it using Hardhat tasks.

Prerequisites

Before interacting with your deployed contract, ensure the following:

• Deployment completed: You have successfully deployed the MyConfidentialERC20 contract (see previous section)

• Contract address: You have saved the deployed contract address

• Sepolia ETH: You have some Sepolia ETH in your wallet for transaction fees

• Environment setup: Your .env file is properly configured with your private key

Step 1: Mint tokens to your account

First, let's mint some confidential tokens to your account:

Once successful, you'll see a transaction confirmation in the terminal that looks like this:

Step 2: Verify total supply

You can check the total supply of tokens to confirm your mint was successful:

Once successful, you'll see a transaction confirmation in the terminal:

Step 3: Check your balance

To verify your account balance:

Note to remind yourself what was are the private keys of the accounts of the MNEMONIC SEED you can always check it by running:

Once successful, you'll see a transaction confirmation in the terminal.

Step 4: Transfer tokens

To transfer confidential tokens to another account:

Once successful, you'll see a transaction confirmation in the terminal.

Step 5: Verify updated balances

After the transfer, you can check both accounts balances:

If both balances have changed accordingly the transaction was successful.

Available Tasks

Here's a complete list of available Hardhat tasks for interacting with your contract:

• mint: Mint new encrypted tokens

• transfer: Transfer encrypted tokens to another address

• balance: Check encrypted balance of an account

• totalSupply: Get the total token supply

For detailed help on any task, run:

Next steps

🎉 Congratulations on completing this tutorial! You’ve taken the first step in building confidential smart contracts using fhEVM. It's time now to take the next step and build your own confidential dApps!

1. Resources

To continue your journey and deepen your knowledge, explore the resources below.

2. Tools

Use out-of-box templates and frameworks designed for developers to build confidential dApps easily.

Smart contract development

Frontend development

3. Community

Join the community to shape the future of blockchain together with us.

This document provides an overview of key features of the fhEVM smart contract library.

Configuration and initialization

Smart contracts using fhEVM require proper configuration and initialization:

• Environment setup: Import and inherit from environment-specific configuration contracts

• Gateway configuration: Configure secure gateway access for cryptographic operations

• Initialization checks: Validate encrypted variables are properly initialized before use

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.

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

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.

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.

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 token 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 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

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.

Save this in your .env file:

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 fulfillment, 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 fulfillment 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.

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 to the return data from the callback.

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 fulfillment 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.

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 guide explains how to use Foundry with fhEVM for developing smart contracts.

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 hardhat). 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 explains how to generate cryptographically secure random encrypted numbers fully on-chain using the TFHE library in fhEVM. These numbers are encrypted and remain confidential, enabling privacy-preserving smart contract logic.

Key notes on random number generation

• On-chain execution: Random number generation must be executed during a transaction, as it requires the pseudo-random number generator (PRNG) state to be updated on-chain. This operation cannot be performed using the eth_call RPC method.

• Cryptographic security: The generated random numbers are cryptographically secure and encrypted, ensuring privacy and unpredictability.

Basic usage

The TFHE library allows you to generate random encrypted numbers of various bit sizes. Below is a list of supported types and their usage:

Example: Random Boolean

Bounded random numbers

To generate random numbers within a specific range, you can specify an upper bound. The random number will be in the range [0, upperBound - 1].

Example: Random bumber with upper bound

Random encrypted bytes

To generate larger random values, you can use encrypted bytes. These are ideal for scenarios requiring high-precision or high-entropy data.

Example: Random Bytes

Security Considerations

• Cryptographic security: The random numbers are generated using a cryptographically secure pseudo-random number generator (CSPRNG) and remain encrypted until explicitly decrypted.

• Gas consumption: Each call to a random number generation function consumes gas. Developers should optimize the use of these functions, especially in gas-sensitive contracts.

• Privacy guarantee: Random values are fully encrypted, ensuring they cannot be accessed or predicted by unauthorized parties.

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

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.

Supported functions

Integer decryption

Decrypts encrypted integers of different bit-widths (euint4, euint8, ..., euint256).

Boolean decryption

Decrypts encrypted booleans (ebool).

Byte array decryption

Decrypts encrypted byte arrays of various sizes (ebytesXX).

Address decryption

Decrypts encrypted addresses.

Function usage

Example: decrypting encrypted values

Example: decrypting byte arrays

How it works

Verifying types

Each decryption function includes a type verification step to ensure the provided handle matches the expected encrypted type. If the type is mismatched, an error is thrown.

Environment checks

Best practices

• Use only for debugging: These functions require access to private keys and are meant exclusively for local testing and debugging.

• Production decryption: For production, always use the asynchronous Gateway-based decryption.

This document provides solutions for common Webpack errors encountered during the development process. Follow the steps below to resolve each issue.

Can't resolve 'tfhe_bg.wasm'

Error message: Module not found: Error: Can't resolve 'tfhe_bg.wasm'

Cause: In the codebase, there is a new URL('tfhe_bg.wasm') which triggers a resolve by Webpack.

Possible solutions: You can add a fallback for this file by adding a resolve configuration in your webpack.config.js:

Buffer not defined

Error message: ReferenceError: Buffer is not defined

Cause: This error occurs when the Node.js Buffer object is used in a browser environment where it is not natively available.

Possible solutions: To resolve this issue, you need to provide browser-compatible fallbacks for Node.js core modules. Install the necessary browserified npm packages and configure Webpack to use these fallbacks.

Issue with importing ESM version

Error message: Issues with importing ESM version

Cause: With a bundler such as Webpack or Rollup, imports will be replaced with the version mentioned in the "browser" field of the package.json. This can cause issues with typing.

Possible solutions:

• If you encounter any other issue, you can force import of the browser package.

Use bundled version

Error message: Issues with bundling the library, especially with SSR frameworks.

Cause: The library may not bundle correctly with certain frameworks, leading to errors during the build or runtime process.

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.

Save this in your .env file:

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.

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.

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:

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 document provides an overview of the functions available in the TFHE Solidity library. The TFHE library provides functionality for working with encrypted types and performing operations on them. It implements fully homomorphic encryption (FHE) operations in Solidity.

Overview

The TFHE Solidity library provides essential functionality for working with encrypted data types and performing fully homomorphic encryption (FHE) operations in smart contracts. It is designed to streamline the developer experience while maintaining flexibility and performance.

Core Functionality

• Homomorphic Operations: Enables arithmetic, bitwise, and comparison operations on encrypted values.

• Ciphertext-Plaintext Interoperability: Supports operations that mix encrypted and plaintext operands, provided the plaintext operand's size does not exceed the encrypted operand's size.

  • Example: add(uint8 a, euint8 b) is valid, but add(uint32 a, euint16 b) is not.

  • Ciphertext-plaintext operations are generally faster and consume less gas than ciphertext-ciphertext operations.

• Implicit Upcasting: Automatically adjusts operand types when necessary to ensure compatibility during operations on encrypted data.

Key Features

• Flexibility: Handles a wide range of encrypted data types, including booleans, integers, addresses, and byte arrays.

• Performance Optimization: Prioritizes efficient computation by supporting optimized operator versions for mixed plaintext and ciphertext inputs.

• Ease of Use: Offers consistent APIs across all supported data types, enabling a smooth developer experience.

The library ensures that all operations on encrypted data follow the constraints of FHE while abstracting complexity, allowing developers to focus on building privacy-preserving smart contracts.

Types

Encrypted Data Types

Boolean

• ebool: Encrypted boolean value

Unsigned Integers

• euint4: Encrypted 4-bit unsigned integer

• euint8: Encrypted 8-bit unsigned integer

• euint16: Encrypted 16-bit unsigned integer

• euint32: Encrypted 32-bit unsigned integer

• euint64: Encrypted 64-bit unsigned integer

• euint128: Encrypted 128-bit unsigned integer

• euint256: Encrypted 256-bit unsigned integer

Addresses & Bytes

• eaddress: Encrypted Ethereum address

• ebytes64: Encrypted 64-byte value

• ebytes128: Encrypted 128-byte value

• ebytes256: Encrypted 256-byte value

Special Types

• einput: Input type for encrypted operations (bytes32)

Casting 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