diff --git a/README.md b/README.md index 4b2df5c..c82991f 100644 --- a/README.md +++ b/README.md @@ -1,113 +1,218 @@ -# Allowance +
-**Give your agent a budget.** A small, single-operator application for buying useful Solana data with exact x402 USDC payments on Solana, with spending decisions enforced outside the model.
+
+Captured from a local build of the public rehearsal on 30 October 2026. No funds moved.
+ +**Allowance gives an AI agent a fixed, human-approved USDC budget for exact x402 payments on Solana.** A person sets the budget, the per-request cap, the permitted tools or recipients, and the expiry. The agent only proposes: the server checks each request against that frozen policy, reserves the charge in a durable ledger, and only then lets a dedicated payer sign. Every decision, hold and settlement lands in a receipt. + +Built by Matt ([RVAClassic](https://x.com/rvaclassic), [Operator Uplift](https://operatoruplift.com)) for the Solana Foundation **Agentic Payments** sprint, September 2026. + +
+| The limits live outside the model The model can only propose a purchase. Budget, per-call maximum, tools, recipient, network, mint and expiry form an immutable policy that application code enforces before anything is signed. |
+ Reserve, then sign A SQLite BEGIN IMMEDIATE transaction reserves the charge first. A unique purchase identity and a canonical request hash stop repeated signing, and a database failure denies new payments. |
+ Evidence, not claims A facilitator response, chain verification and a delivered result are recorded as separate evidence. A receipt only says SETTLED once the chain shows it. |
+
| Rail | +What the agent can do | +How it is gated | +
|---|---|---|
| x402 tool purchases | +Buy two first-party Solana data tools with exact x402 payments: wallet_snapshot for 0.010000 USDC and transaction_explain for 0.020000 USDC. |
+ The run's policy names the tools, the per-request cap and the budget. The guarded buyer checks the actual payment requirement before the payer signs. | +
| Direct payments | +Pay exact USDC to recipients the operator listed in advance, through the execute_guarded_payment MCP tool: one TransferChecked per request. |
+ A mandate fixes the per-request cap, ceiling, expiry and recipients. Blocked requests become durable BLOCKED receipts with nothing signed. See direct payments. |
+
React 19 · Vite 8 · Express 5 · TypeScript · SQLite (better-sqlite3) · @solana/kit 5 · x402 2.25 exact SVM · OpenAI Responses API · MCP stdio · Argon2id sessions · Vitest · Playwright · Docker
+ +| Control | +What it guarantees | +
|---|---|
| Exact money | +USDC is bounded integer micro-units inside, decimal strings at the API boundary. 0.04 is exactly 40000. |
+
| Frozen policy | +Budget, per-call maximum, tools, destination, recipient, network and mint, expiry and call limit are bound at approval. A shared UTC daily ceiling applies across runs, and outstanding holds still count when the day changes. | +
| Guarded signer | +The signer checks the actual transaction and records a signing claim before it touches the key. An uncertain outcome stays held and freezes the payer instead of retrying. | +
| Stop and expiry | +Both block new signatures. Work already signed can still settle, and a restart restores receipts and reconciliation without restarting the old model authorization. | +
| The public rehearsal at allowanceonsolana.vercel.app: landing page, policy lab, narrated tour and walkthrough, developer guide, brand library and installable PWA. It runs no backend, signer, model or payment endpoint. | +Vercel deployment | +|
| Live x402 purchases and direct USDC payments on devnet or mainnet. Implemented and covered by controlled-adapter suites, closed until an operator supplies a persistent host, credentials and funded accounts. As of the 20 September 2026 inspection, no Allowance settlement had been observed on either network. | +Integration status | +|
| The Seeker Android shell and Solana dApp Store listing. The WebView shell builds; native exports and device behavior still need validation, and the listing waits for a live server. | +Seeker and PWA | +|
| Payment channels and remote MCP, kept as design notes. The local stdio MCP bridge is implemented and shares the same policy, ledger and receipts. | +Payment channels | +
| Prerequisites Node 22.19 or newer in the 22 or 24 line, npm and a writable local disk. Docker for the container check. |
+ Read first Live setup and the threat model, before any payment is switched on. |
+ What the checks prove The verification report says what each check covers and what none of them do. |
+
| Understand it Product description Architecture Threat model Receipt contract |
+ Operate it Live setup Configuration reference Runtime, backup and recovery Local MCP runbook |
+ Check it Verification report Integration evidence and gates Release report, 20 September 2026 Sources, SDK reuse and licenses |
+
| Show it Product tour and walkthrough guide Brand kit: 26 compositions, tokens and fonts |
+ Ship it Vercel rehearsal Seeker, Android and PWA dApp Store listing kit |
+ Submit it Sprint submission draft, written to be finalized with a funded run's receipts |
+
Original code and artwork are MIT licensed (see LICENSE); dependencies keep their own licenses. Allowance is a working product name: check trademark availability before any commercial use.
+ +Built by Matt Sim, founder of Operator Uplift. More builds at github.com/operatoruplift. Want one built for your product? Book a 15-minute call.
diff --git a/docs/readme/banner.png b/docs/readme/banner.png new file mode 100644 index 0000000..e272bf1 Binary files /dev/null and b/docs/readme/banner.png differ diff --git a/docs/readme/flow-dark.png b/docs/readme/flow-dark.png new file mode 100644 index 0000000..5d6a456 Binary files /dev/null and b/docs/readme/flow-dark.png differ diff --git a/docs/readme/flow-light.png b/docs/readme/flow-light.png new file mode 100644 index 0000000..67dee79 Binary files /dev/null and b/docs/readme/flow-light.png differ diff --git a/docs/readme/screens-dark.png b/docs/readme/screens-dark.png new file mode 100644 index 0000000..3bc0ed4 Binary files /dev/null and b/docs/readme/screens-dark.png differ diff --git a/docs/readme/screens-light.png b/docs/readme/screens-light.png new file mode 100644 index 0000000..4562964 Binary files /dev/null and b/docs/readme/screens-light.png differ