Architecture

OPP_NET is a full-stack Bitcoin L1 smart contract framework. Every component is written in Rust and designed for performance, correctness, and self-sovereignty.

Stack Overview

┌──────────────────────────────────────────────────────────┐
│                   Client / Browser                       │
│          @opnet/ts-sdk  |  opnet-cli  |  Explorer UI     │
└───────────────┬──────────────────────┬───────────────────┘
                │ JSON-RPC (HTTPS)     │ REST (HTTPS)
                ▼                      ▼
┌──────────────────────────┐  ┌────────────────────────────┐
│  opnet-jsonrpc (Actix)   │  │   osprey (Rust/Actix)      │
│                          │  │                            │
│  btc_*  ─► metashrew     │  │  Polls btc_getBlockTraces  │
│  bitcoin_*─► btcrpc-proxy│  │  Builds secondary indexes  │
│             ──► bitcoind │  │  in RocksDB (17 col fams)  │
└──────────┬───────┬───────┘  │                            │
           │       │          │  REST: /api/v1/*            │
           ▼       ▼          │  explorer | swap | slohm    │
┌────────────────┐ ┌────────┐ └─────────────┬──────────────┘
│  metashrew     │ │btcrpc- │               │
│ (rockshrew-    │ │ proxy  │               │ polls
│  mono)         │ │        │               ▼
│ Runs opshrew.  │ │Proxies │  ┌───────────────────────┐
│ wasm indexer   │ │to      │  │    opnet-jsonrpc       │
│                │ │bitcoind│  │  (btc_getBlockTraces)  │
└────────────────┘ └────────┘  └───────────────────────┘

Key Components

metashrew + opshrew.wasm

The core of OPP_NET. metashrew (specificallyrockshrew-mono) is a WASM-native Bitcoin indexer that loads and executes a WASM module — opshrew.wasm — for every block. The WASM module contains all indexing logic: parsing OP_NET envelopes from tapscript witnesses, deploying contracts, executing interactions, and storing state in RocksDB.

When a view query comes in (like btc_call), metashrew calls the appropriate view function in the WASM module, which reads from the indexed state and returns the result. Contract simulation runs the actual contract WASM bytecode inside the indexer's WASM runtime — WASM-inside-WASM.

opnet-jsonrpc

A Rust (Actix-web) JSON-RPC gateway that routes requests to the appropriate backend:

• btc_* methods → metashrew (opshrew views)
• bitcoin_* methods → btcrpc-proxy → bitcoind

This provides a unified RPC endpoint for clients. The routing is transparent — clients don't need to know which backend handles which method.

btcrpc-proxy

A lightweight Rust HTTP proxy that translates Bitcoin Core JSON-RPC calls to the upstream block source. For testnet4, this proxies tomempool.opnet.org/testnet4, providing compatibility with the canonical OP_NET network. For regtest, it connects directly to a local bitcoind instance.

osprey (Explorer Backend)

osprey is the block explorer and analytics backend. It sits alongside opnet-jsonrpc and continuously polls btc_getBlockTraces to build secondary indexes in its own RocksDB instance with 17 column families (blocks, transactions, addresses, contracts, traces, swap pools, token volumes, SLOHM rebases, and more).

It serves a REST API at /api/v1/* organized into three modules:

• Explorer — blocks, transactions, traces, addresses, contracts, stats
• OppSwap — pool listings, token metadata, volume analytics
• SLOHM — protocol overview, rebase history, bond markets, treasury history

The REST API is exposed externally through OpenResty at rpc.oppnet.dev/<network>/explorer/*.

Contract Execution Model

OPP_NET contracts are compiled to WASM and deployed on-chain via OP_NET's commit/reveal envelope protocol in tapscript witnesses. The envelope contains:

• Deployer pubkey — x-only public key (32 bytes)
• Salt — unique deployment salt (32 bytes)
• Payload — brotli-compressed WASM bytecode

Contract addresses are derived as hash160(deployer_pubkey || salt || bytecode_hash), producing a 20-byte address. Storage is keyed by this address.

PoW Mining

OPP_NET uses a Proof-of-Work challenge system for contract deployment. Each epoch (5 blocks) produces a target checksum. Miners must find a salt that, when XOR'd with the target and their pubkey and hashed with SHA-1, matches the target hash to at least 35 bits of difficulty.

Network Configuration

Why Rust

The canonical OP_NET implementation uses AssemblyScript for contracts and TypeScript for the indexer and tooling. OPP_NET replaces all of this with Rust:

• Contracts — Rust compiled to WASM (not AssemblyScript)
• Indexer — Rust WASM module (opshrew) running in Rust host (metashrew)
• RPC Server — Rust (Actix-web)
• CLI Tools — Rust (opnet-cli)
• Explorer Backend — Rust (osprey: secondary indexer + REST API)
• Proxy — Rust (btcrpc-proxy)
• Cryptography — Rust (opcrypt: secp256k1, ML-DSA, SHA-1)

TypeScript exists only as SDK bindings (@opnet/ts-sdk) for frontend and Node.js consumers. The core protocol has zero JavaScript dependencies.