@btc-vision/btc-runtime 1.1.2 → 1.1.3

package/LICENSE.md

@@ -10,22 +10,23 @@
 
 ## 2. Grant of License
 
-This License permits User to view the Software via the repository hosting the Software ("Hosting Service"). Except as
-provided in this Section, no other use of the Software is permitted. The User may not modify, copy, reproduce,
-republish, upload, post, transmit, or distribute the Software in any way.
+This License permits User to view the Software via the repository hosting the
+Software ("Hosting Service"). Except as provided in this Section, no other use
+of the Software is permitted. The User may not copy, republish, or distribute the Software in any way.
 
 ## 3. Restrictions
 
-- **Modification and Distribution**: User is prohibited from modifying, merging, distributing, sublicensing, and/or
-  selling copies of the Software.
 - **Commercial Use**: User is prohibited from using the Software for any commercial purposes.
-- **Reverse Engineering**: User is prohibited from reverse engineering, decompiling, or disassembling the Software.
+- **Claim of Ownership**: User acknowledges that the Software is the property of the Licensor and that they do not have
+  any ownership rights to the Software.
 
 ## 4. Termination
 
 This License is effective until terminated by the Licensor. It will terminate immediately without notice from the
 Licensor if User fails to comply with any provision of this License. Upon termination, User must destroy all copies of
-the Software.
+the Software. This License will also terminate if the User attempts to circumvent the restrictions set forth in Section
+
+3.
 
 ## 5. Copyright Notice
 

package/README.md

@@ -9,12 +9,37 @@
 
 [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
 
+## Table of Contents
+
+1. [Introduction](#introduction)
+2. [Installation](#installation)
+3. [Core Concepts](#core-concepts)
+    - [Blockchain Environment](#blockchain-environment)
+    - [Contracts](#contracts)
+    - [Events](#events)
+    - [Pointers and Storage Management](#pointers-and-storage-management)
+4. [Usage Examples](#usage-examples)
+5. [Advanced Topics](#advanced-topics)
+6. [Additional Documentation](#additional-documentation)
+7. [License](#license)
+
 ## Introduction
 
-The OPNet Smart Contract Runtime contains all the necessary components to effectively create smart contracts on Bitcoin
-L1. The runtime is written in AssemblyScript.
+The OPNet Smart Contract Runtime provides the foundational components required for creating smart contracts on Bitcoin
+Layer 1 (L1). Written in AssemblyScript, this runtime allows developers to leverage WebAssembly for efficient contract
+execution while integrating deeply with Bitcoin's decentralized architecture.
+
+### Features
 
-### Installation
+- **AssemblyScript and WebAssembly:** Efficient and high-performance contract execution using WebAssembly.
+- **Bitcoin Integration:** Direct interaction with Bitcoin L1, enabling the creation of decentralized applications that
+  operate on the Bitcoin network.
+- **Comprehensive Storage Management:** Flexible and secure storage management using primary pointers and sub-pointers,
+  ensuring data integrity through cryptographic proofs.
+- **Event Handling:** Sophisticated event system for contract state changes, allowing easy tracking and logging of
+  contract activities.
+
+## Installation
 
 1. Clone the repository:
    ```bash
@@ -26,9 +51,136 @@ L1. The runtime is written in AssemblyScript.
    ```
 3. Install the necessary dependencies:
    ```bash
-   npm i
+   npm install
    ```
 
+## Core Concepts
+
+### Blockchain Environment
+
+The `Blockchain` object environment is the backbone of the OPNet runtime, providing essential functionality for
+interacting with the blockchain, such as managing contract states, handling transactions, and emitting events.
+
+For more detailed information, see the [Blockchain.md](docs/Blockchain.md) documentation.
+
+### Contracts
+
+Contracts in OPNet are AssemblyScript classes that extend the `OP_NET` base class. The constructor pattern differs from
+Solidity's, as it runs every time a contract is instantiated, so developers should not use the constructor for
+persistent initialization.
+
+For a detailed guide on how to structure contracts, refer to the [Contract.md](docs/Contract.md) documentation.
+
+### Events
+
+Events in OPNet allow contracts to emit signals that external observers can listen to. They are crucial for tracking
+state changes and interactions within the contract.
+
+For a comprehensive explanation on how to define and use events, refer to the [Events.md](docs/Events.md) documentation.
+
+### Pointers and Storage Management
+
+Storage in OPNet is managed using a combination of pointers (`u16`) and sub-pointers (`u256`). These are encoded and
+hashed to generate unique storage locations that are secure and verifiable. This approach ensures that the data stored
+is tamper-proof and can be efficiently accessed.
+
+For more details on pointers and storage management, see the [Pointers.md](docs/Pointers.md)
+and [Storage.md](docs/Storage.md) documentation.
+
+## Usage Examples
+
+### Creating a Basic Token Contract
+
+Here is a real-world example of how to create a basic token contract using the OPNet Smart Contract Runtime. This
+contract follows the OP20 standard.
+
+```typescript
+import { u128, u256 } from 'as-bignum/assembly';
+import {
+    Address, Blockchain,
+    BytesWriter,
+    Calldata,
+    encodeSelector,
+    Map,
+    OP20InitParameters,
+    Selector,
+} from '@btc-vision/btc-runtime/runtime';
+import { DeployableOP_20 } from '@btc-vision/btc-runtime/runtime/contracts/DeployableOP_20';
+
+@final
+export class MyToken extends DeployableOP_20 {
+    constructor() {
+        super();
+
+        // DO NOT USE TO DEFINE VARIABLE THAT ARE NOT CONSTANT. SEE "solidityLikeConstructor" BELOW.
+    }
+
+    // "solidityLikeConstructor" This is a solidity-like constructor. This method will only run once.
+    public onInstantiated(): void {
+        if (!this.isInstantiated) {
+            super.onInstantiated(); // IMPORTANT.
+
+            const maxSupply: u256 = u128.fromString('100000000000000000000000000').toU256(); // Your max supply.
+            const decimals: u8 = 18; // Your decimals.
+            const name: string = 'MyToken'; // Your token name.
+            const symbol: string = 'TOKEN'; // Your token symbol.
+
+            this.instantiate(new OP20InitParameters(maxSupply, decimals, name, symbol));
+
+            // Add your logic here. Eg, minting the initial supply:
+            // this._mint(Blockchain.origin, maxSupply);
+        }
+    }
+
+    public override callMethod(method: Selector, calldata: Calldata): BytesWriter {
+        switch (method) {
+            default:
+                return super.callMethod(method, calldata);
+        }
+    }
+}
+```
+
+### Emitting Events
+
+```typescript
+class MyContract extends OP_NET {
+    public someAction(): void {
+        const event = new CustomEvent(Blockchain.sender, u256.fromU32(100));
+        this.emitEvent(event);
+    }
+}
+```
+
+## Advanced Topics
+
+### Storage Management with Cryptographic Proofs
+
+Storage pointers and sub-pointers are encoded and hashed to create unique and secure storage locations. These storage
+locations are managed using the `Blockchain` class's `setStorageAt` and `getStorageAt` methods, ensuring data integrity
+and preventing tampering.
+
+### Using Serializable Data Structures
+
+For complex data types, the `Serializable` class allows you to manage and persist data structures across multiple
+storage slots.
+
+```typescript
+class ComplexData extends Serializable {
+    // Implementation
+}
+```
+
+## Additional Documentation
+
+For more detailed explanations on specific topics, refer to the individual documentation files:
+
+- [Blockchain.md](docs/Blockchain.md)
+- [Contract.md](docs/Contract.md)
+- [Events.md](docs/Events.md)
+- [Pointers.md](docs/Pointers.md)
+- [Storage.md](docs/Storage.md)
+
 ## License
 
-View the license by clicking [here](https://github.com/btc-vision/wbtc/blob/main/LICENSE.md).
+This project is licensed under the MIT License. View the full license [here](LICENSE.md).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@btc-vision/btc-runtime",
-    "version": "1.1.2",
+    "version": "1.1.3",
     "description": "Bitcoin Smart Contract Runtime",
     "main": "btc/index.ts",
     "types": "btc/index.ts",

package/runtime/contracts/DeployableOP_20.ts

@@ -33,7 +33,7 @@ export abstract class DeployableOP_20 extends OP_NET implements IOP_20 {
     protected readonly _name: StoredString;
     protected readonly _symbol: StoredString;
 
-    protected constructor(params?: OP20InitParameters) {
+    protected constructor(params: OP20InitParameters | null = null) {
         super();
 
         this.allowanceMap = new MultiAddressMemoryMap<Address, Address, MemorySlotData<u256>>(
@@ -90,12 +90,12 @@ export abstract class DeployableOP_20 extends OP_NET implements IOP_20 {
     }
 
     public instantiate(params: OP20InitParameters, skipOwnerVerification: boolean = false): void {
-        if (!skipOwnerVerification) this.onlyOwner(Blockchain.origin());
-
         if (!this._maxSupply.value.isZero()) {
             throw new Revert('Already initialized');
         }
 
+        if (!skipOwnerVerification) this.onlyOwner(Blockchain.origin);
+
         if (params.decimals > 32) {
             throw new Revert('Decimals can not be more than 32');
         }
@@ -125,7 +125,7 @@ export abstract class DeployableOP_20 extends OP_NET implements IOP_20 {
         const resp = this._approve(spender, value);
         response.writeBoolean(resp);
 
-        this.createApproveEvent(Blockchain.origin(), spender, value);
+        this.createApproveEvent(Blockchain.origin, spender, value);
 
         return response;
     }
@@ -234,7 +234,7 @@ export abstract class DeployableOP_20 extends OP_NET implements IOP_20 {
     }
 
     protected _approve(spender: Address, value: u256): boolean {
-        const callee = Blockchain.origin();
+        const callee = Blockchain.origin;
 
         const senderMap = this.allowanceMap.get(callee);
         senderMap.set(spender, value);
@@ -254,8 +254,8 @@ export abstract class DeployableOP_20 extends OP_NET implements IOP_20 {
             throw new Revert(`No tokens`);
         }
 
-        const callee = Blockchain.origin();
-        const caller = Blockchain.sender();
+        const callee = Blockchain.origin;
+        const caller = Blockchain.sender;
 
         if (onlyOwner) this.onlyOwner(callee); // only indexers can burn tokens
 
@@ -276,7 +276,7 @@ export abstract class DeployableOP_20 extends OP_NET implements IOP_20 {
     }
 
     protected _mint(to: Address, value: u256, onlyOwner: boolean = true): boolean {
-        const callee = Blockchain.origin();
+        const callee = Blockchain.origin;
 
         if (onlyOwner) this.onlyOwner(callee);
 
@@ -299,7 +299,7 @@ export abstract class DeployableOP_20 extends OP_NET implements IOP_20 {
     }
 
     protected _transfer(to: string, value: u256): boolean {
-        const caller = Blockchain.origin();
+        const caller = Blockchain.origin;
 
         if (!this.balanceOfMap.has(caller)) throw new Revert();
         if (this.isSelf(caller)) throw new Revert('Can not transfer from self account');
@@ -355,8 +355,8 @@ export abstract class DeployableOP_20 extends OP_NET implements IOP_20 {
     }
 
     protected _transferFrom(from: Address, to: Address, value: u256): boolean {
-        const spender = Blockchain.origin();
-        if (Blockchain.sender() !== from) {
+        const spender = Blockchain.origin;
+        if (Blockchain.sender !== from) {
             throw new Revert('Not caller.');
         }
 

package/runtime/contracts/OP_NET.ts

@@ -9,14 +9,12 @@ import { MAX_EVENT_DATA_SIZE, NetEvent } from '../events/NetEvent';
 import { StoredBoolean } from '../storage/StoredBoolean';
 
 export class OP_NET implements IBTC {
-    private readonly instantiated: StoredBoolean = new StoredBoolean(Blockchain.nextPointer, false);
+    protected readonly instantiated: StoredBoolean = new StoredBoolean(
+        Blockchain.nextPointer,
+        false,
+    );
 
-    constructor() {
-        if (!this.instantiated.value) {
-            this.instantiated.value = true;
-            this.onContractInstantiate();
-        }
-    }
+    constructor() {}
 
     public get address(): string {
         return Blockchain.contractAddress;
@@ -26,6 +24,16 @@ export class OP_NET implements IBTC {
         return Blockchain.owner;
     }
 
+    public get isInstantiated(): bool {
+        return this.instantiated.value;
+    }
+
+    public onInstantiated(): void {
+        if (!this.isInstantiated) {
+            this.instantiated.value = true;
+        }
+    }
+
     public callMethod(method: Selector, _calldata: Calldata): BytesWriter {
         switch (method) {
             default:
@@ -33,9 +41,6 @@ export class OP_NET implements IBTC {
         }
     }
 
-    // Overwrite this method in your contract
-    public onContractInstantiate(): void {}
-
     public callView(method: Selector): BytesWriter {
         const response = new BytesWriter();
 

package/runtime/env/BTCEnvironment.ts

@@ -31,12 +31,29 @@ export class BlockchainEnvironment {
 
     private storage: PointerStorage = new MapU256();
     private events: NetEvent[] = [];
+    private currentBlock: u256 = u256.Zero;
+
+    constructor() {}
 
     private _origin: PotentialAddress = null;
+
+    public get origin(): Address {
+        if (!this._origin) {
+            throw this.error('Callee is required');
+        }
+
+        return this._origin as Address;
+    }
+
     private _sender: PotentialAddress = null;
-    private currentBlock: u256 = u256.Zero;
 
-    constructor() {}
+    public get sender(): Address {
+        if (!this._sender) {
+            throw this.error('Caller is required');
+        }
+
+        return this._sender as Address;
+    }
 
     private _timestamp: u64 = 0;
 
@@ -98,22 +115,6 @@ export class BlockchainEnvironment {
         return this.currentBlock.toU64();
     }
 
-    public origin(): Address {
-        if (!this._origin) {
-            throw this.error('Callee is required');
-        }
-
-        return this._origin as Address;
-    }
-
-    public sender(): Address {
-        if (!this._sender) {
-            throw this.error('Caller is required');
-        }
-
-        return this._sender as Address;
-    }
-
     public setEnvironment(data: Uint8Array): void {
         const reader: BytesReader = new BytesReader(data);
 

package/runtime/storage/StoredU256.ts

@@ -22,7 +22,9 @@ export class StoredU256 {
 
     @inline
     public set value(value: u256) {
-        if (u256.eq(value, this._value)) return;
+        if (u256.eq(value, this._value)) {
+            return;
+        }
 
         this._value = value;