Run an Animica node

Why run one

The public endpoint at rpc.animica.org is convenient, but it is one node operated by the project, it is rate-limited, and trusting it means trusting whoever runs it to report state honestly. Running your own node gives you an independent view of the chain: you verify every signature and every block yourself, you are not affected by public rate limits or outages, and you can point wallets, the explorer software, a pool, or an AICF worker at 127.0.0.1:8545. Solo mining on port 3334 of the pool does not require a node, but mining directly with your own block templates does. Exchanges, payment processors and anyone tracking balances should run a node rather than rely on the hosted RPC, not least because the emission-changing forks silently mis-credit balances on outdated software.

Install and start

    # Python 3.10+ required
python3 -m pip install --upgrade animica

# Select the network once (mainnet is the default anyway)
animica network set mainnet

# Start the node (uses ops/docker/docker-compose.mainnet.yml under the hood)
animica node up

# Check sync state, head height and peers
animica node status

# Diagnose common misconfigurations
animica node doctor
  

animica node up selects the compose file for the active network, creates the data directory and volumes for that chain id, and starts the node container. The network is resolved in this order: a --network flag, the ANIMICA_NETWORK environment variable, the value persisted by animica network set, and finally the default, mainnet. Each network has its own data directory (~/.animica/chain-1 for mainnet) and its own Docker volumes, so you can run mainnet and devnet side by side without mixing their databases.

If you prefer not to use Docker, the repository's ops/run.sh --profile mainnet node starts the node from a checkout, and python -m core.boot is the lowest-level entry point. These paths are documented in docs/cli-commands.md and docs/BOOTSTRAP.md.

Verify it is working

    curl -s -X POST http://127.0.0.1:8545/rpc \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"chain.getHead","params":[]}'

# Compare with the public node
curl -s -X POST https://rpc.animica.org/rpc \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"chain.getHead","params":[]}'
  

A freshly started node begins in the HEADERS sync phase and the height climbs as blocks are fetched from peers. Once the two responses agree on height and hash (allowing a block or two of lag), you are on the canonical chain. animica node status prints the same information plus the network hashrate estimate and peer count.

Ports and environment

    export ANIMICA_NETWORK=mainnet
export ANIMICA_RPC_URL="http://127.0.0.1:8545/rpc"
# Optional: run the ANM-native L2 inside the same process
export ANIMICA_L2_ENABLE=1
  

Testnet (chain id 2) uses RPC port 18546 and P2P port 31334; devnet (chain id 1337) uses 28545 and 31335. These are the defaults in docs/network-docker-compose.md and can be changed with the corresponding ANIMICA_* variables.

Hardware

The node is pure Python and verifies ML-DSA-65 signatures in software, so CPU matters more than GPU. The repository's multi-node Docker guide assumes a host with 8 GB of RAM and 20 GB of free disk for a three-node local setup; a single mainnet node needs less, and the chain state at block 81,000 fits comfortably within that disk budget. Use an SSD: the database is SQLite-backed and sync is I/O-bound. A stable network connection with inbound port 30333 open helps the network more than it helps you, but is not required.

Because verification is single-threaded Python, a fast core beats many slow ones. The project has observed that heavy unrelated workloads on the same machine (large builds, other containers) can starve the node and cause RPC timeouts, so give a production node its own CPU headroom.

Keeping up with forks

Consensus rules activate at fixed heights and are announced ahead of time on the Network page, the Roadmap, and in GitHub releases. Upgrade with pip install --upgrade animica and restart the node before the activation height. A node on old software keeps peering past an emission fork but will report wrong balances, and will be forked off at the first block that uses a new reject rule. The current release line is 10.x.

Troubleshooting

• RPC not reachable. Run animica node doctor; check that the container is up and that ANIMICA_RPC_URL includes the /rpc path.
• Port already in use. Another network's node or an old container is bound to 8545; stop it or change rpc_port.
• No peers. Check outbound connectivity to port 30333 and that your clock is correct; peer discovery uses DNS seeds and the handshake rejects large clock skew.
• Head stuck. Compare with the explorer. If you are on a stale fork, restart the node; the reorg bound and pinned checkpoints will bring it back to the canonical chain.

More in docs/TROUBLESHOOTING.md, docs/MULTI_NODE_DOCKER_SETUP.md and docs/VERIFIER_NODE_RESTART.md, and on the Support page.

Sources

docs/network-docker-compose.md · docs/MULTI_NODE_DOCKER_SETUP.md · docs/cli-commands.md · docs/BOOTSTRAP.md · docs/rpc-quickstart.md · docs/l2/RUNNING.md · docs/TROUBLESHOOTING.md · python/README.md