sparkbtcbot CLAUDE.md

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
  spend-ledger.js                     # rolling-window cumulative budget (bounds send LOOPS)
  transfer-ids.js                     # persisted per-invoice Lightning dedup transferId (safe retries)
  recipients-allowlist.js             # opt-in outbound allowlist guardrail
  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
      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
      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, with checkable assertions
      trigger-eval.json               # Description-triggering queries (see NOTES: not measurable via claude -p here)
      NOTES.md                        # How to run (subagent output evals, with-skill vs baseline) + last results
tests/                                # vitest suite for the LIBRARY code (unit, integration, funded tiers)
.env.example                          # Environment variable template