H-I02: docs(contracts): add a note that rebasing tokens are not supported

[nksazonov]

Description

The ChannelHub contract tracks node balances using a static _nodeBalances mapping that is fundamentally incompatible with rebasing tokens (e.g., stETH, aTokens, rebase stablecoins). When rebasing tokens rebase, their balances change autonomously without any transfer occurring, creating a critical desynchronization between the accounting tracked in _nodeBalances and the actual token balance held by the contract.

When a rebasing token experiences a negative rebase (balance decrease), the actual contract balance decreases proportionally while _nodeBalances remains completely unchanged. This creates an insolvency scenario where the sum of all recorded node balances in _nodeBalances exceeds the actual tokens held by the contract.

The vulnerability manifests in a first-come-first-served pattern: early withdrawers successfully withdraw their full recorded amounts, while later withdrawers face silent transfer failures. The ChannelHub's transfer failure handling mechanism (_pushFunds) catches these failures and adds the amounts to a reclaim queue (_reclaims mapping), but critically, these are unfulfillable obligations - the tokens simply don't exist in the contract to satisfy these debts. When users attempt to claim their reclaimed funds via claimFunds(), the transaction reverts because the contract lacks sufficient tokens.

The issue affects all vault operations (depositToVault, withdrawFromVault, purgeEscrowDeposits) and channel operations that rely on _nodeBalances for accounting. No balance reconciliation mechanism exists to detect or handle this mismatch.

Summary by CodeRabbit

• Documentation
  • Added clarification that rebasing tokens (e.g., stETH, aTokens) are not supported due to accounting incompatibility.
  • Provided guidance to use non-rebasing token alternatives (e.g., wstETH instead of stETH).

[nksazonov]

@coderabbitai review

[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: 47256e7c-5618-4de2-9f7d-a4dcf08e3ab1

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

Documentation updates across three files clarifying that rebasing tokens (stETH, aTokens, rebase stablecoins) are not supported by the protocol due to static accounting ledger constraints that cannot track autonomous balance changes.

Changes

Cohort / File(s)	Summary
Token Compatibility Documentation contracts/SECURITY.md, contracts/src/ChannelHub.sol, protocol-description.md	Added warnings and explanations across security, implementation, and protocol description documents specifying that rebasing tokens are incompatible with the static ledger-based accounting model (_nodeBalances, lockedFunds). Documentation includes rationale (autonomous balance changes cause permanent divergence) and guidance to use non-rebasing equivalents (e.g., wstETH instead of stETH).

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• YNU-797: feat(contracts/ChannelHub): add NodeBalanceUpdated event #621: Modifies _nodeBalances updates in ChannelHub and introduces NodeBalanceUpdated event—directly related to the node balance accounting system documented in this PR's warnings about rebasing token incompatibility.

Suggested reviewers

• ihsraham
• philanton
• dimast-x

Poem

🐰 Hops with glee through docs so bright,
"No rebasing tokens!"—plain insight,
Static ledgers hold the line,
wstETH wrapped, the solution fine! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 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.
Title check	✅ Passed	The title clearly and accurately summarizes the main change: adding documentation about rebasing token incompatibility with the protocol.

_{✏️ 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/audit-h-i02

---

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]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

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

Inline comments:
In `@contracts/src/ChannelHub.sol`:
- Around line 299-300: The comment warns that rebasing tokens are unsupported
but not enforced; update the ChannelHub contract to enforce token compatibility
by adding an allowlist and checking it in depositToNode: introduce a
mapping(address=>bool) allowedToken (and an admin setter like
setAllowedToken/renounceAllowedToken in the ChannelHub) and
require(allowedToken[token], "token not allowed") at the start of depositToNode
to reject unsupported tokens and prevent _nodeBalances desync; ensure any
admin/setter functions are properly access-controlled (e.g., onlyOwner) and
include tests exercising depositToNode reverts for disallowed tokens and success
for allowed ones.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 734db7c2-21b7-41b9-b474-4a78edc63c9f

📥 Commits

Reviewing files that changed from the base of the PR and between c2310fe and 0ab6639.

📒 Files selected for processing (3)

• contracts/SECURITY.md
• contracts/src/ChannelHub.sol
• protocol-description.md