Running a Ciphernode

This guide covers three methods to run a ciphernode, from easiest to most flexible. Choose the method that best fits your infrastructure.

Method 1: DappNode (Easiest)

DappNode provides a user-friendly interface for running a ciphernode with minimal configuration.

Installation

Open your DappNode UI (http://my.dappnode)
Search for "Enclave Ciphernode" (the current package name for the Interfold ciphernode) and install the package
The setup wizard will prompt you for:
- RPC_URL - WebSocket RPC endpoint (e.g., wss://ethereum-sepolia-rpc.publicnode.com)
- NETWORK - Network name (e.g., sepolia, mainnet)
- Contract addresses and deploy blocks
- Node role (ciphernode or aggregator)
- Optional: encryption password, network key, private key
Confirm and complete the installation
Check Packages → enclave-ciphernode → Logs to verify the node started

Configuration via Environment Variables

Variable	Description	Required
`RPC_URL`	WebSocket RPC endpoint	Yes
`NETWORK`	Network name (sepolia, mainnet, etc.)	No
`NODE_ROLE`	`ciphernode` or `aggregator`	No
`NODE_ADDRESS`	Your Ethereum address	No
`QUIC_PORT`	UDP port for P2P networking (default: 37173)	No
`ENCRYPTION_PASSWORD`	Password to encrypt local data	No
`NETWORK_PRIVATE_KEY`	libp2p network key (ed25519)	No
`PRIVATE_KEY`	Ethereum private key (for aggregator)	No
`PEERS`	Comma-separated peer multiaddresses	No

Method 2: Interfold CLI (Recommended)

The Interfold CLI provides the most control and is recommended for production deployments.

Install the CLI

# Quick install
curl -fsSL https://raw.githubusercontent.com/gnosisguild/enclave/main/install | bash
 
# Then install the CLI
enclaveup install

Initialize Configuration

enclave ciphernode setup

This creates ~/.config/enclave/enclave.config.yaml. You'll be prompted for a password to encrypt sensitive data.

Set Up Credentials

# Set encryption password (encrypts local keystore)
enclave password set
 
# Generate or set network keypair (for libp2p)
enclave net keypair generate
# Or import an existing key:
# enclave net keypair set --net-keypair 0x...
 
# Set your wallet private key (for on-chain transactions)
enclave wallet set --private-key 0xYourPrivateKey

Configure Your Node

Edit ~/.config/enclave/enclave.config.yaml:

node:
  address: '0xYourAddress'
  quic_port: 9091
  peers:
    - '/dnsaddr/bootstrap.enclave.gg'
  autonetkey: true
  autopassword: true
 
chains:
  - name: sepolia
    rpc_url: 'wss://ethereum-sepolia-rpc.publicnode.com'
    contracts:
      enclave:
        address: '0x450015E41E1F6b6AfaEbf598E32a8d02a368c0A0'
        deploy_block: 10395619
      ciphernode_registry:
        address: '0xc8D2880c59D5e807eFFDee3451fb0Aa97f6aefDA'
        deploy_block: 10395615
      bonding_registry:
        address: '0x1323d235Cd040d64D01d3C2adf084F9A16a675aE'
        deploy_block: 10395616

Start Your Node

# Start in foreground with verbose logging
enclave start -v
 
# Or use the node supervisor for multiple nodes
enclave nodes up --detach
enclave nodes ps          # Check status
enclave nodes logs cn1    # View logs
enclave nodes down        # Stop all nodes

CLI Commands Reference

Command	Description
`enclave start`	Start the node in foreground
`enclave start -v`	Start with INFO logging (`-vv`=DEBUG, `-vvv`=TRACE)
`enclave nodes up`	Start all configured nodes
`enclave nodes up --detach`	Start all nodes in background
`enclave nodes up --exclude x`	Start all nodes except `x`
`enclave nodes down`	Stop all nodes
`enclave nodes ps`	List running nodes and their status
`enclave nodes start <name>`	Start an individual node
`enclave nodes stop <name>`	Stop an individual node
`enclave nodes status <name>`	Check specific node status
`enclave nodes restart <name>`	Restart a specific node
`enclave nodes purge`	Purge all local ciphernode data
`enclave ciphernode status`	Show on-chain registration status
`enclave net get-peer-id`	Show your libp2p peer ID
`enclave wallet get`	Show your wallet address
`enclave rev`	Show the git SHA the CLI was built from
`enclave purge-all`	Wipe all local data (use with caution)
`enclave print-env`	Print contract addresses as env vars
`enclave print-env --vite`	Print env vars with `VITE_` prefix
`enclave print-env --chain x`	Print env vars for chain `x`
`enclave noir status`	Check ZK prover status
`enclave noir setup`	Install/update ZK prover components

Method 3: Docker

For containerized deployments, you can run the ciphernode Docker image directly.

Pull the Image

docker pull ghcr.io/gnosisguild/ciphernode:latest

Create Configuration

Create a config.yaml file:

node:
  address: '0xYourAddress'
  quic_port: 9091
  peers:
    - '/dnsaddr/bootstrap.enclave.gg'
  autonetkey: true
  autopassword: true
 
chains:
  - name: sepolia
    rpc_url: 'wss://ethereum-sepolia-rpc.publicnode.com'
    contracts:
      enclave:
        address: '0x450015E41E1F6b6AfaEbf598E32a8d02a368c0A0'
        deploy_block: 10395619
      ciphernode_registry:
        address: '0xc8D2880c59D5e807eFFDee3451fb0Aa97f6aefDA'
        deploy_block: 10395615
      bonding_registry:
        address: '0x1323d235Cd040d64D01d3C2adf084F9A16a675aE'
        deploy_block: 10395616

Run the Container

docker run -d \
  --name ciphernode \
  -v $(pwd)/config.yaml:/home/ciphernode/.config/enclave/config.yaml:ro \
  -v ciphernode-data:/home/ciphernode/.local/share/enclave \
  -p 9091:9091/udp \
  -e ENCRYPTION_PASSWORD=your_password \
  -e PRIVATE_KEY=0xYourPrivateKey \
  ghcr.io/gnosisguild/ciphernode:latest

Docker Compose

For a more manageable setup, use Docker Compose:

services:
  ciphernode:
    image: ghcr.io/gnosisguild/ciphernode:latest
    restart: unless-stopped
    volumes:
      - ./config.yaml:/home/ciphernode/.config/enclave/config.yaml:ro
      - ciphernode-data:/home/ciphernode/.local/share/enclave
    ports:
      - '9091:9091/udp'
    environment:
      ENCRYPTION_PASSWORD: ${ENCRYPTION_PASSWORD}
      PRIVATE_KEY: ${PRIVATE_KEY}
 
volumes:
  ciphernode-data:

View Logs

docker logs -f ciphernode

Configuration Reference

Node Configuration

Field	Description	Default
`address`	Your Ethereum address	Required
`quic_port`	UDP port for QUIC/libp2p networking	`9091`
`peers`	Bootstrap peer multiaddresses	`[]`
`autopassword`	Auto-generate password if missing	`false`
`autowallet`	Auto-load wallet from environment	`false`
`data_dir`	Override data directory	`~/.local/share/enclave`
`config_dir`	Override config directory	`~/.config/enclave`

Chain Configuration

Field	Description	Required
`name`	Chain identifier	Yes
`rpc_url`	WebSocket RPC endpoint	Yes
`contracts`	Contract addresses and deploy blocks	Yes

Contract Addresses

Each chain requires these contract addresses:

Contract	Description	Required for ciphernode
`enclave`	Main Interfold coordinator contract	Yes
`ciphernode_registry`	Tracks registered operators	Yes
`bonding_registry`	Manages bonds and tickets	Yes
`slashing_manager`	Manages slashing penalties	Yes
`e3_program`	E3 Program contract address	No
`fee_token`	Stablecoin address for fees and tickets	No

Each contract can be specified as a simple address string or with a deploy block for faster syncing:

contracts:
  enclave:
    address: '0x450015E41E1F6b6AfaEbf598E32a8d02a368c0A0'
    deploy_block: 10395619
  ciphernode_registry: '0xc8D2880c59D5e807eFFDee3451fb0Aa97f6aefDA'

Networking Requirements

Firewall Configuration

Open the following ports:

Port	Protocol	Purpose
`9091`	UDP	QUIC/libp2p P2P networking

Bootstrap Peers

Connect to the Interfold bootstrap network:

peers:
  - '/dnsaddr/bootstrap.enclave.gg'

Or specify individual peers:

peers:
  - '/dns4/node1.example.com/udp/9091/quic-v1'
  - '/ip4/192.168.1.100/udp/9091/quic-v1'

Data Directories

Directory	Contents
`~/.config/enclave/`	Configuration files, network keys
`~/.local/share/enclave/`	Databases, job data, keystores
`~/.local/share/enclave/jobs/`	Per-E3 secret shares and state

Back up these directories regularly. The jobs/ directory contains encrypted key shares for active E3s - losing this data while participating in a committee may result in slashing.

Monitoring

Log Levels

Control verbosity with the -v flag:

Flag	Level	Description
(none)	WARN	Warnings and errors only
`-v`	INFO	Normal operation logs
`-vv`	DEBUG	Detailed debug output
`-vvv`	TRACE	Full trace logging

Key Events to Watch

Event	Meaning
`E3Requested`	New computation request detected
`TicketGenerated`	Your sortition ticket was calculated
`CiphernodeSelected`	You were selected for a committee
`KeyshareCreated`	Your key share was generated
`PublicKeyAggregated`	Committee public key is ready
`CiphertextOutputPublished`	Time to generate decryption share
`DecryptionshareCreated`	Your decryption share was published
`PlaintextAggregated`	Final result is available

Next Steps

Once your node is running:

Register & License - Bond ENCL and register as an operator
Add Tickets - Purchase tickets to participate in sortition

Overview Registration & Licensing