@btc-vision/btc-runtime 1.11.0-rc.9 → 1.11.0

package/docs/contracts/op-net-base.md

@@ -1,6 +1,6 @@
 # OP_NET Base Contract
 
-`OP_NET` is the base class for all OPNet smart contracts. It implements the `IBTC` interface and provides the foundational structure for contract lifecycle, method dispatching, event emission, and access control.
+`OP_NET` is the base class for all OP_NET smart contracts. It implements the `IBTC` interface and provides the foundational structure for contract lifecycle, method dispatching, event emission, and access control.
 
 ## Overview
 
@@ -42,7 +42,7 @@ contract MyContract {
     }
 }
 
-// OPNet: AUTOMATIC method routing via @method decorators
+// OP_NET: AUTOMATIC method routing via @method decorators
 // - Constructor runs on EVERY call
 // - Routing is automatic via decorator system
 // - One-time init in onDeployment()
@@ -52,7 +52,7 @@ contract MyContract {
 
 ### Inheritance Hierarchy
 
-OPNet contracts follow a clear inheritance pattern:
+OP_NET contracts follow a clear inheritance pattern:
 
 ```mermaid
 classDiagram
@@ -118,7 +118,7 @@ classDiagram
 
 ### Deployment and Execution Flow
 
-The following diagram shows how contracts are deployed and executed on OPNet:
+The following diagram shows how contracts are deployed and executed on OP_NET:
 
 ```mermaid
 ---
@@ -198,7 +198,7 @@ public constructor() {
 
 **Key Difference from Solidity:**
 
-| Solidity | OPNet |
+| Solidity | OP_NET |
 |----------|-------|
 | Constructor runs once at deployment | Constructor runs every call |
 | Initialize state in constructor | Initialize state in `onDeployment` |
@@ -232,7 +232,7 @@ constructor(uint256 initialSupply, string memory tokenName) {
     _mint(msg.sender, initialSupply);
 }
 
-// OPNet: One-time init in onDeployment()
+// OP_NET: One-time init in onDeployment()
 // Constructor runs every call, onDeployment runs once
 ```
 
@@ -255,7 +255,7 @@ public override onUpdate(calldata: Calldata): void {
 }
 ```
 
-> **Note:** This hook is called on the **new** bytecode, not the old one. See [Contract Upgrades](../advanced/contract-upgrades.md#the-onupdate-lifecycle-hook) for details.
+> **Note:** This hook is called on the **new** bytecode, not the old one. See [Contract Updates](../advanced/updatable#the-onupdate-lifecycle-hook) for details.
 
 ### 3. Method Execution
 
@@ -397,12 +397,12 @@ public transfer(calldata: Calldata): BytesWriter {
 function transfer(address to, uint256 amount) public { }
 // Selector: keccak256("transfer(address,uint256)")[:4]
 
-// OPNet: ALSO automatic via @method decorator
+// OP_NET: ALSO automatic via @method decorator
 // @method({ name: 'to', type: ABIDataTypes.ADDRESS }, ...)
 // public transfer(calldata: Calldata): BytesWriter { }
 ```
 
-**Note:** Both Solidity and OPNet handle selector generation automatically. In OPNet, use `@method` decorators and the runtime handles routing.
+**Note:** Both Solidity and OP_NET handle selector generation automatically. In OP_NET, use `@method` decorators and the runtime handles routing.
 
 ### Built-in Methods
 
@@ -444,7 +444,7 @@ contract MyContract is Ownable {
     }
 }
 
-// OPNet: Built-in onlyDeployer check
+// OP_NET: Built-in onlyDeployer check
 // this.onlyDeployer(Blockchain.tx.sender);
 ```
 
@@ -483,7 +483,7 @@ function setParameter(uint256 value) public onlyAdmin {
     // ...
 }
 
-// OPNet: Similar pattern but with explicit method call
+// OP_NET: Similar pattern but with explicit method call
 // this.onlyAdmin(); at start of method
 ```
 
@@ -509,7 +509,7 @@ event Transfer(address indexed from, address indexed to, uint256 value);
 
 emit Transfer(from, to, amount);
 
-// OPNet: emitEvent method
+// OP_NET: emitEvent method
 this.emitEvent(new TransferEvent(from, to, amount));
 ```
 
@@ -570,7 +570,7 @@ contract MyContract {
     bytes private data;           // slot 2
 }
 
-// OPNet: Explicit pointer allocation
+// OP_NET: Explicit pointer allocation
 // private counterPointer: u16 = Blockchain.nextPointer;
 // private counter: StoredU256 = new StoredU256(this.counterPointer, EMPTY_POINTER);
 ```
@@ -596,7 +596,7 @@ export class MyContract extends OP_NET {
 // Solidity: mapping declaration
 mapping(address => uint256) private balances;
 
-// OPNet: AddressMemoryMap with pointer
+// OP_NET: AddressMemoryMap with pointer
 // private balancesPointer: u16 = Blockchain.nextPointer;
 // this.balances = new AddressMemoryMap(this.balancesPointer);
 ```
@@ -750,7 +750,7 @@ contract MyToken is ERC20, Pausable {
     }
 }
 
-// OPNet: Custom Pausable base class
+// OP_NET: Custom Pausable base class
 // export abstract class Pausable extends OP_NET { ... }
 // this.whenNotPaused(); at start of method
 ```

package/docs/contracts/op20-token.md

@@ -1,6 +1,6 @@
 # OP20 Token Standard
 
-OP20 is OPNet's fungible token standard, equivalent to Ethereum's ERC20. It provides a complete implementation for creating tokens with transfer, approval, and balance tracking capabilities.
+OP20 is OP_NET's fungible token standard, equivalent to Ethereum's ERC20. It provides a complete implementation for creating tokens with transfer, approval, and balance tracking capabilities.
 
 ## Overview
 
@@ -38,7 +38,7 @@ export class MyToken extends OP20 {
 
 ## ERC20 vs OP20 Comparison
 
-| Feature | ERC20 (Solidity) | OP20 (OPNet) |
+| Feature | ERC20 (Solidity) | OP20 (OP_NET) |
 |---------|------------------|--------------|
 | Language | Solidity | AssemblyScript |
 | Runtime | EVM | WASM |
@@ -286,7 +286,7 @@ flowchart LR
 <table>
 <tr>
 <th>ERC20 (Solidity)</th>
-<th>OP20 (OPNet)</th>
+<th>OP20 (OP_NET)</th>
 </tr>
 <tr>
 <td>

package/docs/contracts/op20s-signatures.md

@@ -39,7 +39,7 @@ export class MyToken extends OP20S {
 
 ## ERC20Permit vs OP20S Comparison
 
-| Feature | ERC20Permit (EIP-2612) | OP20S (OPNet) |
+| Feature | ERC20Permit (EIP-2612) | OP20S (OP_NET) |
 |---------|------------------------|---------------|
 | Language | Solidity | AssemblyScript |
 | Signature Type | ECDSA (v, r, s) | Schnorr, ECDSA (deprecated), or ML-DSA |
@@ -327,7 +327,7 @@ contract.permit(..., nonce=0, signature0);  // FAILS - nonce mismatch
 <table>
 <tr>
 <th>ERC20Permit (Solidity)</th>
-<th>OP20S (OPNet)</th>
+<th>OP20S (OP_NET)</th>
 </tr>
 <tr>
 <td>

package/docs/contracts/op721-nft.md

@@ -1,6 +1,6 @@
 # OP721 NFT Standard
 
-OP721 is OPNet's non-fungible token standard, equivalent to Ethereum's ERC721. It provides a complete implementation for creating NFTs with ownership tracking, transfers, approvals, and metadata management.
+OP721 is OP_NET's non-fungible token standard, equivalent to Ethereum's ERC721. It provides a complete implementation for creating NFTs with ownership tracking, transfers, approvals, and metadata management.
 
 ## Overview
 
@@ -33,7 +33,7 @@ export class MyNFT extends OP721 {
 
 ## ERC721 vs OP721 Comparison
 
-| Feature | ERC721 (Solidity) | OP721 (OPNet) |
+| Feature | ERC721 (Solidity) | OP721 (OP_NET) |
 |---------|-------------------|---------------|
 | Language | Solidity | AssemblyScript |
 | Runtime | EVM | WASM |
@@ -340,7 +340,7 @@ stateDiagram-v2
 <table>
 <tr>
 <th>ERC721 (Solidity)</th>
-<th>OP721 (OPNet)</th>
+<th>OP721 (OP_NET)</th>
 </tr>
 <tr>
 <td>

package/docs/contracts/reentrancy-guard.md

@@ -31,9 +31,9 @@ export class MyContract extends ReentrancyGuard {
 }
 ```
 
-## OpenZeppelin vs OPNet ReentrancyGuard
+## OpenZeppelin vs OP_NET ReentrancyGuard
 
-| Feature | OpenZeppelin (Solidity) | OPNet ReentrancyGuard |
+| Feature | OpenZeppelin (Solidity) | OP_NET ReentrancyGuard |
 |---------|-------------------------|----------------------|
 | Protection Scope | Per-function (`nonReentrant` modifier) | All methods by default |
 | Opt-in/Opt-out | Opt-in per function | Opt-out via `isSelectorExcluded` |
@@ -529,8 +529,6 @@ The base `ReentrancyGuard` automatically excludes standard token receiver callba
 // Built-in exclusions in ReentrancyGuard base class:
 // - ON_OP20_RECEIVED_SELECTOR
 // - ON_OP721_RECEIVED_SELECTOR
-// - ON_OP1155_RECEIVED_MAGIC
-// - ON_OP1155_BATCH_RECEIVED_MAGIC
 ```
 
 You can override `isSelectorExcluded` to add custom exclusions:
@@ -564,7 +562,7 @@ export class MyContract extends ReentrancyGuard {
 <table>
 <tr>
 <th>OpenZeppelin ReentrancyGuard</th>
-<th>OPNet ReentrancyGuard</th>
+<th>OP_NET ReentrancyGuard</th>
 </tr>
 <tr>
 <td>
@@ -615,7 +613,7 @@ export class MyContract extends ReentrancyGuard {
 
 Key differences:
 - Solidity: Explicit `nonReentrant` modifier per function
-- OPNet: All methods protected by default (opt-out via `isSelectorExcluded`)
+- OP_NET: All methods protected by default (opt-out via `isSelectorExcluded`)
 
 ## Best Practices
 
@@ -731,7 +729,7 @@ public getValue(): u256 {
     return value;
 }
 
-// In OPNet, the guard is checked at method entry,
+// In OP_NET, the guard is checked at method entry,
 // so this isn't an issue - just be aware of it
 ```
 

package/docs/contracts/updatable.md

@@ -0,0 +1,384 @@
+# Updatable
+
+The `Updatable` base class provides a secure update mechanism with configurable timelock protection. Contracts extending `Updatable` can replace their bytecode while giving users time to assess pending changes.
+
+> **Alternative**: If you're already extending another base class (like `OP20` or `OP721`), use the [`UpdatablePlugin`](../advanced/updatable#using-the-updatableplugin) instead. Just call `this.registerPlugin(new UpdatablePlugin(144))` in your constructor - no other code changes needed!
+
+## Overview
+
+```typescript
+import {
+    Updatable,
+    Calldata,
+    BytesWriter,
+    encodeSelector,
+    Selector,
+    ADDRESS_BYTE_LENGTH,
+} from '@btc-vision/btc-runtime/runtime';
+
+@final
+export class MyContract extends Updatable {
+    // Set delay: 144 blocks = ~24 hours
+    protected readonly updateDelay: u64 = 144;
+
+    public override execute(method: Selector, calldata: Calldata): BytesWriter {
+        switch (method) {
+            case encodeSelector('submitUpdate'):
+                return this.submitUpdate(calldata.readAddress());
+            case encodeSelector('applyUpdate'): {
+                const sourceAddress = calldata.readAddress();
+                const updateCalldata = calldata.readBytesWithLength();
+                return this.applyUpdate(sourceAddress, updateCalldata);
+            }
+            case encodeSelector('cancelUpdate'):
+                return this.cancelUpdate();
+            default:
+                return super.execute(method, calldata);
+        }
+    }
+}
+```
+
+## Class Reference
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `updateDelay` | `u64` | Blocks to wait before update can be applied (default: 144 = ~24h) |
+| `pendingUpdateAddress` | `Address` | Source address of pending update (zero if none) |
+| `pendingUpdateBlock` | `u64` | Block when update was submitted (0 if none) |
+| `updateEffectiveBlock` | `u64` | Block when update can be applied (0 if none) |
+| `hasPendingUpdate` | `bool` | Whether an update is pending |
+| `canApplyUpdate` | `bool` | Whether the delay has elapsed |
+
+### Methods
+
+#### submitUpdate
+
+Submits an update for timelock. Only callable by deployer.
+
+```typescript
+protected submitUpdate(sourceAddress: Address): BytesWriter
+```
+
+**Parameters:**
+- `sourceAddress`: The address of the contract containing the new bytecode
+
+**Reverts if:**
+- Caller is not the deployer
+- Source is not a deployed contract
+- An update is already pending
+
+**Emits:** `UpdateSubmitted(sourceAddress, submitBlock, effectiveBlock)`
+
+#### applyUpdate
+
+Applies a pending update after the delay has passed. Only callable by deployer.
+
+```typescript
+protected applyUpdate(sourceAddress: Address, calldata: BytesWriter): BytesWriter
+```
+
+**Parameters:**
+- `sourceAddress`: The source contract address (must match pending)
+- `calldata`: Data passed to the `onUpdate` hook of the new contract
+
+**Reverts if:**
+- Caller is not the deployer
+- No update is pending
+- Delay has not elapsed
+- Address does not match pending update
+
+**Emits:** `UpdateApplied(sourceAddress, appliedAtBlock)`
+
+#### cancelUpdate
+
+Cancels a pending update. Only callable by deployer.
+
+```typescript
+protected cancelUpdate(): BytesWriter
+```
+
+**Reverts if:**
+- Caller is not the deployer
+- No update is pending
+
+**Emits:** `UpdateCancelled(sourceAddress, cancelledAtBlock)`
+
+## Events
+
+### UpdateSubmittedEvent
+
+Emitted when an update is submitted.
+
+```typescript
+class UpdateSubmittedEvent extends NetEvent {
+    constructor(
+        sourceAddress: Address,  // Contract with new bytecode
+        submitBlock: u64,        // Block when submitted
+        effectiveBlock: u64      // Block when can be applied
+    )
+}
+```
+
+### UpdateAppliedEvent
+
+Emitted when an update is applied.
+
+```typescript
+class UpdateAppliedEvent extends NetEvent {
+    constructor(
+        sourceAddress: Address,  // Contract with new bytecode
+        appliedAtBlock: u64      // Block when applied
+    )
+}
+```
+
+### UpdateCancelledEvent
+
+Emitted when a pending update is cancelled.
+
+```typescript
+class UpdateCancelledEvent extends NetEvent {
+    constructor(
+        sourceAddress: Address,  // Cancelled source contract
+        cancelledAtBlock: u64    // Block when cancelled
+    )
+}
+```
+
+## Usage Patterns
+
+### Basic Updatable Contract
+
+```typescript
+@final
+export class SimpleUpdatable extends Updatable {
+    protected readonly updateDelay: u64 = 144; // ~1 day
+
+    public override execute(method: Selector, calldata: Calldata): BytesWriter {
+        switch (method) {
+            case encodeSelector('submitUpdate'):
+                return this.submitUpdate(calldata.readAddress());
+            case encodeSelector('applyUpdate'): {
+                const sourceAddress = calldata.readAddress();
+                const updateCalldata = calldata.readBytesWithLength();
+                return this.applyUpdate(sourceAddress, updateCalldata);
+            }
+            case encodeSelector('cancelUpdate'):
+                return this.cancelUpdate();
+            default:
+                return super.execute(method, calldata);
+        }
+    }
+}
+```
+
+### With Update Status Views
+
+```typescript
+@final
+export class UpdatableWithViews extends Updatable {
+    protected readonly updateDelay: u64 = 1008; // ~1 week
+
+    public override execute(method: Selector, calldata: Calldata): BytesWriter {
+        switch (method) {
+            // Update actions
+            case encodeSelector('submitUpdate'):
+                return this.submitUpdate(calldata.readAddress());
+            case encodeSelector('applyUpdate'): {
+                const sourceAddress = calldata.readAddress();
+                const updateCalldata = calldata.readBytesWithLength();
+                return this.applyUpdate(sourceAddress, updateCalldata);
+            }
+            case encodeSelector('cancelUpdate'):
+                return this.cancelUpdate();
+
+            // View methods
+            case encodeSelector('getPendingUpdate'):
+                return this.getPendingUpdate();
+            case encodeSelector('getUpdateStatus'):
+                return this.getUpdateStatus();
+
+            default:
+                return super.execute(method, calldata);
+        }
+    }
+
+    private getPendingUpdate(): BytesWriter {
+        const response = new BytesWriter(32);
+        response.writeAddress(this.pendingUpdateAddress);
+        return response;
+    }
+
+    private getUpdateStatus(): BytesWriter {
+        const response = new BytesWriter(17);
+        response.writeBoolean(this.hasPendingUpdate);
+        response.writeU64(this.pendingUpdateBlock);
+        response.writeU64(this.updateEffectiveBlock);
+        return response;
+    }
+}
+```
+
+### Emergency Updates (Not Recommended)
+
+For contracts that need faster updates (use with caution):
+
+```typescript
+@final
+export class QuickUpdatable extends Updatable {
+    // Only 6 blocks (~1 hour) - use only for emergencies
+    protected readonly updateDelay: u64 = 6;
+
+    // ... rest of implementation
+}
+```
+
+## Security Considerations
+
+### 1. Delay Selection
+
+Choose an appropriate delay based on your contract's risk profile:
+
+| Contract Type | Recommended Delay |
+|---------------|-------------------|
+| Test/Development | 1-6 blocks |
+| Standard DeFi | 144 blocks (~24 hours) |
+| High-value vaults | 1008 blocks (~1 week) |
+| Governance contracts | 4320 blocks (~1 month) |
+
+### 2. Source Validation
+
+The `submitUpdate` function validates that the source is a deployed contract. This prevents:
+- Submitting non-existent addresses
+- Last-minute malicious deployments
+
+### 3. Address Match Verification
+
+The `applyUpdate` function requires the address to match the pending update. This prevents:
+- Front-running attacks
+- Address substitution attacks
+
+### 4. Storage Compatibility
+
+When upgrading, ensure storage layout compatibility:
+
+```typescript
+// V1 - Original
+class ContractV1 extends Updatable {
+    private ptr1: u16 = Blockchain.nextPointer; // Pointer 1
+    private ptr2: u16 = Blockchain.nextPointer; // Pointer 2
+}
+
+// V2 - Add new pointers at the END
+class ContractV2 extends Updatable {
+    private ptr1: u16 = Blockchain.nextPointer; // Pointer 1 (same)
+    private ptr2: u16 = Blockchain.nextPointer; // Pointer 2 (same)
+    private ptr3: u16 = Blockchain.nextPointer; // Pointer 3 (NEW)
+}
+```
+
+## Update Workflow
+
+```
+1. Deploy new bytecode contract
+   └─> Returns: newContractAddress
+
+2. Submit update
+   └─> submitUpdate(newContractAddress)
+   └─> Emits: UpdateSubmitted
+
+3. Wait for delay
+   └─> Users can monitor and exit
+
+4. Apply update
+   └─> applyUpdate(newContractAddress)
+   └─> Emits: UpdateApplied
+   └─> VM calls onUpdate() on new bytecode
+   └─> New bytecode active next block
+
+5. (Optional) Discard source contract
+   └─> Source contract can be abandoned
+```
+
+### The onUpdate Hook
+
+Override `onUpdate` in your new contract version to perform migrations:
+
+```typescript
+@final
+export class MyContractV2 extends Updatable {
+    protected readonly updateDelay: u64 = 144;
+
+    // New storage added in V2
+    private newFeaturePointer: u16 = Blockchain.nextPointer;
+    private _newFeature: StoredU256;
+
+    public constructor() {
+        super();
+        this._newFeature = new StoredU256(this.newFeaturePointer, EMPTY_POINTER);
+    }
+
+    public override onUpdate(calldata: Calldata): void {
+        super.onUpdate(calldata);
+        // Initialize new storage
+        this._newFeature.value = u256.fromU64(100);
+    }
+
+    // ... execute() and other methods
+}
+```
+
+See [The onUpdate Lifecycle Hook](../advanced/updatable#the-onupdate-lifecycle-hook) for more details.
+
+## Combining with Other Base Classes
+
+### Updatable + ReentrancyGuard
+
+```typescript
+// Create a combined base class
+class UpdatableWithReentrancy extends Updatable {
+    protected readonly reentrancyLevel: ReentrancyLevel = ReentrancyLevel.STANDARD;
+    private _locked: StoredBoolean;
+
+    protected constructor() {
+        super();
+        this._locked = new StoredBoolean(Blockchain.nextPointer, false);
+    }
+
+    protected nonReentrant(): void {
+        if (this._locked.value) {
+            throw new Revert('ReentrancyGuard: LOCKED');
+        }
+        this._locked.value = true;
+    }
+
+    protected releaseGuard(): void {
+        this._locked.value = false;
+    }
+}
+
+@final
+export class SecureUpdatableVault extends UpdatableWithReentrancy {
+    // Implementation with both update and reentrancy protection
+}
+```
+
+## Solidity Comparison
+
+| Feature | OpenZeppelin UUPS | OP_NET Updatable |
+|---------|-------------------|-------------------|
+| Update mechanism | delegatecall | Native bytecode replacement |
+| Storage location | Implementation contract | Same contract |
+| Proxy overhead | Yes | No |
+| Timelock | Separate contract (optional) | Built-in |
+| Events | Custom | Built-in |
+| Cancel update | Custom implementation | Built-in |
+
+---
+
+**Navigation:**
+- Previous: [ReentrancyGuard](./reentrancy-guard.md)
+- Next: [Address Type](../types/address.md)