Run a Ciphernode

This page shows three ways to install and start a ciphernode: DAppNode, the interfold CLI, and Docker. It is for operators who have a host that meets the requirements. At the end, the node runs, syncs the contract history, and waits for registration. For a release change, follow Upgrades.

Before you start

Prepare these items before you install the node:

• A host that meets the requirements, with the QUIC UDP port open.
• An Ethereum WebSocket endpoint that keeps the full log history. Test it on RPC Endpoints first.
• An Avail HTTP endpoint for data availability. The examples on this page use the defaults of the DAppNode package.
• An operator key: a dedicated Ethereum private key for this node. The node signs ticket submissions and release acknowledgments with it, so it needs ETH for gas.
• A bond owner wallet or Safe that holds the FOLD and the ticket collateral. A wallet that is separate from the operator key is recommended. See Registration & Bonding.

Use a fixed release version on an operator node. Do not use a moving version such as the latest Docker tag.

Choose a method

The CLI and Docker methods use the same configuration file. Write it first, as shown in the next section. The DAppNode packages write their own file from the deployment manifest and the package Config.

Write the configuration file

The configuration file sets the node profile and one entry for each chain. Copy the example for your network and replace the placeholders. The addresses come from the deployment manifest. See Contract addresses.

node:
  network: mainnet
  quic_port: 9091
 
chains:
  - name: mainnet
    chain_id: 1
    rpc_url: 'wss://YOUR_MAINNET_ENDPOINT'
    data_availability:
      mode: avail
      rpc_url: 'https://avail-rpc.publicnode.com/'
    contracts:
      interfold:
        address: '0x28cF63B459e6218C69EA97ea7D90541cf648c715'
        deploy_block: 25786382
      ciphernode_registry:
        address: '0xC927A5B2d8F68697bC28C0670df05178c93df2d7'
        deploy_block: 25786378
      bonding_registry:
        address: '0x0ec90465095C21830BEcED07e032809A2Bd2915F'
        deploy_block: 25473398
      slashing_manager:
        address: '0x753109Ee36Dc65cC178875AddA30C6433e5bEEe4'
        deploy_block: 25998899
      fee_token:
        address: '0xdC035D45d973E3EC169d2276DDab16f1e407384F'
        deploy_block: 20663730

node:
  network: sepolia
  quic_port: 9091
 
chains:
  - name: sepolia
    chain_id: 11155111
    rpc_url: 'wss://YOUR_SEPOLIA_ENDPOINT'
    data_availability:
      mode: avail
      rpc_url: 'https://turing-rpc.avail.so/rpc'
    contracts:
      interfold:
        address: '0xb35EE9ed8BE5967daabBA8c2e817C52D0b57ac26'
        deploy_block: 12050035
      ciphernode_registry:
        address: '0x895392D5782E78768A35B1aDfc5b0BD1faB259e4'
        deploy_block: 12050030
      bonding_registry:
        address: '0x8f42eD45556bC8fF8949c37c7644Af9Cf321108F'
        deploy_block: 12050022
      slashing_manager:
        address: '0xa82F589B29BD5c2392b7127Cba8727Af2bbEd84D'
        deploy_block: 12050027
      fee_token:
        address: '0xE2e534F7Cb95777eD870CDCaCb80B1E9E2aD555B'
        deploy_block: 11856062
      faucet:
        address: '0x1B4340A65BB669267BF5DE37385B139987C3F09c'
        deploy_block: 11873271

While Avail Turing is down, the Sepolia CRISP program uses a mock data-availability verifier. Nodes that serve it use data_availability: { mode: mock_http, rpc_url: <CRISP server>/availability } instead of the Avail block above.

The node applies these rules when it loads the file:

• Every enabled chain must belong to the node.network profile. chain_id: 1 belongs to mainnet and chain_id: 11155111 belongs to sepolia. One node serves one network. To keep an entry for another network in the file, set enabled: false on it.
• Each enabled entry must be a different chain. The node refuses to start when two enabled entries resolve to the same chain ID.
• Each contract must have a nonzero deploy_block when rpc_url is not a local address. Otherwise, startup stops with Misconfiguration: Attempted to query historical events from genesis on a non-local node.
• A ciphernode needs interfold, ciphernode_registry, bonding_registry, and a data_availability entry on each enabled chain. The node refuses to start without them.
• A ciphernode uses the SlashingManager that the interfold contract names on each enabled chain. It refuses to start when it cannot read that address. A configured slashing_manager that differs only causes a warning.
• Each $NAME or ${NAME} in the file is replaced with the value of that environment variable. Use this to keep an API key out of the file, for example rpc_url: 'wss://example.invalid/v2/${RPC_API_KEY}'.

Keep the chain name as mainnet or sepolia. The interfold config check command matches chains to the manifest by name, and it skips other names. Also set chain_id, because config check compares it with the manifest. The command does not query the endpoint.

Main configuration keys

The keys below matter most on an operator node. The Configuration Reference lists every node key, and Chain keys lists every chain key.

The defaults of three confirmations and a 7-second poll interval also apply when rpc_url uses localhost or 127.0.0.1, because that URL can be a proxy to a live chain. Set ingestion_confirmations: 0 and rpc_poll_interval_ms: 250 only on a single-process development chain such as Anvil. Do not set them on mainnet or Sepolia.

The node cannot undo a log that it applied, so a chain reorganization deeper than ingestion_confirmations can leave the node out of step with the chain. Each confirmation also delays every duty by about 12 seconds. The default leaves room for a sortition ticket in the 10-minute mainnet window and the 3-minute Sepolia window. The node logs the value that it uses for each chain at startup.

The autonetkey key has no effect in this release. The node derives its libp2p key from the wallet key.

Start the node

{
  "password": "<strong encryption password>",
  "private_key": "0x<64 hex characters>"
}

curl -fsSL https://raw.githubusercontent.com/theinterfold/interfold/main/install | bash -s -- --version v0.19.0
interfold --version

interfold password set

interfold wallet set

interfold config check

interfold start -v

export CIPHERNODE_IMAGE='ghcr.io/theinterfold/ciphernode:0.19.0'
docker pull "$CIPHERNODE_IMAGE"

docker volume create ciphernode-data

umask 077
install -m 600 /dev/null secrets.json
${EDITOR:-vi} secrets.json

{
  "password": "<strong encryption password>",
  "private_key": "0x<64 hex characters>"
}

docker run -d \
  --name ciphernode \
  --restart unless-stopped \
  --stop-timeout 65 \
  -v ciphernode-data:/home/ciphernode/.local/share/interfold \
  -v "$PWD/config.yaml":/home/ciphernode/.config/interfold/config.yaml:ro \
  -v "$PWD/secrets.json":/run/secrets/secrets.json:ro \
  -p 9091:9091/udp \
  "$CIPHERNODE_IMAGE"

docker logs -f ciphernode

services:
  ciphernode:
    image: ${CIPHERNODE_IMAGE:?set CIPHERNODE_IMAGE to a versioned release tag}
    restart: unless-stopped
    stop_grace_period: 65s
    volumes:
      - ciphernode-data:/home/ciphernode/.local/share/interfold
      - ./config.yaml:/home/ciphernode/.config/interfold/config.yaml:ro
    secrets:
      - source: ciphernode_credentials
        target: secrets.json
    ports:
      - '9091:9091/udp'
 
secrets:
  ciphernode_credentials:
    file: ./secrets.json
 
volumes:
  ciphernode-data:

Check the configuration

Contract addresses change when the protocol is deployed again. A node that points at an old address syncs nothing and reports no error. Before the first start, and after each deployment notice, compare your configuration with the published deployment manifest:

interfold config check

The command downloads manifest.json from the latest GitHub release and compares each chain entry. Example output for a current Sepolia entry:

Deployment manifest: release v0.20.0-dev.3
sepolia: up to date
  note  sepolia is a mock deployment - proofs are accepted without being verified

Example output for a stale entry:

sepolia:
  STALE interfold: config has 0xc5DD9418…, published is 0xb35EE9ed…
  warn  ciphernode_registry: deploy_block 11855915, published is 12050030
  note  sepolia is a mock deployment - proofs are accepted without being verified

The command exits with a non-zero status when a line is STALE. You can use it as a gate before a restart in a process manager or a CI job. Use --chain <name> to check one chain. Use --manifest-url <url> to check against a specific manifest file.

Watch the node

The -v flag sets the log level. The flags are global, so they work with every command.

Logs at -vv and higher can contain the endpoint URL. If the URL contains an API key, remove it before you share logs.

These events show the progress of an E3 in the node log:

The node writes one heartbeat file for each chain after every successful read of the chain head: chain-<chain ID>.heartbeat in ingestion/ in the node data directory, for example data/_default/ingestion/chain-1.heartbeat. The file holds key=value lines: chain_id, head, cursor, polled_at, and progressed_at (Unix seconds). A monitoring script can read these files, and they need no RPC request. The DAppNode health check fails when polled_at is older than 120 seconds, or when progressed_at is older than 10 minutes.

When the node runs, some commands run inside the node through the local control port: ciphernode status, wallet get, net get-peer-id, config get, rev, print-env --chain <name>, noir status, and events query. See Commands that run inside a running node. For a visual view, turn on the node dashboard.

Stop and restart

On SIGINT or SIGTERM, the node stops its actors and writes its event log and store to disk. This shutdown has a limit of 60 seconds. Set the stop timeout of your process manager above 60 seconds. The DAppNode package and the examples on this page use 65 seconds.

The node locks its data directory (interfold.lock) while it runs. A second node process with the same data directory does not start.

After a crash, a restore, or a binary upgrade, check the stored state before you start the node. Do these steps with the node stopped:

interfold node validate

docker run --rm \
  -v ciphernode-data:/home/ciphernode/.local/share/interfold \
  -v "$PWD/config.yaml":/home/ciphernode/.config/interfold/config.yaml:ro \
  "$CIPHERNODE_IMAGE" \
  node validate --config /home/ciphernode/.config/interfold/config.yaml

interfold node validate --repair

When the node cannot write or flush its event log, it stops so that the process manager can restart it. Repeated storage failures are an infrastructure problem. Stop the node, keep a copy of the data, and run the validation before the next start. When a release changes the storage schema, see Upgrades.

Data and backups

A CLI node keeps all state in a .interfold directory next to its configuration file. The password file is in .interfold/config/<name>/. The key store and the event log are in .interfold/data/<name>/. Run interfold config get db_file to print the path on your host. The requirements page lists the contents. The Docker image keeps the state on its volume. See Docker state.

Back up the complete .interfold directory as one unit, while the node is stopped. The event log refers to files in its event-blobs-v1 directory. Do not delete those files to free space.

Docker state

Where the node stores its state

The image entrypoint sets E3_CONFIG_DIR=/home/ciphernode/.local/share/interfold/config and E3_DATA_DIR=/home/ciphernode/.local/share/interfold/data, unless the container sets them. Thus the node keeps all of its state on the volume at /home/ciphernode/.local/share/interfold:

A restart, a new container, and a new image all keep this state. docker rm does not delete a named volume.

These variables override config.yaml, so the entrypoint never uses them to move state that exists. If config.yaml sets config_dir, data_dir, key_file, or db_file, the node uses that location. If a key file or database exists at /home/ciphernode/.config/interfold/.interfold, for example on a volume that is mounted at /home/ciphernode/.config/interfold, the node keeps using it. If state exists both there and on the volume, the container does not start. Keep only the state that the node last used, and start the container again. You can also set your own E3_CONFIG_DIR and E3_DATA_DIR for the container.

In these cases the node does not use the entrypoint's variables, so run other interfold commands through the entrypoint, which chooses the same location. For example, run docker exec ciphernode ciphernode-entrypoint.sh wallet get --config /home/ciphernode/.config/interfold/config.yaml. The command in Validate the state also runs through the entrypoint.

Move state from an earlier image

Earlier images did not set these variables. A node that started from such an image, without a volume at /home/ciphernode/.config/interfold, keeps its state inside the container, in /home/ciphernode/.config/interfold/.interfold. That directory is not on the volume. When you remove or recreate that container, you lose the key file, the key/value store, and the event log. The key/value store holds the key shares of the node, and the chain cannot restore them.

Do this procedure one time for each node, when the node serves no active E3. An earlier image uses storage schema 7 or earlier, and v0.19.0 uses schema 8. The procedure therefore resets the state after the copy. The reset keeps the operator key and the libp2p keypair. See Reset node state.

The commands use the container name ciphernode and the volume name ciphernode-data. For Docker Compose, use the names that docker ps -a and docker volume ls show. Each one-off container runs the new image through its entrypoint, with the same volume and configuration file:

new_image() {
  docker run --rm \
    -v ciphernode-data:/home/ciphernode/.local/share/interfold \
    -v "$PWD/config.yaml":/home/ciphernode/.config/interfold/config.yaml:ro \
    "$CIPHERNODE_IMAGE" \
    "$@" --config /home/ciphernode/.config/interfold/config.yaml
}

1. Set the image of the new release, and pull it. The helper and the later steps use this variable.

   export CIPHERNODE_IMAGE='ghcr.io/theinterfold/ciphernode:0.19.0'
   docker pull "$CIPHERNODE_IMAGE"

2. Find out how the old container starts, and whether a stop removes it:

   docker inspect -f '{{json .Config.Entrypoint}} {{.HostConfig.AutoRemove}}' ciphernode

   Continue only if the output is ["interfold"] false, or one path that ends with /interfold followed by false. For all other output, do not stop the container, and contact the protocol team:

   • ["ciphernode-entrypoint.sh"] is the entrypoint of the earlier image. At each start, it sets the password again, and interfold password set refuses a key file that exists. Such a container cannot start again after a stop.
   • true means that the container started with --rm. A stop removes the container and the state inside it.

3. Make sure that no E3 is active on the network. The output must be 0. Get the Interfold address from Contracts and addresses.

   cast call <Interfold> "activeE3Count()(uint256)" --rpc-url <RPC_URL>

4. Record the operator address and the peer ID from the old container, while it runs. If a command fails or prints no value, stop and contact the protocol team.

   docker exec ciphernode interfold wallet get --config /home/ciphernode/.config/interfold/config.yaml
   docker exec ciphernode interfold net get-peer-id --config /home/ciphernode/.config/interfold/config.yaml

5. Make sure that the volume has no data or config directory. If the output shows either name, stop and contact the protocol team.

   docker run --rm \
     -v ciphernode-data:/home/ciphernode/.local/share/interfold \
     --entrypoint ls \
     "$CIPHERNODE_IMAGE" \
     -A /home/ciphernode/.local/share/interfold

6. Stop the old container. Do not remove it.

   docker stop --time 65 ciphernode

7. Copy the data and config directories from the old container to the volume. docker cp sends each directory as a tar stream, so the key file does not go to the host disk.

   for dir in data config; do
     docker cp "ciphernode:/home/ciphernode/.config/interfold/.interfold/$dir" - |
       docker run --rm -i \
         -v ciphernode-data:/home/ciphernode/.local/share/interfold \
         --entrypoint tar \
         "$CIPHERNODE_IMAGE" \
         -xf - -C /home/ciphernode/.local/share/interfold
   done

8. Make sure that the copy is complete. The output must show key, db, and log.0. If a name is missing, stop and contact the protocol team.

   docker run --rm \
     -v ciphernode-data:/home/ciphernode/.local/share/interfold \
     --entrypoint ls \
     "$CIPHERNODE_IMAGE" \
     /home/ciphernode/.local/share/interfold/config/_default \
     /home/ciphernode/.local/share/interfold/data/_default

9. Reset the state:

   new_image node reset-data --yes

   The output must end with this line. If it says No identity was present, stop and contact the protocol team.

   The operator key and libp2p identity were preserved. Verify with: interfold wallet get --name _default

   If the command refuses, use the cases in If the command refuses. Add --allow-active-e3s only in the last case. In each other case, start the old container again:

   started=$(date -u +%Y-%m-%dT%H:%M:%SZ)
   docker start ciphernode

   Use docker start also for Docker Compose. docker compose up removes the old container, which holds the state that the node uses. If the container does not start, stop and contact the protocol team, and keep the copy on the volume.

   The log from before the stop also holds the release lines, so read only the log since the start. When it shows Ciphernode release is accepted or Acknowledging ciphernode release, remove the copy from the volume. Then do what the case tells you.

   docker logs --since "$started" ciphernode

   docker run --rm \
     -v ciphernode-data:/home/ciphernode/.local/share/interfold \
     --entrypoint rm \
     "$CIPHERNODE_IMAGE" \
     -rf /home/ciphernode/.local/share/interfold/data /home/ciphernode/.local/share/interfold/config

10. Run these commands. The address and the peer ID must be equal to the values from step 4. If they differ, or a command fails, stop and contact the protocol team.

    new_image wallet get
    new_image net get-peer-id

11. Validate the state. Continue only if the report shows empty store will be initialized and ends with VALIDATION PASSED — state is intact and consistent. Otherwise, do not start the new image. Keep the old container and the volume, and contact the protocol team.

    new_image node validate

12. Start the new image. For docker run, rename the old container first, then use the command in Start the container:

    docker rename ciphernode ciphernode-old

    For Docker Compose, make sure that CIPHERNODE_IMAGE names the new image. Remove the entrypoint: line from the service: step 2 required the old container to start interfold directly, but the new image must start through its own entrypoint, which uses the volume. Then run docker compose up -d. This command replaces the old container.

13. Make sure that the log shows Ciphernode release is accepted, and that this command shows the operator address from step 4:

    docker exec ciphernode ciphernode-entrypoint.sh wallet get --config /home/ciphernode/.config/interfold/config.yaml

14. For docker run, remove the old container only after step 13 succeeds.

Networking

Open the QUIC UDP port (default 9091) for inbound traffic. Do not open the control port 50505. Requirements lists all ports.

When peers is empty, the node dials the DNS bootstrap address of its network profile. Mainnet uses /dnsaddr/bootstrap.interfold.network. Sepolia uses /dnsaddr/bootstrap-sepolia.interfold.network. The profile also sets a network ID that every Interfold libp2p protocol uses. A mainnet node and a Sepolia node therefore cannot join the same network, also when a peer address is wrong.

To dial specific peers, list them in the configuration:

node:
  network: mainnet
  peers:
    - '/dns4/node1.example.com/udp/9091/quic-v1'
    - '/ip4/192.0.2.10/udp/9091/quic-v1'

You can also add a peer at start with interfold start --peer <multiaddr>. A mainnet profile refuses the Sepolia bootstrap address. A Sepolia profile replaces the mainnet bootstrap address with the Sepolia one.

Run a bootstrap node

A bootstrap node is a peer that other nodes dial first to find each other. Start it with interfold start --bootstrap. The node reads the events of the Interfold contract and joins the network like a full node, but it does not serve on committees, generate proofs, sign votes, or send transactions. It therefore does not need the memory of the prover, and its address needs no ETH. When it starts, it fetches the history of open E3s from its peers like a full node. If no peer can serve that history, it starts without it, so it can start when no other node is running. Its request router expects no protocol recipients and keeps no deferred protocol backlog.

It needs the same setup as a full node: a configuration with the network profile and the chains, a password, and a wallet key. The wallet key sets the node address and the libp2p peer ID, so use a key that no other node uses. The key does not have to belong to a registered operator. Open its QUIC UDP port, and add its address to the peers of the other nodes, for example /dns4/bootstrap.example.com/udp/9091/quic-v1.

Give a bootstrap node a data directory of its own. On its first start, a node records its role (full or bootstrap) in its data directory. A node does not start on a data directory that a node of the other role used. Releases without bootstrap mode do not check the role, so do not start an older release on the data directory of a bootstrap node. To change the role of a node, stop the node and run interfold node reset-data, which keeps the wallet key.

Deferred protocol events

A full node can receive an E3 event before the actor that consumes it starts. The request router keeps these events in order for recipients declared by the installed extensions. Each E3 has a limit of 4,096 deferred entries and 1 GiB of accounted bytes. The router has a shared limit of 16,384 entries and 3 GiB. Each recipient copy counts toward both limits, including shared payload bytes.

Each entry reserves its encoded bytes, nested inline storage, and 64 bytes per allocation candidate. The reservations cover strings, byte buffers, collections, their elements, and shared payload fields. Large contiguous buffers add constant allocation overhead. They have no extra charge per payload byte. Shared bytes retain no spare capacity, and deferred copies compact collections inside shared keys and threshold shares. Each entry also reserves twice its inline event size for queue capacity.

These limits cover four concurrent E3s with the largest supported committee (N=19, H=14) and the secure 8192-degree preset. The slashing recipients start at committee finalization. Keyshare and public-key recipients start at local selection. Only the plaintext recipient retains the complete local DKG history until ciphertext output arrives.

The late-recipient allowance is 1,536 records and 640 MiB per E3. It includes the C1–C3 witnesses, the complete request payloads retained by computation failures, C4 inputs, peer shares, and document envelopes. Four such histories use 2.5 GiB, leaving 512 MiB of margin below the shared byte limit.

The 3 GiB ceiling includes allocation reservations, but it does not measure exact resident memory. In an 8 GiB memory budget, allow another 1.5 GiB for fragmentation, freed storage, and an in-flight event. The remaining 3.5 GiB covers other actors, the process baseline, and the system. The router memory regression checks this allowance with contiguous and separately allocated small payloads. These are buffer allowances, not total node memory requirements or limits on incoming-event decoding. Proof workers need a separate allowance. See Requirements for node sizing.

If a limit is exceeded, the router logs Deferred delivery failed at ERROR and clears the affected recipient's deferred queue. It retains the failure record until E3 teardown or restart and stops adding events to that queue. Other E3s and live delivery continue. The affected E3 can fail at its existing deadline. Deferred queues remain in memory only, so a restart does not restore their pre-checkpoint events.

Command reference

The commands on this page are start, config check, password set, wallet set, node validate, and ciphernode setup. Global flags work with every command: --config <path>, --name <profile>, -v, and -q. The CLI Reference lists every command and flag. For a schema change that needs interfold node reset-data, see Upgrades.

Next steps