Upload File to 0G Storage

Metadata

• Category: storage
• SDK: @0gfoundation/0g-storage-ts-sdk ^1.2.12, ethers 6.13.1
• Activation Triggers: "upload file", "store on 0G", "ZgFile", "save to storage"

Purpose

Upload files to 0G decentralized storage using the ZgFile API and Indexer. Files are split into chunks, organized as a Merkle tree, and distributed across storage nodes. Returns a root hash for later retrieval.

Prerequisites

• Node.js >= 18
• @0gfoundation/0g-storage-ts-sdk and ethers installed
• Funded wallet with 0G tokens
• .env with PRIVATE_KEY, RPC_URL, STORAGE_INDEXER

Quick Workflow

1. Initialize ethers provider and wallet from .env
2. Create an Indexer instance
3. Create a ZgFile from the file path
4. Generate the Merkle tree (computes root hash)
5. Upload via the Indexer
6. Close the file handle (critical!)
7. Return/store the root hash

Core Rules

ALWAYS

• Generate the Merkle tree BEFORE uploading
• Close file handles after upload (file.close())
• Store root hashes — they are the ONLY way to retrieve files later
• Use try/finally to ensure file handles are closed
• Read the upload result by field: result.txHash, result.rootHash, result.txSeq
• Load private keys from environment variables

NEVER

• Skip Merkle tree generation before upload
• Forget to close ZgFile handles (causes memory leaks)
• Treat the first element of the upload() result as a transaction-hash string — it is an object
• Hardcode private keys in source code
• Lose the root hash (data becomes irretrievable)

Code Examples

Basic File Upload

import { ZgFile, Indexer } from '@0gfoundation/0g-storage-ts-sdk';
import { ethers } from 'ethers';
import 'dotenv/config';

async function uploadFile(filePath: string): Promise<string> {
  const provider = new ethers.JsonRpcProvider(process.env.RPC_URL);
  const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);
  const indexer = new Indexer(process.env.STORAGE_INDEXER!);

  const file = await ZgFile.fromFilePath(filePath);
  try {
    const [tree, err] = await file.merkleTree();
    if (err) throw new Error(`Merkle tree error: ${err}`);

    const rootHash = tree!.rootHash();
    console.log('Root hash:', rootHash);

    // upload() resolves to [result, error]. `result` is an OBJECT, not a hash
    // string, and it is a UNION of two shapes:
    //   single file      -> { txHash,   rootHash,   txSeq  }
    //   fragmented file  -> { txHashes, rootHashes, txSeqs }
    // Narrow with an `in` check before reading either shape.
    const [result, uploadErr] = await indexer.upload(file, process.env.RPC_URL!, wallet);
    if (uploadErr) throw new Error(`Upload failed: ${uploadErr.message}`);

    const txHash = 'txHash' in result ? result.txHash : result.txHashes[0];
    const uploadedRoot = 'rootHash' in result ? result.rootHash : result.rootHashes[0];
    console.log('Upload tx:', txHash);
    console.log('Root hash from upload:', uploadedRoot); // matches `rootHash` above

    return rootHash;
  } finally {
    await file.close();
  }
}

// Usage
const rootHash = await uploadFile('./my-document.pdf');
console.log('Stored with root hash:', rootHash);

Upload from Buffer

import { ZgFile, Indexer } from '@0gfoundation/0g-storage-ts-sdk';
import { ethers } from 'ethers';
import * as fs from 'fs';
import * as os from 'os';
import * as path from 'path';
import 'dotenv/config';

async function uploadBuffer(data: Buffer, filename: string): Promise<string> {
  const provider = new ethers.JsonRpcProvider(process.env.RPC_URL);
  const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);
  const indexer = new Indexer(process.env.STORAGE_INDEXER!);

  // SDK requires file path — write buffer to temp file
  const tempPath = path.join(os.tmpdir(), `0g-upload-${Date.now()}-${filename}`);
  fs.writeFileSync(tempPath, data);

  const file = await ZgFile.fromFilePath(tempPath);
  try {
    const [tree, err] = await file.merkleTree();
    if (err) throw new Error(`Merkle tree error: ${err}`);

    const rootHash = tree!.rootHash();
    const [, uploadErr] = await indexer.upload(file, process.env.RPC_URL!, wallet);
    if (uploadErr) throw new Error(`Upload failed: ${uploadErr.message}`);
    return rootHash;
  } finally {
    await file.close();
    fs.unlinkSync(tempPath); // Clean up temp file
  }
}

// Usage
const jsonData = Buffer.from(JSON.stringify({ key: 'value' }));
const rootHash = await uploadBuffer(jsonData, 'data.json');

Upload with Progress and Error Handling

import { ZgFile, Indexer } from '@0gfoundation/0g-storage-ts-sdk';
import { ethers } from 'ethers';
import * as fs from 'fs';
import 'dotenv/config';

async function uploadWithValidation(filePath: string): Promise<string> {
  // Validate environment
  if (!process.env.PRIVATE_KEY) throw new Error('PRIVATE_KEY not set in .env');
  if (!process.env.RPC_URL) throw new Error('RPC_URL not set in .env');
  if (!process.env.STORAGE_INDEXER) throw new Error('STORAGE_INDEXER not set in .env');

  // Validate file exists
  if (!fs.existsSync(filePath)) throw new Error(`File not found: ${filePath}`);

  const stats = fs.statSync(filePath);
  if (stats.size === 0) throw new Error('Cannot upload empty file');
  console.log(`Uploading ${filePath} (${stats.size} bytes)...`);

  const provider = new ethers.JsonRpcProvider(process.env.RPC_URL);
  const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);

  // Check wallet balance
  const balance = await provider.getBalance(wallet.address);
  if (balance === 0n) throw new Error('Wallet has no 0G tokens');

  const indexer = new Indexer(process.env.STORAGE_INDEXER!);
  const file = await ZgFile.fromFilePath(filePath);

  try {
    console.log('Generating Merkle tree...');
    const [tree, err] = await file.merkleTree();
    if (err) throw new Error(`Merkle tree generation failed: ${err}`);

    const rootHash = tree!.rootHash();
    console.log('Root hash:', rootHash);

    console.log('Uploading to 0G Storage...');
    const [result, uploadErr] = await indexer.upload(file, process.env.RPC_URL!, wallet);
    if (uploadErr) throw new Error(`Upload failed: ${uploadErr.message}`);
    const txHash = 'txHash' in result ? result.txHash : result.txHashes[0];
    console.log('Upload complete! Tx:', txHash);

    return rootHash;
  } finally {
    await file.close();
  }
}

Anti-Patterns

// BAD: Missing file.close() — memory leak
const file = await ZgFile.fromFilePath('data.txt');
const [tree] = await file.merkleTree();
await indexer.upload(file, process.env.RPC_URL!, wallet);
// file.close() never called!

// BAD: Uploading without Merkle tree
const file = await ZgFile.fromFilePath('data.txt');
await indexer.upload(file, process.env.RPC_URL!, wallet); // May fail or produce invalid upload
await file.close();

// BAD: Hardcoded private key
const wallet = new ethers.Wallet('0xabc123...', provider);

// BAD: Not storing root hash
await indexer.upload(file, process.env.RPC_URL!, wallet); // Root hash lost!

// BAD: Wrong upload signature (missing RPC URL)
await indexer.upload(file, wallet); // TypeError — must pass RPC URL as second arg

Common Errors & Fixes

Related Skills

• Download File — retrieve uploaded files
• Merkle Verification — verify data integrity
• Storage + Chain — on-chain references

References

• Storage Patterns
• Network Config
• Security Patterns
• 0G Storage SDK Docs