Repository navigation
fix(node): ANS-104 codec and recovery policy types (#26 split 2/4) - #524
Merged
Merged
Conversation
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds the ANS-104 data item codec and the three-outcome recovery policy types for #26 (split 2/4). Continues #385 by @Gravirei. The 13 commits are carried over unchanged and keep their authorship; main was merged in as a separate commit.
Motivation & context
Reviewer 2 closed PR #224 on 2026-08-28 with a directive: split the work into four narrow PRs. This is Split PR 2.
The P1 finding the reviewer assigned to this split: the legacy
anchor_item_presentmappedBAD_REQUESTandGONEtoOk(false), and the recovery code interpreted false as permission to reclaim the row and pay for another upload. Neither 400 nor 410 proves a previously paid item was never accepted: 410 can describe an artifact that existed but is no longer served, and 400 can be produced by gateway, proxy, or routing failure. The concrete failure sequence the reviewer named: bundler accepts the item, the response or terminal DB write is lost, recovery probes the persisted item_id, the gateway returns 400 or 410, and the node pays for a second immutable item for the same transition.Fix: model the probe result as three outcomes, and authorize a re-upload only on a trustworthy, protocol-defined absence.
Round-5 direction (reviewer 2): land here only the standard-compatible ANS-104 primitives and the pure three-outcome policy types. The gateway probe, the
verify_anchorpath, and the public verify endpoint are deferred until the uploader, retrieval proof, and recovery consumer can be proven as one vertical slice against a real provider contract (same-network upload/read pair, redirect-safe client, envelope-supplying read API, provider-documented absence evidence).Refs #26
Kind of change
What changed
Crate touched: gitlawb-node (plus golden-vector scripts under
scripts/).ans104: ANS-104 data item (de)serialization, deep-hash matchingarbundles@0.10.xgetSignatureData(8-element fold, verified byte-exact against the JS implementation), Ed25519 sign/verify (strict), full two-byte signature-type validation, raw-tag-payload preservation across parse/hash/encode. unit tests including a real arbundles-signed Ed25519 golden vector (verified without re-signing), multi-block and size-prefixed tag blocks, and a non-canonical-sigtype rejection test.arweave_v2(policy types only): theProbeOutcomemodel the reviewer demanded —Present/DefinitivelyAbsent/Indeterminate— plus thepermits_reuploadrule, with a unit test. No gateway client, no endpoint.scripts/ans104_golden_ed25519.mjs, output doc) capturing the interop fixture from the pinnedarbundlesdependency.Deferred to the vertical slice (explicitly NOT in this PR): the gateway probe (
probe_anchor_item), theverify_anchorpath,GET /api/v1/arweave/anchors/verify/{item_id}, theirys_tx_idlookup method and index migration, and the gateway/rate-limit config knobs. There is therefore no provider response table here:DefinitivelyAbsentis authorized only by whatever evidence the future provider contract defines, and every ambiguous response stays retryable.How a reviewer can verify
Full workspace suite runs on CI.
crates/gitlawb-node/src/ans104.rs::tests:dataitem_matches_arbundles_golden_vector— real arbundles-signed Ed25519 item: shape pin, id pin, deep-hash pin againstgetSignatureData, verify without re-signing against an independently pinned expected key, byte-exact binary round-trip.signed_binary_parse_and_verify_multi_block_and_negative_count— non-canonical tag encodings hash the original payload bytes and verify without re-signing.decode_tags_accepts_negative_block_count_with_size— legal size-prefixed Avro form parses.from_binary_rejects_non_canonical_signature_type_high_byte— wire02 01(258) is rejected, never aliased onto Ed25519 type 2.binary_round_trip— signature slot, canonical owner, and payload surviveto_binary/from_binarywith the signature intact (no re-sign after parse).sign_then_verify_round_trips,flipped_signature_byte_fails_verify,wrong_expected_pubkey_fails_verify,mutated_data_fails_verify,wire_shape_round_trip,deep_hash_is_stable,deep_hash_empty_tags_is_distinct_from_one_tag,data_item_id_is_base64url_of_sha256_of_signature— round-trip, tamper, and derivation pins.external_reference_vectors(3 tests) — SHA-384 deep-hash primitives against the reference suite.crates/gitlawb-node/src/arweave_v2.rs::tests:only_definitively_absent_authorizes_reupload— the policy: collapsing any ambiguous outcome to absent spends a second immutable upload for the same transition.Each test names the invariant it pins. Reverting the covered line turns the assertion red.
Before you request review
cargo test --workspacepasses locally (theans104filter passes on the merged tree; the full suite runs on CI)cargo fmt --allandcargo clippy --workspace --all-targets -- -D warningsare cleanfeat(...),fix(...),docs(...)).env.exampleupdated if behavior or config changed (N/A: no config or behavior change)Protocol & signing impact
did:key, Ed25519 / RFC 9421 signatures, UCAN, ref certs, or P2P wire formatsNotes for reviewers
ProbeOutcome::permits_reuploadis the policy the reviewer demanded: onlyDefinitivelyAbsentauthorizes a paid re-upload.Indeterminatekeeps the outbox non-terminal; the next probe (or a future retry) gets another chance to give a trustworthy answer. The exact evidence that establishesDefinitivelyAbsentis defined by the provider contract in the vertical slice that introduces the probe — never by a mock-only body shape.Why this is its own PR
PR 2 owns ANS-104 serialization/verification and recovery outcome classification. The bundler upload itself (the handler that builds a DataItem and POSTs to the bundler), the provider-backed probe, and the public verification endpoint live in later slices. The ANS-104 module is fully tested and ready for the bundler upload to call into. PR 1's recovery drain consumes
ProbeOutcome::permits_reupload; the probe that produces the outcome arrives with the provider contract.Overlap with open PRs
Safety to land standalone
arweave_anchorstable is untouched.main.rs/server.rsmodule wiring and a comment.Summary by CodeRabbit