nebula-treasury 0.1.0

package/src/commands/gateway.ts

@@ -0,0 +1,101 @@
+/**
+ * `nebula gateway <sub>` argv dispatcher.
+ *
+ * Subs:
+ *   run       — foreground daemon (blocks; Ctrl+C to stop). Uses operator-session.
+ *   start     — interactive: prompt Touch ID, write operator-session, fork daemon.
+ *   stop      — SIGTERM the running daemon via the lock file's PID.
+ *   restart   — stop + start.
+ *   status    — show PID, uptime, socket path, lock state.
+ *   logs      — tail the gateway log (--tail N, --follow).
+ *
+ * v0.19.x scope: run + start + stop + status. restart/logs/install/setup ship
+ * in v0.19.3 alongside launchd plist generator.
+ */
+
+export type GatewaySub = 'run' | 'start' | 'stop' | 'restart' | 'status' | 'logs'
+
+export interface ParsedGatewayArgs {
+  sub: GatewaySub
+  /** Optional --agent <id> override; defaults to config-derived. */
+  agentId?: string
+  /** --tail N for logs; default 100. */
+  tail?: number
+  /** --follow / -f for logs. */
+  follow?: boolean
+}
+
+export type ParseResult = ParsedGatewayArgs | { error: string }
+
+export function parseGatewayArgs(argv: string[]): ParseResult {
+  const sub = argv[0]
+  if (!sub) {
+    return { error: 'usage: nebula gateway <run | start | stop | restart | status | logs>' }
+  }
+  if (!['run', 'start', 'stop', 'restart', 'status', 'logs'].includes(sub)) {
+    return { error: `unknown gateway sub: ${sub}` }
+  }
+  let agentId: string | undefined
+  let tail: number | undefined
+  let follow = false
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--agent') {
+      const v = argv[++i]
+      if (!v) return { error: '--agent requires a value' }
+      agentId = v
+    } else if (a === '--tail') {
+      const v = argv[++i]
+      if (!v) return { error: '--tail requires a value' }
+      const n = Number.parseInt(v, 10)
+      if (!Number.isFinite(n) || n < 0) return { error: '--tail must be a positive integer' }
+      tail = n
+    } else if (a === '--follow' || a === '-f') {
+      follow = true
+    } else {
+      return { error: `unknown flag: ${a}` }
+    }
+  }
+  return { sub: sub as GatewaySub, agentId, tail, follow }
+}
+
+export async function runGateway(parsed: ParsedGatewayArgs): Promise<void> {
+  switch (parsed.sub) {
+    case 'run': {
+      const { runGatewayForeground } = await import('./gateway-run')
+      await runGatewayForeground({ agentId: parsed.agentId })
+      return
+    }
+    case 'start': {
+      const { runGatewayStart } = await import('./gateway-start')
+      await runGatewayStart({ agentId: parsed.agentId })
+      return
+    }
+    case 'stop': {
+      const { runGatewayStop } = await import('./gateway-stop')
+      await runGatewayStop({ agentId: parsed.agentId })
+      return
+    }
+    case 'restart': {
+      const { runGatewayStop } = await import('./gateway-stop')
+      const { runGatewayStart } = await import('./gateway-start')
+      await runGatewayStop({ agentId: parsed.agentId })
+      await runGatewayStart({ agentId: parsed.agentId })
+      return
+    }
+    case 'status': {
+      const { runGatewayStatus } = await import('./gateway-status')
+      await runGatewayStatus({ agentId: parsed.agentId })
+      return
+    }
+    case 'logs': {
+      const { runGatewayLogs } = await import('./gateway-logs')
+      await runGatewayLogs({
+        agentId: parsed.agentId,
+        tail: parsed.tail ?? 100,
+        follow: parsed.follow ?? false,
+      })
+      return
+    }
+  }
+}

package/src/commands/identity.ts

@@ -0,0 +1,178 @@
+/**
+ * `nebula identity` — ERC-8004 (Trustless Agents) on-chain agent identity.
+ *
+ *   nebula identity card                 build + print the agent card (offline)
+ *   nebula identity register [--name N]  register the agent on the Identity Registry
+ *   nebula identity show [<agentId>]     resolve an agent (by id, or this agent's EOA)
+ *
+ * The owner of the identity NFT is the operator wallet; the card's
+ * `agentAddress` is the agent EOA. Registry address resolves from
+ * NEBULA_IDENTITY_REGISTRY env → baked-in deployment.
+ */
+import { writeFile } from 'node:fs/promises'
+import { cancel, intro, note, outro, spinner } from '@clack/prompts'
+import {
+  NETWORK_RPC,
+  agentIdByAddress,
+  buildAgentCard,
+  cardToDataUri,
+  explorerTxUrl,
+  registerAgent,
+  resolveAgentById,
+  resolveRegistryAddress,
+} from 'nebula-ai-core'
+import { http, type Address, createPublicClient } from 'viem'
+import { findAndLoadConfig } from '../config/load'
+import { loadOrPickOperatorSigner } from './init/operator-picker'
+
+export interface IdentityArgs {
+  sub: 'card' | 'register' | 'show'
+  agentId?: string
+  name?: string
+  url?: string
+  out?: string
+}
+
+export function parseIdentityArgs(argv: string[]): IdentityArgs | { error: string } {
+  const sub = argv[0]
+  if (sub !== 'card' && sub !== 'register' && sub !== 'show') {
+    return { error: `unknown subcommand '${sub ?? '(none)'}' — try: card | register | show` }
+  }
+  const flag = (name: string): string | undefined => {
+    const i = argv.indexOf(name)
+    return i >= 0 ? argv[i + 1] : undefined
+  }
+  const positional = argv.slice(1).find(a => !a.startsWith('--'))
+  return {
+    sub,
+    agentId: sub === 'show' ? positional : undefined,
+    name: flag('--name'),
+    url: flag('--url'),
+    out: flag('--out'),
+  }
+}
+
+export async function runIdentity(args: IdentityArgs): Promise<void> {
+  const loaded = await findAndLoadConfig()
+  if (!loaded) {
+    console.error('No nebula.config.ts found. Run `nebula init` first.')
+    process.exit(1)
+  }
+  const { config } = loaded
+  const network = config.network
+  const agentAddress = config.identity.agent as Address | null
+
+  if (args.sub === 'card') {
+    if (!agentAddress) {
+      console.error('Config has no agent EOA. Run `nebula init` first.')
+      process.exit(1)
+    }
+    const card = buildAgentCard({
+      name: args.name ?? `nebula-${agentAddress.slice(2, 8)}`,
+      agentAddress,
+      network,
+      url: args.url,
+    })
+    const json = JSON.stringify(card, null, 2)
+    if (args.out) {
+      await writeFile(args.out, json, 'utf8')
+      console.log(`agent card written to ${args.out}`)
+    } else {
+      console.log(json)
+    }
+    return
+  }
+
+  const registry = resolveRegistryAddress(network)
+  if (!registry) {
+    console.error(
+      `No Identity Registry address for ${network}. Deploy it (contracts/script/DeployIdentityRegistry.s.sol) and set NEBULA_IDENTITY_REGISTRY.`,
+    )
+    process.exit(1)
+  }
+  const publicClient = createPublicClient({ transport: http(NETWORK_RPC[network]) })
+
+  if (args.sub === 'show') {
+    let id: bigint
+    if (args.agentId) {
+      id = BigInt(args.agentId)
+    } else {
+      if (!agentAddress) {
+        console.error(
+          'Pass an <agentId>, or run `nebula init` so this agent has an EOA to reverse-resolve.',
+        )
+        process.exit(1)
+      }
+      id = await agentIdByAddress({ publicClient, registry, agentAddress })
+      if (id === 0n) {
+        console.log(
+          `agent ${agentAddress} is not registered on ${network}. Run \`nebula identity register\`.`,
+        )
+        return
+      }
+    }
+    const resolved = await resolveAgentById({ publicClient, registry, agentId: id })
+    console.log(`agent id   ${resolved.agentId.toString()}`)
+    console.log(`owner      ${resolved.owner}`)
+    console.log(`agent EOA  ${resolved.agentAddress}`)
+    console.log(`registry   ${registry} (${network})`)
+    console.log(
+      `card       ${resolved.cardURI.slice(0, 80)}${resolved.cardURI.length > 80 ? '…' : ''}`,
+    )
+    return
+  }
+
+  // register
+  intro('nebula identity register')
+  if (!agentAddress) {
+    cancel('Config has no agent EOA. Run `nebula init` first.')
+    return
+  }
+  const existing = await agentIdByAddress({ publicClient, registry, agentAddress })
+  if (existing !== 0n) {
+    note(
+      `agent ${agentAddress} is already registered as id ${existing.toString()}.`,
+      'already registered',
+    )
+    outro('nothing to do')
+    return
+  }
+  const operator = await loadOrPickOperatorSigner({ network, hint: config.operator })
+  if (!operator) {
+    cancel('No operator wallet available; cannot register.')
+    return
+  }
+  const s = spinner()
+  s.start('Registering agent identity on the ERC-8004 registry')
+  try {
+    const walletClient = await operator.walletClient(network)
+    const card = buildAgentCard({
+      name: args.name ?? `nebula-${agentAddress.slice(2, 8)}`,
+      agentAddress,
+      network,
+      url: args.url,
+    })
+    const cardURI = args.url ?? cardToDataUri(card)
+    const { agentId, txHash } = await registerAgent({
+      walletClient,
+      publicClient,
+      registry,
+      cardURI,
+      agentAddress,
+    })
+    s.stop(`registered as agent id ${agentId.toString()}`)
+    outro(
+      [
+        `  agent id   ${agentId.toString()}`,
+        `  registry   ${registry} (${network})`,
+        `  tx         ${explorerTxUrl(network, txHash)}`,
+        '',
+        'Resolve with: nebula identity show',
+      ].join('\n'),
+    )
+  } catch (e) {
+    s.stop(`register failed: ${(e as Error).message.slice(0, 200)}`)
+  } finally {
+    await operator.close?.()
+  }
+}

package/src/commands/init/cost.ts

@@ -0,0 +1,40 @@
+import { formatEther } from 'viem'
+
+/** Mantle mainnet spot price used for USD estimates. Not authoritative, just a hint. */
+const MNT_USD = 0.5
+
+export type DeployTarget = 'local'
+
+export interface CostBreakdown {
+  agentFloat: bigint
+  totalOperator: bigint
+  deployTarget: DeployTarget
+}
+
+export function estimateCosts(opts?: {
+  ledgerSizeOg?: number
+  withSubname?: boolean
+  deployTarget?: DeployTarget
+  agentFloatWei?: bigint
+}): CostBreakdown {
+  // The only init cost is funding the agent EOA with a small gas float. There
+  // is no iNFT mint, no storage anchor, and no compute ledger.
+  const agentFloat = opts?.agentFloatWei ?? 100_000_000_000_000_000n // 0.1 MNT
+  return { agentFloat, totalOperator: agentFloat, deployTarget: opts?.deployTarget ?? 'local' }
+}
+
+export function formatUsd(valueWei: bigint): string {
+  const mnt = Number(formatEther(valueWei))
+  return `$${(mnt * MNT_USD).toFixed(2)}`
+}
+
+export function renderCostSummary(c: CostBreakdown): string {
+  const line = (label: string, wei: bigint): string =>
+    `    ${label.padEnd(32)}${formatEther(wei).padStart(8)} Mantle  (${formatUsd(wei)})`
+  return [
+    '  operator spend (Mantle mainnet):',
+    line('agent infra float (gas)', c.agentFloat),
+    `    ${'─'.repeat(32)}${'─'.repeat(18)}`,
+    line('total operator spend', c.totalOperator),
+  ].join('\n')
+}

package/src/commands/init/funding-gate.ts

@@ -0,0 +1,64 @@
+import { cancel, isCancel, select } from '@clack/prompts'
+import qrcode from 'qrcode-terminal'
+import { type Address, type PublicClient, formatEther } from 'viem'
+
+export interface FundingGateOpts {
+  publicClient: PublicClient
+  operatorAddress: Address
+  requiredOg: bigint
+  pollIntervalMs?: number
+  maxWaitMs?: number
+}
+
+export type FundingGateOutcome =
+  | { kind: 'funded'; balance: bigint }
+  | { kind: 'skip-ledger' }
+  | { kind: 'cancel' }
+
+/**
+ * Show operator address as a QR and poll balance until it meets required
+ * threshold. User can cancel or choose to proceed with minimum-only (skip
+ * full compute ledger) at any point.
+ *
+ * Console prints the QR once; the polling loop updates a single line
+ * using `process.stdout.write` so the display doesn't scroll.
+ */
+export async function fundingGate(opts: FundingGateOpts): Promise<FundingGateOutcome> {
+  const pollIntervalMs = opts.pollIntervalMs ?? 10_000
+  const maxWaitMs = opts.maxWaitMs ?? 30 * 60_000 // 30 minutes
+
+  console.log('')
+  console.log(`  Send at least ${formatEther(opts.requiredOg)} Mantle to:`)
+  console.log(`    ${opts.operatorAddress}`)
+  console.log('')
+  qrcode.generate(opts.operatorAddress, { small: true })
+  console.log('')
+
+  const start = Date.now()
+  while (Date.now() - start < maxWaitMs) {
+    const balance = await opts.publicClient.getBalance({ address: opts.operatorAddress })
+    if (balance >= opts.requiredOg) {
+      process.stdout.write('\r')
+      return { kind: 'funded', balance }
+    }
+    process.stdout.write(
+      `\r  polling... current balance ${formatEther(balance)} Mantle (need ${formatEther(opts.requiredOg)}) `,
+    )
+    await new Promise(resolve => setTimeout(resolve, pollIntervalMs))
+  }
+
+  process.stdout.write('\n\n')
+  const choice = await select({
+    message: 'Balance still insufficient. What now?',
+    options: [
+      { value: 'skip' as const, label: 'Skip compute ledger for now (mint + subname only)' },
+      { value: 'cancel' as const, label: 'Cancel init' },
+    ],
+    initialValue: 'cancel',
+  })
+  if (isCancel(choice)) {
+    cancel('Aborted.')
+    return { kind: 'cancel' }
+  }
+  return choice === 'skip' ? { kind: 'skip-ledger' } : { kind: 'cancel' }
+}

package/src/commands/init/model-picker.ts

@@ -0,0 +1,25 @@
+import type { NebulaNetwork } from 'nebula-ai-core'
+
+export interface ModelPick {
+  provider: string
+  model: string | null
+  inputPricePerTokenWei: bigint
+  outputPricePerTokenWei: bigint
+}
+
+/**
+ * Nebula uses a fixed OpenAI-compatible model configured via env
+ * (`NEBULA_LLM_MODEL` / `NEBULA_LLM_BASE_URL` / `OPENAI_API_KEY`), so there's
+ * no live provider catalog to pick from. Return the configured default so
+ * `init` / `model` proceed without prompting.
+ */
+export async function pickBrainModel(_opts: {
+  network: NebulaNetwork
+}): Promise<ModelPick | null> {
+  return {
+    provider: 'openai-compatible',
+    model: process.env.NEBULA_LLM_MODEL ?? 'gpt-4o-mini',
+    inputPricePerTokenWei: 0n,
+    outputPricePerTokenWei: 0n,
+  }
+}

package/src/commands/init/operator-picker.ts

@@ -0,0 +1,233 @@
+import { existsSync } from 'node:fs'
+import { cancel, isCancel, note, password, select, text } from '@clack/prompts'
+import {
+  KeychainOperatorSigner,
+  KeystoreFileOperatorSigner,
+  type NebulaNetwork,
+  type OperatorSigner,
+  type OperatorSourceHint,
+  type OperatorSourceKind,
+  RawPrivkeyOperatorSigner,
+  WalletConnectOperatorSigner,
+} from 'nebula-ai-core'
+
+interface PickerOptions {
+  network: NebulaNetwork
+}
+
+export interface OperatorPickResult {
+  signer: OperatorSigner
+  hint: OperatorSourceHint
+}
+
+/**
+ * Prompt the user for their operator wallet source and return both the
+ * connected `OperatorSigner` and the metadata needed to reconstruct it
+ * later (`OperatorSourceHint`). The hint is saved to `nebula.config.ts` by
+ * the wizard so subsequent commands (chat, topup, restore) can re-attach
+ * to the same source without re-prompting.
+ *
+ * Platform-aware: on macOS, all four sources are offered. On Linux/Windows
+ * the OS keychain option is hidden because libsecret/Credential-Manager
+ * support is post-MVP.
+ */
+export async function pickOperatorSigner(opts: PickerOptions): Promise<OperatorPickResult | null> {
+  const isMac = process.platform === 'darwin'
+  const choices: { value: OperatorSourceKind; label: string; hint?: string }[] = [
+    {
+      value: 'walletconnect',
+      label: 'WalletConnect',
+      hint: 'scan QR with any WC-compatible mobile wallet',
+    },
+    ...(isMac
+      ? ([
+          {
+            value: 'keychain',
+            label: 'macOS Keychain',
+            hint: 'stored in login keychain',
+          },
+        ] as const)
+      : []),
+    {
+      value: 'keystore-file',
+      label: 'Keystore file',
+      hint: 'encrypted JSON, geth format',
+    },
+    {
+      value: 'raw-privkey',
+      label: 'Raw private key',
+      hint: 'stdin prompt, for CI/scripting',
+    },
+  ]
+  const source = (await select({
+    message: 'Connect your operator wallet (owns the iNFT)',
+    options: choices,
+    initialValue: choices[0]!.value,
+  })) as OperatorSourceKind | symbol
+  if (isCancel(source)) {
+    cancel('Aborted.')
+    return null
+  }
+
+  switch (source) {
+    case 'walletconnect':
+      return {
+        signer: new WalletConnectOperatorSigner({ networks: [opts.network] }),
+        hint: { source: 'walletconnect' },
+      }
+    case 'keychain': {
+      const service = await text({
+        message: 'Keychain service name',
+        placeholder: 'nebula.operator',
+        validate: v => {
+          if (!v || v.length === 0) return 'Required.'
+          if (!/^[a-zA-Z0-9._-]{1,128}$/.test(v))
+            return 'Allowed characters: a-z, A-Z, 0-9, dot, underscore, hyphen (max 128).'
+          return undefined
+        },
+      })
+      if (isCancel(service)) {
+        cancel('Aborted.')
+        return null
+      }
+      const svc = service as string
+      return {
+        signer: new KeychainOperatorSigner(svc),
+        hint: { source: 'keychain', keychainService: svc },
+      }
+    }
+    case 'keystore-file': {
+      const path = await text({
+        message: 'Path to encrypted JSON keystore',
+        placeholder: '~/wallets/operator.json',
+        validate: v => {
+          if (!v) return 'Required.'
+          const expanded = v.replace(/^~/, process.env.HOME ?? '~')
+          if (!existsSync(expanded)) return `File not found: ${expanded}`
+          return undefined
+        },
+      })
+      if (isCancel(path)) {
+        cancel('Aborted.')
+        return null
+      }
+      const expanded = (path as string).replace(/^~/, process.env.HOME ?? '~')
+      const pass = await password({
+        message: 'Passphrase for the keystore',
+        validate: v => (v && v.length > 0 ? undefined : 'Required.'),
+      })
+      if (isCancel(pass)) {
+        cancel('Aborted.')
+        return null
+      }
+      return {
+        signer: new KeystoreFileOperatorSigner({ path: expanded, passphrase: pass as string }),
+        hint: { source: 'keystore-file', keystorePath: path as string },
+      }
+    }
+    case 'raw-privkey': {
+      if (process.env.NEBULA_OPERATOR_PRIVKEY) {
+        note('Using NEBULA_OPERATOR_PRIVKEY from env.', 'raw-privkey')
+        return {
+          signer: new RawPrivkeyOperatorSigner({
+            privkey: process.env.NEBULA_OPERATOR_PRIVKEY,
+            sourceLabel: 'env:NEBULA_OPERATOR_PRIVKEY',
+          }),
+          hint: { source: 'raw-privkey' },
+        }
+      }
+      const pk = await password({
+        message: 'Operator private key (hex, 0x prefix optional)',
+        validate: v => {
+          if (!v) return 'Required.'
+          const clean = v.trim().replace(/^0x/, '')
+          if (!/^[0-9a-fA-F]{64}$/.test(clean)) return 'Must be 32 bytes hex.'
+          return undefined
+        },
+      })
+      if (isCancel(pk)) {
+        cancel('Aborted.')
+        return null
+      }
+      return {
+        signer: new RawPrivkeyOperatorSigner({ privkey: pk as string, sourceLabel: 'stdin' }),
+        hint: { source: 'raw-privkey' },
+      }
+    }
+  }
+}
+
+/**
+ * Reload an `OperatorSigner` from a previously persisted hint in
+ * `nebula.config.ts`. Used by chat / topup / restore / resume so the user
+ * doesn't re-pick a source every session — they only re-supply per-session
+ * secrets (passphrases / QR scans / env vars).
+ *
+ * Returns null when the hint is missing or unusable; the caller falls back
+ * to `pickOperatorSigner` for an interactive choice.
+ */
+export async function loadOperatorFromHint(
+  hint: OperatorSourceHint,
+  network: NebulaNetwork,
+): Promise<OperatorSigner | null> {
+  switch (hint.source) {
+    case 'walletconnect':
+      return new WalletConnectOperatorSigner({ networks: [network] })
+    case 'keychain': {
+      if (!hint.keychainService) return null
+      return new KeychainOperatorSigner(hint.keychainService)
+    }
+    case 'keystore-file': {
+      if (!hint.keystorePath) return null
+      const expanded = hint.keystorePath.replace(/^~/, process.env.HOME ?? '~')
+      if (!existsSync(expanded)) {
+        note(`Operator keystore not found at ${expanded}; pick a new source.`, 'keystore missing')
+        return null
+      }
+      const pass = await password({
+        message: `Passphrase for operator keystore ${expanded}`,
+        validate: v => (v && v.length > 0 ? undefined : 'Required.'),
+      })
+      if (isCancel(pass)) return null
+      return new KeystoreFileOperatorSigner({
+        path: expanded,
+        passphrase: pass as string,
+      })
+    }
+    case 'raw-privkey': {
+      if (process.env.NEBULA_OPERATOR_PRIVKEY) {
+        return new RawPrivkeyOperatorSigner({
+          privkey: process.env.NEBULA_OPERATOR_PRIVKEY,
+          sourceLabel: 'env:NEBULA_OPERATOR_PRIVKEY',
+        })
+      }
+      const pk = await password({
+        message: 'Operator private key (hex, 0x prefix optional)',
+        validate: v => {
+          if (!v) return 'Required.'
+          const clean = v.trim().replace(/^0x/, '')
+          if (!/^[0-9a-fA-F]{64}$/.test(clean)) return 'Must be 32 bytes hex.'
+          return undefined
+        },
+      })
+      if (isCancel(pk)) return null
+      return new RawPrivkeyOperatorSigner({ privkey: pk as string, sourceLabel: 'stdin' })
+    }
+  }
+}
+
+/**
+ * High-level helper: load operator from config hint when available, fall
+ * back to interactive picker otherwise. Used by all post-init commands.
+ */
+export async function loadOrPickOperatorSigner(opts: {
+  network: NebulaNetwork
+  hint?: OperatorSourceHint | null
+}): Promise<OperatorSigner | null> {
+  if (opts.hint) {
+    const signer = await loadOperatorFromHint(opts.hint, opts.network)
+    if (signer) return signer
+  }
+  const picked = await pickOperatorSigner({ network: opts.network })
+  return picked?.signer ?? null
+}