Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// Reputation Staking Market — the pure earnings engine.
//
// Stakers back an agent with escrowed lamports; the agent's ATTESTED ACTION
// HISTORY decides what that conviction earns. This module is the only place the
// weights, the epoch math, and the distribution rule exist. It is the executable
// form of specs/REPUTATION_STAKING_MARKET.md §5.
//
// Intentionally PURE: no I/O, no imports. The same functions run
// server-authoritatively in api/_lib/reputation-market.js (which does the real
// chain + index reads) and in the browser on /reputation/market, so a staker can
// re-derive every lamport the server quotes them. Unit-tested in
// tests/reputation-staking.test.js.
//
// ── Design principles (read before touching the weights) ─────────────────────
//
// 1. Every input is a signed, indexed attestation that already exists on
// Solana (api/_lib/solana-attestations.js). Nothing here invents activity.
//
// 2. Conviction is not work. Stake and unstake attestations contribute zero to
// the yield they earn; otherwise the market would pay itself.
//
// 3. Faults cost double what work pays, so a failed validation is never
// cancelled out by the passed one next to it.
//
// 4. Yield is concave in activity (log2), so spraying cheap attestations does
// not buy proportional yield.
//
// 5. The pool is a fixed per-epoch budget, never a rate. The market can never
// owe more than the escrow holds.
//
// 6. An agent with no attested work earns its stakers nothing. Idle is not
// punished, it is simply unpaid.
/** Seconds in one epoch. An epoch is one UTC day. */
export const EPOCH_SECONDS = 86_400;
/** Minimum escrow delta for a transaction to count as a market stake (0.001 SOL). */
export const MIN_STAKE_LAMPORTS = 1_000_000n;
/** The market envelope tag that separates a market stake from a bare conviction memo. */
export const MARKET_TAG = 'rsm.v1';
/**
* The exact text a staker signs with their wallet to withdraw a position.
* Bound to the network and the stake signature so one proof cannot settle a
* different position, and to a millisecond timestamp the server holds to a
* few minutes, so a captured proof goes stale. Shared so the page that signs
* and the server that verifies can never drift apart.
*/
export function unstakeProofMessage({ network, stakeSignature, issuedAt }) {
const net = network === 'mainnet' ? 'mainnet' : 'devnet';
return `threews.unstake.v1:${net}:${stakeSignature}:${issuedAt}`;
}
/** Weight each attested action contributes to an agent's epoch `work`. */
export const WORK_WEIGHTS = Object.freeze({
taskAccepted: 1.0,
taskOffered: 0.6,
validationPassed: 1.0,
feedbackVerified: 0.75,
feedbackPlain: 0.35,
});
/** Weight each attested failure contributes to an agent's epoch `faults`. */
export const FAULT_WEIGHTS = Object.freeze({
validationFailed: 1.0,
dispute: 1.0,
revocation: 1.0,
});
/** Faults are charged at this multiple of the rate work is credited. */
export const FAULT_PENALTY = 2;
/** Quality of an agent that received no feedback in an epoch. Silence is neutral. */
export const NEUTRAL_QUALITY = 0.5;
/** Decimal places every intermediate is rounded to, so server and browser agree exactly. */
const PRECISION = 9;
const round = (n) => {
const f = 10 ** PRECISION;
return Math.round((Number(n) || 0) * f) / f;
};
const clamp01 = (n) => (n < 0 ? 0 : n > 1 ? 1 : n);
/** The epoch a unix-seconds timestamp falls in. */
export function epochOf(unixSeconds) {
return Math.floor(Number(unixSeconds) / EPOCH_SECONDS);
}
/** The half-open `[start, end)` unix-second bounds of an epoch. */
export function epochBounds(epoch) {
const start = Number(epoch) * EPOCH_SECONDS;
return { start, end: start + EPOCH_SECONDS };
}
/**
* The fraction of an epoch a position was open for, in [0, 1].
*
* @param {{ openedAt: number, closedAt?: number|null }} position unix seconds
* @param {number} epoch
* @param {number} now unix seconds, used when the position is still open
*/
export function epochFraction(position, epoch, now) {
const { start, end } = epochBounds(epoch);
const opened = Number(position.openedAt) || 0;
const closedRaw = position.closedAt === null || position.closedAt === undefined ? now : position.closedAt;
const closed = Math.min(Number(closedRaw) || 0, now);
const from = Math.max(opened, start);
const to = Math.min(closed, end);
if (to <= from) return 0;
// Exact by design (spec section 4): overlap seconds over 86400, no rounding.
// The 9-decimal rounding rule covers the section 5 earnings intermediates;
// rounding here would credit a one-second sliver as a fatter slice than it is.
return (to - from) / EPOCH_SECONDS;
}
/**
* Fold an agent's attestations for one epoch into `work` and `faults`.
*
* Each entry is `{ kind, verified, passed, score, taskAccepted }` — exactly the
* columns `solana_attestations` already carries. Revoked rows must be filtered
* out by the caller; a revoked attestation is not evidence of anything.
*
* @param {Array<object>} attestations
* @returns {{ work: number, faults: number, feedbackCount: number, feedbackScoreSum: number, counts: object }}
*/
export function foldActions(attestations) {
let work = 0;
let faults = 0;
let feedbackCount = 0;
let feedbackScoreSum = 0;
const counts = {
taskAccepted: 0,
taskOffered: 0,
validationPassed: 0,
validationFailed: 0,
feedbackVerified: 0,
feedbackPlain: 0,
dispute: 0,
revocation: 0,
};
for (const a of Array.isArray(attestations) ? attestations : []) {
if (!a || a.verified === false) continue;
switch (a.kind) {
case 'threews.accept.v1':
work += WORK_WEIGHTS.taskAccepted;
counts.taskAccepted++;
break;
case 'threews.task.v1':
work += WORK_WEIGHTS.taskOffered;
counts.taskOffered++;
break;
case 'threews.validation.v1':
if (a.passed === true) {
work += WORK_WEIGHTS.validationPassed;
counts.validationPassed++;
} else {
faults += FAULT_WEIGHTS.validationFailed;
counts.validationFailed++;
}
break;
case 'threews.feedback.v1': {
const linked = a.taskAccepted === true;
work += linked ? WORK_WEIGHTS.feedbackVerified : WORK_WEIGHTS.feedbackPlain;
if (linked) counts.feedbackVerified++;
else counts.feedbackPlain++;
const score = Number(a.score);
if (Number.isFinite(score) && score >= 1 && score <= 5) {
feedbackCount++;
feedbackScoreSum += score;
}
break;
}
case 'threews.dispute.v1':
faults += FAULT_WEIGHTS.dispute;
counts.dispute++;
break;
case 'threews.revoke.v1':
faults += FAULT_WEIGHTS.revocation;
counts.revocation++;
break;
default:
// threews.stake.v1 / threews.unstake.v1 and any future kind: conviction
// is not work, and an unknown kind is not evidence of work either.
break;
}
}
return {
work: round(work),
faults: round(faults),
feedbackCount,
feedbackScoreSum: round(feedbackScoreSum),
counts,
};
}
/**
* An agent's yield weight for one epoch, plus the full derivation so the UI can
* show a staker exactly where the number came from.
*
* @param {Array<object>} attestations the epoch's verified, non-revoked rows
* @returns {{ weight: number, performance: number, quality: number, integrity: number, work: number, faults: number, meanFeedbackScore: number|null, counts: object }}
*/
export function agentEpochWeight(attestations) {
const folded = foldActions(attestations);
const { work, faults, feedbackCount, feedbackScoreSum } = folded;
const meanFeedbackScore = feedbackCount > 0 ? round(feedbackScoreSum / feedbackCount) : null;
const quality = meanFeedbackScore === null ? NEUTRAL_QUALITY : round(clamp01((meanFeedbackScore - 1) / 4));
const integrity = work + faults > 0 ? round(work / (work + FAULT_PENALTY * faults)) : 1;
const performance = round(quality * integrity);
const weight = round(performance * Math.log2(1 + work));
return {
weight,
performance,
quality,
integrity,
work,
faults,
meanFeedbackScore,
counts: folded.counts,
};
}
/**
* Split one epoch's reward pool across the positions open during it.
*
* `positions` are `{ id, agentAsset, principalLamports (bigint|string), openedAt, closedAt }`.
* `agentWeights` maps `agentAsset → weight` (from agentEpochWeight).
* `poolLamports` is the epoch's fixed budget.
*
* Returns a Map of `id → { lamports: bigint, posWeight, epochFraction }`. Floor
* division guarantees the sum never exceeds the pool; the remainder rolls over.
*
* @returns {{ payouts: Map<string, {lamports: bigint, posWeight: number, epochFraction: number}>, totalWeight: number, distributed: bigint }}
*/
export function distributeEpoch({ epoch, positions, agentWeights, poolLamports, now }) {
const pool = toBigInt(poolLamports);
const weights = agentWeights instanceof Map ? agentWeights : new Map(Object.entries(agentWeights || {}));
const nowSec = Number(now);
const rows = [];
let totalWeight = 0;
for (const p of Array.isArray(positions) ? positions : []) {
const fraction = epochFraction(p, epoch, nowSec);
if (fraction <= 0) continue;
const principal = toBigInt(p.principalLamports);
if (principal <= 0n) continue;
const agentWeight = Number(weights.get(p.agentAsset) ?? 0) || 0;
const posWeight = round(Number(principal) * fraction * agentWeight);
rows.push({ id: p.id, posWeight, fraction });
totalWeight = round(totalWeight + posWeight);
}
const payouts = new Map();
let distributed = 0n;
for (const r of rows) {
let lamports = 0n;
if (totalWeight > 0 && pool > 0n && r.posWeight > 0) {
// Ratio in float, applied to the bigint pool. posWeight/totalWeight is a
// bounded [0,1] fraction, so the float cannot lose lamport-scale precision
// the way multiplying two lamport-magnitude floats would.
lamports = BigInt(Math.floor(Number(pool) * (r.posWeight / totalWeight)));
}
payouts.set(r.id, { lamports, posWeight: r.posWeight, epochFraction: r.fraction });
distributed += lamports;
}
return { payouts, totalWeight, distributed };
}
/**
* Total earnings for ONE position across every epoch it overlapped.
*
* `epochInputs` maps `epoch → { poolLamports, positions, agentWeights }` — the
* same shape distributeEpoch takes, because a position's share depends on every
* other position competing for that epoch's pool.
*
* @returns {{ lamports: bigint, byEpoch: Array<{epoch: number, lamports: string, posWeight: number, epochFraction: number}> }}
*/
export function accruePosition({ position, epochInputs, now }) {
const byEpoch = [];
let total = 0n;
const epochs = [...(epochInputs instanceof Map ? epochInputs.keys() : Object.keys(epochInputs || {}))]
.map(Number)
.sort((a, b) => a - b);
for (const epoch of epochs) {
const input = epochInputs instanceof Map ? epochInputs.get(epoch) : epochInputs[epoch];
if (!input) continue;
const { payouts } = distributeEpoch({
epoch,
positions: input.positions,
agentWeights: input.agentWeights,
poolLamports: input.poolLamports,
now,
});
const share = payouts.get(position.id);
if (!share || (share.lamports === 0n && share.posWeight === 0)) continue;
total += share.lamports;
byEpoch.push({
epoch,
lamports: share.lamports.toString(),
posWeight: share.posWeight,
epochFraction: share.epochFraction,
});
}
return { lamports: total, byEpoch };
}
/**
* The epochs a position overlapped, inclusive of the current one.
*
* @returns {number[]}
*/
export function positionEpochs(position, now) {
const opened = Number(position.openedAt) || 0;
const closedRaw = position.closedAt === null || position.closedAt === undefined ? now : position.closedAt;
const closed = Math.min(Number(closedRaw) || 0, Number(now));
const first = epochOf(opened);
const last = epochOf(Math.max(closed, opened));
const out = [];
for (let e = first; e <= last; e++) out.push(e);
return out;
}
/**
* Realized annualised rate for a position. Never a projection: it divides
* earnings that have actually accrued by the time they took to accrue.
*
* @returns {number} e.g. 0.184 for 18.4%
*/
export function realizedApr({ principalLamports, earningsLamports, openedAt, closedAt, now }) {
const principal = Number(toBigInt(principalLamports));
const earnings = Number(toBigInt(earningsLamports));
if (principal <= 0) return 0;
const end = closedAt === null || closedAt === undefined ? Number(now) : Number(closedAt);
const elapsedDays = (end - Number(openedAt)) / EPOCH_SECONDS;
if (!(elapsedDays > 0)) return 0;
return round((earnings / principal) * (365 / elapsedDays));
}
/**
* Clamp a settlement to what the escrow can actually pay. Principal is always
* returned in full; only earnings are reduced, and only when the reward surplus
* is short. See spec §2.
*
* @returns {{ principal: bigint, earnings: bigint, clamped: boolean }}
*/
export function clampSettlement({ principalLamports, earningsLamports, surplusLamports }) {
const principal = toBigInt(principalLamports);
const earnings = toBigInt(earningsLamports);
const surplus = toBigInt(surplusLamports);
if (earnings <= surplus) return { principal, earnings, clamped: false };
return { principal, earnings: surplus < 0n ? 0n : surplus, clamped: true };
}
/** Parse lamports from a bigint, a decimal string, or a safe number. */
export function toBigInt(v) {
if (typeof v === 'bigint') return v;
if (typeof v === 'number') return Number.isFinite(v) ? BigInt(Math.trunc(v)) : 0n;
if (typeof v === 'string' && /^-?\d+$/.test(v.trim())) return BigInt(v.trim());
return 0n;
}
/** Lamports as a human SOL string with the given precision. */
export function formatSol(lamports, decimals = 4) {
const n = Number(toBigInt(lamports)) / 1e9;
return n.toFixed(decimals);
}