0g-orbit 0.2.1 → 0.2.3

package/src/storage.test.ts

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

@@ -1,158 +0,0 @@
-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('insufficient funds') || msg.includes('INSUFFICIENT_FUNDS')) {
-                    suggestion = 'Your wallet needs more OG for gas. Get testnet OG from: https://faucet.0g.ai'
-                } else if (msg.includes('underpriced') || msg.includes('gas required exceeds')) {
-                    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.'
-                }
-                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

@@ -1,157 +0,0 @@
-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
-}
-
-// --- Fine-Tuning ---
-
-export interface DatasetUploadResult {
-    /** Merkle root hash of the uploaded dataset in 0G Storage */
-    root: string
-    /** On-chain transaction hash */
-    txHash: string
-}
-
-export interface CreateTaskOptions {
-    /** Name of the base model to fine-tune (e.g. 'Qwen2.5-0.5B-Instruct') */
-    model: string
-    /** Root hash of the dataset in 0G Storage (from uploadDataset) */
-    dataset: string
-    /** Provider wallet address */
-    providerAddress: string
-    /** Training hyperparameters (JSON object or file path) */
-    trainingParams?: {
-        nEpochs?: number
-        batchSize?: number
-        learningRate?: number
-        loraRank?: number
-        loraAlpha?: number
-        [key: string]: unknown
-    }
-}
-
-export type FineTuneStatus =
-    | 'init'
-    | 'setting-up'
-    | 'set-up'
-    | 'training'
-    | 'trained'
-    | 'delivering'
-    | 'delivered'
-    | 'acknowledged'
-    | 'finished'
-    | 'failed'
-
-export interface FineTuneTask {
-    /** Task ID */
-    id: string
-    /** Base model name or hash */
-    model: string
-    /** Dataset root hash */
-    dataset: string
-    /** Provider address */
-    provider: string
-    /** Current task status */
-    status: FineTuneStatus
-    /** Task creation time */
-    createdAt?: string
-    /** Last update time */
-    updatedAt?: string
-}
-
-export interface FineTuneModel {
-    /** Model name */
-    name: string
-    /** Model configuration (hash, description, etc.) */
-    config: Record<string, string>
-}
-
-export interface FineTuneProvider {
-    /** Provider wallet address */
-    address: string
-    /** Provider endpoint URL */
-    url: string
-    /** Customized models offered by this provider */
-    models: string[]
-}

package/tsconfig.json

@@ -1,20 +0,0 @@
-{
-  "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

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