diff --git a/README.md b/README.md index 4b2df5c..c82991f 100644 --- a/README.md +++ b/README.md @@ -1,113 +1,218 @@ -# Allowance +
-> **In 20 seconds.** Allowance gives an AI agent a fixed, human-approved USDC budget for exact x402 payments on Solana, with the spending policy enforced outside the model and every decision and receipt recorded. Try the public rehearsal: [allowanceonsolana.vercel.app/lab](https://allowanceonsolana.vercel.app/lab). Built by Matt ([RVAClassic](https://x.com/operatoruplift), Operator Uplift) for the Solana Foundation **Agentic Payments** sprint, September 2026. Working today: the policy lab, durable receipts, the MCP bridge, policy-gated direct USDC payments to allowlisted recipients (mandates, devnet-first), an installable PWA and the Seeker Android shell. Live devnet and mainnet settlement is implemented and ships behind an explicit operator gate: run the persistent backend, configure the payment accounts, then authorize the funded smoke command. Everything below is verification detail, with each claim scoped to the dated evidence in this repository. +Allowance. AI agents, x402, Solana. Give your agent a budget. Human-approved USDC spending for AI agents: the limits live outside the model, and every call leaves a receipt. Exact x402 payments, Solana USDC, local MCP bridge, durable receipts. allowanceonsolana.vercel.app -**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. +

-**Short description:** Allowance gives AI agents human-approved USDC budgets to buy useful tools and pay approved recipients on Solana, with spending controls outside the model and a durable record of each decision. +Open the policy lab   +Watch the product tour   +Read the developer guide + +

+ +CI status +Public rehearsal status +Payments: x402 exact SVM +Settles in Solana USDC +Agents connect over local MCP stdio +Node 22.19 or newer +License: MIT + +

Let it buy the tools it needs. See where every cent went.

-**Full description:** Allowance is a single-operator application for bounded agent payments on Solana. A human approves the budget, per-request cap, permitted tools or recipients, and expiry. Agents can buy the first-party `wallet_snapshot` and `transaction_explain` tools through exact x402 payments, or make direct USDC payments under an allowlisted-recipient mandate. Application code checks every request before the server-managed payer signs; both rails share a daily ceiling and durable receipts that distinguish holds, settlement evidence and service delivery. A local stdio MCP bridge gives authorized external agents access to the same controls. The public policy lab lets visitors adjust limits and save a plan without moving funds, and an installable PWA provides access to the public pages. An unset network means mainnet with every payment gate closed (the template ships devnet values), but actual payments still require a persistent backend host, operator credentials, funded accounts and the relevant payment-provider setup; no Allowance mainnet or devnet settlement has been verified in this delivery. The included Android shell still needs native download and device validation. See the [complete product description](docs/product-description.md). - -The public rehearsal works immediately without accounts, signing, paid HTTP requests, or model calls. Live execution switches on with explicit operator setup. **Every settlement statement here is scoped to the evidence behind it: the rehearsal, the controlled-adapter payment suites, and dated public read-only chain checks.** See the [integration matrix](docs/integration-status.md) and [current release evidence](docs/release-2026-09-20.md) for what each check covers and the setup each live capability needs. - -The public rehearsal is live at [allowanceonsolana.vercel.app](https://allowanceonsolana.vercel.app). The [Vercel deployment guide](docs/vercel.md) documents its separate static build. Operator access and live payments run on the persistent backend described below. - -[Source on GitHub](https://github.com/operatoruplift/allowance) · [Product tour](https://allowanceonsolana.vercel.app/demo#product-tour) · [Brand kit](https://allowanceonsolana.vercel.app/brand) · [Download all brand assets](https://allowanceonsolana.vercel.app/brand/allowance-brand-kit.zip) - -## Run - -Node 22.19 or newer in the supported Node 22/24 lines, npm, and a writable local disk are required. - -```sh +Approve  →  Propose  →  Check  →  Reserve  →  Sign  →  Receipt + +
+ +How it works  ·  +Trust model  ·  +Status  ·  +Run it locally  ·  +Docs + +
+ +
+ + + + Four screens of the public rehearsal. 01, plan the allowance: set a total, a per-request cap and a daily limit in the policy lab. 02, keep the budget in code: the agent proposes a tool and the server checks the policy and reserves the charge before the payer signs. 03, watch a run unfold in the narrated walkthrough, with no funds moved. 04, keep the receipt: settled, held and remaining amounts stay visible, and a blocked request never consumes the allowance. + + +

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. + +
+ +## How it works + + + + Agent, Allowance and Solana. The agent proposes: a bounded OpenAI Responses run or any MCP client over local stdio, with narrow tool schemas, and it never sees the payer key. Allowance decides: it checks each request against the operator's frozen policy, reserves in a SQLite ledger before signing, and holds one dedicated backend signer. Solana settles: exact x402 USDC payments through a facilitator, allowlisted direct transfers under a mandate, and settlement checked against chain evidence. Every decision becomes a durable receipt. + + + + + + + + +
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.
+ +Two payment rails share one policy engine, one daily ceiling and one receipt format: + + + + + + + + + + + + + + + + + +
RailWhat the agent can doHow it is gated
x402 tool purchasesBuy 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 paymentsPay 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

+ +
+ +## The trust model + +Allowance is a **server-managed signer with application-enforced controls**, and the scope is deliberate: controls live in application code, not in a custom onchain budget program, a smart wallet or a payment channel. + + + + + + + + + + + + + + + + + + + + + + +
ControlWhat it guarantees
Exact moneyUSDC is bounded integer micro-units inside, decimal strings at the API boundary. 0.04 is exactly 40000.
Frozen policyBudget, 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 signerThe 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 expiryBoth block new signatures. Work already signed can still settle, and a restart restores receipts and reconciliation without restarting the old model authorization.
+ +What it does not claim: a compromised server could defeat application-level controls. That is why the signer stays backend-only and the documented setup uses a dedicated low-balance payer, and why both shipped merchants are labeled as first-party sample services rather than third-party adoption. The full analysis is in the [threat model](docs/threat-model.md). + +
+ +## Status + + + + + + + + + + + + + + + + + + + + + + +
LiveThe 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
GatedLive 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
ValidatingThe 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
PlannedPayment 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
+ +
+ +## Run it locally + + + + + + + +
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.
+ +### 1. Run the app + +```bash npm ci -npm run dev +npm run dev # http://127.0.0.1:4318, Express hosts Vite in one process ``` -Open [127.0.0.1:4318](http://127.0.0.1:4318). Development is **one command: `npm run dev`**. Express hosts Vite in development; there is no second backend to start. +For a local production build, `npm run build` then `npm start`: Express serves `dist/client` and runs the bounded background worker. -For a local production build: +### 2. Before a pull request, run what [CI](.github/workflows/ci.yml) runs -```sh -npm run build -npm start +```bash +npm run check # lint, types, unit and integration tests, production build +npx playwright install chromium +npm run test:browser +npm run build:rehearsal && npm run test:hosted ``` -Production startup is **`npm start`**; Express serves `dist/client` and runs the bounded background worker. The local HTTP origin is allowed only at the exact configured loopback origin. Hosted origins must use HTTPS, with Secure cookies. Set `APP_ORIGIN` to the real origin and configure only the actual trusted proxy hop count. - -| Route | Use | -| ------------- | ------------------------------------------------------------------------------------- | -| `/` | Landing and interactive receipt preview | -| `/demo` | Narrated product tour, captions and downloads; separate interactive outcome fixtures | -| `/lab` | Policy lab: set an allowance, a per-request cap and a daily limit, then save the plan | -| `/login` | Single-operator password login | -| `/app` | Overview, Runs, Payments and Setup workspace; authenticated task and payment controls | -| `/runs/:id` | Private durable run, report, JSON export, print view and stop | -| `/developers` | Tool descriptions and server-side client example | -| `/brand` | Downloadable profiles, wallpapers, headers, social artwork and logos | +Tests use deterministic adapters and isolated SQLite databases. They never spend or call paid APIs. -The workspace uses a desktop sidebar and phone navigation. Direct section links are `/app?view=overview`, `/app?view=runs`, `/app?view=payments`, and `/app?view=setup`. The static public deployment shows setup requirements; private activity and live controls require the persistent operator backend. The [53-second product tour](https://allowanceonsolana.vercel.app/demo#product-tour) records the public planning tools without moving funds. +### 3. Open the operator workspace -## Operator and live setup - -```sh +```bash cp .env.example .env -npm run setup:operator -``` - -The terminal command hides password input and writes an Argon2id hash and random session secret into ignored `.env` with mode 0600. Restart the service after setup. It rotates the session secret, invalidating old sessions. No public registration exists. Every live API stays closed until that hash and session secret are in place, so a deployment without operator credentials cannot spend. - -See [live setup](docs/live-setup.md) for dedicated payer and recipient setup, network-specific SOL and native Circle USDC, required associated token accounts, pinned facilitator fee sponsor, and a repeatable data wallet. Mainnet is the default network, and real spending is opt-in: it turns on with `LIVE_PAYMENTS_ENABLED=true` plus `MAINNET_PAYMENTS_ACKNOWLEDGED=true`. Devnet remains an explicit testing option; existing receipts retain their original network. Configure `OPENAI_API_KEY` and an explicit `OPENAI_MODEL`. The example `gpt-5-mini` is listed in [official documentation](https://developers.openai.com/api/docs/models/gpt-5-mini); set a model your own account can call. The app requires that explicit ID and never guesses a fallback. - -```sh -npm run preflight +npm run setup:operator # Argon2id hash and session secret into .env, mode 0600 +npm run build && npm run preflight # configuration and network checks, no signing, no model calls ``` -This checks configuration and networks without signing or model calls. It exits nonzero when readiness is incomplete. From the operator console, use **Check readiness** before starting a live agent run. The model has at most five calls by default, 1,200 generated tokens per call, 48,000 characters of accumulated input, four tool proposals, and three minutes per run. Each provider call is sent exactly once, with automatic client retries set to zero, so a bounded run cannot quietly multiply model calls. OpenAI billing is **outside** the USDC merchant allowance. +There is no public registration. Every live API stays closed until the password hash and session secret are in place, so a deployment without operator credentials cannot spend. -For a separately authorized external agent, set `MCP_ENABLED=true`, create an authenticated external run, and launch the local stdio bridge with `MCP_GRANT_TOKEN` as described in [the MCP runbook](docs/mcp.md). The bridge is opt-in local stdio only, with no public HTTP endpoint, and it holds no payer key: its paid tools run on the backend through a token-authenticated loopback endpoint (`MCP_BACKEND_TOKEN`). +### 4. Live payments, only on purpose -The standalone opt-in integration check starts its own local merchant listener; stop `npm run dev` first. This command performs scripted real payments, independent of an autonomous model trace: +| Setting | Effect | +|---|---| +| `LIVE_PAYMENTS_ENABLED=true` | Turns on real spending. Off by default. | +| `MAINNET_PAYMENTS_ACKNOWLEDGED=true` | Required as well for mainnet, the default network. | +| `PAYMENT_NETWORK=devnet` | Selects devnet for testing. Existing receipts keep their original network. | +| `DIRECT_PAYMENTS_ENABLED=true` | Opens the mandate rail for allowlisted recipients. | +| `MCP_ENABLED=true` and `MCP_GRANT_TOKEN` | Lets an authorized local agent use the stdio bridge (`npm run mcp`). | +| `OPENAI_API_KEY` and `OPENAI_MODEL` | Powers the built-in runner. The model ID is required and never guessed. | -```sh -# Only after configuring and explicitly authorizing this real-USDC spend: +```bash +# Only after configuring and explicitly authorizing a real-USDC spend: npm run smoke:mainnet -- --confirm-mainnet-spend -# Separate testing alternative: set PAYMENT_NETWORK=devnet first. +# Testing alternatives, with PAYMENT_NETWORK=devnet: npm run smoke:devnet -- --confirm-devnet-spend +npm run smoke:direct-devnet -- --confirm-devnet-spend ``` -Each command rejects the wrong payment network and requires its explicit confirmation flag. Mainnet also requires `MAINNET_PAYMENTS_ACKNOWLEDGED=true`. Both require `LIVE_PAYMENTS_ENABLED=true`, all payment configuration, and `DEMO_WALLET` with at least two available transactions. The scripted two-purchase scenario spends up to 0.030000 USDC; its separate 0.020000 probe must be denied before signing. It buys the wallet snapshot and latest transaction facts, then performs a separately labeled policy probe. It writes its own dated evidence file into `evidence/` the first time an operator authorizes it; the artifacts already in `evidence/` come from the controlled suites, public read-only chain checks and rehearsal captures. Without the flag it exits before creating a signer or a runtime. Do not retry uncertain payments with new IDs. - -## Guarded direct payments - -Besides buying catalog tools, an agent can pay exact USDC to recipients the operator listed in advance. The operator authorizes a **mandate** (per-request cap, ceiling, expiry, recipients) and receives a one-time grant token; the MCP tool `execute_guarded_payment` checks every request against that frozen policy, the shared daily ceiling and the payer hold, and only then signs and submits a single `TransferChecked` with the dedicated payer, proving settlement from chain evidence before the receipt says `SETTLED`. Blocked requests are durable `BLOCKED` receipts; nothing is signed for them. Recipients can be added later only with an administrator's signature and a single-use nonce. The rail is off until `DIRECT_PAYMENTS_ENABLED=true`, uses the explicitly configured payment network (`devnet` or `mainnet-beta`, exactly; the template ships devnet), and is covered by policy, ledger, transfer, MCP and API tests. Its funded devnet check requires `PAYMENT_NETWORK=devnet`: `npm run smoke:direct-devnet -- --confirm-devnet-spend`. See [docs/direct-payments.md](docs/direct-payments.md). - -## Controls and recovery +The scripted scenario spends at most 0.030000 USDC, and its separate 0.020000 probe must be denied before signing. Without the confirmation flag a smoke command exits before it creates a signer. Do not retry an uncertain payment under a new ID. Setup for payer and recipient accounts, the facilitator and the fee sponsor is in [live setup](docs/live-setup.md); every variable is in the [configuration reference](docs/configuration.md). -- USDC is represented as bounded integer micro-units and decimal strings at the API boundary. `0.04` is exactly `40000`. -- An immutable policy binds budget, per-call maximum, tools, exact destination, recipient, selected network/mint, expiry and call limit. The shared UTC daily ceiling applies across runs. Outstanding holds count even when the day changes. -- SQLite `BEGIN IMMEDIATE` transactions reserve before signing. Unique purchase identity and canonical request hashes prevent repeated signing. Database failure denies new payments. -- The guarded signer checks the actual transaction and durably records a signing claim before invoking the key. Uncertain outcomes remain held and freeze the payer. A rejected or crashed signer after this boundary is conservatively uncertain. -- A successful facilitator response, chain verification and returned service result are separate evidence. Replayed purchased responses reuse the same signed identity and never require a new signature. -- Stop or expiry prevents new signatures. Already signed work can settle afterward. Restart restores receipts and reconciliation; it does **not** restart the old model authorization. A new run remains subject to the shared daily ceiling. +
+Docker and persistent disk +
-This is a **server-managed signer with application-enforced controls**, and the trust model is stated plainly: a compromised server could defeat application-level controls, which is why the signer stays backend-only and the documented setup uses a dedicated low-balance payer. The scope is deliberate. Controls live in application code rather than in a custom onchain budget program, a smart-wallet claim or a payment channel, and both shipped merchants are first-party sample services rather than third-party adoption. +Run exactly one application instance on one persistent volume, which holds SQLite, its WAL, sessions, purchase identities and the merchant response cache. Never put the live backend on an ephemeral serverless filesystem. -## Tests - -```sh -npm run check -npx playwright install chromium -npm run test:browser -``` - -`check` runs lint, TypeScript, controlled unit/integration tests, and the production build. Tests use deterministic adapters and isolated SQLite databases. They do not spend or call paid APIs. The HTTP payment test traverses the actual middleware with controlled facilitator/signing adapters. The opt-in smoke commands above are **separate funded checks**, not part of the automated suite. Browser screenshots and dated read-only findings are in `evidence/`. - -## Docker and persistent disk - -Use exactly one application instance and one persistent volume for SQLite, its WAL, sessions, purchase identities and merchant response cache. Never put the live backend on an ephemeral serverless filesystem. - -```sh +```bash docker build -t allowance . docker volume create allowance-data docker run --name allowance --restart unless-stopped \ @@ -122,33 +227,68 @@ docker run --name allowance --restart unless-stopped \ allowance ``` -Place one HTTPS reverse proxy in front of the bound local port. `.env.docker` is ignored by git. Docker env files take literal values: omit the surrounding single quotes from the Argon2 hash generated in `.env` when copying it to `.env.docker`. Do not copy key files into the image. The image runs as the unprivileged `node` user; ensure that user can read the mounted dedicated key. For rehearsal-only hosting, omit the secret mount and keep `LIVE_PAYMENTS_ENABLED=false`; the container then serves the full rehearsal with no signer present. - -Use the [supported backup and restore commands](docs/runtime-recovery.md) rather than copying an active SQLite file. Restores preserve original receipts, holds and replay identities, and each restored journal begins locked against new spending, so offline recovery passes through an explicit operator review. Keep secrets and backups private. Do not run multiple replicas or share one payer across different journals. The schema migration version is recorded in `schema_migrations`; payment cache tables are created by the payment module. - -## Project map and delivery - -The red brand edition includes 26 compositions in full-size PNG and outlined SVG, a phone-friendly `/brand` library, and a complete ZIP. Use the library's **Open full-size image** action to save individual PNGs to a phone; browser downloads may go to Files. See [the brand guide](docs/brand.md) for colors, typography, dimensions and the local `npm run brand:generate` command. - -`src` contains the original React UI; `shared` contains validated contracts and money handling. `server/auth`, `agent`, `policy`, `payments`, `merchant`, `data`, and `db` form one Express service. [Architecture](docs/architecture.md) explains trust boundaries; [the reusable example](examples/paid-tool.ts) demonstrates calling the guarded buyer outside the sample agent. - -- [Product tour and interactive walkthrough guide](docs/demo-script.md) -- [Product descriptions](docs/product-description.md) -- [Submission draft](docs/submission.md), written to be finalized with a funded run's receipts and the event's published rules -- [Verification report](docs/verification.md) -- [Integration evidence and setup gates](docs/integration-status.md) -- [Complete configuration reference](docs/configuration.md) -- [Durable runtime, backup and recovery](docs/runtime-recovery.md) -- [Focused threat model](docs/threat-model.md) -- [Local external-agent MCP runbook](docs/mcp.md) -- [Payment channel transport design](docs/payment-channels.md), a documented future adapter -- [Brand assets and tokens](docs/brand.md) -- [Privacy policy](https://allowanceonsolana.vercel.app/privacy) and [terms of use](https://allowanceonsolana.vercel.app/terms), linked from every page's footer (source: `src/PrivacyPolicy.tsx`, `src/TermsOfUse.tsx`) -- [Solana dApp Store listing kit](docs/dapp-store/listing.md): listing text, banner, screenshots and the listing decision -- [Sources, SDK reuse and licenses](docs/sources.md) - -Payment channels and remote MCP are planned adapters, kept as design notes. The local stdio MCP bridge is implemented and uses the same application service, policy, ledger and receipts. Allowance is the working product name; assess trademark availability before any commercial use. Original application code and artwork use the MIT license. Third-party dependencies retain their own licenses. - -## Seeker, Android and PWA - -Allowance installs as a PWA and ships an Android WebView shell (`android/`) for the Solana Seeker and dApp Store, with native wallet-intent plumbing for future wallet flows. The current product uses a server-managed payer; native exports and device behavior still need validation. The shell packages English resources only. Build, signing, test and publishing steps: [docs/seeker-and-pwa.md](docs/seeker-and-pwa.md). The store listing kit and the recommendation to hold the listing until a live server exists are in [docs/dapp-store/listing.md](docs/dapp-store/listing.md). +- Put one HTTPS reverse proxy in front of the bound local port. `.env.docker` is ignored by git, and Docker env files take literal values, so drop the single quotes around the Argon2 hash when copying it from `.env`. +- Never copy key files into the image. The image runs as the unprivileged `node` user, which must be able to read the mounted key. +- For rehearsal-only hosting, omit the secret mount and keep `LIVE_PAYMENTS_ENABLED=false`: the container then serves the full rehearsal with no signer present. +- Back up and restore with the [supported commands](docs/runtime-recovery.md), never by copying an active SQLite file. A restored journal starts locked against new spending until an operator reviews it. Never run replicas or share one payer across journals. + +
+ +
+Routes +
+ +| Route | Use | +|---|---| +| `/` | Landing page and interactive receipt preview | +| `/demo` | Narrated product tour with captions and downloads, plus interactive outcome fixtures | +| `/lab` | Policy lab: set an allowance, a per-request cap and a daily limit, then save the plan | +| `/developers` | Tool descriptions and a server-side client example | +| `/brand` | Downloadable profiles, wallpapers, headers, social artwork and logos | +| `/login` | Single-operator password login | +| `/app` | Overview, Runs, Payments and Setup, with authenticated task and payment controls | +| `/runs/:id` | A private durable run: report, JSON export, print view and stop | + +The workspace uses a desktop sidebar and phone navigation, with direct links such as `/app?view=payments`. The static deployment shows setup requirements; private activity and live controls need the persistent operator backend. + +
+ +
+Repository layout +
+ +| Path | Contents | +|---|---| +| `src/` | The React UI: landing page, policy lab, walkthrough, workspace, brand library | +| `shared/` | Validated contracts, mandates and exact money handling shared by client and server | +| `server/` | One Express service: `auth`, `agent`, `policy`, `payments`, `direct`, `merchant`, `data`, `db` and the MCP bridge | +| `examples/` | [`paid-tool.ts`](examples/paid-tool.ts): calling the guarded buyer outside the sample agent | +| `tests/` | Vitest suites with controlled adapters, plus Playwright browser and hosted journeys | +| `android/` | The Seeker WebView shell with native wallet-intent plumbing | +| `docs/` | Architecture, setup, runbooks, threat model and dated release reports | +| `evidence/` | Dated screenshots, deployment checks and read-only chain observations | + +
+ +
+ +## Documentation + + + + + + + + + + + + +
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