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.

13.2 KB
Raw Blame
// @ts-check
// Automatic first-claim delivery to Telegram: every time a pump.fun creator
// pulls their accrued creator fees out of the fee vault for the FIRST time,
// that claim gets its own message. Driven by /api/cron/pump-claims-push on
// Cloud Scheduler.
//
// A first claim is an on-chain, irreversible signal that a creator is live and
// engaged with their coin, which is why it is worth its own channel rather
// than a line in the holder changelog. The scan itself lives in
// ./pump-claims.js and is shared with GET /api/pump/first-claims.
//
// Destination: TELEGRAM_PUMP_CLAIMS_CHAT_ID. There is deliberately NO fallback
// to the holder channel (TELEGRAM_CHANGELOG_CHAT_ID): this feed is high-volume
// third-party coin activity and holder-facing release notes are not the same
// audience. An unset chat id reports { skipped: 'not_configured' }.
//
// State (app_settings key `pump_claims_push_telegram`):
//   { lastTs: number|null, seen: string[], githubSeen: string[] }
// `lastTs` is the block time of the newest claim posted; `seen` is a bounded
// ring of recently posted transaction signatures. Both are needed because the
// two failure modes are different:
//
//   1. Claims arriving inside the same second as the last posted one share
//      `lastTs`, so a timestamp cursor alone would drop them. `seen` catches
//      those exactly, by signature.
//   2. `seen` is bounded, so it cannot answer for a claim older than the ring.
//      `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
// 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
// its own signature, but the channel should only ever announce that pairing
// once, the way it only announces a wallet's first claim once.
//
// On first run (no state) the lane seeds from the current scan WITHOUT posting,
// so enabling this feature never dumps a backlog of history into the channel.

import { sql } from './db.js';
import { scanFirstClaims } from './pump-claims.js';

import { fetchUpstream } from './upstream-fetch.js';
const TELEGRAM_LIMIT = 10; // per run; Bot API allows ~20 msg/min per chat
const TELEGRAM_PACE_MS = 3500;
// How far back each tick scans. The cron runs every 5 minutes, so a 30-minute
// window tolerates five consecutive missed ticks without losing a claim.
const SCAN_MINUTES = 30;
// Nothing older than this is ever posted, however far behind the state is. A
// catch-up drains a backlog; it must never replay history into the channel.
const CUTOFF_MINUTES = 180;
// Bounded at roughly the number of claims a very busy hour could produce, so
// the state row stays small while still covering the whole scan window.
const SEEN_LIMIT = 400;
const LOCK_KEY = 'pump_claims_push_lock';
const LOCK_TTL_S = 240;
const STATE_KEY = 'pump_claims_push_telegram';
// Bounded, and deliberately well under LOCK_TTL_S. The lock is what stops two
// ticks posting the same claim twice, but it only holds for its TTL: a request
// that hangs longer outlives its own lock and the next tick re-posts what the
// stalled one is still working through.
const TELEGRAM_TIMEOUT_MS = 20_000;

const LAMPORTS_PER_SOL = 1e9;

async function ensureTable() {
	await sql`
		CREATE TABLE IF NOT EXISTS app_settings (
			key text PRIMARY KEY,
			value jsonb NOT NULL,
			updated_at timestamptz NOT NULL DEFAULT now()
		)
	`;
}

async function getState(key) {
	const [row] = await sql`SELECT value FROM app_settings WHERE key = ${key}`;
	return row?.value ?? null;
}

async function setState(key, value) {
	await sql`
		INSERT INTO app_settings (key, value) VALUES (${key}, ${JSON.stringify(value)}::jsonb)
		ON CONFLICT (key) DO UPDATE SET value = excluded.value, updated_at = now()
	`;
}

export async function acquireLock() {
	await ensureTable();
	const rows = await sql`
		INSERT INTO app_settings (key, value)
		VALUES (${LOCK_KEY}, jsonb_build_object('until', extract(epoch from now()) + ${LOCK_TTL_S}))
		ON CONFLICT (key) DO UPDATE
			SET value = excluded.value, updated_at = now()
			WHERE (app_settings.value->>'until')::numeric < extract(epoch from now())
		RETURNING key
	`;
	return rows.length > 0;
}

export async function releaseLock() {
	await setState(LOCK_KEY, { until: 0 });
}

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

/**
 * Returns the claims to post, oldest-first, from a newest-first scan result.
 *
 * Selection is by signature against `seen` (exact) and by age against the
 * cutoff (so a long outage drains recent claims and drops stale ones rather
 * than replaying an hour of history). `lastTs` is not used to select: it only
 * bounds the scan window upstream, because a claim can share a second with the
 * last one posted and would be lost by a strictly-greater timestamp compare.
 *
 * @param {Array<{creator:string, mint:string, signature:string, lamports:number, ts:number}>} claims
 * @param {{ seen?: string[] }} state
 * @param {number} [nowMs]
 */
export function newClaimsSince(claims, state = {}, nowMs = Date.now()) {
	const seen = new Set(state.seen || []);
	const githubSeen = new Set(state.githubSeen || []);
	const oldestPostableTs = Math.floor(nowMs / 1000) - CUTOFF_MINUTES * 60;
	return claims
		.filter((c) => c.signature && !seen.has(c.signature))
		.filter((c) => !c.githubUserId || !githubSeen.has(githubClaimKey(c)))
		.filter((c) => Number.isFinite(c.ts) && c.ts >= oldestPostableTs)
		.sort((a, b) => a.ts - b.ts);
}

/** Appends signatures to the bounded ring, newest kept. */
export function rememberSignatures(seen = [], signatures = []) {
	const merged = [...seen, ...signatures];
	return merged.slice(Math.max(0, merged.length - SEEN_LIMIT));
}

/** `githubUserId:mint` dedupe key for a GitHub fee-PDA claim. */
export function githubClaimKey(claim) {
	return `${claim.githubUserId}:${claim.mint || ''}`;
}

/** Appends GitHub user+mint keys to the bounded ring, newest kept. */
export function rememberGithubClaims(githubSeen = [], claims = []) {
	const keys = claims.filter((c) => c.githubUserId).map(githubClaimKey);
	const merged = [...githubSeen, ...keys];
	return merged.slice(Math.max(0, merged.length - SEEN_LIMIT));
}

const escapeHtml = (s) =>
	String(s).replace(/[<>&]/g, (c) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;' })[c]);

/** Middle-truncates a base58 address so a message stays one line on mobile. */
export function shortAddress(addr) {
	const s = String(addr || '');
	return s.length > 12 ? `${s.slice(0, 4)}…${s.slice(-4)}` : s;
}

/** Lamports rendered as SOL with a precision that stays readable at any size. */
export function formatSol(lamports) {
	const sol = Number(lamports || 0) / LAMPORTS_PER_SOL;
	if (!Number.isFinite(sol) || sol <= 0) return '0 SOL';
	if (sol < 0.001) return '<0.001 SOL';
	if (sol < 1) return `${sol.toFixed(3)} SOL`;
	if (sol < 1000) return `${sol.toFixed(2)} SOL`;
	return `${Math.round(sol).toLocaleString('en-US')} SOL`;
}

// Every field below is derived from on-chain data supplied by a third party.
// Addresses are base58 and cannot carry markup, but they are escaped anyway so
// a malformed scan result can never break out of the HTML entity structure and
// smuggle a clickable link posted under the platform bot's identity.
/**
 * @param {{creator:string, mint:string, signature:string, lamports:number, ts:number,
 *   githubUserId?:string, githubLogin?:string|null, attribution?:{label:string,headline:string,explanation:string},
 *   held?:boolean, heldReasons?:string[]}} claim
 */
export function formatTelegramMessage(claim) {
	const when = Number.isFinite(claim.ts)
		? new Date(claim.ts * 1000).toISOString().replace('T', ' ').slice(0, 16) + ' UTC'
		: '';

	if (claim.githubUserId) return formatGithubClaimMessage(claim, when);

	const lines = [
		'<b>First creator fee claim</b>',
		'',
		`Creator <code>${escapeHtml(claim.creator)}</code>`,
	];
	if (claim.mint) lines.push(`Coin <code>${escapeHtml(claim.mint)}</code>`);
	lines.push('', `Claimed ${escapeHtml(formatSol(claim.lamports))}`);

	const refs = [
		`<a href="https://solscan.io/tx/${encodeURIComponent(claim.signature)}">tx ${escapeHtml(shortAddress(claim.signature))}</a>`,
	];
	if (claim.mint) {
		refs.push(
			`<a href="https://pump.fun/coin/${encodeURIComponent(claim.mint)}">pump.fun</a>`,
		);
	}
	lines.push('', `${refs.join(' · ')}${when ? ` · ${escapeHtml(when)}` : ''}`);
	return lines.join('\n');
}

/**
 * A GitHub fee-PDA claim's message, held or attributed. A held claim never
 * gets the celebratory framing above: it states plainly that a withdrawal
 * happened and why it is held, instead of crediting a coin or identity the
 * evidence does not support yet.
 */
function formatGithubClaimMessage(claim, when) {
	const identity = claim.githubLogin ? `github.com/${claim.githubLogin}` : `GitHub id ${claim.githubUserId}`;
	const lines = claim.held
		? [
				'<b>GitHub fee withdrawal held for review</b>',
				'',
				`Claimant <code>${escapeHtml(identity)}</code>`,
				...(claim.heldReasons?.length ? [`Held: ${escapeHtml(claim.heldReasons.join('; '))}`] : []),
			]
		: ['<b>GitHub fee claim</b>', '', `${escapeHtml(claim.attribution?.headline || 'UNVERIFIED GITHUB FEE WITHDRAWAL')}`, '', `Claimant <code>${escapeHtml(identity)}</code>`];

	if (claim.mint) lines.push(`Coin <code>${escapeHtml(claim.mint)}</code>`);
	lines.push('', `Claimed ${escapeHtml(formatSol(claim.lamports))}`);
	if (claim.attribution?.explanation) lines.push('', escapeHtml(claim.attribution.explanation));

	const refs = [
		`<a href="https://solscan.io/tx/${encodeURIComponent(claim.signature)}">tx ${escapeHtml(shortAddress(claim.signature))}</a>`,
	];
	if (claim.mint) refs.push(`<a href="https://pump.fun/coin/${encodeURIComponent(claim.mint)}">pump.fun</a>`);
	lines.push('', `${refs.join(' · ')}${when ? ` · ${escapeHtml(when)}` : ''}`);
	return lines.join('\n');
}

async function sendTelegram(botToken, chatId, text) {
	const res = await fetchUpstream(`https://api.telegram.org/bot${botToken}/sendMessage`, {
		method: 'POST',
		headers: { 'content-type': 'application/json' },
		body: JSON.stringify({
			chat_id: chatId,
			text,
			parse_mode: 'HTML',
			// The links are block explorers, not three.ws pages, and a preview
			// card per claim would bury the text in a high-volume feed.
			link_preview_options: { is_disabled: true },
		}),
		signal: AbortSignal.timeout(TELEGRAM_TIMEOUT_MS),
	}, { name: 'telegram', timeoutMs: 10_000, attempts: 2, okWhen: () => true });
	const body = await res.json().catch(() => ({}));
	if (!res.ok || !body.ok) {
		throw new Error(
			`Telegram sendMessage failed (${res.status}): ${body.description || 'unknown error'}`,
		);
	}
}

export async function pushTelegramLane({ scan = scanFirstClaims, now = Date.now } = {}) {
	const botToken = process.env.TELEGRAM_BOT_TOKEN;
	const chatId = process.env.TELEGRAM_PUMP_CLAIMS_CHAT_ID;
	if (!botToken || !chatId) return { skipped: 'not_configured' };

	const nowMs = now();
	const state = (await getState(STATE_KEY)) || { lastTs: null, seen: [], githubSeen: [] };
	// A resumed lane re-scans from its cursor so a gap wider than one window
	// still resolves, bounded by the cutoff so it can never replay history.
	const windowStart = Math.floor(nowMs / 1000) - SCAN_MINUTES * 60;
	const cutoffStart = Math.floor(nowMs / 1000) - CUTOFF_MINUTES * 60;
	const sinceTs = state.lastTs
		? Math.max(cutoffStart, Math.min(windowStart, state.lastTs))
		: windowStart;

	const claims = await scan({ sinceTs, limit: 50 });

	if (!state.lastTs) {
		// Seed: record what is already on-chain so enabling the lane posts
		// nothing, then start posting from the next tick onward.
		await setState(STATE_KEY, {
			lastTs: claims.length ? Math.max(...claims.map((c) => c.ts)) : Math.floor(nowMs / 1000),
			seen: rememberSignatures([], claims.map((c) => c.signature)),
			githubSeen: rememberGithubClaims([], claims),
		});
		return { posted: 0, seeded: true, scanned: claims.length };
	}

	const pending = newClaimsSince(claims, state, nowMs);
	if (pending.length === 0) return { posted: 0, scanned: claims.length };

	// Oldest-first: a backlog larger than one run drains across the following
	// ticks in claim order. Taking the newest would strand everything older.
	const batch = pending.slice(0, TELEGRAM_LIMIT);
	const backlog = pending.length - batch.length;
	if (backlog > 0) {
		console.warn(
			`[pump-claims] ${backlog} claims still queued after this run; draining ${TELEGRAM_LIMIT}/tick`,
		);
	}

	let sent = 0;
	let { lastTs, seen, githubSeen = [] } = state;
	try {
		for (const claim of batch) {
			await sendTelegram(botToken, chatId, formatTelegramMessage(claim));
			lastTs = Math.max(Number(lastTs) || 0, claim.ts);
			seen = rememberSignatures(seen, [claim.signature]);
			githubSeen = rememberGithubClaims(githubSeen, [claim]);
			sent++;
			// Written per claim, not per run: a tick killed mid-batch (the Cloud
			// Run request deadline is shorter than a full paced run) resumes at
			// the next claim rather than repeating the ones already delivered.
			await setState(STATE_KEY, { lastTs, seen, githubSeen });
			await sleep(TELEGRAM_PACE_MS);
		}
	} catch (err) {
		return { posted: sent, backlog, error: String(err?.message || err) };
	}
	return { posted: sent, backlog, scanned: claims.length };
}