0g-orbit 0.1.0

package/dist/storage.js

@@ -0,0 +1,121 @@
+import { Indexer, ZgFile } from '@0gfoundation/0g-ts-sdk';
+import { writeFileSync, unlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { StorageError } from './errors.js';
+import { withRetry, isTransientError } from './retry.js';
+const DEFAULT_REPLICAS = 1;
+const DEFAULT_MAX_GAS_PRICE = 25_000_000_000; // 25 gwei — generous ceiling for auto-escalation
+export class StorageClient {
+    indexer;
+    rpcUrl;
+    signer;
+    constructor(network, signer) {
+        this.indexer = new Indexer(network.indexerUrl);
+        this.rpcUrl = network.rpcUrl;
+        this.signer = signer;
+    }
+    /**
+     * Upload a file to 0G Storage by file path.
+     * Retries transient failures automatically. Gas escalates on each retry.
+     */
+    async store(filePath, options = {}) {
+        return withRetry(() => this._store(filePath, options), {
+            maxAttempts: 3,
+            isRetryable: (err) => {
+                if (!(err instanceof StorageError))
+                    return isTransientError(err);
+                const msg = err.message.toLowerCase();
+                return msg.includes('gas') ||
+                    msg.includes('timeout') ||
+                    msg.includes('etimedout') ||
+                    msg.includes('econnrefused') ||
+                    msg.includes('underpriced');
+            },
+        });
+    }
+    /**
+     * Upload raw data (string, Buffer, or Uint8Array) to 0G Storage.
+     * Writes to a temp file, uploads, then cleans up.
+     */
+    async storeData(data, options = {}) {
+        const tempPath = join(tmpdir(), `orbit-${randomBytes(8).toString('hex')}`);
+        try {
+            writeFileSync(tempPath, data);
+            return await this.store(tempPath, options);
+        }
+        finally {
+            try {
+                unlinkSync(tempPath);
+            }
+            catch { /* ignore cleanup errors */ }
+        }
+    }
+    async _store(filePath, options) {
+        const file = await ZgFile.fromFilePath(filePath);
+        try {
+            const [tree, treeErr] = await file.merkleTree();
+            if (treeErr || !tree) {
+                throw new StorageError(`Failed to compute merkle tree: ${treeErr?.message ?? 'unknown error'}`, 'Ensure the file exists, is readable, and is not empty.');
+            }
+            // Always enable gas auto-escalation via the SDK's built-in retry.
+            // MaxGasPrice sets the ceiling — the SDK starts from the network estimate
+            // and bumps 10% on each retry until it hits this cap.
+            const maxGas = options.maxGasPrice
+                ? Number(options.maxGasPrice)
+                : DEFAULT_MAX_GAS_PRICE;
+            // Cast signer to avoid ESM/CJS ethers type mismatch
+            const [result, uploadErr] = await this.indexer.upload(file, this.rpcUrl, this.signer, {
+                tags: options.tags ?? '0x',
+                expectedReplica: options.replicas ?? DEFAULT_REPLICAS,
+            }, { Retries: 5, Interval: 3, MaxGasPrice: maxGas });
+            if (uploadErr) {
+                const msg = uploadErr.message;
+                let suggestion = 'Check your OG balance and try again.';
+                if (msg.includes('gas') || msg.includes('underpriced')) {
+                    suggestion = `Gas auto-escalation hit the ceiling (${maxGas} wei). Try a higher maxGasPrice, e.g. { maxGasPrice: ${maxGas * 2}n }`;
+                }
+                else if (msg.includes('timeout') || msg.includes('ETIMEDOUT')) {
+                    suggestion = 'The RPC endpoint timed out. Try a different RPC URL with the rpcUrl option.';
+                }
+                else if (msg.includes('insufficient funds')) {
+                    suggestion = 'Your wallet needs more OG for gas. Get testnet OG from: https://faucet.0g.ai';
+                }
+                throw new StorageError(`Upload failed: ${msg}`, suggestion);
+            }
+            if ('txHash' in result) {
+                return {
+                    root: result.rootHash,
+                    txHash: result.txHash,
+                };
+            }
+            // Fragmented upload — return the first root hash as primary handle
+            return {
+                root: result.rootHashes[0],
+                txHash: result.txHashes[0],
+            };
+        }
+        finally {
+            await file.close();
+        }
+    }
+    /**
+     * Download a file from 0G Storage by root hash.
+     */
+    async retrieve(rootHash, outputPath, options = {}) {
+        return withRetry(() => this._retrieve(rootHash, outputPath, options), { maxAttempts: 3 });
+    }
+    async _retrieve(rootHash, outputPath, options) {
+        const err = await this.indexer.download(rootHash, outputPath, options.proof ?? false);
+        if (err) {
+            const msg = err.message;
+            let suggestion = 'Verify the root hash is correct and the file was uploaded successfully.';
+            if (msg.includes('not found') || msg.includes('404')) {
+                suggestion = 'This root hash was not found on the network. Double-check the hash or ensure the upload completed.';
+            }
+            throw new StorageError(`Download failed: ${msg}`, suggestion);
+        }
+    }
+}
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,81 @@
+import type { NetworkName } from './networks.js';
+export interface OrbitConfig {
+    /** Private key for signing transactions. Falls back to PRIVATE_KEY env var if omitted. */
+    privateKey?: string;
+    /** Network to connect to */
+    network: NetworkName;
+    /** Custom RPC URL (overrides network default) */
+    rpcUrl?: string;
+    /** Custom indexer URL (overrides network default) */
+    indexerUrl?: string;
+}
+export interface StoreResult {
+    /** Merkle root hash — use this to retrieve the file */
+    root: string;
+    /** On-chain transaction hash */
+    txHash: string;
+}
+export interface StoreOptions {
+    /** Custom tags for the upload (hex string) */
+    tags?: string;
+    /** Expected number of replicas */
+    replicas?: number;
+    /** Maximum gas price in wei */
+    maxGasPrice?: bigint;
+}
+export interface RetrieveOptions {
+    /** Whether to verify merkle proofs during download */
+    proof?: boolean;
+}
+export interface InferResult {
+    /** The model's response text */
+    content: string;
+    /** The model used */
+    model: string;
+    /** Token usage */
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    /** Whether the response passed TEE verification (null if not verifiable) */
+    verified: boolean | null;
+}
+export interface InferOptions {
+    /** Messages for chat completion */
+    messages: Array<{
+        role: 'system' | 'user' | 'assistant';
+        content: string;
+    }>;
+    /** Temperature for sampling (0-2) */
+    temperature?: number;
+    /** Maximum tokens to generate */
+    maxTokens?: number;
+    /** Specific provider address (auto-selected if omitted) */
+    provider?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+export interface ServiceInfo {
+    /** Provider wallet address */
+    provider: string;
+    /** Model name */
+    model: string;
+    /** Service endpoint URL */
+    url: string;
+    /** Input token price (neuron) */
+    inputPrice: bigint;
+    /** Output token price (neuron) */
+    outputPrice: bigint;
+    /** Whether TEE verification is available */
+    verifiable: boolean;
+}
+export interface AccountStatus {
+    /** Main ledger balance in OG */
+    balance: string;
+    /** Network name */
+    network: NetworkName;
+    /** Wallet address */
+    address: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAEhD,MAAM,WAAW,WAAW;IACxB,0FAA0F;IAC1F,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,4BAA4B;IAC5B,OAAO,EAAE,WAAW,CAAA;IACpB,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,WAAW;IACxB,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAA;IACZ,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,YAAY;IACzB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,+BAA+B;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,eAAe;IAC5B,sDAAsD;IACtD,KAAK,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,WAAW;IACxB,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAA;IACf,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,kBAAkB;IAClB,KAAK,CAAC,EAAE;QACJ,YAAY,EAAE,MAAM,CAAA;QACpB,gBAAgB,EAAE,MAAM,CAAA;QACxB,WAAW,EAAE,MAAM,CAAA;KACtB,CAAA;IACD,4EAA4E;IAC5E,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAA;CAC3B;AAED,MAAM,WAAW,YAAY;IACzB,mCAAmC;IACnC,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC3E,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,WAAW;IACxB,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAA;IAChB,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,2BAA2B;IAC3B,GAAG,EAAE,MAAM,CAAA;IACX,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAA;IAClB,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAA;IACnB,4CAA4C;IAC5C,UAAU,EAAE,OAAO,CAAA;CACtB;AAED,MAAM,WAAW,aAAa;IAC1B,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAA;IACf,mBAAmB;IACnB,OAAO,EAAE,WAAW,CAAA;IACpB,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAA;CAClB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/examples/ai-chatbot/index.ts

@@ -0,0 +1,74 @@
+/**
+ * 0G Orbit — AI Chatbot Example
+ *
+ * A simple interactive chatbot using 0G Compute Network.
+ * Demonstrates multi-turn conversations with TEE verification.
+ *
+ * Usage:
+ *   PRIVATE_KEY=0x... npx tsx index.ts
+ */
+
+import { Orbit } from '@0g-orbit/core'
+import { createInterface } from 'node:readline'
+
+const MODEL = 'meta-llama/Llama-3.3-70B'
+
+async function main() {
+    const orbit = await Orbit.connect({
+        network: 'testnet',
+        privateKey: process.env.PRIVATE_KEY!,
+    })
+
+    const status = await orbit.status()
+    console.log(`Connected: ${status.address} (${status.balance} OG)`)
+    console.log(`Model: ${MODEL}`)
+    console.log('Type "quit" to exit.\n')
+
+    const history: Array<{ role: 'system' | 'user' | 'assistant'; content: string }> = [
+        {
+            role: 'system',
+            content: 'You are a helpful AI assistant running on 0G decentralized compute. Be concise.',
+        },
+    ]
+
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    })
+
+    const ask = (prompt: string): Promise<string> =>
+        new Promise((resolve) => rl.question(prompt, resolve))
+
+    while (true) {
+        const input = await ask('You: ')
+        if (input.toLowerCase() === 'quit') break
+        if (!input.trim()) continue
+
+        history.push({ role: 'user', content: input })
+
+        try {
+            const result = await orbit.infer(MODEL, {
+                messages: history,
+                temperature: 0.7,
+                maxTokens: 1024,
+            })
+
+            history.push({ role: 'assistant', content: result.content })
+
+            console.log(`\nAssistant: ${result.content}`)
+
+            const meta: string[] = []
+            if (result.usage) meta.push(`${result.usage.totalTokens} tokens`)
+            if (result.verified === true) meta.push('TEE verified')
+            if (meta.length) console.log(`  (${meta.join(' | ')})`)
+            console.log()
+        } catch (err) {
+            console.error(`Error: ${err instanceof Error ? err.message : err}\n`)
+        }
+    }
+
+    rl.close()
+    console.log('Goodbye!')
+}
+
+main().catch(console.error)

package/examples/model-registry/index.ts

@@ -0,0 +1,137 @@
+/**
+ * 0G Orbit — Model Registry Example
+ *
+ * Store AI model weights on 0G Storage and maintain
+ * a registry of model versions with their root hashes.
+ *
+ * Usage:
+ *   PRIVATE_KEY=0x... npx tsx index.ts
+ */
+
+import { Orbit } from '@0g-orbit/core'
+import { writeFileSync, readFileSync, existsSync } from 'node:fs'
+
+const REGISTRY_FILE = './registry.json'
+
+interface ModelEntry {
+    name: string
+    version: string
+    rootHash: string
+    txHash: string
+    uploadedAt: string
+    sizeBytes?: number
+}
+
+interface Registry {
+    models: ModelEntry[]
+}
+
+function loadRegistry(): Registry {
+    if (existsSync(REGISTRY_FILE)) {
+        return JSON.parse(readFileSync(REGISTRY_FILE, 'utf-8'))
+    }
+    return { models: [] }
+}
+
+function saveRegistry(registry: Registry) {
+    writeFileSync(REGISTRY_FILE, JSON.stringify(registry, null, 2) + '\n')
+}
+
+async function registerModel(
+    orbit: Orbit,
+    name: string,
+    version: string,
+    filePath: string
+) {
+    console.log(`\nUploading ${name} v${version}...`)
+    const { root, txHash } = await orbit.store(filePath)
+
+    const registry = loadRegistry()
+    registry.models.push({
+        name,
+        version,
+        rootHash: root,
+        txHash,
+        uploadedAt: new Date().toISOString(),
+    })
+    saveRegistry(registry)
+
+    console.log(`Registered: ${name} v${version}`)
+    console.log(`  Root:  ${root}`)
+    console.log(`  Tx:    ${txHash}`)
+    return root
+}
+
+async function downloadModel(
+    orbit: Orbit,
+    name: string,
+    version: string,
+    outputPath: string
+) {
+    const registry = loadRegistry()
+    const entry = registry.models.find(
+        (m) => m.name === name && m.version === version
+    )
+
+    if (!entry) {
+        console.error(`Model ${name} v${version} not found in registry.`)
+        return
+    }
+
+    console.log(`\nDownloading ${name} v${version}...`)
+    await orbit.retrieve(entry.rootHash, outputPath)
+    console.log(`Downloaded to ${outputPath}`)
+}
+
+function listModels() {
+    const registry = loadRegistry()
+    if (registry.models.length === 0) {
+        console.log('No models registered.')
+        return
+    }
+
+    console.log('\nRegistered models:')
+    for (const m of registry.models) {
+        console.log(`  ${m.name} v${m.version}`)
+        console.log(`    root: ${m.rootHash}`)
+        console.log(`    date: ${m.uploadedAt}`)
+    }
+}
+
+async function main() {
+    const orbit = await Orbit.connect({
+        network: 'testnet',
+        privateKey: process.env.PRIVATE_KEY!,
+    })
+
+    const status = await orbit.status()
+    console.log(`Connected: ${status.address} (${status.balance} OG)`)
+
+    const command = process.argv[2] || 'list'
+
+    switch (command) {
+        case 'register': {
+            const [, , , name, version, filePath] = process.argv
+            if (!name || !version || !filePath) {
+                console.error('Usage: npx tsx index.ts register <name> <version> <file>')
+                process.exit(1)
+            }
+            await registerModel(orbit, name, version, filePath)
+            break
+        }
+        case 'download': {
+            const [, , , name, version, outputPath] = process.argv
+            if (!name || !version || !outputPath) {
+                console.error('Usage: npx tsx index.ts download <name> <version> <output>')
+                process.exit(1)
+            }
+            await downloadModel(orbit, name, version, outputPath)
+            break
+        }
+        case 'list':
+        default:
+            listModels()
+    }
+}
+
+main().catch(console.error)

package/examples/quick-start/index.ts

@@ -0,0 +1,65 @@
+/**
+ * 0G Orbit — Quick Start
+ *
+ * Demonstrates the three core operations:
+ * 1. Check account status
+ * 2. Store a file to 0G Storage
+ * 3. Run AI inference on 0G Compute
+ *
+ * Usage:
+ *   PRIVATE_KEY=0x... npx tsx index.ts
+ */
+
+import { Orbit } from '@0g-orbit/core'
+import { writeFileSync, unlinkSync } from 'node:fs'
+
+async function main() {
+    // Connect
+    const orbit = await Orbit.connect({
+        network: 'testnet',
+        privateKey: process.env.PRIVATE_KEY!,
+    })
+
+    // 1. Account status
+    const status = await orbit.status()
+    console.log(`Connected: ${status.address}`)
+    console.log(`Balance:   ${status.balance} OG on ${status.network}`)
+
+    // 2. Store a file
+    const testFile = '/tmp/orbit-test.txt'
+    writeFileSync(testFile, 'Hello from 0G Orbit!')
+
+    console.log('\nUploading file...')
+    const { root, txHash } = await orbit.store(testFile)
+    console.log(`Stored! Root: ${root}`)
+    console.log(`Tx:     ${txHash}`)
+
+    unlinkSync(testFile)
+
+    // 3. Retrieve it back
+    const outputFile = '/tmp/orbit-test-downloaded.txt'
+    console.log('\nDownloading...')
+    await orbit.retrieve(root, outputFile)
+    console.log(`Downloaded to ${outputFile}`)
+
+    // 4. AI inference
+    console.log('\nRunning inference...')
+    const result = await orbit.infer('meta-llama/Llama-3.3-70B', {
+        messages: [
+            { role: 'system', content: 'You are a helpful assistant.' },
+            { role: 'user', content: 'Explain what 0G is in one sentence.' },
+        ],
+        temperature: 0.7,
+    })
+
+    console.log(`\nResponse: ${result.content}`)
+    console.log(`Model:    ${result.model}`)
+    if (result.usage) {
+        console.log(`Tokens:   ${result.usage.totalTokens}`)
+    }
+    if (result.verified !== null) {
+        console.log(`Verified: ${result.verified}`)
+    }
+}
+
+main().catch(console.error)

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "0g-orbit",
+  "version": "0.1.0",
+  "description": "The developer toolkit for 0G. Store, infer, deploy — one SDK, one CLI, five minutes.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "bin": {
+    "orbit": "./dist/cli/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@0gfoundation/0g-ts-sdk": "^1.0.1",
+    "@0glabs/0g-serving-broker": "^0.7.4",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "ethers": "^6.13.1",
+    "ora": "^8.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  },
+  "keywords": ["0g", "blockchain", "ai", "storage", "inference", "sdk", "cli"],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/packages/cli/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "0g-orbit-cli",
+  "version": "0.1.0",
+  "description": "CLI for 0G Orbit — store, infer, deploy from your terminal.",
+  "type": "module",
+  "bin": {
+    "orbit": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "lint": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "0g-orbit-core": "workspace:*",
+    "commander": "^12.1.0",
+    "ora": "^8.0.1",
+    "chalk": "^5.3.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@types/node": "^20.12.0"
+  },
+  "keywords": ["0g", "cli", "blockchain", "ai"],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/packages/cli/src/cli.ts

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander'
+import { storeCommand, storeDataCommand, retrieveCommand } from './commands/storage.js'
+import { inferCommand, listServicesCommand } from './commands/inference.js'
+import { statusCommand } from './commands/account.js'
+import { initCommand } from './commands/init.js'
+
+const program = new Command()
+
+program
+    .name('orbit')
+    .description('The developer toolkit for 0G')
+    .version('0.1.0')
+
+program
+    .command('init')
+    .description('Initialize a new 0G project')
+    .option('-t, --template <name>', 'template to use', 'default')
+    .option('-d, --dir <path>', 'directory to create', '.')
+    .action(initCommand)
+
+program
+    .command('store <file>')
+    .description('Upload a file to 0G Storage')
+    .option('-n, --network <name>', 'network (testnet|mainnet)', 'testnet')
+    .option('--tags <hex>', 'custom tags (hex string)')
+    .option('--replicas <n>', 'number of replicas', '1')
+    .action(storeCommand)
+
+program
+    .command('store-data <text>')
+    .description('Upload a text string to 0G Storage')
+    .option('-n, --network <name>', 'network (testnet|mainnet)', 'testnet')
+    .option('--tags <hex>', 'custom tags (hex string)')
+    .option('--replicas <n>', 'number of replicas', '1')
+    .action(storeDataCommand)
+
+program
+    .command('retrieve <rootHash> <output>')
+    .description('Download a file from 0G Storage')
+    .option('-n, --network <name>', 'network (testnet|mainnet)', 'testnet')
+    .option('--proof', 'verify merkle proofs during download')
+    .action(retrieveCommand)
+
+program
+    .command('infer <model>')
+    .description('Run AI inference on the 0G Compute Network')
+    .option('-n, --network <name>', 'network (testnet|mainnet)', 'testnet')
+    .option('-m, --message <text>', 'message to send')
+    .option('-s, --system <text>', 'system prompt')
+    .option('-t, --temperature <n>', 'sampling temperature', '0.7')
+    .option('--max-tokens <n>', 'maximum tokens to generate')
+    .option('--provider <address>', 'specific provider address')
+    .action(inferCommand)
+
+program
+    .command('services')
+    .description('List available AI services on the network')
+    .option('-n, --network <name>', 'network (testnet|mainnet)', 'testnet')
+    .action(listServicesCommand)
+
+program
+    .command('status')
+    .description('Show account status and balance')
+    .option('-n, --network <name>', 'network (testnet|mainnet)', 'testnet')
+    .action(statusCommand)
+
+program.parse()

package/packages/cli/src/commands/account.ts

@@ -0,0 +1,29 @@
+import ora from 'ora'
+import chalk from 'chalk'
+import { connectOrbit, formatError } from '../utils.js'
+
+interface StatusOpts {
+    network: string
+}
+
+export async function statusCommand(opts: StatusOpts) {
+    const spinner = ora('Checking status...').start()
+
+    try {
+        const orbit = await connectOrbit(opts.network)
+        const status = await orbit.status()
+
+        spinner.stop()
+
+        console.log()
+        console.log(chalk.bold('  0G Orbit'))
+        console.log(`  ${chalk.dim('Network:')}  ${status.network}`)
+        console.log(`  ${chalk.dim('Address:')}  ${status.address}`)
+        console.log(`  ${chalk.dim('Balance:')}  ${chalk.cyan(status.balance)} OG`)
+        console.log()
+    } catch (err) {
+        spinner.fail(chalk.red('Failed to get status'))
+        console.error(chalk.dim(`  ${formatError(err)}`))
+        process.exit(1)
+    }
+}