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 earnings engine.
//
// These tests pin the contract in specs/REPUTATION_STAKING_MARKET.md §4-§5. The
// numbers here are the ones a staker is quoted and the ones the escrow pays, so
// a change that moves any of them is a change to what people are owed.
import { describe, it, expect } from 'vitest';
import {
EPOCH_SECONDS,
MIN_STAKE_LAMPORTS,
MARKET_TAG,
NEUTRAL_QUALITY,
epochOf,
epochBounds,
epochFraction,
positionEpochs,
foldActions,
agentEpochWeight,
distributeEpoch,
accruePosition,
realizedApr,
clampSettlement,
toBigInt,
formatSol,
} from '../src/shared/reputation-staking.js';
import { KIND_MAP, validatePayload } from '../api/_lib/solana-attestations.js';
const AGENT_A = 'THREEsynthetic1111111111111111111111111111A';
const AGENT_B = 'THREEsynthetic1111111111111111111111111111B';
/** An epoch boundary far from any real date, so the maths is readable. */
const E = 20_000;
const { start: E_START } = epochBounds(E);
const feedback = (score, taskAccepted = false) => ({
kind: 'threews.feedback.v1',
verified: true,
score,
taskAccepted,
blockTime: E_START + 10,
});
const validation = (passed) => ({
kind: 'threews.validation.v1',
verified: true,
passed,
blockTime: E_START + 10,
});
const accept = () => ({ kind: 'threews.accept.v1', verified: true, blockTime: E_START + 10 });
describe('epochs', () => {
it('buckets a timestamp into its UTC day', () => {
expect(EPOCH_SECONDS).toBe(86_400);
expect(epochOf(0)).toBe(0);
expect(epochOf(86_399)).toBe(0);
expect(epochOf(86_400)).toBe(1);
expect(epochBounds(1)).toEqual({ start: 86_400, end: 172_800 });
});
it('credits only the fraction of the epoch a position was actually open', () => {
// Opened at noon, still open at the end of the day: half the epoch.
const half = epochFraction({ openedAt: E_START + EPOCH_SECONDS / 2, closedAt: null }, E, E_START + EPOCH_SECONDS);
expect(half).toBe(0.5);
});
it('gives no free day to a stake placed one second before midnight', () => {
const sliver = epochFraction({ openedAt: E_START + EPOCH_SECONDS - 1, closedAt: null }, E, E_START + EPOCH_SECONDS);
expect(sliver).toBeCloseTo(1 / 86_400, 12);
});
it('never accrues past `now`, even for an open position', () => {
const now = E_START + 3_600;
// Spec section 4: overlap seconds over 86400, exact. No 9-decimal rounding
// here; that rule belongs to the section 5 earnings intermediates.
expect(epochFraction({ openedAt: E_START, closedAt: null }, E, now)).toBe(3_600 / 86_400);
});
it('returns zero for an epoch the position did not overlap', () => {
expect(epochFraction({ openedAt: E_START, closedAt: E_START + 10 }, E + 5, E_START + 10 * EPOCH_SECONDS)).toBe(0);
});
it('enumerates every epoch a position spanned, inclusive', () => {
const epochs = positionEpochs({ openedAt: E_START, closedAt: E_START + 2 * EPOCH_SECONDS }, E_START + 3 * EPOCH_SECONDS);
expect(epochs).toEqual([E, E + 1, E + 2]);
});
});
describe('foldActions', () => {
it('weights each attested action per the spec table', () => {
const folded = foldActions([accept(), validation(true), feedback(5, true), feedback(4, false)]);
// 1.00 accept + 1.00 passed validation + 0.75 verified feedback + 0.35 plain feedback
expect(folded.work).toBe(3.1);
expect(folded.faults).toBe(0);
expect(folded.feedbackCount).toBe(2);
});
it('charges faults for failed validations, disputes and revocations', () => {
const folded = foldActions([
validation(false),
{ kind: 'threews.dispute.v1', verified: true },
{ kind: 'threews.revoke.v1', verified: true },
]);
expect(folded.work).toBe(0);
expect(folded.faults).toBe(3);
});
it('counts conviction as worth nothing, so the market cannot pay itself', () => {
const folded = foldActions([
{ kind: 'threews.stake.v1', verified: true, score: 5 },
{ kind: 'threews.unstake.v1', verified: true },
]);
expect(folded.work).toBe(0);
expect(folded.faults).toBe(0);
});
it('ignores unverified rows and unknown kinds', () => {
const folded = foldActions([
{ kind: 'threews.accept.v1', verified: false },
{ kind: 'threews.future-kind.v9', verified: true },
]);
expect(folded.work).toBe(0);
});
});
describe('agentEpochWeight', () => {
it('treats an agent with no feedback as neutral quality, not as bad', () => {
const w = agentEpochWeight([accept(), accept()]);
expect(w.quality).toBe(NEUTRAL_QUALITY);
expect(w.integrity).toBe(1);
// 0.5 * log2(1 + 2)
expect(w.weight).toBeCloseTo(0.5 * Math.log2(3), 8);
});
it('maps the 1-5 feedback scale onto [0, 1]', () => {
expect(agentEpochWeight([feedback(1)]).quality).toBe(0);
expect(agentEpochWeight([feedback(3)]).quality).toBe(0.5);
expect(agentEpochWeight([feedback(5)]).quality).toBe(1);
});
it('charges a fault at double the rate work is credited', () => {
// work 1.0 (one passed validation), faults 1.0 (one failed) => 1 / (1 + 2)
const w = agentEpochWeight([validation(true), validation(false)]);
expect(w.integrity).toBeCloseTo(1 / 3, 9);
});
it('pays nothing for an idle epoch', () => {
expect(agentEpochWeight([]).weight).toBe(0);
});
it('is concave in activity, so spraying attestations does not buy proportional yield', () => {
const ten = agentEpochWeight(Array.from({ length: 10 }, accept)).weight;
const twenty = agentEpochWeight(Array.from({ length: 20 }, accept)).weight;
expect(twenty).toBeGreaterThan(ten);
expect(twenty).toBeLessThan(ten * 2);
});
});
describe('distributeEpoch', () => {
const positions = [
{ id: 'a', agentAsset: AGENT_A, principalLamports: 1_000_000_000n, openedAt: E_START, closedAt: null },
{ id: 'b', agentAsset: AGENT_A, principalLamports: 3_000_000_000n, openedAt: E_START, closedAt: null },
];
it('splits an agent share strictly in proportion to principal', () => {
const { payouts } = distributeEpoch({
epoch: E,
positions,
agentWeights: new Map([[AGENT_A, 1]]),
poolLamports: 4_000_000n,
now: E_START + EPOCH_SECONDS,
});
expect(payouts.get('a').lamports).toBe(1_000_000n);
expect(payouts.get('b').lamports).toBe(3_000_000n);
});
it('never distributes more than the pool', () => {
const { payouts, distributed } = distributeEpoch({
epoch: E,
positions: [
...positions,
{ id: 'c', agentAsset: AGENT_A, principalLamports: 7n, openedAt: E_START, closedAt: null },
],
agentWeights: new Map([[AGENT_A, 1]]),
poolLamports: 1_000_001n,
now: E_START + EPOCH_SECONDS,
});
const sum = [...payouts.values()].reduce((acc, v) => acc + v.lamports, 0n);
expect(sum).toBe(distributed);
expect(sum).toBeLessThanOrEqual(1_000_001n);
});
it('pays a staker of an idle agent nothing while a working agent still earns', () => {
const { payouts } = distributeEpoch({
epoch: E,
positions: [
{ id: 'working', agentAsset: AGENT_A, principalLamports: 1_000_000_000n, openedAt: E_START, closedAt: null },
{ id: 'idle', agentAsset: AGENT_B, principalLamports: 1_000_000_000n, openedAt: E_START, closedAt: null },
],
agentWeights: new Map([
[AGENT_A, 1],
[AGENT_B, 0],
]),
poolLamports: 1_000_000n,
now: E_START + EPOCH_SECONDS,
});
expect(payouts.get('working').lamports).toBe(1_000_000n);
expect(payouts.get('idle').lamports).toBe(0n);
});
it('pays nothing at all when the pool is unfunded', () => {
const { payouts } = distributeEpoch({
epoch: E,
positions,
agentWeights: new Map([[AGENT_A, 1]]),
poolLamports: 0n,
now: E_START + EPOCH_SECONDS,
});
expect(payouts.get('a').lamports).toBe(0n);
expect(payouts.get('a').posWeight).toBeGreaterThan(0);
});
it('halves the share of a position that was only open for half the epoch', () => {
const { payouts } = distributeEpoch({
epoch: E,
positions: [
{ id: 'full', agentAsset: AGENT_A, principalLamports: 1_000_000_000n, openedAt: E_START, closedAt: null },
{
id: 'half',
agentAsset: AGENT_A,
principalLamports: 1_000_000_000n,
openedAt: E_START + EPOCH_SECONDS / 2,
closedAt: null,
},
],
agentWeights: new Map([[AGENT_A, 1]]),
poolLamports: 3_000_000n,
now: E_START + EPOCH_SECONDS,
});
expect(payouts.get('full').lamports).toBe(2_000_000n);
expect(payouts.get('half').lamports).toBe(1_000_000n);
});
});
describe('accruePosition', () => {
it('sums a position across every epoch it overlapped', () => {
const position = { id: 'a', agentAsset: AGENT_A, principalLamports: 1_000_000_000n, openedAt: E_START, closedAt: null };
const cohort = [position];
const agentWeights = new Map([[AGENT_A, 1]]);
const epochInputs = new Map([
[E, { poolLamports: 1_000_000n, positions: cohort, agentWeights }],
[E + 1, { poolLamports: 1_000_000n, positions: cohort, agentWeights }],
]);
const { lamports, byEpoch } = accruePosition({ position, epochInputs, now: E_START + 2 * EPOCH_SECONDS });
expect(lamports).toBe(2_000_000n);
expect(byEpoch.map((r) => r.epoch)).toEqual([E, E + 1]);
});
it('stops accruing the moment the position closes', () => {
const position = {
id: 'a',
agentAsset: AGENT_A,
principalLamports: 1_000_000_000n,
openedAt: E_START,
closedAt: E_START + EPOCH_SECONDS,
};
const agentWeights = new Map([[AGENT_A, 1]]);
const epochInputs = new Map([
[E, { poolLamports: 1_000_000n, positions: [position], agentWeights }],
[E + 1, { poolLamports: 1_000_000n, positions: [position], agentWeights }],
]);
const { lamports } = accruePosition({ position, epochInputs, now: E_START + 5 * EPOCH_SECONDS });
expect(lamports).toBe(1_000_000n);
});
});
describe('realizedApr', () => {
it('annualises what actually accrued, never a projection', () => {
const apr = realizedApr({
principalLamports: 1_000_000_000n,
earningsLamports: 10_000_000n,
openedAt: E_START,
closedAt: E_START + 365 * EPOCH_SECONDS,
now: E_START + 365 * EPOCH_SECONDS,
});
expect(apr).toBeCloseTo(0.01, 9);
});
it('is zero before any time has passed', () => {
expect(realizedApr({ principalLamports: 1n, earningsLamports: 1n, openedAt: E_START, closedAt: E_START, now: E_START })).toBe(0);
});
});
describe('clampSettlement', () => {
it('returns principal in full even when the reward surplus is empty', () => {
const s = clampSettlement({ principalLamports: 5_000_000n, earningsLamports: 900n, surplusLamports: 0n });
expect(s.principal).toBe(5_000_000n);
expect(s.earnings).toBe(0n);
expect(s.clamped).toBe(true);
});
it('pays earnings whole when the surplus covers them', () => {
const s = clampSettlement({ principalLamports: 5_000_000n, earningsLamports: 900n, surplusLamports: 10_000n });
expect(s.earnings).toBe(900n);
expect(s.clamped).toBe(false);
});
});
describe('lamport helpers', () => {
it('parses decimal strings past Number.MAX_SAFE_INTEGER without loss', () => {
expect(toBigInt('9007199254740993')).toBe(9007199254740993n);
expect(toBigInt('not a number')).toBe(0n);
});
it('formats lamports as SOL', () => {
expect(formatSol(1_500_000_000n)).toBe('1.5000');
});
it('pins the market constants the wire format depends on', () => {
expect(MIN_STAKE_LAMPORTS).toBe(1_000_000n);
expect(MARKET_TAG).toBe('rsm.v1');
});
});
describe('registry extension: threews.unstake.v1', () => {
const SIG = '5'.repeat(88);
it('is a registered attestation kind', () => {
expect(KIND_MAP.unstake).toBe('threews.unstake.v1');
});
it('accepts a well-formed unstake envelope', () => {
expect(
validatePayload({
v: 1,
kind: 'threews.unstake.v1',
agent: AGENT_A,
stake: SIG,
principal: '1000000',
}),
).toBe(true);
});
it('rejects a principal sent as a number instead of a decimal string', () => {
expect(
validatePayload({ v: 1, kind: 'threews.unstake.v1', agent: AGENT_A, stake: SIG, principal: 1_000_000 }),
).toBe(false);
});
it('rejects an envelope that names no stake', () => {
expect(validatePayload({ v: 1, kind: 'threews.unstake.v1', agent: AGENT_A, principal: '1' })).toBe(false);
});
});