Update refund docs on IERC7984Receiver

[arr00]

Summary by CodeRabbit

• Documentation
  • Updated guidance for transfer callback behavior, clarifying refund mechanisms and warning against potential double refunds.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[netlify]

✅ Deploy Preview for confidential-tokens ready!

Name	Link
🔨 Latest commit	ed2e52a
🔍 Latest deploy log	https://app.netlify.com/projects/confidential-tokens/deploys/69222d4d970cfb00085edc33
😎 Deploy Preview	https://deploy-preview-257--confidential-tokens.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

Walkthrough

Documentation update to the IERC7984Receiver interface clarifying the onConfidentialTransferReceived callback behavior. The guidance now states that returning false triggers a refund attempt and warns against potential double refunds if manual refunds are performed alongside returning false.

Changes

Cohort / File(s)	Summary
Documentation Updates contracts/interfaces/IERC7984Receiver.sol	Updated callback documentation to clarify refund behavior when callback returns false and added warning about potential double refunds

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• Update checkOnTransferReceived doc #235: Updates related documentation describing fallback behavior when receiver callback returns false, mirroring the same guidance pattern.

Suggested labels

ignore-changeset

Poem

🐰 A note, a clarification, words rearranged,
The callback's behavior, now clearly explained,
"Return false for refund," the guidance now sings,
Yet beware the double refund that might bring!
Documentation blooms in the autumn light. 📝

Pre-merge checks and finishing touches

✅ 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 'Update refund docs on IERC7984Receiver' directly and clearly describes the main change: documentation updates to the IERC7984Receiver interface regarding refund guidance.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/update-refund-docs

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 8199f33 and ed2e52a.

📒 Files selected for processing (1)

• contracts/interfaces/IERC7984Receiver.sol (1 hunks)

🧰 Additional context used

🧠 Learnings (2)

📓 Common learnings

Learnt from: arr00
Repo: OpenZeppelin/openzeppelin-confidential-contracts PR: 186
File: contracts/token/ERC7984/extensions/ERC7984Omnibus.sol:140-167
Timestamp: 2025-09-15T14:43:25.644Z
Learning: In ERC7984Omnibus callback functions like confidentialTransferFromAndCallOmnibus, the encrypted sender and recipient addresses are not passed to the callback recipient - only the standard transfer parameters (omnibusFrom, omnibusTo, amount, data) are passed. The ACL grants for the encrypted addresses are for omnibus event emission and future access, not for callback usage.

Learnt from: james-toussaint
Repo: OpenZeppelin/openzeppelin-confidential-contracts PR: 160
File: test/token/ERC7984/extensions/ERC7984Rwa.test.ts:474-479
Timestamp: 2025-09-22T09:21:34.470Z
Learning: For force transfers in ERC7984Freezable, the frozen balance should be reset to the new balance if the transfer amount exceeded the available balance. If the transfer amount was within the available balance, the frozen amount behavior needs clarification from the user.

📚 Learning: 2025-09-15T14:43:25.644Z

Learnt from: arr00
Repo: OpenZeppelin/openzeppelin-confidential-contracts PR: 186
File: contracts/token/ERC7984/extensions/ERC7984Omnibus.sol:140-167
Timestamp: 2025-09-15T14:43:25.644Z
Learning: In ERC7984Omnibus callback functions like confidentialTransferFromAndCallOmnibus, the encrypted sender and recipient addresses are not passed to the callback recipient - only the standard transfer parameters (omnibusFrom, omnibusTo, amount, data) are passed. The ACL grants for the encrypted addresses are for omnibus event emission and future access, not for callback usage.

Applied to files:

• contracts/interfaces/IERC7984Receiver.sol

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: slither

🔇 Additional comments (1)

contracts/interfaces/IERC7984Receiver.sol (1)

10-13: Refund behavior documentation is accurate; no changes needed.

The implementation at contracts/token/ERC7984/ERC7984.sol lines 268–272 confirms the documented behavior:

• The callback return value is evaluated via FHE.select(success, FHE.asEuint64(0), sent), an encrypted operation that automatically refunds the full amount when ebool is false
• The refund is unconditional and cannot be prevented by the callback recipient
• The double-refund warning is well-placed and necessary, since both the automatic refund and any manual refund in the callback would execute

The documentation is clear and matches the implementation.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}