Skip to content

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.

feat(pump-claims): real-time listener for GitHub fee-PDA claims, replacing per-request RPC scans

nirholasc2b38c27c114
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 669329c42..606fdadd0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
- **A read-only drift report for every standalone GitHub mirror**: npm run mirrors:drift compares each of the ~105 standalone mirrors in data/standalone-mirrors.json against its monorepo source at the last synced commit (GitHub API, with a README-timestamp fallback when rate-limited), flags any package whose GitHub copy has diverged, and writes the result to tasks/mirror-drift-<date>.json. It never pushes or mutates a mirror; it is the audit step that found the two fixes above. (`/docs/contributing`) `[infra, docs]`
- **Deep links to a specific avatar now actually load that avatar**: @three-ws/walk's ?walk=play&avatar=<id> deep link and the drop-in resume path read the saved avatar preference straight out of storage and never looked at the query string, so sharing a link to a specific avatar silently loaded the stored (or default) one instead. A new deepLinkAvatarId resolver gives the query param precedence and persists it, the same way picking an avatar in the UI does. `[fix, sdk]`
- **GitHub fee-claim channel now attributes withdrawals to a coin, or says plainly it cannot**: A GitHub identity withdrawing pump.fun fees through the claim_social_fee_pda instruction only proves payment to that identity, not which coin paid it: one GitHub fee account can be a shareholder on more than one coin, and its address can be pasted into a copycat coin's metadata. The claims feed and its Telegram channel now classify every such withdrawal with on-chain evidence: a same-transaction distribution to the exact account, or a 90%-dominant distribution history since the previous claim, then a repository-owner or creator-wallet match, down to an honest unresolved or unverified label when nothing proves a coin. A new-GitHub-account-plus-copycat-coin pattern holds the claim for review instead of posting it with a celebratory card. `[feature, security]`
+- **GitHub fee-claim feed now reads from a real-time listener, not just an on-demand RPC scan**: The claims feed's GitHub-attribution path used to walk Solana RPC history fresh on every request, the same cost every time, with nothing persisted in between. services/pump-claims is a standalone process that subscribes to PumpFees program logs directly, decodes and attributes each claim as it happens, and writes it to a new pump_fee_claims table with a watchdog that resubscribes on a stalled connection and gap-fills whatever a drop missed. The claims route now reads that table first and only falls back to the RPC scan when the table has nothing for the requested window, so PUMPFUN_BOT_URL is no longer required for GitHub claims specifically (ordinary wallet claims still use it). `[feature, infra]`
- **Robinhood Chain feed worker now runs the published SDK, not a stale local snapshot**: workers/robinhood-feed depended on robinhood/robinhood-chain-sdk through a file: link, a reference copy that drifts from the standalone robinhood-chain-sdk repo it mirrors. The worker now installs hoodchain from npm like any other dependency, so it always runs the released SDK. Also fixed: seven pointer READMEs staged for duplicate or superseded standalone repos (three-ui, crypto-market-data, crypto-market-data-ts, crypto-data-aggregator, memescope-monday-directory, and one of each duplicate Robinhood Chain repo pair), ready for the owner to push and archive. `[fix, infra]`
- **Standalone GitHub mirrors now stage instead of force-pushing**: scripts/sync-standalone-repos.mjs force-pushed straight to main on every run, which could silently create duplicate repos for the eleven mirrors already renamed on GitHub and bypassed the owner's push-approval rule. data/standalone-mirrors.json is now the single source of truth for which monorepo directory maps to which public repo, read by every exporter (sync, growth satellites, the awesome list, the skill-repo builder) instead of each keeping its own list. The sync script only stages a snapshot under dist/standalone-mirrors/, fixes any stale pre-Apache-2.0 README or LICENSE footer, and prints the push command for the owner; npm run sync:repos:check compares what is staged against each mirror's live tree and reports drift without writing anything. (`/docs/contributing`) `[infra, docs]`
- **three.ws Avatar MCP clamps unbounded tool arguments before they reach generated HTML**: render_avatar's name and camera-orbit arguments flowed into the generated <model-viewer> HTML with no length bound, unlike the model URL, which already rejected oversized or unsafe values. Both are now clamped the same way, closing the one argument path that could still balloon a rendered page or chat payload. `[fix, security, sdk]`
diff --git a/STRUCTURE.md b/STRUCTURE.md
index 226f801f4..fdbde9189 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -425,6 +425,7 @@ surface-map row already covers:
| [services/agent-screen-caster/](services/agent-screen-caster) | Self-hosted Playwright caster: an agent owner runs it on their own host with their agent id + key, and it streams the browser it drives into the agent-screen feed. No managed instance exists (the platform's own casting runs in `workers/agent-screen-pool` and `workers/agent-screen-worker`). Tests: [tests/agent-screen-caster.test.js](tests/agent-screen-caster.test.js) |
| [services/fleet-console/](services/fleet-console) | Health console for an open-source fleet: enumerates a GitHub owner's repositories, probes every deployment URL and npm package they advertise, and scores what each one actually delivers. Ships an HTTP dashboard, a CLI (`scan --attention` exits 1 when anything is broken, so cron can gate on it) and an MCP server over the same snapshot. Not deployed and not meant to be: it runs from a terminal, a cron job, or beside an agent. Tests: [tests/fleet-console.test.js](tests/fleet-console.test.js), [tests/fleet-console-server.test.js](tests/fleet-console-server.test.js) |
| [services/pump-graduations/](services/pump-graduations) | Standalone watcher for pump.fun bonding-curve graduations |
+| [services/pump-claims/](services/pump-claims) | Real-time listener for GitHub social-fee-PDA claims on the PumpFees program: decodes, attributes to a coin, and writes `pump_fee_claims`, so `api/_lib/pump-claims.js` no longer needs `PUMPFUN_BOT_URL` for that path. Docs: [README](services/pump-claims/README.md), [docs/pump-claims-channel.md](docs/pump-claims-channel.md) |
| [services/autopilot/](services/autopilot) | Unattended production repair loop for a dedicated GCP VM: every two hours it runs the deep GCP triage, wakes a headless Claude Code session only for findings it may fix, then gates the commits on `npm test`, pushes, deploys, verifies and rolls traffic back on a failed verification, and reports to the owner over Telegram. Not provisioned: the VM, its report bucket, its push secret, the `provision.sh` its bootstrap names and its two systemd units do not exist yet. Docs: [services/autopilot/README.md](services/autopilot/README.md) |
| [services/home-relay/](services/home-relay) | Terminates the outbound WebSocket a LAN-only Home Assistant dials, and multiplexes allowlisted platform sessions onto it. Holds no database and no credential at rest: a house proves ownership with an HMAC install token, and the Home Assistant authentication happens inside the house and never crosses this process. Not a proxy, on purpose: it carries a fixed list of Home Assistant message types and refuses everything else, including every service domain that would administer the machine rather than a device. Deployed unthrottled with min-instances 1 because it holds sockets between requests. Docs: [docs/home-relay.md](docs/home-relay.md), [docs/home-relay-threat-model.md](docs/home-relay-threat-model.md). Tests: [tests/home-relay-protocol.test.js](tests/home-relay-protocol.test.js), [tests/home-relay-transport.test.js](tests/home-relay-transport.test.js) |
| [home-assistant-integration/](home-assistant-integration) | The Python that runs inside a user's house: a Home Assistant custom integration, distributed through HACS as its own public repository, that dials out to `services/home-relay`. A custom integration rather than a Home Assistant add-on because add-ons only work on OS and Supervised installs while an integration works on all four, and because HACS distributes integrations rather than add-ons. Mints its own system refresh token locally, so no Home Assistant credential ever reaches three.ws, and enforces the relay's allowlist a second time from a generated `allowlist.json` shipped byte-identical from `services/home-relay`. Publishing the public repository is owner-gated. |
diff --git a/api/_lib/migrations/20261015080000_pump_fee_claims.sql b/api/_lib/migrations/20261015080000_pump_fee_claims.sql
new file mode 100644
index 000000000..d780f22c4
--- /dev/null
+++ b/api/_lib/migrations/20261015080000_pump_fee_claims.sql
@@ -0,0 +1,27 @@
+-- pump_fee_claims (work order 506-integrate-07): real-time persisted index of
+-- GitHub social-fee-PDA withdrawals on the PumpFees program, written by the
+-- services/pump-claims listener as they happen on-chain. Lets
+-- api/_lib/pump-claims.js's scanFirstClaims answer from this table instead of
+-- an RPC scan: no indexer, no PUMPFUN_BOT_URL dependency, no per-request
+-- GitHub/pump.fun lookups for a claim the listener already resolved.
+--
+-- Only the fields the read path needs back are promoted to columns; the
+-- listener re-derives headline/explanation text for `label` from the fixed
+-- lookup in pump-claims-attribution.js's attributionInfoForLabel rather than
+-- persisting that text twice.
+
+create table if not exists pump_fee_claims (
+ signature text primary key,
+ mint text,
+ claimer text not null,
+ github_user_id text,
+ lamports bigint not null default 0,
+ label text,
+ held boolean not null default false,
+ slot bigint,
+ created_at timestamptz not null default now()
+);
+
+create index if not exists pump_fee_claims_mint on pump_fee_claims(mint) where mint is not null;
+create index if not exists pump_fee_claims_claimer on pump_fee_claims(claimer);
+create index if not exists pump_fee_claims_created_at on pump_fee_claims(created_at desc);
diff --git a/api/_lib/pump-claims-attribution.js b/api/_lib/pump-claims-attribution.js
index f549dd228..4fed8d00d 100644
--- a/api/_lib/pump-claims-attribution.js
+++ b/api/_lib/pump-claims-attribution.js
@@ -128,6 +128,50 @@ export const ATTRIBUTION_LABELS = Object.freeze({
UNVERIFIED: 'unverified',
});
+// Static headline/explanation text per label, for a caller that only has the
+// label on hand (the persisted `pump_fee_claims` row stores `label`, not the
+// full dynamic explanation `classifyClaimAttribution` builds inline). The two
+// labels whose live explanation includes dynamic detail (an owner login, a
+// candidate count) get a generic version of the same sentence here.
+const LABEL_INFO = Object.freeze({
+ [ATTRIBUTION_LABELS.TRANSACTION_ATTRIBUTED]: {
+ headline: 'TRANSACTION-ATTRIBUTED GITHUB FEE CLAIM',
+ explanation: 'This transaction distributed fees from this exact coin to the claimed GitHub fee account.',
+ },
+ [ATTRIBUTION_LABELS.FEE_HISTORY_ATTRIBUTED]: {
+ headline: 'FEE-HISTORY-ATTRIBUTED GITHUB FEE CLAIM',
+ explanation: 'This coin paid at least 90% of the fees withdrawn, in distributions to this exact GitHub fee account since its previous claim.',
+ },
+ [ATTRIBUTION_LABELS.VERIFIED_REPOSITORY]: {
+ headline: 'VERIFIED GITHUB FEE CLAIM',
+ explanation: 'The claiming GitHub identity matches the repository owner linked in the token metadata.',
+ },
+ [ATTRIBUTION_LABELS.VERIFIED_CREATOR_WALLET]: {
+ headline: 'CREATOR-WALLET GITHUB FEE CLAIM',
+ explanation: 'The claim recipient matches the token creator wallet. No repository-owner match was established.',
+ },
+ [ATTRIBUTION_LABELS.IDENTITY_MISMATCH]: {
+ headline: 'IDENTITY MISMATCH, GITHUB FEE WITHDRAWAL',
+ explanation: 'The claiming GitHub account is not the owner linked in the token metadata.',
+ },
+ [ATTRIBUTION_LABELS.UNRESOLVED_POOLED]: {
+ headline: 'UNRESOLVED POOLED GITHUB FEE WITHDRAWAL',
+ explanation: 'One shared fee account is linked to more than one coin. This withdrawal cannot be assigned to one CA.',
+ },
+ [ATTRIBUTION_LABELS.UNVERIFIED]: {
+ headline: 'UNVERIFIED GITHUB FEE WITHDRAWAL',
+ explanation: 'A real fee withdrawal occurred, but it does not prove this GitHub user created or endorses the coin.',
+ },
+});
+
+/**
+ * Headline/explanation text for a label alone, no live context required.
+ * @param {string} label one of ATTRIBUTION_LABELS
+ */
+export function attributionInfoForLabel(label) {
+ return LABEL_INFO[label] || { headline: '', explanation: '' };
+}
+
/**
* Classify only the relationship a claim can actually prove. A successful
* GitHub-PDA withdrawal proves a payment to a GitHub identity; it does not by
diff --git a/api/_lib/pump-claims-push.js b/api/_lib/pump-claims-push.js
index 1a35a8dca..cd1749048 100644
--- a/api/_lib/pump-claims-push.js
+++ b/api/_lib/pump-claims-push.js
@@ -27,7 +27,7 @@
// `lastTs` bounds the query window so the ring never has to.
//
// `githubSeen` is a second, independent dedupe for GitHub fee-PDA claims
-// (api/_lib/pump-claims.js's `_fetchGithubClaimsFromRpc`), keyed by GitHub
+// (api/_lib/pump-claims.js's `fetchGithubClaimsFromRpc`), keyed by GitHub
// user id plus mint rather than by signature: the same GitHub identity can
// submit more than one claim_social_fee_pda transaction against the same coin
// (a sweep followed by a claim, or simply claiming again later), and each has
diff --git a/api/_lib/pump-claims.js b/api/_lib/pump-claims.js
index c28378191..0694392b4 100644
--- a/api/_lib/pump-claims.js
+++ b/api/_lib/pump-claims.js
@@ -14,16 +14,22 @@
* 2. Direct RPC scan of the pump program's recent signatures — always works,
* no indexer required.
*
- * A separate GitHub-fee-claim path (`_fetchGithubClaimsFromRpc`) always runs
- * alongside whichever source above is active: it scans the PumpFees program
- * (`PUMP_FEE_PROGRAM_ID`) for `claim_social_fee_pda` withdrawals, 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 before it is merged into the result.
+ * 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 {
@@ -31,7 +37,13 @@ import {
parseSocialFeeClaim,
parseTransactionDistributions,
} from './pump-events.js';
-import { evidenceForSocialFeePda, evidenceFromPdaHistory, classifyClaimAttribution, assessImpersonation } from './pump-claims-attribution.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;
@@ -45,8 +57,10 @@ const QUOTE_MINTS = new Set([
'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
]);
-// GitHub platform id in SharingConfig.shareholder.platform (claim_social_fee_pda's `platform` byte).
-const GITHUB_SOCIAL_PLATFORM = 2;
+// 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
@@ -75,11 +89,78 @@ export async function scanFirstClaims({ sinceTs, limit }) {
process.env.PUMPFUN_BOT_URL
? _fetchFromBot(lookbackTs, lim * LOOKBACK_MULT)
: _fetchFromRpc(lookbackTs, lim * LOOKBACK_MULT),
- _fetchGithubClaimsFromRpc(lookbackTs),
+ _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);
@@ -222,22 +303,31 @@ function _mintFromBalances(tx) {
* 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>}
*/
-async function _fetchGithubClaimsFromRpc(lookbackTs) {
+export async function fetchGithubClaimsFromRpc(lookbackTs, opts = {}) {
+ const { budget = GITHUB_CLAIMS_BUDGET, sigLimit = 200, before, connection: conn } = opts;
try {
- const connection = getConnection({ network: 'mainnet' });
+ 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: 200,
+ 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 >= GITHUB_CLAIMS_BUDGET) break;
+ if (out.length >= budget) break;
const tx = await connection.getParsedTransaction(s.signature, {
maxSupportedTransactionVersion: 1,
commitment: 'confirmed',
@@ -246,7 +336,7 @@ async function _fetchGithubClaimsFromRpc(lookbackTs) {
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));
+ out.push(await attributeGithubClaim(connection, claim, s.signature, s.blockTime));
}
return out;
} catch {
@@ -254,8 +344,18 @@ async function _fetchGithubClaimsFromRpc(lookbackTs) {
}
}
-/** Attribute and label one decoded GitHub fee-PDA claim. Never throws. */
-async function _attributeGithubClaim(connection, claim, signature, blockTime) {
+/**
+ * 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;
diff --git a/data/changelog.json b/data/changelog.json
index 6e1841601..b8c797074 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,15 @@
{
"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security, desktop (desktop entries become the desktop app's release notes). `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-10-14",
+ "title": "GitHub fee-claim feed now reads from a real-time listener, not just an on-demand RPC scan",
+ "summary": "The claims feed's GitHub-attribution path used to walk Solana RPC history fresh on every request, the same cost every time, with nothing persisted in between. services/pump-claims is a standalone process that subscribes to PumpFees program logs directly, decodes and attributes each claim as it happens, and writes it to a new pump_fee_claims table with a watchdog that resubscribes on a stalled connection and gap-fills whatever a drop missed. The claims route now reads that table first and only falls back to the RPC scan when the table has nothing for the requested window, so PUMPFUN_BOT_URL is no longer required for GitHub claims specifically (ordinary wallet claims still use it).",
+ "tags": [
+ "feature",
+ "infra"
+ ]
+ },
{
"date": "2026-10-14",
"title": "GitHub fee-claim channel now attributes withdrawals to a coin, or says plainly it cannot",
diff --git a/docs/pump-claims-channel.md b/docs/pump-claims-channel.md
index 841c14d5f..d25a3ac48 100644
--- a/docs/pump-claims-channel.md
+++ b/docs/pump-claims-channel.md
@@ -75,12 +75,17 @@ pump.fun program activity
│ └── direct Solana RPC scan (fallback, see "Known limits")
│
└── GitHub fee-PDA claims (PumpFees program, claim_social_fee_pda)
+ │
+ ├── services/pump-claims (real-time listener, see below)
+ │ └── writes pump_fee_claims
│
▼
_fetchGithubClaimsFromRpc() api/_lib/pump-claims.js
- ├── direct Solana RPC scan (always runs; no indexer dependency)
- ├── same-tx / fee-history evidence pump-claims-attribution.js
- └── GitHub user + coin metadata lookups pump-claims-github.js
+ ├── pump_fee_claims table (preferred; populated by the listener)
+ └── direct Solana RPC scan (fallback, when the table has nothing
+ for the requested window; same evidence rules either way)
+ ├── same-tx / fee-history evidence pump-claims-attribution.js
+ └── GitHub user + coin metadata lookups pump-claims-github.js
│
▼
pushTelegramLane() api/_lib/pump-claims-push.js
@@ -96,13 +101,32 @@ GET /api/cron/pump-claims-push every 5 minutes (Cloud Scheduler)
The same scanner also backs `GET /api/pump/first-claims` and the
`pumpfun_first_claims` MCP tool, so the channel and the API never disagree.
+## The real-time listener: `services/pump-claims`
+
+GitHub fee-PDA claims no longer depend on an RPC scan at read time, or on
+`PUMPFUN_BOT_URL`, which only ever covered ordinary wallet claims. A standalone
+long-lived process, [services/pump-claims](../services/pump-claims), holds a
+Solana log subscription on the PumpFees program, decodes and attributes each
+`claim_social_fee_pda` as it lands, and writes it into `pump_fee_claims`
+(migration
+[20261015080000_pump_fee_claims.sql](../api/_lib/migrations/20261015080000_pump_fee_claims.sql)).
+
+`scanFirstClaims`'s GitHub path now reads that table first and only falls back
+to the direct RPC scan described below when the table has nothing for the
+requested window (a fresh deployment before the listener's backfill has run,
+or the listener being down). Both paths run the exact same attribution rules,
+so which one answered is invisible to a caller except for a `source` field
+logged server-side. See the service's own
+[README](../services/pump-claims/README.md) for how it runs, reconnects, and
+backfills.
+
## Configuration
| Variable | Required | Purpose |
|---|---|---|
| `TELEGRAM_BOT_TOKEN` | yes | Bot that posts. Create via [@BotFather](https://t.me/BotFather). |
| `TELEGRAM_PUMP_CLAIMS_CHAT_ID` | yes | `@pumpfunclaims`, or the `-100…` numeric id. |
-| `PUMPFUN_BOT_URL` | yes in practice | pump.fun claims indexer. Without it the scan returns nothing (see below). |
+| `PUMPFUN_BOT_URL` | optional | pump.fun claims indexer for **ordinary wallet claims** only. Without it, wallet claims return nothing (see below); GitHub fee-PDA claims are unaffected, served by `services/pump-claims` and its RPC fallback regardless. |
| `PUMPFUN_BOT_TOKEN` | optional | Bearer token for the indexer, when it requires one. |
The bot **must be an administrator of the channel** with permission to post.
diff --git a/package-lock.json b/package-lock.json
index b35efa2ce..0c0a38170 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -19,6 +19,7 @@
"mcp-server",
"multiplayer",
"services/liquidation-collector",
+ "services/pump-claims",
"packages/avatar-schema",
"packages/mcp-policy",
"packages/avatar-cli",
@@ -29175,6 +29176,10 @@
"resolved": "packages/provenance-mcp",
"link": true
},
+ "node_modules/@three-ws/pump-claims": {
+ "resolved": "services/pump-claims",
+ "link": true
+ },
"node_modules/@three-ws/pumpfun-mcp": {
"resolved": "packages/pumpfun-mcp",
"link": true
@@ -58227,6 +58232,20 @@
"node": ">=20"
}
},
+ "services/pump-claims": {
+ "name": "@three-ws/pump-claims",
+ "version": "1.0.0",
+ "dependencies": {
+ "@neondatabase/serverless": "^1.1.0",
+ "@nirholas/pump-sdk": "^1.0.0",
+ "@solana/web3.js": "^1.99.0",
+ "bs58": "^6.0.0",
+ "ws": "^8.21.0"
+ },
+ "engines": {
+ "node": ">=20"
+ }
+ },
"solana-agent-sdk": {
"name": "@three-ws/solana-agent",
"version": "0.2.2",
diff --git a/package.json b/package.json
index ad1d04df0..5cce70955 100644
--- a/package.json
+++ b/package.json
@@ -76,6 +76,7 @@
"mcp-server",
"multiplayer",
"services/liquidation-collector",
+ "services/pump-claims",
"packages/avatar-schema",
"packages/mcp-policy",
"packages/avatar-cli",
diff --git a/prompts/finish/_context/production-100-OWNER-ACTIONS.md b/prompts/finish/_context/production-100-OWNER-ACTIONS.md
index 0e5ce26b3..b909720f7 100644
--- a/prompts/finish/_context/production-100-OWNER-ACTIONS.md
+++ b/prompts/finish/_context/production-100-OWNER-ACTIONS.md
@@ -9,7 +9,7 @@ it and, if that unblocks a work order, say which one in the owning pack's `produ
Rows carry the date they were added so staleness is visible. Re-verify a row before acting
on it; some resolve themselves as other work lands.
-## Open rows (2026-10-14 (order 503-integrate-04 close-out): row 61 added for pushing and archiving 7 retired repos (`three-ui`, `crypto-market-data`, `crypto-market-data-ts`, `crypto-data-aggregator`, `memescope-monday-directory`, `robinhood-chain-alert-bot`, `robinhood-chain-trading-bot`); 2026-10-14 (order 501-integrate-02 close-out): row 60 added for approving the `@nirholas/pump-sdk` bump to `^1.36.0` in `packages/avatar-agent-mcp/package.json`; 2026-10-14 (order 500-integrate-01 close-out): row 59 added for pushing every staged standalone mirror now that sync-standalone-repos.mjs stages instead of force-pushing; 2026-10-14 (order 404 second pass): correcting the 2026-10-11 entry below, the `x-mention-reply.js` `chainFor()` fix was not actually carried by merge commit `d77b89178`; checking out that commit's own `evolve` parent showed `chainFor()` still importing `resolveAgentBrain`/`modelChain` (the tool-calling chain shape, no `buildBody`), the exact bug row 34 flagged, still live. The real fix is this session's `evolve` commit `7ba9f9749` ("fix(x-mentions): give public replies a buildBody-shaped provider chain"), switching `chainFor()` to `llm.js`'s own `providerChain()` plus `loadOwnerGrokKey`/`agentDefaultModel`/`MODEL_CATALOG`; re-verified now genuinely passing with the same command the earlier entry cited (`RUN_LLM_TESTS=1 npx vitest run tests/x-mention-reply.llm.test.js`, 16/16 `source: 'model'`, no `buildBody` TypeError). Row 34's premise (the `evolve`/`main` divergence) is still correctly closed, just not for the reason originally stated; no row reopened. Order 060's matching status paragraph corrected the same way. 2026-10-13 (order 095 close-out): row 58 added for the Home Assistant integration's standalone repository, release, and the hacs/default and home-assistant/brands pull requests; 2026-10-13 (order 094 close-out): row 57 added for the WordPress.org/Framer/Webflow account signups and submissions for the three <agent-3d> site-builder embeds; 2026-10-13 (order 092 close-out): row 55 added for the VRoid Hub avatar-import OAuth app registration and migration; 2026-10-13 (triage-lane sweep, fifth pass): row 53 added for the Birdeye compute-units cap behind `pump-price-history-upstreams-502` (confirmed live, a billing/plan decision only); row 1 re-measured, deploy gap still 0 against the pushed `threews/main` ref and the 8 page-404/wrong-canonical findings this pass confirmed as deploy lag; row 47 re-measured, still a no-op (`COINGECKO_API_KEY` still absent); the previously-unclassified `/dist-lib/agent-3d.js` and `/agent-3d/latest/agent-3d.js` 500s ("Response size was too large") are the same bug row 48 already tracks, fixed on `evolve` in `f939d5ef1`, confirmed still green (`npx vitest run tests/lib-bundle-size.test.js tests/whisper-stt.test.js`, 16/16) and awaiting the pending deploy, no new row; 2026-10-13 (triage-lane sweep, fourth pass): row 1 re-measured, deploy gap still 0 against the pushed `threews/main` ref; the `ccv-ai-providers-unavailable-503` finding's Groq/OpenRouter/Vertex angles confirmed already covered by rows 6 and 20, no new row added; 2026-10-13 (order 087 close-out): row 51 added for the LiveKit and Pipecat avatar integrations, both built and verified end to end this session, with the PyPI publishes and the two upstream pull requests left as owner actions; 2026-10-13 (order 085 close-out): row 50 added for publishing the CC0 bulk animation library to production, and the Adobe Mixamo permission letter draft is ready to send as owner order 938; 2026-10-12 (order 084 close-out): row 49 added for the Tripo signed webhook's three linked steps (apply the `forge_webhook_deliveries` migration, set `TRIPO_WEBHOOK_SECRET`, register the dashboard webhook), not an active bug since the secret is unset and polling answers every Tripo job today; 2026-10-12 18:10 UTC (triage-lane sweep, third pass): row 48 added for the dist-lib CDN embed size fix (previously-unclassified `/dist-lib/agent-3d.js` 500s, root-caused and fixed on `evolve`, pure code change awaiting the next deploy); 2026-10-12 17:54 UTC (triage-lane sweep, second pass): row 1's same-day "11 behind" figure corrected to the real deploy gap of 0 (querying `/api/version` live, not `/api/healthz`, which has no commit field), row 47 added for CoinGecko's keyless tier being rate-limited (`COINGECKO_API_KEY` already absent from the service, so the finding's own pre-approved env fix is a no-op); 2026-10-12 (triage-lane sweep): row 1 re-measured against the canonical `threews` remote, 11 commits behind `main` (down from 28, local stale ref corrected), row 45 added for the HF image-provider (fal-ai/nscale) credit exhaustion, a separate pool from row 6; 2026-10-11 (best3d order 070 close-out): rows 43 and 44 added for the `model-partcrafter` and `model-holopart` first deploys; 2026-10-11 (triage-lane sweep): row 42 added for the MCP client-sessions nullable-column migration, an active production bug; row 1 re-measured, 28 commits behind `main` (up from 5); 2026-10-11 (best3d order 069 close-out): rows 40 and 41 added for the `model-rig-nonhuman` and `model-anigen` first deploys; 2026-10-11 (best3d order 068 close-out): row 39 added for the `model-pixal3d` first deploy; 2026-10-11 (best3d order 067 retry): row 38 added for the `model-trellis2` first deploy; 2026-10-11 (order 404 close-out): row 34 deleted, its premise cleared by merge commit `d77b89178` (the `evolve`/`main` reconciliation) which also carried the `x-mention-reply.js` `chainFor()` fix row 34 called out, verified live with `RUN_LLM_TESTS=1 npx vitest run tests/x-mention-reply.llm.test.js` (16/16 `source: 'model'`, no `buildBody` TypeError); 2026-10-11 (scout lane): row 36 added for the Cloudflare R2 flapping degraded/down pattern; 2026-10-11 (even later): row 24 re-measured again after order 400's ring-leak-scan tiering/lock fix shipped on `evolve`; 2026-10-11 (later): row 35 added for the agent mention-policy migration; 2026-10-11 04:16 UTC: rows 1 and 24 re-measured by the deep triage sweep; row 34 added for the evolve/main branch divergence; 2026-10-10: row 33 added for the xAI MCP e2e key; rows 1, 19 and 24 re-measured by the triage sweep; 2026-10-09: rows 1, 2 and 24 re-measured by the triage sweep, row 31 added for the GPU worker redeploy and row 32 for database table retention; row 30 added for the Grok Bot CLI setup rerun; 2026-10-08: row 26 added for the coin-gated MCP catalog regeneration; rows 1 and 2 re-measured by the triage sweep, row 24 added for the paid Solana RPC credits, row 25 added for the MCP connector OAuth deploy; 2026-09-30: row 23 added for the $THREE receiver wallets; 2026-09-29: row 19 re-measured after the agent-sniper deploy; 2026-09-09: row 19 added, and row 1 corrected because its outage premise no longer holds; rows 1, 2, 3, 9, 13, 15 and 16 re-measured 2026-09-04; the former row 18 was cleared that day and its number is not reused; the 2026-09-02 and 2026-08-09 passes are folded in below)
+## Open rows (2026-10-14 (order 506-integrate-07 close-out): row 62 added for deploying the new `services/pump-claims` Cloud Run service and applying its `pump_fee_claims` migration to production; 2026-10-14 (order 503-integrate-04 close-out): row 61 added for pushing and archiving 7 retired repos (`three-ui`, `crypto-market-data`, `crypto-market-data-ts`, `crypto-data-aggregator`, `memescope-monday-directory`, `robinhood-chain-alert-bot`, `robinhood-chain-trading-bot`); 2026-10-14 (order 501-integrate-02 close-out): row 60 added for approving the `@nirholas/pump-sdk` bump to `^1.36.0` in `packages/avatar-agent-mcp/package.json`; 2026-10-14 (order 500-integrate-01 close-out): row 59 added for pushing every staged standalone mirror now that sync-standalone-repos.mjs stages instead of force-pushing; 2026-10-14 (order 404 second pass): correcting the 2026-10-11 entry below, the `x-mention-reply.js` `chainFor()` fix was not actually carried by merge commit `d77b89178`; checking out that commit's own `evolve` parent showed `chainFor()` still importing `resolveAgentBrain`/`modelChain` (the tool-calling chain shape, no `buildBody`), the exact bug row 34 flagged, still live. The real fix is this session's `evolve` commit `7ba9f9749` ("fix(x-mentions): give public replies a buildBody-shaped provider chain"), switching `chainFor()` to `llm.js`'s own `providerChain()` plus `loadOwnerGrokKey`/`agentDefaultModel`/`MODEL_CATALOG`; re-verified now genuinely passing with the same command the earlier entry cited (`RUN_LLM_TESTS=1 npx vitest run tests/x-mention-reply.llm.test.js`, 16/16 `source: 'model'`, no `buildBody` TypeError). Row 34's premise (the `evolve`/`main` divergence) is still correctly closed, just not for the reason originally stated; no row reopened. Order 060's matching status paragraph corrected the same way. 2026-10-13 (order 095 close-out): row 58 added for the Home Assistant integration's standalone repository, release, and the hacs/default and home-assistant/brands pull requests; 2026-10-13 (order 094 close-out): row 57 added for the WordPress.org/Framer/Webflow account signups and submissions for the three <agent-3d> site-builder embeds; 2026-10-13 (order 092 close-out): row 55 added for the VRoid Hub avatar-import OAuth app registration and migration; 2026-10-13 (triage-lane sweep, fifth pass): row 53 added for the Birdeye compute-units cap behind `pump-price-history-upstreams-502` (confirmed live, a billing/plan decision only); row 1 re-measured, deploy gap still 0 against the pushed `threews/main` ref and the 8 page-404/wrong-canonical findings this pass confirmed as deploy lag; row 47 re-measured, still a no-op (`COINGECKO_API_KEY` still absent); the previously-unclassified `/dist-lib/agent-3d.js` and `/agent-3d/latest/agent-3d.js` 500s ("Response size was too large") are the same bug row 48 already tracks, fixed on `evolve` in `f939d5ef1`, confirmed still green (`npx vitest run tests/lib-bundle-size.test.js tests/whisper-stt.test.js`, 16/16) and awaiting the pending deploy, no new row; 2026-10-13 (triage-lane sweep, fourth pass): row 1 re-measured, deploy gap still 0 against the pushed `threews/main` ref; the `ccv-ai-providers-unavailable-503` finding's Groq/OpenRouter/Vertex angles confirmed already covered by rows 6 and 20, no new row added; 2026-10-13 (order 087 close-out): row 51 added for the LiveKit and Pipecat avatar integrations, both built and verified end to end this session, with the PyPI publishes and the two upstream pull requests left as owner actions; 2026-10-13 (order 085 close-out): row 50 added for publishing the CC0 bulk animation library to production, and the Adobe Mixamo permission letter draft is ready to send as owner order 938; 2026-10-12 (order 084 close-out): row 49 added for the Tripo signed webhook's three linked steps (apply the `forge_webhook_deliveries` migration, set `TRIPO_WEBHOOK_SECRET`, register the dashboard webhook), not an active bug since the secret is unset and polling answers every Tripo job today; 2026-10-12 18:10 UTC (triage-lane sweep, third pass): row 48 added for the dist-lib CDN embed size fix (previously-unclassified `/dist-lib/agent-3d.js` 500s, root-caused and fixed on `evolve`, pure code change awaiting the next deploy); 2026-10-12 17:54 UTC (triage-lane sweep, second pass): row 1's same-day "11 behind" figure corrected to the real deploy gap of 0 (querying `/api/version` live, not `/api/healthz`, which has no commit field), row 47 added for CoinGecko's keyless tier being rate-limited (`COINGECKO_API_KEY` already absent from the service, so the finding's own pre-approved env fix is a no-op); 2026-10-12 (triage-lane sweep): row 1 re-measured against the canonical `threews` remote, 11 commits behind `main` (down from 28, local stale ref corrected), row 45 added for the HF image-provider (fal-ai/nscale) credit exhaustion, a separate pool from row 6; 2026-10-11 (best3d order 070 close-out): rows 43 and 44 added for the `model-partcrafter` and `model-holopart` first deploys; 2026-10-11 (triage-lane sweep): row 42 added for the MCP client-sessions nullable-column migration, an active production bug; row 1 re-measured, 28 commits behind `main` (up from 5); 2026-10-11 (best3d order 069 close-out): rows 40 and 41 added for the `model-rig-nonhuman` and `model-anigen` first deploys; 2026-10-11 (best3d order 068 close-out): row 39 added for the `model-pixal3d` first deploy; 2026-10-11 (best3d order 067 retry): row 38 added for the `model-trellis2` first deploy; 2026-10-11 (order 404 close-out): row 34 deleted, its premise cleared by merge commit `d77b89178` (the `evolve`/`main` reconciliation) which also carried the `x-mention-reply.js` `chainFor()` fix row 34 called out, verified live with `RUN_LLM_TESTS=1 npx vitest run tests/x-mention-reply.llm.test.js` (16/16 `source: 'model'`, no `buildBody` TypeError); 2026-10-11 (scout lane): row 36 added for the Cloudflare R2 flapping degraded/down pattern; 2026-10-11 (even later): row 24 re-measured again after order 400's ring-leak-scan tiering/lock fix shipped on `evolve`; 2026-10-11 (later): row 35 added for the agent mention-policy migration; 2026-10-11 04:16 UTC: rows 1 and 24 re-measured by the deep triage sweep; row 34 added for the evolve/main branch divergence; 2026-10-10: row 33 added for the xAI MCP e2e key; rows 1, 19 and 24 re-measured by the triage sweep; 2026-10-09: rows 1, 2 and 24 re-measured by the triage sweep, row 31 added for the GPU worker redeploy and row 32 for database table retention; row 30 added for the Grok Bot CLI setup rerun; 2026-10-08: row 26 added for the coin-gated MCP catalog regeneration; rows 1 and 2 re-measured by the triage sweep, row 24 added for the paid Solana RPC credits, row 25 added for the MCP connector OAuth deploy; 2026-09-30: row 23 added for the $THREE receiver wallets; 2026-09-29: row 19 re-measured after the agent-sniper deploy; 2026-09-09: row 19 added, and row 1 corrected because its outage premise no longer holds; rows 1, 2, 3, 9, 13, 15 and 16 re-measured 2026-09-04; the former row 18 was cleared that day and its number is not reused; the 2026-09-02 and 2026-08-09 passes are folded in below)
| # | Action | Size | Unblocks | Detail lives in |
|---|---|---|---|---|
@@ -75,6 +75,7 @@ on it; some resolve themselves as other work lands.
| 58 | **Create `github.com/nirholas/three-ws-home-assistant` from the exported tree, confirm its two CI workflows pass, cut a `v1.0.1` release, then open the `hacs/default` and `home-assistant/brands` pull requests** (added 2026-10-13 by the evolve loop closing out order 095-partners-12). `home-assistant-integration/` now validates clean: `manifest.json`'s broken `documentation` link fixed to the live `/docs/home-relay`, `version` bumped to `1.0.1`, `hacs.json`'s minimum Home Assistant version corrected to `2024.12.0` (the first release bundling the `aiohttp.ClientWSTimeout` the integration's relay client uses, confirmed against HA's own `package_constraints.txt` history), and real local brand icons added at `custom_components/three_ws/brand/{icon,icon@2x,dark_icon,dark_icon@2x}.png`. `node scripts/export-hacs-repo.mjs` builds the exact standalone-repository tree (the integration, README, LICENSE, `hacs.json`, and the two validation workflows, which live only in that exported tree since this monorepo runs no GitHub Actions of its own) under `dist/hacs-export/`. Verified this session with the real tools HACS's own CI runs: the real `ghcr.io/home-assistant/hassfest` Docker image against the exported tree ("Invalid integrations: 0"), the real upstream HACS schema/brand/readme validators from `hacs/integration`'s own source (all pass; the GitHub-settings-dependent checks are architecturally impossible to run before the repository exists), and a full real end-to-end install: a real `ghcr.io/home-assistant/home-assistant:stable` container onboarded via its own REST API, paired through the real config flow against a real `services/home-relay` server, 18 real entities read back, and a confirmed auto-reconnect after a relay restart. Full step-by-step with exact settings and PR text for both targets: [`marketing/growth/submissions/home-assistant.md`](../../marketing/growth/submissions/home-assistant.md). Summary: (a) push `dist/hacs-export/` (rebuild with `node scripts/export-hacs-repo.mjs` first) to a new public personal repository at `github.com/nirholas/three-ws-home-assistant`, set its description/topics/issues, confirm `hassfest.yml` and `hacs.yml` both pass on `main`, and cut a `v1.0.1` release; (b) add it to HACS as a custom repository in a real Home Assistant instance and confirm it installs; (c) fork `hacs/default`, add `"nirholas/three-ws-home-assistant"` to the `integration` file between `nimroddolev/chime_tts` and `nishithdev/wled-taskmap`, and open the PR with the title/description already written in the submission file; (d) fork `home-assistant/brands`, copy the four PNGs already sitting in this repository into `custom_integrations/three_ws/`, and open that PR with its own title/description. | one repository creation + one release cut + two pull requests | Lists three.ws's Home Assistant integration in the HACS default store and gives it an official brand icon | [095-partners-12-home-assistant-hacs.md](../095-partners-12-home-assistant-hacs.md), [marketing/growth/submissions/home-assistant.md](../../marketing/growth/submissions/home-assistant.md) |
| 59 | **Push every staged standalone mirror** (added 2026-10-14 by the evolve loop closing out order 500-integrate-01). `npm run sync:repos` now stages a one-commit snapshot per mirror under `dist/standalone-mirrors/<repo>/` instead of force-pushing, reading `data/standalone-mirrors.json` as the single source of truth for which monorepo directory maps to which public repo (this also fixes the eleven mirrors already renamed on GitHub, so no duplicate repo gets created for them). It never calls `gh`, never pushes, and makes no network writes; the script's own output after staging is the exact push line for each mirror, in the form `git -C dist/standalone-mirrors/<repo> push --force https://github.com/nirholas/<repo>.git HEAD:main`. Run `npm run sync:repos` (optionally `-- --only <repo>` for a single mirror), review a staged tree if you want to, then run the printed push command for each mirror you want to publish. `npm run sync:repos:check` reports drift against each mirror's live tree without writing anything, useful to see which mirrors are stale before deciding which pushes to run. | one `npm run sync:repos` run plus N `git push --force` commands (one per mirror, printed by the tool) | Publishes the Apache-2.0 license-footer fix and the renamed-mirror corrections to every public GitHub mirror | [500-integrate-01-mirror-manifest.md](../500-integrate-01-mirror-manifest.md) (retired this session; see `_context/integrate-PROGRESS.md`), [data/standalone-mirrors.json](../../data/standalone-mirrors.json) |
| 60 | **Approve bumping `@nirholas/pump-sdk` from `^1.30.0` to `^1.36.0`** in `packages/avatar-agent-mcp/package.json` (added 2026-10-14 by the evolve loop closing out order 501-integrate-02). The `avatar-agent-mcp` GitHub mirror moved to this range on its own; `npm run mirrors:drift` flagged the drift. This names another project's SDK, so the commit gate applies: the edit is made and verified (`npm install`, `npm ls @nirholas/pump-sdk` → `1.36.0`, `npm test` → 26/26 green) but held staged, uncommitted, in the worktree rather than committed. The order's own text also named a "2.x move with holder-reward launches"; that claim is stale, the real current GitHub range is `^1.36.0` (still 1.x) and no holder-reward code exists in the mirror (checked, no match for `holder.reward`/`holder_reward`/`holderReward`). To approve: review the staged diff (`git diff packages/avatar-agent-mcp/package.json package-lock.json`), then `git add packages/avatar-agent-mcp/package.json package-lock.json && git commit`. | one `git add` + `git commit` | Keeps `packages/avatar-agent-mcp` on the pump-sdk range its own GitHub mirror and `npm test` already validate | [501-integrate-02-mirror-drift-report.md](../501-integrate-02-mirror-drift-report.md) (retired this session; see `_context/integrate-PROGRESS.md`) |
+| 62 | **Deploy `services/pump-claims` (new Cloud Run service) and apply its migration** (added 2026-10-14 by the evolve loop closing out order 506-integrate-07). The service is a standalone real-time listener: it subscribes to PumpFees program logs, decodes and attributes every GitHub social-fee-PDA claim (`claim_social_fee_pda`), and writes it to a new `pump_fee_claims` table, so `api/_lib/pump-claims.js`'s claims feed can read a persisted real-time source instead of re-scanning RPC history on every request (it still falls back to the RPC scan whenever the table has nothing for the requested window). Built and verified this session: 21/21 `node --test` passing (decode, attribution, idempotent insert, reconnect/gap-fill, a 429-backoff helper for the free RPC lane), a Docker image built AND run (not just built) confirming every transitively-imported module resolves, a new transitive-import-aware vitest guard (`tests/pump-claims-worker-image.test.js`) so a future drift fails the build instead of crashing the container on boot, and the actual migration file applied and verified with the real `npm run db:migrate -- --apply --file 20261015080000_pump_fee_claims.sql` / `npm run db:check` tooling against a local throwaway Postgres (`scripts/use-local-neon.mjs`), never against production. Two things only the owner can do: (a) apply the migration to the real production database, exactly `npm run db:migrate -- --apply --file 20261015080000_pump_fee_claims.sql` (read `npm run db:status` first; this applies immediately, no dry run, and the shared worktree may have other agents' unrelated pending migrations queued, so review the full pending list before running); (b) deploy the service, exactly `gcloud builds submit --config services/pump-claims/cloudbuild.yaml .` from the repo root (pinned to the `three-ws-build@`/`three-ws@` service accounts, `--no-cpu-throttling --min-instances=1`, defaults `SOLANA_RPC_URL` to the free `api.mainnet-beta.solana.com` lane, one of only two lanes measured to serve `logsSubscribe`; see `docs/ops/solana-rpc-lanes.md`). After both land, run `node services/pump-claims/backfill.js --days=7` once (or let the live listener's cold-start gap-fill do it) so the table isn't empty on day one, then confirm with `select count(*) from pump_fee_claims;`. One real finding from this session worth knowing before that backfill runs: the PumpFees program is extremely busy overall (measured ~500 signatures/second across ALL its traffic, not just GitHub claims), so `backfill.js`'s `MAX_SIGNATURES_SCANNED` safety cap (20,000) will be reached within roughly the most recent minute of chain activity regardless of the `--days` flag; a true 7-day backfill of this specific claim type is not reachable by walking raw signature history on any RPC lane and would need a dedicated indexer if ever required, the live listener (real-time, no scan) is the real source of ongoing coverage. | one migration apply + one `gcloud builds submit` + one backfill run | Makes the claims feed's GitHub-attribution path real-time and self-hosted, ending its implicit dependence on RPC-scan freshness per request | [506-integrate-07-pump-claims-listener.md](../506-integrate-07-pump-claims-listener.md), [services/pump-claims/README.md](../../services/pump-claims/README.md) |
| 61 | **Push and archive 7 retired repos** (added 2026-10-14 by the evolve loop closing out order 503-integrate-04). `data/retired-repos.json` lists `three-ui`, `crypto-market-data`, `crypto-market-data-ts`, and `crypto-data-aggregator` (all superseded by the `/markets` page or `src/` in this monorepo), `memescope-monday-directory` (duplicate of `memescope-monday`), and one repo from each of the two Robinhood Chain duplicate pairs (`robinhood-chain-alert-bot`, duplicate of `robinhood-chain-alerts`; `robinhood-chain-trading-bot`, duplicate of `robinhood-chain-traders`). `npm run retire:repos` staged a one-commit pointer README under `dist/retired-repos/<repo>/` for each, explaining the retirement and linking to the replacement; it never calls `gh` and never pushes. To approve, run these 14 commands (7 pushes, 7 archives): `git -C dist/retired-repos/three-ui push --force https://github.com/nirholas/three-ui.git HEAD:main && gh repo archive nirholas/three-ui --yes`, `git -C dist/retired-repos/crypto-market-data push --force https://github.com/nirholas/crypto-market-data.git HEAD:main && gh repo archive nirholas/crypto-market-data --yes`, `git -C dist/retired-repos/crypto-market-data-ts push --force https://github.com/nirholas/crypto-market-data-ts.git HEAD:main && gh repo archive nirholas/crypto-market-data-ts --yes`, `git -C dist/retired-repos/crypto-data-aggregator push --force https://github.com/nirholas/crypto-data-aggregator.git HEAD:main && gh repo archive nirholas/crypto-data-aggregator --yes`, `git -C dist/retired-repos/memescope-monday-directory push --force https://github.com/nirholas/memescope-monday-directory.git HEAD:main && gh repo archive nirholas/memescope-monday-directory --yes`, `git -C dist/retired-repos/robinhood-chain-alert-bot push --force https://github.com/nirholas/robinhood-chain-alert-bot.git HEAD:main && gh repo archive nirholas/robinhood-chain-alert-bot --yes`, `git -C dist/retired-repos/robinhood-chain-trading-bot push --force https://github.com/nirholas/robinhood-chain-trading-bot.git HEAD:main && gh repo archive nirholas/robinhood-chain-trading-bot --yes`. `dist/` is gitignored, so re-run `npm run retire:repos` first if the staged trees were cleaned since this session. | 7 pushes + 7 archives | Removes 7 stale/duplicate public repos from the owner's GitHub without losing their history (each gets a pointer commit first) | [503-integrate-04-robinhood-copies-and-retired-repos.md](../503-integrate-04-robinhood-copies-and-retired-repos.md) (retired this session; see `_context/integrate-PROGRESS.md`) |
Deleted 2026-09-01: the former row 5 (`WALLET_ENCRYPTION_KEY_PREVIOUS` policy), which
diff --git a/public/changelog-recent.json b/public/changelog-recent.json
index 88d796e1e..e53c154da 100644
--- a/public/changelog-recent.json
+++ b/public/changelog-recent.json
@@ -1,11 +1,11 @@
{
- "generated_at": "2026-10-14T03:31:33.811Z",
+ "generated_at": "2026-10-14T04:20:35.625Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
"url": "https://three.ws"
},
- "total": 4084,
+ "total": 4085,
"complete": false,
"full_feed": "/changelog.json",
"entries": [
@@ -42,6 +42,17 @@
"security"
]
},
+ {
+ "date": "2026-10-14",
+ "type": "update",
+ "title": "GitHub fee-claim feed now reads from a real-time listener, not just an on-demand RPC scan",
+ "summary": "The claims feed's GitHub-attribution path used to walk Solana RPC history fresh on every request, the same cost every time, with nothing persisted in between. services/pump-claims is a standalone process that subscribes to PumpFees program logs directly, decodes and attributes each claim as it happens, and writes it to a new pump_fee_claims table with a watchdog that resubscribes on a stalled connection and gap-fills whatever a drop missed. The claims route now reads that table first and only falls back to the RPC scan when the table has nothing for the requested window, so PUMPFUN_BOT_URL is no longer required for GitHub claims specifically (ordinary wallet claims still use it).",
+ "link": null,
+ "tags": [
+ "feature",
+ "infra"
+ ]
+ },
{
"date": "2026-10-14",
"type": "update",
@@ -1547,19 +1558,6 @@
"fix",
"improvement"
]
- },
- {
- "date": "2026-10-10",
- "type": "update",
- "title": "Developer plans with quotas that are enforced, self-serve upgrades, key rotation, IP allowlists and per-key analytics",
- "summary": "Every API key now sits on a developer plan: Free, Builder, Scale or Enterprise, each with a monthly call quota, a per-minute burst ceiling, a concurrency ceiling and a webhook cap, all enforced on every /api/v1 call rather than only recorded. Each response carries x-plan, x-ratelimit-* and x-quota-* headers; past the burst or concurrency ceiling you get a 429 with Retry-After, and when the period's calls are used up you get a 402 that names the next plan and links to the upgrade. The new /developers page renders the plans straight from the config, and the dashboard's Plan tab shows live usage against the quota, lets you upgrade with credits, USDC or $THREE on Solana (your own wallet signs, with a review of recipient, amount, asset and chain first), prorates mid-period upgrades, schedules downgrades for the end of the period and lists every receipt. Revoking a key now takes effect immediately on every server. Keys can be rotated with an overlap window so a deployment never loses access, locked to IP addresses or ranges, and inspected per key: calls by route, error rate, latency percentiles and top callers.",
- "link": "/developers",
- "tags": [
- "feature",
- "sdk",
- "security",
- "docs"
- ]
}
]
}
diff --git a/public/changelog.json b/public/changelog.json
index 40500905e..ec7203039 100644
--- a/public/changelog.json
+++ b/public/changelog.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-10-14T03:31:33.790Z",
+ "generated_at": "2026-10-14T04:20:35.603Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
@@ -39,6 +39,17 @@
"security"
]
},
+ {
+ "date": "2026-10-14",
+ "type": "update",
+ "title": "GitHub fee-claim feed now reads from a real-time listener, not just an on-demand RPC scan",
+ "summary": "The claims feed's GitHub-attribution path used to walk Solana RPC history fresh on every request, the same cost every time, with nothing persisted in between. services/pump-claims is a standalone process that subscribes to PumpFees program logs directly, decodes and attributes each claim as it happens, and writes it to a new pump_fee_claims table with a watchdog that resubscribes on a stalled connection and gap-fills whatever a drop missed. The claims route now reads that table first and only falls back to the RPC scan when the table has nothing for the requested window, so PUMPFUN_BOT_URL is no longer required for GitHub claims specifically (ordinary wallet claims still use it).",
+ "link": null,
+ "tags": [
+ "feature",
+ "infra"
+ ]
+ },
{
"date": "2026-10-14",
"type": "update",
diff --git a/public/changelog.xml b/public/changelog.xml
index b4ead63cb..8a57a3c6a 100644
--- a/public/changelog.xml
+++ b/public/changelog.xml
@@ -30,6 +30,14 @@
<category>feature</category>
<description>A GitHub identity withdrawing pump.fun fees through the claim_social_fee_pda instruction only proves payment to that identity, not which coin paid it: one GitHub fee account can be a shareholder on more than one coin, and its address can be pasted into a copycat coin's metadata. The claims feed and its Telegram channel now classify every such withdrawal with on-chain evidence: a same-transaction distribution to the exact account, or a 90%-dominant distribution history since the previous claim, then a repository-owner or creator-wallet match, down to an honest unresolved or unverified label when nothing proves a coin. A new-GitHub-account-plus-copycat-coin pattern holds the claim for review instead of posting it with a celebratory card.</description>
</item>
+ <item>
+ <title>GitHub fee-claim feed now reads from a real-time listener, not just an on-demand RPC scan</title>
+ <link>https://three.ws/changelog</link>
+ <guid isPermaLink="false">2026-10-14:GitHub fee-claim feed now reads from a real-time listener, not just an on-demand RPC scan</guid>
+ <pubDate>Wed, 14 Oct 2026 12:00:00 GMT</pubDate>
+ <category>feature</category>
+ <description>The claims feed's GitHub-attribution path used to walk Solana RPC history fresh on every request, the same cost every time, with nothing persisted in between. services/pump-claims is a standalone process that subscribes to PumpFees program logs directly, decodes and attributes each claim as it happens, and writes it to a new pump_fee_claims table with a watchdog that resubscribes on a stalled connection and gap-fills whatever a drop missed. The claims route now reads that table first and only falls back to the RPC scan when the table has nothing for the requested window, so PUMPFUN_BOT_URL is no longer required for GitHub claims specifically (ordinary wallet claims still use it).</description>
+ </item>
<item>
<title>Robinhood Chain feed worker now runs the published SDK, not a stale local snapshot</title>
<link>https://three.ws/changelog</link>
diff --git a/public/features.json b/public/features.json
index 692410203..d401333c2 100644
--- a/public/features.json
+++ b/public/features.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-10-14T03:31:33.776Z",
+ "generated_at": "2026-10-14T04:20:35.590Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json",
"site": {
"name": "three.ws",
diff --git a/services/README.md b/services/README.md
index ed680cce0..41e1c6fc5 100644
--- a/services/README.md
+++ b/services/README.md
@@ -7,6 +7,7 @@ Long-running, standalone three.ws services: processes that hold persistent conne
| Service | What it is | Deployed as |
| --- | --- | --- |
| [`pump-graduations/`](pump-graduations) | pump.fun graduations indexer, detailed below | Container (`Dockerfile`) |
+| [`pump-claims/`](pump-claims) | Real-time GitHub social-fee-PDA claim listener. See its [README](pump-claims/README.md) | Container (`Dockerfile`) |
| [`agent-screen-caster/`](agent-screen-caster) | Gives an agent a live, watchable screen from a real Playwright session. See its [README](agent-screen-caster/README.md) | Container (`Dockerfile`) |
| [`liquidation-collector/`](liquidation-collector) | Aggregates public futures liquidation feeds into a rolling REST snapshot. See its [README](liquidation-collector/README.md) | Cloud Run (`liquidation-collector`) |
| [`fleet-console/`](fleet-console) | Health console for an open-source fleet: probes what every repository of a GitHub owner claims and scores what it finds. HTTP dashboard, CLI, and MCP server. See its [README](fleet-console/README.md) | Not deployed, by design: run it from a terminal, a cron job, or next to an agent |
diff --git a/services/pump-claims/Dockerfile b/services/pump-claims/Dockerfile
new file mode 100644
index 000000000..3d5a2dcae
--- /dev/null
+++ b/services/pump-claims/Dockerfile
@@ -0,0 +1,43 @@
+# pump-claims: real-time GitHub social-fee-PDA claim listener.
+#
+# Build from the REPO ROOT (it reaches outside its own directory for shared
+# decode/attribution logic; see the COPY comments below):
+#
+# docker build -f services/pump-claims/Dockerfile -t pump-claims .
+# docker run --env-file .env pump-claims
+#
+# Long-lived WebSocket subscription, not a request/response function. Deploy
+# with --no-cpu-throttling and --min-instances=1 so it keeps listening between
+# health probes. See cloudbuild.yaml.
+
+FROM node:20-alpine
+
+WORKDIR /app
+
+# Install this service's own deps straight from its package.json (not the root
+# lockfile: pulling that in would require every other workspace's package.json
+# present too, just for npm ci's consistency check), landing node_modules at
+# /app so Node's walk-up resolution finds it from both api/_lib and
+# services/pump-claims (a --prefix install scopes node_modules too narrowly).
+COPY services/pump-claims/package.json ./package.json
+RUN npm install --omit=dev --no-audit --no-fund
+
+# Repo code the service imports from OUTSIDE its own directory:
+# pipeline.js -> api/_lib/pump-events.js, api/_lib/pump-claims.js
+# pipeline.js -> api/_lib/pump-claims.js -> api/_lib/pump.js, api/_lib/db.js,
+# api/_lib/pump-claims-attribution.js, api/_lib/pump-claims-github.js,
+# api/_lib/solana/*, src/pump/first-claims.js
+# api/_lib/pump-claims-github.js -> api/_lib/pump-search.js -> src/ipfs.js
+# index.js/backfill.js -> api/_lib/solana/connection.js, api/_lib/solana/programs.js
+# Omitting any of these makes the image BUILD fine and then crash on boot with
+# "Cannot find module".
+COPY api/_lib ./api/_lib
+COPY src/pump ./src/pump
+COPY src/ipfs.js ./src/ipfs.js
+
+# Service source.
+COPY services/pump-claims ./services/pump-claims
+
+ENV NODE_ENV=production
+
+CMD ["node", "services/pump-claims/index.js"]
diff --git a/services/pump-claims/README.md b/services/pump-claims/README.md
new file mode 100644
index 000000000..b1a0f011c
--- /dev/null
+++ b/services/pump-claims/README.md
@@ -0,0 +1,115 @@
+# pump-claims
+
+Real-time listener for GitHub social-fee-PDA claims (`claim_social_fee_pda`) on
+the PumpFees program. Decodes and attributes each claim to a coin using the
+same evidence rules as the rest of the claims feed, then writes it into the
+`pump_fee_claims` Postgres table. Backs `api/_lib/pump-claims.js`'s table-first
+read path so `GET /api/pump/first-claims` (and the Telegram claims channel it
+feeds, see `docs/pump-claims-channel.md`) no longer depend on `PUMPFUN_BOT_URL`
+for GitHub claims.
+
+## Why a standalone service
+
+A claim can land on-chain at any moment; a request-scoped serverless function
+cannot hold a subscription open between invocations. This process holds one
+instead, is deployed with `--min-instances=1 --no-cpu-throttling`, and is
+designed to run forever.
+
+## How it works
+
+```
+PumpFees program logs
+ │ Connection.onLogs (listener.js)
+ ▼
+decodeClaim() / processLogEntry() pipeline.js
+ ├── isSocialClaimLog / parseSocialFeeClaim api/_lib/pump-events.js
+ └── attributeGithubClaim api/_lib/pump-claims.js
+ │
+ ▼
+store.insertClaim() store.js
+ └── insert into pump_fee_claims ... on conflict (signature) do nothing
+```
+
+- **`listener.js`**: `ClaimListener` wraps `Connection.onLogs` (reusing the
+ repo's RPC-failover-aware `Connection`, not a hand-rolled WebSocket client)
+ with an app-level heartbeat watchdog. Claim events are too rare to serve as a
+ liveness signal on their own, so the watchdog pings `connection.getSlot()` on
+ an interval; after `maxMissedHeartbeats` consecutive failures it tears down
+ and resubscribes, then calls `onReconnect` so the caller can gap-fill.
+- **`pipeline.js`**: pure decode/attribute. `decodeClaim` filters a log entry
+ to GitHub claims only; `processLogEntry` additionally resolves the paying
+ coin via `attributeGithubClaim`. No I/O of its own beyond what those shared
+ functions already do (RPC reads, GitHub API, pump.fun metadata).
+- **`store.js`**: `makeStore` takes a `DATABASE_URL` (or an injectable `sql`
+ tagged-template function, for tests) and exposes `toRow`/`insertClaim`/
+ `countSince`. The insert is idempotent on `signature`.
+- **`dedupe.js`**: `SeenSignatures`, a bounded in-memory ring so a resubscribe
+ or a gap-fill overlapping the live stream never double-processes a claim
+ before it even reaches the idempotent insert.
+- **`index.js`**: process entrypoint. Wires `ClaimListener` to the decode/
+ store pipeline, runs gap-fill on cold start and after every forced
+ reconnect, and serves `GET /health`.
+- **`backfill.js`**: one-off script. Walks the PumpFees program's signature history
+ back N days (default 7) through the exact same `createClaimHandler` pipeline
+ the live listener uses, so the table isn't empty on day one. Safe to re-run.
+
+## Environment
+
+| Variable | Required | Purpose |
+|---|---|---|
+| `SOLANA_RPC_URL` | yes | Mainnet HTTPS RPC endpoint. |
+| `SOLANA_RPC_WS_URL` | no | Dedicated WSS override; otherwise derived from `SOLANA_RPC_URL` the same way `api/_lib/solana/connection.js`'s `resolveWsEndpoint` does for every other Solana reader in this repo. |
+| `DATABASE_URL` | yes | Neon Postgres connection string. |
+| `PORT` | no | Health server port, default `8080`. |
+
+## Run locally
+
+```sh
+cd services/pump-claims
+npm install
+SOLANA_RPC_URL=https://api.mainnet-beta.solana.com DATABASE_URL=postgres://... npm start
+```
+
+Backfill the last 7 days before the first live run:
+
+```sh
+SOLANA_RPC_URL=... DATABASE_URL=... npm run backfill -- --days=7
+```
+
+Or as a container, built from the **repo root** (it reaches across into
+`api/_lib` and `src/pump`):
+
+```sh
+docker build -f services/pump-claims/Dockerfile -t pump-claims .
+docker run --env-file .env pump-claims
+```
+
+Deploy:
+
+```sh
+gcloud builds submit --config services/pump-claims/cloudbuild.yaml .
+```
+
+## Tests
+
+```sh
+cd services/pump-claims
+npm test
+```
+
+`pipeline.test.js`, `listener.test.js`, and `store.test.js` run on `node:test`
+(not the root vitest suite) and need no live database or RPC endpoint: the
+listener's log subscriber and the store's `sql` function are both injectable.
+`tests/pump-claims-worker-image.test.js` (root vitest suite) guards the
+Dockerfile's `COPY` list against the service's real import graph, transitively
+(it caught `api/_lib/pump-claims-github.js -> api/_lib/pump-search.js ->
+src/ipfs.js`, a chain a one-hop check would miss).
+
+## Related
+
+- [api/_lib/pump-claims.js](../../api/_lib/pump-claims.js) - `scanFirstClaims`, table-first with RPC fallback
+- [api/_lib/pump-events.js](../../api/_lib/pump-events.js) - the typed Pump/PumpFees event decoder this service and the API share
+- [api/_lib/pump-claims-attribution.js](../../api/_lib/pump-claims-attribution.js) - the evidence rules and the impersonation hold
+- [api/_lib/migrations/20261015080000_pump_fee_claims.sql](../../api/_lib/migrations/20261015080000_pump_fee_claims.sql) - the table this service writes
+- [docs/pump-claims-channel.md](../../docs/pump-claims-channel.md) - the channel and API this service feeds
+- [services/pump-graduations/](../pump-graduations) - the sibling listener this service's `ClaimListener` pattern builds on
diff --git a/services/pump-claims/backfill.js b/services/pump-claims/backfill.js
new file mode 100644
index 000000000..ebe5880b3
--- /dev/null
+++ b/services/pump-claims/backfill.js
@@ -0,0 +1,111 @@
+/**
+ * One-off backfill: walks the PumpFees program's signature history back
+ * `--days` (default 7) and stores every GitHub social-fee-PDA claim found, so
+ * the claims feed isn't empty on day one of the listener's deployment. Safe
+ * to re-run: insertClaim is idempotent on signature, and a page's signatures
+ * are also deduped in-memory before the RPC fetch that would otherwise repeat.
+ *
+ * DATABASE_URL=... SOLANA_RPC_URL=... node backfill.js [--days=7]
+ */
+
+import { pathToFileURL } from 'node:url';
+import { PublicKey } from '@solana/web3.js';
+import { PUMP_FEE_PROGRAM_ID } from '../../api/_lib/solana/programs.js';
+import { isSocialClaimLog } from '../../api/_lib/pump-events.js';
+import { buildConnection, createClaimHandler } from './index.js';
+import { makeStore } from './store.js';
+import { SeenSignatures } from './dedupe.js';
+import { sleep, getParsedTransactionWithBackoff, withRpcBackoff } from './rpc-pace.js';
+
+const PAGE_LIMIT = 200;
+// Safety cap: ~100 pages. The PumpFees program is a single shared account, so
+// an unbounded backward walk could run indefinitely on a busy chain; this caps
+// one backfill run's RPC cost regardless of how far `--days` reaches.
+const MAX_SIGNATURES_SCANNED = 20_000;
+// Per-call pace between getParsedTransaction fetches; see rpc-pace.js. A paid
+// lane set via SOLANA_RPC_URL tolerates a shorter pace, so this is overridable.
+const RPC_PACE_MS = Number(process.env.PUMP_CLAIMS_BACKFILL_PACE_MS) || 150;
+
+function requiredEnv(name) {
+ const v = process.env[name];
+ if (!v) {
+ console.error(`[pump-claims backfill] missing env ${name}`);
+ process.exit(1);
+ }
+ return v;
+}
+
+function parseDays(argv) {
+ const arg = argv.find((a) => a.startsWith('--days='));
+ const days = arg ? Number(arg.split('=')[1]) : 7;
+ return Number.isFinite(days) && days > 0 ? days : 7;
+}
+
+/**
+ * @param {{days?: number, connection?: object, store?: object}} [opts]
+ * `connection`/`store` are injectable for tests; production calls with no
+ * overrides, which builds the real RPC connection and Neon store.
+ */
+export async function backfill({ days = 7, connection: conn, store: st } = {}) {
+ const connection = conn || buildConnection();
+ const store = st || makeStore(requiredEnv('DATABASE_URL'));
+ const seen = new SeenSignatures(MAX_SIGNATURES_SCANNED + 1);
+ const state = { claimsSeen: 0, claimsStored: 0, lastClaimAt: null, reconnects: 0, listener: null };
+ const maybeProcess = createClaimHandler({ connection, store, seen, state });
+
+ const lookbackTs = Math.floor(Date.now() / 1000) - days * 86400;
+ const programKey = new PublicKey(PUMP_FEE_PROGRAM_ID);
+
+ let before;
+ let scanned = 0;
+ let reachedWindow = false;
+
+ while (scanned < MAX_SIGNATURES_SCANNED) {
+ const sigs = await withRpcBackoff(() =>
+ connection.getSignaturesForAddress(programKey, {
+ limit: PAGE_LIMIT,
+ ...(before ? { before } : {}),
+ }),
+ );
+ await sleep(RPC_PACE_MS);
+ if (!sigs.length) break;
+ scanned += sigs.length;
+
+ for (const s of sigs) {
+ if (s.blockTime != null && s.blockTime < lookbackTs) {
+ reachedWindow = true;
+ break;
+ }
+ if (s.err || seen.has(s.signature)) continue;
+ const tx = await getParsedTransactionWithBackoff(connection, s.signature, {
+ maxSupportedTransactionVersion: 1,
+ commitment: 'confirmed',
+ });
+ await sleep(RPC_PACE_MS);
+ const logs = tx?.meta?.logMessages;
+ if (!logs || tx?.meta?.err || !isSocialClaimLog(logs)) continue;
+ await maybeProcess(s.signature, logs, null, { blockTime: s.blockTime ?? undefined });
+ }
+
+ if (reachedWindow || sigs.length < PAGE_LIMIT) break;
+ before = sigs[sigs.length - 1].signature;
+ }
+
+ console.log(
+ '[pump-claims backfill] scanned=%d stored=%d days=%d reachedWindow=%s',
+ scanned,
+ state.claimsStored,
+ days,
+ reachedWindow,
+ );
+ return state;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+ backfill({ days: parseDays(process.argv.slice(2)) })
+ .then(() => process.exit(0))
+ .catch((err) => {
+ console.error('[pump-claims backfill] failed:', err?.message || err);
+ process.exit(1);
+ });
+}
diff --git a/services/pump-claims/cloudbuild.yaml b/services/pump-claims/cloudbuild.yaml
new file mode 100644
index 000000000..b053b9233
--- /dev/null
+++ b/services/pump-claims/cloudbuild.yaml
@@ -0,0 +1,87 @@
+# Cloud Build -> Cloud Run for the pump-claims GitHub fee-PDA claim listener.
+#
+# Long-lived WebSocket subscription to the PumpFees program, so it cannot run
+# as a request/response Cloud Run function. Deployed with --no-cpu-throttling
+# and --min-instances=1 so the subscription stays alive between health probes.
+# Build context is the REPO ROOT (the Dockerfile COPYs api/_lib and src/pump).
+#
+# gcloud builds submit --config services/pump-claims/cloudbuild.yaml .
+#
+# Runtime config mirrors three-ws-api: the DATABASE_URL secret (the same Neon
+# database api/_lib/pump-claims.js reads for the table-first path) and the
+# pinned three-ws@ runtime service account (the project's default compute SA
+# was deleted, so an unpinned deploy fails). SOLANA_RPC_URL is set directly
+# (not a secret): it is the free `api.mainnet-beta.solana.com` lane, the only
+# free lane docs/ops/solana-rpc-lanes.md measured serving logsSubscribe since
+# MagicBlock's IP block, not a credential. If it throttles under a steady
+# subscription, point it at a paid lane the same way other long-lived workers
+# do (a dedicated secret, e.g. agent-mm-solana-rpc-url) with
+# --update-env-vars, never --set-env-vars.
+
+# Builds run as the pinned three-ws-build service account: the project's
+# default compute service account was deleted, so an unpinned submit fails
+# with "Unknown service account".
+serviceAccount: projects/aerial-vehicle-466722-p5/serviceAccounts/[email protected]
+
+# _REPO is the SHARED "workers" Artifact Registry repo other long-lived Node
+# services (agora-citizens, agent-mm, agent-orders) publish into. Cloud Build
+# does not create an Artifact Registry repo on demand, so a per-service repo
+# name that has never been created fails the push step after a full build.
+substitutions:
+ _REGION: us-central1
+ _SERVICE: pump-claims
+ _REPO: workers
+ _MIN_INSTANCES: "1"
+ _MAX_INSTANCES: "1"
+
+steps:
+ - id: build
+ name: gcr.io/cloud-builders/docker
+ args:
+ - build
+ - --file
+ - services/pump-claims/Dockerfile
+ - --tag
+ - ${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/${_SERVICE}:$SHORT_SHA
+ - --tag
+ - ${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/${_SERVICE}:latest
+ - --cache-from
+ - ${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/${_SERVICE}:latest
+ - .
+ timeout: 1800s
+
+ - id: push
+ name: gcr.io/cloud-builders/docker
+ args:
+ - push
+ - --all-tags
+ - ${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/${_SERVICE}
+
+ - id: deploy
+ name: gcr.io/google.com/cloudsdktool/cloud-sdk:slim
+ entrypoint: gcloud
+ args:
+ - run
+ - deploy
+ - ${_SERVICE}
+ - --image=${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/${_SERVICE}:$SHORT_SHA
+ - --region=${_REGION}
+ - --platform=managed
+ - --no-cpu-throttling
+ - --cpu=1
+ - --memory=512Mi
+ - --min-instances=${_MIN_INSTANCES}
+ - --max-instances=${_MAX_INSTANCES}
+ - --port=8080
+ - --no-allow-unauthenticated
+ - --service-account=three-ws@$PROJECT_ID.iam.gserviceaccount.com
+ - --set-env-vars=SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
+ - --set-secrets=DATABASE_URL=DATABASE_URL:latest
+
+images:
+ - ${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/${_SERVICE}:$SHORT_SHA
+ - ${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/${_SERVICE}:latest
+
+options:
+ machineType: E2_HIGHCPU_8
+ logging: CLOUD_LOGGING_ONLY
diff --git a/services/pump-claims/dedupe.js b/services/pump-claims/dedupe.js
new file mode 100644
index 000000000..a98e7c86f
--- /dev/null
+++ b/services/pump-claims/dedupe.js
@@ -0,0 +1,36 @@
+/**
+ * Bounded signature dedupe, same shape as services/pump-graduations's
+ * SeenSignatures: a WS resubscribe or a gap-fill replay can hand this
+ * listener the same signature twice, and an unbounded Set would grow for the
+ * life of the process.
+ *
+ * Drops the oldest quarter when full rather than clearing outright, so a
+ * signature seen one event ago still dedupes right after a trim.
+ */
+export class SeenSignatures {
+ constructor(limit = 5000) {
+ this._limit = limit;
+ this._sigs = new Set();
+ }
+
+ /** @returns {boolean} true the first time a signature is offered. */
+ add(signature) {
+ if (!signature || this._sigs.has(signature)) return false;
+ this._sigs.add(signature);
+ if (this._sigs.size > this._limit) {
+ const drop = Math.floor(this._limit / 4);
+ const it = this._sigs.values();
+ for (let i = 0; i < drop; i++) this._sigs.delete(it.next().value);
+ }
+ return true;
+ }
+
+ /** Cheap pre-check, e.g. to skip an RPC fetch before `add` would reject it anyway. */
+ has(signature) {
+ return this._sigs.has(signature);
+ }
+
+ get size() {
+ return this._sigs.size;
+ }
+}
diff --git a/services/pump-claims/index.js b/services/pump-claims/index.js
new file mode 100644
index 000000000..558406e03
--- /dev/null
+++ b/services/pump-claims/index.js
@@ -0,0 +1,182 @@
+/**
+ * pump-claims listener
+ * ---------------------
+ * Long-lived process: subscribes to PumpFees program logs, decodes and
+ * attributes each GitHub social-fee-PDA claim, and writes it to
+ * `pump_fee_claims`. Backs api/_lib/pump-claims.js's table-first read path so
+ * the claims feed no longer depends on PUMPFUN_BOT_URL for GitHub claims.
+ *
+ * Env:
+ * SOLANA_RPC_URL Mainnet HTTPS RPC endpoint (required).
+ * SOLANA_RPC_WS_URL Optional dedicated WSS endpoint override; otherwise
+ * derived from SOLANA_RPC_URL (same convention as
+ * api/_lib/solana/connection.js's resolveWsEndpoint).
+ * DATABASE_URL Neon Postgres connection string (required).
+ * PORT Health server port (default 8080).
+ *
+ * This process holds a long-lived WebSocket subscription, so it is NOT
+ * deployable as a request/response serverless function. Run it on Cloud Run
+ * with --min-instances=1 --no-cpu-throttling (see cloudbuild.yaml).
+ */
+
+import { createServer } from 'node:http';
+import { pathToFileURL } from 'node:url';
+import { Connection, PublicKey } from '@solana/web3.js';
+import { normalizeRpcUrl, resolveWsEndpoint } from '../../api/_lib/solana/connection.js';
+import { PUMP_FEE_PROGRAM_ID } from '../../api/_lib/solana/programs.js';
+import { isSocialClaimLog } from '../../api/_lib/pump-events.js';
+import { ClaimListener } from './listener.js';
+import { processLogEntry } from './pipeline.js';
+import { makeStore } from './store.js';
+import { SeenSignatures } from './dedupe.js';
+import { sleep, getParsedTransactionWithBackoff, withRpcBackoff } from './rpc-pace.js';
+
+const GAP_FILL_SIG_LIMIT = 100;
+const GAP_FILL_PACE_MS = Number(process.env.PUMP_CLAIMS_GAPFILL_PACE_MS) || 150;
+
+function required(name) {
+ const v = process.env[name];
+ if (!v) {
+ console.error(`[pump-claims] missing env ${name}`);
+ process.exit(1);
+ }
+ return v;
+}
+
+export function buildConnection() {
+ const rpcUrl = normalizeRpcUrl(required('SOLANA_RPC_URL'));
+ if (!rpcUrl) {
+ console.error('[pump-claims] SOLANA_RPC_URL is not a usable http(s) endpoint');
+ process.exit(1);
+ }
+ const wsEndpoint = resolveWsEndpoint(rpcUrl, 'mainnet');
+ return new Connection(rpcUrl, { wsEndpoint, commitment: 'confirmed' });
+}
+
+export function createHealthServer(state) {
+ return createServer((req, res) => {
+ if (req.url !== '/health') {
+ res.writeHead(404, { 'content-type': 'application/json' });
+ res.end(JSON.stringify({ error: 'not_found' }));
+ return;
+ }
+ res.writeHead(200, { 'content-type': 'application/json' });
+ res.end(
+ JSON.stringify({
+ ok: true,
+ uptime: process.uptime(),
+ claimsSeen: state.claimsSeen,
+ claimsStored: state.claimsStored,
+ lastClaimAt: state.lastClaimAt,
+ reconnects: state.reconnects,
+ missedHeartbeats: state.listener?.missedHeartbeats ?? 0,
+ }),
+ );
+ });
+}
+
+/**
+ * Wires one signature's logs through decode -> attribute -> store. Shared by
+ * the live listener callback and gap-fill so neither path can double-count:
+ * both the in-memory `seen` set and the table's `on conflict (signature) do
+ * nothing` make a replay of the same signature a no-op.
+ */
+export function createClaimHandler({ connection, store, seen, state }) {
+ return async function maybeProcess(signature, logs, err, { slot, blockTime } = {}) {
+ if (!seen.add(signature)) return;
+ const claim = await processLogEntry(connection, { signature, logs, err }, { blockTime });
+ if (!claim) return;
+ state.claimsSeen += 1;
+ const row = store.toRow(claim, { slot });
+ const inserted = await store.insertClaim(row);
+ if (inserted) {
+ state.claimsStored += 1;
+ state.lastClaimAt = new Date().toISOString();
+ console.log(
+ '[pump-claims] stored claim %s mint=%s label=%s',
+ signature,
+ claim.mint || '(unresolved)',
+ claim.attribution?.label,
+ );
+ }
+ };
+}
+
+/**
+ * Walk the PumpFees program's recent signature history and process any
+ * GitHub claim this process hasn't seen yet. Covers the gap behind a dropped
+ * WS subscription (called on every forced reconnect) and fills the table
+ * immediately on cold start, before the first live claim arrives.
+ */
+export async function gapFill({ connection, seen, maybeProcess }) {
+ try {
+ const sigs = await withRpcBackoff(() =>
+ connection.getSignaturesForAddress(new PublicKey(PUMP_FEE_PROGRAM_ID), {
+ limit: GAP_FILL_SIG_LIMIT,
+ }),
+ );
+ for (const s of sigs) {
+ if (s.err || seen.has(s.signature)) continue;
+ const tx = await getParsedTransactionWithBackoff(connection, s.signature, {
+ maxSupportedTransactionVersion: 1,
+ commitment: 'confirmed',
+ });
+ await sleep(GAP_FILL_PACE_MS);
+ const logs = tx?.meta?.logMessages;
+ if (!logs || tx?.meta?.err || !isSocialClaimLog(logs)) continue;
+ await maybeProcess(s.signature, logs, null, { blockTime: s.blockTime ?? undefined });
+ }
+ } catch (err) {
+ console.error('[pump-claims] gap-fill failed:', err?.message || err);
+ }
+}
+
+async function main() {
+ const databaseUrl = required('DATABASE_URL');
+ const connection = buildConnection();
+ const store = makeStore(databaseUrl);
+ const seen = new SeenSignatures();
+ const state = {
+ claimsSeen: 0,
+ claimsStored: 0,
+ lastClaimAt: null,
+ reconnects: 0,
+ listener: null,
+ };
+
+ const maybeProcess = createClaimHandler({ connection, store, seen, state });
+ const runGapFill = () => gapFill({ connection, seen, maybeProcess }).catch(() => {});
+
+ const listener = new ClaimListener({ connection });
+ state.listener = listener;
+ listener.start(
+ (entry, context) => {
+ maybeProcess(entry.signature, entry.logs, entry.err, { slot: context?.slot }).catch((err) =>
+ console.error('[pump-claims] handle entry failed:', err?.message || err),
+ );
+ },
+ () => {
+ state.reconnects += 1;
+ console.warn('[pump-claims] resubscribed after missed heartbeats, gap-filling');
+ runGapFill();
+ },
+ );
+
+ console.log('[pump-claims] listener started, program=%s', PUMP_FEE_PROGRAM_ID);
+ runGapFill();
+
+ const server = createHealthServer(state);
+ const port = parseInt(process.env.PORT ?? '8080', 10);
+ server.listen(port, () => console.log(`[pump-claims] health server on :${port}`));
+
+ function shutdown(signal) {
+ console.log(`[pump-claims] ${signal} received, shutting down`);
+ listener.stop();
+ server.close(() => process.exit(0));
+ setTimeout(() => process.exit(0), 5_000).unref?.();
+ }
+ process.on('SIGTERM', () => shutdown('SIGTERM'));
+ process.on('SIGINT', () => shutdown('SIGINT'));
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();
diff --git a/services/pump-claims/listener.js b/services/pump-claims/listener.js
new file mode 100644
index 000000000..c21ccd247
--- /dev/null
+++ b/services/pump-claims/listener.js
@@ -0,0 +1,156 @@
+/**
+ * Live log subscription on the PumpFees program with an explicit watchdog.
+ *
+ * `Connection.onLogs` holds its own WebSocket and reconnects at the transport
+ * layer, but a silently stuck subscription (socket open, server stopped
+ * pushing) looks identical to "no claims happened" from here -- and claims
+ * are rare enough that silence is the normal case. So liveness is judged by
+ * a periodic lightweight RPC call (`getSlot`), not by claim volume: a missed
+ * heartbeat means the connection, not the claim rate, and only repeated
+ * misses force a resubscribe. On a forced resubscribe, `onReconnect` fires so
+ * the caller can gap-fill whatever the dead window missed.
+ */
+
+import { PublicKey } from '@solana/web3.js';
+import { PUMP_FEE_PROGRAM_ID } from '../../api/_lib/solana/programs.js';
+
+// Connection.onLogs's filter param must be a PublicKey instance (it wraps it
+// as {mentions: [pubkey.toBase58()]} internally) or the literal strings
+// 'all'/'allWithVotes'. A bare program-id string is neither: the RPC node
+// rejects it with "unknown variant <id>, expected one of all, allWithVotes,
+// mentions" because the client sends the string through as-is instead of a
+// mentions filter. Build the PublicKey once at module load, not per-call.
+const PUMP_FEE_PROGRAM_KEY = new PublicKey(PUMP_FEE_PROGRAM_ID);
+
+const HEARTBEAT_MS = 30_000;
+const MAX_MISSED_HEARTBEATS = 3;
+const HEARTBEAT_TIMEOUT_MS = 10_000;
+const RESUBSCRIBE_BACKOFF_BASE_MS = 2_000;
+const RESUBSCRIBE_BACKOFF_MAX_MS = 60_000;
+
+export class ClaimListener {
+ /**
+ * @param {object} opts
+ * @param {import('@solana/web3.js').Connection} [opts.connection]
+ * @param {Function} [opts.logSubscriber] Injectable override matching
+ * Connection.onLogs's signature `(programId, handler, commitment) => subId`,
+ * used by tests to inject a fake subscription. `connection` is still used
+ * for the heartbeat probe when both are provided.
+ * @param {number} [opts.heartbeatMs]
+ * @param {number} [opts.maxMissedHeartbeats]
+ * @param {number} [opts.heartbeatTimeoutMs]
+ */
+ constructor({
+ connection,
+ logSubscriber,
+ heartbeatMs = HEARTBEAT_MS,
+ maxMissedHeartbeats = MAX_MISSED_HEARTBEATS,
+ heartbeatTimeoutMs = HEARTBEAT_TIMEOUT_MS,
+ } = {}) {
+ this._conn = connection;
+ this._logSubscriber = logSubscriber;
+ this._heartbeatMs = heartbeatMs;
+ this._maxMissed = maxMissedHeartbeats;
+ this._heartbeatTimeoutMs = heartbeatTimeoutMs;
+ this._subId = null;
+ this._missed = 0;
+ this._backoffAttempt = 0;
+ this._heartbeatTimer = null;
+ this._stopped = true;
+ this._onEntry = null;
+ this._onReconnect = null;
+ }
+
+ /**
+ * @param {(entry: {signature: string, logs?: string[], err?: unknown}, context?: {slot: number}) => void} onEntry
+ * @param {() => void} [onReconnect] Called after every forced resubscribe.
+ */
+ start(onEntry, onReconnect) {
+ this._onEntry = onEntry;
+ this._onReconnect = onReconnect || null;
+ this._stopped = false;
+ this._subscribe();
+ this._heartbeatTimer = setInterval(() => this._heartbeatTick(), this._heartbeatMs);
+ this._heartbeatTimer.unref?.();
+ }
+
+ stop() {
+ this._stopped = true;
+ if (this._heartbeatTimer) clearInterval(this._heartbeatTimer);
+ this._heartbeatTimer = null;
+ this._teardown();
+ }
+
+ get missedHeartbeats() {
+ return this._missed;
+ }
+
+ _subscribe() {
+ const handler = (entry, context) => {
+ this._missed = 0;
+ this._onEntry?.(entry, context);
+ };
+ try {
+ this._subId = this._logSubscriber
+ ? this._logSubscriber(PUMP_FEE_PROGRAM_KEY, handler, 'confirmed')
+ : this._conn.onLogs(PUMP_FEE_PROGRAM_KEY, handler, 'confirmed');
+ this._backoffAttempt = 0;
+ } catch (err) {
+ console.error('[pump-claims] subscribe failed:', err?.message || err);
+ this._scheduleResubscribe();
+ }
+ }
+
+ _teardown() {
+ if (this._conn && this._subId != null) {
+ try {
+ this._conn.removeOnLogsListener(this._subId);
+ } catch {
+ /* best effort: a dead connection cannot remove its own listener */
+ }
+ }
+ this._subId = null;
+ }
+
+ _scheduleResubscribe() {
+ const delay = Math.min(
+ RESUBSCRIBE_BACKOFF_MAX_MS,
+ RESUBSCRIBE_BACKOFF_BASE_MS * 2 ** this._backoffAttempt,
+ );
+ this._backoffAttempt += 1;
+ const t = setTimeout(() => {
+ if (!this._stopped) this._subscribe();
+ }, delay);
+ t.unref?.();
+ }
+
+ /** Exercised directly by tests; also wired to the real heartbeat interval. */
+ async _heartbeatTick() {
+ if (this._stopped) return;
+ try {
+ await this._probe();
+ this._missed = 0;
+ } catch {
+ this._missed += 1;
+ if (this._missed >= this._maxMissed) {
+ this._missed = 0;
+ console.warn('[pump-claims] heartbeat missed %d times, resubscribing', this._maxMissed);
+ this._teardown();
+ this._subscribe();
+ this._onReconnect?.();
+ }
+ }
+ }
+
+ async _probe() {
+ let timer;
+ try {
+ await new Promise((resolve, reject) => {
+ timer = setTimeout(() => reject(new Error('heartbeat timeout')), this._heartbeatTimeoutMs);
+ this._conn.getSlot('confirmed').then(resolve, reject);
+ });
+ } finally {
+ clearTimeout(timer);
+ }
+ }
+}
diff --git a/services/pump-claims/listener.test.js b/services/pump-claims/listener.test.js
new file mode 100644
index 000000000..c5c4d9548
--- /dev/null
+++ b/services/pump-claims/listener.test.js
@@ -0,0 +1,99 @@
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { ClaimListener } from './listener.js';
+
+function fakeSubscriber() {
+ let nextId = 1;
+ const calls = [];
+ const fn = (programId, handler) => {
+ calls.push({ programId, handler });
+ return nextId++;
+ };
+ fn.calls = calls;
+ return fn;
+}
+
+function fakeConnection({ getSlot } = {}) {
+ return {
+ _removed: [],
+ getSlot: getSlot || (async () => 123),
+ removeOnLogsListener(id) {
+ this._removed.push(id);
+ },
+ };
+}
+
+describe('ClaimListener', () => {
+ test('subscribes on start and forwards entries to onEntry', () => {
+ const subscriber = fakeSubscriber();
+ const listener = new ClaimListener({ logSubscriber: subscriber });
+ const entries = [];
+ listener.start((entry) => entries.push(entry));
+
+ assert.equal(subscriber.calls.length, 1);
+ subscriber.calls[0].handler({ signature: 'sig1', logs: [] }, { slot: 10 });
+ assert.equal(entries.length, 1);
+ assert.equal(entries[0].signature, 'sig1');
+ listener.stop();
+ });
+
+ test('a healthy heartbeat resets the missed counter', async () => {
+ const connection = fakeConnection();
+ const listener = new ClaimListener({ connection, logSubscriber: fakeSubscriber(), maxMissedHeartbeats: 3 });
+ listener.start(() => {});
+ await listener._heartbeatTick();
+ assert.equal(listener.missedHeartbeats, 0);
+ listener.stop();
+ });
+
+ test('repeated failed heartbeats force a resubscribe and call onReconnect', async () => {
+ const subscriber = fakeSubscriber();
+ const connection = fakeConnection({ getSlot: async () => { throw new Error('rpc down'); } });
+ const listener = new ClaimListener({
+ connection,
+ logSubscriber: subscriber,
+ maxMissedHeartbeats: 2,
+ heartbeatTimeoutMs: 50,
+ });
+ let reconnects = 0;
+ listener.start(() => {}, () => { reconnects += 1; });
+ assert.equal(subscriber.calls.length, 1);
+
+ await listener._heartbeatTick();
+ assert.equal(listener.missedHeartbeats, 1);
+ assert.equal(reconnects, 0);
+
+ await listener._heartbeatTick();
+ assert.equal(reconnects, 1);
+ assert.equal(subscriber.calls.length, 2, 'resubscribed after reaching maxMissedHeartbeats');
+ assert.equal(listener.missedHeartbeats, 0, 'counter resets after forcing a reconnect');
+
+ listener.stop();
+ });
+
+ test('a heartbeat that times out counts as a miss', async () => {
+ const subscriber = fakeSubscriber();
+ const connection = fakeConnection({ getSlot: () => new Promise(() => {}) }); // never resolves
+ const listener = new ClaimListener({
+ connection,
+ logSubscriber: subscriber,
+ maxMissedHeartbeats: 5,
+ heartbeatTimeoutMs: 20,
+ });
+ listener.start(() => {});
+ await listener._heartbeatTick();
+ assert.equal(listener.missedHeartbeats, 1);
+ listener.stop();
+ });
+
+ test('stop() tears down the subscription and clears the heartbeat timer', () => {
+ const subscriber = fakeSubscriber();
+ const connection = fakeConnection();
+ const listener = new ClaimListener({ connection, logSubscriber: subscriber });
+ listener.start(() => {});
+ listener.stop();
+ // A second stop() must not throw (idempotent shutdown).
+ listener.stop();
+ });
+});
diff --git a/services/pump-claims/package.json b/services/pump-claims/package.json
new file mode 100644
index 000000000..dde1f2fc0
--- /dev/null
+++ b/services/pump-claims/package.json
@@ -0,0 +1,24 @@
+{
+ "name": "@three-ws/pump-claims",
+ "version": "1.0.0",
+ "private": true,
+ "type": "module",
+ "description": "Real-time listener for GitHub social-fee-PDA claims on the PumpFees program. Decodes and attributes each claim to a coin, writes it to pump_fee_claims, and serves /health. Backs api/_lib/pump-claims.js's table-first read path so the claims feed no longer depends on PUMPFUN_BOT_URL.",
+ "main": "index.js",
+ "scripts": {
+ "start": "node index.js",
+ "dev": "node --watch index.js",
+ "backfill": "node backfill.js",
+ "test": "node --test"
+ },
+ "engines": {
+ "node": ">=20"
+ },
+ "dependencies": {
+ "@neondatabase/serverless": "^1.1.0",
+ "@nirholas/pump-sdk": "^1.0.0",
+ "@solana/web3.js": "^1.99.0",
+ "bs58": "^6.0.0",
+ "ws": "^8.21.0"
+ }
+}
diff --git a/services/pump-claims/pipeline.js b/services/pump-claims/pipeline.js
new file mode 100644
index 000000000..17ffc230c
--- /dev/null
+++ b/services/pump-claims/pipeline.js
@@ -0,0 +1,43 @@
+/**
+ * Decode one PumpFees log notification into a stored row, or null when the
+ * entry isn't a GitHub social-fee-PDA claim. Shared by the live listener
+ * (index.js) and the RPC backfill (backfill.js) so both paths attribute a
+ * claim identically: they call the exact same `attributeGithubClaim` the
+ * HTTP route's RPC fallback uses (api/_lib/pump-claims.js), never a
+ * re-implementation.
+ */
+
+import { isSocialClaimLog, parseSocialFeeClaim } from '../../api/_lib/pump-events.js';
+import { attributeGithubClaim, GITHUB_SOCIAL_PLATFORM } from '../../api/_lib/pump-claims.js';
+
+/**
+ * Decode a GitHub social-fee-PDA claim out of one transaction's logs, or null
+ * when the transaction failed, carries no claim event, or claims a non-GitHub
+ * platform.
+ * @param {{signature: string, logs?: string[], err?: unknown}} entry
+ */
+export function decodeClaim(entry) {
+ if (!entry || entry.err) return null;
+ const logs = entry.logs || [];
+ if (!isSocialClaimLog(logs)) return null;
+ const claim = parseSocialFeeClaim(logs);
+ if (!claim || claim.socialPlatform !== GITHUB_SOCIAL_PLATFORM) return null;
+ return claim;
+}
+
+/**
+ * Decode + attribute one log notification into the shape store.js writes, or
+ * null when it isn't a GitHub claim. Never throws: `attributeGithubClaim`
+ * already degrades to an unattributed-but-real claim on an RPC hiccup.
+ * @param {import('@solana/web3.js').Connection} connection
+ * @param {{signature: string, logs?: string[], err?: unknown}} entry
+ * @param {{blockTime?: number}} [opts] blockTime from a confirmed signature
+ * (backfill); omitted on the live path, where the claim just happened and
+ * "now" is the accurate timestamp.
+ */
+export async function processLogEntry(connection, entry, { blockTime } = {}) {
+ const claim = decodeClaim(entry);
+ if (!claim) return null;
+ const ts = blockTime ?? Math.floor(Date.now() / 1000);
+ return attributeGithubClaim(connection, claim, entry.signature, ts);
+}
diff --git a/services/pump-claims/pipeline.test.js b/services/pump-claims/pipeline.test.js
new file mode 100644
index 000000000..7002e2c85
--- /dev/null
+++ b/services/pump-claims/pipeline.test.js
@@ -0,0 +1,154 @@
+import { test, describe, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { decodeClaim, processLogEntry } from './pipeline.js';
+import {
+ socialClaimLogs,
+ socialClaimWithDistributionsLogs,
+ SYNTH,
+} from '../../tests/_helpers/pump-log-fixtures.js';
+
+const GITHUB_PLATFORM = 2;
+const DISCORD_PLATFORM = 1;
+
+function fakeConnection({ txLogs } = {}) {
+ return {
+ async getParsedTransaction() {
+ return { meta: { logMessages: txLogs || [] } };
+ },
+ async getSignaturesForAddress() {
+ return [];
+ },
+ };
+}
+
+let originalFetch;
+before(() => {
+ originalFetch = globalThis.fetch;
+ globalThis.fetch = async (url) => {
+ const u = String(url);
+ if (u.includes('api.github.com/users?since=')) {
+ return { ok: true, json: async () => [{ id: 42, login: 'octocat' }] };
+ }
+ if (u.includes('api.github.com/users/octocat')) {
+ return { ok: true, json: async () => ({ login: 'octocat', created_at: '2015-01-01T00:00:00Z' }) };
+ }
+ if (u.includes('frontend-api-v3.pump.fun/coins-v2/')) {
+ return {
+ ok: true,
+ json: async () => ({ creator: SYNTH.RECIPIENT, name: 'Test Coin', usd_market_cap: 50_000 }),
+ };
+ }
+ return { ok: false, status: 404, json: async () => ({}) };
+ };
+});
+after(() => {
+ globalThis.fetch = originalFetch;
+});
+
+describe('decodeClaim', () => {
+ test('returns null for an entry whose transaction errored', () => {
+ assert.equal(decodeClaim({ signature: 'sig', logs: ['anything'], err: { InstructionError: [] } }), null);
+ });
+
+ test('returns null when the logs carry no claim_social_fee_pda instruction', () => {
+ assert.equal(decodeClaim({ signature: 'sig', logs: ['Program log: Instruction: Trade'] }), null);
+ });
+
+ test('returns null for a non-GitHub social platform claim', () => {
+ const logs = socialClaimLogs({
+ userId: '42',
+ platform: DISCORD_PLATFORM,
+ socialFeePda: SYNTH.PDA_A,
+ recipient: SYNTH.RECIPIENT,
+ socialClaimAuthority: SYNTH.CLAIM_AUTHORITY,
+ amountClaimed: 1_000_000,
+ lifetimeClaimed: 1_000_000,
+ });
+ assert.equal(decodeClaim({ signature: 'sig', logs }), null);
+ });
+
+ test('decodes a GitHub claim', () => {
+ const logs = socialClaimLogs({
+ userId: '42',
+ platform: GITHUB_PLATFORM,
+ socialFeePda: SYNTH.PDA_A,
+ recipient: SYNTH.RECIPIENT,
+ socialClaimAuthority: SYNTH.CLAIM_AUTHORITY,
+ amountClaimed: 1_000_000,
+ lifetimeClaimed: 1_000_000,
+ });
+ const claim = decodeClaim({ signature: 'sig', logs });
+ assert.ok(claim);
+ assert.equal(claim.githubUserId, '42');
+ assert.equal(claim.socialPlatform, GITHUB_PLATFORM);
+ assert.equal(claim.recipient, SYNTH.RECIPIENT);
+ });
+});
+
+describe('processLogEntry', () => {
+ test('returns null when the transaction errored', async () => {
+ const result = await processLogEntry(fakeConnection(), {
+ signature: 'sig',
+ logs: ['anything'],
+ err: { InstructionError: [] },
+ });
+ assert.equal(result, null);
+ });
+
+ test('returns null for a non-claim entry', async () => {
+ const result = await processLogEntry(fakeConnection(), {
+ signature: 'sig',
+ logs: ['Program log: Instruction: Trade'],
+ });
+ assert.equal(result, null);
+ });
+
+ test('attributes a GitHub claim to its coin via same-transaction evidence', async () => {
+ const claimFields = {
+ userId: '42',
+ platform: GITHUB_PLATFORM,
+ socialFeePda: SYNTH.PDA_A,
+ recipient: SYNTH.RECIPIENT,
+ socialClaimAuthority: SYNTH.CLAIM_AUTHORITY,
+ amountClaimed: 1_000_000,
+ lifetimeClaimed: 1_000_000,
+ };
+ const distribution = {
+ mint: SYNTH.MINT_A,
+ bondingCurve: SYNTH.BONDING_CURVE_A,
+ sharingConfig: SYNTH.SHARING_CONFIG_A,
+ admin: SYNTH.ADMIN,
+ shareholders: [{ address: SYNTH.PDA_A, shareBps: 5000 }],
+ distributed: 2_000_000,
+ };
+ const logs = socialClaimWithDistributionsLogs(claimFields, [distribution]);
+
+ const claim = await processLogEntry(fakeConnection({ txLogs: logs }), { signature: 'sig123', logs });
+
+ assert.ok(claim);
+ assert.equal(claim.signature, 'sig123');
+ assert.equal(claim.mint, SYNTH.MINT_A);
+ assert.equal(claim.creator, SYNTH.RECIPIENT);
+ assert.equal(claim.githubUserId, '42');
+ assert.equal(claim.githubLogin, 'octocat');
+ assert.ok(claim.attribution?.label);
+ assert.equal(typeof claim.held, 'boolean');
+ });
+
+ test('a blockTime option is reflected on the returned claim', async () => {
+ const claimFields = {
+ userId: '42',
+ platform: GITHUB_PLATFORM,
+ socialFeePda: SYNTH.PDA_A,
+ recipient: SYNTH.RECIPIENT,
+ socialClaimAuthority: SYNTH.CLAIM_AUTHORITY,
+ amountClaimed: 500_000,
+ lifetimeClaimed: 500_000,
+ };
+ const logs = socialClaimLogs(claimFields);
+ const claim = await processLogEntry(fakeConnection({ txLogs: [] }), { signature: 'sig456', logs }, { blockTime: 1_700_000_000 });
+ assert.ok(claim);
+ assert.equal(claim.ts, 1_700_000_000);
+ });
+});
diff --git a/services/pump-claims/rpc-pace.js b/services/pump-claims/rpc-pace.js
new file mode 100644
index 000000000..d73221a57
--- /dev/null
+++ b/services/pump-claims/rpc-pace.js
@@ -0,0 +1,36 @@
+/**
+ * The free public RPC lane (the default in cloudbuild.yaml) throttles well
+ * under one `getParsedTransaction` per signature run back-to-back: measured
+ * against mainnet on 2026-10-14, an unpaced walk hit `429 Too Many Requests`
+ * within a couple hundred calls even after the SDK's own built-in retries
+ * gave up. Shared by backfill.js's long walk and index.js's gap-fill so
+ * neither silently dies on a busy free lane.
+ */
+
+const MAX_429_RETRIES = 6;
+
+export function sleep(ms) {
+ return new Promise((r) => setTimeout(r, ms));
+}
+
+/**
+ * Generic backoff for any single RPC call on the free lane: `connection`'s own
+ * built-in retry (web3.js retries a 429 a few times internally) gives up long
+ * before this walk is done, so every call that runs in a loop -- not just
+ * getParsedTransaction -- needs its own longer-horizon retry on top of it.
+ */
+export async function withRpcBackoff(fn, sleepFn = sleep) {
+ for (let attempt = 0; ; attempt++) {
+ try {
+ return await fn();
+ } catch (err) {
+ const is429 = /429|Too Many Requests/i.test(err?.message || '');
+ if (!is429 || attempt >= MAX_429_RETRIES) throw err;
+ await sleepFn(Math.min(8000, 500 * 2 ** attempt));
+ }
+ }
+}
+
+export async function getParsedTransactionWithBackoff(connection, signature, opts, sleepFn = sleep) {
+ return withRpcBackoff(() => connection.getParsedTransaction(signature, opts), sleepFn);
+}
diff --git a/services/pump-claims/rpc-pace.test.js b/services/pump-claims/rpc-pace.test.js
new file mode 100644
index 000000000..c0a790955
--- /dev/null
+++ b/services/pump-claims/rpc-pace.test.js
@@ -0,0 +1,41 @@
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { getParsedTransactionWithBackoff } from './rpc-pace.js';
+
+function fakeConnection(responses) {
+ let i = 0;
+ return {
+ calls: 0,
+ async getParsedTransaction() {
+ this.calls += 1;
+ const next = responses[Math.min(i, responses.length - 1)];
+ i += 1;
+ if (next instanceof Error) throw next;
+ return next;
+ },
+ };
+}
+
+const noSleep = async () => {};
+
+describe('getParsedTransactionWithBackoff', () => {
+ test('returns the result once a 429 clears', async () => {
+ const connection = fakeConnection([new Error('429 Too Many Requests'), { meta: { logMessages: [] } }]);
+ const result = await getParsedTransactionWithBackoff(connection, 'sig', {}, noSleep);
+ assert.deepEqual(result, { meta: { logMessages: [] } });
+ assert.equal(connection.calls, 2);
+ });
+
+ test('rethrows a non-429 error immediately, with no retry', async () => {
+ const connection = fakeConnection([new Error('boom')]);
+ await assert.rejects(() => getParsedTransactionWithBackoff(connection, 'sig', {}, noSleep), /boom/);
+ assert.equal(connection.calls, 1);
+ });
+
+ test('gives up after the retry budget on a persistent 429', async () => {
+ const connection = fakeConnection([new Error('429 Too Many Requests')]);
+ await assert.rejects(() => getParsedTransactionWithBackoff(connection, 'sig', {}, noSleep), /429/);
+ assert.ok(connection.calls > 1);
+ });
+});
diff --git a/services/pump-claims/store.js b/services/pump-claims/store.js
new file mode 100644
index 000000000..9ee888bcc
--- /dev/null
+++ b/services/pump-claims/store.js
@@ -0,0 +1,65 @@
+/**
+ * pump_fee_claims persistence. Runs outside api/, so it owns its own Neon
+ * client rather than importing api/_lib/db.js (mirrors workers/agora-citizens's
+ * store.js). `makeStore` accepts either a DATABASE_URL string (production) or
+ * an already-built sql tagged-template function (tests), so the insert path
+ * is exercised without a live database.
+ */
+
+import { neon } from '@neondatabase/serverless';
+
+/**
+ * @param {string|Function} databaseUrlOrSql
+ */
+export function makeStore(databaseUrlOrSql) {
+ const sql = typeof databaseUrlOrSql === 'string' ? neon(databaseUrlOrSql) : databaseUrlOrSql;
+
+ return {
+ /**
+ * Build the DB row for one attributed claim (pipeline.js's output). `slot`
+ * comes from the caller: the live listener's onLogs context carries it,
+ * attributeGithubClaim's return value does not.
+ * @param {object} claim
+ * @param {{slot?: number|null}} [opts]
+ */
+ toRow(claim, { slot = null } = {}) {
+ return {
+ signature: claim.signature,
+ mint: claim.mint || null,
+ claimer: claim.creator,
+ githubUserId: claim.githubUserId != null ? String(claim.githubUserId) : null,
+ lamports: String(claim.lamports || 0),
+ label: claim.attribution?.label || null,
+ held: Boolean(claim.held),
+ slot,
+ ts: claim.ts || Math.floor(Date.now() / 1000),
+ };
+ },
+
+ /**
+ * Idempotent insert keyed on signature.
+ * @returns {Promise<boolean>} true the first time this signature is stored.
+ */
+ async insertClaim(row) {
+ const rows = await sql`
+ insert into pump_fee_claims (
+ signature, mint, claimer, github_user_id, lamports, label, held, slot, created_at
+ ) values (
+ ${row.signature}, ${row.mint}, ${row.claimer}, ${row.githubUserId},
+ ${row.lamports}, ${row.label}, ${row.held}, ${row.slot}, to_timestamp(${row.ts})
+ )
+ on conflict (signature) do nothing
+ returning signature
+ `;
+ return rows.length > 0;
+ },
+
+ /** Row count since `sinceTs` (unix seconds), for the 10-minute verification run. */
+ async countSince(sinceTs) {
+ const rows = await sql`
+ select count(*)::int as n from pump_fee_claims where created_at >= to_timestamp(${sinceTs})
+ `;
+ return rows[0]?.n ?? 0;
+ },
+ };
+}
diff --git a/services/pump-claims/store.test.js b/services/pump-claims/store.test.js
new file mode 100644
index 000000000..b3786c330
--- /dev/null
+++ b/services/pump-claims/store.test.js
@@ -0,0 +1,99 @@
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { makeStore } from './store.js';
+
+function makeFakeSql() {
+ const rows = new Map();
+ const calls = [];
+ async function sql(strings, ...values) {
+ calls.push({ text: strings.join('?'), values });
+ const text = strings.join(' ');
+ if (text.includes('insert into pump_fee_claims')) {
+ const [signature, mint, claimer, githubUserId, lamports, label, held, slot, ts] = values;
+ if (rows.has(signature)) return [];
+ rows.set(signature, { signature, mint, claimer, githubUserId, lamports, label, held, slot, ts });
+ return [{ signature }];
+ }
+ if (text.includes('select count(*)')) {
+ const [sinceTs] = values;
+ const n = [...rows.values()].filter((r) => r.ts >= sinceTs).length;
+ return [{ n }];
+ }
+ return [];
+ }
+ sql.rows = rows;
+ sql.calls = calls;
+ return sql;
+}
+
+describe('store.toRow', () => {
+ test('maps an attributed claim to the DB row shape', () => {
+ const store = makeStore(makeFakeSql());
+ const row = store.toRow(
+ {
+ signature: 'sig1',
+ mint: 'MintAAA',
+ creator: 'ClaimerWallet',
+ githubUserId: 42,
+ lamports: 123456,
+ attribution: { label: 'confirmed_match' },
+ held: false,
+ ts: 1_700_000_000,
+ },
+ { slot: 999 },
+ );
+ assert.deepEqual(row, {
+ signature: 'sig1',
+ mint: 'MintAAA',
+ claimer: 'ClaimerWallet',
+ githubUserId: '42',
+ lamports: '123456',
+ label: 'confirmed_match',
+ held: false,
+ slot: 999,
+ ts: 1_700_000_000,
+ });
+ });
+
+ test('falls back to a null mint and the current time when the claim lacks them', () => {
+ const store = makeStore(makeFakeSql());
+ const before = Math.floor(Date.now() / 1000);
+ const row = store.toRow({ signature: 'sig2', mint: '', creator: 'Wallet', lamports: 0, held: true });
+ assert.equal(row.mint, null);
+ assert.equal(row.githubUserId, null);
+ assert.equal(row.label, null);
+ assert.ok(row.ts >= before);
+ });
+});
+
+describe('store.insertClaim', () => {
+ test('stores a new signature and returns true', async () => {
+ const fakeSql = makeFakeSql();
+ const store = makeStore(fakeSql);
+ const row = store.toRow({ signature: 'sigA', mint: 'MintX', creator: 'Wallet', lamports: 10, ts: 1_700_000_000 });
+ const inserted = await store.insertClaim(row);
+ assert.equal(inserted, true);
+ assert.equal(fakeSql.rows.size, 1);
+ });
+
+ test('a repeat insert of the same signature is a no-op (idempotent)', async () => {
+ const fakeSql = makeFakeSql();
+ const store = makeStore(fakeSql);
+ const row = store.toRow({ signature: 'sigB', mint: 'MintX', creator: 'Wallet', lamports: 10, ts: 1_700_000_000 });
+ assert.equal(await store.insertClaim(row), true);
+ assert.equal(await store.insertClaim(row), false);
+ assert.equal(fakeSql.rows.size, 1);
+ });
+});
+
+describe('store.countSince', () => {
+ test('counts only rows at or after the cutoff', async () => {
+ const fakeSql = makeFakeSql();
+ const store = makeStore(fakeSql);
+ await store.insertClaim(store.toRow({ signature: 'old', creator: 'W', lamports: 1, ts: 1_000 }));
+ await store.insertClaim(store.toRow({ signature: 'new', creator: 'W', lamports: 1, ts: 2_000 }));
+ assert.equal(await store.countSince(1_500), 1);
+ assert.equal(await store.countSince(500), 2);
+ });
+});
diff --git a/tests/pump-claims-worker-image.test.js b/tests/pump-claims-worker-image.test.js
new file mode 100644
index 000000000..c49422fc1
--- /dev/null
+++ b/tests/pump-claims-worker-image.test.js
@@ -0,0 +1,94 @@
+/**
+ * pump-claims container: does the image actually carry everything the
+ * service imports?
+ *
+ * Mirrors tests/agora-worker-image.test.js's guard, but follows imports
+ * TRANSITIVELY (not just one hop out of the service directory): pipeline.js
+ * imports api/_lib/pump-claims.js, which imports api/_lib/pump-claims-github.js,
+ * which imports api/_lib/pump-search.js, which imports src/ipfs.js. A one-hop
+ * scan starting from services/pump-claims would miss that last link entirely,
+ * and the image would build clean and crash on boot with "Cannot find module".
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname, resolve, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const SERVICE_DIR = join(ROOT, 'services', 'pump-claims');
+const DOCKERFILE = join(SERVICE_DIR, 'Dockerfile');
+
+const IMPORT_RE = /(?:from|import)\s*\(?\s*['"](\.\.?\/[^'"]+)['"]/g;
+
+function resolveModule(specifierTarget) {
+ if (existsSync(specifierTarget)) return specifierTarget;
+ if (existsSync(`${specifierTarget}.js`)) return `${specifierTarget}.js`;
+ return null;
+}
+
+/** BFS over every file reachable by relative import from the service's own source, skipping its own test files. */
+function allReachableFiles() {
+ const seeds = ['pipeline.js', 'listener.js', 'store.js', 'index.js', 'backfill.js', 'dedupe.js'].map((f) =>
+ join(SERVICE_DIR, f),
+ );
+ const visited = new Set();
+ const queue = [...seeds];
+ while (queue.length) {
+ const file = queue.pop();
+ if (visited.has(file) || !existsSync(file)) continue;
+ visited.add(file);
+ const src = readFileSync(file, 'utf8');
+ for (const m of src.matchAll(IMPORT_RE)) {
+ const resolved = resolveModule(resolve(dirname(file), m[1]));
+ if (resolved && !visited.has(resolved)) queue.push(resolved);
+ }
+ }
+ return [...visited];
+}
+
+/** Repo-relative targets reachable from the service's source but living outside its own directory. */
+function crossBoundaryImports() {
+ const found = new Set();
+ for (const file of allReachableFiles()) {
+ const rel = relative(SERVICE_DIR, file);
+ if (rel.startsWith('..')) found.add(relative(ROOT, file));
+ }
+ return [...found].sort();
+}
+
+/** Paths the Dockerfile COPYs out of the build context. */
+function dockerfileCopies() {
+ const copies = [];
+ for (const line of readFileSync(DOCKERFILE, 'utf8').split('\n')) {
+ const m = line.match(/^COPY\s+(.+)$/i);
+ if (!m) continue;
+ const parts = m[1].trim().split(/\s+/);
+ for (const src of parts.slice(0, -1)) copies.push(src.replace(/^\.\//, ''));
+ }
+ return copies;
+}
+
+describe('pump-claims image carries the service dependencies', () => {
+ const imports = crossBoundaryImports();
+ const copies = dockerfileCopies();
+
+ it('finds the cross-boundary imports it is meant to guard, including transitive ones', () => {
+ expect(imports.length).toBeGreaterThan(0);
+ expect(imports).toContain('api/_lib/pump-claims.js');
+ // The transitive chain this test exists to catch: pipeline.js -> pump-claims.js
+ // -> pump-claims-github.js -> pump-search.js -> src/ipfs.js.
+ expect(imports).toContain('src/ipfs.js');
+ });
+
+ it.each(crossBoundaryImports())('Dockerfile COPYs the source for %s', (target) => {
+ const covered = copies.some((c) => target === c || target.startsWith(`${c}/`));
+ expect(
+ covered,
+ `services/pump-claims transitively imports ${target}, but no COPY in ` +
+ `services/pump-claims/Dockerfile brings it into the image. The build will still succeed and the ` +
+ `container will crash on boot with "Cannot find module". Add a COPY for it.\n` +
+ `Current COPY sources: ${copies.join(', ')}`,
+ ).toBe(true);
+ });
+});