MF3-L03: docs: document app session close atomicity blocking on in-flight escrow#831
MF3-L03: docs: document app session close atomicity blocking on in-flight escrow#831nksazonov wants to merge 3 commits into
Conversation
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
nksazonov
changed the title
ihsraham
left a comment
ihsraham
left a comment
There was a problem hiding this comment.
This is the right shape for L-03: documenting the cooperative-close liveness tradeoff is an acceptable remediation path, and the main atomic-close behavior matches the current transaction flow.
I would revise a few details before closure, though. Since this PR is the remediation, the docs need to match the release/escrow code path closely, and the public security doc should not point at a file that is missing from the packaged MCP content.
ihsraham
left a comment
ihsraham
left a comment
There was a problem hiding this comment.
Approving for L-03 closure. The docs now make the cooperative-close liveness tradeoff explicit: app-session close is all-participant atomic, a participant rejected by the escrow gate can block everyone, and the recovery paths are described. The previous contracts/SECURITY.md wording and packaged MCP link concerns look addressed.
I left one non-blocking precision note on the public summary. It does not reopen L-03 for me, but it would keep the packaged docs closer to EnsureNoOngoingEscrowOperation.
| - Support for non-EVM blockchains | ||
| - Formal verification of protocol rules | ||
| - Session key off-chain scope enforcement does not apply to direct receive-state acknowledgement. Session key expiration and asset-scope restrictions are enforced by the Nitronode off-chain only; the `SessionKeyValidator` contract validates cryptographic signatures alone. A party holding a session key — even one that has expired, been revoked, or been retired — can bypass the `acknowledge` endpoint, manually sign a pending node-issued receive state, and submit it directly to the contract. This is accepted: receive states exclusively increase the user's allocation and cannot redirect funds away from the user, so out-of-scope acknowledgement carries no financial risk and preserves a recovery path when the node is unavailable. | ||
| - App session cooperative closure is atomic across all participants. The Node refuses to issue a release receive-state to any participant whose latest signed state encodes an escrow operation that the off-chain gate does not yet treat as safely settled — covering any pending `escrow_lock`/`mutual_lock`, plus `escrow_deposit`/`escrow_withdraw` whose on-chain escrow-channel version has not caught up. Stacking a co-signed release on an unfinalized escrow risks state-chain invariant violations if the escrow ultimately reverts or settles to an unexpected version. As a consequence, a single participant with a pending escrow blocks cooperative close for all others in the session until their escrow resolves. Affected participants may wait for the obstruction to clear, or — where the session state machine permits intermediate updates — unwind their share individually via off-chain transfers out of the session and re-close without the blocked participant. This is an accepted trade-off favouring protocol safety over close-time liveness: every release the Node co-signs must remain enforceable on-chain, and an unfinalized escrow cannot offer that guarantee. |
There was a problem hiding this comment.
Non-blocking, but worth tightening: the full rule in contracts/SECURITY.md includes the one-version-behind escrow_deposit allowance for Open or Closed escrow channels, while this shorter summary still reads like any not-caught-up escrow_deposit blocks.
Could we either mirror that allowance here too, or phrase this as “escrow deposit states the gate still treats as unsafe”? That keeps the packaged/public docs aligned with EnsureNoOngoingEscrowOperation.
3 participants
Documents the audit finding (MF3-L03) that app session cooperative close is atomic across all participants and aborts if any participant has an in-flight escrow operation (escrow lock, mutual lock, escrow deposit/withdrawal awaiting finalization).
contracts/SECURITY.md— new Behavior rule 8 with full mechanism, safety rationale, recovery paths, and invariant.protocol-description.md— short note in the "Off-chain application sessions" section, linking to SECURITY.md rule 8.docs/protocol/security-and-limitations.md— bullet in "Known Limitations" matching the existing voice.No code changes.