buoy-wallet 0.0.0-stage → 0.0.1

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 (49) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +160 -2
  3. package/bin/buoy.mjs +408 -0
  4. package/deployments/faststart.xlayer-196.json +15 -0
  5. package/deployments/v2.xlayer-196.json +10 -0
  6. package/deployments/xlayer-196.json +40 -0
  7. package/package.json +83 -6
  8. package/scripts/install-buoy.mjs +144 -0
  9. package/skills/buoy-wallet/SKILL.md +346 -0
  10. package/ts/approve/abi.mjs +336 -0
  11. package/ts/approve/actions.mjs +293 -0
  12. package/ts/approve/assets/GEIST-LICENSE.txt +92 -0
  13. package/ts/approve/assets/Geist-Medium.woff2 +0 -0
  14. package/ts/approve/assets/Geist-Regular.woff2 +0 -0
  15. package/ts/approve/assets/Geist-SemiBold.woff2 +0 -0
  16. package/ts/approve/assets/GeistMono-Regular.woff2 +0 -0
  17. package/ts/approve/errors.mjs +10 -0
  18. package/ts/approve/faststart.mjs +281 -0
  19. package/ts/approve/server.mjs +805 -0
  20. package/ts/approve/setup.mjs +843 -0
  21. package/ts/approve/steps.mjs +62 -0
  22. package/ts/approve/v2.mjs +58 -0
  23. package/ts/mcp/chain.mjs +165 -0
  24. package/ts/mcp/instructions.mjs +69 -0
  25. package/ts/mcp/manifest.mjs +453 -0
  26. package/ts/mcp/payloads.mjs +336 -0
  27. package/ts/mcp/provenance.mjs +148 -0
  28. package/ts/mcp/read.mjs +186 -0
  29. package/ts/mcp/reasons.mjs +161 -0
  30. package/ts/mcp/receipt.mjs +165 -0
  31. package/ts/mcp/server.mjs +469 -0
  32. package/ts/mcp/views.mjs +650 -0
  33. package/ts/mcp/x402.mjs +146 -0
  34. package/ts/okx/signer.mjs +216 -0
  35. package/ts/okx/x402.mjs +99 -0
  36. package/ts/src/policy-binding.mjs +240 -0
  37. package/ts/src/policy-file.mjs +67 -0
  38. package/ts/src/policy-metadata.mjs +117 -0
  39. package/ts/src/policy-word.mjs +186 -0
  40. package/ts/src/tap02.mjs +135 -0
  41. package/ts/src/trace.mjs +78 -0
  42. package/ts/src/xlayer.mjs +71 -0
  43. package/vectors/policies/allowlist.tapnet +0 -0
  44. package/vectors/policies/daily-cap.tapnet +0 -0
  45. package/vectors/policies/deny-all.tapnet +0 -0
  46. package/vectors/policies/pay-or-swap.tapnet +0 -0
  47. package/vectors/policies/per-asset-limits.tapnet +0 -0
  48. package/vectors/policies/swap.tapnet +0 -0
  49. package/vectors/policies/time-window.tapnet +0 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 bshuaibu1
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,161 @@
1
- # Temporary Holding Version
1
+ # Buoy
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **An AI agent's spending account on X Layer, where the limit is enforced by a smart contract
4
+ rather than by the agent's good intentions.**
5
+
6
+ The agent can ask to pay. It cannot move tokens directly, it cannot raise its own limit, and it
7
+ cannot reach the owner's functions. Every decision is made by a [TapeOut](https://tapeout.tech)
8
+ policy circuit whose bytes are fixed and hashed — real silicon on chain — and every refusal comes
9
+ with a receipt anyone can replay offline.
10
+
11
+ There is no dashboard. You talk to your agent; the agent talks to the contract.
12
+
13
+ ```
14
+ Set up Buoy Wallet from https://masterwattson.site/skill.md
15
+ ```
16
+
17
+ Or wire it in yourself, from any folder, with Node 22 or later:
18
+
19
+ ```
20
+ npx -y buoy-wallet@latest install -y
21
+ ```
22
+
23
+ ## Why a shared gatekeeper
24
+
25
+ TAP #84 §0.2.4 states the problem plainly: *"A policy's state belongs to one gatekeeper. A daily
26
+ limit enforced by one escrow-side vault counts the requests that vault saw, not the agent's
27
+ requests everywhere."* §4.2(5) forbids pretending otherwise.
28
+
29
+ So one budget across several accounts is only spec-compliant if **one gatekeeper sees them all**
30
+ — which is what this is. Spend from the vault and the Safe's allowance drops too, because the
31
+ budget was never per-account.
32
+
33
+ ## Nobody here holds a key
34
+
35
+ | Lane | What it can do | Where the key lives |
36
+ |---|---|---|
37
+ | reads | status, balances, agents, verification | nowhere — no key at all |
38
+ | agent payments | ask the vault to pay | OKX Agentic Wallet's TEE |
39
+ | owner actions | first-time setup, add/revoke an agent, change a budget | your own OKX Wallet |
40
+
41
+ The MCP server cannot sign anything: its chain client exposes reads only, and it does not import
42
+ the signing lane. `ts/test/run-okx.mjs` enforces both halves by scanning the source, so breaking
43
+ the property fails the suite rather than quietly widening what a prompt-injected model can reach.
44
+
45
+ Owner actions open a one-card sign-link on loopback — single use, 32-byte nonce, five-minute
46
+ expiry — which signs in your wallet and sends back only a transaction hash.
47
+
48
+ First-time setup is one of those links (`buoy owner setup`): it creates the vault, switches its
49
+ policy on, sets the daily ceiling and lets the first agent spend. It is one link and one tab. How
50
+ many wallet prompts it is depends on the deployment, and the card states the count before you
51
+ press anything. On X Layer mainnet it is **one transaction**: the one-transaction factory builds
52
+ the vault, sets it up and hands it to you inside that transaction, with a handover that works
53
+ exactly once, and keeps no access afterwards. On a deployment without that factory, or with
54
+ `BUOY_V2=none`, it is nine transactions, each an owner-only call on a contract you hold directly
55
+ from the first block. A policy of your own adds one signature either way, and only the wallet
56
+ holding the deployment's subject circuit can sign one; any other is told so before it sends
57
+ anything.
58
+
59
+ Once the deployment's owner has published a shared policy, setup needs no signature at all: one
60
+ transaction (or nine, as above) and gas, with no BEM and no circuit of your own. That is **Fast
61
+ Start**, it is what mainnet offers today, and it comes with two things said on the card before
62
+ you press anything. The policy was signed by the
63
+ deployer, who can revoke it — which stops your vault spending for good, but can never move or
64
+ freeze your funds, since withdrawing is yours alone. And every Fast Start vault shares one expiry
65
+ date. A policy of your own (`--independent`) has neither caveat, and today only the deployment's
66
+ circuit holder can sign one.
67
+
68
+ ## Only the contract may refuse
69
+
70
+ Buoy will tell you a payment looks over budget and then submit it anyway. A refusal computed in
71
+ the agent is a refusal nobody can check; a refusal from the gatekeeper is recorded on chain, and
72
+ `buoy verify <txHash>` re-runs the exact circuit locally and prints **BIT-EXACT MATCH** — for any
73
+ wallet of this deployment, not only your own.
74
+
75
+ A cumulative-cap refusal is *not* circuit-replayable — the 128-bit request word carries no limit
76
+ pin — so it is verified against the chain's own figure and says so, rather than overstating the
77
+ evidence.
78
+
79
+ ## Live on X Layer mainnet
80
+
81
+ Chain 196. Every address below has been read back from the chain; `STATE.md` has the full list
82
+ and what was checked.
83
+
84
+ | | |
85
+ |---|---|
86
+ | One-transaction factory — what a setup is sent to | `0xa8027e391994a82Cda54998fE3FD6F8Fe3903A1B` |
87
+ | Policy adapter | `0x5305A1014B0Bda17D7bb395f7731b0B09ba26128` |
88
+ | Registry | `0xEe98dfD35450e84B2EAB3de56395A481ec20521F` |
89
+ | Processor (TapeOut CPU #439) | `0x2AADaaab1Fc7881374B1Fc20229d8Fb00AeFa581` |
90
+ | Shared Fast Start policy, in force until 2036-11-18 | binding `0xa000b48d1a2a3478e582520c3eacccb481a28eee43da0bc545afe858fe6fbacc`, published in `0x50add1509854d1c11560cbbb24d227f2ff06d2bfe29027164c2993ac46dfc5d0` |
91
+ | Settlement token (USDT0) | `0x779Ded0c9e1022225f8E0630b35a9b54bE713736` |
92
+
93
+ Two receipts, both sent by an agent that holds no OKB and paid no gas, and both replayed offline
94
+ to **BIT-EXACT MATCH** — run `buoy verify` on either to do it yourself:
95
+
96
+ | What | Transaction |
97
+ |---|---|
98
+ | A payment: 0.10 USDT0 from a vault to an allowed payee | `0x11a5a533d93155b067dbed2fcadff2b3787519ab6e53f1e27bdfa38bc8d7359f` |
99
+ | A swap: 0.10 USDT0 into WOKB, which landed in the vault and not with the agent | `0x1b48f06c1ed11c9b5cba0dafd559a17e9dfec7b958221e477cac166e5ee65810` |
100
+
101
+ Two different vaults made them, and both verify from a fresh install with no flags. `buoy verify`
102
+ replays a verdict from any wallet of this deployment and says which one it was: the wallet in
103
+ play, the wallet the launch built, or one this deployment's factory provably created. "Provably"
104
+ is arithmetic, not a registry lookup — the factory's deployer makes each gatekeeper with CREATE,
105
+ so its address can be recomputed from the deployer's address and a counter. A verdict-shaped
106
+ event from any other contract is refused rather than replayed, because any contract can emit
107
+ one.
108
+
109
+ ## Commands
110
+
111
+ ```
112
+ buoy install -y wire the MCP into Claude Code and Cursor
113
+ buoy mcp run the MCP server on stdio (what install registers)
114
+ buoy status is it set up, and what are the budgets called
115
+ buoy balance what it holds, and what is left to spend today
116
+ buoy agents who can spend, by name
117
+ buoy pay --to … --amount …
118
+ buoy swap --in … --out … --amount … --min-out …
119
+ buoy fetch <url> buy a 402-gated URL, drawing the exact price just in time
120
+ buoy verify <txHash> replay the verdict offline
121
+ buoy owner <action> prepare an owner action and open a sign-link
122
+ ```
123
+
124
+ Run any of them without installing: `npx -y buoy-wallet@latest status`.
125
+
126
+ Addresses come from the `deployments/` folder that ships with the package, so the commands work
127
+ from any directory and there is nothing to configure. The one thing Buoy writes on your machine is
128
+ which vault it reads after a setup — addresses only, never a key — in `~/.buoy` (`BUOY_HOME`
129
+ moves it).
130
+
131
+ ## Test
132
+
133
+ The contracts and their suites are in the source tree, not in the npm package. From a checkout:
134
+
135
+ ```
136
+ npm test # Node suites, then 199 Foundry tests
137
+ npm run fork:up # a free local rehearsal of the real launch
138
+ npm run test:on-fork # every suite that needs a chain, plus the red team
139
+ node scripts/mutate.mjs # the Solidity mutation pass: each guard removed once, each killed by a named test
140
+ ```
141
+
142
+ `npm run fork:up` runs `script/Launch.s.sol` — the *same* script the mainnet launch runs, with
143
+ only `--rpc-url` different. A rehearsal that shares no instructions with the real thing rehearses
144
+ nothing.
145
+
146
+ ## Layout
147
+
148
+ Of the source tree. The npm package carries the `ts/` runtime, `bin/`, the mainnet `deployments/`
149
+ files, the policy circuits and the skill.
150
+
151
+ | | |
152
+ |---|---|
153
+ | `src/` | the contracts. Names are historical (`FloatVault`, `FloatGatekeeper`, …) and deliberately unchanged — renaming them would churn the audited surface for nothing |
154
+ | `ts/mcp/` | reads and unsigned payloads. No key, no broadcast |
155
+ | `ts/approve/` | the owner sign-link and its one card |
156
+ | `ts/okx/` | the two steps that need a key, via OKX Agentic Wallet |
157
+ | `bin/buoy.mjs` | the CLI |
158
+ | `skills/buoy-wallet/` | what an agent reads to run all of it |
159
+ | `vectors/` | the official TAP #84 vectors and the five policy circuits |
160
+
161
+ Read `STATE.md` for what is true right now and `DECISIONS.md` for why it is built this way.
package/bin/buoy.mjs ADDED
@@ -0,0 +1,408 @@
1
+ #!/usr/bin/env node
2
+ // SPDX-License-Identifier: MIT
3
+ // The `buoy` command.
4
+ //
5
+ // One entry point for a Buoy wallet on X Layer, with no configuration: every address comes from
6
+ // `deployments/xlayer-196.json` or `deployments/fork.json`, in the folder this code was installed
7
+ // into -- so it runs the same from any directory (see ts/mcp/manifest.mjs).
8
+ //
9
+ // WHICH LANE SIGNS WHAT, because the whole design rests on it:
10
+ //
11
+ // reads no key, no signature, nothing to steal.
12
+ // agent payments handed to `onchainos wallet contract-call`. The agent's key lives in OKX
13
+ // Agentic Wallet's TEE, so it exists nowhere on this machine and Buoy never
14
+ // holds one. That is why this file may import ts/okx and ts/mcp/server.mjs
15
+ // may not -- an MCP server reachable by a prompt-injected model must not be
16
+ // able to sign, and ts/mcp/ has no sendRawTransaction at all.
17
+ // owner actions never here. `buoy owner ...` prepares the unsigned transaction and opens a
18
+ // one-card sign-link the human approves in their own OKX Wallet (TAP #84
19
+ // §5.1: a runtime fed text by other parties MUST NOT sign a binding).
20
+ //
21
+ // ONLY THE CONTRACT MAY REFUSE. `buoy pay` will tell you a payment looks over budget and then
22
+ // submit it anyway, because a refusal computed here is a refusal nobody can check, while the
23
+ // gatekeeper's refusal is recorded on chain with a receipt `buoy verify` can replay.
24
+
25
+ import { resolveManifest, describe, ManifestError, isCheckout } from "../ts/mcp/manifest.mjs";
26
+ import { makeClient } from "../ts/mcp/chain.mjs";
27
+ import { makeReader, units } from "../ts/mcp/read.mjs";
28
+ import {
29
+ statusView, balanceView, agentsView, planPayment, planSwap, planFetch, verifyTransaction, knownNames,
30
+ } from "../ts/mcp/views.mjs";
31
+ import { fetchPaid } from "../ts/mcp/x402.mjs";
32
+
33
+ const C = "\x1b[";
34
+ const b = (s) => `${C}1m${s}${C}0m`;
35
+ const dim = (s) => `${C}2m${s}${C}0m`;
36
+ const green = (s) => `${C}32m${s}${C}0m`;
37
+ const red = (s) => `${C}31m${s}${C}0m`;
38
+ const yellow = (s) => `${C}33m${s}${C}0m`;
39
+
40
+ const argv = process.argv.slice(2);
41
+ const cmd = (argv[0] ?? "help").replace(/^--?/, "");
42
+ const flag = (n, d) => {
43
+ const i = argv.indexOf("--" + n);
44
+ return i < 0 || i + 1 >= argv.length ? d : argv[i + 1];
45
+ };
46
+ const has = (n) => argv.includes("--" + n) || argv.includes("-" + n[0]);
47
+ const JSON_OUT = has("json");
48
+
49
+ const out = (human, data) => {
50
+ if (JSON_OUT) console.log(JSON.stringify(data, null, 2));
51
+ else console.log(human);
52
+ };
53
+
54
+ function connect() {
55
+ const m = resolveManifest();
56
+ const chain = makeClient({ url: m.rpc });
57
+ return { m, chain, r: makeReader(chain, m) };
58
+ }
59
+
60
+ const HELP = `
61
+ ${b("buoy")} — an AI agent's spending account on X Layer
62
+
63
+ ${b("buoy status")} is the wallet set up, and what is it allowed to do
64
+ ${b("buoy balance")} [--token 0x..] what it holds, and what is left to spend today
65
+ ${b("buoy agents")} who can spend, by name
66
+ ${b("buoy pay")} --to 0x.. --amount N pay, from --from <name> (default: vault)
67
+ ${b("buoy swap")} --in 0x.. --out 0x.. --amount N --min-out N
68
+ ${b("buoy verify")} <txHash> replay the verdict offline -> ${b("BIT-EXACT MATCH")}
69
+ ${b("buoy fetch")} <url> buy a 402-gated URL, drawing the exact price just in time
70
+ ${b("buoy owner")} <action> prepare an owner action and open a sign-link
71
+ ${b("buoy install")} [-y] wire the MCP into Claude Code and Cursor
72
+ ${b("buoy mcp")} run the MCP server on stdio (what ${b("install")} registers)
73
+
74
+ ${dim("Common flags: --json machine-readable --yes actually broadcast a payment")}
75
+
76
+ ${dim("Addresses ship with the tool. Nothing to configure, no keys held: the agent signs")}
77
+ ${dim("in OKX Agentic Wallet's TEE, and you sign owner actions in your own OKX Wallet.")}
78
+ `;
79
+
80
+ // ------------------------------------------------------------------ commands
81
+
82
+ async function cmdStatus() {
83
+ const { m, r } = connect();
84
+ const s = await statusView(r);
85
+ if (JSON_OUT) return out(null, s);
86
+
87
+ console.log(`\n${b("Buoy")} — ${s.where}`);
88
+ if (s.isRehearsal) console.log(yellow(" a local rehearsal: these addresses do not exist on X Layer"));
89
+ console.log(` wallet ${dim(s.wallet)}`);
90
+ console.log(` owner ${dim(s.owner)}`);
91
+ console.log(` active ${s.active ? green("yes") : yellow("not yet — the owner must install the policy")}`);
92
+ if (s.policy) {
93
+ console.log(` policy ${s.policy.sharedBinder ? yellow("Buoy's shared Fast Start policy") : "signed by the owner"}${s.policy.revoked ? yellow(" REVOKED") : ""}`);
94
+ if (s.policy.sharedBinder) console.log(` signer ${dim(s.policy.signedBy)}`);
95
+ console.log(` expires ${s.policy.expiresOn}`);
96
+ }
97
+ if (s.named.length) {
98
+ console.log(`\n ${b("budgets")}`);
99
+ for (const n of s.named) {
100
+ const left = n.uncapped ? dim("no cap of its own") : `${n.remainingUnits} left today`;
101
+ console.log(` ${n.name.padEnd(20)} ${left}`);
102
+ }
103
+ }
104
+ if (s.policies.length) console.log(`\n ${b("circuits")} ${dim(s.policies.join(", "))}`);
105
+ console.log(`\n${s.say}\n`);
106
+ }
107
+
108
+ async function cmdBalance() {
109
+ const { r } = connect();
110
+ const v = await balanceView(r, { token: flag("token") });
111
+ if (JSON_OUT) return out(null, v);
112
+ console.log(`\n${b("Buoy")} — ${v.token.symbol} ${dim(v.token.address)}\n`);
113
+ for (const a of v.accounts) {
114
+ console.log(` ${(a.name ?? a.via).padEnd(20)} ${a.balance.padStart(16)} ${dim(a.remainingTodayUnits + " left today")}`);
115
+ }
116
+ console.log(`\n${v.say}\n`);
117
+ }
118
+
119
+ async function cmdAgents() {
120
+ const { r } = connect();
121
+ const v = await agentsView(r);
122
+ if (JSON_OUT) return out(null, v);
123
+ console.log(`\n${b("Buoy")} — who can spend\n`);
124
+ for (const a of v.agents) {
125
+ console.log(` ${a.name.padEnd(20)} ${dim(a.address)} ${a.canSpendFrom.join(", ") || red("bound to nothing")}`);
126
+ }
127
+ if (v.unnamedFromManifest) {
128
+ console.log(`\n ${yellow("unnamed")} ${dim(v.unnamedFromManifest)} is an agent on chain with no name yet`);
129
+ }
130
+ console.log(`\n${v.say}\n`);
131
+ }
132
+
133
+ async function cmdPay() {
134
+ const { m, r } = connect();
135
+ const plan = await planPayment(r, {
136
+ to: flag("to"),
137
+ amount: flag("amount"),
138
+ token: flag("token"),
139
+ from: flag("from"),
140
+ });
141
+
142
+ if (JSON_OUT && !has("yes")) return out(null, plan);
143
+ if (!JSON_OUT) {
144
+ console.log(`\n${b("Buoy")} — payment`);
145
+ console.log(` from ${plan.from.name ?? plan.from.via}`);
146
+ console.log(` to ${dim(plan.to)}`);
147
+ console.log(` amount ${plan.amountHuman}`);
148
+ console.log(`\n ${plan.expectation}\n`);
149
+ }
150
+
151
+ if (!has("yes")) {
152
+ console.log(dim(` Not sent. Add --yes to broadcast via onchainos.\n`));
153
+ if (!JSON_OUT) console.log(dim(` calldata: ${plan.submit.to} ${plan.submit.data.slice(0, 26)}…\n`));
154
+ return;
155
+ }
156
+
157
+ /* The signing lane. Imported HERE, inside the one command that broadcasts, so that reading
158
+ this file makes it obvious which commands can move money and which cannot. */
159
+ const okx = await import("../ts/okx/signer.mjs");
160
+ const run = okx.cliRunner();
161
+ const presentation = okx.present({ run, submit: plan.submit, chain: String(m.chainId) });
162
+ if (!presentation.confirming) {
163
+ console.error(red(`\n onchainos would not confirm this call.`));
164
+ console.error(dim(` ${(presentation.raw.stderr || presentation.raw.stdout || "").trim().slice(0, 400)}\n`));
165
+ process.exitCode = 1;
166
+ return;
167
+ }
168
+ const res = okx.confirm({ run, presentation, confirmed: true });
169
+ if (!res.broadcast) {
170
+ console.error(red(`\n the broadcast failed.`));
171
+ console.error(dim(` ${(res.raw.stderr || res.raw.stdout || "").trim().slice(0, 400)}\n`));
172
+ process.exitCode = 1;
173
+ return;
174
+ }
175
+ console.log(green(` sent: ${res.txHash}`));
176
+ console.log(dim(` verify it with: buoy verify ${res.txHash}\n`));
177
+ if (JSON_OUT) out(null, { ...plan, txHash: res.txHash });
178
+ }
179
+
180
+ async function cmdSwap() {
181
+ const { m, r } = connect();
182
+ const plan = await planSwap(r, {
183
+ router: flag("router", m.raw.router),
184
+ tokenIn: flag("in"),
185
+ tokenOut: flag("out"),
186
+ fee: Number(flag("fee", "500")),
187
+ amountIn: flag("amount"),
188
+ minAmountOut: flag("min-out"),
189
+ from: flag("from"),
190
+ });
191
+ if (JSON_OUT) return out(null, plan);
192
+ console.log(`\n${b("Buoy")} — swap\n ${plan.say}\n`);
193
+ console.log(dim(` ${plan.howToSend}\n`));
194
+ }
195
+
196
+ async function cmdVerify() {
197
+ const txHash = argv[1];
198
+ if (!txHash) {
199
+ console.error("Pass a transaction hash: buoy verify 0x…");
200
+ process.exitCode = 1;
201
+ return;
202
+ }
203
+ const { chain, r } = connect();
204
+ const v = await verifyTransaction(chain, r, txHash);
205
+ if (JSON_OUT) return out(null, v);
206
+
207
+ console.log(`\n${b("Buoy")} — verifying ${dim(txHash)}\n`);
208
+ if (!v.found) {
209
+ console.log(` ${yellow(v.say)}\n`);
210
+ process.exitCode = 1;
211
+ return;
212
+ }
213
+ console.log(` verdict ${v.verdict.allow ? green("allowed") : red("refused")} ${dim("reason " + v.verdict.reason)}`);
214
+ console.log(` circuit ${v.policy ?? dim("not available locally")} ${dim(v.netlistHash)}`);
215
+ // Only when it is NOT the wallet in play: a match on somebody else's receipt must not read as yours.
216
+ if (v.wallet && v.wallet !== "this-wallet") {
217
+ const which = v.wallet === "launch-wallet" ? "this deployment's launch wallet" : "another wallet this deployment's factory made";
218
+ console.log(` wallet ${v.gatekeeper} ${dim(which + ", not the one in play")}`);
219
+ }
220
+ for (const c of v.checks ?? []) console.log(` ${dim("· " + c)}`);
221
+ console.log("");
222
+ if (v.match) console.log(` ${green(b(v.match))}`);
223
+ else if (v.verified) console.log(` ${yellow("confirmed, but by the cumulative cap — no circuit to match")}`);
224
+ else console.log(` ${red("NOT VERIFIED")}`);
225
+ console.log(`\n${v.say}\n`);
226
+ if (!v.verified) process.exitCode = 1;
227
+ }
228
+
229
+ async function cmdFetch() {
230
+ const url = argv[1];
231
+ if (!url || url.startsWith("--")) {
232
+ console.error("Pass the paid URL: buoy fetch https://api.example/thing");
233
+ process.exitCode = 1;
234
+ return;
235
+ }
236
+ const { m, chain, r } = connect();
237
+ const plan = await planFetch(r, {
238
+ url,
239
+ from: flag("from"),
240
+ agentWallet: flag("agent-wallet"),
241
+ maxAmountBaseUnits: flag("max"),
242
+ });
243
+
244
+ if (!plan.needsPayment) {
245
+ if (JSON_OUT) return out(null, plan);
246
+ console.log(`\n${b("Buoy")} — ${plan.say}\n`);
247
+ console.log(plan.body?.slice(0, 2000) ?? "");
248
+ return;
249
+ }
250
+
251
+ if (!JSON_OUT) {
252
+ console.log(`\n${b("Buoy")} — ${url}`);
253
+ console.log(` price ${plan.draw.amountHuman} ${dim("to " + plan.offer.payTo)}`);
254
+ console.log(` draw from ${plan.draw.from.name ?? plan.draw.from.via} into ${dim(plan.agentWallet)}`);
255
+ console.log(`\n ${plan.draw.expectation}\n`);
256
+ }
257
+
258
+ if (!has("yes")) {
259
+ if (JSON_OUT) return out(null, plan);
260
+ console.log(dim(" Nothing drawn. Add --yes to run the loop.\n"));
261
+ return;
262
+ }
263
+
264
+ // ---- the two lanes that need a key, imported here so the file says which command spends ----
265
+ const signer = await import("../ts/okx/signer.mjs");
266
+ const x402 = await import("../ts/okx/x402.mjs");
267
+ const run = x402.cliRunner();
268
+
269
+ /* A second opinion from the tool that will sign, BEFORE any money moves. A disagreement here
270
+ between what Buoy read and what OKX reads is worth knowing now rather than as a failed
271
+ settlement after the vault has already paid out. Non-fatal: the draw is still gated by the
272
+ contract, which is the thing that actually decides. */
273
+ const q = x402.quote({ run, url });
274
+ if (!JSON_OUT) {
275
+ console.log(q.ok ? dim(` onchainos agrees this is payable${q.paymentId ? " (" + q.paymentId + ")" : ""}`)
276
+ : yellow(` onchainos could not quote it: ${(q.raw.stderr || "").trim().slice(0, 160)}`));
277
+ }
278
+
279
+ // ---- 1. draw exactly the invoice out of the vault ----
280
+ const presentation = signer.present({ run, submit: plan.draw.submit, chain: String(m.chainId) });
281
+ if (!presentation.confirming) {
282
+ console.error(red(`\n the draw was not confirmed by onchainos.`));
283
+ console.error(dim(` ${(presentation.raw.stderr || presentation.raw.stdout || "").trim().slice(0, 400)}\n`));
284
+ process.exitCode = 1;
285
+ return;
286
+ }
287
+ const sent = signer.confirm({ run, presentation, confirmed: true });
288
+ if (!sent.broadcast || !sent.txHash) {
289
+ console.error(red(`\n the draw failed to broadcast.`));
290
+ console.error(dim(` ${(sent.raw.stderr || sent.raw.stdout || "").trim().slice(0, 400)}\n`));
291
+ process.exitCode = 1;
292
+ return;
293
+ }
294
+ console.log(` drew ${dim(sent.txHash)}`);
295
+
296
+ // ---- 2. let the contract's verdict decide what happens next ----
297
+ const v = await verifyTransaction(chain, r, sent.txHash);
298
+ if (!v.found || !v.verdict.allow) {
299
+ console.log(`\n ${red("REFUSED")} — the vault would not release it. ${green("$0.00 moved.")}`);
300
+ if (v.match) console.log(` ${green(b(v.match))} ${dim("the refusal replays offline against " + v.policy)}`);
301
+ else if (v.verified) console.log(` ${yellow("confirmed by the cumulative cap")}`);
302
+ console.log(`\n${v.say}\n`);
303
+ if (JSON_OUT) out(null, { ...plan, txHash: sent.txHash, verdict: v, paid: false });
304
+ process.exitCode = 1;
305
+ return;
306
+ }
307
+ console.log(` verdict ${green("allowed")}${v.match ? " " + green(v.match) : ""}`);
308
+
309
+ // ---- 3. only now sign the payment header, and spend what was drawn ----
310
+ const signed = x402.signPayment({ run, challenge: plan.challenge, approve: true });
311
+ if (!signed.ok) {
312
+ console.error(red(`\n the draw succeeded but the payment header could not be signed.`));
313
+ console.error(dim(` The agent wallet is holding ${plan.draw.amountHuman}; it is NOT lost, but it is\n` +
314
+ ` no longer $0.00. ${(signed.raw.stderr || "").trim().slice(0, 240)}\n`));
315
+ process.exitCode = 1;
316
+ return;
317
+ }
318
+
319
+ const paid = await fetchPaid(url, signed.header);
320
+ console.log(` paid ${paid.ok ? green("HTTP " + paid.status) : red("HTTP " + paid.status)}\n`);
321
+ if (JSON_OUT) return out(null, { ...plan, txHash: sent.txHash, verdict: v, paid: true, response: paid.json ?? paid.body });
322
+ console.log((paid.body ?? "").slice(0, 2000));
323
+ console.log(`\n ${dim("receipt trail: draw " + sent.txHash + " · verify with: buoy verify " + sent.txHash)}\n`);
324
+ }
325
+
326
+ async function cmdOwner() {
327
+ const { startSignLink } = await import("../ts/approve/server.mjs");
328
+ await startSignLink({ argv, connect, print: console.log });
329
+ }
330
+
331
+ async function cmdInstall() {
332
+ const { install } = await import("../scripts/install-buoy.mjs");
333
+ await install({ yes: has("yes") || has("y"), target: flag("target", "all"), print: console.log });
334
+ }
335
+
336
+ /**
337
+ * Deliberately absent from `buoy help`: this is a DEVELOPER test, not a product feature.
338
+ *
339
+ * It mutates the fork and reverts it, which is fine for a suite and wrong for a demo. The live
340
+ * demonstration is the agent being asked, in plain words, to do something it is not allowed to
341
+ * do -- and the contract refusing in front of the audience. A canned script that prints three
342
+ * green ticks proves far less than that, because nobody watching can tell what it really ran.
343
+ */
344
+ async function cmdRedteam() {
345
+ // It drives a fork, so it is only in a source checkout: the published package does not carry it.
346
+ if (!isCheckout()) {
347
+ console.error("buoy redteam is a developer test and runs from a source checkout only.");
348
+ process.exitCode = 1;
349
+ return;
350
+ }
351
+ const { redteam } = await import("../scripts/redteam-demo.mjs");
352
+ await redteam({ json: JSON_OUT, only: flag("only"), print: console.log });
353
+ }
354
+
355
+ /**
356
+ * The MCP server, on stdio. This is the command an agent's config runs when Buoy was installed
357
+ * from npm (`npx -y <package> mcp`), where there is no stable path to ts/mcp/server.mjs to name.
358
+ *
359
+ * Nothing may reach stdout before the server owns it -- stdout IS the protocol here -- so this
360
+ * prints nothing. The signing lane stays out of this process: ts/okx is imported only inside
361
+ * `pay` and `fetch`, and a process runs one command.
362
+ */
363
+ async function cmdMcp() {
364
+ const { start } = await import("../ts/mcp/server.mjs");
365
+ await start();
366
+ }
367
+
368
+ // ------------------------------------------------------------------
369
+
370
+ const COMMANDS = {
371
+ status: cmdStatus,
372
+ balance: cmdBalance,
373
+ agents: cmdAgents,
374
+ pay: cmdPay,
375
+ swap: cmdSwap,
376
+ verify: cmdVerify,
377
+ fetch: cmdFetch,
378
+ owner: cmdOwner,
379
+ install: cmdInstall,
380
+ mcp: cmdMcp,
381
+ redteam: cmdRedteam,
382
+ help: async () => console.log(HELP),
383
+ };
384
+
385
+ const fn = COMMANDS[cmd];
386
+ if (!fn) {
387
+ console.error(`buoy: unknown command "${cmd}"`);
388
+ console.error(HELP);
389
+ process.exit(1);
390
+ }
391
+
392
+ try {
393
+ await fn();
394
+ } catch (e) {
395
+ /* A missing manifest is the ONE error a new user is most likely to hit, and "no-manifest" on
396
+ its own tells them nothing. Every other failure keeps its code, because a code is what makes
397
+ a bug report actionable. */
398
+ if (e instanceof ManifestError) {
399
+ console.error(`\n${red("buoy: no deployment found")}\n`);
400
+ console.error(` ${e.message}\n`);
401
+ // A rehearsal needs the contracts' sources, which only a checkout has.
402
+ if (isCheckout()) console.error(dim(` For a free local rehearsal: npm run fork:up\n`));
403
+ process.exit(1);
404
+ }
405
+ console.error(`\n${red("buoy: " + (e.code ?? "failed"))}`);
406
+ console.error(` ${e.message}\n`);
407
+ process.exit(1);
408
+ }
@@ -0,0 +1,15 @@
1
+ {
2
+ "note": "The shared Fast Start policy for this deployment: where it was first installed. Nothing here is trusted as written -- the tools re-read the transaction and check it before issuing a link.",
3
+ "target": "mainnet",
4
+ "factory": "0xfA1D7E8DA93E3F0A6582EEf5AC6bbb8ea1c70083",
5
+ "adapter": "0x5305A1014B0Bda17D7bb395f7731b0B09ba26128",
6
+ "bindingTx": "0x50add1509854d1c11560cbbb24d227f2ff06d2bfe29027164c2993ac46dfc5d0",
7
+ "gatekeeper": "0xcd4ca5bf518de7b5976569721cb395b704afb755",
8
+ "bindingHash": "0xa000b48d1a2a3478e582520c3eacccb481a28eee43da0bc545afe858fe6fbacc",
9
+ "policy": "pay-or-swap",
10
+ "netlistHash": "0xc5c6b36c9b8b0be1abba300735faa46d50c3219fc10d2f0680cb373d1fd970db",
11
+ "canonicalTables": "{\"assets\":{\"0x779ded0c9e1022225f8e0630b35a9b54be713736\":{\"class\":1,\"unit\":\"1000000\"}},\"counterparties\":{}}",
12
+ "notBefore": 1795290217,
13
+ "expires": 2110650277,
14
+ "binder": "0xf72890bd9f905126d69d0a91de2ff7f340649561"
15
+ }
@@ -0,0 +1,10 @@
1
+ {
2
+ "note": "The one-transaction factory for this deployment. Nothing here is trusted as written: the tools read the factory back from the chain and check its wiring before issuing a link.",
3
+ "target": "mainnet",
4
+ "chainId": 196,
5
+ "adapter": "0x5305A1014B0Bda17D7bb395f7731b0B09ba26128",
6
+ "registry": "0xEe98dfD35450e84B2EAB3de56395A481ec20521F",
7
+ "factory": "0xa8027e391994a82Cda54998fE3FD6F8Fe3903A1B",
8
+ "gatekeeperDeployer": "0x08fC883B3A8247b71956B605099ce23Db48F1184",
9
+ "vaultDeployer": "0x882D078E2b1546FAA2740329F8a34D624FB469c2"
10
+ }
@@ -0,0 +1,40 @@
1
+ {
2
+ "target": "mainnet",
3
+ "chainId": 196,
4
+ "processorMode": "own",
5
+ "processor": "0x2AADaaab1Fc7881374B1Fc20229d8Fb00AeFa581",
6
+ "cpuNumber": 439,
7
+ "transistors": "0x6B48c68457976550560590B5a0417694913B080a",
8
+ "adapter": "0x5305A1014B0Bda17D7bb395f7731b0B09ba26128",
9
+ "gatekeeper": "0xC2A940F51C01e08d2d1434AB53BcC615B1E2e8CF",
10
+ "vault": "0x6Ae76F13Dfc34F9B5411CF8Bde3D522d59F5fE2A",
11
+ "safeModule": "0x5DC448b90e48EF96860Ea4b569A45F53d0a38301",
12
+ "safe": "0x006a6374A9fC69C35e7c19C9209B9dd08FABa7aF",
13
+ "usdt": "0x779Ded0c9e1022225f8E0630b35a9b54bE713736",
14
+ "merchant": "0xf72890BD9F905126d69d0A91De2fF7f340649561",
15
+ "agent": "0x147eb0A62ccdd007F60390d00ECE3db26881110e",
16
+ "owner": "0xf72890BD9F905126d69d0A91De2fF7f340649561",
17
+ "container": "0x7FE70Ba740b2d91EDf1CB7976aC7B842F969B1E2",
18
+ "onchainName": "8.2.439.tape",
19
+ "gatewayHost": "8-2-439",
20
+ "policyHash": "0xdcb5b163ce32adc5b1406678c519cafc467e3f65e18b6e088b2cf26895d52d5b",
21
+ "policyCircuitId": 1,
22
+ "subjectCircuitId": 8,
23
+ "factory": "0xfA1D7E8DA93E3F0A6582EEf5AC6bbb8ea1c70083",
24
+ "registry": "0xEe98dfD35450e84B2EAB3de56395A481ec20521F",
25
+ "gatekeeperDeployer": "0x0022ca474BD21B3eb8DF8b1387aA465e52b8e294",
26
+ "vaultDeployer": "0xf1941be8c6EfF418BB9936E6Fb702012CfEaf723",
27
+ "dept": 2,
28
+ "leafVault": 3,
29
+ "leafSafe": 4,
30
+ "policies": {
31
+ "allowlist": { "circuitId": 1, "netlistHash": "0xdcb5b163ce32adc5b1406678c519cafc467e3f65e18b6e088b2cf26895d52d5b" },
32
+ "daily-cap": { "circuitId": 2, "netlistHash": "0x5e2d00e35e7e9a7a521027164a037fead6bbed69ef1ef5816c1b9de07f6cd8c6" },
33
+ "deny-all": { "circuitId": 3, "netlistHash": "0x22116d7a5915a752d3abb233c0953a6764587339ad9413b52c9f13bd38226a4f" },
34
+ "per-asset-limits": { "circuitId": 4, "netlistHash": "0xbeaaae92f275309fc22b0039def38930995104444f9f2ca8cfbf5855a61a3443" },
35
+ "time-window": { "circuitId": 5, "netlistHash": "0x6bec5ba3f1a293a79a8b66030ec03d69c812b24081b950907179a4a7dbbb6989" },
36
+ "pay-or-swap": { "circuitId": 6, "netlistHash": "0xc5c6b36c9b8b0be1abba300735faa46d50c3219fc10d2f0680cb373d1fd970db" },
37
+ "swap": { "circuitId": 7, "netlistHash": "0x4613b89cf7a4125f5fbf814df611242d5898b26d40921f9c8e5c3457c1136b21" }
38
+ },
39
+ "canonicalTables": "{\"assets\":{\"0x779ded0c9e1022225f8e0630b35a9b54be713736\":{\"class\":1,\"unit\":\"1000000\"}},\"counterparties\":{\"0x147eb0a62ccdd007f60390d00ece3db26881110e\":1,\"0xf72890bd9f905126d69d0a91de2ff7f340649561\":1}}"
40
+ }