walletcap 0.2.0__tar.gz → 0.2.2__tar.gz

{walletcap-0.2.0 → walletcap-0.2.2}/.circleci/config.yml

@@ -22,6 +22,11 @@ jobs:
             python3 -m venv /tmp/venv
             /tmp/venv/bin/pip install --quiet pytest
             /tmp/venv/bin/python -m pytest -q
+      - run:
+          name: Examples
+          command: |
+            node examples/quickstart/quickstart.mjs
+            python3 examples/quickstart/quickstart.py
       - run:
           name: Solidity
           command: |

{walletcap-0.2.0 → walletcap-0.2.2}/.gitignore

@@ -10,6 +10,7 @@ __pycache__/
 out/
 cache/
 work/
+examples/quickstart/demo.sqlite
 
 # The fake awal stand-in in the tests is committed on purpose: the CLI test
 # needs its dist/ layout, and the dist/ rule above would hide it.

walletcap-0.2.2/CHANGELOG.md

@@ -0,0 +1,28 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+# Changelog
+
+## 0.2.2 — 2026-11-05
+
+### Changed
+
+- A mixed-case EVM address is checked against EIP-55 before it is accepted. A bad
+  checksum is refused; all-lowercase and all-uppercase hex are still accepted.
+- A Solana CAIP-10 address is reduced to its address, so it and the bare address
+  share one budget.
+- Numeric `window` values are milliseconds in Python too, matching JavaScript.
+
+### Fixed
+
+- The rolling window cannot be shortened once the budget has spend. An edit can
+  change the cap and the per-payment limit, but it cannot reset the count by
+  shrinking the window.
+
+### Added
+
+- `SECURITY.md`, `docs/threat-model.md`, `docs/vendor-disclosure.md`, and the
+  Solidity audit status in `solidity/README.md`.
+- `examples/quickstart/` in JavaScript and Python, run in CI. No wallet, chain,
+  keys or network.
+- EIP-55, Solana CAIP-10, and window-freeze tests in both languages.
+
+## 0.2.1 — 2026-11-05

{walletcap-0.2.0 → walletcap-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: walletcap
-Version: 0.2.0
+Version: 0.2.2
 Summary: One spend budget per wallet for AI agents: counted across every process, replica, key, permission and payment rail.
 Project-URL: Homepage, https://github.com/coriolislabs/WalletCap
 Project-URL: Repository, https://github.com/coriolislabs/WalletCap
@@ -33,6 +33,13 @@ period. So a restart, a second replica, one more key, or the next period hands t
 fresh budget. walletcap counts **per wallet**: one budget that every process,
 replica, key, permission and payment rail spends from.
 
+The owner creates the budget once. Opening it never creates one; pass `create: true` only
+for a demo or first-run setup:
+
+```console
+$ npx walletcap set --wallet 0xYourAgentWallet --per-payment 50 --per-day 150
+```
+
 ```js
 import { openBudget } from 'walletcap';
 
@@ -53,6 +60,21 @@ with budget.pay("$12.50"):
 `npm install walletcap` (Node 22.13+) · `pip install walletcap` (Python 3.11+) ·
 no dependencies · Apache-2.0
 
+## Try it without a wallet
+
+Two runnable demos use a fake payee and a temporary file: no wallet, chain, keys or
+network.
+
+```console
+$ node examples/quickstart/quickstart.mjs
+$ python3 examples/quickstart/quickstart.py
+```
+
+They show three `$0.05` payments against a `$0.15` rolling cap, a `$1.00` refusal, a
+fourth `$0.05` refusal, and a restart that cannot raise the limits. The demo uses
+`create: true`; a production agent opens with the default `create: false` after the
+owner runs `walletcap set`.
+
 ## Why a per-wallet count
 
 Most agent spend controls keep "spent so far" next to something temporary or repeatable: a
@@ -76,8 +98,9 @@ own code. Findings go to the vendors first; this package is the fix, not the fin
    leaves $50, not $200. A restart can lower a limit but never raise one: if the code comes
    back asking for looser limits (a kit's defaults, say), the stored limits stay and you get a
    warning with the command that raises them on purpose.
-4. **Fail closed.** If the count can't be read, nothing pays. A payment whose outcome is
-   unknown keeps counting, because a payment that failed halfway may still have moved money.
+4. **Fail closed.** If the count can't be read, nothing pays; a missing file is not a new
+   budget. A payment whose outcome is unknown keeps counting, because a payment that failed
+   halfway may still have moved money.
 
 The count lives in a SQLite file that every process on the machine shares, and each payment is
 reserved inside one write transaction, so replicas racing for the last dollar can't both win.
@@ -113,7 +136,7 @@ gives you a reservation to `commit()` or `release()` yourself.
 ### x402
 
 `guard()` puts the budget in front of any x402 v2 client from `@x402/core`, so it works under
-`@x402/fetch` and alongside Coinbase's CDP spend controls.
+`@x402/fetch`. Use it as the one counter when the client has no CDP spend store.
 
 ```js
 import { x402Client } from '@x402/core/client';
@@ -138,20 +161,24 @@ const fetchPaid = wrapFetchWithPayment(fetch, client);
 
 ### Coinbase CDP spend controls
 
-`applySpendControls` builds on an x402 client, so `budget.guard(client)` works alongside it, and
-it's the one to use:
+There are two ways to count a CDP payment in the budget; use **one** per client.
+
+- `budget.guard(client)` — the budget prices every asset, refuses anything it cannot price,
+  and reserves in one write transaction. Use it when the budget is the counter.
+- `applySpendControls(client, { ..., store: budget.cdpStore({ asset: USDC }) })` — keep
+  CDP's controls, and make its count durable and shared. The store re-checks the budget inside
+  the write transaction, so replicas sharing the file cannot both take the last dollar.
+
+`budget.cdpStore()` is walletcap's SQLite ledger behind CDP's `SpendStore` interface — **not**
+CDP's in-memory default. Replacing that default is the fix, not a second control.
 
-- **It counts every token.** `guard()` prices the USD stablecoins it knows and refuses
-  anything else, whatever assets the client would otherwise accept.
-- **It reserves in one transaction.** Each payment is checked and reserved inside one write
-  transaction on the budget file, so processes and replicas sharing the file can't both take
-  the last dollar.
-- **It keeps counting what the payee calls failed** until the authorization expires, then frees
-  it on its own.
+Do **not** call both on one client: the CDP store and the guard each record the payment, so
+the budget would count it twice. `budget.guard()` refuses a client that already has CDP
+controls, and a client guarded first refuses CDP controls before signing.
 
-To keep CDP's own count durable and shared as well, swap its in-memory store for walletcap's,
-set `maxCumulativeSpend` (CDP only records through its store when a cumulative cap is set), and
-set `allowedAssets`: CDP never consults its store for a token outside the cap.
+To use the store, swap CDP's in-memory store for walletcap's, set `maxCumulativeSpend` (CDP
+only records through its store when a cumulative cap is set), and set `allowedAssets`: CDP
+never consults its store for a token outside the cap.
 
 ```js
 applySpendControls(client, {
@@ -161,13 +188,15 @@ applySpendControls(client, {
   allowedAssets: [USDC],
   store: budget.cdpStore({ asset: USDC }),
 });
-budget.guard(client);
 ```
 
+`guard()` is the other choice, and the one that prices every token: it refuses a USD stablecoin
+it cannot value instead of letting CDP count only the asset named in the cap.
+
 walletcap's store re-checks the budget when CDP records a payment, so it holds across replicas
 on its own. When CDP removes a payment from its store, the store can't tell why, so the payment
 stays counted as in-flight until you check the chain and run `npx walletcap release <id>`. Use
-CDP 1.56.0 or later.
+CDP 1.56.0 or later; the store is tested against the published 1.60.0.
 
 ### Coinbase Agentic Wallet (awal CLI and MCP server)
 
@@ -256,9 +285,9 @@ The default file is per user: `~/.local/state/walletcap/budget.sqlite` on Linux,
 compute the same default.
 
 The budget is as durable as that file. In a container, put it on a volume that outlives the
-container, or a redeploy starts a new file. For agents that can touch the filesystem, open the
-budget with `create: false` and create it once, as the owner, with `npx walletcap set`:
-then a missing file refuses every payment instead of starting a new budget.
+container, or a redeploy starts a new file. Opening a budget does not create one: a missing file
+refuses every payment. The owner creates it once with `npx walletcap set`; pass `create: true`
+only for a demo or a first-run setup.
 
 ## What it doesn't do
 
@@ -266,8 +295,9 @@ then a missing file refuses every payment instead of starting a new budget.
   go around it: call the wallet directly, or delete the file. To bound an agent like that, keep
   the budget out of its reach (another OS user, another service) or enforce on chain, as
   `AccountCapSpender` does for Spend Permissions.
-- **One file is one host, or a shared volume.** A Postgres backend for replicas on separate
-  hosts is next.
+- **One file is one host.** A shared volume can work for one host's containers, but SQLite
+  over NFS is not a multi-host database. A Postgres backend for replicas on separate hosts is
+  next.
 - **It can't see a revoke that lands later in the same block,** and for x402 schemes that settle
   later (batch vouchers), a payment counts from when the server confirms it.
 - **Some x402 payments can't be confirmed.** `@x402/fetch` doesn't report v1 settlements
@@ -286,8 +316,8 @@ then a missing file refuses every payment instead of starting a new budget.
 | `tests/` | the Python suite, including the tests that drive both languages against one budget file |
 
 ```console
-$ cd js && npm install && node --test            # 50 tests
-$ uv run --with pytest pytest -q                 # 53 tests, from the repository root
+$ cd js && npm install && node --test            # 61 tests
+$ uv run --with pytest pytest -q                 # 59 tests, from the repository root
 $ cd solidity/evm && npm install && node check.mjs ..   # the contract on an EVM, no Foundry needed
 $ cd solidity && forge test                      # the contract's canonical tests, if you have Foundry
 ```
@@ -298,9 +328,19 @@ MCP proxy against stand-ins for Coinbase's wallet and MCP server. The Python sui
 the CLI and one budget shared between both languages. `solidity/evm/check.mjs` compiles the
 contract with solc-js and drives it on an in-process EVM, covering what the Foundry tests cover.
 
-One test is **not** here: the integration test that drives Coinbase's CDP spend controls through
-the shared store. It runs against a vendored build of Coinbase's SDK and lives in ShadowPath's
-own repository. Porting it to the published `@coinbase/cdp-sdk` is open work.
+The JavaScript suite also drives the published `@coinbase/cdp-sdk@1.60.0` through the
+shared store, so the CDP integration is covered against the package users install.
+
+## Security and audit
+
+- [Security policy](SECURITY.md): how to report a vulnerability, supported versions,
+  and the 90-day coordinated-disclosure window for walletcap itself.
+- [Threat model](docs/threat-model.md): what the guard stops, what it does not, and the
+  deployment patterns that hold.
+- [Vendor benchmark disclosure](docs/vendor-disclosure.md): the separate 7-day
+  pre-publication notice for vendor findings in the Agent Payment Benchmark.
+- `AccountCapSpender` is **unaudited**. Read [solidity/README.md](solidity/README.md)
+  before deploying it; testnet only until an independent audit.
 
 ## Prove it holds in your deployment
 

{walletcap-0.2.0 → walletcap-0.2.2}/README.md

@@ -10,6 +10,13 @@ period. So a restart, a second replica, one more key, or the next period hands t
 fresh budget. walletcap counts **per wallet**: one budget that every process,
 replica, key, permission and payment rail spends from.
 
+The owner creates the budget once. Opening it never creates one; pass `create: true` only
+for a demo or first-run setup:
+
+```console
+$ npx walletcap set --wallet 0xYourAgentWallet --per-payment 50 --per-day 150
+```
+
 ```js
 import { openBudget } from 'walletcap';
 
@@ -30,6 +37,21 @@ with budget.pay("$12.50"):
 `npm install walletcap` (Node 22.13+) · `pip install walletcap` (Python 3.11+) ·
 no dependencies · Apache-2.0
 
+## Try it without a wallet
+
+Two runnable demos use a fake payee and a temporary file: no wallet, chain, keys or
+network.
+
+```console
+$ node examples/quickstart/quickstart.mjs
+$ python3 examples/quickstart/quickstart.py
+```
+
+They show three `$0.05` payments against a `$0.15` rolling cap, a `$1.00` refusal, a
+fourth `$0.05` refusal, and a restart that cannot raise the limits. The demo uses
+`create: true`; a production agent opens with the default `create: false` after the
+owner runs `walletcap set`.
+
 ## Why a per-wallet count
 
 Most agent spend controls keep "spent so far" next to something temporary or repeatable: a
@@ -53,8 +75,9 @@ own code. Findings go to the vendors first; this package is the fix, not the fin
    leaves $50, not $200. A restart can lower a limit but never raise one: if the code comes
    back asking for looser limits (a kit's defaults, say), the stored limits stay and you get a
    warning with the command that raises them on purpose.
-4. **Fail closed.** If the count can't be read, nothing pays. A payment whose outcome is
-   unknown keeps counting, because a payment that failed halfway may still have moved money.
+4. **Fail closed.** If the count can't be read, nothing pays; a missing file is not a new
+   budget. A payment whose outcome is unknown keeps counting, because a payment that failed
+   halfway may still have moved money.
 
 The count lives in a SQLite file that every process on the machine shares, and each payment is
 reserved inside one write transaction, so replicas racing for the last dollar can't both win.
@@ -90,7 +113,7 @@ gives you a reservation to `commit()` or `release()` yourself.
 ### x402
 
 `guard()` puts the budget in front of any x402 v2 client from `@x402/core`, so it works under
-`@x402/fetch` and alongside Coinbase's CDP spend controls.
+`@x402/fetch`. Use it as the one counter when the client has no CDP spend store.
 
 ```js
 import { x402Client } from '@x402/core/client';
@@ -115,20 +138,24 @@ const fetchPaid = wrapFetchWithPayment(fetch, client);
 
 ### Coinbase CDP spend controls
 
-`applySpendControls` builds on an x402 client, so `budget.guard(client)` works alongside it, and
-it's the one to use:
+There are two ways to count a CDP payment in the budget; use **one** per client.
+
+- `budget.guard(client)` — the budget prices every asset, refuses anything it cannot price,
+  and reserves in one write transaction. Use it when the budget is the counter.
+- `applySpendControls(client, { ..., store: budget.cdpStore({ asset: USDC }) })` — keep
+  CDP's controls, and make its count durable and shared. The store re-checks the budget inside
+  the write transaction, so replicas sharing the file cannot both take the last dollar.
+
+`budget.cdpStore()` is walletcap's SQLite ledger behind CDP's `SpendStore` interface — **not**
+CDP's in-memory default. Replacing that default is the fix, not a second control.
 
-- **It counts every token.** `guard()` prices the USD stablecoins it knows and refuses
-  anything else, whatever assets the client would otherwise accept.
-- **It reserves in one transaction.** Each payment is checked and reserved inside one write
-  transaction on the budget file, so processes and replicas sharing the file can't both take
-  the last dollar.
-- **It keeps counting what the payee calls failed** until the authorization expires, then frees
-  it on its own.
+Do **not** call both on one client: the CDP store and the guard each record the payment, so
+the budget would count it twice. `budget.guard()` refuses a client that already has CDP
+controls, and a client guarded first refuses CDP controls before signing.
 
-To keep CDP's own count durable and shared as well, swap its in-memory store for walletcap's,
-set `maxCumulativeSpend` (CDP only records through its store when a cumulative cap is set), and
-set `allowedAssets`: CDP never consults its store for a token outside the cap.
+To use the store, swap CDP's in-memory store for walletcap's, set `maxCumulativeSpend` (CDP
+only records through its store when a cumulative cap is set), and set `allowedAssets`: CDP
+never consults its store for a token outside the cap.
 
 ```js
 applySpendControls(client, {
@@ -138,13 +165,15 @@ applySpendControls(client, {
   allowedAssets: [USDC],
   store: budget.cdpStore({ asset: USDC }),
 });
-budget.guard(client);
 ```
 
+`guard()` is the other choice, and the one that prices every token: it refuses a USD stablecoin
+it cannot value instead of letting CDP count only the asset named in the cap.
+
 walletcap's store re-checks the budget when CDP records a payment, so it holds across replicas
 on its own. When CDP removes a payment from its store, the store can't tell why, so the payment
 stays counted as in-flight until you check the chain and run `npx walletcap release <id>`. Use
-CDP 1.56.0 or later.
+CDP 1.56.0 or later; the store is tested against the published 1.60.0.
 
 ### Coinbase Agentic Wallet (awal CLI and MCP server)
 
@@ -233,9 +262,9 @@ The default file is per user: `~/.local/state/walletcap/budget.sqlite` on Linux,
 compute the same default.
 
 The budget is as durable as that file. In a container, put it on a volume that outlives the
-container, or a redeploy starts a new file. For agents that can touch the filesystem, open the
-budget with `create: false` and create it once, as the owner, with `npx walletcap set`:
-then a missing file refuses every payment instead of starting a new budget.
+container, or a redeploy starts a new file. Opening a budget does not create one: a missing file
+refuses every payment. The owner creates it once with `npx walletcap set`; pass `create: true`
+only for a demo or a first-run setup.
 
 ## What it doesn't do
 
@@ -243,8 +272,9 @@ then a missing file refuses every payment instead of starting a new budget.
   go around it: call the wallet directly, or delete the file. To bound an agent like that, keep
   the budget out of its reach (another OS user, another service) or enforce on chain, as
   `AccountCapSpender` does for Spend Permissions.
-- **One file is one host, or a shared volume.** A Postgres backend for replicas on separate
-  hosts is next.
+- **One file is one host.** A shared volume can work for one host's containers, but SQLite
+  over NFS is not a multi-host database. A Postgres backend for replicas on separate hosts is
+  next.
 - **It can't see a revoke that lands later in the same block,** and for x402 schemes that settle
   later (batch vouchers), a payment counts from when the server confirms it.
 - **Some x402 payments can't be confirmed.** `@x402/fetch` doesn't report v1 settlements
@@ -263,8 +293,8 @@ then a missing file refuses every payment instead of starting a new budget.
 | `tests/` | the Python suite, including the tests that drive both languages against one budget file |
 
 ```console
-$ cd js && npm install && node --test            # 50 tests
-$ uv run --with pytest pytest -q                 # 53 tests, from the repository root
+$ cd js && npm install && node --test            # 61 tests
+$ uv run --with pytest pytest -q                 # 59 tests, from the repository root
 $ cd solidity/evm && npm install && node check.mjs ..   # the contract on an EVM, no Foundry needed
 $ cd solidity && forge test                      # the contract's canonical tests, if you have Foundry
 ```
@@ -275,9 +305,19 @@ MCP proxy against stand-ins for Coinbase's wallet and MCP server. The Python sui
 the CLI and one budget shared between both languages. `solidity/evm/check.mjs` compiles the
 contract with solc-js and drives it on an in-process EVM, covering what the Foundry tests cover.
 
-One test is **not** here: the integration test that drives Coinbase's CDP spend controls through
-the shared store. It runs against a vendored build of Coinbase's SDK and lives in ShadowPath's
-own repository. Porting it to the published `@coinbase/cdp-sdk` is open work.
+The JavaScript suite also drives the published `@coinbase/cdp-sdk@1.60.0` through the
+shared store, so the CDP integration is covered against the package users install.
+
+## Security and audit
+
+- [Security policy](SECURITY.md): how to report a vulnerability, supported versions,
+  and the 90-day coordinated-disclosure window for walletcap itself.
+- [Threat model](docs/threat-model.md): what the guard stops, what it does not, and the
+  deployment patterns that hold.
+- [Vendor benchmark disclosure](docs/vendor-disclosure.md): the separate 7-day
+  pre-publication notice for vendor findings in the Agent Payment Benchmark.
+- `AccountCapSpender` is **unaudited**. Read [solidity/README.md](solidity/README.md)
+  before deploying it; testnet only until an independent audit.
 
 ## Prove it holds in your deployment
 

walletcap-0.2.2/SECURITY.md

@@ -0,0 +1,64 @@
+# Security policy
+
+walletcap is a spend guard that sits on the payment path. If you find a way
+around its count, its reservations, or its failure modes, we want to know.
+
+## Supported versions
+
+The latest **0.2.x** release is supported. The 0.2.1 release fixed the
+fail-open default and the CDP store/guard collision; earlier 0.2.0 installs
+should upgrade before relying on the guard.
+
+## Reporting a vulnerability
+
+Email **paul@coriolislabs.ca** with `walletcap security` in the subject. If you
+want to encrypt, ask for a PGP key in the first message; do not send the details
+in a public GitHub issue.
+
+Please include:
+
+- the version, language (JavaScript or Python), and platform;
+- the configuration (single process or replicas, one file or a shared volume);
+- a minimal reproduction, or the sequence of calls;
+- what you expected and what happened.
+
+## What to expect
+
+- We aim to acknowledge a report within **5 business days**.
+- For walletcap itself we use a **90-day** coordinated disclosure window, and
+  we will credit you unless you ask us not to.
+- If a fix ships earlier, we will publish the advisory as soon as users can
+  upgrade.
+
+## In scope
+
+- the SQLite ledger (`ledger.mjs`, `src/walletcap/ledger.py`) and its
+  transaction/counting rules;
+- the JavaScript and Python budget APIs and the CLI;
+- the x402 guard and the CDP `SpendStore`;
+- the Agentic Wallet CLI/MCP wrapper;
+- `AccountCapSpender` and its transfer/allowance handling.
+
+## Out of scope
+
+- an agent with shell access on the same OS user: it can call the wallet
+  directly or delete the file. The guard is not an OS sandbox.
+- editing the SQLite file by someone who can write it;
+- private-key custody and the wallet or chain itself;
+- vulnerabilities in Coinbase, Safe, MetaMask, Tempo, Google or other vendor
+  products. Those are handled under the separate benchmark disclosure policy
+  in [docs/vendor-disclosure.md](docs/vendor-disclosure.md).
+
+## Known limitations
+
+See [docs/threat-model.md](docs/threat-model.md) for the full model. The short
+version:
+
+- the guard binds only the calls that pass through it;
+- the budget file is single-host; a shared volume is not a substitute for a
+  database that speaks a network protocol;
+- an x402 payment whose settlement cannot be confirmed keeps counting until its
+  authorization expires;
+- `AccountCapSpender` is **unaudited**; see
+  [solidity/README.md](solidity/README.md). Do not deploy it with real funds
+  until it has an independent audit.

walletcap-0.2.2/docs/threat-model.md

@@ -0,0 +1,54 @@
+# Threat model
+
+This is the model a security reviewer should test against. It is deliberately
+narrow: walletcap is a spend *counter*, not a sandbox, a key store, or a chain
+observer.
+
+## Assets
+
+- the funds in the wallet;
+- the budget file (limits, reservations, payment history);
+- the agent's ability to keep paying after a restart, a replica, or a key
+  rotation.
+
+## Adversaries and controls
+
+| Adversary | What they can do | Control | Residual risk |
+|---|---|---|---|
+| A buggy agent | Pay more than intended | Per-payment cap, rolling cap, `max_uses`, one reservation per payment | A bug that bypasses the guard entirely |
+| An agent with the same OS user | Delete the budget file, edit it, call the wallet directly | A missing file refuses by default (`create: false`); owner-only `walletcap set`; the file is the source of truth | It can still call the wallet or edit the file. Use a separate OS user, a separate service, or the on-chain cap |
+| A second process or replica on the same host | Race for the last dollar | `BEGIN IMMEDIATE` + a re-check inside the write transaction | A process that writes the file outside the library |
+| A payee | Ask for a different asset, a longer validity, or a "failed" settlement it keeps | The guard prices known USD stablecoins and refuses the rest; the CDP store refuses a different asset; an unknown outcome keeps counting | An asset the guard cannot price is refused, not valued |
+| A payee with a 402 it can replay | Hold authorizations and settle later | A reservation counts until it is committed/released, or its expiry plus one window | A confirmed settlement still needs the chain to be read back |
+| Another local user | Read the budget file | The parent directory is created `0700`; use a `0600` file if you pass a custom `path` | Files copied out of that directory keep their mode |
+| A host failure | Lose the file | The database is one file; back it up like any other state | A lost file is a lost count; the default refuses to recreate it |
+| A later on-chain revoke | Land in the same block after a payment | The payment is already ordered ahead of the revoke | The owner's revocation is not retroactive |
+
+## Deployment patterns
+
+1. **One agent, one OS user.** The owner runs `walletcap set` and keeps the
+   budget file out of the agent's reach. This is the strong pattern.
+2. **A service the agent calls.** The service owns the file and the wallet; the
+   agent gets an API, not the key.
+3. **On chain.** `AccountCapSpender` makes the cap part of the payment path, so
+   the agent's own code cannot raise it. It is unaudited; testnet only until an
+   audit.
+4. **One host, one volume.** SQLite locking is a local-filesystem contract. A
+   shared volume is not a multi-host database; replicas on separate hosts need
+   the Postgres backend (next), not a network mount.
+
+## What the guard does not do
+
+- It does not decide whether a payment *should* happen; it only bounds it.
+- It does not confirm settlement. A payment the payee calls failed keeps
+  counting until its authorization expires, and a payment with no expiry keeps
+  counting until an owner releases it.
+- It does not protect the wallet key or the chain.
+- It does not make an unaudited contract safe.
+
+## CDP store vs guard
+
+Use **one** per client. `budget.guard(client)` is walletcap's own counter and
+prices every asset. `applySpendControls(..., { store: budget.cdpStore() })`
+keeps CDP's policy layer but replaces its store with walletcap's ledger. Both
+write the same budget, so both on one client double-count the payment.

walletcap-0.2.2/docs/vendor-disclosure.md

@@ -0,0 +1,48 @@
+# Vendor benchmark disclosure policy
+
+This policy covers findings about **vendor products** in the Agent Payment
+Benchmark. It is separate from walletcap's own 90-day policy in
+[SECURITY.md](../SECURITY.md).
+
+## The notice
+
+Before publishing a named benchmark result, we send a **7-day pre-publication
+notice** to the vendor's security contact, the product owner, and the relevant
+executive. The notice includes:
+
+- the affected product and version;
+- the configuration tested;
+- the measured impact;
+- a private reproduction package;
+- the exact publication date and time;
+- an offer of a technical call within 48 hours.
+
+We publish on the stated date whether or not the vendor replies. If the vendor
+replies, their statement is included verbatim in the benchmark's response
+column.
+
+## Status labels
+
+- **Unpatched** — no fixed public release as of the publication timestamp.
+- **Acknowledged** — the vendor replied; a fix is in progress.
+- **Fix in review** — a public PR or release candidate exists.
+- **Fixed** — re-tested on the fixed release; the date and version are shown.
+- **Disputed** — the vendor disagrees; their response and our evidence are both
+  published.
+- **No response** — the notice was delivered; no reply by the publication date.
+
+## What we do not do
+
+- We do not change a status because a vendor buys an evaluation, a re-test, or a
+  CI gate. The benchmark publishes regardless.
+- We do not publish a vendor's private data or a customer's identity.
+- We do not treat an in-review report as a public finding before the notice
+  window. Until publication, the public material uses counts and classes, not
+  vendor names or routes.
+
+## Re-tests
+
+Every benchmark entry has a publication timestamp and the exact version tested.
+When a vendor ships a fix, we re-test and update the entry. The paid evaluation
+and annual CI gate are the productized form of that re-test, not a condition of
+the label.

walletcap-0.2.2/examples/quickstart/README.md

@@ -0,0 +1,24 @@
+# Quickstart
+
+No wallet, no chain, no keys, no network. The demo uses a fake payee and a
+temporary SQLite file.
+
+```sh
+node examples/quickstart/quickstart.mjs
+python3 examples/quickstart/quickstart.py
+```
+
+Both print the same story: three `$0.05` payments against a `$0.15` rolling
+cap; a `$1.00` payment refused by the per-payment cap; a fourth `$0.05`
+refused by the rolling cap; a restart that asks for looser limits and is
+refused because the stored count and limits stay.
+
+The demo opens with `create: true` because it starts from an empty file. A
+production agent opens with the default `create: false`, after the owner has
+created the budget once:
+
+```sh
+npx walletcap set --wallet 0xYourAgentWallet --per-payment 50 --per-day 150
+```
+
+The demo file is `examples/quickstart/demo.sqlite` and is gitignored.

walletcap-0.2.2/examples/quickstart/quickstart.mjs

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: Apache-2.0
+// A ten-second demo with a fake payee: no wallet, chain, key or network.
+// Production code opens the budget with create: false; the owner creates it
+// once with `npx walletcap set`.
+import { rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { BudgetRefused, openBudget } from '../../js/index.mjs';
+
+const PATH = join(dirname(fileURLToPath(import.meta.url)), 'demo.sqlite');
+const WALLET = '0xd797ead28c38575fdf4fc523866287372340ca02';
+const TX = `0x${'ab'.repeat(32)}`;
+
+rmSync(PATH, { force: true });
+
+const budget = openBudget({
+  wallet: WALLET,
+  path: PATH,
+  perPayment: '$0.05',
+  perDay: '$0.15',
+  create: true, // demo only
+});
+
+const attempt = async (target, label, amount) => {
+  try {
+    await target.pay(amount, async () => TX);
+    console.log(`paid     ${label.padEnd(28)} ${amount}`);
+  } catch (error) {
+    if (!(error instanceof BudgetRefused)) throw error;
+    console.log(`REFUSED  ${label.padEnd(28)} ${amount}  (${error.reason})`);
+  }
+};
+
+console.log(`Budget: ${budget.status().summary}\n`);
+for (const amount of ['$0.05', '$0.05', '$0.05']) await attempt(budget, 'three small payments', amount);
+await attempt(budget, 'past the per-payment cap', '$1.00');
+await attempt(budget, 'past the rolling cap', '$0.05');
+
+const beforeRestart = budget.status().spent;
+budget.close();
+
+const warnings = [];
+const restarted = openBudget({
+  wallet: WALLET,
+  path: PATH,
+  perPayment: '$2.50',
+  perDay: '$5',
+  onWarning: message => warnings.push(message),
+});
+console.log(`\nRestart asks for looser limits; stored limits stay: ${warnings[0] ?? 'no warning'}`);
+console.log(`Count before restart: ${beforeRestart}; after restart: ${restarted.status().spent}\n`);
+await attempt(restarted, 'the same $0.05 after restart', '$0.05');
+
+const final = openBudget({ wallet: WALLET, path: PATH });
+console.log(`\nFinal: ${final.status().summary}`);
+console.log(`Result: ${final.status().spent} of ${final.status().cap} spent, ${final.status().remaining} left.`);
+console.log(`History: ${final.history().length} payments; the first is ${final.history()[0].status}.`);
+final.close();
+restarted.close();