my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

#1	---
#2	name: pump-claims-readonly
#3	description: "Read-only query methods for PumpFun claims — unclaimed token rewards, creator vault balances, volume accumulators, distributable fees, and current-day token previews across Pump and PumpAMM programs."
#4	metadata:
#5	openclaw:
#6	homepage: https://github.com/nirholas/pump-fun-sdk
#7	requires:
#8	env:
#9	- SOLANA_RPC_URL
#10	---
#11
#12	# PumpFun Claims — Read-Only Queries
#13
#14	Query unclaimed rewards, creator vault balances, volume accumulators, and distributable fee status without submitting any transactions. All methods are read-only RPC calls on the `OnlinePumpSdk` class.
#15
#16	## Overview
#17
#18	The Pump protocol has two claim domains:
#19
#20	\| Domain \| What is claimed \| Who claims \|
#21	\|--------\|----------------\|------------\|
#22	\| Token Incentives \| PUMP governance tokens earned from trading volume \| Any trader \|
#23	\| Creator Fees \| SOL accumulated in creator vaults from coin creation fees \| Coin creators \|
#24
#25	Both domains span two on-chain programs — Pump (bonding curve) and PumpAMM (graduated pools). The `BothPrograms` variants aggregate across both.
#26
#27	## Setup
#28
#29	```typescript
#30	import { Connection, PublicKey } from "@solana/web3.js";
#31	import { OnlinePumpSdk } from "@nirholas/pump-sdk";
#32
#33	const connection = new Connection(process.env.SOLANA_RPC_URL!);
#34	const sdk = new OnlinePumpSdk(connection);
#35	const user = new PublicKey("...");
#36	```
#37
#38	## Token Incentive Queries
#39
#40	### Unclaimed Token Rewards
#41
#42	Get the total unclaimed PUMP tokens for a user. This includes all finalized day epochs but excludes the current day's rewards.
#43
#44	```typescript
#45	// Single program (Pump bonding curve only)
#46	const unclaimed: BN = await sdk.getTotalUnclaimedTokens(user);
#47
#48	// Both programs (Pump + PumpAMM) — recommended
#49	const unclaimedTotal: BN = await sdk.getTotalUnclaimedTokensBothPrograms(user);
#50	```
#51
#52	How it works: Fetches `GlobalVolumeAccumulator` and `UserVolumeAccumulator` accounts, then computes rewards using the pure function `totalUnclaimedTokens()` from `tokenIncentives.ts`.
#53
#54	### Current Day Token Preview
#55
#56	Preview how many PUMP tokens the user would earn from the current (in-progress) day. This is a projection — the day hasn't finalized yet.
#57
#58	```typescript
#59	// Single program
#60	const todayTokens: BN = await sdk.getCurrentDayTokens(user);
#61
#62	// Both programs — recommended
#63	const todayTokensTotal: BN = await sdk.getCurrentDayTokensBothPrograms(user);
#64	```
#65
#66	Important: Returns `BN(0)` if the user hasn't synced during the current day. Call `syncUserVolumeAccumulator` first for an accurate preview.
#67
#68	### Volume Accumulator Stats
#69
#70	Fetch aggregate stats showing claimed, unclaimed, and current volume across both programs.
#71
#72	```typescript
#73	const stats: UserVolumeAccumulatorTotalStats =
#74	await sdk.fetchUserVolumeAccumulatorTotalStats(user);
#75
#76	// stats.totalUnclaimedTokens — BN, finalized unclaimed PUMP tokens
#77	// stats.totalClaimedTokens — BN, lifetime claimed PUMP tokens
#78	// stats.currentSolVolume — BN, SOL volume in current epoch
#79	```
#80
#81	Return type:
#82
#83	```typescript
#84	interface UserVolumeAccumulatorTotalStats {
#85	totalUnclaimedTokens: BN;
#86	totalClaimedTokens: BN;
#87	currentSolVolume: BN;
#88	}
#89	```
#90
#91	### Raw Volume Accumulators
#92
#93	For lower-level access, fetch the on-chain accounts directly:
#94
#95	```typescript
#96	// Global config (start/end times, daily supply, daily volumes)
#97	const global: GlobalVolumeAccumulator =
#98	await sdk.fetchGlobalVolumeAccumulator();
#99
#100	// Per-user accumulator (returns null if account doesn't exist)
#101	const userAcc: UserVolumeAccumulator \| null =
#102	await sdk.fetchUserVolumeAccumulator(user);
#103	```
#104
#105	Account structures:
#106
#107	```typescript
#108	interface GlobalVolumeAccumulator {
#109	startTime: BN;
#110	endTime: BN;
#111	secondsInADay: BN; // typically 86400
#112	mint: PublicKey; // PUMP token mint
#113	totalTokenSupply: BN[]; // tokens available per day
#114	solVolumes: BN[]; // total SOL volume per day
#115	}
#116
#117	interface UserVolumeAccumulator {
#118	user: PublicKey;
#119	needsClaim: boolean;
#120	totalUnclaimedTokens: BN;
#121	totalClaimedTokens: BN;
#122	currentSolVolume: BN;
#123	lastUpdateTimestamp: BN;
#124	}
#125	```
#126
#127	### Pure Computation Functions
#128
#129	If you already hold the account data, compute rewards offline without RPC:
#130
#131	```typescript
#132	import { totalUnclaimedTokens, currentDayTokens } from "@nirholas/pump-sdk";
#133
#134	const unclaimed: BN = totalUnclaimedTokens(globalAcc, userAcc);
#135	const today: BN = currentDayTokens(globalAcc, userAcc);
#136
#137	// Optional: pass a custom timestamp for testing
#138	const unclaimed2 = totalUnclaimedTokens(globalAcc, userAcc, 1700000000);
#139	```
#140
#141	## Creator Fee Queries
#142
#143	### Creator Vault Balance
#144
#145	Check how much SOL is sitting in a creator's fee vault, ready to be collected.
#146
#147	```typescript
#148	// Single program (Pump bonding curve vault only)
#149	const balance: BN = await sdk.getCreatorVaultBalance(creator);
#150
#151	// Both programs (Pump + PumpAMM vaults) — recommended
#152	const totalBalance: BN = await sdk.getCreatorVaultBalanceBothPrograms(creator);
#153	```
#154
#155	Note: `getCreatorVaultBalance` subtracts the rent-exemption minimum — it returns only the withdrawable amount.
#156
#157	### Minimum Distributable Fee
#158
#159	Check whether a token's fee-sharing configuration has enough accumulated fees to distribute, and the minimum threshold required.
#160
#161	```typescript
#162	const result: MinimumDistributableFeeResult =
#163	await sdk.getMinimumDistributableFee(mint);
#164
#165	// result.minimumRequired — BN, minimum SOL needed to distribute
#166	// result.distributableFees — BN, current accumulated fees
#167	// result.canDistribute — boolean, true if fees >= minimum
#168	// result.isGraduated — boolean, true if token migrated to AMM
#169	```
#170
#171	How it works: Simulates a transaction to read the return data from the on-chain program. For graduated tokens, it also simulates consolidating AMM vault fees before checking the threshold.
#172
#173	Return type:
#174
#175	```typescript
#176	interface MinimumDistributableFeeResult {
#177	minimumRequired: BN;
#178	distributableFees: BN;
#179	canDistribute: boolean;
#180	isGraduated: boolean;
#181	}
#182	```
#183
#184	## PDA Addresses
#185
#186	The relevant PDAs for claim-related accounts:
#187
#188	```typescript
#189	import {
#190	userVolumeAccumulatorPda,
#191	creatorVaultPda,
#192	feeSharingConfigPda,
#193	GLOBAL_VOLUME_ACCUMULATOR_PDA,
#194	} from "@nirholas/pump-sdk";
#195
#196	const userVolumePda = userVolumeAccumulatorPda(user);
#197	const vaultPda = creatorVaultPda(creator);
#198	const sharingPda = feeSharingConfigPda(mint);
#199	```
#200
#201	## Quick Reference
#202
#203	\| Method \| Returns \| Programs \|
#204	\|--------\|---------\|----------\|
#205	\| `getTotalUnclaimedTokens(user)` \| `BN` \| Pump only \|
#206	\| `getTotalUnclaimedTokensBothPrograms(user)` \| `BN` \| Pump + AMM \|
#207	\| `getCurrentDayTokens(user)` \| `BN` \| Pump only \|
#208	\| `getCurrentDayTokensBothPrograms(user)` \| `BN` \| Pump + AMM \|
#209	\| `fetchUserVolumeAccumulatorTotalStats(user)` \| `UserVolumeAccumulatorTotalStats` \| Pump + AMM \|
#210	\| `fetchGlobalVolumeAccumulator()` \| `GlobalVolumeAccumulator` \| Pump \|
#211	\| `fetchUserVolumeAccumulator(user)` \| `UserVolumeAccumulator \\| null` \| Pump \|
#212	\| `getCreatorVaultBalance(creator)` \| `BN` \| Pump only \|
#213	\| `getCreatorVaultBalanceBothPrograms(creator)` \| `BN` \| Pump + AMM \|
#214	\| `getMinimumDistributableFee(mint)` \| `MinimumDistributableFeeResult` \| Pump + AMM \|
#215
#216	## Edge Cases
#217
#218	\| Scenario \| Behavior \|
#219	\|----------\|----------\|
#220	\| User has no volume accumulator account \| `fetchUserVolumeAccumulator` returns `null`; unclaimed methods return `BN(0)` \|
#221	\| Creator vault doesn't exist \| `getCreatorVaultBalance` returns `BN(0)` \|
#222	\| Sharing config not found for mint \| `getMinimumDistributableFee` throws `Error` \|
#223	\| User hasn't synced current day \| `getCurrentDayTokens` returns `BN(0)` \|
#224	\| Global volume is zero for a day \| No tokens distributed (division-by-zero guarded) \|
#225	\| Token not yet graduated \| `isGraduated` is `false`; only bonding curve vault checked \|
#226
#227	## Patterns to Follow
#228
#229	- Always use `BothPrograms` variants unless you specifically need single-program data
#230	- All return values are `BN` (bn.js) — never convert to JavaScript `number` for financial math
#231	- `totalUnclaimedTokens` excludes current-day rewards — add `getCurrentDayTokens` for full picture
#232	- Call `syncUserVolumeAccumulator` before reading `getCurrentDayTokens` for accuracy
#233	- This skill covers read-only queries only — for claiming and collecting, see the `pump-token-incentives` and `pump-fee-sharing` skills
#234
#235

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public