crumb-alpha-cli 0.1.0

package/src/commands/withdraw.ts

@@ -0,0 +1,62 @@
+import { GatewayClient } from 'crumb-alpha-core'
+import type { SupportedChainName } from 'crumb-alpha-core'
+import { readConfig } from '../utils/config.js'
+import { loadPrivateKey, getPassword } from '../utils/keystore.js'
+import { heading, success, error, info, keyValue } from '../utils/output.js'
+import ora from 'ora'
+
+export async function withdrawCommand(
+  amount: string,
+  options: { chain?: string },
+): Promise<void> {
+  heading('Withdraw')
+
+  const config = readConfig()
+  if (!config.activeWallet) {
+    error('No wallet configured. Run `crumb init` first.')
+    return
+  }
+
+  let password: string
+  try {
+    password = getPassword()
+  } catch {
+    error('No password provided. Set CRUMB_KEYSTORE_PASSWORD env var.')
+    return
+  }
+
+  let privateKey: string
+  try {
+    privateKey = loadPrivateKey(password)
+  } catch (err: any) {
+    error(`Failed to decrypt keystore: ${err.message}`)
+    return
+  }
+
+  const chain = (config.chain ?? 'arcTestnet') as SupportedChainName
+  const gateway = new GatewayClient({
+    chain,
+    privateKey: privateKey as `0x${string}`,
+  })
+
+  const destChain = options.chain as SupportedChainName | undefined
+  info(`Withdrawing ${amount} USDC from Gateway${destChain ? ` to ${destChain}` : ''}...`)
+  const spinner = ora('  Processing withdrawal...').start()
+
+  try {
+    const result = await gateway.withdraw(amount, {
+      chain: destChain,
+    })
+    spinner.stop()
+
+    console.log()
+    success('Withdrawn')
+    keyValue('Amount:', `${result.formattedAmount} USDC`)
+    keyValue('Tx:', result.mintTxHash)
+    keyValue('From:', result.sourceChain)
+    keyValue('To:', result.destinationChain)
+  } catch (err: any) {
+    spinner.stop()
+    error(`Withdrawal failed: ${err.message}`)
+  }
+}

package/src/index.ts

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander'
+import { initCommand } from './commands/init.js'
+import { walletCreateCommand, walletShowCommand, walletFundCommand } from './commands/wallet.js'
+import { balanceCommand } from './commands/balance.js'
+import { depositCommand } from './commands/deposit.js'
+import { withdrawCommand } from './commands/withdraw.js'
+import { payCommand } from './commands/pay.js'
+import { historyCommand } from './commands/history.js'
+import { serveCommand } from './commands/serve.js'
+
+const program = new Command()
+
+program
+  .name('crumb')
+  .description('CLI for Crumb agentic payments via Circle Gateway')
+  .version('0.1.0')
+
+program
+  .command('init')
+  .description('Initialize Crumb — create config and wallet')
+  .action(initCommand)
+
+const wallet = program
+  .command('wallet')
+  .description('Wallet management')
+
+wallet
+  .command('create')
+  .description('Create a new wallet')
+  .action(walletCreateCommand)
+
+wallet
+  .command('show')
+  .description('Show active wallet info')
+  .action(walletShowCommand)
+
+wallet
+  .command('fund')
+  .description('Instructions to fund your wallet')
+  .action(walletFundCommand)
+
+program
+  .command('balance')
+  .description('Check USDC balance (wallet + gateway)')
+  .action(balanceCommand)
+
+program
+  .command('deposit')
+  .description('Deposit USDC into Gateway for gasless payments')
+  .argument('<amount>', 'Amount in USDC (e.g. 10.0)')
+  .action(depositCommand)
+
+program
+  .command('withdraw')
+  .description('Withdraw USDC from Gateway')
+  .argument('<amount>', 'Amount in USDC (e.g. 10.0)')
+  .option('--chain <chain>', 'Destination chain (for cross-chain withdrawal)')
+  .action(withdrawCommand)
+
+program
+  .command('pay')
+  .description('Pay for an x402-protected resource')
+  .argument('<url>', 'URL of the x402-protected resource')
+  .option('--max-payment <amount>', 'Maximum USDC willing to pay')
+  .action(payCommand)
+
+program
+  .command('history')
+  .description('View transaction history')
+  .option('--limit <n>', 'Number of transactions to show', '20')
+  .action((options) => historyCommand({ limit: parseInt(options.limit, 10) }))
+
+program
+  .command('serve')
+  .description('Run a local test provider')
+  .argument('<file>', 'Path to handler file')
+  .option('--port <port>', 'Port to listen on', '3000')
+  .option('--price <price>', 'USDC per call (e.g. $0.01)', '$0.01')
+  .action(serveCommand)
+
+program.parse()

package/src/utils/config.ts

@@ -0,0 +1,41 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const CRUMB_DIR = join(homedir(), '.crumb')
+const CONFIG_PATH = join(CRUMB_DIR, 'config.json')
+
+export interface CrumbConfig {
+  activeWallet?: string
+  chain: string // e.g. 'arcTestnet'
+}
+
+export function ensureCrumbDir(): void {
+  if (!existsSync(CRUMB_DIR)) {
+    mkdirSync(CRUMB_DIR, { recursive: true })
+  }
+}
+
+export function getCrumbDir(): string {
+  return CRUMB_DIR
+}
+
+export function getConfigPath(): string {
+  return CONFIG_PATH
+}
+
+export function readConfig(): CrumbConfig {
+  if (!existsSync(CONFIG_PATH)) {
+    return { chain: 'arcTestnet' }
+  }
+  return JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'))
+}
+
+export function writeConfig(config: CrumbConfig): void {
+  ensureCrumbDir()
+  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2))
+}
+
+export function configExists(): boolean {
+  return existsSync(CONFIG_PATH)
+}

package/src/utils/keystore.ts

@@ -0,0 +1,65 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { randomBytes, createCipheriv, createDecipheriv, scryptSync } from 'node:crypto'
+import { getCrumbDir, ensureCrumbDir } from './config.js'
+
+const KEYSTORE_FILE = 'keystore.enc'
+
+function getKeystorePath(): string {
+  return join(getCrumbDir(), KEYSTORE_FILE)
+}
+
+export function keystoreExists(): boolean {
+  return existsSync(getKeystorePath())
+}
+
+export function encryptAndSave(privateKey: string, password: string): void {
+  ensureCrumbDir()
+
+  const salt = randomBytes(32)
+  const key = scryptSync(password, salt, 32)
+  const iv = randomBytes(16)
+  const cipher = createCipheriv('aes-256-gcm', key, iv)
+
+  let encrypted = cipher.update(privateKey, 'utf-8', 'hex')
+  encrypted += cipher.final('hex')
+  const authTag = cipher.getAuthTag()
+
+  const payload = {
+    salt: salt.toString('hex'),
+    iv: iv.toString('hex'),
+    authTag: authTag.toString('hex'),
+    encrypted,
+  }
+
+  writeFileSync(getKeystorePath(), JSON.stringify(payload, null, 2))
+}
+
+export function loadPrivateKey(password: string): string {
+  const path = getKeystorePath()
+  if (!existsSync(path)) {
+    throw new Error('No keystore found. Run `crumb init` first.')
+  }
+
+  const payload = JSON.parse(readFileSync(path, 'utf-8'))
+  const salt = Buffer.from(payload.salt, 'hex')
+  const iv = Buffer.from(payload.iv, 'hex')
+  const authTag = Buffer.from(payload.authTag, 'hex')
+  const key = scryptSync(password, salt, 32)
+
+  const decipher = createDecipheriv('aes-256-gcm', key, iv)
+  decipher.setAuthTag(authTag)
+
+  let decrypted = decipher.update(payload.encrypted, 'hex', 'utf-8')
+  decrypted += decipher.final('utf-8')
+
+  return decrypted
+}
+
+export function getPassword(): string {
+  const envPassword = process.env.CRUMB_KEYSTORE_PASSWORD
+  if (envPassword) return envPassword
+  throw new Error(
+    'No password provided. Set CRUMB_KEYSTORE_PASSWORD env var or pass --password flag.',
+  )
+}

package/src/utils/output.ts

@@ -0,0 +1,40 @@
+import chalk from 'chalk'
+
+export function heading(text: string): void {
+  console.log()
+  console.log(chalk.bold.cyan(`  ◆ ${text}`))
+  console.log()
+}
+
+export function success(text: string): void {
+  console.log(chalk.green(`  ✔ ${text}`))
+}
+
+export function error(text: string): void {
+  console.log(chalk.red(`  ✖ ${text}`))
+}
+
+export function info(text: string): void {
+  console.log(chalk.gray(`  ${text}`))
+}
+
+export function keyValue(key: string, value: string): void {
+  console.log(`  ${chalk.dim(key.padEnd(12))} ${value}`)
+}
+
+export function box(lines: string[]): void {
+  const maxLen = Math.max(...lines.map((l) => l.length))
+  const border = '─'.repeat(maxLen + 4)
+  console.log()
+  console.log(`  ┌${border}┐`)
+  for (const line of lines) {
+    console.log(`  │  ${line.padEnd(maxLen + 2)}│`)
+  }
+  console.log(`  └${border}┘`)
+  console.log()
+}
+
+export function truncateAddress(address: string): string {
+  if (address.length <= 12) return address
+  return `${address.slice(0, 6)}...${address.slice(-4)}`
+}

package/test/config.test.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, rmSync, existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+// We need to mock the paths to use a temp directory
+let tempDir: string
+
+beforeEach(() => {
+  tempDir = mkdtempSync(join(tmpdir(), 'crumb-test-'))
+})
+
+afterEach(() => {
+  rmSync(tempDir, { recursive: true, force: true })
+})
+
+// Mock the config module paths
+vi.mock('../src/utils/config.js', async () => {
+  const fs = await import('node:fs')
+  const path = await import('node:path')
+
+  // We use a getter for tempDir so each test gets the right dir
+  const getDir = () => tempDir
+  const getConfigPath = () => path.join(getDir(), 'config.json')
+
+  return {
+    ensureCrumbDir: () => {
+      const dir = getDir()
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true })
+      }
+    },
+    getCrumbDir: getDir,
+    getConfigPath,
+    readConfig: () => {
+      const configPath = getConfigPath()
+      if (!fs.existsSync(configPath)) {
+        return { chain: 'arcTestnet' }
+      }
+      return JSON.parse(fs.readFileSync(configPath, 'utf-8'))
+    },
+    writeConfig: (config: any) => {
+      const dir = getDir()
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true })
+      }
+      fs.writeFileSync(getConfigPath(), JSON.stringify(config, null, 2))
+    },
+    configExists: () => {
+      return fs.existsSync(getConfigPath())
+    },
+  }
+})
+
+const { readConfig, writeConfig, configExists, getCrumbDir, ensureCrumbDir } = await import(
+  '../src/utils/config.js'
+)
+
+describe('config', () => {
+  describe('readConfig', () => {
+    it('returns default config when no file exists', () => {
+      const config = readConfig()
+      expect(config).toEqual({ chain: 'arcTestnet' })
+    })
+
+    it('reads existing config', () => {
+      writeConfig({ chain: 'arcTestnet', activeWallet: '0xabc' })
+      const config = readConfig()
+      expect(config.chain).toBe('arcTestnet')
+      expect(config.activeWallet).toBe('0xabc')
+    })
+  })
+
+  describe('writeConfig', () => {
+    it('writes config to disk', () => {
+      writeConfig({ chain: 'arcTestnet', activeWallet: '0x123' })
+      const config = readConfig()
+      expect(config.chain).toBe('arcTestnet')
+      expect(config.activeWallet).toBe('0x123')
+    })
+
+    it('overwrites existing config', () => {
+      writeConfig({ chain: 'arcTestnet' })
+      writeConfig({ chain: 'arcTestnet', activeWallet: '0xnew' })
+      const config = readConfig()
+      expect(config.chain).toBe('arcTestnet')
+    })
+  })
+
+  describe('configExists', () => {
+    it('returns false when no config file', () => {
+      expect(configExists()).toBe(false)
+    })
+
+    it('returns true after writing config', () => {
+      writeConfig({ chain: 'arcTestnet' })
+      expect(configExists()).toBe(true)
+    })
+  })
+
+  describe('ensureCrumbDir', () => {
+    it('creates directory if not exists', () => {
+      const dir = getCrumbDir()
+      // tempDir already exists, but test the function doesn't throw
+      ensureCrumbDir()
+      expect(existsSync(dir)).toBe(true)
+    })
+  })
+})

package/test/keystore.test.ts

@@ -0,0 +1,118 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, rmSync, existsSync, readFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+let tempDir: string
+
+beforeEach(() => {
+  tempDir = mkdtempSync(join(tmpdir(), 'crumb-keystore-test-'))
+})
+
+afterEach(() => {
+  rmSync(tempDir, { recursive: true, force: true })
+})
+
+vi.mock('../src/utils/config.js', () => {
+  const fs = require('node:fs') // eslint-disable-line
+  return {
+    getCrumbDir: () => tempDir,
+    ensureCrumbDir: () => {
+      if (!fs.existsSync(tempDir)) {
+        fs.mkdirSync(tempDir, { recursive: true })
+      }
+    },
+  }
+})
+
+const { encryptAndSave, loadPrivateKey, keystoreExists } = await import(
+  '../src/utils/keystore.js'
+)
+
+describe('keystore', () => {
+  const testPrivateKey = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80'
+  const testPassword = 'test-password-123'
+
+  describe('encryptAndSave', () => {
+    it('creates an encrypted keystore file', () => {
+      encryptAndSave(testPrivateKey, testPassword)
+      expect(existsSync(join(tempDir, 'keystore.enc'))).toBe(true)
+    })
+
+    it('stores encrypted data as JSON', () => {
+      encryptAndSave(testPrivateKey, testPassword)
+      const raw = readFileSync(join(tempDir, 'keystore.enc'), 'utf-8')
+      const data = JSON.parse(raw)
+      expect(data).toHaveProperty('salt')
+      expect(data).toHaveProperty('iv')
+      expect(data).toHaveProperty('authTag')
+      expect(data).toHaveProperty('encrypted')
+    })
+
+    it('does not store the private key in plaintext', () => {
+      encryptAndSave(testPrivateKey, testPassword)
+      const raw = readFileSync(join(tempDir, 'keystore.enc'), 'utf-8')
+      expect(raw).not.toContain(testPrivateKey)
+    })
+  })
+
+  describe('loadPrivateKey', () => {
+    it('decrypts and returns the original private key', () => {
+      encryptAndSave(testPrivateKey, testPassword)
+      const result = loadPrivateKey(testPassword)
+      expect(result).toBe(testPrivateKey)
+    })
+
+    it('throws with wrong password', () => {
+      encryptAndSave(testPrivateKey, testPassword)
+      expect(() => loadPrivateKey('wrong-password')).toThrow()
+    })
+
+    it('throws when no keystore exists', () => {
+      expect(() => loadPrivateKey(testPassword)).toThrow('No keystore found')
+    })
+  })
+
+  describe('keystoreExists', () => {
+    it('returns false when no keystore', () => {
+      expect(keystoreExists()).toBe(false)
+    })
+
+    it('returns true after saving', () => {
+      encryptAndSave(testPrivateKey, testPassword)
+      expect(keystoreExists()).toBe(true)
+    })
+  })
+
+  describe('roundtrip', () => {
+    it('handles various private key formats', () => {
+      const keys = [
+        '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80',
+        '0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d',
+        '0x5de4111afa1a4b94908f83103eb1f1706367c2e68ca870fc3fb9a804cdab365a',
+      ]
+
+      for (const key of keys) {
+        const keystorePath = join(tempDir, 'keystore.enc')
+        if (existsSync(keystorePath)) {
+          rmSync(keystorePath)
+        }
+
+        encryptAndSave(key, testPassword)
+        expect(loadPrivateKey(testPassword)).toBe(key)
+      }
+    })
+
+    it('uses different salt/iv each time', () => {
+      encryptAndSave(testPrivateKey, testPassword)
+      const raw1 = JSON.parse(readFileSync(join(tempDir, 'keystore.enc'), 'utf-8'))
+
+      encryptAndSave(testPrivateKey, testPassword)
+      const raw2 = JSON.parse(readFileSync(join(tempDir, 'keystore.enc'), 'utf-8'))
+
+      expect(raw1.salt).not.toBe(raw2.salt)
+      expect(raw1.iv).not.toBe(raw2.iv)
+      expect(raw1.encrypted).not.toBe(raw2.encrypted)
+    })
+  })
+})

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}