/pump-token-incentives

name: pump-token-incentives
description: "Volume-based PUMP token reward system with day-indexed epochs, pro-rata distribution, accumulator tracking, and cross-program claiming on Solana."
metadata:
  openclaw:
    homepage: https://github.com/nirholas/pump-fun-sdk
    requires:
      env:
        - SOLANA_RPC_URL

Token Incentives — Volume-Based PUMP Token Rewards

Implement and maintain the token incentive system that rewards traders with PUMP governance tokens based on their SOL trading volume, using a day-based epoch system with pro-rata distribution.

Context

The Pump protocol incentivizes trading activity by distributing PUMP tokens to users proportional to their SOL trading volume. The system tracks volume in day-long epochs, with each day having a pre-configured token supply pool.

Day-Based Epoch System

Volume tracking operates in fixed-length epochs defined by the `GlobalVolumeAccumulator`:

• `startTime` — epoch system start timestamp
• `secondsInADay` — epoch length (typically 86,400 seconds)
• `solVolumes[]` — array of total SOL volume per day
• `totalTokenSupply[]` — array of PUMP tokens available per day

dayIndex = Math.floor((currentTimestamp - startTime) / secondsInADay)

Pro-Rata Reward Formula

$$\text{tokens} = \frac{\text{userSolVolume} \times \text{dayTokenSupply}}{\text{globalSolVolume}}$$

Account Lifecycle

1. **Init** (`initUserVolumeAccumulator`) — creates the user's volume accumulator PDA 2. **Sync** (`syncUserVolumeAccumulator`) — updates the accumulator with latest volume data 3. **Claim** (`claimTokenIncentives`) — claims accumulated PUMP token rewards 4. **Close** (`closeUserVolumeAccumulator`) — closes the account, reclaims rent

BothPrograms Aggregation

Since users trade on both the bonding curve (Pump) and AMM (PumpAMM):

• `fetchUserVolumeAccumulatorTotalStats(user)` — sums across both programs
• `getTotalUnclaimedTokensBothPrograms(user)` — combined unclaimed rewards
• `claimTokenIncentivesBothPrograms(user, payer)` — claims from both
• `syncUserVolumeAccumulatorBothPrograms(user)` — syncs both

Edge Cases

| Case | Behavior | |------|----------| | Zero global volume for a day | No tokens distributed (division by zero guarded) | | User never synced | Only `totalUnclaimedTokens` from account state returned | | Day index beyond arrays | No additional rewards computed | | User updated same day | `currentDayTokens` returns preview, `totalUnclaimedTokens` excludes it |

Patterns to Follow

• Pure functions in `tokenIncentives.ts` — no side effects, no RPC calls
• Accept optional `currentTimestamp` parameter for testability
• Always use `BN` arithmetic — never convert to JavaScript `number`
• Sync before claiming to ensure the latest volume is reflected

Common Pitfalls

• `totalUnclaimedTokens` does NOT include the current day's rewards — only finalized days
• `currentDayTokens` returns 0 if the user's last update was on a different day (sync first)
• Day indices are zero-based from `startTime`, not from epoch 0
• Volume accumulator PDAs differ between Pump and PumpAMM programs