Introduction

This repository implements the core infrastructure for the final and hardened version of Botanix, bringing fully secure, decentralized Bitcoin withdrawals (pegouts) to production. It is the engineering realization of the Dynamic Federation whitepaper, our primary technical specification, together with the earlier Proof-of-Concept specification that established the cryptographic foundations.

The system is built around two interconnected components:

• Foundation Layer: a thin state verification layer that manages validator coordination and pegout lifecycle across the distributed multisig system
• Trusted Execution Machine (TEM): an isolated, networkless environment that cryptographically validates and authorizes pegout requests

Building

This repository is primarily intended to be used as a library. Further structural changes to follow.

To generate the documentation for botanix_tem:

cargo doc --document-private-items

Foundation Layer

The most important aspect of Botanix is that much of the coordination and validation occurs off-chain in an asynchronous manner. Although users initiate pegouts deterministically through the EVM, the multisig system must handle complex, time-distributed operations: initiating signing rounds, exchanging multiple FROST packages across undefined timelines, and potentially employing batching systems that collect multiple pegouts before constructing PSBT transactions. Furthermore, PSBT transactions may fail or become orphaned on the Bitcoin layer, requiring pending pegouts to be nullified and made spendable again. These moving parts operate on different schedules, and we cannot expect these events to occur simultaneously for all observers. Additionally, validators - who may participate in zero, one, or multiple multisig accounts - cannot reliably track the constantly changing states of all other multisig accounts.

The Foundation Layer serves as a thin state verification layer that manages these critical properties without the complexity of tracking states across a constantly evolving landscape of validator set transitions, multisig account changes, rotations, and a dynamic Bitcoin chain where blocks may be orphaned. Following principles similar to the TEM, the Foundation Layer treats all input as potentially malicious, verifies input through cryptographic proofs, and crucially makes all decisions based solely on provided inputs without requiring access to external networks or resources.

The TEM depends on the Foundation Layer for validator state information, while the Foundation Layer operates independently. This unidirectional dependency ensures that the Foundation Layer can function as a standalone validator coordination system while providing the necessary infrastructure for TEM operations.

Trusted Execution Machine (TEM)

The TEM operates as an isolated, networkless environment without persistent storage, responsible for cryptographically validating and authorizing pegout requests from Botanix users. It treats all input as potentially malicious and validates every piece of data through cryptographic proofs before taking any action.

While the TEM can independently validate the cryptographic legitimacy of individual pegout requests, it depends on the Foundation Layer to understand the broader multisig context. Specifically, the TEM requires knowledge of which multisig setup each pegout should be assigned to, which pegouts have already been processed, and which remain pending. This dependency is essential for preventing double-spend attacks, as the TEM must maintain accurate state about pegout lifecycle management across the distributed multisig system.

The TEM's primary security benefits include:

• Key Protection: Botanix validators can deploy the TEM within a Trusted Execution Environment (TEE), ensuring that multisig keys remain secure even if the main Reth node is compromised
• Sequential Validation: The pegout validation process operates deterministically with fewer moving parts, making the system significantly easier to test, audit, and reason about
• Cryptographic Verification: All trust assumptions are eliminated through comprehensive proof verification

Offline Validation

The validation module serves as the security core for the TEM, implementing a comprehensive trust-but-verify model where all external data must be cryptographically validated before use. This approach is essential for TEE deployment where the system operates without network access or persistent storage capabilities.

The validation module implements a hierarchical "Checked Types" pattern where validated data is wrapped in types that guarantee successful validation:

• CheckedBitcoinHeader: Bitcoin header with validated proof-of-work
• CheckedTendermintHeader: Tendermint header with validated BFT consensus
• CheckedBotanixHeader: Botanix header validated against Tendermint commitment
• CheckedPegoutWithId: Pegout with complete multi-layer proof verification

These types prevent direct access to unvalidated data and ensure that only cryptographically verified information is used in downstream processing.

The validation system operates under several core principles that ensure security and reliability:

• Cryptographic Verification: All trust is based on cryptographic proofs rather than external sources or assumptions
• Multi-Chain Consistency: Data consistency is enforced across heterogeneous blockchain systems using their respective proof mechanisms
• Stateless Operation: Validation occurs without persistent state, reconstructing all necessary context from provided proofs
• Deterministic Results: Identical inputs always produce identical validation outcomes, essential for distributed TEE consensus

The validation module consists of four specialized components, each handling validation for different blockchain systems and operations:

Roadmap

Temporary roadmap while this repository remains primarily work-in-progress. This section will be removed later on.

Foundation Module (src/foundation/)

• Commitment System (src/foundation/commitment/) - Cryptographic state commitment using trie-db
  • Entry system with domain-separated keys (entry.rs)
  • Sorted data structures for deterministic operations (sorted.rs)
  • Low-level trie operations with consistency guarantees (trie.rs)
  • Higher-level Botanix state management (botanix.rs)
  • Atomic storage operations with transaction semantics (storage.rs)
  • Custom node codec for trie encoding/decoding (forked) (node_codec.rs)
• Proof System (src/foundation/proof.rs) - Cryptographic state proofs for consensus
  • Foundation state root computation
  • Auxiliary event tracking for efficient lookups
  • State reconstruction capabilities
• Core Foundation API (src/foundation/mod.rs) - Main interface
  • Two-phase operation model (propose/finalize)
  • Pegout lifecycle management (initiated -> pending -> delayed/finalized)
  • Bitcoin block tree coordination with automatic pruning
  • Deterministic state transitions for consensus
• Testing
  • Basic unit tests
  • Comprehensive tests

TEM Module (src/tem/)

• Core Implementation
  • Input validation workflow
  • Pegout set tracking (requires Foundation module)
  • Frost package signing implementation
  • gRPC interface
• Validation Framework
  • Tendermint chain validation setup
  • Botanix header validation against Tendermint
  • Pegout validation with Merkle proofs
• Testing
  • Basic unit tests
  • Comprehensive tests

Validation Module (src/validation/)

Bitcoin Validation (bitcoin.rs)

• CheckedBitcoinHeader
  • Proof-of-work validation with hardcoded difficulty target
  • Block hash computation and verification
  • Minimum difficulty enforcement (based on block 840,000)
• CheckedBitcoinTransaction
  • Transaction inclusion proof verification
  • Partial Merkle tree proof validation
  • TXID matching in proof validation
• Transaction Proof Verification
  • verify_transaction_proof function
  • Merkle root validation
  • TXID inclusion verification
• Testing
  • Basic unit tests
  • Comprehensive tests

Tendermint Validation (tendermint.rs)

• CheckedTendermintHeader
  • Individual header validation wrapper
• CheckedTendermintChain
  • Genesis validator set bootstrapping
  • Chain continuity validation (parent references)
  • Sequential height increment validation
  • Validator signature verification (≥2/3 voting power)
  • Validator set transition handling
  • Bitcoin-anchored chain initialization
• Commit Validation
  • Commit structure validation
  • Signature cryptographic verification
  • Voting power threshold enforcement
• Testing
  • Basic unit tests
  • Comprehensive tests

Botanix Validation (botanix.rs)

• CheckedBotanixHeader
  • Cross-chain validation against Tendermint app_hash
  • Header hash computation
  • App hash mismatch error handling
• Transaction Root Operations
  • compute_transactions_root - Merkle Patricia tree root computation
  • compute_transaction_proof - proof generation
  • verify_transaction_proof - proof verification
• Receipt Root Operations
  • compute_receipts_root - Merkle Patricia tree root computation
  • compute_receipt_proof - proof generation
  • verify_receipt_proof - proof verification
• Testing
  • Basic unit tests
  • Comprehensive tests

Pegout Validation (pegout.rs)

• CheckedPegoutWithId
  • Multi-layer proof verification (transaction + receipt)
  • Position consistency validation (matching nibbles)
  • Log index bounds checking
  • Tenderming proof validation (appHash)
• Pegout Data Structures
  • PegoutWithId - pegout with unique identifier
  • PegoutId - transaction hash + log index identifier
  • PegoutData - amount, destination, network
• Event Log Processing
  • extract_pegout_data function
  • Pegout validation logic
• Testing
  • Basic unit tests
  • Comprehensive tests

Primitives Module (src/primitives/)

Core Data Types (mod.rs)

• BotanixHeader
  • Complete header structure
  • Hash computation (hash_slow)
• Transaction Types
  • TxType enum
  • TransactionSigned structure
  • Transaction structure
  • TransactionSigned::hash_slow implementation
• Receipt Types
  • Receipt
  • ReceiptWithBloom

Structs Module (src/structs/)

Merkle Patricia Tree (merkle_patricia.rs)

• Core Operations
  • compute_root - trie root computation
  • compute_proof - inclusion proof generation
  • verify_proof - inclusion proof verification
  • MerklePatriciaProof with nibbles and nodes

Simple Merkle Tree (merkle_simple.rs)

• Core Operations
  • compute_root - CometBFT-compatible Merkle root
  • compute_proof - inclusion proof generation
  • verify_proof - inclusion proof verification
• Security Features
  • Prefix-based hashing (0x00 for leaves, 0x01 for inner nodes)
  • Protection against second pre-image attacks
  • Deterministic tree construction
• Proof Structure
  • MerkleProof with total leaves, leaf index, and aunt hashes
  • Aunt hash collection in correct order
• Testing
  • Basic unit tests
  • Comprehensive tests

Block Tree (block_tree.rs)

• Core Structure
  • BlockTree with tips, elder, blocks map, best height tracking
  • Confirmation depth configuration
  • Fork handling and resolution
• Block Management
  • Block insertion with parent-child relationships
  • Automatic pruning based on confirmation depth
  • Elder (oldest retained block) tracking
• Pruning Strategy
  • Forward pruning for finalized blocks
  • Backward pruning for orphaned forks
  • BlockFate classification (Finalized vs Orphaned)
• Testing
  • Basic unit tests
  • Comprehensive tests