0gfoundation/skills/storage/merkle-verification

Merkle Verification

Metadata

• Category: storage
• SDK: @0glabs/0g-ts-sdk ^0.3.3
• Activation Triggers: "verify file", "merkle proof", "data integrity", "root hash", "check file"

Purpose

Compute root hashes and verify data integrity for files stored on 0G Storage. Uses Merkle tree proofs to cryptographically verify that downloaded data matches what was originally uploaded.

Prerequisites

• Node.js >= 18
• @0glabs/0g-ts-sdk installed

Quick Workflow

1. Create a ZgFile from the file to verify
2. Generate the Merkle tree
3. Extract the root hash
4. Compare against the expected root hash
5. Close the file handle

Core Rules

ALWAYS

• Close file handles after computing the Merkle tree
• Use verified downloads (true flag) for automatic verification
• Store root hashes securely — they are your proof of data identity

NEVER

• Skip verification for production data
• Trust a root hash without verifying the source

Code Examples

Compute Root Hash

import { ZgFile } from '@0glabs/0g-ts-sdk';

async function computeRootHash(filePath: string): Promise<string> {
  const file = await ZgFile.fromFilePath(filePath);
  try {
    const [tree, err] = await file.merkleTree();
    if (err) throw new Error(`Merkle tree error: ${err}`);
    return tree.rootHash();
  } finally {
    await file.close();
  }
}

// Usage
const hash = await computeRootHash('./my-file.pdf');
console.log('Root hash:', hash);

Verify File Integrity

import { ZgFile } from '@0glabs/0g-ts-sdk';

async function verifyFile(filePath: string, expectedHash: string): Promise<boolean> {
  const file = await ZgFile.fromFilePath(filePath);
  try {
    const [tree, err] = await file.merkleTree();
    if (err) return false;

    const actualHash = tree.rootHash();
    const isValid = actualHash === expectedHash;

    console.log(`Expected: ${expectedHash}`);
    console.log(`Actual:   ${actualHash}`);
    console.log(`Valid:    ${isValid}`);

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

// Usage
const isValid = await verifyFile('./downloaded-file.pdf', '0xabc123...');
if (!isValid) {
  console.error('File integrity check failed!');
}

Verified Download (Automatic Verification)

import { Indexer } from '@0glabs/0g-ts-sdk';

async function downloadAndVerify(rootHash: string, outputPath: string): Promise<void> {
  const indexer = new Indexer(process.env.STORAGE_INDEXER!);

  // The third parameter enables automatic Merkle proof verification
  // Throws an error if verification fails
  await indexer.download(rootHash, outputPath, true);
  console.log('Downloaded and verified successfully');
}

Compare Two Files

async function filesMatch(filePath1: string, filePath2: string): Promise<boolean> {
  const hash1 = await computeRootHash(filePath1);
  const hash2 = await computeRootHash(filePath2);
  return hash1 === hash2;
}

Anti-Patterns

// BAD: Not closing file handle
const file = await ZgFile.fromFilePath('data.txt');
const [tree] = await file.merkleTree();
const hash = tree.rootHash();
// file.close() never called — memory leak!

// BAD: Unverified download in production
await indexer.download(rootHash, outputPath, false); // No verification!

// BAD: Comparing hashes case-sensitively when format may differ
if (hash1 === hash2) // Could fail if one is checksummed

Common Errors & Fixes

| Error | Cause | Fix | | --------------------- | ----------------------- | --------------------------- | | Merkle tree error | Empty or corrupted file | Verify file has content | | Verification failed | Data was tampered with | Re-download from 0G Storage | | ENOENT | File path doesn't exist | Check file path |

Related Skills

• Upload File — generates root hash during upload
• Download File — can auto-verify during download

References

• Storage Patterns
• Security Patterns