@parallel-protocol/cli 0.1.0

package/README.md

@@ -0,0 +1,431 @@
+# @parallel-protocol/cli
+
+Command-line interface for the [Parallel Protocol](https://parallel.best/) — query live on-chain data, build and sign transactions, and interact with the x402 payment layer directly from your terminal.
+
+---
+
+## Installation
+
+```bash
+# Install globally
+npm install -g @parallel-protocol/cli
+
+# Or run without installing
+npx @parallel-protocol/cli <command>
+```
+
+**Requirements:** Node.js ≥ 18
+
+---
+
+## Quick start
+
+```bash
+# 1. Configure (interactive wizard — runs once)
+parallel config init
+
+# 2. Explore
+parallel protocol overview
+parallel protocol tvl --chain base
+parallel protocol savings-rate
+
+# 3. Build a transaction (dry-run — no wallet needed)
+parallel swap quote --op mint --collateral USDC --amount 1000 --chain avalanche
+parallel swap mint  --collateral USDC --amount 1000 --chain avalanche --dry-run
+```
+
+> **Development (from the parallel-mcp repo):**
+> ```bash
+> npm run build:cli                              # build once
+> alias parallel="node packages/cli/dist/index.js"
+> parallel protocol overview
+> ```
+
+---
+
+## Configuration
+
+### `parallel config init`
+
+Interactive wizard that creates `~/.parallel/config.toml`:
+
+```toml
+[network]
+default_chain = "base"
+
+[wallet]
+keystore_path = "~/.parallel/keystore.json"
+
+[display]
+default_format = "table"   # table | json
+```
+
+### `parallel config get / set`
+
+```bash
+parallel config get network.default_chain   # → base
+parallel config set network.default_chain ethereum
+```
+
+### Creating a keystore
+
+> **Always use a dedicated wallet for testing — never your main wallet.**
+
+The CLI uses the [Ethereum V3 keystore](https://github.com/ethereum/wiki/wiki/Web3-Secret-Storage-Definition) format (AES-128-CTR encrypted, password required at each use). Three ways to create one:
+
+**Option A — Foundry `cast` (recommended for developers)**
+
+```bash
+cast wallet new ~/.parallel/keystore.json
+# → generates a fresh address and encrypts it with a password you choose
+```
+
+**Option B — Geth**
+
+```bash
+geth account new --keystore ~/.parallel/
+```
+
+**Option C — From MetaMask (non-dev users)**
+
+```bash
+# 1. MetaMask → Account details → Export Private Key
+# 2. Convert to keystore:
+cast wallet import ~/.parallel/keystore.json --interactive
+# → paste the private key, set a password
+```
+
+Then point the CLI to it:
+
+```bash
+parallel config set wallet.keystore_path ~/.parallel/keystore.json
+# or pass it directly: --wallet ~/.parallel/keystore.json
+```
+
+### Environment variables
+
+All optional — they override the config file when set.
+
+| Variable | Description |
+|---|---|
+| `PARALLEL_PRIVATE_KEY` | Raw private key (hex, `0x` prefix) — alternative to keystore, useful for scripts and CI |
+| `PARALLEL_DEFAULT_CHAIN` | Default chain — overrides `network.default_chain` in config |
+| `PARALLEL_JSON` | Set to `true` to force JSON output on all commands |
+
+
+---
+
+## Global flags
+
+These flags are available across most commands. Command-specific flags (e.g. `--collateral`, `--amount`, `--op`) are documented in each command's section.
+
+| Flag | Alias | Description |
+|---|---|---|
+| `--chain <chain>` | `-c` | Target chain (e.g. `base`, `ethereum`, `avalanche`) |
+| `--json` | `-j` | Force JSON output |
+| `--dry-run` | | Build transaction without broadcasting (write commands only) |
+| `--wallet [path\|env]` | `-w` | Sign with a wallet — see below |
+| `--help` | `-h` | Contextual help |
+
+**`--wallet` resolution:**
+
+| Usage | Behavior |
+|---|---|
+| `--wallet` (alone) | Auto-resolves: reads `wallet.keystore_path` from config first, then falls back to `$PARALLEL_PRIVATE_KEY` |
+| `--wallet env` | Explicitly uses `$PARALLEL_PRIVATE_KEY` |
+| `--wallet /path/to/keystore.json` | Uses that specific keystore file (password prompted) |
+
+---
+
+## Commands
+
+### `parallel protocol`
+
+Read-only. No wallet required.
+
+```bash
+parallel protocol overview                                             # TVL · supply · APY · backing ratio
+parallel protocol tvl            [--chain <chain>]                     # Total Value Locked per chain
+parallel protocol supply         <usdp|susdp|prl|sprl1|sprl2> [--chain <chain>]  # Token supply breakdown
+parallel protocol backing        [--chain <chain>]                     # Collateral composition + backing ratio
+parallel protocol chains                                               # Supported chains + feature matrix
+parallel protocol collaterals    --chain <chain>                       # Accepted collaterals · caps · fees
+parallel protocol mint-capacity  --collateral <symbol> --chain <chain> [--amount <n>]
+parallel protocol fees           [--collateral <symbol>] [--chain <chain>]
+parallel protocol savings-rate   [--chain <chain>]                     # Global APY + per-chain breakdown
+parallel protocol exchange-rate  [--chain <chain>]                     # sUSDp / USDp rate
+parallel protocol solvency       [--chain <chain>]                     # Backing ratio per chain
+parallel protocol surplus        [--chain <chain>]                     # Pending surplus (USDp)
+parallel protocol flashloan      [--chain <chain>]                     # Flash loan capacity + fee rate
+```
+
+---
+
+### `parallel swap`
+
+Build Parallelizer transactions (mint / burn / redeem).
+
+```bash
+# Get a quote first
+parallel swap quote --op mint   --collateral <symbol> --amount <n> --chain <chain>
+parallel swap quote --op burn   --collateral <symbol> --amount <n> --chain <chain>
+parallel swap quote --op redeem --amount <n> --chain <chain>
+
+# Dry-run (shows raw unsigned tx — no wallet needed)
+parallel swap mint   --collateral <symbol> --amount <n> --chain <chain> --dry-run
+parallel swap burn   --collateral <symbol> --amount <n> --chain <chain> --dry-run
+parallel swap redeem --amount <n> --chain <chain> --dry-run
+
+# Sign and broadcast
+parallel swap mint   --collateral <symbol> --amount <n> --chain <chain> --wallet
+parallel swap burn   --collateral <symbol> --amount <n> --chain <chain> --wallet
+parallel swap redeem --amount <n> --chain <chain> --wallet   # proportional redeem
+```
+
+**Options:**
+
+| Flag | Default | Description |
+|---|---|---|
+| `--op <mint\|burn\|redeem>` | | Operation (quote only) |
+| `--collateral <symbol>` | | Collateral symbol (e.g. `USDC`, `USDS`, `sUSDS`) |
+| `--amount <n>` | | Amount in USDp (or collateral units for mint) |
+| `--address <0x...>` | | Receiver address for dry-run (no key needed) |
+
+---
+
+### `parallel savings`
+
+sUSDp savings operations.
+
+```bash
+parallel savings rate     [--chain <chain>]                         # APY + exchange rate + TVL
+parallel savings estimate --amount <n> --duration <days>            # Projected yield
+
+parallel savings balance  <address> [--chain <chain>]               # sUSDp balance + USDp equivalent
+
+# Dry-run
+parallel savings deposit  --amount <n> --chain <chain> --dry-run
+parallel savings withdraw --amount <n> --chain <chain> --dry-run    # amount in sUSDp shares
+
+# Sign and broadcast
+parallel savings deposit  --amount <n> --chain <chain> --wallet
+parallel savings withdraw --amount <n> --chain <chain> --wallet
+```
+
+> **Note:** `savings deposit` uses EIP-3009 `transferWithAuthorization` when available — single signature, gasless on L2/sidechains.
+
+---
+
+### `parallel bridge`
+
+LayerZero cross-chain bridge (USDp / sUSDp).
+
+```bash
+parallel bridge quote  --token <usdp|susdp> --from <chain> --to <chain> --amount <n>
+parallel bridge fees   --from <chain> --token <usdp|susdp>   # fees to all destinations
+parallel bridge limits [--chain <chain>]                      # daily + global limits
+
+# Dry-run
+parallel bridge send --token <usdp|susdp> --from <chain> --to <chain> --amount <n> --dry-run
+
+# Sign and broadcast
+parallel bridge send --token <usdp|susdp> --from <chain> --to <chain> --amount <n> --wallet [--recipient <address>]
+
+parallel bridge status <txHash> --from <chain>
+```
+
+> **Note:** Mantle does not support bridging (no BridgeableToken deployed). All other chains support bridge.
+
+---
+
+### `parallel staking`
+
+PRL staking — sPRL1 (single-sided) and sPRL2 (BPT, Balancer).
+
+```bash
+parallel staking overview                    # global stats: supply, voting power, rewards
+parallel staking info     <address>          # per-address: staked, voting power, pending rewards
+parallel staking cooldown <address>          # cooldown status + expiry date
+
+# sPRL1 — stake PRL on Ethereum
+parallel staking stake   --type sprl1 --amount <n> --dry-run
+parallel staking unstake --type sprl1 --amount <n> --dry-run
+parallel staking stake   --type sprl1 --amount <n> --wallet
+parallel staking unstake --type sprl1 --amount <n> --wallet
+
+# sPRL2 — Ethereum only (Balancer BPT, multi-step: Balancer → Aura)
+parallel staking stake   --type sprl2 --amount <n> --dry-run                                    # BPT path
+parallel staking stake   --type sprl2 --amount <n> --weth-amount <n> --dry-run                  # PRL+WETH path
+parallel staking unstake --type sprl2 --amount <n> --wallet                                     # initiate cooldown
+parallel staking unstake --type sprl2 --wallet                                                  # execute ready withdrawals
+
+# Claim rewards
+parallel staking claim   --type sprl1 --dry-run
+parallel staking claim   --type sprl2 --dry-run
+parallel staking claim   --type all   --wallet
+```
+
+---
+
+### `parallel gov`
+
+Snapshot governance — read-only.
+
+```bash
+parallel gov proposals [--status active|pending|passed|rejected] [--type PIP|PGP|PIR]
+parallel gov proposal  <PIP-65|0xabc...>    # full details + vote results + description
+parallel gov params                          # protocol parameters: fee rates, collateral caps
+```
+
+---
+
+### `parallel pay`
+
+x402 payment layer.
+
+```bash
+# Explore what's available on a chain
+parallel pay capabilities [--chain <chain>]
+
+# Gas sponsoring quota for an address
+parallel pay quota --chain <chain> [--address <address>]
+
+# Verify a payment on-chain
+parallel pay verify <txHash> --chain <chain>
+```
+
+#### `parallel pay prepare`
+
+Builds a signed or unsigned x402 payment payload.
+
+```bash
+# Unsigned — shows route + payload (no wallet required)
+parallel pay prepare \
+  --amount <n> \
+  --recipient <address> \
+  --chain <chain>
+
+# Signed — reads wallet balance, auto-selects best route, encodes the payload
+parallel pay prepare \
+  --amount <n> \
+  --recipient <address> \
+  --chain <chain> \
+  --wallet
+
+# Force which token the agent pays with
+parallel pay prepare --amount <n> --recipient <address> --chain <chain> --pay-with <usdp|usdc|susdp>
+```
+
+**`--token`** controls what the **merchant receives** (default: `usdp`). Accepted values: `usdp` · `usdc` · `susdp` · any backing collateral symbol (`susds`, `sfrxusd`, …).
+
+**`--pay-with`** overrides which token the **agent pays with** (default: auto-detected from wallet balance). Accepted values: `usdp` · `usdc` · `susdp`.
+
+**Auto-route selection** (when `--wallet` is provided):
+
+| `--token` (merchant receives) | Agent wallet | Route | Method |
+|---|---|---|---|
+| `usdp` | USDp ≥ amount | A | `transferWithAuthorization` |
+| `usdp` | sUSDp only | H | `redeemWithAuthorization` → USDp |
+| `usdp` | sUSDp + USDp (top-up) | L | `partialRedeemWithAuthorization` |
+| `usdc` | USDp | B | `swapExactOutputWithAuthorization` |
+| `usdc` | sUSDp | I | `redeemWithAuthorization` → USDC |
+| `usdc` | USDC | F | `transferWithAuthorization` |
+| `susdp` | USDp | C | `depositWithAuthorization` |
+| `susdp` | sUSDp | J | `transferWithAuthorization` |
+| collateral (e.g. `susds`) | USDp | D | `swapExactOutputWithAuthorization` |
+| collateral (e.g. `susds`) | sUSDp | K | `redeemWithAuthorization` → collateral |
+
+Without `--wallet`, the payload is unsigned and `tokenIn` defaults to `usdp`.
+
+---
+
+### `parallel cashback`
+
+Cashback rewards — read-only, via facilitator API.
+
+```bash
+parallel cashback balance  <address>                              # current month spend + earnings + tier
+parallel cashback tier     <address>                              # 4-tier breakdown + rates
+parallel cashback history  <address> [--limit <n>]                # monthly history + distribution status
+parallel cashback estimate <address> [--projected-spend <n>]      # projected earnings this month
+parallel cashback quota    <address> [--chain <chain>]            # gas sponsoring quota
+```
+
+---
+
+### Utilities
+
+```bash
+parallel version                  # CLI version · MCP server version · Node version
+parallel health [--chain <chain>]  # RPC latency check for all chains (or one)
+parallel config init              # interactive setup wizard
+parallel config get <key>         # e.g. network.default_chain
+parallel config set <key> <value> # e.g. parallel config set network.default_chain ethereum
+```
+
+---
+
+## Output
+
+All commands print a human-readable table by default.
+
+```bash
+# Force JSON
+parallel protocol tvl --json
+# {"success":true,"data":{...}}
+
+# Pipe-friendly: JSON is automatic when stdout is not a TTY
+parallel protocol tvl | jq '.data.totalTVL'
+```
+
+JSON envelope:
+
+```json
+{ "success": true, "data": { ... } }
+{ "success": false, "error": { "code": "CHAIN_SUNSET", "message": "..." } }
+```
+
+---
+
+## Supported chains
+
+`ethereum` · `base` · `arbitrum` · `optimism` · `polygon` · `avalanche` · `bsc` · `scroll` · `gnosis` · `sei` · `berachain` · `hyperevm` · `unichain` · `ink` · `tac` · `mantle` · `linea` · `xlayer` · `fraxtal` · `worldchain` · `hemi` · `plume` · `plasma` · `katana`
+
+> `sonic` is sunset (PIP-64) — read operations work, write operations return `CHAIN_SUNSET`.
+
+Not all chains support every feature. Use `parallel protocol chains` to see the full feature matrix (Parallelizer, sUSDp, bridge).
+
+---
+
+## Error codes
+
+| Code | Trigger |
+|---|---|
+| `CHAIN_SUNSET` | Operation not available on a sunset chain |
+| `CHAIN_PAUSED` | Chain temporarily paused (auto-pause by Hypernative or governance) |
+| `PARALLELIZER_NOT_DEPLOYED` | Feature requires Parallelizer, not deployed on this chain |
+| `UNKNOWN_CHAIN` | Chain identifier not recognised |
+| `INSUFFICIENT_BALANCE` | Wallet balance too low for the requested amount |
+| `EXCEEDS_CAP` | Amount would exceed a collateral exposure cap |
+| `EXCEEDS_BRIDGE_LIMIT` | Amount exceeds daily or global bridge limit |
+| `SLIPPAGE_EXCEEDED` | Actual slippage exceeds the configured tolerance |
+| `COOLDOWN_ACTIVE` | Unstake impossible — cooldown period not yet expired |
+| `COLLATERAL_NOT_SUPPORTED` | Collateral not accepted on this chain |
+| `WALLET_REQUIRED` | Write command called without `--wallet` or `--dry-run` |
+| `INVALID_KEYSTORE` | Keystore file not found or invalid format |
+| `WRONG_PASSWORD` | Incorrect keystore decryption password |
+| `INVALID_AMOUNT` | Negative, zero, or unparseable amount |
+| `MISSING_OPTION` | Required flag not provided |
+| `INVALID_ADDRESS` | Argument is not a valid EVM address |
+| `PAYMENT_EXPIRED` | x402 payment — `validBefore` exceeded, re-sign required |
+| `INVALID_SIGNATURE` | x402 payment — EIP-712 signature invalid |
+| `INVALID_NONCE` | x402 payment — nonce already used |
+| `ROUTE_UNAVAILABLE` | x402 payment — no route available for this merchant/chain combination |
+| `RPC_ERROR` | RPC call failed (network issue or node unreachable) |
+
+---
+
+## Related
+
+- [parallel-mcp](https://github.com/parallel-protocol/parallel-mcp) — MCP server + x402 facilitator
+- [Parallel Protocol](https://parallel.best)