Repository navigation
vtxo: authenticate expiry against batch evidence - #1244
Conversation
|
/gateway review |
|
❌ gateway review failed: code-review skill failed across all auth modes: You've hit your session limit · resets 4:40pm (UTC) See workflow logs for details. |
|
/gateway review |
There was a problem hiding this comment.
Gateway review — 6 findings
🔴 0 Blocker · 🟠 3 Major · 🟡 3 Minor · 🔵 0 Nit
Summary
The PR replaces operator-authored absolute expiry with a deadline derived from authenticated batch evidence plus the wallet's own reorg-aware confirmation observation, and removes absolute timing from unilateral-exit proof gating. The direction is right: RelativeExpiry now comes from the locally owned receive record (which is also what the tapscript was derived from), the unroll shape gate no longer lets forged timing metadata strand recoverable funds, and LineageEffectiveExpiry is correctly fail-closed on missing/reconciling/reorged lineage.
Three things concern me. First, the new sweep-script check in batchcanon/rpc_evidence.go compares a root the server supplies against a leaf built from a key and delay the same server supplies; nothing in this file binds sweep_tapscript_root to the commitment output that is authenticated, so the check as written does not by itself constrain the delay. Second, the producers now persist BatchExpiry = 0 unconditionally while the derived deadline only materializes when ExpiryCanonicality is wired and the batch is registered — the fallback for a misconfigured or not-yet-registered wallet is "no deadline at all", and nothing fails loudly. Third, backfillAuthenticatedAncestry installs and persists indexer-supplied ancestry without binding it to the descriptor's commitment, and that ancestry is exactly what selects which batches determine the deadline.
The new tests are good at the helper level but never drive an automatic event through VTXOActor.Receive with an unavailable record, so the FSM's behavior at BatchExpiry == 0 — the state this PR makes reachable everywhere — is unpinned.
Bot commands
/gateway re-review— re-run after pushing changes (maintainers)/gateway dismiss <id>— silence a finding (maintainers)/gateway explain <id>— elaborate on a finding (anyone)
|
🤖 gateway audit metadata for this PR — auto-generated, please don't edit. |
|
This PR's authenticated-expiry work left the per-package docs for diff --git a/arkrpc/AGENTS.md b/arkrpc/AGENTS.md
index f14c8319..2f749fc3 100644
--- a/arkrpc/AGENTS.md
+++ b/arkrpc/AGENTS.md
@@ -22,12 +22,19 @@ Proto source: `arkrpc/ark.proto`, `arkrpc/indexer.proto`.
PSBTs that `IncomingOOREvent` intentionally omits.
- `VTXO` — Phase 2 query response from `ListVTXOsByScripts`. Carries
authoritative lineage metadata including the structured `TreePath`.
+- `AncestryPath` — one rooted commitment-tree fragment plus the canonicality
+ evidence the client authenticates it against: `commitment_tx`,
+ `commitment_inputs`, `commitment_height`, `commitment_csv_expiry_delta`, and
+ `commitment_sweep_key` (field 9, the compressed pubkey in the commitment
+ output's CSV sweep leaf). The delta and the sweep key are only meaningful as
+ a pair — the client recomputes the sweep tapscript root from both and
+ compares it against the fragment's committed root.
## Relationships
- **Depends on**: `lib/tree` (for conversion utilities in `tree_path_convert.go`).
-- **Depended on by**: `indexer`, `waved`, `serverconn`, `oor` (uses generated
- clients and conversion helpers).
+- **Depended on by**: `indexer`, `waved`, `serverconn`, `oor`, `batchcanon`
+ (uses generated clients and conversion helpers).
## Invariants
diff --git a/arkrpc/CLAUDE.md b/arkrpc/CLAUDE.md
index f14c8319..2f749fc3 100644
--- a/arkrpc/CLAUDE.md
+++ b/arkrpc/CLAUDE.md
@@ -22,12 +22,19 @@ Proto source: `arkrpc/ark.proto`, `arkrpc/indexer.proto`.
PSBTs that `IncomingOOREvent` intentionally omits.
- `VTXO` — Phase 2 query response from `ListVTXOsByScripts`. Carries
authoritative lineage metadata including the structured `TreePath`.
+- `AncestryPath` — one rooted commitment-tree fragment plus the canonicality
+ evidence the client authenticates it against: `commitment_tx`,
+ `commitment_inputs`, `commitment_height`, `commitment_csv_expiry_delta`, and
+ `commitment_sweep_key` (field 9, the compressed pubkey in the commitment
+ output's CSV sweep leaf). The delta and the sweep key are only meaningful as
+ a pair — the client recomputes the sweep tapscript root from both and
+ compares it against the fragment's committed root.
## Relationships
- **Depends on**: `lib/tree` (for conversion utilities in `tree_path_convert.go`).
-- **Depended on by**: `indexer`, `waved`, `serverconn`, `oor` (uses generated
- clients and conversion helpers).
+- **Depended on by**: `indexer`, `waved`, `serverconn`, `oor`, `batchcanon`
+ (uses generated clients and conversion helpers).
## Invariants
diff --git a/batchcanon/AGENTS.md b/batchcanon/AGENTS.md
index 212ac7a3..86053d11 100644
--- a/batchcanon/AGENTS.md
+++ b/batchcanon/AGENTS.md
@@ -70,15 +70,29 @@ decides canonicality, and the VTXO manager remains the admission boundary.
generation, re-arms watches, requires an explicit current fact per subject,
and only installs `Ready(g)` + derived state atomically — admission stays
closed until then, so a persisted conflict can never transiently look usable.
+ `WaitReconciled(ctx)` is the companion startup barrier: it blocks until every
+ watch armed by `Reconcile` has a current observation, so expiry consumers do
+ not read a deliberately-not-ready record on the first recovered block.
+- `EvidenceFromAncestryPaths` / `BatchEvidence` — the receive-boundary
+ authenticator for indexer-supplied ancestry. It binds the transport fields to
+ the serialized commitment tx and cross-checks that the advertised
+ `commitment_csv_expiry_delta` and `commitment_sweep_key` recompute the tree
+ fragment's committed sweep tapscript root. It is only half the boundary:
+ callers must also verify the recomputed taproot key against the authenticated
+ output (`VerifyReceivedVTXOBinding` / `VerifyOORAncestryLineage`) before
+ registration.
## Relationships
- **Depends on**: `btcd/chainhash`, `btcd/wire`, `lnd/fn/v2` only (plus
- `baselib/actor` + `chainsource` for the `Manager`). The reducer/model
+ `baselib/actor` + `chainsource` for the `Manager`, and `arkrpc` +
+ `lib/arkscript` for the ancestry-evidence authenticator in
+ `rpc_evidence.go`). The reducer/model
(`state.go`, `availability.go`, `record.go`) is deliberately dependency-light
so the **server can reuse the same reducer** (lumos#454 Server PR2).
-- **Depended on by**: `db` (concrete `Store`), `vtxo` (admission gate), and the
- round/OOR producers (registration before exposure).
+- **Depended on by**: `db` (concrete `Store`), `vtxo` (admission gate and
+ authenticated expiry), and the round/OOR producers (registration before
+ exposure).
## Invariants
@@ -93,6 +107,14 @@ decides canonicality, and the VTXO manager remains the admission boundary.
observation; the logical `ConsumerEdge` graph drives inherited lineage and
conditional restore.
- Expiry is never persisted as a standalone/terminal value; always derived.
+ `LineageEffectiveExpiry` is the only supported way to turn a lineage into a
+ deadline, and it returns `None` — never a fallback height — whenever any
+ contributing batch is missing, not `Ready()`, or not `Usable()`.
+- The CSV expiry delta is authenticated, not advertised. `commitment_sweep_key`
+ plus a strictly-positive `commitment_csv_expiry_delta` must rebuild the
+ `UnilateralCSVTimeoutTapLeaf` whose tap hash equals the fragment's
+ `sweep_tapscript_root`; a mismatch rejects the evidence outright, so an
+ operator cannot lengthen a batch's apparent life.
- State enum integer values are append-only (persisted column).
- Restart increments the observation generation before any watch is armed;
admission is closed until `Ready(g)` installs a complete snapshot.
diff --git a/batchcanon/CLAUDE.md b/batchcanon/CLAUDE.md
index 212ac7a3..86053d11 100644
--- a/batchcanon/CLAUDE.md
+++ b/batchcanon/CLAUDE.md
@@ -70,15 +70,29 @@ decides canonicality, and the VTXO manager remains the admission boundary.
generation, re-arms watches, requires an explicit current fact per subject,
and only installs `Ready(g)` + derived state atomically — admission stays
closed until then, so a persisted conflict can never transiently look usable.
+ `WaitReconciled(ctx)` is the companion startup barrier: it blocks until every
+ watch armed by `Reconcile` has a current observation, so expiry consumers do
+ not read a deliberately-not-ready record on the first recovered block.
+- `EvidenceFromAncestryPaths` / `BatchEvidence` — the receive-boundary
+ authenticator for indexer-supplied ancestry. It binds the transport fields to
+ the serialized commitment tx and cross-checks that the advertised
+ `commitment_csv_expiry_delta` and `commitment_sweep_key` recompute the tree
+ fragment's committed sweep tapscript root. It is only half the boundary:
+ callers must also verify the recomputed taproot key against the authenticated
+ output (`VerifyReceivedVTXOBinding` / `VerifyOORAncestryLineage`) before
+ registration.
## Relationships
- **Depends on**: `btcd/chainhash`, `btcd/wire`, `lnd/fn/v2` only (plus
- `baselib/actor` + `chainsource` for the `Manager`). The reducer/model
+ `baselib/actor` + `chainsource` for the `Manager`, and `arkrpc` +
+ `lib/arkscript` for the ancestry-evidence authenticator in
+ `rpc_evidence.go`). The reducer/model
(`state.go`, `availability.go`, `record.go`) is deliberately dependency-light
so the **server can reuse the same reducer** (lumos#454 Server PR2).
-- **Depended on by**: `db` (concrete `Store`), `vtxo` (admission gate), and the
- round/OOR producers (registration before exposure).
+- **Depended on by**: `db` (concrete `Store`), `vtxo` (admission gate and
+ authenticated expiry), and the round/OOR producers (registration before
+ exposure).
## Invariants
@@ -93,6 +107,14 @@ decides canonicality, and the VTXO manager remains the admission boundary.
observation; the logical `ConsumerEdge` graph drives inherited lineage and
conditional restore.
- Expiry is never persisted as a standalone/terminal value; always derived.
+ `LineageEffectiveExpiry` is the only supported way to turn a lineage into a
+ deadline, and it returns `None` — never a fallback height — whenever any
+ contributing batch is missing, not `Ready()`, or not `Usable()`.
+- The CSV expiry delta is authenticated, not advertised. `commitment_sweep_key`
+ plus a strictly-positive `commitment_csv_expiry_delta` must rebuild the
+ `UnilateralCSVTimeoutTapLeaf` whose tap hash equals the fragment's
+ `sweep_tapscript_root`; a mismatch rejects the evidence outright, so an
+ operator cannot lengthen a batch's apparent life.
- State enum integer values are append-only (persisted column).
- Restart increments the observation generation before any watch is armed;
admission is closed until `Ready(g)` installs a complete snapshot.
diff --git a/oor/AGENTS.md b/oor/AGENTS.md
index bb983c14..48e8b40e 100644
--- a/oor/AGENTS.md
+++ b/oor/AGENTS.md
@@ -31,6 +31,11 @@ For field-level detail, use `go doc github.com/lightninglabs/wavelength/oor.<Sym
- `ReceiveLimits` / `DefaultReceiveLimits` — defense-in-depth bounds on
incoming receive (`MaxCheckpoints`, `MaxVTXOMatches`, `MaxMailboxItems`,
`MaxMailboxScriptBytes`, `MaxConcurrentIncomingSessions`).
+- `IncomingVTXOMetadata` — lineage plus advisory timing metadata for an
+ incoming OOR VTXO (`RoundID`, `CommitmentTxID`, `BatchExpiry`, `ChainDepth`,
+ `CreatedHeight`). Only the lineage fields are authoritative; `BatchExpiry` is
+ the sender/indexer's advisory scalar and is deliberately not copied onto the
+ descriptor (see Invariants).
## Relationships
@@ -116,6 +121,12 @@ For field-level detail, use `go doc github.com/lightninglabs/wavelength/oor.<Sym
attempt counts reach `maxResolveRetries` / `maxMetadataRetries` (20),
freeing the session's concurrency slot instead of pinning a child forever
on operator silence.
+- `BuildIncomingVTXODescriptor` writes `BatchExpiry: 0` rather than copying
+ `IncomingVTXOMetadata.BatchExpiry`. The absolute expiry is operator-authored,
+ so trusting it would let the sender name an arbitrary deadline; the VTXO
+ actor derives the deadline from authenticated batch-canonicality evidence
+ across the contributing rounds instead. `RelativeExpiry` still comes from the
+ locally-known `ExitDelay`, not from metadata.
- Incoming ancestor packages are capped at `maxAncestorPackages = 64`
checkpoints, and indexer-supplied `tree_depth` is cross-checked against the
reconstructed path via `arkrpc.ValidateAncestryPathDepth`.
diff --git a/oor/CLAUDE.md b/oor/CLAUDE.md
index bb983c14..48e8b40e 100644
--- a/oor/CLAUDE.md
+++ b/oor/CLAUDE.md
@@ -31,6 +31,11 @@ For field-level detail, use `go doc github.com/lightninglabs/wavelength/oor.<Sym
- `ReceiveLimits` / `DefaultReceiveLimits` — defense-in-depth bounds on
incoming receive (`MaxCheckpoints`, `MaxVTXOMatches`, `MaxMailboxItems`,
`MaxMailboxScriptBytes`, `MaxConcurrentIncomingSessions`).
+- `IncomingVTXOMetadata` — lineage plus advisory timing metadata for an
+ incoming OOR VTXO (`RoundID`, `CommitmentTxID`, `BatchExpiry`, `ChainDepth`,
+ `CreatedHeight`). Only the lineage fields are authoritative; `BatchExpiry` is
+ the sender/indexer's advisory scalar and is deliberately not copied onto the
+ descriptor (see Invariants).
## Relationships
@@ -116,6 +121,12 @@ For field-level detail, use `go doc github.com/lightninglabs/wavelength/oor.<Sym
attempt counts reach `maxResolveRetries` / `maxMetadataRetries` (20),
freeing the session's concurrency slot instead of pinning a child forever
on operator silence.
+- `BuildIncomingVTXODescriptor` writes `BatchExpiry: 0` rather than copying
+ `IncomingVTXOMetadata.BatchExpiry`. The absolute expiry is operator-authored,
+ so trusting it would let the sender name an arbitrary deadline; the VTXO
+ actor derives the deadline from authenticated batch-canonicality evidence
+ across the contributing rounds instead. `RelativeExpiry` still comes from the
+ locally-known `ExitDelay`, not from metadata.
- Incoming ancestor packages are capped at `maxAncestorPackages = 64`
checkpoints, and indexer-supplied `tree_depth` is cross-checked against the
reconstructed path via `arkrpc.ValidateAncestryPathDepth`.
diff --git a/unroll/AGENTS.md b/unroll/AGENTS.md
index 95cbd240..88ad805b 100644
--- a/unroll/AGENTS.md
+++ b/unroll/AGENTS.md
@@ -243,7 +243,14 @@ For field-level detail, use `go doc github.com/lightninglabs/wavelength/unroll.<
- `validateProofDescriptorShape` checks `len(desc.Ancestry) == 0`
(was `desc.TreePath == nil`) and validates each fragment
individually (non-nil `TreePath`, non-nil root, non-zero
- `CommitmentTxID`, non-zero `TreeDepth`).
+ `CommitmentTxID`). It deliberately does **not** check
+ `BatchExpiry` or `TreeDepth`: both are expiry-timing scalars, not
+ proof material, and `BatchExpiry` is now left unset on ingest until
+ the VTXO actor derives it from authenticated batch evidence.
+ Blocking on either would let missing or forged timing metadata
+ strand otherwise-recoverable funds. `TreeDepth` is still validated
+ against `TreePath.Depth()` at the ingest boundary
+ (`oor.validateIncomingAncestry` / `waved.ancestryFromRPC`).
- `BuildProofFromMaterial` calls `addTreePathNodes` once per tree
path, tolerating overlapping ancestry (duplicate txids silently
deduped; conflicting duplicates — same txid, different bytes — are
diff --git a/unroll/CLAUDE.md b/unroll/CLAUDE.md
index 95cbd240..88ad805b 100644
--- a/unroll/CLAUDE.md
+++ b/unroll/CLAUDE.md
@@ -243,7 +243,14 @@ For field-level detail, use `go doc github.com/lightninglabs/wavelength/unroll.<
- `validateProofDescriptorShape` checks `len(desc.Ancestry) == 0`
(was `desc.TreePath == nil`) and validates each fragment
individually (non-nil `TreePath`, non-nil root, non-zero
- `CommitmentTxID`, non-zero `TreeDepth`).
+ `CommitmentTxID`). It deliberately does **not** check
+ `BatchExpiry` or `TreeDepth`: both are expiry-timing scalars, not
+ proof material, and `BatchExpiry` is now left unset on ingest until
+ the VTXO actor derives it from authenticated batch evidence.
+ Blocking on either would let missing or forged timing metadata
+ strand otherwise-recoverable funds. `TreeDepth` is still validated
+ against `TreePath.Depth()` at the ingest boundary
+ (`oor.validateIncomingAncestry` / `waved.ancestryFromRPC`).
- `BuildProofFromMaterial` calls `addTreePathNodes` once per tree
path, tolerating overlapping ancestry (duplicate txids silently
deduped; conflicting duplicates — same txid, different bytes — are
diff --git a/vtxo/AGENTS.md b/vtxo/AGENTS.md
index dd5718e3..6f9411fc 100644
--- a/vtxo/AGENTS.md
+++ b/vtxo/AGENTS.md
@@ -18,7 +18,9 @@ when the local wallet owns the receive script.
(the authoritative semantic policy for ownership/spend semantics),
`PkScript`, `ClientKey` (keychain.KeyDescriptor), `OperatorKey`,
`TapScript`, `Ancestry []Ancestry`, `RoundID`, `CommitmentTxID`,
- `BatchExpiry`, `RelativeExpiry`, `ChainDepth` (OOR hop count),
+ `BatchExpiry` (actor-derived from authenticated batch evidence, never copied
+ from a wire event or indexer response), `RelativeExpiry` (derived from the
+ local receive script's exit delay), `ChainDepth` (OOR hop count),
`CreatedHeight`, `Status`, `ConstructionVersion` (zero-indexed build-rule
version stamped at creation; validated only at the ingress edge, trusted
verbatim once persisted). Use `EffectivePkScript`/`EffectivePolicyTemplate`
@@ -40,7 +42,15 @@ when the local wallet owns the receive script.
stored key is never reused). `ForfeitParticipantSigner` collects non-local
participant signatures for custom VTXO policies after connector assignment.
`TerminalVTXOObserver` fires with the outpoint whenever a VTXO leaves the
- active set. `ExitOutcomeResolver` is called at startup to reconcile VTXOs
+ active set. `BatchCanonicality` is the staged coin-selection admission gate,
+ while `ExpiryCanonicality` is a separate `batchcanon.Reader` supplying
+ authenticated, reorg-aware expiry evidence — the two are deliberately
+ independent so authenticated expiry works whether or not the admission gate
+ is enabled. `AncestryFetcher` (`IncomingAncestryFetcher`) and
+ `BatchRegistrar` (`IncomingBatchRegistrar`) are propagated to each VTXO actor
+ so a descriptor materialized from a thin push can upgrade to authenticated
+ lineage after a transient indexer failure or a daemon restart.
+ `ExitOutcomeResolver` is called at startup to reconcile VTXOs
still persisted in `VTXOStatusUnilateralExit` with their terminal job
outcome. `ReservationStore` is used at startup to sweep orphaned Spending
VTXOs.
@@ -90,6 +100,16 @@ when the local wallet owns the receive script.
- `ManagerMsg` / `ManagerResp` — Type aliases for `actormsg.VTXOManagerMsg` / `actormsg.VTXOManagerResp` (admission types live in `lib/actormsg` to avoid import cycles).
- `IncomingVTXOHandler` — Actor that consumes `arkrpc.IncomingVTXOEvent` push notifications, looks up the receive script in the owned-script store, builds a `Descriptor` (with tapscript and relative expiry derived from the local receive record), persists it via `VTXOSaver`, and tells the manager via `VTXOsMaterializedNotification`. The operator-authored absolute expiry is not persisted as a trusted deadline. Only `VTXO_EVENT_TYPE_CREATED` events are acted on; unknown event kinds and unowned scripts are silently ignored. Inputs are validated for outpoint shape, pkScript presence, and `int64`/`MaxSatoshi` value bounds before any DB write.
- `VTXOActor.refreshAuthenticatedExpiry` — Before each automatic expiry event, retries missing thin-push ancestry, then derives the earliest deadline across the complete lineage from batch-canonicality confirmation observations plus script-authenticated CSV delays. It persists every deadline change so store-backed RPC and cohort reads cannot reuse operator metadata. Missing or reorged evidence persists an unset deadline and keeps admission fail-closed.
+- `IncomingAncestryFetcher` / `IncomingBatchRegistrar` — the two seams the
+ authenticated-lineage repair path needs. The fetcher resolves ancestry plus
+ created-height for one owned outpoint under the owner's proof-of-control; the
+ registrar durably registers the resulting `batchcanon.RegisterBatchRequest`
+ before the descriptor is persisted or exposed. Both are optional: unset (the
+ legacy harness wiring) leaves the actor fail-closed rather than falling back
+ to operator metadata.
+- `LineageCommitmentTxIDs(desc)` — the deduped commitment-txid set (direct
+ commitment plus every distinct cross-commitment ancestor batch) that both the
+ admission gate and `batchcanon.LineageEffectiveExpiry` are keyed on.
- `IncomingVTXOMsg` / `IncomingVTXOResp` — Actor envelope wrapping an `arkrpc.IncomingVTXOEvent` and the `any`-typed response.
- `IncomingVTXOServiceKey` — Well-known service key (`"incoming-vtxo-handler"`) used by `waved` to register the actor and by `serverconn.EventRouter` to dispatch routed events.
- `OwnedReceiveScript` / `OwnedScriptLookup` — Read-only view of the owned receive scripts store used by the incoming handler. `LookupOwnedReceiveScript` returns `sql.ErrNoRows` for unknown scripts; the handler treats this as "not ours" and exits cleanly.
@@ -100,7 +120,7 @@ when the local wallet owns the receive script.
## Relationships
-- **Depends on**: `baselib/protofsm` (FSM engine), `baselib/actor` (actor system), `lib/types` (`Ancestry`), `lib/arkscript` (taproot construction and policy helpers in `IncomingVTXOHandler`), `lib/actormsg` (admission and custom-forfeit message types), `arkrpc` (`IncomingVTXOEvent`), `chainsource` (block epochs), `coinselect` (largest-first VTXO selection), `metrics` (optional `OORTransferReceivedMsg` sink), `ledger` (`Sink` type for compatibility with manager wiring), `unroll` (via `ExitOutcomeResolver` callback wired by `waved`).
+- **Depends on**: `baselib/protofsm` (FSM engine), `baselib/actor` (actor system), `lib/types` (`Ancestry`), `lib/arkscript` (taproot construction and policy helpers in `IncomingVTXOHandler`), `lib/actormsg` (admission and custom-forfeit message types), `arkrpc` (`IncomingVTXOEvent`), `batchcanon` (`Reader` for the admission gate and for authenticated expiry; `BatchEvidence` registration on the incoming path), `chainsource` (block epochs), `coinselect` (largest-first VTXO selection), `metrics` (optional `OORTransferReceivedMsg` sink), `ledger` (`Sink` type for compatibility with manager wiring), `unroll` (via `ExitOutcomeResolver` callback wired by `waved`).
- **Depended on by**: `round` (triggers forfeit requests), `oor` (incoming VTXOs), `wallet` (admission gating), `db` (persistence), `waved` (wiring, owned-script adapters, incoming event route, and `CheckForfeitAdmission` for the leave filter and exit-plan advisory), `sdk/swaps` (forfeit sign-request conversion).
- **Sends**:
- → `round` (via manager relay): `RelayToRoundMsg` wrapping `ForfeitSignatureSubmission`
@@ -185,7 +205,8 @@ when the local wallet owns the receive script.
- Admission types (`SelectAndReserveSpendRequest`, `SelectAndReserveForfeitRequest`, `ReserveForfeitRequest`, etc.) are defined in `lib/actormsg` and re-exported as type aliases to avoid wallet → vtxo → round → wallet import cycles.
- `selectAndReserveVTXOs` is a shared helper parameterized by `reserveParams` that serves both the OOR spend and cooperative forfeit coin selection paths, avoiding code duplication.
- `IncomingVTXOHandler` only handles `VTXO_EVENT_TYPE_CREATED` events. Other event kinds, missing/short outpoints, empty pkScripts, oversized values (`> int64` or `> MaxSatoshi`), and tapscript derivation failures all return success without persisting — they cannot crash the actor or block the indexer push stream. Real DB lookup/save errors are surfaced.
-- Incoming VTXOs are saved with `Status: VTXOStatusLive` and empty `Ancestry` (the round commitment tree is not pushed alongside the event); `db.VTXOPersistenceStore.descriptorToInsertParams` accepts an empty tree-path blob to support this.
+- Incoming VTXOs are saved with `Status: VTXOStatusLive`. The push carries no commitment tree, so `Ancestry` is whatever `IncomingAncestryFetcher` resolved — empty when the fetcher is unset or the indexer was unreachable; `db.VTXOPersistenceStore.descriptorToInsertParams` accepts an empty tree-path blob to support this. A thin save is repaired later by `VTXOActor.backfillAuthenticatedAncestry`, which registers the batch evidence *before* persisting the upgraded descriptor so a crash mid-repair can never expose unauthenticated lineage.
+- **Absolute expiry is never taken from the wire or the store.** The incoming handler writes `BatchExpiry: 0`, `NewVTXOActor` zeroes any persisted value whenever `ExpiryCanonicality` is configured, and only `refreshAuthenticatedExpiry` may set it. The actor tracks that discarded value (`authenticatedExpiryDirty`) so the first automatic check overwrites the row even when the safe derived value is still zero — otherwise a store-backed RPC or cohort read would keep serving operator metadata. `backfillAuthenticatedAncestry` bounds its indexer fetch at `authenticatedAncestryFetchTimeout` (1 s) so an unavailable indexer cannot pin a VTXO actor; the deadline stays unset and the next block retries.
- The `CommitmentTxID` on a materialized incoming VTXO comes from `IncomingVTXOEvent.CommitmentTxid`, which is the round commitment txid — **not** the leaf txid in the outpoint.
- Per-subsystem logging: `ManagerConfig.Log` provides an optional instance logger; falls back to `build.LoggerFromContext` (no global mutable loggers).
diff --git a/vtxo/CLAUDE.md b/vtxo/CLAUDE.md
index dd5718e3..6f9411fc 100644
--- a/vtxo/CLAUDE.md
+++ b/vtxo/CLAUDE.md
@@ -18,7 +18,9 @@ when the local wallet owns the receive script.
(the authoritative semantic policy for ownership/spend semantics),
`PkScript`, `ClientKey` (keychain.KeyDescriptor), `OperatorKey`,
`TapScript`, `Ancestry []Ancestry`, `RoundID`, `CommitmentTxID`,
- `BatchExpiry`, `RelativeExpiry`, `ChainDepth` (OOR hop count),
+ `BatchExpiry` (actor-derived from authenticated batch evidence, never copied
+ from a wire event or indexer response), `RelativeExpiry` (derived from the
+ local receive script's exit delay), `ChainDepth` (OOR hop count),
`CreatedHeight`, `Status`, `ConstructionVersion` (zero-indexed build-rule
version stamped at creation; validated only at the ingress edge, trusted
verbatim once persisted). Use `EffectivePkScript`/`EffectivePolicyTemplate`
@@ -40,7 +42,15 @@ when the local wallet owns the receive script.
stored key is never reused). `ForfeitParticipantSigner` collects non-local
participant signatures for custom VTXO policies after connector assignment.
`TerminalVTXOObserver` fires with the outpoint whenever a VTXO leaves the
- active set. `ExitOutcomeResolver` is called at startup to reconcile VTXOs
+ active set. `BatchCanonicality` is the staged coin-selection admission gate,
+ while `ExpiryCanonicality` is a separate `batchcanon.Reader` supplying
+ authenticated, reorg-aware expiry evidence — the two are deliberately
+ independent so authenticated expiry works whether or not the admission gate
+ is enabled. `AncestryFetcher` (`IncomingAncestryFetcher`) and
+ `BatchRegistrar` (`IncomingBatchRegistrar`) are propagated to each VTXO actor
+ so a descriptor materialized from a thin push can upgrade to authenticated
+ lineage after a transient indexer failure or a daemon restart.
+ `ExitOutcomeResolver` is called at startup to reconcile VTXOs
still persisted in `VTXOStatusUnilateralExit` with their terminal job
outcome. `ReservationStore` is used at startup to sweep orphaned Spending
VTXOs.
@@ -90,6 +100,16 @@ when the local wallet owns the receive script.
- `ManagerMsg` / `ManagerResp` — Type aliases for `actormsg.VTXOManagerMsg` / `actormsg.VTXOManagerResp` (admission types live in `lib/actormsg` to avoid import cycles).
- `IncomingVTXOHandler` — Actor that consumes `arkrpc.IncomingVTXOEvent` push notifications, looks up the receive script in the owned-script store, builds a `Descriptor` (with tapscript and relative expiry derived from the local receive record), persists it via `VTXOSaver`, and tells the manager via `VTXOsMaterializedNotification`. The operator-authored absolute expiry is not persisted as a trusted deadline. Only `VTXO_EVENT_TYPE_CREATED` events are acted on; unknown event kinds and unowned scripts are silently ignored. Inputs are validated for outpoint shape, pkScript presence, and `int64`/`MaxSatoshi` value bounds before any DB write.
- `VTXOActor.refreshAuthenticatedExpiry` — Before each automatic expiry event, retries missing thin-push ancestry, then derives the earliest deadline across the complete lineage from batch-canonicality confirmation observations plus script-authenticated CSV delays. It persists every deadline change so store-backed RPC and cohort reads cannot reuse operator metadata. Missing or reorged evidence persists an unset deadline and keeps admission fail-closed.
+- `IncomingAncestryFetcher` / `IncomingBatchRegistrar` — the two seams the
+ authenticated-lineage repair path needs. The fetcher resolves ancestry plus
+ created-height for one owned outpoint under the owner's proof-of-control; the
+ registrar durably registers the resulting `batchcanon.RegisterBatchRequest`
+ before the descriptor is persisted or exposed. Both are optional: unset (the
+ legacy harness wiring) leaves the actor fail-closed rather than falling back
+ to operator metadata.
+- `LineageCommitmentTxIDs(desc)` — the deduped commitment-txid set (direct
+ commitment plus every distinct cross-commitment ancestor batch) that both the
+ admission gate and `batchcanon.LineageEffectiveExpiry` are keyed on.
- `IncomingVTXOMsg` / `IncomingVTXOResp` — Actor envelope wrapping an `arkrpc.IncomingVTXOEvent` and the `any`-typed response.
- `IncomingVTXOServiceKey` — Well-known service key (`"incoming-vtxo-handler"`) used by `waved` to register the actor and by `serverconn.EventRouter` to dispatch routed events.
- `OwnedReceiveScript` / `OwnedScriptLookup` — Read-only view of the owned receive scripts store used by the incoming handler. `LookupOwnedReceiveScript` returns `sql.ErrNoRows` for unknown scripts; the handler treats this as "not ours" and exits cleanly.
@@ -100,7 +120,7 @@ when the local wallet owns the receive script.
## Relationships
-- **Depends on**: `baselib/protofsm` (FSM engine), `baselib/actor` (actor system), `lib/types` (`Ancestry`), `lib/arkscript` (taproot construction and policy helpers in `IncomingVTXOHandler`), `lib/actormsg` (admission and custom-forfeit message types), `arkrpc` (`IncomingVTXOEvent`), `chainsource` (block epochs), `coinselect` (largest-first VTXO selection), `metrics` (optional `OORTransferReceivedMsg` sink), `ledger` (`Sink` type for compatibility with manager wiring), `unroll` (via `ExitOutcomeResolver` callback wired by `waved`).
+- **Depends on**: `baselib/protofsm` (FSM engine), `baselib/actor` (actor system), `lib/types` (`Ancestry`), `lib/arkscript` (taproot construction and policy helpers in `IncomingVTXOHandler`), `lib/actormsg` (admission and custom-forfeit message types), `arkrpc` (`IncomingVTXOEvent`), `batchcanon` (`Reader` for the admission gate and for authenticated expiry; `BatchEvidence` registration on the incoming path), `chainsource` (block epochs), `coinselect` (largest-first VTXO selection), `metrics` (optional `OORTransferReceivedMsg` sink), `ledger` (`Sink` type for compatibility with manager wiring), `unroll` (via `ExitOutcomeResolver` callback wired by `waved`).
- **Depended on by**: `round` (triggers forfeit requests), `oor` (incoming VTXOs), `wallet` (admission gating), `db` (persistence), `waved` (wiring, owned-script adapters, incoming event route, and `CheckForfeitAdmission` for the leave filter and exit-plan advisory), `sdk/swaps` (forfeit sign-request conversion).
- **Sends**:
- → `round` (via manager relay): `RelayToRoundMsg` wrapping `ForfeitSignatureSubmission`
@@ -185,7 +205,8 @@ when the local wallet owns the receive script.
- Admission types (`SelectAndReserveSpendRequest`, `SelectAndReserveForfeitRequest`, `ReserveForfeitRequest`, etc.) are defined in `lib/actormsg` and re-exported as type aliases to avoid wallet → vtxo → round → wallet import cycles.
- `selectAndReserveVTXOs` is a shared helper parameterized by `reserveParams` that serves both the OOR spend and cooperative forfeit coin selection paths, avoiding code duplication.
- `IncomingVTXOHandler` only handles `VTXO_EVENT_TYPE_CREATED` events. Other event kinds, missing/short outpoints, empty pkScripts, oversized values (`> int64` or `> MaxSatoshi`), and tapscript derivation failures all return success without persisting — they cannot crash the actor or block the indexer push stream. Real DB lookup/save errors are surfaced.
-- Incoming VTXOs are saved with `Status: VTXOStatusLive` and empty `Ancestry` (the round commitment tree is not pushed alongside the event); `db.VTXOPersistenceStore.descriptorToInsertParams` accepts an empty tree-path blob to support this.
+- Incoming VTXOs are saved with `Status: VTXOStatusLive`. The push carries no commitment tree, so `Ancestry` is whatever `IncomingAncestryFetcher` resolved — empty when the fetcher is unset or the indexer was unreachable; `db.VTXOPersistenceStore.descriptorToInsertParams` accepts an empty tree-path blob to support this. A thin save is repaired later by `VTXOActor.backfillAuthenticatedAncestry`, which registers the batch evidence *before* persisting the upgraded descriptor so a crash mid-repair can never expose unauthenticated lineage.
+- **Absolute expiry is never taken from the wire or the store.** The incoming handler writes `BatchExpiry: 0`, `NewVTXOActor` zeroes any persisted value whenever `ExpiryCanonicality` is configured, and only `refreshAuthenticatedExpiry` may set it. The actor tracks that discarded value (`authenticatedExpiryDirty`) so the first automatic check overwrites the row even when the safe derived value is still zero — otherwise a store-backed RPC or cohort read would keep serving operator metadata. `backfillAuthenticatedAncestry` bounds its indexer fetch at `authenticatedAncestryFetchTimeout` (1 s) so an unavailable indexer cannot pin a VTXO actor; the deadline stays unset and the next block retries.
- The `CommitmentTxID` on a materialized incoming VTXO comes from `IncomingVTXOEvent.CommitmentTxid`, which is the round commitment txid — **not** the leaf txid in the outpoint.
- Per-subsystem logging: `ManagerConfig.Log` provides an optional instance logger; falls back to `build.LoggerFromContext` (no global mutable loggers).
diff --git a/waved/AGENTS.md b/waved/AGENTS.md
index 6a2c1326..0a18f70c 100644
--- a/waved/AGENTS.md
+++ b/waved/AGENTS.md
@@ -37,7 +37,7 @@ For field-level detail, use `go doc github.com/lightninglabs/wavelength/waved.<S
- **Depends on**: `baselib/actor`, `btcwbackend`, `chainbackends`,
`chainsource`, `lib/actormsg`, `db`, `ledger`, `round`, `txconfirm`,
`unroll`, `vtxo`, `wallet`, `walletcore`, `oor`, `serverconn`, `indexer`,
- `arkrpc`, `lndbackend`, `fraud`, `gateway`, `rpc/restclient`,
+ `arkrpc`, `lndbackend`, `fraud`, `gateway`, `rpc/restclient`, `batchcanon`,
`vhtlcrecovery`, `vhtlcrecovery/coordinator`, `vhtlcrecovery/unrollpolicy`.
- **Depended on by**: `cmd/waved`.
@@ -225,6 +225,31 @@ For field-level detail, use `go doc github.com/lightninglabs/wavelength/waved.<S
pre-initialization fallback. All descriptor reads and startup writes go
through `loadClientKeyDesc` and `storeClientKeyDesc` because `GetInfo` is
callable while startup is publishing the value.
+- `initBatchCanonicality` blocks on `Manager.WaitReconciled` (bounded by
+ `DefaultRPCTimeout`) after `Reconcile` and before the VTXO manager starts.
+ Chain observations arrive asynchronously, so without this barrier a recovered
+ VTXO can burn its only catch-up event at the startup height while every
+ batch record is still deliberately not ready and its authenticated expiry is
+ unavailable. A timeout is a warning, not a failure: startup stays fail-closed
+ and a later block retries the expiry calculation.
+- The admission gate and the expiry view are wired from separate fields.
+ `s.batchCanonStore` (the staged coin-selection gate) is only populated when
+ the gate is explicitly enabled, while `s.batchCanonExpiry` is always set to
+ the live manager and threaded into `vtxo.ManagerConfig.ExpiryCanonicality`.
+ Collapsing the two would silently disable authenticated expiry wherever the
+ admission gate is still staged off.
+- `initVTXOManager` also threads `AncestryFetcher` (built from
+ `s.indexer` + `indexerProofSignerFactory`) and `BatchRegistrar` (present only
+ once `batchCanonRef` is set) so VTXO actors can repair thin-push descriptors.
+ Both are best-effort: a signer-factory or fetcher construction error logs
+ "VTXO ancestry backfill disabled" and leaves the seams nil rather than
+ failing startup.
+- `recoveryDescriptorFromIndexer` does not trust operator-authored expiry.
+ It persists `BatchExpiry: 0` and takes the exit delay from local operator
+ terms (`terms.VTXOExitDelay`) rather than `indexed.GetRelativeExpiry()` —
+ the query is scoped to a locally reconstructed receive script and the caller
+ rejects any returned pkScript that differs, so the local policy inputs are
+ the authenticated ones.
- The VTXO manager reads `FreeRefreshWindowBlocks` from the latest cached
operator terms on each expiry check. It delays automatic refresh to the
window boundary only when the local dynamic critical threshold plus retry
diff --git a/waved/CLAUDE.md b/waved/CLAUDE.md
index 6a2c1326..0a18f70c 100644
--- a/waved/CLAUDE.md
+++ b/waved/CLAUDE.md
@@ -37,7 +37,7 @@ For field-level detail, use `go doc github.com/lightninglabs/wavelength/waved.<S
- **Depends on**: `baselib/actor`, `btcwbackend`, `chainbackends`,
`chainsource`, `lib/actormsg`, `db`, `ledger`, `round`, `txconfirm`,
`unroll`, `vtxo`, `wallet`, `walletcore`, `oor`, `serverconn`, `indexer`,
- `arkrpc`, `lndbackend`, `fraud`, `gateway`, `rpc/restclient`,
+ `arkrpc`, `lndbackend`, `fraud`, `gateway`, `rpc/restclient`, `batchcanon`,
`vhtlcrecovery`, `vhtlcrecovery/coordinator`, `vhtlcrecovery/unrollpolicy`.
- **Depended on by**: `cmd/waved`.
@@ -225,6 +225,31 @@ For field-level detail, use `go doc github.com/lightninglabs/wavelength/waved.<S
pre-initialization fallback. All descriptor reads and startup writes go
through `loadClientKeyDesc` and `storeClientKeyDesc` because `GetInfo` is
callable while startup is publishing the value.
+- `initBatchCanonicality` blocks on `Manager.WaitReconciled` (bounded by
+ `DefaultRPCTimeout`) after `Reconcile` and before the VTXO manager starts.
+ Chain observations arrive asynchronously, so without this barrier a recovered
+ VTXO can burn its only catch-up event at the startup height while every
+ batch record is still deliberately not ready and its authenticated expiry is
+ unavailable. A timeout is a warning, not a failure: startup stays fail-closed
+ and a later block retries the expiry calculation.
+- The admission gate and the expiry view are wired from separate fields.
+ `s.batchCanonStore` (the staged coin-selection gate) is only populated when
+ the gate is explicitly enabled, while `s.batchCanonExpiry` is always set to
+ the live manager and threaded into `vtxo.ManagerConfig.ExpiryCanonicality`.
+ Collapsing the two would silently disable authenticated expiry wherever the
+ admission gate is still staged off.
+- `initVTXOManager` also threads `AncestryFetcher` (built from
+ `s.indexer` + `indexerProofSignerFactory`) and `BatchRegistrar` (present only
+ once `batchCanonRef` is set) so VTXO actors can repair thin-push descriptors.
+ Both are best-effort: a signer-factory or fetcher construction error logs
+ "VTXO ancestry backfill disabled" and leaves the seams nil rather than
+ failing startup.
+- `recoveryDescriptorFromIndexer` does not trust operator-authored expiry.
+ It persists `BatchExpiry: 0` and takes the exit delay from local operator
+ terms (`terms.VTXOExitDelay`) rather than `indexed.GetRelativeExpiry()` —
+ the query is scoped to a locally reconstructed receive script and the caller
+ rejects any returned pkScript that differs, so the local policy inputs are
+ the authenticated ones.
- The VTXO manager reads `FreeRefreshWindowBlocks` from the latest cached
operator terms on each expiry check. It delays automatic refresh to the
window boundary only when the local dynamic critical threshold plus retryHow to apply: save the block above to a file and run Run: https://github.com/lightninglabs/wavelength/actions/workflows/doc-gardening-pr.yml |
|
/gateway re-review |
|
❌ gateway re-review failed: code-review skill failed across all auth modes: You've hit your session limit · resets 9:40pm (UTC) See workflow logs for details. |
|
/gateway dismiss F1 |
|
/gateway dismiss F2 |
|
/gateway dismiss F3 |
|
/gateway dismiss F4 |
|
/gateway dismiss F5 |
|
/gateway dismiss F6 |
|
🚫 Dismissed F1 (major) by @bhandras — no reason given Open findings on this PR: 🟠 F2 (major) · 🟡 F4 (minor) · 🟡 F5 (minor) · 🟡 F6 (minor) |
|
🚫 Dismissed F3 (major) by @bhandras — no reason given Open findings on this PR: 🟠 F2 (major) · 🟡 F5 (minor) · 🟡 F6 (minor) |
|
🚫 Dismissed F4 (minor) by @bhandras — no reason given Open findings on this PR: 🟡 F5 (minor) · 🟡 F6 (minor) |
|
🚫 Dismissed F2 (major) by @bhandras — no reason given Open findings on this PR: 🟡 F5 (minor) · 🟡 F6 (minor) |
|
🚫 Dismissed F5 (minor) by @bhandras — no reason given Open findings on this PR: 🟡 F6 (minor) |
|
🚫 Dismissed F6 (minor) by @bhandras — no reason given All findings on this PR are addressed or dismissed. |
ce46774 to
da9a851
Compare
|
/gateway re-review |
|
❌ gateway re-review failed: code-review skill failed across all auth modes: You've hit your session limit · resets 9:40pm (UTC) See workflow logs for details. |
All Gateway findings were fixed or dismissed after individual evidence replies. Final-head re-review was requested but funding-blocked.
|
/gateway review |
|
gateway is already active on this PR. Reply with |
|
/gateway re-review |
|
❌ gateway re-review failed: code-review skill failed across all auth modes: You've hit your session limit · resets 9:40pm (UTC) See workflow logs for details. |
|
/gateway review |
26ea41f to
d907b43
Compare
There was a problem hiding this comment.
Gateway review — 7 findings
🔴 0 Blocker · 🟠 4 Major · 🟡 3 Minor · 🔵 0 Nit
Summary
This PR replaces operator-supplied absolute expiry with a locally-derived value: the client reconstructs the sweep leaf from the advertised key and CSV delay, requires its tap hash to match the tree's committed sweep root, byte-matches the batch output against a locally confirmed commitment transaction, and takes the earliest confirmationHeight + delay across the lineage. The core authentication in vtxo/authenticated_expiry.go is well-constructed — the tree-root recomputation via ComputeFinalKey plus the output value/script match closes the chain from the confirmed commitment back to the advertised delay, and the tests cover forged delays, substituted roots, and overflow.
The concerns are at the edges rather than in the proof. The new authenticator is a blocking chain-confirmation await wired into three synchronous paths that previously tolerated indexer degradation (incoming push handler, custom-refresh RPC, wallet recovery), and its error taxonomy folds transient chain-backend conditions into the permanent ErrInvalidBatchExpiryEvidence class that terminally fails an OOR session. Separately, the new relative-expiry derivation for custom policies reads a raw nSequence into a field the rest of the codebase treats as a block count.
Two changes look unrelated to the stated scope and would be easier to review separately: the AwaitingSubmitAccepted.RetryAfter/RetryReason snapshot persistence, and ManagerConfig.DeferAutomaticRefreshUntilRoundReady.
Bot commands
/gateway re-review— re-run after pushing changes (maintainers)/gateway dismiss <id>— silence a finding (maintainers)/gateway explain <id>— elaborate on a finding (anyone)
|
/gateway re-review Re-review current head |
|
❌ gateway re-review failed: code-review skill failed across all auth modes: You've hit your session limit · resets 1am (UTC) See workflow logs for details. |
cacfb28 to
2fe4c05
Compare
|
/gateway re-review Review exact head Independently verify the main funds-safety invariant: a received target gets an expiry only after the complete signed funding graph is bound to its exact outpoint, amount and script, and every contributing batch's deadline comes from the actual locally confirmed output and committed sweep policy. A real but unrelated later-expiring batch must not authorize the target. IndexedAncestryFromRPC now reconstructs OOR bridge transactions from additive VTXO.ancestry_packages, reuses Tree.Verify and recovery.NewProof, and executes signed inputs against actual parent outputs rather than PSBT prevout claims. Trace incoming thin pushes, OOR metadata acceptance, indexed seed recovery, recovered OOR events and custom refresh through that shared boundary. Check minimum expiry across all parents, omission of an earlier parent, same-commitment distinct leaves, malformed evidence versus retryable chain observations, and event/output comparison before persistence. Trace durable timeout, save-before-ack replay and canonical terminal-row reload. Recheck the individual thread replies against code; prior conclusions are not evidence. Validation: complete untagged root unit suite; affected vtxo/oor/waved/round race suite; changed-code lint with ordinary and system tags; signed target, unrelated batch, forged leaf body, mismatched output, multi-parent and recovery continuation regressions; SQLite and PostgreSQL incoming materialization/self-change/concurrency system tests; actual-producer direct, chained, multi-input and same-commitment OOR receives and indexed/offline seed recovery. Clean-tree format, module tidiness, SQL generation, migration and doc cross-links pass. Required tagged make unit is still finishing. All new commits are GitHub Verified. For each new finding, provide a concrete production trigger and execution trace, change attribution, existing producer/consumer guards and later recovery, realistic likelihood, consequence, smallest useful fix/test and fix regression risk. Classify blocker, follow-up, or not worth changing. Low likelihood does not dismiss a reachable funds/security defect; speculative invalid states, pre-existing debt and optional redesign do not block. Prefer the owning boundary. Do not revive the removed per-block canonicality architecture or expand activation-depth policy here. Stop once the named invariant and recovery paths are established with no material defect. Return a code verdict of BLOCKED, READY WITH FOLLOW-UPS, or READY, while keeping the pending dependency/history/CI gates explicit. |
There was a problem hiding this comment.
Gateway review — 5 findings
🔴 0 Blocker · 🟠 0 Major · 🟡 5 Minor · 🔵 0 Nit
Summary
The goal here is right and the mechanism is now sound: an indexed target only gets an expiry after its complete signed funding graph is bound to the exact outpoint/value/script, and each contributing batch's deadline comes from a locally confirmed output plus the sweep policy committed in that output's tapscript root.
I traced the invariant independently rather than relying on the thread replies. The binding chain holds: IndexedAncestryFromRPC puts every tree node and every reconstructed OOR package tx into one graph, requires each input to resolve to either an authenticated batch output or another graph node, executes each spend against its actual parent output (witnesses rebuilt from PSBT signature fields, so a forged WitnessUtxo buys nothing), and compares proof.TargetOutput() against the claimed value/script. Because the target outpoint's txid commits to that tx's outputs, a mismatched claim cannot survive; a valid-but-unrelated batch fails because the target txid is absent from the graph, and an omitted earlier parent fails on "no authenticated parent." AuthenticateBatchExpiry then re-checks each claimed batch output byte-for-byte against the confirmed transaction (with the tx-hash check doing the real authentication — pkScript/heightHint are correctly documented as lookup hints only) and takes the minimum across parents, which is the conservative direction. Same-commitment multi-leaf grouping and per-commitment lookup dedup both check out.
Six of the seven prior findings are addressed on this head. F5 is still present in the diff but is dependency code owned by #1199 and is minor, so it does not gate. Four new minor findings below — bounds on untrusted package lists, the legacy height-repair path now paying for full proof verification, an abort-on-first-failure sibling of F2's fix in recovered-OOR replay, and a confirmation transition that now hard-errors where it used to degrade. None is a blocker.
This is a code verdict only: the final rebase, #1199 merging, the #1262 duplicate removal, and CI (blocked by the main conflict) remain open, so READY WITH FOLLOW-UPS on the code, not merge-ready as a branch.
Status of prior findings
- F1 addressed: Fixed at
oor/incoming_vtxo.go:293. The filter accepts only1..wire.SequenceLockTimeMask(0x0001–0xffff), which excludes the BIP-68 disable bit and the type bit by construction, so an accepted value is the block count and theearliestcomparison ranks like units.TestIncomingPolicyExitDelayUsesCustomBlockCSVcovers the custom branch.
One residual worth confirming rather than a defect: a custom policy whose owner paths carry no sequence in that window now yields "no authenticated relative expiry", which surfaces as a non-retryable outbox error and fails the receive terminally (previously it fell back to cfg.ExitDelay). That is the correct fail-closed direction if arkscript cannot emit a block delay above SequenceLockTimeMask; I cannot tell that from the diff.
- F2 addressed: Fixed in
recoverIndexedVTXOs. Both the conversion and the expiry-authentication failures now recordfirstExpiryErrandcontinue, and the recorded error is returned after the window completes, so a partial scan is never reported as successful.TestRecoveryContinuesAfterForgedTargetpins that one substituted ancestry proof is skipped while the next valid output is still saved. (Minor asymmetry left behind: only the expiry branch warn-logs; a conversion failure is silent until the returned error.) - F3 addressed: Fixed at
vtxo/authenticated_expiry.go:92-99.Tx == nilandBlockHeight <= 0now return plain wrapped errors and stay retryable;invalidBatchExpiryis reserved for tx-hash mismatch, output mismatch, sweep-root mismatch, and overflow.TestAuthenticateBatchExpiryRejectsInvalidEvidence's "incomplete confirmation remains retryable" subtest assertsNotErrorIs(ErrInvalidBatchExpiryEvidence)for both. - F4 addressed: Fixed. The incoming path is now a durable actor whose complete indexer-and-chain lookup is bounded at
incomingExpiryAuthenticationTimeout(2s), and a transient failure wrapsactor.Postpone(30s)so the delivery is released instead of immediately redelivered — the push stream keeps draining. The shared-budget sub-point is moot in practice: multi-parent lineage only arrives on the OOR path, which keeps the 30s authenticator, while incoming pushes are round-direct (one commitment). - F6 addressed: Fixed. The stale "persists without ancestry ... only unilateral exit is degraded" paragraph is replaced with the fail-closed contract, and the matching statements on
IncomingAncestryFetcher,initOORActor, and the package guides were updated to agree. - F7 addressed: Fixed.
incomingAncestryFetchertakes a single non-variadicoor.IncomingExpiryAuthenticatorand rejects nil at construction; the height-repair caller uses the separately namedincomingAncestryOnlyFetcher. Omission at an acceptance call site is now a compile error.
Bot commands
/gateway re-review— re-run after pushing changes (maintainers)/gateway dismiss <id>— silence a finding (maintainers)/gateway explain <id>— elaborate on a finding (anyone)
Index hints alone cannot authenticate a VTXO deadline. Carry the committed sweep key and delay plus finalized OOR ancestry packages so clients can bind the target transaction graph to confirmed batch outputs. The fields are additive. Existing clients ignore them; servers must export complete evidence before clients require it at acceptance.
Reconstruct the committed sweep policy and root output, match each batch against the locally confirmed transaction, and derive the earliest confirmation height plus delay across all contributing commitments. Treat incomplete local confirmation observations as retryable and reject contradictory evidence. Tests cover sweep substitution, confirmation mismatches, duplicate commitments, bounds and the minimum deadline.
Bind the advertised sweep key and delay to every tree before nonce or signature release. Persist the round deadline from the authenticated policy with checked arithmetic when the commitment confirms. Update normal and asset round fixtures to carry valid sweep evidence, so their original validation assertions remain exercised.
A confirmed batch for another VTXO cannot authorize the received target. Reconstruct the signed ancestry graph, bind its exact outpoint, value and script, and execute all inputs against actual parent outputs. Reuse tree and recovery graph validation. Signed regressions reject unrelated batches, forged leaf bodies, mismatched outputs and omitted earlier-expiring parents. PSBT prevout claims do not establish trust.
Validate indexed target membership and authenticate expiry before the durable materialization transaction. Persist the authenticated metadata state so replay preserves the decision, while transient chain failures remain retryable and contradictory evidence fails closed. Retain unconditional package-graph validation from main. Forward the authenticator through the outbox factory and derive custom exit delays only from canonical block-mode policy values. Cover receive and replay boundaries with signed fixtures and durable metadata regressions.
Keep thin incoming events durable until ancestry and expiry authenticate. One two-second budget covers index and chain lookup; timeout postpones delivery and releases the actor turn. Bound other confirmation callers and remove watches even when registration races cancellation. Compare the pushed output with the authenticated target before saving. Reload the canonical row before notification so save-before-ack replay cannot resurrect terminal state. Wire the durable actor and test failed persistence, postponed delivery and terminal-row replay.
Apply target-proof and local expiry authentication to indexed recovery, OOR metadata and custom refresh. Ignore advertised expiry scalars. Recovery skips rejected indexed entries, saves later valid outputs and returns the first error so partial recovery remains explicit. Exercise signed OOR ancestry and a forged target followed by a valid recovery.
Drive incoming materialization with the explicit expiry authenticator. Exercise manager admission, self-change and concurrent receive using both supported database backends.
Document the target-proof, sweep-policy and durable acceptance boundaries in matching package guides. Explain retry behavior and the limited scope for existing persisted VTXOs. Add the missing mailbox ingress guide link inherited from main so the required documentation cross-link check passes on the rebuilt branch.
2fe4c05 to
3c744aa
Compare
|
/gateway re-review Review exact final candidate The previous exact-head review of Verify that each accepted indexed target is bound by its complete signed funding graph to the exact outpoint, value and script, and every contributing batch deadline comes from the actual locally confirmed output and committed sweep policy. Trace IndexedAncestryFromRPC through thin incoming pushes, OOR metadata, indexed recovery, recovered OOR events and custom refresh. Confirm unrelated batch substitution, forged leaf bodies and omitted earlier parents fail before acceptance. Check durable timeout, failed persistence, save-before-ack replay, canonical terminal-row reload, and preservation of main's package-graph guard. Current local final-base checks pass: complete make unit including baselib, vtxo/oor/waved/round race tests, SQLite and PostgreSQL incoming materialization/self-change/concurrency system tests, changed-code lint with ordinary/system tags, protobuf regeneration, formatting, module tidiness, SQL generation, migration version, documentation cross-links, touched-declaration documentation and commit-message lint. CI is pending. Actual-producer direct/chained/multi-parent receive and indexed/offline seed recovery passed on the prior proof head; a repeat against this exact final pair is being coordinated. Current inventory producer emits BTC trees. The new main asset-round fixtures test asset verification independently; they do not establish an asset-inventory producer or authorize an asset-proof bypass. Prior follow-ups are recorded in the PR: shared package/checkpoint count bounds, cheaper optional legacy height maintenance, and continuing independent OOR recovery events after a per-event error. F11's oversized-delay path is rejected before signing by existing validateCSVLock (1..65535, covered across all high bits). F5's activation-depth policy is now base code from #1199. Do not re-raise unchanged or refuted points without new reachable evidence. For any new finding, give its trigger, concrete production trace, change attribution, existing guards/recovery, likelihood, consequence, smallest useful fix/test and regression risk. Classify blocker, follow-up, or not worth changing. Low likelihood does not excuse a reachable funds/security path, but speculative invalid states, pre-existing debt and optional redesign do not block. Prefer the owning boundary and stop once the named invariant and regressions establish correctness. Return BLOCKED, READY WITH FOLLOW-UPS, or READY for this exact code head; keep remaining CI/paired-validation gates explicit. Do not merge or deploy. |
There was a problem hiding this comment.
Gateway review — 4 findings
🔴 0 Blocker · 🟠 0 Major · 🟡 4 Minor · 🔵 0 Nit
Summary
The rebuilt head is coherent: the nine signed commits contain only the expiry/proof work, and the conflict resolution preserved both sides — validateMaterializeIncoming now runs the new authenticated-expiry gate and main's validateIncomingPackageGraph on every materialization attempt.
Re-verified F1–F4, F6, F7 against the replayed code rather than the prior verdict: the custom-policy delay is now clamped to 1..SequenceLockTimeMask, indexed recovery accumulates a first error and continues, incomplete chain observations return plain retryable errors (with the sentinel reserved for contradictory evidence), the incoming actor is durable with a 2 s whole-lookup budget plus watch cleanup, and the acceptance constructor takes a non-variadic authenticator it rejects when nil. F11 is now closed by this PR's own validateRoundSweepPolicy gate. F5 is retracted from this PR — waved/operator_negotiation.go is no longer in the diff.
Nothing new rises to blocker or major. The core invariant holds on every path I traced: IndexedAncestryFromRPC binds the signed graph to the exact outpoint/value/script and every consumer pairs it with AuthenticateBatchExpiry against a locally confirmed output; a real but unrelated batch cannot reach the target because the leaf txid is fixed by the funding chain. The three carried-over minors (F8, F9, F10) are the bounded follow-ups already recorded in the PR body, and one new minor concerns how the sweep-policy check interacts with main's asset trees.
Status of prior findings
- F1 addressed: Fixed at
oor/incoming_vtxo.go:290—incomingPolicyExitDelaynow skips any sequence outside1..wire.SequenceLockTimeMask, so the BIP-68 type and disable bits can never be read as a block count, andTestIncomingPolicyExitDelayUsesCustomBlockCSVcovers the custom vHTLC path that previously had none. - F2 addressed: Fixed at
waved/wallet_recovery.go:351— both the conversion failure and the expiry-authentication failure now recordfirstExpiryErrandcontinue, and the scan returns that error at the end.TestRecoveryContinuesAfterForgedTargetpins that a substituted ancestry proof leaves its target uncredited while the next valid output is still saved. - F3 addressed: Fixed at
vtxo/authenticated_expiry.go:97—confirmation.Tx == nilandBlockHeight <= 0return plain wrapped errors, and the new "incomplete confirmation remains retryable" subtest assertsNotErrorIs(ErrInvalidBatchExpiryEvidence)for both. The sentinel is now only used for tx-hash, output, sweep-root, and overflow mismatches. - F4 addressed: Fixed.
incomingAncestryFetcherWithTimeoutwraps the whole indexer-and-chain lookup atincomingExpiryAuthenticationTimeout(2 s), which dominates the inner 30 s deadline viacontext.WithTimeout, andincomingVTXODurableBehaviorpostpones on transient failure so the push stream is released rather than blocked.unregisterExpiryConfirmationis armed withdeferbefore the registrationAsk, so a watch created after the caller's deadline is still torn down. - F5 withdrawn: Retracting from this PR.
waved/operator_negotiation.gois not in the diff againsta43d0b005f— thevtxo_confirmationssplit landed via #1199 and is now base code. The concern about a client-side floor may still be worth raising, but it belongs on the owning change, not here. - F6 addressed: Fixed at
waved/incoming_ancestry_fetcher.go:44— the doc now states that structural or authentication errors keep the durable event pending and that no VTXO is accepted without expiry evidence, replacing the stale "persists without ancestry ... only unilateral exit is degraded" contract. - F7 addressed: Fixed —
incomingAncestryFetchertakes a single non-variadicoor.IncomingExpiryAuthenticatorand returns an error when it is nil, and the legacy height repair routes through the separately namedincomingAncestryOnlyFetcher. Omitting the authenticator on an acceptance path is now a compile error. - F11 addressed: Closed by this PR's own gate.
validateRoundSweepPolicyruns inCommitmentTxReceivedStateand reconstructs the sweep leaf througharkscript.UnilateralCSVTimeoutTapLeaf, so a delay outside the canonical CSV range fails the round pre-signing viafailBeforeForfeitSigningrather than reaching the confirmation transition.SweepDelayis carried unchanged toInputSigSentState, soint64(BlockHeight) + int64(SweepDelay)cannot reach the newmath.MaxInt32guard on a round the client actually signed — the remediation I asked for (bound the delay where it is authenticated) is exactly what landed.
Bot commands
/gateway re-review— re-run after pushing changes (maintainers)/gateway dismiss <id>— silence a finding (maintainers)/gateway explain <id>— elaborate on a finding (anyone)
Stack status: Rebuilt on
mainata43d0b005fa12ac680327662a9ca796497d86bdcafter #1199 merged. The nine signed, Verified commits contain only the intended expiry/proof work; the obsolete #1199 prefix and #1262 duplicate are removed. Current head:3c744aa6c6ea9152450889a7bca99417fc963ae5. Local final-base checks pass. Exact-head Gateway review found no blocker or major. All 17 CI jobs pass after retrying the two runner-loss failures. The coordinated final producer pass remains pending.The problem
A received virtual transaction output (VTXO) needs an expiry tied to the batches that actually fund it. An indexer-provided expiry height is only a hint.
Authenticating a supplied batch is insufficient. Suppose target A expires at height 150. The indexer supplies a real, confirmed batch for unrelated output B that expires at height 300. B can even have the same value and receive script as A. Accepting B's expiry for A would delay A's refresh or unilateral exit past its real deadline.
The fix
Before accepting an indexed output, the client validates its complete signed transaction path to the exact target outpoint, value, and script. It reuses tree validation and the recovery proof graph, then executes each spend against its actual parent output. This rejects both a valid unrelated batch and a fabricated leaf whose signature does not authorize its contents.
Out-of-round (OOR) inventory now includes finalized ancestry packages. These connect the round-tree leaves through checkpoint and Ark transactions to the target. Every supplied proof node must contribute to that target, and every input must have a parent in the proof or an authenticated batch output.
The client then reconstructs each committed sweep policy, matches its batch output against a locally confirmed transaction, and derives the earliest confirmation height plus sweep delay across all parents. Advertised expiry heights are discarded. Round signing also verifies the committed sweep policy.
Incoming events, OOR receive, indexed recovery, and custom refresh use these checks before accepting the expiry. Chain and index outages remain retryable. The incoming event actor bounds its complete evidence lookup at two seconds and uses durable redelivery. Recovery continues past rejected entries and returns the first error, so it does not report an incomplete scan as successful.
Safety rule
A new target receives an expiry only after its signed funding path and every contributing batch's sweep deadline are authenticated. A later-expiring batch for another output cannot authorize it.
Existing live VTXOs retain their spend and exit behavior. Optional legacy commitment-height repair also passes through target-proof validation; if the indexer lacks that evidence, maintenance retains the configured safe unroll lookback floor. This change adds no continuous canonicality tracker or legacy-record repair subsystem.
Tests
Compatibility and rollout
Deploy a server that exports the committed sweep key/delay and complete OOR ancestry packages before deploying this client. The protobuf fields are additive, so old clients can continue using the upgraded server. New clients fail closed when required evidence is absent; deploying them first can delay receive, recovery, or custom refresh until the server is upgraded.
Review status and bounded follow-ups
Gateway reviewed final head
3c744aa6c6ea9152450889a7bca99417fc963ae5after the dependency rebuild and found zero blocker or major findings. Its four minor findings are tracked below. All 17 CI jobs pass, including both complete system-test suites, race, lint, static checks, and all cross-builds. Two jobs lost their self-hosted runners on the first attempt and passed on retry. Final paired verification remains pending.The reported oversized sweep-delay confirmation path is rejected before signing by the existing canonical CSV range check. Activation-depth policy remains owned by #1199.