@fastxyz/cli 1.0.2 → 1.1.0

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-PZWIJK2U.js → app-WYI56SLP.js}

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

package/dist/{chunk-ECO24H3M.js → chunk-FLVU732R.js}

@@ -1,20 +1,96 @@
 #!/usr/bin/env node
 
 // src/services/config/app.ts
-import { Context, Layer, Schema as Schema2 } from "effect";
+import { Context, Layer } from "effect";
 
-// src/config/app.json
-var app_default = {
-  name: "fast",
-  version: "1.0.1"
+// package.json
+var package_default = {
+  name: "@fastxyz/cli",
+  description: "Fast CLI - Account, network, and transaction management",
+  version: "1.1.0",
+  repository: {
+    type: "git",
+    url: "https://github.com/fastxyz/fast-sdk",
+    directory: "app/cli"
+  },
+  bin: {
+    fast: "./dist/main.js"
+  },
+  type: "module",
+  files: [
+    "dist",
+    "drizzle",
+    "README.md"
+  ],
+  scripts: {
+    build: "tsup",
+    prepack: "tsup",
+    dev: "tsup --watch",
+    test: "vitest run"
+  },
+  dependencies: {
+    "@clack/core": "^1.2.0",
+    "@effect/platform": "^0.96.0",
+    "@effect/platform-node": "^0.106.0",
+    "@effect/printer": "^0.49.0",
+    "@effect/printer-ansi": "^0.49.0",
+    "@effect/typeclass": "^0.40.0",
+    "@optique/core": "^0.10.7",
+    bech32: "^2.0.0",
+    "better-sqlite3": "^12.8.0",
+    "cli-table3": "^0.6.5",
+    "drizzle-orm": "^0.45.2",
+    effect: "^3.21.0",
+    uuid: "^11.1.0"
+  },
+  devDependencies: {
+    "@fastxyz/allset-sdk": "workspace:*",
+    "@fastxyz/schema": "workspace:*",
+    "@fastxyz/sdk": "workspace:*",
+    "@fastxyz/x402-client": "workspace:*",
+    "@noble/ciphers": "^1.3.0",
+    "@noble/curves": "^2.0.1",
+    "@noble/hashes": "^2.0.1",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^25.5.0",
+    "@types/uuid": "^10.0.0",
+    "drizzle-kit": "^0.31.10"
+  },
+  publishConfig: {
+    access: "public",
+    provenance: true
+  }
 };
 
-// src/config/networks.json
-var networks_default = {
+// ../../packages/fast-sdk/dist/networks/index.js
+var mainnet = {
+  url: "https://api.fast.xyz/proxy-rest",
+  explorerUrl: "https://explorer.fast.xyz",
+  networkId: "fast:mainnet",
+  defaultToken: {
+    tokenId: "0x125b60bb2e805336f0934077d4f9fdb36f45bec9ded8d7b0e637516cc43a86eb",
+    symbol: "fastUSD",
+    decimals: 6
+  }
+};
+var testnet = {
+  url: "https://testnet.api.fast.xyz/proxy-rest",
+  explorerUrl: "https://testnet.explorer.fast.xyz",
+  networkId: "fast:testnet",
+  defaultToken: {
+    tokenId: "0xd73a0679a2be46981e2a8aedecd951c8b6690e7d5f8502b34ed3ff4cc2163b46",
+    symbol: "testUSDC",
+    decimals: 6
+  }
+};
+
+// src/config/networks.ts
+var bundledNetworks = {
   testnet: {
-    url: "https://testnet.api.fast.xyz/proxy-rest",
-    explorerUrl: "https://testnet.explorer.fast.xyz",
-    networkId: "fast:testnet",
+    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",
@@ -53,9 +129,10 @@ var networks_default = {
     }
   },
   mainnet: {
-    url: "https://api.fast.xyz/proxy-rest",
-    explorerUrl: "https://explorer.fast.xyz",
-    networkId: "fast:mainnet",
+    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",
@@ -110,44 +187,10 @@ var networks_default = {
   }
 };
 
-// src/schemas/networks.ts
-import { Schema } from "effect";
-var AllSetChainTokenSchema = Schema.Struct({
-  evmAddress: Schema.String,
-  fastTokenId: Schema.String,
-  decimals: Schema.Number
-});
-var AllSetChainSchema = Schema.Struct({
-  chainId: Schema.Number,
-  bridgeContract: Schema.String,
-  fastBridgeAddress: Schema.String,
-  relayerUrl: Schema.String,
-  evmRpcUrl: Schema.String,
-  evmExplorerUrl: Schema.String,
-  tokens: Schema.Record({ key: Schema.String, value: AllSetChainTokenSchema })
-});
-var AllSetConfigSchema = Schema.Struct({
-  crossSignUrl: Schema.String,
-  portalApiUrl: Schema.String,
-  chains: Schema.Record({ key: Schema.String, value: AllSetChainSchema })
-});
-var NetworkConfigSchema = Schema.Struct({
-  url: Schema.String,
-  explorerUrl: Schema.String,
-  networkId: Schema.String,
-  allSet: Schema.optional(AllSetConfigSchema)
-});
-var BundledNetworksSchema = Schema.Record({
-  key: Schema.String,
-  value: NetworkConfigSchema
-});
-
 // src/services/config/app.ts
-var bundledNetworks = Schema2.decodeUnknownSync(
-  BundledNetworksSchema
-)(networks_default);
-var getAppName = () => app_default.name;
-var getVersion = () => app_default.version;
+var appName = Object.keys(package_default.bin)[0] ?? "fast";
+var getAppName = () => appName;
+var getVersion = () => package_default.version;
 var getBundledNetworks = () => bundledNetworks;
 var isBundledNetwork = (name) => Object.hasOwn(bundledNetworks, name);
 var getBundledNetwork = (name) => bundledNetworks[name];
@@ -162,7 +205,6 @@ var AppConfigLive = Layer.sync(AppConfig, () => ({
 }));
 
 export {
-  NetworkConfigSchema,
   getAppName,
   getVersion,
   getBundledNetworks,