Skip to main content

sui_getCheckpoint

Retrieves detailed information about a specific checkpoint on the Sui blockchain, including transactions, network metrics, and consensus data.

Overview​

The sui_getCheckpoint method provides comprehensive information about Sui network checkpoints. Checkpoints represent finalized batches of transactions that have been agreed upon by the network consensus. This method is essential for blockchain analytics, network monitoring, historical data analysis, and understanding the state progression of the Sui blockchain.

Parameters​

ParameterTypeRequiredDescription
idstringYesCheckpoint identifier - can be checkpoint sequence number or digest

Checkpoint Identifier Types​

You can query checkpoints using either:

  • Sequence Number: String representation of the checkpoint number (e.g., "1234567")
  • Digest: Checkpoint content hash (e.g., "0x123abc...")

Returns​

Returns a comprehensive checkpoint object containing all checkpoint information.

FieldTypeDescription
epochstringEpoch number containing this checkpoint
sequenceNumberstringSequential checkpoint number
digeststringContent hash of the checkpoint
networkTotalTransactionsstringTotal transactions processed by the network at this checkpoint
previousDigeststringDigest of the previous checkpoint
timestampMsstringCheckpoint timestamp in milliseconds
transactionsarrayArray of transaction digests included in this checkpoint
checkpointCommitmentsarrayValidator commitments for this checkpoint
validatorSignaturestringAggregated validator signature
endOfEpochDataobjectEnd-of-epoch information (if applicable)

End of Epoch Data​

When a checkpoint marks the end of an epoch, additional information is included:

FieldTypeDescription
nextEpochCommitteearrayValidator committee for the next epoch
nextEpochProtocolVersionstringProtocol version for the next epoch
epochCommitmentsarrayEpoch-level commitments

Code Examples​

# Get checkpoint by sequence number
curl -X POST https://sui-mainnet.dwellir.com/YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "sui_getCheckpoint",
    "params": [
      "1234567"
    ],
    "id": 1
  }'

# Get checkpoint by digest
curl -X POST https://sui-mainnet.dwellir.com/YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "sui_getCheckpoint",
    "params": [
      "0x8c123c0b23c456789abcdef0123456789abcdef0123456789abcdef0123456789a"
    ],
    "id": 1
  }'

# Get latest checkpoint (using highest known sequence number)
curl -X POST https://sui-mainnet.dwellir.com/YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "sui_getLatestCheckpointSequenceNumber",
    "params": [],
    "id": 1
  }'

# Then use that number to get the checkpoint
curl -X POST https://sui-mainnet.dwellir.com/YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "sui_getCheckpoint",
    "params": [
      "LATEST_SEQUENCE_NUMBER"
    ],
    "id": 2
  }'

Response Example​

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "epoch": "251",
    "sequenceNumber": "18523456",
    "digest": "0x8c123c0b23c456789abcdef0123456789abcdef0123456789abcdef0123456789a",
    "networkTotalTransactions": "450123789",
    "previousDigest": "0x7d456e78f90123456789abcdef0123456789abcdef0123456789abcdef012345",
    "timestampMs": "1703097600000",
    "transactions": [
      "0x9f234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef0",
      "0xa1b2c3d4e5f6789012345678901234567890123456789012345678901234567890",
      "0xb2c3d4e5f6789012345678901234567890123456789012345678901234567890ab"
    ],
    "checkpointCommitments": [],
    "validatorSignature": "0xValidatorSignatureHere123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0",
    "endOfEpochData": null
  }
}

End of Epoch Checkpoint Example​

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "epoch": "251",
    "sequenceNumber": "18525000",
    "digest": "0x1a2b3c4d5e6f789012345678901234567890123456789012345678901234567890",
    "networkTotalTransactions": "450125000",
    "previousDigest": "0x8c123c0b23c456789abcdef0123456789abcdef0123456789abcdef0123456789a",
    "timestampMs": "1703100000000",
    "transactions": [
      "0xe1f2a3b4c5d6789012345678901234567890123456789012345678901234567890"
    ],
    "checkpointCommitments": [],
    "validatorSignature": "0xEndOfEpochValidatorSignature123456789abcdef0123456789abcdef0123456789abcdef0",
    "endOfEpochData": {
      "nextEpochCommittee": [
        {
          "authorityName": "0x1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef01",
          "stakeUnit": "100000000000",
          "networkAddress": "/ip4/192.168.1.1/tcp/8080",
          "primaryAddress": "/ip4/192.168.1.1/tcp/8081"
        }
      ],
      "nextEpochProtocolVersion": "1.0.0",
      "epochCommitments": []
    }
  }
}

Common Use Cases​

1. Network Health Monitoring​

async function monitorNetworkHealth() {
  const monitor = new CheckpointMonitor(client);
  
  // Set custom thresholds for alerts
  monitor.thresholds = {
    maxTransactionsPerCheckpoint: 5000,
    minTimeBetweenCheckpoints: 2000,
    maxTimeBetweenCheckpoints: 15000
  };
  
  monitor.onNewCheckpoint = (checkpoint) => {
    const txCount = checkpoint.transactions.length;
    const timestamp = new Date(parseInt(checkpoint.timestampMs));
    
    console.log(`📊 Network Status:`);
    console.log(`  Checkpoint: ${checkpoint.sequenceNumber}`);
    console.log(`  TPS: ${txCount} transactions`);
    console.log(`  Time: ${timestamp.toLocaleTimeString()}`);
  };
  
  await monitor.startMonitoring(5000); // Check every 5 seconds
}

2. Transaction Throughput Analysis​

async function analyzeThroughput(checkpointCount = 100) {
  const metricsTracker = new NetworkMetricsTracker(client);
  const metrics = await metricsTracker.trackMetrics(checkpointCount);
  
  const throughput = metrics.transactionThroughput;
  
  const analysis = {
    averageTPS: metrics.averageTPS,
    peakTPS: Math.max(...throughput.map(t => t.tps)),
    minTPS: Math.min(...throughput.map(t => t.tps)),
    medianTPS: throughput.map(t => t.tps).sort()[Math.floor(throughput.length / 2)],
    tpsStandardDeviation: calculateStandardDeviation(throughput.map(t => t.tps))
  };
  
  return analysis;
}

3. Epoch Transition Tracking​

async function trackEpochTransitions(epochCount = 5) {
  const latestCheckpoint = await getLatestCheckpoint();
  const currentEpoch = parseInt(latestCheckpoint.epoch);
  
  const epochTransitions = [];
  
  for (let epoch = currentEpoch - epochCount; epoch <= currentEpoch; epoch++) {
    // Find last checkpoint of epoch (simplified search)
    let foundTransition = false;
    let checkpointSeq = parseInt(latestCheckpoint.sequenceNumber) - (currentEpoch - epoch) * 1000;
    
    for (let i = 0; i < 2000 && !foundTransition; i++) {
      const checkpoint = await getCheckpointBySequence(checkpointSeq + i);
      
      if (checkpoint && checkpoint.endOfEpochData) {
        epochTransitions.push({
          epoch: checkpoint.epoch,
          checkpoint: checkpoint.sequenceNumber,
          timestamp: checkpoint.timestampMs,
          nextEpochCommitteeSize: checkpoint.endOfEpochData.nextEpochCommittee?.length || 0
        });
        foundTransition = true;
      }
    }
  }
  
  return epochTransitions;
}

4. Data Availability Verification​

async function verifyDataAvailability(startSeq, endSeq) {
  const verification = {
    requestedRange: { start: startSeq, end: endSeq },
    availableCheckpoints: [],
    missingCheckpoints: [],
    consecutiveRanges: [],
    availabilityPercentage: 0
  };
  
  let currentRange = null;
  
  for (let seq = startSeq; seq <= endSeq; seq++) {
    const checkpoint = await getCheckpointBySequence(seq);
    
    if (checkpoint) {
      verification.availableCheckpoints.push(seq);
      
      if (currentRange) {
        currentRange.end = seq;
      } else {
        currentRange = { start: seq, end: seq };
      }
    } else {
      verification.missingCheckpoints.push(seq);
      
      if (currentRange) {
        verification.consecutiveRanges.push(currentRange);
        currentRange = null;
      }
    }
  }
  
  if (currentRange) {
    verification.consecutiveRanges.push(currentRange);
  }
  
  verification.availabilityPercentage = 
    (verification.availableCheckpoints.length / (endSeq - startSeq + 1)) * 100;
  
  return verification;
}

Best Practices​

1. Efficient Checkpoint Queries​

// Cache frequently accessed checkpoints
const checkpointCache = new Map();

async function getCachedCheckpoint(id) {
  if (checkpointCache.has(id)) {
    return checkpointCache.get(id);
  }
  
  const checkpoint = await client.getCheckpoint({ id });
  
  if (checkpoint) {
    checkpointCache.set(id, checkpoint);
    
    // Limit cache size
    if (checkpointCache.size > 1000) {
      const firstKey = checkpointCache.keys().next().value;
      checkpointCache.delete(firstKey);
    }
  }
  
  return checkpoint;
}

2. Batch Processing​

// Process checkpoints in batches to avoid overwhelming the RPC
async function processCheckpointRange(start, end, batchSize = 10) {
  const results = [];
  
  for (let i = start; i <= end; i += batchSize) {
    const batchEnd = Math.min(i + batchSize - 1, end);
    
    const batchPromises = [];
    for (let j = i; j <= batchEnd; j++) {
      batchPromises.push(getCheckpointBySequence(j));
    }
    
    const batchResults = await Promise.allSettled(batchPromises);
    results.push(...batchResults.map(r => r.value).filter(Boolean));
    
    // Small delay between batches
    if (batchEnd < end) {
      await new Promise(resolve => setTimeout(resolve, 200));
    }
  }
  
  return results;
}

3. Error Handling and Retry Logic​

async function robustGetCheckpoint(id, retries = 3) {
  for (let attempt = 1; attempt <= retries; attempt++) {
    try {
      const checkpoint = await client.getCheckpoint({ id });
      return { success: true, data: checkpoint };
    } catch (error) {
      console.warn(`Attempt ${attempt} failed for checkpoint ${id}:`, error.message);
      
      if (attempt === retries) {
        return { success: false, error: error.message };
      }
      
      // Exponential backoff
      await new Promise(resolve => 
        setTimeout(resolve, Math.pow(2, attempt - 1) * 1000)
      );
    }
  }
}

Performance Considerations​

  1. Rate Limiting: Implement delays between requests to avoid overwhelming the RPC endpoint
  2. Caching: Cache checkpoint data as it's immutable once finalized
  3. Batch Processing: Process checkpoints in batches rather than individual requests
  4. Selective Queries: Only fetch the checkpoint data you need
  5. Parallel Processing: Use Promise.all for independent checkpoint queries

Error Handling​

async function handleCheckpointErrors(id) {
  try {
    const checkpoint = await client.getCheckpoint({ id });
    return { success: true, data: checkpoint };
  } catch (error) {
    if (error.message.includes('not found')) {
      return { 
        success: false, 
        error: 'Checkpoint not found',
        notFound: true 
      };
    }
    
    if (error.message.includes('timeout')) {
      return { 
        success: false, 
        error: 'Request timeout',
        retry: true 
      };
    }
    
    return { 
      success: false, 
      error: error.message 
    };
  }
}

Notes​

  • Checkpoints are immutable once finalized by consensus
  • Sequential numbering ensures no gaps in the checkpoint sequence
  • End of epoch checkpoints contain additional validator committee information
  • Timestamps are in milliseconds since Unix epoch
  • Transaction digests in checkpoints can be used to fetch detailed transaction data
  • Validator signatures provide cryptographic proof of consensus

Need help? Contact our support team or check the Sui documentation.