Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
docs(wallet): document owner-funded on-chain agent budgets with the program, guard ceiling, API and devnet proof
nirholas2693fe3aebb5
diff --git a/STRUCTURE.md b/STRUCTURE.mdindex 1512296c6..fbf7c574a 100644--- a/STRUCTURE.md+++ b/STRUCTURE.md@@ -265,6 +265,7 @@ packages, a generated standalone GitHub mirror). See| Solana Memo viewer | [public/onchain/index.html](public/onchain/index.html) `→ /onchain` | Live | A shareable, wallet-free reader for public Solana transaction Memos. It accepts a signature or Solscan transaction URL, requests version-1 transactions directly from the mainnet RPC, previews the supported raster data URI formats, provides a file download or text-copy action, and keeps each result tied to its signer, timestamp, and Solscan source. It refuses to execute active formats such as SVG because Memo content is untrusted. Docs: [docs/solana.md](docs/solana.md#viewing-files-written-in-a-transaction-memo). || 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. || Destination whitelist (cooldown allowlist for agent wallet payouts) | Engine [api/_lib/destination-whitelist.js](api/_lib/destination-whitelist.js), endpoint [api/wallet-whitelist/index.js](api/wallet-whitelist/index.js), MCP tools [api/_mcp/tools/whitelist.js](api/_mcp/tools/whitelist.js), cron [api/cron/whitelist-activate.js](api/cron/whitelist-activate.js), hub tab [src/agent-wallet-hub/tabs/whitelist.js](src/agent-wallet-hub/tabs/whitelist.js), migration `api/_lib/migrations/20261010160000_destination_whitelist.sql` | Built; migration not yet applied to production | New payout addresses wait out an owner-set cooldown (24h default, 1h floor), need step-up to add, are proposal-only for agents, cancel in one click and remove instantly. Enforced in the shared spend guards for transfers, tips, bridge, payouts and withdrawals. Docs: [docs/destination-whitelist.md](docs/destination-whitelist.md). Tests: [tests/destination-whitelist.test.js](tests/destination-whitelist.test.js) |+| Owner-funded agent budgets (on-chain allowances) | lib [api/_lib/onchain-allowance.js](api/_lib/onchain-allowance.js), store and guard hook [api/_lib/onchain-allowance-store.js](api/_lib/onchain-allowance-store.js), endpoint [api/agents/solana-allowance.js](api/agents/solana-allowance.js) `-> /api/agents/:id/solana/allowance`, guard wiring [api/agent/guard.js](api/agent/guard.js), hub tab [src/agent-wallet-hub/tabs/allowance.js](src/agent-wallet-hub/tabs/allowance.js), devnet proof [scripts/allowance-devnet-proof.mjs](scripts/allowance-devnet-proof.mjs), migration [api/_lib/migrations/20261023170000_agent_onchain_allowances.sql](api/_lib/migrations/20261023170000_agent_onchain_allowances.sql) | Built; migration not yet applied to production; recurring behind `ALLOWANCE_RECURRING_ENABLED` | The owner keeps funds in their own wallet and signs one transaction creating a capped, expiring fixed delegation to the agent wallet via the Solana Subscriptions and Allowances program. The remaining on-chain allowance is a hard ceiling in the spend guards, and the Budget tab shows cap, spent, remaining and expiry with one-click revoke. Docs: [docs/agent-allowance-budgets.md](docs/agent-allowance-budgets.md). Tests: [tests/onchain-allowance.test.js](tests/onchain-allowance.test.js) || 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) |diff --git a/data/changelog.json b/data/changelog.jsonindex 744032782..123546f4b 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -1,6 +1,13 @@{"$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, desktop (desktop entries become the desktop app's release notes). `link` is optional and must be a live three.ws path.","entries": [+ {+ "date": "2026-10-23",+ "title": "Owner-funded agent budgets enforced on-chain",+ "summary": "Keep funds in your own wallet and sign one transaction that gives an agent a capped, expiring allowance through the Solana Subscriptions and Allowances program. The agent can pull only what is left, the spend guards refuse a pull the program would reject before any transaction is built, and the new Budget tab shows cap, spent, remaining and expiry with one-click revoke.",+ "tags": ["feature"],+ "link": "/docs/agent-allowance-budgets"+ },{"date": "2026-10-23","title": "Prepaid x402 balances settled on-chain in batches",diff --git a/data/pages.json b/data/pages.jsonindex c382e160a..7c3fcfafd 100644--- a/data/pages.json+++ b/data/pages.json@@ -7135,6 +7135,14 @@"changefreq": "monthly","added": "2026-09-05"},+ {+ "path": "/docs/agent-allowance-budgets",+ "title": "Docs · Owner-Funded Agent Budgets",+ "description": "Keep funds in your own wallet and give an agent a capped, expiring allowance enforced by the Solana Subscriptions and Allowances program. How the budget is created, pulled, guarded and revoked, and how to prove it on devnet.",+ "priority": 0.7,+ "changefreq": "monthly",+ "added": "2026-10-23"+ },{"path": "/awesome","title": "Awesome 3D Agents",diff --git a/docs/agent-allowance-budgets.md b/docs/agent-allowance-budgets.mdnew file mode 100644index 000000000..121571e56--- /dev/null+++ b/docs/agent-allowance-budgets.md@@ -0,0 +1,84 @@+# Owner-funded agent budgets++An agent budget enforced by the chain, not by our database. The owner keeps the funds in their own wallet and signs one transaction that creates an allowance (token, cap, expiry) naming the agent's wallet as the only spender. The agent can pull up to what is left of that allowance and not a unit more. The owner can revoke it at any time with one signature.++It sits next to the existing custodial controls (spend limits, destination allowlist, signed spend delegations) and is the right choice when you do not want to pre-fund the agent wallet at all.++## How it works++1. **Create.** In the agent wallet hub, open the **Budget** tab, choose a token mint, a cap and an expiry, and approve the transaction in your browser wallet. The server builds the transaction and returns it unsigned. It never holds your key.+2. **Pull.** When the agent needs funds it calls the pull operation. The platform reads the live allowance from the chain first and refuses a request the program would reject. Otherwise the agent signs a pull with its own custodial key. The funds land in the agent wallet's own token account, so everything the agent does next still passes the existing spend guards.+3. **Watch.** The tab shows cap, spent, remaining and expiry, read from the chain on every load.+4. **Revoke.** One click prepares an unsigned revoke transaction. After you sign it the delegation account is closed and every later pull fails.++## The program and client (primary sources)++| | |+|---|---|+| Program | Solana Subscriptions and Allowances, `De1egAFMkMWZSN5rYXRj9CAdheBamobVNubTsi9avR44` |+| Source | https://github.com/solana-foundation/subscriptions (Solana Foundation, MIT) |+| Client | `@solana/subscriptions` 0.5.0 on npm (generated TypeScript client, MIT) |+| Peer | `@solana/kit`. The package declares `^7`; this repo runs `^8.5.0` and the full lifecycle was verified against it |++We use the generated client's overlay builders. No instruction is hand-encoded.++Instruction set used by the platform:++| Purpose | Instruction |+|---|---|+| First-time setup of the owner's authority | `initSubscriptionAuthority` |+| Fixed cap | `createFixedDelegation`, `transferFixed`, `revokeDelegation` |+| Recurring cap (feature flag) | `createRecurringDelegation`, `transferRecurring`, `revokeDelegation` |++The program also defines plans and subscriptions (`createPlan`, `subscribe`, `transferSubscription`, `cancelSubscription` and others). Subscription plans are out of scope for this feature.++### What the program stores++A fixed delegation stores the **remaining** amount, not the original cap. We record the cap at creation (table `agent_onchain_allowances`) so the UI can show cap, spent and remaining. The chain stays the source of truth for what is left.++A delegation is a standard SPL-token-style approval by the owner to the program, then pulled by the delegatee. The owner's token account must still hold the funds at pull time, so the ceiling also checks the owner's live balance.++## Guard integration++`api/agent/guard.js` treats a call named `allowance_pull` with `{ mint, amountRaw }` as a pull and folds the live on-chain allowance into the verdict as a hard ceiling. The verdict `blockedBy` is `onchain_allowance` and the codes are:++| Code | Meaning |+|---|---|+| `allowance_exceeded` | Request is above the remaining allowance |+| `allowance_expired` | The expiry has passed |+| `no_allowance` | Revoked, closed, or never created |+| `owner_balance_low` | The owner's token account holds less than requested |+| `invalid_amount` | Zero or negative |++An unreadable chain is reported as a blind spot rather than silently allowing. An agent with no allowance for the token is not gated; the feature is owner opt-in like every other cap. The pull endpoint runs the same check, so a refused request never reaches transaction building.++## API++All under `/api/agents/:id/solana/allowance`, owner only, CSRF protected.++| Call | Purpose |+|---|---|+| `GET ?network=` | Allowances with live status, cap, spent, remaining, expiry, token decimals |+| `POST {op:"prepare", owner, mint, amount, expiresInDays, kind?}` | Unsigned create transaction (base64) |+| `POST {op:"confirm", signature, delegationPda, nonce, kind?}` | Verify the account on chain (delegatee is this agent, delegator is a wallet linked to your account) and record it |+| `POST {op:"revoke", id}` | Unsigned revoke transaction |+| `POST {op:"revoked", id, signature}` | Verify the account is closed and record the revoke |+| `POST {op:"pull", id, amountRaw}` | Agent pulls within the cap; simulated, sent, logged as an `allowance_pull` custody event |++## Recurring delegations++`createRecurringDelegation` (an amount per period, resetting each period) is built and read by the same module but ships behind `ALLOWANCE_RECURRING_ENABLED=1`. With the flag off, `prepare` with `kind: "recurring"` is refused with `feature_disabled`.++## Verifying it yourself (devnet only)++```bash+node scripts/allowance-devnet-proof.mjs+```++The script generates throwaway keys and a throwaway mint, then runs create, pull within the cap, an over-cap pull (refused by our guard and by the program), revoke, and a post-revoke pull (refused by both). It prints every signature and exits non-zero if any assertion fails. It refuses to run against any cluster whose genesis is not devnet. It signs nothing on mainnet.++Unit and guard tests: `tests/onchain-allowance.test.js` and the allowance block in `tests/agent-guard-endpoint.test.js`.++## Creating a mainnet allowance++Nothing here signs a mainnet transaction on your behalf. The create transaction is signed in your own wallet from the Budget tab, after your wallet shows you the program, the token, the cap and the expiry.diff --git a/prompts/finish/_context/beat-PROGRESS.md b/prompts/finish/_context/beat-PROGRESS.mdindex 5d07c05af..5ff32f13a 100644--- a/prompts/finish/_context/beat-PROGRESS.md+++ b/prompts/finish/_context/beat-PROGRESS.md@@ -5,3 +5,4 @@ Append one dated entry per finished or partially finished order: order number, c- 2026-10-09: campaign created (27 orders, 601 to 627). Nothing run yet.- 2026-10-23: order 603 (pay CLI: keychain, x402, MPP) done. Source modules landed in 2b7bb3921 (swept by another agent's commit); tests, commands, README, docs and changelog in the commit titled feat(cli): three-ws pay. Remaining, owner-gated: the first real mainnet settlement (gate 1), command in the final report.- 2026-10-23: order 612 (prepaid balances settled on-chain in batches) done. Ledger, batcher, route hook (`paidEndpoint({ mode: 'prepaid' })`), endpoints, crons and migration landed in a37074e67 (swept by another agent's commit); the interval fix, constants split, reconcile script, triage entry and docs landed in ed75c5946 (also swept by another agent); this commit closes the order and logs it. Remaining, owner-gated: apply migration 20261023160000 (`npm run db:status` first), fund the settler and set `X402_PREPAID_SETTLE_LIVE=1` for the first mainnet batch settlement (gate 1), details in the final report.+- 2026-10-23: order 605 (owner-funded on-chain allowance budgets) done except the real devnet run: faucet 429 (owner or faucet is the dependency); the same lifecycle script passed on a local validator running the real program. Code landed in ed75c5946 (swept by another agent's commit); docs, pages, changelog and STRUCTURE row in the commit titled docs(wallet): document owner-funded on-chain agent budgets. Run `node scripts/allowance-devnet-proof.mjs` when devnet SOL is available.