walletcap 0.2.4__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (114) hide show
  1. {walletcap-0.2.4 → walletcap-0.3.0}/.circleci/config.yml +0 -1
  2. {walletcap-0.2.4 → walletcap-0.3.0}/.github/workflows/ci.yml +10 -7
  3. walletcap-0.3.0/CHANGELOG.md +211 -0
  4. {walletcap-0.2.4 → walletcap-0.3.0}/PKG-INFO +89 -46
  5. {walletcap-0.2.4 → walletcap-0.3.0}/README.md +88 -45
  6. {walletcap-0.2.4 → walletcap-0.3.0}/SECURITY.md +8 -6
  7. {walletcap-0.2.4 → walletcap-0.3.0}/crash-test/README.md +2 -2
  8. {walletcap-0.2.4 → walletcap-0.3.0}/crash-test/agentkit-agent.mjs +4 -0
  9. {walletcap-0.2.4 → walletcap-0.3.0}/crash-test/ci/check-agentkit.mjs +4 -2
  10. {walletcap-0.2.4 → walletcap-0.3.0}/crash-test/cli.mjs +8 -3
  11. {walletcap-0.2.4 → walletcap-0.3.0}/crash-test/package.json +2 -2
  12. {walletcap-0.2.4 → walletcap-0.3.0}/crash-test/test/crash-test.test.mjs +11 -3
  13. {walletcap-0.2.4 → walletcap-0.3.0}/docs/coinbase-agentic-wallet-budget.md +21 -11
  14. {walletcap-0.2.4 → walletcap-0.3.0}/docs/coinbase-agentkit-spending-limit.md +9 -5
  15. {walletcap-0.2.4 → walletcap-0.3.0}/docs/coinbase-cdp-spend-controls.md +14 -6
  16. {walletcap-0.2.4 → walletcap-0.3.0}/docs/index.md +5 -4
  17. {walletcap-0.2.4 → walletcap-0.3.0}/docs/llms.txt +4 -4
  18. {walletcap-0.2.4 → walletcap-0.3.0}/docs/python-agent-spending-limit.md +9 -3
  19. walletcap-0.3.0/docs/threat-model.md +62 -0
  20. {walletcap-0.2.4 → walletcap-0.3.0}/docs/x402-spending-limit.md +11 -5
  21. {walletcap-0.2.4 → walletcap-0.3.0}/js/README.md +5 -4
  22. walletcap-0.3.0/js/_clock.mjs +20 -0
  23. {walletcap-0.2.4 → walletcap-0.3.0}/js/agentic.mjs +156 -48
  24. {walletcap-0.2.4 → walletcap-0.3.0}/js/cdp.mjs +49 -28
  25. {walletcap-0.2.4 → walletcap-0.3.0}/js/cli.mjs +61 -4
  26. walletcap-0.3.0/js/errors.mjs +66 -0
  27. {walletcap-0.2.4 → walletcap-0.3.0}/js/index.d.ts +77 -14
  28. {walletcap-0.2.4 → walletcap-0.3.0}/js/index.mjs +62 -32
  29. walletcap-0.3.0/js/ledger.mjs +786 -0
  30. {walletcap-0.2.4 → walletcap-0.3.0}/js/money.mjs +91 -27
  31. {walletcap-0.2.4 → walletcap-0.3.0}/js/package.json +3 -2
  32. walletcap-0.3.0/js/tests/agentic.test.mjs +564 -0
  33. walletcap-0.3.0/js/tests/budget.test.mjs +429 -0
  34. walletcap-0.3.0/js/tests/cdp.test.mjs +203 -0
  35. walletcap-0.3.0/js/tests/cli.test.mjs +172 -0
  36. {walletcap-0.2.4 → walletcap-0.3.0}/js/tests/money.test.mjs +32 -0
  37. {walletcap-0.2.4 → walletcap-0.3.0}/js/tests/processes.test.mjs +25 -0
  38. {walletcap-0.2.4 → walletcap-0.3.0}/js/tests/support/fake-awal/dist/ipcClient.js +4 -3
  39. walletcap-0.3.0/js/tests/x402.test.mjs +249 -0
  40. {walletcap-0.2.4 → walletcap-0.3.0}/js/x402.mjs +112 -26
  41. {walletcap-0.2.4 → walletcap-0.3.0}/llms.txt +4 -4
  42. {walletcap-0.2.4 → walletcap-0.3.0}/pyproject.toml +1 -1
  43. {walletcap-0.2.4 → walletcap-0.3.0}/scripts/ci.sh +0 -1
  44. {walletcap-0.2.4 → walletcap-0.3.0}/server.json +2 -2
  45. {walletcap-0.2.4 → walletcap-0.3.0}/solidity/evm/package.json +1 -1
  46. walletcap-0.3.0/spec/vectors/money.json +297 -0
  47. {walletcap-0.2.4 → walletcap-0.3.0}/src/walletcap/__init__.py +6 -2
  48. {walletcap-0.2.4 → walletcap-0.3.0}/src/walletcap/__main__.py +93 -6
  49. walletcap-0.3.0/src/walletcap/_clock.py +21 -0
  50. {walletcap-0.2.4 → walletcap-0.3.0}/src/walletcap/budget.py +122 -24
  51. {walletcap-0.2.4 → walletcap-0.3.0}/src/walletcap/errors.py +17 -0
  52. {walletcap-0.2.4 → walletcap-0.3.0}/src/walletcap/ledger.py +463 -81
  53. {walletcap-0.2.4 → walletcap-0.3.0}/src/walletcap/money.py +144 -30
  54. walletcap-0.3.0/tests/test_budget.py +681 -0
  55. walletcap-0.3.0/tests/test_ledger.py +389 -0
  56. walletcap-0.3.0/tests/test_money.py +109 -0
  57. walletcap-0.2.4/CHANGELOG.md +0 -77
  58. walletcap-0.2.4/docs/threat-model.md +0 -54
  59. walletcap-0.2.4/js/errors.mjs +0 -40
  60. walletcap-0.2.4/js/ledger.mjs +0 -519
  61. walletcap-0.2.4/js/tests/agentic.test.mjs +0 -288
  62. walletcap-0.2.4/js/tests/budget.test.mjs +0 -219
  63. walletcap-0.2.4/js/tests/cdp.test.mjs +0 -117
  64. walletcap-0.2.4/js/tests/cli.test.mjs +0 -80
  65. walletcap-0.2.4/js/tests/x402.test.mjs +0 -124
  66. walletcap-0.2.4/tests/test_budget.py +0 -332
  67. walletcap-0.2.4/tests/test_ledger.py +0 -277
  68. walletcap-0.2.4/tests/test_money.py +0 -36
  69. {walletcap-0.2.4 → walletcap-0.3.0}/.github/workflows/mcp-registry.yml +0 -0
  70. {walletcap-0.2.4 → walletcap-0.3.0}/.github/workflows/publish.yml +0 -0
  71. {walletcap-0.2.4 → walletcap-0.3.0}/.gitignore +0 -0
  72. {walletcap-0.2.4 → walletcap-0.3.0}/LICENSE +0 -0
  73. {walletcap-0.2.4 → walletcap-0.3.0}/NOTICE +0 -0
  74. {walletcap-0.2.4 → walletcap-0.3.0}/crash-test/agent.mjs +0 -0
  75. {walletcap-0.2.4 → walletcap-0.3.0}/crash-test/contracts/build.mjs +0 -0
  76. {walletcap-0.2.4 → walletcap-0.3.0}/crash-test/contracts/coinbase-base-mainnet.json +0 -0
  77. {walletcap-0.2.4 → walletcap-0.3.0}/crash-test/contracts/walletcap.json +0 -0
  78. {walletcap-0.2.4 → walletcap-0.3.0}/crash-test/spend-permissions.mjs +0 -0
  79. {walletcap-0.2.4 → walletcap-0.3.0}/crash-test/spend-store.mjs +0 -0
  80. {walletcap-0.2.4 → walletcap-0.3.0}/docs/_config.yml +0 -0
  81. {walletcap-0.2.4 → walletcap-0.3.0}/docs/coinbase-spend-permissions-cap.md +0 -0
  82. {walletcap-0.2.4 → walletcap-0.3.0}/docs/social-preview.png +0 -0
  83. {walletcap-0.2.4 → walletcap-0.3.0}/docs/vendor-disclosure.md +0 -0
  84. {walletcap-0.2.4 → walletcap-0.3.0}/examples/quickstart/README.md +0 -0
  85. {walletcap-0.2.4 → walletcap-0.3.0}/examples/quickstart/quickstart.mjs +0 -0
  86. {walletcap-0.2.4 → walletcap-0.3.0}/examples/quickstart/quickstart.py +0 -0
  87. {walletcap-0.2.4 → walletcap-0.3.0}/glama.json +0 -0
  88. {walletcap-0.2.4 → walletcap-0.3.0}/js/LICENSE +0 -0
  89. {walletcap-0.2.4 → walletcap-0.3.0}/js/NOTICE +0 -0
  90. {walletcap-0.2.4 → walletcap-0.3.0}/js/_keccak.mjs +0 -0
  91. {walletcap-0.2.4 → walletcap-0.3.0}/js/tests/agentkit.test.mjs +0 -0
  92. {walletcap-0.2.4 → walletcap-0.3.0}/js/tests/cdp-sdk.test.mjs +0 -0
  93. {walletcap-0.2.4 → walletcap-0.3.0}/js/tests/keccak.test.mjs +0 -0
  94. {walletcap-0.2.4 → walletcap-0.3.0}/js/tests/support/fake-awal/dist/index.js +0 -0
  95. {walletcap-0.2.4 → walletcap-0.3.0}/js/tests/support/fake-awal/package.json +0 -0
  96. {walletcap-0.2.4 → walletcap-0.3.0}/js/tests/support/fake-payments-mcp.mjs +0 -0
  97. {walletcap-0.2.4 → walletcap-0.3.0}/js/tests/support/payer.mjs +0 -0
  98. {walletcap-0.2.4 → walletcap-0.3.0}/js/tests/support/race.mjs +0 -0
  99. {walletcap-0.2.4 → walletcap-0.3.0}/js/tests/support/x402-kit.mjs +0 -0
  100. {walletcap-0.2.4 → walletcap-0.3.0}/js/tests/support/x402-payer.mjs +0 -0
  101. {walletcap-0.2.4 → walletcap-0.3.0}/js/tests/types/agentkit.d.ts +0 -0
  102. {walletcap-0.2.4 → walletcap-0.3.0}/js/tests/types/recipe.ts +0 -0
  103. {walletcap-0.2.4 → walletcap-0.3.0}/js/tests/types/subclass.ts +0 -0
  104. {walletcap-0.2.4 → walletcap-0.3.0}/js/tests/x402-fetch.test.mjs +0 -0
  105. {walletcap-0.2.4 → walletcap-0.3.0}/pytest.ini +0 -0
  106. {walletcap-0.2.4 → walletcap-0.3.0}/solidity/README.md +0 -0
  107. {walletcap-0.2.4 → walletcap-0.3.0}/solidity/evm/check.mjs +0 -0
  108. {walletcap-0.2.4 → walletcap-0.3.0}/solidity/foundry.toml +0 -0
  109. {walletcap-0.2.4 → walletcap-0.3.0}/solidity/src/AccountCapSpender.sol +0 -0
  110. {walletcap-0.2.4 → walletcap-0.3.0}/solidity/test/AccountCapSpender.t.sol +0 -0
  111. {walletcap-0.2.4 → walletcap-0.3.0}/solidity/test/Mocks.sol +0 -0
  112. {walletcap-0.2.4 → walletcap-0.3.0}/src/walletcap/_keccak.py +0 -0
  113. {walletcap-0.2.4 → walletcap-0.3.0}/src/walletcap/py.typed +0 -0
  114. {walletcap-0.2.4 → walletcap-0.3.0}/tests/test_keccak.py +0 -0
@@ -37,7 +37,6 @@ jobs:
37
37
  name: Crash test
38
38
  command: |
39
39
  cd crash-test
40
- npm install --no-audit --no-fund --no-package-lock
41
40
  npm install --no-save --no-audit --no-fund --no-package-lock ../js
42
41
  node contracts/build.mjs --check
43
42
  node --test
@@ -52,10 +52,10 @@ jobs:
52
52
  container: node:22-bookworm
53
53
  steps:
54
54
  - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
55
+ # One install, so the walletcap the crash test depends on comes from this checkout and is
56
+ # never looked up on npm (a release's walletcap isn't published until the PR merges).
55
57
  - name: Install the crash test, on this checkout's walletcap
56
- run: |
57
- npm install --no-audit --no-fund --no-package-lock
58
- npm install --no-save --no-audit --no-fund --no-package-lock ../js
58
+ run: npm install --no-save --no-audit --no-fund --no-package-lock ../js
59
59
  working-directory: crash-test
60
60
  - name: Check the shipped contracts match their sources
61
61
  run: node contracts/build.mjs --check
@@ -70,11 +70,14 @@ jobs:
70
70
  container: node:22-bookworm
71
71
  steps:
72
72
  - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
73
- - name: Pack the crash test
74
- run: npm pack --pack-destination "$RUNNER_TEMP"
73
+ - name: Pack the crash test and this checkout's walletcap
74
+ run: |
75
+ npm pack --pack-destination "$RUNNER_TEMP"
76
+ (cd ../js && npm pack --pack-destination "$RUNNER_TEMP")
75
77
  working-directory: crash-test
76
- # As users run it: AgentKit installed alongside, walletcap from npm.
78
+ # As users run it, from the packed tarballs, with AgentKit installed alongside. walletcap is
79
+ # this checkout's: the version the crash test depends on isn't on npm until it is released.
77
80
  - name: Run it with Coinbase AgentKit alongside
78
- run: npx -y -p "$RUNNER_TEMP"/walletcap-crash-test-*.tgz -p @coinbase/agentkit@0.10.4 walletcap-crash-test --agentkit --json > "$RUNNER_TEMP/agentkit.json"
81
+ run: npx -y -p "$RUNNER_TEMP"/walletcap-crash-test-*.tgz -p "$RUNNER_TEMP"/walletcap-[0-9]*.tgz -p @coinbase/agentkit@0.10.4 walletcap-crash-test --agentkit --json > "$RUNNER_TEMP/agentkit.json"
79
82
  - name: Check the AgentKit row
80
83
  run: node crash-test/ci/check-agentkit.mjs "$RUNNER_TEMP/agentkit.json"
@@ -0,0 +1,211 @@
1
+ <!-- SPDX-License-Identifier: Apache-2.0 -->
2
+ # Changelog
3
+
4
+ ## 0.3.0 — 2026-11-06
5
+
6
+ This release fixes ways past walletcap's own cap that reviewers reproduced, and ways its
7
+ JavaScript and Python packages read the same input differently. It removes public options,
8
+ changes what an error does to a payment and upgrades the budget file, so it is a minor release,
9
+ not a patch.
10
+
11
+ ### Breaking
12
+
13
+ - An error never settles a payment. When the payment function throws an error not tagged
14
+ `notSent()` (Python: `NotSent`), the payment stays in flight, marked unknown, instead of being
15
+ committed. It counts until one window past its `settlesBy`, or, without one, until its owner
16
+ releases it. `status()` shows it as in flight, not spent. The Agentic Wallet wrapper does the
17
+ same for a send or paid x402 payment whose outcome is unknown.
18
+ - A commit never shortens a hold. A payment committed from a reservation with a settle-by time
19
+ counts until one window past the later of the commit and that time, so a payee's own word that
20
+ a payment settled can't free the budget while its authorization can still be redeemed.
21
+ - The budget file is schema 2. 0.3 upgrades a 0.2.x file when it first opens it: a budget kept
22
+ under another spelling of a wallet (checksummed, uppercase, CAIP-10) moves to the lowercase
23
+ name, merged with any budget there with the tighter of every limit and every payment.
24
+ `declare()` with other limits than a merged budget's says what the upgrade merged. A budget in
25
+ another unit than the wallet's can't be merged: it stays under its 0.2.x name, and the wallet
26
+ is frozen, with the reason in its refusals, until its owner unfreezes it; the rest of the file
27
+ upgrades as usual. 0.2.x refuses a schema 2 file, so stop 0.2.x processes before upgrading.
28
+ - The `clock` option is gone from `openBudget`, `cdpStore` and `SharedBudgetStore`, and from
29
+ Python's `open_budget`, `Budget` and `Ledger`. The ledger reads the system clock. Passing a
30
+ clock is an error.
31
+ - Python's `Ledger` no longer takes `reservation_ttl_seconds`.
32
+ - A `settlesBy` that isn't after now is refused with a `BudgetError`.
33
+ - Python refuses a naive datetime for `settles_by`.
34
+ - A payment that went through, or may have, but couldn't be recorded raises
35
+ `PaymentNotRecorded`, not `BudgetError`. It is not a subclass of `BudgetError`, and it carries
36
+ the reservation id (`reservationId`, `reservation_id`) and the cause.
37
+ - `MAX_AMOUNT` is 10^15 micro-dollars ($1,000,000,000), not 2^63 − 1. A larger amount, cap or
38
+ per-payment limit is refused.
39
+ - The x402 guard pays only on terms whose `maxTimeoutSeconds` is a whole number of seconds up to
40
+ 3600 (`MAX_PAYMENT_TIMEOUT_SECONDS`), as Coinbase's CDP spend controls do. It passes over
41
+ longer terms for shorter ones on offer, and refuses before signing, with the reason
42
+ `'timeout'`, when none are.
43
+ - The Agentic Wallet wrapper hands the wallet only the terms it can price that are valid an hour
44
+ or less, and refuses a paid x402 request, before the wallet is asked, when none are left
45
+ (reason `'asset'` or `'timeout'`).
46
+ - `guard(client, { assets })` and the Agentic Wallet wrapper's `assets` refuse an entry that
47
+ changes a built-in asset's decimals, and decimals that aren't an integer from 0 to 18.
48
+ - Amounts and windows take only the digits 0-9, and only ASCII whitespace is trimmed, in both
49
+ languages. `walletcap awal send` refuses an amount with trailing text, an exponent or a
50
+ separator. The wrapper refuses a send whose `amountAtomic` isn't plain digits or that has no
51
+ recipient, and passes the wallet only `recipient`, `amountAtomic`, `asset` and `chain`.
52
+ - Every ledger method names a budget the way `openBudget` does: an EVM address, bare or CAIP-10,
53
+ is lowercased after its EIP-55 check.
54
+
55
+ ### Fixed
56
+
57
+ - A payment whose function threw was committed, so it counted for one window from the error. A
58
+ transfer whose receipt wait timed out and that was mined a day later let $300 through a $150
59
+ window.
60
+ - A payee could answer "settled" with a made-up hash, keep the authorization and redeem it later:
61
+ the commit had ended the count after one window. With a 30-day validity, five $0.15
62
+ authorizations passed a $0.15-a-day cap; with Permit2, $0.75 passed a $0.15-per-10-minutes cap
63
+ in 50 minutes. A payment now counts until one window past its authorization's expiry. The
64
+ guard reads it from the signed payload (EIP-3009 `validBefore`, Permit2 `deadline`), or takes
65
+ the signing time plus `maxTimeoutSeconds`. The Agentic Wallet wrapper takes the longest
66
+ `maxTimeoutSeconds` among the terms it hands the wallet, whatever their scheme.
67
+ - The CDP store counted a payment for one window from when CDP recorded it, though CDP signs it
68
+ after and lets the authorization be redeemed for up to an hour. It now counts until an hour
69
+ and a minute after the record, plus one window.
70
+ - A `settlesBy` already past was stored as given, so the reservation never counted and a second
71
+ full cap was reserved.
72
+ - The CDP store recorded a payment at the time in CDP's entry, so a backdated entry had already
73
+ aged out. It records at the ledger's own time.
74
+ - A process that waited for another's write lock dated its payment as much as the wait earlier,
75
+ so the payment stopped counting that much early. Both ledgers read the time once the lock is
76
+ held.
77
+ - A process whose clock ran a day ahead saw an empty budget and paid a second full cap.
78
+ - Python's `reservation_ttl_seconds` let a hold lapse while its payment could still settle: $300
79
+ on a $150 cap.
80
+ - `SharedBudgetStore` and Python's `Ledger` took a checksummed address as given, which opened a
81
+ second budget beside the lowercase one, with its own cap.
82
+ - Two near-maximum payments overflowed SQLite's `SUM`, and every later payment from the wallet
83
+ failed.
84
+ - Python read a naive `settles_by` as local time: 9 hours early in Tokyo.
85
+ - Code that retried on `BudgetError` could pay twice after "the payment went through but could
86
+ not be recorded".
87
+ - An asset override could price USDC at 18 decimals, counting $1 as a millionth of a cent.
88
+ - `walletcap awal send` read amounts with `parseFloat`: `100.5abc` was $100.50, and `0.29` was
89
+ 289,999 atomic units.
90
+ - Python read Arabic-Indic and other Unicode digits as numbers (`١٢` was $12), and trimmed
91
+ `\x85` and other non-ASCII spaces, which JavaScript doesn't.
92
+ - A float of dollars converted differently in the two languages on about 0.5% of halfway values.
93
+ Both now read the shortest decimal that gives the float back and round it half up.
94
+ - Python rounded a `Decimal` amount at 28 digits before checking it was a whole number of
95
+ micro-dollars, and raised `ValueError`, not `BudgetError`, for an input over 4,300 digits.
96
+
97
+ ### Changed
98
+
99
+ - `budget.holds()` (Python: `budget.holds()`, returning `Hold`s) and `walletcap holds` list the
100
+ open payments that still count: id, amount, reason (in flight, refused, unknown), age, and
101
+ when each stops counting. `walletcap release --all-unknown --older-than <24h|7d|30m>` gives
102
+ back every payment of unknown or refused outcome older than that, for an owner who has checked
103
+ the chain, except one whose settle-by time is still ahead: the payee could still settle it. One
104
+ with no settle-by time, which the wallet may have signed as it failed, goes only once it is an
105
+ hour and a minute old (`UNBOUNDED_HOLD_MS`).
106
+ - A budget or payment-count refusal names the open payments that take up the room, oldest
107
+ first, and says how to list and release them. `BudgetRefused.brief`, and `brief` beside
108
+ `message` in `budget.check()`, is the refusal without them. The x402 guard (and so AgentKit),
109
+ the CDP store and the Agentic Wallet wrapper, with its CLI and MCP proxy, tell the agent only
110
+ that.
111
+ - Python's `pay()` takes `settles_by`, as JavaScript's `pay()` takes `settlesBy`. Python's
112
+ `Reservation` and `Ledger` have `annotate()`.
113
+ - The Agentic Wallet wrapper:
114
+ - It hands the wallet, as `paymentRequirements`, the terms it can price that are valid an hour
115
+ or less, from the caller's or the ones walletcap discovered, with the 402's extensions unless
116
+ the caller gave some. The wallet then skips its own discovery and signs only a term equal to
117
+ one of them. A `discover` option of one's own may return the 402 answer or its list of terms.
118
+ - Once the wallet answers, a paid request counts until the longest `maxTimeoutSeconds` among
119
+ the terms it was handed (a Solana term at least two minutes, the life of its blockhash), plus
120
+ a minute, after that answer, plus one window, instead of until it is released. That holds for
121
+ one the payee calls settled too. One the wallet never answered counts until it is released.
122
+ - A free endpoint's one-unit hold is released unless the payee confirms a payment, so a free
123
+ endpoint that fails can't use up `maxPayments`.
124
+ - Every ledger write after the wallet answers raises `PaymentNotRecorded` if it fails.
125
+ - `cdpStore()` and `SharedBudgetStore` refuse options they don't take. The docs ask for CDP
126
+ 1.60.0 or later, whose published source refuses a `maxTimeoutSeconds` over 3600. A payment CDP
127
+ rolls back counts as long as it would have settled, an hour and a minute after CDP recorded it
128
+ plus one window, instead of until it is released.
129
+ - The docs no longer say machines can share a budget through a shared volume. The budget file
130
+ serves one host: SQLite's locks aren't reliable over NFS, SMB or Docker Desktop bind mounts,
131
+ and multiple hosts need a shared service, which isn't shipped yet.
132
+ - `spec/vectors/money.json` holds the amounts both test suites must read the same way, or refuse.
133
+ - `walletcap-crash-test` 0.3.1 depends on walletcap `^0.3.0`. In its AgentKit row, walletcap now
134
+ passes over the merchant's first-listed $1.00, valid 4 days, and the offer left is the 1¢ one
135
+ the agent approved, where it refused the payment before. walletcap limits the amount, not which
136
+ offer is paid; the row passes only if walletcap signs the approved offer or nothing.
137
+
138
+ ## 0.2.4 — 2026-11-06
139
+
140
+ ### Added
141
+
142
+ - `mcpName` in the npm package and a `server.json`, so `walletcap awal-mcp` can be listed in the
143
+ official MCP Registry as `io.github.coriolislabs/walletcap`. `glama.json` names the maintainer
144
+ for Glama.
145
+ - A docs site, https://coriolislabs.github.io/WalletCap/, with one page per integration, and
146
+ `llms.txt`.
147
+
148
+ ### Fixed
149
+
150
+ - The `create` doc comment in `index.d.ts` said it defaulted to true. It defaults to false.
151
+
152
+ ### Changed
153
+
154
+ - Package descriptions and search keywords on npm and PyPI, and a README that leads with the
155
+ crash test.
156
+
157
+ ## 0.2.3 — 2026-11-06
158
+
159
+ ### Changed
160
+
161
+ - Releases are published from GitHub Actions with trusted publishing: npm with provenance,
162
+ PyPI with PEP 740 attestations. No token is stored. A GitHub Release whose tag doesn't
163
+ match the package version is refused.
164
+
165
+ ### Fixed
166
+
167
+ - `AccountCapSpender` no longer locks an account after a burst of payments. An unbounded log
168
+ made the first payment after 3,000 tiny ones cost about 17.7M gas, past the 2^24
169
+ per-transaction cap. The window is now counted in 24 buckets in a fixed ring of 25 slots, so
170
+ every `pay` costs the same gas. A payment counts for up to one bucket (window/24) past its
171
+ window, never less. The window must be a multiple of 24 seconds.
172
+ - `walletcap awal-mcp` ran `npx -y @coinbase/payments-mcp`, which is Coinbase's installer, not
173
+ the MCP server. It now runs the installed server, `~/.payments-mcp/bundle.js`, and says how to
174
+ install it when it is missing.
175
+ - `walletcap awal-mcp` forwarded every tool it didn't count. It now passes through only the
176
+ tools that move no money, and counts `send` and `make_http_request_with_x402`. It refuses
177
+ everything else, `trade` included, and leaves those tools out of `tools/list`, unless the
178
+ owner names one with `--allow-tool`. JSON-RPC batches and lines that aren't JSON are refused.
179
+
180
+ ### Added
181
+
182
+ - `budget.guardAgentKit(provider)` puts the budget on every x402 client an AgentKit
183
+ `X402ActionProvider` builds. The README's subclass recipe didn't compile in TypeScript,
184
+ where `createX402Client` is private. `tsc` now checks the recipe against AgentKit's declared
185
+ types in the test suite.
186
+
187
+ ## 0.2.2 — 2026-11-05
188
+
189
+ ### Changed
190
+
191
+ - A mixed-case EVM address is checked against EIP-55 before it is accepted. A bad
192
+ checksum is refused; all-lowercase and all-uppercase hex are still accepted.
193
+ - A Solana CAIP-10 address is reduced to its address, so it and the bare address
194
+ share one budget.
195
+ - Numeric `window` values are milliseconds in Python too, matching JavaScript.
196
+
197
+ ### Fixed
198
+
199
+ - The rolling window cannot be shortened once the budget has spend. An edit can
200
+ change the cap and the per-payment limit, but it cannot reset the count by
201
+ shrinking the window.
202
+
203
+ ### Added
204
+
205
+ - `SECURITY.md`, `docs/threat-model.md`, `docs/vendor-disclosure.md`, and the
206
+ Solidity audit status in `solidity/README.md`.
207
+ - `examples/quickstart/` in JavaScript and Python, run in CI. No wallet, chain,
208
+ keys or network.
209
+ - EIP-55, Solana CAIP-10, and window-freeze tests in both languages.
210
+
211
+ ## 0.2.1 — 2026-11-05
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: walletcap
3
- Version: 0.2.4
3
+ Version: 0.3.0
4
4
  Summary: Spend limits for AI agent wallets: a per-payment cap and rolling 24-hour budget that holds across restarts, kept in a SQLite file every process and the npm package share.
5
5
  Project-URL: Homepage, https://github.com/coriolislabs/WalletCap
6
6
  Project-URL: Repository, https://github.com/coriolislabs/WalletCap
@@ -30,7 +30,7 @@ Description-Content-Type: text/markdown
30
30
  [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/coriolislabs/WalletCap/blob/main/LICENSE)
31
31
 
32
32
  **Spend limits for AI agent wallets that pay in USDC: a per-payment cap and a rolling 24-hour
33
- budget that holds across restarts, replicas and payment rails.** walletcap plugs into x402
33
+ budget that holds across restarts, replicas on one host and payment rails.** walletcap plugs into x402
34
34
  clients, Coinbase CDP's x402 spend controls, Coinbase AgentKit, the Coinbase Agentic Wallet CLI
35
35
  and payments MCP server, and Coinbase Spend Permissions. By ShadowPath.
36
36
 
@@ -66,8 +66,9 @@ times. Those runs used `@coinbase/cdp-sdk` 1.61.0, `@x402/core` 2.30.0, SpendPer
66
66
  1.0.0 and walletcap 0.2.3.
67
67
 
68
68
  Add `--agentkit` for Coinbase AgentKit's row: the agent approves a 1¢ offer, and AgentKit signs
69
- the merchant's first-listed $1.00 on Base mainnet. walletcap, at 2¢ a payment, refuses it before
70
- signing. [The crash test's README](https://github.com/coriolislabs/WalletCap/tree/main/crash-test)
69
+ the merchant's first-listed $1.00 on Base mainnet. walletcap, at 2¢ a payment, limits the amount,
70
+ not which offer is paid: it passes over the $1.00, valid 4 days, and the offer left is the 1¢ the
71
+ agent approved. [The crash test's README](https://github.com/coriolislabs/WalletCap/tree/main/crash-test)
71
72
  says exactly what runs.
72
73
 
73
74
  ## Install and use
@@ -154,11 +155,11 @@ own code. Findings go to the vendors first; this package is the fix, not the fin
154
155
  warning with the command that raises them on purpose.
155
156
  4. **Fail closed.** If the count can't be read, nothing pays; a missing file is not a new
156
157
  budget. A payment whose outcome is unknown keeps counting, because a payment that failed
157
- halfway may still have moved money.
158
+ halfway may still have moved money. An error never settles a payment.
158
159
 
159
- The count lives in a SQLite file that every process on the machine shares, and each payment is
160
- reserved inside one write transaction, so replicas racing for the last dollar can't both win.
161
- JavaScript and Python read and write the same file.
160
+ The count lives in a SQLite file that every process on one host shares, and each payment is
161
+ reserved inside one write transaction, so replicas on that host racing for the last dollar
162
+ can't both win. JavaScript and Python read and write the same file.
162
163
 
163
164
  ## Use it
164
165
 
@@ -172,8 +173,10 @@ const tx = await budget.pay('$5', async reservation => {
172
173
  }, { to: payee, note: 'weather API' });
173
174
  ```
174
175
 
175
- If the payment throws, it still counts, because it may have left the wallet. If you know it
176
- didn't, say so and the amount comes back:
176
+ If the payment throws, it may still have left the wallet, so it stays in flight, marked
177
+ unknown in the history. It counts until one window past `settlesBy`, the last moment it could
178
+ still settle (after now), if you pass one; otherwise until you check the chain and run
179
+ `npx walletcap release <id>`. If you know it didn't leave, say so and the amount comes back:
177
180
 
178
181
  ```js
179
182
  import { notSent } from 'walletcap';
@@ -181,8 +184,13 @@ import { notSent } from 'walletcap';
181
184
  throw notSent(error); // inside the payment function
182
185
  ```
183
186
 
184
- In Python, `raise NotSent("card declined")` inside the `with` block. Set `payment.tx` in the
185
- block to keep the transaction hash in the history, and use `async with` in async code.
187
+ In Python, `raise NotSent("card declined")` inside the `with` block, and pass `settles_by` (a
188
+ timezone-aware datetime) to `pay()`. Set `payment.tx` in the block to keep the transaction hash
189
+ in the history, and use `async with` in async code.
190
+
191
+ If the payment went through but the budget can't record it, `pay()` throws
192
+ `PaymentNotRecorded`. It is not a `BudgetError`, so code that retries on a `BudgetError` won't
193
+ pay twice. The payment still counts as in flight.
186
194
 
187
195
  `budget.check('$5')` answers `{ ok, reason, remaining }` without spending. `budget.reserve()`
188
196
  gives you a reservation to `commit()` or `release()` yourself.
@@ -203,13 +211,17 @@ const fetchPaid = wrapFetchWithPayment(fetch, client);
203
211
 
204
212
  - Each payment is checked before it is signed, and reserved once its payload exists and every
205
213
  other control has passed.
206
- - It counts as spent when the server confirms settlement. A payee that answers "payment
207
- failed" still holds your signed authorization and could settle it until it expires, so the
208
- payment keeps counting until then.
214
+ - It counts as spent when the server confirms settlement, and at least until its authorization
215
+ expires, plus one window: the confirmation is the payee's own word, and a payee that answers
216
+ "payment failed" still holds the signed authorization too.
217
+ - A payee may ask for an authorization valid up to an hour (`MAX_PAYMENT_TIMEOUT_SECONDS`, 3600),
218
+ as Coinbase's CDP spend controls allow. Longer terms are passed over for shorter ones on offer;
219
+ when none are, the payment is refused before signing, with the reason `timeout`.
209
220
  - USDC on Base, Ethereum, Polygon, Arbitrum, Optimism, Avalanche and Solana is priced out of
210
221
  the box, plus Base Sepolia, Arbitrum Sepolia and Solana devnet. Add another USD stablecoin with
211
- `budget.guard(client, { assets: [{ network, asset, decimals }] })`. Anything else is refused,
212
- not guessed.
222
+ `budget.guard(client, { assets: [{ network, asset, decimals }] })`. List only USD-pegged
223
+ stablecoins: each counts at $1 a token. Decimals are an integer from 0 to 18, and a built-in
224
+ asset's decimals can't be changed. Anything else is refused, not guessed.
213
225
  - `@x402/fetch` rewraps errors from payment creation, so a refusal reaches you as an `Error`
214
226
  whose message starts `Failed to create payment payload:` and carries the budget's reason.
215
227
 
@@ -221,7 +233,8 @@ There are two ways to count a CDP payment in the budget; use **one** per client.
221
233
  and reserves in one write transaction. Use it when the budget is the counter.
222
234
  - `applySpendControls(client, { ..., store: budget.cdpStore({ asset: USDC }) })` — keep
223
235
  CDP's controls, and make its count durable and shared. The store re-checks the budget inside
224
- the write transaction, so replicas sharing the file cannot both take the last dollar.
236
+ the write transaction, so replicas on one host sharing the file cannot both take the last
237
+ dollar.
225
238
 
226
239
  `budget.cdpStore()` is walletcap's SQLite ledger behind CDP's `SpendStore` interface — **not**
227
240
  CDP's in-memory default. Replacing that default is the fix, not a second control.
@@ -248,14 +261,18 @@ applySpendControls(client, {
248
261
  it cannot value instead of letting CDP count only the asset named in the cap.
249
262
 
250
263
  walletcap's store re-checks the budget when CDP records a payment, so it holds across replicas
251
- on its own. When CDP removes a payment from its store, the store can't tell why, so the payment
252
- stays counted as in-flight until you check the chain and run `npx walletcap release <id>`. Use
253
- CDP 1.56.0 or later; the store is tested against the published 1.60.0.
264
+ on one host on its own. It records the payment at its own time, not the time in CDP's entry,
265
+ and counts it until an hour (and a minute) after that, plus one window: CDP signs the payment
266
+ after recording it, and lets a payee ask for an authorization it can redeem for up to an hour.
267
+ When CDP removes a payment from its store, the store can't tell why, so the payment stays
268
+ counted as in-flight until you check the chain and run `npx walletcap release <id>`. Use CDP
269
+ 1.60.0 or later: its published source refuses a `maxTimeoutSeconds` over 3600, which the store's
270
+ hour relies on. The store is tested against 1.60.0, and the crash test runs 1.61.0.
254
271
 
255
272
  ### Coinbase Agentic Wallet (awal CLI and MCP server)
256
273
 
257
274
  Run the Agentic Wallet's CLI and MCP server through walletcap, and every payment counts in the
258
- wallet's budget, whichever process, session or machine makes it:
275
+ wallet's budget, whichever process or session on the host makes it:
259
276
 
260
277
  ```console
261
278
  $ npx walletcap set --wallet 0xYourAgentWallet --per-payment 0.05 --per-day 0.15
@@ -281,15 +298,22 @@ command after `--`.
281
298
  left out of the tool list: walletcap can't count it. `--allow-tool <name>` lets one through,
282
299
  uncounted. JSON-RPC batches are refused.
283
300
  - An x402 payment is priced from the endpoint's own 402 answer, and the wallet is capped at exactly
284
- that amount, so it refuses to sign for more.
285
- - A payment the payee confirms as settled counts for one window. One it doesn't confirm keeps
286
- counting until you release it: the wallet signs whatever validity the payee asks for, and
287
- walletcap can't see it. Check the chain, then `npx walletcap release <id>`.
288
- - The wallet's own refusal, before it signs, gives the amount back. Any other failure keeps
289
- counting.
290
- - Only USDC is counted; a send in any other asset is refused.
291
- - Machines share a budget when they share its file (a shared volume). Separate hosts without one
292
- wait for the Postgres backend.
301
+ that amount, so it refuses to sign for more. The wallet is handed, as `paymentRequirements`, the
302
+ terms walletcap can price that are valid an hour or less, from the caller's or the ones
303
+ walletcap discovered; the rest are left out. With terms handed to it, the wallet skips its own
304
+ discovery and signs only a term equal to one of them.
305
+ - With no such terms left, the payment is refused before the wallet is asked. Once the wallet
306
+ answers, the payment counts until the longest `maxTimeoutSeconds` among the terms it was handed
307
+ (a Solana term at least two minutes, the life of its blockhash), plus a minute, after that
308
+ answer, plus one window, whatever the payee says about it.
309
+ - The wallet's own refusal, before it signs, gives the amount back. Any other failure, a send
310
+ included, keeps counting as unknown until you release it: check the chain, then
311
+ `npx walletcap release <id>`. A free endpoint's one-unit hold is given back unless the payee
312
+ confirms a payment.
313
+ - A refusal tells the agent why, not which holds its owner could release: `walletcap holds` and
314
+ `budget.check().message` name them. The x402 guard and the CDP store tell the agent the same.
315
+ - Only USDC is counted; a send in any other asset is refused. Amounts are read exactly: `100.5abc`
316
+ is refused, not read as $100.50.
293
317
  - It binds the payments that go through it. The wallet app takes requests from any process of
294
318
  the same user, so keep the real `awal` out of an agent's reach.
295
319
 
@@ -332,12 +356,17 @@ $ npx walletcap set --per-day 0.20 # what was spent still counts
332
356
  $ npx walletcap freeze # every process, every rail, now
333
357
  $ npx walletcap unfreeze
334
358
  $ npx walletcap history
359
+ $ npx walletcap holds # open payments that still count, and why
335
360
  $ npx walletcap release <id> # an in-flight payment you know never left
361
+ $ npx walletcap release --all-unknown --older-than 24h # every unknown or refused one older than that
336
362
  ```
337
363
 
338
364
  Python ships the same commands as `walletcap`. Amounts are dollars; leave out the `$`
339
365
  sign, which your shell would expand. Add `--wallet` when the file holds more than one budget,
340
- and `--json` for scripts.
366
+ and `--json` for scripts. A refusal names the open payments that take up the room, and
367
+ `budget.holds()` lists them in code. `release --all-unknown` leaves a payment the payee could
368
+ still settle: it counts until one window past the time it can't. A payment with no such time, one
369
+ the wallet may have signed as it failed, stays until it is an hour and a minute old.
341
370
 
342
371
  ## Where the budget lives
343
372
 
@@ -346,10 +375,19 @@ The default file is per user: `~/.local/state/walletcap/budget.sqlite` on Linux,
346
375
  `%LOCALAPPDATA%\walletcap\budget.sqlite` on Windows. Set `WALLETCAP_PATH`, or pass `path`, to put it elsewhere. Both languages
347
376
  compute the same default.
348
377
 
349
- The budget is as durable as that file. In a container, put it on a volume that outlives the
350
- container, or a redeploy starts a new file. Opening a budget does not create one: a missing file
351
- refuses every payment. The owner creates it once with `npx walletcap set`; pass `create: true`
352
- only for a demo or a first-run setup.
378
+ The file serves one host. Keep it on that host's local disk: SQLite's locks aren't reliable over
379
+ NFS, SMB or Docker Desktop bind mounts, so processes that open it through one of those can both
380
+ take the last dollar. Agents on more than one host need a shared service, which walletcap
381
+ doesn't ship yet.
382
+
383
+ The budget is as durable as that file. In a container, put it on a local volume that outlives
384
+ the container, or a redeploy starts a new file. Opening a budget does not create one: a missing
385
+ file refuses every payment. The owner creates it once with `npx walletcap set`; pass
386
+ `create: true` only for a demo or a first-run setup.
387
+
388
+ 0.3 upgrades a 0.2.x file the first time it opens it, and 0.2.x can't open it afterwards, so
389
+ stop every 0.2.x process before upgrading. Budgets that 0.2.x kept under other spellings of one
390
+ wallet become one budget, with the tighter of every limit and every payment.
353
391
 
354
392
  ## What it doesn't do
355
393
 
@@ -357,16 +395,19 @@ only for a demo or a first-run setup.
357
395
  go around it: call the wallet directly, or delete the file. To bound an agent like that, keep
358
396
  the budget out of its reach (another OS user, another service) or enforce on chain, as
359
397
  `AccountCapSpender` does for Spend Permissions.
360
- - **One file is one host.** A shared volume can work for one host's containers, but SQLite
361
- over NFS is not a multi-host database. A Postgres backend for replicas on separate hosts is
362
- next.
398
+ - **One file is one host.** Machines can't share a budget through a shared volume or file:
399
+ SQLite's locks aren't reliable over NFS, SMB or Docker Desktop bind mounts. Multiple hosts need
400
+ a shared service, which isn't shipped yet.
363
401
  - **It can't see a revoke that lands later in the same block,** and for x402 schemes that settle
364
402
  later (batch vouchers), a payment counts from when the server confirms it.
365
403
  - **Some x402 payments can't be confirmed.** `@x402/fetch` doesn't report v1 settlements
366
- back, and only the exact EVM scheme carries an expiry the guard can read. An unconfirmed
367
- payment keeps counting until its authorization expires plus one window, or, with no expiry,
368
- until you `release` it.
369
- - Amounts are micro-dollars and must fit in 64 bits.
404
+ back. An unconfirmed payment keeps counting until one window past the time it can no longer
405
+ settle: the expiry the signed payment carries (an EIP-3009 `validBefore` or a Permit2
406
+ `deadline`), or else the time it was signed plus its terms' `maxTimeoutSeconds`. On the
407
+ Agentic Wallet, a payment the wallet never answered keeps counting until you `release` it.
408
+ - Amounts are micro-dollars. A budget, a limit or one payment is at most $1,000,000,000
409
+ (10^15 micro-dollars), so no sum of payments can overflow.
410
+ - The ledger reads the system clock; there is no option to set it.
370
411
 
371
412
  ## This repository
372
413
 
@@ -377,12 +418,13 @@ only for a demo or a first-run setup.
377
418
  | `solidity/` | `AccountCapSpender`, the on-chain cap for Coinbase Spend Permissions |
378
419
  | `crash-test/` | the crash test: CDP's spend controls and walletcap through the same events, in dollars |
379
420
  | `tests/` | the Python suite, including the tests that drive both languages against one budget file |
421
+ | `spec/vectors/` | the amounts both suites must read the same way, or refuse |
380
422
  | `docs/` | the docs site for GitHub Pages: one page per integration, each with a full snippet, plus the threat model |
381
423
  | `llms.txt` | a summary of the package and links to the docs, for language models |
382
424
 
383
425
  ```console
384
- $ cd js && npm install && node --test # 65 tests
385
- $ uv run --with pytest pytest -q # 59 tests, from the repository root
426
+ $ cd js && npm install && node --test # 109 tests
427
+ $ uv run --with pytest pytest -q # 143 tests, from the repository root
386
428
  $ cd solidity/evm && npm install && node check.mjs .. # the contract on an EVM, no Foundry needed
387
429
  $ cd solidity && forge test # the contract's canonical tests, if you have Foundry
388
430
  ```
@@ -392,7 +434,8 @@ restarts and racing replicas as separate processes, and drives the Agentic Walle
392
434
  MCP proxy against stand-ins for Coinbase's wallet and MCP server. It builds AgentKit's x402
393
435
  client the way AgentKit 0.10.4 does, and type-checks the AgentKit recipe with `tsc` against
394
436
  AgentKit's declared types. The Python suite covers the ledger, the API,
395
- the CLI and one budget shared between both languages. `solidity/evm/check.mjs` compiles the
437
+ the CLI and one budget shared between both languages. Both suites read the amounts in
438
+ `spec/vectors/money.json`, and a Python test checks 15,000 floats against Node. `solidity/evm/check.mjs` compiles the
396
439
  contract with solc-js and drives it on an in-process EVM, covering what the Foundry tests cover.
397
440
 
398
441
  The JavaScript suite also drives the published `@coinbase/cdp-sdk@1.60.0` through the