@btc-vision/btc-runtime 1.10.11 → 1.10.12

package/docs/api-reference/storage.md

@@ -21,38 +21,7 @@ import {
 } from '@btc-vision/btc-runtime/runtime';
 ```
 
-## CRITICAL: Map Implementation Warning
-
-> **DO NOT USE AssemblyScript's Built-in Map**
->
-> When creating custom map implementations or extending map functionality, you **MUST** use the Map class from `@btc-vision/btc-runtime/runtime`, NOT the built-in AssemblyScript Map.
->
-> **Why the AssemblyScript Map is broken for blockchain:**
-> - NOT optimized for blockchain storage patterns
-> - Does NOT handle Uint8Array buffers as keys correctly
-> - Does NOT work properly with Address key comparisons
-> - Will cause silent data corruption or key collisions
->
-> **CORRECT:**
-> ```typescript
-> import { Map } from '@btc-vision/btc-runtime/runtime';
->
-> export class MyCustomMap<V> extends Map<Address, V> {
->     // Your implementation
-> }
-> ```
->
-> **WRONG:**
-> ```typescript
-> // DO NOT DO THIS - will break!
-> const map = new Map<Uint8Array, u256>();  // AssemblyScript Map
-> ```
->
-> The btc-runtime Map is specifically designed to:
-> - Handle Address and Uint8Array key comparisons correctly
-> - Optimize for blockchain storage access patterns
-> - Support proper serialization for persistent storage
-> - Prevent key collisions with custom equality logic
+> **Important:** Do NOT use AssemblyScript's built-in Map for blockchain storage. See [CRITICAL: Map Implementation Warning](../storage/stored-maps.md#critical-map-implementation-warning) for details.
 
 ## Storage Type Hierarchy
 
@@ -609,87 +578,9 @@ class Nested<T> {
 }
 ```
 
-```typescript
-import { MapOfMap, Nested } from '@btc-vision/btc-runtime/runtime';
-
-// mapping(address => mapping(address => uint256))
-private allowancesPointer: u16 = Blockchain.nextPointer;
-private allowances: MapOfMap<u256>;
-
-constructor() {
-    super();
-    this.allowances = new MapOfMap<u256>(this.allowancesPointer);
-}
-
-// Get nested value - two-step process
-protected getAllowance(owner: Address, spender: Address): u256 {
-    const ownerMap = this.allowances.get(owner);  // Returns Nested<u256>
-    return ownerMap.get(spender);                  // Returns u256
-}
-
-// Set nested value - get, modify, commit back
-protected setAllowance(owner: Address, spender: Address, amount: u256): void {
-    const ownerMap = this.allowances.get(owner);  // Get the nested map
-    ownerMap.set(spender, amount);                 // Modify it
-    this.allowances.set(owner, ownerMap);          // Commit back
-}
-```
-
 > **Important:** `MapOfMap.get(key)` returns a `Nested<T>` object, not the final value. You must call `.get()` on the nested object to retrieve the actual value.
 
-The following diagram shows the two-level nested storage pattern:
-
-```mermaid
-flowchart LR
-    subgraph "Read Path - Two-Level Mapping"
-        A[MapOfMap allowances] --> B[First Level:<br/>Owner Address]
-        B --> C[allowances.get owner]
-        C --> D[Returns Nested<br/>u256 Map]
-        D --> E[Second Level:<br/>Spender Address]
-        E --> F[nested.get spender]
-        F --> G[Returns u256<br/>allowance]
-    end
-
-    subgraph "Write Path - Set Allowance"
-        H[Set Allowance] --> I[Get owner's<br/>nested map]
-        I --> J[nested.set<br/>spender, amount]
-        J --> K[Commit back<br/>to MapOfMap]
-        K --> L[allowances.set<br/>owner, nested]
-    end
-```
-
-The following sequence diagram shows the nested allowance operations:
-
-```mermaid
-sequenceDiagram
-    participant Contract
-    participant MapOfMap as allowances MapOfMap
-    participant Nested as Nested Map
-    participant BC as Blockchain
-
-    Note over Contract,BC: Get Nested Allowance
-
-    Contract->>MapOfMap: allowances.get(owner)
-    MapOfMap->>MapOfMap: Compute owner's map hash
-    MapOfMap->>Contract: Return Nested~u256~ map
-
-    Contract->>Nested: nested.get(spender)
-    Nested->>Nested: Compute spender hash within owner's space
-    Nested->>BC: getStorageAt(combined_hash)
-    BC->>Nested: Return allowance bytes
-    Nested->>Contract: Return u256 allowance
-
-    Note over Contract,BC: Set Nested Allowance
-
-    Contract->>MapOfMap: allowances.get(owner)
-    MapOfMap->>Contract: Return Nested map
-
-    Contract->>Nested: nested.set(spender, new_amount)
-    Nested->>BC: setStorageAt(combined_hash, new_amount)
-
-    Contract->>MapOfMap: allowances.set(owner, nested)
-    Note over Contract: Commit nested map changes
-```
+See [Stored Maps - MapOfMap](../storage/stored-maps.md#mapofmap) for detailed usage patterns and diagrams.
 
 ## Storage Patterns
 

package/docs/core-concepts/security.md

@@ -76,137 +76,34 @@ See [SafeMath API](../api-reference/safe-math.md) for complete reference.
 
 ## Reentrancy Protection
 
-### The Problem
-
-Reentrancy attacks occur when a contract calls back into itself before completing:
-
-```
-1. User calls withdraw()
-2. Contract sends funds to User
-3. User's receive function calls withdraw() again
-4. Contract sends funds again (before updating balance)
-5. Repeat until drained
-```
-
-### Reentrancy Attack Sequence
-
-```mermaid
-sequenceDiagram
-    participant Attacker
-    participant VulnerableContract
-    participant AttackerContract
-
-    Attacker->>VulnerableContract: withdraw()
-    activate VulnerableContract
-
-    Note over VulnerableContract: balance = 100<br/>Check balance 
-
-    VulnerableContract->>AttackerContract: Transfer 100 tokens
-    activate AttackerContract
-
-    Note over AttackerContract: Receive callback triggered
+Reentrancy attacks occur when a contract calls back into itself before completing, allowing attackers to drain funds by repeatedly calling withdraw before the balance is updated.
 
-    AttackerContract->>VulnerableContract: withdraw() [RE-ENTER!]
-    activate VulnerableContract
-
-    Note over VulnerableContract: balance still = 100<br/>Check balance [BUG!]
-
-    VulnerableContract->>AttackerContract: Transfer 100 tokens AGAIN
-    deactivate VulnerableContract
-
-    AttackerContract-->>VulnerableContract: Return
-    deactivate AttackerContract
-
-    Note over VulnerableContract: balance = 0<br/>(Too late!)
-
-    VulnerableContract-->>Attacker: Complete
-    deactivate VulnerableContract
-
-    Note over Attacker: Stole 200 tokens!<br/>Expected: 100
-```
-
-### The Solution: ReentrancyGuard
+**Solution:** Extend `ReentrancyGuard` to automatically protect all methods:
 
 ```typescript
 import { ReentrancyGuard, ReentrancyLevel } from '@btc-vision/btc-runtime/runtime';
 
 @final
 export class MyContract extends ReentrancyGuard {
-    // Override the reentrancy level (STANDARD is the default)
     protected override readonly reentrancyLevel: ReentrancyLevel = ReentrancyLevel.STANDARD;
 
-    public constructor() {
-        super();
-    }
-
     @method()
     public withdraw(calldata: Calldata): BytesWriter {
-        // ReentrancyGuard automatically protects this method
+        // Protected automatically - re-entry attempts will revert
         const amount = this.balances.get(Blockchain.tx.sender);
-
-        // Even if external call tries to re-enter, it will fail
         this.balances.set(Blockchain.tx.sender, u256.Zero);
         // ... transfer funds ...
-
         return new BytesWriter(0);
     }
 }
 ```
 
-### ReentrancyGuard Mechanism Flow
-
-```mermaid
----
-config:
-  theme: dark
----
-flowchart LR
-    Start["Method Called"] --> Check{"Guard Active?"}
-    Check -->|Yes| Revert["REVERT"]
-    Check -->|No| SetGuard["Set Guard Flag"]
-    SetGuard --> Execute["Execute Logic"]
-    Execute --> External{"External Call?"}
-    External -->|Yes| Call["Call External"]
-    Call --> Detect{"Re-enter?"}
-    Detect -->|Yes| Block["REVERT: Blocked"]
-    Detect -->|No| Clear["Clear Guard"]
-    External -->|No| Clear
-    Clear --> Success["Transaction Success"]
-```
-
-### Guard Modes
-
-| Mode | Description | Use Case |
-|------|-------------|----------|
-| `ReentrancyLevel.STANDARD` | Uses boolean lock, strict mutual exclusion | Default for most contracts |
-| `ReentrancyLevel.CALLBACK` | Uses depth counter, still blocks reentrancy | Depth tracking use cases |
-
-```typescript
-// STANDARD: No re-entry allowed, uses boolean lock (default)
-protected override readonly reentrancyLevel: ReentrancyLevel = ReentrancyLevel.STANDARD;
-
-// CALLBACK: No re-entry allowed, uses depth counter for tracking
-protected override readonly reentrancyLevel: ReentrancyLevel = ReentrancyLevel.CALLBACK;
-```
-
-### Guard Mode Decision Tree
-
-```mermaid
----
-config:
-  theme: dark
----
-flowchart LR
-    Start{"External Calls?"}
-    Start -->|No| None["No Guard Needed"]
-    Start -->|Yes| Tracking{"Need Depth Tracking?"}
-    Tracking -->|No| Standard["STANDARD Mode"]
-    Tracking -->|Yes| CallbackMode["CALLBACK Mode"]
-```
-
-Note: Both modes block reentrancy. STANDARD uses a boolean lock; CALLBACK uses a depth counter.
+| Mode | Description |
+|------|-------------|
+| `ReentrancyLevel.STANDARD` | Boolean lock (default) |
+| `ReentrancyLevel.CALLBACK` | Depth counter for tracking |
 
-See [ReentrancyGuard](../contracts/reentrancy-guard.md) for detailed usage.
+Both modes block reentrancy. See [ReentrancyGuard](../contracts/reentrancy-guard.md) for detailed explanation, attack diagrams, and advanced usage.
 
 ## Access Control
 

package/docs/core-concepts/storage-system.md

@@ -195,38 +195,7 @@ flowchart LR
     end
 ```
 
-## CRITICAL: Map Implementation Warning
-
-> **DO NOT USE AssemblyScript's Built-in Map**
->
-> When creating custom map implementations or extending map functionality, you **MUST** use the Map class from `@btc-vision/btc-runtime/runtime`, NOT the built-in AssemblyScript Map.
->
-> **Why the AssemblyScript Map is broken for blockchain:**
-> - NOT optimized for blockchain storage patterns
-> - Does NOT handle Uint8Array buffers as keys correctly
-> - Does NOT work properly with Address key comparisons
-> - Will cause silent data corruption or key collisions
->
-> **CORRECT:**
-> ```typescript
-> import { Map } from '@btc-vision/btc-runtime/runtime';
->
-> export class MyCustomMap<V> extends Map<Address, V> {
->     // Your implementation
-> }
-> ```
->
-> **WRONG:**
-> ```typescript
-> // DO NOT DO THIS - will break!
-> const map = new Map<Uint8Array, u256>();  // AssemblyScript Map
-> ```
->
-> The btc-runtime Map is specifically designed to:
-> - Handle Address and Uint8Array key comparisons correctly
-> - Optimize for blockchain storage access patterns
-> - Support proper serialization for persistent storage
-> - Prevent key collisions with custom equality logic
+> **Important:** Do NOT use AssemblyScript's built-in Map for blockchain storage. See [CRITICAL: Map Implementation Warning](../storage/stored-maps.md#critical-map-implementation-warning) for details.
 
 ## Pointer Allocation
 

package/docs/examples/nft-with-reservations.md

@@ -906,249 +906,19 @@ public reserve(calldata: Calldata): BytesWriter { }
 public getSaleInfo(_calldata: Calldata): BytesWriter { }
 ```
 
-## Solidity Equivalent
-
-For developers familiar with Solidity, here is an equivalent ERC721 implementation with reservations and reveal mechanics:
-
-```solidity
-// SPDX-License-Identifier: MIT
-pragma solidity ^0.8.20;
-
-import "@openzeppelin/contracts/token/ERC721/ERC721.sol";
-import "@openzeppelin/contracts/access/Ownable.sol";
-import "@openzeppelin/contracts/utils/Strings.sol";
-
-contract NFTWithReservations is ERC721, Ownable {
-    using Strings for uint256;
-
-    enum SalePhase { INACTIVE, WHITELIST, PUBLIC }
-
-    // Configuration
-    uint256 public maxSupply;
-    uint256 public price;
-    uint256 public maxPerWallet;
-    string private baseURI_;
-    string private hiddenURI;
-    bool public revealed;
-    SalePhase public salePhase;
-    uint256 private nextTokenId = 1;
-
-    // Reservation system
-    uint256 public reservationEnd;
-    mapping(address => uint256) public reservations;
-
-    // Whitelist
-    mapping(address => bool) public whitelist;
-    mapping(address => uint256) public mintedCount;
-
-    event Reserved(address indexed user, uint256 quantity);
-    event ReservationClaimed(address indexed user, uint256 quantity);
-    event ReservationCancelled(address indexed user, uint256 quantity);
-
-    constructor(
-        string memory name,
-        string memory symbol,
-        uint256 _maxSupply,
-        uint256 _price,
-        uint256 _maxPerWallet,
-        string memory _hiddenURI
-    ) ERC721(name, symbol) Ownable(msg.sender) {
-        maxSupply = _maxSupply;
-        price = _price;
-        maxPerWallet = _maxPerWallet;
-        hiddenURI = _hiddenURI;
-    }
-
-    // ============ RESERVATION SYSTEM ============
-
-    function reserve(uint256 quantity) external payable {
-        require(block.timestamp < reservationEnd, "Reservation period ended");
-        require(reservations[msg.sender] + quantity <= maxPerWallet, "Exceeds max per wallet");
-        require(msg.value >= price * quantity, "Insufficient payment");
-
-        reservations[msg.sender] += quantity;
-        emit Reserved(msg.sender, quantity);
-    }
-
-    function claimReserved() external {
-        require(block.timestamp >= reservationEnd, "Reservation period not ended");
-        uint256 quantity = reservations[msg.sender];
-        require(quantity > 0, "No reservations");
-
-        reservations[msg.sender] = 0;
-
-        for (uint256 i = 0; i < quantity; i++) {
-            _safeMint(msg.sender, nextTokenId++);
-        }
-
-        emit ReservationClaimed(msg.sender, quantity);
-    }
-
-    function cancelReservation() external {
-        require(block.timestamp < reservationEnd, "Reservation period ended");
-        uint256 quantity = reservations[msg.sender];
-        require(quantity > 0, "No reservations");
-
-        reservations[msg.sender] = 0;
-
-        // Refund
-        uint256 refundAmount = price * quantity;
-        (bool success, ) = msg.sender.call{value: refundAmount}("");
-        require(success, "Refund failed");
-
-        emit ReservationCancelled(msg.sender, quantity);
-    }
-
-    // ============ MINTING ============
-
-    function whitelistMint(uint256 quantity) external payable {
-        require(salePhase == SalePhase.WHITELIST, "Whitelist sale not active");
-        require(whitelist[msg.sender], "Not whitelisted");
-        require(msg.value >= price * quantity, "Insufficient payment");
-
-        _mintInternal(msg.sender, quantity);
-    }
-
-    function publicMint(uint256 quantity) external payable {
-        require(salePhase == SalePhase.PUBLIC, "Public sale not active");
-        require(msg.value >= price * quantity, "Insufficient payment");
-
-        _mintInternal(msg.sender, quantity);
-    }
-
-    function _mintInternal(address to, uint256 quantity) internal {
-        require(nextTokenId + quantity - 1 <= maxSupply, "Exceeds max supply");
-        require(mintedCount[to] + quantity <= maxPerWallet, "Exceeds max per wallet");
-
-        mintedCount[to] += quantity;
-
-        for (uint256 i = 0; i < quantity; i++) {
-            _safeMint(to, nextTokenId++);
-        }
-    }
-
-    // ============ REVEAL ============
-
-    function tokenURI(uint256 tokenId) public view override returns (string memory) {
-        require(_ownerOf(tokenId) != address(0), "Token does not exist");
-
-        if (!revealed) {
-            return hiddenURI;
-        }
-
-        return string(abi.encodePacked(baseURI_, tokenId.toString(), ".json"));
-    }
-
-    // ============ ADMIN FUNCTIONS ============
-
-    function startReservation(uint256 duration) external onlyOwner {
-        reservationEnd = block.timestamp + duration;
-    }
-
-    function setSalePhase(SalePhase phase) external onlyOwner {
-        salePhase = phase;
-    }
-
-    function setWhitelist(address[] calldata addresses, bool status) external onlyOwner {
-        for (uint256 i = 0; i < addresses.length; i++) {
-            whitelist[addresses[i]] = status;
-        }
-    }
-
-    function reveal(string calldata _baseURI) external onlyOwner {
-        baseURI_ = _baseURI;
-        revealed = true;
-    }
-
-    function setPrice(uint256 _price) external onlyOwner {
-        price = _price;
-    }
-
-    function withdraw() external onlyOwner {
-        (bool success, ) = owner().call{value: address(this).balance}("");
-        require(success, "Withdrawal failed");
-    }
-
-    // ============ VIEW FUNCTIONS ============
-
-    function totalSupply() public view returns (uint256) {
-        return nextTokenId - 1;
-    }
-
-    function getSaleInfo() external view returns (
-        SalePhase phase,
-        uint256 currentPrice,
-        uint256 maxSupply_,
-        uint256 totalSupply_,
-        bool isRevealed
-    ) {
-        return (salePhase, price, maxSupply, totalSupply(), revealed);
-    }
-}
-```
-
-## Solidity vs OPNet Comparison
-
-### Key Differences Table
+## Solidity Comparison
 
 | Aspect | Solidity (ERC721) | OPNet (OP721) |
 |--------|-------------------|---------------|
-| **Inheritance** | `contract NFT is ERC721, Ownable` | `class NFT extends OP721` |
-| **Constructor** | `constructor() ERC721("Name", "SYM")` | `onDeployment()` + `this.instantiate(...)` |
-| **Enum Definition** | `enum SalePhase { INACTIVE, WHITELIST }` | `const PHASE_INACTIVE: u8 = 0` |
-| **Mint** | `_safeMint(to, tokenId)` | `this._mint(to, tokenId)` |
-| **Token Counter** | `uint256 private nextTokenId` | `StoredU256` with pointer |
-| **Timestamp** | `block.timestamp` | `Blockchain.block.medianTime` |
-| **Whitelist Storage** | `mapping(address => bool)` | `AddressMemoryMap` |
-| **Payment Handling** | `msg.value`, `payable` | Bitcoin UTXO model |
-| **String Concat** | `string(abi.encodePacked(...))` | `baseURI + tokenId.toString() + '.json'` |
-
-### Reservation Pattern Comparison
-
-**Solidity:**
-```solidity
-mapping(address => uint256) public reservations;
-uint256 public reservationEnd;
-
-function reserve(uint256 quantity) external payable {
-    require(block.timestamp < reservationEnd, "Reservation period ended");
-    require(reservations[msg.sender] + quantity <= maxPerWallet, "Exceeds max per wallet");
-    require(msg.value >= price * quantity, "Insufficient payment");
-
-    reservations[msg.sender] += quantity;
-}
-```
-
-**OPNet:**
-```typescript
-private _reservedBy: AddressMemoryMap;
-private _reservationEnd: StoredU256;
+| Inheritance | `contract NFT is ERC721, Ownable` | `class NFT extends OP721` |
+| Constructor | `constructor() ERC721("Name", "SYM")` | `onDeployment()` + `this.instantiate(...)` |
+| Mint | `_safeMint(to, tokenId)` | `this._mint(to, tokenId)` |
+| Timestamp | `block.timestamp` | `Blockchain.block.medianTime` |
+| Whitelist Storage | `mapping(address => bool)` | `AddressMemoryMap` |
 
-@method({ name: 'quantity', type: ABIDataTypes.UINT256 })
-@returns({ name: 'success', type: ABIDataTypes.BOOL })
-@emit('Reserved')
-public reserve(calldata: Calldata): BytesWriter {
-    const quantity = calldata.readU256();
-    const sender = Blockchain.tx.sender;
-
-    const now = u256.fromU64(Blockchain.block.medianTime);
-    if (now >= this._reservationEnd.value) {
-        throw new Revert('Reservation period ended');
-    }
-
-    const currentReserved = this._reservedBy.get(sender);
-    const newTotal = SafeMath.add(currentReserved, quantity);
-
-    if (newTotal > this._maxPerWallet.value) {
-        throw new Revert('Exceeds max per wallet');
-    }
-
-    this._reservedBy.set(sender, newTotal);
-    return new BytesWriter(0);
-}
-```
+For detailed OP721 API documentation, see [OP721 Contract](../contracts/op721-nft.md).
 
-### Whitelist Verification Comparison
+### Whitelist Implementation Comparison
 
 **Solidity (Using Merkle Proofs):**
 ```solidity

package/docs/storage/memory-maps.md

@@ -202,50 +202,7 @@ flowchart LR
 | `transfer(to, amount)` | `balances[msg.sender] -= amount; balances[to] += amount;` | `this.balances.set(sender, SafeMath.sub(...)); this.balances.set(to, SafeMath.add(...));` |
 | `approve(spender, amount)` | `allowances[msg.sender][spender] = amount;` | Use `MapOfMap<u256>` for nested mapping |
 
-### Full Comparison Example
-
-```solidity
-// Solidity
-contract Token {
-    mapping(address => uint256) public balances;
-
-    function transfer(address to, uint256 amount) external {
-        require(balances[msg.sender] >= amount, "Insufficient");
-        balances[msg.sender] -= amount;
-        balances[to] += amount;
-    }
-}
-```
-
-```typescript
-// OPNet
-@final
-export class Token extends OP_NET {
-    private balancesPointer: u16 = Blockchain.nextPointer;
-    private balances: AddressMemoryMap;
-
-    constructor() {
-        super();
-        this.balances = new AddressMemoryMap(this.balancesPointer);
-    }
-
-    public transfer(calldata: Calldata): BytesWriter {
-        const to = calldata.readAddress();
-        const amount = calldata.readU256();
-        const sender = Blockchain.tx.sender;
-
-        const senderBalance = this.balances.get(sender);
-        if (senderBalance < amount) {
-            throw new Revert('Insufficient balance');
-        }
-
-        this.balances.set(sender, SafeMath.sub(senderBalance, amount));
-        this.balances.set(to, SafeMath.add(this.balances.get(to), amount));
-
-        return new BytesWriter(0);
-    }
-}
-```
+For a complete token implementation using AddressMemoryMap, see [Basic Token Example](../examples/basic-token.md).
 
 ## Side-by-Side Code Examples
 

package/docs/storage/stored-arrays.md

@@ -238,71 +238,7 @@ if (this.holders.getLength() === 0) {
 | Get last element | `arr[arr.length - 1]` | `arr.get(arr.getLength() - 1)` |
 | Initialize with values | `arr = [1, 2, 3];` | Multiple `arr.push()` calls in `onDeployment`, then `arr.save()` |
 
-### Full Example Comparison
-
-```solidity
-// Solidity
-contract Registry {
-    address[] public members;
-
-    function addMember(address member) external {
-        members.push(member);
-    }
-
-    function removeMember(uint256 index) external {
-        members[index] = members[members.length - 1];
-        members.pop();
-    }
-
-    function getMemberCount() external view returns (uint256) {
-        return members.length;
-    }
-}
-```
-
-```typescript
-// OPNet
-@final
-export class Registry extends OP_NET {
-    private membersPointer: u16 = Blockchain.nextPointer;
-    private members: StoredAddressArray;
-
-    constructor() {
-        super();
-        this.members = new StoredAddressArray(this.membersPointer, EMPTY_POINTER);
-    }
-
-    public addMember(calldata: Calldata): BytesWriter {
-        const member = calldata.readAddress();
-        this.members.push(member);
-        this.members.save();
-        return new BytesWriter(0);
-    }
-
-    public removeMember(calldata: Calldata): BytesWriter {
-        const index = calldata.readU32();
-        const length = this.members.getLength();
-
-        if (index >= length) {
-            throw new Revert('Index out of bounds');
-        }
-
-        if (index < length - 1) {
-            this.members.set(index, this.members.get(length - 1));
-        }
-        this.members.deleteLast();
-        this.members.save();
-
-        return new BytesWriter(0);
-    }
-
-    public getMemberCount(_calldata: Calldata): BytesWriter {
-        const writer = new BytesWriter(4);
-        writer.writeU32(this.members.getLength());
-        return writer;
-    }
-}
-```
+For complete contract examples using stored arrays, see the [Examples](../examples/) section.
 
 ## Side-by-Side Code Examples
 

package/docs/storage/stored-maps.md

@@ -312,79 +312,7 @@ flowchart LR
 | Token metadata | `mapping(uint256 => string)` | `StoredMapU256` with encoded strings |
 | Checkpoints | `mapping(address => mapping(uint256 => uint256))` | `MapOfMap<u256>` or composite keys |
 
-### Full Example Comparison
-
-```solidity
-// Solidity
-contract Token {
-    mapping(address => uint256) public balances;
-    mapping(address => mapping(address => uint256)) public allowances;
-
-    function transfer(address to, uint256 amount) external {
-        require(balances[msg.sender] >= amount);
-        balances[msg.sender] -= amount;
-        balances[to] += amount;
-    }
-
-    function approve(address spender, uint256 amount) external {
-        allowances[msg.sender][spender] = amount;
-    }
-}
-```
-
-```typescript
-// OPNet
-@final
-export class Token extends OP_NET {
-    private balancesPointer: u16 = Blockchain.nextPointer;
-    private allowancesPointer: u16 = Blockchain.nextPointer;
-
-    private balances: StoredMapU256;
-    private allowances: MapOfMap<u256>;
-
-    constructor() {
-        super();
-        this.balances = new StoredMapU256(this.balancesPointer);
-        this.allowances = new MapOfMap<u256>(this.allowancesPointer);
-    }
-
-    private addressKey(addr: Address): u256 {
-        return u256.fromBytes(addr.toBytes());
-    }
-
-    public transfer(calldata: Calldata): BytesWriter {
-        const to = calldata.readAddress();
-        const amount = calldata.readU256();
-        const sender = Blockchain.tx.sender;
-
-        const senderKey = this.addressKey(sender);
-        const toKey = this.addressKey(to);
-
-        const senderBalance = this.balances.get(senderKey);
-        if (senderBalance < amount) {
-            throw new Revert('Insufficient balance');
-        }
-
-        this.balances.set(senderKey, SafeMath.sub(senderBalance, amount));
-        this.balances.set(toKey, SafeMath.add(this.balances.get(toKey), amount));
-
-        return new BytesWriter(0);
-    }
-
-    public approve(calldata: Calldata): BytesWriter {
-        const spender = calldata.readAddress();
-        const amount = calldata.readU256();
-        const sender = Blockchain.tx.sender;
-
-        // Correct two-step MapOfMap pattern
-        const senderMap = this.allowances.get(sender);
-        senderMap.set(spender, amount);
-        this.allowances.set(sender, senderMap);
-
-        return new BytesWriter(0);
-    }
-}
-```
+For a complete token implementation using these map types, see [Basic Token Example](../examples/basic-token.md).
 
 ## Side-by-Side Code Examples
 

package/docs/storage/stored-primitives.md

@@ -102,14 +102,7 @@ classDiagram
 
 ## Storage Key Generation
 
-Each stored primitive computes its storage key by combining the pointer and subPointer:
-
-```mermaid
-flowchart LR
-    A["pointer: u16<br/>subPointer: u256"] --> B["32-byte buffer<br/>[0-1] = pointer<br/>[2-31] = subPointer"]
-    B --> C["SHA256"]
-    C --> D["Storage Key<br/>(32 bytes)"]
-```
+Each stored primitive computes its storage key using `SHA256(pointer || subPointer)`. See [Pointers](../core-concepts/pointers.md#encodepointer-function-flow) for the detailed flow diagram.
 
 ## Usage
 
@@ -323,47 +316,7 @@ public override onDeployment(calldata: Calldata): void {
 | `bool public paused = false;` | `private pausedPtr: u16 = Blockchain.nextPointer;`<br>`private _paused: StoredBoolean = new StoredBoolean(this.pausedPtr, false);` |
 | `address public owner;` | `private ownerPtr: u16 = Blockchain.nextPointer;`<br>`private _owner: StoredAddress = new StoredAddress(this.ownerPtr);` |
 
-### Full Example Comparison
-
-```solidity
-// Solidity
-contract Token {
-    string public name;       // slot 0
-    uint256 public supply;    // slot 1
-    bool public paused;       // slot 2 (packed)
-
-    constructor(string memory _name, uint256 _supply) {
-        name = _name;
-        supply = _supply;
-    }
-}
-```
-
-```typescript
-// OPNet
-@final
-export class Token extends OP_NET {
-    private namePointer: u16 = Blockchain.nextPointer;
-    private supplyPointer: u16 = Blockchain.nextPointer;
-    private pausedPointer: u16 = Blockchain.nextPointer;
-
-    private _name: StoredString = new StoredString(this.namePointer, 0);
-    private _supply: StoredU256 = new StoredU256(this.supplyPointer, EMPTY_POINTER);
-    private _paused: StoredBoolean = new StoredBoolean(this.pausedPointer, false);
-
-    public override onDeployment(calldata: Calldata): void {
-        this._name.value = calldata.readString();
-        this._supply.value = calldata.readU256();
-    }
-
-    // Manual getter
-    public name(_calldata: Calldata): BytesWriter {
-        const writer = new BytesWriter(256);
-        writer.writeString(this._name.value);
-        return writer;
-    }
-}
-```
+For complete token examples using stored primitives, see [Basic Token Example](../examples/basic-token.md).
 
 ## Side-by-Side Code Examples
 

package/docs/types/safe-math.md

@@ -236,52 +236,9 @@ const approxLn = SafeMath.approxLog(value);  // Approximate ln(x) * 1e6
 const bits = SafeMath.bitLength256(value);  // Returns u32
 ```
 
-## Operations for Other Integer Sizes
+## Other Integer Sizes
 
-SafeMath provides variants for u128 and u64 for more efficient operations when u256 is not needed:
-
-### u128 Operations
-
-```typescript
-import { u128 } from '@btc-vision/as-bignum/assembly';
-
-const a = u128.fromU64(100);
-const b = u128.fromU64(50);
-
-SafeMath.add128(a, b);    // Addition
-SafeMath.sub128(a, b);    // Subtraction
-SafeMath.mul128(a, b);    // Multiplication
-SafeMath.div128(a, b);    // Division
-SafeMath.min128(a, b);    // Minimum
-SafeMath.max128(a, b);    // Maximum
-SafeMath.shl128(a, 10);   // Left shift
-```
-
-### u64 Operations
-
-```typescript
-const x: u64 = 100;
-const y: u64 = 50;
-
-SafeMath.add64(x, y);     // Addition
-SafeMath.sub64(x, y);     // Subtraction
-SafeMath.mul64(x, y);     // Multiplication
-SafeMath.div64(x, y);     // Division
-SafeMath.min64(x, y);     // Minimum
-SafeMath.max64(x, y);     // Maximum
-```
-
-## Solidity Comparison
-
-| Solidity | SafeMath |
-|----------|----------|
-| `a + b` (checked) | `SafeMath.add(a, b)` |
-| `a - b` (checked) | `SafeMath.sub(a, b)` |
-| `a * b` (checked) | `SafeMath.mul(a, b)` |
-| `a / b` | `SafeMath.div(a, b)` |
-| `a % b` | `SafeMath.mod(a, b)` |
-| `a ** b` | `SafeMath.pow(a, b)` |
-| `mulmod(a, b, n)` | `SafeMath.mulmod(a, b, n)` |
+SafeMath also provides u128 and u64 variants. See [SafeMath API Reference](../api-reference/safe-math.md#u128-operations) for the complete list.
 
 ## SafeMathI128
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@btc-vision/btc-runtime",
-    "version": "1.10.11",
+    "version": "1.10.12",
     "description": "Bitcoin L1 Smart Contract Runtime for OPNet. Build decentralized applications on Bitcoin using AssemblyScript and WebAssembly. Fully audited.",
     "main": "btc/index.ts",
     "types": "btc/index.ts",

package/runtime/types/SafeMath.ts

@@ -1249,7 +1249,91 @@ export class SafeMath {
         return atanhSum << 1; // Multiply by 2 using bit shift
     }
 
-    // ==================== Internal Helper Functions ====================
+    /**
+     * Calculate ln(a/b) with precision, avoiding bit-length mismatch issues.
+     * Returns the result scaled by 1e6 (i.e., ln(a/b) * 1,000,000)
+     *
+     * This function correctly handles the case where a and b have different
+     * bit lengths, which would cause incorrect results if computing
+     * preciseLog(a) - preciseLog(b) directly.
+     *
+     * @param a - Numerator (must be > 0)
+     * @param b - Denominator (must be > 0)
+     * @returns ln(a/b) * 1,000,000
+     */
+    public static preciseLogRatio(a: u256, b: u256): u256 {
+        if (a.isZero() || b.isZero()) {
+            return u256.Zero;
+        }
+
+        // If a == b, ln(1) = 0
+        if (u256.eq(a, b)) {
+            return u256.Zero;
+        }
+
+        const SCALE = u256.fromU64(1_000_000);
+        const LN2_SCALED = u256.fromU64(693147); // ln(2) * 1e6
+
+        // Compute ratio = a / b with scaling to preserve precision
+        // scaledRatio = (a * SCALE) / b represents (a/b) * SCALE
+        const scaledRatio = SafeMath.div(SafeMath.mul(a, SCALE), b);
+
+        if (scaledRatio.isZero()) {
+            // a/b is very small, return negative (but we only handle positive ln)
+            // For a < b, ln(a/b) < 0. Return 0 or handle separately if needed.
+            return u256.Zero;
+        }
+
+        // If scaledRatio == SCALE, then a/b == 1, ln = 0
+        if (u256.eq(scaledRatio, SCALE)) {
+            return u256.Zero;
+        }
+
+        // If scaledRatio < SCALE (i.e., a < b), ln is negative
+        // We only return positive values, so return 0 for this case
+        if (u256.lt(scaledRatio, SCALE)) {
+            return u256.Zero;
+        }
+
+        // Now scaledRatio > SCALE, meaning a/b > 1, so ln(a/b) > 0
+        // We want to compute ln(scaledRatio / SCALE) = ln(scaledRatio) - ln(SCALE)
+        // But we do this correctly by computing ln(1 + (scaledRatio - SCALE) / SCALE)
+
+        // fraction = (scaledRatio - SCALE) / SCALE = (a/b - 1)
+        // fractionScaled = scaledRatio - SCALE represents fraction * SCALE
+        const fractionScaled = SafeMath.sub(scaledRatio, SCALE);
+
+        // For small fractions (a/b < 2, i.e., fractionScaled < SCALE), use Taylor series
+        // Note: Use strict less-than to ensure ratio = 2 uses the k*ln(2) decomposition
+        // This ensures continuity at the boundary - both paths give ln(2) for ratio = 2
+        if (u256.lt(fractionScaled, SCALE)) {
+            return this.calculateLnOnePlusFraction(fractionScaled, SCALE);
+        }
+
+        // For ratios >= 2, use the decomposition:
+        // ln(a/b) = k * ln(2) + ln(normalized)
+        // where normalized = (a/b) / 2^k is in range [1, 2)
+
+        // Find k such that scaledRatio / 2^k is in [SCALE, 2*SCALE)
+        let temp = scaledRatio;
+        let k: u32 = 0;
+        const twoScale = SafeMath.mul(SCALE, u256.fromU32(2));
+
+        while (u256.ge(temp, twoScale)) {
+            temp = SafeMath.shr(temp, 1);
+            k++;
+        }
+
+        // Now temp is in [SCALE, 2*SCALE), representing a value in [1, 2)
+        // ln(a/b) = k * ln(2) + ln(temp/SCALE)
+        // temp/SCALE is in [1, 2), so (temp - SCALE)/SCALE is in [0, 1)
+
+        const normalizedFraction = SafeMath.sub(temp, SCALE);
+        const lnNormalized = this.calculateLnOnePlusFraction(normalizedFraction, SCALE);
+        const base = SafeMath.mul(u256.fromU32(k), LN2_SCALED);
+
+        return SafeMath.add(base, lnNormalized);
+    }
 
     /**
      * @internal
@@ -1270,4 +1354,40 @@ export class SafeMath {
         const mMinusX = u256.sub(m, x);
         return u256.ge(x, mMinusX) ? u256.sub(x, mMinusX) : u256.add(x, x);
     }
+
+    // ==================== Internal Helper Functions ====================
+
+    /**
+     * Helper function: Calculate ln(1 + x) where x is provided as xScaled = x * scale
+     * Returns the result scaled by scale (i.e., ln(1+x) * scale)
+     *
+     * Uses Taylor series: ln(1+x) ≈ x - x²/2 + x³/3 - x⁴/4 + x⁵/5
+     * Valid for 0 <= x <= 1 (i.e., xScaled <= scale)
+     */
+    private static calculateLnOnePlusFraction(xScaled: u256, scale: u256): u256 {
+        if (xScaled.isZero()) {
+            return u256.Zero;
+        }
+
+        // x² scaled
+        const x2 = SafeMath.div(SafeMath.mul(xScaled, xScaled), scale);
+
+        // x³ scaled
+        const x3 = SafeMath.div(SafeMath.mul(x2, xScaled), scale);
+
+        // x⁴ scaled
+        const x4 = SafeMath.div(SafeMath.mul(x3, xScaled), scale);
+
+        // x⁵ scaled
+        const x5 = SafeMath.div(SafeMath.mul(x4, xScaled), scale);
+
+        // ln(1+x) ≈ x - x²/2 + x³/3 - x⁴/4 + x⁵/5
+        let result = xScaled;
+        result = SafeMath.sub(result, SafeMath.div(x2, u256.fromU32(2)));
+        result = SafeMath.add(result, SafeMath.div(x3, u256.fromU32(3)));
+        result = SafeMath.sub(result, SafeMath.div(x4, u256.fromU32(4)));
+        result = SafeMath.add(result, SafeMath.div(x5, u256.fromU32(5)));
+
+        return result;
+    }
 }