README

Introduction

This repository provides a docker based setup to locally run an integration of Zama FHEVM and Zama KMS (Key Management System).

For overview of the system, architecture and details on individual components, refer to our documentation.

Main features

KMS can be configured to two modes:

• Centralized
• Threshold

Table of contents

• Introduction
• Main Features
• Get Started
  • Quickstart
  • Forcing Local Builds
  • Local Developer Optimizations
  • Resuming a Deployment
  • Deploying a Single Step
• Security Policy
  • Handling Sensitive Data
    • Environment Files
    • Development Environment
    • Common Sensitive Data
  • Reporting Security Issues
• Support

Get started

Quickstart

The test suite offers a unified CLI for all operations:

cd test-suite/fhevm

# Deploy the entire stack
./fhevm-cli deploy

# Deploy with local BuildKit cache (disables provenance attestations)
./fhevm-cli deploy --local

# Deploy with threshold 2 out of 2 coprocessors (local multicoprocessor mode)
./fhevm-cli deploy --coprocessors 2 --coprocessor-threshold 2

# Resume a failed deploy from a specific step (keeps existing containers/volumes)
./fhevm-cli deploy --resume kms-connector

# Deploy only a single step (useful for redeploying one service)
./fhevm-cli deploy --only coprocessor

# Run specific tests (works for both 1/1 and n/t topologies)
./fhevm-cli test input-proof
# Skip Hardhat compile when artifacts are already up to date
./fhevm-cli test input-proof --no-hardhat-compile
# Trivial
./fhevm-cli test user-decryption
# Trivial
./fhevm-cli test public-decrypt-http-mixed
./fhevm-cli test public-decrypt-http-ebool
./fhevm-cli test erc20

# Upgrade a specific service
./fhevm-cli upgrade coprocessor

# View logs
./fhevm-cli logs relayer

# Clean up
./fhevm-cli clean

WIP - Forcing Local Builds (--build)

⚠️ IMPORTANT: THIS FEATURE IS STILL A WORK IN PROGRESS! ⚠️ We are actively working to optimize caching for local machines and GitHub runners.

🚨 SECURITY NOTICE: The pre-built Docker images for the FHEVM stack are currently hosted in a private registry and are not publicly available for direct pulling. This is intentional for security reasons.

Therefore, for external developers or anyone setting up the stack for the first time without access to our private registry, using the --build option is the recommended and necessary way to get started:

./fhevm-cli deploy --build

This command instructs Docker Compose to:

1. Build the images locally using the Dockerfile and context specified in the respective docker-compose/*.yml files for each service. This process uses the source code available in your local checkout (or cloned sub-repositories).
2. Tag the newly built images with the versions specified in the fhevm-cli script.
3. Then, start the services using these freshly built local images.

Why --build is essential for external developers:

• Image Access: Since pre-built images are private, --build allows you to construct the necessary images from the publicly available source code.
• Local Modifications: If you have made local changes to any of the Dockerfiles or the build context of a service (e.g., you've cloned one of the sub-repositories like fhevm-contracts or fhevm-coprocessor into the expected relative paths and made changes), --build ensures these changes are incorporated.
• Ensuring Correct Setup: It guarantees that you are running with images built directly from the provided source, eliminating discrepancies that could arise from attempting to pull non-existent or inaccessible public images.

🚧 In summary: Until public images are made available, external users should always use ./fhevm-cli deploy --build to ensure a successful deployment.

Local developer optimizations

For faster local iteration, use --local to enable a local BuildKit cache (stored under .buildx-cache/) and disable default provenance attestations:

./fhevm-cli deploy --local

When running tests and you know your Hardhat artifacts are already up to date, you can skip compilation:

./fhevm-cli test input-proof --no-hardhat-compile

Resuming a deployment

If a deploy fails mid-way, you can resume from a specific step without tearing down containers or regenerating .env files:

./fhevm-cli deploy --resume kms-connector

Resume steps (in order): minio, core, kms-signer, database, host-node, gateway-node, coprocessor, kms-connector, gateway-mocked-payment, gateway-sc, host-sc, relayer, test-suite.

When resuming:

• Services before the resume step are preserved (containers + volumes kept)
• Services from the resume step onwards are torn down and redeployed

Deploying a single step

To redeploy only a single service without touching others:

./fhevm-cli deploy --only coprocessor

This is useful when you need to restart or rebuild just one component. Only the specified step's containers are torn down and redeployed; all other services remain untouched.

You can combine --only or --resume with other flags:

# Redeploy only gateway-sc with a local build
./fhevm-cli deploy --only gateway-sc --build --local

Security policy

Handling sensitive data

This document outlines security best practices for the FHEVM project, particularly regarding the handling of sensitive configuration data.

Environment files

Our repository contains example environment files env/staging that include sensitive values like private keys, mnemonics, and API keys. These values are for testing purposes only and should never be used in production environments.

For production deployments:

• Do not use the same keys, passwords, or mnemonics that appear in the example files
• Do not commit actual production secrets to any repository
• Do use a proper secrets management solution:
  • Environment variables managed by your deployment platform
  • HashiCorp Vault or similar secrets management service
  • AWS Secrets Manager, GCP Secret Manager, or Azure Key Vault
  • Kubernetes Secrets (with proper encryption)

Example of replacing sensitive data in production:

# Replace test mnemonic with environment variable reference
# TEST: MNEMONIC=coyote sketch defense hover finger envelope celery urge panther venue verb cheese
MNEMONIC=${PRODUCTION_MNEMONIC}

# Replace test private key with key stored in a secure vault
# TEST: TX_SENDER_PRIVATE_KEY=0x8f82b3f482c19a95ac29c82cf048c076ed0de2530c64a73f2d2d7d1e64b5cc6e
TX_SENDER_PRIVATE_KEY=${SECURE_PRIVATE_KEY}

Development environment

When developing locally:

• Use .env.local files (added to .gitignore) for your personal secrets
• Rotate keys regularly, especially if used for shared development environments
• Consider using environment-specific configuration files (dev, staging, prod)
• Use fake/test data for local development whenever possible

Common sensitive data

The following values should NEVER be committed to repositories:

• Private keys
• Mnemonics
• API keys
• Database credentials
• JWT secrets

Reporting security issues

Please report security vulnerabilities to [email protected] rather than creating public issues.

Include:

• Description of the vulnerability
• Steps to reproduce
• Potential impact
• Suggested mitigation (if any)

Support

🌟 If you find this project helpful or interesting, please consider giving it a star on GitHub! Your support helps to grow the community and motivates further development.