@btc-vision/btc-runtime 1.6.0 → 1.6.2

package/runtime/storage/arrays/StoredAddressArray.ts

@@ -1,298 +1,39 @@
-import { BytesWriter } from '../../buffer/BytesWriter';
-import { Blockchain } from '../../env';
-import {
-    addUint8ArraysBE,
-    bigEndianAdd,
-    encodeBasePointer,
-    readLengthAndStartIndex,
-    u64ToBE32Bytes,
-} from '../../math/bytes';
+import { DEFAULT_MAX_LENGTH, StoredPackedArray } from './StoredPackedArray';
+import { bigEndianAdd } from '../../math/bytes';
 import { Address } from '../../types/Address';
-import { Revert } from '../../types/Revert';
 
 /**
- * @class StoredAddressArray
- * @description Manages an array of Address values across multiple storage slots.
- * Each slot holds one Address (stored as a raw Uint8Array in storage).
+ * StoredAddressArray
+ *
+ * Array of addresses.
  */
 @final
-export class StoredAddressArray {
-    private readonly baseU256Pointer: Uint8Array;
-    private readonly lengthPointer: Uint8Array;
-
-    private _values: Map<u64, Address> = new Map(); // slotIndex -> Address
-    private _isChanged: Set<u64> = new Set(); // track changed slotIndexes
-
-    private _length: u64 = 0;
-    private _startIndex: u64 = 0;
-    private _isChangedLength: bool = false;
-    private _isChangedStartIndex: bool = false;
-
-    private readonly MAX_LENGTH: u64 = u64(u32.MAX_VALUE - 1);
-
-    private readonly defaultValue: Address = Address.zero();
-
-    /**
-     * @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. (AddressArray, got ${subPointer.length})`,
-        );
-
-        const basePointer = encodeBasePointer(pointer, subPointer);
-        this.lengthPointer = Uint8Array.wrap(basePointer.buffer);
-        this.baseU256Pointer = bigEndianAdd(basePointer, 1);
-
-        const storedLenStart = Blockchain.getStorageAt(basePointer);
-        const data = readLengthAndStartIndex(storedLenStart);
-
-        this._length = data[0];
-        this._startIndex = data[1];
-    }
-
-    @inline
-    public has(index: u64): bool {
-        return index < this._length;
-    }
-
-    /** Get an element by its global index. */
-    @inline
-    @operator('[]')
-    public get(index: u64): Address {
-        if (index >= this._length) {
-            throw new Revert('get: index out of range (address array)');
-        }
-
-        const physicalIndex = (this._startIndex + index) % this.MAX_LENGTH;
-        const slotIndex: u32 = <u32>physicalIndex;
-        this.ensureValues(slotIndex);
-
-        return this._values.get(slotIndex);
+export class StoredAddressArray extends StoredPackedArray<Address> {
+    public constructor(pointer: u16, subPointer: Uint8Array, maxLength: u32 = DEFAULT_MAX_LENGTH) {
+        super(pointer, subPointer, Address.zero(), maxLength);
     }
 
-    /** Set an element by its global index. */
-    @inline
-    @operator('[]=')
-    public set(index: u64, value: Address): void {
-        if (index >= this._length) {
-            throw new Revert('set: index out of range (address array)');
-        }
-
-        const physicalIndex = (this._startIndex + index) % this.MAX_LENGTH;
-        const slotIndex: u32 = <u32>physicalIndex;
-        this.ensureValues(slotIndex);
-
-        const currentValue = this._values.get(slotIndex);
-        if (currentValue != value) {
-            this._values.set(slotIndex, value);
-            this._isChanged.add(slotIndex);
-        }
+    protected getSlotCapacity(): u32 {
+        return 1; // 1 x u256 => 32 bytes
     }
 
-    /** Append an address at the end of the array. */
-    @inline
-    public push(value: Address): void {
-        if (this._length >= this.MAX_LENGTH) {
-            throw new Revert('push: array reached maximum length (address array)');
-        }
-
-        const newLogicalIndex: u64 = this._length;
-        const physicalIndex: u64 = (this._startIndex + newLogicalIndex) % this.MAX_LENGTH;
-        const slotIndex: u32 = <u32>physicalIndex;
-
-        this.ensureValues(slotIndex);
-        this._values.set(slotIndex, value);
-        this._isChanged.add(slotIndex);
-
-        this._length += 1;
-        this._isChangedLength = true;
+    protected zeroValue(): Address {
+        return Address.zero();
     }
 
-    /** Delete the last element. */
-    public deleteLast(): void {
-        if (this._length === 0) {
-            throw new Revert('deleteLast: array is empty (address array)');
-        }
-
-        const lastLogicalIndex: u64 = this._length - 1;
-        const physicalIndex: u64 = (this._startIndex + lastLogicalIndex) % this.MAX_LENGTH;
-        const slotIndex: u32 = <u32>physicalIndex;
-        this.ensureValues(slotIndex);
-
-        const currentValue = this._values.get(slotIndex);
-        if (currentValue != this.defaultValue) {
-            this._values.set(slotIndex, this.defaultValue);
-            this._isChanged.add(slotIndex);
-        }
-
-        this._length -= 1;
-        this._isChangedLength = true;
+    protected eq(a: Address, b: Address): bool {
+        return a == b;
     }
 
-    /** Adjust the starting index. */
-    public setStartingIndex(index: u64): void {
-        this._startIndex = index;
-        this._isChangedStartIndex = true;
+    protected packSlot(values: Address[]): Uint8Array {
+        return values[0];
     }
 
-    /** Delete a specific element by setting it to `defaultValue`. */
-    @inline
-    public delete(index: u64): void {
-        if (index > this.MAX_LENGTH) {
-            throw new Revert('delete: index out of range (address array)');
-        }
-
-        const physicalIndex: u64 = (this._startIndex + index) % this.MAX_LENGTH;
-        const slotIndex: u32 = <u32>physicalIndex;
-        this.ensureValues(slotIndex);
-
-        const currentValue = this._values.get(slotIndex);
-        if (currentValue != this.defaultValue) {
-            this._values.set(slotIndex, this.defaultValue);
-            this._isChanged.add(slotIndex);
-        }
+    protected unpackSlot(slotData: Uint8Array): Address[] {
+        return [Address.fromUint8Array(slotData)];
     }
 
-    /**
-     * Persist changes to storage.
-     *  - Store any changed slotIndex -> Address
-     *  - Store updated length and startIndex if changed
-     */
-    @inline
-    public save(): void {
-        // 1) Save 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();
-
-        // 2) Save length and startIndex if changed
-        if (this._isChangedLength || this._isChangedStartIndex) {
-            const writer = new BytesWriter(16);
-            writer.writeU64(this._length);
-            writer.writeU64(this._startIndex);
-
-            Blockchain.setStorageAt(this.lengthPointer, writer.getBuffer());
-            this._isChangedLength = false;
-            this._isChangedStartIndex = false;
-        }
-    }
-
-    /** Clear entire array content from storage, reset length and startIndex. */
-    public deleteAll(): void {
-        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, this.defaultValue);
-        }
-
-        Blockchain.setStorageAt(this.lengthPointer, new Uint8Array(32));
-
-        this._length = 0;
-        this._startIndex = 0;
-        this._isChangedLength = false;
-        this._isChangedStartIndex = false;
-
-        this._values.clear();
-        this._isChanged.clear();
-    }
-
-    /** Bulk-set multiple addresses starting at `startIndex`. */
-    @inline
-    public setMultiple(startIndex: u32, values: Address[]): void {
-        for (let i: u32 = 0; i < values.length; i++) {
-            this.set(<u64>(startIndex + i), values[i]);
-        }
-    }
-
-    /** Retrieve a batch of addresses (range). */
-    @inline
-    public getAll(startIndex: u32, count: u32): Address[] {
-        if (startIndex + count > this._length) {
-            throw new Revert('getAll: index out of range (address array)');
-        }
-
-        const result = new Array<Address>(count);
-        for (let i: u32 = 0; i < count; i++) {
-            result[i] = this.get(<u64>(startIndex + i));
-        }
-        return result;
-    }
-
-    /** Returns a string of the form "[addr0, addr1, ...]". */
-    @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;
-    }
-
-    /** Reset in-memory and persist. */
-    @inline
-    public reset(): void {
-        this._length = 0;
-        this._startIndex = 0;
-        this._isChangedLength = true;
-        this._isChangedStartIndex = true;
-
-        this._values.clear();
-        this._isChanged.clear();
-
-        this.save();
-    }
-
-    /** Current array length. */
-    @inline
-    public getLength(): u64 {
-        return this._length;
-    }
-
-    /** Current starting index. */
-    public startingIndex(): u64 {
-        return this._startIndex;
-    }
-
-    /**
-     * Ensure the given slot index is loaded into `_values`.
-     */
-    private ensureValues(slotIndex: u32): void {
-        if (!this._values.has(slotIndex)) {
-            const storagePointer = this.calculateStoragePointer(slotIndex);
-
-            // Load raw bytes from storage
-            const stored: Uint8Array = Blockchain.getStorageAt(storagePointer);
-
-            const storedAddress: Address =
-                stored.length == 0 ? this.defaultValue : Address.fromUint8Array(stored);
-
-            this._values.set(slotIndex, storedAddress);
-        }
-    }
-
-    /**
-     * Compute a 32-byte storage pointer = basePointer + (slotIndex + 1) big-endian.
-     */
-    private calculateStoragePointer(slotIndex: u64): Uint8Array {
-        // Convert (slotIndex) to a 32-byte big-endian offset
-        const offset = u64ToBE32Bytes(slotIndex);
-
-        return addUint8ArraysBE(this.baseU256Pointer, offset);
+    protected calculateStoragePointer(slotIndex: u64): Uint8Array {
+        return bigEndianAdd(this.basePointer, slotIndex);
     }
 }

package/runtime/storage/arrays/StoredBooleanArray.ts

@@ -1,6 +1,6 @@
-import { BytesWriter } from '../../buffer/BytesWriter';
-import { Blockchain } from '../../env';
-import { Revert } from '../../types/Revert';
+import {BytesWriter} from '../../buffer/BytesWriter';
+import {Blockchain} from '../../env';
+import {Revert} from '../../types/Revert';
 import {
     addUint8ArraysBE,
     bigEndianAdd,
@@ -11,6 +11,7 @@ import {
     setBit,
     u64ToBE32Bytes,
 } from '../../math/bytes';
+import {DEFAULT_MAX_LENGTH} from './StoredPackedArray';
 
 /**
  * @class StoredBooleanArray
@@ -21,34 +22,40 @@ import {
  *  - slot 0 stores indexes [0..255]
  *  - slot 1 stores indexes [256..511]
  *  - ...
+ *  Note: This is designed to wrap around.
  */
 @final
 export class StoredBooleanArray {
     private readonly basePointer: Uint8Array;
     private readonly lengthPointer: Uint8Array;
 
-    private _values: Map<u64, Uint8Array> = new Map();
-    private _isChanged: Set<u64> = new Set();
+    private _values: Map<u32, Uint8Array> = new Map();
+    private _isChanged: Set<u32> = new Set();
 
-    private _length: u64 = 0;
-    private _startIndex: u64 = 0;
+    private _length: u32 = 0;
+    private _startIndex: u32 = 0;
     private _isChangedLength: bool = false;
     private _isChangedStartIndex: bool = false;
 
-    private readonly MAX_LENGTH: u64 = u32.MAX_VALUE;
+    private nextItemOffset: u32 = 0;
 
     /**
      * @constructor
      * @param {u16} pointer       - The primary pointer identifier.
      * @param {Uint8Array} subPtr - The sub-pointer for memory slot addressing.
+     * @param {u32} [MAX_LENGTH=DEFAULT_MAX_LENGTH] - The maximum length of the array.
      *
      * The code below treats the first 16 bytes of `lengthPointer` as storing [length, startIndex].
      */
     constructor(
         public pointer: u16,
         public subPtr: Uint8Array,
+        protected MAX_LENGTH: u32 = DEFAULT_MAX_LENGTH,
     ) {
-        assert(subPtr.length <= 30, `You must pass a 30 bytes sub-pointer. (StoredBooleanArray, got ${subPtr.length})`);
+        assert(
+            subPtr.length <= 30,
+            `You must pass a 30 bytes sub-pointer. (StoredBooleanArray, got ${subPtr.length})`,
+        );
 
         const basePointer = encodeBasePointer(pointer, subPtr);
         this.lengthPointer = Uint8Array.wrap(basePointer.buffer);
@@ -61,28 +68,81 @@ export class StoredBooleanArray {
         this._startIndex = data[1];
     }
 
-    // -------------- Public Accessors -------------- //
+    @inline
+    public get previousOffset(): u32 {
+        return <u32>(
+            ((this._startIndex +
+                    <u64>(this.nextItemOffset === 0 ? this.nextItemOffset : this.nextItemOffset - 1)) %
+                this.MAX_LENGTH)
+        );
+    }
 
+    /**
+     * Set the maximum length of the array.
+     * This is a safety check to prevent unbounded usage.
+     */
     @inline
-    public has(index: u64): bool {
+    public setMaxLength(maxLength: u32): void {
+        if (maxLength > this.MAX_LENGTH) {
+            throw new Revert('setMaxLength: maxLength exceeds MAX_LENGTH');
+        }
+
+        this.MAX_LENGTH = maxLength;
+    }
+
+    @inline
+    public has(index: u32): bool {
         return index < this._length;
     }
 
+    /**
+     * Get the next item in the array, starting from the current offset.
+     * This is useful for iterating through the array.
+     */
+    @inline
+    public next(): bool {
+        const value = this.get(this.nextItemOffset);
+        this.nextItemOffset += 1;
+
+        return value;
+    }
+
+    /**
+     * Apply the starting index with n offset.
+     */
+    @inline
+    public applyNextOffsetToStartingIndex(): void {
+        if (!this.nextItemOffset) return;
+
+        this._startIndex += this.nextItemOffset - 1;
+        this._isChangedStartIndex = true;
+        this.nextItemOffset = 0;
+    }
+
+    @inline
+    public incrementStartingIndex(): void {
+        if (this._startIndex >= this.MAX_LENGTH) {
+            this._startIndex = 0;
+        } else {
+            this._startIndex += 1;
+        }
+
+        this._isChangedStartIndex = true;
+    }
+
     /**
      * Retrieve boolean at `index`.
      */
     @operator('[]')
     @inline
-    public get(index: u64): bool {
+    public get(index: u32): bool {
         if (index >= this._length) {
-            throw new Revert(`get: index out of range (${index} >= ${this._length}, boolean array)`);
+            throw new Revert(
+                `get: index out of range (${index} >= ${this._length}, boolean array)`,
+            );
         }
 
-        const effectiveIndex = this._startIndex + index;
-        const wrappedIndex = effectiveIndex < this.MAX_LENGTH
-            ? effectiveIndex
-            : effectiveIndex % this.MAX_LENGTH;
-
+        const wrappedIndex = this.getRealIndex(index);
         const slotIndex = wrappedIndex / 256;
         const bitIndex = <u16>(wrappedIndex % 256);
 
@@ -97,16 +157,14 @@ export class StoredBooleanArray {
      */
     @operator('[]=')
     @inline
-    public set(index: u64, value: bool): void {
+    public set(index: u32, value: bool): void {
         if (index >= this._length) {
-            throw new Revert(`set: index out of range (${index} >= ${this._length}, boolean array)`);
+            throw new Revert(
+                `set: index out of range (${index} >= ${this._length}, boolean array)`,
+            );
         }
 
-        const effectiveIndex = this._startIndex + index;
-        const wrappedIndex = effectiveIndex < this.MAX_LENGTH
-            ? effectiveIndex
-            : effectiveIndex % this.MAX_LENGTH;
-
+        const wrappedIndex = this.getRealIndex(index);
         const slotIndex = wrappedIndex / 256;
         const bitIndex = <u16>(wrappedIndex % 256);
 
@@ -126,17 +184,12 @@ export class StoredBooleanArray {
      * Push a new boolean at the "end" of the array.
      */
     @inline
-    public push(value: bool): void {
+    public push(value: bool): u32 {
         if (this._length >= this.MAX_LENGTH) {
             throw new Revert('push: reached max allowed length (boolean array)');
         }
 
-        const newIndex = this._length;
-        const effectiveIndex = this._startIndex + newIndex;
-        const wrappedIndex = effectiveIndex < this.MAX_LENGTH
-            ? effectiveIndex
-            : effectiveIndex % this.MAX_LENGTH;
-
+        const wrappedIndex = this.getRealIndex(this._length);
         const slotIndex = wrappedIndex / 256;
         const bitIndex = <u16>(wrappedIndex % 256);
 
@@ -150,22 +203,20 @@ export class StoredBooleanArray {
 
         this._length += 1;
         this._isChangedLength = true;
+
+        return wrappedIndex;
     }
 
     /**
      * Delete the boolean at `index` by setting it to false.
      */
     @inline
-    public delete(index: u64): void {
+    public delete(index: u32): void {
         if (index >= this._length) {
             throw new Revert('delete: index out of range (boolean array)');
         }
 
-        const effectiveIndex = this._startIndex + index;
-        const wrappedIndex = effectiveIndex < this.MAX_LENGTH
-            ? effectiveIndex
-            : effectiveIndex % this.MAX_LENGTH;
-
+        const wrappedIndex = this.getRealIndex(index);
         const slotIndex = wrappedIndex / 256;
         const bitIndex = <u16>(wrappedIndex % 256);
 
@@ -181,6 +232,16 @@ export class StoredBooleanArray {
         }
     }
 
+    @inline
+    public removeItemFromLength(): void {
+        if (this._length == 0) {
+            throw new Revert('delete: array is empty');
+        }
+
+        this._length -= 1;
+        this._isChangedLength = true;
+    }
+
     /**
      * Remove the last element by setting it false and decrementing length.
      */
@@ -212,11 +273,10 @@ export class StoredBooleanArray {
 
         this._isChanged.clear();
 
-        // 2) If length or startIndex changed, store them
         if (this._isChangedLength || this._isChangedStartIndex) {
             const w = new BytesWriter(32);
-            w.writeU64(this._length);
-            w.writeU64(this._startIndex);
+            w.writeU32(this._length);
+            w.writeU32(this._startIndex);
 
             const data = w.getBuffer();
             Blockchain.setStorageAt(this.lengthPointer, data);
@@ -255,8 +315,8 @@ export class StoredBooleanArray {
      * Set multiple bools starting at `startIndex`.
      */
     @inline
-    public setMultiple(startIndex: u64, values: bool[]): void {
-        for (let i: u64 = 0; i < values.length; i++) {
+    public setMultiple(startIndex: u32, values: bool[]): void {
+        for (let i: u32 = 0; i < values.length; i++) {
             this.set(startIndex + i, values[i]);
         }
     }
@@ -265,17 +325,17 @@ export class StoredBooleanArray {
      * Retrieve a batch of bools.
      */
     @inline
-    public getAll(start: u64, count: u64): bool[] {
+    public getAll(start: u32, count: u32): bool[] {
         if (start + count > this._length) {
             throw new Revert('getAll: range exceeds array length (boolean array)');
         }
 
-        if (count > u64(u32.MAX_VALUE)) {
+        if (count > u32(u32.MAX_VALUE)) {
             throw new Revert('getAll: range exceeds max allowed (boolean array)');
         }
 
         const result = new Array<bool>(<i32>count);
-        for (let i: u64 = 0; i < count; i++) {
+        for (let i: u32 = 0; i < count; i++) {
             result[<i32>i] = this.get(start + i);
         }
 
@@ -288,7 +348,7 @@ export class StoredBooleanArray {
     @inline
     public toString(): string {
         let s = '[';
-        for (let i: u64 = 0; i < this._length; i++) {
+        for (let i: u32 = 0; i < this._length; i++) {
             s += this.get(i).toString();
             if (i < this._length - 1) {
                 s += ', ';
@@ -318,12 +378,12 @@ export class StoredBooleanArray {
      * Current array length (number of booleans stored).
      */
     @inline
-    public getLength(): u64 {
+    public getLength(): u32 {
         return this._length;
     }
 
     @inline
-    public setStartingIndex(index: u64): void {
+    public setStartingIndex(index: u32): void {
         this._startIndex = index;
         this._isChangedStartIndex = true;
     }
@@ -332,14 +392,24 @@ export class StoredBooleanArray {
      * Current starting index for the array.
      */
     @inline
-    public startingIndex(): u64 {
+    public startingIndex(): u32 {
         return this._startIndex;
     }
 
+    private getRealIndex(index: u32): u32 {
+        const maxLength: u64 = <u64>this.MAX_LENGTH;
+        let realIndex: u64 = <u64>this._startIndex + <u64>index;
+        if (!(realIndex < maxLength)) {
+            realIndex %= maxLength;
+        }
+
+        return <u32>realIndex;
+    }
+
     /**
      * Ensure the 32-byte slot for `slotIndex` is loaded into _values.
      */
-    private ensureSlotLoaded(slotIndex: u64): void {
+    private ensureSlotLoaded(slotIndex: u32): void {
         if (!this._values.has(slotIndex)) {
             const pointer = this.calculateStoragePointer(slotIndex);
             const stored = Blockchain.getStorageAt(pointer);
@@ -350,7 +420,7 @@ export class StoredBooleanArray {
     /**
      * Convert `slotIndex` -> pointer = basePointer + (slotIndex + 1), as big-endian addition.
      */
-    private calculateStoragePointer(slotIndex: u64): Uint8Array {
+    private calculateStoragePointer(slotIndex: u32): Uint8Array {
         const offset = u64ToBE32Bytes(slotIndex);
         return addUint8ArraysBE(this.basePointer, offset);
     }