@btc-vision/btc-runtime 1.3.8 → 1.3.10

package/runtime/storage/StoredU256Array.ts

@@ -0,0 +1,382 @@
+import { u256 } from 'as-bignum/assembly';
+import { Blockchain } from '../env';
+import { BytesWriter } from '../buffer/BytesWriter';
+import { SafeMath } from '../types/SafeMath';
+import { Revert } from '../types/Revert';
+
+/**
+ * @class StoredU256Array
+ * @description Manages an array of u256 values across multiple storage slots. Each slot holds one u256 value.
+ */
+@final
+export class StoredU256Array {
+    private readonly baseU256Pointer: u256;
+    private readonly lengthPointer: u256;
+
+    // Internal cache for storage slots
+    private _values: Map<u64, u256> = new Map(); // Map from slotIndex to u256 value
+    private _isLoaded: Set<u64> = new Set(); // Set of slotIndexes that are loaded
+    private _isChanged: Set<u64> = new Set(); // Set of slotIndexes that are modified
+
+    // Internal variables for length and startIndex management
+    private _length: u64 = 0; // Current length of the array
+    private _startIndex: u64 = 0; // Starting index of the array
+    private _isChangedLength: bool = false; // Indicates if the length has been modified
+    private _isChangedStartIndex: bool = false; // Indicates if the startIndex has been modified
+
+    // Define a maximum allowed length to prevent excessive storage usage
+    private readonly MAX_LENGTH: u64 = u64.MAX_VALUE - 1;
+
+    /**
+     * @constructor
+     * @param {u16} pointer - The primary pointer identifier.
+     * @param {Uint8Array} subPointer - The sub-pointer for memory slot addressing.
+     * @param {u256} defaultValue - The default u256 value if storage is uninitialized.
+     */
+    constructor(
+        public pointer: u16,
+        public subPointer: Uint8Array,
+        private defaultValue: u256,
+    ) {
+        // Initialize the base u256 pointer using the primary pointer and subPointer
+        const writer = new BytesWriter(32);
+        writer.writeU16(pointer);
+        writer.writeBytes(subPointer);
+
+        // Initialize the base and length pointers
+        const baseU256Pointer = u256.fromBytes(writer.getBuffer(), true);
+        const lengthPointer = baseU256Pointer.clone();
+
+        // Load the current length and startIndex from storage
+        const storedLengthAndStartIndex: u256 = Blockchain.getStorageAt(lengthPointer, u256.Zero);
+        this.lengthPointer = lengthPointer;
+        this.baseU256Pointer = baseU256Pointer;
+
+        this._length = storedLengthAndStartIndex.lo1; // Bytes 0-7: length
+        this._startIndex = storedLengthAndStartIndex.lo2; // Bytes 8-15: startIndex
+    }
+
+    /**
+     * @method get
+     * @description Retrieves the u256 value at the specified global index.
+     * @param {u64} index - The global index (0 to ∞) of the u256 value to retrieve.
+     * @returns {u256} - The u256 value at the specified index.
+     */
+    @inline
+    public get(index: u64): u256 {
+        assert(index < this._length, 'Index out of bounds');
+        const slotIndex: u32 = <u32>index;
+        this.ensureValues(slotIndex);
+        const value = this._values.get(slotIndex);
+        return value ? value : u256.Zero;
+    }
+
+    /**
+     * @method set
+     * @description Sets the u256 value at the specified global index.
+     * @param {u64} index - The global index (0 to ∞) of the u256 value to set.
+     * @param {u256} value - The u256 value to assign.
+     */
+    @inline
+    public set(index: u64, value: u256): void {
+        assert(index < this._length, 'Index exceeds current array length');
+        const slotIndex: u32 = <u32>index;
+        this.ensureValues(slotIndex);
+
+        const currentValue = this._values.get(slotIndex);
+        if (!u256.eq(currentValue, value)) {
+            this._values.set(slotIndex, value);
+            this._isChanged.add(slotIndex);
+        }
+    }
+
+    /**
+     * @method push
+     * @description Appends a new u256 value to the end of the array.
+     * @param {u256} value - The u256 value to append.
+     */
+    public push(value: u256): void {
+        if (this._length >= this.MAX_LENGTH) {
+            throw new Revert(
+                'Push operation failed: Array has reached its maximum allowed length.',
+            );
+        }
+
+        const newIndex: u64 = this._length;
+        const effectiveIndex: u64 = this._startIndex + newIndex;
+        const wrappedIndex: u64 =
+            effectiveIndex < this.MAX_LENGTH ? effectiveIndex : effectiveIndex % this.MAX_LENGTH;
+        const slotIndex: u32 = <u32>wrappedIndex;
+
+        // Ensure the slot is loaded
+        this.ensureValues(slotIndex);
+
+        // Set the new value
+        this._values.set(slotIndex, value);
+        this._isChanged.add(slotIndex);
+
+        // Increment the length
+        this._length += 1;
+        this._isChangedLength = true;
+    }
+
+    /**
+     * @method delete
+     * @description Deletes the u256 value at the specified index by setting it to zero. Does not reorder the array.
+     * @param {u64} index - The global index of the u256 value to delete.
+     */
+    public delete(index: u64): void {
+        if (index >= this._length) {
+            throw new Revert('Delete operation failed: Index out of bounds.');
+        }
+
+        const slotIndex: u32 = <u32>index;
+        this.ensureValues(slotIndex);
+
+        const currentValue = this._values.get(slotIndex);
+        if (!u256.eq(currentValue, u256.Zero)) {
+            this._values.set(slotIndex, u256.Zero);
+            this._isChanged.add(slotIndex);
+        }
+    }
+
+    /**
+     * @method shift
+     * @description Removes the first element of the array by setting it to zero, decrementing the length, and incrementing the startIndex.
+     *              If the startIndex reaches the maximum value of u64, it wraps around to 0.
+     */
+    public shift(): void {
+        if (this._length === 0) {
+            throw new Revert('Shift operation failed: Array is empty.');
+        }
+
+        const currentStartIndex: u64 = this._startIndex;
+        const slotIndex: u32 = <u32>currentStartIndex;
+        this.ensureValues(slotIndex);
+
+        const currentValue = this._values.get(slotIndex);
+        if (!u256.eq(currentValue, u256.Zero)) {
+            this._values.set(slotIndex, u256.Zero);
+            this._isChanged.add(slotIndex);
+        }
+
+        // Decrement the length
+        this._length -= 1;
+        this._isChangedLength = true;
+
+        // Increment the startIndex with wrap-around
+        if (this._startIndex < this.MAX_LENGTH - 1) {
+            this._startIndex += 1;
+        } else {
+            this._startIndex = 0;
+        }
+        this._isChangedStartIndex = true;
+    }
+
+    /**
+     * @method save
+     * @description Persists all cached u256 values, the length, and the startIndex to their respective storage slots if any have been modified.
+     */
+    public save(): void {
+        // Save all changed slots
+        const changed = this._isChanged.values();
+        for (let i = 0; i < changed.length; i++) {
+            const slotIndex = changed[i];
+            const storagePointer = this.calculateStoragePointer(slotIndex);
+            const value = this._values.get(slotIndex);
+            Blockchain.setStorageAt(storagePointer, value);
+        }
+        this._isChanged.clear();
+
+        // Save length and startIndex if changed
+        if (this._isChangedLength || this._isChangedStartIndex) {
+            const packedLengthAndStartIndex = new u256();
+            packedLengthAndStartIndex.lo1 = this._length;
+            packedLengthAndStartIndex.lo2 = this._startIndex;
+            Blockchain.setStorageAt(this.lengthPointer, packedLengthAndStartIndex);
+            this._isChangedLength = false;
+            this._isChangedStartIndex = false;
+        }
+    }
+
+    /**
+     * @method deleteAll
+     * @description Deletes all storage slots by setting them to zero, including the length and startIndex slots.
+     */
+    public deleteAll(): void {
+        // Iterate over all loaded slots and clear them
+        const keys = this._values.keys();
+        for (let i = 0; i < keys.length; i++) {
+            const slotIndex = keys[i];
+            const storagePointer = this.calculateStoragePointer(slotIndex);
+            Blockchain.setStorageAt(storagePointer, u256.Zero);
+        }
+
+        // Reset the length and startIndex to zero
+        const zeroLengthAndStartIndex = u256.Zero;
+        Blockchain.setStorageAt(this.lengthPointer, zeroLengthAndStartIndex);
+        this._length = 0;
+        this._startIndex = 0;
+        this._isChangedLength = false;
+        this._isChangedStartIndex = false;
+
+        // Clear internal caches
+        this._values.clear();
+        this._isLoaded.clear();
+        this._isChanged.clear();
+    }
+
+    /**
+     * @method setMultiple
+     * @description Sets multiple u256 values starting from a specific global index.
+     * @param {u32} startIndex - The starting global index.
+     * @param {u256[]} values - An array of u256 values to set.
+     */
+    @inline
+    public setMultiple(startIndex: u32, values: u256[]): void {
+        for (let i: u32 = 0; i < values.length; i++) {
+            this.set(<u64>(startIndex + i), values[i]);
+        }
+    }
+
+    /**
+     * @method getAll
+     * @description Retrieves a range of u256 values starting from a specific global index.
+     * @param {u32} startIndex - The starting global index.
+     * @param {u32} count - The number of u256 values to retrieve.
+     * @returns {u256[]} - An array containing the retrieved u256 values.
+     */
+    @inline
+    public getAll(startIndex: u32, count: u32): u256[] {
+        assert(startIndex + count <= this._length, 'Requested range exceeds array length');
+        const result: u256[] = new Array<u256>(count);
+        for (let i: u32 = 0; i < count; i++) {
+            result[i] = this.get(<u64>(startIndex + i));
+        }
+        return result;
+    }
+
+    /**
+     * @method toString
+     * @description Returns a string representation of all cached u256 values.
+     * @returns {string} - A string in the format "[value0, value1, ..., valueN]".
+     */
+    @inline
+    public toString(): string {
+        let str = '[';
+        for (let i: u32 = 0; i < this._length; i++) {
+            const value = this.get(<u64>i);
+            str += value.toString();
+            if (i !== this._length - 1) {
+                str += ', ';
+            }
+        }
+        str += ']';
+        return str;
+    }
+
+    /**
+     * @method toBytes
+     * @description Returns the packed u256 values as a byte array.
+     * @returns {u8[]} - The packed u256 values in byte form.
+     */
+    @inline
+    public toBytes(): u8[] {
+        const bytes: u8[] = new Array<u8>();
+        for (let i: u32 = 0; i < this._length; i++) {
+            this.ensureValues(i);
+            const value = this._values.get(i);
+            if (value) {
+                const valueBytes = value.toBytes();
+                for (let j: u32 = 0; j < valueBytes.length; j++) {
+                    bytes.push(valueBytes[j]);
+                }
+            }
+        }
+        return bytes;
+    }
+
+    /**
+     * @method reset
+     * @description Resets all cached u256 values to zero and marks them as changed, including resetting the length and startIndex.
+     */
+    @inline
+    public reset(): void {
+        // Reset the length and startIndex to zero
+        this._length = 0;
+        this._startIndex = 0;
+        this._isChangedLength = true;
+        this._isChangedStartIndex = true;
+
+        this.save();
+    }
+
+    /**
+     * @method getLength
+     * @description Retrieves the current length of the array.
+     * @returns {u64} - The current length.
+     */
+    @inline
+    public getLength(): u64 {
+        return this._length;
+    }
+
+    /**
+     * @method startingIndex
+     * @description Retrieves the current starting index of the array.
+     * @returns {u64} - The starting index.
+     */
+    public startingIndex(): u64 {
+        return this._startIndex;
+    }
+
+    /**
+     * @method setLength
+     * @description Sets the length of the array.
+     * @param {u64} newLength - The new length to set.
+     */
+    public setLength(newLength: u64): void {
+        if (newLength > this.MAX_LENGTH) {
+            throw new Revert('SetLength operation failed: Length exceeds maximum allowed value.');
+        }
+
+        if (newLength < this._length) {
+            // Truncate the array if newLength is smaller
+            for (let i: u64 = newLength; i < this._length; i++) {
+                this.delete(i);
+            }
+        }
+
+        this._length = newLength;
+        this._isChangedLength = true;
+    }
+
+    /**
+     * @private
+     * @method ensureValues
+     * @description Loads and caches the u256 value from the specified storage slot.
+     * @param {u32} slotIndex - The index of the storage slot.
+     */
+    private ensureValues(slotIndex: u32): void {
+        if (!this._isLoaded.has(slotIndex)) {
+            const storagePointer = this.calculateStoragePointer(slotIndex);
+            const storedU256: u256 = Blockchain.getStorageAt(storagePointer, this.defaultValue);
+            this._values.set(slotIndex, storedU256);
+            this._isLoaded.add(slotIndex);
+        }
+    }
+
+    /**
+     * @private
+     * @method calculateStoragePointer
+     * @description Calculates the storage pointer for a given slot index by incrementing the base pointer.
+     * @param {u32} slotIndex - The index of the storage slot.
+     * @returns {u256} - The calculated storage pointer.
+     */
+    private calculateStoragePointer(slotIndex: u64): u256 {
+        // Each slot is identified by baseU256Pointer + slotIndex + 1
+        // Slot 0: baseU256Pointer + 1 (first element)
+        // Slot 1: baseU256Pointer + 2, etc.
+        return SafeMath.add(this.baseU256Pointer, u256.fromU64(slotIndex + 1));
+    }
+}

package/runtime/storage/StoredU64.ts

@@ -0,0 +1,179 @@
+import { MemorySlotPointer } from '../memory/MemorySlotPointer';
+import { Blockchain } from '../env';
+import { encodePointer } from '../math/abi';
+import { BytesWriter } from '../buffer/BytesWriter';
+import { u256 } from 'as-bignum/assembly';
+
+/**
+ * @class StoredU64
+ * @description Manages up to four u64 values within a single u256 storage slot.
+ */
+@final
+export class StoredU64 {
+    private readonly u256Pointer: u256;
+
+    // Internal cache for four u64 values: [lo1, lo2, hi1, hi2]
+    private _values: u64[] = [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 {MemorySlotPointer} subPointer - The sub-pointer for memory slot addressing.
+     * @param {u256} defaultValue - The default u256 value if storage is uninitialized.
+     */
+    constructor(
+        public pointer: u16,
+        public subPointer: MemorySlotPointer,
+        private defaultValue: u256,
+    ) {
+        const writer = new BytesWriter(32);
+        writer.writeU256(subPointer);
+
+        this.u256Pointer = encodePointer(pointer, writer.getBuffer());
+    }
+
+    /**
+     * @method get
+     * @description Retrieves the u64 value at the specified offset.
+     * @param {u8} index - The index (0 to 3) of the u64 value to retrieve.
+     * @returns {u64} - The u64 value at the specified index.
+     */
+    @inline
+    public get(index: u8): u64 {
+        assert(index < 4, 'Index out of bounds for StoredU64 (0-3)');
+        this.ensureValues();
+        return this._values[index];
+    }
+
+    /**
+     * @method set
+     * @description Sets the u64 value at the specified offset.
+     * @param {u8} index - The index (0 to 3) of the u64 value to set.
+     * @param {u64} value - The u64 value to assign.
+     */
+    @inline
+    public set(index: u8, value: u64): void {
+        assert(index < 4, 'Index out of bounds for StoredU64 (0-3)');
+        this.ensureValues();
+        if (this._values[index] != value) {
+            this._values[index] = value;
+            this.isChanged = true;
+        }
+    }
+
+    /**
+     * @method save
+     * @description Persists the cached u64 values to storage if any have been modified.
+     */
+    public save(): void {
+        if (this.isChanged) {
+            const packed = this.packValues();
+            Blockchain.setStorageAt(this.u256Pointer, packed);
+            this.isChanged = false;
+        }
+    }
+
+    /**
+     * @method setMultiple
+     * @description Sets multiple u64 values at once.
+     * @param {[u64, u64, u64, u64]} values - An array of four u64 values to set.
+     */
+    @inline
+    public setMultiple(values: u64[]): void {
+        this.ensureValues();
+        let changed = false;
+        for (let i: u8 = 0; i < 4; i++) {
+            if (this._values[i] != values[i]) {
+                this._values[i] = values[i];
+                changed = true;
+            }
+        }
+        if (changed) {
+            this.isChanged = true;
+        }
+    }
+
+    /**
+     * @method getAll
+     * @description Retrieves all four u64 values as a tuple.
+     * @returns {[u64, u64, u64, u64]} - A tuple containing all four u64 values.
+     */
+    @inline
+    public getAll(): u64[] {
+        this.ensureValues();
+        return this._values;
+    }
+
+    /**
+     * @method toString
+     * @description Returns a string representation of all four u64 values.
+     * @returns {string} - A string in the format "[value0, value1, value2, value3]".
+     */
+    @inline
+    public toString(): string {
+        this.ensureValues();
+        return `[${this._values[0].toString()}, ${this._values[1].toString()}, ${this._values[2].toString()}, ${this._values[3].toString()}]`;
+    }
+
+    /**
+     * @method toBytes
+     * @description Returns the packed u256 value as a byte array.
+     * @returns {Uint8Array} - The packed u256 value in byte form.
+     */
+    @inline
+    public toBytes(): u8[] {
+        this.ensureValues();
+        const packed = this.packValues();
+        return packed.toBytes();
+    }
+
+    /**
+     * @method reset
+     * @description Resets the cached values to default and marks as changed.
+     */
+    @inline
+    public reset(): void {
+        this._values = [0, 0, 0, 0];
+        this.isChanged = true;
+    }
+
+    /**
+     * @private
+     * @method ensureValues
+     * @description Loads and unpacks the u256 value from storage into four u64 cache variables.
+     */
+    private ensureValues(): void {
+        if (!this.isLoaded) {
+            const storedU256: u256 = Blockchain.getStorageAt(this.u256Pointer, this.defaultValue);
+
+            // Unpack the stored u256 into four u64s
+            this._values[0] = storedU256.lo1;
+            this._values[1] = storedU256.lo2;
+            this._values[2] = storedU256.hi1;
+            this._values[3] = storedU256.hi2;
+
+            this.isLoaded = true;
+        }
+    }
+
+    /**
+     * @private
+     * @method packValues
+     * @description Packs the four cached u64 values into a single u256 for storage.
+     * @returns {u256} - The packed u256 value.
+     */
+    private packValues(): u256 {
+        return new u256(
+            this._values[0], // lo1
+            this._values[1], // lo2
+            this._values[2], // hi1
+            this._values[3], // hi2
+        );
+    }
+}

package/runtime/types/SafeMath.ts

@@ -1,4 +1,4 @@
-import { u256 } from 'as-bignum/assembly';
+import { u128, u256 } from 'as-bignum/assembly';
 
 export class SafeMath {
     public static ZERO: u256 = u256.fromU32(0);
@@ -11,6 +11,23 @@ export class SafeMath {
         return c;
     }
 
+    public static add128(a: u128, b: u128): u128 {
+        const c: u128 = u128.add(a, b);
+        if (c < a) {
+            throw new Error('SafeMath: addition overflow');
+        }
+        return c;
+    }
+
+    public static add64(a: u64, b: u64): u64 {
+        const c: u64 = a + b;
+
+        if (c < a) {
+            throw new Error('SafeMath: addition overflow');
+        }
+        return c;
+    }
+
     public static sub(a: u256, b: u256): u256 {
         if (a < b) {
             throw new Error('SafeMath: subtraction overflow');
@@ -19,6 +36,22 @@ export class SafeMath {
         return u256.sub(a, b);
     }
 
+    public static sub128(a: u128, b: u128): u128 {
+        if (a < b) {
+            throw new Error('SafeMath: subtraction overflow');
+        }
+
+        return u128.sub(a, b);
+    }
+
+    public static sub64(a: u64, b: u64): u64 {
+        if (a < b) {
+            throw new Error('SafeMath: subtraction overflow');
+        }
+
+        return a - b;
+    }
+
     // Computes (a * b) % modulus with full precision
     public static mulmod(a: u256, b: u256, modulus: u256): u256 {
         if (u256.eq(modulus, u256.Zero)) throw new Error('SafeMath: modulo by zero');
@@ -91,6 +124,56 @@ export class SafeMath {
         return c;
     }
 
+    public static mul128(a: u128, b: u128): u128 {
+        if (a === u128.Zero || b === u128.Zero) {
+            return u128.Zero;
+        }
+
+        const c: u128 = u128.mul(a, b);
+        const d: u128 = SafeMath.div128(c, a);
+
+        if (u128.ne(d, b)) {
+            throw new Error('SafeMath: multiplication overflow');
+        }
+
+        return c;
+    }
+
+    public static div128(a: u128, b: u128): u128 {
+        if (b.isZero()) {
+            throw new Error('Division by zero');
+        }
+
+        if (a.isZero()) {
+            return new u128();
+        }
+
+        if (u128.lt(a, b)) {
+            return new u128(); // Return 0 if a < b
+        }
+
+        if (u128.eq(a, b)) {
+            return new u128(1); // Return 1 if a == b
+        }
+
+        let n = a.clone();
+        let d = b.clone();
+        let result = new u128();
+
+        const shift = u128.clz(d) - u128.clz(n);
+        d = SafeMath.shl128(d, shift); // align d with n by shifting left
+
+        for (let i = shift; i >= 0; i--) {
+            if (u128.ge(n, d)) {
+                n = u128.sub(n, d);
+                result = u128.or(result, SafeMath.shl128(u128.One, i));
+            }
+            d = u128.shr(d, 1); // restore d to original by shifting right
+        }
+
+        return result;
+    }
+
     @unsafe
     @operator('/')
     public static div(a: u256, b: u256): u256 {
@@ -199,6 +282,41 @@ export class SafeMath {
         return new u256(result[0], result[1], result[2], result[3]);
     }
 
+    public static shl128(value: u128, shift: i32): u128 {
+        if (shift == 0) {
+            return value.clone();
+        }
+
+        const totalBits = 256;
+        const bitsPerSegment = 64;
+
+        // Normalize shift to be within 0-255 range
+        shift &= 255;
+
+        if (shift >= totalBits) {
+            return new u128(); // Shift size larger than width results in zero
+        }
+
+        // Determine how many full 64-bit segments we are shifting
+        const segmentShift = (shift / bitsPerSegment) | 0;
+        const bitShift = shift % bitsPerSegment;
+
+        const segments = [value.lo, value.hi];
+
+        const result = new Array<u64>(2).fill(0);
+
+        for (let i = 0; i < segments.length; i++) {
+            if (i + segmentShift < segments.length) {
+                result[i + segmentShift] |= segments[i] << bitShift;
+            }
+            if (bitShift != 0 && i + segmentShift + 1 < segments.length) {
+                result[i + segmentShift + 1] |= segments[i] >>> (bitsPerSegment - bitShift);
+            }
+        }
+
+        return new u128(result[0], result[1]);
+    }
+
     public static and(a: u256, b: u256): u256 {
         return u256.and(a, b);
     }