Zebra Documentation

Zebra platform support is categorized into three tiers based on build and testing guarantees. Platforms are identified by their Rust "target triple" (<machine>-<vendor>-<operating system>).

Tier 1: Guaranteed to work

Official binary releases and Docker images are provided. Automated testing ensures these platforms build and pass tests after every change.

• x86_64-unknown-linux-gnu (Debian 13, 64-bit): Provides Docker and binary artifacts.
• aarch64-unknown-linux-gnu (Debian 13, 64-bit ARM64): Provides Docker and binary artifacts.

Note: Official Docker images are multi-architecture and support both AMD64 and ARM64 using the same image tag.

Tier 2: Guaranteed to build

Automated CI builds ensure these platforms can compile, but not all tests are run. Official builds are not provided.

• x86_64-unknown-linux-gnu (GitHub ubuntu-latest, 64-bit): Uses latest stable Rust.
• x86_64-unknown-linux-gnu (GitHub ubuntu-latest, 64-bit beta): Uses latest beta Rust.

Tier 3: Supported but untested

The codebase supports these platforms, but they are not built or tested automatically. Official builds are not available.

• x86_64-apple-darwin (macOS, 64-bit)
• aarch64-apple-darwin (macOS, 64-bit Apple M1/M2)
• x86_64-pc-windows-msvc (Windows, 64-bit)

When Zebra starts, it launches multiple concurrent tasks to initialize the node. The process generally follows these stages:

1. Load Configuration: Reads settings from the config file.
2. Open Cached State: Loads existing blockchain data from disk or creates a new empty state.
3. Peer Handling: Discovers initial peers via DNS seeders and establishes connections.
4. Initialize JSON-RPC Server: Starts the optional RPC interface for external applications (e.g., lightwalletd).
5. Initialize Verifiers: Loads Sprout and Sapling parameters to verify blocks and transactions.
6. Initialize Transaction Mempool: Prepares tasks for syncing, verifying, and gossiping transaction hashes.
7. Syncing the Block Chain: Downloads, verifies, and gossips blocks until the node reaches the network consensus chain tip.

You can monitor the progress of these tasks using Grafana dashboards.

Stolon is a transaction diffusion algorithm designed to improve the privacy of shielded transactions by obscuring their provenance. It is inspired by the Dandelion algorithm but optimized for Zcash.

Stolon operates in two distinct phases:

1. Relay phase (stem phase): Transactions are relayed through a small-fanout network using ephemeral, isolated Tor connections. These connections are designed to be minimally distinguishable and are isolated from the node's other state to prevent information leakage.
2. Broadcast phase (fluff phase): Transactions are broadcast widely across the standard clearnet P2P network to be propagated as quickly as possible.

Transitioning from the relay phase to the broadcast phase occurs based on a random probability. Stolon is intended for use by full nodes (like Zebra or Zcashd) and wallet software to ensure that the initial creation of a transaction does not immediately reveal the sender's identity to the network.

The zcashd-compat mode is designed for operators (like exchanges or custodial services) who need to migrate to Zebra while maintaining their existing zcashd wallet and RPC integrations.

In this topology, Zebra acts as the consensus node facing the public Zcash P2P network. zcashd runs as a P2P sidecar that makes a single outbound connection to the local Zebra node and does not listen for any inbound P2P connections.

Key responsibilities shift as follows:

Zebra uses RocksDB to provide a persistent, thread-safe BTreeMap<&[u8], &[u8]>. The database is organized into several Column Families categorized by protocol features (Blocks, Transactions, Transparent, Sprout, Sapling, Orchard, and Chain).

Key Storage Principles

• Lexicographic Order: Keys are sorted using [u8].sorted(). To ensure integer values maintain numeric ordering in the database, they must be stored using big-endian encoding.
• 1-to-Many Maps: Zebra uses prefix-based keys to implement 1-to-many relationships. For example, tx_loc_by_transparent_addr_loc maps an address to multiple transactions by prefixing each transaction key with the address, allowing for efficient prefix listing.
• Encoding: Most Zcash protocol structures use ZcashSerialize/ZcashDeserialize. Some use custom IntoDisk/FromDisk implementations.

Warning: Avoid using bincode for new column families, as it is sensitive to struct field order and type changes.

/* Column Family Overview (Partial) */
| Column Family                      | Keys                   | Values                        |
| ---------------------------------- | ---------------------- | ----------------------------- |
| _Blocks_                           |                        |                               |
| `hash_by_height`                   | `block::Height`        | `block::Hash`                 |
| `height_by_hash`                   | `block::Hash`          | `block::Height`               |
| `block_header_by_height`           | `block::Height`        | `block::Header`               |
| _Transactions_                     |                        |                               |
| `tx_by_loc`                        | `TransactionLocation`  | `Transaction`                 |