@blackpool/cli 0.3.0 → 0.4.0

package/AGENTS.md

@@ -119,7 +119,7 @@ Without `--pool` (one entry per chain; `--chain all` returns four):
 A value of `"?"` with an `error` field means that read failed; retry.
 
 ### `deposit <amount> [--pool P] [--chain C]`
-Shield public funds from the agent wallet. ERC-20 pools approve first (one extra transaction). Needs native gas. ~30–90 s.
+Shield public funds from the agent wallet. ERC-20 pools approve first (one extra transaction). Needs native gas. ~10–30 s (the first run also downloads the 20 MB proving key).
 ```json
 {"ok":true,"command":"deposit","chain":"base","pool":"usdc","amount":25,"symbol":"USDC",
  "txHash":"0x…","explorer":"https://basescan.org/tx/0x…","privateBalance":"25.0"}
@@ -127,7 +127,7 @@ Shield public funds from the agent wallet. ERC-20 pools approve first (one extra
 `--pool` defaults to the chain's stablecoin pool.
 
 ### `send <recipient> <amount> [--pool P] [--chain C]`
-Private payment to any EVM address on the same chain. `amount` is what leaves your private balance; the recipient gets `amount − fee`. No gas needed. ~30–90 s.
+Private payment to any EVM address on the same chain. `amount` is what leaves your private balance; the recipient gets `amount − fee`. No gas needed. ~10–30 s.
 ```json
 {"ok":true,"command":"send","chain":"base","pool":"usdc","recipient":"0x…","amount":10,
  "received":"8.965","fee":"1.035","symbol":"USDC","txHash":"0x…","explorer":"https://basescan.org/tx/0x…"}
@@ -441,7 +441,7 @@ Use the hosted server to plan (fees, routes, quotes, status) and the local serve
 
 - **Dedicated agent wallet.** Fund it with only what the agent may spend. Never use a personal or treasury key.
 - `BLACKPOOL_KEY` never leaves the machine: it signs the sign-in message, deposit approvals and deposit transactions locally.
-- The **sign-in signature** is cached in `$BLACKPOOL_HOME/config.json` (mode 600) and sent to the API with each private operation. The API derives the private account keys from it in memory to build the proof and does not store or log it, but anyone holding that signature can spend the agent's private balance. Treat the config directory like a key: never print it, never put it in prompts, logs or tool output.
+- The **sign-in signature** is cached in `$BLACKPOOL_HOME/config.json` (mode 600) and never sent anywhere: keys, note scanning and proofs are computed locally (CLI 0.4.0+), and the relayer receives finished proofs only. Anyone holding that signature can spend the agent's private balance. Treat the config directory like a key: never print it, never put it in prompts, logs or tool output.
 - Only sign the Blackpool sign-in message on blackpool.cash or with this CLI.
 - The contracts and circuits have not been externally audited; pools are upgradeable by an admin key during launch. Size balances accordingly. Details: https://blackpool.cash/docs#security
 - Report vulnerabilities privately to hello@blackpool.cash (subject `security`).
@@ -450,7 +450,7 @@ Use the hosted server to plan (fees, routes, quotes, status) and the local serve
 
 ## 14. Direct API (advanced)
 
-The CLI is the supported interface. If you cannot run Node.js, the same operations are HTTP calls on `https://api.blackpool.cash` (`/api/balance`, `/api/deposit/prepare`, `/api/withdraw`, `/api/swap-private`, `/api/bridge/quote`, `/api/swap`, `/api/intents`, `/api/burner/*`, `/api/health`), all JSON. They need the sign-in signature (EIP-191 signature of the exact message below by the agent wallet), and deposits need you to sign and broadcast the returned transaction yourself. Endpoint list: https://blackpool.cash/docs#api
+The CLI is the supported interface: it derives keys and generates Groth16 proofs locally. A client in another language must do the same (see `cli/lib/zk.js`): read public pool data from `GET /api/zk/pool`, derive keys from the EIP-191 signature of the exact message below, prove with the published circuit (`https://blackpool.cash/zk/manifest.json`), then post the proof to `POST /api/relay`, or broadcast a deposit from its own wallet. The API never accepts the signature itself. Endpoint list: https://blackpool.cash/docs#api
 
 ```text
 Welcome to Blackpool

package/README.md

@@ -24,7 +24,7 @@ blackpool login
 # ✓ wallet stored at ~/.blackpool/wallet.json (chmod 600)
 ```
 
-The key is prompted with **hidden input** (no echo, never enters shell history), then stored locally at `~/.blackpool/wallet.json` with `chmod 600` (owner-only). It is never transmitted - only the derived signature is sent to the relayer.
+The key is prompted with **hidden input** (no echo, never enters shell history), then stored locally at `~/.blackpool/wallet.json` with `chmod 600` (owner-only). It is never transmitted, and neither is the sign-in signature: keys and proofs are computed on your machine.
 
 ### Env var (agents / CI) - no prompt
 
@@ -72,7 +72,7 @@ blackpool recover --to 0xADDR                # sweep to a different destination
 
 Each command follows the pattern `docs.blackpool.cash/agents` documents.
 
-**Login / balance / send / bridge** - you sign once, the relayer builds the Groth16 proof server-side, and broadcasts. You pay no gas. The relayer is compensated via the protocol fee (flat + 0.35% per withdraw / swap / bridge).
+**Login / balance / send / bridge** - you sign once; the CLI scans your notes and builds the Groth16 proof locally (the 20 MB proving key is downloaded once to `~/.blackpool/zk/`), then the relayer broadcasts it. You pay no gas. The relayer is compensated via the protocol fee (flat + 0.35% per withdraw / swap / bridge).
 
 **Deposit** - your public wallet signs and broadcasts the shield tx (this is the only step where you pay gas, because the pool must see funds coming from a public address). For ERC-20 pools (USDC), an `approve` runs first; the CLI polls the on-chain allowance before broadcasting the deposit (same fix as the frontend for load-balanced RPC lag).
 
@@ -103,6 +103,7 @@ If any step fails between (2) and (7), funds remain on the burner; its key is in
 
 - `~/.blackpool/wallet.json` - stored private key (chmod 600, only if you used `blackpool login` interactively).
 - `~/.blackpool/config.json` - cached BLACKPOOL signatures per wallet (chmod 600).
+- `~/.blackpool/zk/` - public proving key files, verified against the published SHA-256.
 
 ## Verified live on Base mainnet
 

package/bin/blackpool.js

@@ -175,7 +175,48 @@ async function ensureSignature(wallet, { forceNew = false } = {}) {
 }
 
 // === HTTP ===
+// === local proving ===
+// Balance scans, deposits, payments and swaps are computed on this machine (lib/localApi.js): keys come from
+// the cached sign-in signature, proofs from the circuit files in <BLACKPOOL_HOME>/zk/. The API only receives
+// finished proofs (POST /api/relay) and serves public pool data, so the signature never leaves this machine.
+let LOCAL = null
+function localApi() {
+  if (LOCAL) return LOCAL
+  const { createLocalApi } = require('../lib/localApi')
+  const { createCircuitLoader } = require('../lib/circuit')
+  const UA = `blackpool-cli/${require('../package.json').version}`
+  const request = async (method, endpoint, body) => {
+    for (let attempt = 0; ; attempt++) {
+      const r = await fetch(`${API}${endpoint}`, {
+        method, headers: { 'Content-Type': 'application/json', 'User-Agent': UA },
+        body: method === 'GET' ? undefined : JSON.stringify(body || {}), signal: AbortSignal.timeout(120_000),
+      })
+      let json = {}
+      try { json = await r.json() } catch {}
+      if (r.status === 429 && attempt < 4) {
+        const wait = Math.min(Math.max(Number(json?.retryAfter) || 5, 1), 30)
+        info(`rate limited by the API, retrying in ${wait}s...`)
+        await new Promise((res) => setTimeout(res, wait * 1000)); continue
+      }
+      if (!r.ok) throw Object.assign(new Error(json?.error || `HTTP ${r.status}`), { status: r.status })
+      return json
+    }
+  }
+  let said = false
+  LOCAL = createLocalApi({
+    request,
+    loadCircuit: createCircuitLoader({ dir: path.join(CONFIG_DIR, 'zk'), userAgent: UA }),
+    onProgress: (p) => {
+      if (p.stage === 'download') info(`downloading proving key (${p.file}, ${Math.round((p.bytes || 0) / 1e6)} MB, first run only)...`)
+      if (p.stage === 'prove' && !said) { info('generating zero-knowledge proof locally...'); said = true }
+    },
+  })
+  return LOCAL
+}
+
 async function apiPost(endpoint, body, opts = {}) {
+  if (localApi().handles(endpoint)) return localApi().handle(endpoint, body)
+  if (body && 'signature' in body) { body = { ...body }; delete body.signature } // never sent to the API
   for (let attempt = 0; ; attempt++) {
     try { return await apiPostOnce(endpoint, body, opts) }
     catch (e) {
@@ -636,7 +677,7 @@ async function cmdDeposit(args) {
   log(color(`  shielding ${amount} ${pool.toUpperCase()} on ${C.label}`, c.bold))
   log(color(`  from public wallet ${wallet.address}`, c.dim))
   log('')
-  info('preparing deposit... proof generation can take ~60-90 seconds')
+  info('preparing deposit (the proof is generated on this machine)...')
 
   const prep = await apiPost('/api/deposit/prepare', {
     signature: sig, address: wallet.address, amount: n, pool, chain,

package/lib/circuit.js

@@ -0,0 +1,54 @@
+'use strict'
+// Proving-key loader for Node (CLI and its MCP server). Downloads the Groth16 circuit files once from the
+// published manifest, verifies their SHA-256 and keeps them in <BLACKPOOL_HOME>/zk/. These files are public
+// (the same ones the pool verifier was generated from); nothing secret is written.
+const fs = require('fs')
+const path = require('path')
+const crypto = require('crypto')
+
+const MANIFEST_URL = process.env.BLACKPOOL_ZK_MANIFEST || 'https://blackpool.cash/zk/manifest.json'
+
+function sha256(buf) { return crypto.createHash('sha256').update(buf).digest('hex') }
+
+function createCircuitLoader({ dir, userAgent = 'blackpool-cli' }) {
+  let cached = null
+  return async function loadCircuit(onProgress = () => {}) {
+    if (cached) return cached
+    fs.mkdirSync(dir, { recursive: true })
+    const local = (name) => path.join(dir, name)
+    let manifest
+    try {
+      const r = await fetch(MANIFEST_URL, { headers: { 'User-Agent': userAgent }, signal: AbortSignal.timeout(30_000) })
+      if (!r.ok) throw new Error(`HTTP ${r.status}`)
+      manifest = await r.json()
+      fs.writeFileSync(local('manifest.json'), JSON.stringify(manifest))
+    } catch (e) {
+      // offline: fall back to the last manifest whose files are already here
+      if (!fs.existsSync(local('manifest.json'))) throw new Error(`cannot fetch the proving-key manifest (${e.message})`)
+      manifest = JSON.parse(fs.readFileSync(local('manifest.json'), 'utf8'))
+    }
+    const out = {}
+    for (const kind of ['wasm', 'zkey']) {
+      const f = manifest[kind]
+      const name = path.basename(f.path)
+      const file = local(name)
+      let buf = fs.existsSync(file) ? fs.readFileSync(file) : null
+      if (!buf || sha256(buf) !== f.sha256) {
+        onProgress({ stage: 'download', file: kind, bytes: f.bytes })
+        const url = new URL(f.path, MANIFEST_URL).toString()
+        const r = await fetch(url, { headers: { 'User-Agent': userAgent }, signal: AbortSignal.timeout(300_000) })
+        if (!r.ok) throw new Error(`download ${name}: HTTP ${r.status}`)
+        buf = Buffer.from(await r.arrayBuffer())
+        if (sha256(buf) !== f.sha256) throw new Error(`download ${name}: checksum mismatch`)
+        fs.writeFileSync(file + '.tmp', buf)
+        fs.renameSync(file + '.tmp', file)
+        for (const old of fs.readdirSync(dir)) if (old !== name && old.endsWith('.' + kind)) fs.rmSync(local(old), { force: true })
+      }
+      out[kind] = new Uint8Array(buf)
+    }
+    cached = out
+    return out
+  }
+}
+
+module.exports = { createCircuitLoader, MANIFEST_URL }

package/lib/localApi.js

@@ -0,0 +1,197 @@
+'use strict'
+// Local replacements for the five endpoints that used to receive the sign-in signature.
+//
+// createLocalApi() returns handle(path, body) for:
+//   /api/balance  /api/withdraw  /api/deposit/prepare  /api/swap  /api/swap-private
+// with the SAME request and response shapes the server used, so callers (web app, CLI, MCP server) only swap the
+// transport. The signature is used here, in memory, to derive keys; it is never sent anywhere. Proofs are made
+// locally and only the finished proof goes to /api/relay. Nothing is persisted by this module.
+const { utils: U, Wallet } = require('ethers') // v5
+const zk = require('./zk')
+
+const LOCAL_PATHS = new Set(['/api/balance', '/api/withdraw', '/api/deposit/prepare', '/api/swap', '/api/swap-private'])
+const REGISTRY_AUTH_DOMAIN = 'blackpool/registry-auth/v1'
+const REGISTRY_AUTH_MESSAGE = 'Blackpool Registry\n\nAuthorize access to your encrypted recovery data.\nThis does not move funds and does not expose your account keys.'
+const ERC20 = new U.Interface(['function approve(address,uint256) returns (bool)'])
+
+/** Same derivation as the burner/intent registries: owner = address(keccak256(sig || domain)). */
+function registryAuthSig(signInSig) {
+  const key = U.keccak256(U.concat([U.arrayify(signInSig), U.toUtf8Bytes(REGISTRY_AUTH_DOMAIN)]))
+  return new Wallet(key).signMessage(REGISTRY_AUTH_MESSAGE)
+}
+
+/**
+ * request(method, path, body) -> parsed JSON; must throw Error(message) on a non-2xx answer.
+ * loadCircuit(onProgress) -> { wasm, zkey } (Uint8Array or file paths), loaded once by the caller.
+ */
+function createLocalApi({ request, loadCircuit, snarkjs, singleThread = false, onProgress = () => {} }) {
+  const mem = { config: null, configAt: 0, keys: new Map(), pending: new Map() }
+
+  async function config() {
+    if (!mem.config || Date.now() - mem.configAt > 5 * 60_000) { mem.config = await request('GET', '/api/zk/config'); mem.configAt = Date.now() }
+    return mem.config
+  }
+  async function keysFor(signature) {
+    let k = mem.keys.get(signature)
+    if (!k) { k = await zk.deriveKeys(signature); mem.keys.set(signature, k) }
+    return k
+  }
+  async function poolOf({ chain, pool, fromAsset }) {
+    const cfg = await config()
+    let key = chain && pool ? `${String(chain).toLowerCase()}:${String(pool).toLowerCase()}` : null
+    if (!key && fromAsset) key = Object.keys(cfg.pools).find((k) => cfg.pools[k].oneClickAsset === fromAsset) || null
+    if (!key) key = `${String(chain || 'base').toLowerCase()}:${String(pool || 'eth').toLowerCase()}`
+    const P = cfg.pools[key]
+    if (!P) throw new Error('unknown pool')
+    return { key, ...P, feeRecipient: cfg.feeRecipient }
+  }
+  const units = (P, v) => BigInt(U.parseUnits(String(v), P.decimals).toString())
+  const fmt = (P, v) => U.formatUnits(v.toString(), P.decimals)
+
+  async function account(keys, P) {
+    onProgress({ stage: 'scan', pool: P.key })
+    const data = await request('GET', `/api/zk/pool?chain=${P.chain}&pool=${P.pool}`)
+    const indexed = new Set(data.nullifiers.map((n) => n.toLowerCase()))
+    const pend = mem.pending.get(P.key) || new Set()
+    for (const n of pend) if (indexed.has(n)) pend.delete(n)
+    return zk.loadAccount({ keys, poolData: { root: data.root, entries: data.entries, nullifiers: [...data.nullifiers, ...pend] } })
+  }
+  async function proofFor(tx) {
+    onProgress({ stage: 'circuit' })
+    const circuit = await loadCircuit(onProgress)
+    onProgress({ stage: 'prove' })
+    const proof = await zk.prove(tx.circuitInput, { ...circuit, snarkjs, singleThread })
+    return { ...proof, ...tx.publicArgs }
+  }
+  async function relay(P, tx, purpose, extra = {}) {
+    const args = await proofFor(tx)
+    onProgress({ stage: 'relay' })
+    const r = await request('POST', '/api/relay', { chain: P.chain, pool: P.pool, args, extData: tx.extData, purpose, ...extra })
+    const set = mem.pending.get(P.key) || new Set()
+    for (const n of tx.publicArgs.inputNullifiers) set.add(n.toLowerCase())
+    mem.pending.set(P.key, set)
+    return r
+  }
+  // A second spend in the same session needs the first one's change note in the tree.
+  async function waitIndexed(P, nullifiers, timeoutMs = 90_000) {
+    const want = nullifiers.map((n) => n.toLowerCase())
+    const until = Date.now() + timeoutMs
+    while (Date.now() < until) {
+      const d = await request('GET', `/api/zk/pool?chain=${P.chain}&pool=${P.pool}`)
+      const have = new Set(d.nullifiers.map((n) => n.toLowerCase()))
+      if (want.every((n) => have.has(n))) return
+      await new Promise((r) => setTimeout(r, 3000))
+    }
+    throw new Error('timed out waiting for the indexer; your first payment went through, retry the second')
+  }
+  function friendly(e, P) {
+    if (e.code === 'TOO_SMALL') return new Error(`amount must be more than twice the fee (${fmt(P, e.minimum)} ${P.symbol})`)
+    if (e.code === 'FRAGMENTED') return new Error(`max ${fmt(P, e.maxSpendable)} per transaction (funds split across several notes; spend the rest separately)`)
+    if (e.code === 'INSUFFICIENT') return new Error(`insufficient balance: have ${fmt(P, e.maxSpendable)}`)
+    return e
+  }
+
+  const handlers = {
+    async '/api/balance'(b) {
+      const P = await poolOf(b)
+      const acc = await account(await keysFor(b.signature), P)
+      return { balance: fmt(P, acc.balance), symbol: P.symbol, utxoCount: acc.notes.length, utxos: acc.notes.map((n) => fmt(P, n.amount)) }
+    },
+
+    async '/api/withdraw'(b) {
+      const P = await poolOf(b)
+      const keys = await keysFor(b.signature)
+      const list = Array.isArray(b.recipients) && b.recipients.length ? b.recipients.map((r) => ({ address: r.address, amount: r.amount })) : [{ address: b.recipient, amount: b.amount }]
+      if (list.length > 2) throw new Error('max 2 recipients (circuit 2-output constraint)')
+      for (const r of list) {
+        if (!r.address || !/^0x[a-fA-F0-9]{40}$/.test(r.address)) throw new Error(`invalid recipient address: ${r.address || '(empty)'}`)
+        if (!r.amount || isNaN(Number(r.amount)) || Number(r.amount) <= 0) throw new Error(`invalid amount for ${r.address}`)
+      }
+      const results = []
+      for (let i = 0; i < list.length; i++) {
+        if (i > 0) await waitIndexed(P, results[i - 1]._nullifiers)
+        const acc = await account(keys, P)
+        if (!acc.notes.length) throw new Error('no unspent UTXOs')
+        let tx
+        try { tx = await zk.prepareWithdraw({ keys, account: acc, amount: units(P, list[i].amount), recipient: list[i].address, flatFeeWei: P.flatFeeWei, feeRecipient: P.feeRecipient }) }
+        catch (e) { throw friendly(e, P) }
+        const r = await relay(P, tx, 'withdraw')
+        results.push({ ...r, _nullifiers: tx.publicArgs.inputNullifiers })
+      }
+      const clean = results.map(({ _nullifiers, ...r }) => r)
+      return clean.length === 1 ? clean[0] : { success: clean.every((x) => x.success), transfers: clean }
+    },
+
+    async '/api/deposit/prepare'(b) {
+      if (!b.address || !b.amount) throw new Error('missing address/amount')
+      const P = await poolOf(b)
+      const keys = await keysFor(b.signature)
+      const acc = await account(keys, P)
+      const amount = units(P, b.amount)
+      const tx = await zk.prepareDeposit({ keys, account: acc, amount, depositor: b.address, feeRecipient: P.feeRecipient })
+      const args = await proofFor(tx)
+      const resp = {
+        to: P.address,
+        data: zk.encodeTransact(args, tx.extData),
+        value: P.isNative ? amount.toString() : '0',
+        newBalance: fmt(P, tx.newBalance),
+        symbol: P.symbol,
+      }
+      if (!P.isNative) {
+        const a = await request('GET', `/api/zk/allowance?chain=${P.chain}&pool=${P.pool}&owner=${b.address}`)
+        if (BigInt(a.allowance) < amount) resp.approveTx = { to: P.token, data: ERC20.encodeFunctionData('approve', [P.address, amount.toString()]), value: '0' }
+      }
+      return resp
+    },
+
+    async '/api/swap'(b) {
+      if (!b.signature) throw new Error('missing signature')
+      const q = await request('POST', '/api/swap/quote', {
+        fromAsset: b.fromAsset, toAsset: b.toAsset, amount: b.amount, recipient: b.recipient, refundTo: b.refundTo, slippage: b.slippage,
+        ...(b.chain && b.pool ? { chain: b.chain, pool: b.pool } : {}),
+      })
+      const P = await poolOf({ chain: q.chain, pool: q.pool })
+      const keys = await keysFor(b.signature)
+      const acc = await account(keys, P)
+      if (!acc.notes.length) throw new Error(`your private ${P.symbol} balance on ${P.chain} is empty — switch to the pool that holds your funds, or deposit ${P.symbol} first`)
+      let tx
+      try { tx = await zk.prepareWithdraw({ keys, account: acc, amount: BigInt(q.amountWei), recipient: q.depositAddress, flatFeeWei: P.flatFeeWei, feeRecipient: P.feeRecipient }) }
+      catch (e) { throw friendly(e, P) }
+      const r = await relay(P, tx, 'swap', { authSig: await registryAuthSig(b.signature) })
+      return { success: r.success, txHash: r.txHash, depositAddress: r.depositAddress, amountOut: r.amountOut, timeEstimate: r.timeEstimate, statusUrl: r.statusUrl }
+    },
+
+    async '/api/swap-private'(b) {
+      if (!b.burnerAddress || !/^0x[a-fA-F0-9]{40}$/.test(b.burnerAddress)) throw new Error('invalid burnerAddress')
+      if (!b.amount || isNaN(Number(b.amount)) || Number(b.amount) <= 0) throw new Error('invalid amount')
+      const P = await poolOf(b)
+      const keys = await keysFor(b.signature)
+      const acc = await account(keys, P)
+      if (!acc.notes.length) throw new Error('no unspent UTXOs')
+      let tx
+      try { tx = await zk.prepareWithdraw({ keys, account: acc, amount: units(P, b.amount), recipient: b.burnerAddress, flatFeeWei: P.flatFeeWei, feeRecipient: P.feeRecipient }) }
+      catch (e) { throw friendly(e, P) }
+      const r = await relay(P, tx, 'swap-private')
+      if (!r.success) throw new Error('withdraw to burner failed')
+      return {
+        success: true, step: 'withdrawn_to_burner', txHash: r.txHash, burnerAddress: b.burnerAddress, originToken: P.symbol,
+        originIsNative: !!P.isNative, burnerReceives: fmt(P, tx.receives), burnerReceivesEth: P.isNative ? fmt(P, tx.receives) : undefined,
+        gasReserveEth: String(b.gasBuffer || '0.00005'), needsGasTopup: !P.isNative, fee: fmt(P, tx.fee),
+      }
+    },
+  }
+
+  return {
+    handles: (path) => LOCAL_PATHS.has(path),
+    async handle(path, body) {
+      const h = handlers[path]
+      if (!h) throw new Error(`no local handler for ${path}`)
+      if (!body || !body.signature) throw new Error('missing signature')
+      return h(body)
+    },
+    /** Forget every key derived in this session. */
+    forget() { mem.keys.clear(); mem.pending.clear() },
+  }
+}
+
+module.exports = { createLocalApi, LOCAL_PATHS, registryAuthSig, REGISTRY_AUTH_MESSAGE }

package/lib/zk.js

@@ -0,0 +1,356 @@
+'use strict'
+// Blackpool client-side zero-knowledge core.
+//
+// Runs unchanged in Node (the CLI and its MCP server) and in the browser (bundled into the web app's proving
+// worker). Key derivation, note scanning, Merkle paths, coin selection and Groth16 proving all happen here, on
+// the user's device. The relayer only ever receives a finished proof and its public data — never the sign-in
+// signature, the keys or the notes. Nothing in this module writes to disk or to any browser storage: every
+// secret lives in the caller's memory for as long as the caller keeps it.
+const { utils: U, BigNumber } = require('ethers') // ethers v5 (CLI dependency; bundled for the browser)
+const { poseidon1, poseidon2, poseidon3, poseidon4 } = require('poseidon-lite')
+
+const FIELD_SIZE = 21888242871839275222246405745257275088548364400416034343698204186575808495617n
+const TREE_HEIGHT = 26
+// Merkle zeros(0) of every Blackpool pool: keccak256("privacyblackpool") % FIELD_SIZE.
+const ZERO_LEAF = 13957331740549083428539157647087363326246483135047439495076507042642183216086n
+const FEE_RATE_BPS = 35n // must match the relayer
+
+const SIGN_IN_MESSAGE =
+  'Welcome to Blackpool\n\nSign this message to access your private account.\n\n- Gas free: no transaction is sent\n- Your private account keys are derived from this signature\n- It cannot move funds from your wallet or approve spending\n- Only sign it on blackpool.cash or the Blackpool CLI'
+
+const POOL_ABI = [
+  'function transact((uint256[2] pA,uint256[2][2] pB,uint256[2] pC,bytes32 root,bytes32[2] inputNullifiers,bytes32[2] outputCommitments,uint256 publicAmount,bytes32 extDataHash) _args,(address recipient,int256 extAmount,address feeRecipient,uint256 fee,bytes encryptedOutput1,bytes encryptedOutput2) _extData) payable',
+  'function isKnownRoot(bytes32) view returns (bool)',
+]
+const POOL_IFACE = new U.Interface(POOL_ABI)
+
+// ---------- primitives ----------
+
+function webcrypto() {
+  if (globalThis.crypto && globalThis.crypto.subtle) return globalThis.crypto
+  return require('crypto').webcrypto // Node 18
+}
+
+const big = (x) => (typeof x === 'bigint' ? x : BigInt(BigNumber.from(x).toString()))
+const mod = (x) => ((x % FIELD_SIZE) + FIELD_SIZE) % FIELD_SIZE
+
+function poseidon(items) {
+  const f = [null, poseidon1, poseidon2, poseidon3, poseidon4][items.length]
+  if (!f) throw new Error(`unsupported poseidon arity ${items.length}`)
+  return f(items.map((x) => (typeof x === 'bigint' ? x : big(x))))
+}
+
+/** 0x-prefixed, zero-padded hex. Negative numbers become '-0x…' (how ethers v5 reads signed ints). */
+function toHex(x, bytes = 32) {
+  const v = big(x)
+  const h = (v < 0n ? -v : v).toString(16).padStart(bytes * 2, '0')
+  return (v < 0n ? '-0x' : '0x') + h
+}
+
+function randomField(nbytes = 31) {
+  const b = new Uint8Array(nbytes)
+  webcrypto().getRandomValues(b)
+  return BigInt(U.hexlify(b))
+}
+
+function randomPrivkey() {
+  const b = new Uint8Array(32)
+  webcrypto().getRandomValues(b)
+  return U.hexlify(b)
+}
+
+// ---------- keys ----------
+
+class Keypair {
+  constructor(privkey = randomPrivkey()) {
+    this.privkey = privkey
+    this.pubkey = poseidon([privkey])
+  }
+  sign(commitment, index) {
+    return poseidon([this.privkey, commitment, index])
+  }
+}
+
+/**
+ * Keys of a private account, derived from the sign-in signature exactly as before:
+ * encryptionKey = keccak256(signature), utxoPrivateKey = keccak256(encryptionKey).
+ */
+async function deriveKeys(signature) {
+  if (!/^0x[0-9a-fA-F]{130}$/.test(String(signature))) throw new Error('invalid sign-in signature')
+  const encKeyHex = U.keccak256(signature)
+  const encKey = U.arrayify(encKeyHex)
+  const keypair = new Keypair(U.keccak256(encKey))
+  const aesKey = await webcrypto().subtle.importKey('raw', encKey, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt'])
+  return { keypair, aesKey, pubkey: toHex(keypair.pubkey) }
+}
+
+// AES-256-GCM in the format the pools have always used: IV(12) || tag(16) || ciphertext.
+async function encrypt(aesKey, text) {
+  const iv = new Uint8Array(12)
+  webcrypto().getRandomValues(iv)
+  const out = new Uint8Array(await webcrypto().subtle.encrypt({ name: 'AES-GCM', iv, tagLength: 128 }, aesKey, new TextEncoder().encode(text)))
+  const ct = out.slice(0, out.length - 16)
+  const tag = out.slice(out.length - 16)
+  return U.hexlify(U.concat([iv, tag, ct]))
+}
+
+async function decrypt(aesKey, hex) {
+  const buf = U.arrayify(hex)
+  if (buf.length < 29) throw new Error('ciphertext too short')
+  const iv = buf.slice(0, 12)
+  const tag = buf.slice(12, 28)
+  const ct = buf.slice(28)
+  const plain = await webcrypto().subtle.decrypt({ name: 'AES-GCM', iv, tagLength: 128 }, aesKey, U.concat([ct, tag]))
+  return new TextDecoder().decode(plain)
+}
+
+// ---------- notes ----------
+
+class Note {
+  constructor({ amount = 0n, keypair = new Keypair(), blinding = randomField(), index = null, mint = 0n } = {}) {
+    this.amount = big(amount)
+    this.keypair = keypair
+    this.blinding = big(blinding)
+    this.index = index
+    this.mint = big(mint)
+  }
+  commitment() {
+    return poseidon([this.amount, this.keypair.pubkey, this.blinding, this.mint])
+  }
+  nullifier() {
+    if (this.amount > 0n && this.index == null) throw new Error('nullifier needs the note index')
+    const c = this.commitment()
+    const i = BigInt(this.index || 0)
+    return poseidon([c, i, this.keypair.sign(c, i)])
+  }
+  encrypt(aesKey) {
+    return encrypt(aesKey, `${this.amount}|${this.blinding}|${this.index || 0}|${this.mint}`)
+  }
+}
+
+/**
+ * Find this account's unspent notes in a pool.
+ * entries: [{ index, commitment, encryptedOutput }] (public, from the indexer)
+ * spent:   Set of spent nullifiers as lowercase 0x-hex (public NewNullifier events)
+ */
+async function scanNotes({ keys, entries, spent }) {
+  const mine = []
+  for (const e of entries) {
+    let parts
+    try { parts = (await decrypt(keys.aesKey, e.encryptedOutput)).split('|') } catch { continue }
+    if (parts.length !== 4) continue
+    let note
+    try {
+      note = new Note({ amount: BigInt(parts[0]), blinding: BigInt(parts[1]), keypair: keys.keypair, index: Number(e.index), mint: BigInt(parts[3]) })
+    } catch { continue }
+    if (note.amount === 0n) continue
+    if (toHex(note.commitment()) !== toHex(e.commitment)) continue
+    if (spent && spent.has(toHex(note.nullifier()).toLowerCase())) continue
+    mine.push(note)
+  }
+  return mine
+}
+
+// ---------- Merkle tree (height 26, Poseidon, Blackpool zero leaf) ----------
+
+const ZEROS = (() => {
+  const z = [ZERO_LEAF]
+  for (let i = 1; i <= TREE_HEIGHT; i++) z.push(poseidon([z[i - 1], z[i - 1]]))
+  return z
+})()
+
+/** Builds every non-empty layer once; path() is then O(height). leaves are in index order. */
+function buildTree(leaves) {
+  const layers = [leaves.map(big)]
+  for (let level = 0; level < TREE_HEIGHT; level++) {
+    const cur = layers[level]
+    const next = []
+    for (let i = 0; i < cur.length; i += 2) next.push(poseidon([cur[i], i + 1 < cur.length ? cur[i + 1] : ZEROS[level]]))
+    layers.push(next)
+  }
+  const root = layers[TREE_HEIGHT].length ? layers[TREE_HEIGHT][0] : ZEROS[TREE_HEIGHT]
+  return {
+    root,
+    size: leaves.length,
+    path(index) {
+      if (index < 0 || index >= leaves.length) throw new Error(`leaf ${index} not in tree`)
+      const pathElements = []
+      let idx = index
+      for (let level = 0; level < TREE_HEIGHT; level++) {
+        const sib = idx ^ 1
+        pathElements.push(sib < layers[level].length ? layers[level][sib] : ZEROS[level])
+        idx >>= 1
+      }
+      return pathElements
+    },
+  }
+}
+
+// ---------- fees and coin selection ----------
+
+/** The relayer fee for spending `gross` out of the pool (same formula the relayer enforces). */
+function relayFee(gross, flatFeeWei) {
+  return big(flatFeeWei) + (big(gross) * FEE_RATE_BPS) / 10000n
+}
+
+/** The 2-in circuit can spend at most two notes; take the two largest. */
+function pickInputs(notes, amount) {
+  const sorted = [...notes].sort((a, b) => (a.amount < b.amount ? 1 : a.amount > b.amount ? -1 : 0))
+  const inputs = sorted.slice(0, 2)
+  const sum = inputs.reduce((s, n) => s + n.amount, 0n)
+  const total = notes.reduce((s, n) => s + n.amount, 0n)
+  if (sum < big(amount)) {
+    const err = new Error(total >= big(amount)
+      ? `max ${sum} per transaction (funds split across ${notes.length} notes; spend the rest separately)`
+      : `insufficient balance: have ${sum}`)
+    err.code = total >= big(amount) ? 'FRAGMENTED' : 'INSUFFICIENT'
+    err.maxSpendable = sum
+    throw err
+  }
+  return { inputs, sum }
+}
+
+// ---------- transaction building + proving ----------
+
+function extDataHash(ext) {
+  const enc = U.defaultAbiCoder.encode(
+    ['tuple(address recipient,int256 extAmount,address feeRecipient,uint256 fee,bytes encryptedOutput1,bytes encryptedOutput2)'],
+    [ext],
+  )
+  return mod(BigInt(U.keccak256(enc)))
+}
+
+/**
+ * Builds the circuit input and the transaction's public data.
+ * tree: buildTree() over the pool's current leaves. nextIndex = tree.size.
+ */
+async function buildTransaction({ keys, tree, inputs, outputs, fee = 0n, recipient, feeRecipient }) {
+  if (inputs.length > 2 || outputs.length > 2) throw new Error('at most 2 inputs and 2 outputs')
+  inputs = [...inputs]; outputs = [...outputs]
+  while (inputs.length < 2) inputs.push(new Note())
+  while (outputs.length < 2) outputs.push(new Note())
+  fee = big(fee)
+  const extAmount = fee + outputs.reduce((s, n) => s + n.amount, 0n) - inputs.reduce((s, n) => s + n.amount, 0n)
+
+  const inPathIndices = []
+  const inPathElements = []
+  for (const n of inputs) {
+    if (n.amount > 0n) {
+      inPathIndices.push(n.index)
+      inPathElements.push(tree.path(n.index).map(String))
+    } else {
+      inPathIndices.push(0)
+      inPathElements.push(new Array(TREE_HEIGHT).fill('0'))
+    }
+  }
+  let next = tree.size
+  for (const o of outputs) o.index = next++
+
+  const ext = {
+    recipient: U.getAddress(toHex(big(recipient || 0), 20)),
+    extAmount: toHex(extAmount),
+    feeRecipient: U.getAddress(toHex(big(feeRecipient || 0), 20)),
+    fee: toHex(fee),
+    encryptedOutput1: await outputs[0].encrypt(keys.aesKey),
+    encryptedOutput2: await outputs[1].encrypt(keys.aesKey),
+  }
+  const hash = extDataHash(ext)
+  const publicAmount = mod(extAmount - fee)
+  const nullifiers = inputs.map((n) => n.nullifier())
+  const commitments = outputs.map((n) => n.commitment())
+
+  const circuitInput = {
+    root: tree.root.toString(),
+    inputNullifier: nullifiers.map(String),
+    outputCommitment: commitments.map(String),
+    publicAmount: publicAmount.toString(),
+    extDataHash: hash.toString(),
+    mintAddress: inputs[0].mint.toString(),
+    inAmount: inputs.map((n) => n.amount.toString()),
+    inPrivateKey: inputs.map((n) => big(n.keypair.privkey).toString()),
+    inBlinding: inputs.map((n) => n.blinding.toString()),
+    inPathIndices,
+    inPathElements,
+    outAmount: outputs.map((n) => n.amount.toString()),
+    outBlinding: outputs.map((n) => n.blinding.toString()),
+    outPubkey: outputs.map((n) => n.keypair.pubkey.toString()),
+  }
+  const publicArgs = {
+    root: toHex(tree.root),
+    inputNullifiers: nullifiers.map((x) => toHex(x)),
+    outputCommitments: commitments.map((x) => toHex(x)),
+    publicAmount: toHex(publicAmount),
+    extDataHash: toHex(hash),
+  }
+  return { circuitInput, publicArgs, extData: ext, extAmount }
+}
+
+/**
+ * Groth16 proof with snarkjs. wasm/zkey: Uint8Array (or a path in Node). singleThread avoids nested workers.
+ */
+async function prove(circuitInput, { wasm, zkey, snarkjs, singleThread = false }) {
+  const sj = snarkjs || require('snarkjs')
+  const { proof } = await sj.groth16.fullProve(circuitInput, wasm, zkey, undefined, undefined, { singleThread })
+  return {
+    pA: [toHex(proof.pi_a[0]), toHex(proof.pi_a[1])],
+    pB: [
+      [toHex(proof.pi_b[0][1]), toHex(proof.pi_b[0][0])],
+      [toHex(proof.pi_b[1][1]), toHex(proof.pi_b[1][0])],
+    ],
+    pC: [toHex(proof.pi_c[0]), toHex(proof.pi_c[1])],
+  }
+}
+
+/** Calldata for a self-broadcast deposit (the user's wallet sends it; value = extAmount for native pools). */
+function encodeTransact(args, extData) {
+  return POOL_IFACE.encodeFunctionData('transact', [args, extData])
+}
+
+// ---------- high-level flows (pure: the caller supplies pool data and circuit files) ----------
+
+/**
+ * poolData: { root, entries, nullifiers } from GET /api/zk/pool. Rebuilds the tree locally and refuses to
+ * continue if it does not reproduce the root the pool reported (stale or inconsistent indexer data).
+ */
+async function loadAccount({ keys, poolData }) {
+  const entries = [...poolData.entries].sort((a, b) => a.index - b.index)
+  entries.forEach((e, i) => { if (Number(e.index) !== i) throw new Error(`indexer data has a gap at leaf ${i}; retry in a few seconds`) })
+  const tree = buildTree(entries.map((e) => e.commitment))
+  if (poolData.root && toHex(tree.root).toLowerCase() !== String(poolData.root).toLowerCase()) {
+    throw new Error('pool data is out of sync (root mismatch); retry in a few seconds')
+  }
+  const spent = new Set((poolData.nullifiers || []).map((n) => toHex(n).toLowerCase()))
+  const notes = await scanNotes({ keys, entries, spent })
+  const balance = notes.reduce((s, n) => s + n.amount, 0n)
+  return { tree, notes, balance }
+}
+
+/** Shield `amount` (merging the oldest existing note so the balance stays in few notes). */
+async function prepareDeposit({ keys, account, amount, depositor, feeRecipient }) {
+  const inputs = account.notes.length ? [account.notes.slice().sort((a, b) => a.index - b.index)[0]] : []
+  const inSum = inputs.reduce((s, n) => s + n.amount, 0n)
+  const outputs = [new Note({ amount: inSum + big(amount), keypair: keys.keypair })]
+  const tx = await buildTransaction({ keys, tree: account.tree, inputs, outputs, fee: 0n, recipient: depositor, feeRecipient })
+  return { ...tx, newBalance: account.balance + big(amount) }
+}
+
+/** Spend `amount` (gross, before the relayer fee) to `recipient`; change stays private. */
+async function prepareWithdraw({ keys, account, amount, recipient, flatFeeWei, feeRecipient }) {
+  amount = big(amount)
+  const fee = relayFee(amount, flatFeeWei)
+  if (fee * 2n >= amount) {
+    const err = new Error('amount must be more than twice the fee'); err.code = 'TOO_SMALL'; err.minimum = fee * 2n; throw err
+  }
+  const { inputs, sum } = pickInputs(account.notes, amount)
+  const change = sum - amount
+  const outputs = change > 0n ? [new Note({ amount: change, keypair: keys.keypair })] : []
+  const tx = await buildTransaction({ keys, tree: account.tree, inputs, outputs, fee, recipient, feeRecipient })
+  return { ...tx, fee, receives: amount - fee, change }
+}
+
+module.exports = {
+  FIELD_SIZE, TREE_HEIGHT, ZERO_LEAF, ZEROS, FEE_RATE_BPS, SIGN_IN_MESSAGE, POOL_ABI,
+  poseidon, toHex, Keypair, Note, deriveKeys, encrypt, decrypt, scanNotes, buildTree,
+  relayFee, pickInputs, extDataHash, buildTransaction, prove, encodeTransact,
+  loadAccount, prepareDeposit, prepareWithdraw,
+}

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@blackpool/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Private payments for onchain agents. CLI for BLACKPOOL - shield, send, swap, bridge with zero-knowledge privacy on Base, Robinhood Chain, Arbitrum, and BNB Smart Chain.",
+  "mcpName": "cash.blackpool/blackpool",
   "bin": {
     "blackpool": "bin/blackpool.js"
   },
@@ -11,11 +12,14 @@
   },
   "files": [
     "bin/",
+    "lib/",
     "README.md",
     "AGENTS.md"
   ],
   "dependencies": {
-    "ethers": "^5.7.2"
+    "ethers": "^5.7.2",
+    "poseidon-lite": "^0.3.0",
+    "snarkjs": "0.7.5"
   },
   "keywords": [
     "mcp",