0g-orbit 0.1.0

package/src/cli/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/src/cli/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)
+    }
+}

package/src/cli/commands/inference.ts

@@ -0,0 +1,103 @@
+import ora from 'ora'
+import chalk from 'chalk'
+import { connectOrbit, formatError } from '../utils.js'
+
+interface InferOpts {
+    network: string
+    message?: string
+    system?: string
+    temperature: string
+    maxTokens?: string
+    provider?: string
+}
+
+export async function inferCommand(model: string, opts: InferOpts) {
+    if (!opts.message) {
+        console.error(chalk.red('Error: --message is required'))
+        console.error(chalk.dim('  orbit infer meta-llama/Llama-3.3-70B -m "Hello!"'))
+        process.exit(1)
+    }
+
+    const spinner = ora('Connecting to 0G...').start()
+
+    try {
+        const orbit = await connectOrbit(opts.network)
+        spinner.text = `Sending to ${model}...`
+
+        const messages: Array<{ role: 'system' | 'user'; content: string }> = []
+        if (opts.system) {
+            messages.push({ role: 'system', content: opts.system })
+        }
+        messages.push({ role: 'user', content: opts.message })
+
+        const result = await orbit.infer(model, {
+            messages,
+            temperature: parseFloat(opts.temperature),
+            maxTokens: opts.maxTokens ? parseInt(opts.maxTokens, 10) : undefined,
+            provider: opts.provider,
+        })
+
+        spinner.succeed('Response received')
+        console.log()
+        console.log(result.content)
+        console.log()
+
+        if (result.usage) {
+            console.log(
+                chalk.dim(
+                    `  tokens: ${result.usage.promptTokens} in / ${result.usage.completionTokens} out` +
+                        ` | model: ${result.model}` +
+                        (result.verified !== null
+                            ? ` | verified: ${result.verified ? chalk.green('yes') : chalk.red('no')}`
+                            : '')
+                )
+            )
+        }
+    } catch (err) {
+        spinner.fail(chalk.red('Inference failed'))
+        console.error(chalk.dim(`  ${formatError(err)}`))
+        process.exit(1)
+    }
+}
+
+interface ServicesOpts {
+    network: string
+}
+
+export async function listServicesCommand(opts: ServicesOpts) {
+    const spinner = ora('Fetching services...').start()
+
+    try {
+        const orbit = await connectOrbit(opts.network)
+        const services = await orbit.listServices()
+
+        spinner.stop()
+
+        if (services.length === 0) {
+            console.log(chalk.dim('No services found on this network.'))
+            return
+        }
+
+        console.log(chalk.bold(`\n  ${services.length} services on ${opts.network}\n`))
+
+        for (const svc of services) {
+            const verTag = svc.verifiable
+                ? chalk.green(' [TEE]')
+                : ''
+            console.log(
+                `  ${chalk.cyan(svc.model)}${verTag}`
+            )
+            console.log(
+                chalk.dim(
+                    `    provider: ${svc.provider.slice(0, 10)}...${svc.provider.slice(-6)}` +
+                        `  |  in: ${svc.inputPrice} neuron  |  out: ${svc.outputPrice} neuron`
+                )
+            )
+        }
+        console.log()
+    } catch (err) {
+        spinner.fail(chalk.red('Failed to list services'))
+        console.error(chalk.dim(`  ${formatError(err)}`))
+        process.exit(1)
+    }
+}

package/src/cli/commands/init.ts

@@ -0,0 +1,71 @@
+import chalk from 'chalk'
+import { writeFileSync, mkdirSync, existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+interface InitOpts {
+    template: string
+    dir: string
+}
+
+export async function initCommand(opts: InitOpts) {
+    const dir = resolve(opts.dir)
+
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true })
+    }
+
+    // Create package.json
+    const pkg = {
+        name: 'my-0g-app',
+        version: '0.1.0',
+        type: 'module',
+        scripts: {
+            start: 'node index.js',
+        },
+        dependencies: {
+            '0g-orbit': '^0.1.0',
+        },
+    }
+    writeFileSync(join(dir, 'package.json'), JSON.stringify(pkg, null, 2) + '\n')
+
+    // Create index.js with example
+    const example = `import { Orbit } from '0g-orbit'
+
+const orbit = await Orbit.connect({
+    network: 'testnet',
+    privateKey: process.env.PRIVATE_KEY,
+})
+
+// Check account status
+const status = await orbit.status()
+console.log(\`Connected: \${status.address} on \${status.network}\`)
+console.log(\`Balance: \${status.balance} OG\`)
+
+// Upload a file
+// const { root } = await orbit.store('./my-file.txt')
+// console.log('Stored at:', root)
+
+// Run inference
+// const result = await orbit.infer('meta-llama/Llama-3.3-70B', {
+//     messages: [{ role: 'user', content: 'What is 0G?' }],
+// })
+// console.log(result.content)
+`
+    writeFileSync(join(dir, 'index.js'), example)
+
+    // Create .env.example
+    writeFileSync(join(dir, '.env.example'), 'PRIVATE_KEY=0x...\n')
+
+    // Create .gitignore
+    writeFileSync(join(dir, '.gitignore'), 'node_modules/\n.env\n')
+
+    console.log()
+    console.log(chalk.bold('  0G Orbit project initialized'))
+    console.log()
+    console.log(chalk.dim('  Next steps:'))
+    console.log(`  1. ${chalk.cyan('cd ' + (opts.dir === '.' ? '.' : opts.dir))}`)
+    console.log(`  2. ${chalk.cyan('cp .env.example .env')} and add your private key`)
+    console.log(`  3. ${chalk.cyan('npm install')}`)
+    console.log(`  4. ${chalk.cyan('node index.js')}`)
+    console.log()
+}

package/src/cli/commands/storage.ts

@@ -0,0 +1,91 @@
+import ora from 'ora'
+import chalk from 'chalk'
+import { connectOrbit, formatError } from '../utils.js'
+
+interface StoreOpts {
+    network: string
+    tags?: string
+    replicas: string
+}
+
+export async function storeCommand(file: string, opts: StoreOpts) {
+    const spinner = ora('Connecting to 0G...').start()
+
+    try {
+        const orbit = await connectOrbit(opts.network)
+        spinner.text = `Uploading ${file}...`
+
+        const result = await orbit.store(file, {
+            tags: opts.tags,
+            replicas: parseInt(opts.replicas, 10),
+        })
+
+        spinner.succeed('Upload complete')
+        console.log()
+        console.log(chalk.bold('  Root hash: ') + chalk.cyan(result.root))
+        console.log(chalk.bold('  Tx hash:   ') + chalk.dim(result.txHash))
+        console.log()
+        console.log(chalk.dim(`  Retrieve with: orbit retrieve ${result.root} ./output`))
+    } catch (err) {
+        spinner.fail(chalk.red('Upload failed'))
+        console.error(chalk.dim(`  ${formatError(err)}`))
+        process.exit(1)
+    }
+}
+
+interface StoreDataOpts {
+    network: string
+    tags?: string
+    replicas: string
+}
+
+export async function storeDataCommand(text: string, opts: StoreDataOpts) {
+    const spinner = ora('Connecting to 0G...').start()
+
+    try {
+        const orbit = await connectOrbit(opts.network)
+        spinner.text = 'Uploading data...'
+
+        const result = await orbit.storeData(text, {
+            tags: opts.tags,
+            replicas: parseInt(opts.replicas, 10),
+        })
+
+        spinner.succeed('Upload complete')
+        console.log()
+        console.log(chalk.bold('  Root hash: ') + chalk.cyan(result.root))
+        console.log(chalk.bold('  Tx hash:   ') + chalk.dim(result.txHash))
+        console.log()
+        console.log(chalk.dim(`  Retrieve with: orbit retrieve ${result.root} ./output`))
+    } catch (err) {
+        spinner.fail(chalk.red('Upload failed'))
+        console.error(chalk.dim(`  ${formatError(err)}`))
+        process.exit(1)
+    }
+}
+
+interface RetrieveOpts {
+    network: string
+    proof?: boolean
+}
+
+export async function retrieveCommand(
+    rootHash: string,
+    output: string,
+    opts: RetrieveOpts
+) {
+    const spinner = ora('Connecting to 0G...').start()
+
+    try {
+        const orbit = await connectOrbit(opts.network)
+        spinner.text = `Downloading to ${output}...`
+
+        await orbit.retrieve(rootHash, output, { proof: opts.proof })
+
+        spinner.succeed(`Downloaded to ${output}`)
+    } catch (err) {
+        spinner.fail(chalk.red('Download failed'))
+        console.error(chalk.dim(`  ${formatError(err)}`))
+        process.exit(1)
+    }
+}

package/src/cli/utils.ts

@@ -0,0 +1,21 @@
+import { Orbit, OrbitError } from '../index.js'
+import type { NetworkName } from '../index.js'
+import chalk from 'chalk'
+
+export async function connectOrbit(network: string): Promise<Orbit> {
+    return Orbit.connect({
+        network: network as NetworkName,
+    })
+}
+
+export function formatError(err: unknown): string {
+    if (err instanceof OrbitError) {
+        let msg = err.message
+        if (err.suggestion) {
+            msg += '\n  ' + chalk.yellow('Hint: ') + err.suggestion
+        }
+        return msg
+    }
+    if (err instanceof Error) return err.message
+    return String(err)
+}

package/src/errors.test.ts

@@ -0,0 +1,99 @@
+import { describe, it, expect } from 'vitest'
+import {
+    OrbitError,
+    ConnectionError,
+    StorageError,
+    InferenceError,
+    InsufficientBalanceError,
+    ProviderNotFoundError,
+    TimeoutError,
+} from './errors.js'
+
+describe('OrbitError', () => {
+    it('has code and suggestion', () => {
+        const err = new OrbitError('test', 'TEST_CODE', 'try this')
+        expect(err.message).toBe('test')
+        expect(err.code).toBe('TEST_CODE')
+        expect(err.suggestion).toBe('try this')
+        expect(err.name).toBe('OrbitError')
+        expect(err).toBeInstanceOf(Error)
+    })
+
+    it('suggestion is optional', () => {
+        const err = new OrbitError('test', 'CODE')
+        expect(err.suggestion).toBeUndefined()
+    })
+})
+
+describe('ConnectionError', () => {
+    it('has default suggestion', () => {
+        const err = new ConnectionError('failed')
+        expect(err.code).toBe('CONNECTION_ERROR')
+        expect(err.suggestion).toContain('RPC')
+    })
+
+    it('accepts custom suggestion', () => {
+        const err = new ConnectionError('failed', 'custom hint')
+        expect(err.suggestion).toBe('custom hint')
+    })
+})
+
+describe('StorageError', () => {
+    it('has default suggestion', () => {
+        const err = new StorageError('upload broke')
+        expect(err.code).toBe('STORAGE_ERROR')
+        expect(err.suggestion).toContain('file exists')
+    })
+})
+
+describe('InferenceError', () => {
+    it('has default suggestion', () => {
+        const err = new InferenceError('inference broke')
+        expect(err.code).toBe('INFERENCE_ERROR')
+        expect(err.suggestion).toContain('listServices')
+    })
+})
+
+describe('InsufficientBalanceError', () => {
+    it('includes required and available amounts', () => {
+        const err = new InsufficientBalanceError(1.5, 0.1)
+        expect(err.required).toBe(1.5)
+        expect(err.available).toBe(0.1)
+        expect(err.message).toContain('1.5')
+        expect(err.message).toContain('0.1')
+        expect(err.suggestion).toContain('faucet')
+    })
+})
+
+describe('ProviderNotFoundError', () => {
+    it('has suggestion about listServices', () => {
+        const err = new ProviderNotFoundError('No provider for model "gpt-5"')
+        expect(err.message).toContain('gpt-5')
+        expect(err.suggestion).toContain('listServices')
+    })
+})
+
+describe('TimeoutError', () => {
+    it('has timeout-specific suggestion', () => {
+        const err = new TimeoutError('timed out after 30s')
+        expect(err.code).toBe('TIMEOUT')
+        expect(err.suggestion).toContain('timeout')
+    })
+})
+
+describe('error hierarchy', () => {
+    it('all errors are instanceof OrbitError and Error', () => {
+        const errors = [
+            new ConnectionError('a'),
+            new StorageError('b'),
+            new InferenceError('c'),
+            new InsufficientBalanceError(1, 0),
+            new ProviderNotFoundError('d'),
+            new TimeoutError('e'),
+        ]
+        for (const err of errors) {
+            expect(err).toBeInstanceOf(OrbitError)
+            expect(err).toBeInstanceOf(Error)
+        }
+    })
+})

package/src/errors.ts

@@ -0,0 +1,79 @@
+export class OrbitError extends Error {
+    constructor(
+        message: string,
+        public readonly code: string,
+        public readonly suggestion?: string
+    ) {
+        super(message)
+        this.name = 'OrbitError'
+    }
+}
+
+export class ConnectionError extends OrbitError {
+    constructor(message: string, suggestion?: string) {
+        super(
+            message,
+            'CONNECTION_ERROR',
+            suggestion ?? 'Check your RPC URL and network connection. Try a different RPC endpoint with the rpcUrl option.'
+        )
+        this.name = 'ConnectionError'
+    }
+}
+
+export class StorageError extends OrbitError {
+    constructor(message: string, suggestion?: string) {
+        super(
+            message,
+            'STORAGE_ERROR',
+            suggestion ?? 'Check that your file exists and you have sufficient OG balance for gas fees.'
+        )
+        this.name = 'StorageError'
+    }
+}
+
+export class InferenceError extends OrbitError {
+    constructor(message: string, suggestion?: string) {
+        super(
+            message,
+            'INFERENCE_ERROR',
+            suggestion ?? 'Run orbit.listServices() to check available models and provider status.'
+        )
+        this.name = 'InferenceError'
+    }
+}
+
+export class InsufficientBalanceError extends OrbitError {
+    constructor(
+        public readonly required: number,
+        public readonly available: number
+    ) {
+        super(
+            `Insufficient balance: need ${required} OG but have ${available} OG`,
+            'INSUFFICIENT_BALANCE',
+            'Get testnet OG from the faucet: https://faucet.0g.ai'
+        )
+        this.name = 'InsufficientBalanceError'
+    }
+}
+
+export class ProviderNotFoundError extends OrbitError {
+    constructor(message: string) {
+        super(
+            message,
+            'PROVIDER_NOT_FOUND',
+            'Run orbit.listServices() to see available models and their providers.'
+        )
+        this.name = 'ProviderNotFoundError'
+    }
+}
+
+export class TimeoutError extends OrbitError {
+    constructor(message: string) {
+        super(
+            message,
+            'TIMEOUT',
+            'The request timed out. Try increasing the timeout option or check if the provider is responsive.'
+        )
+        this.name = 'TimeoutError'
+    }
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+// Main entry point
+export { Orbit } from './orbit.js'
+
+// Clients (for direct access)
+export { StorageClient } from './storage.js'
+export { InferenceClient } from './inference.js'
+
+// Types
+export type {
+    OrbitConfig,
+    StoreResult,
+    StoreOptions,
+    RetrieveOptions,
+    InferResult,
+    InferOptions,
+    ServiceInfo,
+    AccountStatus,
+} from './types.js'
+
+// Network config
+export type { NetworkName, NetworkConfig } from './networks.js'
+export { NETWORKS, getNetwork } from './networks.js'
+
+// Retry utilities
+export { withRetry, isTransientError } from './retry.js'
+export type { RetryOptions } from './retry.js'
+
+// Errors
+export {
+    OrbitError,
+    ConnectionError,
+    StorageError,
+    InferenceError,
+    InsufficientBalanceError,
+    ProviderNotFoundError,
+    TimeoutError,
+} from './errors.js'