@parallel-protocol/cli 0.2.5 → 0.2.7

package/README.md

@@ -14,7 +14,7 @@ npm install -g @parallel-protocol/cli
 npx @parallel-protocol/cli <command>
 ```
 
-**Requirements:** Node.js ≥ 18
+**Requirements:** Node.js ≥ 22
 
 ---
 
@@ -36,7 +36,7 @@ parallel swap mint  --collateral USDC --amount 1000 --chain avalanche --dry-run
 
 > **Development (from the parallel-mcp repo):**
 > ```bash
-> npm run build:cli                              # build once
+> bun run build:cli                              # build once
 > alias parallel="node packages/cli/dist/index.js"
 > parallel protocol overview
 > ```
@@ -55,9 +55,6 @@ default_chain = "base"
 
 [wallet]
 keystore_path = "~/.parallel/keystore.json"
-
-[display]
-default_format = "table"   # table | json
 ```
 
 ### `parallel config get / set`
@@ -76,8 +73,10 @@ The CLI uses the [Ethereum V3 keystore](https://github.com/ethereum/wiki/wiki/We
 **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
+mkdir -p ~/.parallel
+cast wallet new ~/.parallel
+# → generates a fresh address, encrypted with a password you choose,
+#   as ~/.parallel/<id> (random filename — rename it if you like)
 ```
 
 **Option B — Geth**
@@ -91,27 +90,31 @@ geth account new --keystore ~/.parallel/
 ```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
+cast wallet import parallel-cli --keystore-dir ~/.parallel --interactive
+# → paste the private key, set a password — writes ~/.parallel/parallel-cli
 ```
 
 Then point the CLI to it:
 
 ```bash
-parallel config set wallet.keystore_path ~/.parallel/keystore.json
-# or pass it directly: --wallet ~/.parallel/keystore.json
+parallel config set wallet.keystore_path ~/.parallel/parallel-cli
+# or pass it directly: --wallet ~/.parallel/parallel-cli
 ```
 
 ### Environment variables
 
-All optional — they override the config file when set.
+All optional.
 
 | Variable | Description |
 |---|---|
-| `PARALLEL_PRIVATE_KEY` | Raw private key (hex, `0x` prefix) — alternative to keystore, useful for scripts and CI |
+| `PARALLEL_PRIVATE_KEY` | Raw private key (hex, `0x` prefix) — alternative to keystore, useful for scripts and CI. Used by `--wallet env`, or by `--wallet` alone when no keystore is configured |
 | `PARALLEL_DEFAULT_CHAIN` | Default chain — overrides `network.default_chain` in config |
 | `PARALLEL_JSON` | Set to `true` to force JSON output on all commands |
 | `PARALLEL_API_URL` | Parallel API base URL for `--history` commands (default: `https://api.parallel.best`) |
+| `FACILITATOR_URL` | Facilitator base URL for `pay` commands (default: `https://agents.parallel.best`) |
+| `ALCHEMY_API_KEY` | Optional Alchemy key — upgrades RPC calls from public endpoints to Alchemy |
+
+> **Precedence:** flags > environment > config file — except the wallet: `--wallet` used alone tries the config `keystore_path` **first**, then falls back to `PARALLEL_PRIVATE_KEY`.
 
 
 ---
@@ -170,32 +173,38 @@ parallel protocol supply       --history usdp  # USDp circulating supply over ti
 
 ### `parallel swap`
 
-Build Parallelizer transactions (mint / burn / redeem).
+Build Parallelizer transactions (mint / redeem / redeem-all).
 
 ```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>
+parallel swap quote --op mint       --collateral <symbol> --amount <n> --chain <chain>
+parallel swap quote --op redeem     --collateral <symbol> --amount <n> --chain <chain>
+parallel swap quote --op redeem-all --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
+parallel swap mint       --collateral <symbol> --amount <n> --chain <chain> --dry-run
+parallel swap redeem     --collateral <symbol> --amount <n> --chain <chain> --dry-run
+parallel swap redeem-all --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
+parallel swap mint       --collateral <symbol> --amount <n> --chain <chain> --wallet
+parallel swap redeem     --collateral <symbol> --amount <n> --chain <chain> --wallet
+parallel swap redeem-all --amount <n> --chain <chain> --wallet   # proportional redeem
 ```
 
+> Command names match the MCP tools since 0.2.7: `redeem` targets ONE
+> collateral (formerly `burn`), `redeem-all` redeems proportionally across the
+> whole basket (formerly `redeem`). The old `swap burn` keeps working as a
+> hidden legacy command.
+
 **Options:**
 
 | Flag | Default | Description |
 |---|---|---|
-| `--op <mint\|burn\|redeem>` | | Operation (quote only) |
+| `--op <mint\|redeem\|redeem-all>` | | Operation (quote only) |
 | `--collateral <symbol>` | | Collateral symbol (e.g. `USDC`, `USDS`, `sUSDS`) |
 | `--amount <n>` | | Amount in USDp (or collateral units for mint) |
+| `--slippage <pct>` | `0.5` | Slippage tolerance in % (`mint` / `redeem` / `redeem-all`) |
 | `--address <0x...>` | | Receiver address for dry-run (no key needed) |
 
 ---
@@ -219,29 +228,30 @@ 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.
+> **Note:** in a terminal, `savings deposit` shows an interactive menu with two methods: **EIP-3009** `depositWithAuthorization` (no approval transaction — two EIP-712 signatures, one on-chain transaction) or **standard** approve + deposit (two transactions). In JSON / non-TTY mode the standard path is used automatically.
 
 ---
 
 ### `parallel bridge`
 
-LayerZero cross-chain bridge (USDp / sUSDp).
+LayerZero cross-chain bridge (USDp).
 
 ```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
+parallel bridge quote  --from <chain> --to <chain> --amount <n>
+parallel bridge fees   --from <chain>                          # 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
+parallel bridge send --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 send --from <chain> --to <chain> --amount <n> --wallet [--recipient <address>]
 
-parallel bridge status <txHash> --from <chain>
+parallel bridge status  <txHash> --from <chain>
+parallel bridge history <address> [--limit <n>] [--offset <n>]   # past transfers (default: 20)
 ```
 
-> **Note:** Mantle does not support bridging (no BridgeableToken deployed). All other chains support bridge.
+> **Note:** only `usdp` can be bridged for now (`--token` defaults to it; other values are rejected). Mantle does not support bridging (no BridgeableToken deployed) — all other chains do.
 
 ---
 
@@ -258,7 +268,8 @@ parallel staking cooldown <address>          # cooldown status + expiry date
 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
+parallel staking unstake --type sprl1 --amount <n> --wallet   # initiate cooldown
+parallel staking unstake --type sprl1 --wallet                # execute ready withdrawals
 
 # sPRL2 — Ethereum only (Balancer BPT, multi-step: Balancer → Aura)
 parallel staking stake   --type sprl2 --amount <n> --dry-run                                    # BPT path
@@ -295,12 +306,19 @@ x402 payment layer.
 parallel pay capabilities [--chain <chain>]
 
 # Gas sponsoring quota for an address
-parallel pay quota --chain <chain> [--address <address>]
+parallel pay quota <address> [--chain <chain>]
 
 # Verify a payment on-chain
 parallel pay verify <txHash> --chain <chain>
 ```
 
+> **Note:** `confirmed: true` means the facilitator actually settled this hash as an x402 payment —
+> not merely that the transaction is mined. The response also carries `x402Payment` and `txMined`
+> separately: a mined transaction that is not an x402 payment returns
+> `{ confirmed: false, x402Payment: false, txMined: true }`; an unknown hash returns all three
+> `false`. Route, amount, token and recipient (`route`, `amount`, `tokenOut`, `paidTo`) are filled
+> only for confirmed payments.
+
 #### `parallel pay prepare`
 
 Builds a signed or unsigned x402 payment payload.
@@ -323,7 +341,7 @@ parallel pay prepare \
 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`, …).
+**`--token`** controls what the **merchant receives** (default: `usdp`). Accepted values: `usdp` · `usdc` · `susdp` · any backing collateral symbol (`susds`, `sfrxusd`, …) · a token contract address.
 
 **`--pay-with`** overrides which token the **agent pays with** (default: auto-detected from wallet balance). Accepted values: `usdp` · `usdc` · `susdp`.
 
@@ -346,20 +364,6 @@ 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
@@ -389,7 +393,17 @@ JSON envelope:
 
 ```json
 { "success": true, "data": { ... } }
-{ "success": false, "error": { "code": "CHAIN_SUNSET", "message": "..." } }
+{ "success": false, "error": { "code": "CHAIN_SUNSET", "message": "...", "hint": "..." } }
+```
+
+**Streams and exit codes:** success envelopes are written to **stdout**; error envelopes are written
+to **stderr**, and the process exits with code `1` (`0` on success). stdout carries data only — on a
+failure it stays empty, so `parallel … --json | jq` prints nothing when the command errors. Read
+errors from stderr or branch on the exit code (`hint` is optional):
+
+```bash
+parallel protocol tvl --chain nope --json 2>err.json || jq -r '.error.code' err.json
+# → UNKNOWN_CHAIN
 ```
 
 ---
@@ -398,7 +412,7 @@ JSON envelope:
 
 `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`.
+> `sonic` is sunset (PIP-64) — Parallelizer/Savings operations return `CHAIN_SUNSET`; USDp bridging and balance reads stay active.
 
 Not all chains support every feature. Use `parallel protocol chains` to see the full feature matrix (Parallelizer, sUSDp, bridge).
 
@@ -409,26 +423,22 @@ Not all chains support every feature. Use `parallel protocol chains` to see the
 | 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 |
+| `COLLATERAL_NOT_SUPPORTED` | Collateral (or bridge token) not accepted on this chain |
+| `WALLET_REQUIRED` | Signing requested but no wallet available (`--wallet` unresolvable) |
+| `INVALID_KEYSTORE` | Keystore unreadable, invalid format, or wrong decryption password |
+| `INVALID_AMOUNT` | Negative, zero, malformed, or sub-decimal amount / duration / slippage |
+| `MISSING_OPTION` | Required flag, argument, or subcommand not provided |
+| `INVALID_OPTION` | A provided flag or argument has an invalid value |
+| `UNKNOWN_COMMAND` / `UNKNOWN_OPTION` | Typo in a command or flag name |
 | `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) |
+| `CONFIG_KEY_NOT_FOUND` | `config get` on a key absent from the config file |
+| `RPC_ERROR` | An HTTP provider (facilitator, history APIs) is unreachable |
+| `UNKNOWN` | Any other failure |
+
+Protocol-layer errors (caps, bridge limits, sunset chains, partial reads…) are surfaced with their own code in the `code` field since 0.2.7 — e.g. `EXCEEDS_CAP`, `EXCEEDS_BRIDGE_LIMIT`, `EXCEEDS_GLOBAL_LIMIT`, `CHAIN_SUNSET`, `ROUTE_UNAVAILABLE`, `PARTIAL_READ`, `PARALLELIZER_NOT_DEPLOYED`, `COLLATERAL_NOT_SUPPORTED`, `INSUFFICIENT_BALANCE`. Match on `error.code`; the message carries the human detail (remaining capacity, valid values…) without the code prefix.
 
 ---