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:

1. Open the Remix IDE by navigating to https://remix.ethereum.org.

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.

This tutorial guides you to start quickly with Zama’s Fully Homomorphic Encryption (FHE) technology for building confidential smart contracts.

What You’ll Learn

In about 20 minutes, you will:

• Build your first confidential ERC20 contract that leverages FHE.

• Deploy the contract on the Sepolia Network.

• Mint tokens and perform transactions in FHE.

• Build a frontend application for your contract.

Prerequisite

• A basic understanding of Solidity library and Ethereum.

• A certain amount of Sepolia ETH available.

  • If you don’t have enough ETH, use a Sepolia faucet to request free SepoliaETH for testing such as Alchemy Faucet or QuickNode Faucet.

What is Confidenetial ERC20

The contract that you will build with this tutorial is called ConfidentialERC20Mintable — a privacy-preserving ERC20 implementation that leverages FHE to keep balances and transactions confidential. To understand this contract, let’s first introduce the foundational concepts.

RC20

ERC20 is a widely used token standard on Ethereum that defines a set of rules for creating and managing fungible tokens. These tokens are efficient but lack privacy — balances and transactions are visible to anyone on the blockchain.

Confidential ERC20

Zama’s ConfidentialERC20 introduces privacy to ERC20 tokens by storing balances and transactions in an encrypted format using FHE.

The ConfidentialERC20 contract still supports standard ERC20 functions such as transfer, approve, transferFrom, balanceOf, and totalSupply but ensures these operations are processed securely with encrypted data.

To explore the implementation details of ConfidentialERC20, check out the Zama blog post.

Confidential ERC-20 Mintable

The contract that we will build in this tutorial is ConfidentialERC20Mintable . It's built on top of ConfidentialERC20 by adding secure minting capabilities. This allows authorized accounts to create new tokens, while maintaining the privacy guarantees of encrypted balances and transactions.

The ConfidentialERC20Mintable contract ensures:

• Enhanced privacy: Balances are stored as encrypted values (euint64), preventing public inspection of account balances.

• Secure transactions: Token transfers are processed securely, maintaining confidentiality of amounts.

• Owner visibility: Only account owners can decrypt and view their balances.

Next steps

Choose your path and get started:

• Remix Guide – Rapid in‐browser setup, great for learning and fast prototyping.

• Hardhat Guide – Full-fledged development environment, suitable for production.

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.

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.

• Architecture overview

• FHE on blockchain

• fhEVM components

• Encryption, decryption re-encryption and computation

References

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

• API function specifications

• Repositories

Supports

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

• Community forum

• Discord channel

• Telegram

Developers

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

• Contribute to fhEVM

• Follow the development roadmap

• See the latest test release note

• Request a feature

• Report a bug

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

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

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:

1. Reload your terminal configuration:

1. Run the Foundry installer:

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

To verify the installation, run:

Next Steps

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!

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:

# Mint 1000 tokens to your account by replacing recipient-address with your address
npx hardhat mint --to <recipient-address> --amount 1000 --network sepolia

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

Starting mint process...
Contract address: 0x1...26
Minting 1000 tokens to address: 0x1...26
Transaction submitted, waiting for confirmation...
✅ Mint transaction successful!
Transaction hash: 0x1...26
1000 tokens were minted to 0x1....26

Step 2: Verify total supply

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

# Check the total supply
npx hardhat totalSupply --network sepolia

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

✅ Retrieved total supply successfully
----------------------------------------
Total Supply: 1000 tokens
----------------------------------------

Step 3: Check your balance

To verify your account balance:

# Check your encrypted balance by replacing <private-key> with the private key of the account you want to check
# You can get the private key by running 'npx hardhat get-accounts --num-accounts 5'
npx hardhat balance --privatekey <private-key> --network sepolia

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

npx hardhat get-accounts --num-accounts 5

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

✅ Retrieved balance handle successfully
----------------------------------------
Address: 0x1..59
Balance: 1000 tokens
----------------------------------------

Step 4: Transfer tokens

To transfer confidential tokens to another account:

# Transfer tokens from your account to another address
# Replace <private-key> with the private key of the sending account
# Replace <recipient-address> with the destination wallet address
# Adjust the amount (100) as needed
npx hardhat transfer --privatekey <private-key> --to <recipient-address> --amount 100 --network sepolia

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

Starting transfer process...
Contract address: 0x1...26
From: 0x1...59
To: 0xA...4D
Amount: 100 tokens
Encrypting and proving in 9.4s
Verifying in 8.7s
Submitting transfer transaction...
Waiting for confirmation...
----------------------------------------
✅ Transfer successful!
Transaction hash: 0xc..13
Transferred 100 tokens to 0xA..4D

Step 5: Verify updated balances

After the transfer, you can check both accounts balances:

# Check sender's updated balance after transfer
# Replace <private-key> with the private key of the senders account
npx hardhat balance --privatekey <private-key> --network sepolia

# Check recipient's updated balance after receiving transfer
# Replace <private-key> with the private key of the recipient account
npx hardhat balance --privatekey <private-key> --network sepolia

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:

npx hardhat help <task-name>

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.

• Read the white paper: Understand the core technology behind fhEVM, including its cryptographic foundations and use cases.

• See more demos and tutorials: Expand your skills with hands-on demos and tutorials crafted to guide you through various real-world scenarios.

• Try out AI coding assistant: If you have a ChatGPT plus account, try out our custom ChatGPT model tailored for Solidity and fhEVM developers.

2. Tools

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

Smart contract development

• Hardhat Template: A developer-friendly starting point for building and testing smart contracts on fhEVM.

• fhEVM Contracts Library: Access standardized contracts for encrypted operations.

Frontend development

• React.js Template: Quickly develop FHE-compatible dApps using a clean React.js setup.

• Next.js Template: Build scalable, server-rendered dApps with FHE integration.

• Vue.js Template: Develop responsive and modular dApps with FHE support in Vue.js.

3. Community

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

• Discord: Join the community to get the latest update, have live discussion with fellow developers and Zama team.

• Community Forum: Get support on all technical questions related to fhEVM

• Zama Bounty Program: Participate to tackle challenges and earn rewards in cash.

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

Step 1: Clone the Hardhat template

1. Open the repository: Zama fhEVM 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.

To learn more about Hardhat, refer to the official Hardhat documentation.

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

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

Prerequisites

Before proceeding, ensure you have:

• A configured Hardhat project using the fhEVM Hardhat template. (See the previous section)

• Basic knowledge of Solidity and Hardhat testing. (See the Hardhat testing documentation)

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

For most development and demonstration scenarios, mocked mode is sufficient. However, for production-ready development and a real testing environment, you need to run your tests on a real network where the coprocessor is deployed for example Sepolia. Refer to the next section on how to deploy your contract on Sepolia test network.

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

Prerequisites

Before proceeding, ensure you have:

• A working Hardhat environment set up (see previous section).

• 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:

• Explore the full range of fhEVM capabilities in the Smart Contract section.

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

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

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.

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:

• The Zama Plugin installed is installed in the Remix IDE(see Step 1).

• Your wallet is connected to the Sepolia testnet(see Step 2).

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:

// SPDX-License-Identifier: BSD-3-Clause-Clear

pragma solidity ^0.8.24;

import "fhevm/lib/TFHE.sol";
import "fhevm/config/ZamaFHEVMConfig.sol";

contract MyConfidentialERC20 is SepoliaZamaFHEVMConfig {}

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:

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

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

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

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.

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:

• Deployment completed: You have successfully deployed the MyConfidentialERC20 contract (see Step 3).

• MetaMask wallet: Your MetaMask wallet is connected to the Sepolia testnet(see Step 2). You might want to prepare an additional wallet as the receiver to mock the transfer function.

• Zama Plugin in Remix: The Zama Plugin is installed and accessible in Remix (see Step 1).

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:

1. Use the balanceOf function again to check the updated balance of your original account (see the Step 5: Check your 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.

• Read the Whitepaper: Understand the core technology behind fhEVM, including its cryptographic foundations and use cases.

• See more demos and tutorials: Expand your skills with hands-on demos and tutorials crafted to guide you through various real-world scenarios.

• Try out AI coding assistant: If you have a chatGPT plus account, try out our custom ChatGPT model tailored for Solidity and fhEVM developers.

2. Tools

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

Smart contract development

• Hardhat Template: A developer-friendly starting point for building and testing smart contracts on fhEVM.

• fhEVM Contracts Library: Access standardized contracts for encrypted operations.

Frontend development

• React.js Template: Quickly develop FHE-compatible dApps using a clean React.js setup.

• Next.js Template: Build scalable, server-rendered dApps with FHE integration.

• Vue.js Template: Develop responsive and modular dApps with FHE support in Vue.js.

3. Community

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

• Discord: Join the community to get the latest update, have live discussion with fellow developers and Zama team.

• Community Forum: Get support on all technical questions related to fhEVM

• Zama Bounty Program: Participate to tackle challenges and earn rewards in cash.

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:

  • Alchemy Faucet

  • QuickNode Faucet

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):

cast wallet new-mnemonic

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:

npx hardhat get-accounts --num-accounts 5

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:

# Using npm
npm run deploy-sepolia

# Using yarn
yarn deploy-sepolia

# Using pnpm
pnpm deploy-sepolia

Step 4. Verify the deployment

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

MyConfidentialERC20: 0x1234........ABCD

You can verify this contract on Sepolia Etherscan by searching for the deployed address.

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

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

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:

✅ Instead, use the smallest appropriate type:

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:

✅ Than this one:

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:

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

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

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:

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:

Deploying to Ethereum Sepolia

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

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:

❌ Wrong order:

Available contracts

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.

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

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 to the 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 fulfillment 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 a 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 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.

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

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.

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";

Next steps

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

• Decryption in depth

• Re-encryption

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 access control list (ACL) overview.

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);
}

By understanding how to grant and verify permissions, you can effectively manage access to encrypted data in your fhEVM smart contracts. For additional context, see the ACL overview.

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

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:

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

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

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 explains how to implement conditional logic (if/else branching) when working with encrypted values in fhEVM. Unlike typical Solidity programming, working with Fully Homomorphic Encryption (FHE) requires specialized methods to handle conditions on encrypted data.

Overview

To facilitate conditional assignments, fhEVM provides the TFHE.select function, which acts as a ternary operator for encrypted values.

Using TFHE.select for conditional logic

The TFHE.select function enables branching logic by selecting one of two encrypted values based on an encrypted condition (ebool). It works as follows:

• condition: An encrypted boolean (ebool) resulting from a comparison.

• valueIfTrue: The encrypted value to return if the condition is true.

• valueIfFalse: The encrypted value to return if the condition is false.

Example: Auction Bidding Logic

Here's an example of using conditional logic to update the highest winning number in a guessing game:

How It Works

• Comparison:

  • The TFHE.lt function compares highestBid and bid, returning an ebool (isAbove) that indicates whether the new bid is higher.

• Selection:

  • The TFHE.select function updates highestBid to either the new bid or the previous highest bid, based on the encrypted condition isAbove.

• Permission Handling:

  • After updating highestBid, the contract reauthorizes itself to manipulate the updated ciphertext using TFHE.allowThis.

Key Considerations

• Value change behavior: Each time TFHE.select assigns a value, a new ciphertext is created, even if the underlying plaintext value remains unchanged. This behavior is inherent to FHE and ensures data confidentiality, but developers should account for it when designing their smart contracts.

• Gas consumption: Using TFHE.select and other encrypted operations incurs additional gas costs compared to traditional Solidity logic. Optimize your code to minimize unnecessary operations.

• Access control: Always use appropriate ACL functions (e.g., TFHE.allowThis, TFHE.allow) to ensure the updated ciphertexts are authorized for use in future computations or transactions.

Summary

• TFHE.select is a powerful tool for conditional logic on encrypted values.

• Encrypted booleans (ebool) and values maintain confidentiality, enabling privacy-preserving logic.

• Developers should account for gas costs and ciphertext behavior when designing conditional operations.

This guide explains how to estimate gas costs for Fully Homomorphic Encryption (FHE) operations in your smart contracts on Zama's fhEVM. Understanding gas consumption is critical for designing efficient confidential smart contracts.

Overview

FHE operations in fhEVM are computationally intensive, resulting in higher gas costs compared to standard Ethereum operations. This is due to the complex mathematical operations required to ensure privacy and security.

Types of gas in fhEVM

1. Native Gas:

   • Standard gas used for operations on the underlying EVM chain.

   • On fhEVM, native gas consumption is approximately 20% higher than in mocked environments.

2. FHEGas:

   • Represents gas consumed by FHE-specific computations.

   • A new synthetic kind of gas consumed by FHE-specific computations.

   • FHEGas is tracked in each block by the FHEGasLimit contract to prevent DDOS attacks.

   • If too many FHE operations are requested in the same block, the transaction will revert once the FHEGas block limit is reached.

   • FHEGas is consistent across both mocked and real fhEVM environments.

Note: Gas values provided are approximate and may vary based on network conditions, implementation details, and contract complexity.

Measuring gas consumption

To monitor gas usage during development, use the following tools:

• getFHEGasFromTxReceipt:

  • Extracts FHEGas consumption from a transaction receipt.

  • Works only in mocked fhEVM environments, but gives the exact same value as in non-mocked environments.

  • Import as: import { getFHEGasFromTxReceipt } from "../coprocessorUtils";

• .gasUsed from ethers.js transaction receipt:

  • Standard ethers.js transaction receipt property that returns the native gas used.

  • In mocked mode, this value underestimates real native gas usage by ~20%.

  • Works in both mocked and real fhEVM environments, as it's a standard Ethereum transaction property.

Example: gas measurement

The following code demonstrates how to measure both FHEGas and native gas during a transaction:

FHEGas limit

The current devnet has a FHEGas limit of 10,000,000 per block. Here's what you need to know:

• If you send a transaction that exceeds this limit or if the FHEGas block limit is exceeded, depending on other previous transaction in the same block:

  • The transaction will revert

  • Any native gas fees (but not FHEGas) will still be charged

  • You should do one of the following:

    • Reduce the number of FHE operations in your transaction

    • Wait for the next block when the FHEGas limit resets

    • Split your operations across multiple transactions

FHEGas costs for common operations

Boolean operations (ebool)

Unsigned integer operations

Gas costs increase with the bit-width of the encrypted integer type. Below are the detailed costs for various operations on encrypted types.

4-bit Encrypted Integers (euint4)

8-bit Encrypted integers (euint8)

16-bit Encrypted integers (euint16)

32-bit Encrypted Integers (euint32)

64-bit Encrypted integers (euint64)