0g-orbit 0.2.2 → 0.2.3

package/src/networks.ts

@@ -1,62 +0,0 @@
-export type NetworkName = 'testnet' | 'mainnet'
-
-export interface NetworkConfig {
-    name: NetworkName
-    chainId: bigint
-    rpcUrl: string
-    /** Fallback RPC URLs, tried in order if the primary fails */
-    rpcUrls: string[]
-    indexerUrl: string
-    flowContractAddress: string
-    ledgerContractAddress: string
-    inferenceContractAddress: string
-    fineTuningContractAddress: string
-}
-
-export const NETWORKS: Record<NetworkName, NetworkConfig> = {
-    testnet: {
-        name: 'testnet',
-        chainId: 16602n,
-        rpcUrl: 'https://evmrpc-testnet.0g.ai',
-        rpcUrls: [
-            'https://evmrpc-testnet.0g.ai',
-            'https://16600-rpc.testnet.0g.ai',
-            'https://og-testnet-evm-rpc.allthatnode.com',
-        ],
-        indexerUrl: 'https://indexer-storage-testnet-turbo.0g.ai',
-        flowContractAddress: '0xbD2C3F0E65eDF5582141C35969d66e34e4E6BF80',
-        ledgerContractAddress: '0xE70830508dAc0A97e6c087c75f402f9Be669E406',
-        inferenceContractAddress: '0xa79F4c8311FF93C06b8CfB403690cc987c93F91E',
-        fineTuningContractAddress: '0xC6C075D8039763C8f1EbE580be5ADdf2fd6941bA',
-    },
-    mainnet: {
-        name: 'mainnet',
-        chainId: 16661n,
-        rpcUrl: 'https://evmrpc.0g.ai',
-        rpcUrls: [
-            'https://evmrpc.0g.ai',
-            'https://0g-rpc-evm01.validatorvn.com',
-            'https://rpc.0g.thirdweb.com',
-        ],
-        indexerUrl: 'https://indexer-storage.0g.ai',
-        flowContractAddress: '0x0460aA47b41a66694c0a73f667a1b795A5ED3556',
-        ledgerContractAddress: '0x2dE54c845Cd948B72D2e32e39586fe89607074E3',
-        inferenceContractAddress: '0x47340d900bdFec2BD393c626E12ea0656F938d84',
-        fineTuningContractAddress: '0x4e3474095518883744ddf135b7E0A23301c7F9c0',
-    },
-}
-
-export function getNetwork(nameOrChainId: NetworkName | bigint): NetworkConfig {
-    if (typeof nameOrChainId === 'string') {
-        const config = NETWORKS[nameOrChainId]
-        if (!config) throw new Error(`Unknown network: ${nameOrChainId}`)
-        // Return a copy so overrides don't mutate the original
-        return { ...config, rpcUrls: [...config.rpcUrls] }
-    }
-    for (const config of Object.values(NETWORKS)) {
-        if (config.chainId === nameOrChainId) {
-            return { ...config, rpcUrls: [...config.rpcUrls] }
-        }
-    }
-    throw new Error(`Unknown chain ID: ${nameOrChainId}`)
-}

package/src/orbit.test.ts

@@ -1,153 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest'
-import { ConnectionError } from './errors.js'
-
-// Mock ethers before importing Orbit
-vi.mock('ethers', () => {
-    const mockProvider = {
-        getNetwork: vi.fn().mockResolvedValue({ chainId: 16602n }),
-        getBalance: vi.fn().mockResolvedValue(1000000000000000000n), // 1 OG
-    }
-    const MockJsonRpcProvider = vi.fn(() => mockProvider)
-    const MockWallet = vi.fn((key: string, provider: any) => ({
-        address: '0x1234567890abcdef1234567890abcdef12345678',
-        provider,
-    }))
-    return {
-        JsonRpcProvider: MockJsonRpcProvider,
-        Wallet: MockWallet,
-    }
-})
-
-// Mock the storage and inference clients
-vi.mock('./storage.js', () => ({
-    StorageClient: vi.fn(),
-}))
-vi.mock('./inference.js', () => ({
-    InferenceClient: vi.fn(),
-}))
-
-import { Orbit } from './orbit.js'
-import { JsonRpcProvider } from 'ethers'
-
-describe('Orbit.connect', () => {
-    beforeEach(() => {
-        vi.clearAllMocks()
-        delete process.env.PRIVATE_KEY
-    })
-
-    it('connects with explicit private key', async () => {
-        const orbit = await Orbit.connect({
-            network: 'testnet',
-            privateKey: '0xabc123',
-        })
-        expect(orbit.address).toBe('0x1234567890abcdef1234567890abcdef12345678')
-        expect(orbit.network.name).toBe('testnet')
-    })
-
-    it('reads PRIVATE_KEY from env var', async () => {
-        process.env.PRIVATE_KEY = '0xenv_key_123'
-        const orbit = await Orbit.connect({ network: 'testnet' })
-        expect(orbit.address).toBeDefined()
-    })
-
-    it('throws with suggestion when no private key available', async () => {
-        await expect(
-            Orbit.connect({ network: 'testnet' })
-        ).rejects.toThrow('No private key provided')
-
-        try {
-            await Orbit.connect({ network: 'testnet' })
-        } catch (err) {
-            expect(err).toBeInstanceOf(ConnectionError)
-            expect((err as ConnectionError).suggestion).toContain('PRIVATE_KEY')
-        }
-    })
-
-    it('throws on chain ID mismatch', async () => {
-        const { JsonRpcProvider } = await import('ethers')
-        const mockProvider = new JsonRpcProvider() as any
-        mockProvider.getNetwork.mockResolvedValueOnce({ chainId: 99999n })
-
-        await expect(
-            Orbit.connect({ network: 'testnet', privateKey: '0xabc' })
-        ).rejects.toThrow('Chain ID mismatch')
-    })
-
-    it('warns on zero balance but still connects', async () => {
-        const { JsonRpcProvider } = await import('ethers')
-        const mockProvider = new JsonRpcProvider() as any
-        mockProvider.getNetwork.mockResolvedValueOnce({ chainId: 16602n })
-        mockProvider.getBalance.mockResolvedValueOnce(0n)
-
-        const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
-
-        const orbit = await Orbit.connect({
-            network: 'testnet',
-            privateKey: '0xabc',
-        })
-
-        expect(orbit).toBeDefined()
-        expect(warnSpy).toHaveBeenCalledWith(
-            expect.stringContaining('0 OG balance')
-        )
-        warnSpy.mockRestore()
-    })
-
-    it('tries fallback RPC URLs on connection failure', async () => {
-        const { JsonRpcProvider } = await import('ethers')
-
-        // First two URLs fail, third succeeds
-        let callCount = 0
-        ;(JsonRpcProvider as any).mockImplementation(() => {
-            callCount++
-            const provider = {
-                getNetwork: callCount < 3
-                    ? vi.fn().mockRejectedValue(new Error('ECONNREFUSED'))
-                    : vi.fn().mockResolvedValue({ chainId: 16602n }),
-                getBalance: vi.fn().mockResolvedValue(1000000000000000000n),
-            }
-            return provider
-        })
-
-        const orbit = await Orbit.connect({
-            network: 'testnet',
-            privateKey: '0xabc',
-        })
-        expect(orbit).toBeDefined()
-        expect(callCount).toBe(3)
-    })
-
-    it('throws when all RPC URLs fail', async () => {
-        const { JsonRpcProvider } = await import('ethers')
-        ;(JsonRpcProvider as any).mockImplementation(() => ({
-            getNetwork: vi.fn().mockRejectedValue(new Error('ECONNREFUSED')),
-        }))
-
-        await expect(
-            Orbit.connect({ network: 'testnet', privateKey: '0xabc' })
-        ).rejects.toThrow('Failed to connect to any RPC endpoint')
-    })
-})
-
-describe('Orbit.status', () => {
-    beforeEach(() => {
-        vi.clearAllMocks()
-        // Restore default mock after tests that override JsonRpcProvider
-        const mockProvider = {
-            getNetwork: vi.fn().mockResolvedValue({ chainId: 16602n }),
-            getBalance: vi.fn().mockResolvedValue(1000000000000000000n),
-        }
-        ;(JsonRpcProvider as any).mockImplementation(() => mockProvider)
-    })
-
-    it('returns formatted balance and address', async () => {
-        const orbit = await Orbit.connect({
-            network: 'testnet',
-            privateKey: '0xabc',
-        })
-        const status = await orbit.status()
-        expect(status.network).toBe('testnet')
-        expect(status.address).toBe('0x1234567890abcdef1234567890abcdef12345678')
-        expect(status.balance).toMatch(/^\d+\.\d{6}$/)
-    })
-})

package/src/orbit.ts

@@ -1,204 +0,0 @@
-import { Wallet, JsonRpcProvider } from 'ethers'
-import type { NetworkName, NetworkConfig } from './networks.js'
-import { getNetwork, NETWORKS } from './networks.js'
-import { StorageClient } from './storage.js'
-import { InferenceClient } from './inference.js'
-import { FineTuningClient } from './fine-tuning.js'
-import type {
-    OrbitConfig,
-    StoreResult,
-    StoreOptions,
-    RetrieveOptions,
-    InferResult,
-    InferOptions,
-    ServiceInfo,
-    AccountStatus,
-    DatasetUploadResult,
-    CreateTaskOptions,
-    FineTuneTask,
-    FineTuneModel,
-    FineTuneProvider,
-} from './types.js'
-import { ConnectionError } from './errors.js'
-
-export class Orbit {
-    readonly network: NetworkConfig
-    readonly storage: StorageClient
-    readonly inference: InferenceClient
-    private _fineTuning: FineTuningClient | null = null
-    private wallet: Wallet
-    private provider: JsonRpcProvider
-
-    private constructor(
-        network: NetworkConfig,
-        wallet: Wallet,
-        provider: JsonRpcProvider
-    ) {
-        this.network = network
-        this.wallet = wallet
-        this.provider = provider
-        this.storage = new StorageClient(network, wallet)
-        this.inference = new InferenceClient(network, wallet)
-    }
-
-    /** Lazy-initialized fine-tuning client */
-    get fineTuning(): FineTuningClient {
-        if (!this._fineTuning) {
-            this._fineTuning = new FineTuningClient(this.network, this.wallet, this.storage)
-        }
-        return this._fineTuning
-    }
-
-    /**
-     * Connect to the 0G network. This is the primary entry point.
-     *
-     * Tries the primary RPC URL first, then falls back to alternates.
-     * If privateKey is not provided, reads from PRIVATE_KEY env var.
-     */
-    static async connect(config: OrbitConfig): Promise<Orbit> {
-        // Resolve private key: explicit > env var
-        const privateKey = config.privateKey ?? process.env.PRIVATE_KEY
-        if (!privateKey) {
-            throw new ConnectionError(
-                'No private key provided.',
-                'Pass privateKey in config or set the PRIVATE_KEY environment variable. Example: PRIVATE_KEY=0x... npx tsx index.ts'
-            )
-        }
-
-        const networkConfig = getNetwork(config.network)
-
-        // Allow overrides
-        if (config.rpcUrl) networkConfig.rpcUrl = config.rpcUrl
-        if (config.indexerUrl) networkConfig.indexerUrl = config.indexerUrl
-
-        // Build candidate RPC URLs: explicit override first, then the fallback list
-        const rpcUrls = config.rpcUrl
-            ? [config.rpcUrl]
-            : networkConfig.rpcUrls
-
-        // Try each RPC URL until one connects
-        let lastError: Error | null = null
-        for (const url of rpcUrls) {
-            try {
-                const provider = new JsonRpcProvider(url)
-                const wallet = new Wallet(privateKey, provider)
-
-                const chainId = (await provider.getNetwork()).chainId
-                if (chainId !== networkConfig.chainId) {
-                    throw new ConnectionError(
-                        `Chain ID mismatch: expected ${networkConfig.chainId}, got ${chainId}`,
-                        `Your RPC endpoint is on a different network. Use the correct RPC URL for ${networkConfig.name}.`
-                    )
-                }
-
-                // Lock in the working URL
-                networkConfig.rpcUrl = url
-
-                // Check balance and warn if zero (non-blocking)
-                try {
-                    const balance = await provider.getBalance(wallet.address)
-                    if (balance === 0n) {
-                        console.warn(
-                            `[0G Orbit] Warning: wallet ${wallet.address} has 0 OG balance on ${networkConfig.name}. ` +
-                            `Get testnet tokens at https://faucet.0g.ai`
-                        )
-                    }
-                } catch {
-                    // Balance check failure is non-fatal
-                }
-
-                return new Orbit(networkConfig, wallet, provider)
-            } catch (err) {
-                // Chain ID mismatch is not a transient failure — don't try other URLs
-                if (err instanceof ConnectionError && err.message.includes('Chain ID mismatch')) {
-                    throw err
-                }
-                lastError = err instanceof Error ? err : new Error(String(err))
-            }
-        }
-
-        const tried = rpcUrls.join(', ')
-        throw new ConnectionError(
-            `Failed to connect to any RPC endpoint. Tried: ${tried}. Last error: ${lastError?.message ?? 'unknown'}`,
-            'All RPC endpoints are unreachable. Check your internet connection, or provide a custom RPC URL with the rpcUrl option.'
-        )
-    }
-
-    // --- Storage shortcuts ---
-
-    async store(filePath: string, options?: StoreOptions): Promise<StoreResult> {
-        return this.storage.store(filePath, options)
-    }
-
-    async storeData(
-        data: string | Buffer | Uint8Array,
-        options?: StoreOptions
-    ): Promise<StoreResult> {
-        return this.storage.storeData(data, options)
-    }
-
-    async retrieve(
-        rootHash: string,
-        outputPath: string,
-        options?: RetrieveOptions
-    ): Promise<void> {
-        return this.storage.retrieve(rootHash, outputPath, options)
-    }
-
-    // --- Inference shortcuts ---
-
-    async infer(model: string, options: InferOptions): Promise<InferResult> {
-        return this.inference.infer(model, options)
-    }
-
-    async listServices(): Promise<ServiceInfo[]> {
-        return this.inference.listServices()
-    }
-
-    // --- Fine-Tuning shortcuts ---
-
-    async uploadDataset(filePath: string): Promise<DatasetUploadResult> {
-        return this.fineTuning.uploadDataset(filePath)
-    }
-
-    async createFineTuneTask(options: CreateTaskOptions): Promise<FineTuneTask> {
-        return this.fineTuning.createTask(options)
-    }
-
-    async getFineTuneTask(providerAddress: string, taskId: string): Promise<FineTuneTask> {
-        return this.fineTuning.getTask(providerAddress, taskId)
-    }
-
-    async downloadModel(
-        providerAddress: string,
-        taskId: string,
-        outputPath: string
-    ): Promise<void> {
-        return this.fineTuning.downloadModel(providerAddress, taskId, outputPath)
-    }
-
-    async listModels(): Promise<FineTuneModel[]> {
-        return this.fineTuning.listModels()
-    }
-
-    async listProviders(): Promise<FineTuneProvider[]> {
-        return this.fineTuning.listProviders()
-    }
-
-    // --- Account ---
-
-    async status(): Promise<AccountStatus> {
-        const balance = await this.provider.getBalance(this.wallet.address)
-        const balanceOG = Number(balance) / 1e18
-
-        return {
-            balance: balanceOG.toFixed(6),
-            network: this.network.name,
-            address: this.wallet.address,
-        }
-    }
-
-    get address(): string {
-        return this.wallet.address
-    }
-}

package/src/retry.test.ts

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

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