Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Component Relationships

BLVM implements a 6-tier layered architecture where each tier builds upon the previous one.

Dependency Graph

Edges point from a crate toward a crate it depends on (library import direction). The Orange Paper is not a Rust crate; it informs consensus (dotted).

flowchart LR OP[Orange Paper] C[blvm-consensus] P[blvm-protocol] N[blvm-node] S[blvm-sdk] G[blvm-commons] OP -.->|informs| C P --> C N --> P N --> C S --> P S --> C G --> S G --> P style OP fill:#f9f,stroke:#333,stroke-width:2px style C fill:#bbf,stroke:#333,stroke-width:2px style P fill:#bfb,stroke:#333,stroke-width:2px style N fill:#fbf,stroke:#333,stroke-width:2px style S fill:#ffb,stroke:#333,stroke-width:2px style G fill:#fbb,stroke:#333,stroke-width:2px

blvm-primitives (types, serialization, crypto) sits under blvm-consensus and blvm-protocol; it is not shown as its own tier here.

Layer Descriptions

Tier 1: Orange Paper (blvm-spec)

  • Purpose: Mathematical foundation - timeless consensus rules
  • Type: Documentation and specification
  • Governance: Layer 1 (Constitutional - 6-of-7 maintainers, 180 days, see Layer-Tier Model)

Tier 2: Consensus Layer (blvm-consensus)

  • Purpose: Pure mathematical implementation of Orange Paper functions
  • Type: Rust library (pure functions, no side effects)
  • Dependencies: blvm-primitives (shared types, serialization, consensus crypto); pinned transitive crates as in Cargo.toml
  • Governance: Layer 2 (Constitutional - 6-of-7 maintainers, 180 days, see Layer-Tier Model)
  • Key Functions: CheckTransaction, ConnectBlock, EvalScript, VerifyScript

Tier 3: Protocol Layer (blvm-protocol)

  • Purpose: Protocol abstraction layer for multiple Bitcoin variants
  • Type: Rust library
  • Dependencies: blvm-consensus and blvm-primitives (exact / ranged versions per Cargo.toml)
  • Governance: Layer 3 (Implementation - 4-of-5 maintainers, 90 days, see Layer-Tier Model)
  • Supports: mainnet, testnet, regtest, and additional protocol variants

Tier 4: Node Implementation (blvm-node)

Tier 5: Developer SDK (blvm-sdk)

  • Purpose: Developer toolkit and governance cryptographic primitives
  • Type: Rust library and CLI tools
  • Dependencies: Declares blvm-protocol and blvm-consensus on crates.io (for composition and module tooling); optional blvm-node via the default node feature. See the crate Cargo.toml.
  • Governance: Layer 5 (Extension - 2-of-3 maintainers, 14 days, see Layer-Tier Model)
  • Components: Key generation, signing, verification, multisig operations

Tier 6: Governance Infrastructure (blvm-commons)

  • Purpose: Cryptographic governance enforcement
  • Type: Rust service (GitHub App / server binaries)
  • Dependencies: blvm-sdk, blvm-protocol (see blvm-commons / Cargo.toml)
  • Governance: Layer 5 (Extension - 2-of-3 maintainers, 14 days)
  • Components: GitHub integration, signature verification, status checks

Data flow

The dependency graph above is the accurate picture for crate dependencies. At runtime, blocks and transactions flow through the node, which calls into protocol and consensus libraries to validate; the Orange Paper remains the specification those libraries implement.

How the Stack Works Figure: Operational view (IBD, validation, modules, governance). For which crate depends on which, use the dependency graph in this page.

  1. Orange Paper specifies consensus rules.
  2. blvm-consensus implements those rules (pure functions).
  3. blvm-protocol layers network parameters, wire helpers, and protocol policy on top of consensus types.
  4. blvm-node runs networking, storage, RPC, and orchestration; validation calls into protocol + consensus.
  5. blvm-sdk supplies governance crypto, composition, and (optional) node integration for modules.
  6. blvm-commons runs governance enforcement services using blvm-sdk and blvm-protocol types.

Cross-Layer Validation

  • Dependencies between layers are strictly enforced in the crate graph (no application layer should reimplement consensus).
  • Consensus rule modifications are prevented in application layers by design (validation calls into blvm-consensus).
  • The Orange Paper is the specification; blvm-consensus is checked with formal verification, tests, and review—not a single “one-shot” equivalence proof of the whole spec.
  • Version coordination (Cargo / release sets) keeps compatible crate versions together.

See Also