Skip to main content

Subrail Runtime

Subrail is the high-performance WebAssembly (WASM) runtime at the heart of the SUBFROST node. It is specifically designed to execute the consensus-critical logic of Alkanes and other state transition functions within the SUBFROST protocol.

Purpose and Design​

The primary purpose of Subrail is to provide a secure, deterministic, and fast execution environment for the programs that define the SUBFROST protocol. By using WASM, Subrail allows for protocol logic to be developed in any language that can compile to a WASM target (such as Rust, C++, or Go), offering developers flexibility without sacrificing performance.

Key design features include:

  • Sandboxed Execution: All WASM modules are executed in a sandboxed environment, preventing them from accessing the host system's resources and ensuring the determinism required for consensus.
  • State Management: Subrail integrates directly with the node's state database. It provides the WASM guest with an API to read from and write to the world state, but only in a controlled, transactional manner.
  • Integration with metashrew: Subrail is powered by metashrew, a specialized Bitcoin blockchain indexer. metashrew processes Bitcoin blocks, extracts relevant data (like OP_RETURN outputs containing Runestones), and provides this data to the Subrail runtime. This allows Alkane contracts to be aware of and react to events on the Bitcoin L1.

Execution Lifecycle​

When a subfrost-node processes a new block, the following occurs:

  1. Data Ingestion: The metashrew component of the node parses the block and identifies any transactions containing Runestones.
  2. Runtime Invocation: The data from the Runestone (edicts, calldata, etc.) is passed to the Subrail runtime.
  3. WASM Execution: Subrail loads the appropriate Alkane WASM module (e.g., the frBTC contract) and executes it, passing the Runestone data as input.
  4. State Transition: The WASM module executes its logic. If it's a mint operation, it will calculate the new frBTC balance and use the Subrail API to write this new state to a pending state transition.
  5. State Commit: Once the block is fully processed and consensus is reached, the pending state transitions are committed to the node's database, finalizing the changes.

This architecture separates the core node logic from the application-specific logic of the Alkanes, making the entire system more modular, secure, and upgradeable.