Skip to content

vtxo: authenticate expiry against batch evidence - #1244

Merged
bhandras merged 9 commits into
mainfrom
codex/p1-vtxo-expiry-auth
Sep 15, 2026
Merged

bhandras merged 9 commits into
mainfrom
codex/p1-vtxo-expiry-auth

Conversation

@bhandras

@bhandras bhandras commented Sep 3, 2026 •

Copy link
Copy Markdown
Member

Stack status: Rebuilt on main at a43d0b005fa12ac680327662a9ca796497d86bdc after #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

  • Valid signed target; unrelated confirmed ancestry; mismatched outpoint, output index, value, or script; forged signed leaf contents.
  • Multi-parent earliest expiry; omitted earlier-expiring parent; distinct leaf paths within one commitment.
  • Transient index and chain failures, bounded confirmation waits, and watch cleanup after cancellation.
  • Failed persistence, durable redelivery, save-before-ack replay, and reload of a terminal row without resurrecting it.
  • Recovery rejects one forged target while saving a later valid output.
  • Incoming materialization, self-change, and concurrent receive with SQLite and PostgreSQL.
  • Real-chain directed receive and chained/multi-input OOR receive using the actual producer's signed evidence.

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 3c744aa6c6ea9152450889a7bca99417fc963ae5 after 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.

  • Add shared package/checkpoint count limits at indexed ingress after confirming the producer contract. Transport already bounds message bytes; this follow-up concerns parsing cost.
  • Separate structural-only legacy height maintenance from full target-proof validation while keeping every new-acceptance path strict.
  • Continue independent recovered OOR events after a per-event failure, retaining an explicit partial-recovery error and atomic materialization within each event.
  • Before enabling asset rounds, authenticate sweep-leaf inclusion in the combined asset signing root. The builder includes the leaf, but the existing client asset-context validation does not prove that relationship. The current operator has no asset-tree producer, and indexed acceptance rejects combined roots without the required proof context. This PR adds no asset bypass.

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.

@bhandras

bhandras commented Sep 3, 2026

Copy link
Copy Markdown
Member Author

/gateway review

@lightninglabs-gateway

lightninglabs-gateway Bot commented Sep 3, 2026 •

Copy link
Copy Markdown

❌ 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.

@bhandras

bhandras commented Sep 3, 2026

Copy link
Copy Markdown
Member Author

/gateway review

@lightninglabs-gateway lightninglabs-gateway Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Comment thread batchcanon/rpc_evidence.go Resolved
Comment thread vtxo/actor.go Resolved
Comment thread vtxo/actor.go Resolved
Comment thread vtxo/actor.go Resolved
Comment thread vtxo/actor.go Resolved
Comment thread oor/incoming_vtxo.go Resolved
@lightninglabs-gateway

lightninglabs-gateway Bot commented Sep 3, 2026 •

Copy link
Copy Markdown

🤖 gateway audit metadata for this PR — auto-generated, please don't edit.

@litbot-9000

litbot-9000 commented Sep 3, 2026 •

Copy link
Copy Markdown
Collaborator

This PR's authenticated-expiry work left the per-package docs for arkrpc, batchcanon, oor, unroll, vtxo, and waved stale; the diff below reconciles each CLAUDE.md (and its byte-identical AGENTS.md) against the current code.

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 retry

How to apply: save the block above to a file and run git apply <file> from the repo root, or run the nightly gardener locally with /doc-gardening arkrpc batchcanon oor unroll vtxo waved.

Run: https://github.com/lightninglabs/wavelength/actions/workflows/doc-gardening-pr.yml

@bhandras

bhandras commented Sep 3, 2026

Copy link
Copy Markdown
Member Author

/gateway re-review

@lightninglabs-gateway

lightninglabs-gateway Bot commented Sep 3, 2026 •

Copy link
Copy Markdown

❌ 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.

@bhandras

bhandras commented Sep 3, 2026

Copy link
Copy Markdown
Member Author

/gateway dismiss F1

@bhandras

bhandras commented Sep 3, 2026

Copy link
Copy Markdown
Member Author

/gateway dismiss F2

@bhandras

bhandras commented Sep 3, 2026

Copy link
Copy Markdown
Member Author

/gateway dismiss F3

@bhandras

bhandras commented Sep 3, 2026

Copy link
Copy Markdown
Member Author

/gateway dismiss F4

@bhandras

bhandras commented Sep 3, 2026

Copy link
Copy Markdown
Member Author

/gateway dismiss F5

@bhandras

bhandras commented Sep 3, 2026

Copy link
Copy Markdown
Member Author

/gateway dismiss F6

@lightninglabs-gateway

Copy link
Copy Markdown

🚫 Dismissed F1 (major) by @bhandras — no reason given

Open findings on this PR: 🟠 F2 (major) · 🟡 F4 (minor) · 🟡 F5 (minor) · 🟡 F6 (minor)

@lightninglabs-gateway

Copy link
Copy Markdown

🚫 Dismissed F3 (major) by @bhandras — no reason given

Open findings on this PR: 🟠 F2 (major) · 🟡 F5 (minor) · 🟡 F6 (minor)

@lightninglabs-gateway

Copy link
Copy Markdown

🚫 Dismissed F4 (minor) by @bhandras — no reason given

Open findings on this PR: 🟡 F5 (minor) · 🟡 F6 (minor)

@lightninglabs-gateway

Copy link
Copy Markdown

🚫 Dismissed F2 (major) by @bhandras — no reason given

Open findings on this PR: 🟡 F5 (minor) · 🟡 F6 (minor)

@lightninglabs-gateway

Copy link
Copy Markdown

🚫 Dismissed F5 (minor) by @bhandras — no reason given

Open findings on this PR: 🟡 F6 (minor)

@lightninglabs-gateway

Copy link
Copy Markdown

🚫 Dismissed F6 (minor) by @bhandras — no reason given

All findings on this PR are addressed or dismissed.

@bhandras
bhandras force-pushed the codex/p1-vtxo-expiry-auth branch from ce46774 to da9a851 Compare September 3, 2026 17:51
@bhandras

bhandras commented Sep 3, 2026

Copy link
Copy Markdown
Member Author

/gateway re-review

@lightninglabs-gateway

lightninglabs-gateway Bot commented Sep 3, 2026 •

Copy link
Copy Markdown

❌ 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.

@bhandras
bhandras dismissed lightninglabs-gateway[bot]’s stale review September 3, 2026 17:57

All Gateway findings were fixed or dismissed after individual evidence replies. Final-head re-review was requested but funding-blocked.

@bhandras

bhandras commented Sep 3, 2026

Copy link
Copy Markdown
Member Author

/gateway review

@lightninglabs-gateway

Copy link
Copy Markdown

gateway is already active on this PR. Reply with /gateway re-review to refresh against current HEAD.

@bhandras

bhandras commented Sep 3, 2026

Copy link
Copy Markdown
Member Author

/gateway re-review

@lightninglabs-gateway

lightninglabs-gateway Bot commented Sep 3, 2026 •

Copy link
Copy Markdown

❌ 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.

@bhandras bhandras added the eng-brain:wavelength-core-fixes Engineering Brain commitment: wavelength-core-fixes label Sep 4, 2026
@bhandras

bhandras commented Sep 4, 2026

Copy link
Copy Markdown
Member Author

/gateway review

@bhandras
bhandras force-pushed the codex/p1-vtxo-expiry-auth branch from 26ea41f to d907b43 Compare September 4, 2026 22:58

@lightninglabs-gateway lightninglabs-gateway Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Comment thread oor/incoming_vtxo.go Resolved
Comment thread waved/wallet_recovery.go Resolved
Comment thread vtxo/authenticated_expiry.go Resolved
Comment thread vtxo/incoming_handler.go Resolved
Comment thread waved/operator_negotiation.go Resolved
Comment thread waved/incoming_ancestry_fetcher.go Resolved
Comment thread waved/incoming_ancestry_fetcher.go Resolved
@bhandras

bhandras commented Sep 4, 2026

Copy link
Copy Markdown
Member Author

/gateway re-review

Re-review current head aa530861fda879501d1aa0283939a7ca9cfca19c. Re-check F1-F4, F6, and F7 against their individual replies and focused signed commits. F5 is owned by logically stacked bounded-reorg PR #1199 and must not expand this expiry branch. Require a concrete production path, change attribution, existing recovery, and material downside for any blocker. Stop when the expiry-authentication invariants are proven. Return BLOCKED, READY WITH FOLLOW-UPS, or READY.

@lightninglabs-gateway

lightninglabs-gateway Bot commented Sep 4, 2026 •

Copy link
Copy Markdown

❌ 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.

@bhandras
bhandras force-pushed the codex/p1-vtxo-expiry-auth branch 3 times, most recently from cacfb28 to 2fe4c05 Compare September 8, 2026 15:28
@bhandras

bhandras commented Sep 8, 2026

Copy link
Copy Markdown
Member Author

/gateway re-review

Review exact head 2fe4c056822f073699d971a02f4cf5aa3e723380. This is a provisional code review: final rebase and dependency cleanup remain gated on #1199 merging, and the current main conflict prevents CI. Do not report the branch merge-ready until those gates finish. The intended expiry change is 89e6aa5d96a34f26b7262dfd57ca9b0bfffd6da3..2fe4c056822f073699d971a02f4cf5aa3e723380; the preceding activation-depth commits belong to #1199 and the #1262 duplicate will be removed in the final rebuild.

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.

@lightninglabs-gateway lightninglabs-gateway Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 only 1..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 the earliest comparison ranks like units. TestIncomingPolicyExitDelayUsesCustomBlockCSV covers 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 record firstExpiryErr and continue, and the recorded error is returned after the window completes, so a partial scan is never reported as successful. TestRecoveryContinuesAfterForgedTarget pins 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 == nil and BlockHeight <= 0 now return plain wrapped errors and stay retryable; invalidBatchExpiry is reserved for tx-hash mismatch, output mismatch, sweep-root mismatch, and overflow. TestAuthenticateBatchExpiryRejectsInvalidEvidence's "incomplete confirmation remains retryable" subtest asserts NotErrorIs(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 wraps actor.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. incomingAncestryFetcher takes a single non-variadic oor.IncomingExpiryAuthenticator and rejects nil at construction; the height-repair caller uses the separately named incomingAncestryOnlyFetcher. 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)

Comment thread vtxo/indexed_ancestry.go Resolved
Comment thread waved/incoming_ancestry_fetcher.go Resolved
Comment thread waved/wallet_recovery.go Resolved
Comment thread round/transitions.go Resolved
Comment thread waved/operator_negotiation.go Resolved
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.
@bhandras
bhandras force-pushed the codex/p1-vtxo-expiry-auth branch from 2fe4c05 to 3c744aa Compare September 8, 2026 17:37
@bhandras

bhandras commented Sep 8, 2026

Copy link
Copy Markdown
Member Author

/gateway re-review

Review exact final candidate 3c744aa6c6ea9152450889a7bca99417fc963ae5 on base a43d0b005fa12ac680327662a9ca796497d86bdc. #1199 has merged. The obsolete dependency prefix and #1262 duplicate are removed; all nine remaining commits are signed and GitHub Verified. The branch is now MERGEABLE and required CI has started.

The previous exact-head review of 2fe4c056822f073699d971a02f4cf5aa3e723380 returned READY WITH FOLLOW-UPS. Independently verify the final integration; do not assume that verdict proves the rebuilt head. The allowed expiry/proof suffix was replayed onto fresh main and folded into coherent commits. One conflict combined the new positive authenticated-expiry gate with main's unconditional OOR package-graph validation before materialization. The only additional changes are main's new asset-round test fixtures using a real sweep leaf and SweepKey so their asset-verification assertions remain reached, and one missing main documentation index link. The final tree was compared with the resolved replay before and after regrouping.

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.

@lightninglabs-gateway lightninglabs-gateway Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 — incomingPolicyExitDelay now skips any sequence outside 1..wire.SequenceLockTimeMask, so the BIP-68 type and disable bits can never be read as a block count, and TestIncomingPolicyExitDelayUsesCustomBlockCSV covers 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 record firstExpiryErr and continue, and the scan returns that error at the end. TestRecoveryContinuesAfterForgedTarget pins 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 == nil and BlockHeight <= 0 return plain wrapped errors, and the new "incomplete confirmation remains retryable" subtest asserts NotErrorIs(ErrInvalidBatchExpiryEvidence) for both. The sentinel is now only used for tx-hash, output, sweep-root, and overflow mismatches.
  • F4 addressed: Fixed. incomingAncestryFetcherWithTimeout wraps the whole indexer-and-chain lookup at incomingExpiryAuthenticationTimeout (2 s), which dominates the inner 30 s deadline via context.WithTimeout, and incomingVTXODurableBehavior postpones on transient failure so the push stream is released rather than blocked. unregisterExpiryConfirmation is armed with defer before the registration Ask, so a watch created after the caller's deadline is still torn down.
  • F5 withdrawn: Retracting from this PR. waved/operator_negotiation.go is not in the diff against a43d0b005f — the vtxo_confirmations split 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 — incomingAncestryFetcher takes a single non-variadic oor.IncomingExpiryAuthenticator and returns an error when it is nil, and the legacy height repair routes through the separately named incomingAncestryOnlyFetcher. Omitting the authenticator on an acceptance path is now a compile error.
  • F11 addressed: Closed by this PR's own gate. validateRoundSweepPolicy runs in CommitmentTxReceivedState and reconstructs the sweep leaf through arkscript.UnilateralCSVTimeoutTapLeaf, so a delay outside the canonical CSV range fails the round pre-signing via failBeforeForfeitSigning rather than reaching the confirmation transition. SweepDelay is carried unchanged to InputSigSentState, so int64(BlockHeight) + int64(SweepDelay) cannot reach the new math.MaxInt32 guard 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)

Comment thread round/sweep_policy.go Resolved
Comment thread vtxo/indexed_ancestry.go Resolved
Comment thread waved/incoming_ancestry_fetcher.go Resolved
Comment thread waved/wallet_recovery.go Resolved
@bhandras
bhandras merged commit 5a564bf into main Sep 15, 2026
58 of 60 checks passed
@bhandras
bhandras deleted the codex/p1-vtxo-expiry-auth branch September 15, 2026 13:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

eng-brain:wavelength-core-fixes Engineering Brain commitment: wavelength-core-fixes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants