Repository navigation
fix(drive): look up a single document at a block time (PV15) - #5838
Conversation
A single document query in its "maybe contested" status looks among the documents of its type and in the contest's area at once. No proof of one verified at any protocol version: the verifier asked GroveDB to name the absent keys, which needs an overall limit the merged query does not have. verify_proof_keep_serialized 1, selected by protocol version 15, verifies the proof against the merged query and answers with the document from whichever place holds it. Under GROVE_V5 the query of a document type that keeps history states its cap itself, since the merge no longer derives one above a subquery, and builds the query protocol version 14 built. A lookup at a block time is refused in this status. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Only a document type that keeps history refuses a block time in this status. A type without history has one version and ignores it, as in every status. The README, note 29 and the error say so. Tests: a block time is ignored for a type without history, and protocol version 14 still refuses a proof that generation 1 accepts, whole and as a subset. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
In a document type that keeps history, a single document query with a block time asks for the newest version stored at or before that time. It never worked: its range also reached the pointer to the latest version at key [0], so a time before the document was first stored answered with the latest version, and no proof of it verified, as the verifier asked GroveDB to name the absent keys of a range. The query gets generations. single_document_path_query 1, selected only by protocol version 15's document method table, stops the range above the pointer, and states the cap of a document that may be contested as the merge of GROVE_V5 needs it. Generation 0 is what protocol versions 1 to 14 build. verify_proof_keep_serialized 1 verifies such a lookup against the query as it is, for a document outside a contest and for one that may be contested, which is no longer refused at a block time. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…cument' into claude/single-document-block-time # Conflicts: # packages/rs-drive/src/query/single_document_drive_query.rs # packages/rs-platform-version/src/version/v15.rs # packages/wasm-drive-verify/README_SINGLE_DOCUMENT.md
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…cument' into claude/single-document-block-time # Conflicts: # packages/rs-drive/src/query/single_document_drive_query.rs
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
|
Warning Review limit reachedYou've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. Next included review available in 42 minutes. View limit details
No actionable comments were generated in the recent review. Walkthrough
Merge Risk:
|
|
🕓 Review not started yet because the new head is waiting for the 30-minute push debounce.
Commit cfc146a. Normal review starts when eligible; priority review starts as soon as a slot is available. |
|
Waiting for bot review — thepastaclaw not yet. Wait for the missing reviews, or a writer can post |
…ument-block-time v5.1-dev now holds #5835 as one squashed commit. Every conflict is with that commit's content, which this branch already merged from #5835's branch, so this branch's side is kept, plus the two verifier tests #5835 added after the head merged here: a document that may be contested verified as a subset of a larger proof, and a document in both places refused as a subset too. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Waiting for bot review — thepastaclaw not yet. Wait for the missing reviews, or a writer can post |
thepastaclaw
left a comment
There was a problem hiding this comment.
Final validation — Phase 2 only (queue backlog)
At head 4c578c4, the versioned query construction preserves earlier protocol behavior, but the newly supported historical MaybeContested lookup can return and authenticate a document submitted after the requested time. The missing contested-history regression coverage is consolidated into that blocking finding. Validation was static only; current CI reports successful Rust workspace, wasm32, Swift, Kotlin, and JavaScript checks, with review and hygiene checks pending.
🔴 1 blocking
Review provenance
Source: reviewer 1: gpt-6.1-sol (agent: phase2-reviewer, role: general); reviewer 2: gpt-6.1-sol (agent: phase2-reviewer, role: architecture-layering); reviewer 3: gpt-6.1-sol (agent: phase2-reviewer, role: platform-versioning); reviewer 4: gpt-6.1-sol (agent: phase2-reviewer, role: rust-quality); reviewer 5: gpt-6.1-sol (agent: phase2-reviewer, role: security-auditor); reviewer 6: gpt-6.1-sol (agent: phase2-reviewer, role: general); reviewer 7: gpt-6.1-sol (agent: phase2-reviewer, role: architecture-layering); reviewer 8: gpt-6.1-sol (agent: phase2-reviewer, role: platform-versioning); reviewer 9: gpt-6.1-sol (agent: phase2-reviewer, role: rust-quality); reviewer 10: gpt-6.1-sol (agent: phase2-reviewer, role: security-auditor); final verifier: gpt-6.1-sol (agent: sol-verifier, role: final-verifier)
- Triage:
normalbygpt-6.1-sol(effort low) — The change adds version-gated historical document query logic and proof-verification handling across multiple Rust modules, but does not itself change consensus rules, cryptographic primitives, funds movement, or storage layout. - Phase 1 reviewers: not run (skipped for throughput: 15 PRs queued, above the 10 limit)
- Second Phase-2 pass: on this first full review every Phase-2 reviewer also ran a second, independent time, and the verifier weighed both sets
- Fresh verifier:
gpt-6.1-sol— final-verifier; agentsol-verifier - Phase 2 reviewers:
gpt-6.1-sol— general (completed, effort high); agentphase2-reviewer,gpt-6.1-sol— architecture-layering (completed, effort high); agentphase2-reviewer,gpt-6.1-sol— platform-versioning (completed, effort high); agentphase2-reviewer,gpt-6.1-sol— rust-quality (completed, effort high); agentphase2-reviewer,gpt-6.1-sol— security-auditor (completed, effort high); agentphase2-reviewer,gpt-6.1-sol— general (completed, effort high); agentphase2-reviewer,gpt-6.1-sol— architecture-layering (completed, effort high); agentphase2-reviewer,gpt-6.1-sol— platform-versioning (completed, effort high); agentphase2-reviewer,gpt-6.1-sol— rust-quality (completed, effort high); agentphase2-reviewer,gpt-6.1-sol— security-auditor (completed, effort high); agentphase2-reviewer
🤖 Prompt for all review comments with AI agents
These findings are from an automated code review (PastaClaw). How to work through them:
- Verify each finding against the code; fix only what is real, as narrowly as the finding.
- If a finding is wrong, decline it on its thread in one or two sentences; the bot answers once and stops.
- To defer one, link a tracking issue on its thread (or reply asking the bot to file one).
- Suggestions are optional: fix them forward in a later PR rather than pushing another round just for them.
- Address every current finding in one push: self-review the full diff first, and don't push piecemeal.
- Keep the PR's scope; don't grow it to satisfy hardening suggestions.
- Carried items were raised in an earlier round: read the thread first, and don't re-fix what you already fixed, declined or deferred there. Disputed and deferred items are already handled and are not listed.
In `packages/rs-drive/src/query/single_document_drive_query/v1/mod.rs`:
- [BLOCKING] packages/rs-drive/src/query/single_document_drive_query/v1/mod.rs:32-39: Honor the block-time cutoff when the document is in the contest area
The newly enabled historical `MaybeContested` query applies `block_time_ms` only to the ordinary-storage branch. `construct_contested_path_query` selects the document ID without a temporal condition, and `add_contested_document_to_primary_storage_0` stores a plain document item even when its type keeps history. A contender first stored at time 2000 can therefore be returned by a query at time 1000. The generation-1 verifier authenticates that exact lookup and returns the item without checking its time, so both whole-proof and subset verification can accept the incorrect historical answer. This combination was previously refused at PV15; lifting the refusal introduces the incorrect result. The documented exception for an explicitly `Contested` query does not satisfy the historical guarantee advertised for `MaybeContested`, whose caller does not know the storage location. Retain the unsupported-combination guard until Drive can guarantee the cutoff, or implement temporal handling for the contest branch. Add a history-bearing contested fixture covering times before and after its submission, whole-proof and subset verification, and absence while another contender exists; the new temporal tests currently store their documents only in ordinary history.
|
Your move: thepastaclaw requested changes on this head; dismiss the review or push a fix; thepastaclaw left review threads unresolved; resolve them. |
… block time A contest's area holds each contender as it was submitted, a plain item with no time to compare, so a lookup that may be contested would find a contender submitted after the block time there, and the proof would verify. Generation 1 of the query refuses that lookup again, as #5835 did, until the contest's area can answer at a time. A lookup at a block time outside a contest still works. Tests: the refusal through the query and through the verifier, as a whole proof and as a subset. The block time tests now look outside a contest only. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Waiting for bot review — thepastaclaw not yet. Wait for the missing reviews, or a writer can post |
…ument-block-time #5825 added protocol version 15 note 30, for the asset lock input cap, where this branch had its own note 30. Both are kept: the lookup at a block time is note 31 now, and the drive table comment and DRIVE_VERSION_V10's doc name it so. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Waiting for bot review — thepastaclaw not yet. Wait for the missing reviews, or a writer can post |
…et-listings Keeps #5838's v15 note 31 (a single document is looked up at a block time) and moves the token listings note to 32. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…-diff-spec v5.1-dev added protocol v15 notes 29 (#5835, a document that may be contested), 30 (#5825, the chain asset lock input cap) and 31 (#5838, a single document at a block time). This branch's operator payout note was 29, so it becomes note 32, after them. The v15.rs conflict is in the note list and in PLATFORM_V15's drive comment: v5.1-dev's notes 29 to 31 come first, then this branch's note renumbered to 32, and the drive comment keeps both sides' entries with add_new_keys_to_masternode_identity 1 pointing at note 32. The DRIVE_ABCI_METHOD_VERSIONS_V11 comment and the "(v15 note 32)" comment in transition_to_version_15 follow the new number. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…uests Brings in #5556 (shared broadcast keeps uncertain submission outcomes), #5823 (proven state transition outcome, getRecentStateTransitionStatus), #5815, #5834, #5825, #5835, #5838 and #5839. One textual conflict, in packages/rs-sdk/src/platform/transition/broadcast.rs at the end of broadcast_with_retries. This branch (#5837) had the shared broadcast fail over on a nonce-ahead answer and on a missing DPNS owner (retry_with_additional_error, from #5562), and made is_address_nonce_ahead public for the wallet's single-dispatch broadcast. #5556 replaced both failovers with the plain shared retry, so that a concrete refusal ends sending, with tests saying so (should_stop_on_nonce_rejection_without_ rebuilding_or_resending, should_stop_on_concrete_rejection_regardless_of_ node_failover_settings), and removed is_address_nonce_ahead and is_missing_transition_owner. The file is taken as v5.1-dev has it. The wallet's single-dispatch broadcast (broadcast_outcome::track_delivery) still goes on to the next dispatch after a nonce-ahead answer, as #5837 meant: the classifier moves into broadcast_outcome.rs, unchanged, and its doc no longer says the SDK's own broadcast fails over too. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Basic explanation
What this does: Some document types keep history: every change stores a new version of the document next to the old ones. A client can ask for proof of one document "as it stood at a given time". That lookup never worked. From protocol version 15 it answers with the newest version stored at or before the time, and with nothing for a time before the document existed, and its proof can be verified.
Value: Code that verifies proofs on the client (
wasm-drive-verifyand the Rustdriveverifier) gets a working way to read a past version of a document outside a name contest. Nothing in the SDKs or the node uses it yet, so a public helper is fixed before anyone depends on it.Risks: Low. No state transition is proved or verified at a block time, so block execution and state transition proofs do not change. Only protocol version 15, which is not released, selects the change: protocol version 14 and earlier build the query they built, pinned by tests. One thing to know: #4652 (open) changes how history is stored at protocol version 15 and refuses these lookups under its new layout, so whichever of the two lands second has to be reworked against the other.
Issue being fixed or feature implemented
SingleDocumentDriveQuerytakesblock_time_ms. For a document type that keeps history it then looks in the document's history, which holds one key per time a version was stored, plus the key[0], a pointer to the latest version. Two things were wrong:[0]sorts below every time, so the range reached it: a time before the document was first stored answered with the latest version.Found while fixing the "maybe contested" lookup in #5835, which left this out to stay focused and refused the block time in that status. No issue was open for it, and no open PR fixes it.
This PR builds on #5835, now merged as one commit into
v5.1-dev: it needs that PR's verifier generation, and it moves and lifts what that PR added for a lookup at a block time.What was done?
A person document stored at time 1000 and changed at time 2000, in a type that keeps history, looked up outside a contest:
The same lookups for a document that may be contested are still refused at protocol version 15, as #5835 left them (
QuerySyntaxError::Unsupported). A contest's area holds each contender as it was submitted, a plain item with no time to compare, so a contender submitted after the block time would be found there and its proof would verify.The query for block time 1500, in the document's history:
SingleDocumentDriveQuery::construct_path_querynow dispatches on a new table number,drive.methods.document.query.single_document_path_query.packages/rs-drive/src/query/single_document_drive_query/v0/mod.rs) is what protocol versions 1 to 14 build. It is the code as it was, moved.v1/mod.rs) reuses generation 0 and changes two lookups in a type that keeps history. A lookup at a block time stops above the pointer. A lookup of a document that may be contested states its cap itself before the merge, and is refused at a block time, both of which fix(drive): verify a single document that may be contested (PV15) #5835 did behind a check of GroveDB's merge generation. That check is gone: the generation is selected by the table.i64::MAXis read asi64::MAX. Times are stored with their top bit flipped, so a later time would sort below every real one and find nothing.u64::MAXnow answers with the latest version.verify_proof_keep_serialized1 (packages/rs-drive/src/verify/single_document/verify_proof_keep_serialized/v1/mod.rs, added by fix(drive): verify a single document that may be contested (PV15) #5835, not released) also verifies a lookup at a block time against the query as it is, withGroveDb::verify_query, orverify_subset_queryfor a subset. It answers with the one version found, or with none. Lookups with no block time, in a type without history, or in a contest go to generation 0 as before.single_document_path_queryis 0 in document method tables v1 to v4 and 1 inDRIVE_DOCUMENT_METHOD_VERSIONS_V5, protocol version 15's. Note 31 inpackages/rs-platform-version/src/version/v15.rsdescribes it, and note 29 no longer says a block time is refused.packages/wasm-drive-verify/README_SINGLE_DOCUMENT.mdgets a "Block Time" section.Points for review
[0]" and not "from time 0". Both leave the pointer out. "Above[0]" says so directly, depends on nothing but the pointer's key, and no time can turn it into an inverted range.prove_state_transitionalways asks for the latest version. A client needs a proof of the built query, which today only proving that query directly gives.construct_path_queryrefuse a block time for history types there. This PR fixes the lookup on the layoutv5.1-devhas today.Public interface changes
No signature changes. One struct gains a field, and three calls behave differently at protocol version 15.
platform-versionCode that builds this struct with a literal must add the field. In this repository only the four document method tables did, and they set it to 0.
Defaultgives 0, generation 0.drive(SingleDocumentDriveQuery, in a document type that keeps history, at protocol version 15)construct_path_query,NotContested, a block time..=time, reaching the pointer at[0][0]up to the timeconstruct_path_query,MaybeContested, a block timeQuerySyntaxError::UnsupportedQuerySyntaxError::Unsupportedconstruct_path_query, an unknownsingle_document_path_queryDriveError::UnknownVersionMismatchverify_proofandverify_proof_keep_serialized,NotContested, a block timeNonePathQuery::try_from_platform_versioned(SingleDocumentDriveQuery, ..)followsconstruct_path_query.wasm-drive-verify:verifySingleDocumentProofKeepSerializedwith a query created withblockTimeMs, called with platform version 15, returns the root hash and the version, where it returned "Verification failed".What stays the same: every query with no block time, every query in a type without history, and every
Contestedquery build exactly what protocol version 14 builds (tested over all statuses). Stored bytes, state transition proofs and every protocol version up to 14 are untouched.How Has This Been Tested?
verify_proof_keep_serialized/v1/mod.rs, 5 new tests that prove and verify against a real Drive, each as a whole proof and as a subset, with the root hash checked against the stored state. A history document with two versions (times 1000 and 2000) is looked up outside a contest at 0, 999, 1000, 1500, 1999, 2000, 2500 andu64::MAX: nothing before 1000, the first version up to 1999, the second from 2000. A document that was never stored is proved absent at a block time. A proof made for another block time is refused. A "maybe contested" lookup at a block time is refused. Protocol version 14 still refuses a lookup at a block time.single_document_drive_query.rs: protocol version 14 builds the block time query it built, written out by hand, and the "maybe contested" merge it built; protocol version 15 builds the same query as 14 for every status, with and without history, with and without a block time, except the block time lookup in a history; the new range is as described, also foru64::MAX; a "maybe contested" history lookup at a block time is refused, one without history is not; an unknown table number is refused.[0], no clamp of the block time, no cap stated for a "maybe contested" history lookup, the verifier sending a block time lookup to generation 0, the table selecting generation 0 at protocol version 15, no refusal of a "maybe contested" lookup at a block time.cargo test -p drive --lib -- verify:: prove:: query::single(402 passed),cargo test -p platform-version(31 passed).cargo clippy -p drive -p platform-version --all-targets -- -D warnings,cargo fmt --all --check,cargo check -p drive --no-default-features --features verify,cargo check -p wasm-drive-verify.cargo check --workspace --all-targets(the new field is set in every struct literal a search of the repository finds). No full suite was run locally.In-place changes to shipped generations
SingleDocumentDriveQuery::construct_path_queryhad no generations, and every protocol version ran it. It is now a dispatcher. Protocol versions 1 to 14 select generation 0 (their tables setsingle_document_path_queryto 0), which is the function's body before fix(drive): verify a single document that may be contested (PV15) #5835, moved unchanged: its two helpers differ only bypub(super). Tests pin that protocol version 14 builds the queries it built. It is not on a consensus path.DRIVE_DOCUMENT_METHOD_VERSIONS_V1toV4gain the new field, set to 0, which selects that unchanged code.verify_proof_keep_serialized1 is edited in place. Only protocol version 15's table selects it, and it is not released.Breaking Changes
None. Calls that returned an error or a wrong answer at protocol version 15 now return the right one. Rust code outside this repository that builds
DriveDocumentQueryMethodVersionswith a struct literal must add the new field.Checklist:
structure.rs, regeneratedgrovedb-structure.json, and checked the structure viewer link posted on this pull requestFor repository code-owners and collaborators only
🤖 Generated with Claude Code
PR Hygiene ·
cfc146a/skip-botsproceeds without the ones not yet reported/self-reviewedWhen every merge requirement is met, the
PR Hygienecheck passes. Reviewer limits do not block merging; other required GitHub checks and protections still apply.Summary by CodeRabbit
New Features
Documentation