@btc-vision/btc-runtime 1.5.4 → 1.5.7

package/package.json

@@ -1,46 +1,46 @@
 {
-  "name": "@btc-vision/btc-runtime",
-  "version": "1.5.4",
-  "description": "Bitcoin Smart Contract Runtime",
-  "main": "btc/index.ts",
-  "scripts": {},
-  "types": "btc/index.ts",
-  "keywords": [
-    "bitcoin",
-    "smart",
-    "contract",
-    "runtime",
-    "opnet",
-    "OP_NET"
-  ],
-  "homepage": "https://opnet.org",
-  "author": "BlobMaster41",
-  "license": "MIT",
-  "devDependencies": {
-    "@types/node": "^22.13.10",
-    "assemblyscript": "^0.27.35"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/btc-vision/btc-runtime"
-  },
-  "type": "module",
-  "files": [
-    "package.json",
-    "runtime",
-    "runtime/*.ts",
-    "runtime/**/*.ts",
-    "!**/*.js.map",
-    "!**/*.tsbuildinfo",
-    "test/*.ts"
-  ],
-  "dependencies": {
-    "@assemblyscript/loader": "^0.27.35",
-    "@btc-vision/as-bignum": "^0.0.5",
-    "@eslint/js": "^9.22.0",
-    "gulplog": "^2.2.0",
-    "ts-node": "^10.9.2",
-    "typescript": "^5.8.2",
-    "typescript-eslint": "^8.26.1"
-  }
+    "name": "@btc-vision/btc-runtime",
+    "version": "1.5.7",
+    "description": "Bitcoin Smart Contract Runtime",
+    "main": "btc/index.ts",
+    "scripts": {},
+    "types": "btc/index.ts",
+    "keywords": [
+        "bitcoin",
+        "smart",
+        "contract",
+        "runtime",
+        "opnet",
+        "OP_NET"
+    ],
+    "homepage": "https://opnet.org",
+    "author": "BlobMaster41",
+    "license": "MIT",
+    "devDependencies": {
+        "@types/node": "^22.13.10",
+        "assemblyscript": "^0.27.35"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/btc-vision/btc-runtime"
+    },
+    "type": "module",
+    "files": [
+        "package.json",
+        "runtime",
+        "runtime/*.ts",
+        "runtime/**/*.ts",
+        "!**/*.js.map",
+        "!**/*.tsbuildinfo",
+        "test/*.ts"
+    ],
+    "dependencies": {
+        "@assemblyscript/loader": "^0.27.35",
+        "@btc-vision/as-bignum": "^0.0.5",
+        "@eslint/js": "^9.22.0",
+        "gulplog": "^2.2.0",
+        "ts-node": "^10.9.2",
+        "typescript": "^5.8.2",
+        "typescript-eslint": "^8.26.1"
+    }
 }

package/runtime/contracts/DeployableOP_20.ts

@@ -39,7 +39,7 @@ export abstract class DeployableOP_20 extends OP_NET implements IOP_20 {
 
     protected readonly _nonceMap: AddressMemoryMap;
 
-    protected constructor(params: OP20InitParameters | null = null) {
+    public constructor(params: OP20InitParameters | null = null) {
         super();
 
         // Initialize main storage structures

package/runtime/contracts/OP_20.ts

@@ -3,7 +3,7 @@ import { u256 } from '@btc-vision/as-bignum/assembly';
 import { OP20InitParameters } from './interfaces/OP20InitParameters';
 
 export abstract class OP_20 extends DeployableOP_20 {
-    protected constructor(maxSupply: u256, decimals: u8, name: string, symbol: string) {
+    public constructor(maxSupply: u256, decimals: u8, name: string, symbol: string) {
         super(new OP20InitParameters(maxSupply, decimals, name, symbol));
     }
 }

package/runtime/env/BlockchainEnvironment.ts

@@ -25,13 +25,10 @@ import { eqUint, MapUint8Array } from '../generic/MapUint8Array';
 import { EMPTY_BUFFER } from '../math/bytes';
 import { Plugin } from '../plugins/Plugin';
 import { Calldata } from '../types';
+import { Revert } from '../types/Revert';
 
 export * from '../env/global';
 
-export function runtimeError(msg: string): Error {
-    return new Error(`RuntimeException: ${msg}`);
-}
-
 @final
 export class BlockchainEnvironment {
     private static readonly MAX_U16: u16 = 65535;
@@ -47,7 +44,7 @@ export class BlockchainEnvironment {
     @inline
     public get block(): Block {
         if (!this._block) {
-            throw this.error('Block is required');
+            throw new Revert('Block is required');
         }
 
         return this._block as Block;
@@ -58,7 +55,7 @@ export class BlockchainEnvironment {
     @inline
     public get tx(): Transaction {
         if (!this._tx) {
-            throw this.error('Transaction is required');
+            throw new Revert('Transaction is required');
         }
 
         return this._tx as Transaction;
@@ -80,7 +77,7 @@ export class BlockchainEnvironment {
 
     public get nextPointer(): u16 {
         if (this._nextPointer === BlockchainEnvironment.MAX_U16) {
-            throw this.error(`Out of storage pointer.`);
+            throw new Revert(`Out of storage pointer.`);
         }
 
         this._nextPointer += 1;
@@ -92,7 +89,7 @@ export class BlockchainEnvironment {
 
     public get contractDeployer(): Address {
         if (!this._contractDeployer) {
-            throw this.error('Deployer is required');
+            throw new Revert('Deployer is required');
         }
 
         return this._contractDeployer as Address;
@@ -102,7 +99,7 @@ export class BlockchainEnvironment {
 
     public get contractAddress(): Address {
         if (!this._contractAddress) {
-            throw this.error('Contract address is required');
+            throw new Revert('Contract address is required');
         }
 
         return this._contractAddress as Address;
@@ -148,6 +145,7 @@ export class BlockchainEnvironment {
         const blockHash = reader.readBytes(32);
         const blockNumber = reader.readU64();
         const blockMedianTime = reader.readU64();
+        const txId = reader.readBytes(32);
         const txHash = reader.readBytes(32);
         const contractAddress = reader.readAddress();
         const contractDeployer = reader.readAddress();
@@ -157,6 +155,7 @@ export class BlockchainEnvironment {
         this._tx = new Transaction(
             caller,
             origin,
+            txId,
             txHash,
         );
 
@@ -169,12 +168,8 @@ export class BlockchainEnvironment {
     }
 
     public call(destinationContract: Address, calldata: BytesWriter): BytesReader {
-        if (destinationContract === this.contractAddress) {
-            throw this.error('Cannot call self');
-        }
-
         if (!destinationContract) {
-            throw this.error('Destination contract is required');
+            throw new Revert('Destination contract is required');
         }
 
         const resultLengthBuffer = new ArrayBuffer(32);
@@ -232,7 +227,7 @@ export class BlockchainEnvironment {
         );
 
         if (status !== 0) {
-            throw this.error('Failed to deploy contract');
+            throw new Revert('Failed to deploy contract');
         }
 
         const contractAddressReader = new BytesReader(Uint8Array.wrap(resultAddressBuffer));
@@ -281,7 +276,7 @@ export class BlockchainEnvironment {
 
     private createContractIfNotExists(): void {
         if (!this._contract) {
-            throw this.error('Contract is required');
+            throw new Revert('Contract is required');
         }
 
         if (!this._selfContract) {
@@ -289,10 +284,6 @@ export class BlockchainEnvironment {
         }
     }
 
-    private error(msg: string): Error {
-        return runtimeError(msg);
-    }
-
     private _internalSetStorageAt(pointerHash: Uint8Array, value: Uint8Array): void {
         this.storage.set(pointerHash, value);
 

package/runtime/env/classes/Transaction.ts

@@ -9,6 +9,7 @@ export class Transaction {
     public constructor(
         public readonly sender: Address, // "immediate caller"
         public readonly origin: Address, // "leftmost thing in the call chain"
+        public readonly txId: Uint8Array,
         public readonly hash: Uint8Array,
     ) {
     }

package/runtime/exports/index.ts

@@ -5,7 +5,7 @@ import { Selector } from '../math/abi';
 import { Calldata } from '../types';
 import { env_exit, getCalldata, getEnvironmentVariables } from '../env/global';
 
-const ENVIRONMENT_VARIABLES_BYTE_LENGTH: u32 = 208;
+const ENVIRONMENT_VARIABLES_BYTE_LENGTH: u32 = 240;
 
 export function execute(calldataLength: u32): u32 {
     const environmentVariablesBuffer = new ArrayBuffer(ENVIRONMENT_VARIABLES_BYTE_LENGTH);

package/runtime/math/bytes.ts

@@ -171,23 +171,7 @@ export function encodeBasePointer(pointer: u16, subPointer: Uint8Array): Uint8Ar
 
 @inline
 export function bigEndianAdd(base: Uint8Array, increment: u64): Uint8Array {
-    const out = new Uint8Array(32);
+    const add = u64ToBE32Bytes(increment);
 
-    // Copy the base pointer
-    for (let i = 0; i < 32; i++) {
-        out[i] = base[i];
-    }
-
-    // If this is truly big-endian, out[0] is the MSB, out[31] is the LSB.
-    // So to add `increment`, we start from out[31] backward.
-    let carry: u64 = increment;
-    for (let i = 31; i >= 0; i--) {
-        const sum = <u64>out[i] + (carry & 0xFF);
-        out[i] = <u8>(sum & 0xFF);
-        carry = sum >> 8;
-        if (carry == 0 || i == 0) {
-            break;
-        }
-    }
-    return out;
+    return addUint8ArraysBE(base, add);
 }

package/runtime/storage/arrays/StoredAddressArray.ts

@@ -1,6 +1,12 @@
 import { BytesWriter } from '../../buffer/BytesWriter';
 import { Blockchain } from '../../env';
-import { addUint8ArraysBE, encodeBasePointer, readLengthAndStartIndex, u64ToBE32Bytes } from '../../math/bytes';
+import {
+    addUint8ArraysBE,
+    bigEndianAdd,
+    encodeBasePointer,
+    readLengthAndStartIndex,
+    u64ToBE32Bytes,
+} from '../../math/bytes';
 import { Address } from '../../types/Address';
 import { Revert } from '../../types/Revert';
 
@@ -39,7 +45,7 @@ export class StoredAddressArray {
 
         const basePointer = encodeBasePointer(pointer, subPointer);
         this.lengthPointer = Uint8Array.wrap(basePointer.buffer);
-        this.baseU256Pointer = basePointer;
+        this.baseU256Pointer = bigEndianAdd(basePointer, 1);
 
         const storedLenStart = Blockchain.getStorageAt(basePointer);
         const data = readLengthAndStartIndex(storedLenStart);
@@ -48,13 +54,21 @@ export class StoredAddressArray {
         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.MAX_LENGTH) {
-            throw new Revert('Operation failed: Index exceeds maximum allowed value.');
+        if (index >= this._length) {
+            throw new Revert('get: index out of range (address array)');
         }
-        const slotIndex: u32 = <u32>index;
+
+        const physicalIndex = (this._startIndex + index) % this.MAX_LENGTH;
+        const slotIndex: u32 = <u32>physicalIndex;
         this.ensureValues(slotIndex);
 
         return this._values.get(slotIndex);
@@ -62,11 +76,14 @@ export class StoredAddressArray {
 
     /** Set an element by its global index. */
     @inline
+    @operator('[]=')
     public set(index: u64, value: Address): void {
-        if (index > this.MAX_LENGTH) {
-            throw new Revert('Set failed: Index exceeds maximum allowed value.');
+        if (index >= this._length) {
+            throw new Revert('set: index out of range (address array)');
         }
-        const slotIndex: u32 = <u32>index;
+
+        const physicalIndex = (this._startIndex + index) % this.MAX_LENGTH;
+        const slotIndex: u32 = <u32>physicalIndex;
         this.ensureValues(slotIndex);
 
         const currentValue = this._values.get(slotIndex);
@@ -76,33 +93,16 @@ export class StoredAddressArray {
         }
     }
 
-    /** Find the first index containing `value`. Returns -1 if not found. */
-    @inline
-    public indexOf(value: Address): i64 {
-        for (let i: u64 = 0; i < this._length; i++) {
-            if (this.get(i) == value) {
-                return i64(i);
-            }
-        }
-        return -1;
-    }
-
-    /** Check if the array contains `value`. */
-    @inline
-    public contains(value: Address): boolean {
-        return this.indexOf(value) !== -1;
-    }
-
     /** 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 failed: Array has reached its maximum length.');
+            throw new Revert('push: array reached maximum length (address array)');
         }
 
-        const newIndex: u64 = this._length;
-        const wrappedIndex: u64 =
-            newIndex < this.MAX_LENGTH ? newIndex : newIndex % this.MAX_LENGTH;
-        const slotIndex: u32 = <u32>wrappedIndex;
+        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);
@@ -115,11 +115,12 @@ export class StoredAddressArray {
     /** Delete the last element. */
     public deleteLast(): void {
         if (this._length === 0) {
-            throw new Revert('Delete failed: Array is empty.');
+            throw new Revert('deleteLast: array is empty (address array)');
         }
 
-        const lastIndex: u64 = this._length - 1;
-        const slotIndex: u32 = <u32>(this._startIndex + lastIndex);
+        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);
@@ -139,12 +140,14 @@ export class StoredAddressArray {
     }
 
     /** Delete a specific element by setting it to `defaultValue`. */
+    @inline
     public delete(index: u64): void {
         if (index > this.MAX_LENGTH) {
-            throw new Revert('Operation failed: Index exceeds maximum allowed value.');
+            throw new Revert('delete: index out of range (address array)');
         }
 
-        const slotIndex: u32 = <u32>index;
+        const physicalIndex: u64 = (this._startIndex + index) % this.MAX_LENGTH;
+        const slotIndex: u32 = <u32>physicalIndex;
         this.ensureValues(slotIndex);
 
         const currentValue = this._values.get(slotIndex);
@@ -159,6 +162,7 @@ export class StoredAddressArray {
      *  - 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();
@@ -185,7 +189,6 @@ export class StoredAddressArray {
 
     /** Clear entire array content from storage, reset length and startIndex. */
     public deleteAll(): void {
-        // Clear all loaded slots
         const keys = this._values.keys();
         for (let i = 0; i < keys.length; i++) {
             const slotIndex = keys[i];
@@ -193,14 +196,13 @@ export class StoredAddressArray {
             Blockchain.setStorageAt(storagePointer, this.defaultValue);
         }
 
-        // Reset length and startIndex in storage
-        Blockchain.setStorageAt(this.lengthPointer, new Uint8Array(0)); // or a 16-byte zero array if preferred
+        Blockchain.setStorageAt(this.lengthPointer, new Uint8Array(32));
+
         this._length = 0;
         this._startIndex = 0;
         this._isChangedLength = false;
         this._isChangedStartIndex = false;
 
-        // Clear internal caches
         this._values.clear();
         this._isChanged.clear();
     }
@@ -217,7 +219,7 @@ export class StoredAddressArray {
     @inline
     public getAll(startIndex: u32, count: u32): Address[] {
         if (startIndex + count > this._length) {
-            throw new Revert('Requested range exceeds array length');
+            throw new Revert('getAll: index out of range (address array)');
         }
 
         const result = new Array<Address>(count);
@@ -249,6 +251,10 @@ export class StoredAddressArray {
         this._startIndex = 0;
         this._isChangedLength = true;
         this._isChangedStartIndex = true;
+
+        this._values.clear();
+        this._isChanged.clear();
+
         this.save();
     }
 
@@ -284,8 +290,8 @@ export class StoredAddressArray {
      * Compute a 32-byte storage pointer = basePointer + (slotIndex + 1) big-endian.
      */
     private calculateStoragePointer(slotIndex: u64): Uint8Array {
-        // Convert (slotIndex + 1) to a 32-byte big-endian offset
-        const offset = u64ToBE32Bytes(slotIndex + 1);
+        // Convert (slotIndex) to a 32-byte big-endian offset
+        const offset = u64ToBE32Bytes(slotIndex);
 
         return addUint8ArraysBE(this.baseU256Pointer, offset);
     }

package/runtime/storage/arrays/StoredBooleanArray.ts

@@ -3,6 +3,7 @@ import { Blockchain } from '../../env';
 import { Revert } from '../../types/Revert';
 import {
     addUint8ArraysBE,
+    bigEndianAdd,
     encodeBasePointer,
     GET_EMPTY_BUFFER,
     getBit,
@@ -51,7 +52,7 @@ export class StoredBooleanArray {
 
         const basePointer = encodeBasePointer(pointer, subPtr);
         this.lengthPointer = Uint8Array.wrap(basePointer.buffer);
-        this.basePointer = basePointer;
+        this.basePointer = bigEndianAdd(basePointer, 1);
 
         const storedLenStart = Blockchain.getStorageAt(basePointer);
         const data = readLengthAndStartIndex(storedLenStart);
@@ -62,16 +63,28 @@ export class StoredBooleanArray {
 
     // -------------- Public Accessors -------------- //
 
+    @inline
+    public has(index: u64): bool {
+        return index < this._length;
+    }
+
     /**
      * Retrieve boolean at `index`.
      */
+    @operator('[]')
     @inline
     public get(index: u64): bool {
-        if (index > this.MAX_LENGTH) {
-            throw new Revert('get: Index exceeds maximum allowed value.');
+        if (index >= this._length) {
+            throw new Revert(`get: index out of range (${index} >= ${this._length}, boolean array)`);
         }
-        const slotIndex = index / 256;      // which 32-byte slot
-        const bitIndex = <u16>(index % 256);
+
+        const effectiveIndex = this._startIndex + index;
+        const wrappedIndex = effectiveIndex < this.MAX_LENGTH
+            ? effectiveIndex
+            : effectiveIndex % this.MAX_LENGTH;
+
+        const slotIndex = wrappedIndex / 256;
+        const bitIndex = <u16>(wrappedIndex % 256);
 
         this.ensureSlotLoaded(slotIndex);
 
@@ -82,13 +95,20 @@ export class StoredBooleanArray {
     /**
      * Set boolean at `index`.
      */
+    @operator('[]=')
     @inline
     public set(index: u64, value: bool): void {
-        if (index > this.MAX_LENGTH) {
-            throw new Revert('set: Index exceeds maximum allowed value.');
+        if (index >= this._length) {
+            throw new Revert(`set: index out of range (${index} >= ${this._length}, boolean array)`);
         }
-        const slotIndex = index / 256;
-        const bitIndex = <u16>(index % 256);
+
+        const effectiveIndex = this._startIndex + index;
+        const wrappedIndex = effectiveIndex < this.MAX_LENGTH
+            ? effectiveIndex
+            : effectiveIndex % this.MAX_LENGTH;
+
+        const slotIndex = wrappedIndex / 256;
+        const bitIndex = <u16>(wrappedIndex % 256);
 
         this.ensureSlotLoaded(slotIndex);
 
@@ -108,7 +128,7 @@ export class StoredBooleanArray {
     @inline
     public push(value: bool): void {
         if (this._length >= this.MAX_LENGTH) {
-            throw new Revert('push: Reached max allowed length');
+            throw new Revert('push: reached max allowed length (boolean array)');
         }
 
         const newIndex = this._length;
@@ -137,11 +157,17 @@ export class StoredBooleanArray {
      */
     @inline
     public delete(index: u64): void {
-        if (index > this.MAX_LENGTH) {
-            throw new Revert('delete: Index exceeds maximum allowed value.');
+        if (index >= this._length) {
+            throw new Revert('delete: index out of range (boolean array)');
         }
-        const slotIndex = index / 256;
-        const bitIndex = <u16>(index % 256);
+
+        const effectiveIndex = this._startIndex + index;
+        const wrappedIndex = effectiveIndex < this.MAX_LENGTH
+            ? effectiveIndex
+            : effectiveIndex % this.MAX_LENGTH;
+
+        const slotIndex = wrappedIndex / 256;
+        const bitIndex = <u16>(wrappedIndex % 256);
 
         this.ensureSlotLoaded(slotIndex);
 
@@ -161,8 +187,9 @@ export class StoredBooleanArray {
     @inline
     public deleteLast(): void {
         if (this._length === 0) {
-            throw new Revert('deleteLast: Array is empty');
+            throw new Revert('deleteLast: array is empty');
         }
+
         const lastIndex = this._length - 1;
         this.delete(lastIndex);
 
@@ -200,11 +227,10 @@ export class StoredBooleanArray {
     }
 
     /**
-     * Delete all slots in storage (that are loaded) + reset length + startIndex.
+     * Delete all slots in storage (that are loaded) + reset length + _startIndex.
      */
     @inline
     public deleteAll(): void {
-        // clear all loaded slots
         const keys = this._values.keys();
         const zeroArr = GET_EMPTY_BUFFER();
         for (let i = 0; i < keys.length; i++) {
@@ -213,15 +239,14 @@ export class StoredBooleanArray {
             Blockchain.setStorageAt(storagePointer, zeroArr);
         }
 
-        // also reset length + startIndex in storage
         const writer = new BytesWriter(32);
         Blockchain.setStorageAt(this.lengthPointer, writer.getBuffer());
 
-        // reset in memory
         this._length = 0;
         this._startIndex = 0;
         this._isChangedLength = false;
         this._isChangedStartIndex = false;
+
         this._values.clear();
         this._isChanged.clear();
     }
@@ -240,18 +265,20 @@ export class StoredBooleanArray {
      * Retrieve a batch of bools.
      */
     @inline
-    public getAll(startIndex: u64, count: u64): bool[] {
-        if (startIndex + count > this._length) {
-            throw new Revert('getAll: range exceeds array length');
+    public getAll(start: u64, count: u64): bool[] {
+        if (start + count > this._length) {
+            throw new Revert('getAll: range exceeds array length (boolean array)');
         }
+
         if (count > u64(u32.MAX_VALUE)) {
-            throw new Revert('getAll: range exceeds max allowed');
+            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++) {
-            result[<i32>i] = this.get(startIndex + i);
+            result[<i32>i] = this.get(start + i);
         }
+
         return result;
     }
 
@@ -295,6 +322,12 @@ export class StoredBooleanArray {
         return this._length;
     }
 
+    @inline
+    public setStartingIndex(index: u64): void {
+        this._startIndex = index;
+        this._isChangedStartIndex = true;
+    }
+
     /**
      * Current starting index for the array.
      */
@@ -303,7 +336,6 @@ export class StoredBooleanArray {
         return this._startIndex;
     }
 
-
     /**
      * Ensure the 32-byte slot for `slotIndex` is loaded into _values.
      */
@@ -319,7 +351,7 @@ export class StoredBooleanArray {
      * Convert `slotIndex` -> pointer = basePointer + (slotIndex + 1), as big-endian addition.
      */
     private calculateStoragePointer(slotIndex: u64): Uint8Array {
-        const offset = u64ToBE32Bytes(slotIndex + 1);
+        const offset = u64ToBE32Bytes(slotIndex);
         return addUint8ArraysBE(this.basePointer, offset);
     }
 }

package/runtime/storage/arrays/StoredPackedArray.ts

@@ -1,4 +1,5 @@
 import {
+    bigEndianAdd,
     encodeBasePointer,
     GET_EMPTY_BUFFER,
     readLengthAndStartIndex,
@@ -48,12 +49,12 @@ export abstract class StoredPackedArray<T> {
      */
     protected readonly MAX_LENGTH: u64 = <u64>(u32.MAX_VALUE - 1);
 
-    protected constructor(public pointer: u16, public subPointer: Uint8Array) {
+    protected constructor(public pointer: u16, public subPointer: Uint8Array, protected defaultValue: T) {
         assert(subPointer.length <= 30, `You must pass a 30 bytes sub-pointer. (Array, got ${subPointer.length})`);
 
         const basePointer = encodeBasePointer(pointer, subPointer);
         this.lengthPointer = Uint8Array.wrap(basePointer.buffer);
-        this.basePointer = basePointer;
+        this.basePointer = bigEndianAdd(basePointer, 1);
 
         const storedLenStart = Blockchain.getStorageAt(basePointer);
         const data = readLengthAndStartIndex(storedLenStart);
@@ -62,24 +63,70 @@ export abstract class StoredPackedArray<T> {
         this._startIndex = data[1];
     }
 
+    @inline
+    @operator('[]')
     public get(index: u64): T {
+        // max length used on purpose to prevent unbounded usage
         if (index > this.MAX_LENGTH) {
-            throw new Revert('get: index exceeds MAX_LENGTH');
+            throw new Revert('get: out of range');
+        }
+
+        const realIndex = (this._startIndex + index) % this.MAX_LENGTH;
+        const cap = this.getSlotCapacity();
+        const slotIndex = realIndex / cap;
+        const subIndex = <u32>(realIndex % cap);
+
+        const slotData = this.ensureSlot(slotIndex);
+        const arr = this.unpackSlot(slotData);
+
+        return arr[subIndex];
+    }
+
+    @inline
+    public get_physical(index: u64): T {
+        if (index > this.MAX_LENGTH) {
+            throw new Revert('get: index exceeds MAX_LENGTH (packed array)');
         }
 
         const cap = this.getSlotCapacity();
         const slotIndex = index / cap;
         const subIndex = <u32>(index % cap);
 
-        // Load the slot if not cached
         const slotData = this.ensureSlot(slotIndex);
-
-        // Unpack and return the subIndex
         const arr = this.unpackSlot(slotData);
+
         return arr[subIndex];
     }
 
+    @inline
+    @operator('[]=')
     public set(index: u64, value: T): void {
+        if (index > this.MAX_LENGTH) {
+            throw new Revert('set: index exceeds MAX_LENGTH (packed array)');
+        }
+
+        const realIndex = (this._startIndex + index) % this.MAX_LENGTH;
+        const cap = this.getSlotCapacity();
+        const slotIndex = realIndex / cap;
+        const subIndex = <u32>(realIndex % cap);
+
+        let slotData = this.ensureSlot(slotIndex);
+        const arr = this.unpackSlot(slotData);
+
+        if (!this.eq(arr[subIndex], value)) {
+            arr[subIndex] = value;
+            slotData = this.packSlot(arr);
+            this._slots.set(slotIndex, slotData);
+            this._isChanged.add(slotIndex);
+        }
+    }
+
+    @inline
+    public set_physical(index: u64, value: T): void {
+        if (index > this.MAX_LENGTH) {
+            throw new Revert('set: index exceeds MAX_LENGTH (packed array)');
+        }
+
         const cap = this.getSlotCapacity();
         const slotIndex = index / cap;
         const subIndex = <u32>(index % cap);
@@ -95,15 +142,16 @@ export abstract class StoredPackedArray<T> {
         }
     }
 
-    public push(value: T): void {
+    @inline
+    public push(value: T, isPhysical: bool = false): void {
         if (this._length >= this.MAX_LENGTH) {
             throw new Revert('push: array has reached MAX_LENGTH');
         }
 
-        const newIndex = this._length;
+        const realIndex = ((isPhysical ? 0 : this._startIndex) + this._length) % this.MAX_LENGTH;
         const cap = this.getSlotCapacity();
-        const slotIndex = newIndex / cap;
-        const subIndex = <u32>(newIndex % cap);
+        const slotIndex = realIndex / cap;
+        const subIndex = <u32>(realIndex % cap);
 
         let slotData = this.ensureSlot(slotIndex);
         const arr = this.unpackSlot(slotData);
@@ -119,11 +167,70 @@ export abstract class StoredPackedArray<T> {
         this._isChangedLength = true;
     }
 
+    /**
+     * Remove the first element by zeroing it and shifting all other elements.
+     */
+    @inline
+    public shift(): T {
+        if (this._length == 0) {
+            throw new Revert('shift: array is empty (packed array)');
+        }
+
+        const newIndex = this._startIndex;
+        const cap = this.getSlotCapacity();
+        const slotIndex = newIndex / cap;
+        const subIndex = <u32>(newIndex % cap);
+
+        let slotData = this.ensureSlot(slotIndex);
+
+        const arr = this.unpackSlot(slotData);
+        const currentData = arr[subIndex];
+
+        if (!this.eq(currentData, this.defaultValue)) {
+            arr[subIndex] = this.defaultValue;
+            slotData = this.packSlot(arr);
+
+            this._slots.set(slotIndex, slotData);
+            this._isChanged.add(slotIndex);
+        }
+
+        this._length -= 1;
+        this._startIndex += 1;
+        this._isChangedLength = true;
+        this._isChangedStartIndex = true;
+
+        return currentData;
+    }
+
     /**
      * "Delete" by zeroing out the element at `index`,
      * but does not reduce the length.
      */
+    @inline
     public delete(index: u64): void {
+        const realIndex = (this._startIndex + index) % this.MAX_LENGTH;
+        const cap = this.getSlotCapacity();
+        const slotIndex = realIndex / cap;
+        const subIndex = <u32>(realIndex % cap);
+
+        let slotData = this.ensureSlot(slotIndex);
+        const arr = this.unpackSlot(slotData);
+
+        const zeroVal = this.zeroValue();
+        if (!this.eq(arr[subIndex], zeroVal)) {
+            arr[subIndex] = zeroVal;
+            slotData = this.packSlot(arr);
+            this._slots.set(slotIndex, slotData);
+            this._isChanged.add(slotIndex);
+        }
+    }
+
+    /**
+     * "Delete" by zeroing out the element at `index`,
+     * but does not reduce the length.
+     */
+    @inline
+    public delete_physical(index: u64): void {
         const cap = this.getSlotCapacity();
         const slotIndex = index / cap;
         const subIndex = <u32>(index % cap);
@@ -143,9 +250,10 @@ export abstract class StoredPackedArray<T> {
     /**
      * Remove the last element by zeroing it and decrementing length by 1.
      */
+    @inline
     public deleteLast(): void {
         if (this._length == 0) {
-            throw new Revert('deleteLast: array is empty');
+            throw new Revert('deleteLast: array is empty (packed array)');
         }
 
         const lastIndex = this._length - 1;
@@ -155,11 +263,13 @@ export abstract class StoredPackedArray<T> {
         this._isChangedLength = true;
     }
 
+    @inline
     public setMultiple(startIndex: u64, values: T[]): void {
         const end = startIndex + <u64>values.length;
         if (end > this._length) {
-            throw new Revert('setMultiple: out of range');
+            throw new Revert('setMultiple: out of range (packed array)');
         }
+
         for (let i = 0; i < values.length; i++) {
             this.set(startIndex + <u64>i, values[i]);
         }
@@ -168,10 +278,10 @@ export abstract class StoredPackedArray<T> {
     // -----------------------------------------------------------
     //              Public Array-Like Methods
     // -----------------------------------------------------------
-
+    @inline
     public getAll(startIndex: u64, count: u64): T[] {
         if (count > <u64>u32.MAX_VALUE) {
-            throw new Revert('getAll: count too large');
+            throw new Revert('getAll: count too large (packed array)');
         }
 
         const out = new Array<T>(<i32>count);
@@ -182,14 +292,17 @@ export abstract class StoredPackedArray<T> {
         return out;
     }
 
+    @inline
     public getLength(): u64 {
         return this._length;
     }
 
+    @inline
     public startingIndex(): u64 {
         return this._startIndex;
     }
 
+    @inline
     public setStartingIndex(index: u64): void {
         this._startIndex = index;
         this._isChangedStartIndex = true;
@@ -250,6 +363,9 @@ export abstract class StoredPackedArray<T> {
         this._isChanged.clear();
     }
 
+    /**
+     * Reset the array to its initial state.
+     */
     public reset(): void {
         this._length = 0;
         this._startIndex = 0;

package/runtime/storage/arrays/StoredU128Array.ts

@@ -10,7 +10,7 @@ import { bigEndianAdd } from '../../math/bytes';
 @final
 export class StoredU128Array extends StoredPackedArray<u128> {
     public constructor(pointer: u16, subPointer: Uint8Array) {
-        super(pointer, subPointer);
+        super(pointer, subPointer, u128.Zero);
     }
 
     protected getSlotCapacity(): u64 {
@@ -59,6 +59,6 @@ export class StoredU128Array extends StoredPackedArray<u128> {
     }
 
     protected calculateStoragePointer(slotIndex: u64): Uint8Array {
-        return bigEndianAdd(this.basePointer, slotIndex + 1);
+        return bigEndianAdd(this.basePointer, slotIndex);
     }
 }

package/runtime/storage/arrays/StoredU16Array.ts

@@ -7,7 +7,7 @@ import { bigEndianAdd } from '../../math/bytes';
 @final
 export class StoredU16Array extends StoredPackedArray<u16> {
     public constructor(pointer: u16, subPointer: Uint8Array) {
-        super(pointer, subPointer);
+        super(pointer, subPointer, 0);
     }
 
     protected getSlotCapacity(): u64 {
@@ -53,6 +53,6 @@ export class StoredU16Array extends StoredPackedArray<u16> {
     }
 
     protected calculateStoragePointer(slotIndex: u64): Uint8Array {
-        return bigEndianAdd(this.basePointer, slotIndex + 1);
+        return bigEndianAdd(this.basePointer, slotIndex);
     }
 }

package/runtime/storage/arrays/StoredU256Array.ts

@@ -9,7 +9,7 @@ import { bigEndianAdd } from '../../math/bytes';
 @final
 export class StoredU256Array extends StoredPackedArray<u256> {
     public constructor(pointer: u16, subPointer: Uint8Array) {
-        super(pointer, subPointer);
+        super(pointer, subPointer, u256.Zero);
     }
 
     protected getSlotCapacity(): u64 {
@@ -34,6 +34,6 @@ export class StoredU256Array extends StoredPackedArray<u256> {
     }
 
     protected calculateStoragePointer(slotIndex: u64): Uint8Array {
-        return bigEndianAdd(this.basePointer, slotIndex + 1);
+        return bigEndianAdd(this.basePointer, slotIndex);
     }
 }

package/runtime/storage/arrays/StoredU32Array.ts

@@ -8,7 +8,7 @@ import { bigEndianAdd } from '../../math/bytes';
 @final
 export class StoredU32Array extends StoredPackedArray<u32> {
     public constructor(pointer: u16, subPointer: Uint8Array) {
-        super(pointer, subPointer);
+        super(pointer, subPointer, 0);
     }
 
     protected getSlotCapacity(): u64 {
@@ -52,6 +52,6 @@ export class StoredU32Array extends StoredPackedArray<u32> {
     }
 
     protected calculateStoragePointer(slotIndex: u64): Uint8Array {
-        return bigEndianAdd(this.basePointer, slotIndex + 1);
+        return bigEndianAdd(this.basePointer, slotIndex);
     }
 }

package/runtime/storage/arrays/StoredU64Array.ts

@@ -8,7 +8,7 @@ import { bigEndianAdd } from '../../math/bytes';
 @final
 export class StoredU64Array extends StoredPackedArray<u64> {
     public constructor(pointer: u16, subPointer: Uint8Array) {
-        super(pointer, subPointer);
+        super(pointer, subPointer, 0);
     }
 
     protected getSlotCapacity(): u64 {
@@ -61,6 +61,6 @@ export class StoredU64Array extends StoredPackedArray<u64> {
     }
 
     protected calculateStoragePointer(slotIndex: u64): Uint8Array {
-        return bigEndianAdd(this.basePointer, slotIndex + 1);
+        return bigEndianAdd(this.basePointer, slotIndex);
     }
 }

package/runtime/storage/arrays/StoredU8Array.ts

@@ -8,7 +8,7 @@ import { bigEndianAdd } from '../../math/bytes';
 @final
 export class StoredU8Array extends StoredPackedArray<u8> {
     public constructor(pointer: u16, subPointer: Uint8Array) {
-        super(pointer, subPointer);
+        super(pointer, subPointer, 0);
     }
 
     protected getSlotCapacity(): u64 {
@@ -43,6 +43,6 @@ export class StoredU8Array extends StoredPackedArray<u8> {
 
     protected calculateStoragePointer(slotIndex: u64): Uint8Array {
         // basePointer + (slotIndex+1) in big-endian
-        return bigEndianAdd(this.basePointer, slotIndex + 1);
+        return bigEndianAdd(this.basePointer, slotIndex);
     }
 }