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.

10.5 KB
Raw Blame

Docs: Reputation Staking Market

Stake conviction on an agent, earn from its attested action history. The Reputation Staking Market turns the existing threews.stake.v1 conviction signal into escrowed positions: principal sits in a market escrow, yield is derived per epoch from the agent's signed on-chain attestations, and a withdrawal returns principal plus earnings in one settlement transaction.

The load-bearing contract is specs/REPUTATION_STAKING_MARKET.md (rsm.v1). This page is the walkthrough; when the two disagree, the spec wins.

Live surface: /reputation/market.

What the market pays for

Reputation is already attested on Solana as signed SPL-Memo envelopes indexed into solana_attestations (see docs/solana-reputation). An agent's threews.accept.v1, threews.task.v1, threews.validation.v1, threews.feedback.v1, threews.dispute.v1, and threews.revoke.v1 envelopes are its attested action history: work it shipped, validations it passed or failed, and reviews it earned.

The market reads exactly that history and pays stakers for backing agents whose history is real. Each epoch (one UTC day) a fixed reward pool splits across every open position in proportion to:

posWeight = principal × epochFraction × agentWeight

where agentWeight comes from the agent's attestations that epoch: passed validations and accepted tasks count as work, failed validations, disputes, and revocations count as faults (at double weight), and the 1-5 feedback scale sets a quality multiplier. The full table, rounding rules, and constants live in spec §5; the only implementation is src/shared/reputation-staking.js, which runs identically on the server and in the browser.

Two consequences worth knowing before you stake:

  • An idle agent earns nothing. Zero attested work in an epoch means agentWeight === 0 for that epoch, so its stakers earn zero that epoch. Principal is never at risk; conviction on a quiet agent is just unrewarded.
  • Positions are never slashed. Bad conviction is punished by zero yield, not confiscated principal. The market expresses trust; it does not underwrite an agent's losses.

Networks

Network Status What it costs
devnet open Nothing. Airdropped lamports, the free proof path.
mainnet owner-gated Writes refuse with mainnet_gated until the owner sets REPUTATION_MARKET_ALLOW_MAINNET=1 on the service.

Opening mainnet is one owner action, one command:

gcloud run services update three-ws-api --region us-central1 \
  --update-env-vars REPUTATION_MARKET_ALLOW_MAINNET=1

Everything below works on devnet today, unchanged.

Stake

A stake is a transaction you sign and broadcast; the market never signs it. One transaction, two instructions: a transfer of your principal to the market escrow, and an SPL Memo envelope tagged market: "rsm.v1" naming the agent, your 1-5 conviction score, and the escrow. The transaction signature is your position id.

From the page, connect a Solana wallet on /reputation/market, pick an agent, choose an amount (minimum 0.001 SOL) and a conviction score, and sign. The page then calls POST /api/reputation/market-stake with the signature; the server verifies the transaction against the chain (memo shape, escrow match, balance delta) and indexes the position. Verification is a chain read, so no caller can assert a principal the chain did not record.

From code, stakeOnMarket in src/solana-stake.js builds the exact transaction:

import { stakeOnMarket } from '/solana-stake.js';

const signature = await stakeOnMarket({
	agentAsset: agent.solanaAsset,   // the agent's Solana asset pubkey
	escrow,                          // from GET /api/reputation/market
	lamports: 5_000_000n,            // 0.005 SOL
	score: 4,                        // 1-5 conviction
	network: 'devnet',
	wallet,                          // a connected wallet adapter
});
await fetch('/api/reputation/market-stake', {
	method: 'POST',
	headers: { 'content-type': 'application/json' },
	body: JSON.stringify({ signature, network: 'devnet' }),
});

Earn

The position starts accruing in the epoch it opens, for the fraction of the day it was actually open. Pending earnings recompute on every read; they are only fixed when a settlement lands. Watch them on the positions section of /reputation/market or read them directly:

curl "https://three.ws/api/reputation/market-positions?staker=<wallet>&network=devnet"

Every position row carries a per-epoch breakdown, so the number the page quotes is auditable against the spec, epoch by epoch.

Withdraw

There is no lockup. Withdraw any time. Only the wallet that opened a position can withdraw it: sign the text threews.unstake.v1:<network>:<stake signature>:<issued_at> with that wallet (issued_at is the current time in milliseconds; the server accepts it for 5 minutes) and send the base58 signature as proof. The /reputation/market page does this for you with one wallet prompt and no fee.

curl -X POST https://three.ws/api/reputation/market-withdraw \
  -H 'content-type: application/json' \
  -d '{"signature": "<stake signature>", "network": "devnet", "proof": {"issued_at": 1760000000000, "signature": "<base58 wallet signature>"}}'

The market escrow signs one settlement transaction paying principal plus earnings back to the staker recorded on-chain, with a threews.unstake.v1 memo carrying both numbers. Only the escrow ever signs a settlement, and it pays only the on-chain staker, so nobody can route your payout to themselves.

Withdrawal is idempotent: the position flips to settling before the payout is signed, so a crash is retried, never double-paid; a second withdrawal of a closed position returns the original settlement.

One solvency rule (spec §2): earnings can never exceed the escrow's reward surplus. If accrued earnings exceed the surplus, the payout clamps to the surplus and the settlement records clamped: true. Principal always returns in full.

What a withdrawal does to the agent's reputation

Settling retires the conviction the stake expressed. The agent's reputation card (GET /api/agents/solana-reputation) counts what is still staked, so your position drops out of stake.total_lamports and out of stake.top_stakers the moment the settlement lands. Backing an agent and then walking away does not leave a permanent endorsement behind.

The history is not erased: stake.gross_lamports still reports everything ever staked and stake.retired_lamports what settlement gave back, so "1 SOL staked, 3 SOL withdrawn" stays distinguishable from "1 SOL staked". Only the market escrow's settlements retire anything, so nobody can deflate an agent's standing by writing a memo naming somebody else's stake. Spec §3.3.

Verify it yourself

The database behind the market is an index, not the ledger. Every position is re-derivable by replaying the chain: positions from threews.stake.v1 memos into the escrow, settlements from threews.unstake.v1 memos out of it.

scripts/reputation-market-proof.mjs runs the whole contract against Solana devnet with airdropped lamports: fund, stake, verify, accrue against real attested action history, withdraw, and re-read the chain to confirm the settlement. It takes no arguments:

node scripts/reputation-market-proof.mjs

When the faucet says no

The public devnet faucet rate-limits per source IP, so a shared machine (a Codespace, a CI runner, an office network) can find it already exhausted by someone else and the run stops at fund with a 429. The proof does not depend on the faucet: fund any devnet keypair once at faucet.solana.com, then hand the proof its secret and it funds each run itself.

REPUTATION_MARKET_PROOF_FUNDER_SECRET_KEY=<base58 secret> node scripts/reputation-market-proof.mjs

The funder needs roughly 0.02 SOL per run and is only ever debited to the throwaway staker the run generates. If it is short, the proof says which account holds how much and what it needs, rather than failing at a later stage.

When there is no faucet and no funded keypair either

A local validator needs nothing external at all: solana-test-validator bundles the same SPL Memo program the attestations and the settlement memo use, and it airdrops without limit, so the whole contract runs offline.

solana-test-validator --reset --ledger /tmp/rsm-ledger &
solana-keygen new --no-bip39-passphrase --silent --outfile /tmp/rsm-funder.json
solana airdrop 20 "$(solana-keygen pubkey /tmp/rsm-funder.json)" --url http://127.0.0.1:8899

SOLANA_RPC_URL_DEVNET="http://127.0.0.1:8899/?cluster=devnet" \
REPUTATION_MARKET_PROOF_FUNDER_SECRET_KEY="$(cat /tmp/rsm-funder.json)" \
node scripts/reputation-market-proof.mjs

Two details in that command are load-bearing. The ?cluster=devnet suffix is how the RPC layer infers the cluster (inferNetwork in api/_lib/solana/connection.js); a bare localhost URL reads as mainnet and would queue mainnet endpoints as fallbacks behind it. And the funder rung is used rather than the faucet because requestAirdrop confirms over a WebSocket subscription, which a local validator serves on a port the derived URL does not point at; every other stage of the proof confirms over HTTP polling and works untouched.

HTTP surface

Endpoint Method Purpose
/api/reputation/market?network=devnet GET Agents ranked by net staked conviction, epoch weight, realized yield.
/api/reputation/market-positions?staker=<wallet>&network=devnet GET Every position a wallet holds, with pending earnings.
/api/reputation/market-stake POST Index a stake transaction. Body: { signature, network }.
/api/reputation/market-withdraw POST Settle a position. Body: { signature, network, proof }, where proof is the staker's signed unstake message.

Failure codes (market_not_configured, mainnet_gated, tx_not_found, not_a_market_stake, stake_below_minimum, unknown_position, already_closed, escrow_unsigned, proof_required, proof_expired, not_staker) are pinned in spec §9.

Related