@btc-vision/btc-runtime 1.10.12 → 1.11.0-alpha

package/docs/contracts/upgradeable.md

@@ -0,0 +1,396 @@
+# Upgradeable
+
+The `Upgradeable` base class provides a secure upgrade mechanism with configurable timelock protection. Contracts extending `Upgradeable` 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 [`UpgradeablePlugin`](../advanced/contract-upgrades.md#using-the-upgradeableplugin) instead. Just call `this.registerPlugin(new UpgradeablePlugin(144))` in your constructor - no other code changes needed!
+
+## Overview
+
+```typescript
+import {
+    Upgradeable,
+    Calldata,
+    BytesWriter,
+    encodeSelector,
+    Selector,
+    ADDRESS_BYTE_LENGTH,
+} from '@btc-vision/btc-runtime/runtime';
+
+@final
+export class MyContract extends Upgradeable {
+    // Set delay: 144 blocks = ~24 hours
+    protected readonly upgradeDelay: u64 = 144;
+
+    public override execute(method: Selector, calldata: Calldata): BytesWriter {
+        switch (method) {
+            case encodeSelector('submitUpgrade'):
+                return this.submitUpgrade(calldata.readAddress());
+            case encodeSelector('applyUpgrade'): {
+                const sourceAddress = calldata.readAddress();
+                const remainingLength = calldata.byteLength - ADDRESS_BYTE_LENGTH;
+                const updateCalldata = new BytesWriter(remainingLength);
+                if (remainingLength > 0) {
+                    updateCalldata.writeBytes(calldata.readBytes(remainingLength));
+                }
+                return this.applyUpgrade(sourceAddress, updateCalldata);
+            }
+            case encodeSelector('cancelUpgrade'):
+                return this.cancelUpgrade();
+            default:
+                return super.execute(method, calldata);
+        }
+    }
+}
+```
+
+## Class Reference
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `upgradeDelay` | `u64` | Blocks to wait before upgrade can be applied (default: 144 = ~24h) |
+| `pendingUpgradeAddress` | `Address` | Source address of pending upgrade (zero if none) |
+| `pendingUpgradeBlock` | `u64` | Block when upgrade was submitted (0 if none) |
+| `upgradeEffectiveBlock` | `u64` | Block when upgrade can be applied (0 if none) |
+| `hasPendingUpgrade` | `bool` | Whether an upgrade is pending |
+| `canApplyUpgrade` | `bool` | Whether the delay has elapsed |
+
+### Methods
+
+#### submitUpgrade
+
+Submits an upgrade for timelock. Only callable by deployer.
+
+```typescript
+protected submitUpgrade(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 upgrade is already pending
+
+**Emits:** `UpgradeSubmitted(sourceAddress, submitBlock, effectiveBlock)`
+
+#### applyUpgrade
+
+Applies a pending upgrade after the delay has passed. Only callable by deployer.
+
+```typescript
+protected applyUpgrade(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 upgrade is pending
+- Delay has not elapsed
+- Address does not match pending upgrade
+
+**Emits:** `UpgradeApplied(sourceAddress, appliedAtBlock)`
+
+#### cancelUpgrade
+
+Cancels a pending upgrade. Only callable by deployer.
+
+```typescript
+protected cancelUpgrade(): BytesWriter
+```
+
+**Reverts if:**
+- Caller is not the deployer
+- No upgrade is pending
+
+**Emits:** `UpgradeCancelled(sourceAddress, cancelledAtBlock)`
+
+## Events
+
+### UpgradeSubmittedEvent
+
+Emitted when an upgrade is submitted.
+
+```typescript
+class UpgradeSubmittedEvent extends NetEvent {
+    constructor(
+        sourceAddress: Address,  // Contract with new bytecode
+        submitBlock: u64,        // Block when submitted
+        effectiveBlock: u64      // Block when can be applied
+    )
+}
+```
+
+### UpgradeAppliedEvent
+
+Emitted when an upgrade is applied.
+
+```typescript
+class UpgradeAppliedEvent extends NetEvent {
+    constructor(
+        sourceAddress: Address,  // Contract with new bytecode
+        appliedAtBlock: u64      // Block when applied
+    )
+}
+```
+
+### UpgradeCancelledEvent
+
+Emitted when a pending upgrade is cancelled.
+
+```typescript
+class UpgradeCancelledEvent extends NetEvent {
+    constructor(
+        sourceAddress: Address,  // Cancelled source contract
+        cancelledAtBlock: u64    // Block when cancelled
+    )
+}
+```
+
+## Usage Patterns
+
+### Basic Upgradeable Contract
+
+```typescript
+@final
+export class SimpleUpgradeable extends Upgradeable {
+    protected readonly upgradeDelay: u64 = 144; // ~1 day
+
+    public override execute(method: Selector, calldata: Calldata): BytesWriter {
+        switch (method) {
+            case encodeSelector('submitUpgrade'):
+                return this.submitUpgrade(calldata.readAddress());
+            case encodeSelector('applyUpgrade'): {
+                const sourceAddress = calldata.readAddress();
+                const remainingLength = calldata.byteLength - ADDRESS_BYTE_LENGTH;
+                const updateCalldata = new BytesWriter(remainingLength);
+                if (remainingLength > 0) {
+                    updateCalldata.writeBytes(calldata.readBytes(remainingLength));
+                }
+                return this.applyUpgrade(sourceAddress, updateCalldata);
+            }
+            case encodeSelector('cancelUpgrade'):
+                return this.cancelUpgrade();
+            default:
+                return super.execute(method, calldata);
+        }
+    }
+}
+```
+
+### With Upgrade Status Views
+
+```typescript
+@final
+export class UpgradeableWithViews extends Upgradeable {
+    protected readonly upgradeDelay: u64 = 1008; // ~1 week
+
+    public override execute(method: Selector, calldata: Calldata): BytesWriter {
+        switch (method) {
+            // Upgrade actions
+            case encodeSelector('submitUpgrade'):
+                return this.submitUpgrade(calldata.readAddress());
+            case encodeSelector('applyUpgrade'): {
+                const sourceAddress = calldata.readAddress();
+                const remainingLength = calldata.byteLength - ADDRESS_BYTE_LENGTH;
+                const updateCalldata = new BytesWriter(remainingLength);
+                if (remainingLength > 0) {
+                    updateCalldata.writeBytes(calldata.readBytes(remainingLength));
+                }
+                return this.applyUpgrade(sourceAddress, updateCalldata);
+            }
+            case encodeSelector('cancelUpgrade'):
+                return this.cancelUpgrade();
+
+            // View methods
+            case encodeSelector('getPendingUpgrade'):
+                return this.getPendingUpgrade();
+            case encodeSelector('getUpgradeStatus'):
+                return this.getUpgradeStatus();
+
+            default:
+                return super.execute(method, calldata);
+        }
+    }
+
+    private getPendingUpgrade(): BytesWriter {
+        const response = new BytesWriter(32);
+        response.writeAddress(this.pendingUpgradeAddress);
+        return response;
+    }
+
+    private getUpgradeStatus(): BytesWriter {
+        const response = new BytesWriter(17);
+        response.writeBoolean(this.hasPendingUpgrade);
+        response.writeU64(this.pendingUpgradeBlock);
+        response.writeU64(this.upgradeEffectiveBlock);
+        return response;
+    }
+}
+```
+
+### Emergency Upgrades (Not Recommended)
+
+For contracts that need faster upgrades (use with caution):
+
+```typescript
+@final
+export class QuickUpgradeable extends Upgradeable {
+    // Only 6 blocks (~1 hour) - use only for emergencies
+    protected readonly upgradeDelay: 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 `submitUpgrade` function validates that the source is a deployed contract. This prevents:
+- Submitting non-existent addresses
+- Last-minute malicious deployments
+
+### 3. Address Match Verification
+
+The `applyUpgrade` function requires the address to match the pending upgrade. This prevents:
+- Front-running attacks
+- Address substitution attacks
+
+### 4. Storage Compatibility
+
+When upgrading, ensure storage layout compatibility:
+
+```typescript
+// V1 - Original
+class ContractV1 extends Upgradeable {
+    private ptr1: u16 = Blockchain.nextPointer; // Pointer 1
+    private ptr2: u16 = Blockchain.nextPointer; // Pointer 2
+}
+
+// V2 - Add new pointers at the END
+class ContractV2 extends Upgradeable {
+    private ptr1: u16 = Blockchain.nextPointer; // Pointer 1 (same)
+    private ptr2: u16 = Blockchain.nextPointer; // Pointer 2 (same)
+    private ptr3: u16 = Blockchain.nextPointer; // Pointer 3 (NEW)
+}
+```
+
+## Upgrade Workflow
+
+```
+1. Deploy new bytecode contract
+   └─> Returns: newContractAddress
+
+2. Submit upgrade
+   └─> submitUpgrade(newContractAddress)
+   └─> Emits: UpgradeSubmitted
+
+3. Wait for delay
+   └─> Users can monitor and exit
+
+4. Apply upgrade
+   └─> applyUpgrade(newContractAddress)
+   └─> Emits: UpgradeApplied
+   └─> 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 Upgradeable {
+    protected readonly upgradeDelay: 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/contract-upgrades.md#the-onupdate-lifecycle-hook) for more details.
+
+## Combining with Other Base Classes
+
+### Upgradeable + ReentrancyGuard
+
+```typescript
+// Create a combined base class
+class UpgradeableWithReentrancy extends Upgradeable {
+    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 SecureUpgradeableVault extends UpgradeableWithReentrancy {
+    // Implementation with both upgrade and reentrancy protection
+}
+```
+
+## Solidity Comparison
+
+| Feature | OpenZeppelin UUPS | OPNet Upgradeable |
+|---------|-------------------|-------------------|
+| Upgrade 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 upgrade | Custom implementation | Built-in |
+
+---
+
+**Navigation:**
+- Previous: [ReentrancyGuard](./reentrancy-guard.md)
+- Next: [Address Type](../types/address.md)

package/docs/core-concepts/blockchain-environment.md

@@ -587,7 +587,6 @@ classDiagram
         +getBlockHash(blockNumber) Uint8Array
         +emit(event) void
         +log(data) void
-        +registerPlugin(plugin) void
     }
 
     class Block {
@@ -715,7 +714,6 @@ export class MyContract extends OP_NET {
 | `Blockchain.getBlockHash()` | `Uint8Array` | Historical block hash |
 | `Blockchain.emit()` | `void` | Emit event |
 | `Blockchain.log()` | `void` | Debug logging (testing only) |
-| `Blockchain.registerPlugin()` | `void` | Register a plugin |
 
 ---
 

package/docs/types/bytes-writer-reader.md

@@ -31,6 +31,7 @@ classDiagram
         -Uint8Array typedArray
         -u32 currentOffset
         +BytesWriter(length)
+        +write~T~(value) void
         +writeU8(value)
         +writeU16(value, be)
         +writeU32(value, be)
@@ -38,9 +39,13 @@ classDiagram
         +writeU128(value, be)
         +writeU256(value, be)
         +writeAddress(addr)
+        +writeExtendedAddress(extAddr)
+        +writeSchnorrSignature(addr, sig)
         +writeString(str)
         +writeBytes(data)
         +writeBoolean(bool)
+        +writeExtendedAddressArray(arr)
+        +writeExtendedAddressMapU256(map)
         +getBuffer() Uint8Array
     }
 
@@ -48,6 +53,7 @@ classDiagram
         -DataView buffer
         -i32 currentOffset
         +BytesReader(bytes)
+        +read~T~() T
         +readU8() u8
         +readU16(be) u16
         +readU32(be) u32
@@ -55,9 +61,13 @@ classDiagram
         +readU128(be) u128
         +readU256(be) u256
         +readAddress() Address
+        +readExtendedAddress() ExtendedAddress
+        +readSchnorrSignature() SchnorrSignature
         +readString() string
         +readBytes(length) Uint8Array
         +readBoolean() bool
+        +readExtendedAddressArray() ExtendedAddress[]
+        +readExtendedAddressMapU256() ExtendedAddressMap
         +hasMoreData() bool
     }
 
@@ -113,6 +123,12 @@ writer.writeI64(value);
 // Address (32 bytes)
 writer.writeAddress(address);
 
+// ExtendedAddress (64 bytes: 32 tweaked key + 32 ML-DSA key hash)
+writer.writeExtendedAddress(extendedAddress);
+
+// Schnorr signature with signer address (128 bytes total)
+writer.writeSchnorrSignature(signerAddress, signature);
+
 // String without length prefix
 writer.writeString('Hello, World!');
 
@@ -129,6 +145,25 @@ writer.writeBytesWithLength(data);
 writer.writeSelector(selector);
 ```
 
+### Generic Write Method
+
+The `write<T>()` method automatically selects the correct write method based on the type:
+
+```typescript
+// Automatically dispatches to the correct write method
+writer.write<u64>(12345);                    // writeU64
+writer.write<u256>(amount);                  // writeU256
+writer.write<bool>(true);                    // writeBoolean
+writer.write<Address>(addr);                 // writeAddress
+writer.write<ExtendedAddress>(extAddr);      // writeExtendedAddress
+writer.write<string>('hello');               // writeStringWithLength
+
+// Supported types:
+// - Primitives: bool, u8, u16, u32, u64, i8, i16, i32, i64
+// - Big numbers: u128, u256, i128
+// - Complex: Address, ExtendedAddress, Selector, string, Uint8Array
+```
+
 ### Writing Arrays
 
 All array methods use a u16 length prefix (max 65535 elements):
@@ -137,6 +172,9 @@ All array methods use a u16 length prefix (max 65535 elements):
 // Address array (u16 length prefix + addresses)
 writer.writeAddressArray(addresses);
 
+// ExtendedAddress array (u16 length prefix + 64-byte addresses)
+writer.writeExtendedAddressArray(extendedAddresses);
+
 // Numeric arrays (u16 length prefix + values)
 writer.writeU8Array(u8Values);
 writer.writeU16Array(u16Values);
@@ -150,6 +188,9 @@ writer.writeArrayOfBuffer(buffers);
 
 // AddressMap<u256> (u16 count, then address + u256 pairs)
 writer.writeAddressMapU256(addressMap);
+
+// ExtendedAddressMap<u256> (u16 count, then 64-byte address + u256 pairs)
+writer.writeExtendedAddressMapU256(extendedAddressMap);
 ```
 
 ### Getting Results
@@ -222,6 +263,14 @@ const i64val: i64 = reader.readI64();
 // Address (32 bytes)
 const addr: Address = reader.readAddress();
 
+// ExtendedAddress (64 bytes: 32 tweaked key + 32 ML-DSA key hash)
+const extAddr: ExtendedAddress = reader.readExtendedAddress();
+
+// Schnorr signature with signer address (128 bytes)
+const schnorrSig: SchnorrSignature = reader.readSchnorrSignature();
+const signer: ExtendedAddress = schnorrSig.address;
+const signature: Uint8Array = schnorrSig.signature;
+
 // String with known length (bytes read, zeroStop = true)
 const name: string = reader.readString(32);  // reads up to 32 bytes, stops at null
 
@@ -238,6 +287,25 @@ const data2: Uint8Array = reader.readBytesWithLength();
 const selector: Selector = reader.readSelector();
 ```
 
+### Generic Read Method
+
+The `read<T>()` method automatically selects the correct read method based on the type:
+
+```typescript
+// Automatically dispatches to the correct read method
+const num: u64 = reader.read<u64>();              // readU64
+const amount: u256 = reader.read<u256>();         // readU256
+const flag: bool = reader.read<bool>();           // readBoolean
+const addr: Address = reader.read<Address>();     // readAddress
+const extAddr: ExtendedAddress = reader.read<ExtendedAddress>();  // readExtendedAddress
+const text: string = reader.read<string>();       // readStringWithLength
+
+// Supported types:
+// - Primitives: bool, u8, u16, u32, u64, i8, i16, i32, i64
+// - Big numbers: u128, u256, i128
+// - Complex: Address, ExtendedAddress, Selector, string
+```
+
 ### Reading Arrays
 
 All array methods expect a u16 length prefix:
@@ -246,6 +314,9 @@ All array methods expect a u16 length prefix:
 // Address array
 const addresses: Address[] = reader.readAddressArray();
 
+// ExtendedAddress array (64 bytes each)
+const extAddresses: ExtendedAddress[] = reader.readExtendedAddressArray();
+
 // Numeric arrays
 const u8Values: u8[] = reader.readU8Array();
 const u16Values: u16[] = reader.readU16Array();
@@ -259,6 +330,9 @@ const buffers: Uint8Array[] = reader.readArrayOfBuffer();
 
 // AddressMap<u256>
 const addressMap: AddressMap<u256> = reader.readAddressMapU256();
+
+// ExtendedAddressMap<u256> (64-byte addresses as keys)
+const extAddressMap: ExtendedAddressMap<u256> = reader.readExtendedAddressMapU256();
 ```
 
 ### Position Management
@@ -291,6 +365,8 @@ reader.verifyEnd(offset + 32);  // Throws Revert if not enough bytes
 | `u128`/`i128` | 16 | Big-endian (default) |
 | `u256` | 32 | Big-endian (default) |
 | `Address` | 32 | Raw bytes |
+| `ExtendedAddress` | 64 | 32 bytes tweaked key + 32 bytes ML-DSA key hash |
+| `SchnorrSignature` | 128 | 64 bytes ExtendedAddress + 64 bytes signature |
 | `Selector` | 4 | Big-endian (u32) |
 | `string` | 4 + n | Length prefix (u32 BE) + UTF-8 |
 | `bytes` | 4 + n | Length prefix (u32 BE) + raw |

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@btc-vision/btc-runtime",
-    "version": "1.10.12",
+    "version": "1.11.0-alpha",
     "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",
@@ -56,17 +56,17 @@
         "docs"
     ],
     "engines": {
-        "node": ">=22.0.0"
+        "node": ">=24.0.0"
     },
     "dependencies": {
         "@assemblyscript/loader": "^0.28.9",
         "@btc-vision/as-bignum": "^0.0.7",
         "@btc-vision/opnet-transform": "^0.2.1",
-        "@eslint/js": "9.39.1",
+        "@eslint/js": "9.39.2",
         "gulplog": "^2.2.0",
         "ts-node": "^10.9.2",
         "typescript": "^5.9.3",
-        "typescript-eslint": "^8.46.3"
+        "typescript-eslint": "^8.53.1"
     },
     "devDependencies": {
         "@btc-vision/as-covers-assembly": "^0.4.4",
@@ -74,7 +74,7 @@
         "@btc-vision/as-pect-assembly": "^8.2.0",
         "@btc-vision/as-pect-cli": "^8.2.0",
         "@btc-vision/as-pect-transform": "^8.2.0",
-        "@types/node": "^24.10.1",
+        "@types/node": "^25.0.9",
         "assemblyscript": "^0.28.9"
     }
 }