openclaw-messagebox-plugin 0.1.3 → 0.1.5

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 (47) hide show
  1. package/README.md +44 -5
  2. package/dist/index.d.ts.map +1 -1
  3. package/dist/index.js +85 -14
  4. package/dist/index.js.map +1 -1
  5. package/dist/src/client.d.ts +11 -4
  6. package/dist/src/client.d.ts.map +1 -1
  7. package/dist/src/client.js +94 -13
  8. package/dist/src/client.js.map +1 -1
  9. package/dist/src/core/config.d.ts +12 -0
  10. package/dist/src/core/config.d.ts.map +1 -0
  11. package/dist/src/core/config.js +14 -0
  12. package/dist/src/core/config.js.map +1 -0
  13. package/dist/src/core/index.d.ts +26 -0
  14. package/dist/src/core/index.d.ts.map +1 -0
  15. package/dist/src/core/index.js +27 -0
  16. package/dist/src/core/index.js.map +1 -0
  17. package/dist/src/core/payment.d.ts +17 -0
  18. package/dist/src/core/payment.d.ts.map +1 -0
  19. package/dist/src/core/payment.js +95 -0
  20. package/dist/src/core/payment.js.map +1 -0
  21. package/dist/src/core/types.d.ts +95 -0
  22. package/dist/src/core/types.d.ts.map +1 -0
  23. package/dist/src/core/types.js +5 -0
  24. package/dist/src/core/types.js.map +1 -0
  25. package/dist/src/core/verify.d.ts +29 -0
  26. package/dist/src/core/verify.d.ts.map +1 -0
  27. package/dist/src/core/verify.js +105 -0
  28. package/dist/src/core/verify.js.map +1 -0
  29. package/dist/src/core/wallet.d.ts +100 -0
  30. package/dist/src/core/wallet.d.ts.map +1 -0
  31. package/dist/src/core/wallet.js +225 -0
  32. package/dist/src/core/wallet.js.map +1 -0
  33. package/index.ts +95 -14
  34. package/openclaw.plugin.json +3 -2
  35. package/package.json +7 -6
  36. package/src/client.ts +106 -14
  37. package/src/core/config.d.ts +12 -0
  38. package/src/core/config.ts +21 -0
  39. package/src/core/index.ts +42 -0
  40. package/src/core/payment.d.ts +17 -0
  41. package/src/core/payment.ts +111 -0
  42. package/src/core/types.d.ts +95 -0
  43. package/src/core/types.ts +102 -0
  44. package/src/core/verify.d.ts +29 -0
  45. package/src/core/verify.ts +119 -0
  46. package/src/core/wallet.d.ts +100 -0
  47. package/src/core/wallet.ts +289 -0
package/index.ts CHANGED
@@ -1,22 +1,51 @@
1
1
  import path from "node:path";
2
2
  import os from "node:os";
3
3
  import fs from "node:fs";
4
+ import { MessageBoxManager } from "./src/client.js";
5
+ import { MessageStore } from "./src/store.js";
6
+ import { BSVAgentWallet } from "./src/core/wallet.js";
4
7
 
5
8
  /**
6
9
  * OpenClaw MessageBox Plugin
7
10
  * Enables secure P2P encrypted messaging and payments.
8
11
  */
9
12
  export default function register(api: any) {
10
- // Capture configuration from the gateway (handle both flat and nested structures)
11
- const entry = api.getConfig?.()?.plugins?.entries?.['openclaw-messagebox'] || {};
13
+ // Capture configuration from the gateway (handle multiple IDs and flat/nested structures)
14
+ const entries = api.getConfig?.()?.plugins?.entries || {};
15
+ const entry = entries['openclaw-messagebox']
16
+ || entries['openclaw-messagebox-plugin']
17
+ || entries['bsv-messagebox']
18
+ || {};
19
+
12
20
  const pluginConfig = { ...entry, ...(entry.config || {}), ...(api.config || {}) };
13
21
  const host = pluginConfig.host || 'https://msg.bsv.direct';
14
22
  const network = pluginConfig.network || 'mainnet';
15
23
  const chaintracksUrl = pluginConfig.chaintracksUrl || 'https://chaintracks-us-1.bsvb.tech';
16
- const arcUrl = pluginConfig.arcUrl || '';
24
+ const arcUrl = pluginConfig.arcUrl || (network === 'testnet' ? 'https://testnet.arc.gorillapool.io' : 'https://arc.gorillapool.io');
17
25
  const walletDir = pluginConfig.walletDir || path.join(os.homedir(), '.openclaw', 'bsv-wallet');
26
+ const dbPath = pluginConfig.dbPath || path.join(os.homedir(), '.openclaw', 'openclaw-messagebox', 'messages.sqlite');
18
27
 
19
- api.logger.info(`[messagebox] Initializing MessageBox Plugin (network: ${network}, host: ${host}, chaintracks: ${chaintracksUrl}, arc: ${arcUrl || 'default'})`);
28
+ let manager: MessageBoxManager | null = null;
29
+ let store: MessageStore | null = null;
30
+ let wallet: BSVAgentWallet | null = null;
31
+
32
+ api.logger.info(`[messagebox] Initializing MessageBox Plugin (network: ${network}, host: ${host})`);
33
+
34
+ async function ensureInitialized() {
35
+ if (manager) return manager;
36
+
37
+ // Initialize shared wallet
38
+ wallet = await BSVAgentWallet.load({
39
+ network: network as any,
40
+ storageDir: walletDir
41
+ });
42
+
43
+ store = new MessageStore(dbPath);
44
+ await store.init();
45
+
46
+ manager = new MessageBoxManager({ host, walletDir, dbPath }, store, wallet);
47
+ return manager;
48
+ }
20
49
 
21
50
  // Register the messagebox tool
22
51
  api.registerTool({
@@ -38,6 +67,11 @@ export default function register(api: any) {
38
67
  type: "string",
39
68
  description: "Message content (will be encrypted client-side)"
40
69
  },
70
+ box: {
71
+ type: "string",
72
+ default: "default",
73
+ description: "Target mailbox/folder"
74
+ },
41
75
  sats: {
42
76
  type: "number",
43
77
  description: "Amount in satoshis for direct P2P payment"
@@ -52,13 +86,44 @@ export default function register(api: any) {
52
86
  },
53
87
  async execute(_id: string, params: any) {
54
88
  try {
55
- // Implementation logic will go here
56
- return {
57
- content: [{
58
- type: "text",
59
- text: `MessageBox action '${params.action}' received. (Logic implementation pending)`
60
- }]
61
- };
89
+ const m = await ensureInitialized();
90
+
91
+ switch (params.action) {
92
+ case "send":
93
+ if (!params.recipientKey || !params.body) throw new Error("recipientKey and body required");
94
+ const msgId = await m.send(params.recipientKey, params.body, params.box);
95
+ return { content: [{ type: "text", text: `✅ Message sent successfully. ID: ${msgId}` }] };
96
+
97
+ case "inbox":
98
+ await m.poll(params.box);
99
+ const messages = await store!.getInbox();
100
+ if (messages.length === 0) return { content: [{ type: "text", text: "Your inbox is empty." }] };
101
+
102
+ const list = messages.map(msg => `[${new Date(msg.ts).toLocaleString()}] FROM: ${msg.senderKey.slice(0, 12)}... - "${msg.body}"`).join('\n');
103
+ return { content: [{ type: "text", text: `📬 Inbox (Last ${messages.length} messages):\n\n${list}` }] };
104
+
105
+ case "acknowledge":
106
+ if (!params.messageIds || params.messageIds.length === 0) throw new Error("messageIds array required");
107
+ await m.acknowledge(params.messageIds);
108
+ return { content: [{ type: "text", text: `✅ Acknowledged ${params.messageIds.length} messages.` }] };
109
+
110
+ case "status":
111
+ return { content: [{ type: "text", text: `MessageBox Status:\nHost: ${host}\nIdentity: ${m.getIdentityKey()}\nDatabase: ${dbPath}` }] };
112
+
113
+ case "pay":
114
+ if (!params.recipientKey || !params.sats) throw new Error("recipientKey and sats required");
115
+ const payResult = await wallet!.createPayment({
116
+ to: params.recipientKey,
117
+ satoshis: params.sats,
118
+ description: "P2P Payment via MessageBox"
119
+ });
120
+ // Send the BEEF payment as a message to the recipient's payment_inbox
121
+ const pmsgId = await m.send(params.recipientKey, JSON.stringify(payResult), 'payment_inbox');
122
+ return { content: [{ type: "text", text: `✅ P2P Payment sent! Amount: ${params.sats} sats. Notification ID: ${pmsgId}` }] };
123
+
124
+ default:
125
+ throw new Error(`Unknown action: ${params.action}`);
126
+ }
62
127
  } catch (error: any) {
63
128
  return {
64
129
  content: [{
@@ -74,11 +139,27 @@ export default function register(api: any) {
74
139
  api.registerService({
75
140
  id: "messagebox-listener",
76
141
  start: async () => {
77
- api.logger.info("[messagebox] Starting WebSocket listener...");
78
- // Logic for client.listenForLiveMessages goes here
142
+ try {
143
+ const m = await ensureInitialized();
144
+ api.logger.info("[messagebox] Starting WebSocket listener...");
145
+
146
+ await m.listen((msg) => {
147
+ api.logger.info(`[messagebox] ⚡ New message from ${msg.senderKey.slice(0, 12)}...`);
148
+
149
+ // Wake the agent to handle the incoming private message
150
+ const wakeText = `⚡ New private message received!\n\nFrom: ${msg.senderKey}\nMessage: ${msg.body}\n\nYou can reply using messagebox({ action: "send", recipientKey: "${msg.senderKey}", body: "..." })`;
151
+
152
+ api.wakeAgent?.({
153
+ prompt: wakeText,
154
+ sessionKey: `hook:messagebox:${msg.id}`
155
+ });
156
+ });
157
+ } catch (err: any) {
158
+ api.logger.error(`[messagebox] WebSocket listener failed: ${err.message}`);
159
+ }
79
160
  },
80
161
  stop: async () => {
81
- api.logger.info("[messagebox] Stopping MessageBox WebSocket listener...");
162
+ api.logger.info("[messagebox] Stopping WebSocket listener...");
82
163
  }
83
164
  });
84
165
  }
@@ -1,5 +1,5 @@
1
1
  {
2
- "id": "openclaw-messagebox",
2
+ "id": "openclaw-messagebox-plugin",
3
3
  "name": "BSV MessageBox P2P",
4
4
  "description": "Secure P2P encrypted messaging and payments for AI agents",
5
5
  "version": "0.1.0",
@@ -28,6 +28,7 @@
28
28
  },
29
29
  "arcUrl": {
30
30
  "type": "string",
31
+ "default": "https://arc.gorillapool.io",
31
32
  "description": "Custom ARC/Arcade server URL for transaction broadcasting"
32
33
  },
33
34
  "walletDir": {
@@ -56,7 +57,7 @@
56
57
  },
57
58
  "arcUrl": {
58
59
  "label": "ARC/Arcade Server URL",
59
- "placeholder": "https://arc.taal.com",
60
+ "placeholder": "https://arc.gorillapool.io",
60
61
  "help": "Custom server for transaction broadcasting",
61
62
  "advanced": true
62
63
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "openclaw-messagebox-plugin",
3
- "version": "0.1.3",
3
+ "version": "0.1.5",
4
4
  "description": "OpenClaw plugin for P2P encrypted messaging and payments via BSV MessageBox",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -19,16 +19,17 @@
19
19
  "test": "npx tsx src/**/*.test.ts"
20
20
  },
21
21
  "dependencies": {
22
- "@bsv/sdk": "^2.0.13",
23
22
  "@bsv/message-box-client": "^2.0.4",
23
+ "@bsv/sdk": "^2.0.13",
24
+ "@bsv/wallet-toolbox": "^2.1.17",
24
25
  "better-sqlite3": "^12.8.0",
25
- "knex": "^3.2.8",
26
- "dotenv": "^17.3.1"
26
+ "dotenv": "^17.3.1",
27
+ "knex": "^3.2.8"
27
28
  },
28
29
  "devDependencies": {
29
30
  "@types/node": "^22.10.0",
30
- "typescript": "^6.0.2",
31
- "eslint": "^10.1.0"
31
+ "eslint": "^10.1.0",
32
+ "typescript": "^6.0.2"
32
33
  },
33
34
  "openclaw": {
34
35
  "extensions": [
package/src/client.ts CHANGED
@@ -1,27 +1,119 @@
1
1
  import { MessageBoxClient } from '@bsv/message-box-client';
2
+ import { PrivateKey } from '@bsv/sdk';
2
3
  import { MessageBoxConfig, MessageRecord } from './types.js';
4
+ import { MessageStore } from './store.js';
5
+ import * as fs from 'node:fs';
6
+ import * as path from 'node:path';
7
+ import { BSVAgentWallet } from './core/wallet.js';
3
8
 
4
9
  export class MessageBoxManager {
5
- private client!: MessageBoxClient;
10
+ private client: MessageBoxClient;
11
+ private privKey: PrivateKey;
12
+ private store: MessageStore;
13
+ private wallet: BSVAgentWallet;
6
14
 
7
- constructor(_config: MessageBoxConfig) {
8
- // Note: MessageBoxClient requires a WalletClient/Identity
9
- // This will be initialized in an async init method or similar
15
+ constructor(config: MessageBoxConfig, store: MessageStore, wallet: BSVAgentWallet) {
16
+ const identityPath = path.join(config.walletDir, 'wallet-identity.json');
17
+ if (!fs.existsSync(identityPath)) {
18
+ throw new Error(`Identity file not found at ${identityPath}. Please onboard your agent first.`);
19
+ }
20
+
21
+ const identity = JSON.parse(fs.readFileSync(identityPath, 'utf-8'));
22
+ this.privKey = PrivateKey.fromHex(identity.rootKeyHex);
23
+ this.store = store;
24
+ this.wallet = wallet;
25
+
26
+ // Initialize the MessageBoxClient with correct SDK-style wallet interface
27
+ // @ts-ignore
28
+ this.client = new MessageBoxClient({
29
+ host: config.host,
30
+ walletClient: this.wallet._setup.wallet,
31
+ networkPreset: config.walletDir.includes('testnet') ? 'testnet' : 'mainnet'
32
+ });
33
+ }
34
+
35
+ async send(recipientKey: string, body: string, box: string = 'default'): Promise<string> {
36
+ // sendMessage handles BRC-2 encryption internally using the walletClient
37
+ // @ts-ignore
38
+ const response = await this.client.sendMessage({
39
+ recipient: recipientKey,
40
+ messageBox: box,
41
+ body: body
42
+ });
43
+
44
+ // Save to local store
45
+ await this.store.saveMessage({
46
+ id: response.messageId,
47
+ senderKey: this.privKey.toPublicKey().toString(),
48
+ recipientKey,
49
+ body, // store decrypted locally
50
+ box,
51
+ ts: Date.now(),
52
+ acknowledged: false
53
+ });
54
+
55
+ return response.messageId;
10
56
  }
11
57
 
12
- async send(_recipientKey: string, _body: string, _box: string = 'default'): Promise<string> {
13
- // 1. Encrypt body for recipient
14
- // 2. Call client.sendMessage
15
- return "msg_id";
58
+ async poll(box: string = 'default'): Promise<MessageRecord[]> {
59
+ // listMessages handles BRC-2 decryption internally using the walletClient
60
+ // @ts-ignore
61
+ const messages = await this.client.listMessages({ messageBox: box });
62
+ const records: MessageRecord[] = [];
63
+
64
+ for (const msg of messages) {
65
+ const record: MessageRecord = {
66
+ // @ts-ignore
67
+ id: msg.id || (msg as any).messageId,
68
+ // @ts-ignore
69
+ senderKey: msg.sender || (msg as any).senderKey,
70
+ recipientKey: this.privKey.toPublicKey().toString(),
71
+ body: typeof msg.body === 'string' ? msg.body : JSON.stringify(msg.body),
72
+ // @ts-ignore
73
+ box: msg.box || box,
74
+ // @ts-ignore
75
+ ts: msg.timestamp || Date.now(),
76
+ acknowledged: false
77
+ };
78
+
79
+ await this.store.saveMessage(record);
80
+ records.push(record);
81
+ }
82
+
83
+ return records;
16
84
  }
17
85
 
18
- async poll(_box: string = 'default'): Promise<MessageRecord[]> {
19
- // 1. Call client.listMessages
20
- // 2. Decrypt and format
21
- return [];
86
+ async acknowledge(messageIds: string[]) {
87
+ // @ts-ignore
88
+ await this.client.acknowledgeMessage({ messageIds });
89
+ await this.store.markAcknowledged(messageIds);
90
+ }
91
+
92
+ async listen(onMessage: (msg: MessageRecord) => void) {
93
+ // @ts-ignore
94
+ return this.client.listenForLiveMessages({
95
+ messageBox: 'default',
96
+ onMessage: async (msg: any) => {
97
+ const record: MessageRecord = {
98
+ // @ts-ignore
99
+ id: msg.id || (msg as any).messageId,
100
+ // @ts-ignore
101
+ senderKey: msg.sender || (msg as any).senderKey,
102
+ recipientKey: this.privKey.toPublicKey().toString(),
103
+ body: typeof msg.body === 'string' ? msg.body : JSON.stringify(msg.body),
104
+ // @ts-ignore
105
+ box: msg.box || 'default',
106
+ ts: Date.now(),
107
+ acknowledged: false
108
+ };
109
+
110
+ await this.store.saveMessage(record);
111
+ onMessage(record);
112
+ }
113
+ });
22
114
  }
23
115
 
24
- async acknowledge(_messageIds: string[]) {
25
- // Call client.acknowledgeMessage
116
+ getIdentityKey(): string {
117
+ return this.privKey.toPublicKey().toString();
26
118
  }
27
119
  }
@@ -0,0 +1,12 @@
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";
12
+ //# sourceMappingURL=config.d.ts.map
@@ -0,0 +1,21 @@
1
+ /**
2
+ * @a2a-bsv/core — Configuration defaults and helpers.
3
+ */
4
+
5
+ import type { WalletConfig } from './types.js';
6
+
7
+ /** Map our 'mainnet'/'testnet' to the wallet-toolbox's 'main'/'test' chain type. */
8
+ export type Chain = 'main' | 'test';
9
+
10
+ export function toChain(network: WalletConfig['network']): Chain {
11
+ return network === 'mainnet' ? 'main' : 'test';
12
+ }
13
+
14
+ /** Default TAAL API keys from the wallet-toolbox examples. */
15
+ export const DEFAULT_TAAL_API_KEYS: Record<Chain, string> = {
16
+ main: 'mainnet_9596de07e92300c6287e4393594ae39c',
17
+ test: 'testnet_0e6cf72133b43ea2d7861da2a38684e3',
18
+ };
19
+
20
+ /** Default SQLite database name. */
21
+ export const DEFAULT_DB_NAME = 'a2a_agent_wallet';
@@ -0,0 +1,42 @@
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
+
21
+ // Main wallet class
22
+ export { BSVAgentWallet } from './wallet.js';
23
+
24
+ // All types
25
+ export type {
26
+ WalletConfig,
27
+ WalletIdentity,
28
+ PaymentParams,
29
+ PaymentResult,
30
+ VerifyParams,
31
+ VerifyResult,
32
+ AcceptParams,
33
+ AcceptResult,
34
+ } from './types.js';
35
+
36
+ // Config helpers (for advanced use)
37
+ export { toChain, DEFAULT_TAAL_API_KEYS, DEFAULT_DB_NAME } from './config.js';
38
+ export type { Chain } from './config.js';
39
+
40
+ // Lower-level helpers (for advanced use)
41
+ export { buildPayment } from './payment.js';
42
+ export { verifyPayment, acceptPayment } from './verify.js';
@@ -0,0 +1,17 @@
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>;
17
+ //# sourceMappingURL=payment.d.ts.map
@@ -0,0 +1,111 @@
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
+
8
+ import { Beef, Utils } from '@bsv/sdk';
9
+ import { randomBytesBase64, ScriptTemplateBRC29 } from '@bsv/wallet-toolbox';
10
+ import type { SetupWallet } from '@bsv/wallet-toolbox';
11
+ import type { PaymentParams, PaymentResult } from './types.js';
12
+ import type { CachedKeyDeriver } from '@bsv/sdk';
13
+
14
+ /**
15
+ * Build a BRC-29 payment transaction using the wallet's createAction API.
16
+ *
17
+ * The transaction is created with `acceptDelayedBroadcast: false` — the sender
18
+ * broadcasts immediately. The resulting Atomic BEEF and derivation metadata are
19
+ * returned so the recipient can verify and internalize the payment on their side.
20
+ */
21
+ export async function buildPayment(
22
+ setup: SetupWallet,
23
+ params: PaymentParams,
24
+ ): Promise<PaymentResult> {
25
+ const { to, satoshis, description } = params;
26
+ const desc = normalizeDescription(description ?? 'agent payment');
27
+
28
+ // Generate unique BRC-29 derivation prefixes and suffixes
29
+ const derivationPrefix = randomBytesBase64(8);
30
+ const derivationSuffix = randomBytesBase64(8);
31
+
32
+ // Build BRC-29 locking script
33
+ const keyDeriver = setup.keyDeriver as CachedKeyDeriver;
34
+ const t = new ScriptTemplateBRC29({
35
+ derivationPrefix,
36
+ derivationSuffix,
37
+ keyDeriver,
38
+ });
39
+
40
+ // Determine the recipient identity key.
41
+ // If `to` is a compressed public key hex (66 chars, starts with 02/03), use directly.
42
+ // Otherwise treat as an address — for BRC-29 we need a public key.
43
+ let recipientPubKey: string;
44
+ if (/^0[23][0-9a-fA-F]{64}$/.test(to)) {
45
+ recipientPubKey = to;
46
+ } else {
47
+ // If it's an address, we can't do BRC-29 (needs pubkey). Throw a clear error.
48
+ throw new Error(
49
+ 'PaymentParams.to must be a compressed public key (hex) for BRC-29 payments. ' +
50
+ 'Raw BSV addresses are not supported — the recipient must share their identity key.'
51
+ );
52
+ }
53
+
54
+ const lockingScript = t.lock(setup.rootKey.toString(), recipientPubKey);
55
+
56
+ const label = 'a2a-payment';
57
+ const car = await setup.wallet.createAction({
58
+ outputs: [
59
+ {
60
+ lockingScript: lockingScript.toHex(),
61
+ satoshis,
62
+ outputDescription: desc,
63
+ tags: ['relinquish'],
64
+ customInstructions: JSON.stringify({
65
+ derivationPrefix,
66
+ derivationSuffix,
67
+ type: 'BRC29',
68
+ }),
69
+ },
70
+ ],
71
+ options: {
72
+ randomizeOutputs: false,
73
+ acceptDelayedBroadcast: false,
74
+ },
75
+ labels: [label],
76
+ description: desc,
77
+ });
78
+
79
+ // Extract the txid from the createAction result.
80
+ // The tx field is a number[] (AtomicBEEF binary). Parse it to get txid.
81
+ if (!car.tx) {
82
+ throw new Error('createAction did not return a transaction. Check wallet funding.');
83
+ }
84
+
85
+ const beef = Beef.fromBinary(car.tx);
86
+ // The last transaction in the beef is our new tx
87
+ const lastTx = beef.txs[beef.txs.length - 1];
88
+ const txid = lastTx.txid;
89
+
90
+ // Encode the atomic BEEF as base64
91
+ const atomicBinary = beef.toBinaryAtomic(txid);
92
+ const beefBase64 = Utils.toBase64(atomicBinary);
93
+
94
+ return {
95
+ beef: beefBase64,
96
+ txid,
97
+ satoshis,
98
+ derivationPrefix,
99
+ derivationSuffix,
100
+ senderIdentityKey: setup.identityKey,
101
+ };
102
+ }
103
+
104
+ /**
105
+ * Ensure description meets BRC-100's 5-50 character requirement.
106
+ */
107
+ function normalizeDescription(desc: string): string {
108
+ if (desc.length < 5) return desc.padEnd(5, ' ');
109
+ if (desc.length > 50) return desc.slice(0, 50);
110
+ return desc;
111
+ }
@@ -0,0 +1,95 @@
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
+ }
95
+ //# sourceMappingURL=types.d.ts.map