@btc-vision/btc-runtime 1.3.9 → 1.3.10

package/runtime/storage/StoredU256Array.ts

@@ -1,136 +1,229 @@
-import { MemorySlotPointer } from '../memory/MemorySlotPointer';
+import { u256 } from 'as-bignum/assembly';
 import { Blockchain } from '../env';
-import { encodePointer } from '../math/abi';
 import { BytesWriter } from '../buffer/BytesWriter';
-import { u256 } from 'as-bignum/assembly';
 import { SafeMath } from '../types/SafeMath';
+import { Revert } from '../types/Revert';
 
 /**
  * @class StoredU256Array
- * @description Manages an array of u256 values across multiple u256 storage slots. Each u256 slot holds one u256 value.
+ * @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 multiple storage slots, each holding one u256 value
-    private _values: Array<u256> = []; // Each element is a u256 value
-    private _isLoaded: Array<bool> = []; // Indicates if the corresponding slot is loaded
-    private _isChanged: Array<bool> = []; // Indicates if the corresponding slot has been modified
+    // 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 management
-    private _length: u16 = 0; // Current length of the array
+    // 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 {MemorySlotPointer} subPointer - The sub-pointer for memory slot addressing.
+     * @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: MemorySlotPointer,
+        public subPointer: Uint8Array,
         private defaultValue: u256,
     ) {
         // Initialize the base u256 pointer using the primary pointer and subPointer
         const writer = new BytesWriter(32);
-        writer.writeU256(subPointer);
-        this.baseU256Pointer = encodePointer(pointer, writer.getBuffer());
+        writer.writeU16(pointer);
+        writer.writeBytes(subPointer);
 
-        // Initialize the length pointer by incrementing the base pointer by 1
-        this.lengthPointer = SafeMath.add(this.baseU256Pointer, u256.One);
+        // Initialize the base and length pointers
+        const baseU256Pointer = u256.fromBytes(writer.getBuffer(), true);
+        const lengthPointer = baseU256Pointer.clone();
 
-        // Load the current length from storage
-        const storedLength: u256 = Blockchain.getStorageAt(this.lengthPointer, u256.Zero);
-        this._length = u16(storedLength.toU32());
+        // Load the current length and startIndex from storage
+        const storedLengthAndStartIndex: u256 = Blockchain.getStorageAt(lengthPointer, u256.Zero);
+        this.lengthPointer = lengthPointer;
+        this.baseU256Pointer = baseU256Pointer;
 
-        // Optionally, you can preload values based on the initial length
-        for (let i: u32 = 0; i < this._length; i++) {
-            this.ensureValues(i);
-        }
+        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 {u32} index - The global index (0 to ∞) of the u256 value to retrieve.
+     * @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: u32): u256 {
-        const slotIndex: u32 = index; // Each slot holds one u256
+    public get(index: u64): u256 {
+        assert(index < this._length, 'Index out of bounds');
+        const slotIndex: u32 = <u32>index;
         this.ensureValues(slotIndex);
-        return this._values[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 {u32} index - The global index (0 to ∞) of the u256 value to set.
+     * @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: u32, value: u256): void {
-        const slotIndex: u32 = index;
+    public set(index: u64, value: u256): void {
+        assert(index < this._length, 'Index exceeds current array length');
+        const slotIndex: u32 = <u32>index;
         this.ensureValues(slotIndex);
 
-        if (!u256.eq(this._values[slotIndex], value)) {
-            this._values[slotIndex] = value;
-            this._isChanged[slotIndex] = true;
+        const currentValue = this._values.get(slotIndex);
+        if (!u256.eq(currentValue, value)) {
+            this._values.set(slotIndex, value);
+            this._isChanged.add(slotIndex);
+        }
+    }
 
-            // Update length if setting a new index beyond current length
-            if (index >= this._length) {
-                this._length = u16(index + 1);
-                this._isChangedLength = true;
-            }
+    /**
+     * @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 and the length to their respective storage slots if any have been modified.
+     * @description Persists all cached u256 values, the length, and the startIndex to their respective storage slots if any have been modified.
      */
     public save(): void {
-        const max: u32 = this._values.length;
-
-        for (let slotIndex: u32 = 0; slotIndex < max; slotIndex++) {
-            if (this._isChanged[slotIndex]) {
-                const packed = this.packValues(slotIndex);
-                const storagePointer = this.calculateStoragePointer(slotIndex);
-                Blockchain.setStorageAt(storagePointer, packed);
-                this._isChanged[slotIndex] = false;
-            }
+        // 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);
         }
-
-        if (this._isChangedLength) {
-            const lengthU256 = u256.from(this._length);
-            Blockchain.setStorageAt(this.lengthPointer, lengthU256);
+        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 delete
-     * @description Deletes all storage slots by setting them to zero, including the length slot.
+     * @method deleteAll
+     * @description Deletes all storage slots by setting them to zero, including the length and startIndex slots.
      */
-    public delete(): void {
-        const max: u32 = this._values.length;
-        for (let slotIndex: u32 = 0; slotIndex < max; slotIndex++) {
+    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 to zero
-        Blockchain.setStorageAt(this.lengthPointer, 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 = [];
-        this._isLoaded = [];
-        this._isChanged = [];
+        this._values.clear();
+        this._isLoaded.clear();
+        this._isChanged.clear();
     }
 
     /**
@@ -142,7 +235,7 @@ export class StoredU256Array {
     @inline
     public setMultiple(startIndex: u32, values: u256[]): void {
         for (let i: u32 = 0; i < values.length; i++) {
-            this.set(startIndex + i, values[i]);
+            this.set(<u64>(startIndex + i), values[i]);
         }
     }
 
@@ -155,9 +248,10 @@ export class StoredU256Array {
      */
     @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(startIndex + i);
+            result[i] = this.get(<u64>(startIndex + i));
         }
         return result;
     }
@@ -170,10 +264,10 @@ export class StoredU256Array {
     @inline
     public toString(): string {
         let str = '[';
-        for (let slotIndex: u32 = 0; slotIndex < this._values.length; slotIndex++) {
-            const value = this._values[slotIndex];
+        for (let i: u32 = 0; i < this._length; i++) {
+            const value = this.get(<u64>i);
             str += value.toString();
-            if (slotIndex !== this._values.length - 1) {
+            if (i !== this._length - 1) {
                 str += ', ';
             }
         }
@@ -189,11 +283,14 @@ export class StoredU256Array {
     @inline
     public toBytes(): u8[] {
         const bytes: u8[] = new Array<u8>();
-        for (let slotIndex: u32 = 0; slotIndex < this._values.length; slotIndex++) {
-            const packed = this.packValues(slotIndex);
-            const slotBytes = packed.toBytes();
-            for (let i: u32 = 0; i < slotBytes.length; i++) {
-                bytes.push(slotBytes[i]);
+        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;
@@ -201,38 +298,53 @@ export class StoredU256Array {
 
     /**
      * @method reset
-     * @description Resets all cached u256 values to zero and marks them as changed, including resetting the length.
+     * @description Resets all cached u256 values to zero and marks them as changed, including resetting the length and startIndex.
      */
     @inline
     public reset(): void {
-        for (let slotIndex: u32 = 0; slotIndex < this._values.length; slotIndex++) {
-            this._values[slotIndex] = u256.Zero;
-            this._isChanged[slotIndex] = true;
-        }
-
-        // Reset the length to zero
+        // 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 {u16} - The current length.
+     * @returns {u64} - The current length.
      */
     @inline
-    public getLength(): u16 {
+    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 {u16} newLength - The new length to set.
+     * @param {u64} newLength - The new length to set.
      */
-    public setLength(newLength: u16): void {
-        if (newLength > u16.MAX_VALUE) {
-            throw new Error('Length exceeds maximum allowed value.');
+    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;
@@ -246,55 +358,25 @@ export class StoredU256Array {
      * @param {u32} slotIndex - The index of the storage slot.
      */
     private ensureValues(slotIndex: u32): void {
-        // Initialize arrays if necessary
-        while (slotIndex >= <u32>this._isLoaded.length) {
-            this._isLoaded.push(false);
-            this._isChanged.push(false);
-            this._values.push(u256.Zero);
-        }
-
-        if (!this._isLoaded[slotIndex]) {
+        if (!this._isLoaded.has(slotIndex)) {
             const storagePointer = this.calculateStoragePointer(slotIndex);
             const storedU256: u256 = Blockchain.getStorageAt(storagePointer, this.defaultValue);
-            this._values[slotIndex] = this.unpackU256(storedU256);
-            this._isLoaded[slotIndex] = true;
+            this._values.set(slotIndex, storedU256);
+            this._isLoaded.add(slotIndex);
         }
     }
 
-    /**
-     * @private
-     * @method packValues
-     * @description Retrieves the cached u256 value for storage.
-     * @param {u32} slotIndex - The index of the storage slot.
-     * @returns {u256} - The packed u256 value.
-     */
-    private packValues(slotIndex: u32): u256 {
-        return this._values[slotIndex];
-    }
-
-    /**
-     * @private
-     * @method unpackU256
-     * @description Returns the u256 value as is since no unpacking is required.
-     * @param {u256} storedU256 - The u256 value to unpack.
-     * @returns {u256} - The unpacked u256 value.
-     */
-    private unpackU256(storedU256: u256): u256 {
-        return storedU256;
-    }
-
     /**
      * @private
      * @method calculateStoragePointer
-     * @description Calculates the storage pointer for a given slot index by incrementing the subpointer.
+     * @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: u32): u256 {
-        // Clone the subpointer to avoid mutating the original
-        const modifiedSubPointer = this.subPointer.clone();
-
-        // Increment the subpointer by slotIndex using SafeMath
-        return SafeMath.add(modifiedSubPointer, u256.fromU32(slotIndex));
+    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));
     }
 }