Setting up a Celestia bridge node

This tutorial will go over the steps to set up your Celestia bridge node.

Bridge nodes connect the data availability layer and the consensus layer.

Overview of bridge nodes

A Celestia bridge node has the following properties:

1. Import and process “raw” headers & blocks from a trusted core process (meaning a trusted RPC connection to a consensus node) in the Consensus network. Bridge nodes can run this core process internally (embedded) or simply connect to a remote endpoint. Bridge nodes also have the option of being an active validator in the consensus network.
2. Validate and erasure code the “raw” blocks
3. Supply block shares with data availability headers to light nodes in the DA network.

From an implementation perspective, Bridge nodes run two separate processes:

1. celestia-app with celestia-core (see repo )

   • celestia-app is the state machine where the application and the proof-of-stake logic is run. celestia-app is built on Cosmos SDK  and also encompasses celestia-core.
   • celestia-core is the state interaction, consensus and block production layer. celestia-core is built on Tendermint Core , modified to store data roots of erasure coded blocks among other changes (see ADRs ).

2. celestia-node (see repo )

   • celestia-node augments the above with a separate libp2p network that serves data availability sampling requests. The team sometimes refers to this as the “halo” network.

Pruning vs archival modes

Bridge nodes can operate in two modes:

Pruned mode (default)

• Default behavior: Bridge nodes now prune old data automatically
• Stores only recent blocks within the availability window
• Significantly reduces storage requirements
• Can sync from a recent height or hash instead of genesis
• Suitable for most use cases

Archival mode

• Stores all historical data from genesis
• Requires the --archival flag to enable
• Much higher storage requirements (see hardware requirements)
• Necessary for applications requiring full historical data access
• Required if you need to serve data to light nodes for blocks outside the availability window

Choosing between modes

Use pruned mode (default) if you:

• Want lower storage requirements
• Only need recent blockchain data
• Are running a standard bridge node for the network

Use archival mode (--archival flag) if you:

• Need access to full historical data
• Are running infrastructure that requires all blocks from genesis
• Want to serve data for blocks outside the availability window
• Are running a bridge node on a private network without proper genesis hash configuration

Hardware requirements

See hardware requirements.

Setting up your bridge node

The following tutorial is done on an Ubuntu Linux 20.04 (LTS) x64 instance machine.

Deploy the Celestia bridge node with the following steps.

celestia bridge init --core.ip <URI> --core.port <port>

celestia bridge init --core.ip <URI> --core.port <port> --archival

# Pruned mode (default)
celestia bridge init --core.ip <URI> --core.port <port>
 
# Archival mode
celestia bridge init --core.ip <URI> --core.port <port> --archival

# Pruned mode (default)
celestia bridge init --core.ip <URI> --core.port <port> \
    --p2p.network mocha
 
# Archival mode
celestia bridge init --core.ip <URI> --core.port <port> \
    --p2p.network mocha --archival

# Pruned mode (default)
celestia bridge init --core.ip <URI> --core.port <port> \
    --p2p.network arabica
 
# Archival mode
celestia bridge init --core.ip <URI> --core.port <port> \
    --p2p.network arabica --archival

# Pruned mode (default)
celestia bridge start --core.ip <URI> --core.port <port>
 
# Archival mode
celestia bridge start --core.ip <URI> --core.port <port> --archival

# Pruned mode (default)
celestia bridge start --core.ip rpc-mocha.pops.one --core.port 9090 --p2p.network mocha
 
# Archival mode
celestia bridge start --core.ip rpc-mocha.pops.one --core.port 9090 --p2p.network mocha --archival

# Pruned mode (default)
celestia bridge start --core.ip validator-1.celestia-arabica-11.com \
  --p2p.network arabica --core.port 9090
 
# Archival mode
celestia bridge start --core.ip validator-1.celestia-arabica-11.com \
  --p2p.network arabica --core.port 9090 --archival

[grpc]
# Enable defines if the gRPC server should be enabled.
enable = true
# Address defines the gRPC server address to bind to.
address = "localhost:9090"

You can create your key for your node by following the cel-key instructions.

Once you start the bridge node, a wallet key will be generated for you. You will need to fund that address with Testnet tokens to pay for PayForBlob transactions. You can find the address by running the following command:

./cel-key list --node.type bridge --keyring-backend test --p2p.network <network>

You can get testnet tokens from:

• Mocha
• Arabica

Note: If you are running a bridge node for your validator, it is highly recommended to request Mocha testnet tokens as this is the testnet used to test out validator operations.

Optional: run the bridge node with a custom key

In order to run a bridge node using a custom key:

1. The custom key must exist inside the celestia bridge node directory at the correct path (default: ~/.celestia-bridge/keys/keyring-test)
2. The name of the custom key must be passed upon start, like so:

celestia bridge start --core.ip <URI> --keyring.keyname <name-of-custom-key> \
    --core.port <port>

celestia bridge start --core.ip <URI> --keyring.keyname <name-of-custom-key> \
    --p2p.network mocha --core.port <port>

celestia bridge start --core.ip <URI> --keyring.keyname <name-of-custom-key> \
    --p2p.network arabica --core.port <port>

Optional: Migrate node id to another server

To migrate a bridge node ID:

1. You need to back up two files located in the celestia-bridge node directory at the correct path (default: ~/.celestia-bridge/keys).
2. Upload the files to the new server and start the node.

Optional: start the bridge node with SystemD

Follow the tutorial on setting up the bridge node as a background process with SystemD.

You have successfully set up a bridge node that is syncing with the network.

Optional: enable on-fly compression with ZFS

Follow the tutorial on how to set up your DA node to use on-fly compression with ZFS.

Migration guide for existing bridge nodes

If you’re running an existing bridge node and upgrading to celestia-node [TODO: Add version from PR #4768] or later, you need to be aware of the pruning changes:

For nodes that need full historical data

If your bridge node needs to maintain full historical data:

1. Stop your existing bridge node
2. Add the --archival flag to your start command
3. Restart your node

Example:

# Old command
celestia bridge start --core.ip <URI> --core.port <port>
 
# New command with archival mode
celestia bridge start --core.ip <URI> --core.port <port> --archival

For nodes that can use pruned mode

If your bridge node doesn’t need full historical data:

1. Your node will automatically start pruning old data after the upgrade
2. No action required - this is now the default behavior
3. Storage usage will gradually decrease as old data is pruned

For private networks

Options for private network operators:

1. Use archival mode: Add --archival to maintain existing behavior
2. Configure genesis hash: Set up CELESTIA_CUSTOM environment variable with your network’s genesis hash
3. Use SyncFromHeight or SyncFromHash: Configure the node to sync from a specific height or hash