Automatic claims

[exo404]

Summary

This PR adds Gelato-powered automatic claims to the existing AutomaticSavingCircles automation extension.

Gelato can now resolve and execute claimable payouts automatically once both required conditions are true:

• all members have deposited for the payout round,
• the payout round’s time window has passed.

What Changed

Added a new automatic claim flow:

• claimChecker() scans all circles and returns executable calldata when any member is eligible to claim.
• getEligibleAutomatedClaims() returns all eligible (circleId, member) claim targets.
• batchExecuteAutomatedClaims(...) executes claim targets through Gelato’s configured executor.
• executeAutomatedClaimTarget(...) is used internally so failed targets do not block the full batch with the try/catch pattern.
• AutomatedClaimFailed(...) is emitted when an individual claim target fails during batch execution.

Claim eligibility requires:

• the circle is active,
• the circle is not decommissionable,
• the member’s payout round time has passed,
• SavingCircles.isMemberWithdrawable(circleId, member) returns true.

This means Gelato only claims when deposits are complete and the time condition is satisfied.

SavingCircles Change

withdrawFor(...) is now truly permissionless for valid claim recipients. The caller no longer needs to be a circle member; instead, the target member must be a valid member and must be withdrawable.

This is required because the automation contract is not a member of each circle, but it needs to trigger claims on behalf of eligible members. The payout safety checks still remain in place through _claimable(...).

Tests

Added coverage for:

• claim targets are not returned before the round time has passed,
• claim targets are not returned when deposits are incomplete,
• claimChecker() returns the correct batch execution payload,
• automatic claims execute across multiple circles,
• only the configured Gelato executor can run claim batches,
• mismatched claim batch arrays revert,
• non-member callers can trigger withdrawFor(...) for valid recipients,
• invalid claim recipients still revert.

Validation:

• forge test
  Full suite passes: 156 tests.

[bagelface]

There is a discrepancy here. need to either update this comment to "Whether Gelato can execute the claims" or change the name of the variable.

[bagelface]

check these values are false and balance is correct before the automated claim? maybe not needed since we dont seem to be checking pre-state for other tests

[bagelface]

Naming of this function is a bit confusing, since it implies it's populating an array but really it's just returning the next index. The comments and function name prescribe a use to the function, which I think isn't ideal. Consider renaming to something like "_getNextEligibleAutomationClaimIndexForCircle"

[bagelface]

This and every comment in this thread was generated by Claude 🤖

Overall the PR is well-structured and consistent with the existing deposit automation pattern. A few issues below, not covered by existing comments.

[bagelface]

_executeAutomatedClaimTarget fetches getCircleMembers and calls _getMemberIndex to check membership, then calls _isEligibleForAutomatedClaim, which calls isMemberWithdrawable → _claimable → _activeClaimableCheck → _getMemberIndex — so membership is verified twice with two separate getCircleMembers calls. Since withdrawFor → _withdraw has onlyMember(_id, _member) as a hard guard, the explicit NotMember revert at line 239 is also redundant. Consider dropping the pre-check and relying on withdrawFor to enforce it, or at least share the member list with _isEligibleForAutomatedClaim to avoid the duplicate fetch.

[bagelface]

This assumes _memberIndex (the position in getCircleMembers()) equals the member's payout round index. That invariant holds as long as member order in the array is the canonical payout order, but it is implicit. Worth adding a comment asserting this assumption so a future refactor of how member order is stored does not silently break claim eligibility.

[bagelface]

I think we make this assumption throughout the contract, so can probably skip this

[bagelface]

isActive and isDecommissionable are checked here (and again in _populateEligibleAutomatedClaimsForCircle) before calling _isEligibleForAutomatedClaim, which already checks both conditions (lines 438–440). The early-exit guards are redundant and could diverge from the authoritative check over time. Consider removing them from _countEligibleAutomatedClaimsForCircle and _populateEligibleAutomatedClaimsForCircle and letting _isEligibleForAutomatedClaim be the single gate.

[bagelface]

I generally agree with this comment, but assuming the early-exit guards aren't too expensive it can be worth leaving in just to future proof. isDecommissionable loops over members, so this is sort of a heavy check.

[bagelface]

When automationExecutor == address(0), canExec is false but execPayload is still a valid (empty-arrays) encoded call. This is safe (the call would revert on onlyAutomationExecutor), but Gelato's own resolver examples use execPayload = "" when canExec = false. Low priority, but worth aligning for consistency with Gelato conventions.

[bagelface]

Missing parity with the deposit side: there is no test that a failed individual claim target (e.g. already claimed, or round time not yet passed) emits AutomatedClaimFailed and does not block the rest of the batch. Worth adding to match the coverage pattern for deposits.

[bagelface]

Got a few comments on here that I think are worth addressing.