@parallel-protocol/cli 0.2.6 → 0.2.7

package/README.md

@@ -173,33 +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` / `burn` / `redeem`) |
+| `--slippage <pct>` | `0.5` | Slippage tolerance in % (`mint` / `redeem` / `redeem-all`) |
 | `--address <0x...>` | | Receiver address for dry-run (no key needed) |
 
 ---
@@ -263,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
@@ -306,6 +312,13 @@ parallel pay quota <address> [--chain <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.
@@ -380,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
 ```
 
 ---
@@ -389,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).
 
@@ -406,13 +429,16 @@ Not all chains support every feature. Use `parallel protocol chains` to see the
 | `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, or unparseable amount |
-| `MISSING_OPTION` | Required flag not provided |
+| `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 |
-| `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 |
 
-Errors raised by the protocol layer (caps, bridge limits, slippage, cooldowns, expired authorizations…) surface with `code: "UNKNOWN"` and the underlying reason at the start of `message` — e.g. `[EXCEEDS_BRIDGE_LIMIT] Daily bridge limit reached`. Match on the message prefix, not the code, for these.
+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.
 
 ---