Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
/**
* pump-claims.js
* --------------
* On-chain pump.fun creator-fee claim scanning. Shared by the HTTP route
* (`/api/pump/first-claims`) and the agent-sniper worker's first-claim trigger.
*
* A "first claim" is the first time a creator EVER pulls their accrued
* creator/delegated rewards out of the fee vault — an on-chain, irreversible
* signal that the creator is live and engaged with the coin. `scanFirstClaims`
* returns only creators whose earliest observed claim falls inside the window.
*
* Sources, in priority order:
* 1. PUMPFUN_BOT_URL (an indexer) when configured — fast, pre-aggregated.
* 2. Direct RPC scan of the pump program's recent signatures — always works,
* no indexer required.
*
* A separate GitHub-fee-claim path always runs alongside whichever source
* above is active: it surfaces `claim_social_fee_pda` withdrawals on the
* PumpFees program (`PUMP_FEE_PROGRAM_ID`), which an indexer built around the
* main pump program does not see. Each one is attributed to a coin (or left
* unattributed) by `pump-claims-attribution.js` and checked for impersonation
* via `attributeGithubClaim`, exported so `services/pump-claims` (the
* real-time listener) decodes and attributes claims with the exact same
* logic this RPC fallback uses. The GitHub path itself prefers the listener's
* own `pump_fee_claims` table (real-time, no RPC budget) and falls back to
* `fetchGithubClaimsFromRpc` only when the table has nothing for the window
* (e.g. the listener isn't deployed yet, or the table is empty).
*/
import bs58 from 'bs58';
import { getConnection } from './pump.js';
import { sql } from './db.js';
import { filterFirstClaims } from '../../src/pump/first-claims.js';
import { PUMP_PROGRAM_ID, PUMP_FEE_PROGRAM_ID, WSOL_MINT } from './solana/programs.js';
import {
isSocialClaimLog,
parseSocialFeeClaim,
parseTransactionDistributions,
} from './pump-events.js';
import {
evidenceForSocialFeePda,
evidenceFromPdaHistory,
classifyClaimAttribution,
assessImpersonation,
attributionInfoForLabel,
} from './pump-claims-attribution.js';
import { resolveGithubUserById, resolveCoinGithubContext, resolveSameNameTokens } from './pump-claims-github.js';
const PUMP_PROGRAM = PUMP_PROGRAM_ID;
// Anchor discriminators for the three pump.fun fee-claim instruction variants.
const CLAIM_DISCS = new Set(['e8f5c2eeeada3a59', '7a027f010ebf0caf', 'a537817004b3ca28']);
// Pull a wider lookback so prior claimers are visible and "first" is real.
const LOOKBACK_MULT = 8;
// Quote mints that show up in a claim tx but are never the coin being claimed.
const QUOTE_MINTS = new Set([
'So11111111111111111111111111111111111111112', // wSOL
'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
]);
// GitHub platform id in SharingConfig.shareholder.platform (claim_social_fee_pda's
// `platform` byte). Exported so services/pump-claims's live decoder filters to
// GitHub claims with the exact same constant this RPC fallback uses.
export const GITHUB_SOCIAL_PLATFORM = 2;
// Per-request budget: each candidate can cost one GitHub user lookup, one coin
// metadata fetch, and (lacking same-transaction evidence) up to HISTORY_MAX_TX
// extra RPC calls walking the PDA's history. This is a live HTTP handler, not
// the owner's long-running claim-monitor bot, so the per-scan candidate count
// is bounded tightly; claim instructions are rare enough (per the RPC-fallback
// limits below) that this still covers a normal scan window in practice.
const GITHUB_CLAIMS_BUDGET = 8;
// Ported from the owner's pumpfun-github-claims bot (src/claim-monitor.ts).
const HISTORY_MAX_TX = 40;
const HISTORY_MAX_AGE_SEC = 7 * 86400;
function isSolQuote(quoteMint) {
return !quoteMint || quoteMint === WSOL_MINT || quoteMint === '11111111111111111111111111111111';
}
/**
* First-time claimers in [sinceTs, now]. Newest first, capped at `limit`.
* @param {{ sinceTs: number, limit: number }} opts
* @returns {Promise<Array<{creator,mint,signature,lamports,ts}>>}
*/
export async function scanFirstClaims({ sinceTs, limit }) {
const lim = Math.max(1, Math.min(50, limit));
const lookbackTs =
sinceTs - Math.max(3600, (Math.floor(Date.now() / 1000) - sinceTs) * LOOKBACK_MULT);
const [baseClaims, githubClaims] = await Promise.all([
process.env.PUMPFUN_BOT_URL
? _fetchFromBot(lookbackTs, lim * LOOKBACK_MULT)
: _fetchFromRpc(lookbackTs, lim * LOOKBACK_MULT),
_fetchGithubClaims(lookbackTs),
]);
return filterFirstClaims([...baseClaims, ...githubClaims], sinceTs, lim);
}
/**
* GitHub-attributed fee-PDA withdrawals since `lookbackTs`. Reads the
* `pump_fee_claims` table (populated in real time by `services/pump-claims`)
* first and falls back to the RPC scan whenever the table is empty for the
* window -- not just on a hard failure. A claim instruction is rare enough
* (see "Known limits" in docs/pump-claims-channel.md) that an empty table
* result is ambiguous: it is just as likely to mean "the listener isn't
* deployed yet" or "the backfill hasn't run" as "nothing happened", so the
* RPC scan (bounded, cheap, and the sole source before this listener
* existed) is always worth trying rather than trusting silence from a table
* that might simply not be populated yet.
* @param {number} lookbackTs
*/
async function _fetchGithubClaims(lookbackTs) {
const tableClaims = await _fetchGithubClaimsFromTable(lookbackTs);
if (tableClaims != null && tableClaims.length > 0) {
console.log('[pump-claims] github claims source=table count=%d', tableClaims.length);
return tableClaims;
}
const rpcClaims = await fetchGithubClaimsFromRpc(lookbackTs);
console.log('[pump-claims] github claims source=rpc count=%d', rpcClaims.length);
return rpcClaims;
}
/**
* Read GitHub fee-PDA claims out of the `pump_fee_claims` table. Returns
* `null` when the table itself can't be used -- no `DATABASE_URL`, the table
* doesn't exist yet, or the query failed. Returns an array (possibly empty)
* on a successful query. The caller treats both "null" and "empty array" as
* reasons to also try the RPC scan.
* @param {number} lookbackTs
* @returns {Promise<Array|null>}
*/
async function _fetchGithubClaimsFromTable(lookbackTs) {
try {
const rows = await sql`
select signature, mint, claimer, github_user_id, lamports, label, held, created_at
from pump_fee_claims
where created_at >= to_timestamp(${lookbackTs})
order by created_at desc
limit 200
`;
return rows.map(_rowToGithubClaim);
} catch {
return null;
}
}
function _rowToGithubClaim(row) {
const info = attributionInfoForLabel(row.label);
return {
creator: row.claimer,
mint: row.mint || '',
signature: row.signature,
lamports: Number(row.lamports) || 0,
ts: row.created_at ? Math.floor(new Date(row.created_at).getTime() / 1000) : 0,
source: 'github_fee_claim',
githubUserId: row.github_user_id,
githubLogin: null,
quoteMint: null,
amountRaw: String(row.lamports ?? '0'),
attribution: { label: row.label, headline: info.headline, explanation: info.explanation },
held: Boolean(row.held),
heldReasons: row.held ? ['held for review (see services/pump-claims listener)'] : [],
};
}
async function _fetchFromBot(lookbackTs, maxItems) {
const r = await _botCall('getFirstClaims', { sinceTs: lookbackTs, limit: maxItems });
if (r.ok) return _normalise(r.data);
const r2 = await _botCall('getRecentClaims', { limit: maxItems });
if (r2.ok) return _normalise(r2.data);
return [];
}
async function _botCall(tool, args) {
const url = process.env.PUMPFUN_BOT_URL;
if (!url) return { ok: false };
const headers = { 'content-type': 'application/json', accept: 'application/json' };
if (process.env.PUMPFUN_BOT_TOKEN)
headers.authorization = `Bearer ${process.env.PUMPFUN_BOT_TOKEN}`;
const ctrl = new AbortController();
const t = setTimeout(() => ctrl.abort(), 8000);
try {
const resp = await fetch(url.replace(/\/$/, ''), {
method: 'POST',
headers,
signal: ctrl.signal,
body: JSON.stringify({
jsonrpc: '2.0',
id: 1,
method: 'tools/call',
params: { name: tool, arguments: args || {} },
}),
});
if (!resp.ok) return { ok: false, error: `bot ${resp.status}` };
const j = await resp.json();
if (j.error) return { ok: false, error: j.error.message || 'rpc error' };
const data = j.result?.structuredContent ?? j.result?.content ?? j.result;
return { ok: true, data: Array.isArray(data) ? data : (data?.items ?? []) };
} catch (err) {
return { ok: false, error: err?.message || 'fetch failed' };
} finally {
clearTimeout(t);
}
}
function _normalise(items) {
return (items || [])
.map((x) => ({
creator: String(x.claimerWallet || x.creator || x.wallet || ''),
mint: String(x.tokenMint || x.mint || ''),
signature: String(x.txSignature || x.tx_signature || x.signature || ''),
lamports: Number(x.amountLamports || x.lamports || 0),
ts: Number(x.timestamp || x.ts || 0),
}))
.filter((x) => x.creator && x.signature && x.ts > 0);
}
async function _fetchFromRpc(lookbackTs, maxItems) {
try {
const connection = getConnection({ network: 'mainnet' });
const { PublicKey } = await import('@solana/web3.js');
const sigs = await connection.getSignaturesForAddress(new PublicKey(PUMP_PROGRAM), {
limit: 200,
});
const inWindow = sigs.filter((s) => s.blockTime != null && s.blockTime >= lookbackTs && !s.err);
if (!inWindow.length) return [];
const toFetch = inWindow.slice(0, Math.min(30, maxItems * 2));
const settled = await Promise.allSettled(
toFetch.map((s) =>
connection.getParsedTransaction(s.signature, {
maxSupportedTransactionVersion: 1,
commitment: 'confirmed',
}),
),
);
const claims = [];
for (let i = 0; i < settled.length; i++) {
if (settled[i].status !== 'fulfilled' || !settled[i].value) continue;
const claim = _parseClaim(settled[i].value, toFetch[i].signature, toFetch[i].blockTime ?? 0);
if (claim) claims.push(claim);
}
return claims;
} catch {
return [];
}
}
function _parseClaim(tx, signature, ts) {
if (tx?.meta?.err) return null;
const ixs = tx?.transaction?.message?.instructions ?? [];
const accountKeys = tx?.transaction?.message?.accountKeys ?? [];
const pre = tx?.meta?.preBalances ?? [],
post = tx?.meta?.postBalances ?? [];
for (const ix of ixs) {
if (!ix.data || typeof ix.data !== 'string') continue;
const progKey = accountKeys[ix.programIdIndex];
const progId = progKey?.pubkey?.toString?.() ?? String(progKey ?? '');
if (progId !== PUMP_PROGRAM) continue;
let bytes;
try {
bytes = bs58.decode(ix.data);
} catch {
continue;
}
if (bytes.length < 8) continue;
const disc = Buffer.from(bytes.subarray(0, 8)).toString('hex');
if (!CLAIM_DISCS.has(disc)) continue;
const creator = accountKeys[0]?.pubkey?.toString?.() ?? String(accountKeys[0] ?? '');
if (!creator) continue;
let lamports = 0;
for (let i = 0; i < accountKeys.length; i++) {
const delta = (post[i] ?? 0) - (pre[i] ?? 0);
if (delta > lamports) lamports = delta;
}
let mint = '';
if (disc === 'a537817004b3ca28' && bytes.length >= 48) {
try {
mint = bs58.encode(bytes.slice(16, 48));
} catch {}
}
// Fallback: the coin's mint appears in the tx token balances. Skip the
// quote mints (wSOL/USDC) — the snipe target is the coin, not the quote.
if (!mint) mint = _mintFromBalances(tx) || '';
return { creator, mint, signature, lamports, ts };
}
return null;
}
function _mintFromBalances(tx) {
const balances = [
...(tx?.meta?.postTokenBalances ?? []),
...(tx?.meta?.preTokenBalances ?? []),
];
for (const b of balances) {
if (b?.mint && !QUOTE_MINTS.has(b.mint)) return b.mint;
}
return null;
}
/**
* GitHub-attributed fee-PDA withdrawals since `lookbackTs`, each already
* labeled by `pump-claims-attribution.js` and checked for impersonation. One
* entry per `claim_social_fee_pda` transaction on the PumpFees program whose
* claimed platform is GitHub (platform id 2); a claim that resolved to no
* coin at all (see `classifyClaimAttribution`'s `unverified` label) is still
* included; it just has `mint: ''`, matching the base scanner's shape for an
* unresolvable coin.
*
* Exported so `services/pump-claims/backfill.js` can walk further back than
* one page by passing `before` (a signature cursor) and a larger `budget`
* than this live HTTP handler's default; the real-time listener itself
* decodes and attributes with `attributeGithubClaim` directly off its own
* WebSocket feed, never through this RPC-polling path.
* @param {number} lookbackTs
* @param {{budget?: number, sigLimit?: number, before?: string, connection?: object}} [opts]
* @returns {Promise<Array>}
*/
export async function fetchGithubClaimsFromRpc(lookbackTs, opts = {}) {
const { budget = GITHUB_CLAIMS_BUDGET, sigLimit = 200, before, connection: conn } = opts;
try {
const connection = conn || getConnection({ network: 'mainnet' });
const { PublicKey } = await import('@solana/web3.js');
const sigs = await connection.getSignaturesForAddress(new PublicKey(PUMP_FEE_PROGRAM_ID), {
limit: sigLimit,
...(before ? { before } : {}),
});
const inWindow = sigs.filter((s) => s.blockTime != null && s.blockTime >= lookbackTs && !s.err);
if (!inWindow.length) return [];
const out = [];
for (const s of inWindow) {
if (out.length >= budget) break;
const tx = await connection.getParsedTransaction(s.signature, {
maxSupportedTransactionVersion: 1,
commitment: 'confirmed',
});
const logs = tx?.meta?.logMessages;
if (!logs || tx?.meta?.err || !isSocialClaimLog(logs)) continue;
const claim = parseSocialFeeClaim(logs);
if (!claim || claim.socialPlatform !== GITHUB_SOCIAL_PLATFORM) continue;
out.push(await attributeGithubClaim(connection, claim, s.signature, s.blockTime));
}
return out;
} catch {
return [];
}
}
/**
* Attribute and label one decoded GitHub fee-PDA claim. Never throws. Shared
* by this module's own RPC fallback (`fetchGithubClaimsFromRpc`) and by
* `services/pump-claims`, which calls it directly off its live WebSocket feed
* so the real-time listener and the RPC fallback can never disagree on how a
* claim is attributed.
* @param {import('@solana/web3.js').Connection} connection
* @param {{githubUserId:string, socialPlatform:number, socialFeePda:string, recipient:string, amountClaimedRaw:string, quoteMint?:string}} claim
* @param {string} signature
* @param {number} [blockTime]
*/
export async function attributeGithubClaim(connection, claim, signature, blockTime) {
const amountClaimedRaw = BigInt(claim.amountClaimedRaw);
let evidence = null;
let candidateMintCount = 0;
try {
const txLogs = await _logsForSignature(connection, signature);
const sameTx = evidenceForSocialFeePda(parseTransactionDistributions(txLogs), claim.socialFeePda);
if (sameTx.length) {
evidence = sameTx[0];
candidateMintCount = sameTx.length;
} else {
const history = await _pdaHistoryDistributions(connection, claim.socialFeePda, signature, blockTime);
const historyEvidence = evidenceFromPdaHistory(history, claim.socialFeePda, amountClaimedRaw, claim.quoteMint);
if (historyEvidence.length) {
evidence = historyEvidence[0];
candidateMintCount = 1;
} else {
candidateMintCount = new Set(history.map((d) => d.mint)).size;
}
}
} catch {
// Attribution evidence is best-effort; an RPC failure here still leaves
// a real, unattributed claim worth reporting rather than dropping it.
}
const mint = evidence?.mint || '';
const [githubUser, coinCtx] = await Promise.all([
resolveGithubUserById(claim.githubUserId).catch(() => null),
mint ? resolveCoinGithubContext(mint).catch(() => ({})) : Promise.resolve({}),
]);
const classification = classifyClaimAttribution({
evidence,
candidateMintCount,
githubLogin: githubUser?.login || null,
githubRepoOwner: coinCtx.repoOwner || null,
claimerWallet: claim.recipient,
tokenCreatorWallet: coinCtx.creatorWallet || null,
});
const sameNameTokens = mint && coinCtx.tokenName ? await resolveSameNameTokens(coinCtx.tokenName, mint).catch(() => []) : [];
const impersonation = assessImpersonation({
githubUser,
tokenInfo: coinCtx.usdMarketCap != null ? { usdMarketCap: coinCtx.usdMarketCap } : null,
sameNameTokens,
repoInfo: coinCtx.repoCreatedAt ? { createdAt: coinCtx.repoCreatedAt } : null,
});
return {
creator: claim.recipient,
mint,
signature,
lamports: isSolQuote(claim.quoteMint) ? Number(amountClaimedRaw) : 0,
ts: blockTime ?? 0,
source: 'github_fee_claim',
githubUserId: claim.githubUserId,
githubLogin: githubUser?.login || null,
quoteMint: claim.quoteMint || null,
amountRaw: claim.amountClaimedRaw,
attribution: classification,
held: impersonation.suspected,
heldReasons: impersonation.reasons,
};
}
async function _logsForSignature(connection, signature) {
const tx = await connection.getParsedTransaction(signature, {
maxSupportedTransactionVersion: 1,
commitment: 'confirmed',
});
return tx?.meta?.logMessages || [];
}
/**
* Every DistributeCreatorFeesEvent paid to `socialFeePda` since its previous
* claim, oldest work first. Walks the PDA's own signature history backward
* from just before `beforeSignature`, stopping at whichever bound is hit
* first: the previous `claim_social_fee_pda` on this PDA, `HISTORY_MAX_TX`
* transactions, or `HISTORY_MAX_AGE_SEC` of age.
*/
async function _pdaHistoryDistributions(connection, socialFeePda, beforeSignature, claimBlockTime) {
const { PublicKey } = await import('@solana/web3.js');
const sigs = await connection.getSignaturesForAddress(new PublicKey(socialFeePda), {
limit: HISTORY_MAX_TX,
before: beforeSignature,
});
const minTs = (claimBlockTime || Math.floor(Date.now() / 1000)) - HISTORY_MAX_AGE_SEC;
const distributions = [];
for (const s of sigs) {
if (s.err || s.blockTime == null || s.blockTime < minTs) continue;
const logs = await _logsForSignature(connection, s.signature);
if (!logs.length) continue;
if (isSocialClaimLog(logs)) break; // the previous claim on this PDA: stop here
distributions.push(...parseTransactionDistributions(logs));
}
return distributions;
}