feat(l1): add PBT (8297)

Cargo.toml

@@ -7,6 +7,7 @@ members = [
   "crates/common",
   "crates/common/rlp",
   "crates/common/trie",
+  "crates/common/binary-trie",
   "crates/common/crypto",
   "crates/l2/",
   "crates/l2/common",
@@ -77,6 +78,7 @@ ethrex-storage = { path = "./crates/storage", version = "22.0.0" }
 ethrex-vm = { path = "./crates/vm", version = "22.0.0", default-features = false }
 ethrex-levm = { path = "./crates/vm/levm", version = "22.0.0" }
 ethrex-trie = { path = "./crates/common/trie", version = "22.0.0" }
+ethrex-binary-trie = { path = "./crates/common/binary-trie", version = "22.0.0" }
 ethrex-rlp = { path = "./crates/common/rlp", version = "22.0.0" }
 ethrex-crypto = { path = "./crates/common/crypto", version = "22.0.0", default-features = false }
 ethrex-metrics = { path = "./crates/blockchain/metrics", version = "22.0.0" }
@@ -108,6 +110,7 @@ hex-literal = "0.4.1"
 crc32fast = "1.4.2"
 lazy_static = "1.5.0"
 lru = "0.16.2"
+blake3 = "1"
 sha2 = "0.10.9"
 sha3 = "0.10.8"
 tokio-util = { version = "0.7.15", features = ["rt"] }

crates/common/binary-trie/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "ethrex-binary-trie"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+documentation.workspace = true
+license.workspace = true
+description = "EIP-8297 Partitioned Binary Tree for the ethrex Ethereum execution client"
+repository.workspace = true
+
+[dependencies]
+ethereum-types.workspace = true
+blake3.workspace = true
+thiserror.workspace = true
+
+[dev-dependencies]
+hex.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+hex-literal.workspace = true
+
+[lints]
+workspace = true

crates/common/binary-trie/README.md

@@ -0,0 +1,53 @@
+## Ethrex-Binary-Trie
+
+Implementation of the [EIP-8297](https://eips.ethereum.org/EIPS/eip-8297)
+Partitioned Binary Tree: the binary trie proposed to replace the Merkle
+Patricia Trie as Ethereum's state commitment.
+
+The crate has two halves:
+
+- `trie` — the raw tree: a compressed binary radix trie mapping
+  prefix-free variable-length keys to 32-byte values, committing to its
+  contents with BLAKE3 over tagged leaf/branch preimages
+  (`blake3(0x00 ‖ key ‖ value)`, `blake3(0x01 ‖ prefix ‖ left ‖ right)`)
+  up to a single root. The empty tree's root is the 32-zero-byte
+  sentinel `EMPTY_TRIE_ROOT`.
+- `embedding` — the state embedding: how accounts, storage and code map
+  onto tree keys and values. Zone-prefixed keys, per-account header
+  stems (basic data, code hash, first 64 storage slots, first 128 code
+  chunks under one stem), overflow storage/code key derivation
+  (`get_tree_key_for_storage_slot`, `get_tree_key_for_code_chunk`),
+  code chunking (`chunkify_code`) and basic-data packing
+  (`encode_basic_data`).
+
+### The trie
+
+`trie::BinaryTrie` is incremental and insertion-based. Its canonical
+structure is insertion-order independent: any insertion order over the
+same key/value set yields the same root. Correctness is pinned by the
+spec conformance vectors rather than by a second in-crate
+implementation.
+
+### Test vectors
+
+`tests/vectors/binary_trie_vectors.json` is **vendored** from the EELS
+reference implementation, which owns the generator and its schema
+documentation:
+
+    ethereum/execution-specs, branch projects/binary-trie
+    tests/binary_trie/vectors/
+
+**Vendored from:** `projects/binary-trie` @ `f8986dca`
+
+### Non-goals (today)
+
+No persistence/`TrieDB` backing, no hash caching, no deletion, no
+proofs, no fork wiring. These are deferred to the state-commitment
+integration work.
+
+### Spec discrepancy
+
+`encode_basic_data` packs `code_size` as 4 bytes at offset 4, following
+the EELS branch this crate is ported from; EIP-7864 specifies a 3-byte
+field at offset 5. The conformance fixture pins the EELS choice —
+revisit when EIP-8297's final layout lands.