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.

docs(contracts): describe every contract in the directory, with the ERC-8004 addresses the right way round

nirholas97fc801ac93a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 62be492de..3bff623b2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -52,6 +52,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
- **The Agent Exchange stops offering a purchase its wallet cannot pay for**: On /agent-exchange two 3D agents buy and sell live crypto intel, and the buyer settles $0.01 of real USDC on Solana for every signal. The page already warned you when the buyer's wallet was too empty to settle, but it left the Buy intel button live anyway, so the only thing a click could produce was a failed payment. The button now turns itself off and says why, and the warning carries a Check again button, so a wallet you fund while the page is open recovers without a reload. The balance is also re-read after every purchase, so a settlement that empties the wallet is reflected immediately instead of one click too late. When the balance check itself does not answer, the page used to say nothing at all and quietly log a browser error; it now tells you the balance is unknown and offers the same retry. Two smaller fixes came with it: the page title and the buy button were being rewritten at load time from the translation catalog, which had drifted from the page and still carried the old punctuation, now corrected in all 85 languages; and the two avatar frames were keyboard stops that did nothing and showed no focus outline, so they are out of the tab order and the topic chips and buy button are two tabs closer for anyone navigating by keyboard. (`/agent-exchange`) `[fix, improvement]`
- **The agent-payment and MCP docs now show the code that actually ships**: Three developer docs had drifted from the code they document, in ways that cost a reader real time. The Payment Sessions walkthrough, which is the guide for giving an agent a budget instead of a wallet key, quoted five snippets that no longer match the source: the branch that refuses a payment when the budget will not cover it, the host-allowlist check (which has moved into a shared module so the dry-run simulator and the live enforcement can never disagree), the expiry sweep that refunds unspent budget, the dollars-to-atomic-units helper, and a column missing from the table definition. All five now match the shipped code line for line, and the page links the two source files it had not been pointing at. The MCP article listed the Solana vanity grinder at up to $0.50 scaled by the work done; it is a flat $0.05 per successful grind, and its setup example set a wallet variable the package does not read, so anyone copying it would have configured a payout address that was silently ignored. That example now shows only the variable that works, and says plainly that settlement is USDC on Solana mainnet. The IBM Granite forecasting example showed three data points for a tool that requires at least sixty-four, so a copied sample was guaranteed to be rejected; it now says so. (`/docs/aws-builder-center-agent-payment-sessions`) `[docs, fix]`
- **The Alibaba Cloud MCP server starts now, and five MCP packages document how to import them**: The @three-ws/alibaba-cloud-mcp package, which lets an agent use Qwen chat, embeddings, and model discovery on your own Alibaba Cloud key, could not start at all. Two faults, both on the first line of use: the check for whether the file was launched directly crashed before the server ever opened, and the three tools were registered with a schema format the MCP library rejects. Both are fixed, so the server now boots, advertises its tools, and answers a client. The payment-sessions MCP package had a documentation fault with the same cost: its quick start told you to set your session variable to the whole cookie including the name, which the server then wrapped in the cookie name again, so every session-management call came back unauthorized. It now says to use the cookie value, and ships its two runnable examples inside the published package instead of only in the repository. Five packages (payment sessions, Agora, alerts, the assistant widget, and Alibaba Cloud) gained a Programmatic use section showing the exact code to import their tools into a host of your own, and the sniper package's HTTP table now lists every endpoint it actually serves, including the paid close-position route it had left out. `[fix, sdk, docs]`
+- **The contracts README now describes the contracts that are actually there**: Anyone opening the on-chain contracts directory was reading a page written when it held three ERC-8004 registries. It now holds ten contracts and programs, including the two that custody real USDC on BNB Smart Chain, Base and Arbitrum, and the two Solana programs. The README listed none of them, claimed 25 tests where there are 242, and printed the canonical ERC-8004 identity addresses with mainnet and testnet swapped, so a developer copying them would have pointed at the wrong chain's registry. It also told you to edit a shared entry that seven testnets read from, which would have silently repointed all of them. All of that is corrected, the Solana build and test commands are documented, and the sample registration snippet now shows the values the function really returns. `[docs]`
- **The Duplicate button on your widgets works again**: Duplicating a widget from the dashboard failed every single time. The clone request never gave the new widget an identifier, and because the database requires one, the copy was rejected before it was written and the page showed only a generic server error with a support reference. A second, correct copy of the same clone logic was already in the codebase and the route simply was not using it; the route now runs that one, so duplicating gives you a real new widget with its own id, its own name ending in (copy), and the original's type, look, avatar and visibility carried over. The duplicate request also now carries the same cross-site request protection every other widget change already had, and it accepts an API key with write access, so you can clone a widget from a script as well as from the dashboard. Two smaller corrections travelled with it. When no chat provider is configured and the platform answers a visitor with its own placeholder line, that message is no longer filed in your transcript as though a model had written it. And chatting with one of the showcase widgets in the public gallery no longer tries to file a transcript against a widget that does not exist, which failed on every message. The developer reference now documents duplicate, stats, chat, transcripts and the knowledge base, all of which were live but undocumented. (`/dashboard/widgets`) `[fix, docs]`
- **The embed and sharing tutorials now describe the surfaces that actually exist**: An audit of eight beginner tutorials found several describing features the platform does not have. The avatar-swap tutorial sent readers to Widget Studio for a body swap it cannot do, through a gallery with filters, preview buttons, and a 'Bust cache' save dialog that were never built; it now documents the real one-click swap in the agent editor's Outfit panel, and explains why nothing needs a cache purge. The sharing tutorial claimed rich social previews came from the plain agent URL, which actually serves a generic card, and described a headless renderer, a 24-hour image cache, a 'Refresh preview image' button, and a private-profile toggle that do not exist; it now points at the real share URL that carries the agent's name, description, and card, and explains what genuinely controls discoverability. The AR tutorial's iframe example used an address that returns 404 for an avatar id. The embed quickstart showed an agent ID in the wrong format, overstated the bundle size, and had the effect of the shadow DOM backwards. The docs-world tutorial gained the search palette it never mentioned, and the greeting tutorial now warns that the editor's Greeting field is not what makes an embed talk. Five page descriptions were corrected too, including one promising knobs the tutorial never covered. (`/tutorials/swap-avatar-in-studio`) `[docs, fix]`
- **The embed tutorials now name the attribute that actually hides the built-in chat**: Several tutorials told you to set avatar-chat="off" to hide an agent's built-in chat input. It does not do that: it moves the avatar out of the chat column and lays the chat out as a plain bottom bar, leaving the input on screen. The multi-agent walkthrough leaned on it to keep its behind-the-scenes stage-director messages hidden, so anyone following it verbatim saw those messages leak into the visible chat. The affected tutorials now use chat="off", the real bare-avatar switch, and note that the brain still boots behind it so say(), ask(), and the event stream keep working. The same accuracy pass corrected the walking-avatar leaderboard example, which read fields the API never returns and so always rendered an empty top-walkers list, and the JavaScript API event table, which named the wrong key for the skill a tool-call event reports. (`/tutorials/web-component-end-to-end`) `[fix, docs]`
@@ -68,6 +69,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
- **The tokenized-stock board sorts the way you asked, with the busiest names first**: The Robinhood Chain stock board (and the API behind it) accepts a sort column and a direction. Both ran backwards: asking for the highest 24h volume returned the quietest tokens, the ones with no market at all led every column, and passing dir=asc handed back descending results. Numeric columns now read highest-first by default, dir=asc genuinely flips them, and a token with no price or no NAV feed sorts to the end in either direction instead of crowding the top. The response now also echoes the sort and direction that actually ran, so an unknown sort value comes back as the default it fell to rather than as the value you sent; the memecoin screener echoes its sort the same honest way. (`/markets/robinhood`) `[fix]`
- **The trades feed stopped labelling a winning exit with a losing multiple**: When an agent sells part of a position to take its initial stake back and lets the rest ride, only that final sell is recorded against the position, while the profit percentage covers both sells. The feed was working out the “×” badge from the final sell alone, so a trade that returned +88% could show up as “0.56× +88%” on the same row. The multiple is now worked out from the trade's actual return, so the two numbers always agree. A coin's page also asked the feed for every trade on that coin and was quietly given only the ones above +10%, hiding the rest of that coin's history; it now gets what it asked for. The feed also answers a malformed page cursor or coin address by saying so, instead of returning results for the wrong coin, and a database problem no longer looks like a platform where nobody has ever turned a profit. (`/trades`) `[fix]`
- **The trading and MCP docs now match what the code and the live API actually do**: An audit of eight documentation pages ran every command they print and checked every claim against the code behind it, then corrected what had drifted. The biggest one was in the trading tutorial: the command it gave you for verifying a fleet's fills on-chain asked for a field the leaderboard does not publish, so it returned an empty explorer link for every agent and the verification step could not be completed at all. It now uses the fields that exist, linking both legs of each trade straight to Solscan, and it skips agents whose wallet has not been provisioned yet instead of building a URL that goes nowhere. The MCP tool safety page undercounted the tools that share a name across two servers, which matters because that collision is exactly why a trust policy has to key on the namespaced id; it now lists all nine and prints a command that re-derives the list so it cannot go stale again. The MCP tool catalog itself had drifted from its source and was serving outdated descriptions for three tools, on a page whose whole promise is that it is generated from source and cannot drift; it has been regenerated. The package extraction guide had every version in its roster out of date along with its build and test columns, and still described a publisher field as missing that was set some time ago. The 10 SOL trading experiment page stated a risk rule in absolute terms that contradicted the setup script it tells you to run, which read as a bug in one of the two; the rule now carries the scope the code actually applies. (`/docs/mcp-safety`) `[docs, fix]`
+- **The trading control room now tells you when the agents cannot afford to trade**: The /trading page showed a green "Trading live" badge whenever the worker was up and the launch feed was connected. Both of those can be true while the agents' wallets are too empty to place a single buy, which is exactly what was happening: four of twelve armed wallets were below the minimum entry size and the page said everything was fine. It now reads the fleet verdict the trading worker already publishes, so an underfunded fleet says "Live, wallets underfunded" and one that cannot trade at all says "Out of SOL", each naming the real cause instead of blaming the feed. A new Wallets funded vital shows how many armed wallets can actually place their configured size, how much SOL would refill the rest, and whether the funding wallet can do it automatically or a person has to step in. An agent with no return to report now reads "ROI unavailable" rather than a stray dot. (`/trading`) `[fix, improvement]`
- **The trusted-agent leaderboard now ranks every candidate, not an arbitrary sample of them**: The leaderboard scores a capped pool of agents on every request, and that pool was selected in whatever order the database happened to return, from a candidate set roughly twice the cap. Half the agents with a real track record were silently skipped, so a top-scoring agent could be missing from the board entirely and two identical page loads could disagree on the ranking. The pool is now ordered by settled ledger volume before it is capped, so the strongest candidates are always scored and the board is stable between requests. Two related repairs: asking for a leaderboard with a non-numeric size (limit=abc) returned an empty board that looked exactly like 'no agent here is trusted', and now returns a plain error; and a database outage no longer publishes an empty leaderboard as if it were the truth, it reports the outage. (`/trending`) `[fix]`
- **The Tutor’s running tab and end-of-session invoice now show what you actually paid**: The Tutor charges one cent per answer and keeps an itemized tab you can reload later and close for a signed invoice. That ledger only ever knew how to store itself in a key-value service this deployment does not run, so nothing was ever written down: reopening the page never restored your history, and ending a session always produced an invoice reading "no questions" and a total of zero, however many answers you had paid for. The tab is now stored in the platform’s own database, so it survives a reload, a new browser tab, and any server restart, and the invoice lists every answer with its charge and a verification hash over the line items. Closing a session twice returns the identical invoice instead of a freshly stamped one, closing a session id that was never used no longer makes that id unusable for its real owner, and if the ledger itself is ever unreachable the page says so rather than quietly reporting that you owe nothing. Asking a question still succeeds even if the ledger write fails, because a bookkeeping outage should never cost you the answer you paid for. (`/tutor`) `[fix]`
- **The vanity receipt verifier stops calling honest receipts fraudulent, and the avatar CLI takes a Solana address**: Two documented commands did not do what their page said. The command-line verifier for a provably-fair vanity address receipt scored the difficulty claim with the retired flat model, the one that treats every Base58 character as equally likely. Every receipt issued since the leading-character correction landed therefore failed its difficulty check and was reported as untrustworthy, even though the in-browser verifier at /vanity/verify passed the same receipt. The verifier now reads the model each receipt names in its own signed difficulty block, exactly as the page and the SDK do, so current receipts verify and older ones keep verifying under the model they were issued under. Separately, the Rig Doctor page showed an avatar-manifest command taking a Solana address as the owner, which the CLI rejected outright: it understood Ethereum addresses and full CAIP-10 identifiers and nothing else. Since Solana is the home chain, a bare Solana address is now accepted and recorded as solana:mainnet-beta. Alongside those, eight tutorial and reference pages were audited against the code they describe: the Vercel self-hosting guide had a stale copy of the config file and pointed at a migrations folder that has moved, the MCP guide listed three placeholder OAuth scopes where the live server publishes twelve real per-capability ones, and the Avatar CLI page pinned a version number that npm has never had. (`/docs/rig-doctor`) `[fix, docs, sdk]`
diff --git a/STRUCTURE.md b/STRUCTURE.md
index 8c1f770e1..ba0919159 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -144,7 +144,7 @@ bottom.
| Open Inference Protocol (OIN v0.1) | spec [specs/OPEN_INFERENCE_PROTOCOL.md](specs/OPEN_INFERENCE_PROTOCOL.md), verifier [api/_lib/oin-verify.js](api/_lib/oin-verify.js), conformance runner [scripts/oin-conformance.mjs](scripts/oin-conformance.mjs), reference node [workers/stylize/oin.py](workers/stylize/oin.py) | In-repo | Phase 4 roadmap: the vendor-neutral wire protocol that decouples inference from any single provider. A job envelope, a signed capability advertisement at `GET /.well-known/oin`, and an Ed25519-signed response bound to the job by a SHA-256 digest over its RFC 8785 canonical form, so any third party can verify a node's result without trusting the transport or the platform. The stylize worker is the reference node behind `OIN_ENABLED=true` (byte-for-byte its pre-OIN self with the flag off) and self-hosted operators with no GCS bucket sign filesystem artifacts via `OIN_RESULT_DIR`. `node scripts/oin-conformance.mjs --node <url>` drives advertisement, submit, poll, response verification, and artifact hashing end to end. Settlement rides on [specs/inference-receipts.md](specs/inference-receipts.md). Tests: [tests/oin-verify.test.js](tests/oin-verify.test.js), [workers/stylize/test_stylize.py](workers/stylize/test_stylize.py) |
| Production server (Google Cloud Run) | [server/](server) + [Dockerfile](Dockerfile) | Live | Single Express container serving the static frontend, the vercel.json route table, and all `api/**` handlers with Vercel-parity routing; deploy via `npm run deploy:gcp` ([server/cloudbuild.yaml](server/cloudbuild.yaml)), crons via [scripts/create-gcp-scheduler.mjs](scripts/create-gcp-scheduler.mjs) · see [server/README.md](server/README.md) |
| Multiplayer 3D world (world.three.ws) | [deploy/world/](deploy/world) — [Dockerfile](deploy/world/Dockerfile), [cloudrun.yaml](deploy/world/cloudrun.yaml), [apply-hardening.sh](deploy/world/apply-hardening.sh), patches in [deploy/world/patches/](deploy/world/patches); health monitor [api/cron/world-health.js](api/cron/world-health.js) | Live · `hyperfy-world` on Cloud Run | [Hyperfy](https://github.com/hyperfy-xyz/hyperfy) pinned to an exact upstream commit and rebuilt with three local patches (server-side upload cap, `/status` blueprint-asset enumeration, fail-closed-without-`ADMIN_CODE`). World state (SQLite + uploaded assets) lives in the GCS bucket `world-three-ws-data` mounted at `/app/world`, so the container is stateless. **The world is gated:** without `ADMIN_CODE` Hyperfy's `effectiveRank` falls back to `Ranks.ADMIN` and every anonymous visitor gets server-side build rights — the fail-open default that emptied the world on 2026-06-12. Deploy + verify with `bash deploy/world/apply-hardening.sh`; builders unlock in-world with `/admin <code>`. See [deploy/world/README.md](deploy/world/README.md) |
-| On-chain identity | [contracts/](contracts) | In-repo | Foundry-based on-chain agent identity, ERC-8004 |
+| On-chain contracts (Solidity + Solana) | [contracts/](contracts) · [contracts/README.md](contracts/README.md) | Mixed: `ThreeWSPayments` + `ThreeWSFactory` live on BSC/Base/Arbitrum, the rest in-repo | Every contract and program three.ws owns, in one Foundry project plus two Anchor programs. ERC-8004 identity/reputation/validation registries (reference implementations of the canonical deployments the platform actually reads), the live x402 USDC receiver and its CREATE2 vanity factory, `AgentPayments`, `GreenfieldVault`, `WorldMoves`, and the Solana `skill_license` / `agent_invocation` programs. `forge test` covers the Solidity set with 242 tests across 8 suites; the Solana side is covered by the LiteSVM row below. Deploy status per contract and the address provenance per chain: [contracts/DEPLOYMENTS.md](contracts/DEPLOYMENTS.md) |
| Contract audit pack | [contracts/AUDIT-README.md](contracts/AUDIT-README.md), invariants [specs/ECONOMY_CONTRACT_INVARIANTS.md](specs/ECONOMY_CONTRACT_INVARIANTS.md), threat model [specs/ECONOMY_CONTRACT_THREAT_MODEL.md](specs/ECONOMY_CONTRACT_THREAT_MODEL.md), static analysis [contracts/audit/](contracts/audit) | In-repo | Everything a review firm needs on day one for the reputation, royalty and delegation contracts: scope + deploy status per contract, stable invariant ids with a positive and a negative test each, an assets/actors/failure-modes threat model, and committed Slither + Clippy output with every finding fixed or dispositioned in writing |
| Recurring payments (subscriptions + DCA) | Page [public/recurring.html](public/recurring.html) `→ /recurring`, module [src/recurring.js](src/recurring.js), lifecycle rules [api/_lib/recurring.js](api/_lib/recurring.js), APIs [api/agent-subscriptions.js](api/agent-subscriptions.js) `→ /api/agent-subscriptions` and [api/dca-strategies.js](api/dca-strategies.js) `→ /api/dca-strategies`, hourly crons `run-subscriptions` + `run-dca` in [api/cron/[name].js](api/cron/%5Bname%5D.js), schema [api/_lib/migrations/20260813191500_recurring_payment_lifecycle.sql](api/_lib/migrations/20260813191500_recurring_payment_lifecycle.sql) | Live | One signed ERC-7710 permission, then money moves on a schedule: a subscription transfers a fixed USDC amount to an agent's wallet each period, a DCA strategy swaps the same amount into a token through Uniswap V3. `/recurring` is the whole lifecycle in one place (create, pause, resume, cancel, per-charge history) plus an Incoming tab scoped by agent ownership rather than by payer, so a creator sees what is being paid in. Every attempt is written to `subscription_charges` / `dca_executions`, and one shared classifier decides what a failure means: a revoked or expired permission pauses the schedule with the reason attached, a network blip releases the period claim and retries for three ticks, a timeout is never retried (the only failure that could double-charge), a diverged DCA quote skips the period for free, and a platform-side relayer outage never counts against the owner at all. Settlement needs `AGENT_RELAYER_KEY` + `RPC_URL_<chainId>` on the deployment; DCA creation needs `DCA_ALLOWED_TOKEN_OUT` + `DCA_CHAIN_ID`. Docs: [docs/recurring-payments.md](docs/recurring-payments.md). Tests: [tests/recurring-charge-outcomes.test.js](tests/recurring-charge-outcomes.test.js), [tests/api/recurring-subscription-cron.test.js](tests/api/recurring-subscription-cron.test.js) |
| Solana program invariant tests | [contracts/program-tests/](contracts/program-tests) | In-repo | LiteSVM suite running the real compiled SBF bytecode of `skill_license` and `agent_invocation` against invariants `SL-*` and `AI-*`, with the real SPL Token and ATA programs loaded |
diff --git a/contracts/README.md b/contracts/README.md
index 09c555468..eeeee39ca 100644
--- a/contracts/README.md
+++ b/contracts/README.md
@@ -1,51 +1,112 @@
-# ERC-8004 Contracts (optional / reference)
+# three.ws on-chain contracts
-> **You probably don't need to deploy these.** The canonical ERC-8004 reference
-> contracts are already live at the same addresses on every major EVM chain
-> (see [`../src/erc8004/abi.js`](../src/erc8004/abi.js)). Identity:
-> `0x8004A818...` (mainnet) / `0x8004A169...` (testnet). This directory is kept
-> as a local reference implementation — useful if you ever need to fork, audit,
-> or run a private deployment.
+Every contract and program three.ws owns lives here: the Solidity set built with
+[Foundry](https://book.getfoundry.sh/), and the two Solana programs built with
+[Anchor](https://www.anchor-lang.com/). Solana is the home chain; the EVM
+contracts are additional surfaces.
> **Reviewing these contracts?** Start at [`AUDIT-README.md`](./AUDIT-README.md):
> scope, deploy status, where the money is, the invariant ids, and the exact
> commands that reproduce every coverage and static-analysis number.
-Three registries implementing [ERC-8004](https://eips.ethereum.org/EIPS/eip-8004) for the `3d-agent` project:
+> **You probably do not need to deploy the ERC-8004 registries.** The canonical
+> ERC-8004 reference contracts are already live at the same addresses on every
+> major EVM chain, and [`../src/erc8004/abi.js`](../src/erc8004/abi.js) already
+> points at them: identity `0x8004A169...` on mainnets, `0x8004A818...` on
+> testnets. The registry sources here are a local reference implementation,
+> useful if you need to fork, audit, or run a private deployment.
-- **IdentityRegistry** — ERC-721 agents with `tokenURI`, delegated wallet (EIP-712), and key/value metadata.
-- **ReputationRegistry** — one signed score per reviewer per agent, aggregated on-chain.
-- **ValidationRegistry** (not deployed; the platform uses the ERC-8004 reference registry instead): requested validators attest to off-chain proofs (e.g. glTF-Validator reports).
+## What is in here
-The browser code in `../src/erc8004/` already targets these ABIs — only the deployed addresses are missing.
+| Contract | Source | Role | Deploy status |
+| --- | --- | --- | --- |
+| `ThreeWSPayments` | [`ThreeWSPayments.sol`](./ThreeWSPayments.sol) | x402 pay-per-call USDC receiver | Live on BNB Smart Chain, Base, Arbitrum One. Custodies real USDC |
+| `ThreeWSFactory` | [`ThreeWSFactory.sol`](./ThreeWSFactory.sol) | CREATE2 deployer behind the platform's vanity addresses | Live on the same three chains |
+| `IdentityRegistry` | [`src/IdentityRegistry.sol`](./src/IdentityRegistry.sol) | ERC-8004 agents as ERC-721, EIP-712 delegated wallet, key/value metadata | Canonical ERC-8004 address live everywhere; not deployed from this tree |
+| `ReputationRegistry` | [`src/ReputationRegistry.sol`](./src/ReputationRegistry.sol) | One signed score per reviewer per agent, aggregated on-chain | Same as above |
+| `ValidationRegistry` | [`src/ValidationRegistry.sol`](./src/ValidationRegistry.sol) | Allow-listed validators attest to off-chain proofs (for example glTF-Validator reports) | Not deployed from this tree; the platform uses the ERC-8004 reference registry |
+| `AgentPayments` | [`src/AgentPayments.sol`](./src/AgentPayments.sol) | Payments in, split into authority and buyback shares, buyback swaps and burns | Not deployed. See [`AGENT_PAYMENTS.md`](./AGENT_PAYMENTS.md) |
+| `GreenfieldVault` | [`src/GreenfieldVault.sol`](./src/GreenfieldVault.sol) | Pay-to-unlock marketplace over a real BNB Greenfield cross-chain permission grant | Not deployed to a public chain; proven on an anvil fork |
+| `WorldMoves` | [`src/WorldMoves.sol`](./src/WorldMoves.sol) | Event-only move stream for the Agora world. No value, no admin | Not deployed to a public chain |
+| `skill_license` | [`skill-license/`](./skill-license) | Solana: a 1-of-1 NFT access key per purchased skill, revocable on refund | Not deployed. Program id reserved |
+| `agent_invocation` | [`agent-invocation/`](./agent-invocation) | Solana: verifiable agent-to-agent invocation events | Not deployed. Program id reserved |
-## Build & test
+Per-address provenance and every chain id: [`DEPLOYMENTS.md`](./DEPLOYMENTS.md).
+
+## Build and test the Solidity set
+
+Install Foundry once:
+
+```bash
+curl -L https://foundry.paradigm.xyz | bash
+foundryup
+```
+
+Then, from this directory:
```bash
forge build
-forge test -vv
+forge test
```
-25 tests across the three contracts. All passing.
+242 tests across 8 suites, all passing:
-## Deploy to Base Sepolia
+| Suite | Tests |
+| --- | --- |
+| `AgentPaymentsTest` | 57 |
+| `GreenfieldVaultTest` | 41 |
+| `IdentityRegistryTest` | 37 |
+| `ReputationRegistryTest` | 31 |
+| `ThreeWSPaymentsTest` | 22 |
+| `ValidationRegistryTest` | 22 |
+| `WorldMovesTest` | 19 |
+| `ThreeWSFactoryTest` | 13 |
-1. Install Foundry if you haven't:
+`forge test --summary` reprints that table. Dependencies (`forge-std`,
+`openzeppelin-contracts`) are vendored under `lib/`, so no `forge install` step
+is needed.
- ```bash
- curl -L https://foundry.paradigm.xyz | bash && foundryup
- ```
+## Build and test the Solana programs
+
+The invariant suite in [`program-tests/`](./program-tests) runs the real compiled
+SBF bytecode in LiteSVM, so the bytecode has to exist before the tests run:
-2. Fund a deployer wallet with Base Sepolia ETH: https://www.alchemy.com/faucets/base-sepolia
+```bash
+cd skill-license && cargo-build-sbf
+cd ../agent-invocation && cargo-build-sbf
+cd ../program-tests && cargo test
+```
-3. Configure environment:
+`cargo-build-sbf` ships with the Solana (Agave) toolchain, and `cargo test` needs
+a host Rust toolchain:
+
+```bash
+sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"
+export PATH="$HOME/.local/share/solana/install/active_release/bin:$PATH"
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
+```
+
+A cold SBF build takes minutes per program; the tests themselves run in seconds.
+Green is 32 tests, 21 for `skill_license` and 11 for `agent_invocation`. The
+harness, the invariant ids, and the reason the LiteSVM clock must be set are all
+documented in [`program-tests/README.md`](./program-tests/README.md).
+
+## Deploy the registries to Base Sepolia
+
+Only needed for a private or forked deployment. The platform itself reads the
+canonical registries.
+
+1. Fund a deployer wallet with Base Sepolia ETH:
+ https://www.alchemy.com/faucets/base-sepolia
+
+2. Configure environment:
```bash
cp .env.example .env
# Fill in DEPLOYER_PK and BASESCAN_API_KEY
```
-4. Deploy + verify:
+3. Deploy and verify:
```bash
source .env
@@ -56,28 +117,51 @@ forge test -vv
--verify
```
-5. Copy the three addresses from the console output into [`../src/erc8004/abi.js`](../src/erc8004/abi.js) under the `84532` entry of `REGISTRY_DEPLOYMENTS`.
+ To rehearse without spending anything, point `--rpc-url` at a local
+ `anvil` and use one of its funded dev keys. The script prints the three
+ addresses and the `ValidationRegistry` owner either way.
+
+4. Point the browser code at your deployment. In
+ [`../src/erc8004/abi.js`](../src/erc8004/abi.js), `REGISTRY_DEPLOYMENTS[84532]`
+ currently references the shared `TESTNET` constant that all seven supported
+ testnets point at, so editing that constant would repoint every one of them.
+ Replace the single entry with a literal instead:
+
+ ```js
+ 84532: {
+ identityRegistry: '0xYourIdentityRegistry',
+ reputationRegistry: '0xYourReputationRegistry',
+ validationRegistry: '0xYourValidationRegistry',
+ },
+ ```
-## Deploy to Base mainnet
+## Deploy the registries to Base mainnet
-Same as above but with `$BASE_RPC_URL`, and update the `8453` entry in `abi.js`.
+Same as above with `$BASE_RPC_URL`, replacing the `8453` entry (which references
+the shared `MAINNET` constant) the same way.
-## After deploy: register the three.ws itself
+## After deploy: register three.ws itself
```js
-// Browser console on three.ws with wallet connected to Base Sepolia:
+// Browser console on three.ws with a wallet connected to Base Sepolia:
import { registerAgent } from './src/erc8004/index.js';
const r = await registerAgent({
- glbFile: /* your GLB File */,
name: 'three.ws',
description: 'AI-powered 3D model viewer & validation agent',
- apiToken: 'YOUR_WEB3STORAGE_TOKEN',
+ glbFile: yourGlbFile, // a File; omit and pass glbUrl if it is already pinned
onStatus: console.log,
});
-console.log(r); // { agentId, registrationCID, txHash }
+console.log(r); // { agentId, registrationUrl, txHash, chainId }
```
-Then update [`../public/.well-known/agent-registration.json`](../public/.well-known/agent-registration.json):
+Pinning uses the platform's built-in R2 backend by default. Pass
+`apiToken: '<your Pinata JWT>'` to pin through your own Pinata account instead.
+The full option list (2D image, auto thumbnail, declared services, x402 support)
+is documented on `registerAgent` in
+[`../src/erc8004/agent-registry.js`](../src/erc8004/agent-registry.js).
+
+Then update
+[`../public/.well-known/agent-registration.json`](../public/.well-known/agent-registration.json):
```json
"registrations": [
@@ -107,24 +191,39 @@ approves it as an operator instead: `approve(validator, agentId)` or
The validator then answers with
`validationResponse(requestHash, response, responseURI, responseHash, tag)`, which
-the `recordValidation()` helper in `../src/erc8004/validation-recorder.js` wraps
-(including the request leg when the same wallet owns the agent).
+the `recordValidation()` helper in
+[`../src/erc8004/validation-recorder.js`](../src/erc8004/validation-recorder.js)
+wraps (including the request leg when the same wallet owns the agent).
## Layout
```
contracts/
+├── ThreeWSPayments.sol live x402 USDC receiver
+├── ThreeWSFactory.sol live CREATE2 vanity deployer
├── src/
│ ├── IdentityRegistry.sol
│ ├── ReputationRegistry.sol
-│ └── ValidationRegistry.sol
-├── test/
-│ ├── IdentityRegistry.t.sol
-│ ├── ReputationRegistry.t.sol
-│ └── ValidationRegistry.t.sol
-├── script/
-│ └── Deploy.s.sol
+│ ├── ValidationRegistry.sol
+│ ├── IIdentityRegistry.sol
+│ ├── AgentPayments.sol
+│ ├── GreenfieldVault.sol
+│ ├── WorldMoves.sol
+│ └── greenfield/ BNB Greenfield precompile interfaces
+├── test/ 8 Foundry suites, 242 tests
+│ └── mocks/ MockGreenfield, Reentrant
+├── script/ Foundry deploy scripts, one per contract
+├── skill-license/ Anchor program + DEPLOYMENT.md
+├── agent-invocation/ Anchor program
+├── program-tests/ LiteSVM invariant suite over the real bytecode
+├── idl/ vendored Anchor IDLs (ours plus the launchpad
+│ interfaces the platform reads; see idl/pump/README.md)
+├── audit/ committed Slither + Clippy output
+├── vanity/ CREATE2 salt grind artifacts
+├── lib/ vendored forge-std + openzeppelin-contracts
+├── AUDIT-README.md start here for a review
+├── DEPLOYMENTS.md address provenance per chain
+├── AGENT_PAYMENTS.md AgentPayments design notes
├── foundry.toml
-├── .env.example
-└── README.md
+└── .env.example
```
diff --git a/contracts/test/mocks/MockGreenfield.sol b/contracts/test/mocks/MockGreenfield.sol
index 439bc14e8..f974aefbe 100644
--- a/contracts/test/mocks/MockGreenfield.sol
+++ b/contracts/test/mocks/MockGreenfield.sol
@@ -60,6 +60,9 @@ contract MockPermissionHub is IPermissionHub {
bool public rejectOnCreate;
bool public rejectOnDelete;
+ /// @dev Revert reason for the `prepare*` overrides. See the note above them.
+ string internal constant PREPARE_UNSUPPORTED = "MockPermissionHub: vault does not use the prepare path";
+
struct PendingCreate {
address caller; // becomes the minted policy's owner on success, mirrors real `_doCreate`
bytes callbackData;
@@ -122,13 +125,23 @@ contract MockPermissionHub is IPermissionHub {
return true;
}
+ /*----------------- prepare* : deliberately rejected -----------------*/
+ //
+ // The real PermissionHub exposes a `prepare*` family used by callers that
+ // relay their own cross-chain packages. `GreenfieldVault` never takes that
+ // path: it calls `createPolicy` / `deletePolicy` directly and pays the relay
+ // fee itself. These four overrides exist because `IPermissionHub` declares
+ // them, and they revert so that a future vault change routing through the
+ // prepare path fails loudly in the suite instead of silently passing against
+ // a mock that guessed at semantics it was never given.
+
function prepareCreatePolicy(address, bytes calldata)
external
payable
override
returns (uint8, bytes memory, uint256, uint256, address)
{
- revert("not implemented");
+ revert(PREPARE_UNSUPPORTED);
}
function prepareCreatePolicy(address, bytes calldata, ExtraData memory)
@@ -137,7 +150,7 @@ contract MockPermissionHub is IPermissionHub {
override
returns (uint8, bytes memory, uint256, uint256, address)
{
- revert("not implemented");
+ revert(PREPARE_UNSUPPORTED);
}
function prepareDeletePolicy(address, uint256)
@@ -146,7 +159,7 @@ contract MockPermissionHub is IPermissionHub {
override
returns (uint8, bytes memory, uint256, uint256, address)
{
- revert("not implemented");
+ revert(PREPARE_UNSUPPORTED);
}
function prepareDeletePolicy(address, uint256, ExtraData memory)
@@ -155,7 +168,7 @@ contract MockPermissionHub is IPermissionHub {
override
returns (uint8, bytes memory, uint256, uint256, address)
{
- revert("not implemented");
+ revert(PREPARE_UNSUPPORTED);
}
/*----------------- internal -----------------*/
diff --git a/data/changelog.json b/data/changelog.json
index 6ca646fae..4573e6fe3 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,24 @@
{
"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security. `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-08-15",
+ "title": "The trading control room now tells you when the agents cannot afford to trade",
+ "summary": "The /trading page showed a green \"Trading live\" badge whenever the worker was up and the launch feed was connected. Both of those can be true while the agents' wallets are too empty to place a single buy, which is exactly what was happening: four of twelve armed wallets were below the minimum entry size and the page said everything was fine. It now reads the fleet verdict the trading worker already publishes, so an underfunded fleet says \"Live, wallets underfunded\" and one that cannot trade at all says \"Out of SOL\", each naming the real cause instead of blaming the feed. A new Wallets funded vital shows how many armed wallets can actually place their configured size, how much SOL would refill the rest, and whether the funding wallet can do it automatically or a person has to step in. An agent with no return to report now reads \"ROI unavailable\" rather than a stray dot.",
+ "tags": [
+ "fix",
+ "improvement"
+ ],
+ "link": "/trading"
+ },
+ {
+ "date": "2026-08-15",
+ "title": "The contracts README now describes the contracts that are actually there",
+ "summary": "Anyone opening the on-chain contracts directory was reading a page written when it held three ERC-8004 registries. It now holds ten contracts and programs, including the two that custody real USDC on BNB Smart Chain, Base and Arbitrum, and the two Solana programs. The README listed none of them, claimed 25 tests where there are 242, and printed the canonical ERC-8004 identity addresses with mainnet and testnet swapped, so a developer copying them would have pointed at the wrong chain's registry. It also told you to edit a shared entry that seven testnets read from, which would have silently repointed all of them. All of that is corrected, the Solana build and test commands are documented, and the sample registration snippet now shows the values the function really returns.",
+ "tags": [
+ "docs"
+ ]
+ },
{
"date": "2026-08-15",
"title": "Pages stop loading a 3D robot you have not scrolled to yet",
diff --git a/prompts/swarm-100/sdk-contracts.md b/prompts/swarm-100/sdk-contracts.md
deleted file mode 100644
index e759c77f5..000000000
--- a/prompts/swarm-100/sdk-contracts.md
+++ /dev/null
@@ -1,89 +0,0 @@
-# Module audit: contracts/
-
-How to run: paste this file's repo path into a fresh Claude Code chat in this
-repository and say "run this work order". This file is fully self-contained:
-it depends on no other prompt file anywhere. If neighboring files in
-prompts/swarm-100/ are gone, that work is done; if present, ignore them.
-Every claim below rots; step 0 re-measures, and what you measure wins.
-
-## Operating clause (binding)
-
-- Read CLAUDE.md first. Its rules override everything, including this file.
-- Finish 100% in this session. Never end the turn with a question, an option
- list, or an unexecuted plan. A judgment call goes in one line of the final
- report; it never becomes a question that halts work.
-- The only permitted stops are the CLAUDE.md stop-and-ask gates: spending real
- funds or any irreversible on-chain write, git push or a production deploy,
- committing content that references a crypto project other than $THREE, and
- destroying unrecoverable data.
-- No mocks, no fake data, no placeholder stubs, no unfinished-work markers, no
- commented-out code. Real APIs and real integrations only.
-- The em-dash and en-dash characters are banned in everything you write.
-- Concurrent agents share this worktree: stage explicit paths only (never a
- bare add-everything), and commit finished work promptly.
-- Before committing, run: npm run check:rules -- --paths <files you touched>.
- It must exit 0.
-
-## Step 0: re-derive the current state
-
-1. Read contracts/README.md and contracts/package.json (or the equivalent manifest).
-2. Find every consumer: grep the repo for imports of this module and check
- STRUCTURE.md for the surfaces it powers.
-
-## Task: bring contracts/ to verified-shippable
-
-1. Build it with its own build script; the build must succeed from this
- worktree.
-2. Run its tests; add a core-path test if none proves the main export works.
-3. README quickstart: execute it verbatim as a new user would. Every command
- must run, every code sample must work. Fix drift in the same change.
-4. Public API: import the declared entry points with node and confirm they
- load. Exported functions the README documents must exist and behave as
- documented.
-5. Hard-rule scan across its source: no stubs, no mock data, no unfinished
- markers, no commented-out code.
-6. If this module publishes an artifact consumed elsewhere (a UMD bundle, a
- published npm package, a served static build), verify the wiring that
- produces the artifact still works; never hand-edit generated output.
-
-## Definition of done
-
-- [ ] Build green from this worktree.
-- [ ] Tests green, core path covered.
-- [ ] README quickstart executed successfully end to end.
-- [ ] Entry points import cleanly; documented API verified real.
-- [ ] Zero hard-rule violations remain in this module.
-- [ ] npm run check:rules -- --paths <touched files> exits 0.
-
-## Never blocked
-
-| Blocker | Resolution (act, do not ask) |
-|---|---|
-| Missing env var or credential | Check .env and .env.local, then the Cloud Run service env, then Secret Manager (the CLAUDE.md self-unblock playbook has the exact commands). If it truly exists nowhere, wire the code fully behind the env var, prove the wiring with a dry run, and name the single missing var in the report. |
-| gcloud not on PATH | Run: export PATH="$HOME/google-cloud-sdk/bin:$PATH" |
-| Dev server port 3000 busy | Another agent may be serving this repo; probe it and reuse if so. Otherwise start your own on a free port: npx vite --port 3101 |
-| Playwright browser missing | npx playwright install chromium |
-| A surface needs a signed-in user | Register a fresh account through the real /register flow against the real API and use it. Never mock the session. |
-| A defect sits in code you did not touch | Fix it if it blocks a Definition of done line (root cause it, never mask it). Otherwise note it in the report and continue. |
-| An unrelated test is red | Same rule. Never pipe npm test through tail; it masks exit codes. |
-
-## Close out (required)
-
-1. Verify every Definition of done line with the actual command output in
- front of you. Never claim a line you did not verify.
-2. Commit with explicit paths and a subject that describes the diff (house
- style: type(scope): what changed and why a reader cares).
-3. Delete this prompt file in that same commit:
-
- git rm prompts/swarm-100/sdk-contracts.md
-
- The shrinking directory is this campaign's only progress ledger; there is
- no progress log to update.
-4. Final report: what step 0 measured, what changed (file list), evidence per
- Definition of done line, and any one-line judgment calls. No trailing
- questions, no unexecuted plans.
-
-If a line genuinely cannot pass inside this session (an external party must
-respond, or an owner-gated action is the final step), finish everything else,
-leave this file in place, and state exactly which line remains and who owns
-it. Never delete this file on a partial.
diff --git a/public/changelog.json b/public/changelog.json
index a40ffeaf2..fdd5e97de 100644
--- a/public/changelog.json
+++ b/public/changelog.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-08-15T17:52:56.554Z",
+ "generated_at": "2026-08-15T19:03:12.893Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
@@ -503,6 +503,16 @@
"docs"
]
},
+ {
+ "date": "2026-08-15",
+ "type": "update",
+ "title": "The contracts README now describes the contracts that are actually there",
+ "summary": "Anyone opening the on-chain contracts directory was reading a page written when it held three ERC-8004 registries. It now holds ten contracts and programs, including the two that custody real USDC on BNB Smart Chain, Base and Arbitrum, and the two Solana programs. The README listed none of them, claimed 25 tests where there are 242, and printed the canonical ERC-8004 identity addresses with mainnet and testnet swapped, so a developer copying them would have pointed at the wrong chain's registry. It also told you to edit a shared entry that seven testnets read from, which would have silently repointed all of them. All of that is corrected, the Solana build and test commands are documented, and the sample registration snippet now shows the values the function really returns.",
+ "link": null,
+ "tags": [
+ "docs"
+ ]
+ },
{
"date": "2026-08-15",
"type": "update",
@@ -675,6 +685,17 @@
"fix"
]
},
+ {
+ "date": "2026-08-15",
+ "type": "update",
+ "title": "The trading control room now tells you when the agents cannot afford to trade",
+ "summary": "The /trading page showed a green \"Trading live\" badge whenever the worker was up and the launch feed was connected. Both of those can be true while the agents' wallets are too empty to place a single buy, which is exactly what was happening: four of twelve armed wallets were below the minimum entry size and the page said everything was fine. It now reads the fleet verdict the trading worker already publishes, so an underfunded fleet says \"Live, wallets underfunded\" and one that cannot trade at all says \"Out of SOL\", each naming the real cause instead of blaming the feed. A new Wallets funded vital shows how many armed wallets can actually place their configured size, how much SOL would refill the rest, and whether the funding wallet can do it automatically or a person has to step in. An agent with no return to report now reads \"ROI unavailable\" rather than a stray dot.",
+ "link": "/trading",
+ "tags": [
+ "fix",
+ "improvement"
+ ]
+ },
{
"date": "2026-08-15",
"type": "update",
diff --git a/public/changelog.xml b/public/changelog.xml
index dc6ca6e7e..2180b94fe 100644
--- a/public/changelog.xml
+++ b/public/changelog.xml
@@ -374,6 +374,14 @@
<category>fix</category>
<description>The @three-ws/alibaba-cloud-mcp package, which lets an agent use Qwen chat, embeddings, and model discovery on your own Alibaba Cloud key, could not start at all. Two faults, both on the first line of use: the check for whether the file was launched directly crashed before the server ever opened, and the three tools were registered with a schema format the MCP library rejects. Both are fixed, so the server now boots, advertises its tools, and answers a client. The payment-sessions MCP package had a documentation fault with the same cost: its quick start told you to set your session variable to the whole cookie including the name, which the server then wrapped in the cookie name again, so every session-management call came back unauthorized. It now says to use the cookie value, and ships its two runnable examples inside the published package instead of only in the repository. Five packages (payment sessions, Agora, alerts, the assistant widget, and Alibaba Cloud) gained a Programmatic use section showing the exact code to import their tools into a host of your own, and the sniper package's HTTP table now lists every endpoint it actually serves, including the paid close-position route it had left out.</description>
</item>
+ <item>
+ <title>The contracts README now describes the contracts that are actually there</title>
+ <link>https://three.ws/changelog</link>
+ <guid isPermaLink="false">2026-08-15:The contracts README now describes the contracts that are actually there</guid>
+ <pubDate>Sat, 15 Aug 2026 12:00:00 GMT</pubDate>
+ <category>docs</category>
+ <description>Anyone opening the on-chain contracts directory was reading a page written when it held three ERC-8004 registries. It now holds ten contracts and programs, including the two that custody real USDC on BNB Smart Chain, Base and Arbitrum, and the two Solana programs. The README listed none of them, claimed 25 tests where there are 242, and printed the canonical ERC-8004 identity addresses with mainnet and testnet swapped, so a developer copying them would have pointed at the wrong chain's registry. It also told you to edit a shared entry that seven testnets read from, which would have silently repointed all of them. All of that is corrected, the Solana build and test commands are documented, and the sample registration snippet now shows the values the function really returns.</description>
+ </item>
<item>
<title>The Duplicate button on your widgets works again</title>
<link>https://three.ws/dashboard/widgets</link>
@@ -502,6 +510,14 @@
<category>docs</category>
<description>An audit of eight documentation pages ran every command they print and checked every claim against the code behind it, then corrected what had drifted. The biggest one was in the trading tutorial: the command it gave you for verifying a fleet's fills on-chain asked for a field the leaderboard does not publish, so it returned an empty explorer link for every agent and the verification step could not be completed at all. It now uses the fields that exist, linking both legs of each trade straight to Solscan, and it skips agents whose wallet has not been provisioned yet instead of building a URL that goes nowhere. The MCP tool safety page undercounted the tools that share a name across two servers, which matters because that collision is exactly why a trust policy has to key on the namespaced id; it now lists all nine and prints a command that re-derives the list so it cannot go stale again. The MCP tool catalog itself had drifted from its source and was serving outdated descriptions for three tools, on a page whose whole promise is that it is generated from source and cannot drift; it has been regenerated. The package extraction guide had every version in its roster out of date along with its build and test columns, and still described a publisher field as missing that was set some time ago. The 10 SOL trading experiment page stated a risk rule in absolute terms that contradicted the setup script it tells you to run, which read as a bug in one of the two; the rule now carries the scope the code actually applies.</description>
</item>
+ <item>
+ <title>The trading control room now tells you when the agents cannot afford to trade</title>
+ <link>https://three.ws/trading</link>
+ <guid isPermaLink="false">2026-08-15:The trading control room now tells you when the agents cannot afford to trade</guid>
+ <pubDate>Sat, 15 Aug 2026 12:00:00 GMT</pubDate>
+ <category>fix</category>
+ <description>The /trading page showed a green &quot;Trading live&quot; badge whenever the worker was up and the launch feed was connected. Both of those can be true while the agents' wallets are too empty to place a single buy, which is exactly what was happening: four of twelve armed wallets were below the minimum entry size and the page said everything was fine. It now reads the fleet verdict the trading worker already publishes, so an underfunded fleet says &quot;Live, wallets underfunded&quot; and one that cannot trade at all says &quot;Out of SOL&quot;, each naming the real cause instead of blaming the feed. A new Wallets funded vital shows how many armed wallets can actually place their configured size, how much SOL would refill the rest, and whether the funding wallet can do it automatically or a person has to step in. An agent with no return to report now reads &quot;ROI unavailable&quot; rather than a stray dot.</description>
+ </item>
<item>
<title>The trusted-agent leaderboard now ranks every candidate, not an arbitrary sample of them</title>
<link>https://three.ws/trending</link>