sparkbtcbot: Instructions file for Claude Code

sparkbtcbot

Claude Code skill for setting up Spark Bitcoin L2 wallet capabilities for AI agents.

Installation: the plugin marketplace, or clone anywhere (e.g. ~/sparkbtcbot) and symlink the nested skill: ln -s ~/sparkbtcbot/skills/sparkbtcbot ~/.claude/skills/sparkbtcbot. Never clone directly into ~/.claude/skills/ — the skill nests at skills/sparkbtcbot/, so a direct clone buries SKILL.md too deep to be discovered (README → Local clone).

What This Skill Does

Teaches Claude Code how to give AI agents Bitcoin capabilities using the Spark L2:

1. Initialize Wallet — Create or import a BIP39 mnemonic-based wallet
2. Check Balance — Query BTC and token balances
3. Receive Deposits — Generate L1 Bitcoin deposit addresses
4. Transfer BTC — Instant, zero-fee Spark-to-Spark transfers
5. Lightning Invoices — Create and pay BOLT11 invoices (Lightning Network interop)
6. Spark Invoices — Native Spark invoices payable in sats or tokens
7. Token Operations — Transfer BTKN/LRC20 tokens natively
8. Withdraw to L1 — Cooperative exit back to on-chain Bitcoin
9. Message Signing — Sign and verify messages for identity proof
10. Merchant Purchases — Buy real-world goods/services with sats (Bitrefill, nadanada) under a shared payment policy (references/merchant-spending.md): invoice-vs-quote guard, confirm-before-buy, PII consent, bearer-secret deliverables
11. Unilateral-Exit Backup — Continuously-fresh spark.unilateral-exit-bundle.v1 recovery bundle (the "leaf-vault"), consumed by Blink's spark-unilateral-exit tool if the operators ever vanish

Structure

lib/
  atomic-file.js                      # the one atomic writer (temp+fsync+link/rename+dir-fsync)
  encrypted-seed.js                   # scrypt + AES-256-GCM seed file helper
  leaf-vault.js                       # SDK-free recovery-bundle persistence + shape validation
  fee-guards.js                       # fee/amount ceilings for sends, claims, withdrawals
  l402-token.js                       # SDK-free: read the expiry a server signed into an L402 token (fetchL402 refuses dead ones)
  payment-outcome.js                  # PaymentCommittedError + the SDK's pre-send error list (pinned to the installed SDK)
  fiat-rate.js                        # BTC price from mempool.space + Coinbase, cross-checked (the number behind "$100")
  spend-ledger.js                     # rolling-window cumulative budget (bounds send LOOPS)
  transfer-ids.js                     # persisted per-invoice Lightning dedup transferId (safe retries)
  wallet-privacy.js                   # SDK-free: turn the operators' per-wallet privacy setting on (wallets are public by default)
  recipients-allowlist.js             # opt-in outbound allowlist guardrail
  wallet-options.js                   # sparkWalletOptions: every wallet opens with the SDK's fee ladders OFF (default ON since 0.13)
  index.js / index.d.ts               # npm entry (also exports ./leaf-vault subpaths)
skills/
  sparkbtcbot/
    SKILL.md                          # Always-loaded skill body (security, setup, navigator)
    references/                       # Detail loaded on demand (SDK API, agent class, L402, etc.)
      encrypted-seed.md               # Threat model, setup modes, recovery
      unilateral-exit.md              # The leaf-vault backup + Blink's exit tool
      first-spend.md                  # The product path: fiat invoice for a newbie → country-aware gift card sized under the balance
      supply-chain.md                 # When/how to offer npm hardening (moved out of SKILL.md for the size ratchet)
      recovery-scenarios.md           # Recovery properties (staleness, justice, economics)
    scripts/                          # Runnable example scripts
      cli.js                          # `sparkbtcbot <command>` — the single published bin (dispatcher)
      setup-encrypted-seed.js         # `npm run setup` — one-time bootstrap
      leaf-vault.js                   # snapshotLeafVault / verifyVault / enableLeafVault (library)
      leaf-vault-cli.js               # `npm run leaf-vault [-- verify]` — snapshot/verify CLI
      viewer-key.js                   # `sparkbtcbot viewer` — read-only access to a private wallet: status/grant(y/N)/revoke/pubkey/balance
      balance-and-deposits.js
      payment-flow.js
      token-operations.js
      spark-agent.js
      l402-paywalls.js
    evals/                            # Skill-quality evals (does the skill make Claude produce correct/safe code?)
      evals.json                      # Output evals: SDK-correctness + security-behavior + user-story (graded on the reply), with checkable assertions
      trigger-eval.json               # Description-triggering queries (see eval-notes/NOTES.md: not measurable via claude -p here)
eval-notes/                           # Eval run notes, kept out of the package: how to run + every run's results
  NOTES.md                            # How to run (subagent output evals, with-skill vs baseline) + results, newest at the bottom
  findings-*.md / rerun-*.md          # Per-run reports
tests/                                # vitest suite for the LIBRARY code (unit, integration, funded tiers)
.env.example                          # Environment variable template