v0.2.5: sync from monorepo 2026-03-07

Author: azeth-sync[bot]

README.md

@@ -38,7 +38,7 @@ azeth call https://api.example.com/eth-price --max-amount 0.10
 | `AZETH_PRIVATE_KEY` | Yes | Account owner's private key |
 | `PIMLICO_API_KEY` | Yes* | Pimlico bundler key (*required for state-changing ops) |
 | `AZETH_CHAIN` | No | Default chain (`baseSepolia`) |
-| `BASE_RPC_URL` | No | RPC endpoint URL |
+| `AZETH_RPC_URL_BASE_SEPOLIA` | No | RPC endpoint (per-chain: `AZETH_RPC_URL_BASE`, etc.) |
 | `AZETH_SERVER_URL` | No | Azeth server URL |
 
 ## Commands

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azeth/cli",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "type": "module",
   "description": "CLI for the Azeth trust infrastructure — register, discover, pay, and manage machine participants",
   "license": "MIT",
@@ -35,8 +35,8 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@azeth/common": "^0.2.4",
-    "@azeth/sdk": "^0.2.4",
+    "@azeth/common": "^0.2.5",
+    "@azeth/sdk": "^0.2.5",
     "commander": "^12.1.0",
     "chalk": "^5.3.0",
     "ora": "^8.1.0",

src/commands/quickstart.ts

@@ -5,6 +5,7 @@ import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
 import { AzethKit, type AzethKitConfig } from '@azeth/sdk';
 import { isValidChainName, TOKENS, type Guardrails, type SupportedChainName } from '@azeth/common';
 import { printHeader, printField, printSuccess, printError } from '../utils/display.js';
+import { saveKey } from '../utils/key-persistence.js';
 
 const DEFAULT_SERVER_URL = 'https://api.azeth.ai';
 
@@ -62,6 +63,7 @@ export const quickstartCommand = new Command('quickstart')
       } else {
         privateKey = generatePrivateKey();
         generated = true;
+        saveKey(privateKey);
       }
 
       const account = privateKeyToAccount(privateKey);
@@ -83,13 +85,16 @@ export const quickstartCommand = new Command('quickstart')
       }
 
       // Step 4: Build AzethKitConfig directly (no env vars required)
+      const serverUrl = process.env['AZETH_SERVER_URL'] ?? DEFAULT_SERVER_URL;
       const config: AzethKitConfig = {
         privateKey,
         chain,
-        serverUrl: process.env['AZETH_SERVER_URL'] ?? DEFAULT_SERVER_URL,
+        serverUrl,
       };
 
-      const spinner = ora(`Deploying smart account on ${chain} (gas sponsored by Azeth)...`).start();
+      // SDK auto-tries gasless relay (createAccountWithSignature) before falling back
+      // to direct on-chain tx. No need to sponsor gas separately.
+      const spinner = ora(`Deploying smart account on ${chain}...`).start();
       kit = await AzethKit.create(config);
 
       // Step 5: Deploy smart account + register on ERC-8004
@@ -127,7 +132,6 @@ export const quickstartCommand = new Command('quickstart')
       spinner.stop();
 
       // Step 6: Print results
-      const serverUrl = config.serverUrl ?? DEFAULT_SERVER_URL;
       const tokenIdStr = result.tokenId.toString();
       const badgeUrl = `${serverUrl}/badge/${tokenIdStr}`;
       const profileUrl = `https://azeth.ai/agent/${result.account}`;
@@ -142,38 +146,10 @@ export const quickstartCommand = new Command('quickstart')
       printField('Profile', profileUrl);
       printField('Badge', badgeUrl);
       console.log();
-      printSuccess('Gas sponsored by Azeth testnet — no ETH required.');
+      printSuccess('Account deployed — zero gas required from you.');
       console.log();
 
-      // Step 6b: Fund the smart account with testnet USDC via faucet (testnet only)
-      if (isTestnet) {
-        try {
-          const faucetSpinner = ora('Funding account with testnet USDC...').start();
-          const faucetRes = await fetch(`${serverUrl}/api/v1/faucet`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ address: result.account }),
-            signal: AbortSignal.timeout(60_000),
-          });
-          if (faucetRes.ok) {
-            const faucetBody = await faucetRes.json() as { data?: { amount?: string; txHash?: string } };
-            faucetSpinner.stop();
-            printSuccess(`Funded with ${faucetBody.data?.amount ?? '1.00 USDC'} for demo calls.`);
-            console.log();
-          } else {
-            faucetSpinner.stop();
-            // Non-fatal: show manual funding instructions
-            console.log(chalk.gray('  Faucet unavailable — send testnet USDC to your smart account to try paid services.'));
-            console.log();
-          }
-        } catch {
-          // Non-fatal — faucet unreachable
-          console.log(chalk.gray('  Could not reach faucet — send testnet USDC to your smart account to try paid services.'));
-          console.log();
-        }
-      }
-
-      // Step 6c: Demo the live ecosystem — call the free catalog
+      // Step 6b: Demo the live ecosystem — call the free catalog
       const catalogUrl = `${serverUrl}/api/v1/pricing`;
       try {
         const catalogSpinner = ora('Discovering live services...').start();
@@ -190,9 +166,6 @@ export const quickstartCommand = new Command('quickstart')
               console.log(`  ${chalk.cyan(item.name ?? '?')}  ${chalk.gray(item.pricing ?? '')}  ${chalk.white(item.description ?? '')}`);
             }
             console.log();
-            console.log(chalk.gray('  Try a paid call now' + (isTestnet ? ' (your account is funded)' : '') + ':'));
-            console.log(chalk.cyan(`    azeth call ${serverUrl}/api/v1/pricing/ethereum`));
-            console.log();
           }
         } else {
           catalogSpinner.stop();
@@ -201,6 +174,26 @@ export const quickstartCommand = new Command('quickstart')
         // Non-fatal — catalog fetch failed, just skip the demo
       }
 
+      // Step 6d: Make a live paid API call to demonstrate x402 (testnet only)
+      if (isTestnet) {
+        try {
+          const demoSpinner = ora('Making your first paid API call...').start();
+          const demoRes = await kit.fetch402(`${serverUrl}/api/v1/pricing/ethereum`);
+          demoSpinner.stop();
+          if (demoRes.response.ok) {
+            const body = await demoRes.response.json() as { data?: { symbol?: string; price?: string } };
+            const price = body?.data?.price;
+            const costStr = demoRes.amount !== undefined
+              ? `$${(Number(demoRes.amount) / 1_000_000).toFixed(2)}`
+              : '$0.01';
+            printSuccess(`First paid call complete! ETH = ${price ?? 'N/A'} (cost: ${costStr})`);
+            console.log();
+          }
+        } catch {
+          // Non-fatal — the demo call is a nice-to-have
+        }
+      }
+
       console.log(chalk.gray('  Next steps:'));
       console.log(chalk.gray('    azeth status                — Check your account'));
       console.log(chalk.gray('    azeth find "price feed"     — Discover services'));
@@ -209,11 +202,8 @@ export const quickstartCommand = new Command('quickstart')
 
       // Step 7: Print key persistence instructions (only for generated keys)
       if (generated) {
-        console.log(chalk.bold('  To continue using this account:'));
-        console.log(chalk.cyan(`    export AZETH_PRIVATE_KEY=${privateKey}`));
-        console.log();
-        console.log(chalk.gray('  Or add to .env:'));
-        console.log(chalk.gray(`    echo 'AZETH_PRIVATE_KEY=${privateKey}' >> .env`));
+        console.log(chalk.gray('  Key saved to ~/.azeth/key'));
+        console.log(chalk.gray('  To use in other terminals: export AZETH_PRIVATE_KEY=$(cat ~/.azeth/key)'));
         console.log();
       }
     } catch (err) {

src/index.ts

@@ -16,7 +16,7 @@ const program = new Command()
   .description('Azeth.ai CLI — Trust Infrastructure for the Machine Economy')
   .version('0.1.0')
   .option('--chain <chain>', 'Chain to use (base|baseSepolia|ethereumSepolia|ethereum)', 'baseSepolia')
-  .option('--rpc-url <url>', 'RPC URL (or set BASE_RPC_URL)')
+  .option('--rpc-url <url>', 'RPC URL (or set AZETH_RPC_URL_BASE_SEPOLIA, etc.)')
   .option('--server-url <url>', 'Azeth server URL (or set AZETH_SERVER_URL)');
 
 // Daily porcelain commands

src/utils/config.ts

@@ -1,8 +1,9 @@
 import { AzethKit, type AzethKitConfig } from '@azeth/sdk';
-import { isValidChainName, isValidPrivateKey } from '@azeth/common';
+import { isValidChainName, isValidPrivateKey, RPC_ENV_KEYS } from '@azeth/common';
 import type { SupportedChainName } from '@azeth/common';
 import type { Command } from 'commander';
 import dotenv from 'dotenv';
+import { loadKey } from './key-persistence.js';
 
 dotenv.config();
 
@@ -25,7 +26,7 @@ export function resolveOptions(cmd: Command): CliOptions {
     throw new Error(`Invalid chain "${chainRaw}". Must be one of: base, baseSepolia, ethereumSepolia, ethereum`);
   }
 
-  const rpcUrl = opts.rpcUrl ?? process.env['BASE_RPC_URL'];
+  const rpcUrl = opts.rpcUrl ?? process.env[RPC_ENV_KEYS[chainRaw]];
   const serverUrl = opts.serverUrl ?? process.env['AZETH_SERVER_URL'];
 
   // Validate server URL if provided
@@ -48,10 +49,16 @@ export function resolveOptions(cmd: Command): CliOptions {
  *  Private key is read exclusively from the AZETH_PRIVATE_KEY environment variable.
  *  NEVER pass private keys via command-line arguments (visible in shell history and process listings). */
 export async function createKit(options: CliOptions): Promise<AzethKit> {
-  const privateKey = process.env['AZETH_PRIVATE_KEY'];
+  let privateKey = process.env['AZETH_PRIVATE_KEY'];
+  if (!privateKey) {
+    const fileKey = loadKey();
+    if (fileKey) {
+      privateKey = fileKey;
+    }
+  }
   if (!privateKey) {
     throw new Error(
-      'Private key required. Set the AZETH_PRIVATE_KEY environment variable.\n' +
+      "Private key required. Set AZETH_PRIVATE_KEY or run 'azeth quickstart' to auto-generate one.\n" +
       'Example: export AZETH_PRIVATE_KEY=0x...\n' +
       'WARNING: Never pass private keys via command-line flags — they are visible in shell history.',
     );

src/utils/key-persistence.ts

@@ -0,0 +1,72 @@
+/**
+ * Private key persistence for the Azeth CLI.
+ *
+ * Saves and loads private keys from ~/.azeth/key so that quickstart-generated
+ * keys persist across CLI invocations without manual `export AZETH_PRIVATE_KEY=...`.
+ *
+ * File permissions: ~/.azeth/ = 0o700, ~/.azeth/key = 0o600
+ * The private key is NEVER logged — only the derived EOA address.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const KEY_FILE_RE = /^0x[0-9a-fA-F]{64}$/;
+
+/**
+ * Save a private key to ~/.azeth/key with secure file permissions.
+ * Creates ~/.azeth/ directory (0o700) if it doesn't exist.
+ * Returns true if saved successfully, false otherwise.
+ */
+export function saveKey(privateKey: string): boolean {
+  const home = homedir();
+  if (!home) return false;
+
+  const azethDir = join(home, '.azeth');
+  const keyFile = join(azethDir, 'key');
+
+  // Ensure ~/.azeth/ directory exists
+  if (existsSync(azethDir)) {
+    try {
+      if (!statSync(azethDir).isDirectory()) return false;
+    } catch {
+      return false;
+    }
+  } else {
+    try {
+      mkdirSync(azethDir, { recursive: true, mode: 0o700 });
+    } catch {
+      return false;
+    }
+  }
+
+  try {
+    writeFileSync(keyFile, privateKey, { mode: 0o600 });
+    chmodSync(keyFile, 0o600);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Load a private key from ~/.azeth/key.
+ * Returns the key string if found and valid, null otherwise.
+ */
+export function loadKey(): string | null {
+  const home = homedir();
+  if (!home) return null;
+
+  const keyFile = join(home, '.azeth', 'key');
+
+  if (!existsSync(keyFile)) return null;
+
+  try {
+    const key = readFileSync(keyFile, 'utf-8').trim();
+    if (KEY_FILE_RE.test(key)) return key;
+    return null;
+  } catch {
+    return null;
+  }
+}

test/commands/discover.test.ts

@@ -44,7 +44,8 @@ describe('discover command', () => {
       .addCommand(cmd);
   }
 
-  it('displays results in a table when services are found', async () => {
+  // First dynamic import after vi.resetModules() cold-loads @azeth/common (large ABIs)
+  it('displays results in a table when services are found', { timeout: 15000 }, async () => {
     const responseData = {
       data: [
         { tokenId: '1', owner: '0x1111111111111111111111111111111111111111', entityType: 'service', name: 'PriceFeed', capabilities: ['price-feed'], active: true },

test/utils/config.test.ts

@@ -15,6 +15,12 @@ vi.mock('@azeth/sdk', () => ({
 // Prevent dotenv from loading .env files during tests
 vi.mock('dotenv', () => ({ default: { config: vi.fn() } }));
 
+// Mock key-persistence so tests don't read the real ~/.azeth/key
+vi.mock('../../src/utils/key-persistence.js', () => ({
+  loadKey: vi.fn().mockReturnValue(null),
+  saveKey: vi.fn().mockReturnValue(true),
+}));
+
 /** Build a Commander tree that mirrors the real CLI's global options
  *  so that optsWithGlobals() works correctly in resolveOptions().
  *
@@ -48,7 +54,7 @@ describe('resolveOptions', () => {
 
   beforeEach(() => {
     // Snapshot env vars we might mutate
-    for (const key of ['AZETH_CHAIN', 'AZETH_PRIVATE_KEY', 'BASE_RPC_URL', 'AZETH_SERVER_URL']) {
+    for (const key of ['AZETH_CHAIN', 'AZETH_PRIVATE_KEY', 'AZETH_RPC_URL_BASE_SEPOLIA', 'AZETH_SERVER_URL']) {
       savedEnv[key] = process.env[key];
       delete process.env[key];
     }
@@ -121,8 +127,8 @@ describe('resolveOptions', () => {
     expect((opts as Record<string, unknown>)['privateKey']).toBeUndefined();
   });
 
-  it('reads rpc URL from env var', () => {
-    process.env['BASE_RPC_URL'] = 'https://custom-rpc.example.com';
+  it('reads rpc URL from per-chain env var', () => {
+    process.env['AZETH_RPC_URL_BASE_SEPOLIA'] = 'https://custom-rpc.example.com';
     const sub = buildProgram();
     const opts = resolveOptions(sub);
 
@@ -179,7 +185,7 @@ describe('createKit', () => {
     };
 
     await expect(createKit(options)).rejects.toThrow(
-      'Private key required. Set the AZETH_PRIVATE_KEY environment variable.',
+      'Private key required.',
     );
   });