MF-L02: docs(protocol): qualify enforcement guarantee for intent-specific execution paths

[nksazonov]

Qualifies the enforcement guarantee across three protocol docs.

The blanket statement "Any party MAY submit the latest signed state at any time" is not fully accurate: an OPERATE state with non-zero user net flow delta cannot be used to create or checkpoint a channel from VOID status, because OPERATE requires zero user net flow change relative to the last enforced state.

Changes:

• docs/protocol/security-and-limitations.md: rewrite Enforcement Guarantees section — adds intent-path qualifier and a new bullet requiring parties to retain intermediate states (e.g. DEPOSIT) before discarding them
• docs/protocol/enforcement.md: qualify the Enforcement Model bullet; add caveat in Channel Creation section about OPERATE intent not being usable when user net flow was accumulated from an unconfirmed DEPOSIT state
• docs/protocol/overview.md: qualify the State Enforcement paragraph

Summary by CodeRabbit

Documentation

• Updated protocol enforcement submission rules, including requirements for valid execution paths when submitting states
• Clarified channel creation restrictions and requirements for state operations
• Enhanced enforcement guarantees documentation with improved clarity on state management and enforcement behavior

[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: 294589cd-1a5f-47c3-8df9-8936c17c8000

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

📝 Walkthrough

Walkthrough

This PR refines protocol enforcement documentation across three specification files, clarifying that state submission requires valid execution path validation, restricting OPERATE-intent states from depending on unconfirmed prior DEPOSITs, and requiring parties to enforce intermediate states before discarding them.

Changes

Enforcement Rule Clarifications

Layer / File(s)	Summary
High-level Enforcement Rule Update docs/protocol/overview.md	State Enforcement rule updated to require latest mutually signed state with additional blockchain-layer validation of valid execution path for the submitted state's intent within current channel context.
Enforcement Guarantees and Dependencies docs/protocol/security-and-limitations.md	Enforcement Guarantees clarified to specify that success depends on finding valid execution path in current channel context, and parties must retain and enforce intermediate states (e.g., DEPOSIT) before discarding them to prevent subsequent OPERATE states from being used for on-chain creation.
Detailed Submission and Creation Constraints docs/protocol/enforcement.md	Enforcement submission rule refined to require valid execution path for state's intent; OPERATE-intent channel creation constrained to states with zero user net flow delta relative to empty prior on-chain state and prohibited from using states depending on unconfirmed prior DEPOSIT enforcement.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• layer-3/nitrolite#619: Introduced the enforcement model that this PR refines by adding valid execution path requirements and OPERATE-on-unconfirmed-DEPOSIT prevention constraints.

Suggested reviewers

• ihsraham
• philanton
• dimast-x

Poem

🐰 Enforcement paths now gleam so clear,
No OPERATE on DEPOSIT unclear,
Intermediate states must stay,
Till confirmation lights the way!
Rules refined with precision bright, 🌟

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and specifically summarizes the main change: qualifying enforcement guarantees in protocol documentation to account for intent-specific execution path requirements.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/sc-l02

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

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

[coderabbitai]

🧹 Nitpick comments (1)

docs/protocol/enforcement.md (1)

72-72: ⚖️ Poor tradeoff

Align scope with security-and-limitations.md and clarify "unconfirmed."

Line 72 states the OPERATE-on-unconfirmed-DEPOSIT restriction applies only to channel creation: "cannot be used to create a channel." However, security-and-limitations.md line 45 states this restriction applies to both creation and advancement: "cannot be used to create or advance a channel on-chain."

The broader scope is technically correct because OPERATE requires zero user net flow delta relative to the last enforced state—this constraint applies to all enforcement operations, not just creation. The same sentence's later phrase "before advancing to subsequent OPERATE states" also implies the restriction extends beyond creation.

Additionally, "unconfirmed" could be clearer. Consider "unenforced," "not yet checkpointed," or "off-chain-only" to explicitly indicate the DEPOSIT has not been submitted on-chain.

Suggested alignment

-An OPERATE state that carries accumulated user net flow from an unconfirmed prior DEPOSIT state cannot be used to create a channel — parties MUST enforce the DEPOSIT state on-chain before advancing to subsequent OPERATE states that depend on it.
+An OPERATE state that carries accumulated user net flow from an unenforced prior DEPOSIT state cannot be used to create or checkpoint a channel — parties MUST enforce the DEPOSIT state on-chain before advancing to subsequent OPERATE states that depend on it.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/protocol/enforcement.md` at line 72, The sentence beginning "An OPERATE
state that carries accumulated user net flow from an unconfirmed prior DEPOSIT
state cannot be used to create a channel" should be broadened and clarified:
change the scope to "create or advance a channel on-chain" (so it applies to
both creation and advancement) and replace "unconfirmed" with a clearer term
such as "unenforced (not yet submitted on-chain)" or "off-chain-only" to
indicate the DEPOSIT was not enforced on-chain; update the sentence fragment "An
OPERATE state that carries accumulated user net flow..." and the phrase "cannot
be used to create a channel" accordingly so the text reads that OPERATE states
depending on an unenforced prior DEPOSIT cannot be used to create or advance a
channel on-chain.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@docs/protocol/enforcement.md`:
- Line 72: The sentence beginning "An OPERATE state that carries accumulated
user net flow from an unconfirmed prior DEPOSIT state cannot be used to create a
channel" should be broadened and clarified: change the scope to "create or
advance a channel on-chain" (so it applies to both creation and advancement) and
replace "unconfirmed" with a clearer term such as "unenforced (not yet submitted
on-chain)" or "off-chain-only" to indicate the DEPOSIT was not enforced
on-chain; update the sentence fragment "An OPERATE state that carries
accumulated user net flow..." and the phrase "cannot be used to create a
channel" accordingly so the text reads that OPERATE states depending on an
unenforced prior DEPOSIT cannot be used to create or advance a channel on-chain.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3c015f5f-b779-4b51-b1c3-ee1ed2b384f9

📥 Commits

Reviewing files that changed from the base of the PR and between 14fd16d and b4d52d2.

📒 Files selected for processing (3)

• docs/protocol/enforcement.md
• docs/protocol/overview.md
• docs/protocol/security-and-limitations.md

[ihsraham]

approved, this now closes L-02 with the enforcement-path caveat documented in the right places.