M-L05: docs(contracts): document native token deposits

[philanton]

Description

_pullFunds() enforces different funding mechanics for native assets vs ERC20. When token == address(0), it requires msg.value == amount, so the caller must supply native funds even if the logical funding party is def.user. By contrast, the ERC20 path uses IERC20.safeTransferFrom() with the from address’ allowance.
In result, state submissions that require funds movement cannot be enforced by anyone, unless they are willing to pay for it. This asymmetry is not obvious from createChannel() / depositToChannel() and can surprise integrators who assume identical funding mechanics across asset types.

Summary by CodeRabbit

• Documentation
  • Added comprehensive documentation clarifying deposit mechanics for native ETH versus ERC20 tokens, detailing submission requirements and transaction caller responsibilities across deposit flows.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds documentation and inline NOTE comments explaining that ERC20 deposits are pulled via transferFrom (requiring prior allowance and allowing permissionless submission), whereas native ETH deposits require the transaction caller to supply msg.value == amount.

Changes

Cohort / File(s)	Summary
Security doc contracts/SECURITY.md	New section "Native ETH vs ERC20 Deposit Asymmetry" describing how _pullFunds(from, token, amount) differs for address(0) (native ETH) vs ERC20, listing affected flows and integrator guidance.
Protocol docs protocol-description.md	Added protocol-level explanation of deposit mechanics for ERC20 vs native ETH, including bridging/escrow call sites and submission/value requirements.
Contract comments contracts/src/ChannelHub.sol	Inserted NOTE comments in createChannel, depositToChannel, and initiateEscrowDeposit documenting that native ETH DEPOSIT intents require the caller to attach msg.value == amount; no executable logic changed.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• H-L06: fix(contracts/ChannelHub): remove payable from methods, clarify in create #666: Touches ChannelHub deposit/msg.value handling; closely related to the documented asymmetry.
• H-M02: fix(contracts/ChannelHub): allow unblocking escrow ops after migration #637: Modifies initiateEscrowDeposit/escrow routing logic referenced by the new docs.

Suggested reviewers

• ihsraham
• dimast-x

Poem

🐇 I hopped through code and left a note,
Of ERC20 pulls and ETH that must float,
One needs allowance, one needs the fee,
Now integrators know how deposits be,
Cheers from a rabbit, light on its tote!

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'M-L05: docs(contracts): document native token deposits' accurately summarizes the main change—adding documentation about native ETH deposit asymmetry mechanics across multiple files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ 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/contract-l-05

---

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)

contracts/SECURITY.md (1)

380-387: Optional wording tweak: prefer “native token” over “ETH” for multi-chain precision.

Since this applies on non-Ethereum chains too, consider phrasing as “native token (ETH on Ethereum)” to avoid chain-specific ambiguity in integrator docs.

Also applies to: 400-403

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@contracts/SECURITY.md` around lines 380 - 387, Update the section titled
"Native ETH vs ERC20 Deposit Asymmetry" to use chain-neutral wording: replace
occurrences of "ETH" with "native token" and where helpful add parenthetical
clarification like "(ETH on Ethereum)" so the text reads e.g. "Native token (ETH
on Ethereum) vs ERC20 Deposit Asymmetry" and the bullets refer to "native token"
instead of "Native ETH"; also apply the same replacement to the related lines
referenced (around lines 400-403) so all mentions are consistent across the
section.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@contracts/SECURITY.md`:
- Around line 380-387: Update the section titled "Native ETH vs ERC20 Deposit
Asymmetry" to use chain-neutral wording: replace occurrences of "ETH" with
"native token" and where helpful add parenthetical clarification like "(ETH on
Ethereum)" so the text reads e.g. "Native token (ETH on Ethereum) vs ERC20
Deposit Asymmetry" and the bullets refer to "native token" instead of "Native
ETH"; also apply the same replacement to the related lines referenced (around
lines 400-403) so all mentions are consistent across the section.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a39fa75a-aa4b-4633-8d4f-d80df27b1248

📥 Commits

Reviewing files that changed from the base of the PR and between d29d099 and 30526ac.

📒 Files selected for processing (2)

• contracts/SECURITY.md
• contracts/src/ChannelHub.sol

✅ Files skipped from review due to trivial changes (1)

• contracts/src/ChannelHub.sol