Documentation

Detailed Architecture

Overview

OP_NET observes Bitcoin blocks and derives deterministic state according to its own ruleset, without requiring any modifications to Bitcoin's protocol. This is fundamentally different from metaprotocols (which rely on indexers that can disagree) and Layer 2s (which require bridges and trust assumptions).

OP_NET Four Layers

The OP_NET architecture is divided into four layers that work together to process transactions, execute smart contracts, and maintain state consistency across the network.

The following diagram illustrates the four layers of the OP_NET architecture:
OP_NET Four Layer Architecture Layer 4: Consensus Layer (Epochs) Checkpointing & Consensus Finality Epoch Structure 5 Bitcoin blocks ~50 minutes Groups transactions Finalization periods Formula: Epoch N = Blocks (N×5) to (N×5+4) SHA-1 Mining Near-collision search Computational PoW Best match wins Deterministic selection Target: SHA-1(checksum + pubkey + salt) Time-Delayed Attestations Attest to state 4 epochs ago ~21 blocks deep Immutable history Makes forks impossible Rewards Gas fees from future epochs +3 epoch delay (~150 minutes) Prevents manipulation & incentivizes health Layer 3: State Management Layer Contract Storage & Verification Storage System 32 bytes key/value slots Contract variables Token balances Local databases Merkle Trees Track all state changes Cryptographic proofs Efficient verification Tamper-evident State Roots Checksum of all state In epoch solutions Immutable checkpoints ~50 min intervals Layer 2: Execution Layer (OP_VM) WebAssembly Virtual Machine WebAssembly VM Isolated execution environment Multi-language support (AssemblyScript, Rust) Fully deterministic execution Contract-to-contract calls Gas Metering Computational cost tracking Prevents infinite loops Paid in BTC (satoshis) No separate gas token Layer 1: Transaction Layer (OP_NET Nodes) Bitcoin as Data Transport Taproot Integration Script-path spending Witness data embedding WASM bytecode Function calls P2OP Addresses Deterministic generation Deployer pubkey + salt + bytecode hash Unique contract addr Ordering System Deterministic sorting 1. Gas price 2. Priority fees 3. Transaction ID Data Transport Bitcoin transactions No separate chain No bridges/locks Native Bitcoin L1 FOUNDATION: Bitcoin Layer 1 Immutable Data Storage All contract bytecode All function calls & parameters Permanent, unchangeable record Global Clock Block height = universal timestamp All nodes agree on time Enables time-delayed consensus No Bitcoin modifications • No BIP required • Optional consensus layer • Inherits Bitcoin's security

Layer 1: The Transaction Layer (OP_NET Nodes)

At its foundation, OP_NET utilizes Bitcoin transactions as its data transport mechanism. Deploying a smart contract or interacting with one involves creating specialized Bitcoin transactions that carry the necessary data.

Transaction Structure

OP_NET currently leverages Taproot's script-path spending capabilities to embed data directly within Bitcoin transactions. Future releases will extend support to additional transaction types, including SegWit and Legacy formats.

  • Smart Contract Deployment: A transaction containing the smart contract's compiled WebAssembly bytecode is created and broadcast to the network.
  • Smart Contract Interaction: A transaction containing the function call, parameters, and additional OP_NET-specific data is created and broadcast.

Since Bitcoin does not support native smart contract addresses, OP_NET generates deterministic addresses using the P2OP format. These addresses are derived from a combination of:

  • The deployer's public key.
  • A random salt.
  • The smart contract bytecode hash.

This approach (similar to Ethereum's CREATE2 mechanism) ensures each smart contract has a unique, predictable address that cannot be exploited to redirect funds.

Layer 2: The Execution Layer (OP_VM)

Above the transaction layer is OP_VM, the virtual machine responsible for smart contract execution. When OP_NET nodes detect smart contract related transactions within Bitcoin blocks, these transactions are passed to OP_VM for processing.

OP_VM executes WebAssembly bytecode within an isolated environment. This design provides two key benefits:

  • Language Flexibility: Smart contracts can be written in multiple languages (AssemblyScript, Rust, and others) that compile to WebAssembly.
  • Deterministic Execution: The isolated environment ensures that every node executing the same smart contract with identical inputs produces exactly the same result.

OP_VM implements a gas metering system similar to Ethereum, where each operation has an associated cost. This prevents infinite loops and ensures users pay proportionally for the computational resources consumed. Unlike Ethereum, gas fees are paid in Bitcoin (satoshis) rather than a separate token.

Layer 3: The State Management Layer

Smart contracts require persistent storage for data such as token balances, smart contract variables, and other state information. OP_NET manages this through a sophisticated state system. Each smart contract can allocate storage slots consisting of 32 bytes keys mapped to 32 bytes values, with all state changes tracked through Merkle trees.

OP_NET nodes maintain state locally in databases, but the data remains provable and verifiable. The state root, a cryptographic summary of all smart contract states, is included in epoch solutions, creating an immutable record of the system's state at regular intervals.

The following diagram illustrates the state management layer:
OP_NET State Management Layer Smart Contracts Token Contract (OP_20) NFT Contract (OP_721) Custom Contract read write Storage Slots 32 bytes Key → 32 bytes Value Key (32 bytes) Value (32 bytes) balance_slot_0x1a... 1000000 sats owner_slot_0x2b... 0xbc1q...address Token balances, contract variables, state data track Merkle Tree Cryptographic State Tracking Root Hash A Hash B H1 H2 H3 H4 Tamper-evident, efficient proofs OP_NET Node - Local Database State maintained locally but provable and verifiable Contract States All storage slots persisted locally Merkle Proofs Cryptographic paths for verification State Root Cryptographic summary of all contract states compute root Epoch Solution Immutable State Record Checksum Root 0x7f3a9c2b1d8e... Every 5 Bitcoin blocks (~50 min) include

Layer 4: The Epoch System

OP_NET uses an epoch-based checkpointing system rather than traditional blockchain consensus. Every 5 Bitcoin blocks form an epoch (approximately 50 minutes).

At each epoch boundary, miners compete to find the best SHA-1 near-collision with the epoch's checksum root. The winner must include an attestation about state from 4 epochs ago (~21 blocks deep in Bitcoin). This time-delay ensures the attested state is so deep it's effectively immutable.

Critical point: SHA-1 miners cannot decide consensus. They only compete for rewards. Given the same Bitcoin blocks, every OP_NET node derives the exact same state regardless of who mines the epoch. If nobody mines a valid solution, the genesis block hash becomes the epoch miner, ensuring consensus finality never stops.

Fork-Impossible Consensus

OP_NET forks are mathematically impossible, not just unlikely, but actually impossible. To understand why, consider how traditional blockchains handle competing histories.

Traditional Blockchains

In Bitcoin, two miners might find valid blocks simultaneously, creating temporary forks until one chain grows longer. This happens because these systems make decisions about events happening right now, where network latency and timing differences create ambiguity.

The following diagram illustrate a traditional fork scenario:
Traditional Blockchains (Bitcoin) Fork Scenario Decisions About the Present → Forks Possible Block N N+1 N+2a N+3a N+2b N+3b Two miners find valid blocks simultaneously • Network latency and timing differences create ambiguity TEMPORARY FORKS UNTIL ONE CHAIN WINS

OP_NET Consenus

OP_NET completely sidesteps this problem by never making decisions about the present. When epoch 184446 ends at block 922234, miners compete to create the winning solution. But every valid solution must include an attestation about the state at the end of epoch 184442 (block 922214). By the time anyone can submit a solution, block 922214 is already 21 blocks deep in Bitcoin's history.

For two nodes to disagree about epoch 184446's winner, they would need to disagree about what happened at block 922234. But at 21 blocks deep, every honest node has exactly the same view of block 922214's contents and state. The historical reference point is so deeply buried that all nodes must agree on it. There's no ambiguity, no possibility of different views. OP_NET uses Bitcoin blocks and does not create blocks on its own. If Bitcoin reorgs, OP_NET reorgs, simple as that.

Even when two miners submit equally good solutions with the same number of SHA-1 matching bits, OP_NET's deterministic tie-breaking mechanism prevents any ambiguity. The system doesn't care who submitted first or which node saw what solution when. Instead, it uses a mathematical comparison of the miners' public keys, the transaction hash that submitted this solution, and the one numerically closer to zero wins. This means that given the same set of submissions, every node will independently arrive at exactly the same winner, regardless of the order they received the submissions or their network position.

The following diagram illustrate why a fork scenario is not possible with OP_NET:
Why OP_NET Forks Are Mathematically Impossible OP_NET Consensus: Decisions About the Past → No Ambiguity Block N N+1 N+2 N+3 N+4 N+5 All nodes reference the same buried history • If Bitcoin reorgs, OP_NET reorgs FORKS MATHEMATICALLY IMPOSSIBLE Mechanism 1: Time-Delayed Attestations Solutions must attest to state from 4 epochs ago (~21 blocks deep) Bitcoin Blocks: 922214 Epoch 184442 ... 922219 ... 922229 ... 922234 Epoch 184446 Mining window ← 21 blocks deep = immutable history → Must attest to state at block 922214 (21 blocks deep) By the time anyone submits a solution, all honest nodes have the exact same view Mechanism 2: Deterministic Tie-Breaking When two solutions have equal SHA-1 matching bits Miner A Solution SHA-1 match: 42 bits pubkey: 0x7f3a9c2b... vs Miner B Solution SHA-1 match: 42 bits pubkey: 0x2b1c8d4e... Deterministic Winner Compare: pubkey + tx_hash Closer to zero wins

This dual mechanism, time delayed attestations to immutable history plus deterministic tie breaking, transforms the consensus problem from "which chain should we follow?" to "what does Bitcoin say happened 20 blocks ago, and who had the best solution?" Both questions have exactly one answer across all honest nodes, making forks logically impossible rather than just unlikely.

Transaction Flow

The sequence diagram below shows how the four layers works together:
OP_NET Smart Contract Transaction Flow User Bitcoin Network OP_NET Nodes OP_VM State Layer Epoch System 1 Create Contract Transaction 2 Broadcast Transaction Include in Block 3 New Block detect OP_NET transaction 4 Order by Priority deterministic ordering 5 Execute Transaction Update State State Updated 6 Record State Changes Create Epoch Checkpoint User Bitcoin Network OP_NET Nodes OP_VM State Layer Epoch System

The following sequence illustrates how these layers work together during a smart contract interaction:

  1. A user creates a transaction calling a smart contract function (such as swapping tokens on a DEX).
  2. The transaction is broadcast to the Bitcoin network and included in a block.
  3. OP_NET nodes detect the transaction.
  4. The transaction enters a deterministic ordering queue based on gas fees.
  5. Nodes execute the transaction and update states accordingly.
  6. State changes are recorded and included in the next epoch checkpoint.

Handling Bitcoin Reorganizations

While OP_NET's design makes internal forks impossible, it must still handle the reality that Bitcoin itself can experience reorganizations. When Bitcoin reorganizes, OP_NET needs to gracefully handle the state changes this implies.

Understanding how Bitcoin reorganizations affect OP_NET is essential. When Bitcoin reorganizes, blocks that OP_NET has already processed are replaced with different blocks. These new blocks may contain different transactions, in a different order, or may exclude some transactions entirely. OP_NET must therefore rewind its state to the point before the reorganization and replay the new chain of blocks.

Important

Since reorganizations only affect recent epochs that have not been finalized, no epoch winners need to be changed.

The diagram below illustrate how OP_NET manage Bitcoin reorganizations:
OP_NET Bitcoin Reorganization Handling Chain Reorganization Visualization Block N-3 Block N-2 Block N-1 Block N Common Ancestor N+1' N+2' N+3' Orphaned Chain (discarded) N+1 N+2 N+3 N+4 New Canonical Chain (longer) Common Ancestor Orphaned Canonical Reorganization Process 1. Detection OP_NET node detects reorg when a previously confirmed block has been replaced 2. Identification Node identifies the common ancestor: last valid block in both old and new chains 3. Reversion Node reverts OP_NET state back to the common ancestor block state 4. Reprocessing Node processes new blocks in sequential order deterministically State Transition During Reorg State @ N+3' (old chain tip) revert State @ N (common ancestor) replay State @ N+1 State @ N+2 State @ N+4 (new chain tip)

The reorganization process works as follows:

  1. Detection: The OP_NET node detects a reorganization in Bitcoin by noticing that a previously confirmed block has been replaced.
  2. Identification: The node identifies the common ancestor, which is the last block that remains valid in both the old and new chains.
  3. Reversion: The node reverts its state to the common ancestor block.
  4. Reprocessing: The node processes the new blocks in sequential order.

Smart Contract Bytecode Storage

When deploying a smart contract, the bytecode is stored in Bitcoin transactions using Tapscript and OP_PUSHDATA opcodes. The P2OP format serves as the address type for OP_NET contracts but does not store the bytecode itself.

Smart contracts bytecode is compressed using ZLIB to minimize storage requirements, with a maximum bytecode size of 400KB. The compressed bytecode is embedded directly in the witness data of the Bitcoin transaction.

On this page