0g-orbit 0.1.0

package/packages/cli/src/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/packages/cli/src/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-core': '^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-core'
+
+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/packages/cli/src/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/packages/cli/src/utils.ts

@@ -0,0 +1,21 @@
+import { Orbit, OrbitError } from '0g-orbit-core'
+import type { NetworkName } from '0g-orbit-core'
+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/packages/cli/tsconfig.json

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

package/packages/core/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "0g-orbit-core",
+  "version": "0.1.0",
+  "description": "Unified SDK for 0G — storage, compute, and chain in one interface.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "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",
+    "ethers": "^6.13.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  },
+  "keywords": ["0g", "blockchain", "ai", "storage", "inference"],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/packages/core/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/packages/core/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/packages/core/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'