@feelyourprotocol/binarytree 8141.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 EthereumJS 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,46 @@
+# @ethereumjs/binarytree `v10` (EXPERIMENTAL)
+
+[![NPM Package][binarytree-npm-badge]][binarytree-npm-link]
+[![GitHub Issues][binarytree-issues-badge]][binarytree-issues-link]
+[![Actions Status][binarytree-actions-badge]][binarytree-actions-link]
+[![Code Coverage][binarytree-coverage-badge]][binarytree-coverage-link]
+[![Discord][discord-badge]][discord-link]
+
+| Implementation of Binary Trees as specified in [EIP-7864](https://eips.ethereum.org/EIPS/eip-7864) |
+| --------------------------------------------------------------------------------------------------------------------------------------------------- |
+
+> Binary Trees are a novel cryptographic data structure proposed for use in Ethereum to optimize state storage and proof verification. Unlike Merkle Patricia Tries, Binary Trees use a strict binary branching structure, allowing smaller proof sizes. By reducing storage overhead and improving proof efficiency, Binary Trees aim to enhance Ethereum’s scalability while maintaining robust security guarantees.
+
+**Note:** This library is in an **experimental** stage and should not be used in production!
+
+## Table of Contents
+
+- [Installation](#installation)
+- [EthereumJS](#ethereumjs)
+- [License](#license)
+
+## Installation
+
+To obtain the latest version, simply install the project using `npm`:
+
+```shell
+npm install @ethereumjs/binarytree
+```
+## EthereumJS
+
+The `EthereumJS` GitHub organization and its repositories are managed by members of the former Ethereum Foundation JavaScript team and the broader Ethereum community. If you want to join for work or carry out improvements on the libraries see the [developer docs](../../DEVELOPER.md) for an overview of current standards and tools and review our [code of conduct](../../CODE_OF_CONDUCT.md).
+
+## License
+
+[MIT](https://opensource.org/licenses/MIT)
+
+[discord-badge]: https://img.shields.io/static/v1?logo=discord&label=discord&message=Join&color=blue
+[discord-link]: https://discord.gg/TNwARpR
+[binarytree-npm-badge]: https://img.shields.io/npm/v/@ethereumjs/binarytree.svg
+[binarytree-npm-link]: https://www.npmjs.com/package/@ethereumjs/binarytree
+[binarytree-issues-badge]: https://img.shields.io/github/issues/ethereumjs/ethereumjs-monorepo/package:%20binarytree?label=issues
+[binarytree-issues-link]: https://github.com/ethereumjs/ethereumjs-monorepo/issues?q=is%3Aopen+is%3Aissue+label%3A"package%3A+binarytree"
+[binarytree-actions-badge]: https://github.com/ethereumjs/ethereumjs-monorepo/workflows/binarytree/badge.svg
+[binarytree-actions-link]: https://github.com/ethereumjs/ethereumjs-monorepo/actions?query=workflow%3A%22binarytree%22
+[binarytree-coverage-badge]: https://codecov.io/gh/ethereumjs/ethereumjs-monorepo/branch/master/graph/badge.svg?flag=binarytree
+[binarytree-coverage-link]: https://codecov.io/gh/ethereumjs/ethereumjs-monorepo/tree/master/packages/binarytree

package/dist/cjs/binaryTree.d.ts

@@ -0,0 +1,167 @@
+import { Lock } from '@feelyourprotocol/util';
+import { CheckpointDB } from './db/index.ts';
+import { StemBinaryNode } from './node/stemNode.ts';
+import { type BinaryTreeOpts } from './types.ts';
+import type { Debugger } from 'debug';
+import type { BinaryNode } from './node/types.ts';
+interface Path {
+    node: BinaryNode | null;
+    remaining: number[];
+    stack: Array<[BinaryNode, number[]]>;
+}
+/**
+ * The basic binary tree interface, use with `import { BinaryTree } from '@feelyourprotocol/binarytree'`.
+ *
+ * A BinaryTree object can be created with the constructor method:
+ *
+ * - {@link createBinaryTree}
+ */
+export declare class BinaryTree {
+    /** The options for instantiating the binary tree */
+    protected _opts: BinaryTreeOpts;
+    /** The root for an empty tree */
+    EMPTY_TREE_ROOT: Uint8Array;
+    protected _db: CheckpointDB;
+    protected _hashLen: number;
+    protected _lock: Lock;
+    protected _root: Uint8Array;
+    protected DEBUG: boolean;
+    protected _debug: Debugger;
+    protected debug: (...args: any) => void;
+    /**
+     * Creates a new binary tree.
+     * @param opts Options for instantiating the binary tree
+     *
+     * Note: in most cases, the static {@link createBinaryTree} constructor should be used. It uses the same API but provides sensible defaults
+     */
+    constructor(opts: BinaryTreeOpts);
+    /**
+     * Gets and/or Sets the current root of the `tree`
+     */
+    root(value?: Uint8Array | null): Uint8Array;
+    /**
+     * Checks if a given root exists.
+     */
+    checkRoot(root: Uint8Array): Promise<boolean>;
+    /**
+     * Gets values at a given binary tree `stem` and set of suffixes
+     * @param stem - the stem of the stem node where we're seeking values
+     * @param suffixes - an array of suffixes corresponding to the values desired
+     * @returns A Promise that resolves to an array of `Uint8Array`s or `null` depending on if values were found.
+     * If the stem is not found, will return an empty array.
+     */
+    get(stem: Uint8Array, suffixes: number[]): Promise<(Uint8Array | null)[]>;
+    /**
+     * Stores a given `value` at the given `key` or performs a deletion if `value` is null.
+     * @param stem - the stem (must be 31 bytes) to store the value at.
+     * @param suffixes - array of suffixes at which to store individual values.
+     * @param values - the value(s) to store (or null for deletion).
+     * @returns A Promise that resolves once the value is stored.
+     */
+    put(stem: Uint8Array, suffixes: number[], values: (Uint8Array | null)[]): Promise<void>;
+    /**
+     * Helper method for updating or creating the parent internal node for a given stem node.
+     * If the nearest node is a stem node with a different stem, a new internal node is created
+     * to branch at the first differing bit.
+     * If the nearest node is an internal node, its child reference is updated.
+     *
+     * @param stemNode - The child stem node that will be referenced by the new/updated internal node.
+     * @param nearestNode - The nearest node to the new stem node.
+     * @param pathToNode - The path (in bits) to `nearestNode` as known from the trie.
+     * @returns An array of nodes and their partial paths from the new stem node to the branch parent node
+     *          or `undefined` if no changes were made.
+     */
+    updateBranch(stemNode: StemBinaryNode, nearestNode: BinaryNode, pathToNode: number[], pathToParent: number[]): {
+        node: BinaryNode;
+        parentPath: number[];
+    }[] | undefined;
+    /**
+     * Tries to find a path to the node for the given key.
+     * It returns a `Path` object containing:
+     *   - `node`: the found node (if any),
+     *   - `stack`: an array of tuples [node, path] representing the nodes encountered,
+     *   - `remaining`: the bits of the key that were not matched.
+     *
+     * @param keyInBytes - the search key as a byte array.
+     * @returns A Promise that resolves to a Path object.
+     */
+    findPath(keyInBytes: Uint8Array): Promise<Path>;
+    /**
+     * Deletes a given `key` from the tree.
+     * @param stem - the stem of the stem node to delete from
+     * @param suffixes - the suffixes to delete
+     * @returns A Promise that resolves once the key is deleted.
+     */
+    del(stem: Uint8Array, suffixes: number[]): Promise<void>;
+    /**
+     * Create empty root node for initializing an empty tree.
+     */
+    createRootNode(): Promise<void>;
+    /**
+     * Creates the initial node from an empty tree.
+     * @private
+     */
+    protected _createInitialNode(stem: Uint8Array, indexes: number[], values: (Uint8Array | null)[]): Promise<void>;
+    /**
+     * Saves a stack of nodes to the database.
+     *
+     * @param putStack - an array of tuples of keys (the partial path of the node in the trie) and nodes (BinaryNodes)
+     */
+    saveStack(putStack: [Uint8Array, BinaryNode | null][]): Promise<void>;
+    /**
+     * Creates a proof from a tree and key that can be verified using {@link BinaryTree.verifyBinaryProof}.
+     * @param key a 32 byte binary tree key (31 byte stem + 1 byte suffix)
+     */
+    createBinaryProof(key: Uint8Array): Promise<Uint8Array[]>;
+    /**
+     * The `data` event is given an `Object` that has two properties; the `key` and the `value`. Both should be Uint8Arrays.
+     * @return Returns a [stream](https://nodejs.org/dist/latest-v12.x/docs/api/stream.html#stream_class_stream_readable) of the contents of the `tree`
+     */
+    createReadStream(): any;
+    /**
+     * Returns a copy of the underlying tree.
+     *
+     * Note on db: the copy will create a reference to the
+     * same underlying database.
+     *
+     * Note on cache: for memory reasons a copy will not
+     * recreate a new LRU cache but initialize with cache
+     * being deactivated.
+     *
+     * @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): BinaryTree;
+    /**
+     * Persists the root hash in the underlying database
+     */
+    persistRoot(): Promise<void>;
+    /**
+     * Is the tree 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 tree 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;
+    protected hash(msg: Uint8Array | null): Uint8Array;
+    protected merkelize(node: BinaryNode | null): Uint8Array;
+}
+export {};
+//# sourceMappingURL=binaryTree.d.ts.map

package/dist/cjs/binaryTree.d.ts.map

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