Migrate a Node

This page moves a ciphernode to a different server without a change of identity. It is for operators who replace a host. At the end, the new server runs the node with the same operator address, peer ID, and event history. The old server is stopped.

The migration needs no on-chain transaction. The bond, the tickets, and the registration belong to the operator address, and the address does not change. To install a new release, read Upgrades. If you do both, migrate first, verify the identity, and then upgrade.

What identifies a node

A ciphernode keeps its identity and its state in two directories. By default, both directories are in a .interfold directory next to the configuration file.

interfold.config.yaml

- - key
- - log.0
  - log.<chain_id>
  - ciphernode.jsonl
  - interfold.lock

<node> is the node name. The default node, which the node key configures, is _default.

Item	Path	Contents	If it is missing
Key file	`.interfold/config/<node>/key`	The encryption password. The node derives the encryption key from it.	The node cannot decrypt its keys. `interfold password set` with the same password makes the file again.
Key/value store	`.interfold/data/<node>/db`	The encrypted operator key, the encrypted libp2p keypair, and protocol state.	The identity is lost, unless you have another copy of the operator private key.
Event log	`.interfold/data/<node>/log.<n>`	The durable events: `log.0` and one file for each chain ID.	The key/value store and the event log no longer match.
Configuration file	`interfold.config.yaml`	Chains, contract addresses, peers, and ports.	The node cannot start. You can write the file again.

The other files are not part of the identity:

ciphernode.jsonl is the operational log. The node writes it but never reads it.
interfold.lock is the process lock. The operating system releases it when the process exits.
.interfold/noir holds the prover files. At startup, the node downloads them when they are missing.

The paths change when the configuration sets config_dir, data_dir, key_file, db_file, or log_file. See Storage paths. To see the paths that the node uses, run interfold config get key_file, interfold config get db_file, and interfold config get log_file with --name <node>. The log file path is the base name. The real event-log files add an index, for example log.0.

Why both directories must move together

Both keys are in the key/value store, encrypted with the key from the key file. A copy of only the data directory fails with Failed to get metadata for keyfile. A copy of only the configuration directory has no keys to decrypt.

The libp2p keypair comes from the operator private key. interfold wallet set derives both keys from the same private key, so the peer ID follows the operator key.

Before you start

Know the encryption password. The key file contains it. Without the password, a lost key file cannot be made again.
Know how the operator key was made. No CLI command exports a private key. If the node generated its own key (autowallet), the archive of this procedure is the only copy of the identity.
Install the same release on the new server. Use interfold --version on both servers.
Keep the old data. Do not delete the data on the old server until the new node runs correctly.

⚠️

Two servers that run the same node at the same time put the position at risk. See Do not run both servers.

Move the node

Wait for active work to finish

Make sure that the node has no active E3. The Updates view of the local dashboard shows the number of active E3s.

Stop the old node

Stop the process with the tool that supervises it, for example systemctl stop <unit>, pm2 stop <node>, or docker stop <container>.

Do not copy the key/value store while a node writes to it. A copy from a running node can open without an error and still be inconsistent.

Confirm that the node is stopped

Run interfold node validate --name <node>.

The command takes the same process lock as the node. While a node runs, it fails with another interfold instance is already running for node '<node>'.

Record the identity

Run these commands and write down the results:

interfold wallet get --name <node>
interfold net get-peer-id --name <node>
interfold node validate --name <node>

The validation report includes a line such as read 1234 event(s) across 2 aggregate(s). Use the event count as a second check after the move.

Make an archive

Go to the directory that contains interfold.config.yaml. Then run:

tar czpf node-migration.tgz .interfold/config .interfold/data interfold.config.yaml

The p flag keeps the file permissions. The key file must stay readable only by its owner.

Transfer the archive

Copy the archive to the new server over a channel that you trust, for example scp.

The archive contains the encrypted operator key and the password that decrypts it.

Unpack the archive on the new server

Install the same Interfold release. Then unpack the archive in the node directory:

tar xzpf node-migration.tgz

Keep interfold.config.yaml next to the .interfold directory, so that the node finds its directories.

Verify before you start

Run the same commands on the new server:

interfold wallet get --name <node>
interfold net get-peer-id --name <node>
interfold node validate --name <node>

The address, the peer ID, and the event count must be equal to the values that you recorded. The report must end with VALIDATION PASSED. Do not start the node if a value is different.

Update the network settings

Open the QUIC port (quic_port, UDP) in the firewall of the new server.

If other nodes dial this node by address, update their peer lists. The peer ID stays the same, but a new IP address or port needs a new multiaddr.

Start the new node

Start the node the same way as on the old server.

Run interfold ciphernode status and make sure that Active is true.

Decommission the old server

Keep the old node stopped. Delete its data only after the new node works correctly.

Do not run both servers

⚠️

Two processes with one operator key sign conflicting protocol messages and transactions for the same operator. The process lock protects only one data directory on one host, so it cannot stop a second server. Peers can reject the conflicting messages or accuse the operator, and the E3 can fail. A confirmed accusation can slash the bond and the tickets of the position when the slash policy is enabled.

Keep the old node stopped from the first step of the procedure until you decommission it. Make sure that no supervisor, for example a service manager or a container restart policy, starts it again.

Docker and DAppNode

For a Docker installation, the .interfold directory is next to the configuration file in the mounted volume. A node that started from an image before 0.19.0 without a volume at /home/ciphernode/.config/interfold keeps its state inside the container instead. Copy that state onto the volume first, as Move state from an earlier image describes, because removing the container deletes it. Then stop the container and copy the complete volume. The Docker entrypoint sets the password and the operator key from the credentials secret when the volume has none. Use the same credentials secret on the new server.

The DAppNode package keeps its configuration and its .interfold directory in the /data volume. Its backup includes the configuration, encryption password, and durable node state. Downloaded circuits and prover caches are excluded. Use the package for the same network on the new server.

Migrate and upgrade together

A release that changes the storage schema needs a state reset, which deletes the event history that a migration keeps. Do the steps in this order:

Migrate the node with the procedure on this page.
Verify the address and the peer ID on the new server.
Follow the upgrade procedure, including Reset node state if the release needs it.

The verification before the reset proves that the identity arrived complete. interfold node reset-data keeps the identity, so the node keeps its bond and peer ID. The node then syncs again from the deploy_block of each contract.

Next steps

Upgrades

Install a new release and reset the state when a release needs it.

Maintain Troubleshooting

Check peers and connectivity after the node starts on the new server.

Fix Running a ciphernode

Installation methods, configuration, and data directories.

Set up

Upgrades Exits, Rewards, and Slashing