@fastxyz/cli 1.0.3 → 1.1.1

package/README.md

@@ -32,11 +32,18 @@ fast account create
 # Check balances
 fast info balance
 
-# Send USDC
+# Send the network's default token (fastUSD on mainnet) — Fast → Fast
 fast send fast1abc...xyz 10
 
-# Bridge from Arbitrum Sepolia to Fast
-fast fund crypto 50 --chain arbitrum-sepolia
+# Send a specific token explicitly
+fast send fast1abc...xyz 10 --token USDC
+
+# Bridge USDC from Arbitrum Sepolia to Fast (--token USDC is required on
+# mainnet because the network default — fastUSD — is not on EVM chains)
+fast fund usdc crypto 50 --chain arbitrum-sepolia --token USDC
+
+# Or get a unified Fast web-app URL to fund fastUSD (mainnet only)
+fast fund fastusd --amount 50
 
 # Pay an x402-protected API
 fast pay https://api.example.com/resource
@@ -73,6 +80,32 @@ These options work with every command:
 | `--non-interactive` | Auto-confirm confirmations and fail when required input is missing |
 | `--debug` | Enable verbose debug logging to stderr |
 
+### Default token
+
+Commands that accept `--token` (currently `fast send` and `fast fund usdc
+crypto`) default to the active network's `defaultToken.symbol` when the flag
+is omitted: `fastUSD` on mainnet, `testUSDC` on testnet. Bridge routes
+additionally require the resolved token to exist on the target chain — on
+mainnet bridges you must pass `--token USDC` explicitly because `fastUSD` does
+not exist on EVM chains.
+
+To customize the default, register a network with `fast network add <name>
+--config <path>` where the JSON config includes a `defaultToken` field, for
+example:
+
+```json
+{
+  "defaultToken": {
+    "symbol": "USDC",
+    "tokenId": "0x...",
+    "decimals": 6
+  }
+}
+```
+
+If a custom network omits `defaultToken`, callers must pass `--token`
+explicitly; otherwise the command errors with `INVALID_USAGE`.
+
 ## Commands
 
 ### `fast account create`
@@ -98,6 +131,7 @@ fast account import --name my-imported-account --private-key 0x...
 ```
 
 **Options:**
+
 - `--name <alias>` — Optional human-readable alias for the imported account
 - `--private-key <hex>` — Hex-encoded 32-byte private key
 - `--key-file <path>` — Path to a JSON file containing a `privateKey` field
@@ -157,13 +191,15 @@ fast send fast1recipient... 10.5 --token USDC
 ```
 
 **Positional arguments:**
+
 - `<address>` — Recipient address (`fast1...` for Fast, `0x...` for EVM)
 - `<amount>` — Human-readable amount (for example, `10` or `1.5`)
 
 **Options:**
+
 - `--from-chain <chain>` — Source EVM chain for EVM → Fast transfers
 - `--to-chain <chain>` — Destination EVM chain for Fast → EVM transfers
-- `--token <token>` — Token symbol or token ID (defaults to the first configured bridge token, typically `USDC`)
+- `--token <token>` — Token symbol or token ID. Defaults to the network's `defaultToken.symbol` (`fastUSD` on mainnet, `testUSDC` on testnet). Bridge routes require the resolved token to be available on the target chain; otherwise the command errors with `CommandUnsupportedForTokenError`.
 - `--eip-7702` — Use the smart deposit flow for EVM → Fast transfers
 - `--account <name>` — Sender account (defaults to the configured default)
 
@@ -212,6 +248,7 @@ fast info history --from fast1... --limit 20
 ```
 
 **Options:**
+
 - `--from <address>` — Filter by sender address
 - `--to <address>` — Filter by recipient address
 - `--token <token>` — Filter by token name or token ID
@@ -240,39 +277,152 @@ fast info bridge-tokens
 
 ---
 
-### `fast fund fiat`
+### `fast fund usdc fiat`
 
-Get a fiat on-ramp URL for funding a Fast address.
+Get a fiat on-ramp URL for funding a Fast address with USDC. The URL targets
+[ramp.fast.xyz](https://ramp.fast.xyz); the deposit lands on Fast as bridged
+USDC, distinct from the Fast-native `fastUSD`.
 
 ```bash
-fast fund fiat --network mainnet
+fast fund usdc fiat --network mainnet
 ```
 
 **Requirements:**
-- Only available on `mainnet`
-- Prints a funding URL for you to open in your browser
 
-**Options:**
-- `--address <fast-address>` — Fund a specific Fast address directly (otherwise uses the selected account)
-- `--network <name>` — Must be `mainnet`
+- Mainnet only (Ramp does not support testnet).
+- Active account or `--address <fast1...>`.
 
 ---
 
-### `fast fund crypto <amount>`
+### `fast fund usdc crypto <amount>`
 
-Bridge crypto from an EVM chain to the Fast network.
+Bridge USDC from an EVM chain to the Fast network. The deposit lands as
+bridged USDC on Fast (distinct from `fastUSD`).
 
 ```bash
-fast fund crypto 10.5 --chain arbitrum-sepolia --token USDC
+fast fund usdc crypto 10.5 --chain arbitrum-sepolia --token USDC
 ```
 
 **Positional arguments:**
-- `<amount>` — Human-readable amount
+
+- `<amount>` — Human-readable amount to bridge (e.g., `10.5`).
+
+**Options:**
+
+- `--chain <chain>` — Source EVM chain (required).
+- `--token <token>` — Token symbol or token ID. Defaults to the network's `defaultToken.symbol`. On mainnet that's `fastUSD`, which is **not** on EVM chains — pass `--token USDC` explicitly for the bridge case, or the command errors with `CommandUnsupportedForTokenError`.
+- `--eip-7702` — Use the smart deposit flow (gas paid in USDC via paymaster).
+
+---
+
+### `fast fund fastusd`
+
+Print an `app.fast.xyz/send` URL that opens the unified Fast web app to fund
+your account with **fastUSD** (a Fast-native token, separate from bridged USDC).
+The web app handles fiat-onramp, crypto-bridge, and wallet-to-wallet funding
+under the hood; the CLI's job is just to produce the URL.
+
+```bash
+fast fund fastusd
+# → https://app.fast.xyz/send?to=fast1...
+
+fast fund fastusd --amount 25
+# → https://app.fast.xyz/send?to=fast1...&amount=25
+
+fast fund fastusd --to fast1someoneelse --amount 10
+# → https://app.fast.xyz/send?to=fast1someoneelse&amount=10
+```
+
+**Options:**
+
+- `--to <fast1...>` — Recipient Fast address (default: active account).
+- `--amount <decimal>` — Optional amount; if omitted, the web app prompts.
+
+**Requirements:**
+
+- Mainnet only.
+
+---
+
+### `fast authorize request`
+
+Generate a one-time HPKE authorization request. The command creates a URL for the wallet user to open, and stores a short-lived key in `~/.fast/handover-pending.json` (mode 0600, up to 5 minutes).
+
+```bash
+fast authorize request [--requester NAME] [--url URL]
+```
+
+**Options:**
+
+- `--requester <name>` — Optional label shown to the wallet user to identify who is requesting
+- `--url <url>` — Override the wallet base URL the auth link points to (default: `https://app.fast.xyz/authorize`). Useful for local dev against a non-production wallet, e.g. `--url http://localhost:3000/authorize`.
+
+**Output (human):**
+
+```
+Authorization URL:
+  https://app.fast.xyz/authorize?data=eyJ...
+
+Fingerprint:    123456
+Expires at:     2026-05-25T12:05:00Z
+
+Show the URL to the wallet user. Once they paste back the handover
+code, run:
+  fast authorize complete --message '<paste here>'
+```
+
+**Output (`--json`):**
+
+```json
+{
+  "auth_url": "...",
+  "request_fingerprint": "123456",
+  "request_expires_at": "2026-05-25T12:05:00Z"
+}
+```
+
+**Security note:** `~/.fast/handover-pending.json` contains the HPKE one-time private key — not the account seed. An attacker who steals only this file cannot derive the account key; they would also need to intercept the handover code the wallet user pastes back. The file expires within 5 minutes and is deleted after a successful `authorize complete`.
+
+---
+
+### `fast authorize complete`
+
+Decrypt a handover code returned by the wallet user and print the account private key to stdout.
+
+```bash
+fast authorize complete [--message TEXT | --stdin] [--print-account] [--json]
+```
 
 **Options:**
-- `--chain <chain>` — Source EVM chain (required)
-- `--token <token>` — Token symbol or token ID (defaults to `USDC` / `testUSDC`)
-- `--eip-7702` — Use the smart deposit flow when supported
+
+- `--message <text>` — Handover code or chat message containing it (bare base64url or quoted)
+- `--stdin` — Read the handover code from stdin (e.g., `cat code.txt | fast authorize complete --stdin`)
+- `--print-account` — Also print the derived Fast address and public key
+- `--json` — Emit JSON output
+
+If neither `--message` nor `--stdin` is provided, the CLI prompts interactively. With `--non-interactive`, absence of both flags is an error.
+
+**Output (human, default):**
+
+```
+0x1313131313131313131313131313131313131313131313131313131313131313
+```
+
+**Output (human, `--print-account`):**
+
+```
+Private key:     0x1313...
+Address:         fast1abc...xyz
+Public key:      0xdead...beef
+```
+
+**Output (`--json`):**
+
+```json
+{ "private_key": "0x1313..." }
+```
+
+After a successful decryption, `~/.fast/handover-pending.json` is deleted. On decryption failures, the state file is updated (or deleted after 3 attempts) so the same request may be retried.
 
 ---
 
@@ -285,9 +435,11 @@ fast pay https://api.example.com/premium
 ```
 
 **Positional arguments:**
+
 - `<url>` — URL of the x402-protected resource (required)
 
 **Options:**
+
 - `--dry-run` — Show payment details without actually paying
 - `--method <GET|POST|...>` — HTTP method (default: GET)
 - `--header <key:value>` — Custom request header (can be repeated)
@@ -324,12 +476,15 @@ fast network add my-custom-net --config ./network-config.json
 ```
 
 **Positional arguments:**
+
 - `<name>` — Unique name for the network
 
 **Options:**
+
 - `--config <path>` — Path to a JSON file with the network configuration (required)
 
 **Example JSON config (`network-config.json`):**
+
 ```json
 {
   "url": "https://api.fast.xyz/proxy-rest",
@@ -383,8 +538,11 @@ The CLI stores data in `~/.fast/`:
 # 1. Create an account
 fast account create --name my-account
 
-# 2. Get a fiat on-ramp URL
-fast fund fiat --network mainnet --address fast1...
+# 2. Get a fiat on-ramp URL (delivers USDC to your Fast account)
+fast fund usdc fiat --network mainnet --address fast1...
+
+# 2b. Or open the unified Fast web app to fund fastUSD
+fast fund fastusd --network mainnet
 
 # 3. Check your balance
 fast info balance --account my-account

package/dist/{app-ZXKQBKVM.js → app-OXURVZBK.js}

@@ -7,7 +7,7 @@ import {
   getBundledNetworks,
   getVersion,
   isBundledNetwork
-} from "./chunk-UZZ2O26Y.js";
+} from "./chunk-CPDXMZPW.js";
 import "./chunk-77HVPD4G.js";
 export {
   AppConfig,

package/dist/{chunk-UZZ2O26Y.js → chunk-CPDXMZPW.js}

@@ -7,7 +7,7 @@ import { Context, Layer } from "effect";
 var package_default = {
   name: "@fastxyz/cli",
   description: "Fast CLI - Account, network, and transaction management",
-  version: "1.0.3",
+  version: "1.1.1",
   repository: {
     type: "git",
     url: "https://github.com/fastxyz/fast-sdk",
@@ -25,7 +25,8 @@ var package_default = {
   scripts: {
     build: "tsup",
     prepack: "tsup",
-    dev: "tsup --watch"
+    dev: "tsup --watch",
+    test: "vitest run"
   },
   dependencies: {
     "@clack/core": "^1.2.0",
@@ -67,7 +68,7 @@ var mainnet = {
   explorerUrl: "https://explorer.fast.xyz",
   networkId: "fast:mainnet",
   defaultToken: {
-    tokenId: "0x125b60bb2e805336f0934077d4f9fdb36f45bec9ded8d7b0e637516cc43a86eb",
+    tokenId: "0xc655a12330da6af361d281b197996d2bc135aaed3b66278e729c2222291e9130",
     symbol: "fastUSD",
     decimals: 6
   }
@@ -89,6 +90,7 @@ var bundledNetworks = {
     url: testnet.url,
     explorerUrl: testnet.explorerUrl,
     networkId: testnet.networkId,
+    defaultToken: testnet.defaultToken,
     allSet: {
       crossSignUrl: "https://testnet.cross-sign.allset.fast.xyz",
       portalApiUrl: "https://testnet.allset.fast.xyz/api",
@@ -130,6 +132,7 @@ var bundledNetworks = {
     url: mainnet.url,
     explorerUrl: mainnet.explorerUrl,
     networkId: mainnet.networkId,
+    defaultToken: mainnet.defaultToken,
     allSet: {
       crossSignUrl: "https://cross-sign.allset.fast.xyz",
       portalApiUrl: "https://allset.fast.xyz/api",

package/dist/{chunk-DITXH2ZY.js → chunk-NUQ2N6AG.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   AppConfig
-} from "./chunk-UZZ2O26Y.js";
+} from "./chunk-CPDXMZPW.js";
 import {
   DatabaseService,
   DefaultNetworkError,
@@ -13,7 +13,7 @@ import {
   ReservedNameError,
   customNetworks,
   metadata
-} from "./chunk-T7HRTMD7.js";
+} from "./chunk-WXSBQOV4.js";
 
 // src/services/storage/network.ts
 import { readFileSync } from "fs";
@@ -2310,10 +2310,16 @@ var AllSetConfigSchema = Schema19.Struct({
   portalApiUrl: Schema19.String,
   chains: Schema19.Record({ key: Schema19.String, value: AllSetChainSchema })
 });
+var FastTokenSchema = Schema19.Struct({
+  tokenId: Schema19.String,
+  symbol: Schema19.String,
+  decimals: Schema19.Number
+});
 var NetworkConfigSchema = Schema19.Struct({
   url: Schema19.String,
   explorerUrl: Schema19.String,
   networkId: NetworkId,
+  defaultToken: Schema19.optional(FastTokenSchema),
   allSet: Schema19.optional(AllSetConfigSchema)
 });
 var BundledNetworksSchema = Schema19.Record({

package/dist/{chunk-T7HRTMD7.js → chunk-WXSBQOV4.js}

@@ -140,16 +140,57 @@ var FastSdkError = class extends Data2.TaggedError("FastSdkError") {
   errorCode = "FAST_SDK_ERROR";
 };
 
-// src/errors/network.ts
+// src/errors/key-handover.ts
 import { Data as Data3 } from "effect";
-var NetworkExistsError = class extends Data3.TaggedError("NetworkExistsError") {
+var PendingAlreadyExistsError = class extends Data3.TaggedError(
+  "PendingAlreadyExistsError"
+) {
+  exitCode = 1;
+  errorCode = "PENDING_ALREADY_EXISTS";
+  get message() {
+    return `Already have a pending authorization request (fingerprint ${this.fingerprint}, expires ${this.expiresAt}). Run 'fast authorize complete' to finish it, or wait until it expires.`;
+  }
+};
+var NoPendingRequestError = class extends Data3.TaggedError(
+  "NoPendingRequestError"
+) {
+  exitCode = 1;
+  errorCode = "NO_PENDING_REQUEST";
+  message = "No pending authorization request. Run 'fast authorize request' first.";
+};
+var CorruptPendingStateError = class extends Data3.TaggedError(
+  "CorruptPendingStateError"
+) {
+  exitCode = 1;
+  errorCode = "CORRUPT_PENDING_STATE";
+  get message() {
+    return `Corrupt pending state file (${this.reason}). Delete ~/.fast/handover-pending.json and run 'request' again.`;
+  }
+};
+var MissingHandoverMessageError = class extends Data3.TaggedError(
+  "MissingHandoverMessageError"
+) {
+  exitCode = 2;
+  errorCode = "MISSING_HANDOVER_MESSAGE";
+  message = "Missing handover code. Provide --message <code> or --stdin, or run without --non-interactive.";
+};
+var KeyHandoverProtocolError = class extends Data3.TaggedError(
+  "KeyHandoverProtocolError"
+) {
+  exitCode = 1;
+  errorCode = "KEY_HANDOVER_PROTOCOL_ERROR";
+};
+
+// src/errors/network.ts
+import { Data as Data4 } from "effect";
+var NetworkExistsError = class extends Data4.TaggedError("NetworkExistsError") {
   exitCode = 2;
   errorCode = "NETWORK_EXISTS";
   get message() {
     return `Network "${this.name}" already exists`;
   }
 };
-var NetworkNotFoundError = class extends Data3.TaggedError(
+var NetworkNotFoundError = class extends Data4.TaggedError(
   "NetworkNotFoundError"
 ) {
   exitCode = 2;
@@ -158,7 +199,7 @@ var NetworkNotFoundError = class extends Data3.TaggedError(
     return `Network "${this.name}" not found`;
   }
 };
-var DefaultNetworkError = class extends Data3.TaggedError(
+var DefaultNetworkError = class extends Data4.TaggedError(
   "DefaultNetworkError"
 ) {
   exitCode = 2;
@@ -167,7 +208,7 @@ var DefaultNetworkError = class extends Data3.TaggedError(
     return `Cannot remove "${this.name}" because it is the default network. Use \`fast network set-default\` first.`;
   }
 };
-var NoDefaultNetworkError = class extends Data3.TaggedError(
+var NoDefaultNetworkError = class extends Data4.TaggedError(
   "NoDefaultNetworkError"
 ) {
   exitCode = 2;
@@ -176,14 +217,14 @@ var NoDefaultNetworkError = class extends Data3.TaggedError(
     return "No default network set. Use `fast network set-default <name>` to set one.";
   }
 };
-var ReservedNameError = class extends Data3.TaggedError("ReservedNameError") {
+var ReservedNameError = class extends Data4.TaggedError("ReservedNameError") {
   exitCode = 2;
   errorCode = "RESERVED_NAME";
   get message() {
     return `"${this.name}" is a reserved name and cannot be modified`;
   }
 };
-var InvalidNetworkConfigError = class extends Data3.TaggedError(
+var InvalidNetworkConfigError = class extends Data4.TaggedError(
   "InvalidNetworkConfigError"
 ) {
   exitCode = 2;
@@ -192,7 +233,7 @@ var InvalidNetworkConfigError = class extends Data3.TaggedError(
     return `Invalid network config for "${this.name}"`;
   }
 };
-var UnsupportedChainError = class extends Data3.TaggedError(
+var UnsupportedChainError = class extends Data4.TaggedError(
   "UnsupportedChainError"
 ) {
   exitCode = 2;
@@ -203,26 +244,26 @@ var UnsupportedChainError = class extends Data3.TaggedError(
 };
 
 // src/errors/payment.ts
-import { Data as Data4 } from "effect";
-var PaymentRejectedError = class extends Data4.TaggedError(
+import { Data as Data5 } from "effect";
+var PaymentRejectedError = class extends Data5.TaggedError(
   "PaymentRejectedError"
 ) {
   exitCode = 6;
   errorCode = "PAYMENT_REJECTED";
 };
-var PaymentFailedError = class extends Data4.TaggedError(
+var PaymentFailedError = class extends Data5.TaggedError(
   "PaymentFailedError"
 ) {
   exitCode = 1;
   errorCode = "PAYMENT_FAILED";
 };
-var InvalidPaymentLinkError = class extends Data4.TaggedError(
+var InvalidPaymentLinkError = class extends Data5.TaggedError(
   "InvalidPaymentLinkError"
 ) {
   exitCode = 2;
   errorCode = "INVALID_PAYMENT_LINK";
 };
-var InsufficientPaymentBalanceError = class extends Data4.TaggedError(
+var InsufficientPaymentBalanceError = class extends Data5.TaggedError(
   "InsufficientPaymentBalanceError"
 ) {
   exitCode = 4;
@@ -230,69 +271,79 @@ var InsufficientPaymentBalanceError = class extends Data4.TaggedError(
 };
 
 // src/errors/transaction.ts
-import { Data as Data5 } from "effect";
-var TxNotFoundError = class extends Data5.TaggedError("TxNotFoundError") {
+import { Data as Data6 } from "effect";
+var TxNotFoundError = class extends Data6.TaggedError("TxNotFoundError") {
   exitCode = 1;
   errorCode = "TX_NOT_FOUND";
   get message() {
     return `Transaction not found: ${this.hash}`;
   }
 };
-var TransactionFailedError = class extends Data5.TaggedError(
+var TransactionFailedError = class extends Data6.TaggedError(
   "TransactionFailedError"
 ) {
   exitCode = 2;
   errorCode = "TX_FAILED";
 };
-var InvalidAddressError = class extends Data5.TaggedError(
+var InvalidAddressError = class extends Data6.TaggedError(
   "InvalidAddressError"
 ) {
   exitCode = 2;
   errorCode = "INVALID_ADDRESS";
 };
-var InvalidAmountError = class extends Data5.TaggedError("InvalidAmountError") {
+var InvalidAmountError = class extends Data6.TaggedError("InvalidAmountError") {
   exitCode = 2;
   errorCode = "INVALID_AMOUNT";
 };
-var InsufficientBalanceError = class extends Data5.TaggedError(
+var InsufficientBalanceError = class extends Data6.TaggedError(
   "InsufficientBalanceError"
 ) {
   exitCode = 2;
   errorCode = "INSUFFICIENT_BALANCE";
 };
-var InsufficientGasError = class extends Data5.TaggedError(
+var InsufficientGasError = class extends Data6.TaggedError(
   "InsufficientGasError"
 ) {
   exitCode = 2;
   errorCode = "INSUFFICIENT_GAS";
 };
-var TokenNotFoundError = class extends Data5.TaggedError("TokenNotFoundError") {
+var TokenNotFoundError = class extends Data6.TaggedError("TokenNotFoundError") {
   exitCode = 2;
   errorCode = "TOKEN_NOT_FOUND";
   get message() {
     return `Unknown token "${this.token}". Run \`fast info bridge-tokens\` to list supported tokens.`;
   }
 };
-var FundingRequiredError = class extends Data5.TaggedError(
+var FundingRequiredError = class extends Data6.TaggedError(
   "FundingRequiredError"
 ) {
   exitCode = 4;
   errorCode = "FUNDING_REQUIRED";
 };
+var CommandUnsupportedForTokenError = class extends Data6.TaggedError(
+  "CommandUnsupportedForTokenError"
+) {
+  exitCode = 2;
+  errorCode = "COMMAND_UNSUPPORTED_FOR_TOKEN";
+  get message() {
+    const base = `${this.command} is not supported for ${this.token} on ${this.network}.`;
+    return this.suggestion ? `${base} ${this.suggestion}` : base;
+  }
+};
 
 // src/errors/usage.ts
-import { Data as Data6 } from "effect";
-var InvalidUsageError = class extends Data6.TaggedError("InvalidUsageError") {
+import { Data as Data7 } from "effect";
+var InvalidUsageError = class extends Data7.TaggedError("InvalidUsageError") {
   exitCode = 2;
   errorCode = "INVALID_USAGE";
 };
-var NotImplementedError = class extends Data6.TaggedError(
+var NotImplementedError = class extends Data7.TaggedError(
   "NotImplementedError"
 ) {
   exitCode = 2;
   errorCode = "NOT_IMPLEMENTED";
 };
-var UserCancelledError = class extends Data6.TaggedError("UserCancelledError") {
+var UserCancelledError = class extends Data7.TaggedError("UserCancelledError") {
   exitCode = 2;
   errorCode = "USER_CANCELLED";
   get message() {
@@ -343,6 +394,11 @@ export {
   FileIOError,
   InternalError,
   FastSdkError,
+  PendingAlreadyExistsError,
+  NoPendingRequestError,
+  CorruptPendingStateError,
+  MissingHandoverMessageError,
+  KeyHandoverProtocolError,
   NetworkExistsError,
   NetworkNotFoundError,
   DefaultNetworkError,
@@ -359,6 +415,7 @@ export {
   InvalidAmountError,
   TokenNotFoundError,
   FundingRequiredError,
+  CommandUnsupportedForTokenError,
   InvalidUsageError,
   UserCancelledError,
   accounts,

package/dist/{database-NXA7GQKE.js → database-CKOZYRD7.js}

@@ -2,7 +2,7 @@
 import {
   DatabaseLive,
   DatabaseService
-} from "./chunk-T7HRTMD7.js";
+} from "./chunk-WXSBQOV4.js";
 import "./chunk-77HVPD4G.js";
 export {
   DatabaseLive,