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

package/docs/contracts/upgradeable.md

@@ -1,396 +0,0 @@
-# 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/runtime/contracts/Upgradeable.ts

@@ -1,242 +0,0 @@
-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 {
-    UpgradeAppliedEvent,
-    UpgradeCancelledEvent,
-    UpgradeSubmittedEvent,
-} 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/contracts/interfaces/IOP1155.ts

@@ -1,33 +0,0 @@
-import { BytesWriter } from '../../buffer/BytesWriter';
-import { Calldata } from '../../types';
-
-export interface IOP1155 {
-    // Core properties
-    fn_name(calldata: Calldata): BytesWriter;
-    fn_symbol(calldata: Calldata): BytesWriter;
-    uri(calldata: Calldata): BytesWriter;
-
-    // Balance and supply
-    balanceOf(calldata: Calldata): BytesWriter;
-    balanceOfBatch(calldata: Calldata): BytesWriter;
-    totalSupply(calldata: Calldata): BytesWriter;
-    exists(calldata: Calldata): BytesWriter;
-
-    // Transfer functions
-    safeTransferFrom(calldata: Calldata): BytesWriter;
-    safeBatchTransferFrom(calldata: Calldata): BytesWriter;
-
-    // Approval functions
-    setApprovalForAll(calldata: Calldata): BytesWriter;
-    isApprovedForAll(calldata: Calldata): BytesWriter;
-
-    // Advanced functions
-    burn(calldata: Calldata): BytesWriter;
-    burnBatch(calldata: Calldata): BytesWriter;
-    transferBySignature(calldata: Calldata): BytesWriter;
-    batchTransferBySignature(calldata: Calldata): BytesWriter;
-    domainSeparator(calldata: Calldata): BytesWriter;
-
-    // Interface support
-    supportsInterface(calldata: Calldata): BytesWriter;
-}

package/runtime/contracts/interfaces/OP1155InitParameters.ts

@@ -1,11 +0,0 @@
-export class OP1155InitParameters {
-    public name: string;
-    public symbol: string;
-    public baseUri: string;
-
-    constructor(name: string, symbol: string, baseUri: string) {
-        this.name = name;
-        this.symbol = symbol;
-        this.baseUri = baseUri;
-    }
-}