On-Chain Rollup State

This method returns the current on-chain state, representing the latest database snapshot that has been successfully published and confirmed on the blockchain. This state serves as the authoritative, immutable reference point for database integrity.

State information includes:

• Current step: The rollup sequence number representing blockchain state
• Merkle roots: Cryptographic fingerprints of old and new database states
• Rollup status: Current blockchain synchronization state
  • Updated: On-chain state matches off-chain state (fully synchronized)
  • Updating: Rollup transaction is pending blockchain confirmation
  • Outdated: Off-chain operations exist that haven't been rolled up
  • Failed: Last rollup transaction failed and needs attention
  • Unavailable: Database not deployed or no rollup history
• Rollup difference: Number of off-chain operations not yet rolled up (offChainStep - onChainStep)
• Last success timestamp: When the most recent rollup was confirmed

Use cases:

• State verification: Confirm database integrity against blockchain
• Synchronization monitoring: Track how current your on-chain state is
• Audit compliance: Provide immutable proof of database state
• Recovery planning: Identify the last known good blockchain state

State Lag

On-chain state may lag behind off-chain operations. Use rollUpOffChainState() to see the most current database state before rollup.

Status workflow: Check this state → Compare with rollUpOffChainState() → If outdated, run rollUpOnChainStart()

Read-Only Operation

This operation only reads the current blockchain state and does not require gas fees.

Definition

await zkdb
  .db(databaseName: string)
  .rollUpOnChainState(): Promise<TRollupOnChainStateResponse>;

Parameters

• None

Returns

• Promise<TRollupOnChainStateResponse>: Returns the current blockchain-verified database state, or null if no rollup has been performed yet. This represents the last successfully committed state on the blockchain.

type TRollupOnChainStateResponse = {
  step: bigint;
  merkleRoot: string;
  txHash: string;
  blockHeight: number;
  timestamp: string;
} | null;

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 state = await dbTest.rollUpOnChainState();
console.log('On-chain state:', state);

await zkdb.auth.signOut();

Result:

{
  "step": 10,
  "merkleRoot": "0x123...",
  "txHash": "0x456...",
  "blockHeight": 12345,
  "timestamp": "2025-01-01T00:00:00.000Z"
}