@btc-vision/btc-runtime/docs/README.md

Bitcoin L1 Smart Contract Runtime for OP_NET. Build decentralized applications on Bitcoin using AssemblyScript and WebAssembly. Fully audited.

# Documentation

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

## Quick Start

```bash
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](./getting-started/installation.md)
- [Quick Start - Clone Example Project](./getting-started/installation.md#quick-start---clone-example-project)
- [Prerequisites](./getting-started/installation.md#prerequisites)
- [Manual Setup](./getting-started/installation.md#manual-setup)
  - [1. Create Project](./getting-started/installation.md#1-create-project)
  - [2. Install Dependencies](./getting-started/installation.md#2-install-dependencies)
  - [3. Create Configuration Files](./getting-started/installation.md#3-create-configuration-files)
  - [4. Create Project Structure](./getting-started/installation.md#4-create-project-structure)
  - [5. Build](./getting-started/installation.md#5-build)
- [Adding More Contracts](./getting-started/installation.md#adding-more-contracts)
- [Package Dependencies](./getting-started/installation.md#package-dependencies)
- [Troubleshooting](./getting-started/installation.md#troubleshooting)

#### [First Contract](./getting-started/first-contract.md)
- [What We're Building](./getting-started/first-contract.md#what-were-building)
- [Step 1: Create the Contract File](./getting-started/first-contract.md#step-1-create-the-contract-file)
- [Contract Lifecycle Overview](./getting-started/first-contract.md#contract-lifecycle-overview)
- [Step 2: Understanding the Code](./getting-started/first-contract.md#step-2-understanding-the-code)
  - [Token Contract Architecture](./getting-started/first-contract.md#token-contract-architecture)
  - [The Class Declaration](./getting-started/first-contract.md#the-class-declaration)
  - [The Constructor](./getting-started/first-contract.md#the-constructor)
  - [The Deployment Hook](./getting-started/first-contract.md#the-deployment-hook)
  - [The Mint Function](./getting-started/first-contract.md#the-mint-function)
  - [Mint Operation Data Flow](./getting-started/first-contract.md#mint-operation-data-flow)
- [Step 3: Understanding Types](./getting-started/first-contract.md#step-3-understanding-types)
  - [u256 - Big Numbers](./getting-started/first-contract.md#u256---big-numbers)
  - [Address](./getting-started/first-contract.md#address)
  - [Calldata](./getting-started/first-contract.md#calldata)
- [Step 4: Inherited OP20 Methods](./getting-started/first-contract.md#step-4-inherited-op20-methods)
- [Step 5: Building the Contract](./getting-started/first-contract.md#step-5-building-the-contract)
- [Solidity Comparison](./getting-started/first-contract.md#solidity-comparison)
- [Common Patterns](./getting-started/first-contract.md#common-patterns)
  - [Access Control](./getting-started/first-contract.md#access-control)
  - [Error Handling](./getting-started/first-contract.md#error-handling)
  - [Reading Storage](./getting-started/first-contract.md#reading-storage)

#### [Project Structure](./getting-started/project-structure.md)
- [Your Project Structure](./getting-started/project-structure.md#your-project-structure)
  - [Project Directory Layout](./getting-started/project-structure.md#project-directory-layout)
- [Key Files](./getting-started/project-structure.md#key-files)
  - [assembly/index.ts](./getting-started/project-structure.md#assemblyindexts)
  - [asconfig.json](./getting-started/project-structure.md#asconfigjson)
  - [package.json Scripts](./getting-started/project-structure.md#packagejson-scripts)
- [btc-runtime Library Structure](./getting-started/project-structure.md#btc-runtime-library-structure)
  - [Runtime Library Architecture](./getting-started/project-structure.md#runtime-library-architecture)
- [Import Patterns](./getting-started/project-structure.md#import-patterns)
  - [Basic Imports](./getting-started/project-structure.md#basic-imports)
  - [Storage Types](./getting-started/project-structure.md#storage-types)
  - [Events](./getting-started/project-structure.md#events)
  - [Contract Initialization](./getting-started/project-structure.md#contract-initialization)
  - [Storage Pointer System](./getting-started/project-structure.md#storage-pointer-system)
- [Contract Organization](./getting-started/project-structure.md#contract-organization)
  - [Single Contract Project](./getting-started/project-structure.md#single-contract-project)
  - [Multi-Contract Project](./getting-started/project-structure.md#multi-contract-project)
  - [Shared Logic](./getting-started/project-structure.md#shared-logic)
- [Comparison with Solidity Projects](./getting-started/project-structure.md#comparison-with-solidity-projects)
- [Best Practices](./getting-started/project-structure.md#best-practices)
- [Testing Structure](./getting-started/project-structure.md#testing-structure)

---

### Core Concepts

#### [Blockchain Environment](./core-concepts/blockchain-environment.md)
- [Overview](./core-concepts/blockchain-environment.md#overview)
- [Blockchain Singleton](./core-concepts/blockchain-environment.md#blockchain-singleton)
- [Transaction Context](./core-concepts/blockchain-environment.md#transaction-context)
- [Contract Context](./core-concepts/blockchain-environment.md#contract-context)
- [Network Information](./core-concepts/blockchain-environment.md#network-information)
- [Storage Operations](./core-concepts/blockchain-environment.md#storage-operations)
- [Event Emission](./core-concepts/blockchain-environment.md#event-emission)
- [Cross-Contract Calls](./core-concepts/blockchain-environment.md#cross-contract-calls)
- [Signature Verification](./core-concepts/blockchain-environment.md#signature-verification)
- [Solidity Comparison](./core-concepts/blockchain-environment.md#solidity-comparison)

#### [Storage System](./core-concepts/storage-system.md)
- [Overview](./core-concepts/storage-system.md#overview)
- [Storage Architecture](./core-concepts/storage-system.md#storage-architecture)
- [Pointer System](./core-concepts/storage-system.md#pointer-system)
- [Storage Types](./core-concepts/storage-system.md#storage-types)
- [Reading and Writing](./core-concepts/storage-system.md#reading-and-writing)
- [Solidity vs OP_NET Comparison](./core-concepts/storage-system.md#solidity-vs-opnet-comparison)
- [Best Practices](./core-concepts/storage-system.md#best-practices)

#### [Pointers](./core-concepts/pointers.md)
- [Overview](./core-concepts/pointers.md#overview)
- [What is a Pointer?](./core-concepts/pointers.md#what-is-a-pointer)
- [Pointer Allocation](./core-concepts/pointers.md#pointer-allocation)
- [encodePointer](./core-concepts/pointers.md#encodepointer)
- [Sub-Pointers](./core-concepts/pointers.md#sub-pointers)
- [Best Practices](./core-concepts/pointers.md#best-practices)

#### [Events](./core-concepts/events.md)
- [Overview](./core-concepts/events.md#overview)
- [Event Architecture](./core-concepts/events.md#event-architecture)
- [Creating Events](./core-concepts/events.md#creating-events)
- [Emitting Events](./core-concepts/events.md#emitting-events)
- [Built-in Events](./core-concepts/events.md#built-in-events)
- [Best Practices](./core-concepts/events.md#best-practices)

#### [Decorators](./core-concepts/decorators.md)
- [Overview](./core-concepts/decorators.md#overview)
- [@method](./core-concepts/decorators.md#method)
- [@returns](./core-concepts/decorators.md#returns)
- [@emit](./core-concepts/decorators.md#emit)
- [ABIDataTypes](./core-concepts/decorators.md#abidatatypes)
- [Complete Example](./core-concepts/decorators.md#complete-example)

#### [Security](./core-concepts/security.md)
- [Overview](./core-concepts/security.md#overview)
- [Reentrancy Protection](./core-concepts/security.md#reentrancy-protection)
- [Access Control](./core-concepts/security.md#access-control)
- [Input Validation](./core-concepts/security.md#input-validation)
- [Overflow Protection](./core-concepts/security.md#overflow-protection)
- [Best Practices](./core-concepts/security.md#best-practices)

---

### Contract Standards

#### [OP_NET Base Contract](./contracts/op-net-base.md)
- [Overview](./contracts/op-net-base.md#overview)
- [Contract Lifecycle](./contracts/op-net-base.md#contract-lifecycle)
  - [Inheritance Hierarchy](./contracts/op-net-base.md#inheritance-hierarchy)
  - [Deployment and Execution Flow](./contracts/op-net-base.md#deployment-and-execution-flow)
  - [1. Construction](./contracts/op-net-base.md#1-construction)
  - [2. Deployment (onDeployment)](./contracts/op-net-base.md#2-deployment-ondeployment)
  - [3. Method Execution (execute)](./contracts/op-net-base.md#3-method-execution-execute)
  - [Transaction Sequence](./contracts/op-net-base.md#transaction-sequence)
- [Method Selectors](./contracts/op-net-base.md#method-selectors)
  - [Solidity Comparison](./contracts/op-net-base.md#solidity-comparison)
- [Access Control](./contracts/op-net-base.md#access-control)
  - [onlyDeployer](./contracts/op-net-base.md#onlydeployer)
  - [Custom Access Control](./contracts/op-net-base.md#custom-access-control)
- [Event Emission](./contracts/op-net-base.md#event-emission)
- [Storage Patterns](./contracts/op-net-base.md#storage-patterns)
  - [Pointer Allocation](./contracts/op-net-base.md#pointer-allocation)
  - [Storage Maps](./contracts/op-net-base.md#storage-maps)
- [Complete Example](./contracts/op-net-base.md#complete-example)
- [Inheritance](./contracts/op-net-base.md#inheritance)
  - [Extending OP_NET](./contracts/op-net-base.md#extending-op_net)
  - [Adding Functionality](./contracts/op-net-base.md#adding-functionality)
- [Best Practices](./contracts/op-net-base.md#best-practices)

#### [OP20 Token Standard](./contracts/op20-token.md)
- [Overview](./contracts/op20-token.md#overview)
- [ERC20 vs OP20 Comparison](./contracts/op20-token.md#erc20-vs-op20-comparison)
- [Initialization](./contracts/op20-token.md#initialization)
  - [OP20InitParameters](./contracts/op20-token.md#op20initparameters)
  - [Decimal Limit](./contracts/op20-token.md#decimal-limit)
- [Transfer Flow](./contracts/op20-token.md#transfer-flow)
  - [Detailed Transfer Sequence](./contracts/op20-token.md#detailed-transfer-sequence)
- [Token Lifecycle](./contracts/op20-token.md#token-lifecycle)
- [Built-in Methods](./contracts/op20-token.md#built-in-methods)
  - [Query Methods](./contracts/op20-token.md#query-methods)
  - [Transfer Methods](./contracts/op20-token.md#transfer-methods)
  - [Approval Methods](./contracts/op20-token.md#approval-methods)
- [Approval Flow](./contracts/op20-token.md#approval-flow)
- [Solidity Comparison](./contracts/op20-token.md#solidity-comparison)
- [Storage Layout](./contracts/op20-token.md#storage-layout)
- [Extending OP20](./contracts/op20-token.md#extending-op20)
  - [Adding Custom Methods](./contracts/op20-token.md#adding-custom-methods)
  - [Internal Methods](./contracts/op20-token.md#internal-methods)
- [Events](./contracts/op20-token.md#events)
  - [TransferEvent](./contracts/op20-token.md#transferevent)
  - [ApprovalEvent](./contracts/op20-token.md#approvalevent)
- [Approval Patterns](./contracts/op20-token.md#approval-patterns)
  - [Standard Approval](./contracts/op20-token.md#standard-approval)
  - [Unlimited Approval](./contracts/op20-token.md#unlimited-approval)
  - [Increase/Decrease Pattern](./contracts/op20-token.md#increasedecrease-pattern)
- [Edge Cases](./contracts/op20-token.md#edge-cases)
  - [Zero Address](./contracts/op20-token.md#zero-address)
  - [Overflow Protection](./contracts/op20-token.md#overflow-protection)
  - [Self-Approval](./contracts/op20-token.md#self-approval)
- [Complete Token Example](./contracts/op20-token.md#complete-token-example)
- [Best Practices](./contracts/op20-token.md#best-practices)

#### [OP20S - Signature-Based Approvals](./contracts/op20s-signatures.md)
- [Overview](./contracts/op20s-signatures.md#overview)
- [ERC20Permit vs OP20S Comparison](./contracts/op20s-signatures.md#erc20permit-vs-op20s-comparison)
- [Why Signature-Based Approvals?](./contracts/op20s-signatures.md#why-signature-based-approvals)
  - [Traditional Approval Flow](./contracts/op20s-signatures.md#traditional-approval-flow)
  - [Signature-Based Flow](./contracts/op20s-signatures.md#signature-based-flow)
- [Permit Flow](./contracts/op20s-signatures.md#permit-flow)
- [Detailed Permit Sequence](./contracts/op20s-signatures.md#detailed-permit-sequence)
- [Message Construction](./contracts/op20s-signatures.md#message-construction)
- [Nonce Management](./contracts/op20s-signatures.md#nonce-management)
- [Permit Method](./contracts/op20s-signatures.md#permit-method)
  - [Usage](./contracts/op20s-signatures.md#usage)
  - [Parameters](./contracts/op20s-signatures.md#parameters)
  - [Signature Verification](./contracts/op20s-signatures.md#signature-verification)
- [Nonces](./contracts/op20s-signatures.md#nonces)
  - [Replay Protection](./contracts/op20s-signatures.md#replay-protection)
- [Solidity Comparison (EIP-2612)](./contracts/op20s-signatures.md#solidity-comparison-eip-2612)
- [Domain Separator](./contracts/op20s-signatures.md#domain-separator)
- [Quantum Resistance](./contracts/op20s-signatures.md#quantum-resistance)
  - [Extended Address](./contracts/op20s-signatures.md#extended-address)
- [Implementation Details](./contracts/op20s-signatures.md#implementation-details)
  - [Permit Verification](./contracts/op20s-signatures.md#permit-verification)
  - [Message Format](./contracts/op20s-signatures.md#message-format)
- [Additional Methods](./contracts/op20s-signatures.md#additional-methods)
- [Use Cases](./contracts/op20s-signatures.md#use-cases)
  - [1. Off-Chain Approvals](./contracts/op20s-signatures.md#1-off-chain-approvals)
  - [2. Single-Transaction Approve+Transfer](./contracts/op20s-signatures.md#2-single-transaction-approvetransfer)
  - [3. Meta-Transactions](./contracts/op20s-signatures.md#3-meta-transactions)
- [Security Considerations](./contracts/op20s-signatures.md#security-considerations)
  - [Deadline Selection](./contracts/op20s-signatures.md#deadline-selection)
  - [Signature Storage](./contracts/op20s-signatures.md#signature-storage)
  - [Front-Running Protection](./contracts/op20s-signatures.md#front-running-protection)
- [Best Practices](./contracts/op20s-signatures.md#best-practices)

#### [OP721 NFT Standard](./contracts/op721-nft.md)
- [Overview](./contracts/op721-nft.md#overview)
- [ERC721 vs OP721 Comparison](./contracts/op721-nft.md#erc721-vs-op721-comparison)
- [Initialization](./contracts/op721-nft.md#initialization)
  - [OP721InitParameters](./contracts/op721-nft.md#op721initparameters)
- [Minting Flow](./contracts/op721-nft.md#minting-flow)
- [Transfer Sequence](./contracts/op721-nft.md#transfer-sequence)
- [Safe Transfer Pattern](./contracts/op721-nft.md#safe-transfer-pattern)
- [NFT Lifecycle](./contracts/op721-nft.md#nft-lifecycle)
- [Token Existence States](./contracts/op721-nft.md#token-existence-states)
- [Built-in Methods](./contracts/op721-nft.md#built-in-methods)
  - [Query Methods](./contracts/op721-nft.md#query-methods)
  - [Transfer Methods](./contracts/op721-nft.md#transfer-methods)
  - [Approval Methods](./contracts/op721-nft.md#approval-methods)
- [Solidity Comparison](./contracts/op721-nft.md#solidity-comparison)
- [Storage Layout](./contracts/op721-nft.md#storage-layout)
- [Extending OP721](./contracts/op721-nft.md#extending-op721)
  - [Adding Minting](./contracts/op721-nft.md#adding-minting)
  - [Adding Token URIs](./contracts/op721-nft.md#adding-token-uris)
  - [Collection Metadata](./contracts/op721-nft.md#collection-metadata)
- [Internal Methods](./contracts/op721-nft.md#internal-methods)
- [Enumeration](./contracts/op721-nft.md#enumeration)
  - [Swap-Last Removal Pattern](./contracts/op721-nft.md#swap-last-removal-pattern)
- [Events](./contracts/op721-nft.md#events)
- [Edge Cases](./contracts/op721-nft.md#edge-cases)
  - [Token ID Uniqueness](./contracts/op721-nft.md#token-id-uniqueness)
  - [Zero Token ID](./contracts/op721-nft.md#zero-token-id)
  - [Owner Truncation](./contracts/op721-nft.md#owner-truncation)
- [Complete NFT Example](./contracts/op721-nft.md#complete-nft-example)
- [Best Practices](./contracts/op721-nft.md#best-practices)

#### [ReentrancyGuard](./contracts/reentrancy-guard.md)
- [Overview](./contracts/reentrancy-guard.md#overview)
- [OpenZeppelin vs OP_NET ReentrancyGuard](./contracts/reentrancy-guard.md#openzeppelin-vs-opnet-reentrancyguard)
- [What is Reentrancy?](./contracts/reentrancy-guard.md#what-is-reentrancy)
  - [The Attack](./contracts/reentrancy-guard.md#the-attack)
  - [The Defense](./contracts/reentrancy-guard.md#the-defense)
- [Guard Mechanism](./contracts/reentrancy-guard.md#guard-mechanism)
- [Vulnerable Contract Attack](./contracts/reentrancy-guard.md#vulnerable-contract-attack)
- [Protected Contract Defense](./contracts/reentrancy-guard.md#protected-contract-defense)
- [Choosing a Guard Mode](./contracts/reentrancy-guard.md#choosing-a-guard-mode)
- [Guard Modes](./contracts/reentrancy-guard.md#guard-modes)
  - [STANDARD Mode](./contracts/reentrancy-guard.md#standard-mode)
  - [CALLBACK Mode](./contracts/reentrancy-guard.md#callback-mode)
- [How It Works](./contracts/reentrancy-guard.md#how-it-works)
  - [Internal State](./contracts/reentrancy-guard.md#internal-state)
  - [STANDARD Mode Logic](./contracts/reentrancy-guard.md#standard-mode-logic)
  - [CALLBACK Mode Logic](./contracts/reentrancy-guard.md#callback-mode-logic)
- [Usage Patterns](./contracts/reentrancy-guard.md#usage-patterns)
  - [Basic Protection](./contracts/reentrancy-guard.md#basic-protection)
  - [Combined with Other Bases](./contracts/reentrancy-guard.md#combined-with-other-bases)
  - [Excluded Methods](./contracts/reentrancy-guard.md#excluded-methods)
- [Solidity Comparison](./contracts/reentrancy-guard.md#solidity-comparison)
- [Best Practices](./contracts/reentrancy-guard.md#best-practices)
- [Common Mistakes](./contracts/reentrancy-guard.md#common-mistakes)
- [Testing Reentrancy](./contracts/reentrancy-guard.md#testing-reentrancy)

#### [Updatable](./contracts/updatable.md)
- [Overview](./contracts/updatable.md#overview)
- [Class Reference](./contracts/updatable.md#class-reference)
  - [Properties](./contracts/updatable.md#properties)
  - [Methods](./contracts/updatable.md#methods)
- [Events](./contracts/updatable.md#events)
- [Usage Patterns](./contracts/updatable.md#usage-patterns)
- [Security Considerations](./contracts/updatable.md#security-considerations)
- [Update Workflow](./contracts/updatable.md#update-workflow)
- [Combining with Other Base Classes](./contracts/updatable.md#combining-with-other-base-classes)
- [Solidity Comparison](./contracts/updatable.md#solidity-comparison)

---

### Types & Utilities

#### [Address](./types/address.md)
- [Overview](./types/address.md#overview)
- [Creating Addresses](./types/address.md#creating-addresses)
- [Address Comparison](./types/address.md#address-comparison)
- [Special Addresses](./types/address.md#special-addresses)
- [Address Methods](./types/address.md#address-methods)
- [Solidity vs OP_NET Comparison](./types/address.md#solidity-vs-opnet-comparison)
- [Best Practices](./types/address.md#best-practices)

#### [SafeMath](./types/safe-math.md)
- [Overview](./types/safe-math.md#overview)
- [Basic Operations](./types/safe-math.md#basic-operations)
- [Modular Operations](./types/safe-math.md#modular-operations)
- [Comparison](./types/safe-math.md#comparison)
- [Best Practices](./types/safe-math.md#best-practices)

#### [Calldata](./types/calldata.md)
- [Overview](./types/calldata.md#overview)
- [Reading Values](./types/calldata.md#reading-values)
- [Reading Arrays](./types/calldata.md#reading-arrays)
- [Reading Complex Types](./types/calldata.md#reading-complex-types)
- [Solidity vs OP_NET Comparison](./types/calldata.md#solidity-vs-opnet-comparison)
- [Best Practices](./types/calldata.md#best-practices)

#### [BytesWriter/Reader](./types/bytes-writer-reader.md)
- [Overview](./types/bytes-writer-reader.md#overview)
- [BytesWriter](./types/bytes-writer-reader.md#byteswriter)
- [BytesReader](./types/bytes-writer-reader.md#bytesreader)
- [Solidity vs OP_NET Comparison](./types/bytes-writer-reader.md#solidity-vs-opnet-comparison)
- [Migration Patterns](./types/bytes-writer-reader.md#migration-patterns)
- [Best Practices](./types/bytes-writer-reader.md#best-practices)

---

### Storage Types

#### [Stored Primitives](./storage/stored-primitives.md)
- [Overview](./storage/stored-primitives.md#overview)
- [Class Hierarchy](./storage/stored-primitives.md#class-hierarchy)
- [Available Types](./storage/stored-primitives.md#available-types)
- [Storage Key Generation](./storage/stored-primitives.md#storage-key-generation)
- [Usage](./storage/stored-primitives.md#usage)
  - [StoredU256](./storage/stored-primitives.md#storedu256)
  - [StoredBoolean](./storage/stored-primitives.md#storedboolean)
  - [StoredString](./storage/stored-primitives.md#storedstring)
  - [StoredAddress](./storage/stored-primitives.md#storedaddress)
- [Storage Behavior](./storage/stored-primitives.md#storage-behavior)
  - [Lazy Loading (Value Read Flow)](./storage/stored-primitives.md#lazy-loading-value-read-flow)
  - [Automatic Commit (Value Write Flow)](./storage/stored-primitives.md#automatic-commit-value-write-flow)
  - [Manual Commit Control](./storage/stored-primitives.md#manual-commit-control)
- [Initialization](./storage/stored-primitives.md#initialization)
  - [Default Values](./storage/stored-primitives.md#default-values)
  - [Setting Initial Values](./storage/stored-primitives.md#setting-initial-values)
- [Solidity vs OP_NET Comparison](./storage/stored-primitives.md#solidity-vs-opnet-comparison)
- [Side-by-Side Code Examples](./storage/stored-primitives.md#side-by-side-code-examples)
  - [Counter Contract](./storage/stored-primitives.md#counter-contract)
  - [Ownable Contract](./storage/stored-primitives.md#ownable-contract)
- [Patterns](./storage/stored-primitives.md#patterns)
  - [Read-Modify-Write](./storage/stored-primitives.md#read-modify-write)
  - [Conditional Updates](./storage/stored-primitives.md#conditional-updates)
  - [View Functions](./storage/stored-primitives.md#view-functions)
- [Best Practices](./storage/stored-primitives.md#best-practices)

#### [Stored Arrays](./storage/stored-arrays.md)
- [Overview](./storage/stored-arrays.md#overview)
- [Available Types](./storage/stored-arrays.md#available-types)
- [Storage Structure](./storage/stored-arrays.md#storage-structure)
  - [Size Limits](./storage/stored-arrays.md#size-limits)
- [Operations](./storage/stored-arrays.md#operations)
  - [Push](./storage/stored-arrays.md#push)
  - [Pop](./storage/stored-arrays.md#pop)
  - [Get](./storage/stored-arrays.md#get)
  - [Set](./storage/stored-arrays.md#set)
  - [Length](./storage/stored-arrays.md#length)
- [Solidity vs OP_NET Comparison](./storage/stored-arrays.md#solidity-vs-opnet-comparison)
- [Side-by-Side Code Examples](./storage/stored-arrays.md#side-by-side-code-examples)
  - [Simple Address List](./storage/stored-arrays.md#simple-address-list)
  - [Value Queue (FIFO-like with array)](./storage/stored-arrays.md#value-queue-fifo-like-with-array)
- [Common Patterns](./storage/stored-arrays.md#common-patterns)
  - [Iterating](./storage/stored-arrays.md#iterating)
  - [Finding Elements](./storage/stored-arrays.md#finding-elements)
  - [Removing Elements](./storage/stored-arrays.md#removing-elements)
  - [Unique Elements Set](./storage/stored-arrays.md#unique-elements-set)
- [Use Cases](./storage/stored-arrays.md#use-cases)
  - [Token Holder Tracking](./storage/stored-arrays.md#token-holder-tracking)
  - [Order Queue](./storage/stored-arrays.md#order-queue)
  - [Whitelist Management](./storage/stored-arrays.md#whitelist-management)
- [Best Practices](./storage/stored-arrays.md#best-practices)

#### [Stored Maps](./storage/stored-maps.md)
- [Overview](./storage/stored-maps.md#overview)
- [CRITICAL: Map Implementation Warning](./storage/stored-maps.md#critical-map-implementation-warning)
- [StoredMapU256](./storage/stored-maps.md#storedmapu256)
  - [Storage Layout](./storage/stored-maps.md#storage-layout)
- [Using Address Keys](./storage/stored-maps.md#using-address-keys)
- [Nested Maps](./storage/stored-maps.md#nested-maps)
- [MapOfMap](./storage/stored-maps.md#mapofmap)
  - [MapOfMap Get/Set Pattern](./storage/stored-maps.md#mapofmap-getset-pattern)
- [Solidity vs OP_NET Comparison](./storage/stored-maps.md#solidity-vs-opnet-comparison)
- [Side-by-Side Code Examples](./storage/stored-maps.md#side-by-side-code-examples)
  - [Simple Key-Value Store](./storage/stored-maps.md#simple-key-value-store)
  - [Approval System with Nested Mapping](./storage/stored-maps.md#approval-system-with-nested-mapping)
- [Common Patterns](./storage/stored-maps.md#common-patterns)
  - [Counter/Nonce Tracking](./storage/stored-maps.md#counternonce-tracking)
  - [Role Management](./storage/stored-maps.md#role-management)
  - [Token Metadata Storage](./storage/stored-maps.md#token-metadata-storage)
  - [Snapshot/Checkpoint Pattern](./storage/stored-maps.md#snapshotcheckpoint-pattern)
- [Best Practices](./storage/stored-maps.md#best-practices)

#### [Memory Maps](./storage/memory-maps.md)
- [Overview](./storage/memory-maps.md#overview)
- [AddressMemoryMap](./storage/memory-maps.md#addressmemorymap)
  - [Constructor Pattern](./storage/memory-maps.md#constructor-pattern)
  - [Methods](./storage/memory-maps.md#methods)
- [Storage Flow](./storage/memory-maps.md#storage-flow)
  - [Address to Storage Key](./storage/memory-maps.md#address-to-storage-key)
- [Solidity vs OP_NET Comparison](./storage/memory-maps.md#solidity-vs-opnet-comparison)
- [Side-by-Side Code Examples](./storage/memory-maps.md#side-by-side-code-examples)
  - [Basic Token Balance Tracking](./storage/memory-maps.md#basic-token-balance-tracking)
  - [Staking Contract](./storage/memory-maps.md#staking-contract)
- [Usage Examples](./storage/memory-maps.md#usage-examples)
  - [Basic Balance Tracking](./storage/memory-maps.md#basic-balance-tracking)
  - [Approval Tracking](./storage/memory-maps.md#approval-tracking)
  - [Staking with Multiple Values](./storage/memory-maps.md#staking-with-multiple-values)
- [Storage vs Memory](./storage/memory-maps.md#storage-vs-memory)
  - [Storage (Persistent)](./storage/memory-maps.md#storage-persistent)
  - [In-Memory Collections](./storage/memory-maps.md#in-memory-collections)
- [Warning: AssemblyScript Map vs btc-runtime Map](./storage/memory-maps.md#warning-assemblyscript-map-vs-btc-runtime-map)
- [Patterns](./storage/memory-maps.md#patterns)
  - [Enumerable Map](./storage/memory-maps.md#enumerable-map)
  - [Lazy Initialization](./storage/memory-maps.md#lazy-initialization)
  - [Read-Modify-Write Pattern](./storage/memory-maps.md#read-modify-write-pattern)
- [Best Practices](./storage/memory-maps.md#best-practices)

---

### Advanced Topics

#### [Cross-Contract Calls](./advanced/cross-contract-calls.md)
- [Architecture Overview](./advanced/cross-contract-calls.md#architecture-overview)
- [Overview](./advanced/cross-contract-calls.md#overview)
- [Making Calls](./advanced/cross-contract-calls.md#making-calls)
  - [Basic Call](./advanced/cross-contract-calls.md#basic-call)
  - [Call Parameters](./advanced/cross-contract-calls.md#call-parameters)
  - [stopOnFailure Behavior](./advanced/cross-contract-calls.md#stoponfailure-behavior)
- [Handling Results](./advanced/cross-contract-calls.md#handling-results)
  - [CallResult Structure](./advanced/cross-contract-calls.md#callresult-structure)
  - [Processing Return Data](./advanced/cross-contract-calls.md#processing-return-data)
  - [Error Handling](./advanced/cross-contract-calls.md#error-handling)
- [Common Patterns](./advanced/cross-contract-calls.md#common-patterns)
  - [Calling Token Transfers](./advanced/cross-contract-calls.md#calling-token-transfers)
  - [Calling TransferFrom](./advanced/cross-contract-calls.md#calling-transferfrom)
  - [Querying Another Contract](./advanced/cross-contract-calls.md#querying-another-contract)
  - [Multi-Call Pattern](./advanced/cross-contract-calls.md#multi-call-pattern)
- [Solidity Comparison](./advanced/cross-contract-calls.md#solidity-comparison)
- [Security Considerations](./advanced/cross-contract-calls.md#security-considerations)
  - [1. Reentrancy Risk](./advanced/cross-contract-calls.md#1-reentrancy-risk)
  - [2. Return Value Validation](./advanced/cross-contract-calls.md#2-return-value-validation)
  - [3. Trust Assumptions](./advanced/cross-contract-calls.md#3-trust-assumptions)
- [Advanced Patterns](./advanced/cross-contract-calls.md#advanced-patterns)
  - [Interface Abstraction](./advanced/cross-contract-calls.md#interface-abstraction)
  - [Callback Pattern](./advanced/cross-contract-calls.md#callback-pattern)

#### [Signature Verification](./advanced/signature-verification.md)
- [Overview](./advanced/signature-verification.md#overview)
- [Supported Signature Schemes](./advanced/signature-verification.md#supported-signature-schemes)
- [Schnorr Signatures](./advanced/signature-verification.md#schnorr-signatures)
- [ML-DSA Signatures](./advanced/signature-verification.md#ml-dsa-signatures)
- [Verification API](./advanced/signature-verification.md#verification-api)
- [Solidity vs OP_NET Comparison](./advanced/signature-verification.md#solidity-vs-opnet-comparison)
- [Best Practices](./advanced/signature-verification.md#best-practices)

#### [Quantum Resistance](./advanced/quantum-resistance.md)
- [Overview](./advanced/quantum-resistance.md#overview)
- [ML-DSA (FIPS 204)](./advanced/quantum-resistance.md#ml-dsa-fips-204)
- [Security Levels](./advanced/quantum-resistance.md#security-levels)
- [The Address Class](./advanced/quantum-resistance.md#the-address-class)
- [Migration Path](./advanced/quantum-resistance.md#migration-path)
- [Solidity vs OP_NET Comparison](./advanced/quantum-resistance.md#solidity-vs-opnet-comparison)
- [Best Practices](./advanced/quantum-resistance.md#best-practices)

#### [Bitcoin Scripts](./advanced/bitcoin-scripts.md)
- [Overview](./advanced/bitcoin-scripts.md#overview)
- [BitcoinOpcodes](./advanced/bitcoin-scripts.md#bitcoinopcodes)
- [Address Generation](./advanced/bitcoin-scripts.md#address-generation)
  - [P2WPKH](./advanced/bitcoin-scripts.md#p2wpkh)
  - [P2TR](./advanced/bitcoin-scripts.md#p2tr)
  - [P2WSH](./advanced/bitcoin-scripts.md#p2wsh)
- [Script Building](./advanced/bitcoin-scripts.md#script-building)
  - [P2PKH Script](./advanced/bitcoin-scripts.md#p2pkh-script)
  - [Multisig Scripts](./advanced/bitcoin-scripts.md#multisig-scripts)
- [Timelocks](./advanced/bitcoin-scripts.md#timelocks)
  - [CSV (CheckSequenceVerify)](./advanced/bitcoin-scripts.md#csv-checksequenceverify)
  - [CLTV (CheckLockTimeVerify)](./advanced/bitcoin-scripts.md#cltv-checklockimeverify)
- [Script Analysis](./advanced/bitcoin-scripts.md#script-analysis)
- [Solidity vs OP_NET Comparison](./advanced/bitcoin-scripts.md#solidity-vs-opnet-comparison)
- [Best Practices](./advanced/bitcoin-scripts.md#best-practices)

#### [Contract Updates](./advanced/updatable)
- [Overview](./advanced/updatable#overview)
- [How It Works](./advanced/updatable#how-it-works)
- [Basic Usage](./advanced/updatable#basic-usage)
- [The Timelock Pattern](./advanced/updatable#the-timelock-pattern)
  - [Why Use a Timelock?](./advanced/updatable#why-use-a-timelock)
  - [Using the Updatable Base Class](./advanced/updatable#using-the-updatable-base-class)
  - [Using the UpdatablePlugin](./advanced/updatable#using-the-updatableplugin)
- [Storage Compatibility](./advanced/updatable#storage-compatibility)
- [Security Considerations](./advanced/updatable#security-considerations)
- [Comparison with Other Platforms](./advanced/updatable#comparison-with-other-platforms)
- [Complete Example](./advanced/updatable#complete-example)
- [Update Workflow](./advanced/updatable#update-workflow)

#### [Plugins](./advanced/plugins.md)
- [Overview](./advanced/plugins.md#overview)
- [Plugin Architecture](./advanced/plugins.md#plugin-architecture)
- [Creating Plugins](./advanced/plugins.md#creating-plugins)
- [Lifecycle Hooks](./advanced/plugins.md#lifecycle-hooks)
  - [onDeployment](./advanced/plugins.md#ondeployment)
  - [onUpdate](./advanced/plugins.md#onupdate)
  - [onExecutionStarted](./advanced/plugins.md#onexecutionstarted)
  - [onExecutionCompleted](./advanced/plugins.md#onexecutioncompleted)
  - [execute](./advanced/plugins.md#execute)
- [Built-in Plugins](./advanced/plugins.md#built-in-plugins)
- [Solidity vs OP_NET Comparison](./advanced/plugins.md#solidity-vs-opnet-comparison)
- [Best Practices](./advanced/plugins.md#best-practices)

---

### Examples

#### [Basic Token](./examples/basic-token.md)
- [Overview](./examples/basic-token.md#overview)
- [Complete Code](./examples/basic-token.md#complete-code)
- [Code Walkthrough](./examples/basic-token.md#code-walkthrough)
- [Solidity Comparison](./examples/basic-token.md#solidity-comparison)
- [Deployment](./examples/basic-token.md#deployment)
- [Testing](./examples/basic-token.md#testing)

#### [Stablecoin](./examples/stablecoin.md)
- [Overview](./examples/stablecoin.md#overview)
- [Features](./examples/stablecoin.md#features)
- [Role System](./examples/stablecoin.md#role-system)
- [Pausability](./examples/stablecoin.md#pausability)
- [Blacklist](./examples/stablecoin.md#blacklist)
- [Minter Allowances](./examples/stablecoin.md#minter-allowances)
- [Complete Code](./examples/stablecoin.md#complete-code)
- [Solidity Comparison](./examples/stablecoin.md#solidity-comparison)

#### [Oracle Integration](./examples/oracle-integration.md)
- [Overview](./examples/oracle-integration.md#overview)
- [Multi-Oracle Architecture](./examples/oracle-integration.md#multi-oracle-architecture)
- [Price Aggregation](./examples/oracle-integration.md#price-aggregation)
- [Staleness Protection](./examples/oracle-integration.md#staleness-protection)
- [Deviation Checks](./examples/oracle-integration.md#deviation-checks)
- [Complete Code](./examples/oracle-integration.md#complete-code)
- [Solidity Comparison](./examples/oracle-integration.md#solidity-comparison)

#### [NFT with Reservations](./examples/nft-with-reservations.md)
- [Overview](./examples/nft-with-reservations.md#overview)
- [Sale Phases](./examples/nft-with-reservations.md#sale-phases)
- [Reservation System](./examples/nft-with-reservations.md#reservation-system)
- [Whitelist](./examples/nft-with-reservations.md#whitelist)
- [Reveal Mechanism](./examples/nft-with-reservations.md#reveal-mechanism)
- [Complete Code](./examples/nft-with-reservations.md#complete-code)
- [Solidity Comparison](./examples/nft-with-reservations.md#solidity-comparison)

---

### API Reference

#### [Blockchain](./api-reference/blockchain.md)
- [Overview](./api-reference/blockchain.md#overview)
- [Properties](./api-reference/blockchain.md#properties)
- [Transaction Context](./api-reference/blockchain.md#transaction-context)
- [Contract Context](./api-reference/blockchain.md#contract-context)
- [Network Context](./api-reference/blockchain.md#network-context)
- [Storage Architecture](./api-reference/blockchain.md#storage-architecture)
- [Storage Methods](./api-reference/blockchain.md#storage-methods)
- [Event Methods](./api-reference/blockchain.md#event-methods)
- [Cross-Contract Methods](./api-reference/blockchain.md#cross-contract-methods)
- [Signature Methods](./api-reference/blockchain.md#signature-methods)

#### [OP20](./api-reference/op20.md)
- [Overview](./api-reference/op20.md#overview)
- [Initialization](./api-reference/op20.md#initialization)
- [Query Methods](./api-reference/op20.md#query-methods)
- [Transfer Methods](./api-reference/op20.md#transfer-methods)
- [Approval Methods](./api-reference/op20.md#approval-methods)
- [Internal Methods](./api-reference/op20.md#internal-methods)
- [Events](./api-reference/op20.md#events)

#### [OP721](./api-reference/op721.md)
- [Overview](./api-reference/op721.md#overview)
- [Initialization](./api-reference/op721.md#initialization)
- [Query Methods](./api-reference/op721.md#query-methods)
- [Transfer Methods](./api-reference/op721.md#transfer-methods)
- [Approval Methods](./api-reference/op721.md#approval-methods)
- [Internal Methods](./api-reference/op721.md#internal-methods)
- [Events](./api-reference/op721.md#events)

#### [SafeMath](./api-reference/safe-math.md)
- [Overview](./api-reference/safe-math.md#overview)
- [Basic Operations](./api-reference/safe-math.md#basic-operations)
- [Modular Operations](./api-reference/safe-math.md#modular-operations)
- [Signed Operations](./api-reference/safe-math.md#signed-operations)

#### [Storage](./api-reference/storage.md)
- [Overview](./api-reference/storage.md#overview)
- [StoredU256](./api-reference/storage.md#storedu256)
- [StoredU64](./api-reference/storage.md#storedu64)
- [StoredBoolean](./api-reference/storage.md#storedboolean)
- [StoredString](./api-reference/storage.md#storedstring)
- [StoredAddress](./api-reference/storage.md#storedaddress)
- [StoredU256Array](./api-reference/storage.md#storedu256array)
- [StoredAddressArray](./api-reference/storage.md#storedaddressarray)
- [StoredMapU256](./api-reference/storage.md#storedmapu256)
- [AddressMemoryMap](./api-reference/storage.md#addressmemorymap)

#### [Events](./api-reference/events.md)
- [Overview](./api-reference/events.md#overview)
- [NetEvent Base Class](./api-reference/events.md#netevent-base-class)
- [Creating Custom Events](./api-reference/events.md#creating-custom-events)
- [Emitting Events](./api-reference/events.md#emitting-events)
- [Predefined Events](./api-reference/events.md#predefined-events)

---

## Quick Links

- [Example Tokens Repository](https://github.com/btc-vision/example-tokens)
- [btc-runtime Repository](https://github.com/btc-vision/btc-runtime)
- [OP_NET Website](https://opnet.org)

## Solidity Developer?

Every documentation page includes **Solidity Comparison** sections with side-by-side code examples. Start with:
- [First Contract - Solidity Comparison](./getting-started/first-contract.md#solidity-comparison)
- [OP20 vs ERC20](./contracts/op20-token.md#erc20-vs-op20-comparison)
- [OP721 vs ERC721](./contracts/op721-nft.md#erc721-vs-op721-comparison)