{"_id":"@a2a-bsv/core","_rev":"2-b8079a2c5b65d05c0f0f1aa187f327db","name":"@a2a-bsv/core","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@a2a-bsv/core","version":"0.1.0","keywords":["bsv","blockchain","micropayments","agent","a2a","wallet"],"author":{"name":"Galt TR"},"license":"MIT","_id":"@a2a-bsv/core@0.1.0","maintainers":[{"name":"johngalt5","email":"dylan@murraydt.com"}],"homepage":"https://github.com/galt-tr/a2a-bsv#readme","bugs":{"url":"https://github.com/galt-tr/a2a-bsv/issues"},"dist":{"shasum":"680b02702bf5231f10766052ca41856b2728a4f6","tarball":"https://registry.npmjs.org/@a2a-bsv/core/-/core-0.1.0.tgz","fileCount":26,"integrity":"sha512-OtY+4f4zobb4TEpTXfn+whOpCzkmrB20T4jhtpRip/2OYMvowkLCyLKzKvHnzbygw0tpHUqeF2nwkai6P4xuDw==","signatures":[{"sig":"MEYCIQCskx9f2dg+i/8vPsixJVfqxM5KLcwA5ZiJldTskCRa9QIhAIJl9Szu3+LRytQpT+8wEVLel67TKhOBlpUPiFRNyhl4","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":52159},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"a60779c7651a895006120896bec9b34a7eb754e4","scripts":{"test":"npx tsx test/wallet.test.ts","build":"tsc","check":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"johngalt5","email":"dylan@murraydt.com"},"repository":{"url":"git+https://github.com/galt-tr/a2a-bsv.git","type":"git","directory":"packages/core"},"_npmVersion":"10.9.3","description":"BSV agent-to-agent payment library wrapping @bsv/sdk and @bsv/wallet-toolbox","directories":{},"_nodeVersion":"22.20.0","dependencies":{"knex":"^3.1.0","dotenv":"^17.2.3","@bsv/sdk":"^1.10.3","@bsv/wallet-toolbox":"^1.7.22"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/core_0.1.0_1769970771993_0.44774395249032684","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@a2a-bsv/core","version":"0.1.1","description":"BSV agent-to-agent payment library wrapping @bsv/sdk and @bsv/wallet-toolbox","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"scripts":{"build":"tsc","check":"tsc --noEmit","prepublishOnly":"npm run build","test":"npx tsx test/wallet.test.ts"},"repository":{"type":"git","url":"git+https://github.com/galt-tr/a2a-bsv.git","directory":"packages/core"},"keywords":["bsv","blockchain","micropayments","agent","a2a","wallet"],"author":{"name":"Galt TR"},"dependencies":{"@bsv/sdk":"^1.10.3","@bsv/wallet-toolbox":"^1.7.22","dotenv":"^17.2.3","knex":"^3.1.0"},"devDependencies":{"@types/node":"^22.0.0","typescript":"^5.7.0"},"license":"MIT","_id":"@a2a-bsv/core@0.1.1","gitHead":"c64b2a4b54adc4206fd90ef54b2720b7d8f1d3e8","bugs":{"url":"https://github.com/galt-tr/a2a-bsv/issues"},"homepage":"https://github.com/galt-tr/a2a-bsv#readme","_nodeVersion":"22.20.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-+dTwwxTbKZlVltszgIYMJi3f4wVhMzLo3CQLOdfohCMvNcc0gb35F89gslGBLrD2yxgkWb01qyidoo5Schwbfg==","shasum":"1f4993361e5678890d87d0ed886fdb1f0babaec7","tarball":"https://registry.npmjs.org/@a2a-bsv/core/-/core-0.1.1.tgz","fileCount":26,"unpackedSize":53049,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDzrTqeLXX83nkxDDYjF5TUogMFZ9AbyjjomobcpyTV6QIhAOIhgED1VaMLIwd87ZDCjwoSarVgTEv21A9PKNGzseFG"}]},"_npmUser":{"name":"johngalt5","email":"dylan@murraydt.com"},"directories":{},"maintainers":[{"name":"johngalt5","email":"dylan@murraydt.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/core_0.1.1_1770060816968_0.8423927822709283"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-01T18:32:51.875Z","modified":"2026-02-02T19:33:37.262Z","0.1.0":"2026-02-01T18:32:52.137Z","0.1.1":"2026-02-02T19:33:37.139Z"},"bugs":{"url":"https://github.com/galt-tr/a2a-bsv/issues"},"author":{"name":"Galt TR"},"license":"MIT","homepage":"https://github.com/galt-tr/a2a-bsv#readme","keywords":["bsv","blockchain","micropayments","agent","a2a","wallet"],"repository":{"type":"git","url":"git+https://github.com/galt-tr/a2a-bsv.git","directory":"packages/core"},"description":"BSV agent-to-agent payment library wrapping @bsv/sdk and @bsv/wallet-toolbox","maintainers":[{"name":"johngalt5","email":"dylan@murraydt.com"}],"readme":"# @a2a-bsv/core\n\nBSV agent-to-agent payment library. Wraps [`@bsv/sdk`](https://github.com/bsv-blockchain/ts-sdk) and [`@bsv/wallet-toolbox`](https://github.com/bsv-blockchain/wallet-toolbox) to provide exactly the operations AI agents need to pay each other on the BSV blockchain.\n\n## Features\n\n- **BRC-100 compliant wallet** backed by SQLite for local persistence\n- **BRC-29 payments** — privacy-preserving key derivation, no address reuse\n- **SPV verification** via Atomic BEEF transaction format\n- **noSend workflow** — sender builds the transaction, recipient verifies and broadcasts\n- **Clean API** — minimal surface area designed for automated agent use\n\n## Installation\n\n```bash\nnpm install @a2a-bsv/core\n```\n\n> Requires Node.js 18+ and SQLite3 (native dependency via `@bsv/wallet-toolbox`).\n\n## Quick Start\n\n```typescript\nimport { BSVAgentWallet } from '@a2a-bsv/core';\n\n// 1. Create wallets for two agents\nconst agentA = await BSVAgentWallet.create({\n  network: 'testnet',\n  storageDir: './wallet-agent-a',\n});\n\nconst agentB = await BSVAgentWallet.create({\n  network: 'testnet',\n  storageDir: './wallet-agent-b',\n});\n\nconst agentBKey = await agentB.getIdentityKey();\nconsole.log('Agent B identity:', agentBKey);\n\n// 2. Agent A builds a payment to Agent B (requires funded wallet)\nconst payment = await agentA.createPayment({\n  to: agentBKey,\n  satoshis: 500,\n  description: 'Payment for code review',\n});\n\n// 3. Agent B verifies the payment\nconst verification = await agentB.verifyPayment({\n  beef: payment.beef,\n});\n\n// 4. Agent B accepts (internalizes) the payment\nif (verification.valid) {\n  const receipt = await agentB.acceptPayment({\n    beef: payment.beef,\n    derivationPrefix: payment.derivationPrefix,\n    derivationSuffix: payment.derivationSuffix,\n    senderIdentityKey: payment.senderIdentityKey,\n    description: 'Code review payment received',\n  });\n  console.log('Payment accepted:', receipt.accepted);\n}\n\n// 5. Clean up\nawait agentA.destroy();\nawait agentB.destroy();\n```\n\n## API\n\n### `BSVAgentWallet`\n\n#### Factory Methods\n\n| Method | Description |\n|--------|-------------|\n| `BSVAgentWallet.create(config)` | Create a new wallet (generates keys, creates SQLite DB) |\n| `BSVAgentWallet.load(config)` | Load an existing wallet from storage |\n\n#### `WalletConfig`\n\n```typescript\ninterface WalletConfig {\n  network: 'mainnet' | 'testnet';\n  storageDir: string;      // Directory for SQLite DB and identity file\n  rootKeyHex?: string;     // Optional: provide your own root key\n  taalApiKey?: string;     // Optional: TAAL API key for ARC broadcasting\n}\n```\n\n#### Wallet Lifecycle\n\n| Method | Returns | Description |\n|--------|---------|-------------|\n| `getIdentityKey()` | `Promise<string>` | Compressed public key (hex) — share this with other agents |\n| `getBalance()` | `Promise<number>` | Balance in satoshis |\n| `destroy()` | `Promise<void>` | Close DB connections, stop monitor |\n\n#### Payments (Sender Side)\n\n```typescript\nconst payment = await wallet.createPayment({\n  to: recipientPublicKey,  // Compressed hex pubkey (required)\n  satoshis: 500,           // Amount in satoshis\n  description: 'Agent task payment',\n});\n```\n\nReturns a `PaymentResult`:\n\n```typescript\ninterface PaymentResult {\n  beef: string;               // Base64-encoded Atomic BEEF\n  txid: string;               // Transaction ID\n  satoshis: number;           // Amount paid\n  derivationPrefix: string;   // BRC-29 derivation info (send to recipient)\n  derivationSuffix: string;   // BRC-29 derivation info (send to recipient)\n  senderIdentityKey: string;  // Sender's identity key (send to recipient)\n}\n```\n\n> **Important:** The `derivationPrefix`, `derivationSuffix`, and `senderIdentityKey` MUST be transmitted to the recipient alongside the `beef`. These are needed for the recipient to claim the payment.\n\n#### Payments (Receiver Side)\n\n**Verify** (includes SPV verification):\n\n```typescript\nconst result = await wallet.verifyPayment({\n  beef: payment.beef,\n  expectedSender: senderKey,  // Optional\n});\n// result.valid, result.txid, result.errors\n```\n\n**Accept** (internalize into wallet):\n\n```typescript\nconst receipt = await wallet.acceptPayment({\n  beef: payment.beef,\n  vout: 0,                                    // Output index (default: 0)\n  derivationPrefix: payment.derivationPrefix,\n  derivationSuffix: payment.derivationSuffix,\n  senderIdentityKey: payment.senderIdentityKey,\n  description: 'Payment received',\n});\n// receipt.accepted\n```\n\n#### Advanced Access\n\n```typescript\n// Access underlying wallet-toolbox SetupWallet for advanced operations\nconst setup = wallet.getSetup();\n// setup.wallet — the BRC-100 Wallet instance\n// setup.rootKey — the root PrivateKey\n// setup.services — network Services\n// setup.storage — WalletStorageManager\n```\n\n## Architecture\n\n```\nBSVAgentWallet\n├── Wallet (BRC-100)          — from @bsv/wallet-toolbox\n│   ├── CachedKeyDeriver      — BRC-42 key derivation\n│   ├── WalletStorageManager   — manages storage providers\n│   │   └── StorageKnex       — SQLite via knex\n│   ├── Services               — ARC broadcasting, chain tracking\n│   └── Monitor                — background task processing\n└── ScriptTemplateBRC29        — BRC-29 payment scripts\n```\n\n### Payment Flow\n\n```\nAgent A (Payer)                          Agent B (Merchant)\n─────────────────                        ──────────────────\n1. createPayment(to=B, sat=500)\n   → builds BRC-29 tx (noSend)\n   → returns BEEF + derivation info\n                                    ──→\n2.                                       verifyPayment(beef)\n                                         → structural checks\n                                         → returns valid/errors\n\n3.                                       acceptPayment(beef, derivation)\n                                         → wallet.internalizeAction()\n                                         → SPV verification\n                                         → broadcasts to network\n                                         → output added to wallet\n```\n\n## Key Concepts\n\n### BRC-29 Key Derivation\nEach payment uses unique derivation prefixes and suffixes to generate a one-time key. This means:\n- No address reuse (privacy preserving)\n- Recipient needs the derivation info to claim the payment\n- The sender's identity key is also needed for key derivation\n\n### Atomic BEEF\nTransactions are packaged as Atomic BEEF (Background Evaluation Extended Format), which includes:\n- The payment transaction itself\n- All ancestor transactions needed for SPV verification\n- Merkle proofs linking to block headers\n\nThis allows the recipient to verify the payment without trusting any third party.\n\n### noSend Workflow\nThe sender builds and signs the transaction but does NOT broadcast it. Instead:\n1. The signed transaction (as Atomic BEEF) is sent directly to the recipient\n2. The recipient verifies it via SPV\n3. The recipient internalizes it (claiming the output and broadcasting)\n\nThis is the BRC-100 Direct Instant Payments (DIP) pattern.\n\n## Storage\n\nEach wallet creates:\n- `wallet-identity.json` — Contains the root key hex, identity key, and network\n- `a2a_agent_wallet.sqlite` — SQLite database with all wallet state\n\n> ⚠️ **Security:** The `wallet-identity.json` file contains the root private key. Guard it carefully in production.\n\n## Known Issues\n\n- **Wallet-toolbox bug:** `Setup.createWalletSQLite` has an internal `randomBytesHex` stub that throws. This library works around it by constructing wallet components manually.\n- **Funding required:** `createPayment()` requires the wallet to have spendable UTXOs. On testnet, use the [WitnessOnChain faucet](https://witnessonchain.com/faucet/tbsv) to fund your wallet. Track transactions on [WhatsonChain testnet](https://test.whatsonchain.com/) or [WhatsonChain mainnet](https://whatsonchain.com/).\n\n## Development\n\n```bash\n# Type check\nnpm run check\n\n# Build\nnpm run build\n\n# Test\nnpm test\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}