Run Citrea Full Node

Running a Citrea node is permissionless - anyone can run a full node for development & security purposes.

A Citrea Full Node requires a Bitcoin node. Citrea uses Bitcoin as its DA layer, so before running a Citrea node you need a fully synced Bitcoin Mainnet node running with -txindex=1. Set one up first by following Bitcoin Mainnet, then use its RPC URL, username, and password in the steps below.

The easiest way to get started is to use the Citrea full node Docker image.

Step 1: Install Docker

Follow instructions to install Docker here.

Step 2: Run Citrea Full Node (mainnet)

docker run -d \
  -e NETWORK=mainnet \
  -e NODE_URL=<your_bitcoin_node_rpc_url> \
  -e NODE_USERNAME=<your_bitcoin_rpc_username> \
  -e NODE_PASSWORD=<your_bitcoin_rpc_password> \
  -v citrea-data:/mnt/task/citrea-db \
  -p 8080:8080 \
  chainwayxyz/citrea-full-node:latest

This starts a Citrea mainnet full node. You must provide a fully synced Bitcoin mainnet node running with -txindex=1 for NODE_URL

Running on Testnet? Set NETWORK=testnet and point NODE_URL at a Bitcoin Testnet4 node (see Bitcoin Mainnet — each guide has a Testnet4 info box). Everything else stays the same:

docker run -d \
  -e NETWORK=testnet \
  -e NODE_URL=<your_bitcoin_testnet4_node_rpc_url> \
  -e NODE_USERNAME=<your_bitcoin_rpc_username> \
  -e NODE_PASSWORD=<your_bitcoin_rpc_password> \
  -v citrea-data:/mnt/task/citrea-db \
  -p 8080:8080 \
  chainwayxyz/citrea-full-node:latest

Please note that there are no financial incentives to run a Citrea Full Node. It's for your own development setup and security practices.

---

Mainnet manual setup (binary or source)

If you prefer to avoid Docker or need to customize your setup, use one of the options below.

Option 1: Pre-built binary

1. Download the latest binary for your OS from the Citrea releases page.

2. Download mainnet config and genesis files:

curl https://raw.githubusercontent.com/chainwayxyz/citrea/nightly/resources/configs/mainnet/rollup_config.toml --output rollup_config.toml
mkdir -p genesis
curl https://raw.githubusercontent.com/chainwayxyz/citrea/nightly/resources/genesis/mainnet/evm.json --output genesis/evm.json
curl https://raw.githubusercontent.com/chainwayxyz/citrea/nightly/resources/genesis/mainnet/accounts.json --output genesis/accounts.json
curl https://raw.githubusercontent.com/chainwayxyz/citrea/nightly/resources/genesis/mainnet/l2_block_rule_enforcer.json --output genesis/l2_block_rule_enforcer.json

1. Run the node (example for macOS):

./citrea-v2.4.0-osx-arm64 --network mainnet --da-layer bitcoin --rollup-config-path ./rollup_config.toml --genesis-paths ./genesis

Testnet config & genesis: To run on testnet, download the testnet config and genesis instead and run with --network testnet:

curl https://raw.githubusercontent.com/chainwayxyz/citrea/nightly/resources/configs/testnet/rollup_config.toml --output rollup_config.toml
mkdir -p genesis
curl https://raw.githubusercontent.com/chainwayxyz/citrea/nightly/resources/genesis/testnet/evm.json --output genesis/evm.json
curl https://raw.githubusercontent.com/chainwayxyz/citrea/nightly/resources/genesis/testnet/accounts.json --output genesis/accounts.json
curl https://raw.githubusercontent.com/chainwayxyz/citrea/nightly/resources/genesis/testnet/l2_block_rule_enforcer.json --output genesis/l2_block_rule_enforcer.json

./citrea-v2.4.0-osx-arm64 --network testnet --da-layer bitcoin --rollup-config-path ./rollup_config.toml --genesis-paths ./genesis

Option 2: Build from source

1. Clone the repository and checkout the latest tag:

git clone https://github.com/chainwayxyz/citrea
cd citrea
git fetch --tags
git checkout $(git describe --tags `git rev-list --tags --max-count=1`)

1. Build and run:

SKIP_GUEST_BUILD=1 cargo build --release
./target/release/citrea --network mainnet --da-layer bitcoin --rollup-config-path ./resources/configs/mainnet/rollup_config.toml --genesis-paths ./resources/genesis/mainnet

Testnet: the repo also ships testnet config and genesis. Build the same way and run with --network testnet:

./target/release/citrea --network testnet --da-layer bitcoin --rollup-config-path ./resources/configs/testnet/rollup_config.toml --genesis-paths ./resources/genesis/testnet

Want to sync faster? Syncing from genesis can take a while. You can start from a recent snapshot instead — see Full Node Snapshots.

Step 3: Check the sync status

You can check the status with the following command (you may need to arrange the URL at the end based on your setup):

curl -X POST --header "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"citrea_syncStatus","params":[], "id":31}' http://0.0.0.0:8080

A sample response (fields may vary based on the sync status):

{
  "jsonrpc": "2.0",
  "id": 31,
  "result": {
    "l1Status": {
      "Synced": 46916
    },
    "l2Status": {
      "Syncing": {
        "headBlockNumber": 252441,
        "syncedBlockNumber": 123425
      }
    }
  }
}

Hardware Requirements for running a node

A Linux/Mac/Windows system with a configuration of

• 8 GB RAM

• 2 TB SSD (NVMe recommended)

• 4 core CPU (if you're using cloud)

• 25+ Mbps network connection

should satisfy the minimum requirements to run a Citrea node. Allocating more resources improves the syncing speed.

---

If you encounter any problems during the node running even though you have a system that fits the requirements, please visit our Discord and let us know by opening a ticket.

Looking for Testnet? There's no separate testnet guide — each step above has a Testnet info box showing the changes (set NETWORK=testnet / --network testnet, use the testnet config & genesis, and point at a Bitcoin Testnet4 node).