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

package/runtime/contracts/Upgradeable.ts

@@ -0,0 +1,242 @@
+import { u256 } from '@btc-vision/as-bignum/assembly';
+import { Blockchain } from '../env';
+import { OP_NET } from './OP_NET';
+import { StoredAddress } from '../storage/StoredAddress';
+import { StoredU256 } from '../storage/StoredU256';
+import { Address } from '../types/Address';
+import { Revert } from '../types/Revert';
+import { BytesWriter } from '../buffer/BytesWriter';
+import { EMPTY_POINTER } from '../math/bytes';
+import {
+    UpgradeSubmittedEvent,
+    UpgradeAppliedEvent,
+    UpgradeCancelledEvent,
+} from '../events/upgradeable/UpgradeableEvents';
+
+const pendingUpgradeAddressPointer: u16 = Blockchain.nextPointer;
+const pendingUpgradeBlockPointer: u16 = Blockchain.nextPointer;
+
+/**
+ * Upgradeable - Base contract for upgradeable contracts with timelock protection.
+ *
+ * This contract provides a secure upgrade mechanism with a configurable delay period.
+ * The pattern prevents instant malicious upgrades by requiring:
+ * 1. submitUpgrade() - Submit the source contract address, starts the timelock
+ * 2. Wait for the delay period to pass
+ * 3. applyUpgrade() - Apply the upgrade after the delay
+ *
+ * Users can monitor for UpgradeSubmitted events and exit if they distrust pending changes.
+ *
+ * @example
+ * ```typescript
+ * @final
+ * export class MyUpgradeableContract extends Upgradeable {
+ *     // Set a 24-hour delay (144 blocks at 10 min/block)
+ *     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 updateCalldata = new BytesWriter(calldata.byteLength - ADDRESS_BYTE_LENGTH);
+ *                 // Copy remaining calldata for onUpdate
+ *                 return this.applyUpgrade(sourceAddress, updateCalldata);
+ *             case encodeSelector('cancelUpgrade'):
+ *                 return this.cancelUpgrade();
+ *             default:
+ *                 return super.execute(method, calldata);
+ *         }
+ *     }
+ * }
+ * ```
+ */
+export class Upgradeable extends OP_NET {
+    /**
+     * The pending upgrade source address.
+     * Zero address means no pending upgrade.
+     */
+    protected readonly _pendingUpgradeAddress: StoredAddress;
+
+    /**
+     * The block number when the upgrade was submitted.
+     * Stored as u256, used as u64.
+     */
+    protected readonly _pendingUpgradeBlock: StoredU256;
+
+    /**
+     * The number of blocks to wait before an upgrade can be applied.
+     * Override this in derived contracts to set the delay.
+     *
+     * Common values:
+     * - 6 blocks = ~1 hour
+     * - 144 blocks = ~24 hours
+     * - 1008 blocks = ~1 week
+     */
+    protected readonly upgradeDelay: u64 = 144; // ~24 hours default
+
+    protected constructor() {
+        super();
+        this._pendingUpgradeAddress = new StoredAddress(pendingUpgradeAddressPointer);
+        this._pendingUpgradeBlock = new StoredU256(pendingUpgradeBlockPointer, EMPTY_POINTER);
+    }
+
+    /**
+     * Returns the pending upgrade source address.
+     * Returns zero address if no upgrade is pending.
+     */
+    public get pendingUpgradeAddress(): Address {
+        return this._pendingUpgradeAddress.value;
+    }
+
+    /**
+     * Returns the block number when the pending upgrade was submitted.
+     * Returns 0 if no upgrade is pending.
+     */
+    public get pendingUpgradeBlock(): u64 {
+        return this._pendingUpgradeBlock.value.lo1;
+    }
+
+    /**
+     * Returns the block number when the pending upgrade can be applied.
+     * Returns 0 if no upgrade is pending.
+     */
+    public get upgradeEffectiveBlock(): u64 {
+        const submitBlock = this.pendingUpgradeBlock;
+        if (submitBlock === 0) return 0;
+        return submitBlock + this.upgradeDelay;
+    }
+
+    /**
+     * Returns true if there is a pending upgrade.
+     */
+    public get hasPendingUpgrade(): bool {
+        return this.pendingUpgradeBlock !== 0;
+    }
+
+    /**
+     * Returns true if the pending upgrade can be applied (delay has passed).
+     */
+    public get canApplyUpgrade(): bool {
+        if (!this.hasPendingUpgrade) return false;
+        return Blockchain.block.number >= this.upgradeEffectiveBlock;
+    }
+
+    /**
+     * Submits an upgrade for timelock.
+     *
+     * The source address must be a deployed contract containing the new bytecode.
+     * After submission, the upgrade can only be applied after upgradeDelay blocks.
+     *
+     * Emits UpgradeSubmitted event.
+     *
+     * @param sourceAddress - The source contract address containing new bytecode
+     * @returns Empty response
+     * @throws If caller is not deployer
+     * @throws If source is not a deployed contract
+     * @throws If an upgrade is already pending
+     */
+    protected submitUpgrade(sourceAddress: Address): BytesWriter {
+        this.onlyDeployer(Blockchain.tx.sender);
+
+        // Check no pending upgrade
+        if (this.hasPendingUpgrade) {
+            throw new Revert('Upgrade already pending. Cancel first.');
+        }
+
+        // Validate source is a deployed contract
+        if (!Blockchain.isContract(sourceAddress)) {
+            throw new Revert('Source must be a deployed contract');
+        }
+
+        // Store pending upgrade
+        const currentBlock = Blockchain.block.number;
+        this._pendingUpgradeAddress.value = sourceAddress;
+        this._pendingUpgradeBlock.value = u256.fromU64(currentBlock);
+
+        // Emit event
+        const effectiveBlock = currentBlock + this.upgradeDelay;
+        Blockchain.emit(new UpgradeSubmittedEvent(sourceAddress, currentBlock, effectiveBlock));
+
+        return new BytesWriter(0);
+    }
+
+    /**
+     * Applies a pending upgrade after the timelock period has passed.
+     *
+     * The provided address must match the pending upgrade address as an
+     * additional security measure against front-running attacks.
+     *
+     * Emits UpgradeApplied event before the upgrade (new bytecode takes effect next block).
+     *
+     * @param sourceAddress - The source contract address (must match pending)
+     * @param calldata - The calldata to pass to onUpdate method of the new contract
+     * @returns Empty response
+     * @throws If caller is not deployer
+     * @throws If no upgrade is pending
+     * @throws If delay has not passed
+     * @throws If provided address does not match pending
+     */
+    protected applyUpgrade(sourceAddress: Address, calldata: BytesWriter): BytesWriter {
+        this.onlyDeployer(Blockchain.tx.sender);
+
+        // Check pending upgrade exists
+        if (!this.hasPendingUpgrade) {
+            throw new Revert('No pending upgrade');
+        }
+
+        // Check delay has passed
+        if (!this.canApplyUpgrade) {
+            throw new Revert('Upgrade delay not elapsed');
+        }
+
+        // Verify address matches pending
+        if (!sourceAddress.equals(this._pendingUpgradeAddress.value)) {
+            throw new Revert('Address does not match pending upgrade');
+        }
+
+        // Clear pending state before upgrade
+        this._pendingUpgradeAddress.value = Address.zero();
+        this._pendingUpgradeBlock.value = u256.Zero;
+
+        // Emit event
+        Blockchain.emit(new UpgradeAppliedEvent(sourceAddress, Blockchain.block.number));
+
+        // Perform upgrade - new bytecode takes effect next block
+        Blockchain.updateContractFromExisting(sourceAddress, calldata);
+
+        return new BytesWriter(0);
+    }
+
+    /**
+     * Cancels a pending upgrade.
+     *
+     * Can only be called by the deployer. Clears the pending upgrade state.
+     *
+     * Emits UpgradeCancelled event.
+     *
+     * @returns Empty response
+     * @throws If caller is not deployer
+     * @throws If no upgrade is pending
+     */
+    protected cancelUpgrade(): BytesWriter {
+        this.onlyDeployer(Blockchain.tx.sender);
+
+        // Check pending upgrade exists
+        if (!this.hasPendingUpgrade) {
+            throw new Revert('No pending upgrade');
+        }
+
+        const pendingAddress = this._pendingUpgradeAddress.value;
+
+        // Clear pending state
+        this._pendingUpgradeAddress.value = Address.zero();
+        this._pendingUpgradeBlock.value = u256.Zero;
+
+        // Emit event
+        Blockchain.emit(new UpgradeCancelledEvent(pendingAddress, Blockchain.block.number));
+
+        return new BytesWriter(0);
+    }
+}

package/runtime/env/BlockchainEnvironment.ts

@@ -22,12 +22,12 @@ import {
     storePointer,
     tLoadPointer,
     tStorePointer,
+    updateFromAddress,
     validateBitcoinAddress,
     verifySignature,
 } from './global';
 import { eqUint, MapUint8Array } from '../generic/MapUint8Array';
 import { EMPTY_BUFFER } from '../math/bytes';
-import { Plugin } from '../plugins/Plugin';
 import { Calldata } from '../types';
 import { Revert } from '../types/Revert';
 import { Selector } from '../math/abi';
@@ -75,7 +75,6 @@ export class BlockchainEnvironment {
     private storage: MapUint8Array = new MapUint8Array();
     private transientStorage: MapUint8Array = new MapUint8Array();
     private _selfContract: Potential<OP_NET> = null;
-    private _plugins: Plugin[] = [];
     private _network: Networks = Networks.Unknown;
 
     /**
@@ -268,32 +267,29 @@ export class BlockchainEnvironment {
     }
 
     /**
-     * Registers a plugin to extend contract functionality.
+     * Handles contract deployment initialization.
      *
-     * @param plugin - Plugin instance to register
+     * @param calldata - Deployment parameters
      *
      * @remarks
-     * Plugins execute in registration order and have full access to contract state.
+     * Called once during deployment. Delegates to the contract's onDeployment
+     * which handles plugin notification.
      */
-    public registerPlugin(plugin: Plugin): void {
-        this._plugins.push(plugin);
+    public onDeployment(calldata: Calldata): void {
+        this.contract.onDeployment(calldata);
     }
 
     /**
-     * Handles contract deployment initialization.
+     * Handles contract bytecode update.
      *
-     * @param calldata - Deployment parameters
+     * @param calldata - Update parameters passed to updateContractFromExisting
      *
      * @remarks
-     * Called once during deployment. State changes here are permanent.
+     * Called when the contract's bytecode is updated. Delegates to the contract's
+     * onUpdate which handles plugin notification and migration logic.
      */
-    public onDeployment(calldata: Calldata): void {
-        const len = this._plugins.length;
-        for (let i: i32 = 0; i < len; i++) {
-            // Unchecked access for speed
-            unchecked(this._plugins[i].onDeployment(calldata));
-        }
-        this.contract.onDeployment(calldata);
+    public onUpdate(calldata: Calldata): void {
+        this.contract.onUpdate(calldata);
     }
 
     /**
@@ -303,13 +299,9 @@ export class BlockchainEnvironment {
      * @param calldata - Method parameters
      *
      * @remarks
-     * Used for access control, reentrancy guards, and validation.
+     * Delegates to the contract's onExecutionStarted which handles plugin notification.
      */
     public onExecutionStarted(selector: Selector, calldata: Calldata): void {
-        const len = this._plugins.length;
-        for (let i: i32 = 0; i < len; i++) {
-            unchecked(this._plugins[i].onExecutionStarted(selector, calldata));
-        }
         this.contract.onExecutionStarted(selector, calldata);
     }
 
@@ -320,13 +312,9 @@ export class BlockchainEnvironment {
      * @param calldata - Method parameters that were passed
      *
      * @remarks
-     * Only called on successful execution. Used for cleanup and events.
+     * Delegates to the contract's onExecutionCompleted which handles plugin notification.
      */
     public onExecutionCompleted(selector: Selector, calldata: Calldata): void {
-        const len = this._plugins.length;
-        for (let i: i32 = 0; i < len; i++) {
-            unchecked(this._plugins[i].onExecutionCompleted(selector, calldata));
-        }
         this.contract.onExecutionCompleted(selector, calldata);
     }
 
@@ -591,6 +579,115 @@ export class BlockchainEnvironment {
         return contractAddressReader.readAddress();
     }
 
+    /**
+     * Updates this contract's bytecode from an existing deployed contract.
+     *
+     * This method triggers a bytecode replacement where the calling contract's execution
+     * logic is replaced with the bytecode from the source contract. The new bytecode
+     * takes effect at the next block.
+     *
+     * @param sourceAddress - Address of the contract containing the new bytecode
+     * @param [calldata] - Optional parameters passed to the new bytecode's onUpdate method
+     * @throws {Revert} When the source address is invalid or the update fails
+     *
+     * @warning This is a privileged operation with significant implications:
+     *          - Storage layout compatibility is entirely the developer's responsibility
+     *          - The contract address and all storage slots persist unchanged
+     *          - Only the execution logic changes
+     *          - The source contract must be an already-deployed contract
+     *
+     * @remarks
+     * Contracts should implement their own permission checks and optional timelock
+     * patterns before calling this method. A recommended pattern is:
+     *
+     * 1. `submitUpdate(address)` - Logs source address and block number, validates
+     *    that the address is an existing deployed contract
+     * 2. `applyUpdate(address)` - Can only be called after a configured delay,
+     *    verifies address matches the submitted one, then calls this method
+     *
+     * This pattern gives users time to assess pending changes and exit if needed.
+     *
+     * @example
+     * ```typescript
+     * // Simple immediate update (not recommended for production)
+     * public upgrade(calldata: Calldata): BytesWriter {
+     *     this.onlyDeployer(Blockchain.tx.sender);
+     *     const newBytecodeAddress = calldata.readAddress();
+     *     Blockchain.updateContractFromExisting(newBytecodeAddress);
+     *     return new BytesWriter(0);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Timelock pattern (recommended)
+     * private pendingUpdatePointer: u16 = Blockchain.nextPointer;
+     * private pendingUpdate: StoredAddress = new StoredAddress(this.pendingUpdatePointer);
+     *
+     * private pendingUpdateBlockPointer: u16 = Blockchain.nextPointer;
+     * private pendingUpdateBlock: StoredU64 = new StoredU64(this.pendingUpdateBlockPointer);
+     *
+     * private readonly UPDATE_DELAY: u64 = 144; // ~1 day in blocks
+     *
+     * public submitUpdate(calldata: Calldata): BytesWriter {
+     *     this.onlyDeployer(Blockchain.tx.sender);
+     *     const sourceAddress = calldata.readAddress();
+     *
+     *     // Validate source is an existing contract
+     *     if (!Blockchain.isContract(sourceAddress)) {
+     *         throw new Revert('Source must be a deployed contract');
+     *     }
+     *
+     *     this.pendingUpdate.value = sourceAddress;
+     *     this.pendingUpdateBlock.value = Blockchain.block.number;
+     *     return new BytesWriter(0);
+     * }
+     *
+     * public applyUpdate(calldata: Calldata): BytesWriter {
+     *     this.onlyDeployer(Blockchain.tx.sender);
+     *     const sourceAddress = calldata.readAddress();
+     *
+     *     // Verify address matches pending update
+     *     if (!sourceAddress.equals(this.pendingUpdate.value)) {
+     *         throw new Revert('Address does not match pending update');
+     *     }
+     *
+     *     // Verify delay has passed
+     *     const submitBlock = this.pendingUpdateBlock.value;
+     *     if (Blockchain.block.number < submitBlock + this.UPDATE_DELAY) {
+     *         throw new Revert('Update delay not elapsed');
+     *     }
+     *
+     *     Blockchain.updateContractFromExisting(sourceAddress);
+     *     return new BytesWriter(0);
+     * }
+     * ```
+     */
+    public updateContractFromExisting(
+        sourceAddress: Address,
+        calldata: BytesWriter | null = null,
+    ): void {
+        if (!sourceAddress) {
+            throw new Revert('Source address is required');
+        }
+
+        if (!this.isContract(sourceAddress)) {
+            throw new Revert('Source address must be a deployed contract');
+        }
+
+        const callDataBuffer = calldata ? calldata.getBuffer().buffer : new ArrayBuffer(0);
+
+        const status = updateFromAddress(
+            sourceAddress.buffer,
+            callDataBuffer,
+            callDataBuffer.byteLength,
+        );
+
+        if (status !== 0) {
+            throw new Revert('Failed to update contract bytecode');
+        }
+    }
+
     /**
      * Reads a value from persistent storage.
      *

package/runtime/env/global.ts

@@ -65,6 +65,30 @@ export declare function tStorePointer(key: ArrayBuffer, value: ArrayBuffer): voi
 @external('env', 'deployFromAddress')
 export declare function deployFromAddress(originAddress: ArrayBuffer, salt: ArrayBuffer, calldata: ArrayBuffer, calldataLength: u32, resultAddress: ArrayBuffer): u32;
 
+/**
+ * Updates the calling contract's bytecode from an existing contract.
+ *
+ * This VM opcode enables bytecode replacement where a contract can replace its own
+ * execution logic by referencing another deployed contract containing the new WASM bytecode.
+ * The new bytecode takes effect at the next block.
+ *
+ * @param {ArrayBuffer} sourceAddress - The address of the contract containing the new bytecode.
+ * @param {ArrayBuffer} calldata - The calldata for the update (passed to onUpdate if implemented).
+ * @param {u32} calldataLength - The length of the calldata.
+ * @returns {u32} - Status code (0 = success, non-zero = failure).
+ *
+ * @remarks
+ * - The source contract must be an already-deployed contract
+ * - Storage layout compatibility is the developer's responsibility
+ * - The contract address and all storage slots persist unchanged
+ * - Only the execution logic changes
+ *
+ * @warning This is a privileged operation. Contracts should implement their own
+ *          permission checks and optional timelock patterns before calling this.
+ */
+@external('env', 'updateFromAddress')
+export declare function updateFromAddress(sourceAddress: ArrayBuffer, calldata: ArrayBuffer, calldataLength: u32): u32;
+
 /**
  * Calls a contract.
  * @param {ArrayBuffer} address - The address of the contract to call.

package/runtime/events/upgradeable/UpgradeableEvents.ts

@@ -0,0 +1,41 @@
+import { NetEvent } from '../NetEvent';
+import { BytesWriter } from '../../buffer/BytesWriter';
+import { Address } from '../../types/Address';
+import { ADDRESS_BYTE_LENGTH } from '../../utils';
+
+/**
+ * Event emitted when an upgrade is submitted for timelock.
+ */
+export class UpgradeSubmittedEvent extends NetEvent {
+    constructor(sourceAddress: Address, submitBlock: u64, effectiveBlock: u64) {
+        const data = new BytesWriter(ADDRESS_BYTE_LENGTH + 16);
+        data.writeAddress(sourceAddress);
+        data.writeU64(submitBlock);
+        data.writeU64(effectiveBlock);
+        super('UpgradeSubmitted', data);
+    }
+}
+
+/**
+ * Event emitted when an upgrade is applied.
+ */
+export class UpgradeAppliedEvent extends NetEvent {
+    constructor(sourceAddress: Address, appliedAtBlock: u64) {
+        const data = new BytesWriter(ADDRESS_BYTE_LENGTH + 8);
+        data.writeAddress(sourceAddress);
+        data.writeU64(appliedAtBlock);
+        super('UpgradeApplied', data);
+    }
+}
+
+/**
+ * Event emitted when a pending upgrade is cancelled.
+ */
+export class UpgradeCancelledEvent extends NetEvent {
+    constructor(sourceAddress: Address, cancelledAtBlock: u64) {
+        const data = new BytesWriter(ADDRESS_BYTE_LENGTH + 8);
+        data.writeAddress(sourceAddress);
+        data.writeU64(cancelledAtBlock);
+        super('UpgradeCancelled', data);
+    }
+}

package/runtime/generic/AddressMap.ts

@@ -26,23 +26,7 @@ export class AddressMap<V> implements IMap<Address, V> {
     }
 
     public set(key: Address, value: V): this {
-        let index = -1;
-
-        // Check Cache (Fastest)
-        if (this._lastIndex !== -1) {
-            const cachedKey = unchecked(this._keys[this._lastIndex]);
-            // Check length first, then full content equality
-            if (cachedKey.length === key.length) {
-                if (memory.compare(cachedKey.dataStart, key.dataStart, key.length) === 0) {
-                    index = this._lastIndex;
-                }
-            }
-        }
-
-        // Full Scan if cache missed
-        if (index === -1) {
-            index = this.indexOf(key);
-        }
+        const index = this.indexOf(key);
 
         if (index === -1) {
             this._keys.push(key);
@@ -50,7 +34,7 @@ export class AddressMap<V> implements IMap<Address, V> {
             this._lastIndex = this._keys.length - 1;
         } else {
             unchecked((this._values[index] = value));
-            // Cache is already pointing to this index (from indexOf or the check above)
+            // Cache is already pointing to this index (from indexOf)
             this._lastIndex = index;
         }
 
@@ -63,6 +47,10 @@ export class AddressMap<V> implements IMap<Address, V> {
      * Uses a "Prefix Filter" to skip expensive memory comparisons.
      */
     public indexOf(pointerHash: Address): i32 {
+        if (this.isLastIndex(pointerHash)) {
+            return this._lastIndex;
+        }
+
         const len = this._keys.length;
         if (len === 0) return -1;
 
@@ -111,6 +99,20 @@ export class AddressMap<V> implements IMap<Address, V> {
         return -1;
     }
 
+    private isLastIndex(key: Uint8Array): bool {
+        if (this._lastIndex !== -1) {
+            const cachedKey = unchecked(this._keys[this._lastIndex]);
+            // Check length first, then full content equality
+            if (cachedKey.length === key.length) {
+                if (memory.compare(cachedKey.dataStart, key.dataStart, key.length) === 0) {
+                    return true;
+                }
+            }
+        }
+
+        return false;
+    }
+
     @inline
     public has(key: Address): bool {
         return this.indexOf(key) !== -1;