ERC-7540: Epoch-based fulfillment strategy

[ernestognw]

Summary

• Adds ERC7540EpochDeposit and ERC7540EpochRedeem — epoch-based batch fulfillment strategies for ERC-7540 async vaults
• Adds ERC7540EpochMock for testing
• Extracted from Add abstract ERC7540 and specific implementations #228 to reduce complexity of the base PR

Production equivalents: Cove, Amphor, Lagoon.

Known pending work

• Replace bare require statements in _fulfillDeposit/_fulfillRedeem with custom errors — typed errors *TooEarly, *EmptyEpoch, *AlreadyFulfilled are now thrown
• Add fulfillment events to _fulfillDeposit/_fulfillRedeem — ERC7540Epoch{Deposit,Redeem}Fulfilled emitted with the locked rate
• Verify whether saturatingSub is needed for the subtraction operations in _consumeClaimable* loops — resolved via saturatingSub + drained-epoch handling; residual-dust bound is documented as a NOTE in both contracts
• Public getters for _epochs totals — totalDepositAssets/totalDepositShares and totalRedeemAssets/totalRedeemShares expose the per-epoch state
• Public getter for _memberOf (per-controller epoch queue) — depends on Add values(start, end) slice accessor to DoubleEndedQueue openzeppelin-contracts#6522 for paginated DoubleEndedQueue access
• Add tests — ERC7540EpochDeposit.test.js (435 lines) and ERC7540EpochRedeem.test.js (410 lines)

Test plan

• Test epoch lifecycle: request → fulfill → claim across deposit and redeem
• Test multi-epoch claims (controller with requests in multiple fulfilled epochs)
• Test _requestQueueLimit enforcement (32 default)
• Test partial claims within an epoch
• Test that DoS via small requests is bounded per-account by queue limit
• ERC-165 interface support validation — covered via shouldSupportInterfaces in the included shouldBehaveLikeERC7540{Operator,Deposit,Redeem} helpers

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Implemented ERC-7540 epoch-based asynchronous deposit protocol with automatic request batching, queue management, and pro-rata share distribution upon epoch fulfillment
  • Implemented ERC-7540 epoch-based asynchronous redemption protocol with automatic request batching, queue management, and pro-rata asset distribution upon epoch fulfillment
  • Added comprehensive test infrastructure for validating epoch-driven deposit and redemption request behavior

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

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: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a9406a3a-99d9-411a-be4e-39009d183ba5

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

Three new contracts are introduced to implement ERC-7540 epoch-based asynchronous deposits and redemptions. An abstract ERC7540EpochDeposit contract handles deposit requests batched by epoch with pro-rata share conversion upon fulfillment. A complementary ERC7540EpochRedeem contract manages redemption requests similarly. A test mock contract (ERC7540EpochMock) combines both implementations for testing purposes.

Changes

Cohort / File(s)	Summary
Epoch-Based Deposit & Redeem contracts/token/ERC20/extensions/ERC7540EpochDeposit.sol, contracts/token/ERC20/extensions/ERC7540EpochRedeem.sol	Introduces two abstract contracts implementing ERC-7540 asynchronous deposit and redemption flows with per-epoch tracking of totals and requests, controller epoch queue management with limits, claimability determination via fulfillment status, and pro-rata conversion logic using floor/ceil rounding rules.
Test Mock contracts/mocks/token/ERC7540EpochMock.sol	Adds abstract mock contract combining both epoch deposit and redeem functionality with internal method overrides (_requestDeposit, _requestRedeem, _requestQueueLimit) that forward to parent implementations for testing derived contracts.

Sequence Diagram(s)

sequenceDiagram
    participant Controller
    participant ERC7540EpochDeposit
    participant EpochQueue
    participant Fulfillment

    Controller->>ERC7540EpochDeposit: requestDeposit(assets)
    ERC7540EpochDeposit->>ERC7540EpochDeposit: Calculate currentDepositEpoch
    ERC7540EpochDeposit->>ERC7540EpochDeposit: Record assets to epoch.requests
    ERC7540EpochDeposit->>EpochQueue: Enqueue epochId if new (respecting _requestQueueLimit)
    Note over ERC7540EpochDeposit: Deposit request batched by epoch

    Fulfillment->>ERC7540EpochDeposit: _fulfillDeposit(epochId, totalShares)
    ERC7540EpochDeposit->>ERC7540EpochDeposit: Set epoch.totalShares (now claimable)
    Note over ERC7540EpochDeposit: Epoch becomes eligible for claims

    Controller->>ERC7540EpochDeposit: claimDeposit() or maxClaimableDeposit()
    loop For each queued epoch
        ERC7540EpochDeposit->>ERC7540EpochDeposit: Check if totalShares > 0 (fulfilled)
        ERC7540EpochDeposit->>ERC7540EpochDeposit: Pro-rata convert: shares = (requests × totalShares) / totalAssets
        ERC7540EpochDeposit->>ERC7540EpochDeposit: Reduce epoch.requests and totalAssets
    end
    ERC7540EpochDeposit->>Controller: Return minted shares

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

A rabbit hops through epochs bright,
Deposits queue in batches light,
When fulfilment's whisper breaks the night,
Pro-rata shares bloom just right! 🐰✨
Async redemptions, queued with care—
New ERC-7540 magic fair!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'ERC-7540: Epoch-based fulfillment strategy' clearly and concisely summarizes the main change: introducing epoch-based fulfillment logic for ERC-7540 vaults.
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ 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 feat/erc-7540-epoch

---

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

[coderabbitai]

Actionable comments posted: 4

🤖 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/token/ERC20/extensions/ERC7540EpochDeposit.sol`:
- Around line 183-188: Compute batchShares using the pre-mutation epoch totals
(use details.totalAssets and details.totalShares before any -= on
details.totalAssets/details.totalShares/requests[controller]/assets) so
conversions use the locked epoch rate; i.e., calculate batchShares =
batchAssets.mulDiv(details.totalShares, details.totalAssets,
Math.Rounding.Floor) before you decrement details.requests[controller],
details.totalAssets, details.totalShares, and assets, and then perform the
saturatingSub-style decrements after that calculation (apply same fix for the
other similar block around lines 211-217).
- Around line 58-74: The epoch fulfilment sentinel must not rely on totalShares
== 0 because _fulfillDeposit can legitimately set totalShares to 0; add an
explicit boolean (e.g., EpochDepositMetadata.fulfilled) to the
EpochDepositMetadata struct, set it to true in _fulfillDeposit, and update
_pendingDepositRequest, _claimableDepositRequest, and _assetsToFulfillDeposit to
check details.fulfilled (false = pending, true = claimable) instead of comparing
totalShares; also ensure any logic that previously relied on totalShares==0 is
adjusted to use the new fulfilled flag and that _fulfillDeposit still records
totalShares correctly while marking fulfilled.

In `@contracts/token/ERC20/extensions/ERC7540EpochRedeem.sol`:
- Around line 59-75: The code treats details.totalAssets == 0 as the sole
sentinel for "fulfilled", which breaks when _fulfillRedeem writes totalAssets ==
0; to fix, add an explicit fulfilled flag to EpochRedeemMetadata (e.g., bool
fulfilled), set details.fulfilled = true inside _fulfillRedeem whenever the
epoch is processed (even if totalAssets == 0), and change _pendingRedeemRequest
and _claimableRedeemRequest to check details.fulfilled (pending when !fulfilled,
claimable when fulfilled). Also update any logic in _sharesToFulfillRedeem and
other spots that currently rely on totalAssets == 0 to use the new fulfilled
flag while still reading totalAssets for amounts.
- Around line 187-193: The batch share conversion uses mutated epoch totals
causing divide-by-zero and wrong rates; before mutating details.totalAssets or
details.totalShares, snapshot the epoch totals (e.g., uint256 epochAssets =
details.totalAssets; uint256 epochShares = details.totalShares) and compute
batchShares = batchAssets.mulDiv(epochShares, epochAssets, Math.Rounding.Floor)
using those snapshots, then decrement details.totalAssets/details.totalShares
(and details.requests[controller]) with saturating subtraction to avoid
underflow; apply the same change to the other conversion block that mirrors this
logic.

🪄 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: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 421b1500-d74a-47ef-8a85-bf011a63b917

📥 Commits

Reviewing files that changed from the base of the PR and between 38b8329 and aaaa6c4.

📒 Files selected for processing (3)

• contracts/mocks/token/ERC7540EpochMock.sol
• contracts/token/ERC20/extensions/ERC7540EpochDeposit.sol
• contracts/token/ERC20/extensions/ERC7540EpochRedeem.sol

[ernestognw]

Worth flagging that we still don't have a way to observe the epochs a user has pending requests in — the _epochs / _memberOf getter item in the "Known pending work" list above. Toward that, I just opened OpenZeppelin/openzeppelin-contracts#6522, which adds a values(start, end) slice accessor to DoubleEndedQueue. Once it lands, we can expose a paginated getter here that returns the queue of pending requests per account without copying the whole deque.