@btc-vision/btc-runtime 1.8.1 → 1.9.0

package/README.md

@@ -31,13 +31,13 @@ execution while integrating deeply with Bitcoin's decentralized architecture.
 
 ### Features
 
--   **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.
+- **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
 
@@ -95,22 +95,20 @@ Here is a real-world example of how to create a basic token contract using the O
 contract follows the OP20 standard.
 
 ```typescript
+import { u256 } from '@btc-vision/as-bignum/assembly';
 import {
     Address,
+    AddressMap,
     Blockchain,
     BytesWriter,
     Calldata,
-    DeployableOP_20,
-    encodeSelector,
-    Map,
+    OP20,
     OP20InitParameters,
-    Selector,
-    AddressMap,
+    SafeMath,
 } from '@btc-vision/btc-runtime/runtime';
-import { u128, u256 } from 'as-bignum/assembly';
 
 @final
-export class MyToken extends DeployableOP_20 {
+export class MyToken extends OP20 {
     public constructor() {
         super();
 
@@ -119,71 +117,72 @@ export class MyToken extends DeployableOP_20 {
 
     // "solidityLikeConstructor" This is a solidity-like constructor. This method will only run once when the contract is deployed.
     public override onDeployment(_calldata: Calldata): void {
-        const maxSupply: u256 = u128.fromString('100000000000000000000000000').toU256(); // Your max supply.
+        const maxSupply: u256 = u256.fromString('1000000000000000000000000000'); // Your max supply. (Here, 1 billion tokens)
         const decimals: u8 = 18; // Your decimals.
-        const name: string = 'MyToken'; // Your token name.
-        const symbol: string = 'TOKEN'; // Your token symbol.
+        const name: string = 'Test'; // Your token name.
+        const symbol: string = 'TEST'; // Your token symbol.
 
         this.instantiate(new OP20InitParameters(maxSupply, decimals, name, symbol));
 
         // Add your logic here. Eg, minting the initial supply:
-        this._mint(Blockchain.tx.origin, maxSupply);
+        // this._mint(Blockchain.tx.origin, maxSupply);
     }
 
-    public override execute(method: Selector, calldata: Calldata): BytesWriter {
-        switch (method) {
-            case encodeSelector('airdrop()'):
-                return this.airdrop(calldata);
-            case encodeSelector('airdropWithAmount()'):
-                return this.airdropWithAmount(calldata);
-            default:
-                return super.execute(method, calldata);
-        }
+    @method(
+        {
+            name: 'address',
+            type: ABIDataTypes.ADDRESS,
+        },
+        {
+            name: 'amount',
+            type: ABIDataTypes.UINT256,
+        },
+    )
+    @emit('Minted')
+    public mint(calldata: Calldata): BytesWriter {
+        this.onlyDeployer(Blockchain.tx.sender);
+        this._mint(calldata.readAddress(), calldata.readU256());
+        return new BytesWriter(0);
     }
 
-    private airdrop(calldata: Calldata): BytesWriter {
+    /**
+     * Mints tokens to the specified addresses.
+     *
+     * @param calldata Calldata containing an `AddressMap<Address, u256>` to mint to.
+     */
+    @method({
+        name: 'addressAndAmount',
+        type: ABIDataTypes.ADDRESS_UINT256_TUPLE,
+    })
+    @emit('Minted')
+    public airdrop(calldata: Calldata): BytesWriter {
         this.onlyDeployer(Blockchain.tx.sender);
 
-        const drops: AddressMap<u256> = calldata.readAddressValueTuple();
+        const addressAndAmount: AddressMap<u256> = calldata.readAddressMapU256();
+        const addresses: Address[] = addressAndAmount.keys();
+
+        let totalAirdropped: u256 = u256.Zero;
 
-        const addresses: Address[] = drops.keys();
         for (let i: i32 = 0; i < addresses.length; i++) {
             const address = addresses[i];
-            const amount = drops.get(address);
+            const amount = addressAndAmount.get(address);
 
-            this._mint(address, amount, false);
-        }
+            const currentBalance: u256 = this.balanceOfMap.get(address);
 
-        const writer: BytesWriter = new BytesWriter(1);
-        writer.writeBoolean(true);
+            if (currentBalance) {
+                this.balanceOfMap.set(address, SafeMath.add(currentBalance, amount));
+            } else {
+                this.balanceOfMap.set(address, amount);
+            }
 
-        return writer;
-    }
-
-    private _optimizedMint(address: Address, amount: u256): void {
-        this.balanceOfMap.set(address, amount);
-
-        this._totalSupply.addNoCommit(amount);
-
-        this.createMintEvent(address, amount);
-    }
-
-    private airdropWithAmount(calldata: Calldata): BytesWriter {
-        this.onlyDeployer(Blockchain.tx.sender);
+            totalAirdropped = SafeMath.add(totalAirdropped, amount);
 
-        const amount: u256 = calldata.readU256();
-        const addresses: Address[] = calldata.readAddressArray();
-
-        for (let i: i32 = 0; i < addresses.length; i++) {
-            this._optimizedMint(addresses[i], amount);
+            this.createMintedEvent(address, amount);
         }
 
-        this._totalSupply.commit();
-
-        const writer: BytesWriter = new BytesWriter(1);
-        writer.writeBoolean(true);
+        this._totalSupply.set(SafeMath.add(this._totalSupply.value, totalAirdropped));
 
-        return writer;
+        return new BytesWriter(0);
     }
 }
 ```
@@ -196,27 +195,6 @@ Storage pointers and sub-pointers are encoded and hashed to create unique and se
 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
 
 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.8.1",
+    "version": "1.9.0",
     "description": "Bitcoin Smart Contract Runtime",
     "main": "btc/index.ts",
     "scripts": {},
@@ -17,8 +17,8 @@
     "author": "BlobMaster41",
     "license": "MIT",
     "devDependencies": {
-        "@types/node": "^24.0.3",
-        "assemblyscript": "^0.28.2"
+        "@types/node": "^24.2.1",
+        "assemblyscript": "^0.28.4"
     },
     "repository": {
         "type": "git",
@@ -35,13 +35,13 @@
         "test/*.ts"
     ],
     "dependencies": {
-        "@assemblyscript/loader": "^0.28.2",
+        "@assemblyscript/loader": "^0.28.4",
         "@btc-vision/as-bignum": "^0.0.5",
-        "@btc-vision/opnet-transform": "^0.1.6",
-        "@eslint/js": "^9.29.0",
+        "@btc-vision/opnet-transform": "^0.1.10",
+        "@eslint/js": "^9.33.0",
         "gulplog": "^2.2.0",
         "ts-node": "^10.9.2",
-        "typescript": "^5.8.3",
-        "typescript-eslint": "^8.35.0"
+        "typescript": "^5.9.2",
+        "typescript-eslint": "^8.39.0"
     }
 }

package/runtime/buffer/BytesReader.ts

@@ -6,7 +6,10 @@ import { Revert } from '../types/Revert';
 import {
     ADDRESS_BYTE_LENGTH,
     I128_BYTE_LENGTH,
+    I16_BYTE_LENGTH,
+    I32_BYTE_LENGTH,
     I64_BYTE_LENGTH,
+    I8_BYTE_LENGTH,
     U128_BYTE_LENGTH,
     U16_BYTE_LENGTH,
     U256_BYTE_LENGTH,
@@ -14,7 +17,6 @@ import {
     U64_BYTE_LENGTH,
     U8_BYTE_LENGTH,
 } from '../utils';
-import { sizeof } from 'builtins';
 
 @final
 export class BytesReader {
@@ -41,31 +43,31 @@ export class BytesReader {
                 const size = sizeof<T>();
 
                 switch (size) {
-                    case 8:
-                        return this.readU8() as T;
-                    case 16:
+                    case I8_BYTE_LENGTH:
+                        return this.readI8() as T;
+                    case I16_BYTE_LENGTH:
                         return this.readI16() as T;
-                    case 32:
+                    case I32_BYTE_LENGTH:
                         return this.readI32() as T;
-                    case 64:
+                    case I64_BYTE_LENGTH:
                         return this.readI64() as T;
                     default:
-                        throw new Error(`Invalid size ${size}`);
+                        throw new Revert(`Invalid size ${size}`);
                 }
             } else {
                 const size = sizeof<T>();
 
                 switch (size) {
-                    case 8:
+                    case U8_BYTE_LENGTH:
                         return this.readU8() as T;
-                    case 16:
+                    case U16_BYTE_LENGTH:
                         return this.readU16() as T;
-                    case 32:
+                    case U32_BYTE_LENGTH:
                         return this.readU32() as T;
-                    case 64:
+                    case U64_BYTE_LENGTH:
                         return this.readU64() as T;
                     default:
-                        throw new Error(`Invalid size ${size}`);
+                        throw new Revert(`Invalid size ${size}`);
                 }
             }
         } else if (id === idof<u256>()) {
@@ -81,21 +83,35 @@ export class BytesReader {
         } else if (id === idof<string>()) {
             return this.readStringWithLength() as T;
         } else {
-            throw new Error(`Unsupported type ${id}`);
+            throw new Revert(`Unsupported type ${id}`);
         }
     }
 
+    public readI8(): i8 {
+        this.verifyEnd(this.currentOffset + I8_BYTE_LENGTH);
+        const value = this.buffer.getInt8(this.currentOffset);
+        this.currentOffset += I8_BYTE_LENGTH;
+        return value;
+    }
+
     public readI16(): i16 {
-        this.verifyEnd(this.currentOffset + 2);
+        this.verifyEnd(this.currentOffset + I16_BYTE_LENGTH);
         const value = this.buffer.getInt16(this.currentOffset, true);
-        this.currentOffset += 2;
+        this.currentOffset += I16_BYTE_LENGTH;
         return value;
     }
 
     public readI32(): i32 {
-        this.verifyEnd(this.currentOffset + 4);
+        this.verifyEnd(this.currentOffset + I32_BYTE_LENGTH);
         const value = this.buffer.getInt32(this.currentOffset, true);
-        this.currentOffset += 4;
+        this.currentOffset += I32_BYTE_LENGTH;
+        return value;
+    }
+
+    public readI64(be: boolean = true): i64 {
+        this.verifyEnd(this.currentOffset + I64_BYTE_LENGTH);
+        const value = this.buffer.getInt64(this.currentOffset, !be);
+        this.currentOffset += I64_BYTE_LENGTH;
         return value;
     }
 
@@ -146,13 +162,6 @@ export class BytesReader {
         return be ? u256.fromBytesBE(raw) : u256.fromBytesLE(raw);
     }
 
-    public readI64(be: boolean = true): i64 {
-        this.verifyEnd(this.currentOffset + I64_BYTE_LENGTH);
-        const value = this.buffer.getInt64(this.currentOffset, !be);
-        this.currentOffset += I64_BYTE_LENGTH;
-        return value;
-    }
-
     public readU128(be: boolean = true): u128 {
         this.verifyEnd(this.currentOffset + U128_BYTE_LENGTH);
         const raw: u8[] = this.readBytesArray(U128_BYTE_LENGTH);
@@ -211,10 +220,6 @@ export class BytesReader {
         return String.UTF8.decode(bytes.buffer);
     }
 
-    /**
-     * [u16 length][raw bytes].
-     * The AS writer calls `writeStringWithLength(value: string)` => writes length big-endian by default.
-     */
     public readStringWithLength(be: boolean = true): string {
         const length = this.readU32(be);
         return this.readString(length);
@@ -243,13 +248,8 @@ export class BytesReader {
 
     // ------------------- Arrays ------------------- //
 
-    /**
-     * The AS writer does `writeU32(length)` for U256 arrays, so we read a u32.
-     * If you changed it to a `u16`, then do readU16() here.
-     */
     public readU256Array(be: boolean = true): u256[] {
-        // The AS writer currently writes a u32 length for U256 arrays
-        const length = this.readU32();
+        const length = this.readU16();
         const result = new Array<u256>(length);
         for (let i: u32 = 0; i < length; i++) {
             result[i] = this.readU256(be);
@@ -257,9 +257,6 @@ export class BytesReader {
         return result;
     }
 
-    /**
-     * The AS writer uses a [u16 length] for U64 arrays.
-     */
     public readU64Array(be: boolean = true): u64[] {
         const length = this.readU16(be);
         const result = new Array<u64>(length);
@@ -296,10 +293,6 @@ export class BytesReader {
         return result;
     }
 
-    /**
-     * The AS writer uses a [u8 length] for transaction inputs/outputs in the example,
-     * but for an "AddressArray" we use [u16 length].
-     */
     public readAddressArray(be: boolean = true): Address[] {
         const length = this.readU16(be);
         const result = new Array<Address>(length);
@@ -309,9 +302,6 @@ export class BytesReader {
         return result;
     }
 
-    /**
-     * Map of [u16 length] entries, each entry = [Address, U256], consistent with the writer’s `writeAddressMapU256`.
-     */
     public readAddressMapU256(be: boolean = true): AddressMap<u256> {
         const length = this.readU16(be);
         const result = new AddressMap<u256>();
@@ -334,6 +324,7 @@ export class BytesReader {
     }
 
     public setOffset(offset: i32): void {
+        this.verifyEnd(offset);
         this.currentOffset = offset;
     }
 
@@ -342,7 +333,7 @@ export class BytesReader {
      */
     public verifyEnd(size: i32): void {
         if (size > this.buffer.byteLength) {
-            throw new Error(
+            throw new Revert(
                 `Attempt to read beyond buffer length. Requested up to offset ${size}, ` +
                     `but buffer is only ${this.buffer.byteLength} bytes.`,
             );

package/runtime/buffer/BytesWriter.ts

@@ -6,6 +6,10 @@ import { Revert } from '../types/Revert';
 import {
     ADDRESS_BYTE_LENGTH,
     I128_BYTE_LENGTH,
+    I16_BYTE_LENGTH,
+    I32_BYTE_LENGTH,
+    I64_BYTE_LENGTH,
+    I8_BYTE_LENGTH,
     U128_BYTE_LENGTH,
     U16_BYTE_LENGTH,
     U256_BYTE_LENGTH,
@@ -33,20 +37,19 @@ export class BytesWriter {
     public write<T>(value: T): void {
         if (isInteger<T>()) {
             const size = sizeof<T>();
-            if (size === 1) {
-                this.writeU8(<u8>value);
-                return;
-            }
 
             if (isSigned<T>()) {
                 switch (size) {
-                    case 2:
+                    case I8_BYTE_LENGTH:
+                        this.writeI8(<i8>value);
+                        break;
+                    case I16_BYTE_LENGTH:
                         this.writeI16(<i16>value);
                         break;
-                    case 4:
+                    case I32_BYTE_LENGTH:
                         this.writeI32(<i32>value);
                         break;
-                    case 8:
+                    case I64_BYTE_LENGTH:
                         this.writeI64(<i64>value);
                         break;
                     default:
@@ -54,13 +57,16 @@ export class BytesWriter {
                 }
             } else {
                 switch (size) {
-                    case 2:
+                    case U8_BYTE_LENGTH:
+                        this.writeU8(<u8>value);
+                        break;
+                    case U16_BYTE_LENGTH:
                         this.writeU16(<u16>value);
                         break;
-                    case 4:
+                    case U32_BYTE_LENGTH:
                         this.writeU32(<u32>value);
                         break;
-                    case 8:
+                    case U64_BYTE_LENGTH:
                         this.writeU64(<u64>value);
                         break;
                     default:
@@ -121,21 +127,27 @@ export class BytesWriter {
     }
 
     public writeI64(value: i64, be: boolean = true): void {
-        this.allocSafe(U64_BYTE_LENGTH);
+        this.allocSafe(I64_BYTE_LENGTH);
         this.buffer.setInt64(this.currentOffset, value, !be);
-        this.currentOffset += U64_BYTE_LENGTH;
+        this.currentOffset += I64_BYTE_LENGTH;
     }
 
     public writeI32(value: i32, be: boolean = true): void {
-        this.allocSafe(U32_BYTE_LENGTH);
+        this.allocSafe(I32_BYTE_LENGTH);
         this.buffer.setInt32(this.currentOffset, value, !be);
-        this.currentOffset += U32_BYTE_LENGTH;
+        this.currentOffset += I32_BYTE_LENGTH;
     }
 
     public writeI16(value: i16, be: boolean = true): void {
-        this.allocSafe(U16_BYTE_LENGTH);
+        this.allocSafe(I16_BYTE_LENGTH);
         this.buffer.setInt16(this.currentOffset, value, !be);
-        this.currentOffset += U16_BYTE_LENGTH;
+        this.currentOffset += I16_BYTE_LENGTH;
+    }
+
+    public writeI8(value: u8): void {
+        this.allocSafe(I8_BYTE_LENGTH);
+        this.buffer.setInt8(this.currentOffset, value);
+        this.currentOffset += I8_BYTE_LENGTH;
     }
 
     /**
@@ -289,6 +301,38 @@ export class BytesWriter {
         this.writeBytes(bytes);
     }
 
+    // zero-copy bulk writer
+    public writeRaw(data: Uint8Array): void {
+        const n = data.length;
+        this.allocSafe(n);
+
+        const off = this.currentOffset;
+        const dst = this.typedArray;
+
+        memory.copy(changetype<usize>(dst.buffer) + <usize>off, changetype<usize>(data.buffer), n);
+
+        this.currentOffset = off + n;
+    }
+
+    public writeRawSlice(data: Uint8Array, offset: i32, length: i32): void {
+        if (offset < 0 || length < 0 || offset + length > data.length) {
+            throw new Revert('writeRawSlice bounds');
+        }
+
+        this.allocSafe(length);
+
+        const off = this.currentOffset;
+        const dst = this.typedArray;
+
+        memory.copy(
+            changetype<usize>(dst.buffer) + <usize>off,
+            changetype<usize>(data.buffer) + <usize>offset,
+            length,
+        );
+
+        this.currentOffset = off + length;
+    }
+
     /**
      * Equivalent to TS’s writeAddressValueTuple, except specialized for u256 values.
      */
@@ -318,10 +362,6 @@ export class BytesWriter {
         return this.currentOffset;
     }
 
-    public setOffset(offset: u32): void {
-        this.currentOffset = offset;
-    }
-
     /**
      * Ensures we have space for `size` more bytes without going past the current buffer.
      * If not, calls `resize()` which by default throws a Revert.