MF2-H03: guard challenge_rescue against post-Finalize close

[philanton]

Summary

• HandleHomeChannelClosed previously issued a challenge rescue for every channel that was Challenged before the on-chain close, including cooperative closes backed by a node-signed Finalize. In that path the rescue either silently overwrote a post-Finalize receiver credit at (epoch+1, version=0) or collided on deterministic GetStateID with an existing (epoch+1, version=1) credit — rolling back the close-event handler and leaving the channel stuck Challenged, which in turn blocked request_creation for the same (wallet, asset) pair.
• Guard the rescue branch with HasSignedFinalize. Mirrors the existing post-Finalize check in HandleHomeChannelCheckpointed.
• Align NewChallengeRescueState with the NextState() post-final convention: fresh-epoch state starts at version 0, not 1. The guard guarantees no other (epoch+1, version=0) row exists when the rescue actually runs.

Failure modes prevented

Post-Finalize receiver credits are produced by NextState() in a fresh epoch with HomeChannelID=nil. Without the guard:

1. GetLastStateByChannelID only matches channel-attached rows → returns the Finalize state at the original epoch, missing the post-Finalize credits.
2. SumNetTransitionAmountAfterVersion filters by home_channel_id → returns zero.
3. NewChallengeRescueState builds a zero-amount rescue at (Finalize.Epoch+1, version=1).
4. StoreUserState either overwrites the lone credit at (epoch+1, version=0) (silent balance loss) or collides with (epoch+1, version=1) and rolls back the entire close handler.

Test plan

• go test ./pkg/core/... — TestNewChallengeRescueState updated for version 0.
• go test ./nitronode/event_handlers/... -run TestHandleHomeChannelClosed — all rescue tests pass.
• New TestHandleHomeChannelClosed_PostFinalize_SkipsRescue verifies the rescue branch fully short-circuits when HasSignedFinalize is true.
• New TestHandleHomeChannelClosed_PostFinalize_CollisionRegression documents the two failure modes the guard prevents.
• New TestHandleHomeChannelClosed_PostFinalize_HasSignedFinalizeErr confirms error propagation from the HasSignedFinalize lookup.
• Existing rescue tests (_Squash, _NoCredits, _NegativeNet_ClampsToZero) updated for the new version=0 invariant and the added HasSignedFinalize mock.
• go vet ./nitronode/event_handlers/... ./pkg/core/... clean.

Follow-ups (separate tickets)

• Post-Finalize unsigned receiver credits at (epoch+1, version=0..N) with HomeChannelID=nil remain unsigned forever (channel_v1/handler.go:130 skips node-sig when channel status is non-Open). Confirm request_creation folds them into the next signed ledger correctly; otherwise file a separate fix.
• Operator reconciliation for production channels already wedged at Challenged due to this bug pre-fix: needs a detection query (Challenged channels where HasSignedFinalize=true) and a one-shot flip to Closed.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1a5eaec2-558d-4593-9c71-e28cf7c715fb

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/nitronode-mf2-h03

---

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 and usage tips.}

[nksazonov]

Excellent work. The guard at service.go:375 correctly and completely remediates all three failure modes described in the audit finding — the balance-overwrite path, the StoreUserState ID-collision path, and the resulting Challenged-channel deadlock. The version-0 correction in NewChallengeRescueState aligns the rescue with the NextState() convention. All three new regression tests are well-scoped and the existing tests are correctly updated. The two comments below are informational — neither blocks merging.

[ihsraham]

Approving for H-03. Nice fix: the signed-Finalize guard closes the destructive rescue path, while the normal challenge-rescue flow stays covered. Thanks for the focused tests and follow-up cleanup.