@parallel-protocol/cli 0.2.4 → 0.2.6

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`.
 
 
 ---
@@ -196,6 +199,7 @@ parallel swap redeem --amount <n> --chain <chain> --wallet   # proportional rede
 | `--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) |
+| `--slippage <pct>` | `0.5` | Slippage tolerance in % (`mint` / `burn` / `redeem`) |
 | `--address <0x...>` | | Receiver address for dry-run (no key needed) |
 
 ---
@@ -219,29 +223,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.
 
 ---
 
@@ -295,7 +300,7 @@ 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>
@@ -323,7 +328,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 +351,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
@@ -409,26 +400,19 @@ 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 |
+| `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_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) |
+| `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.
 
 ---
 

package/dist/index.js

@@ -1632,6 +1632,10 @@ var logger = new Logger({
 function suppressLogs() {
   logger.settings.minLevel = 7;
 }
+
+// package.json
+var package_default = {
+  version: "0.2.6"};
 function findEnvFile(dir) {
   const candidate = join(dir, ".env");
   if (existsSync(candidate)) return candidate;
@@ -3697,7 +3701,7 @@ var CHAINS_STATIC = {
       accessManager: "0x94Ea8800444017695345156319e96bdB1E355F7a",
       parallelizer: "0x6efeDDF9269c3683Ba516cb0e2124FE335F262a2",
       usdp: "0x9B3a8f7CEC208e247d97dEE13313690977e24459",
-      susdp: "0x0d45b129dc868963025Db79A9074EA9c9e32Cae4",
+      susdp: "0xd3a452B305C8285c0Dd7b8537665c734d3D279eF",
       bridgeableUsdp: "0x78BB4882b77D74aD9B04Ab71fE8e61f72595823C",
       flashParallel: "0xC9B6279baa19dBB8bCc3250c89cAa093AaBA0bfc",
       harvester: "0x36DA06796fD9d22BCD6287b66A87FfdadB12636C"
@@ -5161,13 +5165,16 @@ function quoteCmd() {
     "usdp"
   ).option("--from <chain>", "source chain").option("--to <chain>", "destination chain").option("--amount <n>", "amount to bridge").action(async function() {
     const opts = resolveOpts(this);
-    if (!opts.from)
-      throw new CliError(ErrorCode.MISSING_OPTION, "Missing --from <chain>");
-    if (!opts.to)
-      throw new CliError(ErrorCode.MISSING_OPTION, "Missing --to <chain>");
-    if (!opts.amount)
-      throw new CliError(ErrorCode.MISSING_OPTION, "Missing --amount <n>");
     try {
+      if (!opts.from)
+        throw new CliError(
+          ErrorCode.MISSING_OPTION,
+          "Missing --from <chain>"
+        );
+      if (!opts.to)
+        throw new CliError(ErrorCode.MISSING_OPTION, "Missing --to <chain>");
+      if (!opts.amount)
+        throw new CliError(ErrorCode.MISSING_OPTION, "Missing --amount <n>");
       validateToken(opts.token);
       if (CHAINS[opts.from]?.status === "sunset")
         throw new CliError(
@@ -5213,9 +5220,12 @@ function quoteCmd() {
 function feesCmd() {
   return new Command("fees").description("Show LayerZero bridge fees to all destinations from a chain").option("--token <token>", "token: usdp|susdp|prl (default: usdp)", "usdp").option("--from <chain>", "source chain").action(async function() {
     const opts = resolveOpts(this);
-    if (!opts.from)
-      throw new CliError(ErrorCode.MISSING_OPTION, "Missing --from <chain>");
     try {
+      if (!opts.from)
+        throw new CliError(
+          ErrorCode.MISSING_OPTION,
+          "Missing --from <chain>"
+        );
       validateToken(opts.token);
       if (CHAINS[opts.from]?.status === "sunset")
         throw new CliError(
@@ -5251,13 +5261,16 @@ function sendCmd() {
     "usdp"
   ).option("--from <chain>", "source chain").option("--to <chain>", "destination chain").option("--amount <n>", "amount to bridge").option("--recipient <addr>", "override destination recipient address").option("-w, --wallet [path|env]", "keystore path or 'env'").option("--address <addr>", "sender address (for dry-run without --wallet)").option("--dry-run", "build tx without broadcasting").action(async function() {
     const opts = resolveOpts(this);
-    if (!opts.from)
-      throw new CliError(ErrorCode.MISSING_OPTION, "Missing --from <chain>");
-    if (!opts.to)
-      throw new CliError(ErrorCode.MISSING_OPTION, "Missing --to <chain>");
-    if (!opts.amount)
-      throw new CliError(ErrorCode.MISSING_OPTION, "Missing --amount <n>");
     try {
+      if (!opts.from)
+        throw new CliError(
+          ErrorCode.MISSING_OPTION,
+          "Missing --from <chain>"
+        );
+      if (!opts.to)
+        throw new CliError(ErrorCode.MISSING_OPTION, "Missing --to <chain>");
+      if (!opts.amount)
+        throw new CliError(ErrorCode.MISSING_OPTION, "Missing --amount <n>");
       validateToken(opts.token);
       if (CHAINS[opts.from]?.status === "sunset")
         throw new CliError(
@@ -13239,19 +13252,19 @@ function infoCmd() {
 function stakeCmd() {
   return new Command("stake").description("Stake PRL (sPRL1) or BPT/PRL+WETH (sPRL2)").option("--type <sprl1|sprl2>", "staking type: sprl1 or sprl2").option("--amount <n>", "amount of PRL (sPRL1) or BPT (sPRL2) to stake").option("--weth-amount <n>", "WETH amount for sPRL2 PRL+WETH path").option("-w, --wallet [path|env]", "keystore path or 'env'").option("--address <addr>", "sender address (for dry-run without --wallet)").option("--dry-run", "build tx without broadcasting").action(async function() {
     const opts = resolveOpts(this);
-    if (!opts.type)
-      throw new CliError(
-        ErrorCode.MISSING_OPTION,
-        "Missing --type <sprl1|sprl2>"
-      );
-    if (!opts.amount)
-      throw new CliError(ErrorCode.MISSING_OPTION, "Missing --amount <n>");
-    if (opts.type !== "sprl1" && opts.type !== "sprl2")
-      throw new CliError(
-        ErrorCode.INVALID_AMOUNT,
-        `--type must be "sprl1" or "sprl2", got: ${opts.type}`
-      );
     try {
+      if (!opts.type)
+        throw new CliError(
+          ErrorCode.MISSING_OPTION,
+          "Missing --type <sprl1|sprl2>"
+        );
+      if (!opts.amount)
+        throw new CliError(ErrorCode.MISSING_OPTION, "Missing --amount <n>");
+      if (opts.type !== "sprl1" && opts.type !== "sprl2")
+        throw new CliError(
+          ErrorCode.INVALID_AMOUNT,
+          `--type must be "sprl1" or "sprl2", got: ${opts.type}`
+        );
       const { account, sender } = await resolveWallet(opts);
       if (opts.type === "sprl1") {
         const result = await buildStakeSprl1Tx(opts.amount, sender);
@@ -13410,17 +13423,17 @@ function unstakeCmd() {
     "shares to unstake (omit to execute ready withdrawals)"
   ).option("-w, --wallet [path|env]", "keystore path or 'env'").option("--address <addr>", "sender address (for dry-run without --wallet)").option("--dry-run", "build tx without broadcasting").action(async function() {
     const opts = resolveOpts(this);
-    if (!opts.type)
-      throw new CliError(
-        ErrorCode.MISSING_OPTION,
-        "Missing --type <sprl1|sprl2>"
-      );
-    if (opts.type !== "sprl1" && opts.type !== "sprl2")
-      throw new CliError(
-        ErrorCode.INVALID_AMOUNT,
-        `--type must be "sprl1" or "sprl2", got: ${opts.type}`
-      );
     try {
+      if (!opts.type)
+        throw new CliError(
+          ErrorCode.MISSING_OPTION,
+          "Missing --type <sprl1|sprl2>"
+        );
+      if (opts.type !== "sprl1" && opts.type !== "sprl2")
+        throw new CliError(
+          ErrorCode.INVALID_AMOUNT,
+          `--type must be "sprl1" or "sprl2", got: ${opts.type}`
+        );
       const { account, sender } = await resolveWallet(opts);
       if (sender !== ZERO_ADDRESS4 && opts.amount) {
         const info = await getStakingInfo(sender);
@@ -13533,17 +13546,17 @@ function claimCmd() {
     "reward type to claim: sprl1, sprl2, or all"
   ).option("-w, --wallet [path|env]", "keystore path or 'env'").option("--address <addr>", "sender address (for dry-run without --wallet)").option("--dry-run", "build tx without broadcasting").action(async function() {
     const opts = resolveOpts(this);
-    if (!opts.type)
-      throw new CliError(
-        ErrorCode.MISSING_OPTION,
-        "Missing --type <sprl1|sprl2|all>"
-      );
-    if (opts.type !== "sprl1" && opts.type !== "sprl2" && opts.type !== "all")
-      throw new CliError(
-        ErrorCode.INVALID_AMOUNT,
-        `--type must be "sprl1", "sprl2", or "all", got: ${opts.type}`
-      );
     try {
+      if (!opts.type)
+        throw new CliError(
+          ErrorCode.MISSING_OPTION,
+          "Missing --type <sprl1|sprl2|all>"
+        );
+      if (opts.type !== "sprl1" && opts.type !== "sprl2" && opts.type !== "all")
+        throw new CliError(
+          ErrorCode.INVALID_AMOUNT,
+          `--type must be "sprl1", "sprl2", or "all", got: ${opts.type}`
+        );
       const { account, sender } = await resolveWallet(opts);
       const result = await buildClaimRewardsTx(
         opts.type,
@@ -14582,18 +14595,14 @@ function swapCommand() {
 }
 
 // ../mcp-server/package.json
-var package_default = {
-  version: "1.0.0"};
-
-// package.json
 var package_default2 = {
-  version: "0.2.4"};
+  version: "1.0.0"};
 
 // src/commands/version.ts
 function versionCommand() {
   return new Command("version").description("Show CLI and runtime versions").action(() => {
-    const cliVersion = package_default2.version;
-    const mcpVersion = package_default.version;
+    const cliVersion = package_default.version;
+    const mcpVersion = package_default2.version;
     const runtime2 = process.version;
     const entries = [
       ["parallel CLI", `v${cliVersion}`],
@@ -14611,7 +14620,7 @@ function versionCommand() {
 loadEnv(import.meta.url);
 suppressLogs();
 var program = new Command();
-program.name("parallel").description("Parallel Protocol CLI").version("0.1.0").option("-c, --chain <chain>", "target chain (e.g. base, ethereum)").option("--rpc <url>", "custom RPC URL").option("-j, --json", "force JSON output").option("--dry-run", "build transaction without broadcasting").option(
+program.name("parallel").description("Parallel Protocol CLI").version(package_default.version).option("-c, --chain <chain>", "target chain (e.g. base, ethereum)").option("--rpc <url>", "custom RPC URL").option("-j, --json", "force JSON output").option("--dry-run", "build transaction without broadcasting").option(
   "-w, --wallet [path|env]",
   "keystore path, 'env', or alone to auto-resolve from config/env"
 ).option("--gas-limit <n>", "override gas limit").option("-v, --verbose", "verbose logs").option("--no-cache", "bypass TTL cache, force fresh RPC call").hook("preAction", (thisCommand) => {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@parallel-protocol/cli",
-	"version": "0.2.4",
+	"version": "0.2.6",
 	"private": false,
 	"type": "module",
 	"files": [