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): put the knock escrow program on the contracts README and the structure map

nirholasdb1ea40a7ce3
diff --git a/STRUCTURE.md b/STRUCTURE.md
index 33d60c0b2..fe51a7b25 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -183,7 +183,7 @@ bottom.
| 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) |
| Metaplex Agent Registry deploy (Genesis-333 mint for everyone) | [pages/deploy-onchain.html](pages/deploy-onchain.html) + [src/deploy-onchain.js](src/deploy-onchain.js) `→ /deploy-onchain`, shared builders [packages/metaplex-agent-mcp/src/lib/](packages/metaplex-agent-mcp/src/lib) (published as `@three-ws/metaplex-agent-mcp`, also in the official MCP registry as `io.github.nirholas/metaplex-agent`) | Live | Mint any agent into the Metaplex Agent Registry in the exact Genesis 333 shape: data: URI metadata, verified creator, 5% royalties, immutable metadata, EIP-8004 identity with `model.uri` + `x402Support`. The page signs with the user's own wallet (Phantom/Solflare/Backpack, `signAllTransactions`) through the same-origin RPC proxy; the MCP server gives agents the identical mint with their own key (preview-first, `confirm:true` gated) plus a prepare/send lane for external wallets. Both consume one isomorphic builder library, and [tests](packages/metaplex-agent-mcp/test/genesis-shape.test.mjs) pin the output byte-for-byte to the live Genesis #332 URIs. Devnet is a free rehearsal lane end-to-end. A mainnet deploy also pays a flat 0.02 SOL fee to the $THREE buyback wallet, halved at 50k $THREE in the paying wallet and waived at 250k, disclosed in every preview and carried inside the create transaction ([packages/metaplex-agent-mcp/src/lib/three.js](packages/metaplex-agent-mcp/src/lib/three.js)); the `three_status` tool prices it against any wallet. |
| Onchain agent wallets (spending allowances, not private keys) | [packages/onchain-agent-wallets/](packages/onchain-agent-wallets) (published as `@three-ws/onchain-agent-wallets`, MCP registry `io.github.nirholas/onchain-agent-wallets`) | Live | Give an agent a Solana wallet without giving it the money. Funds sit in a vault token account the OWNER owns, derived deterministically from the owner address plus the agent id (`createWithSeed(owner, "oaw1:<agent>")`); the agent holds only a capped SPL Token delegation over it, so the token program itself refuses any spend past the ceiling and decrements it on every transfer. Guardrails on top (per-tx, rolling daily, recipient and host allowlists, expiry, pause, confirm-above threshold) are enforced before signing, and every decision including refusals lands in a local ledger. `pay_x402` probes the price unpaid, checks it against the guardrails, tops the agent up for exactly that amount, pays, and leaves it empty. Owner actions need no key on the machine: they come back as unsigned transactions for Phantom/Solflare/Ledger. [Delegation tests](packages/onchain-agent-wallets/test/token-delegation.test.mjs) run the real SPL Token program in process and assert that 61 against a remaining allowance of 60 fails on-chain. |
-| 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) |
+| 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 three 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 |
@@ -200,6 +200,7 @@ bottom.
| pump.fun first-claims Telegram channel (@pumpfunclaims) | Delivery lane [api/_lib/pump-claims-push.js](api/_lib/pump-claims-push.js), cron [api/cron/pump-claims-push.js](api/cron/pump-claims-push.js) (every 5 min), shared scanner [api/_lib/pump-claims.js](api/_lib/pump-claims.js) (also backs `GET /api/pump/first-claims` and the `pumpfun_first_claims` MCP tool) | In-repo · lane wired, channel dark pending `PUMPFUN_BOT_URL` + `TELEGRAM_PUMP_CLAIMS_CHAT_ID` | A live feed of first-time pump.fun creator fee claims, one message per claim: the first time a creator ever pulls accrued rewards out of the fee vault is an irreversible on-chain signal that they are engaged with their coin. Mirrors the commit-feed lane's safety properties (DB lock, seed-without-posting on first run, per-message state writes, oldest-first drain, 3h replay cutoff) but dedupes by transaction signature rather than timestamp, because claims routinely share a second and a timestamp cursor drops the second one. No fallback to the holder changelog channel on purpose. The RPC fallback inside the scanner cannot serve this feed (the pump program clears a 200-signature page in under one second, so a scan covers no useful window); an indexer is required. Docs: [docs/pump-claims-channel.md](docs/pump-claims-channel.md). Tests: [tests/pump-claims-push.test.js](tests/pump-claims-push.test.js) |
| Ship log (release notes joined to the commits that shipped them) | Package [packages/shipfeed/](packages/shipfeed/README.md), endpoint [api/ship/feed.js](api/ship/feed.js) `→ GET /api/ship/feed`, page [public/ship/index.html](public/ship/index.html) `→ /ship`, provenance for the announcement lane [api/_lib/ship-provenance.js](api/_lib/ship-provenance.js) | Live | The join between the two records of the same work this repo keeps: the changelog (readable, incomplete) and the commit log (complete, unreadable). `@three-ws/shipfeed` parses conventional commits, scores each one by audience (holder / developer / internal) and signal, and links release notes to the commits that produced them with no metadata in the workflow: a `Changelog:` trailer wins where one exists, otherwise a time window plus IDF-weighted term overlap plus tag agreement plus proximity, and every link publishes its confidence and its reasons (`?explain=<sha>` returns one commit's full reasoning). Unclaimed commits are grouped into bursts and shown as "unannounced", which is the half no changelog has ever surfaced. The same package now drives both Telegram lanes: release announcements carry a "shipped in N commits" compare link, and the raw commit feed reads its headline from the parser (`feat(resilience):` reads as "Feature · resilience") and skips merges, `chore(deps):` bumps and lockfile-only changes. Zero dependencies, works on any repository, CLI included (`npx @three-ws/shipfeed`). Docs: [docs/shipfeed.md](docs/shipfeed.md). Tests: [packages/shipfeed/tests/](packages/shipfeed/tests), [tests/ship-feed-endpoint.test.js](tests/ship-feed-endpoint.test.js), [tests/ship-provenance.test.js](tests/ship-provenance.test.js) |
| On-chain agent invocation | [contracts/agent-invocation/](contracts/agent-invocation) | In-repo | Anchor program: verifiable agent-to-agent skill invocation events. SDK: [agent-protocol-sdk/](agent-protocol-sdk) |
+| Escrowed knocks (pay-per-reply) | [contracts/knock-escrow/](contracts/knock-escrow) | In-repo | Anchor program making a knock's payment conditional instead of final: `knock` parks the price in a vault owned by the knock's own PDA, and only three things can happen to it. `answer` pays the owner minus a fee capped at 10% in the program itself, `refuse` refunds the sender in full and takes no fee, and `reclaim` refunds the sender once the reply window closes and can be called by anyone. Each `KnockRecord` snapshots the fee that was in force when it was made, so an authority cannot reprice money already in escrow, and it stores only the SHA-256 of the message and the reply, never their text. The trust-me version of this settles straight to the owner at [api/knock/](api/knock) (row above); this is the version that works between strangers. Docs: [contracts/knock-escrow/README.md](contracts/knock-escrow/README.md) |
| Cross-chain SDKs | [sdk/](sdk), [solana-agent-sdk/](solana-agent-sdk), [agent-payments-sdk/](agent-payments-sdk), [agent-protocol-sdk/](agent-protocol-sdk) | Published | Cross-chain agent SDKs |
| MCP integration | [mcp-server/](mcp-server), [mcp-bridge/](mcp-bridge), [packages/*-mcp/](packages) | 43 npm servers + 7 hosted remote (50 total, incl. the free `/api/mcp-studio` 3D Studio), all in the [MCP registry](https://registry.modelcontextprotocol.io/?q=io.github.nirholas). Canonical metadata: [prompts/store-submissions/_generated/mcp-listing-source.json](prompts/store-submissions/_generated/mcp-listing-source.json), generated from the manifests by [scripts/build-mcp-listing-source.mjs](scripts/build-mcp-listing-source.mjs) (`npm run audit:mcp-listing` fails when it drifts) | Model Context Protocol surface, full server list in [docs/mcp.md](docs/mcp.md). Searchable index of every tool: [pages/mcp-tools.html](pages/mcp-tools.html) `→ /mcp-tools`, rendered from the generated [public/mcp-catalog.json](public/mcp-catalog.json) ([scripts/build-mcp-catalog.mjs](scripts/build-mcp-catalog.mjs), `npm run build:mcp-catalog`, staleness gated by `npm run audit:mcp-catalog`). Tool safety annotations are verified against each handler by [scripts/audit-mcp-safety.mjs](scripts/audit-mcp-safety.mjs) (`npm run audit:mcp-safety`, rules in [scripts/lib/mcp-safety-check.mjs](scripts/lib/mcp-safety-check.mjs), guarded-file list shared with the golden snapshot via [scripts/lib/mcp-tool-sources.mjs](scripts/lib/mcp-tool-sources.mjs)); docs [docs/mcp-safety.md](docs/mcp-safety.md) `→ /docs/mcp-safety`. Trust policy: [api/mcp-policy.js](api/mcp-policy.js) `-> GET /api/mcp-policy` turns those verified labels into a ready-to-paste client allowlist (profiles strict/balanced/open x formats claude/vscode/json), surfaced by the builder panel on `/mcp-tools`. Connector-review readiness (every paid stdio tool answers a clean x402 challenge, and the reviewer entitlement lifts it): [scripts/audit-mcp-reviewer-path.mjs](scripts/audit-mcp-reviewer-path.mjs), `npm run audit:mcp-reviewer`. Tests: [tests/mcp-safety-audit.test.js](tests/mcp-safety-audit.test.js), [tests/mcp-catalog.test.js](tests/mcp-catalog.test.js), [tests/api/mcp-policy.test.js](tests/api/mcp-policy.test.js) |
| Agent Skills pack | [.agents/skills/](.agents/skills) → manifest [.agents/skills/SKILLS.md](.agents/skills/SKILLS.md), [.agents/skills/skills-pack.json](.agents/skills/skills-pack.json) | In-repo; bundled in the `three-ws-core` [plugin](.claude-plugin/marketplace.json) | 40 portable `SKILL.md` folders (Agent Skills open standard) for any Claude surface — 3d/creative (cross-platform-safe), wallet/payments, intel/trading. Regenerate manifest: `node scripts/build-skills-pack.mjs`. Docs: [docs/agent-skills.md](docs/agent-skills.md) |
diff --git a/contracts/README.md b/contracts/README.md
index eeeee39ca..0726c7293 100644
--- a/contracts/README.md
+++ b/contracts/README.md
@@ -1,7 +1,7 @@
# three.ws on-chain contracts
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
+[Foundry](https://book.getfoundry.sh/), and the three Solana programs built with
[Anchor](https://www.anchor-lang.com/). Solana is the home chain; the EVM
contracts are additional surfaces.
@@ -30,6 +30,7 @@ contracts are additional surfaces.
| `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 |
+| `knock_escrow` | [`knock-escrow/`](./knock-escrow) | Solana: a priced message held in escrow that pays out only against a reply, and refunds in full otherwise | Not deployed. Program id reserved |
Per-address provenance and every chain id: [`DEPLOYMENTS.md`](./DEPLOYMENTS.md).
@@ -72,8 +73,9 @@ The invariant suite in [`program-tests/`](./program-tests) runs the real compile
SBF bytecode in LiteSVM, so the bytecode has to exist before the tests run:
```bash
-cd skill-license && cargo-build-sbf
+cd skill-license && cargo-build-sbf
cd ../agent-invocation && cargo-build-sbf
+cd ../knock-escrow && cargo-build-sbf
cd ../program-tests && cargo test
```
@@ -87,9 +89,10 @@ 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).
+Green is 42 tests: 21 for `skill_license`, 11 for `agent_invocation`, and 10 for
+`knock_escrow`. 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
@@ -215,6 +218,7 @@ contracts/
├── script/ Foundry deploy scripts, one per contract
├── skill-license/ Anchor program + DEPLOYMENT.md
├── agent-invocation/ Anchor program
+├── knock-escrow/ Anchor program, escrowed pay-per-reply
├── 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)