run-dev.md

Running Citrea

This document covers how to run Citrea sequencer and a full node locally using a mock DA layer and Bitcoin Regtest.

Prerequisites

Follow the instructions in this document.

Building and running

Build citrea:

make build

Run on Mock DA

Run on a local da layer, sharable between nodes that run on your computer.

Run sequencer on Mock DA:

./target/debug/citrea --da-layer mock --rollup-config-path resources/configs/mock/sequencer_rollup_config.toml --sequencer resources/configs/mock/sequencer_config.toml --genesis-paths resources/genesis/mock/

Sequencer RPC is accessible at 127.0.0.1:12345

Optional: Run full node on Mock DA:

./target/debug/citrea --rollup-config-path resources/configs/mock/rollup_config.toml --genesis-paths resources/genesis/mock/

Full node RPC is accessible at 127.0.0.1:12346

If test_mode is set to false in the sequencer config, the sequencer will publish blocks every 2 seconds.

Run on Bitcoin Regtest

Run on local Bitcoin network.

Run Bitcoin Regtest:

bitcoind -regtest -txindex=1 -addresstype=bech32m

Or using docker:

docker compose -f docker/docker-compose.regtest.yml up

Keep this terminal open.

Create bitcoin wallet for Bitcoin DA adapter.

bitcoin-cli -regtest createwallet citreatesting
bitcoin-cli -regtest loadwallet citreatesting

Mine blocks so that the wallet has BTC:

bitcoin-cli -regtest -generate 201

Edit resources/configs/bitcoin-regtest/sequencer_config.toml to adjust the sequencer settings.

Edit resources/configs/bitcoin-regtest/sequencer_rollup_config.toml file and put in your rpc url, username and password:

[da]
# fill here
node_url = ""
# fill here
node_username = ""
# fill here
node_password = ""

Run sequencer:

./target/debug/citrea --da-layer bitcoin --rollup-config-path resources/configs/bitcoin-regtest/sequencer_rollup_config.toml --sequencer resources/configs/bitcoin-regtest/sequencer_config.toml --genesis-paths resources/genesis/bitcoin-regtest/

Sequencer RPC is accessible at 127.0.0.1:12345

Optional: Run full node

Run full node:

./target/debug/citrea --da-layer bitcoin --rollup-config-path resources/configs/bitcoin-regtest/rollup_config.toml --genesis-paths resources/genesis/bitcoin-regtest/

Full node RPC is accessible at 127.0.0.1:12346

Optional: Run batch prover:

./target/debug/citrea --da-layer bitcoin --rollup-config-path resources/configs/bitcoin-regtest/batch_prover_rollup_config.toml --batch-prover resources/configs/bitcoin-regtest/batch_prover_config.toml --genesis-paths resources/genesis/bitcoin-regtest

If you want to test proofs, make sure to set proof_sampling_number in resources/configs/bitcoin-regtest/batch_prover_config.toml to 0, and you can lower the min_soft_confirmations_per_commitment to a number between 5-50, as higher numbers than that takes too long even if you run the prover in execute mode.

To publish blocks on Bitcoin Regtest, run the sequencer with test_mode in sequencer config set to false and blocks will be published every two seconds.

Optional: Run light client prover:

./target/debug/citrea --da-layer bitcoin --rollup-config-path resources/configs/bitcoin-regtest/light_client_prover_rollup_config.toml --light-client-prover resources/configs/bitcoin-regtest/light_client_prover_config.toml --genesis-paths resources/genesis/bitcoin-regtest

To delete sequencer or full nodes databases run:

make clean-node

Testing

To run tests:

make test

This will run cargo nextest.