@feelyourprotocol/mpt 8141.0.0

package/dist/esm/util/asyncWalk.js

@@ -0,0 +1,47 @@
+import { RLP } from '@feelyourprotocol/rlp';
+import { bytesToHex, equalsBytes } from '@feelyourprotocol/util';
+import { BranchMPTNode } from "../node/branch.js";
+import { ExtensionMPTNode } from "../node/extension.js";
+/**
+ * Walk MerklePatriciaTrie via async generator
+ * @param nodeHash - The root key to walk on.
+ * @param currentKey - The current (partial) key.
+ * @param onFound - Called on every node found (before filter)
+ * @param filter - Filter nodes yielded by the generator.
+ * @param visited - Set of visited nodes
+ * @returns AsyncIterable<{ node: MPTNode; currentKey: number[] }>
+ * Iterate through nodes with
+ * `for await (const { node, currentKey } of trie._walkTrie(root)) { ... }`
+ */
+export async function* _walkTrie(nodeHash, currentKey = [], onFound = async (_trieNode, _key) => { }, filter = async (_trieNode, _key) => true, visited = new Set()) {
+    if (equalsBytes(nodeHash, this.EMPTY_TRIE_ROOT)) {
+        return;
+    }
+    try {
+        const node = await this.lookupNode(nodeHash);
+        if (node === undefined || visited.has(bytesToHex(this.hash(node.serialize())))) {
+            return;
+        }
+        visited.add(bytesToHex(this.hash(node.serialize())));
+        await onFound(node, currentKey);
+        if (await filter(node, currentKey)) {
+            yield { node: node, currentKey };
+        }
+        if (node instanceof BranchMPTNode) {
+            for (const [nibble, childNode] of node._branches.entries()) {
+                const nextKey = [...currentKey, nibble];
+                const _childNode = childNode instanceof Uint8Array ? childNode : this.hash(RLP.encode(childNode));
+                yield* _walkTrie.bind(this)(_childNode, nextKey, onFound, filter, visited);
+            }
+        }
+        else if (node instanceof ExtensionMPTNode) {
+            const childNode = node.value();
+            const nextKey = [...currentKey, ...node._nibbles];
+            yield* _walkTrie.bind(this)(childNode, nextKey, onFound, filter, visited);
+        }
+    }
+    catch {
+        return;
+    }
+}
+//# sourceMappingURL=asyncWalk.js.map

package/dist/esm/util/asyncWalk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asyncWalk.js","sourceRoot":"","sources":["../../../src/util/asyncWalk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAA;AACrC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAE1D,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAQvD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,SAAS,CAE9B,QAAoB,EACpB,aAAuB,EAAE,EACzB,UAAmB,KAAK,EAAE,SAAkB,EAAE,IAAc,EAAE,EAAE,GAAE,CAAC,EACnE,SAAqB,KAAK,EAAE,SAAkB,EAAE,IAAc,EAAE,EAAE,CAAC,IAAI,EACvE,UAAuB,IAAI,GAAG,EAAU;IAExC,IAAI,WAAW,CAAC,QAAQ,EAAE,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC;QAChD,OAAM;IACR,CAAC;IACD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAA;QAC5C,IAAI,IAAI,KAAK,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAChF,OAAM;QACR,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,CAAA;QACrD,MAAM,OAAO,CAAC,IAAK,EAAE,UAAU,CAAC,CAAA;QAChC,IAAI,MAAM,MAAM,CAAC,IAAK,EAAE,UAAU,CAAC,EAAE,CAAC;YACpC,MAAM,EAAE,IAAI,EAAE,IAAK,EAAE,UAAU,EAAE,CAAA;QACnC,CAAC;QACD,IAAI,IAAI,YAAY,aAAa,EAAE,CAAC;YAClC,KAAK,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,EAAE,CAAC;gBAC3D,MAAM,OAAO,GAAG,CAAC,GAAG,UAAU,EAAE,MAAM,CAAC,CAAA;gBACvC,MAAM,UAAU,GACd,SAAS,YAAY,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAA;gBAChF,KAAK,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,CAAA;YAC5E,CAAC;QACH,CAAC;aAAM,IAAI,IAAI,YAAY,gBAAgB,EAAE,CAAC;YAC5C,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,EAAE,CAAA;YAC9B,MAAM,OAAO,GAAG,CAAC,GAAG,UAAU,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAA;YACjD,KAAK,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,CAAA;QAC3E,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAM;IACR,CAAC;AACH,CAAC"}

package/dist/esm/util/encoding.d.ts

@@ -0,0 +1,31 @@
+import type { Nibbles } from '../types.ts';
+export declare const nibblesToBytes: (nibbles: Uint8Array) => Uint8Array<ArrayBuffer>;
+export declare const hexToKeybytes: (hex: Uint8Array) => Uint8Array<ArrayBuffer>;
+export declare const nibblesToCompactBytes: (nibbles: Uint8Array) => Uint8Array<ArrayBuffer>;
+export declare const bytesToNibbles: (str: Uint8Array) => Uint8Array<ArrayBuffer>;
+export declare const compactBytesToNibbles: (compact: Uint8Array) => Uint8Array<ArrayBufferLike>;
+/**
+ * Converts each nibble into a single byte
+ *
+ * @param arr Nibble typed nibble array
+ * @returns Uint8Array typed byte array
+ */
+export declare const nibbleTypeToByteType: (arr: Nibbles) => Uint8Array;
+/**
+ * Turns each byte into a single nibble, only extracting the lower nibble of each byte
+ *
+ * @param key Uint8Array typed byte array
+ * @returns Nibble typed nibble array
+ */
+export declare const byteTypeToNibbleType: (key: Uint8Array) => Nibbles;
+/**
+ * Takes a string path and extends it by the given extension nibbles
+ *
+ * @param path String node path
+ * @param extension nibbles to extend by
+ * @param retType string indicating whether to return the key in "keybyte" or "hex" encoding
+ * @returns hex-encoded key
+ */
+export declare const pathToHexKey: (path: string, extension: Nibbles, retType: string) => Uint8Array;
+export declare const mergeAndFormatKeyPaths: (pathStrings: string[]) => Uint8Array<ArrayBuffer>[][];
+//# sourceMappingURL=encoding.d.ts.map

package/dist/esm/util/encoding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../../../src/util/encoding.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAgC1C,eAAO,MAAM,cAAc,GAAI,SAAS,UAAU,4BAOjD,CAAA;AAED,eAAO,MAAM,aAAa,GAAI,KAAK,UAAU,4BAS5C,CAAA;AAGD,eAAO,MAAM,qBAAqB,GAAI,SAAS,UAAU,4BAoBxD,CAAA;AAED,eAAO,MAAM,cAAc,GAAI,KAAK,UAAU,4BAY7C,CAAA;AAED,eAAO,MAAM,qBAAqB,GAAI,SAAS,UAAU,gCAaxD,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAAI,KAAK,OAAO,KAAG,UAQnD,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAAI,KAAK,UAAU,KAAG,OAStD,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,EAAE,WAAW,OAAO,EAAE,SAAS,MAAM,KAAG,UAShF,CAAA;AAED,eAAO,MAAM,sBAAsB,GAAI,aAAa,MAAM,EAAE,gCAgD3D,CAAA"}

package/dist/esm/util/encoding.js

@@ -0,0 +1,188 @@
+import { concatBytes, hexToBytes, unprefixedHexToBytes } from '@feelyourprotocol/util';
+import { nibblesTypeToPackedBytes } from "./nibbles.js";
+// Reference: https://ethereum.org/en/developers/docs/data-structures-and-encoding/patricia-merkle-trie/
+//
+// MerklePatriciaTrie keys are dealt with in three distinct encodings:
+//
+// KEYBYTES encoding contains the actual key and nothing else. This encoding is the
+// input to most API functions.
+//
+// HEX encoding contains one byte for each nibble of the key and an optional trailing
+// 'terminator' byte of value 0x10 which indicates whether or not the node at the key
+// contains a value. Hex key encoding is used for nodes loaded in memory because it's
+// convenient to access.
+//
+// COMPACT encoding is defined by the Ethereum Yellow Paper (it's called "hex prefix
+// encoding" there) and contains the bytes of the key and a flag. The high nibble of the
+// first byte contains the flag; the lowest bit encoding the oddness of the length and
+// the second-lowest encoding whether the node at the key is a value node. The low nibble
+// of the first byte is zero in the case of an even number of nibbles and the first nibble
+// in the case of an odd number. All remaining nibbles (now an even number) fit properly
+// into the remaining bytes. Compact encoding is used for nodes stored on disk.
+/**
+ *
+ * @param nibbles byte sequence
+ * @returns boolean indicating if input hex nibble sequence has terminator indicating leaf-node
+ *          terminator is represented with 16 because a nibble ranges from 0 - 15(f)
+ */
+const hasTerminator = (nibbles) => {
+    return nibbles.length > 0 && nibbles[nibbles.length - 1] === 16;
+};
+export const nibblesToBytes = (nibbles) => {
+    const bytes = new Uint8Array(nibbles.length / 2);
+    for (let bi = 0, ni = 0; ni < nibbles.length; bi += 1, ni += 2) {
+        bytes[bi] = (nibbles[ni] << 4) | nibbles[ni + 1];
+    }
+    return bytes;
+};
+export const hexToKeybytes = (hex) => {
+    if (hasTerminator(hex)) {
+        hex = hex.subarray(0, hex.length - 1);
+    }
+    if (hex.length % 2 === 1) {
+        throw Error("Can't convert hex key of odd length");
+    }
+    return nibblesToBytes(hex);
+};
+// hex to compact
+export const nibblesToCompactBytes = (nibbles) => {
+    let terminator = 0;
+    if (hasTerminator(nibbles)) {
+        terminator = 1;
+        // Remove the terminator from the sequence
+        nibbles = nibbles.subarray(0, nibbles.length - 1);
+    }
+    const buf = new Uint8Array(nibbles.length / 2 + 1);
+    // Shift the terminator info into the first nibble of buf[0]
+    buf[0] = terminator << 5;
+    // If odd length, then add that flag into the first nibble and put the odd nibble to
+    // second part of buf[0] which otherwise will be left padded with a 0
+    if ((nibbles.length & 1) === 1) {
+        buf[0] |= 1 << 4;
+        buf[0] |= nibbles[0];
+        nibbles = nibbles.subarray(1);
+    }
+    // create bytes out of the rest even nibbles
+    return concatBytes(buf.subarray(0, 1), nibblesToBytes(nibbles));
+};
+export const bytesToNibbles = (str) => {
+    const l = str.length * 2 + 1;
+    const nibbles = new Uint8Array(l);
+    for (let i = 0; i < str.length; i++) {
+        const b = str[i];
+        nibbles[i * 2] = b / 16;
+        nibbles[i * 2 + 1] = b % 16;
+    }
+    // This will get removed from calling function if the first nibble
+    // indicates that terminator is not present
+    nibbles[l - 1] = 16;
+    return nibbles;
+};
+export const compactBytesToNibbles = (compact) => {
+    if (compact.length === 0) {
+        return compact;
+    }
+    let base = bytesToNibbles(compact);
+    // delete terminator flag if terminator flag was not in first nibble
+    if (base[0] < 2) {
+        base = base.subarray(0, base.length - 1);
+    }
+    // chop the terminator nibble and the even padding (if there is one)
+    // i.e.  chop 2 left nibbles when even else 1 when odd
+    const chop = 2 - (base[0] & 1);
+    return base.subarray(chop);
+};
+/**
+ * Converts each nibble into a single byte
+ *
+ * @param arr Nibble typed nibble array
+ * @returns Uint8Array typed byte array
+ */
+export const nibbleTypeToByteType = (arr) => {
+    const l = arr.length;
+    const buf = new Uint8Array(l);
+    for (let i = 0; i < buf.length; i++) {
+        buf[i] = arr[i];
+    }
+    return buf;
+};
+/**
+ * Turns each byte into a single nibble, only extracting the lower nibble of each byte
+ *
+ * @param key Uint8Array typed byte array
+ * @returns Nibble typed nibble array
+ */
+export const byteTypeToNibbleType = (key) => {
+    const nibbles = [];
+    for (let i = 0; i < key.length; i++) {
+        const q = i;
+        nibbles[q] = key[i] % 16;
+    }
+    return nibbles;
+};
+/**
+ * Takes a string path and extends it by the given extension nibbles
+ *
+ * @param path String node path
+ * @param extension nibbles to extend by
+ * @param retType string indicating whether to return the key in "keybyte" or "hex" encoding
+ * @returns hex-encoded key
+ */
+export const pathToHexKey = (path, extension, retType) => {
+    const b = hexToBytes(`0x${path}`);
+    const n = byteTypeToNibbleType(b);
+    if (retType === 'hex') {
+        return nibbleTypeToByteType(n.concat(extension));
+    }
+    else if (retType === 'keybyte') {
+        return nibblesTypeToPackedBytes(n.concat(extension));
+    }
+    throw Error('retType must be either "keybyte" or "hex"');
+};
+export const mergeAndFormatKeyPaths = (pathStrings) => {
+    const ret = [];
+    let paths = [];
+    let i = 0;
+    while (i < pathStrings.length) {
+        const outerPathString = pathStrings[i].split('/');
+        const outerAccountPath = outerPathString[0];
+        const outerStoragePath = outerPathString[1];
+        paths.push(outerAccountPath);
+        if (outerStoragePath !== undefined) {
+            paths.push(outerStoragePath);
+        }
+        let j = ++i;
+        while (j < pathStrings.length) {
+            const innerPathString = pathStrings[j].split('/');
+            const innerAccountPath = innerPathString[0];
+            const innerStoragePath = innerPathString[1];
+            if (innerAccountPath === outerAccountPath) {
+                paths.push(innerStoragePath);
+            }
+            else {
+                ret.push(paths);
+                paths = [];
+                i = j;
+                break;
+            }
+            j++;
+        }
+        if (paths.length > 0) {
+            ret.push(paths);
+            paths = [];
+        }
+    }
+    if (paths.length > 0)
+        ret.push(paths);
+    return ret.map((pathStrings) => pathStrings.map((s) => {
+        if (s.length < 64) {
+            // partial path is compact encoded
+            return nibblesToCompactBytes(unprefixedHexToBytes(s));
+        }
+        else {
+            // full path is keybyte encoded
+            return hexToKeybytes(unprefixedHexToBytes(s));
+        }
+    }));
+};
+//# sourceMappingURL=encoding.js.map

package/dist/esm/util/encoding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoding.js","sourceRoot":"","sources":["../../../src/util/encoding.ts"],"names":[],"mappings":"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"}

package/dist/esm/util/genesisState.d.ts

@@ -0,0 +1,6 @@
+import type { GenesisState } from '@feelyourprotocol/common';
+/**
+ * Derives the stateRoot of the genesis block based on genesis allocations
+ */
+export declare function genesisMPTStateRoot(genesisState: GenesisState): Promise<Uint8Array<ArrayBufferLike>>;
+//# sourceMappingURL=genesisState.d.ts.map

package/dist/esm/util/genesisState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"genesisState.d.ts","sourceRoot":"","sources":["../../../src/util/genesisState.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAgB,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEpE;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,YAAY,EAAE,YAAY,wCAkCnE"}

package/dist/esm/util/genesisState.js

@@ -0,0 +1,42 @@
+import { RLP } from '@feelyourprotocol/rlp';
+import { Account, hexToBytes, isHexString, unpadBytes, unprefixedHexToBytes, } from '@feelyourprotocol/util';
+import { keccak_256 } from '@noble/hashes/sha3.js';
+import { MerklePatriciaTrie } from "../mpt.js";
+/**
+ * Derives the stateRoot of the genesis block based on genesis allocations
+ */
+export async function genesisMPTStateRoot(genesisState) {
+    const trie = new MerklePatriciaTrie({ useKeyHashing: true });
+    for (const [key, value] of Object.entries(genesisState)) {
+        const address = isHexString(key) ? hexToBytes(key) : unprefixedHexToBytes(key);
+        const account = new Account();
+        if (typeof value === 'string') {
+            account.balance = BigInt(value);
+        }
+        else {
+            const [balance, code, storage, nonce] = value;
+            if (balance !== undefined) {
+                account.balance = BigInt(balance);
+            }
+            if (code !== undefined) {
+                const codeBytes = isHexString(code) ? hexToBytes(code) : unprefixedHexToBytes(code);
+                account.codeHash = keccak_256(codeBytes);
+            }
+            if (storage !== undefined) {
+                const storageTrie = new MerklePatriciaTrie({ useKeyHashing: true });
+                for (const [k, val] of storage) {
+                    const storageKey = isHexString(k) ? hexToBytes(k) : unprefixedHexToBytes(k);
+                    const storageVal = RLP.encode(unpadBytes(isHexString(val) ? hexToBytes(val) : unprefixedHexToBytes(val)));
+                    await storageTrie.put(storageKey, storageVal);
+                }
+                account.storageRoot = storageTrie.root();
+            }
+            if (nonce !== undefined) {
+                account.nonce = BigInt(nonce);
+            }
+        }
+        await trie.put(address, account.serialize());
+    }
+    return trie.root();
+}
+//# sourceMappingURL=genesisState.js.map

package/dist/esm/util/genesisState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"genesisState.js","sourceRoot":"","sources":["../../../src/util/genesisState.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAA;AACrC,OAAO,EACL,OAAO,EACP,UAAU,EACV,WAAW,EACX,UAAU,EACV,oBAAoB,GACrB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAElD,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAI9C;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,YAA0B;IAClE,MAAM,IAAI,GAAG,IAAI,kBAAkB,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAA;IAC5D,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;QACxD,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,oBAAoB,CAAC,GAAG,CAAC,CAAA;QAC9E,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAA;QAC7B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,CAAC,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;QACjC,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,GAAG,KAA8B,CAAA;YACtE,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,OAAO,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,CAAA;YACnC,CAAC;YACD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvB,MAAM,SAAS,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAA;gBACnF,OAAO,CAAC,QAAQ,GAAG,UAAU,CAAC,SAAS,CAAC,CAAA;YAC1C,CAAC;YACD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,MAAM,WAAW,GAAG,IAAI,kBAAkB,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAA;gBACnE,KAAK,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,OAAO,EAAE,CAAC;oBAC/B,MAAM,UAAU,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAA;oBAC3E,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,CAC3B,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,oBAAoB,CAAC,GAAG,CAAC,CAAC,CAC3E,CAAA;oBACD,MAAM,WAAW,CAAC,GAAG,CAAC,UAAU,EAAE,UAAU,CAAC,CAAA;gBAC/C,CAAC;gBACD,OAAO,CAAC,WAAW,GAAG,WAAW,CAAC,IAAI,EAAE,CAAA;YAC1C,CAAC;YACD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,OAAO,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;YAC/B,CAAC;QACH,CAAC;QACD,MAAM,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAA;IAC9C,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,EAAE,CAAA;AACpB,CAAC"}

package/dist/esm/util/hex.d.ts

@@ -0,0 +1,20 @@
+import type { Nibbles } from '../types.ts';
+/**
+ * Prepends hex prefix to an array of nibbles.
+ * @param key - Array of nibbles
+ * @returns returns buffer of encoded data
+ **/
+export declare function addHexPrefix(key: Nibbles, terminator: boolean): Nibbles;
+/**
+ * Removes hex prefix of an array of nibbles.
+ * @param val - Array of nibbles
+ * @private
+ */
+export declare function removeHexPrefix(val: Nibbles): Nibbles;
+/**
+ * Returns true if hex-prefixed path is for a terminating (leaf) node.
+ * @param key - a hex-prefixed array of nibbles
+ * @private
+ */
+export declare function isTerminator(key: Nibbles): boolean;
+//# sourceMappingURL=hex.d.ts.map

package/dist/esm/util/hex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hex.d.ts","sourceRoot":"","sources":["../../../src/util/hex.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAE1C;;;;IAII;AACJ,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,GAAG,OAAO,CAevE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAQrD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAElD"}

package/dist/esm/util/hex.js

@@ -0,0 +1,43 @@
+/**
+ * Prepends hex prefix to an array of nibbles.
+ * @param key - Array of nibbles
+ * @returns returns buffer of encoded data
+ **/
+export function addHexPrefix(key, terminator) {
+    // odd
+    if (key.length % 2) {
+        key.unshift(1);
+    }
+    else {
+        // even
+        key.unshift(0);
+        key.unshift(0);
+    }
+    if (terminator) {
+        key[0] += 2;
+    }
+    return key;
+}
+/**
+ * Removes hex prefix of an array of nibbles.
+ * @param val - Array of nibbles
+ * @private
+ */
+export function removeHexPrefix(val) {
+    if (val[0] % 2) {
+        val = val.slice(1);
+    }
+    else {
+        val = val.slice(2);
+    }
+    return val;
+}
+/**
+ * Returns true if hex-prefixed path is for a terminating (leaf) node.
+ * @param key - a hex-prefixed array of nibbles
+ * @private
+ */
+export function isTerminator(key) {
+    return key[0] > 1;
+}
+//# sourceMappingURL=hex.js.map

package/dist/esm/util/hex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hex.js","sourceRoot":"","sources":["../../../src/util/hex.ts"],"names":[],"mappings":"AAEA;;;;IAII;AACJ,MAAM,UAAU,YAAY,CAAC,GAAY,EAAE,UAAmB;IAC5D,MAAM;IACN,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnB,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;IAChB,CAAC;SAAM,CAAC;QACN,OAAO;QACP,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;QACd,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;IAChB,CAAC;IAED,IAAI,UAAU,EAAE,CAAC;QACf,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;IACb,CAAC;IAED,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;QACf,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;IACpB,CAAC;SAAM,CAAC;QACN,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;IACpB,CAAC;IAED,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,OAAO,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;AACnB,CAAC"}

package/dist/esm/util/index.d.ts

@@ -0,0 +1,4 @@
+export * from './encoding.ts';
+export * from './genesisState.ts';
+export * from './walkController.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/util/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/util/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAA;AAC7B,cAAc,mBAAmB,CAAA;AACjC,cAAc,qBAAqB,CAAA"}

package/dist/esm/util/index.js

@@ -0,0 +1,4 @@
+export * from "./encoding.js";
+export * from "./genesisState.js";
+export * from "./walkController.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/util/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/util/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAA;AAC7B,cAAc,mBAAmB,CAAA;AACjC,cAAc,qBAAqB,CAAA"}

package/dist/esm/util/nibbles.d.ts

@@ -0,0 +1,30 @@
+import type { Nibbles } from '../types.ts';
+/**
+ * Converts a bytes to a nibble array.
+ * @private
+ * @param key
+ */
+export declare function bytesToNibbles(key: Uint8Array): Nibbles;
+/**
+ * Converts a nibble array into bytes.
+ * @private
+ * @param arr - Nibble array
+ */
+export declare function nibblesTypeToPackedBytes(arr: Nibbles): Uint8Array;
+/**
+ * Compare two nibble array.
+ * * `0` is returned if `n2` === `n1`.
+ * * `1` is returned if `n2` > `n1`.
+ * * `-1` is returned if `n2` < `n1`.
+ * @param n1 - Nibble array
+ * @param n2 - Nibble array
+ */
+export declare function nibblesCompare(n1: Nibbles, n2: Nibbles): number;
+/**
+ * Returns the number of in order matching nibbles of two give nibble arrays.
+ * @private
+ * @param nib1
+ * @param nib2
+ */
+export declare function matchingNibbleLength(nib1: Nibbles, nib2: Nibbles): number;
+//# sourceMappingURL=nibbles.d.ts.map

package/dist/esm/util/nibbles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nibbles.d.ts","sourceRoot":"","sources":["../../../src/util/nibbles.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAE1C;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAWvD;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,CAOjE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,UAuBtD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CAMzE"}

package/dist/esm/util/nibbles.js

@@ -0,0 +1,73 @@
+/**
+ * Converts a bytes to a nibble array.
+ * @private
+ * @param key
+ */
+export function bytesToNibbles(key) {
+    const nibbles = [];
+    for (let i = 0; i < key.length; i++) {
+        let q = i * 2;
+        nibbles[q] = key[i] >> 4;
+        ++q;
+        nibbles[q] = key[i] % 16;
+    }
+    return nibbles;
+}
+/**
+ * Converts a nibble array into bytes.
+ * @private
+ * @param arr - Nibble array
+ */
+export function nibblesTypeToPackedBytes(arr) {
+    const buf = new Uint8Array(arr.length / 2);
+    for (let i = 0; i < buf.length; i++) {
+        let q = i * 2;
+        buf[i] = (arr[q] << 4) + arr[++q];
+    }
+    return buf;
+}
+/**
+ * Compare two nibble array.
+ * * `0` is returned if `n2` === `n1`.
+ * * `1` is returned if `n2` > `n1`.
+ * * `-1` is returned if `n2` < `n1`.
+ * @param n1 - Nibble array
+ * @param n2 - Nibble array
+ */
+export function nibblesCompare(n1, n2) {
+    const cmpLength = Math.min(n1.length, n2.length);
+    let res = 0;
+    for (let i = 0; i < cmpLength; i++) {
+        if (n1[i] < n2[i]) {
+            res = -1;
+            break;
+        }
+        else if (n1[i] > n2[i]) {
+            res = 1;
+            break;
+        }
+    }
+    if (res === 0) {
+        if (n1.length < n2.length) {
+            res = -1;
+        }
+        else if (n1.length > n2.length) {
+            res = 1;
+        }
+    }
+    return res;
+}
+/**
+ * Returns the number of in order matching nibbles of two give nibble arrays.
+ * @private
+ * @param nib1
+ * @param nib2
+ */
+export function matchingNibbleLength(nib1, nib2) {
+    let i = 0;
+    while (nib1[i] === nib2[i] && nib1.length > i) {
+        i++;
+    }
+    return i;
+}
+//# sourceMappingURL=nibbles.js.map

package/dist/esm/util/nibbles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nibbles.js","sourceRoot":"","sources":["../../../src/util/nibbles.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,GAAe;IAC5C,MAAM,OAAO,GAAG,EAAa,CAAA;IAE7B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACb,OAAO,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;QACxB,EAAE,CAAC,CAAA;QACH,OAAO,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAA;IAC1B,CAAC;IAED,OAAO,OAAO,CAAA;AAChB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAY;IACnD,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAC1C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACb,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC,CAAC,CAAA;IACnC,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,EAAW,EAAE,EAAW;IACrD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,CAAA;IAEhD,IAAI,GAAG,GAAG,CAAC,CAAA;IACX,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC;QACnC,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAClB,GAAG,GAAG,CAAC,CAAC,CAAA;YACR,MAAK;QACP,CAAC;aAAM,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzB,GAAG,GAAG,CAAC,CAAA;YACP,MAAK;QACP,CAAC;IACH,CAAC;IAED,IAAI,GAAG,KAAK,CAAC,EAAE,CAAC;QACd,IAAI,EAAE,CAAC,MAAM,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC;YAC1B,GAAG,GAAG,CAAC,CAAC,CAAA;QACV,CAAC;aAAM,IAAI,EAAE,CAAC,MAAM,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC;YACjC,GAAG,GAAG,CAAC,CAAA;QACT,CAAC;IACH,CAAC;IAED,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAa,EAAE,IAAa;IAC/D,IAAI,CAAC,GAAG,CAAC,CAAA;IACT,OAAO,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9C,CAAC,EAAE,CAAA;IACL,CAAC;IACD,OAAO,CAAC,CAAA;AACV,CAAC"}

package/dist/esm/util/walkController.d.ts

@@ -0,0 +1,72 @@
+import { PrioritizedTaskExecutor } from '@feelyourprotocol/util';
+import { BranchMPTNode } from '../node/index.ts';
+import type { MerklePatriciaTrie } from '../mpt.ts';
+import type { FoundNodeFunction, MPTNode, Nibbles, NodeReferenceOrRawMPTNode } from '../types.ts';
+/**
+ * Interface to control how the trie is being traversed. Schedules node visits via a
+ * prioritized task queue and invokes the provided callback for each node.
+ *
+ * Used by {@link MerklePatriciaTrie.findPath}, {@link MerklePatriciaTrie.walkTrie}, etc.
+ */
+export declare class WalkController {
+    /** The {@link FoundNodeFunction} to call when a node is found. */
+    readonly onNode: FoundNodeFunction;
+    /** Task executor that prioritizes node visits (shorter paths first). */
+    readonly taskExecutor: PrioritizedTaskExecutor;
+    /** The trie being walked. */
+    readonly trie: MerklePatriciaTrie;
+    private _resolvePromise;
+    private _rejectPromise;
+    /**
+     * @param onNode - The {@link FoundNodeFunction} to call when a node is found.
+     * @param trie - The trie to walk on.
+     * @param poolSize - The size of the task queue.
+     */
+    private constructor();
+    /**
+     * Creates and starts an async walk over a trie from the given root.
+     * Resolves when all reachable nodes have been visited and no new tasks were scheduled.
+     *
+     * @param onNode - The {@link FoundNodeFunction} to call when a node is found.
+     * @param trie - The trie to walk on.
+     * @param rootHash - The root hash (32-byte keccak) to start walking from.
+     * @param poolSize - Task execution pool size to prevent OOM errors. Defaults to 500.
+     * @returns A Promise that resolves when the walk is finished.
+     */
+    static newWalk(onNode: FoundNodeFunction, trie: MerklePatriciaTrie, rootHash: Uint8Array, poolSize?: number): Promise<void>;
+    private _startWalk;
+    /**
+     * Runs all children of a node. Priority of these nodes is the key length of the children.
+     * Used when walking an Extension or when exploring all branches of a Branch node.
+     *
+     * @param node - Node to get all children of and call onNode on.
+     * @param currentKeyNibbles - The current key (nibbles) which would yield the `node` when
+     *        trying to get this node with a `get` operation. Defaults to `[]`.
+     * @returns `void`
+     */
+    allChildren(node: MPTNode, currentKeyNibbles?: Nibbles): void;
+    /**
+     * Pushes a node to the queue. If the queue has capacity, the node is executed immediately,
+     * otherwise it is queued for later execution.
+     *
+     * @param nodeRef - A node reference (32-byte keccak hash or raw encoding) to enqueue.
+     * @param currentKeyNibbles - The current key (nibbles) corresponding to this node. Defaults to `[]`.
+     * @param priority - Optional priority. Defaults to key length.
+     * @returns `void`
+     */
+    pushNodeToQueue(nodeRef: NodeReferenceOrRawMPTNode, currentKeyNibbles?: Nibbles, priority?: number): void;
+    /**
+     * Pushes a branch of a certain BranchMPTNode to the event queue.
+     * Used by findPath when following a specific key (only one child index is traversed).
+     *
+     * @param node - The BranchMPTNode to select a branch on.
+     * @param currentKeyNibbles - The current key which leads to the corresponding node. Defaults to `[]`.
+     * @param childIndex - The child index (0–15) to add to the event queue.
+     * @param priority - Optional priority of the event. Defaults to the total key length.
+     * @returns `void`
+     * @throws If `node` is not a BranchMPTNode or if the branch at `childIndex` is empty.
+     */
+    onlyBranchIndex(node: BranchMPTNode, currentKeyNibbles: Nibbles | undefined, childIndex: number, priority?: number): void;
+    private _processNode;
+}
+//# sourceMappingURL=walkController.d.ts.map

package/dist/esm/util/walkController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walkController.d.ts","sourceRoot":"","sources":["../../../src/util/walkController.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,uBAAuB,EAAE,MAAM,kBAAkB,CAAA;AAEtF,OAAO,EAAE,aAAa,EAAiC,MAAM,kBAAkB,CAAA;AAE/E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAA;AAEjG;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;IAElC,wEAAwE;IACxE,QAAQ,CAAC,YAAY,EAAE,uBAAuB,CAAA;IAE9C,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAA;IAEjC,OAAO,CAAC,eAAe,CAAY;IACnC,OAAO,CAAC,cAAc,CAA0B;IAEhD;;;;OAIG;IACH,OAAO;IAQP;;;;;;;;;OASG;WACU,OAAO,CAClB,MAAM,EAAE,iBAAiB,EACzB,IAAI,EAAE,kBAAkB,EACxB,QAAQ,EAAE,UAAU,EACpB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC;YAKF,UAAU;IAexB;;;;;;;;OAQG;IACH,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,iBAAiB,GAAE,OAAY,GAAG,IAAI;IAqBjE;;;;;;;;OAQG;IACH,eAAe,CACb,OAAO,EAAE,yBAAyB,EAClC,iBAAiB,GAAE,OAAY,EAC/B,QAAQ,CAAC,EAAE,MAAM,GAChB,IAAI;IAeP;;;;;;;;;;OAUG;IACH,eAAe,CACb,IAAI,EAAE,aAAa,EACnB,iBAAiB,EAAE,OAAO,YAAK,EAC/B,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB,IAAI;IAaP,OAAO,CAAC,YAAY;CAUrB"}