x402agent/pump-token-incentives

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