Skip to content

State sync does not support indexed trees (PCIT/PSIT/PCPSIT) #778

Closed

Description

@QuantumExplorer

This is Claude, filing on behalf of @QuantumExplorer.

Summary

State sync fails closed on indexed trees. Both sides reject them:

  • Source: fetch_chunk refuses to emit a chunk for an indexed subtree's prefix.
  • Discovery: state_sync_session.rs rejects an indexed element with NotSupported ("state sync does not yet support indexed trees").

Pinned by fetch_chunk_source_side_rejects_indexed_tree_chunk in grovedb/src/tests/replication_session_tests.rs.

Why it matters

A node cannot state-sync a database containing indexed trees. Failing closed is the right default — silently syncing a primary without its secondaries would produce a node whose H1-A bindings are wrong — but it means indexed trees are unusable in any deployment that relies on state sync for node bootstrap or recovery, unless this lands first.

What makes it non-trivial

The secondaries live at derived prefixes (Blake3(primary_prefix ‖ axis_tag)) that are not GroveDB paths, so they are invisible to path-driven chunk discovery. A PCPSIT can carry up to three of them. The chunk protocol needs a way to enumerate, transfer, and verify them alongside the primary, and the restored element's combine_hash_three / axes_digest binding must be checked against the transferred secondary roots rather than trusted.

Worth checking against the known chunk-restore aggregate bug (#671) while designing this — the Provable* family already has a restore-side OWN-vs-AGGREGATE mismatch.

Why it can't be deferred indefinitely

The companion repair API (reconcile_indexed_tree_secondaries) covers content damage, but a Merk root hash also commits to tree shape, which is a function of operation history and cannot be recovered by any content repair. Damage that permanently rotated surviving nodes leaves a self-consistent, verify_grovedb-clean index whose root may still differ from an undamaged peer's. State sync is the only path back to consensus for that case.

Scope

Blocks GROVE_V4 activation if Platform intends to use indexed trees at launch, not the merge of #657 (indexed trees are live on no released version).

Activity

  1. QuantumExplorer commented on Sep 7, 2026

    @QuantumExplorer
    MemberAuthor

    This is Claude, closing on behalf of the maintainer.

    Implemented in #840 (6ec8fee). The target requests an indexed primary with a header request built from its hash-verified element (axis tags plus secondary root keys); the source answers with an indexed header carrying the primary and per-axis secondary root hashes together with the primary's root chunk; the axis secondaries transfer as ordinary Merk chunks addressed by their derived prefixes. The header is only a hint for per-chunk verification: the group is accepted solely when combine_hash_three over the actual restored root hashes matches the element value hash bound into the restored parent. Secondaries of an open group are activated ahead of ordinary descendants so incremental commits are never starved.

    Tests: the state_sync_indexed_* round-trip and tamper cases (tampered header, lying empty header, tampered secondary chunk, foreign axis tags), never_splits_an_indexed_group_across_a_commit.

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions