Skip to content

README.md

Latest commit

 

History

History
182 lines (126 loc) · 6.37 KB

README.md

File metadata and controls

182 lines (126 loc) · 6.37 KB

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

Get started

Quickstart

The test suite offers a unified CLI for all operations:

cd test-suite/fhevm

# Preview the resolved bundle and boot plan
./fhevm-cli up --target latest-release --dry-run

# Boot the stack
./fhevm-cli up --target latest-release

# Deploy with threshold 2 out of 2 coprocessors (local multicoprocessor mode)
./fhevm-cli up --target latest-release --coprocessors 2 --threshold 2

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

# Run specific tests (works for both 1/1 and n/t topologies)
./fhevm-cli test input-proof
./fhevm-cli test user-decryption
./fhevm-cli test public-decrypt-http-mixed
./fhevm-cli test public-decrypt-http-ebool
./fhevm-cli test erc20

# Boot with a local coprocessor override (all services)
./fhevm-cli up --target latest-release --override coprocessor

# Boot with only specific runtime services built locally
./fhevm-cli up --target latest-release --override coprocessor:host-listener,tfhe-worker

# View logs
./fhevm-cli logs relayer

# Clean up
./fhevm-cli clean

For the local CLI entrypoint and architecture, see test-suite/fhevm/README.md and test-suite/fhevm/ARCHITECTURE.md.

Local overrides

To run one local component on top of an otherwise versioned stack, use --override:

# Override an entire group (builds all services locally)
./fhevm-cli up --target latest-release --override coprocessor


# Override specific services within a group (others pull from registry)
./fhevm-cli up --target latest-release --override coprocessor:host-listener,tfhe-worker

Supported override groups are coprocessor, kms-connector, gateway-contracts, host-contracts, and test-suite. Per-service override syntax is supported only for runtime groups: coprocessor, kms-connector, and test-suite. Local overrides always build release images.

When specifying individual services, use the short suffix after the group prefix (e.g., host-listener not coprocessor-host-listener). Services that share a Docker image are automatically co-selected (e.g., host-listener includes host-listener-poller).

Resuming a deployment

If a boot fails mid-way, you can resume from a specific step:

./fhevm-cli up --target latest-release --resume --from-step kms-connector

Resume steps (in order): preflight, resolve, generate, base, kms-signer, gateway-deploy, host-deploy, discover, regenerate, validate, coprocessor, kms-connector, bootstrap, relayer, test-suite.

When resuming:

  • Steps before the resume step are preserved
  • Steps from the resume step onward are regenerated and restarted under .fhevm

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 security@zama.ia rather than creating public issues.

Include:

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

Support

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.