Add partitioned binary trie

.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Default owners for PBT / stateless work
+* @besu-eth/maintainers

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,50 @@
+---
+name: Bug Report
+about: necessary information to help us resolve the issue
+title: ''
+labels: 'bug'
+assignees: ''
+
+---
+
+<!-- Have you done the following? -->
+<!--   * read the Code of Conduct? By filing an Issue, you are expected to -->  
+<!--     comply with it, including treating everyone with respect: -->
+<!--     https://github.com/besu-eth/besu-stateless/blob/main/CODE_OF_CONDUCT.md -->
+<!--   * Reproduced the issue in the latest version of the software -->
+<!--   * Read the docs: https://docs.besu-eth.org/ -->
+<!--   * Duplicate Issue check:  https://github.com/search?q=+is%3Aissue+repo%3Abesu-eth/besu -->
+
+### Steps to Reproduce
+1. [Step 1]
+2. [Step 2]
+3. [Step ...]
+
+**Expected behavior:** [What you expect to happen]
+
+**Actual behavior:** [What actually happens]
+
+**Frequency:** [What percentage of the time does it occur?]
+
+### Logs
+Please post relevant logs from Besu (and the consensus client, if running proof of stake) from before and after the issue.
+
+### Versions (Add all that apply)
+* Software version: [`besu --version`]
+* Java version: [`java -version`]
+* OS Name & Version: [`cat /etc/*release`]
+* Kernel Version: [`uname -a`]
+* Virtual Machine software & version: [`vmware -v`]
+* Docker Version: [`docker version`]
+* Cloud VM, type, size: [Amazon Web Services I3-large]
+* Consensus Client & Version if using Proof of Stake: [e.g. Teku, Lighthouse, Prysm, Nimbus, Lodestar]
+
+### Smart contract information (If you're reporting an issue arising from deploying or calling a smart contract, please supply related information)
+* Solidity version [`solc --version`]
+* Repo with minimal set of deployable/reproducible contract code - please provide a link
+* Please include specifics on how you are deploying/calling the contract
+* Have you reproduced the issue on other eth clients
+
+### Additional Information (Add any of the following or anything else that may be relevant)
+* Besu setup info - genesis file, config options
+* System info - memory, CPU

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,45 @@
+---
+name: Feature Request
+about: suggesting new or altered functionality
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+<!-- Have you done the following? -->
+<!--   * read the Code of Conduct? By filing an Issue, you are expected to -->  
+<!--     comply with it, including treating everyone with respect: -->
+<!--     https://github.com/besu-eth/besu/blob/main/CODE_OF_CONDUCT.md -->
+<!--   * Duplicate Issue check:  https://github.com/search?q=+is%3Aissue+repo%3Abesu-eth/besu -->
+
+### Description
+As an [Actor], I want [feature] so that [why].
+
+### Acceptance Criteria
+* [Criteria 1]
+* [Criteria 2]
+* [Criteria 3...]
+
+### Logs (if a change in behavior)
+Please post relevant logs illustrating behavior to be altered
+
+### Versions (Add all that apply)
+* Software version: [`besu --version`]
+* Java version: [`java -version`]
+* OS Name & Version: [`cat /etc/*release`]
+* Kernel Version: [`uname -a`]
+* Virtual Machine software & version: [`vmware -v`]
+* Docker Version: [`docker version`]
+* Cloud VM, type, size: [Amazon Web Services I3-large]
+* Consensus Client & Version if using Proof of Stake: [e.g. Teku, Lighthouse, Prysm, Nimbus, Lodestar]
+
+### Smart contract information (If you're reporting an issue arising from deploying or calling a smart contract, please supply related information)
+* Solidity version [`solc --version`]
+* Repo with minimal set of deployable/reproducible contract code - please provide a link
+* Please include specifics on how you are deploying/calling the contract
+* Have you reproduced the issue on other eth clients
+
+### Additional Information (Add any of the following or anything else that may be relevant)
+* Besu setup info - genesis file, config options
+* System info - memory, CPU

.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - 'feat/**'
+      - 'feature/**'
+  pull_request:
+    branches:
+      - main
+  schedule:
+    # Weekly JMH compile smoke (full JMH is too slow for every PR)
+    - cron: '0 6 * * 1'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    if: ${{ github.actor != 'dependabot[bot]' }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Java 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+          cache: gradle
+
+      - name: Spotless check
+        run: ./gradlew --no-daemon spotlessCheck
+
+      - name: Run tests
+        run: ./gradlew --no-daemon clean test
+
+      - name: Compile JMH sources
+        run: ./gradlew --no-daemon compileJmhJava
+
+  jmh-compile-scheduled:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'schedule'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Java 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+          cache: gradle
+
+      - name: Compile JMH (scheduled)
+        run: ./gradlew --no-daemon compileJmhJava

CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0-SNAPSHOT] - 2026-07-28
+
+### Added
+
+- Initial import of the Partitioned Binary Trie (PBT) library from `besu-partitioned-binary-trie`.
+- `StoredPartitionedBinaryTrie` with Tuweni `Bytes` API (`putDeferred`, `commit`, `getRootHash`).
+- EIP-8297 embedding layer: zone-based key derivation, account header encoding, bytecode chunking.
+- Stored trie visitors (get, put, remove, commit, proof), node codec, and merkle proof support.
+- `ParallelStoredPartitionedBinaryTrie` for parallel commit.
+- JMH benchmarks under `src/jmh/java`.
+- Comprehensive test suite (~200 tests) with execution-specs conformance oracle.
+- GitHub Actions CI workflow (Java 21, `./gradlew clean test`, `compileJmhJava`).
+
+### Removed
+
+- Legacy Verkle / binary-trie prototype code previously in this repository.

CODE_OF_CONDUCT.md

@@ -1,24 +1,24 @@
-# [Hyperledger Code of Conduct](https://wiki.hyperledger.org/community/hyperledger-project-code-of-conduct)
+# Besu Code of Conduct
 
-Hyperledger is a collaborative project at The Linux Foundation. It is an open-source and open
+Besu is a collaborative project at The Linux Foundation. It is an open-source and open
 community project where participants choose to work together, and in that process experience
 differences in language, location, nationality, and experience. In such a diverse environment,
 misunderstandings and disagreements happen, which in most cases can be resolved informally. In rare
 cases, however, behavior can intimidate, harass, or otherwise disrupt one or more people in the
-community, which Hyperledger will not tolerate.
+community, which Besu will not tolerate.
 
 A **Code of Conduct** is useful to define accepted and acceptable behaviors and to promote high
 standards of professional practice. It also provides a benchmark for self evaluation and acts as a
 vehicle for better identity of the organization.
 
-This code (**CoC**) applies to any member of the Hyperledger community – developers, participants in
+This code (**CoC**) applies to any member of the Besu community – developers, participants in
 meetings, teleconferences, mailing lists, conferences or functions, etc. Note that this code
 complements rather than replaces legal rights and obligations pertaining to any particular
 situation.
 
 ## Statement of Intent
 
-Hyperledger is committed to maintain a **positive** [work environment](#work-environment). This
+Besu is committed to maintain a **positive** [work environment](#work-environment). This
 commitment calls for a workplace where [participants](#participant) at all levels behave according
 to the rules of the following code. A foundational concept of this code is that we all share
 responsibility for our work environment.
@@ -57,7 +57,7 @@ responsibility for our work environment.
     discussions. Remember when you update an issue or respond to an email you are potentially
     sending to a large number of people.
 
-11. Step down considerately: Members of every project come and go, and the Hyperledger is no
+11. Step down considerately: Members of every project come and go, and Besu is no
     different. When you leave or disengage from the project, in whole or in part, we ask that you do
     so in a way that minimizes disruption to the project. This means you should tell people you are
     leaving and take the proper steps to ensure that others can pick up where you left off.
@@ -100,13 +100,13 @@ includes the following persons:
 - Developers
 - Member representatives
 - Staff members
-- Anyone from the Public partaking in the Hyperledger work environment (e.g. contribute code,
+- Anyone from the Public partaking in the Besu work environment (e.g. contribute code,
   comment on our code or specs, email us, attend our conferences, functions, etc)
 
 ### Respect
 
 is the genuine consideration you have for someone (if only because of their status as participant in
-Hyperledger, like yourself), and that you show by treating them in a polite and kind way.
+Besu, like yourself), and that you show by treating them in a polite and kind way.
 
 ### Sexual Harassment
 
@@ -164,3 +164,4 @@ in the event of a misunderstanding.
 This code is based on the
 [W3C’s Code of Ethics and Professional Conduct](https://www.w3.org/Consortium/cepc) with some
 additions from the [Cloud Foundry](https://www.cloudfoundry.org/)‘s Code of Conduct.
+This project also follows the [Hyperledger Project Code of Conduct](https://wiki.hyperledger.org/community/hyperledger-project-code-of-conduct).

CONTRIBUTING.md

@@ -1,36 +1,70 @@
-# Contributing to Hyperledger Besu stateless
-## :tada: Thanks for taking the time to contribute! :tada:
+# Contributing to Besu Stateless
 
-Welcome to the Besu stateless repository! The following links are a set of guidelines for contributing to this repo and its packages. These are mostly guidelines, not rules. Use your best judgement, and feel free to propose changes to this document in a pull request. Contributions come in the form of code submissions, writing documentation, raising issues, helping others in chat, and any other actions that help develop Besu stateless.
+Thanks for taking the time to contribute!
 
-### Github/Discord/LF Accounts
+This repository hosts the [EIP-8297](https://eips.ethereum.org/EIPS/eip-8297) Partitioned Binary Trie library for Hyperledger Besu. Contributions include code, tests, documentation, benchmarks, and issue reports.
 
-Having the following accounts is necessary for contributing code/issues to Besu stateless.  
-* If you want to contribute code, you can make a [github account here](https://github.com).  
-* If you want to raise an issue, do so [in the issues tab](https://github.com/hyperledger/besu-stateless/issues).
-* To ask questions or chat with us, join our [Discord](https://discord.gg/hyperledger)
-* To edit pages in our wiki, you'll need a [Linux Foundation (LF) account].
+## Getting started
 
-### Useful contributing links
+1. Fork [besu-eth/besu-stateless](https://github.com/besu-eth/besu-stateless) on GitHub.
+2. Clone your fork and create a feature branch from `main`.
+3. Install **Java 21** (Temurin or Corretto recommended).
+4. Build and test locally:
 
-* [I just have a quick question](https://wiki.hyperledger.org/display/BESU/I+just+have+a+quick+question)
-* [How to Contribute]
-* [First contribution workflow](https://wiki.hyperledger.org/display/BESU/First+contribution?src=contextnavpagetreemode)
-* [Did you find a bug?](https://wiki.hyperledger.org/display/BESU/Reporting+Bugs)
-* [Issues](https://wiki.hyperledger.org/display/BESU/Issues)
-* [DCO](https://wiki.hyperledger.org/display/BESU/DCO)
-* [Suggesting Enhancements](https://wiki.hyperledger.org/display/BESU/Suggesting+Enhancements)
-* [Pull Requests](https://wiki.hyperledger.org/display/BESU/Pull+Requests)
-* [Code Reviews](https://wiki.hyperledger.org/display/BESU/Code+Reviews)
+   ```bash
+   ./gradlew clean test
+   ./gradlew compileJmhJava
+   ```
 
+5. Format code before committing:
 
-* [Security contributions](https://wiki.hyperledger.org/display/BESU/Security)
+   ```bash
+   ./gradlew spotlessApply
+   ```
 
-### Other important information
+## Code style
 
-* [Roadmap](https://wiki.hyperledger.org/display/BESU/Roadmap)
-* [Code of Conduct](https://wiki.hyperledger.org/display/BESU/Code+of+Conduct)
-* [Governance](https://wiki.hyperledger.org/display/BESU/Governance)
+- Java 21 toolchain; follow existing package layout under `org.hyperledger.besu.ethereum.partitionedbinarytrie`.
+- Spotless enforces Google Java Format, import order (`org.hyperledger` first), and the Apache 2.0 license header.
+- Compiler warnings are errors (`-Werror`); Error Prone checks are enabled.
+- Keep hot-path code allocation-free where the surrounding code already does (see `internal` and `stored` packages).
+- Match existing naming, abstractions, and test patterns — read neighboring code before adding new APIs.
 
-[How to Contribute]: https://wiki.hyperledger.org/display/BESU/How+to+Contribute
-[Linux Foundation (LF) account]: https://identity.linuxfoundation.org/
+## Tests
+
+- All changes must pass `./gradlew clean test`.
+- Add or update tests for behavioral changes. The spec-reference oracle under `src/test/java/.../trie/reference/` is the conformance baseline.
+- JMH sources must compile: `./gradlew compileJmhJava`.
+
+## Pull request process
+
+1. Open a PR against `main` with a clear description of the change and motivation.
+2. Link related issues (e.g. `fixes #123`).
+3. Ensure CI is green.
+4. Request review from maintainers (see [MAINTAINERS.md](MAINTAINERS.md)).
+5. Address review feedback; keep commits focused or squash before merge per reviewer preference.
+
+Use the [pull request template](.github/pull_request_template.md).
+
+## Developer Certificate of Origin (DCO)
+
+Every commit must include a DCO sign-off. Add this line to your commit message:
+
+```
+Signed-off-by: Your Name <your.email@example.com>
+```
+
+Or use `git commit -s`. See [DCO.md](DCO.md) and the [Hyperledger DCO policy](https://wiki.hyperledger.org/display/BESU/DCO).
+
+## Code of conduct
+
+Participants must follow the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Security
+
+Do not open public issues for security vulnerabilities. See [SECURITY.md](SECURITY.md).
+
+## Questions
+
+- [Hyperledger Besu Discord](https://discord.gg/hyperledger)
+- [Besu wiki — How to Contribute](https://wiki.hyperledger.org/display/BESU/How+to+Contribute)

DCO.md

@@ -1,8 +1,21 @@
 DCO
 ===
 
-As per section 13.a of the [Hyperledger Charter](https://www.hyperledger.org/about/charter) all code submitted to the Hyperledger Foundation needs to have a [Developer Certificate of Origin](http://developercertificate.org/) (DCO) sign-off.
+All code submitted to Besu stateless must have a [Developer Certificate of Origin](https://developercertificate.org/) (DCO) sign-off, in line with the [Linux Foundation Decentralized Trust (LF Decentralized Trust) charter](https://www.lfdecentralizedtrust.org/about/charter).
 
-The sign off needs to be using your legal name, not a pseudonym.  Git has a built-in mechanism to allow this with the `-s` or `--signoff` argument to `git commit` command, providing your `user.name` and `user.email` have been setup correctly.
+The sign-off must use your legal name, not a pseudonym. Git has a built-in mechanism to add it via the `-s` or `--signoff` argument to `git commit`, provided your `user.name` and `user.email` have been set up correctly.
 
-If you have any questions, you can reach us on Besu chat; first, [join the Discord server](https://discord.gg/hyperledger/) then [join the Besu channel](https://discord.com/channels/905194001349627914/938504958909747250).
+TL;DR:
+
+If you don't want to break the DCO check, ensure all your commits have a sign-off.
+
+`git config user.name "FIRST_NAME LAST_NAME"`
+`git config user.email "MY_NAME@example.com"`
+
+If you use the GitHub web UI for commits, make sure the `Signed-off-by` line uses the same email address as the commit author. This can be your GitHub `users.noreply.github.com` email if you keep your email address private.
+
+You can also set up a git global alias.
+
+More info, including how to set up an alias and what to do if the DCO check is failing on your PR, is in the [Working with DCO](https://github.com/besu-eth/besu/wiki/Contributing-Working-with-DCO) wiki page.
+
+If you have any questions, you can reach us on [Discord](https://discord.com/invite/hyperledger).