Run Citrea Full Node

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

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

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-v1.2.0-osx-arm64 --network mainnet --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

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.

Testnet4

If you need a Testnet4 setup, keep using the Testnet4-specific guides:

1. Run a Bitcoin Testnet4 Node

2. Run a Citrea Testnet Full Node