Skip to content

feat(bal): scaffold BAL store abstraction#23596

Merged
mattsse merged 12 commits into
paradigmxyz:mainfrom
0xKarl98:feat/bal-store-scaffold
Apr 21, 2026
Merged

feat(bal): scaffold BAL store abstraction#23596
mattsse merged 12 commits into
paradigmxyz:mainfrom
0xKarl98:feat/bal-store-scaffold

Conversation

@0xKarl98
Copy link
Copy Markdown
Contributor

@0xKarl98 0xKarl98 commented Apr 16, 2026 •
edited
Loading

This is the first step of the revamp of PR #22952.

This PR is intentionally limited in scope:

  • adds a BalStore abstraction plus a default NoopBalStore
  • threads the BAL store through the node/RPC builder chain into EngineApi
  • updates BAL-aware engine paths to read/write through the injected store instead of baking a concrete cache into rpc-engine-api

This PR does not implement the final BAL storage strategy yet:

  • no static-file BAL persistence
  • no historical BAL backfill
  • no finalized gap/coverage policy

Follow-up PRs will add concrete implementations on top of this scaffold:

  1. a transient/recent BAL store for hot-path data
  2. a static-file-backed BAL store for canonical persisted data
  3. backfill and explicit gap/coverage handling for older nodes

cc @mattsse

@github-project-automation github-project-automation Bot moved this to Backlog in Reth Tracker Apr 16, 2026
@0xKarl98 0xKarl98 marked this pull request as draft April 16, 2026 14:27
@0xKarl98 0xKarl98 marked this pull request as ready for review April 17, 2026 01:27
mattsse
mattsse requested changes Apr 17, 2026
View reviewed changes
Copy link
Copy Markdown
Collaborator

@mattsse mattsse left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cool, great start.

I'd like to change one thing architecturally, closer to what

#22952

did and move the store into the BlockChainProvider itself, and leave the engine api untouched.
this is because we also want bals on non engine api nodes:

https://github.com/paradigmxyz/reth/pull/22952/changes#diff-3e907e0480039111c3e6da6ce067cc7512c8086d3f1bc0879c09a645fc87918cR54-R55

Comment thread crates/storage/storage-api/src/bal.rs
Copy link
Copy Markdown
Collaborator

@mattsse mattsse Apr 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like this, this is a good start

@github-project-automation github-project-automation Bot moved this from Backlog to In Progress in Reth Tracker Apr 17, 2026
@0xKarl98 0xKarl98 requested a review from mattsse April 17, 2026 10:50
@0xKarl98 0xKarl98 marked this pull request as draft April 17, 2026 10:57
mattsse
mattsse requested changes Apr 17, 2026
View reviewed changes
Comment thread crates/node/builder/src/rpc.rs
Copy link
Copy Markdown
Collaborator

@mattsse mattsse Apr 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can undo these

Comment thread crates/rpc/rpc-engine-api/src/engine_api.rs
Copy link
Copy Markdown
Collaborator

@mattsse mattsse Apr 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lets also keep this unchanged because we should handle all things bal in the tree itself, so that we can also support non engine api paths properly

@0xKarl98 0xKarl98 requested a review from mattsse April 17, 2026 12:58
@0xKarl98 0xKarl98 marked this pull request as ready for review April 18, 2026 01:08
mattsse
mattsse reviewed Apr 21, 2026
View reviewed changes
Comment thread crates/storage/storage-api/src/bal.rs
use alloc::{sync::Arc, vec::Vec};
use alloy_primitives::{BlockHash, BlockNumber, Bytes};
use reth_storage_errors::provider::ProviderResult;

Copy link
Copy Markdown
Collaborator

@mattsse mattsse Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I addition, can we introduce a config type:

struct BalStoreConfig {
  pub prune_mode: PruneMode
}

@mattsse mattsse added this pull request to the merge queue Apr 21, 2026
Merged via the queue into paradigmxyz:main with commit 165a804 Apr 21, 2026
34 checks passed
@github-project-automation github-project-automation Bot moved this from In Progress to Done in Reth Tracker Apr 21, 2026
This was referenced Apr 22, 2026
Closed
Merged
crazywriter1 pushed a commit to crazywriter1/tempo that referenced this pull request Apr 23, 2026
@decofe @shekhirin
deps: update reth from main (2026-04-23) (tempoxyz#3698)
328c734 
Automated nightly update of reth dependencies from `paradigmxyz/reth`
main branch.

## Upstream reth changes


[`98ebc34...7839f3d`](paradigmxyz/reth@98ebc34...7839f3d)

🔗 Amp thread:
https://ampcode.com/threads/T-019db884-a7c3-738b-8f38-cc04f8942d8a
**Engine**
- Suppress persistence during payload building
([#23618](paradigmxyz/reth#23618))
- Align Amsterdam endpoint validation
([#23625](paradigmxyz/reth#23625))
- Revert [#23541](paradigmxyz/reth#23541) and
[#23578](paradigmxyz/reth#23578)
([#23646](paradigmxyz/reth#23646))
- Let consensus impls control which errors are transient
([#23668](paradigmxyz/reth#23668))
- Configure invalid header cache hit eviction
([#23670](paradigmxyz/reth#23670))

**Perf**
- Relax executor reset thresholds for re-execute
([#23617](paradigmxyz/reth#23617))
- Replace `BTreeMap` with `imbl::OrdMap` in `BestTransactions`
([#23621](paradigmxyz/reth#23621))
- Avoid reopening `.csoff` on every changeset lookup
([#23687](paradigmxyz/reth#23687))
- Disable read tx timeout during re-execute
([#23680](paradigmxyz/reth#23680))

**P2P / Net**
- Add snap/2 wire helpers and messages
([#23611](paradigmxyz/reth#23611))
- Optionally fetch BAL with full blocks
([#23629](paradigmxyz/reth#23629))
- Discv5 enabled by default
([#23686](paradigmxyz/reth#23686))

**DB**
- Add `reth db migrate-v2` for v1→v2 storage migration
([#23422](paradigmxyz/reth#23422))
- Detect and warn about ZFS
([#23685](paradigmxyz/reth#23685))

**BAL**
- Scaffold BAL store abstraction
([#23596](paradigmxyz/reth#23596))
- Enable BAL building in ethereum payload
([#23597](paradigmxyz/reth#23597))
- Add parallelization and batch IO flags
([#23663](paradigmxyz/reth#23663))

**Refactor**
- Make `WorkerPool` lazy by default
([#23627](paradigmxyz/reth#23627))
- Encapsulate state fetching in db provider
([#23656](paradigmxyz/reth#23656))
- Remove `TrieNodeProvider`
([#23658](paradigmxyz/reth#23658))
- Unify opaque consensus error helpers
([#23669](paradigmxyz/reth#23669))

**Payload**
- Add gas limit and slot number to `BlockOrPayload`
([#23624](paradigmxyz/reth#23624),
[#23626](paradigmxyz/reth#23626))

**Bench**
- Add CLI flag to fetch balances by default; require local benchmark
data ([#23655](paradigmxyz/reth#23655),
[#23679](paradigmxyz/reth#23679))

**Deps**
- Bump alloy crates to 2.0.1
([#23677](paradigmxyz/reth#23677)),
rustls-webpki
([#23681](paradigmxyz/reth#23681)), weekly
`cargo update`
([#23628](paradigmxyz/reth#23628))

**Testing**
- Remove unsafe `env::set_var(RUST_LOG)` from tests
([#23672](paradigmxyz/reth#23672))
- Address nightly clippy warnings
([#23630](paradigmxyz/reth#23630))

## Migrations

🔗 Amp thread:
https://ampcode.com/threads/T-019db884-dc46-71f5-a823-00c3a16191d4
- **Reth dependency bump**: All `reth-*` git dependencies updated from
rev `98ebc34` to `7839f3d`
- **Alloy version bump**: `alloy-*` crates updated from `2.0.0` to
`2.0.1`; `alloy-evm` changed from `0.33.2` to `0.33.0`
- **`ConsensusError::Other` → `ConsensusError::msg`**: All
`ConsensusError::Other(...)` calls migrated to
`ConsensusError::msg(...)`, which accepts `&str`/`impl Display` directly
instead of requiring `String` (removes `.to_string()` calls for string
literals)
- **`deny.toml` license exceptions**: Added MPL-2.0 exceptions for
`bitmaps`, `imbl`, and `imbl-sized-chunks` (new transitive dependencies)

[GitHub
Workflow](https://github.com/tempoxyz/tempo/actions/runs/24816009191)

---------

Co-authored-by: Alexey Shekhirin <github@shekhirin.com>
@0xKarl98 0xKarl98 deleted the feat/bal-store-scaffold branch April 25, 2026 12:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@mediocregopher mediocregopher mediocregopher approved these changes

@mattsse mattsse mattsse approved these changes

@klkvr klkvr klkvr approved these changes

@joshieDo joshieDo Awaiting requested review from joshieDo joshieDo is a code owner

@shekhirin shekhirin Awaiting requested review from shekhirin shekhirin is a code owner

@Rjected Rjected Awaiting requested review from Rjected

Assignees

No one assigned

Labels

None yet

Projects

Reth Tracker
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@0xKarl98 @mediocregopher @mattsse @klkvr