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): give knock escrow the KE-* invariant ids its tests already prove

nirholasb9129fd9a6b6
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 09887f049..1b13d1dd6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,10 @@
Public history for [three.ws](https://three.ws), newest first. New pages come from `added` dates in data/pages.json; everything else is curated in data/changelog.json. Also available as [JSON](https://three.ws/changelog.json) and [RSS](https://three.ws/changelog.xml), live at [three.ws/changelog](https://three.ws/changelog).
+## 2026-09-04
+
+- **A knock now holds the money until you actually get a reply**: Paying to reach someone used to send your money the instant the payment cleared, which meant an owner could take every knock and answer none, and you had no way to get it back. A new Solana program makes the payment conditional: it sits in a vault that only the knock itself controls, and exactly three things can happen to it. The owner answers inside the reply window and gets paid, the owner declines and you are refunded in full with no fee taken, or the window closes and anyone at all can trigger your refund. There is no admin key that can move a knock that is parked, the fee is capped at 10% in the program itself, and the fee you agreed to when you knocked cannot be raised on money that is already in escrow. Your message never touches the chain: only a fingerprint of it is stored, so either side can later prove what was sent without publishing it. Ten invariants covering every one of those promises run against the real compiled program on every test run. `[feature, security]`
+
## 2026-09-03
- **Docs · Connect a home that is only on your network** (`/docs/home-relay`): Most Home Assistant installs cannot be reached from the internet, so the house dials three.ws instead: install one HACS integration, paste a ten-minute pairing code, and nothing listens on your network, no port is forwarded, and three.ws never receives a Home Assistant token. Includes the operator half: the relay service, its configuration and deploy, how the allowlist is changed, and how to prove the whole path against a real house on a network the server cannot route to.
diff --git a/STRUCTURE.md b/STRUCTURE.md
index fe51a7b25..f532e21a5 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -186,7 +186,7 @@ bottom.
| 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 |
+| Solana program invariant tests | [contracts/program-tests/](contracts/program-tests) | In-repo | LiteSVM suite running the real compiled SBF bytecode of `skill_license`, `agent_invocation`, and `knock_escrow` against invariants `SL-*`, `AI-*`, and `KE-*`, with the real SPL Token and ATA programs loaded. 42 tests green |
| Reputation Staking Market | spec [specs/REPUTATION_STAKING_MARKET.md](specs/REPUTATION_STAKING_MARKET.md), engine [src/shared/reputation-staking.js](src/shared/reputation-staking.js), server [api/_lib/reputation-market.js](api/_lib/reputation-market.js) + [api/reputation/market*.js](api/reputation), surface [public/reputation/market/](public/reputation/market) `→ /reputation/market` | In-repo · devnet open, mainnet owner-gated | Phase 3 roadmap: stake conviction on an agent and earn from its attested action history. A stake is a staker-signed Solana transfer to the market escrow carrying an `rsm.v1` SPL-Memo, so the chain (not the database) defines a position; the server only verifies it by reading the transaction back. Yield comes from a fixed per-epoch pool split by `principal × time × agentWeight`, where the weight is derived purely from the agent's signed `threews.*` attestations (work concave in `log2`, faults charged double), so conviction never pays itself. Principal is never slashed and settlement clamps earnings to the escrow surplus. Extends the SPL-Memo attestation layer in [docs/solana-reputation.md](docs/solana-reputation.md). Storage: [reputation_staking_market migration](api/_lib/migrations/20260811140000_reputation_staking_market.sql). Walkthrough: [docs/reputation-staking-market.md](docs/reputation-staking-market.md). Devnet proof: `node scripts/reputation-market-proof.mjs`. Tests: [tests/reputation-staking.test.js](tests/reputation-staking.test.js) |
| On-chain skill licenses | [contracts/skill-license/](contracts/skill-license) `→ /api/skills/license-onchain` | In-repo | Anchor program: each purchased skill = a 1/1 SPL NFT + `SkillLicense` PDA, a trustless alternative to DB-backed access checks. Backend: [api/_lib/skill-license-onchain.js](api/_lib/skill-license-onchain.js) |
| Tokenized 3D (mint an avatar as an NFT) | [api/_lib/tokenize-3d.js](api/_lib/tokenize-3d.js) + [api/_lib/tokenize-3d-metadata.js](api/_lib/tokenize-3d-metadata.js), MCP tools [api/_mcp/tools/tokenize.js](api/_mcp/tools/tokenize.js) (`mint_3d_asset`, `get_3d_asset_onchain`), signed ledger provenance [api/_lib/asset-provenance.js](api/_lib/asset-provenance.js), launch directory [api/v1/tokenized/launches.js](api/v1/tokenized/launches.js) `→ GET /api/v1/tokenized/launches`, public gallery [pages/minted.html](pages/minted.html) + [src/minted.js](src/minted.js) `→ /minted` | In-repo | Mint a generated/owned GLB as a Metaplex Core NFT whose media is a live 3D viewer (GLB under `animation_url`), with baked provenance + enforced capped royalties (10%), idempotent, devnet-default. Every generated avatar AND every mint also appends an ERC-191-signed record to the `agent_actions` ledger (verifiable via `@three-ws/provenance-mcp`'s `query_action`). A mint naming `parent_mint` (a remix) routes the parent creator's royalty out of the mint fee as a real on-chain USDC transfer (mainnet, x402-collected calls only) — [api/_lib/remix-royalty.js](api/_lib/remix-royalty.js) split math, [api/_lib/remix-settlement.js](api/_lib/remix-settlement.js) payout wallet. Premium/token-gated generation: the Forge High tier (200k poly + PBR) is $THREE hold-or-pay gated — [api/forge.js](api/forge.js) `requireFeatureAccess('forge.high')` + [api/_lib/three-tier.js](api/_lib/three-tier.js) tier ladder, x402 pay-per-use or credits fallback; Draft/Standard stay free and ungated. Launch record: [tokenized_3d_assets](api/_lib/migrations/20260707120000_tokenized_3d_assets.sql) + [remix-royalty columns](api/_lib/migrations/20260708130000_tokenized_3d_remix_royalty.sql). Public gallery: `/minted` renders the launch directory live (model-viewer thumbnails, network toggle, royalty + remix badges) — the NFT counterpart of `/launches`. Docs: [docs/mcp.md](docs/mcp.md#mint_3d_asset). E2E: [scripts/tokenize-3d-devnet-e2e.mjs](scripts/tokenize-3d-devnet-e2e.mjs). Tests: [tests/tokenize-3d.test.js](tests/tokenize-3d.test.js), [tests/tokenize-3d-remix-royalty.test.js](tests/tokenize-3d-remix-royalty.test.js), [tests/asset-provenance.test.js](tests/asset-provenance.test.js) |
diff --git a/contracts/program-tests/README.md b/contracts/program-tests/README.md
index 529477e91..a23bc1337 100644
--- a/contracts/program-tests/README.md
+++ b/contracts/program-tests/README.md
@@ -1,6 +1,6 @@
# `program-tests`
-Invariant tests for the two three.ws Solana programs, run against their **real
+Invariant tests for the three three.ws Solana programs, run against their **real
compiled bytecode** in [LiteSVM](https://github.com/LiteSVM/litesvm).
Nothing in here re-implements program logic. The crate builds instructions,
@@ -13,6 +13,7 @@ program is wrong, not that a stub drifted.
|---|---|---|---|
| `skill_license` | [`../skill-license/src/lib.rs`](../skill-license/src/lib.rs) | 21 | `SL-1` .. `SL-8` |
| `agent_invocation` | [`../agent-invocation/src/lib.rs`](../agent-invocation/src/lib.rs) | 11 | `AI-1` .. `AI-4` |
+| `knock_escrow` | [`../knock-escrow/src/lib.rs`](../knock-escrow/src/lib.rs) | 10 | `KE-1` .. `KE-10` |
Invariants are defined in
[`specs/ECONOMY_CONTRACT_INVARIANTS.md`](../../specs/ECONOMY_CONTRACT_INVARIANTS.md).
@@ -28,6 +29,7 @@ with the exact command to run if a `.so` is missing.
```bash
cd contracts/skill-license && cargo-build-sbf
cd contracts/agent-invocation && cargo-build-sbf
+cd contracts/knock-escrow && cargo-build-sbf
cd contracts/program-tests && cargo test
```
diff --git a/data/changelog.json b/data/changelog.json
index 98e890af8..947fbc451 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,15 @@
{
"$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-09-04",
+ "title": "A knock now holds the money until you actually get a reply",
+ "summary": "Paying to reach someone used to send your money the instant the payment cleared, which meant an owner could take every knock and answer none, and you had no way to get it back. A new Solana program makes the payment conditional: it sits in a vault that only the knock itself controls, and exactly three things can happen to it. The owner answers inside the reply window and gets paid, the owner declines and you are refunded in full with no fee taken, or the window closes and anyone at all can trigger your refund. There is no admin key that can move a knock that is parked, the fee is capped at 10% in the program itself, and the fee you agreed to when you knocked cannot be raised on money that is already in escrow. Your message never touches the chain: only a fingerprint of it is stored, so either side can later prove what was sent without publishing it. Ten invariants covering every one of those promises run against the real compiled program on every test run.",
+ "tags": [
+ "feature",
+ "security"
+ ]
+ },
{
"date": "2026-09-03",
"title": "Twenty-one finished packages were built and never shipped; the publisher now finds them by itself",
diff --git a/public/changelog.json b/public/changelog.json
index 23c8fd3e1..61f42d411 100644
--- a/public/changelog.json
+++ b/public/changelog.json
@@ -1,11 +1,22 @@
{
- "generated_at": "2026-09-03T16:35:40.785Z",
+ "generated_at": "2026-09-04T00:54:16.165Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
"url": "https://three.ws"
},
"entries": [
+ {
+ "date": "2026-09-04",
+ "type": "update",
+ "title": "A knock now holds the money until you actually get a reply",
+ "summary": "Paying to reach someone used to send your money the instant the payment cleared, which meant an owner could take every knock and answer none, and you had no way to get it back. A new Solana program makes the payment conditional: it sits in a vault that only the knock itself controls, and exactly three things can happen to it. The owner answers inside the reply window and gets paid, the owner declines and you are refunded in full with no fee taken, or the window closes and anyone at all can trigger your refund. There is no admin key that can move a knock that is parked, the fee is capped at 10% in the program itself, and the fee you agreed to when you knocked cannot be raised on money that is already in escrow. Your message never touches the chain: only a fingerprint of it is stored, so either side can later prove what was sent without publishing it. Ten invariants covering every one of those promises run against the real compiled program on every test run.",
+ "link": null,
+ "tags": [
+ "feature",
+ "security"
+ ]
+ },
{
"date": "2026-09-03",
"type": "launch",
diff --git a/public/changelog.xml b/public/changelog.xml
index 2883f8613..30dcbc076 100644
--- a/public/changelog.xml
+++ b/public/changelog.xml
@@ -6,6 +6,14 @@
<atom:link href="https://three.ws/changelog.xml" rel="self" type="application/rss+xml"/>
<description>What's new on three.ws: features, improvements, and releases, newest first.</description>
<language>en</language>
+ <item>
+ <title>A knock now holds the money until you actually get a reply</title>
+ <link>https://three.ws/changelog</link>
+ <guid isPermaLink="false">2026-09-04:A knock now holds the money until you actually get a reply</guid>
+ <pubDate>Fri, 04 Sep 2026 12:00:00 GMT</pubDate>
+ <category>feature</category>
+ <description>Paying to reach someone used to send your money the instant the payment cleared, which meant an owner could take every knock and answer none, and you had no way to get it back. A new Solana program makes the payment conditional: it sits in a vault that only the knock itself controls, and exactly three things can happen to it. The owner answers inside the reply window and gets paid, the owner declines and you are refunded in full with no fee taken, or the window closes and anyone at all can trigger your refund. There is no admin key that can move a knock that is parked, the fee is capped at 10% in the program itself, and the fee you agreed to when you knocked cannot be raised on money that is already in escrow. Your message never touches the chain: only a fingerprint of it is stored, so either side can later prove what was sent without publishing it. Ten invariants covering every one of those promises run against the real compiled program on every test run.</description>
+ </item>
<item>
<title>Docs · Connect a home that is only on your network</title>
<link>https://three.ws/docs/home-relay</link>
diff --git a/public/features.json b/public/features.json
index f73d5f0ca..13aeab557 100644
--- a/public/features.json
+++ b/public/features.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-09-03T16:35:40.767Z",
+ "generated_at": "2026-09-04T00:54:16.149Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json",
"site": {
"name": "three.ws",
diff --git a/specs/ECONOMY_CONTRACT_INVARIANTS.md b/specs/ECONOMY_CONTRACT_INVARIANTS.md
index 9f65f0774..aa33e1c1f 100644
--- a/specs/ECONOMY_CONTRACT_INVARIANTS.md
+++ b/specs/ECONOMY_CONTRACT_INVARIANTS.md
@@ -209,6 +209,33 @@ events.
| AI-3 | `skill_name` is non-empty and at most 64 bytes; `parameters` is at most 512 bytes. Both bounds are enforced before the event is emitted. |
| AI-4 | The program moves no funds and grants no capability. Its only effect is the emitted event, so a bug here can mislead an indexer but cannot cause a loss. |
+## knock_escrow (`KE-*`)
+
+[`contracts/knock-escrow/src/lib.rs`](../contracts/knock-escrow/src/lib.rs).
+Solana/Anchor program holding a knock's payment in escrow until the door's owner
+answers or refuses it, or the reply window lapses. It is the only Solana program
+in this set that custodies a stranger's money, so its invariants are written from
+the sender's side: what a person who has never met the owner is guaranteed after
+they pay. Each id below is proved by a positive and a negative test in
+[`contracts/program-tests/tests/knock_escrow.rs`](../contracts/program-tests/tests/knock_escrow.rs)
+against the real compiled bytecode. Three further properties the program enforces
+but that are structural rather than behavioral (no admin path can move a parked
+vault, message bodies never touch the chain, and price and window bounds) are
+documented in [`contracts/knock-escrow/README.md`](../contracts/knock-escrow/README.md).
+
+| Id | Invariant |
+|---|---|
+| KE-1 | An answer pays the owner exactly `amount - fee` and the treasury exactly `fee`, then closes the vault. No dust is ever stranded in a settled knock's vault. |
+| KE-2 | Only the door's owner may answer. No other signer, including the `Config` authority, can settle a knock in the owner's favor. |
+| KE-3 | An answer after `expires_at` is rejected, so money the sender is already owed back cannot be taken late. |
+| KE-4 | Once the window has closed, ANYONE may crank the refund, and every unit goes to the sender. The refund does not depend on the sender still being online or on the owner cooperating. |
+| KE-5 | Nobody may crank the refund while the window is open, so a sender cannot retract a knock the owner is still entitled to answer. |
+| KE-6 | A refusal refunds in full and charges no fee. Declining to read something is not a service and is never billed. |
+| KE-7 | A knock leaves `Pending` exactly once. `Answered`, `Refused`, and `Refunded` are terminal, so a settled knock can never be settled again. |
+| KE-8 | `fee_bps` can never exceed `MAX_FEE_BPS` (1000, ten percent), enforced in both `initialize` and `set_config`, so an authority cannot set a fee that takes every future answer. |
+| KE-9 | Shutting a door stops new knocks but does not touch knocks already in flight: those are still owed an answer or a refund. Closing up shop is not an escape from either. |
+| KE-10 | A `KnockRecord` snapshots the fee in force when it was made, so raising the fee cannot reprice money that is already parked. The new fee applies only to knocks created after it lands. |
+
---
## Cross-contract invariants (`X-*`)