docs

Documentation

Welcome to the comprehensive documentation for @btc-vision/btc-runtime, the OP_NET Smart Contract Runtime for Bitcoin L1.

Quick Start

git clone https://github.com/btc-vision/example-tokens.git
cd example-tokens
npm install
npm run build:token

---

Complete Table of Contents

Getting Started

Installation

• Quick Start - Clone Example Project
• Prerequisites
• Manual Setup
  • 1. Create Project
  • 2. Install Dependencies
  • 3. Create Configuration Files
  • 4. Create Project Structure
  • 5. Build
• Adding More Contracts
• Package Dependencies
• Troubleshooting

First Contract

• What We're Building
• Step 1: Create the Contract File
• Contract Lifecycle Overview
• Step 2: Understanding the Code
  • Token Contract Architecture
  • The Class Declaration
  • The Constructor
  • The Deployment Hook
  • The Mint Function
  • Mint Operation Data Flow
• Step 3: Understanding Types
  • u256 - Big Numbers
  • Address
  • Calldata
• Step 4: Inherited OP20 Methods
• Step 5: Building the Contract
• Solidity Comparison
• Common Patterns
  • Access Control
  • Error Handling
  • Reading Storage

Project Structure

• Your Project Structure
  • Project Directory Layout
• Key Files
  • assembly/index.ts
  • asconfig.json
  • package.json Scripts
• btc-runtime Library Structure
  • Runtime Library Architecture
• Import Patterns
  • Basic Imports
  • Storage Types
  • Events
  • Contract Initialization
  • Storage Pointer System
• Contract Organization
  • Single Contract Project
  • Multi-Contract Project
  • Shared Logic
• Comparison with Solidity Projects
• Best Practices
• Testing Structure

---

Core Concepts

Blockchain Environment

• Overview
• Blockchain Singleton
• Transaction Context
• Contract Context
• Network Information
• Storage Operations
• Event Emission
• Cross-Contract Calls
• Signature Verification
• Solidity Comparison

Storage System

• Overview
• Storage Architecture
• Pointer System
• Storage Types
• Reading and Writing
• Solidity vs OP_NET Comparison
• Best Practices

Pointers

• Overview
• What is a Pointer?
• Pointer Allocation
• encodePointer
• Sub-Pointers
• Best Practices

Events

• Overview
• Event Architecture
• Creating Events
• Emitting Events
• Built-in Events
• Best Practices

Decorators

• Overview
• @method
• @returns
• @emit
• ABIDataTypes
• Complete Example

Security

• Overview
• Reentrancy Protection
• Access Control
• Input Validation
• Overflow Protection
• Best Practices

---

Contract Standards

OP_NET Base Contract

• Overview
• Contract Lifecycle
  • Inheritance Hierarchy
  • Deployment and Execution Flow
  • 1. Construction
  • 2. Deployment (onDeployment)
  • 3. Method Execution (execute)
  • Transaction Sequence
• Method Selectors
  • Solidity Comparison
• Access Control
  • onlyDeployer
  • Custom Access Control
• Event Emission
• Storage Patterns
  • Pointer Allocation
  • Storage Maps
• Complete Example
• Inheritance
  • Extending OP_NET
  • Adding Functionality
• Best Practices

OP20 Token Standard

• Overview
• ERC20 vs OP20 Comparison
• Initialization
  • OP20InitParameters
  • Decimal Limit
• Transfer Flow
  • Detailed Transfer Sequence
• Token Lifecycle
• Built-in Methods
  • Query Methods
  • Transfer Methods
  • Approval Methods
• Approval Flow
• Solidity Comparison
• Storage Layout
• Extending OP20
  • Adding Custom Methods
  • Internal Methods
• Events
  • TransferEvent
  • ApprovalEvent
• Approval Patterns
  • Standard Approval
  • Unlimited Approval
  • Increase/Decrease Pattern
• Edge Cases
  • Zero Address
  • Overflow Protection
  • Self-Approval
• Complete Token Example
• Best Practices

OP20S - Signature-Based Approvals

• Overview
• ERC20Permit vs OP20S Comparison
• Why Signature-Based Approvals?
  • Traditional Approval Flow
  • Signature-Based Flow
• Permit Flow
• Detailed Permit Sequence
• Message Construction
• Nonce Management
• Permit Method
  • Usage
  • Parameters
  • Signature Verification
• Nonces
  • Replay Protection
• Solidity Comparison (EIP-2612)
• Domain Separator
• Quantum Resistance
  • Extended Address
• Implementation Details
  • Permit Verification
  • Message Format
• Additional Methods
• Use Cases
  • 1. Off-Chain Approvals
  • 2. Single-Transaction Approve+Transfer
  • 3. Meta-Transactions
• Security Considerations
  • Deadline Selection
  • Signature Storage
  • Front-Running Protection
• Best Practices

OP721 NFT Standard

• Overview
• ERC721 vs OP721 Comparison
• Initialization
  • OP721InitParameters
• Minting Flow
• Transfer Sequence
• Safe Transfer Pattern
• NFT Lifecycle
• Token Existence States
• Built-in Methods
  • Query Methods
  • Transfer Methods
  • Approval Methods
• Solidity Comparison
• Storage Layout
• Extending OP721
  • Adding Minting
  • Adding Token URIs
  • Collection Metadata
• Internal Methods
• Enumeration
  • Swap-Last Removal Pattern
• Events
• Edge Cases
  • Token ID Uniqueness
  • Zero Token ID
  • Owner Truncation
• Complete NFT Example
• Best Practices

ReentrancyGuard

• Overview
• OpenZeppelin vs OP_NET ReentrancyGuard
• What is Reentrancy?
  • The Attack
  • The Defense
• Guard Mechanism
• Vulnerable Contract Attack
• Protected Contract Defense
• Choosing a Guard Mode
• Guard Modes
  • STANDARD Mode
  • CALLBACK Mode
• How It Works
  • Internal State
  • STANDARD Mode Logic
  • CALLBACK Mode Logic
• Usage Patterns
  • Basic Protection
  • Combined with Other Bases
  • Excluded Methods
• Solidity Comparison
• Best Practices
• Common Mistakes
• Testing Reentrancy

Updatable

• Overview
• Class Reference
  • Properties
  • Methods
• Events
• Usage Patterns
• Security Considerations
• Update Workflow
• Combining with Other Base Classes
• Solidity Comparison

---

Types & Utilities

Address

• Overview
• Creating Addresses
• Address Comparison
• Special Addresses
• Address Methods
• Solidity vs OP_NET Comparison
• Best Practices

SafeMath

• Overview
• Basic Operations
• Modular Operations
• Comparison
• Best Practices

Calldata

• Overview
• Reading Values
• Reading Arrays
• Reading Complex Types
• Solidity vs OP_NET Comparison
• Best Practices

BytesWriter/Reader

• Overview
• BytesWriter
• BytesReader
• Solidity vs OP_NET Comparison
• Migration Patterns
• Best Practices

---

Storage Types

Stored Primitives

• Overview
• Class Hierarchy
• Available Types
• Storage Key Generation
• Usage
  • StoredU256
  • StoredBoolean
  • StoredString
  • StoredAddress
• Storage Behavior
  • Lazy Loading (Value Read Flow)
  • Automatic Commit (Value Write Flow)
  • Manual Commit Control
• Initialization
  • Default Values
  • Setting Initial Values
• Solidity vs OP_NET Comparison
• Side-by-Side Code Examples
  • Counter Contract
  • Ownable Contract
• Patterns
  • Read-Modify-Write
  • Conditional Updates
  • View Functions
• Best Practices

Stored Arrays

• Overview
• Available Types
• Storage Structure
  • Size Limits
• Operations
  • Push
  • Pop
  • Get
  • Set
  • Length
• Solidity vs OP_NET Comparison
• Side-by-Side Code Examples
  • Simple Address List
  • Value Queue (FIFO-like with array)
• Common Patterns
  • Iterating
  • Finding Elements
  • Removing Elements
  • Unique Elements Set
• Use Cases
  • Token Holder Tracking
  • Order Queue
  • Whitelist Management
• Best Practices

Stored Maps

• Overview
• CRITICAL: Map Implementation Warning
• StoredMapU256
  • Storage Layout
• Using Address Keys
• Nested Maps
• MapOfMap
  • MapOfMap Get/Set Pattern
• Solidity vs OP_NET Comparison
• Side-by-Side Code Examples
  • Simple Key-Value Store
  • Approval System with Nested Mapping
• Common Patterns
  • Counter/Nonce Tracking
  • Role Management
  • Token Metadata Storage
  • Snapshot/Checkpoint Pattern
• Best Practices

Memory Maps

• Overview
• AddressMemoryMap
  • Constructor Pattern
  • Methods
• Storage Flow
  • Address to Storage Key
• Solidity vs OP_NET Comparison
• Side-by-Side Code Examples
  • Basic Token Balance Tracking
  • Staking Contract
• Usage Examples
  • Basic Balance Tracking
  • Approval Tracking
  • Staking with Multiple Values
• Storage vs Memory
  • Storage (Persistent)
  • In-Memory Collections
• Warning: AssemblyScript Map vs btc-runtime Map
• Patterns
  • Enumerable Map
  • Lazy Initialization
  • Read-Modify-Write Pattern
• Best Practices

---

Advanced Topics

Cross-Contract Calls

• Architecture Overview
• Overview
• Making Calls
  • Basic Call
  • Call Parameters
  • stopOnFailure Behavior
• Handling Results
  • CallResult Structure
  • Processing Return Data
  • Error Handling
• Common Patterns
  • Calling Token Transfers
  • Calling TransferFrom
  • Querying Another Contract
  • Multi-Call Pattern
• Solidity Comparison
• Security Considerations
  • 1. Reentrancy Risk
  • 2. Return Value Validation
  • 3. Trust Assumptions
• Advanced Patterns
  • Interface Abstraction
  • Callback Pattern

Signature Verification

• Overview
• Supported Signature Schemes
• Schnorr Signatures
• ML-DSA Signatures
• Verification API
• Solidity vs OP_NET Comparison
• Best Practices

Quantum Resistance

• Overview
• ML-DSA (FIPS 204)
• Security Levels
• The Address Class
• Migration Path
• Solidity vs OP_NET Comparison
• Best Practices

Bitcoin Scripts

• Overview
• BitcoinOpcodes
• Address Generation
  • P2WPKH
  • P2TR
  • P2WSH
• Script Building
  • P2PKH Script
  • Multisig Scripts
• Timelocks
  • CSV (CheckSequenceVerify)
  • CLTV (CheckLockTimeVerify)
• Script Analysis
• Solidity vs OP_NET Comparison
• Best Practices

Contract Updates

• Overview
• How It Works
• Basic Usage
• The Timelock Pattern
  • Why Use a Timelock?
  • Using the Updatable Base Class
  • Using the UpdatablePlugin
• Storage Compatibility
• Security Considerations
• Comparison with Other Platforms
• Complete Example
• Update Workflow

Plugins

• Overview
• Plugin Architecture
• Creating Plugins
• Lifecycle Hooks
  • onDeployment
  • onUpdate
  • onExecutionStarted
  • onExecutionCompleted
  • execute
• Built-in Plugins
• Solidity vs OP_NET Comparison
• Best Practices

---

Examples

Basic Token

• Overview
• Complete Code
• Code Walkthrough
• Solidity Comparison
• Deployment
• Testing

Stablecoin

• Overview
• Features
• Role System
• Pausability
• Blacklist
• Minter Allowances
• Complete Code
• Solidity Comparison

Oracle Integration

• Overview
• Multi-Oracle Architecture
• Price Aggregation
• Staleness Protection
• Deviation Checks
• Complete Code
• Solidity Comparison

NFT with Reservations

• Overview
• Sale Phases
• Reservation System
• Whitelist
• Reveal Mechanism
• Complete Code
• Solidity Comparison

---

API Reference

Blockchain

• Overview
• Properties
• Transaction Context
• Contract Context
• Network Context
• Storage Architecture
• Storage Methods
• Event Methods
• Cross-Contract Methods
• Signature Methods

OP20

• Overview
• Initialization
• Query Methods
• Transfer Methods
• Approval Methods
• Internal Methods
• Events

OP721

• Overview
• Initialization
• Query Methods
• Transfer Methods
• Approval Methods
• Internal Methods
• Events

SafeMath

• Overview
• Basic Operations
• Modular Operations
• Signed Operations

Storage

• Overview
• StoredU256
• StoredU64
• StoredBoolean
• StoredString
• StoredAddress
• StoredU256Array
• StoredAddressArray
• StoredMapU256
• AddressMemoryMap

Events

• Overview
• NetEvent Base Class
• Creating Custom Events
• Emitting Events
• Predefined Events

---

Quick Links

• Example Tokens Repository
• btc-runtime Repository
• OP_NET Website

Solidity Developer?

Every documentation page includes Solidity Comparison sections with side-by-side code examples. Start with:

• First Contract - Solidity Comparison
• OP20 vs ERC20
• OP721 vs ERC721