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.

69.6 KB
Raw Blame
// Consolidated public Solana agent handlers.
// Reached via api/agents/solana/[action].js dispatcher.
// Named exports (taskHash, buildPayload, verifyPumpkitSignature) are kept
// for backward-compat with the test suite.

import crypto from 'node:crypto';
import { z } from 'zod';
import { PublicKey } from '@solana/web3.js';
import { solanaConnection, solanaRpcEndpoints, isEndpointCooling } from '../../_lib/solana/connection.js';
import { sql } from '../../_lib/db.js';
import { cors, json, method, wrap, error, readBody, readJson, rateLimited, serverError, respondError } from '../../_lib/http.js';
import { limits, clientIp } from '../../_lib/rate-limit.js';
import { getSessionUser } from '../../_lib/auth.js';
import { parse } from '../../_lib/validate.js';
import { randomToken } from '../../_lib/crypto.js';
import { env } from '../../_lib/env.js';
import { publicUrl, thumbnailUrl } from '../../_lib/r2.js';
import { buildAgentManifest, buildAgentOnchainAttributes, agentRoyaltyConfig, skillCollectionSymbol, THREE_WS } from '../../_lib/three-brand.js';
import {
	getAgentCollection,
	loadCollectionAuthorityKeypair,
	collectionAuthoritySigner,
	AGENT_COLLECTION,
} from '../../_lib/solana-collection.js';
import { KIND_MAP, crawlAgentAttestations } from '../../_lib/solana-attestations.js';
import { netStakeForAgent } from '../../_lib/reputation-market.js';
import {
	mintAttestation,
	loadAttesterKeypair,
	taskHash as _taskHash,
	buildPayload as _buildPayload,
} from '../../_lib/attest-event.js';

// ── Named exports preserved for tests ────────────────────────────────────────

export const taskHash = _taskHash;
export const buildPayload = _buildPayload;

const REPLAY_WINDOW_SECS = 5 * 60;
const MAX_BODY_BYTES = 64_000;

export function verifyPumpkitSignature({ secret, timestamp, signature, raw, nowSecs = Math.floor(Date.now() / 1000) }) {
	if (!secret || !timestamp || !signature) return { ok: false, reason: 'missing' };
	const ts = Number(timestamp);
	if (!Number.isFinite(ts)) return { ok: false, reason: 'bad_timestamp' };
	if (Math.abs(nowSecs - ts) > REPLAY_WINDOW_SECS) return { ok: false, reason: 'stale' };
	const expect = crypto.createHmac('sha256', secret).update(`${ts}.`).update(raw).digest();
	let got;
	try { got = Buffer.from(signature, 'hex'); } catch { return { ok: false, reason: 'bad_signature' }; }
	if (got.length !== expect.length) return { ok: false, reason: 'bad_signature' };
	return { ok: crypto.timingSafeEqual(got, expect), reason: 'ok' };
}

// ── solana-attestations ───────────────────────────────────────────────────────

export const handleAttestations = wrap(async (req, res) => {
	if (cors(req, res, { methods: 'GET,OPTIONS', credentials: false })) return;
	if (!method(req, res, ['GET'])) return;

	const rl = await limits.authedReadIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	const url     = new URL(req.url, `http://${req.headers.host}`);
	const asset   = url.searchParams.get('asset');
	const kindArg = url.searchParams.get('kind') || 'all';
	const network = url.searchParams.get('network') === 'mainnet' ? 'mainnet' : 'devnet';
	const limit   = Math.min(Number(url.searchParams.get('limit') || 100), 500);
	const includeRevoked = url.searchParams.get('include_revoked') === '1';
	// One-shot on-demand reindex. The crawl cron only runs every 5 min, so a
	// visitor who just submitted feedback would otherwise wait minutes to see it.
	// `refresh=1` (already rate-limited by authIp above) pulls the latest
	// signatures for this agent before answering, closing the submit→see-it loop.
	const force = url.searchParams.get('refresh') === '1';

	if (!asset) return error(res, 400, 'validation_error', 'asset query param required');
	try { new PublicKey(asset); } catch { return error(res, 400, 'validation_error', 'invalid asset pubkey'); }

	const wantKind = kindArg === 'all' ? null : KIND_MAP[kindArg];
	if (kindArg !== 'all' && !wantKind) {
		return error(res, 400, 'validation_error', 'kind must be one of: feedback, validation, task, accept, revoke, dispute, all');
	}

	let [cursor] = await sql`select last_indexed_at from solana_attestations_cursor where agent_asset = ${asset} limit 1`;
	if (!cursor || force) {
		const [agent] = await sql`select wallet_address as owner from agent_identities where meta->>'sol_mint_address' = ${asset} and deleted_at is null limit 1`;
		try { await crawlAgentAttestations({ agentAsset: asset, network, ownerWallet: agent?.owner || null }); } catch {}
		[cursor] = await sql`select last_indexed_at from solana_attestations_cursor where agent_asset = ${asset} limit 1`;
	}

	const rows = wantKind
		? await sql`select signature, slot, block_time, attester, kind, payload, verified, revoked, disputed from solana_attestations where agent_asset = ${asset} and network = ${network} and kind = ${wantKind} and (${includeRevoked} or revoked = false) order by slot desc limit ${limit}`
		: await sql`select signature, slot, block_time, attester, kind, payload, verified, revoked, disputed from solana_attestations where agent_asset = ${asset} and network = ${network} and (${includeRevoked} or revoked = false) order by slot desc limit ${limit}`;

	return json(res, 200, { data: rows, agent: asset, network, kind: kindArg, count: rows.length, last_indexed_at: cursor?.last_indexed_at || null });
});

// ── solana-attest-event ───────────────────────────────────────────────────────

// readBody, not a direct stream read: the Cloud Run server's body parsers drain
// the stream before handlers run (bytes preserved on req.rawBody). readBody
// rejects with { status: 413 } past the limit, matching the old behavior.
function readBuffered(req) {
	return readBody(req, MAX_BODY_BYTES);
}

const attestEventSchema = z.object({
	event_id:    z.string().min(1).max(128),
	event_type:  z.enum(['graduation', 'fee_claim', 'whale_trade', 'cto_detected']),
	agent_asset: z.string().min(32).max(44),
	network:     z.enum(['mainnet', 'devnet']),
	token_mint:  z.string().min(32).max(44),
	task_id:     z.string().min(1).max(128),
	detail:      z.record(z.unknown()).optional(),
});

export const handleAttestEvent = wrap(async (req, res) => {
	if (cors(req, res, { methods: 'POST,OPTIONS' })) return;
	if (!method(req, res, ['POST'])) return;

	const startedAt = Date.now();
	const rl = await limits.authIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	const secret = process.env.PUMPKIT_WEBHOOK_SECRET;
	if (!secret) return error(res, 500, 'internal', 'webhook secret not configured');

	const raw = await readBuffered(req);
	const verdict = verifyPumpkitSignature({
		secret,
		timestamp: req.headers['x-pumpkit-timestamp'],
		signature: req.headers['x-pumpkit-signature'],
		raw,
	});
	if (!verdict.ok) return error(res, 401, 'unauthorized', `invalid webhook signature (${verdict.reason})`);

	let parsed;
	try { parsed = JSON.parse(raw.toString('utf8')); } catch { return error(res, 400, 'validation_error', 'invalid JSON'); }
	const body = parse(attestEventSchema, parsed);

	const [agent] = await sql`select id, user_id from agent_identities where meta->'onchain'->>'sol_asset' = ${body.agent_asset} or meta->>'sol_mint_address' = ${body.agent_asset} limit 1`;
	if (!agent) return error(res, 404, 'not_found', 'agent_asset not registered');

	const result = await mintAttestation({
		event_id:    body.event_id,
		event_type:  body.event_type,
		source:      `pumpkit.${body.event_type === 'cto_detected' ? 'cto' : body.event_type === 'whale_trade' ? 'whale' : body.event_type}`,
		agent_asset: body.agent_asset,
		network:     body.network,
		token_mint:  body.token_mint,
		task_id:     body.task_id,
		detail:      body.detail,
		attester:    loadAttesterKeypair(),
	});

	const baseLog = { userId: agent.user_id, agentId: agent.id, kind: 'attest_event', tool: `pumpkit.${body.event_type}`, latencyMs: Date.now() - startedAt, meta: { network: body.network, event_id: body.event_id, signature: result.signature } };
	const { recordEvent } = await import('../../_lib/usage.js');

	if (result.status === 'minted') {
		recordEvent({ ...baseLog, status: 'ok', meta: { ...baseLog.meta, kind: result.kind } });
		return json(res, 201, { data: { signature: result.signature, kind: result.kind, deduped: false } });
	}
	if (result.status === 'deduped') {
		recordEvent({ ...baseLog, status: 'deduped' });
		return json(res, 200, { data: { signature: result.signature, deduped: true } });
	}
	recordEvent({ ...baseLog, status: 'in_progress' });
	return json(res, 202, { data: { deduped: true, status: 'in_progress' } });
});

// ── solana-validate (write: glTF/schema validation attestation) ────────────────

import { attestValidationSolana, platformValidatorAddress, SolanaAttestError } from '../../_lib/solana-validation-attest.js';
import { SUBKIND_GLB_SCHEMA } from '../../_lib/solana-attestations.js';

const SOLANA_ATTEST_ERROR_STATUS = {
	unsupported_network: 400,
	invalid_asset: 400,
	invalid_glb_url: 400,
	glb_fetch_failed: 502,
	glb_too_large: 413,
	attester_key_not_configured: 500,
	record_failed: 502,
};

const validateSchema = z.object({
	asset_pubkey: z.string().min(32).max(44),
	network:      z.enum(['mainnet', 'devnet']).default('mainnet'),
	glb_url:      z.string().url().optional(),
});

export const handleValidate = wrap(async (req, res) => {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const user = await getSessionUser(req);
	if (!user) return error(res, 401, 'unauthorized', 'sign in required');

	const rl = await limits.authIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	const body = parse(validateSchema, await readJson(req));
	const { asset_pubkey, network } = body;
	try { new PublicKey(asset_pubkey); } catch { return error(res, 400, 'validation_error', 'invalid asset pubkey'); }

	// Ownership: the agent must belong to the signed-in user (mirrors handleEdit).
	const [agent] = await sql`select id, avatar_id from agent_identities where (meta->>'sol_mint_address') = ${asset_pubkey} and user_id = ${user.id} and deleted_at is null limit 1`;
	if (!agent) return error(res, 404, 'not_found', 'agent not found for your account');

	// Resolve the GLB to validate: explicit glb_url wins; otherwise the agent's
	// avatar GLB. validateGlb SSRF-guards whatever URL we pass.
	let glbUrl = body.glb_url || null;
	if (!glbUrl && agent.avatar_id) {
		const [av] = await sql`select storage_key from avatars where id = ${agent.avatar_id} and deleted_at is null limit 1`;
		if (av?.storage_key) glbUrl = publicUrl(av.storage_key);
	}
	if (!glbUrl) return error(res, 422, 'no_model', 'agent has no GLB to validate — attach an avatar or pass glb_url');

	let result;
	try {
		result = await attestValidationSolana({
			network,
			agentAsset: asset_pubkey,
			glbUrl,
			validatedAt: new Date().toISOString(),
		});
	} catch (e) {
		if (e instanceof SolanaAttestError) {
			const status = SOLANA_ATTEST_ERROR_STATUS[e.code] || 500;
			if (status >= 500) console.error('[agents/solana] attest failed', e.code, e?.message);
			return respondError(res, status, e.code, e);
		}
		throw e;
	}

	const { recordEvent } = await import('../../_lib/usage.js');
	recordEvent({
		userId: user.id, agentId: agent.id, kind: 'solana_validation', tool: 'glb-schema',
		status: 'ok', meta: { network, signature: result.signature, passed: result.passed, deduped: result.status === 'deduped' },
	});

	return json(res, result.status === 'deduped' ? 200 : 201, {
		ok: true,
		passed: result.passed,
		signature: result.signature,
		proof_hash: result.proofHash,
		proof_uri: result.proofUri,
		model_sha256: result.modelSha256,
		kind: result.kind,
		subkind: SUBKIND_GLB_SCHEMA,
		validator: result.validator,
		network,
		asset_pubkey,
		deduped: result.status === 'deduped',
		explorer: `https://explorer.solana.com/tx/${result.signature}${network === 'devnet' ? '?cluster=devnet' : ''}`,
	});
});

// ── solana-validation (read: latest + history of glTF/schema validations) ──────

export const handleValidation = wrap(async (req, res) => {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;

	const rl = await limits.authedReadIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	const url     = new URL(req.url, `http://${req.headers.host}`);
	const asset   = url.searchParams.get('asset');
	const network = url.searchParams.get('network') === 'mainnet' ? 'mainnet' : 'devnet';
	const limit   = Math.min(Number(url.searchParams.get('limit') || 25), 200);
	const force   = url.searchParams.get('refresh') === '1';

	if (!asset) return error(res, 400, 'validation_error', 'asset query param required');
	try { new PublicKey(asset); } catch { return error(res, 400, 'validation_error', 'invalid asset pubkey'); }

	// Refresh-on-demand so a just-recorded validation is visible immediately.
	let [cursor] = await sql`select last_indexed_at from solana_attestations_cursor where agent_asset = ${asset} limit 1`;
	if (!cursor || force) {
		const [a] = await sql`select wallet_address as owner from agent_identities where meta->>'sol_mint_address' = ${asset} and deleted_at is null limit 1`;
		try { await crawlAgentAttestations({ agentAsset: asset, network, ownerWallet: a?.owner || null }); } catch {}
		[cursor] = await sql`select last_indexed_at from solana_attestations_cursor where agent_asset = ${asset} limit 1`;
	}

	// Only the platform attester's memos are model validations; anyone can post a
	// memo with the same shape, so an unfiltered read would let any wallet award
	// any agent the badge. No configured attester means no rows, never all rows.
	const validator = platformValidatorAddress();
	const rows = validator
		? await sql`
			select signature, slot, block_time, attester, payload, verified, revoked, disputed
			from solana_attestations
			where agent_asset = ${asset} and network = ${network}
			  and kind = 'threews.validation.v1'
			  and payload->>'subkind' = ${SUBKIND_GLB_SCHEMA}
			  and attester = ${validator}
			  and revoked = false
			order by slot desc nulls first, block_time desc
			limit ${limit}
		`
		: [];

	const history = rows.map((r) => ({
		signature: r.signature,
		slot: r.slot,
		block_time: r.block_time,
		validator: r.attester,
		passed: r.payload?.passed === true,
		proof_hash: r.payload?.proof_hash || null,
		proof_uri: r.payload?.proof_uri || null,
		model_sha256: r.payload?.model_sha256 || null,
		verified: r.verified,
		disputed: r.disputed,
		explorer: `https://explorer.solana.com/tx/${r.signature}${network === 'devnet' ? '?cluster=devnet' : ''}`,
	}));

	return json(res, 200, {
		agent: asset,
		network,
		kind: SUBKIND_GLB_SCHEMA,
		latest: history[0] || null,
		count: history.length,
		history,
		last_indexed_at: cursor?.last_indexed_at || null,
	}, { 'cache-control': 'public, max-age=30', 'access-control-allow-origin': '*' });
});

// ── solana-metadata ──────────────────────────────────────────────────────────

export const handleMetadata = wrap(async (req, res) => {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;

	const url     = new URL(req.url, `http://${req.headers.host}`);
	const network = url.searchParams.get('network') === 'devnet' ? 'devnet' : 'mainnet';
	let   asset   = url.searchParams.get('asset');
	if (asset) { try { new PublicKey(asset); } catch { asset = null; } }

	// Defaults come from the query (mint-time, agent not yet in the DB). Once the
	// agent is registered + confirmed, we serve its live name/skills/avatar.
	let name        = url.searchParams.get('name') || 'Agent';
	let description = url.searchParams.get('desc') || '';
	let skills      = [];
	let ownerAddress = null;
	let avatarId    = null;
	let image;          // real avatar thumbnail (PNG) when available
	let animationUrl;   // real avatar GLB when available

	if (asset) {
		const [a] = await sql`select name, description, skills, wallet_address as owner, avatar_id from agent_identities where meta->>'sol_mint_address' = ${asset} and deleted_at is null limit 1`;
		if (a) {
			name         = a.name || name;
			description  = a.description || description;
			skills       = a.skills || [];
			ownerAddress = a.owner || null;
			avatarId     = a.avatar_id || null;
			if (a.avatar_id) {
				const [av] = await sql`select storage_key, thumbnail_key from avatars where id = ${a.avatar_id} and deleted_at is null limit 1`;
				image = thumbnailUrl(av?.thumbnail_key) || image;
				if (av?.storage_key) animationUrl = publicUrl(av.storage_key);
			}
		}
	}

	// Prep bakes the resolved avatar media into the mint URI (img/anim) so the
	// manifest is complete on the FIRST fetch — before the agent row above
	// exists. The live DB values (when present) win; these are the fallback.
	// Only http(s)/ipfs URLs are honoured: they are echoed into JSON, never
	// fetched server-side, so this can't be turned into an SSRF vector.
	const SAFE_MEDIA = /^(https?:|ipfs:)/i;
	if (!image) { const q = url.searchParams.get('img'); if (q && SAFE_MEDIA.test(q)) image = q; }
	if (!animationUrl) { const q = url.searchParams.get('anim'); if (q && SAFE_MEDIA.test(q)) animationUrl = q; }

	const manifest = buildAgentManifest({
		name,
		description,
		image,
		animationUrl,
		externalUrl: asset ? `${env.APP_ORIGIN}/agent-passport.html?asset=${asset}&network=${network}` : undefined,
		avatarId,
		skills,
		ownerAddress,
	});

	return json(res, 200, manifest, { 'cache-control': 'public, max-age=300', 'access-control-allow-origin': '*' });
});

// ── solana-card ───────────────────────────────────────────────────────────────

export const handleCard = wrap(async (req, res) => {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;

	const url = new URL(req.url, `http://${req.headers.host}`);
	const asset = url.searchParams.get('asset');
	if (!asset) return error(res, 400, 'validation_error', 'asset required');
	try { new PublicKey(asset); } catch { return error(res, 400, 'validation_error', 'invalid asset pubkey'); }

	const [a] = await sql`select id, name, description, skills, wallet_address as owner, meta, avatar_id from agent_identities where meta->>'sol_mint_address' = ${asset} and deleted_at is null limit 1`;
	if (!a) return error(res, 404, 'not_found', 'agent not found');

	const network = a.meta?.network || 'mainnet';
	const origin = env.APP_ORIGIN;

	// Sections sourced from independent reads below. A read that throws on a
	// transient DB error is recorded here so the response can tell the client
	// "temporarily unavailable" apart from a genuine "no data" (null), instead of
	// silently conflating the two.
	const degraded = [];

	let pumpfun = null;
	try {
		const rows = await sql`select kind, count(*)::int as n, max(seen_at) as last_seen from pumpfun_signals where agent_asset = ${asset} group by kind`;
		if (rows.length > 0) {
			const byKind = {};
			let total = 0, last = null;
			for (const r of rows) {
				byKind[r.kind] = { count: r.n, last_seen: r.last_seen };
				total += r.n;
				if (!last || (r.last_seen && r.last_seen > last)) last = r.last_seen;
			}
			pumpfun = { signal_count: total, by_kind: byKind, last_seen: last, feed_url: `${origin}/api/agents/pumpfun-feed` };
		}
	} catch (err) {
		degraded.push('pumpfun');
		console.warn('[agent-card] pumpfun signals read failed:', err?.message || err);
	}

	let token_stats = null;
	try {
		const [s] = await sql`select s.graduated, s.bonding_curve, s.amm, s.last_signature, s.last_signature_at, s.recent_tx_count, s.refreshed_at, m.mint, m.network from pump_agent_stats s join pump_agent_mints m on m.id = s.mint_id where m.mint = ${asset} limit 1`;
		if (s) token_stats = { mint: s.mint, network: s.network, graduated: s.graduated, bonding_curve: s.bonding_curve, amm: s.amm, last_signature: s.last_signature, last_signature_at: s.last_signature_at, recent_tx_count: s.recent_tx_count, refreshed_at: s.refreshed_at };
	} catch (err) {
		degraded.push('token_stats');
		console.warn('[agent-card] token_stats read failed:', err?.message || err);
	}

	let validation = null;
	try {
		// Platform-signed only, for the same reason as handleValidation above.
		const validator = platformValidatorAddress();
		const [v] = validator
			? await sql`select signature, attester, payload, block_time from solana_attestations where agent_asset = ${asset} and network = ${network} and kind = 'threews.validation.v1' and payload->>'subkind' = ${SUBKIND_GLB_SCHEMA} and attester = ${validator} and revoked = false order by slot desc nulls first, block_time desc limit 1`
			: [];
		if (v) validation = { passed: v.payload?.passed === true, proof_hash: v.payload?.proof_hash || null, proof_uri: v.payload?.proof_uri || null, validator: v.attester, signature: v.signature, validated_at: v.block_time };
	} catch (err) {
		degraded.push('validation');
		console.warn('[agent-card] validation read failed:', err?.message || err);
	}

	return json(res, 200, {
		schema_version: '1.0',
		name: a.name,
		description: a.description,
		capabilities: {
			extensions: [
				{
					uri: 'https://github.com/google-a2a/a2a-x402/v0.1',
					description: 'Supports payments using the x402 protocol for on-chain settlement.',
					required: true,
				},
			],
		},
		identity: {
			chain: 'solana', network, asset_pubkey: asset, owner: a.owner,
			passport_url: `${origin}/agent-passport.html?asset=${asset}&network=${network}`,
			...(a.meta?.vanity_prefix ? { vanity_prefix: a.meta.vanity_prefix } : {}),
			...(a.meta?.solana_address ? { operator_wallet: { address: a.meta.solana_address, ...(a.meta.solana_vanity_prefix ? { vanity_prefix: a.meta.solana_vanity_prefix } : {}), ...(a.meta.solana_wallet_source ? { source: a.meta.solana_wallet_source } : {}) } } : {}),
		},
		skills: a.skills || [],
		endpoints: {
			chat: `${origin}/api/agents/${a.id}/chat`,
			a2a_paid: `${origin}/api/agents/a2a-paid`,
			attestations: `${origin}/api/agents/solana-attestations?asset=${asset}&network=${network}`,
			reputation: `${origin}/api/agents/solana-reputation?asset=${asset}&network=${network}`,
			validation: `${origin}/api/agents/solana-validation?asset=${asset}&network=${network}`,
			...(token_stats ? { quote: `${origin}/api/pump/quote?mint=${asset}&network=${network}`, price_history: `${origin}/api/agents/solana-price-history?asset=${asset}&network=${network}` } : {}),
		},
		attestation: {
			schemas_url: `${origin}/.well-known/agent-attestation-schemas`,
			transport: 'spl-memo',
			memo_program: 'MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr',
			usage: 'Sign an SPL Memo tx with one of the published schemas as JSON, including this asset_pubkey as a non-signer key.',
		},
		...(validation ? { validation } : {}),
		...(pumpfun ? { pumpfun } : {}),
		...(token_stats ? { token_stats } : {}),
		...(degraded.length ? { degraded } : {}),
	}, { 'cache-control': degraded.length ? 'no-store' : 'public, max-age=120', 'access-control-allow-origin': '*' });
});

// ── solana-price-history ──────────────────────────────────────────────────────

export const handlePriceHistory = wrap(async (req, res) => {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;

	const url = new URL(req.url, `http://${req.headers.host}`);
	const asset = url.searchParams.get('asset');
	const network = url.searchParams.get('network') === 'devnet' ? 'devnet' : 'mainnet';
	const hours = Math.max(1, Math.min(720, Number(url.searchParams.get('hours') || 24)));
	if (!asset) return error(res, 400, 'validation_error', 'asset required');

	const [mintRow] = await sql`select id from pump_agent_mints where mint=${asset} and network=${network} limit 1`;
	if (!mintRow) return error(res, 404, 'not_found', 'mint not tracked');

	const points = await sql`select ts, sol_per_token, market_cap_lamports, source from pump_agent_price_points where mint_id=${mintRow.id} and ts > now() - (${hours} || ' hours')::interval order by ts asc`;

	return json(res, 200, {
		mint: asset, network, hours, point_count: points.length,
		points: points.map((p) => ({ ts: p.ts, sol_per_token: p.sol_per_token, market_cap_lamports: p.market_cap_lamports?.toString?.() ?? p.market_cap_lamports, source: p.source })),
	}, { 'cache-control': 'public, max-age=60', 'access-control-allow-origin': '*' });
});

// ── solana-register-prep ──────────────────────────────────────────────────────

import { createUmi } from '@metaplex-foundation/umi-bundle-defaults';
import { mplCore, create, ruleSet, updatePlugin, update, fetchAsset, fetchCollection } from '@metaplex-foundation/mpl-core';
import { generateSigner, publicKey as umiPublicKey, signerIdentity, createNoopSigner } from '@metaplex-foundation/umi';
import bs58 from 'bs58';
import { limits as _limits } from '../../_lib/rate-limit.js';
import { mplAgentIdentity, getAgentIdentityV2AccountDataSerializer, findAgentIdentityV1Pda } from '@metaplex-foundation/mpl-agent-registry';
import { buildPartiallySignedV1Transaction, SOLANA_TRANSACTION_V1 } from '../../_lib/solana/transaction-v1.js';

const BASE58_RE = /^[1-9A-HJ-NP-Za-km-z]+$/;
const VANITY_FREE_THRESHOLD = 5;

const registerPrepSchema = z.object({
	name:           z.string().trim().min(1).max(60),
	description:    z.string().trim().max(280).default(''),
	avatar_id:      z.string().uuid().optional(),
	wallet_address: z.string().min(32).max(44),
	metadata_uri:   z.string().url().optional(),
	network:        z.enum(['mainnet', 'devnet']).default('mainnet'),
	asset_pubkey:   z.string().min(32).max(44).optional(),
	vanity_prefix:  z.string().min(1).max(6).optional(),
	// 1 only when the signing wallet advertises Wallet Standard v1 support;
	// every other wallet keeps the v0 envelope.
	transaction_version: z.union([z.literal(0), z.literal(1)]).default(0),
});

export const handleRegisterPrep = wrap(async (req, res) => {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const user = await getSessionUser(req);
	if (!user) return error(res, 401, 'unauthorized', 'sign in required');

	const rl = await limits.authIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	const body = parse(registerPrepSchema, await readJson(req));
	const { name, description, avatar_id, wallet_address, network, asset_pubkey, vanity_prefix, transaction_version } = body;

	const [walletRow] = await sql`select id from user_wallets where user_id = ${user.id} and address = ${wallet_address} and chain_type = 'solana' limit 1`;
	if (!walletRow) return error(res, 403, 'forbidden', 'wallet not linked to your account');

	// Resolve the avatar's media up front so it can be baked into the metadata
	// URI as query-param fallbacks (img/anim). This makes the off-chain JSON
	// complete from the very FIRST indexer fetch — before solana-register-confirm
	// writes the agent row that handleMetadata normally joins against — closing
	// the race where a DAS provider caches a body-less, image-less manifest.
	let avatarImg = null;
	let avatarAnim = null;
	if (avatar_id) {
		const [av] = await sql`select id, storage_key, thumbnail_key from avatars where id=${avatar_id} and owner_id=${user.id} and deleted_at is null limit 1`;
		if (!av) return error(res, 404, 'not_found', 'avatar not found');
		avatarImg = thumbnailUrl(av.thumbnail_key) || avatarImg;
		if (av.storage_key) avatarAnim = publicUrl(av.storage_key);
	}

	if (vanity_prefix && !asset_pubkey) return error(res, 400, 'validation_error', 'vanity_prefix requires asset_pubkey');
	if (asset_pubkey) {
		if (!BASE58_RE.test(asset_pubkey)) return error(res, 400, 'validation_error', 'asset_pubkey is not valid base58');
		if (vanity_prefix) {
			if (!BASE58_RE.test(vanity_prefix)) return error(res, 400, 'validation_error', 'vanity_prefix is not valid base58');
			if (!asset_pubkey.startsWith(vanity_prefix)) return error(res, 400, 'validation_error', 'asset_pubkey does not start with vanity_prefix');
			if (vanity_prefix.length >= VANITY_FREE_THRESHOLD && (user.plan ?? 'free') === 'free') {
				return error(res, 402, 'payment_required', `vanity prefixes of ${VANITY_FREE_THRESHOLD}+ characters require a paid plan`);
			}
		}
	}

	// Pick the first non-cooling endpoint from the full Helius → Alchemy → Ankr →
	// public chain. When Helius is parked in _endpointCooldown (e.g. quota 429)
	// this silently skips it rather than burning a 503 on the user.
	const rpcEndpoints = solanaRpcEndpoints(network);
	const liveEndpoint = rpcEndpoints.find((ep) => !isEndpointCooling(ep)) || rpcEndpoints[0];

	const appOrigin = env.APP_ORIGIN;

	// Resolve the asset signer up front so its pubkey can be baked into the
	// metadata URI and the on-chain attributes before the tx is built.
	// generateSigner is local crypto (no RPC), so this is safe even if the
	// configured RPC is unreachable.
	const assetSigner = asset_pubkey
		? createNoopSigner(umiPublicKey(asset_pubkey))
		: generateSigner(createUmi(liveEndpoint).use(mplCore()));
	const assetPubkey = assetSigner.publicKey;

	const passportUrl = `${appOrigin}/agent-passport.html?asset=${assetPubkey}&network=${network}`;
	const metadataUri = body.metadata_uri
		|| `${appOrigin}/api/agents/solana-metadata?asset=${assetPubkey}&network=${network}`
			+ `&name=${encodeURIComponent(name)}&desc=${encodeURIComponent(description)}`
			+ (avatarImg ? `&img=${encodeURIComponent(avatarImg)}` : '')
			+ (avatarAnim ? `&anim=${encodeURIComponent(avatarAnim)}` : '');

	// On-chain brand written into the asset account itself: three.ws identity,
	// our links, and the $THREE mint (Attributes plugin) + an enforced 5%
	// secondary-sale royalty to the owner (Royalties plugin).
	const attributeList = buildAgentOnchainAttributes({
		name,
		agentUrl: passportUrl,
		createdAt: new Date().toISOString(),
	});
	const royalty = agentRoyaltyConfig(wallet_address);
	const plugins = [
		{ type: 'Attributes', attributeList },
		...(royalty
			? [{
					type: 'Royalties',
					basisPoints: royalty.basisPoints,
					creators: royalty.creators.map((c) => ({ address: umiPublicKey(c.address), percentage: c.percentage })),
					ruleSet: ruleSet('None'),
				}]
			: []),
	];

	// If a three.ws Agent Collection is deployed for this network, mint the asset
	// INTO it so the asset's update authority resolves to the collection (held by
	// three.ws) — the authority-managed model that lets us edit on-chain metadata
	// on the owner's behalf. Adding to a collection requires the collection
	// authority to co-sign, so the server partial-signs with it; the owner still
	// pays + signs in their wallet. When no collection is configured we fall back
	// to the legacy standalone mint (owner = update authority) unchanged.
	const collectionAddr = getAgentCollection(network);
	if (collectionAddr) {
		try {
			loadCollectionAuthorityKeypair();
		} catch (e) {
			return error(res, 500, 'authority_unconfigured', e.message);
		}
	}

	const buildTx = async (rpc) => {
		// Failover Connection rather than the bare `rpc` URL: buildAndSign's
		// getLatestBlockhash rotates across the endpoint chain, so a single node's
		// malformed/empty 200 body fails over to a healthy provider instead of
		// throwing `StructError: … but received:` and failing the whole registration.
		const umi = createUmi(solanaConnection({ url: rpc, network })).use(mplCore());
		const ownerPubkey = umiPublicKey(wallet_address);
		umi.use(signerIdentity(createNoopSigner(ownerPubkey)));
		const createArgs = { asset: assetSigner, owner: ownerPubkey, name, uri: metadataUri, plugins };
		if (collectionAddr) {
			createArgs.collection = umiPublicKey(collectionAddr);
			createArgs.authority = collectionAuthoritySigner(umi);
		}
		const builder = create(umi, createArgs);
		if (transaction_version === SOLANA_TRANSACTION_V1) {
			return buildPartiallySignedV1Transaction({
				instructions: builder.getInstructions(),
				signers: builder.getSigners(umi),
				feePayer: wallet_address,
				lifetime: await umi.rpc.getLatestBlockhash({ commitment: 'confirmed' }),
				clientSigners: asset_pubkey ? [asset_pubkey] : [],
			});
		}
		const tx = await builder.buildAndSign(umi);
		return umi.transactions.serialize(tx);
	};

	let txBytes;
	try {
		txBytes = await buildTx(liveEndpoint);
	} catch (rpcErr) {
		console.error('[solana/register-prep] RPC error after all fallbacks:', rpcErr.message);
		return error(res, 503, 'rpc_unavailable', 'Solana RPC temporarily unavailable — try again in a moment.');
	}

	const txBase64 = Buffer.from(txBytes).toString('base64');

	const prepId = await randomToken(24);
	const expiresAt = new Date(Date.now() + 30 * 60 * 1000);

	await sql`insert into agent_registrations_pending (user_id, cid, metadata_uri, payload, expires_at) values (${user.id}, ${assetSigner.publicKey}, ${metadataUri}, ${JSON.stringify({ name, description, avatar_id, wallet_address, asset_pubkey: assetSigner.publicKey, network, prep_id: prepId, vanity_prefix: vanity_prefix || null, collection: collectionAddr || null, transaction_version })}::jsonb, ${expiresAt})`;

	return json(res, 201, {
		prep_id: prepId,
		asset_pubkey: assetSigner.publicKey,
		tx_base64: txBase64,
		transaction_version,
		network,
		metadata_uri: metadataUri,
		expires_at: expiresAt.toISOString(),
		instructions: 'Sign and submit the transaction with your Solana wallet, then call /api/agents/solana-register-confirm with the tx signature.',
	});
});

// ── solana-register-confirm ───────────────────────────────────────────────────

const registerConfirmSchema = z.object({
	tx_signature:   z.string().min(80).max(100),
	asset_pubkey:   z.string().min(32).max(44),
	wallet_address: z.string().min(32).max(44),
	network:        z.enum(['mainnet', 'devnet']).default('mainnet'),
	name:           z.string().trim().min(1).max(60).optional(),
	description:    z.string().trim().max(500).optional(),
	avatar_id:      z.string().uuid().optional(),
});

export const handleRegisterConfirm = wrap(async (req, res) => {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const user = await getSessionUser(req);
	if (!user) return error(res, 401, 'unauthorized', 'sign in required');

	const rl = await limits.authIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	const body = parse(registerConfirmSchema, await readJson(req));
	const { tx_signature, asset_pubkey, wallet_address, network } = body;

	const [walletRow] = await sql`select id from user_wallets where user_id=${user.id} and address=${wallet_address} and chain_type='solana' limit 1`;
	if (!walletRow) return error(res, 403, 'forbidden', 'wallet not linked to your account');

	const rpcEndpoint = network === 'devnet'
		? (process.env.SOLANA_RPC_URL_DEVNET || 'https://api.devnet.solana.com')
		: (process.env.SOLANA_RPC_URL || 'https://api.mainnet-beta.solana.com');

	const connection = solanaConnection({ url: rpcEndpoint, commitment: 'confirmed' });
	let tx;
	try { tx = await connection.getParsedTransaction(tx_signature, { maxSupportedTransactionVersion: 1, commitment: 'confirmed' }); }
	catch { return error(res, 422, 'tx_not_found', 'transaction not found — try again after a few seconds'); }
	if (!tx) return error(res, 422, 'tx_not_found', 'transaction not found');
	if (tx.meta?.err) return error(res, 422, 'tx_failed', 'transaction failed on-chain');

	const accountKeys = tx.transaction.message.accountKeys.map((k) => k.pubkey?.toString());
	if (!accountKeys.includes(asset_pubkey)) return error(res, 422, 'asset_not_in_tx', 'The asset pubkey was not found in the transaction accounts');

	// A tx that merely mentions the asset proves nothing. Require that the
	// linked wallet signed this tx, and that the asset exists on-chain as a
	// Metaplex Core asset owned by that wallet, before writing a public
	// deployments-feed row for it.
	const signerKeys = tx.transaction.message.accountKeys
		.filter((k) => k.signer)
		.map((k) => k.pubkey?.toString());
	if (!signerKeys.includes(wallet_address)) {
		return error(res, 422, 'not_signer', 'the linked wallet did not sign this transaction');
	}
	const MPL_CORE_PROGRAM_ID = 'CoREENxT6tW1HoK8ypY1SxRMZTcVPm7R94rH4PZNhX7d';
	let assetInfo;
	try {
		assetInfo = await connection.getAccountInfo(new PublicKey(asset_pubkey));
	} catch {
		return error(res, 422, 'asset_not_found', 'could not load the asset account; try again shortly');
	}
	if (!assetInfo) return error(res, 422, 'asset_not_found', 'asset account does not exist on-chain');
	if (assetInfo.owner?.toBase58() !== MPL_CORE_PROGRAM_ID) {
		return error(res, 422, 'not_core_asset', 'account is not a Metaplex Core asset');
	}
	// AssetV1 layout: key discriminator (1 = AssetV1), then the owner pubkey.
	if (assetInfo.data?.[0] !== 1 || assetInfo.data.length < 33) {
		return error(res, 422, 'not_core_asset', 'account is not a Metaplex Core AssetV1');
	}
	const assetOwner = new PublicKey(assetInfo.data.subarray(1, 33)).toBase58();
	if (assetOwner !== wallet_address) {
		return error(res, 422, 'not_asset_owner', 'the asset is not owned by the linked wallet');
	}

	const [existing] = await sql`select id from agent_identities where (meta->>'sol_mint_address') = ${asset_pubkey} and deleted_at is null limit 1`;
	if (existing) return error(res, 409, 'conflict', 'agent already registered for this mint');

	const [pending] = await sql`select payload from agent_registrations_pending where user_id=${user.id} and payload->>'asset_pubkey'=${asset_pubkey} and expires_at > now() order by created_at desc limit 1`;
	const payload = pending?.payload || {};
	// A live prep pins the envelope the server built. A different version on
	// chain means the wallet re-encoded or replaced the prepared transaction.
	if (pending && tx.version !== (payload.transaction_version ?? 0)) {
		return error(res, 422, 'tx_wrong_version', `transaction version ${String(tx.version)} does not match the prepared v${payload.transaction_version ?? 0}`);
	}
	const name = body.name || payload.name || `Agent ${asset_pubkey.slice(0, 6)}`;
	const description = body.description || payload.description || '';
	const avatar_id = body.avatar_id || payload.avatar_id || null;

	const onchainBlock = {
		chain: network === 'devnet'
			? 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1'
			: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
		family: 'solana',
		cluster: network,
		tx_hash: tx_signature,
		onchain_id: null,
		contract_or_mint: asset_pubkey,
		wallet: wallet_address,
		metadata_uri: payload.metadata_uri || null,
		confirmed_at: new Date().toISOString(),
		transaction_version: tx.version,
	};
	const [agent] = await sql`insert into agent_identities (user_id, name, description, avatar_id, wallet_address, meta) values (${user.id}, ${name}, ${description}, ${avatar_id}, ${wallet_address}, ${JSON.stringify({ chain_type: 'solana', network, sol_mint_address: asset_pubkey, tx_signature, onchain: onchainBlock, ...(payload.vanity_prefix ? { vanity_prefix: payload.vanity_prefix } : {}), ...(payload.collection ? { collection: payload.collection, update_authority: 'threews' } : {}) })}::jsonb) returning id, name, description, wallet_address, meta, created_at`;

	await sql`delete from agent_registrations_pending where user_id=${user.id} and payload->>'asset_pubkey'=${asset_pubkey}`;

	// Best-effort glTF/schema validation attestation, recorded on-chain by the
	// platform validator. Mirrors the EVM auto-validation path: a failure here
	// (missing key, RPC trouble, no avatar GLB) must never fail the registration.
	let validation = null;
	try {
		if (avatar_id) {
			const [av] = await sql`select storage_key from avatars where id = ${avatar_id} and deleted_at is null limit 1`;
			if (av?.storage_key) {
				const r = await attestValidationSolana({
					network,
					agentAsset: asset_pubkey,
					glbUrl: publicUrl(av.storage_key),
					validatedAt: new Date().toISOString(),
				});
				validation = { passed: r.passed, signature: r.signature, proof_hash: r.proofHash, deduped: r.status === 'deduped' };
			}
		}
	} catch (e) {
		validation = { error: e.code || 'validation_failed' };
	}

	return json(res, 201, { ok: true, agent: { ...agent, home_url: `${env.APP_ORIGIN}/agents/${agent.id}` }, sol_mint_address: asset_pubkey, tx_signature, network, ...(validation ? { validation } : {}) });
});

// ── solana-collection-metadata ─────────────────────────────────────────────────
// Off-chain JSON for the three.ws Agent Collection account (its `uri`). Standard
// Metaplex collection metadata so wallets/explorers render it as a real
// collection that groups every deployed three.ws agent.

export const handleCollectionMetadata = wrap(async (req, res) => {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;

	const url = new URL(req.url, `http://${req.headers.host}`);
	const network = url.searchParams.get('network') === 'devnet' ? 'devnet' : 'mainnet';

	return json(
		res,
		200,
		{
			name: AGENT_COLLECTION.name,
			symbol: 'AGENT',
			description: AGENT_COLLECTION.description,
			image: THREE_WS.ogImage,
			external_url: THREE_WS.website,
			properties: {
				category: 'image',
				files: [{ uri: THREE_WS.ogImage, type: 'image/png' }],
			},
			platform: { name: THREE_WS.name, url: THREE_WS.website, x: THREE_WS.x, github: THREE_WS.github },
			network,
		},
		{ 'cache-control': 'public, max-age=3600', 'access-control-allow-origin': '*' },
	);
});

// ── skill-collection-metadata ───────────────────────────────────────────────
// Off-chain JSON for a per-agent skill NFT collection (the master identifier
// for every "skill ownership" NFT minted to buyers of that agent's skills).
// Pointed at by the collection's on-chain URI; see
// scripts/create-agent-collection.mjs. Resolvable by agent id so the document
// always reflects the agent's live name + avatar.

export const handleSkillCollectionMetadata = wrap(async (req, res) => {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;

	const url = new URL(req.url, `http://${req.headers.host}`);
	const network = url.searchParams.get('network') === 'devnet' ? 'devnet' : 'mainnet';
	const agentId = url.searchParams.get('agent');
	if (!agentId || !/^[0-9a-f-]{36}$/i.test(agentId)) {
		return error(res, 400, 'validation_error', 'agent (uuid) required');
	}

	const [agent] = await sql`select name, description, avatar_id, skill_collection_mint from agent_identities where id = ${agentId} and deleted_at is null limit 1`;
	if (!agent) return error(res, 404, 'not_found', 'agent not found');

	let image = THREE_WS.ogImage;
	if (agent.avatar_id) {
		const [av] = await sql`select thumbnail_key from avatars where id = ${agent.avatar_id} and deleted_at is null limit 1`;
		image = thumbnailUrl(av?.thumbnail_key) || image;
	}

	const name = `${agent.name} — Skills`;
	const description =
		`Verifiable on-chain ownership of skills offered by ${agent.name} on ${THREE_WS.name}. ` +
		`Each NFT in this collection certifies that its holder has purchased the named skill from this agent.`;

	return json(
		res,
		200,
		{
			name,
			symbol: skillCollectionSymbol(agent.name),
			description,
			image,
			external_url: `${env.APP_ORIGIN}/agents/${agentId}`,
			properties: {
				category: 'image',
				files: [{ uri: image, type: 'image/png' }],
			},
			platform: { name: THREE_WS.name, url: THREE_WS.website, x: THREE_WS.x, github: THREE_WS.github },
			agent_id: agentId,
			collection_mint: agent.skill_collection_mint || null,
			network,
		},
		{ 'cache-control': 'public, max-age=300', 'access-control-allow-origin': '*' },
	);
});

// ── skill-nft-metadata ──────────────────────────────────────────────────────
// Off-chain JSON for an individual "skill ownership" NFT minted to a buyer. The
// asset's on-chain URI points here; see api/_lib/skill-nft.js. Resolvable by
// (agent, skill) so the document always reflects the agent's live name + avatar.

export const handleSkillNftMetadata = wrap(async (req, res) => {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;

	const url = new URL(req.url, `http://${req.headers.host}`);
	const network = url.searchParams.get('network') === 'devnet' ? 'devnet' : 'mainnet';
	const agentId = url.searchParams.get('agent');
	const skill = (url.searchParams.get('skill') || '').trim().slice(0, 100);
	if (!agentId || !/^[0-9a-f-]{36}$/i.test(agentId)) {
		return error(res, 400, 'validation_error', 'agent (uuid) required');
	}
	if (!skill) return error(res, 400, 'validation_error', 'skill required');

	const [agent] = await sql`select name, avatar_id, skill_collection_mint from agent_identities where id = ${agentId} and deleted_at is null limit 1`;
	if (!agent) return error(res, 404, 'not_found', 'agent not found');

	let image = THREE_WS.ogImage;
	if (agent.avatar_id) {
		const [av] = await sql`select thumbnail_key from avatars where id = ${agent.avatar_id} and deleted_at is null limit 1`;
		image = thumbnailUrl(av?.thumbnail_key) || image;
	}

	const name = `${agent.name}: ${skill}`;
	const description =
		`On-chain proof of ownership and a perpetual license for the “${skill}” skill ` +
		`offered by ${agent.name} on ${THREE_WS.name}. Holding this NFT certifies the wallet ` +
		`purchased this skill and may invoke it.`;

	return json(
		res,
		200,
		{
			name,
			symbol: skillCollectionSymbol(agent.name),
			description,
			image,
			external_url: `${env.APP_ORIGIN}/agents/${agentId}`,
			attributes: [
				{ trait_type: 'Type', value: 'Skill License' },
				{ trait_type: 'Agent', value: agent.name },
				{ trait_type: 'Skill', value: skill },
				{ trait_type: 'Platform', value: THREE_WS.name },
			],
			properties: {
				category: 'image',
				files: [{ uri: image, type: 'image/png' }],
			},
			platform: { name: THREE_WS.name, url: THREE_WS.website, x: THREE_WS.x, github: THREE_WS.github },
			agent_id: agentId,
			skill,
			collection_mint: agent.skill_collection_mint || null,
			network,
		},
		{ 'cache-control': 'public, max-age=300', 'access-control-allow-origin': '*' },
	);
});

// ── solana-edit ───────────────────────────────────────────────────────────────
// Authority-managed edit of a deployed agent's ON-CHAIN metadata. The user owns
// the asset, but three.ws holds the collection update authority, so edits to the
// Attributes plugin (and the asset name) are signed + paid server-side by the
// three.ws authority — no owner-wallet round-trip. Only agents minted into the
// three.ws collection (meta.update_authority='threews') are editable this way;
// legacy standalone (owner-managed) assets are rejected with a clear message.

const editSchema = z
	.object({
		asset_pubkey: z.string().min(32).max(44),
		network:      z.enum(['mainnet', 'devnet']).default('mainnet'),
		name:         z.string().trim().min(1).max(60).optional(),
		description:  z.string().trim().max(280).optional(),
		skills:       z.array(z.string().regex(/^[a-z0-9-]{1,40}$/i)).max(16).optional(),
		avatar_id:    z.string().uuid().nullable().optional(),
	})
	.refine(
		(b) => b.name !== undefined || b.description !== undefined || b.skills !== undefined || b.avatar_id !== undefined,
		{ message: 'at least one editable field is required' },
	);

const base58Sig = (sig) => bs58.encode(sig);

export const handleEdit = wrap(async (req, res) => {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const user = await getSessionUser(req);
	if (!user) return error(res, 401, 'unauthorized', 'sign in required');

	const rl = await limits.authIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	const body = parse(editSchema, await readJson(req));
	const { asset_pubkey, network } = body;
	try { new PublicKey(asset_pubkey); } catch { return error(res, 400, 'validation_error', 'invalid asset pubkey'); }

	// Ownership: the agent must belong to the signed-in user.
	const [agent] = await sql`select id, name, description, avatar_id, wallet_address, meta from agent_identities where (meta->>'sol_mint_address') = ${asset_pubkey} and user_id = ${user.id} and deleted_at is null limit 1`;
	if (!agent) return error(res, 404, 'not_found', 'agent not found for your account');

	const collectionAddr = agent.meta?.collection || null;
	if (!collectionAddr || agent.meta?.update_authority !== 'threews') {
		return error(res, 409, 'not_authority_managed', 'this agent is owner-managed (minted before the three.ws collection); on-chain edits must be signed by the owner wallet');
	}

	if (body.avatar_id) {
		const [av] = await sql`select id from avatars where id=${body.avatar_id} and owner_id=${user.id} and deleted_at is null limit 1`;
		if (!av) return error(res, 404, 'not_found', 'avatar not found');
	}

	// Merge requested edits over current DB values. Skills are stored on-chain in
	// the Attributes plugin (and in the off-chain manifest), not as an
	// agent_identities column, so they are not written to the DB here.
	const next = {
		name: body.name ?? agent.name,
		description: body.description ?? agent.description,
		avatar_id: body.avatar_id === undefined ? agent.avatar_id : body.avatar_id,
	};

	const rpc = network === 'devnet'
		? (process.env.SOLANA_RPC_URL_DEVNET || 'https://api.devnet.solana.com')
		: (process.env.SOLANA_RPC_URL || 'https://api.mainnet-beta.solana.com');

	let umi;
	try {
		// Failover Connection rather than the bare `rpc` URL: every on-chain read
		// (fetchAsset/fetchCollection) and write (sendAndConfirm → getLatestBlockhash)
		// below rotates across the endpoint chain, so a single node's malformed/empty
		// 200 body fails over to a healthy provider instead of throwing
		// `StructError: … but received:` and failing the whole edit.
		umi = createUmi(solanaConnection({ url: rpc, network })).use(mplCore());
		umi.use(signerIdentity(collectionAuthoritySigner(umi)));
	} catch (e) {
		console.error('[agents/solana] authority/umi init failed', e?.message);
		return serverError(res, 500, 'authority_unconfigured', e);
	}

	const assetPk = umiPublicKey(asset_pubkey);
	const collectionPk = umiPublicKey(collectionAddr);
	const passportUrl = `${env.APP_ORIGIN}/agent-passport.html?asset=${asset_pubkey}&network=${network}`;

	// Only name/skills live in the on-chain Attributes plugin (and name in the
	// asset's name field). Description/avatar are served dynamically from the
	// metadata endpoint via the asset URI, so they need no on-chain write.
	const nameChanged = body.name !== undefined && body.name !== agent.name;
	const skillsChanged = body.skills !== undefined;

	const signatures = {};
	if (nameChanged || skillsChanged) {
		try {
			// Read current on-chain attributes so unedited fields (skills, the
			// original created timestamp) are preserved rather than dropped.
			const onchainAsset = await fetchAsset(umi, assetPk);
			const existingAttrs = onchainAsset.attributes?.attributeList || [];
			const attrMap = new Map(existingAttrs.map((a) => [a.key, a.value]));
			const existingSkills = attrMap.get('skills')
				? String(attrMap.get('skills')).split(',').filter(Boolean)
				: [];

			const attributeList = buildAgentOnchainAttributes({
				name: next.name,
				agentUrl: passportUrl,
				skills: body.skills ?? existingSkills,
				createdAt: attrMap.get('created') || undefined,
			});
			const attrRes = await updatePlugin(umi, {
				asset: assetPk,
				collection: collectionPk,
				plugin: { type: 'Attributes', attributeList },
			}).sendAndConfirm(umi, { confirm: { commitment: 'confirmed' } });
			signatures.attributes = base58Sig(attrRes.signature);

			// If the display name changed, update the asset's on-chain name too.
			if (nameChanged) {
				const onchainCollection = await fetchCollection(umi, collectionPk);
				const nameRes = await update(umi, {
					asset: onchainAsset,
					collection: onchainCollection,
					name: next.name,
				}).sendAndConfirm(umi, { confirm: { commitment: 'confirmed' } });
				signatures.name = base58Sig(nameRes.signature);
			}
		} catch (e) {
			console.error('[agents/solana] on-chain edit failed', e?.message || e);
			return serverError(res, 502, 'onchain_edit_failed', e);
		}
	}

	// Keep the off-chain row in sync (name/description/avatar are real columns).
	const [updated] = await sql`update agent_identities set name=${next.name}, description=${next.description}, avatar_id=${next.avatar_id}, updated_at=now() where id=${agent.id} returning id, name, description, avatar_id, wallet_address, meta, updated_at`;

	return json(res, 200, {
		ok: true,
		agent: { ...updated, home_url: `${env.APP_ORIGIN}/agents/${updated.id}` },
		asset_pubkey,
		network,
		signatures,
	});
});

// ── solana-reputation ─────────────────────────────────────────────────────────

export const handleReputation = wrap(async (req, res) => {
	if (cors(req, res, { methods: 'GET,OPTIONS', credentials: false })) return;
	if (!method(req, res, ['GET'])) return;

	const rl = await limits.authedReadIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	const url = new URL(req.url, `http://${req.headers.host}`);
	const asset = url.searchParams.get('asset');
	const network = url.searchParams.get('network') === 'mainnet' ? 'mainnet' : 'devnet';

	if (!asset) return error(res, 400, 'validation_error', 'asset query param required');
	try { new PublicKey(asset); } catch { return error(res, 400, 'validation_error', 'invalid asset pubkey'); }

	const [fb] = await sql`
		with feedback as (
			select f.signature, f.attester, f.disputed, f.revoked,
				(f.payload->>'score')::int as score, f.payload->>'task_id' as task_id,
				exists (select 1 from solana_attestations a where a.agent_asset = f.agent_asset and a.kind = 'threews.accept.v1' and a.payload->>'task_id' = f.payload->>'task_id' and a.verified = true and f.payload->>'task_id' is not null) as task_accepted,
				exists (select 1 from solana_credentials c where c.subject = f.attester and c.network = f.network and c.kind = 'threews.verified-client.v1' and c.closed = false and (c.expiry is null or c.expiry > now())) as credentialed,
				((f.payload->>'source' like 'pumpkit.%' or f.payload->>'source' like 'pumpfun.%') and exists (select 1 from solana_attest_event_claims ec where ec.signature = f.signature and ec.network = f.network)) as event_attested
			from solana_attestations f where f.agent_asset = ${asset} and f.network = ${network} and f.kind = 'threews.feedback.v1' and f.revoked = false
		),
		per_attester as (select attester, avg(score)::float as score_avg, bool_or(task_accepted) as any_verified, bool_or(credentialed) as any_credentialed, bool_or(event_attested) as any_event_attested from feedback group by attester)
		select
			(select count(*)::int from feedback) as total,
			(select count(*) filter (where task_accepted)::int from feedback) as verified,
			(select count(*) filter (where credentialed)::int from feedback) as credentialed,
			(select count(*) filter (where event_attested)::int from feedback) as event_attested,
			(select count(*) filter (where disputed)::int from feedback) as disputed,
			(select coalesce(avg(score), 0)::float from feedback) as score_avg,
			(select coalesce(avg(score) filter (where task_accepted), 0)::float from feedback) as score_avg_verified,
			(select coalesce(avg(score) filter (where credentialed), 0)::float from feedback) as score_avg_credentialed,
			(select coalesce(avg(score) filter (where event_attested), 0)::float from feedback) as score_avg_event_attested,
			(select count(*)::int from per_attester) as unique_attesters,
			(select count(*) filter (where any_verified)::int from per_attester) as unique_verified_attesters,
			(select count(*) filter (where any_credentialed)::int from per_attester) as unique_credentialed_attesters,
			(select coalesce(avg(score_avg), 0)::float from per_attester) as score_avg_weighted,
			(select coalesce(avg(score_avg) filter (where any_verified), 0)::float from per_attester) as score_avg_weighted_verified,
			(select coalesce(avg(score_avg) filter (where any_credentialed), 0)::float from per_attester) as score_avg_weighted_credentialed
	`;

	const [val] = await sql`select count(*) filter (where (payload->>'passed')::bool)::int as passed, count(*) filter (where not (payload->>'passed')::bool)::int as failed, count(*) filter (where (payload->>'passed')::bool and (payload->>'source' like 'pumpkit.%' or payload->>'source' like 'pumpfun.%'))::int as event_passed, count(*) filter (where not (payload->>'passed')::bool and (payload->>'source' like 'pumpkit.%' or payload->>'source' like 'pumpfun.%'))::int as event_failed from solana_attestations where agent_asset = ${asset} and network = ${network} and kind = 'threews.validation.v1' and revoked = false`;

	const [auditedVal] = await sql`select count(*) filter (where (data->>'passed')::bool)::int as passed, count(*) filter (where not (data->>'passed')::bool)::int as failed from solana_credentials where subject = ${asset} and network = ${network} and kind = 'threews.audited-validation.v1' and closed = false and (expiry is null or expiry > now())`;

	const [counts] = await sql`select count(*) filter (where kind = 'threews.task.v1')::int as tasks_offered, count(*) filter (where kind = 'threews.accept.v1' and verified)::int as tasks_accepted, count(*) filter (where kind = 'threews.dispute.v1' and verified)::int as disputes_filed, count(*) filter (where revoked)::int as revoked_count from solana_attestations where agent_asset = ${asset} and network = ${network}`;

	const [cursor] = await sql`select last_indexed_at from solana_attestations_cursor where agent_asset = ${asset} limit 1`;

	// Net, not gross: a settled position's conviction is retired the moment the
	// escrow's threews.unstake.v1 memo lands. Spec §3.3 (specs/REPUTATION_STAKING_MARKET.md).
	const stakeAgg = await netStakeForAgent({ asset, network });

	let pumpfunRows = [];
	try {
		pumpfunRows = await sql`select kind, count(*)::int as n, coalesce(sum(weight), 0)::float as w from pumpfun_signals where agent_asset = ${asset} group by kind`;
	} catch {}
	const pumpfunByKind = {};
	let pumpfunTotal = 0, pumpfunWeight = 0;
	for (const r of pumpfunRows) {
		pumpfunByKind[r.kind] = { count: r.n, weight: Number(r.w.toFixed(3)) };
		pumpfunTotal += r.n; pumpfunWeight += r.w;
	}

	const [actRow] = await sql`select s.graduated, s.recent_tx_count, (select count(*)::int from pump_agent_trades t where t.mint_id = m.id) as trade_count from pump_agent_stats s join pump_agent_mints m on m.id = s.mint_id where m.mint = ${asset} and m.network = ${network} limit 1`;
	const tokenActivity = actRow ? { graduated: !!actRow.graduated, recent_tx_count: actRow.recent_tx_count || 0, trade_count: actRow.trade_count || 0, weight: Number(((actRow.graduated ? 0.3 : 0) + Math.min(0.4, (actRow.recent_tx_count || 0) * 0.005) + Math.min(0.3, (actRow.trade_count || 0) * 0.01)).toFixed(3)) } : { graduated: false, recent_tx_count: 0, trade_count: 0, weight: 0 };

	const [payRow] = await sql`select count(*) filter (where p.status='confirmed')::int as confirmed_count, count(distinct p.payer_wallet) filter (where p.status='confirmed')::int as unique_payers, coalesce(sum(p.amount_atomics) filter (where p.status='confirmed'), 0)::text as total_atomics from pump_agent_payments p join pump_agent_mints m on m.id = p.mint_id join agent_identities a on a.id = m.agent_id where (a.meta->>'sol_mint_address') = ${asset} and m.network = ${network}`;

	return json(res, 200, {
		agent: asset, network,
		pump_payments: payRow || { confirmed_count: 0, unique_payers: 0, total_atomics: '0' },
		pumpfun_signals: { count: pumpfunTotal, weight: Number(pumpfunWeight.toFixed(3)), by_kind: pumpfunByKind },
		token_activity: tokenActivity,
		feedback: {
			total: fb.total, verified: fb.verified, credentialed: fb.credentialed, event_attested: fb.event_attested, disputed: fb.disputed,
			unique_attesters: fb.unique_attesters, unique_verified_attesters: fb.unique_verified_attesters, unique_credentialed_attesters: fb.unique_credentialed_attesters,
			score_avg: Number(fb.score_avg.toFixed(3)), score_avg_verified: Number(fb.score_avg_verified.toFixed(3)),
			score_avg_credentialed: Number(fb.score_avg_credentialed.toFixed(3)), score_avg_event_attested: Number(fb.score_avg_event_attested.toFixed(3)),
			score_avg_weighted: Number(fb.score_avg_weighted.toFixed(3)), score_avg_weighted_verified: Number(fb.score_avg_weighted_verified.toFixed(3)), score_avg_weighted_credentialed: Number(fb.score_avg_weighted_credentialed.toFixed(3)),
		},
		validation: { self_passed: val.passed, self_failed: val.failed, event_passed: val.event_passed, event_failed: val.event_failed, audited_passed: auditedVal.passed, audited_failed: auditedVal.failed },
		tasks: { offered: counts.tasks_offered, accepted: counts.tasks_accepted },
		disputes_filed: counts.disputes_filed, revoked_count: counts.revoked_count,
		stake: {
			total_lamports: stakeAgg.total_lamports,
			count: stakeAgg.count,
			unique_stakers: stakeAgg.unique_stakers,
			gross_lamports: stakeAgg.gross_lamports,
			retired_lamports: stakeAgg.retired_lamports,
			retired_count: stakeAgg.retired_count,
			top_stakers: stakeAgg.top_stakers,
		},
		last_indexed_at: cursor?.last_indexed_at || null,
	});
});

// ── solana-reputation-history ─────────────────────────────────────────────────

const MAX_DAYS = 90;

export const handleReputationHistory = wrap(async (req, res) => {
	if (cors(req, res, { methods: 'GET,OPTIONS', credentials: false })) return;
	if (!method(req, res, ['GET'])) return;

	const rl = await limits.authedReadIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	const url   = new URL(req.url, `http://${req.headers.host}`);
	const asset = url.searchParams.get('asset');
	const network = url.searchParams.get('network') === 'mainnet' ? 'mainnet' : 'devnet';
	const days  = Math.min(Math.max(Number(url.searchParams.get('days') || 30), 1), MAX_DAYS);

	if (!asset) return error(res, 400, 'validation_error', 'asset query param required');
	try { new PublicKey(asset); } catch { return error(res, 400, 'validation_error', 'invalid asset pubkey'); }

	const rows = await sql`
		with feedback as (
			select date_trunc('day', f.block_time) as day, f.attester, (f.payload->>'score')::int as score,
				exists (select 1 from solana_attestations a where a.agent_asset = f.agent_asset and a.kind = 'threews.accept.v1' and a.payload->>'task_id' = f.payload->>'task_id' and a.verified = true and f.payload->>'task_id' is not null) as task_accepted,
				exists (select 1 from solana_credentials c where c.subject = f.attester and c.network = f.network and c.kind = 'threews.verified-client.v1' and c.closed = false and (c.expiry is null or c.expiry > f.block_time)) as credentialed,
				((f.payload->>'source' like 'pumpkit.%' or f.payload->>'source' like 'pumpfun.%') and exists (select 1 from solana_attest_event_claims ec where ec.signature = f.signature and ec.network = f.network)) as event_attested
			from solana_attestations f where f.agent_asset = ${asset} and f.network = ${network} and f.kind = 'threews.feedback.v1' and f.revoked = false and f.block_time >= now() - (${days} || ' days')::interval
		)
		select day, count(*)::int as n,
			coalesce(avg(score) filter (where credentialed), 0)::float as score_credentialed,
			coalesce(avg(score) filter (where task_accepted), 0)::float as score_verified,
			coalesce(avg(score) filter (where event_attested), 0)::float as score_event,
			coalesce(avg(score), 0)::float as score_raw,
			count(*) filter (where credentialed)::int as n_credentialed,
			count(*) filter (where task_accepted)::int as n_verified,
			count(*) filter (where event_attested)::int as n_event
		from feedback group by day order by day asc
	`;

	const series = rows.map((r) => {
		const tier = r.n_credentialed > 0 ? { tier: 'credentialed', score: r.score_credentialed, n: r.n_credentialed } : r.n_verified > 0 ? { tier: 'verified', score: r.score_verified, n: r.n_verified } : r.n_event > 0 ? { tier: 'event', score: r.score_event, n: r.n_event } : { tier: 'community', score: r.score_raw, n: r.n };
		return { day: r.day instanceof Date ? r.day.toISOString().slice(0, 10) : String(r.day).slice(0, 10), tier: tier.tier, score: Number(tier.score.toFixed(3)), n: tier.n };
	});

	return json(res, 200, { agent: asset, network, days, series });
});

// ── solana-registration-card ──────────────────────────────────────────────────
// Resolves an asset pubkey → Metaplex Agent Registry registration card JSON.
//
// Resolution chain:
//   1. On-chain identity PDA: if agentRegistrationUri is present —
//      - data: URI  → decode base64 payload, return inline as application/json
//      - https: URI → 302 redirect so callers always get the live card
//   2. DB lookup by sol_mint_address: redirect to /api/agents/{id}/registration
//      (the platform's stable, mutable endpoint for this agent)
//   3. 404 with a clear description of what was tried
//
// Note: the current on-chain program (mpl-agent-registry v0.2.5) stores only
// a membership marker in the identity PDA; agentRegistrationUri is not persisted
// in the account bytes (confirmed by reading 104-byte V2 accounts for all
// tested assets). Step 2 is therefore the primary resolution path today.

export const handleRegistrationCard = wrap(async (req, res) => {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;

	const url = new URL(req.url, `http://${req.headers.host}`);
	const asset = url.searchParams.get('asset');
	if (!asset) return error(res, 400, 'validation_error', 'asset query param required');
	try { new PublicKey(asset); } catch { return error(res, 400, 'validation_error', 'invalid asset pubkey'); }

	const network = url.searchParams.get('network') === 'devnet' ? 'devnet' : 'mainnet';
	const rpcUrl = network === 'devnet'
		? (process.env.SOLANA_RPC_URL_DEVNET || 'https://api.devnet.solana.com')
		: (process.env.SOLANA_RPC_URL || 'https://api.mainnet-beta.solana.com');

	const origin = env.APP_ORIGIN;

	// ── Step 1: on-chain identity PDA ────────────────────────────────────────
	let pdaUri = null;
	try {
		// Failover Connection so the best-effort on-chain PDA read rotates across the
		// endpoint chain rather than silently failing (→ DB fallback) every time the
		// single configured node returns a malformed/empty body.
		const umi = createUmi(solanaConnection({ url: rpcUrl, network })).use(mplCore()).use(mplAgentIdentity());
		const assetPk = umiPublicKey(asset);
		const [pdaAddr] = findAgentIdentityV1Pda(umi, { asset: assetPk });
		const acct = await umi.rpc.getAccount(pdaAddr).catch(() => null);
		if (acct?.exists && acct.data?.length) {
			const ser = getAgentIdentityV2AccountDataSerializer();
			const [parsed] = ser.deserialize(acct.data, 0);
			// The current program version does not write agentRegistrationUri into
			// the account, so this will be absent for all existing assets. The
			// check is here for forward-compatibility when the program is upgraded.
			if (parsed?.agentRegistrationUri) pdaUri = parsed.agentRegistrationUri;
		}
	} catch { /* RPC or deserialize failure — fall through to DB */ }

	if (pdaUri) {
		if (pdaUri.startsWith('data:')) {
			// Decode inline registration document and return it as JSON.
			try {
				const [meta, b64] = pdaUri.slice('data:'.length).split(',', 2);
				if (!b64) return error(res, 502, 'bad_data_uri', 'malformed data: URI in identity PDA');
				const encoding = meta.includes('base64') ? 'base64' : 'utf8';
				const raw = encoding === 'base64' ? Buffer.from(b64, 'base64').toString('utf8') : decodeURIComponent(b64);
				const doc = JSON.parse(raw);
				return json(res, 200, doc, {
					'cache-control': 'public, max-age=3600',
					'access-control-allow-origin': '*',
					'x-registration-source': 'onchain-data-uri',
					'x-asset': asset,
				});
			} catch {
				return error(res, 502, 'bad_data_uri', 'failed to decode data: URI from identity PDA');
			}
		}
		if (pdaUri.startsWith('https://') || pdaUri.startsWith('http://')) {
			res.setHeader('access-control-allow-origin', '*');
			res.setHeader('x-registration-source', 'onchain-https-uri');
			res.setHeader('x-asset', asset);
			res.writeHead(302, { Location: pdaUri });
			res.end();
			return;
		}
	}

	// ── Step 2: DB lookup by sol_mint_address ────────────────────────────────
	const [agent] = await sql`
		select id from agent_identities
		where (meta->>'sol_mint_address') = ${asset} and deleted_at is null
		limit 1
	`;
	if (agent) {
		const registrationUrl = `${origin}/api/agents/${agent.id}/registration`;
		res.setHeader('access-control-allow-origin', '*');
		res.setHeader('x-registration-source', 'db-registration-endpoint');
		res.setHeader('x-asset', asset);
		res.writeHead(302, { Location: registrationUrl });
		res.end();
		return;
	}

	// ── Step 3: not found ────────────────────────────────────────────────────
	return error(res, 404, 'not_found', `no registration card found for asset ${asset} — identity PDA has no agentRegistrationUri and asset is not registered on three.ws`);
});