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

package/runtime/contracts/ReentrancyGuard.ts

@@ -8,8 +8,6 @@ import { Revert } from '../types/Revert';
 import { u256 } from '@btc-vision/as-bignum/assembly';
 import { SafeMath } from '../types/SafeMath';
 import {
-    ON_OP1155_BATCH_RECEIVED_MAGIC,
-    ON_OP1155_RECEIVED_MAGIC,
     ON_OP20_RECEIVED_SELECTOR,
     ON_OP721_RECEIVED_SELECTOR,
 } from '../constants/Exports';
@@ -128,9 +126,7 @@ export class ReentrancyGuard extends OP_NET {
     protected isSelectorExcluded(selector: Selector): boolean {
         return (
             selector === ON_OP20_RECEIVED_SELECTOR ||
-            selector === ON_OP721_RECEIVED_SELECTOR ||
-            selector === ON_OP1155_RECEIVED_MAGIC ||
-            selector === ON_OP1155_BATCH_RECEIVED_MAGIC
+            selector === ON_OP721_RECEIVED_SELECTOR
         );
     }
 }

package/runtime/contracts/Updatable.ts

@@ -0,0 +1,241 @@
+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 {
+    UpdateAppliedEvent,
+    UpdateCancelledEvent,
+    UpdateSubmittedEvent,
+} from '../events/updatable/UpdatableEvents';
+
+const pendingUpdateAddressPointer: u16 = Blockchain.nextPointer;
+const pendingUpdateBlockPointer: u16 = Blockchain.nextPointer;
+
+/**
+ * Updatable - Base contract for updatable contracts with timelock protection.
+ *
+ * This contract provides a secure update mechanism with a configurable delay period.
+ * The pattern prevents instant malicious updates by requiring:
+ * 1. submitUpdate() - Submit the source contract address, starts the timelock
+ * 2. Wait for the delay period to pass
+ * 3. applyUpdate() - Apply the update after the delay
+ *
+ * Users can monitor for UpdateSubmitted events and exit if they distrust pending changes.
+ *
+ * @example
+ * ```typescript
+ * @final
+ * export class MyUpdatableContract extends Updatable {
+ *     // Set a 24-hour delay (144 blocks at 10 min/block)
+ *     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);
+ *         }
+ *     }
+ * }
+ * ```
+ */
+export class Updatable extends OP_NET {
+    /**
+     * The pending update source address.
+     * Zero address means no pending update.
+     */
+    protected readonly _pendingUpdateAddress: StoredAddress;
+
+    /**
+     * The block number when the update was submitted.
+     * Stored as u256, used as u64.
+     */
+    protected readonly _pendingUpdateBlock: StoredU256;
+
+    /**
+     * The number of blocks to wait before an update 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 updateDelay: u64 = 144; // ~24 hours default
+
+    protected constructor() {
+        super();
+        this._pendingUpdateAddress = new StoredAddress(pendingUpdateAddressPointer);
+        this._pendingUpdateBlock = new StoredU256(pendingUpdateBlockPointer, EMPTY_POINTER);
+    }
+
+    /**
+     * Returns the pending update source address.
+     * Returns zero address if no update is pending.
+     */
+    public get pendingUpdateAddress(): Address {
+        return this._pendingUpdateAddress.value;
+    }
+
+    /**
+     * Returns the block number when the pending update was submitted.
+     * Returns 0 if no update is pending.
+     */
+    public get pendingUpdateBlock(): u64 {
+        return this._pendingUpdateBlock.value.lo1;
+    }
+
+    /**
+     * Returns the block number when the pending update can be applied.
+     * Returns 0 if no update is pending.
+     */
+    public get updateEffectiveBlock(): u64 {
+        const submitBlock = this.pendingUpdateBlock;
+        if (submitBlock === 0) return 0;
+        return submitBlock + this.updateDelay;
+    }
+
+    /**
+     * Returns true if there is a pending update.
+     */
+    public get hasPendingUpdate(): bool {
+        return this.pendingUpdateBlock !== 0;
+    }
+
+    /**
+     * Returns true if the pending update can be applied (delay has passed).
+     */
+    public get canApplyUpdate(): bool {
+        if (!this.hasPendingUpdate) return false;
+        return Blockchain.block.number >= this.updateEffectiveBlock;
+    }
+
+    /**
+     * Submits an update for timelock.
+     *
+     * The source address must be a deployed contract containing the new bytecode.
+     * After submission, the update can only be applied after updateDelay blocks.
+     *
+     * Emits UpdateSubmitted 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 update is already pending
+     */
+    protected submitUpdate(sourceAddress: Address): BytesWriter {
+        this.onlyDeployer(Blockchain.tx.sender);
+
+        // Check no pending update
+        if (this.hasPendingUpdate) {
+            throw new Revert('Update 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 update
+        const currentBlock = Blockchain.block.number;
+        this._pendingUpdateAddress.value = sourceAddress;
+        this._pendingUpdateBlock.value = u256.fromU64(currentBlock);
+
+        // Emit event
+        const effectiveBlock = currentBlock + this.updateDelay;
+        Blockchain.emit(new UpdateSubmittedEvent(sourceAddress, currentBlock, effectiveBlock));
+
+        return new BytesWriter(0);
+    }
+
+    /**
+     * Applies a pending update after the timelock period has passed.
+     *
+     * The provided address must match the pending update address as an
+     * additional security measure against front-running attacks.
+     *
+     * Emits UpdateApplied event before the update (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 update is pending
+     * @throws If delay has not passed
+     * @throws If provided address does not match pending
+     */
+    protected applyUpdate(sourceAddress: Address, calldata: BytesWriter): BytesWriter {
+        this.onlyDeployer(Blockchain.tx.sender);
+
+        // Check pending update exists
+        if (!this.hasPendingUpdate) {
+            throw new Revert('No pending update');
+        }
+
+        // Check delay has passed
+        if (!this.canApplyUpdate) {
+            throw new Revert('Update delay not elapsed');
+        }
+
+        // Verify address matches pending
+        if (!sourceAddress.equals(this._pendingUpdateAddress.value)) {
+            throw new Revert('Address does not match pending update');
+        }
+
+        // Clear pending state before update
+        this._pendingUpdateAddress.value = Address.zero();
+        this._pendingUpdateBlock.value = u256.Zero;
+
+        // Emit event
+        Blockchain.emit(new UpdateAppliedEvent(sourceAddress, Blockchain.block.number));
+
+        // Perform update - new bytecode takes effect next block
+        Blockchain.updateContractFromExisting(sourceAddress, calldata);
+
+        return new BytesWriter(0);
+    }
+
+    /**
+     * Cancels a pending update.
+     *
+     * Can only be called by the deployer. Clears the pending update state.
+     *
+     * Emits UpdateCancelled event.
+     *
+     * @returns Empty response
+     * @throws If caller is not deployer
+     * @throws If no update is pending
+     */
+    protected cancelUpdate(): BytesWriter {
+        this.onlyDeployer(Blockchain.tx.sender);
+
+        // Check pending update exists
+        if (!this.hasPendingUpdate) {
+            throw new Revert('No pending update');
+        }
+
+        const pendingAddress = this._pendingUpdateAddress.value;
+
+        // Clear pending state
+        this._pendingUpdateAddress.value = Address.zero();
+        this._pendingUpdateBlock.value = u256.Zero;
+
+        // Emit event
+        Blockchain.emit(new UpdateCancelledEvent(pendingAddress, Blockchain.block.number));
+
+        return new BytesWriter(0);
+    }
+}

package/runtime/contracts/interfaces/OP721InitParameters.ts

@@ -6,10 +6,10 @@ export class OP721InitParameters {
     public baseURI: string;
     public maxSupply: u256;
 
-    public collectionBanner: string;
-    public collectionIcon: string;
-    public collectionWebsite: string;
-    public collectionDescription: string;
+    public banner: string;
+    public icon: string;
+    public website: string;
+    public description: string;
 
     constructor(
         name: string,
@@ -26,9 +26,9 @@ export class OP721InitParameters {
         this.baseURI = baseURI;
         this.maxSupply = maxSupply;
 
-        this.collectionBanner = collectionBanner;
-        this.collectionIcon = collectionIcon;
-        this.collectionWebsite = collectionWebsite;
-        this.collectionDescription = collectionDescription;
+        this.banner = collectionBanner;
+        this.icon = collectionIcon;
+        this.website = collectionWebsite;
+        this.description = collectionDescription;
     }
 }

package/runtime/env/BlockchainEnvironment.ts

@@ -610,7 +610,7 @@ export class BlockchainEnvironment {
      * @example
      * ```typescript
      * // Simple immediate update (not recommended for production)
-     * public upgrade(calldata: Calldata): BytesWriter {
+     * public update(calldata: Calldata): BytesWriter {
      *     this.onlyDeployer(Blockchain.tx.sender);
      *     const newBytecodeAddress = calldata.readAddress();
      *     Blockchain.updateContractFromExisting(newBytecodeAddress);
@@ -675,12 +675,12 @@ export class BlockchainEnvironment {
             throw new Revert('Source address must be a deployed contract');
         }
 
-        const callDataBuffer = calldata ? calldata.getBuffer().buffer : new ArrayBuffer(0);
+        const calldataBuffer = calldata ? calldata.getBuffer().buffer : new ArrayBuffer(0);
 
         const status = updateFromAddress(
             sourceAddress.buffer,
-            callDataBuffer,
-            callDataBuffer.byteLength,
+            calldataBuffer,
+            calldataBuffer.byteLength,
         );
 
         if (status !== 0) {
@@ -903,7 +903,7 @@ export class BlockchainEnvironment {
      * The `unsafeSignaturesAllowed()` flag indicates whether the network is still accepting
      * legacy Schnorr signatures. This flag will be `true` during the transition period to
      * maintain backwards compatibility with existing infrastructure. Once the network completes
-     * its quantum-resistant upgrade, this flag will permanently become `false`, enforcing
+     * its quantum-resistant update, this flag will permanently become `false`, enforcing
      * ML-DSA signatures exclusively.
      *
      * @param address - The address containing the public key(s) to verify against.

package/runtime/env/global.ts

@@ -244,17 +244,18 @@ export declare function getOutputsSize(): u32;
  *
  * The signature algorithm is determined by the public key format:
  * - First byte indicates the signature type:
- *   - 0x00: Schnorr signature (33 bytes total - type byte + 32-byte x-only public key)
- *   - 0x01: ML-DSA signature (variable length based on security level)
+ *   - 0x00: ECDSA signature
+ *   - 0x01: Schnorr signature (33 bytes total - type byte + 32-byte x-only public key)
+ *   - 0x02: ML-DSA signature (variable length based on security level)
  *
  * For Schnorr signatures:
- * - Public key format: [0x00] + [32-byte x-only public key] (33 bytes total)
+ * - Public key format: [0x01] + [32-byte x-only public key] (33 bytes total)
  * - Signature: 64 bytes
  * - Message: 32 bytes (typically a hash)
  * - Note: Schnorr signatures are only allowed when UNSAFE_QUANTUM_SIGNATURES_ALLOWED consensus flag is set
  *
  * For ML-DSA signatures (quantum-resistant):
- * - Public key format: [0x01] + [level byte] + [public key data]
+ * - Public key format: [0x02] + [level byte] + [public key data]
  *   - Level 0x00: ML-DSA-44 (1313 bytes total - 1 header byte + 1312 key bytes)
  *   - Level 0x01: ML-DSA-65 (1955 bytes total - 1 header byte + 1952 key bytes)
  *   - Level 0x02: ML-DSA-87 (2593 bytes total - 1 header byte + 2592 key bytes)
@@ -268,7 +269,7 @@ export declare function getOutputsSize(): u32;
  * ```typescript
  * // Schnorr signature verification
  * const writer = new BytesWriter(33);
- * writer.writeU8(0x00); // Schnorr type
+ * writer.writeU8(0x01); // Schnorr type
  * writer.writeBytes(xOnlyPublicKey); // 32-byte x-only public key
  *
  * const publicKey = writer.getBuffer().buffer;
@@ -282,7 +283,7 @@ export declare function getOutputsSize(): u32;
  * ```typescript
  * // ML-DSA-44 signature verification
  * const writer = new BytesWriter(1314);
- * writer.writeU8(0x01); // ML-DSA type
+ * writer.writeU8(0x02); // ML-DSA type
  * writer.writeU8(0x00); // ML-DSA-44 level
  * writer.writeBytes(mldsaPublicKey); // 1312-byte public key
  *

package/runtime/events/predefined/{ApprovedEvent.ts → OP20ApprovedEvent.ts}

@@ -5,7 +5,7 @@ import { ADDRESS_BYTE_LENGTH, U256_BYTE_LENGTH } from '../../utils';
 import { NetEvent } from '../NetEvent';
 
 @final
-export class ApprovedEvent extends NetEvent {
+export class OP20ApprovedEvent extends NetEvent {
     constructor(owner: Address, spender: Address, amount: u256) {
         const data: BytesWriter = new BytesWriter(ADDRESS_BYTE_LENGTH * 2 + U256_BYTE_LENGTH);
         data.writeAddress(owner);

package/runtime/events/predefined/{BurnedEvent.ts → OP20BurnedEvent.ts}

@@ -5,7 +5,7 @@ import { NetEvent } from '../NetEvent';
 import { Address } from '../../types/Address';
 
 @final
-export class BurnedEvent extends NetEvent {
+export class OP20BurnedEvent extends NetEvent {
     constructor(from: Address, amount: u256) {
         const data: BytesWriter = new BytesWriter(ADDRESS_BYTE_LENGTH + U256_BYTE_LENGTH);
         data.writeAddress(from);

package/runtime/events/predefined/{MintedEvent.ts → OP20MintedEvent.ts}

@@ -5,7 +5,7 @@ import { ADDRESS_BYTE_LENGTH, U256_BYTE_LENGTH } from '../../utils';
 import { NetEvent } from '../NetEvent';
 
 @final
-export class MintedEvent extends NetEvent {
+export class OP20MintedEvent extends NetEvent {
     constructor(to: Address, amount: u256) {
         const data: BytesWriter = new BytesWriter(ADDRESS_BYTE_LENGTH + U256_BYTE_LENGTH);
         data.writeAddress(to);

package/runtime/events/predefined/{TransferredEvent.ts → OP20TransferredEvent.ts}

@@ -5,7 +5,7 @@ import { ADDRESS_BYTE_LENGTH, U256_BYTE_LENGTH } from '../../utils';
 import { NetEvent } from '../NetEvent';
 
 @final
-export class TransferredEvent extends NetEvent {
+export class OP20TransferredEvent extends NetEvent {
     constructor(operator: Address, from: Address, to: Address, amount: u256) {
         const data: BytesWriter = new BytesWriter(ADDRESS_BYTE_LENGTH * 3 + U256_BYTE_LENGTH);
         data.writeAddress(operator);

package/runtime/events/predefined/OP721ApprovedEvent.ts

@@ -0,0 +1,17 @@
+import { u256 } from '@btc-vision/as-bignum/assembly';
+import { BytesWriter } from '../../buffer/BytesWriter';
+import { Address } from '../../types/Address';
+import { ADDRESS_BYTE_LENGTH, U256_BYTE_LENGTH } from '../../utils';
+import { NetEvent } from '../NetEvent';
+
+@final
+export class OP721ApprovedEvent extends NetEvent {
+    constructor(owner: Address, operator: Address, tokenId: u256) {
+        const data: BytesWriter = new BytesWriter(ADDRESS_BYTE_LENGTH * 2 + U256_BYTE_LENGTH);
+        data.writeAddress(owner);
+        data.writeAddress(operator);
+        data.writeU256(tokenId);
+
+        super('Approved', data);
+    }
+}

package/runtime/events/predefined/{ApprovedForAll.ts → OP721ApprovedForAllEvent.ts}

@@ -4,7 +4,7 @@ import { Address } from '../../types/Address';
 import { ADDRESS_BYTE_LENGTH } from '../../utils';
 
 @final
-export class ApprovedForAllEvent extends NetEvent {
+export class OP721ApprovedForAllEvent extends NetEvent {
     constructor(account: Address, operator: Address, approved: boolean) {
         const writer = new BytesWriter(ADDRESS_BYTE_LENGTH * 2 + 1);
         writer.writeAddress(account);

package/runtime/events/predefined/OP721BurnedEvent.ts

@@ -0,0 +1,16 @@
+import { u256 } from '@btc-vision/as-bignum/assembly';
+import { BytesWriter } from '../../buffer/BytesWriter';
+import { ADDRESS_BYTE_LENGTH, U256_BYTE_LENGTH } from '../../utils';
+import { NetEvent } from '../NetEvent';
+import { Address } from '../../types/Address';
+
+@final
+export class OP721BurnedEvent extends NetEvent {
+    constructor(from: Address, amount: u256) {
+        const data: BytesWriter = new BytesWriter(ADDRESS_BYTE_LENGTH + U256_BYTE_LENGTH);
+        data.writeAddress(from);
+        data.writeU256(amount);
+
+        super('Burned', data);
+    }
+}

package/runtime/events/predefined/OP721MintedEvent.ts

@@ -0,0 +1,16 @@
+import { u256 } from '@btc-vision/as-bignum/assembly';
+import { BytesWriter } from '../../buffer/BytesWriter';
+import { Address } from '../../types/Address';
+import { ADDRESS_BYTE_LENGTH, U256_BYTE_LENGTH } from '../../utils';
+import { NetEvent } from '../NetEvent';
+
+@final
+export class OP721MintedEvent extends NetEvent {
+    constructor(to: Address, amount: u256) {
+        const data: BytesWriter = new BytesWriter(ADDRESS_BYTE_LENGTH + U256_BYTE_LENGTH);
+        data.writeAddress(to);
+        data.writeU256(amount);
+
+        super('Minted', data);
+    }
+}

package/runtime/events/predefined/OP721TransferredEvent.ts

@@ -0,0 +1,18 @@
+import { u256 } from '@btc-vision/as-bignum/assembly';
+import { BytesWriter } from '../../buffer/BytesWriter';
+import { Address } from '../../types/Address';
+import { ADDRESS_BYTE_LENGTH, U256_BYTE_LENGTH } from '../../utils';
+import { NetEvent } from '../NetEvent';
+
+@final
+export class OP721TransferredEvent extends NetEvent {
+    constructor(operator: Address, from: Address, to: Address, tokenId: u256) {
+        const data: BytesWriter = new BytesWriter(ADDRESS_BYTE_LENGTH * 3 + U256_BYTE_LENGTH);
+        data.writeAddress(operator);
+        data.writeAddress(from);
+        data.writeAddress(to);
+        data.writeU256(tokenId);
+
+        super('Transferred', data);
+    }
+}

package/runtime/events/predefined/index.ts

@@ -1,8 +1,8 @@
-export * from './ApprovedEvent';
-export * from './BurnedEvent';
-export * from './MintedEvent';
-export * from './TransferredEvent';
-export * from './ApprovedForAll';
+export * from './OP20ApprovedEvent';
+export * from './OP20BurnedEvent';
+export * from './OP20MintedEvent';
+export * from './OP20TransferredEvent';
+export * from './OP721ApprovedForAllEvent';
 export * from './URIEvent';
 export * from './TransferredBatchEvent';
 export * from './TransferredSingleEvent';

package/runtime/events/{upgradeable/UpgradeableEvents.ts → updatable/UpdatableEvents.ts}

@@ -4,38 +4,38 @@ import { Address } from '../../types/Address';
 import { ADDRESS_BYTE_LENGTH } from '../../utils';
 
 /**
- * Event emitted when an upgrade is submitted for timelock.
+ * Event emitted when an update is submitted for timelock.
  */
-export class UpgradeSubmittedEvent extends NetEvent {
+export class UpdateSubmittedEvent 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);
+        super('UpdateSubmitted', data);
     }
 }
 
 /**
- * Event emitted when an upgrade is applied.
+ * Event emitted when an update is applied.
  */
-export class UpgradeAppliedEvent extends NetEvent {
+export class UpdateAppliedEvent extends NetEvent {
     constructor(sourceAddress: Address, appliedAtBlock: u64) {
         const data = new BytesWriter(ADDRESS_BYTE_LENGTH + 8);
         data.writeAddress(sourceAddress);
         data.writeU64(appliedAtBlock);
-        super('UpgradeApplied', data);
+        super('UpdateApplied', data);
     }
 }
 
 /**
- * Event emitted when a pending upgrade is cancelled.
+ * Event emitted when a pending update is cancelled.
  */
-export class UpgradeCancelledEvent extends NetEvent {
+export class UpdateCancelledEvent extends NetEvent {
     constructor(sourceAddress: Address, cancelledAtBlock: u64) {
         const data = new BytesWriter(ADDRESS_BYTE_LENGTH + 8);
         data.writeAddress(sourceAddress);
         data.writeU64(cancelledAtBlock);
-        super('UpgradeCancelled', data);
+        super('UpdateCancelled', data);
     }
 }

package/runtime/hashing/keccak256.ts

@@ -1,5 +1,5 @@
 /**
- * Keccak-256 implementation for OPNet (AssemblyScript / btc-runtime compatible)
+ * Keccak-256 implementation for OP_NET (AssemblyScript / btc-runtime compatible)
  *
  * This implements the ORIGINAL Keccak-256 as used by Ethereum (pre-NIST),
  * NOT the NIST SHA-3-256 standard. The difference is the domain separation

package/runtime/index.ts

@@ -20,7 +20,7 @@ export * from './interfaces/IBTC';
 export * from './events/NetEvent';
 export * from './events/predefined';
 export * from './events/op20s/OP20SEvents';
-export * from './events/upgradeable/UpgradeableEvents';
+export * from './events/updatable/UpdatableEvents';
 
 /** Env */
 export * from './env/classes/UTXO';
@@ -109,12 +109,10 @@ export * from './script/Segwit';
 export * from './constants/Exports';
 export * from './contracts/OP721';
 export * from './contracts/interfaces/IOP721';
-export * from './contracts/interfaces/IOP1155';
 export * from './contracts/interfaces/OP721InitParameters';
 export * from './contracts/ReentrancyGuard';
-export * from './contracts/Upgradeable';
-export * from './contracts/interfaces/OP1155InitParameters';
+export * from './contracts/Updatable';
 
 /** Plugins */
 export * from './plugins/Plugin';
-export * from './plugins/UpgradeablePlugin';
+export * from './plugins/UpdatablePlugin';