@btc-vision/btc-runtime 1.6.1 → 1.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@btc-vision/btc-runtime",
-    "version": "1.6.1",
+    "version": "1.6.2",
     "description": "Bitcoin Smart Contract Runtime",
     "main": "btc/index.ts",
     "scripts": {},

package/runtime/env/Atomic.ts

@@ -0,0 +1,51 @@
+// @ts-ignore
+@external('env', '__atomic_wait32')
+declare function __atomic_wait32(addr: i32, expected: i32, timeout: i64, proof: ArrayBuffer, verifier: ArrayBuffer): i32;
+
+// @ts-ignore
+@external('env', '__atomic_wait64')
+declare function __atomic_wait64(addr: i32, expected: i64, timeout: i64, proof: ArrayBuffer, verifier: ArrayBuffer): i32;
+
+// @ts-ignore
+@external('env', '__atomic_notify')
+declare function __atomic_notify(addr: i32, count: i32): i32;
+
+// @ts-ignore
+@external('env', '__thread_spawn')
+declare function __thread_spawn(): i32;
+
+export namespace Atomics {
+    export const OK: i32 = 0;
+    export const TIMED_OUT: i32 = 1;
+    export const NOT_EQUAL: i32 = 2;
+    export const NOT_AUTHORIZED: i32 = 3;
+    export const FAULT: i32 = -1;
+
+    /** Waits on `addr` until its value != `expected` or timeout (ns). */
+    export function wait32(addr: usize, expected: i32, timeoutNs: i64, proof: Uint8Array, verifier: Uint8Array): i32 {
+        WARNING('EXPERIMENTAL: wait32 is not yet stable and may change in the future. This feature is not available in production.');
+
+        return __atomic_wait32(<i32>addr, expected, timeoutNs, proof.buffer, verifier.buffer);
+    }
+
+    /** Waits on `addr` until its value != `expected` or timeout (ns). */
+    export function wait64(addr: usize, expected: i64, timeoutNs: i64, proof: Uint8Array, verifier: Uint8Array): i32 {
+        WARNING('EXPERIMENTAL: wait64 is not yet stable and may change in the future. This feature is not available in production.');
+
+        return __atomic_wait64(<i32>addr, expected, timeoutNs, proof.buffer, verifier.buffer);
+    }
+
+    /** Wakes up at most `count` waiters. */
+    export function notify(addr: usize, count: i32 = 1): i32 {
+        WARNING('EXPERIMENTAL: notify is not yet stable and may change in the future. This feature is not available in production.');
+
+        return __atomic_notify(<i32>addr, count);
+    }
+
+    /** Spawns a helper thread. */
+    export function spawn(): i32 {
+        WARNING('EXPERIMENTAL: spawn is not yet stable and may change in the future. This feature is not available in production.');
+
+        return __thread_spawn();
+    }
+}

package/runtime/env/global.ts

@@ -98,3 +98,5 @@ export declare function getAccountType(address: ArrayBuffer): u32;
 // @ts-ignore
 @external('env', 'exit')
 export declare function env_exit(status: u32, data: ArrayBuffer, dataLength: u32): void;
+
+export * from './Atomic';

package/runtime/index.ts

@@ -61,10 +61,15 @@ export * from './nested/codecs/VariableBytesCodec';
 /** Storage */
 export * from './storage/StoredU256';
 export * from './storage/StoredU64';
+export * from './storage/StoredU32';
 export * from './storage/StoredString';
+export * from './storage/AdvancedStoredString';
 export * from './storage/StoredAddress';
 export * from './storage/StoredBoolean';
 
+/** Maps */
+export * from './storage/maps/StoredMapU256';
+
 /** Arrays */
 export * from './storage/arrays/StoredAddressArray';
 export * from './storage/arrays/StoredBooleanArray';

package/runtime/math/bytes.ts

@@ -133,14 +133,14 @@ export function setBit(buffer: Uint8Array, bitIndex: u16, bitValue: bool): void
  * Assume the data is at least 16 bytes, read two u64s from it in big-endian order.
  */
 @inline
-export function readLengthAndStartIndex(data: Uint8Array): u64[] {
+export function readLengthAndStartIndex(data: Uint8Array): u32[] {
     if (data.length < 16) {
         return [0, 0];
     }
 
     const reader = new BytesReader(data);
-    const length = reader.readU64();
-    const startIndex = reader.readU64();
+    const length = reader.readU32();
+    const startIndex = reader.readU32();
 
     return [length, startIndex];
 }
@@ -149,10 +149,10 @@ export function readLengthAndStartIndex(data: Uint8Array): u64[] {
  * Write two u64s into a 32-byte buffer in big-endian order
  */
 @inline
-export function writeLengthAndStartIndex(length: u64, startIndex: u64): Uint8Array {
+export function writeLengthAndStartIndex(length: u32, startIndex: u32): Uint8Array {
     const writer = new BytesWriter(32);
-    writer.writeU64(length);
-    writer.writeU64(startIndex);
+    writer.writeU32(length);
+    writer.writeU32(startIndex);
 
     return writer.getBuffer();
 }
@@ -174,4 +174,4 @@ export function bigEndianAdd(base: Uint8Array, increment: u64): Uint8Array {
     const add = u64ToBE32Bytes(increment);
 
     return addUint8ArraysBE(base, add);
-}
+}

package/runtime/storage/AdvancedStoredString.ts

@@ -0,0 +1,199 @@
+import { Blockchain } from '../env';
+import { encodePointer } from '../math/abi';
+import { bigEndianAdd } from '../math/bytes';
+import { Revert } from '../types/Revert';
+
+const MAX_LENGTH: u32 = 256;
+
+/**
+ * @class AdvancedStoredString
+ * @description
+ * Stores a string in a sequence of 32-byte storage slots, in UTF-8 format:
+ *  - Slot 0: first 4 bytes = length (big-endian), next 28 bytes = partial data
+ *  - Slot N>0: 32 bytes of data each
+ *
+ * The maximum is 65,535 bytes in UTF-8 form (not necessarily the same as code points).
+ */
+@final
+export class AdvancedStoredString {
+    constructor(
+        public pointer: u16,
+        private readonly subPointer: Uint8Array,
+    ) {}
+
+    private _value: string = '';
+
+    /**
+     * Cached string value. If `_value` is empty, we call `load()` on first access.
+     */
+    public get value(): string {
+        if (!this._value) {
+            this.load();
+        }
+        return this._value;
+    }
+
+    public set value(v: string) {
+        this._value = v;
+
+        this.save();
+    }
+
+    /**
+     * Derives a 32-byte pointer for the given chunkIndex and performs big-endian addition.
+     * chunkIndex=0 => header slot, 1 => second slot, etc.
+     */
+    private getPointer(chunkIndex: u64): Uint8Array {
+        const base = encodePointer(this.pointer, this.subPointer);
+        return bigEndianAdd(base, chunkIndex);
+    }
+
+    /**
+     * Reads the first slot and returns the stored byte length (big-endian).
+     * Returns 0 if the slot is all zero.
+     */
+    private getStoredLength(): u32 {
+        const headerSlot = Blockchain.getStorageAt(this.getPointer(0));
+        const b0 = <u32>headerSlot[0];
+        const b1 = <u32>headerSlot[1];
+        const b2 = <u32>headerSlot[2];
+        const b3 = <u32>headerSlot[3];
+        return (b0 << 24) | (b1 << 16) | (b2 << 8) | b3;
+    }
+
+    /**
+     * Clears old data from storage. Based on `oldLength`, determines how many slots
+     * were used, and writes zeroed 32-byte arrays to each.
+     */
+    private clearOldStorage(oldLength: u32): void {
+        if (oldLength == 0) {
+            return;
+        }
+
+        // We always use at least 1 slot (the header slot).
+        let chunkCount: u64 = 1;
+
+        // In the header slot, we can store up to 28 bytes of data.
+        const remaining = oldLength > 28 ? oldLength - 28 : 0;
+        if (remaining > 0) {
+            // Each additional chunk is 32 bytes.
+            // Use integer math ceiling: (remaining + 32 - 1) / 32
+            chunkCount += (remaining + 32 - 1) / 32;
+        }
+
+        // Zero out each previously used slot
+        for (let i: u64 = 0; i < chunkCount; i++) {
+            Blockchain.setStorageAt(this.getPointer(i), new Uint8Array(32));
+        }
+    }
+
+    /**
+     * Saves the current string to storage in UTF-8 form.
+     */
+    private save(): void {
+        // 1) Clear old data
+        const oldLen = this.getStoredLength();
+        this.clearOldStorage(oldLen);
+
+        // 2) Encode new string as UTF-8
+        const utf8Data = String.UTF8.encode(this._value, false);
+        const length = <u32>utf8Data.byteLength;
+
+        // Enforce max length
+        if (length > MAX_LENGTH) {
+            throw new Revert(`StoredString: value is too long (max=${MAX_LENGTH})`);
+        }
+
+        // 3) If new string is empty, just store a zeroed header and return
+        if (length == 0) {
+            // A zeroed 32-byte array => indicates length=0
+            Blockchain.setStorageAt(this.getPointer(0), new Uint8Array(32));
+            return;
+        }
+
+        // 4) Write the first slot: length + up to 28 bytes
+        let remaining: u32 = length;
+        let offset: u32 = 0;
+        const firstSlot = new Uint8Array(32);
+        firstSlot[0] = <u8>((length >> 24) & 0xff);
+        firstSlot[1] = <u8>((length >> 16) & 0xff);
+        firstSlot[2] = <u8>((length >> 8) & 0xff);
+        firstSlot[3] = <u8>(length & 0xff);
+
+        const bytes = Uint8Array.wrap(utf8Data);
+        const firstChunkSize = remaining < 28 ? remaining : 28;
+        for (let i: u32 = 0; i < firstChunkSize; i++) {
+            firstSlot[4 + i] = bytes[i];
+        }
+        Blockchain.setStorageAt(this.getPointer(0), firstSlot);
+
+        remaining -= firstChunkSize;
+        offset += firstChunkSize;
+
+        // 5) Write subsequent slots (32 bytes each)
+        let chunkIndex: u64 = 1;
+        while (remaining > 0) {
+            const slotData = new Uint8Array(32);
+            const chunkSize = remaining < u32(32) ? remaining : u32(32);
+            for (let i: u32 = 0; i < chunkSize; i++) {
+                slotData[i] = bytes[offset + i];
+            }
+            Blockchain.setStorageAt(this.getPointer(chunkIndex), slotData);
+
+            remaining -= chunkSize;
+            offset += chunkSize;
+            chunkIndex++;
+        }
+    }
+
+    /**
+     * Loads the string from storage by reading the stored byte length, then decoding
+     * the corresponding UTF-8 data from the slots.
+     */
+    private load(): void {
+        // Read the header slot first
+        const headerSlot = Blockchain.getStorageAt(this.getPointer(0));
+
+        // Parse the big-endian length
+        const b0 = <u32>headerSlot[0];
+        const b1 = <u32>headerSlot[1];
+        const b2 = <u32>headerSlot[2];
+        const b3 = <u32>headerSlot[3];
+        const length: u32 = (b0 << 24) | (b1 << 16) | (b2 << 8) | b3;
+
+        // If length=0, then the string is empty
+        if (length == 0) {
+            this._value = '';
+            return;
+        }
+
+        // Read the UTF-8 bytes from storage
+        let remaining: u32 = length;
+        let offset: u32 = 0;
+        const out = new Uint8Array(length);
+
+        // First slot can hold up to 28 bytes after the length
+        const firstChunkSize = remaining < 28 ? remaining : 28;
+        for (let i: u32 = 0; i < firstChunkSize; i++) {
+            out[i] = headerSlot[4 + i];
+        }
+        remaining -= firstChunkSize;
+        offset += firstChunkSize;
+
+        // Read the subsequent slots of 32 bytes each
+        let chunkIndex: u64 = 1;
+        while (remaining > 0) {
+            const slotData = Blockchain.getStorageAt(this.getPointer(chunkIndex));
+            const chunkSize = remaining < 32 ? remaining : 32;
+            for (let i: u32 = 0; i < chunkSize; i++) {
+                out[offset + i] = slotData[i];
+            }
+            remaining -= chunkSize;
+            offset += chunkSize;
+            chunkIndex++;
+        }
+
+        // Decode UTF-8 into a normal string
+        this._value = String.UTF8.decode(out.buffer, false);
+    }
+}

package/runtime/storage/StoredU32.ts

@@ -0,0 +1,178 @@
+import { u256 } from '@btc-vision/as-bignum/assembly';
+import { BytesWriter } from '../buffer/BytesWriter';
+import { Blockchain } from '../env';
+import { encodePointer } from '../math/abi';
+import { BytesReader } from '../buffer/BytesReader';
+
+/**
+ * @class StoredU32
+ * @description Manages up to height u32 values within a single u256 storage slot.
+ */
+@final
+export class StoredU32 {
+    private readonly bufferPointer: Uint8Array;
+
+    // Internal cache for four u32 values
+    private _values: u32[] = [0, 0, 0, 0, 0, 0, 0, 0];
+
+    // Flag to indicate if values are loaded from storage
+    private isLoaded: bool = false;
+
+    // Flag to indicate if any value has been changed
+    private isChanged: bool = false;
+
+    /**
+     * @constructor
+     * @param {u16} pointer - The primary pointer identifier.
+     * @param {Uint8Array} subPointer - The sub-pointer for memory slot addressing.
+     */
+    constructor(
+        public pointer: u16,
+        public subPointer: Uint8Array,
+    ) {
+        assert(
+            subPointer.length <= 30,
+            `You must pass a 30 bytes sub-pointer. (StoredU32, got ${subPointer.length})`,
+        );
+
+        this.bufferPointer = encodePointer(pointer, subPointer);
+    }
+
+    /**
+     * @method get
+     * @description Retrieves the u32 value at the specified offset.
+     * @param {u8} index - The index (0 to 7) of the u32 value to retrieve.
+     * @returns {u32} - The u32 value at the specified index.
+     */
+    @inline
+    public get(index: u8): u32 {
+        assert(index < 8, 'Index out of bounds for StoredU32 (0-7)');
+        this.ensureValues();
+        return this._values[index];
+    }
+
+    /**
+     * @method set
+     * @description Sets the u32 value at the specified offset.
+     * @param {u8} index - The index (0 to 7) of the u32 value to set.
+     * @param {u32} value - The u32 value to assign.
+     */
+    @inline
+    public set(index: u8, value: u32): void {
+        assert(index < 8, 'Index out of bounds for StoredU32 (0-7)');
+        this.ensureValues();
+        if (this._values[index] != value) {
+            this._values[index] = value;
+            this.isChanged = true;
+        }
+    }
+
+    /**
+     * @method save
+     * @description Persists the cached u32 values to storage if any have been modified.
+     */
+    public save(): void {
+        if (this.isChanged) {
+            const packed = this.packValues();
+            Blockchain.setStorageAt(this.bufferPointer, packed);
+            this.isChanged = false;
+        }
+    }
+
+    /**
+     * @method setMultiple
+     * @description Sets multiple u32 values at once.
+     * @param {[u32, u32, u32, u32,u32, u32, u32, u32]} values - An array of four u32 values to set.
+     */
+    @inline
+    public setMultiple(values: u32[]): void {
+        this.ensureValues();
+        let changed = false;
+        for (let i: u8 = 0; i < 8; i++) {
+            if (this._values[i] != values[i]) {
+                this._values[i] = values[i];
+                changed = true;
+            }
+        }
+        if (changed) {
+            this.isChanged = true;
+        }
+    }
+
+    /**
+     * @method getAll
+     * @description Retrieves all height u32 values as a tuple.
+     * @returns {[u32, u32, u32, u32,u32, u32, u32, u32]} - A tuple containing all four u32 values.
+     */
+    @inline
+    public getAll(): u32[] {
+        this.ensureValues();
+        return this._values;
+    }
+
+    /**
+     * @method toString
+     * @description Returns a string representation of all height u32 values.
+     * @returns {string} - A string in the format "[value0, value1, value2, value3, value4, value5, value6, value7]".
+     */
+    @inline
+    public toString(): string {
+        this.ensureValues();
+        return `[${this._values[0].toString()}, ${this._values[1].toString()}, ${this._values[2].toString()}, ${this._values[3].toString()},, ${this._values[4].toString()},, ${this._values[5].toString()},, ${this._values[6].toString()},, ${this._values[7].toString()}]`;
+    }
+
+    /**
+     * @method reset
+     * @description Resets the cached values to default and marks as changed.
+     */
+    @inline
+    public reset(): void {
+        this._values = [0, 0, 0, 0, 0, 0, 0, 0];
+        this.isChanged = true;
+    }
+
+    /**
+     * @private
+     * @method ensureValues
+     * @description Loads and unpacks the u256 value from storage into height u32 cache variables.
+     */
+    private ensureValues(): void {
+        if (!this.isLoaded) {
+            const storedU256: Uint8Array = Blockchain.getStorageAt(this.bufferPointer);
+
+            const reader = new BytesReader(storedU256);
+
+            this._values[0] = reader.readU32();
+            this._values[1] = reader.readU32();
+            this._values[2] = reader.readU32();
+            this._values[3] = reader.readU32();
+            this._values[4] = reader.readU32();
+            this._values[5] = reader.readU32();
+            this._values[6] = reader.readU32();
+            this._values[7] = reader.readU32();
+
+            this.isLoaded = true;
+        }
+    }
+
+    /**
+     * @private
+     * @method packValues
+     * @description Packs the height cached u32 values into a single u256 for storage.
+     * @returns {u256} - The packed u256 value.
+     */
+    private packValues(): Uint8Array {
+        const writer = new BytesWriter(32);
+
+        writer.writeU32(this._values[0]);
+        writer.writeU32(this._values[1]);
+        writer.writeU32(this._values[2]);
+        writer.writeU32(this._values[3]);
+        writer.writeU32(this._values[4]);
+        writer.writeU32(this._values[5]);
+        writer.writeU32(this._values[6]);
+        writer.writeU32(this._values[7]);
+
+        return writer.getBuffer();
+    }
+}