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

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.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"
     }
 }

package/runtime/buffer/BytesReader.ts

@@ -1,15 +1,18 @@
 import { i128, u128, u256 } from '@btc-vision/as-bignum/assembly';
 import { AddressMap } from '../generic/AddressMap';
+import { ExtendedAddressMap } from '../generic/ExtendedAddressMap';
 import { Selector } from '../math/abi';
 import { Address } from '../types/Address';
 import { Revert } from '../types/Revert';
 import {
     ADDRESS_BYTE_LENGTH,
+    EXTENDED_ADDRESS_BYTE_LENGTH,
     I128_BYTE_LENGTH,
     I16_BYTE_LENGTH,
     I32_BYTE_LENGTH,
     I64_BYTE_LENGTH,
     I8_BYTE_LENGTH,
+    SCHNORR_SIGNATURE_BYTE_LENGTH,
     U128_BYTE_LENGTH,
     U16_BYTE_LENGTH,
     U256_BYTE_LENGTH,
@@ -17,6 +20,8 @@ import {
     U64_BYTE_LENGTH,
     U8_BYTE_LENGTH,
 } from '../utils';
+import { ExtendedAddress } from '../types/ExtendedAddress';
+import { SchnorrSignature } from '../types/SchnorrSignature';
 
 @final
 export class BytesReader {
@@ -32,8 +37,7 @@ export class BytesReader {
     }
 
     public read<T>(): T {
-        const id = idof<T>();
-
+        // Handle primitives first (before calling idof which doesn't work on primitives)
         if (isBoolean<T>()) {
             return this.readBoolean() as T;
         } else if (isString<T>()) {
@@ -70,12 +74,19 @@ export class BytesReader {
                         throw new Revert(`Invalid size ${size}`);
                 }
             }
-        } else if (id === idof<u256>()) {
+        }
+
+        // For reference types, use idof
+        const id = idof<T>();
+
+        if (id === idof<u256>()) {
             return this.readU256() as T;
         } else if (id === idof<u128>()) {
             return this.readU128() as T;
         } else if (id === idof<i128>()) {
             return this.readI128() as T;
+        } else if (id === idof<ExtendedAddress>()) {
+            return this.readExtendedAddress() as T;
         } else if (id === idof<Address>()) {
             return this.readAddress() as T;
         } else if (id === idof<Uint8Array>()) {
@@ -245,6 +256,48 @@ export class BytesReader {
         return addr;
     }
 
+    /**
+     * Reads an ExtendedAddress (64 bytes).
+     * Format: [32 bytes tweakedPublicKey][32 bytes ML-DSA key hash]
+     *
+     * @returns The ExtendedAddress read from the buffer
+     */
+    public readExtendedAddress(): ExtendedAddress {
+        this.verifyEnd(this.currentOffset + EXTENDED_ADDRESS_BYTE_LENGTH);
+
+        // Read tweaked public key (32 bytes)
+        const tweakedPublicKey: u8[] = new Array<u8>(ADDRESS_BYTE_LENGTH);
+        for (let i: i32 = 0; i < ADDRESS_BYTE_LENGTH; i++) {
+            tweakedPublicKey[i] = this.readU8();
+        }
+
+        // Read ML-DSA key hash (32 bytes)
+        const publicKey: u8[] = new Array<u8>(ADDRESS_BYTE_LENGTH);
+        for (let i: i32 = 0; i < ADDRESS_BYTE_LENGTH; i++) {
+            publicKey[i] = this.readU8();
+        }
+
+        return new ExtendedAddress(tweakedPublicKey, publicKey);
+    }
+
+    /**
+     * Reads a Schnorr signature with its associated ExtendedAddress.
+     * Format: [64 bytes ExtendedAddress][64 bytes signature]
+     *
+     * Used for deserializing signed data where both the signer's address
+     * and their Schnorr signature are stored together.
+     *
+     * @returns A SchnorrSignature containing the address and signature
+     */
+    public readSchnorrSignature(): SchnorrSignature {
+        this.verifyEnd(this.currentOffset + EXTENDED_ADDRESS_BYTE_LENGTH + SCHNORR_SIGNATURE_BYTE_LENGTH);
+
+        const address = this.readExtendedAddress();
+        const signature = this.readBytes(SCHNORR_SIGNATURE_BYTE_LENGTH);
+
+        return new SchnorrSignature(address, signature);
+    }
+
     // ------------------- Arrays ------------------- //
 
     public readArrayOfBuffer(be: boolean = true): Uint8Array[] {
@@ -336,6 +389,40 @@ export class BytesReader {
         return result;
     }
 
+    /**
+     * Reads an array of ExtendedAddress (64 bytes each).
+     * Format: [u16 length][ExtendedAddress 0][ExtendedAddress 1]...
+     */
+    public readExtendedAddressArray(be: boolean = true): ExtendedAddress[] {
+        const length = this.readU16(be);
+        const result = new Array<ExtendedAddress>(length);
+        for (let i: u16 = 0; i < length; i++) {
+            result[i] = this.readExtendedAddress();
+        }
+        return result;
+    }
+
+    /**
+     * Reads a map of ExtendedAddress -> u256.
+     * Format: [u16 length][ExtendedAddress key][u256 value]...
+     */
+    public readExtendedAddressMapU256(be: boolean = true): ExtendedAddressMap<u256> {
+        const length = this.readU16(be);
+        const result = new ExtendedAddressMap<u256>();
+
+        for (let i: u16 = 0; i < length; i++) {
+            const address = this.readExtendedAddress();
+            const value = this.readU256(be);
+
+            if (result.has(address)) {
+                throw new Revert('Duplicate extended address found in map');
+            }
+            result.set(address, value);
+        }
+
+        return result;
+    }
+
     public getOffset(): i32 {
         return this.currentOffset;
     }

package/runtime/buffer/BytesWriter.ts

@@ -1,15 +1,18 @@
 import { i128, u128, u256 } from '@btc-vision/as-bignum/assembly';
 import { AddressMap } from '../generic/AddressMap';
+import { ExtendedAddressMap } from '../generic/ExtendedAddressMap';
 import { Selector } from '../math/abi';
 import { Address } from '../types/Address';
 import { Revert } from '../types/Revert';
 import {
     ADDRESS_BYTE_LENGTH,
+    EXTENDED_ADDRESS_BYTE_LENGTH,
     I128_BYTE_LENGTH,
     I16_BYTE_LENGTH,
     I32_BYTE_LENGTH,
     I64_BYTE_LENGTH,
     I8_BYTE_LENGTH,
+    SCHNORR_SIGNATURE_BYTE_LENGTH,
     U128_BYTE_LENGTH,
     U16_BYTE_LENGTH,
     U256_BYTE_LENGTH,
@@ -17,6 +20,7 @@ import {
     U64_BYTE_LENGTH,
     U8_BYTE_LENGTH,
 } from '../utils';
+import { ExtendedAddress } from '../types/ExtendedAddress';
 import { BytesReader } from './BytesReader';
 
 const arrayTooLargeError: string = 'Array is too large';
@@ -90,10 +94,14 @@ export class BytesWriter {
             this.writeBoolean(<boolean>value);
         } else if (isString<T>()) {
             this.writeStringWithLength(<string>value);
-        } else if (value instanceof Uint8Array) {
-            this.writeBytesWithLength(<Uint8Array>value);
+        } else if (value instanceof ExtendedAddress) {
+            // Check ExtendedAddress before Address (ExtendedAddress extends Address)
+            this.writeExtendedAddress(<ExtendedAddress>value);
         } else if (value instanceof Address) {
+            // Check Address before Uint8Array (Address extends Uint8Array)
             this.writeAddress(<Address>value);
+        } else if (value instanceof Uint8Array) {
+            this.writeBytesWithLength(<Uint8Array>value);
         } else if (value instanceof u128) {
             this.writeU128(<u128>value);
         } else if (value instanceof u256) {
@@ -291,6 +299,20 @@ export class BytesWriter {
         }
     }
 
+    /**
+     * Writes an array of ExtendedAddress (64 bytes each).
+     * Format: [u16 length][ExtendedAddress 0][ExtendedAddress 1]...
+     */
+    public writeExtendedAddressArray(value: ExtendedAddress[]): void {
+        if (value.length > 65535) throw new Revert(arrayTooLargeError);
+        this.allocSafe(U16_BYTE_LENGTH + value.length * EXTENDED_ADDRESS_BYTE_LENGTH);
+        this.writeU16(u16(value.length));
+
+        for (let i: i32 = 0; i < value.length; i++) {
+            this.writeExtendedAddress(value[i]);
+        }
+    }
+
     // --------------------------------------------------- //
 
     public writeBytes(value: Uint8Array): void {
@@ -336,6 +358,42 @@ export class BytesWriter {
         this.writeBytes(bytes);
     }
 
+    /**
+     * Writes an ExtendedAddress (64 bytes total).
+     * Format: [32 bytes tweakedPublicKey][32 bytes ML-DSA key hash]
+     *
+     * @param value - The ExtendedAddress to write
+     */
+    public writeExtendedAddress(value: ExtendedAddress): void {
+        this.allocSafe(EXTENDED_ADDRESS_BYTE_LENGTH);
+        // Write tweaked public key first (32 bytes)
+        this.writeBytes(value.tweakedPublicKey);
+        // Write ML-DSA key hash (32 bytes) - inherited from Address
+        this.writeBytes(value);
+    }
+
+    /**
+     * Writes a Schnorr signature with its associated ExtendedAddress.
+     * Format: [64 bytes ExtendedAddress][64 bytes signature]
+     *
+     * Used for serializing signed data where both the signer's address
+     * and their Schnorr signature need to be stored together.
+     *
+     * @param address - The signer's ExtendedAddress (64 bytes)
+     * @param signature - The 64-byte Schnorr signature
+     * @throws {Revert} If signature is not exactly 64 bytes
+     */
+    public writeSchnorrSignature(address: ExtendedAddress, signature: Uint8Array): void {
+        if (signature.length !== SCHNORR_SIGNATURE_BYTE_LENGTH) {
+            throw new Revert(
+                `Invalid Schnorr signature length: expected ${SCHNORR_SIGNATURE_BYTE_LENGTH}, got ${signature.length}`,
+            );
+        }
+        this.allocSafe(EXTENDED_ADDRESS_BYTE_LENGTH + SCHNORR_SIGNATURE_BYTE_LENGTH);
+        this.writeExtendedAddress(address);
+        this.writeBytes(signature);
+    }
+
     // zero-copy bulk writer
     public writeRaw(data: Uint8Array): void {
         const n = data.length;
@@ -369,7 +427,7 @@ export class BytesWriter {
     }
 
     /**
-     * Equivalent to TS’s writeAddressValueTuple, except specialized for u256 values.
+     * Equivalent to TS's writeAddressValueTuple, except specialized for u256 values.
      */
     public writeAddressMapU256(value: AddressMap<u256>, be: boolean = true): void {
         const keys: Address[] = value.keys();
@@ -383,6 +441,22 @@ export class BytesWriter {
         }
     }
 
+    /**
+     * Writes a map of ExtendedAddress -> u256.
+     * Format: [u16 length][ExtendedAddress key][u256 value]...
+     */
+    public writeExtendedAddressMapU256(value: ExtendedAddressMap<u256>, be: boolean = true): void {
+        const keys: ExtendedAddress[] = value.keys();
+        if (keys.length > 65535) throw new Revert('Map size is too large');
+
+        this.writeU16(u16(keys.length), be);
+
+        for (let i: i32 = 0; i < keys.length; i++) {
+            this.writeExtendedAddress(keys[i]);
+            this.writeU256(value.get(keys[i]), be);
+        }
+    }
+
     // --------------------------------------------------- //
 
     public getBuffer(): Uint8Array {
@@ -402,6 +476,10 @@ export class BytesWriter {
      * If not, calls `resize()` which by default throws a Revert.
      */
     public allocSafe(size: u32): void {
+        if (size > u32.MAX_VALUE - this.currentOffset) {
+            throw new Revert('BytesWriter: offset overflow');
+        }
+
         const needed = this.currentOffset + size;
         if (needed > u32(this.buffer.byteLength)) {
             const sizeDiff: u32 = needed - u32(this.buffer.byteLength);

package/runtime/contracts/OP721.ts

@@ -1,3 +1,6 @@
+// THIS STANDARD IS EXPERIMENTAL AND SHOULDN'T BE USED IN REAL PROJECTS
+// CONTRACTS USING THIS COULD BREAK IN THE FUTURE
+
 import { u256 } from '@btc-vision/as-bignum/assembly';
 import { BytesWriter } from '../buffer/BytesWriter';
 import { Blockchain } from '../env';
@@ -305,6 +308,36 @@ export abstract class OP721 extends ReentrancyGuard implements IOP721 {
         return w;
     }
 
+    @method(
+        { name: 'to', type: ABIDataTypes.ADDRESS },
+        { name: 'tokenId', type: ABIDataTypes.UINT256 },
+    )
+    @emit('Transferred')
+    public transfer(calldata: Calldata): BytesWriter {
+        const to = calldata.readAddress();
+        const tokenId = calldata.readU256();
+
+        this._transfer(Blockchain.tx.sender, to, tokenId);
+
+        return new BytesWriter(0);
+    }
+
+    @method(
+        { name: 'from', type: ABIDataTypes.ADDRESS },
+        { name: 'to', type: ABIDataTypes.ADDRESS },
+        { name: 'tokenId', type: ABIDataTypes.UINT256 },
+    )
+    @emit('Transferred')
+    public transferFrom(calldata: Calldata): BytesWriter {
+        const from = calldata.readAddress();
+        const to = calldata.readAddress();
+        const amount = calldata.readU256();
+
+        this._transfer(from, to, amount);
+
+        return new BytesWriter(0);
+    }
+
     @method(
         { name: 'to', type: ABIDataTypes.ADDRESS },
         { name: 'tokenId', type: ABIDataTypes.UINT256 },
@@ -316,7 +349,7 @@ export abstract class OP721 extends ReentrancyGuard implements IOP721 {
         const tokenId = calldata.readU256();
         const data = calldata.readBytesWithLength();
 
-        this._transfer(Blockchain.tx.sender, to, tokenId, data);
+        this._safeTransfer(Blockchain.tx.sender, to, tokenId, data);
 
         return new BytesWriter(0);
     }
@@ -334,7 +367,7 @@ export abstract class OP721 extends ReentrancyGuard implements IOP721 {
         const tokenId = calldata.readU256();
         const data = calldata.readBytesWithLength();
 
-        this._transfer(from, to, tokenId, data);
+        this._safeTransfer(from, to, tokenId, data);
 
         return new BytesWriter(0);
     }
@@ -637,7 +670,7 @@ export abstract class OP721 extends ReentrancyGuard implements IOP721 {
         this.createTransferEvent(owner, Address.zero(), tokenId);
     }
 
-    protected _transfer(from: Address, to: Address, tokenId: u256, data: Uint8Array): void {
+    protected _transfer(from: Address, to: Address, tokenId: u256): void {
         // Skip self-transfers
         if (from === to) return;
 
@@ -680,8 +713,11 @@ export abstract class OP721 extends ReentrancyGuard implements IOP721 {
         this.ownerOfMap.set(tokenId, this._u256FromAddress(to));
 
         this.createTransferEvent(from, to, tokenId);
+    }
+
+    protected _safeTransfer(from: Address, to: Address, tokenId: u256, data: Uint8Array): void {
+        this._transfer(from,  to, tokenId);
 
-        // External call happens after all state changes
         if (Blockchain.isContract(to)) {
             this._checkOnOP721Received(from, to, tokenId, data);
         }

package/runtime/contracts/OP_NET.ts

@@ -7,8 +7,15 @@ import { Calldata } from '../types';
 import { Address } from '../types/Address';
 import { Revert } from '../types/Revert';
 import { ADDRESS_BYTE_LENGTH } from '../utils';
+import { Plugin } from '../plugins/Plugin';
 
 export class OP_NET implements IBTC {
+    /**
+     * Registered plugins that can handle method selectors.
+     * Plugins are checked in registration order when execute() is called.
+     */
+    private readonly _plugins: Plugin[] = [];
+
     public get address(): Address {
         return Blockchain.contractAddress;
     }
@@ -17,25 +24,90 @@ export class OP_NET implements IBTC {
         return Blockchain.contractDeployer;
     }
 
-    public onDeployment(_calldata: Calldata): void {}
+    public onDeployment(calldata: Calldata): void {
+        // Call onDeployment for all registered plugins
+        for (let i = 0; i < this._plugins.length; i++) {
+            this._plugins[i].onDeployment(calldata);
+        }
+    }
 
-    public onExecutionStarted(_selector: Selector, _calldata: Calldata): void {}
+    /**
+     * Called when the contract's bytecode is updated via updateContractFromExisting.
+     * Override this method to perform migration logic when the contract is upgraded.
+     *
+     * @param calldata - The calldata passed to updateContractFromExisting
+     *
+     * @example
+     * ```typescript
+     * public override onUpdate(calldata: Calldata): void {
+     *     super.onUpdate(calldata); // Call plugins
+     *     const version = calldata.readU64();
+     *     // Perform migration based on version
+     * }
+     * ```
+     */
+    public onUpdate(calldata: Calldata): void {
+        // Call onUpdate for all registered plugins
+        for (let i = 0; i < this._plugins.length; i++) {
+            this._plugins[i].onUpdate(calldata);
+        }
+    }
 
-    public onExecutionCompleted(_selector: Selector, _calldata: Calldata): void {}
+    public onExecutionStarted(selector: Selector, calldata: Calldata): void {
+        // Call onExecutionStarted for all registered plugins
+        for (let i = 0; i < this._plugins.length; i++) {
+            this._plugins[i].onExecutionStarted(selector, calldata);
+        }
+    }
 
-    public execute(method: Selector, _calldata: Calldata): BytesWriter {
-        let response: BytesWriter;
+    public onExecutionCompleted(selector: Selector, calldata: Calldata): void {
+        // Call onExecutionCompleted for all registered plugins
+        for (let i = 0; i < this._plugins.length; i++) {
+            this._plugins[i].onExecutionCompleted(selector, calldata);
+        }
+    }
 
+    public execute(method: Selector, calldata: Calldata): BytesWriter {
+        // Check built-in methods first
         switch (method) {
-            case encodeSelector('deployer()'):
-                response = new BytesWriter(ADDRESS_BYTE_LENGTH);
+            case encodeSelector('deployer()'): {
+                const response = new BytesWriter(ADDRESS_BYTE_LENGTH);
                 response.writeAddress(this.contractDeployer);
-                break;
-            default:
-                throw new Revert(`Method not found: ${method}`);
+                return response;
+            }
         }
 
-        return response;
+        // Try registered plugins
+        const startOffset = calldata.getOffset();
+        for (let i = 0; i < this._plugins.length; i++) {
+            const result = this._plugins[i].execute(method, calldata);
+            if (result !== null) {
+                return result;
+            }
+
+            calldata.setOffset(startOffset);
+        }
+
+        // No handler found
+        throw new Revert(`Method not found: ${method}`);
+    }
+
+    /**
+     * Registers a plugin to handle method selectors automatically.
+     * Plugins are checked in registration order when the contract's execute() falls through to super.
+     *
+     * @example
+     * ```typescript
+     * public constructor() {
+     *     super();
+     *     this.registerPlugin(new UpgradeablePlugin(144));
+     * }
+     * ```
+     *
+     * @param plugin - The plugin to register
+     */
+    protected registerPlugin(plugin: Plugin): void {
+        this._plugins.push(plugin);
     }
 
     protected emitEvent(event: NetEvent): void {