@feelyourprotocol/mpt 8141.0.0

package/dist/esm/db/index.js

@@ -0,0 +1,2 @@
+export * from "./checkpointDB.js";
+//# sourceMappingURL=index.js.map

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

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

package/dist/esm/index.d.ts

@@ -0,0 +1,8 @@
+export * from './constructors.ts';
+export * from './db/index.ts';
+export * from './mpt.ts';
+export * from './node/index.ts';
+export * from './proof/index.ts';
+export * from './types.ts';
+export * from './util/index.ts';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,cAAc,eAAe,CAAA;AAC7B,cAAc,UAAU,CAAA;AACxB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA;AAChC,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA"}

package/dist/esm/index.js

@@ -0,0 +1,8 @@
+export * from "./constructors.js";
+export * from "./db/index.js";
+export * from "./mpt.js";
+export * from "./node/index.js";
+export * from "./proof/index.js";
+export * from "./types.js";
+export * from "./util/index.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,cAAc,eAAe,CAAA;AAC7B,cAAc,UAAU,CAAA;AACxB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA;AAChC,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA"}

package/dist/esm/mpt.d.ts

@@ -0,0 +1,261 @@
+import { Lock, ValueEncoding } from '@feelyourprotocol/util';
+import { CheckpointDB } from './db/checkpointDB.ts';
+import type { BatchDBOp, DB } from '@feelyourprotocol/util';
+import type { Debugger } from 'debug';
+import type { BranchMPTNodeBranchValue, FoundNodeFunction, MPTNode, MPTOpts, MPTOptsWithDefaults, Nibbles, NodeReferenceOrRawMPTNode, Path, TrieShallowCopyOpts } from './types.ts';
+import type { OnFound } from './util/asyncWalk.ts';
+/**
+ * The basic trie interface, use with `import { MerklePatriciaTrie } from '@feelyourprotocol/mpt'`.
+ *
+ * A MerklePatriciaTrie object can be created with the constructor method:
+ *
+ * - {@link createMPT}
+ *
+ * A sparse MerklePatriciaTrie object can be created from a merkle proof:
+ *
+ * - {@link createMPTFromProof}
+ */
+/**
+ * Merkle Patricia Trie - a space-optimized trie where each node with only one child
+ * is merged with its parent. Used for Ethereum state and storage.
+ *
+ * Node types:
+ * - Branch: 16-way branch + optional value (for keys ending at this node)
+ * - Extension: short path (nibbles) → child node
+ * - Leaf: remaining path (nibbles) → value
+ */
+export declare class MerklePatriciaTrie {
+    /** Options with defaults applied */
+    protected readonly _opts: MPTOptsWithDefaults;
+    /** The root for an empty trie */
+    EMPTY_TRIE_ROOT: Uint8Array;
+    /** The backend DB */
+    protected _db: CheckpointDB;
+    protected _hashLen: number;
+    protected _lock: Lock;
+    protected _root: Uint8Array;
+    /** Debug logging */
+    protected DEBUG: boolean;
+    protected _debug: Debugger;
+    protected debug: (...args: any) => void;
+    /**
+     * Creates a new trie.
+     * @param opts Options for instantiating the trie
+     *
+     * Note: in most cases, {@link createMPT} constructor should be used.  It uses the same API but provides sensible defaults
+     */
+    constructor(opts?: MPTOpts);
+    database(db?: DB<string, string | Uint8Array>, valueEncoding?: ValueEncoding): CheckpointDB;
+    /**
+     * Gets and/or Sets the current root of the `trie`
+     */
+    root(value?: Uint8Array | null): Uint8Array;
+    /**
+     * Checks if a given root exists.
+     */
+    checkRoot(root: Uint8Array): Promise<boolean>;
+    /**
+     * Gets a value given a `key`
+     * @param key - the key to search for
+     * @param throwIfMissing - if true, throws if any nodes are missing. Used for verifying proofs. (default: false)
+     * @returns A Promise that resolves to `Uint8Array` if a value was found or `null` if no value was found.
+     */
+    get(key: Uint8Array, throwIfMissing?: boolean): Promise<Uint8Array | null>;
+    /**
+     * Stores a given `value` at the given `key` or do a delete if `value` is empty
+     * (delete operations are only executed on DB with `deleteFromDB` set to `true`)
+     * @param key
+     * @param value
+     * @returns A Promise that resolves once value is stored.
+     */
+    put(key: Uint8Array, value: Uint8Array | null, skipKeyTransform?: boolean): Promise<void>;
+    /**
+     * Deletes a value given a `key` from the trie
+     * (delete operations are only executed on DB with `deleteFromDB` set to `true`)
+     * @param key
+     * @returns A Promise that resolves once value is deleted.
+     */
+    del(key: Uint8Array, skipKeyTransform?: boolean): Promise<void>;
+    /**
+     * Finds the path from root to the node for the given key.
+     * Walks the trie, matching nibbles at each level. Returns the target node (if found)
+     * and the stack of nodes along the path (needed for updates/deletes).
+     *
+     * @param key - the search key (bytes)
+     * @param throwIfMissing - if true, throws when nodes are missing (e.g. proof verification)
+     * @param partialPath - optional pre-loaded stack for resuming from a mid-path node
+     */
+    findPath(key: Uint8Array, throwIfMissing?: boolean, partialPath?: {
+        stack: MPTNode[];
+    }): Promise<Path>;
+    /**
+     * Walks a trie until finished.
+     * @param root
+     * @param onFound - callback to call when a node is found. This schedules new tasks. If no tasks are available, the Promise resolves.
+     * @returns Resolves when finished walking trie.
+     */
+    walkTrie(root: Uint8Array, onFound: FoundNodeFunction): Promise<void>;
+    walkTrieIterable: (nodeHash: Uint8Array<ArrayBufferLike>, currentKey?: number[] | undefined, onFound?: OnFound | undefined, filter?: import("./util/asyncWalk.ts").NodeFilter | undefined, visited?: Set<string> | undefined) => AsyncIterable<{
+        node: MPTNode;
+        currentKey: number[];
+    }>;
+    /**
+     * Executes a callback for each node in the trie.
+     * @param onFound - callback to call when a node is found.
+     * @returns Resolves when finished walking trie.
+     */
+    walkAllNodes(onFound: OnFound): Promise<void>;
+    /**
+     * Executes a callback for each value node in the trie.
+     * @param onFound - callback to call when a node is found.
+     * @returns Resolves when finished walking trie.
+     */
+    walkAllValueNodes(onFound: OnFound): Promise<void>;
+    /**
+     * Creates the initial leaf node when inserting into an empty trie.
+     * @private
+     */
+    protected _createInitialNode(key: Uint8Array, value: Uint8Array): Promise<void>;
+    /**
+     * Retrieves a node from db by hash.
+     */
+    lookupNode(node: Uint8Array | Uint8Array[]): Promise<MPTNode>;
+    /**
+     * True when we're updating an existing leaf value (key already exists, no structural change).
+     * @private
+     */
+    protected _isMatchingLeafUpdate(lastNode: MPTNode, stack: MPTNode[], fullKeyNibbles: Nibbles, keyRemainder: Nibbles): boolean;
+    /**
+     * Applies a value update given the path from findPath. Modifies the stack in-place
+     * to represent the new structure, then calls saveStack to persist.
+     *
+     * Three cases:
+     * 1. Match leaf: key exists, just update value (no structure change)
+     * 2. Branch: add new leaf to branch, or set branch value
+     * 3. Extension/Leaf with diverging path: create new branch at divergence, re-hang old + new leaf
+     *
+     * @private
+     */
+    protected _updateNode(keyBytes: Uint8Array, value: Uint8Array, keyRemainder: Nibbles, stack: MPTNode[]): Promise<void>;
+    /**
+     * Removes a key from the trie. Handles two main cases:
+     * - Deleting from a leaf: remove leaf, possibly collapse parent branch
+     * - Deleting from a branch value: clear value, possibly collapse if branch has single child
+     *
+     * When a branch ends up with only one child after deletion, we collapse it into
+     * an extension (or merge with parent extension) to keep the trie minimal.
+     *
+     * @private
+     */
+    protected _deleteNode(keyBytes: Uint8Array, stack: MPTNode[]): Promise<void>;
+    /**
+     * Persists the modified node stack to the DB. Processes nodes from leaf toward root,
+     * wiring each node's references (extension value, branch slot) to its child's hash.
+     *
+     * @param key - nibble path that corresponds to the stack
+     * @param stack - nodes from findPath/update, bottom (leaf) to top (root)
+     * @param opStack - put/del operations accumulated by _formatNode
+     */
+    saveStack(pathNibbles: Nibbles, stack: MPTNode[], opStack: BatchDBOp[]): Promise<void>;
+    /**
+     * Serializes a node and either stores it (put) or schedules removal (del).
+     * Nodes ≥32 bytes (or top-level) are hashed and stored; smaller nodes are inlined as raw.
+     *
+     * @param node - the node to persist
+     * @param topLevel - if true, always store (root must be in DB)
+     * @param opStack - accumulates put/del operations for batch commit
+     * @param remove - if true, schedule del (used when pruning)
+     * @returns hash (for references) or raw encoding (for inline)
+     */
+    _formatNode(node: MPTNode, topLevel: boolean, opStack: BatchDBOp[], remove?: boolean): Uint8Array | NodeReferenceOrRawMPTNode | BranchMPTNodeBranchValue[];
+    /**
+     * The given hash of operations (key additions or deletions) are executed on the trie
+     * (delete operations are only executed on DB with `deleteFromDB` set to `true`)
+     * @example
+     * const ops = [
+     *    { type: 'del', key: Uint8Array.from('father') }
+     *  , { type: 'put', key: Uint8Array.from('name'), value: Uint8Array.from('Yuri Irsenovich Kim') } // cspell:disable-line
+     *  , { type: 'put', key: Uint8Array.from('dob'), value: Uint8Array.from('16 February 1941') }
+     *  , { type: 'put', key: Uint8Array.from('spouse'), value: Uint8Array.from('Kim Young-sook') } // cspell:disable-line
+     *  , { type: 'put', key: Uint8Array.from('occupation'), value: Uint8Array.from('Clown') }
+     * ]
+     * await trie.batch(ops)
+     * @param ops
+     */
+    batch(ops: BatchDBOp[], skipKeyTransform?: boolean): Promise<void>;
+    /**
+     * Verifies that every key in the DB is reachable from the root. Used to ensure
+     * pruning is correct – unreachable keys indicate a bug or corrupt state.
+     */
+    verifyPrunedIntegrity(): Promise<boolean>;
+    /**
+     * Returns a copy of the underlying trie.
+     *
+     * Note on db: the copy will create a reference to the
+     * same underlying database.
+     *
+     * Note on cache: for memory reasons a copy will by default
+     * not recreate a new LRU cache but initialize with cache
+     * being deactivated. This behavior can be overwritten by
+     * explicitly setting `cacheSize` as an option on the method.
+     *
+     * @param includeCheckpoints - If true and during a checkpoint, the copy will contain the checkpointing metadata and will use the same scratch as underlying db.
+     */
+    shallowCopy(includeCheckpoints?: boolean, opts?: TrieShallowCopyOpts): MerklePatriciaTrie;
+    /**
+     * Persists the root hash in the underlying database
+     */
+    persistRoot(): Promise<void>;
+    /**
+     * Finds all nodes that are stored directly in the db
+     * (some nodes are stored raw inside other nodes)
+     * called by {@link ScratchReadStream}
+     * @private
+     */
+    protected _findDbNodes(onFound: FoundNodeFunction): Promise<void>;
+    /** Applies keyPrefix to a hash when multiple tries share a DB. */
+    protected _getDbKey(hash: Uint8Array): Uint8Array;
+    /** Builds del ops for nodes that will be replaced (pruning). */
+    protected _createPruneDeleteOps(stack: MPTNode[]): BatchDBOp[];
+    /** Applies key hashing (keccak) when useKeyHashing is enabled (Ethereum-style). */
+    protected appliedKey(key: Uint8Array): Uint8Array<ArrayBufferLike>;
+    protected hash(inputBytes: Uint8Array): Uint8Array;
+    /**
+     * Is the trie during a checkpoint phase?
+     */
+    hasCheckpoints(): boolean;
+    /**
+     * Creates a checkpoint that can later be reverted to or committed.
+     * After this is called, all changes can be reverted until `commit` is called.
+     */
+    checkpoint(): void;
+    /**
+     * Commits a checkpoint to disk, if current checkpoint is not nested.
+     * If nested, only sets the parent checkpoint as current checkpoint.
+     * @throws If not during a checkpoint phase
+     */
+    commit(): Promise<void>;
+    /**
+     * Reverts the trie to the state it was at when `checkpoint` was first called.
+     * If during a nested checkpoint, sets root to most recent checkpoint, and sets
+     * parent checkpoint as current.
+     */
+    revert(): Promise<void>;
+    /**
+     * Flushes all checkpoints, restoring the initial checkpoint state.
+     */
+    flushCheckpoints(): void;
+    /**
+     * Returns a list of values stored in the trie
+     * @param startKey first unhashed key in the range to be returned (defaults to 0).  Note, all keys must be of the same length or undefined behavior will result
+     * @param limit - the number of keys to be returned (undefined means all keys)
+     * @returns an object with two properties (a map of all key/value pairs in the trie - or in the specified range) and then a `nextKey` reference if a range is specified
+     */
+    getValueMap(startKey?: bigint, limit?: number): Promise<{
+        values: {
+            [key: string]: string;
+        };
+        nextKey: null | string;
+    }>;
+}
+//# sourceMappingURL=mpt.d.ts.map

package/dist/esm/mpt.d.ts.map

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