Skip to main content

Off-Chain Rollup History

This method retrieves the detailed history of off-chain rollup operations that occur within the zkDatabase system. Off-chain rollups process individual document operations (insert, update, drop) immediately while generating cryptographic proofs, providing instant finality without blockchain costs.

Off-chain operation tracking:

  • Document operations: Individual insert, update, and drop operations
  • Collection context: Which collection each operation affects
  • Proof generation: Status of zero-knowledge proof creation for each operation
  • State progression: Merkle root changes for each document modification
  • Batch preparation: Operations ready for on-chain rollup aggregation

Key benefits:

  • Immediate feedback: Know instantly if operations succeeded or failed
  • Cost efficiency: No gas fees for individual document operations
  • High throughput: Process thousands of operations per second
  • Cryptographic security: Every operation is cryptographically verified
Monitoring Strategy

Use this history to monitor off-chain operation health before initiating on-chain rollups. Failed off-chain operations should be resolved with proverRetry() before rollup.

Workflow: Check this → Fix with proverRetry() → Monitor proverStatus() → Start rollUpOnChainStart()

Gas-Free Operations

Off-chain rollups do not require gas fees and provide instant finality within the zkDatabase system.

Definition​

await zkdb
  .db(databaseName: string)
  .rollUpOffChainHistory(pagination?: TPagination): Promise<TRollupOffChainHistoryResponse>;

Parameters​

  • pagination (TPagination, optional): { limit: number; offset: number }.

Returns​

  • Promise<TRollupOffChainHistoryResponse>: Returns a paginated chronological record of all off-chain operations that have been processed and prepared for rollup. This includes document operations (insert, update, delete) with their sequence numbers, timestamps, and proof generation status, allowing you to track which operations are ready for blockchain publication.
type TRollupOffChainHistoryResponse = {
  total: number;
  offset: number;
  data: Array<{
    sequenceNumber: bigint;
    merkleRootOld: string;
    merkleRootNew: string;
    timestamp: string;
  }>;
};

Example​

import { ZkDatabase } from 'zkdb';

const zkdb = await ZkDatabase.connect({
  userName: "chiro-user",
  privateKey: "EKFTciRxyxshZjimay9sktsn7v5PvmC5zPq7q4JnitHUytxUVnFP",
  environment: "node",
  // This URL is for test environment
  url: "https://api.zkdatabase.org/graphql",
});

await zkdb.auth.signIn();

const dbTest = zkdb.db('zkdb_test');
const history = await dbTest.rollUpOffChainHistory({ limit: 5, offset: 0 });
console.log('Off-chain history:', history);

await zkdb.auth.signOut();

Result:​

{
  "total": 5,
  "offset": 0,
  "data": [
    {
      "sequenceNumber": 10,
      "merkleRootOld": "0x123...",
      "merkleRootNew": "0x456...",
      "timestamp": "2025-01-01T00:00:00.000Z"
    }
  ]
}