openclaw-overlay-plugin 0.7.22

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 (221) hide show
  1. package/README.md +406 -0
  2. package/SKILL.md +78 -0
  3. package/clawdbot.plugin.json +106 -0
  4. package/dist/cli-main.d.ts +7 -0
  5. package/dist/cli-main.js +192 -0
  6. package/dist/cli.d.ts +8 -0
  7. package/dist/cli.js +14 -0
  8. package/dist/core/config.d.ts +11 -0
  9. package/dist/core/config.js +13 -0
  10. package/dist/core/index.d.ts +25 -0
  11. package/dist/core/index.js +26 -0
  12. package/dist/core/payment.d.ts +16 -0
  13. package/dist/core/payment.js +94 -0
  14. package/dist/core/types.d.ts +94 -0
  15. package/dist/core/types.js +4 -0
  16. package/dist/core/verify.d.ts +28 -0
  17. package/dist/core/verify.js +104 -0
  18. package/dist/core/wallet.d.ts +99 -0
  19. package/dist/core/wallet.js +219 -0
  20. package/dist/scripts/baemail/commands.d.ts +64 -0
  21. package/dist/scripts/baemail/commands.js +258 -0
  22. package/dist/scripts/baemail/handler.d.ts +36 -0
  23. package/dist/scripts/baemail/handler.js +284 -0
  24. package/dist/scripts/baemail/index.d.ts +5 -0
  25. package/dist/scripts/baemail/index.js +5 -0
  26. package/dist/scripts/config.d.ts +48 -0
  27. package/dist/scripts/config.js +68 -0
  28. package/dist/scripts/index.d.ts +7 -0
  29. package/dist/scripts/index.js +7 -0
  30. package/dist/scripts/messaging/connect.d.ts +8 -0
  31. package/dist/scripts/messaging/connect.js +114 -0
  32. package/dist/scripts/messaging/handlers.d.ts +21 -0
  33. package/dist/scripts/messaging/handlers.js +334 -0
  34. package/dist/scripts/messaging/inbox.d.ts +11 -0
  35. package/dist/scripts/messaging/inbox.js +51 -0
  36. package/dist/scripts/messaging/index.d.ts +8 -0
  37. package/dist/scripts/messaging/index.js +8 -0
  38. package/dist/scripts/messaging/poll.d.ts +7 -0
  39. package/dist/scripts/messaging/poll.js +52 -0
  40. package/dist/scripts/messaging/send.d.ts +7 -0
  41. package/dist/scripts/messaging/send.js +43 -0
  42. package/dist/scripts/output.d.ts +12 -0
  43. package/dist/scripts/output.js +19 -0
  44. package/dist/scripts/overlay/discover.d.ts +7 -0
  45. package/dist/scripts/overlay/discover.js +72 -0
  46. package/dist/scripts/overlay/index.d.ts +7 -0
  47. package/dist/scripts/overlay/index.js +7 -0
  48. package/dist/scripts/overlay/registration.d.ts +19 -0
  49. package/dist/scripts/overlay/registration.js +176 -0
  50. package/dist/scripts/overlay/services.d.ts +29 -0
  51. package/dist/scripts/overlay/services.js +167 -0
  52. package/dist/scripts/overlay/transaction.d.ts +42 -0
  53. package/dist/scripts/overlay/transaction.js +103 -0
  54. package/dist/scripts/payment/build.d.ts +24 -0
  55. package/dist/scripts/payment/build.js +54 -0
  56. package/dist/scripts/payment/commands.d.ts +15 -0
  57. package/dist/scripts/payment/commands.js +73 -0
  58. package/dist/scripts/payment/index.d.ts +6 -0
  59. package/dist/scripts/payment/index.js +6 -0
  60. package/dist/scripts/payment/types.d.ts +56 -0
  61. package/dist/scripts/payment/types.js +4 -0
  62. package/dist/scripts/services/index.d.ts +6 -0
  63. package/dist/scripts/services/index.js +6 -0
  64. package/dist/scripts/services/queue.d.ts +11 -0
  65. package/dist/scripts/services/queue.js +28 -0
  66. package/dist/scripts/services/request.d.ts +7 -0
  67. package/dist/scripts/services/request.js +82 -0
  68. package/dist/scripts/services/respond.d.ts +11 -0
  69. package/dist/scripts/services/respond.js +132 -0
  70. package/dist/scripts/types.d.ts +107 -0
  71. package/dist/scripts/types.js +4 -0
  72. package/dist/scripts/utils/index.d.ts +6 -0
  73. package/dist/scripts/utils/index.js +6 -0
  74. package/dist/scripts/utils/merkle.d.ts +12 -0
  75. package/dist/scripts/utils/merkle.js +47 -0
  76. package/dist/scripts/utils/storage.d.ts +66 -0
  77. package/dist/scripts/utils/storage.js +211 -0
  78. package/dist/scripts/utils/woc.d.ts +26 -0
  79. package/dist/scripts/utils/woc.js +91 -0
  80. package/dist/scripts/wallet/balance.d.ts +22 -0
  81. package/dist/scripts/wallet/balance.js +240 -0
  82. package/dist/scripts/wallet/identity.d.ts +70 -0
  83. package/dist/scripts/wallet/identity.js +151 -0
  84. package/dist/scripts/wallet/index.d.ts +6 -0
  85. package/dist/scripts/wallet/index.js +6 -0
  86. package/dist/scripts/wallet/setup.d.ts +15 -0
  87. package/dist/scripts/wallet/setup.js +105 -0
  88. package/dist/scripts/x-verification/commands.d.ts +27 -0
  89. package/dist/scripts/x-verification/commands.js +222 -0
  90. package/dist/scripts/x-verification/index.d.ts +4 -0
  91. package/dist/scripts/x-verification/index.js +4 -0
  92. package/dist/services/built-in/api-proxy/index.d.ts +6 -0
  93. package/dist/services/built-in/api-proxy/index.js +23 -0
  94. package/dist/services/built-in/code-develop/index.d.ts +6 -0
  95. package/dist/services/built-in/code-develop/index.js +23 -0
  96. package/dist/services/built-in/code-review/index.d.ts +10 -0
  97. package/dist/services/built-in/code-review/index.js +51 -0
  98. package/dist/services/built-in/image-analysis/index.d.ts +6 -0
  99. package/dist/services/built-in/image-analysis/index.js +33 -0
  100. package/dist/services/built-in/memory-store/index.d.ts +6 -0
  101. package/dist/services/built-in/memory-store/index.js +22 -0
  102. package/dist/services/built-in/roulette/index.d.ts +6 -0
  103. package/dist/services/built-in/roulette/index.js +27 -0
  104. package/dist/services/built-in/summarize/index.d.ts +6 -0
  105. package/dist/services/built-in/summarize/index.js +21 -0
  106. package/dist/services/built-in/tell-joke/handler.d.ts +7 -0
  107. package/dist/services/built-in/tell-joke/handler.js +122 -0
  108. package/dist/services/built-in/tell-joke/index.d.ts +9 -0
  109. package/dist/services/built-in/tell-joke/index.js +31 -0
  110. package/dist/services/built-in/translate/index.d.ts +6 -0
  111. package/dist/services/built-in/translate/index.js +21 -0
  112. package/dist/services/built-in/web-research/index.d.ts +9 -0
  113. package/dist/services/built-in/web-research/index.js +51 -0
  114. package/dist/services/index.d.ts +13 -0
  115. package/dist/services/index.js +14 -0
  116. package/dist/services/loader.d.ts +77 -0
  117. package/dist/services/loader.js +292 -0
  118. package/dist/services/manager.d.ts +86 -0
  119. package/dist/services/manager.js +255 -0
  120. package/dist/services/registry.d.ts +98 -0
  121. package/dist/services/registry.js +204 -0
  122. package/dist/services/types.d.ts +230 -0
  123. package/dist/services/types.js +30 -0
  124. package/dist/test/cli.test.d.ts +7 -0
  125. package/dist/test/cli.test.js +329 -0
  126. package/dist/test/comprehensive-overlay.test.d.ts +13 -0
  127. package/dist/test/comprehensive-overlay.test.js +593 -0
  128. package/dist/test/key-derivation.test.d.ts +12 -0
  129. package/dist/test/key-derivation.test.js +86 -0
  130. package/dist/test/overlay-submit.test.d.ts +10 -0
  131. package/dist/test/overlay-submit.test.js +460 -0
  132. package/dist/test/request-response-flow.test.d.ts +5 -0
  133. package/dist/test/request-response-flow.test.js +209 -0
  134. package/dist/test/service-system.test.d.ts +5 -0
  135. package/dist/test/service-system.test.js +190 -0
  136. package/dist/test/utils/server-logic.d.ts +98 -0
  137. package/dist/test/utils/server-logic.js +286 -0
  138. package/dist/test/wallet.test.d.ts +7 -0
  139. package/dist/test/wallet.test.js +146 -0
  140. package/index.ts +1965 -0
  141. package/openclaw.plugin.json +106 -0
  142. package/package.json +73 -0
  143. package/src/cli-main.ts +230 -0
  144. package/src/cli.ts +16 -0
  145. package/src/core/README.md +246 -0
  146. package/src/core/config.ts +21 -0
  147. package/src/core/index.ts +42 -0
  148. package/src/core/payment.ts +111 -0
  149. package/src/core/types.ts +102 -0
  150. package/src/core/verify.ts +119 -0
  151. package/src/core/wallet.ts +282 -0
  152. package/src/scripts/baemail/commands.ts +326 -0
  153. package/src/scripts/baemail/handler.ts +338 -0
  154. package/src/scripts/baemail/index.ts +6 -0
  155. package/src/scripts/config.ts +81 -0
  156. package/src/scripts/index.ts +8 -0
  157. package/src/scripts/messaging/connect.ts +121 -0
  158. package/src/scripts/messaging/handlers.ts +394 -0
  159. package/src/scripts/messaging/inbox.ts +64 -0
  160. package/src/scripts/messaging/index.ts +9 -0
  161. package/src/scripts/messaging/poll.ts +59 -0
  162. package/src/scripts/messaging/send.ts +54 -0
  163. package/src/scripts/output.ts +21 -0
  164. package/src/scripts/overlay/discover.ts +81 -0
  165. package/src/scripts/overlay/index.ts +8 -0
  166. package/src/scripts/overlay/registration.ts +199 -0
  167. package/src/scripts/overlay/services.ts +199 -0
  168. package/src/scripts/overlay/transaction.ts +124 -0
  169. package/src/scripts/payment/build.ts +65 -0
  170. package/src/scripts/payment/commands.ts +92 -0
  171. package/src/scripts/payment/index.ts +7 -0
  172. package/src/scripts/payment/types.ts +62 -0
  173. package/src/scripts/services/index.ts +7 -0
  174. package/src/scripts/services/queue.ts +35 -0
  175. package/src/scripts/services/request.ts +98 -0
  176. package/src/scripts/services/respond.ts +149 -0
  177. package/src/scripts/types.ts +121 -0
  178. package/src/scripts/utils/index.ts +7 -0
  179. package/src/scripts/utils/merkle.ts +57 -0
  180. package/src/scripts/utils/storage.ts +231 -0
  181. package/src/scripts/utils/woc.ts +106 -0
  182. package/src/scripts/wallet/balance.ts +277 -0
  183. package/src/scripts/wallet/identity.ts +203 -0
  184. package/src/scripts/wallet/index.ts +7 -0
  185. package/src/scripts/wallet/setup.ts +121 -0
  186. package/src/scripts/x-verification/commands.ts +256 -0
  187. package/src/scripts/x-verification/index.ts +5 -0
  188. package/src/services/built-in/api-proxy/index.ts +26 -0
  189. package/src/services/built-in/api-proxy/prompt.md +26 -0
  190. package/src/services/built-in/code-develop/index.ts +26 -0
  191. package/src/services/built-in/code-develop/prompt.md +35 -0
  192. package/src/services/built-in/code-review/index.ts +54 -0
  193. package/src/services/built-in/code-review/prompt.md +105 -0
  194. package/src/services/built-in/image-analysis/index.ts +36 -0
  195. package/src/services/built-in/image-analysis/prompt.md +42 -0
  196. package/src/services/built-in/memory-store/index.ts +25 -0
  197. package/src/services/built-in/memory-store/prompt.md +45 -0
  198. package/src/services/built-in/roulette/index.ts +30 -0
  199. package/src/services/built-in/roulette/prompt.md +35 -0
  200. package/src/services/built-in/summarize/index.ts +24 -0
  201. package/src/services/built-in/summarize/prompt.md +27 -0
  202. package/src/services/built-in/tell-joke/handler.ts +134 -0
  203. package/src/services/built-in/tell-joke/index.ts +34 -0
  204. package/src/services/built-in/tell-joke/prompt.md +59 -0
  205. package/src/services/built-in/translate/index.ts +24 -0
  206. package/src/services/built-in/translate/prompt.md +23 -0
  207. package/src/services/built-in/web-research/index.ts +54 -0
  208. package/src/services/built-in/web-research/prompt.md +110 -0
  209. package/src/services/index.ts +16 -0
  210. package/src/services/loader.ts +344 -0
  211. package/src/services/manager.ts +304 -0
  212. package/src/services/registry.ts +246 -0
  213. package/src/services/types.ts +259 -0
  214. package/src/test/cli.test.ts +352 -0
  215. package/src/test/comprehensive-overlay.test.ts +729 -0
  216. package/src/test/key-derivation.test.ts +102 -0
  217. package/src/test/overlay-submit.test.ts +570 -0
  218. package/src/test/request-response-flow.test.ts +252 -0
  219. package/src/test/service-system.test.ts +241 -0
  220. package/src/test/utils/server-logic.ts +368 -0
  221. package/src/test/wallet.test.ts +166 -0
@@ -0,0 +1,192 @@
1
+ /**
2
+ * BSV Overlay CLI - Main Command Dispatcher
3
+ *
4
+ * Routes commands to the appropriate modules.
5
+ * All business logic is in the scripts/ modules.
6
+ */
7
+ import { ok, fail } from './scripts/output.js';
8
+ // Wallet commands
9
+ import { cmdSetup, cmdIdentity, cmdAddress } from './scripts/wallet/setup.js';
10
+ import { cmdBalance, cmdImport, cmdRefund } from './scripts/wallet/balance.js';
11
+ // Overlay registration commands
12
+ import { cmdRegister, cmdUnregister } from './scripts/overlay/registration.js';
13
+ // Service commands
14
+ import { cmdServices, cmdAdvertise, cmdRemove, cmdReadvertise } from './scripts/overlay/services.js';
15
+ // Discovery commands
16
+ import { cmdDiscover } from './scripts/overlay/discover.js';
17
+ // Payment commands
18
+ import { cmdPay, cmdVerify, cmdAccept } from './scripts/payment/commands.js';
19
+ // Messaging commands
20
+ import { cmdSend } from './scripts/messaging/send.js';
21
+ import { cmdInbox, cmdAck } from './scripts/messaging/inbox.js';
22
+ import { cmdPoll } from './scripts/messaging/poll.js';
23
+ import { cmdConnect } from './scripts/messaging/connect.js';
24
+ // Service request/response commands
25
+ import { cmdRequestService } from './scripts/services/request.js';
26
+ import { cmdRespondService, cmdResearchRespond } from './scripts/services/respond.js';
27
+ import { cmdServiceQueue, cmdResearchQueue } from './scripts/services/queue.js';
28
+ // X verification commands
29
+ import { cmdXVerifyStart, cmdXVerifyComplete, cmdXVerifications, cmdXLookup, cmdXEngagementQueue, cmdXEngagementFulfill, } from './scripts/x-verification/commands.js';
30
+ // Baemail commands
31
+ import { cmdBaemailSetup, cmdBaemailConfig, cmdBaemailBlock, cmdBaemailUnblock, cmdBaemailLog, cmdBaemailRefund, } from './scripts/baemail/commands.js';
32
+ const [, , command, ...args] = process.argv;
33
+ async function main() {
34
+ try {
35
+ switch (command) {
36
+ // Help
37
+ case 'help':
38
+ case '--help':
39
+ case '-h':
40
+ ok({
41
+ usage: 'openclaw-overlay <command> [args...]',
42
+ commands: {
43
+ wallet: ['setup', 'identity', 'address', 'balance', 'import <txid> [vout]', 'refund <address>'],
44
+ registration: ['register', 'unregister'],
45
+ services: ['services', 'advertise <id> <name> <priceSats> [desc]', 'readvertise <id> [name] [priceSats] [desc]', 'remove <id>'],
46
+ discovery: ['discover [--service <type>] [--agent <name>]'],
47
+ payments: ['pay <pubkey> <sats> [desc]', 'verify <beef>', 'accept <beef> <prefix> <suffix> <senderKey> [desc]'],
48
+ messaging: ['send <key> <type> <json>', 'inbox', 'ack', 'poll', 'connect'],
49
+ 'service-requests': ['request-service <key> <serviceId> <sats> [input]', 'service-queue', 'respond-service <reqId> <key> <serviceId> <result>'],
50
+ research: ['research-queue', 'research-respond <reqId>'],
51
+ 'x-verification': ['x-verify-start <handle>', 'x-verify-complete <handle>', 'x-verifications', 'x-lookup <handle>', 'x-engagement-queue', 'x-engagement-fulfill <reqId> <result>'],
52
+ baemail: ['baemail-setup <price> <xHandle> <forwardEmail> <greeting>', 'baemail-config', 'baemail-block <sender>', 'baemail-unblock <sender>', 'baemail-log [limit]', 'baemail-refund <msgId>'],
53
+ },
54
+ });
55
+ break;
56
+ // Wallet
57
+ case 'setup':
58
+ await cmdSetup();
59
+ break;
60
+ case 'identity':
61
+ await cmdIdentity();
62
+ break;
63
+ case 'address':
64
+ await cmdAddress();
65
+ break;
66
+ case 'balance':
67
+ await cmdBalance();
68
+ break;
69
+ case 'import':
70
+ await cmdImport(args[0], args[1]);
71
+ break;
72
+ case 'refund':
73
+ await cmdRefund(args[0]);
74
+ break;
75
+ // Overlay registration
76
+ case 'register':
77
+ await cmdRegister();
78
+ break;
79
+ case 'unregister':
80
+ await cmdUnregister();
81
+ break;
82
+ // Services
83
+ case 'services':
84
+ await cmdServices();
85
+ break;
86
+ case 'advertise':
87
+ await cmdAdvertise(args[0], args[1], args[2], args[3]);
88
+ break;
89
+ case 'remove':
90
+ await cmdRemove(args[0]);
91
+ break;
92
+ case 'readvertise':
93
+ await cmdReadvertise(args[0], args[1], args[2], args.slice(3).join(' ') || undefined);
94
+ break;
95
+ // Discovery
96
+ case 'discover':
97
+ await cmdDiscover(args);
98
+ break;
99
+ // Payments
100
+ case 'pay':
101
+ await cmdPay(args[0], args[1], args.slice(2).join(' ') || undefined);
102
+ break;
103
+ case 'verify':
104
+ await cmdVerify(args[0]);
105
+ break;
106
+ case 'accept':
107
+ await cmdAccept(args[0], args[1], args[2], args[3], args.slice(4).join(' ') || undefined);
108
+ break;
109
+ // Messaging (relay)
110
+ case 'send':
111
+ await cmdSend(args[0], args[1], args[2]);
112
+ break;
113
+ case 'inbox':
114
+ await cmdInbox(args);
115
+ break;
116
+ case 'ack':
117
+ await cmdAck(args);
118
+ break;
119
+ case 'poll':
120
+ await cmdPoll();
121
+ break;
122
+ case 'connect':
123
+ await cmdConnect();
124
+ break;
125
+ case 'request-service':
126
+ await cmdRequestService(args[0], args[1], args[2], args[3]);
127
+ break;
128
+ case 'research-respond':
129
+ await cmdResearchRespond(args[0]);
130
+ break;
131
+ case 'research-queue':
132
+ await cmdResearchQueue();
133
+ break;
134
+ case 'service-queue':
135
+ await cmdServiceQueue();
136
+ break;
137
+ case 'respond-service':
138
+ await cmdRespondService(args[0], args[1], args[2], args.slice(3).join(' '));
139
+ break;
140
+ // X Account Verification
141
+ case 'x-verify-start':
142
+ await cmdXVerifyStart(args[0]);
143
+ break;
144
+ case 'x-verify-complete':
145
+ await cmdXVerifyComplete(args[0]);
146
+ break;
147
+ case 'x-verifications':
148
+ await cmdXVerifications();
149
+ break;
150
+ case 'x-lookup':
151
+ await cmdXLookup(args[0]);
152
+ break;
153
+ // X Engagement Service
154
+ case 'x-engagement-queue':
155
+ await cmdXEngagementQueue();
156
+ break;
157
+ case 'x-engagement-fulfill':
158
+ await cmdXEngagementFulfill(args[0], args[1]);
159
+ break;
160
+ // Baemail Service
161
+ case 'baemail-setup':
162
+ await cmdBaemailSetup(args[0], args[1], args[2], args[3]);
163
+ break;
164
+ case 'baemail-config':
165
+ await cmdBaemailConfig();
166
+ break;
167
+ case 'baemail-block':
168
+ await cmdBaemailBlock(args[0]);
169
+ break;
170
+ case 'baemail-unblock':
171
+ await cmdBaemailUnblock(args[0]);
172
+ break;
173
+ case 'baemail-log':
174
+ await cmdBaemailLog(args[0]);
175
+ break;
176
+ case 'baemail-refund':
177
+ await cmdBaemailRefund(args[0]);
178
+ break;
179
+ default:
180
+ fail(`Unknown command: ${command || '(none)'}. Commands: setup, identity, address, balance, import, refund, ` +
181
+ `register, unregister, services, advertise, readvertise, remove, discover, pay, verify, accept, ` +
182
+ `send, inbox, ack, poll, connect, request-service, research-queue, research-respond, ` +
183
+ `service-queue, respond-service, x-verify-start, x-verify-complete, x-verifications, x-lookup, ` +
184
+ `x-engagement-queue, x-engagement-fulfill, baemail-setup, baemail-config, baemail-block, ` +
185
+ `baemail-unblock, baemail-log, baemail-refund`);
186
+ }
187
+ }
188
+ catch (err) {
189
+ fail(err.message || String(err));
190
+ }
191
+ }
192
+ main();
package/dist/cli.d.ts ADDED
@@ -0,0 +1,8 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * BSV Overlay CLI - Bootstrap Entry Point
4
+ *
5
+ * Sets environment variables before importing the main CLI module
6
+ * to suppress dotenv v17 verbose logging.
7
+ */
8
+ export {};
package/dist/cli.js ADDED
@@ -0,0 +1,14 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * BSV Overlay CLI - Bootstrap Entry Point
4
+ *
5
+ * Sets environment variables before importing the main CLI module
6
+ * to suppress dotenv v17 verbose logging.
7
+ */
8
+ // Must be set before any imports that might load dotenv
9
+ process.env.DOTENV_CONFIG_QUIET = 'true';
10
+ // Dynamic import to ensure env var is set first
11
+ import('./cli-main.js');
12
+ // Before importing the library
13
+ globalThis.window = { fetch: globalThis.fetch };
14
+ export {};
@@ -0,0 +1,11 @@
1
+ /**
2
+ * @a2a-bsv/core — Configuration defaults and helpers.
3
+ */
4
+ import type { WalletConfig } from './types.js';
5
+ /** Map our 'mainnet'/'testnet' to the wallet-toolbox's 'main'/'test' chain type. */
6
+ export type Chain = 'main' | 'test';
7
+ export declare function toChain(network: WalletConfig['network']): Chain;
8
+ /** Default TAAL API keys from the wallet-toolbox examples. */
9
+ export declare const DEFAULT_TAAL_API_KEYS: Record<Chain, string>;
10
+ /** Default SQLite database name. */
11
+ export declare const DEFAULT_DB_NAME = "a2a_agent_wallet";
@@ -0,0 +1,13 @@
1
+ /**
2
+ * @a2a-bsv/core — Configuration defaults and helpers.
3
+ */
4
+ export function toChain(network) {
5
+ return network === 'mainnet' ? 'main' : 'test';
6
+ }
7
+ /** Default TAAL API keys from the wallet-toolbox examples. */
8
+ export const DEFAULT_TAAL_API_KEYS = {
9
+ main: 'mainnet_9596de07e92300c6287e4393594ae39c',
10
+ test: 'testnet_0e6cf72133b43ea2d7861da2a38684e3',
11
+ };
12
+ /** Default SQLite database name. */
13
+ export const DEFAULT_DB_NAME = 'a2a_agent_wallet';
@@ -0,0 +1,25 @@
1
+ /**
2
+ * @a2a-bsv/core — Agent-to-agent BSV payment library.
3
+ *
4
+ * Wraps @bsv/sdk and @bsv/wallet-toolbox to provide a clean, minimal API
5
+ * for AI agents to pay each other using BSV blockchain transactions.
6
+ *
7
+ * @example
8
+ * ```ts
9
+ * import { BSVAgentWallet } from '@a2a-bsv/core';
10
+ *
11
+ * const wallet = await BSVAgentWallet.load({
12
+ * network: 'testnet',
13
+ * storageDir: './my-agent-wallet',
14
+ * });
15
+ *
16
+ * const identityKey = await wallet.getIdentityKey();
17
+ * console.log('My identity:', identityKey);
18
+ * ```
19
+ */
20
+ export { BSVAgentWallet } from './wallet.js';
21
+ export type { WalletConfig, WalletIdentity, PaymentParams, PaymentResult, VerifyParams, VerifyResult, AcceptParams, AcceptResult, } from './types.js';
22
+ export { toChain, DEFAULT_TAAL_API_KEYS, DEFAULT_DB_NAME } from './config.js';
23
+ export type { Chain } from './config.js';
24
+ export { buildPayment } from './payment.js';
25
+ export { verifyPayment, acceptPayment } from './verify.js';
@@ -0,0 +1,26 @@
1
+ /**
2
+ * @a2a-bsv/core — Agent-to-agent BSV payment library.
3
+ *
4
+ * Wraps @bsv/sdk and @bsv/wallet-toolbox to provide a clean, minimal API
5
+ * for AI agents to pay each other using BSV blockchain transactions.
6
+ *
7
+ * @example
8
+ * ```ts
9
+ * import { BSVAgentWallet } from '@a2a-bsv/core';
10
+ *
11
+ * const wallet = await BSVAgentWallet.load({
12
+ * network: 'testnet',
13
+ * storageDir: './my-agent-wallet',
14
+ * });
15
+ *
16
+ * const identityKey = await wallet.getIdentityKey();
17
+ * console.log('My identity:', identityKey);
18
+ * ```
19
+ */
20
+ // Main wallet class
21
+ export { BSVAgentWallet } from './wallet.js';
22
+ // Config helpers (for advanced use)
23
+ export { toChain, DEFAULT_TAAL_API_KEYS, DEFAULT_DB_NAME } from './config.js';
24
+ // Lower-level helpers (for advanced use)
25
+ export { buildPayment } from './payment.js';
26
+ export { verifyPayment, acceptPayment } from './verify.js';
@@ -0,0 +1,16 @@
1
+ /**
2
+ * @a2a-bsv/core — Payment construction helpers.
3
+ *
4
+ * Uses BRC-29 key derivation so the recipient can internalize the payment
5
+ * without ever reusing an address.
6
+ */
7
+ import type { SetupWallet } from '@bsv/wallet-toolbox';
8
+ import type { PaymentParams, PaymentResult } from './types.js';
9
+ /**
10
+ * Build a BRC-29 payment transaction using the wallet's createAction API.
11
+ *
12
+ * The transaction is created with `acceptDelayedBroadcast: false` — the sender
13
+ * broadcasts immediately. The resulting Atomic BEEF and derivation metadata are
14
+ * returned so the recipient can verify and internalize the payment on their side.
15
+ */
16
+ export declare function buildPayment(setup: SetupWallet, params: PaymentParams): Promise<PaymentResult>;
@@ -0,0 +1,94 @@
1
+ /**
2
+ * @a2a-bsv/core — Payment construction helpers.
3
+ *
4
+ * Uses BRC-29 key derivation so the recipient can internalize the payment
5
+ * without ever reusing an address.
6
+ */
7
+ import { Beef, Utils } from '@bsv/sdk';
8
+ import { randomBytesBase64, ScriptTemplateBRC29 } from '@bsv/wallet-toolbox';
9
+ /**
10
+ * Build a BRC-29 payment transaction using the wallet's createAction API.
11
+ *
12
+ * The transaction is created with `acceptDelayedBroadcast: false` — the sender
13
+ * broadcasts immediately. The resulting Atomic BEEF and derivation metadata are
14
+ * returned so the recipient can verify and internalize the payment on their side.
15
+ */
16
+ export async function buildPayment(setup, params) {
17
+ const { to, satoshis, description } = params;
18
+ const desc = normalizeDescription(description ?? 'agent payment');
19
+ // Generate unique BRC-29 derivation prefixes and suffixes
20
+ const derivationPrefix = randomBytesBase64(8);
21
+ const derivationSuffix = randomBytesBase64(8);
22
+ // Build BRC-29 locking script
23
+ const keyDeriver = setup.keyDeriver;
24
+ const t = new ScriptTemplateBRC29({
25
+ derivationPrefix,
26
+ derivationSuffix,
27
+ keyDeriver,
28
+ });
29
+ // Determine the recipient identity key.
30
+ // If `to` is a compressed public key hex (66 chars, starts with 02/03), use directly.
31
+ // Otherwise treat as an address — for BRC-29 we need a public key.
32
+ let recipientPubKey;
33
+ if (/^0[23][0-9a-fA-F]{64}$/.test(to)) {
34
+ recipientPubKey = to;
35
+ }
36
+ else {
37
+ // If it's an address, we can't do BRC-29 (needs pubkey). Throw a clear error.
38
+ throw new Error('PaymentParams.to must be a compressed public key (hex) for BRC-29 payments. ' +
39
+ 'Raw BSV addresses are not supported — the recipient must share their identity key.');
40
+ }
41
+ const lockingScript = t.lock(setup.rootKey.toString(), recipientPubKey);
42
+ const label = 'a2a-payment';
43
+ const car = await setup.wallet.createAction({
44
+ outputs: [
45
+ {
46
+ lockingScript: lockingScript.toHex(),
47
+ satoshis,
48
+ outputDescription: desc,
49
+ tags: ['relinquish'],
50
+ customInstructions: JSON.stringify({
51
+ derivationPrefix,
52
+ derivationSuffix,
53
+ type: 'BRC29',
54
+ }),
55
+ },
56
+ ],
57
+ options: {
58
+ randomizeOutputs: false,
59
+ acceptDelayedBroadcast: false,
60
+ },
61
+ labels: [label],
62
+ description: desc,
63
+ });
64
+ // Extract the txid from the createAction result.
65
+ // The tx field is a number[] (AtomicBEEF binary). Parse it to get txid.
66
+ if (!car.tx) {
67
+ throw new Error('createAction did not return a transaction. Check wallet funding.');
68
+ }
69
+ const beef = Beef.fromBinary(car.tx);
70
+ // The last transaction in the beef is our new tx
71
+ const lastTx = beef.txs[beef.txs.length - 1];
72
+ const txid = lastTx.txid;
73
+ // Encode the atomic BEEF as base64
74
+ const atomicBinary = beef.toBinaryAtomic(txid);
75
+ const beefBase64 = Utils.toBase64(atomicBinary);
76
+ return {
77
+ beef: beefBase64,
78
+ txid,
79
+ satoshis,
80
+ derivationPrefix,
81
+ derivationSuffix,
82
+ senderIdentityKey: setup.identityKey,
83
+ };
84
+ }
85
+ /**
86
+ * Ensure description meets BRC-100's 5-50 character requirement.
87
+ */
88
+ function normalizeDescription(desc) {
89
+ if (desc.length < 5)
90
+ return desc.padEnd(5, ' ');
91
+ if (desc.length > 50)
92
+ return desc.slice(0, 50);
93
+ return desc;
94
+ }
@@ -0,0 +1,94 @@
1
+ /**
2
+ * @a2a-bsv/core — Type definitions for agent-to-agent BSV payments.
3
+ */
4
+ /** Wallet configuration for creating or loading an agent wallet. */
5
+ export interface WalletConfig {
6
+ /** BSV network to use. */
7
+ network: 'mainnet' | 'testnet';
8
+ /** Directory path for SQLite wallet persistence. */
9
+ storageDir: string;
10
+ /** Optional: pre-existing root private key hex. If omitted on create(), a new one is generated. */
11
+ rootKeyHex?: string;
12
+ /** Optional TAAL API key for ARC broadcasting. Falls back to public default. */
13
+ taalApiKey?: string;
14
+ /** Optional fee model in sat/KB. Falls back to BSV_FEE_MODEL env var or default 100 sat/KB. */
15
+ feeModel?: number;
16
+ }
17
+ /** Parameters for building a payment transaction. */
18
+ export interface PaymentParams {
19
+ /** Recipient's compressed public key (hex) or BSV address. */
20
+ to: string;
21
+ /** Amount to pay in satoshis. */
22
+ satoshis: number;
23
+ /** Human-readable description (5-50 chars per BRC-100). */
24
+ description?: string;
25
+ /** Optional metadata embedded as OP_RETURN (future use). */
26
+ metadata?: {
27
+ taskId?: string;
28
+ protocol?: string;
29
+ };
30
+ }
31
+ /** Result from building a payment. */
32
+ export interface PaymentResult {
33
+ /** Base64-encoded Atomic BEEF transaction data. */
34
+ beef: string;
35
+ /** Transaction ID (hex). */
36
+ txid: string;
37
+ /** Amount paid in satoshis. */
38
+ satoshis: number;
39
+ /** BRC-29 derivation prefix (base64). Needed by recipient to internalize. */
40
+ derivationPrefix: string;
41
+ /** BRC-29 derivation suffix (base64). Needed by recipient to internalize. */
42
+ derivationSuffix: string;
43
+ /** Sender's identity key (compressed hex). Needed by recipient to internalize. */
44
+ senderIdentityKey: string;
45
+ }
46
+ /** Parameters for verifying an incoming payment. */
47
+ export interface VerifyParams {
48
+ /** Base64-encoded Atomic BEEF data. */
49
+ beef: string;
50
+ /** Expected payment amount in satoshis. */
51
+ expectedAmount?: number;
52
+ /** Expected sender identity key (optional). */
53
+ expectedSender?: string;
54
+ }
55
+ /** Result from verifying a payment. */
56
+ export interface VerifyResult {
57
+ /** Whether the payment passes all checks. */
58
+ valid: boolean;
59
+ /** Transaction ID (hex). */
60
+ txid: string;
61
+ /** Number of outputs found in the transaction. */
62
+ outputCount: number;
63
+ /** Errors encountered during verification. */
64
+ errors: string[];
65
+ }
66
+ /** Parameters for accepting (internalizing) a verified payment. */
67
+ export interface AcceptParams {
68
+ /** Base64-encoded Atomic BEEF data. */
69
+ beef: string;
70
+ /** The output index to internalize (default: 0). */
71
+ vout?: number;
72
+ /** BRC-29 derivation prefix from the PaymentResult. */
73
+ derivationPrefix: string;
74
+ /** BRC-29 derivation suffix from the PaymentResult. */
75
+ derivationSuffix: string;
76
+ /** Sender's identity key from the PaymentResult. */
77
+ senderIdentityKey: string;
78
+ /** Human-readable description for wallet records (5-50 chars). */
79
+ description?: string;
80
+ }
81
+ /** Result from accepting a payment. */
82
+ export interface AcceptResult {
83
+ /** Whether the payment was accepted. */
84
+ accepted: boolean;
85
+ }
86
+ /** Serializable wallet identity info, persisted alongside the SQLite database. */
87
+ export interface WalletIdentity {
88
+ /** The root private key (hex). Guard this carefully. */
89
+ rootKeyHex: string;
90
+ /** The wallet's public identity key (compressed hex). */
91
+ identityKey: string;
92
+ /** Network this wallet targets. */
93
+ network: 'mainnet' | 'testnet';
94
+ }
@@ -0,0 +1,4 @@
1
+ /**
2
+ * @a2a-bsv/core — Type definitions for agent-to-agent BSV payments.
3
+ */
4
+ export {};
@@ -0,0 +1,28 @@
1
+ /**
2
+ * @a2a-bsv/core — Payment verification and acceptance helpers.
3
+ *
4
+ * Verification: parse the Atomic BEEF, validate structure.
5
+ * Acceptance: internalize the payment into the recipient wallet via BRC-29
6
+ * wallet payment protocol.
7
+ */
8
+ import type { SetupWallet } from '@bsv/wallet-toolbox';
9
+ import type { VerifyParams, VerifyResult, AcceptParams, AcceptResult } from './types.js';
10
+ /**
11
+ * Verify an incoming Atomic BEEF payment.
12
+ *
13
+ * This performs structural validation:
14
+ * - Decodes the base64 BEEF
15
+ * - Checks the BEEF is parseable
16
+ * - Checks there is at least one transaction
17
+ * - Runs SPV verification via tx.verify()
18
+ * - Optionally checks the sender identity key
19
+ */
20
+ export declare function verifyPayment(params: VerifyParams): Promise<VerifyResult>;
21
+ /**
22
+ * Accept (internalize) a verified BRC-29 payment into the recipient's wallet.
23
+ *
24
+ * This calls wallet.internalizeAction with the 'wallet payment' protocol,
25
+ * providing the BRC-29 derivation info so the wallet can derive the correct
26
+ * key and claim the output.
27
+ */
28
+ export declare function acceptPayment(setup: SetupWallet, params: AcceptParams): Promise<AcceptResult>;
@@ -0,0 +1,104 @@
1
+ /**
2
+ * @a2a-bsv/core — Payment verification and acceptance helpers.
3
+ *
4
+ * Verification: parse the Atomic BEEF, validate structure.
5
+ * Acceptance: internalize the payment into the recipient wallet via BRC-29
6
+ * wallet payment protocol.
7
+ */
8
+ import { Beef, Utils } from '@bsv/sdk';
9
+ /**
10
+ * Verify an incoming Atomic BEEF payment.
11
+ *
12
+ * This performs structural validation:
13
+ * - Decodes the base64 BEEF
14
+ * - Checks the BEEF is parseable
15
+ * - Checks there is at least one transaction
16
+ * - Runs SPV verification via tx.verify()
17
+ * - Optionally checks the sender identity key
18
+ */
19
+ export async function verifyPayment(params) {
20
+ const errors = [];
21
+ let txid = '';
22
+ let outputCount = 0;
23
+ try {
24
+ const binary = Utils.toArray(params.beef, 'base64');
25
+ const beef = Beef.fromBinary(binary);
26
+ if (beef.txs.length === 0) {
27
+ errors.push('BEEF contains no transactions');
28
+ }
29
+ else {
30
+ const lastTx = beef.txs[beef.txs.length - 1];
31
+ txid = lastTx.txid;
32
+ // Parse the atomic transaction to count outputs
33
+ const tx = beef.findAtomicTransaction(txid);
34
+ if (tx) {
35
+ outputCount = tx.outputs.length;
36
+ // Run SPV verification
37
+ try {
38
+ await tx.verify();
39
+ }
40
+ catch (err) {
41
+ const message = err instanceof Error ? err.message : String(err);
42
+ errors.push(`SPV verification failed: ${message}`);
43
+ }
44
+ }
45
+ else {
46
+ errors.push('Could not find atomic transaction in BEEF');
47
+ }
48
+ }
49
+ }
50
+ catch (err) {
51
+ const message = err instanceof Error ? err.message : String(err);
52
+ errors.push(`BEEF parse error: ${message}`);
53
+ }
54
+ // Sender validation is independent of BEEF parsing
55
+ if (params.expectedSender) {
56
+ if (!/^0[23][0-9a-fA-F]{64}$/.test(params.expectedSender)) {
57
+ errors.push('expectedSender is not a valid compressed public key');
58
+ }
59
+ }
60
+ return {
61
+ valid: errors.length === 0,
62
+ txid,
63
+ outputCount,
64
+ errors,
65
+ };
66
+ }
67
+ /**
68
+ * Accept (internalize) a verified BRC-29 payment into the recipient's wallet.
69
+ *
70
+ * This calls wallet.internalizeAction with the 'wallet payment' protocol,
71
+ * providing the BRC-29 derivation info so the wallet can derive the correct
72
+ * key and claim the output.
73
+ */
74
+ export async function acceptPayment(setup, params) {
75
+ const desc = normalizeDescription(params.description ?? 'received payment');
76
+ const vout = params.vout ?? 0;
77
+ const binary = Utils.toArray(params.beef, 'base64');
78
+ const args = {
79
+ tx: binary,
80
+ outputs: [
81
+ {
82
+ outputIndex: vout,
83
+ protocol: 'wallet payment',
84
+ paymentRemittance: {
85
+ derivationPrefix: params.derivationPrefix,
86
+ derivationSuffix: params.derivationSuffix,
87
+ senderIdentityKey: params.senderIdentityKey,
88
+ },
89
+ },
90
+ ],
91
+ description: desc,
92
+ };
93
+ const result = await setup.wallet.internalizeAction(args);
94
+ return {
95
+ accepted: result.accepted,
96
+ };
97
+ }
98
+ function normalizeDescription(desc) {
99
+ if (desc.length < 5)
100
+ return desc.padEnd(5, ' ');
101
+ if (desc.length > 50)
102
+ return desc.slice(0, 50);
103
+ return desc;
104
+ }