Strategic Proposal: BASE-NETWORK Optimization

[arawrdn]

Summary

This PR introduces a strategic shift from fully push-based recipient payouts to a pull-based cumulative index distribution model for pool revenue distribution.

Instead of iterating over every recipient during each distribution cycle, pools now track a high-precision cumulative accumulator, accUSDCPerShare, and recipients claim their accrued USDC based on their assigned shares and rewardDebt.

This approach significantly improves scalability, gas predictability, and operational liveness as pool participation grows.

---

Motivation

The previous push-based distribution model required processing recipient payouts during each cycle, resulting in O(n) execution cost relative to the number of recipients.

As pools grow, this pattern becomes increasingly expensive and operationally fragile:

• Distribution cycles become gas-heavy as recipient count increases.
• A failed or problematic recipient payout path can disrupt the entire cycle.
• Frequent treasury operations become harder to automate reliably.
• Scaling to larger pools introduces unnecessary execution risk.

This PR adopts a pull-based accrual and claim model, where funding updates remain near O(1) and payout execution is moved to recipients or delegated claim bots.

---

What Changed

Cumulative Pool Index

Each pool now maintains a high-precision cumulative USDC-per-share accumulator:

accUSDCPerShare

The accumulator uses a precision scalar, such as 1e27, to safely account for fractional allocations.

When revenue enters a pool, the pool accumulator is incremented once based on the incoming amount and the total active shares.

---

Recipient Accounting

Each recipient is tracked using:

shares
rewardDebt

Claimable rewards are calculated as:

claimable = shares * accUSDCPerShare - rewardDebt

On claim, the recipient receives the owed USDC and their rewardDebt is updated to reflect the latest accumulator checkpoint.

---

Pull-Based Claims

Recipients can now claim accrued USDC directly.

This enables:

• Self-service claims by recipients
• Claims through delegated bots or subaccounts
• Cleaner operational automation
• Reduced dependency on centralized distribution execution

---

Checkpointing on Mutations

Before recipient state is changed, the recipient is force-settled/checkpointed.

This applies to changes such as:

• Adding a recipient
• Removing a recipient
• Updating recipient shares
• Reassigning allocation weight

Checkpointing before mutation ensures accrued rewards remain correct and prevents allocation drift across share changes.

---

Strategic Benefits

Predictable Gas at Scale

Distribution updates no longer require iterating through every recipient.

Incoming revenue updates are near O(1), making costs more predictable even as the number of recipients grows.

---

Improved Liveness

A single problematic recipient payout can no longer block a full distribution cycle.

Each recipient claim is isolated, improving reliability and reducing operational risk.

---

Better Automation

The model supports claim bots, delegated execution, and subaccount-based workflows.

This makes recurring treasury operations easier to automate without requiring full-pool payout transactions.

---

Preserved Auditability

The model preserves on-chain auditability through accumulator updates, recipient checkpoints, and claim events.

Revenue can still be attributed by source, bucket, pool, or distribution checkpoint through emitted events.

---

High-Level Flow

Revenue Accrual

1. USDC revenue is received by the pool.
2. Pool updates accUSDCPerShare.
3. Event is emitted for attribution and auditability.

Recipient Claim

1. Recipient calls claim().
2. Contract calculates accrued USDC:

   shares * accUSDCPerShare - rewardDebt

3. USDC is transferred to the recipient.
4. rewardDebt is updated.
5. Claim event is emitted.

Share Mutation

1. Recipient is checkpointed before mutation.
2. Any accrued amount is settled or recorded.
3. Shares are updated.
4. rewardDebt is reset against the current accumulator.

---

Impact

This change replaces a gas-intensive, cycle-based payout model with a scalable accrual model that is better suited for larger pools and frequent treasury activity.

The result is:

• Lower and more predictable distribution gas
• Reduced risk of failed payout cycles
• Better support for automation
• Scalable recipient growth
• Clear on-chain accounting and attribution

---

Notes for Reviewers

Please pay particular attention to:

• Accumulator precision and rounding behavior
• rewardDebt updates on claim and share mutation
• Checkpoint behavior when adding, removing, or modifying recipients
• Handling of zero-share pools during revenue accrual
• USDC transfer safety and failure isolation
• Event coverage for auditability and attribution