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.

[luiz-lvj]

Hey @ernestognw, what is the expected behavior if there are two epochs in the queue and the admin, by mistake or something else, calls _fulfillDeposit on the newer epoch first? As of now, it would result in losses of the oldest epoch, which is not desired. This happens because:

• _consumeClaimable* consumes .front() (oldest) without checking it's fulfilled.
• _asyncMax* sums _claimableDepositRequest across the whole queue, skipping pending epochs but continuing to count fulfilled ones behind them.

Imo we could either revert if the admin tries to do that or only ever look at the contiguous fulfilled prefix (which I prefer). If the current behavior is intended we should at least document it.

[ernestognw]

Hey @ernestognw, what is the expected behavior if there are two epochs in the queue and the admin, by mistake or something else, calls _fulfillDeposit on the newer epoch first?

Hey @luiz-lvj, thanks for the review, this is a great finding. I believe we just didn't consider an out of order fulfillment because it's arguably on the integrator side but it's true that we can make it safe from the base layer.

I believe the right behavior for the _fulfill* functions is to allow out-of-order fulfillment, but then the corresponding _consume* functions should stop at the first pending epoch. This way we still keep it as a "no op" (ie. meaning it won't force a revert).

I updated accordingly and added tests for these cases.