@blackpool/cli 0.0.0-stage → 0.2.0

package/AGENTS.md

@@ -0,0 +1,130 @@
+# AGENTS.md — Blackpool for agents
+
+This file tells an AI agent (or a script) how to make private payments with Blackpool through the CLI: install it, give it a wallet, read its JSON output, and handle failures safely. Humans can read it too.
+
+- Web: https://blackpool.cash · Docs: https://blackpool.cash/docs#agents · This file: https://blackpool.cash/AGENTS.md
+- Package: [`@blackpool/cli`](https://www.npmjs.com/package/@blackpool/cli) (Node.js 18+)
+- API: `https://api.blackpool.cash` (the CLI talks to it for you)
+
+## What you can do
+
+Shield funds into a zero-knowledge pool, then pay, swap or bridge them with no on-chain link back to your wallet. The relayer pays gas for every private operation, so the agent only needs gas for the initial shield.
+
+| Command | What it does |
+|---|---|
+| `blackpool address` | Print the agent wallet address (fund this). |
+| `blackpool balance [--chain C] [--pool P] [--wait]` | Private and public balances. `--chain all` covers every chain. |
+| `blackpool deposit <amount> [--pool P] [--chain C]` | Shield public funds from the agent wallet into the pool (the agent pays this gas). |
+| `blackpool send <to> <amount> [--pool P] [--chain C]` | Private payment to any address. No gas needed. |
+| `blackpool swap <amount> --from P [--chain C] [--slippage BPS]` | Private same-chain swap (native ⇄ stablecoin), output re-shielded. |
+| `blackpool bridge <dest-asset> <recipient> <amount> --from ORIGIN [--no-wait]` | Private cross-chain transfer via NEAR Intents. |
+| `blackpool assets` | Bridge destination assets and valid `--from` origins. |
+| `blackpool bridges` | Your bridges with status, and where a refund went. |
+| `blackpool recover [--to ADDR] [--chain C]` | Sweep anything stranded on one-time burner wallets. Idempotent. |
+| `blackpool login` / `logout` / `version` / `latest` / `help` | Housekeeping. |
+
+## Chains, pools and minimums
+
+| `--chain` | Pools (`--pool`) | Minimum shield | Minimum send / swap / bridge |
+|---|---|---|---|
+| `base` (default) | `eth`, `usdc` | 0.001 ETH · 3 USDC | 0.001 ETH · 2 USDC |
+| `robinhood` | `eth`, `usdg` | 0.001 ETH · 3 USDG | 0.001 ETH · 2 USDG |
+| `arbitrum` | `eth`, `usdc` | 0.001 ETH · 3 USDC | 0.001 ETH · 2 USDC |
+| `bsc` | `bnb`, `usdc`, `usdt` | 0.02 BNB · 3 USDC/USDT | 0.001 BNB · 2 USDC/USDT |
+
+When `--pool` is omitted, `deposit` and `send` use the chain's stablecoin pool. Fees: a flat fee (0.00015 ETH, 0.001 BNB, 1 USDC on Base, 0.5 on the other stablecoin pools) plus 0.35%, taken inside the proof from the amount you move. A spend must be more than twice its own fee. Bridge origins for `--from`: `base_eth`, `base_usdc`, `hood_eth`, `hood_usdg`, `arb_eth`, `arb_usdc`, `bsc_bnb`, `bsc_usdc`, `bsc_usdt`.
+
+## Setup
+
+```sh
+npm i -g @blackpool/cli          # or prefix every command with: npx -y @blackpool/cli
+export BLACKPOOL_KEY=0x...       # private key of a DEDICATED agent wallet (see Security)
+export BLACKPOOL_JSON=1          # machine-readable output (same as --json on every command)
+blackpool address                # fund this address with gas + the asset to shield
+```
+
+`BLACKPOOL_KEY` replaces the interactive `blackpool login`. The first command that needs your private account signs the Blackpool sign-in message with that key and caches the signature in `~/.blackpool/config.json` (mode 600). Set `BLACKPOOL_HOME` to keep that cache somewhere else, for example a writable directory inside a sandbox.
+
+| Variable | Purpose |
+|---|---|
+| `BLACKPOOL_KEY` | Agent wallet private key (0x-hex). Never sent anywhere. |
+| `BLACKPOOL_JSON` | `1` = JSON output for every command. |
+| `BLACKPOOL_HOME` | Config directory (default `~/.blackpool`). |
+| `BLACKPOOL_API` | API base URL (default `https://api.blackpool.cash`). |
+
+## JSON output
+
+With `--json` (or `BLACKPOOL_JSON=1`) stdout carries exactly one JSON object and nothing else; progress messages go to stderr. Parse stdout, log stderr if you want.
+
+```sh
+$ blackpool send 0x9f3c...41e7 5 --pool usdc --chain base --json
+{"ok":true,"command":"send","chain":"base","pool":"usdc","recipient":"0x9f3c...41e7","amount":5,
+ "received":"3.9825","fee":"1.0175","symbol":"USDC","txHash":"0x...","explorer":"https://basescan.org/tx/0x..."}
+
+$ blackpool send 0x9f3c...41e7 0.5 --json
+{"ok":false,"command":"send","error":"minimum send is 2 USDC on Base — smaller amounts are mostly consumed by the withdraw fee (flat + 0.35%)"}
+```
+
+| Command | Fields on success |
+|---|---|
+| `address`, `login` | `address` |
+| `balance` | `balances[]`: `{chain, address, private: {SYM: {balance, utxos}}, public: {SYM: amount}}`; with `--pool`: `{chain, pool, balance, symbol, utxos}` |
+| `deposit` | `chain, pool, amount, symbol, txHash, explorer, privateBalance` |
+| `send` | `chain, pool, recipient, amount, received, fee, symbol, txHash, explorer` |
+| `swap` | `chain, from, amount, received, symbol, txHash, explorer, privateBalance` |
+| `bridge` | `from, to, recipient, amount, amountOutQuote, withdrawTx, depositAddress, statusUrl, status` (`SUBMITTED`, `SUCCESS` or `PENDING`) |
+| `bridges` | `bridges[]` with `status`, `amountIn`, `fromAsset`, `toAsset`, `recipient`, `refundTo`, `statusUrl` |
+| `assets` | `assets{}`, `origins[]` |
+| `recover` | `recovered[]`: `{chain, to, swept, dust, errors}` |
+
+Balances and amounts are decimal strings in token units, never wei.
+
+**Exit codes:** `0` success · `1` the operation failed or was refused (including amounts under a minimum) · `2` usage error (unknown command or missing arguments). On `1` and `2` the JSON has `"ok": false` and an `error` message written for a human.
+
+## Recipes
+
+Pay someone privately (first time on a chain):
+
+```sh
+blackpool deposit 25 --pool usdc --chain base --json     # shield once
+blackpool send 0xRECIPIENT 10 --pool usdc --chain base --json
+```
+
+Check before paying:
+
+```sh
+blackpool balance --chain base --pool usdc --json        # .balance must cover amount
+```
+
+Bridge to Solana and return as soon as the solver has the funds:
+
+```sh
+blackpool bridge sol_usdc <solana-address> 10 --from base_usdc --no-wait --json
+blackpool bridges --json                                 # poll status later
+```
+
+After any swap or bridge that failed half-way:
+
+```sh
+blackpool recover --chain all --json                     # safe to run any time
+```
+
+## Failure handling
+
+- **Read-only commands** (`address`, `balance`, `assets`, `bridges`, `version`) are safe to retry.
+- **`recover` is idempotent**: run it again whenever a swap or bridge did not finish.
+- **Do not blindly retry `deposit`, `send`, `swap` or `bridge`.** A timeout can mean the transaction landed. Check `balance --wait` (or `bridges`) first, then decide.
+- A balance that reads `0` right after a deposit is usually the indexer catching up: use `balance --wait`.
+- `rate limited, slow down`: the API allows 40 relay operations and 600 reads per minute per IP. The CLI waits for the `retryAfter` the API sends and retries up to four times; space out bulk payments.
+- Proof generation takes about 30–90 seconds per private operation. Use a command timeout of at least 3 minutes (bridges without `--no-wait` can poll up to 6 minutes).
+
+## Security
+
+- **Use a dedicated agent wallet** holding only what the agent should spend. Never give an agent your main wallet key.
+- `BLACKPOOL_KEY` stays on the machine. It is used to sign the sign-in message and the deposit transaction locally; it is never sent to the API.
+- The sign-in signature **is** sent to the API with each private operation: the API derives your private account keys from it in memory to build the proof, and does not store or log it. Anyone holding that signature can spend the agent's private balance, so protect `~/.blackpool/config.json` like a key, and never paste the signature into prompts, logs or tool output.
+- Pools and circuits have not been externally audited yet. Keep balances proportional to that risk. Details: https://blackpool.cash/docs#security
+
+## Working on this repository
+
+If you are a coding agent editing this repository rather than using the CLI: the CLI lives in `cli/`, contracts in `contracts/`, circuits in `circuits/`, the web app in `frontend/`. Run `npx hardhat test` before changing contracts or core libraries, keep the sign-in message, note format and circuit byte-identical across `src/`, `cli/` and `frontend/` (changing any of them changes every account), and never commit keys, `.env` files or credentials.

package/README.md

@@ -1,3 +1,133 @@
-# Temporary Holding Version
+# @blackpool/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Private payments for onchain agents. One env var or one hidden prompt, then shield / send / swap / bridge with zero-knowledge privacy on **Base**, **Robinhood Chain**, **Arbitrum**, and **BNB Smart Chain**. Wraps the same API `docs.blackpool.cash/agents` uses - no ZK client needed on your side.
+
+Every command takes an optional `--chain base|robinhood|arbitrum|bsc` flag (default `base`). On Base and Arbitrum the stablecoin is USDC; on Robinhood it's USDG; on BSC the stablecoins are USDC and USDT (Binance-Peg, 18 decimals) and the native asset is BNB.
+
+## Install
+
+```bash
+npm i -g @blackpool/cli
+# or
+npx @blackpool/cli help
+```
+
+## Setup
+
+Two ways to provide your key, depending on who's running it.
+
+### Interactive (humans / local demo) - key never shown
+
+```bash
+blackpool login
+#   private key: ●●●●●●●●●●   <- hidden input, like sudo password
+# ✓ 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.
+
+### Env var (agents / CI) - no prompt
+
+```bash
+export BLACKPOOL_KEY=0xyour_agent_private_key
+blackpool login   # detects env var, skips the prompt, stores nothing to disk
+```
+
+Agents pull the key from their own secret manager / vault into `BLACKPOOL_KEY`. The CLI reads it directly and does not write it to disk.
+
+### Logout
+
+```bash
+blackpool logout   # removes ~/.blackpool/wallet.json + config.json
+```
+
+**Key resolution order:** `BLACKPOOL_KEY` env var → `~/.blackpool/wallet.json` → error.
+
+## Commands
+
+```bash
+blackpool balance                            # private + public balances (both pools), Base
+blackpool balance --chain robinhood          # balances on Robinhood (ETH + USDG)
+blackpool balance --chain arbitrum           # balances on Arbitrum (ETH + USDC)
+blackpool balance --chain bsc                # balances on BSC (BNB + USDC + USDT)
+blackpool balance --pool eth                 # just private ETH
+blackpool deposit 25 --pool usdc             # shield 25 USDC from public to private (Base)
+blackpool deposit 15 --pool usdg --chain robinhood  # shield 15 USDG on Robinhood
+blackpool deposit 0.05 --pool bnb --chain bsc       # shield BNB (BSC native pool is 'bnb', not 'eth')
+blackpool send 0xRECIPIENT 2.5               # send 2.5 USDC privately (no gas from you)
+blackpool send 0xRECIPIENT 0.01 --pool eth   # send private ETH
+blackpool send 0xRECIPIENT 2.5 --chain robinhood    # send 2.5 USDG privately on Robinhood
+blackpool swap 0.001 --from eth              # private same-chain swap ETH -> USDC (Uniswap V3)
+blackpool swap 3 --from usdc                 # private same-chain swap USDC -> ETH
+blackpool bridge arb_usdc 0xRECIPIENT 2.5    # bridge cross-chain privately to Arbitrum (1Click)
+blackpool bridge bsc_usdt 0xRECIPIENT 5 --from bsc_usdc  # 1Click origin can be any shielded pool
+blackpool bridge rarb_eth 0xRECIPIENT 0.01 --chain robinhood  # router: Robinhood -> Arbitrum
+blackpool bridge rbsc_bnb 0xRECIPIENT 0.01 --chain robinhood  # router: Robinhood -> BSC
+blackpool assets                             # list all supported bridge destinations
+blackpool recover                            # sweep any stranded funds from burner slots
+blackpool recover --to 0xADDR                # sweep to a different destination
+```
+
+## How it works
+
+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).
+
+**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).
+
+**Swap same-chain** - mirrors the frontend burner flow exactly:
+
+1. Create a fresh random burner wallet and register its key, encrypted with your signature, in the recovery registry before any funds move.
+2. Private withdraw from your pool → burner via `/api/swap-private`.
+3. For USDC origin: relayer tops up burner gas via `/api/burner-gas`.
+4. Burner approves + swaps on Uniswap V3 (SwapRouter02, 0.01% fee tier).
+5. WETH is unwrapped to ETH if ETH is the destination.
+6. Pre-flight `eth_call` simulation of the reshield (catches reverts cheap).
+7. Burner reshields the swapped output back to **your** private balance via `/api/deposit/prepare`.
+
+If any step fails between (2) and (7), funds remain on the burner; its key is in the registry, encrypted so only your signature can read it. Run `blackpool recover` to sweep them home from any device.
+
+**Bridge cross-chain** - private withdraw to a NEAR Intents 1Click solver via `/api/swap`, then poll `/api/intent-status` until `SUCCESS` (or `REFUNDED`, in which case the solver returns your funds automatically). No burner involved for bridges.
+
+**Recover** - fetches every burner registered for your wallet, decrypts the keys locally, and sweeps stranded funds back to your public wallet (or `--to <addr>`). Handles the wallets `swap` may have left behind if a later step reverted. Uses Base-realistic gas params (0.05 gwei) so the burner's tiny ETH top-up is enough for the sweep tx.
+
+## Environment
+
+- `BLACKPOOL_KEY` - agent private key (0x-hex). Optional if you've run `blackpool login`.
+- `BLACKPOOL_API` - API base URL (default `https://api.blackpool.cash`).
+- `BLACKPOOL_RPC` / `BLACKPOOL_BASE_RPC` - Base RPC endpoint (default `https://mainnet.base.org`). Set to your own Alchemy / QuickNode URL for faster + more reliable gas estimation on the burner-heavy swap flow.
+- `BLACKPOOL_ROBINHOOD_RPC` - Robinhood Chain RPC endpoint (default `https://rpc.mainnet.chain.robinhood.com`), used when `--chain robinhood`.
+
+## Config files
+
+- `~/.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).
+
+## Verified live on Base mainnet
+
+Every command in this CLI has been exercised end-to-end against `api.blackpool.cash` with real on-chain transactions:
+
+- `deposit` → `0x7ae2dde7…` (3 USDC shielded)
+- `send` → `0x2108ae58…` (1.49125 USDC delivered privately, fee 1.00875)
+- `swap` → `0x1bd8d68d…` (0.001 ETH → 1.170797 USDC private, full reshield)
+- `bridge` → `0xdfc495fa…` (2.5 USDC Base → 1.484306 USDC delivered to Arbitrum)
+- `recover` → 1.9895 USDC swept back from a stranded burner
+
+## Cross-chain destinations
+
+Run `blackpool assets` for the full live list. Currently: **Base, Ethereum, BSC, Arbitrum** - ETH / WETH / USDC / USDT / cbBTC / ARB / BNB depending on the chain.
+
+## Roadmap
+
+- `@blackpool/sdk` - TypeScript SDK for programmatic use inside an agent.
+- Mandate limits - human-signed spend cap per window (aligns with the "supervised agent" pattern).
+- Optional wallet encryption at rest - passphrase-protected `wallet.json`.
+
+## Support
+
+Docs: [docs.blackpool.cash/agents](https://docs.blackpool.cash/agents) · Site: [blackpool.cash](https://blackpool.cash)
+
+## Agents
+
+Run any command with `--json` (or `BLACKPOOL_JSON=1`) to get one JSON object on stdout and progress on stderr; exit codes are `0` ok, `1` failed, `2` usage. [`AGENTS.md`](AGENTS.md) (also at https://blackpool.cash/AGENTS.md) documents every command's fields, minimums, retry rules and security notes.