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

package/docs/advanced/plugins.md

@@ -5,7 +5,7 @@ Plugins extend contract functionality through lifecycle hooks. They allow modula
 ## Overview
 
 ```typescript
-import { Plugin, Blockchain, Calldata, Selector } from '@btc-vision/btc-runtime/runtime';
+import { Plugin, Blockchain, Calldata, Selector, BytesWriter } from '@btc-vision/btc-runtime/runtime';
 
 // Create a plugin by extending Plugin class
 class MyPlugin extends Plugin {
@@ -13,6 +13,10 @@ class MyPlugin extends Plugin {
         // Called during contract deployment
     }
 
+    public override onUpdate(calldata: Calldata): void {
+        // Called when contract bytecode is updated
+    }
+
     public override onExecutionStarted(selector: Selector, calldata: Calldata): void {
         // Called before each method execution
     }
@@ -20,15 +24,20 @@ class MyPlugin extends Plugin {
     public override onExecutionCompleted(selector: Selector, calldata: Calldata): void {
         // Called after each successful method execution
     }
+
+    public override execute(method: Selector, calldata: Calldata): BytesWriter | null {
+        // Handle method selectors - return BytesWriter if handled, null if not
+        return null;
+    }
 }
 
 // Register with contract
-Blockchain.registerPlugin(new MyPlugin());
+this.registerPlugin(new MyPlugin());
 ```
 
 ## Plugin Lifecycle
 
-Plugins are initialized when the contract is deployed and can intercept method calls:
+Plugins are initialized when the contract is deployed and can intercept method calls or handle them directly:
 
 ```mermaid
 ---
@@ -44,7 +53,7 @@ sequenceDiagram
     Note over Deployer,Blockchain: Contract Deployment
     Deployer->>Contract: constructor()
     Contract->>Plugin: new Plugin()
-    Contract->>Blockchain: registerPlugin(plugin)
+    Contract->>Contract: registerPlugin(plugin)
 
     Deployer->>Contract: deploy(calldata)
     Blockchain->>Plugin: onDeployment(calldata)
@@ -62,9 +71,14 @@ sequenceDiagram
     Note over Plugin: Pre-execution checks<br/>(access control, pausing, etc.)
     Plugin-->>Blockchain: continue
 
-    Blockchain->>Contract: method executes
-    Note over Contract: Core business logic
-    Contract-->>Blockchain: result
+    alt Plugin handles selector
+        Blockchain->>Plugin: execute(selector, calldata)
+        Plugin-->>Blockchain: BytesWriter result
+    else Contract handles selector
+        Blockchain->>Contract: method executes
+        Note over Contract: Core business logic
+        Contract-->>Blockchain: result
+    end
 
     Blockchain->>Plugin: onExecutionCompleted(selector, calldata)
     Note over Plugin: Post-execution tasks<br/>(metrics, logging, etc.)
@@ -86,8 +100,10 @@ classDiagram
     class Plugin {
         <<base>>
         +onDeployment(calldata: Calldata) void
+        +onUpdate(calldata: Calldata) void
         +onExecutionStarted(selector: Selector, calldata: Calldata) void
         +onExecutionCompleted(selector: Selector, calldata: Calldata) void
+        +execute(method: Selector, calldata: Calldata) BytesWriter|null
     }
 
     class RoleBasedAccessPlugin {
@@ -121,18 +137,26 @@ classDiagram
 
 ### Base Plugin Class
 
-The `Plugin` class provides three lifecycle hooks:
+The `Plugin` class provides lifecycle hooks and method handling:
 
 ```typescript
 export class Plugin {
     // Called once during contract deployment, before contract's onDeployment
     public onDeployment(_calldata: Calldata): void {}
 
+    // Called when contract bytecode is updated via updateContractFromExisting
+    public onUpdate(_calldata: Calldata): void {}
+
     // Called before each method execution
     public onExecutionStarted(_selector: Selector, _calldata: Calldata): void {}
 
     // Called after each successful method execution
     public onExecutionCompleted(_selector: Selector, _calldata: Calldata): void {}
+
+    // Handle method selectors - return BytesWriter if handled, null if not
+    public execute(_method: Selector, _calldata: Calldata): BytesWriter | null {
+        return null;
+    }
 }
 ```
 
@@ -144,14 +168,21 @@ import {
     Calldata,
     Selector,
     Blockchain,
-    Revert
+    BytesWriter,
+    Revert,
+    encodeSelector
 } from '@btc-vision/btc-runtime/runtime';
 
+// Simple logging plugin using lifecycle hooks
 class LoggingPlugin extends Plugin {
     public override onDeployment(calldata: Calldata): void {
         // Log deployment
     }
 
+    public override onUpdate(calldata: Calldata): void {
+        // Handle contract upgrades
+    }
+
     public override onExecutionStarted(selector: Selector, calldata: Calldata): void {
         // Log method call before execution
     }
@@ -160,6 +191,23 @@ class LoggingPlugin extends Plugin {
         // Log method completion
     }
 }
+
+// Plugin that handles method selectors (like UpgradeablePlugin)
+class MethodHandlerPlugin extends Plugin {
+    public override execute(method: Selector, calldata: Calldata): BytesWriter | null {
+        switch (method) {
+            case encodeSelector('myPluginMethod()'):
+                return this.myPluginMethod();
+            default:
+                return null; // Not handled by this plugin
+        }
+    }
+
+    private myPluginMethod(): BytesWriter {
+        // Method implementation
+        return new BytesWriter(0);
+    }
+}
 ```
 
 ## Registration
@@ -178,7 +226,7 @@ export class MyContract extends OP_NET {
 
         // Create and register plugins
         this.loggingPlugin = new LoggingPlugin();
-        Blockchain.registerPlugin(this.loggingPlugin);
+        this.registerPlugin(this.loggingPlugin);
     }
 }
 ```
@@ -190,7 +238,7 @@ public override onDeployment(calldata: Calldata): void {
     const enableLogging = calldata.readBoolean();
 
     if (enableLogging) {
-        Blockchain.registerPlugin(new LoggingPlugin());
+        this.registerPlugin(new LoggingPlugin());
     }
 
     // Continue with normal deployment
@@ -518,7 +566,7 @@ export class MyContract extends OP_NET {
             Blockchain.nextPointer,
             Blockchain.nextPointer
         );
-        Blockchain.registerPlugin(this.feePlugin);
+        this.registerPlugin(this.feePlugin);
     }
 
     @method(
@@ -551,15 +599,21 @@ export class MyContract extends OP_NET {
 ### Execution Order
 
 ```
+Deployment:
 1. Plugin.onDeployment (for each registered plugin, in order)
 2. Contract.onDeployment
 
-Then for each method call:
+Upgrade (when bytecode is updated):
+1. Plugin.onUpdate (for each registered plugin, in order)
+2. Contract.onUpdate
+
+Method execution:
 1. Plugin.onExecutionStarted (for each registered plugin, in order)
 2. Contract.onExecutionStarted
-3. Contract method executes
-4. Plugin.onExecutionCompleted (for each registered plugin, in order)
-5. Contract.onExecutionCompleted
+3. Plugin.execute (check plugins first, return if handled)
+4. Contract method executes (if no plugin handled it)
+5. Plugin.onExecutionCompleted (for each registered plugin, in order)
+6. Contract.onExecutionCompleted
 ```
 
 ### Metrics Plugin Example
@@ -733,7 +787,7 @@ export class MyContract extends OP_NET {
         super();
         // Single plugin handles ALL access control
         this.accessPlugin = new RoleBasedAccessPlugin(Blockchain.nextPointer);
-        Blockchain.registerPlugin(this.accessPlugin);
+        this.registerPlugin(this.accessPlugin);
     }
 
     @method()
@@ -812,7 +866,7 @@ export class MyContract extends OP_NET {
     public constructor() {
         super();
         this.pausablePlugin = new PausablePlugin(Blockchain.nextPointer);
-        Blockchain.registerPlugin(this.pausablePlugin);
+        this.registerPlugin(this.pausablePlugin);
     }
 
     @method(ABIDataTypes.UINT256)
@@ -861,19 +915,19 @@ export class CompleteContract extends OP_NET {
 
         // Order matters - security checks first!
         this.accessPlugin = new RoleBasedAccessPlugin(Blockchain.nextPointer);
-        Blockchain.registerPlugin(this.accessPlugin);  // 1. Check permissions
+        this.registerPlugin(this.accessPlugin);  // 1. Check permissions
 
         this.pausablePlugin = new PausablePlugin(Blockchain.nextPointer);
-        Blockchain.registerPlugin(this.pausablePlugin);  // 2. Check pause status
+        this.registerPlugin(this.pausablePlugin);  // 2. Check pause status
 
         this.feePlugin = new FeeCollectorPlugin(
             Blockchain.nextPointer,
             Blockchain.nextPointer
         );
-        Blockchain.registerPlugin(this.feePlugin);  // 3. Fee calculations
+        this.registerPlugin(this.feePlugin);  // 3. Fee calculations
 
         this.metricsPlugin = new MetricsPlugin(Blockchain.nextPointer);
-        Blockchain.registerPlugin(this.metricsPlugin);  // 4. Track metrics
+        this.registerPlugin(this.metricsPlugin);  // 4. Track metrics
     }
 
     // All plugins execute their hooks automatically
@@ -886,7 +940,9 @@ export class CompleteContract extends OP_NET {
 | Lifecycle Event | Solidity | OPNet |
 |-----------------|----------|-------|
 | Contract deployment | Single constructor | `onDeployment` per plugin + contract |
+| Contract upgrade | Proxy reinitialize | `onUpdate` per plugin + contract |
 | Before method call | Modifiers (manual per function) | `onExecutionStarted` (automatic) |
+| Method handling | Function dispatch | `execute` returns BytesWriter or null |
 | After method call | No built-in hook | `onExecutionCompleted` (automatic) |
 | Error handling | try/catch (limited) | Revert in any hook |
 
@@ -928,6 +984,10 @@ class MyPlugin extends Plugin {
         // Implementation
     }
 
+    public override onUpdate(calldata: Calldata): void {
+        // Implementation
+    }
+
     public override onExecutionStarted(selector: Selector, calldata: Calldata): void {
         // Implementation
     }
@@ -935,6 +995,11 @@ class MyPlugin extends Plugin {
     public override onExecutionCompleted(selector: Selector, calldata: Calldata): void {
         // Implementation
     }
+
+    public override execute(method: Selector, calldata: Calldata): BytesWriter | null {
+        // Return BytesWriter if handled, null if not
+        return null;
+    }
 }
 ```
 
@@ -994,9 +1059,9 @@ public override onExecutionStarted(selector: Selector, calldata: Calldata): void
 
 ```typescript
 // Security checks should come first
-Blockchain.registerPlugin(this.accessControl);  // Check permissions first
-Blockchain.registerPlugin(this.pausable);       // Then pausable
-Blockchain.registerPlugin(this.metrics);        // Metrics last
+this.registerPlugin(this.accessControl);  // Check permissions first
+this.registerPlugin(this.pausable);       // Then pausable
+this.registerPlugin(this.metrics);        // Metrics last
 ```
 
 ---

package/docs/api-reference/blockchain.md

@@ -432,6 +432,34 @@ const newContract = Blockchain.deployContractFromExisting(
 );
 ```
 
+### updateContractFromExisting
+
+Updates the calling contract's bytecode from another deployed contract. The new bytecode takes effect at the next block.
+
+```typescript
+updateContractFromExisting(
+    sourceAddress: Address,
+    calldata?: BytesWriter | null
+): void
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `sourceAddress` | `Address` | Contract containing new bytecode |
+| `calldata` | `BytesWriter \| null` | Optional calldata passed to VM (default: empty) |
+
+```typescript
+// Basic upgrade (not recommended without access control)
+Blockchain.updateContractFromExisting(newBytecodeAddress);
+
+// With calldata
+const upgradeData = new BytesWriter(32);
+upgradeData.writeU256(migrationVersion);
+Blockchain.updateContractFromExisting(newBytecodeAddress, upgradeData);
+```
+
+> **Warning:** This is a privileged operation. Always implement access control (e.g., `onlyDeployer`) and consider using the `Upgradeable` base class or `UpgradeablePlugin` for timelock protection. See [Contract Upgrades](../advanced/contract-upgrades.md) for details.
+
 ## Cryptographic Operations
 
 ### sha256
@@ -698,20 +726,6 @@ log(data: string): void
 Blockchain.log('Debug: operation started');
 ```
 
-## Plugin Methods
-
-### registerPlugin
-
-Registers a plugin.
-
-```typescript
-registerPlugin(plugin: Plugin): void
-```
-
-```typescript
-Blockchain.registerPlugin(new MyPlugin());
-```
-
 ## Lifecycle Hooks
 
 These are called by the runtime:
@@ -719,9 +733,29 @@ These are called by the runtime:
 | Method | When Called |
 |--------|-------------|
 | `onDeployment(calldata)` | Contract deployment |
+| `onUpdate(calldata)` | Contract bytecode update (via `updateContractFromExisting`) |
 | `onExecutionStarted(selector, calldata)` | Before method execution |
 | `onExecutionCompleted(selector, calldata)` | After successful execution |
 
+### onUpdate
+
+Called when the contract's bytecode is updated via `updateContractFromExisting`. Use this hook to perform storage migrations or initialization logic when upgrading.
+
+```typescript
+public override onUpdate(calldata: Calldata): void {
+    super.onUpdate(calldata); // Call plugins first
+
+    // Perform migration logic
+    const migrationVersion = calldata.readU64();
+    if (migrationVersion === 2) {
+        // Migrate from v1 to v2
+        this.migrateToV2();
+    }
+}
+```
+
+> **Note:** The calldata is the same data passed to `Blockchain.updateContractFromExisting(sourceAddress, calldata)`. If no calldata was provided, an empty reader is passed.
+
 ---
 
 **Navigation:**

package/docs/contracts/op-net-base.md

@@ -62,6 +62,7 @@ classDiagram
         +address Address (getter)
         +contractDeployer Address (getter)
         +onDeployment(_calldata: Calldata) void
+        +onUpdate(_calldata: Calldata) void
         +onExecutionStarted(_selector: Selector, _calldata: Calldata) void
         +onExecutionCompleted(_selector: Selector, _calldata: Calldata) void
         +execute(method: Selector, _calldata: Calldata) BytesWriter
@@ -235,6 +236,27 @@ constructor(uint256 initialSupply, string memory tokenName) {
 // Constructor runs every call, onDeployment runs once
 ```
 
+### 2b. Update (onUpdate)
+
+Runs when the contract's bytecode is updated via `updateContractFromExisting`:
+
+```typescript
+public override onUpdate(calldata: Calldata): void {
+    super.onUpdate(calldata); // Notify plugins
+
+    // Read migration parameters
+    const fromVersion = calldata.readU64();
+
+    // Perform migration based on version
+    if (fromVersion === 1) {
+        // Initialize new storage added in this version
+        this._newFeature.value = u256.fromU64(100);
+    }
+}
+```
+
+> **Note:** This hook is called on the **new** bytecode, not the old one. See [Contract Upgrades](../advanced/contract-upgrades.md#the-onupdate-lifecycle-hook) for details.
+
 ### 3. Method Execution
 
 Methods are automatically routed via `@method` decorators: