vtxo: widen onchain spend tracking to onchain-kind vtxos

[bitcoin-coder-bob]

Closes #1181. Part of #1159, Milestone 5. Follow-up to #1174 on top of #1161.

Important

Stacked. Based on feat/unrolled-vtxo-onchain-spend (#1174) with bob/onchain-arkade-vtxo-kind (#1161) merged in, so the diff shows #1161's commits through the merge until both land on master. The change itself is the last commit. Once #1161 and #1174 merge, this rebases onto master and the merge commit goes away.

Context

#1174 tracks the onchain spends of unrolled vtxos, the only vtxos with an onchain output until now. Its candidate selectors, its apply path and its restore-on-restart loop are all scoped to unrolled = true, and Vtxo.IsOnchainSpent derives "spent onchain" from unrolled plus the absence of an in-Ark spend marker.

With #1161 arkd also records vtxos held in on-chain Arkade UTXOs, Kind = Onchain. Their unilateral spends bypass arkd exactly as an unrolled vtxo's do, and need the same detection, retraction and guards.

What changed

Every predicate the tracking keyed on unrolled now takes either shape.

• Domain. Vtxo.HasOnchainOutput is the one Go predicate, unrolled or onchain kind, and IsOnchainSpent builds on it.
• SQL, both dialects. The five onchain-spend statements, mark, re-point, retract and the two candidate selectors, match (unrolled = true OR vtxo_kind = 1). The literal is the value the add_vtxo_kind migration defines, and a comment above the first statement says so.
• Badger. The two selectors take both shapes, and the mark guard uses the predicate.
• Application. applyOnchainSpends filters on the predicate, and the restore loop in restoreWatchingVtxos follows through the widened selectors.

SelectSweepableUnrolledVtxos stays as it is: an onchain-kind UTXO has no checkpoint tx for the sweeper to resolve, and its ark_txid predicate already keeps onchain spends out.

Nothing here writes Kind = Onchain rows. That is M3.

Tests

On sqlite, postgres and badger, with onchain-kind rows inserted directly so nothing waits for the write path:

• mark, re-point and retract work on an onchain-kind row, and leave it onchain kind and never unrolled;
• the selectors partition by kind as they do by unrolled, and an offchain row that was never unrolled appears in neither;
• an onchain-kind row spent onchain never enters the sweepable set.

The IsOnchainSpent table and the applyOnchainSpends unit test gain the kind cases. Removing the kind from the predicate fails both; the sql cases cannot pass on the old statements, which never matched a row that was not unrolled. go build, go vet and make lint clean.

Decided on the issue

#1159 question 9 is decided (decision): cosigned outputs the client reveals are registered at cosign time as a pending on-chain kind and promoted to onchain kind at confirmation. A pending output has nothing on chain for a unilateral spend to take and its CSV cannot mature before confirmation, so HasOnchainOutput stays on the confirmed kind and a pending row never enters the predicates here. Adding the pending enum value later is a migration-free change that does not touch this diff.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[arkana-ai-bot]

Arkana review — widen onchain spend tracking to onchain-kind vtxos ⚠️ PROTOCOL-CRITICAL — human review required

This PR extends the onchain spend tracking and domain logic to cover VtxoKindOnchain vtxos (part of issue #1159), building on the VtxoKind discriminator introduced in #1161.

Domain changes are correct:

• HasOnchainOutput() correctly captures both unrolled vtxos and onchain-kind vtxos. Using this helper consistently in place of raw Unrolled checks keeps the two categories in sync.
• IsNote(): adding the Kind != VtxoKindOnchain guard is necessary — an on-chain Arkade UTXO has no commitment txids, which would otherwise make it read as a note.
• IsExpired(): guarding on-chain kind is critical — a zero ExpiresAt (no batch expiry) would read as permanently expired, making the vtxo appear unspendable everywhere.
• RequiresForfeit(): on-chain kind vtxos join a batch as boarding inputs and are signed directly, never forfeited. The guard is correct.
• IsOnchainSpent(): updated to use HasOnchainOutput() — correct.

Application layer:

• applyOnchainSpends switches to HasOnchainOutput() — correct.
• restoreWatchingVtxos log message and comment updated — no logic change.

Test coverage is thorough: each modified method has a new test case for VtxoKindOnchain.

This is stacked on #1161 (VtxoKind discriminator). Flagging for human review as it touches VTXO domain logic and sweep/spend tracking. Looks correct. ✓