(This document has been revised with Claude.AI)

Introduction

This document describes the core architectural components that Botanix requires to achieve secure, decentralized Bitcoin withdrawals (pegouts). The rationale and technical foundation for this work was established in our initial Proof-of-concept specification.

This project encompasses two interconnected but distinct components: the Trusted Execution Machine (TEM) and the Foundation Layer.

Foundation Layer

The Foundation Layer manages the complex validator coordination logic that underpins Botanix's multisig system and serves as the foundation for the eventual dynamic federation (DynaFed) implementation. It processes input from the Botanix chain through a Non-Deterministic Data (NDD) messaging system and maintains deterministic state management for all validator operations.

Key responsibilities include:

• Validator Set Management: Handling validator rotations and multisig membership changes
• State Commitment Proofs: Enforcing validator participation through cryptographic commitments
• Equivocation Detection: Providing the infrastructure for detecting and penalizing malicious validator behavior
• Deterministic State Transitions: Ensuring all validators maintain consistent views of system state, which is critical for implementing penalties and equivocation handling

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.

=> More indepth writeup on the Foundation Layer

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

=> More indepth writeup on the Trusted Execution Machine (TEM)

Building

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

To generate the documentation for botanix_tem:

cargo doc --document-private-items

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