Docs

GetCheckpoint - Query Finalized Blockchain State

Retrieve Sui blockchain checkpoints via gRPC to access finalized state, transaction batches, and validator signatures. Essential for applications requiring guaranteed finality with Dwellir's infrastructure.

Access Finalized Blockchain State

The GetCheckpoint method retrieves checkpoint data from Sui's blockchain, providing access to finalized state snapshots that represent guaranteed points of consistency. Checkpoints bundle transactions into atomic units with validator signatures, making them essential for applications requiring verified finality and historical state reconstruction.

Overview

Checkpoints are fundamental to Sui's consensus mechanism. Every ~0.5 seconds, the network creates a new checkpoint containing a batch of executed transactions. Once a checkpoint receives validator signatures exceeding the quorum threshold, it becomes immutable and represents an irrevocable point of finality. Applications use checkpoints to verify transaction inclusion, reconstruct historical state, and monitor network progression.

Why Checkpoints Matter

  • Guaranteed Finality: Checkpoints mark irreversible blockchain state
  • Audit Trail: Complete record of all network state transitions
  • State Snapshots: Point-in-time views of the entire network
  • Validator Proof: Cryptographic signatures from consensus participants
  • Synchronization: Reference points for syncing blockchain state

Method Signature

Service: sui.rpc.v2.LedgerService Method: GetCheckpoint Type: Unary RPC (single request, single response)

Use Cases

1. Transaction Finality Verification

Confirm a transaction reached immutable finality:

TypeScript
interface FinalityStatus {
  isFinalized: boolean;
  checkpointSequence?: string;
  confirmations?: number;
}

async function checkTransactionFinality(
  txDigest: string,
  expectedCheckpoint: string
): Promise<FinalityStatus> {
  const checkpoint = await getCheckpointBySequence(expectedCheckpoint);

  const isIncluded = checkpoint.transactions.includes(txDigest);

  if (isIncluded) {
    // Get latest checkpoint to calculate confirmations
    // (In production, you'd track the latest known checkpoint)
    const latestSequence = parseInt(expectedCheckpoint) + 1000;
    const confirmations = latestSequence - parseInt(checkpoint.sequence_number);

    return {
      isFinalized: true,
      checkpointSequence: checkpoint.sequence_number,
      confirmations: confirmations
    };
  }

  return { isFinalized: false };
}

2. Historical State Reconstruction

Reconstruct blockchain state at specific checkpoint:

TypeScript
interface StateSnapshot {
  sequence: string;
  timestamp: Date;
  totalTransactions: number;
  includedTransactions: string[];
}

async function captureStateSnapshot(
  checkpointSequence: string
): Promise<StateSnapshot> {
  const checkpoint = await getCheckpointBySequence(checkpointSequence);

  return {
    sequence: checkpoint.sequence_number,
    timestamp: new Date(parseInt(checkpoint.timestamp_ms)),
    totalTransactions: parseInt(checkpoint.network_total_transactions),
    includedTransactions: checkpoint.transactions
  };
}

// Create timeline of snapshots
async function createStateTimeline(
  startSequence: string,
  endSequence: string,
  interval: number
): Promise<StateSnapshot[]> {
  const timeline: StateSnapshot[] = [];
  const start = parseInt(startSequence);
  const end = parseInt(endSequence);

  for (let seq = start; seq <= end; seq += interval) {
    const snapshot = await captureStateSnapshot(seq.toString());
    timeline.push(snapshot);
  }

  return timeline;
}

3. Network Performance Monitoring

Track network throughput metrics:

TypeScript
interface NetworkMetrics {
  periodStart: Date;
  periodEnd: Date;
  totalTransactions: number;
  avgTPS: number;
  peakTPS: number;
  checkpointsAnalyzed: number;
}

async function analyzeNetworkPerformance(
  startSequence: string,
  count: number
): Promise<NetworkMetrics> {
  const checkpoints = [];

  for (let i = 0; i < count; i++) {
    const seq = (parseInt(startSequence) + i).toString();
    const checkpoint = await getCheckpointBySequence(seq);
    checkpoints.push(checkpoint);
  }

  const first = checkpoints[0];
  const last = checkpoints[checkpoints.length - 1];

  const totalTxs = parseInt(last.network_total_transactions) -
                   parseInt(first.network_total_transactions);
  const timeSpan = (parseInt(last.timestamp_ms) - parseInt(first.timestamp_ms)) / 1000;
  const avgTPS = totalTxs / timeSpan;

  // Calculate peak TPS from individual checkpoints
  let peakTPS = 0;
  for (let i = 1; i < checkpoints.length; i++) {
    const txCount = checkpoints[i].transactions.length;
    const timeDiff = (parseInt(checkpoints[i].timestamp_ms) -
                     parseInt(checkpoints[i-1].timestamp_ms)) / 1000;
    const tps = txCount / timeDiff;
    peakTPS = Math.max(peakTPS, tps);
  }

  return {
    periodStart: new Date(parseInt(first.timestamp_ms)),
    periodEnd: new Date(parseInt(last.timestamp_ms)),
    totalTransactions: totalTxs,
    avgTPS: avgTPS,
    peakTPS: peakTPS,
    checkpointsAnalyzed: count
  };
}

4. Checkpoint Chain Validation

Verify checkpoint chain integrity:

TypeScript
async function validateCheckpointChain(
  startSequence: string,
  count: number
): Promise<boolean> {
  let previousDigest: string | null = null;

  for (let i = 0; i < count; i++) {
    const seq = (parseInt(startSequence) + i).toString();
    const checkpoint = await getCheckpointBySequence(seq);

    if (i > 0 && checkpoint.previous_digest !== previousDigest) {
      console.error(`Chain break at sequence ${seq}`);
      console.error(`Expected previous: ${previousDigest}`);
      console.error(`Got previous: ${checkpoint.previous_digest}`);
      return false;
    }

    previousDigest = checkpoint.digest;
  }

  console.log(`✓ Validated ${count} checkpoints in chain`);
  return true;
}

Best Practices

1. Cache Checkpoint Data

Checkpoints are immutable once finalized:

TypeScript
const checkpointCache = new Map<string, any>();

async function getCachedCheckpoint(sequence: string): Promise<any> {
  if (checkpointCache.has(sequence)) {
    return checkpointCache.get(sequence);
  }

  const checkpoint = await getCheckpointBySequence(sequence);
  checkpointCache.set(sequence, checkpoint);

  return checkpoint;
}

2. Use Field Masking

Request only required data:

TypeScript
// ✅ Good: Minimal fields
const request = {
  sequence_number: seq,
  read_mask: {
    paths: ['sequence_number', 'transactions']
  }
};

// ❌ Bad: All fields
const request = { sequence_number: seq };

3. Handle Missing Checkpoints

Not all sequence numbers may exist:

TypeScript
async function safeGetCheckpoint(sequence: string): Promise<any | null> {
  try {
    return await getCheckpointBySequence(sequence);
  } catch (error: any) {
    if (error.code === grpc.status.NOT_FOUND) {
      console.log(`Checkpoint ${sequence} not found`);
      return null;
    }
    throw error;
  }
}

Need help with checkpoints? Contact support@dwellir.com or check the gRPC overview.

BatchGetObjects

Retrieve multiple Sui objects in a single gRPC request for maximum efficiency. Learn how to use BatchGetObjects to minimize latency and optimize blockchain data fetching with Dwellir's Sui infrastructure.

GetEpoch

Retrieve Sui epoch information via gRPC including validators, stake distribution, and timing. Essential for staking applications and network monitoring with Dwellir.

On this page

Access Finalized Blockchain State
Overview
Why Checkpoints Matter
Method Signature
Use Cases
1. Transaction Finality Verification
2. Historical State Reconstruction
3. Network Performance Monitoring
4. Checkpoint Chain Validation
Best Practices
1. Cache Checkpoint Data
2. Use Field Masking
3. Handle Missing Checkpoints
Related Methods