Module zebrad::commands::start

source ·
Expand description

start subcommand - entry point for starting a zebra node

§Application Structure

A zebra node consists of the following major services and tasks:


  • Peer Connection Pool Service
    • primary external interface for outbound requests from this node to remote peers
    • accepts requests from services and tasks in this node, and sends them to remote peers
  • Peer Discovery Service
    • maintains a list of peer addresses, and connection priority metadata
    • discovers new peer addresses from existing peer connections
    • initiates new outbound peer connections in response to demand from tasks within this node
  • Peer Cache Service
    • Reads previous peer cache on startup, and adds it to the configured DNS seed peers
    • Periodically updates the peer cache on disk from the latest address book state

Blocks & Mempool Transactions:

  • Consensus Service
    • handles all validation logic for the node
    • verifies blocks using zebra-chain, then stores verified blocks in zebra-state
    • verifies mempool and block transactions using zebra-chain and zebra-script, and returns verified mempool transactions for mempool storage
  • Inbound Service
    • primary external interface for inbound peer requests to this node
    • handles requests from peers for network data, chain data, and mempool transactions
    • spawns download and verify tasks for each gossiped block
    • sends gossiped transactions to the mempool service


  • Sync Task
    • runs in the background and continuously queries the network for new blocks to be verified and added to the local state
    • spawns download and verify tasks for each crawled block
  • State Service
    • contextually verifies blocks
    • handles in-memory storage of multiple non-finalized chains
    • handles permanent storage of the best finalized chain
  • Old State Version Cleanup Task
    • deletes outdated state versions
  • Block Gossip Task
    • runs in the background and continuously queries the state for newly committed blocks to be gossiped to peers
  • Progress Task
    • logs progress towards the chain tip

Shielded Scanning:

  • Shielded Scanner Task
    • if the user has configured Zebra with their shielded viewing keys, scans new and existing blocks for transactions that use those keys

Block Mining:

  • Internal Miner Task
    • if the user has configured Zebra to mine blocks, spawns tasks to generate new blocks, and submits them for verification. This automatically shares these new blocks with peers.

Mempool Transactions:

  • Mempool Service
    • activates when the syncer is near the chain tip
    • spawns download and verify tasks for each crawled or gossiped transaction
    • handles in-memory storage of unmined transactions
  • Queue Checker Task
    • runs in the background, polling the mempool to store newly verified transactions
  • Transaction Gossip Task
    • runs in the background and gossips newly added mempool transactions to peers

Remote Procedure Calls:

  • JSON-RPC Service
    • answers RPC client requests using the State Service and Mempool Service
    • submits client transactions to the node’s mempool

Zebra also has diagnostic support:

Some of the diagnostic features are optional, and need to be enabled at compile-time.


  • Start the application (default command)