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.

16.5 KB
Raw Blame
// api/_lib/x402/pipelines/reputation-refresh.js
//
// Agent Reputation Score Refresh — autonomous pipeline (self/005).
//
// On each run it refreshes the on-chain attestation reputation of the stalest
// registered Solana agents. For every agent it makes a REAL paid x402 call to
// the /api/mcp tool `solana_agent_reputation` ($0.001 USDC/call) using the seed
// wallet — never mocked. The pipeline:
//
//   1. Selects the stalest agents that have an on-chain Metaplex Core asset
//      (agent_identities.meta.sol_mint_address). Stalest-first ordering rotates
//      coverage across runs, exactly like the recompute-reputation cron.
//   2. Probes + pays each call via the shared payX402 client (real on-chain USDC).
//   3. Extracts the reputation summary and writes it to agent_solana_reputation,
//      flagging agents whose verified score drops below the trust threshold.
//   4. Records a row in x402_autonomous_log for every call (success or failure),
//      with the extracted score summary in value_extracted.
//
// Wiring: declared as a run()-style entry in autonomous-registry.js. The per-tick
// loop (api/cron/x402-autonomous-loop.js) hands run() a shared payment context
// (buyer, conn, blockhash, mintInfo, remainingCap); called standalone (manual
// test) it bootstraps its own via bootstrapSolanaContext().
//
// DATA OUT (value extraction):
//   Table  : agent_solana_reputation
//   Columns: score (headline trust number — the verified feedback average when
//            any verified feedback exists, else the raw average), feedback_total,
//            feedback_verified, feedback_disputed, validation_passed,
//            validation_failed, flagged, raw, refreshed_at.
//
// DOWNSTREAM CONSUMERS (read via the exported helpers below):
//   • Agent-profile trust badge  → getStoredSolanaReputation(agentId)
//   • Reputation leaderboard     → listSolanaReputationLeaderboard(limit)
//   • Moderation / flagged feed  → listFlaggedSolanaAgents(limit)
//
// This is the on-chain ATTESTATION reputation (signed feedback + validation
// memos), deliberately separate from the financial reputation in
// agent_reputation_scores (api/cron/recompute-reputation.js). The two never
// share a table.

import { randomUUID } from 'node:crypto';

import { sql } from '../../db.js';
import { env } from '../../env.js';
import { logger } from '../../usage.js';
import { payX402, bootstrapSolanaContext, USDC_MINT } from '../pay.js';

const log = logger('x402-reputation-refresh');

const TOOL = 'solana_agent_reputation';
const ASSET = USDC_MINT || 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
// Advertised price of the tool: $0.001 USDC (6 decimals). Used only to pre-check
// the daily cap; the authoritative amount comes from the 402 challenge.
const PRICE_ATOMIC = 1000;

// On-chain feedback scores use a 1–5 star scale. Flag an agent whose verified
// average drops below the threshold once it has a meaningful sample. Tunable.
const FLAG_THRESHOLD = Number(process.env.SOLANA_REPUTATION_FLAG_THRESHOLD || 3.0);
const FLAG_MIN_SAMPLE = Number(process.env.SOLANA_REPUTATION_FLAG_MIN_SAMPLE || 3);
// Agents refreshed per run — bounds per-tick spend and RPC/DB load. Stalest
// agents sort first, so coverage rotates across runs.
const REFRESH_BATCH = Math.max(1, Number(process.env.SOLANA_REPUTATION_REFRESH_BATCH || 25));

async function ensureSchema() {
	await sql`
		create table if not exists agent_solana_reputation (
			agent_id          uuid primary key,
			agent_asset       text not null,
			network           text not null default 'mainnet',
			score             numeric(6,3) not null default 0,
			feedback_total    int not null default 0,
			feedback_verified int not null default 0,
			feedback_disputed int not null default 0,
			validation_passed int not null default 0,
			validation_failed int not null default 0,
			flagged           boolean not null default false,
			raw               jsonb,
			refreshed_at      timestamptz not null default now()
		)
	`;
	// Reputation leaderboard: rank by stored score cheaply.
	await sql`create index if not exists agent_solana_reputation_score_idx on agent_solana_reputation (score desc)`;
	// Moderation feed: list flagged agents without a full scan.
	await sql`create index if not exists agent_solana_reputation_flagged_idx on agent_solana_reputation (flagged) where flagged = true`;
	// Stalest-first selection for this loop.
	await sql`create index if not exists agent_solana_reputation_refreshed_idx on agent_solana_reputation (refreshed_at asc)`;
	// The autonomous log predates the value_extracted column some pipelines use;
	// add it idempotently so this pipeline records its parsed summary into it.
	await sql`ALTER TABLE x402_autonomous_log ADD COLUMN IF NOT EXISTS value_extracted jsonb`;
}

async function listAgentsToRefresh(limit) {
	// Never-refreshed agents first, then stalest. Only agents with a registered
	// on-chain asset are eligible (those are the ones with attestations to read).
	return sql`
		select a.id,
		       a.name,
		       a.meta->>'sol_mint_address' as asset,
		       coalesce(a.meta->>'network', 'mainnet') as network
		from agent_identities a
		left join agent_solana_reputation r on r.agent_id = a.id
		where a.deleted_at is null
		  and a.meta->>'sol_mint_address' is not null
		order by (r.agent_id is null) desc, r.refreshed_at asc nulls first
		limit ${limit}
	`;
}

function jsonRpcReputation(asset, network, id) {
	return {
		jsonrpc: '2.0',
		id,
		method: 'tools/call',
		params: { name: TOOL, arguments: { asset, network } },
	};
}

// Pull the solana_agent_reputation structuredContent out of a JSON-RPC body.
export function extractReputation(responseBody) {
	const msg = Array.isArray(responseBody) ? responseBody[0] : responseBody;
	const sc = msg?.result?.structuredContent;
	if (!sc || sc.error) return null;
	return sc; // { agent, network, feedback:{...}, validation:{...} }
}

// Derive the headline trust score and the flag verdict from a reputation
// payload. Exported for unit coverage.
export function evaluateReputation(rep) {
	const fb = rep.feedback || {};
	const val = rep.validation || {};
	const verified = Number(fb.verified || 0);
	const total = Number(fb.total || 0);
	const disputed = Number(fb.disputed || 0);
	const passed = Number(val.passed || 0);
	const failed = Number(val.failed || 0);

	// Prefer the verified-only average (feedback whose task the owner acknowledged
	// on-chain) when any exists; otherwise the raw average.
	const score = Number(verified > 0 ? (fb.score_avg_verified || 0) : (fb.score_avg || 0));
	const sample = verified > 0 ? verified : total;

	const reasons = [];
	if (sample >= FLAG_MIN_SAMPLE && score < FLAG_THRESHOLD) reasons.push(`score ${score.toFixed(2)} < ${FLAG_THRESHOLD}`);
	if (total > 0 && disputed / total > 0.5) reasons.push('majority of feedback disputed');
	if (passed + failed > 0 && failed > passed) reasons.push('validation failing');

	return { score, flagged: reasons.length > 0, reasons, total, verified, disputed, passed, failed };
}

async function upsertReputation(agent, rep, evald) {
	await sql`
		insert into agent_solana_reputation
			(agent_id, agent_asset, network, score, feedback_total, feedback_verified,
			 feedback_disputed, validation_passed, validation_failed, flagged, raw, refreshed_at)
		values
			(${agent.id}, ${agent.asset}, ${agent.network}, ${evald.score},
			 ${evald.total}, ${evald.verified}, ${evald.disputed},
			 ${evald.passed}, ${evald.failed}, ${evald.flagged},
			 ${JSON.stringify(rep)}, now())
		on conflict (agent_id) do update set
			agent_asset       = excluded.agent_asset,
			network           = excluded.network,
			score             = excluded.score,
			feedback_total    = excluded.feedback_total,
			feedback_verified = excluded.feedback_verified,
			feedback_disputed = excluded.feedback_disputed,
			validation_passed = excluded.validation_passed,
			validation_failed = excluded.validation_failed,
			flagged           = excluded.flagged,
			raw               = excluded.raw,
			refreshed_at      = now()
	`;
}

// Per-call row into x402_autonomous_log, including value_extracted. The loop
// also records one aggregate summary row for the run() entry; these are the
// granular per-agent rows this pipeline owns.
async function recordCall(runId, { agent, endpointUrl, amountAtomic, txSig, responseData, durationMs, success, errorMsg, valueExtracted }) {
	try {
		await sql`
			INSERT INTO x402_autonomous_log
				(run_id, endpoint_type, service_name, endpoint_url,
				 network, amount_atomic, asset, tx_signature,
				 response_data, value_extracted, duration_ms, success, error_msg, pipeline)
			VALUES
				(${runId}, ${'self'}, ${`Reputation Refresh: ${agent.name || agent.asset}`}, ${endpointUrl},
				 ${'solana:mainnet'}, ${amountAtomic || 0}, ${ASSET}, ${txSig || null},
				 ${responseData ? JSON.stringify(responseData) : null},
				 ${valueExtracted ? JSON.stringify(valueExtracted) : null},
				 ${durationMs || 0}, ${success}, ${errorMsg || null}, ${'self'})
		`;
	} catch (err) {
		log.warn('reputation_refresh_log_insert_failed', { asset: agent.asset, message: err?.message });
	}
}

/**
 * Run the reputation refresh. Conforms to the run()-style registry contract: the
 * loop hands over { origin, buyer, conn, blockhash, mintInfo, remainingCap,
 * runId }; called standalone (manual test) it bootstraps its own Solana context.
 *
 * Returns the aggregate outcome the loop records as one summary row:
 *   { success, amountAtomic, txSig, errorMsg, responseData, signalData, skipped, note }
 */
export async function run(ctx = {}) {
	const runId = ctx.runId || randomUUID();
	const origin = ctx.origin || env.APP_ORIGIN || 'https://three.ws';
	const endpointUrl = `${origin}/api/mcp`;
	let remainingCap = ctx.remainingCap ?? Number.POSITIVE_INFINITY;

	// ── Schema first: without the sink there is no value to extract, so don't pay.
	try {
		await ensureSchema();
	} catch (err) {
		log.warn('reputation_refresh_schema_failed', { message: err?.message });
		return { success: false, skipped: true, amountAtomic: 0, errorMsg: `schema_failed: ${err?.message}` };
	}

	// ── Eligible agents. A DB failure here is logged and the run exits cleanly.
	let agents;
	try {
		agents = await listAgentsToRefresh(REFRESH_BATCH);
	} catch (err) {
		log.error('reputation_refresh_list_failed', { message: err?.message });
		return { success: false, skipped: true, amountAtomic: 0, errorMsg: `db_list_failed: ${err?.message}` };
	}
	if (!agents.length) {
		log.info('reputation_refresh_no_agents');
		return { success: true, skipped: true, amountAtomic: 0, note: 'no_registered_agents' };
	}

	// ── Solana payment context: reuse the loop's, else bootstrap (graceful on an
	//    unconfigured wallet — bootstrap throws, we exit logged without paying).
	let { buyer, conn, blockhash, mintInfo } = ctx;
	if (!buyer || !conn || !blockhash || !mintInfo) {
		try {
			({ buyer, conn, blockhash, mintInfo } = await bootstrapSolanaContext({ buyer }));
		} catch (err) {
			log.info('reputation_refresh_skipped', { reason: err.message });
			return { success: false, skipped: true, amountAtomic: 0, errorMsg: err.message, note: 'wallet_or_rpc_unconfigured' };
		}
	}

	let spentAtomic = 0;
	let paid = 0;
	let stored = 0;
	let flaggedCount = 0;
	let callErrors = 0;
	let lastTxSig = null;

	for (let i = 0; i < agents.length; i++) {
		const agent = agents[i];

		// Stop before charging again if the next call would exceed the daily cap.
		if (Number.isFinite(remainingCap) && remainingCap < PRICE_ATOMIC) {
			log.info('reputation_refresh_cap_reached', { spent_atomic: spentAtomic });
			break;
		}

		const t0 = Date.now();
		let result;
		try {
			result = await payX402({
				url: endpointUrl,
				method: 'POST',
				body: jsonRpcReputation(agent.asset, agent.network, i + 1),
				buyer, conn, blockhash, mintInfo,
				remainingCap,
				// Distinct nonce per call so these identical-amount ($0.001) payments
				// against the one shared blockhash each produce a unique signature.
				nonce: i + 1,
			});
		} catch (err) {
			// Network failure / abort — log the call, never crash the sweep.
			callErrors += 1;
			await recordCall(runId, {
				agent, endpointUrl, amountAtomic: 0, txSig: null, responseData: null,
				durationMs: Date.now() - t0, success: false, errorMsg: err?.message || 'fetch_failed', valueExtracted: null,
			});
			continue;
		}

		if (result.paid) {
			spentAtomic += result.amountAtomic;
			remainingCap -= result.amountAtomic;
			paid += 1;
			if (result.txSig) lastTxSig = result.txSig;
		}

		let valueExtracted = null;
		let success = result.success;
		let errorMsg = result.errorMsg;

		if (result.success) {
			const rep = extractReputation(result.responseBody);
			if (!rep) {
				success = false;
				errorMsg = 'unparseable_response';
				callErrors += 1;
			} else {
				const evald = evaluateReputation(rep);
				valueExtracted = {
					agent_id: agent.id, asset: agent.asset, network: agent.network,
					score: evald.score, flagged: evald.flagged, reasons: evald.reasons,
					feedback_total: evald.total, feedback_verified: evald.verified,
					feedback_disputed: evald.disputed,
					validation_passed: evald.passed, validation_failed: evald.failed,
				};
				try {
					await upsertReputation(agent, rep, evald);
					stored += 1;
					if (evald.flagged) flaggedCount += 1;
				} catch (dbErr) {
					// Payment already settled; persisting the value failed. Mark the row
					// a failure so the agent is retried next tick.
					success = false;
					errorMsg = `store_failed: ${dbErr?.message || 'unknown'}`;
					callErrors += 1;
				}
			}
		} else {
			callErrors += 1;
		}

		await recordCall(runId, {
			agent,
			endpointUrl,
			amountAtomic: result.amountAtomic,
			txSig: result.txSig,
			// Keep the granular row lean — value_extracted holds the useful shape.
			responseData: { status: result.status, rpc_error: result.responseBody?.error || null },
			durationMs: Date.now() - t0,
			success,
			errorMsg,
			valueExtracted,
		});
	}

	log.info('reputation_refresh_complete', {
		run_id: runId, scanned: agents.length, paid, stored,
		flagged: flaggedCount, errors: callErrors, spent_usdc: (spentAtomic / 1e6).toFixed(4),
	});

	// Aggregate outcome for the loop's single summary row. success=true when at
	// least one agent's score was stored; per-agent detail lives in the rows above.
	return {
		success: stored > 0,
		amountAtomic: spentAtomic,
		txSig: lastTxSig,
		errorMsg: stored === 0 && callErrors > 0 ? `reputation_refresh_calls_failed:${callErrors}` : null,
		skipped: paid === 0 && stored === 0,
		responseData: { scanned: agents.length, paid, stored, flagged: flaggedCount, errors: callErrors },
		signalData: { scanned: agents.length, stored, flagged: flaggedCount },
		note: `reputation_refresh stored=${stored} flagged=${flaggedCount} paid=${paid}`,
	};
}

// ── Downstream consumers ────────────────────────────────────────────────────
// The data this pipeline extracts is read back through these helpers.

/** Trust badge on an agent profile: the stored on-chain reputation, or null. */
export async function getStoredSolanaReputation(agentId) {
	if (!agentId) return null;
	try {
		const [row] = await sql`
			select agent_id, agent_asset, network, score, feedback_total, feedback_verified,
			       feedback_disputed, validation_passed, validation_failed, flagged, refreshed_at
			from agent_solana_reputation where agent_id = ${agentId} limit 1
		`;
		return row || null;
	} catch {
		return null;
	}
}

/** Reputation leaderboard: top agents by stored on-chain score. */
export async function listSolanaReputationLeaderboard(limit = 50) {
	const n = Math.min(Math.max(1, Number(limit) || 50), 200);
	try {
		return await sql`
			select r.agent_id, r.agent_asset, r.network, r.score, r.feedback_total,
			       r.feedback_verified, r.flagged, r.refreshed_at, a.name
			from agent_solana_reputation r
			join agent_identities a on a.id = r.agent_id and a.deleted_at is null
			where r.feedback_total > 0
			order by r.score desc, r.feedback_verified desc
			limit ${n}
		`;
	} catch {
		return [];
	}
}

/** Moderation feed: agents currently flagged below the trust threshold. */
export async function listFlaggedSolanaAgents(limit = 100) {
	const n = Math.min(Math.max(1, Number(limit) || 100), 500);
	try {
		return await sql`
			select r.agent_id, r.agent_asset, r.network, r.score, r.feedback_total,
			       r.feedback_disputed, r.refreshed_at, a.name
			from agent_solana_reputation r
			join agent_identities a on a.id = r.agent_id and a.deleted_at is null
			where r.flagged = true
			order by r.score asc
			limit ${n}
		`;
	} catch {
		return [];
	}
}