@btc-vision/btc-runtime 1.10.8 → 1.10.11

package/docs/README.md

@@ -0,0 +1,614 @@
+# Documentation
+
+Welcome to the comprehensive documentation for **@btc-vision/btc-runtime**, the OPNet 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 OPNet 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 OPNet 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)
+
+---
+
+### 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 OPNet 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 OPNet 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 OPNet 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 OPNet 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 OPNet 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 OPNet 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 OPNet 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 OPNet 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 OPNet 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 OPNet Comparison](./advanced/bitcoin-scripts.md#solidity-vs-opnet-comparison)
+- [Best Practices](./advanced/bitcoin-scripts.md#best-practices)
+
+#### [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)
+  - [onExecutionStarted](./advanced/plugins.md#onexecutionstarted)
+  - [onExecutionCompleted](./advanced/plugins.md#onexecutioncompleted)
+- [Built-in Plugins](./advanced/plugins.md#built-in-plugins)
+- [Solidity vs OPNet 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)
+- [OPNet 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)