Skip to content

Utreexo, State Commitments, and Lite Wallet support - #57

Draft
akumaigorodski wants to merge 4 commits into
LayerTwo-Labs:masterfrom
akumaigorodski:utreexo-archive-storage
Draft

akumaigorodski wants to merge 4 commits into
LayerTwo-Labs:masterfrom
akumaigorodski:utreexo-archive-storage

Conversation

@akumaigorodski

@akumaigorodski akumaigorodski commented Jul 31, 2026

Copy link
Copy Markdown

This is a second, more structured attempt to address three related areas:

  • Full-node Utreexo accumulator handling.
  • A consensus-defined block-header commitment to compact chain state, including state not derivable from UTXOs, such as active AMMs and auctions, open for future extensions, intended for fast full node sync.
  • Full-node support for lite wallets.

This began as lite-wallet work, but all three depend on the same consensus-critical state commitment, which should be defined first.

Plan

  1. Define storage formats suited to Utreexo and lite-wallet queries.
  2. Define an extensible compact-state bundle for fast, trust-less initial sync; commit to it in block headers and add network transfer.
  3. Add lite-wallet data formats and protocol support.

General rationale: lite wallet is UTXO-based so strictly speaking it does not need to know tx history, however, it is still nice to show users actual tx history so they can figure out what was going on. However again, storing full tx history is too demanding for a full node so it is capped.
Add a compact address/outpoint index and synchronize it with the primary UTXO database across block and two-way-peg transitions. Preserve creation heights in spent entries for rollback, expose height-filtered node queries, and update callers and tests.
Define the BLAKE3 hashing format and serializable accumulator types.

Add archive databases for:
- accumulators: infrequent full snapshots keyed by block hash
- accumulator_diffs: per-block UTXO changes
- accumulator_reorg_floor: oldest reconstructible height

Add pruning helpers and storage round-trip tests.
@akumaigorodski

akumaigorodski commented Jul 31, 2026

Copy link
Copy Markdown
Author

So far this is the first point of the plan and it only touches proposed storage formats such as:

  • UTXOs searchable by address and creation height, so lite wallets can request delta updates (from genesis block for first sync, from block N since last time a wallet has been launched etc.).
  • Recent transactions archive, also searchable by address and height and along with Merkle proofs, so lite wallets can request these.
  • Utreexo db formats for storing infrequent memforest snapshots and less heavy per-block utreexo delta updates.

The general rationale is that lite wallet sync should not be a computational/traffic hit for a full node and it should be able to serve everything with minimal effort.

When it comes to utreexo storage formats, this is a tradeoff between storing a lot of heavy memforest snapshots and taking a lot of computation/time to reconstruct current memforest from per-block diffs.

All proposed databases are designed to be prunable (except UTXO database).

@akumaigorodski
akumaigorodski marked this pull request as draft July 31, 2026 07:27
@akumaigorodski

Copy link
Copy Markdown
Author

I propose to move though the whole plan by first reaching an agreement on what is already done, and then the further work will be based on that, point by point.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant