0g-orbit 0.1.0

package/src/retry.test.ts

@@ -0,0 +1,99 @@
+import { describe, it, expect, vi } from 'vitest'
+import { withRetry, isTransientError } from './retry.js'
+
+describe('withRetry', () => {
+    it('returns on first success', async () => {
+        const fn = vi.fn().mockResolvedValue('ok')
+        const result = await withRetry(fn)
+        expect(result).toBe('ok')
+        expect(fn).toHaveBeenCalledTimes(1)
+    })
+
+    it('retries on transient error and succeeds', async () => {
+        const fn = vi.fn()
+            .mockRejectedValueOnce(new Error('ECONNREFUSED'))
+            .mockResolvedValue('ok')
+
+        const result = await withRetry(fn, { baseDelay: 10 })
+        expect(result).toBe('ok')
+        expect(fn).toHaveBeenCalledTimes(2)
+    })
+
+    it('throws after maxAttempts exhausted', async () => {
+        const fn = vi.fn().mockRejectedValue(new Error('ETIMEDOUT'))
+
+        await expect(
+            withRetry(fn, { maxAttempts: 3, baseDelay: 10 })
+        ).rejects.toThrow('ETIMEDOUT')
+        expect(fn).toHaveBeenCalledTimes(3)
+    })
+
+    it('does not retry non-transient errors', async () => {
+        const fn = vi.fn().mockRejectedValue(new Error('Invalid private key'))
+
+        await expect(
+            withRetry(fn, { maxAttempts: 3, baseDelay: 10 })
+        ).rejects.toThrow('Invalid private key')
+        expect(fn).toHaveBeenCalledTimes(1)
+    })
+
+    it('calls onRetry callback', async () => {
+        const onRetry = vi.fn()
+        const fn = vi.fn()
+            .mockRejectedValueOnce(new Error('ECONNRESET'))
+            .mockResolvedValue('ok')
+
+        await withRetry(fn, { baseDelay: 10, onRetry })
+        expect(onRetry).toHaveBeenCalledTimes(1)
+        expect(onRetry).toHaveBeenCalledWith(1, expect.any(Error))
+    })
+
+    it('respects custom isRetryable predicate', async () => {
+        const fn = vi.fn()
+            .mockRejectedValueOnce(new Error('custom-retryable'))
+            .mockResolvedValue('ok')
+
+        const result = await withRetry(fn, {
+            baseDelay: 10,
+            isRetryable: (err) => err instanceof Error && err.message === 'custom-retryable',
+        })
+        expect(result).toBe('ok')
+        expect(fn).toHaveBeenCalledTimes(2)
+    })
+})
+
+describe('isTransientError', () => {
+    it.each([
+        'ECONNREFUSED',
+        'ECONNRESET',
+        'ETIMEDOUT',
+        'ENOTFOUND',
+        'fetch failed',
+        'network error',
+        'timeout exceeded',
+        'server error',
+        'bad gateway',
+        'service unavailable',
+        'rate limit exceeded',
+        'missing response',
+        'connection error',
+        'could not detect network',
+    ])('returns true for "%s"', (msg) => {
+        expect(isTransientError(new Error(msg))).toBe(true)
+    })
+
+    it.each([
+        'Invalid private key',
+        'insufficient funds for gas',
+        'File not found',
+        'unknown error',
+    ])('returns false for "%s"', (msg) => {
+        expect(isTransientError(new Error(msg))).toBe(false)
+    })
+
+    it('returns false for non-Error values', () => {
+        expect(isTransientError('string error')).toBe(false)
+        expect(isTransientError(null)).toBe(false)
+        expect(isTransientError(42)).toBe(false)
+    })
+})

package/src/retry.ts

@@ -0,0 +1,99 @@
+export interface RetryOptions {
+    /** Maximum number of attempts (default: 3) */
+    maxAttempts?: number
+    /** Base delay between retries in ms (default: 1000). Doubles each retry. */
+    baseDelay?: number
+    /** Maximum delay cap in ms (default: 10000) */
+    maxDelay?: number
+    /** Predicate to decide if an error is retryable (default: transient errors only) */
+    isRetryable?: (err: unknown) => boolean
+    /** Called before each retry with attempt number and error */
+    onRetry?: (attempt: number, err: unknown) => void
+}
+
+const DEFAULT_OPTIONS: Required<Omit<RetryOptions, 'onRetry'>> = {
+    maxAttempts: 3,
+    baseDelay: 1000,
+    maxDelay: 10_000,
+    isRetryable: isTransientError,
+}
+
+/**
+ * Retry an async operation with exponential backoff.
+ * Only retries on transient errors (network, timeout, 5xx) by default.
+ */
+export async function withRetry<T>(
+    fn: () => Promise<T>,
+    options: RetryOptions = {}
+): Promise<T> {
+    const opts = { ...DEFAULT_OPTIONS, ...options }
+    let lastError: unknown
+
+    for (let attempt = 1; attempt <= opts.maxAttempts; attempt++) {
+        try {
+            return await fn()
+        } catch (err) {
+            lastError = err
+
+            if (attempt === opts.maxAttempts || !opts.isRetryable(err)) {
+                throw err
+            }
+
+            if (options.onRetry) {
+                options.onRetry(attempt, err)
+            }
+
+            // Exponential backoff with jitter
+            const delay = Math.min(
+                opts.baseDelay * Math.pow(2, attempt - 1) + Math.random() * 500,
+                opts.maxDelay
+            )
+            await sleep(delay)
+        }
+    }
+
+    throw lastError
+}
+
+function sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/**
+ * Determines if an error is transient and worth retrying.
+ * Covers: network failures, timeouts, RPC errors, 5xx responses.
+ */
+export function isTransientError(err: unknown): boolean {
+    if (!(err instanceof Error)) return false
+    const msg = err.message.toLowerCase()
+
+    // Network-level failures
+    if (msg.includes('econnrefused')) return true
+    if (msg.includes('econnreset')) return true
+    if (msg.includes('etimedout')) return true
+    if (msg.includes('enotfound')) return true
+    if (msg.includes('epipe')) return true
+    if (msg.includes('fetch failed')) return true
+    if (msg.includes('network error')) return true
+
+    // Timeout
+    if (msg.includes('timeout')) return true
+    if (err.name === 'AbortError') return true
+
+    // RPC-level transient errors
+    if (msg.includes('server error')) return true
+    if (msg.includes('bad gateway')) return true
+    if (msg.includes('service unavailable')) return true
+    if (msg.includes('rate limit')) return true
+    if (msg.includes('429')) return true
+    if (msg.includes('502')) return true
+    if (msg.includes('503')) return true
+    if (msg.includes('504')) return true
+
+    // ethers provider errors
+    if (msg.includes('missing response')) return true
+    if (msg.includes('connection error')) return true
+    if (msg.includes('could not detect network')) return true
+
+    return false
+}

package/src/storage.test.ts

@@ -0,0 +1,199 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+// Mock the 0G SDK
+vi.mock('@0gfoundation/0g-ts-sdk', () => {
+    const mockClose = vi.fn()
+    const mockMerkleTree = vi.fn().mockResolvedValue([{ rootHash: '0xabc' }, null])
+
+    return {
+        ZgFile: {
+            fromFilePath: vi.fn().mockResolvedValue({
+                merkleTree: mockMerkleTree,
+                close: mockClose,
+                size: () => 100,
+            }),
+        },
+        Indexer: vi.fn().mockImplementation(() => ({
+            upload: vi.fn().mockResolvedValue([
+                { txHash: '0xtx123', rootHash: '0xroot456' },
+                null,
+            ]),
+            download: vi.fn().mockResolvedValue(null),
+        })),
+    }
+})
+
+import { StorageClient } from './storage.js'
+import { StorageError } from './errors.js'
+import { NETWORKS } from './networks.js'
+import { Indexer, ZgFile } from '@0gfoundation/0g-ts-sdk'
+
+const mockSigner = { address: '0x123' } as any
+const testNetwork = { ...NETWORKS.testnet }
+
+describe('StorageClient', () => {
+    beforeEach(() => {
+        vi.clearAllMocks()
+    })
+
+    describe('store', () => {
+        it('uploads a file and returns root + tx hash', async () => {
+            const client = new StorageClient(testNetwork, mockSigner)
+            const result = await client.store('/tmp/test.txt')
+            expect(result.root).toBe('0xroot456')
+            expect(result.txHash).toBe('0xtx123')
+        })
+
+        it('passes tags and replicas to upload', async () => {
+            const client = new StorageClient(testNetwork, mockSigner)
+            await client.store('/tmp/test.txt', { tags: '0xbeef', replicas: 3 })
+
+            const indexerInstance = (Indexer as any).mock.results[0].value
+            expect(indexerInstance.upload).toHaveBeenCalledWith(
+                expect.anything(),
+                testNetwork.rpcUrl,
+                expect.anything(),
+                expect.objectContaining({ tags: '0xbeef', expectedReplica: 3 }),
+                expect.objectContaining({ Retries: 5, Interval: 3 })
+            )
+        })
+
+        it('always passes gas retry options', async () => {
+            const client = new StorageClient(testNetwork, mockSigner)
+            await client.store('/tmp/test.txt')
+
+            const indexerInstance = (Indexer as any).mock.results[0].value
+            const retryOpts = indexerInstance.upload.mock.calls[0][4]
+            expect(retryOpts).toBeDefined()
+            expect(retryOpts.Retries).toBe(5)
+            expect(retryOpts.MaxGasPrice).toBeGreaterThan(0)
+        })
+
+        it('throws StorageError with suggestion on merkle failure', async () => {
+            const mockFile = {
+                merkleTree: vi.fn().mockResolvedValue([null, new Error('corrupt file')]),
+                close: vi.fn(),
+            }
+            ;(ZgFile.fromFilePath as any).mockResolvedValueOnce(mockFile)
+
+            const client = new StorageClient(testNetwork, mockSigner)
+            try {
+                await client.store('/tmp/bad.txt')
+                expect.unreachable('should have thrown')
+            } catch (err) {
+                expect(err).toBeInstanceOf(StorageError)
+                expect((err as StorageError).suggestion).toContain('file exists')
+            }
+        })
+
+        it('throws StorageError with gas suggestion on underpriced', async () => {
+            const indexerMock = {
+                upload: vi.fn().mockResolvedValue([
+                    { txHash: '', rootHash: '' },
+                    new Error('transaction underpriced'),
+                ]),
+                download: vi.fn(),
+            }
+            ;(Indexer as any).mockImplementationOnce(() => indexerMock)
+
+            const client = new StorageClient(testNetwork, mockSigner)
+            try {
+                await client.store('/tmp/test.txt')
+                expect.unreachable('should have thrown')
+            } catch (err) {
+                expect(err).toBeInstanceOf(StorageError)
+                expect((err as StorageError).suggestion).toContain('maxGasPrice')
+            }
+        })
+
+        it('always closes the file even on error', async () => {
+            const mockClose = vi.fn()
+            const mockFile = {
+                merkleTree: vi.fn().mockRejectedValue(new Error('boom')),
+                close: mockClose,
+            }
+            ;(ZgFile.fromFilePath as any).mockResolvedValueOnce(mockFile)
+
+            const client = new StorageClient(testNetwork, mockSigner)
+            await client.store('/tmp/test.txt').catch(() => {})
+            expect(mockClose).toHaveBeenCalled()
+        })
+    })
+
+    describe('storeData', () => {
+        it('stores a string by writing to temp file', async () => {
+            const client = new StorageClient(testNetwork, mockSigner)
+            const result = await client.storeData('hello world')
+            expect(result.root).toBe('0xroot456')
+            expect(result.txHash).toBe('0xtx123')
+
+            // Verify ZgFile.fromFilePath was called with a temp path
+            const calledPath = (ZgFile.fromFilePath as any).mock.calls[0][0]
+            expect(calledPath).toContain('orbit-')
+        })
+
+        it('stores a Buffer', async () => {
+            const client = new StorageClient(testNetwork, mockSigner)
+            const result = await client.storeData(Buffer.from('binary data'))
+            expect(result.root).toBe('0xroot456')
+        })
+
+        it('stores a Uint8Array', async () => {
+            const client = new StorageClient(testNetwork, mockSigner)
+            const result = await client.storeData(new Uint8Array([1, 2, 3]))
+            expect(result.root).toBe('0xroot456')
+        })
+
+        it('cleans up temp file after upload', async () => {
+            const client = new StorageClient(testNetwork, mockSigner)
+            await client.storeData('cleanup test')
+
+            const calledPath = (ZgFile.fromFilePath as any).mock.calls[0][0]
+            // Temp file should have been deleted
+            expect(existsSync(calledPath)).toBe(false)
+        })
+
+        it('cleans up temp file even on error', async () => {
+            const mockFile = {
+                merkleTree: vi.fn().mockResolvedValue([null, new Error('fail')]),
+                close: vi.fn(),
+            }
+            ;(ZgFile.fromFilePath as any).mockResolvedValueOnce(mockFile)
+
+            const client = new StorageClient(testNetwork, mockSigner)
+            await client.storeData('error cleanup test').catch(() => {})
+
+            const calledPath = (ZgFile.fromFilePath as any).mock.calls[0][0]
+            expect(existsSync(calledPath)).toBe(false)
+        })
+    })
+
+    describe('retrieve', () => {
+        it('downloads successfully', async () => {
+            const client = new StorageClient(testNetwork, mockSigner)
+            await expect(
+                client.retrieve('0xroot', '/tmp/output.txt')
+            ).resolves.toBeUndefined()
+        })
+
+        it('throws StorageError on download failure', async () => {
+            const indexerMock = {
+                upload: vi.fn(),
+                download: vi.fn().mockResolvedValue(new Error('file not found: 404')),
+            }
+            ;(Indexer as any).mockImplementationOnce(() => indexerMock)
+
+            const client = new StorageClient(testNetwork, mockSigner)
+            try {
+                await client.retrieve('0xbad', '/tmp/out.txt')
+                expect.unreachable('should have thrown')
+            } catch (err) {
+                expect(err).toBeInstanceOf(StorageError)
+                expect((err as StorageError).suggestion).toContain('root hash')
+            }
+        })
+    })
+})

package/src/storage.ts

@@ -0,0 +1,158 @@
+import { Indexer, ZgFile } from '@0gfoundation/0g-ts-sdk'
+import type { Signer } from 'ethers'
+import { writeFileSync, unlinkSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { randomBytes } from 'node:crypto'
+import type { NetworkConfig } from './networks.js'
+import type { StoreResult, StoreOptions, RetrieveOptions } from './types.js'
+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 {
+    private indexer: Indexer
+    private rpcUrl: string
+    private signer: Signer
+
+    constructor(network: NetworkConfig, signer: 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: string, options: StoreOptions = {}): Promise<StoreResult> {
+        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: string | Buffer | Uint8Array,
+        options: StoreOptions = {}
+    ): Promise<StoreResult> {
+        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 */ }
+        }
+    }
+
+    private async _store(filePath: string, options: StoreOptions): Promise<StoreResult> {
+        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 as any,
+                {
+                    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: string,
+        outputPath: string,
+        options: RetrieveOptions = {}
+    ): Promise<void> {
+        return withRetry(
+            () => this._retrieve(rootHash, outputPath, options),
+            { maxAttempts: 3 }
+        )
+    }
+
+    private async _retrieve(
+        rootHash: string,
+        outputPath: string,
+        options: RetrieveOptions
+    ): Promise<void> {
+        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)
+        }
+    }
+}

package/src/types.ts

@@ -0,0 +1,85 @@
+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
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.test.ts"]
+}

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+    test: {
+        include: ['src/**/*.test.ts'],
+    },
+})