my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

#1	---
#2	name: pump-token-incentives
#3	description: "Volume-based PUMP token reward system with day-indexed epochs, pro-rata distribution, accumulator tracking, and cross-program claiming on Solana."
#4	metadata:
#5	openclaw:
#6	homepage: https://github.com/nirholas/pump-fun-sdk
#7	requires:
#8	env:
#9	- SOLANA_RPC_URL
#10	---
#11
#12	# Token Incentives — Volume-Based PUMP Token Rewards
#13
#14	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.
#15
#16	## Context
#17
#18	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.
#19
#20	## Day-Based Epoch System
#21
#22	Volume tracking operates in fixed-length epochs defined by the `GlobalVolumeAccumulator`:
#23	- `startTime` — epoch system start timestamp
#24	- `secondsInADay` — epoch length (typically 86,400 seconds)
#25	- `solVolumes[]` — array of total SOL volume per day
#26	- `totalTokenSupply[]` — array of PUMP tokens available per day
#27
#28	```typescript
#29	dayIndex = Math.floor((currentTimestamp - startTime) / secondsInADay)
#30	```
#31
#32	## Pro-Rata Reward Formula
#33
#34	$$\text{tokens} = \frac{\text{userSolVolume} \times \text{dayTokenSupply}}{\text{globalSolVolume}}$$
#35
#36	## Account Lifecycle
#37
#38	1. Init (`initUserVolumeAccumulator`) — creates the user's volume accumulator PDA
#39	2. Sync (`syncUserVolumeAccumulator`) — updates the accumulator with latest volume data
#40	3. Claim (`claimTokenIncentives`) — claims accumulated PUMP token rewards
#41	4. Close (`closeUserVolumeAccumulator`) — closes the account, reclaims rent
#42
#43	## BothPrograms Aggregation
#44
#45	Since users trade on both the bonding curve (Pump) and AMM (PumpAMM):
#46
#47	- `fetchUserVolumeAccumulatorTotalStats(user)` — sums across both programs
#48	- `getTotalUnclaimedTokensBothPrograms(user)` — combined unclaimed rewards
#49	- `claimTokenIncentivesBothPrograms(user, payer)` — claims from both
#50	- `syncUserVolumeAccumulatorBothPrograms(user)` — syncs both
#51
#52	## Edge Cases
#53
#54	\| Case \| Behavior \|
#55	\|------\|----------\|
#56	\| Zero global volume for a day \| No tokens distributed (division by zero guarded) \|
#57	\| User never synced \| Only `totalUnclaimedTokens` from account state returned \|
#58	\| Day index beyond arrays \| No additional rewards computed \|
#59	\| User updated same day \| `currentDayTokens` returns preview, `totalUnclaimedTokens` excludes it \|
#60
#61	## Patterns to Follow
#62
#63	- Pure functions in `tokenIncentives.ts` — no side effects, no RPC calls
#64	- Accept optional `currentTimestamp` parameter for testability
#65	- Always use `BN` arithmetic — never convert to JavaScript `number`
#66	- Sync before claiming to ensure the latest volume is reflected
#67
#68	## Common Pitfalls
#69
#70	- `totalUnclaimedTokens` does NOT include the current day's rewards — only finalized days
#71	- `currentDayTokens` returns 0 if the user's last update was on a different day (sync first)
#72	- Day indices are zero-based from `startTime`, not from epoch 0
#73	- Volume accumulator PDAs differ between Pump and PumpAMM programs
#74
#75

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public