Ledger State Deltas

← Back to Algod Client

Description

This example demonstrates how to retrieve ledger state deltas using:

• ledgerStateDelta(round) - Get state changes for a specific round
• ledgerStateDeltaForTransactionGroup(txId) - Get deltas for a specific transaction group
• transactionGroupLedgerStateDeltasForRound(round) - Get all transaction group deltas in a round State deltas show what changed in the ledger (accounts, balances, apps, assets) between rounds. Note: These endpoints may require node configuration to enable (EnableDeveloperAPI=true).

Prerequisites

• LocalNet running (via algokit localnet start)

Run This Example

From the repository root:

cd examples
npm run example algod_client/14-state-deltas.ts

Code

View source on GitHub

14-state-deltas.ts

/**
 * Example: Ledger State Deltas
 *
 * This example demonstrates how to retrieve ledger state deltas using:
 * - ledgerStateDelta(round) - Get state changes for a specific round
 * - ledgerStateDeltaForTransactionGroup(txId) - Get deltas for a specific transaction group
 * - transactionGroupLedgerStateDeltasForRound(round) - Get all transaction group deltas in a round
 *
 * State deltas show what changed in the ledger (accounts, balances, apps, assets) between rounds.
 *
 * Note: These endpoints may require node configuration to enable (EnableDeveloperAPI=true).
 *
 * Prerequisites:
 * - LocalNet running (via `algokit localnet start`)
 */

import { algo } from '@algorandfoundation/algokit-utils';
import type {
  LedgerStateDelta,
  TransactionGroupLedgerStateDeltasForRoundResponse,
} from '@algorandfoundation/algokit-utils/algod-client';
import {
  createAlgodClient,
  createAlgorandClient,
  formatMicroAlgo,
  printError,
  printHeader,
  printInfo,
  printStep,
  printSuccess,
  shortenAddress,
} from '../shared/utils.js';

async function main() {
  printHeader('Ledger State Deltas Example');

  // Create clients
  const algod = createAlgodClient();
  const algorand = createAlgorandClient();

  // =========================================================================
  // Step 1: Set up accounts and submit a transaction to create state changes
  // =========================================================================
  printStep(1, 'Setting up accounts and submitting a payment transaction');

  // Get a funded account from LocalNet (the dispenser)
  const sender = await algorand.account.dispenserFromEnvironment();
  printInfo(`Sender address: ${shortenAddress(sender.addr.toString())}`);

  // Get sender initial balance
  const senderInfoBefore = await algod.accountInformation(sender.addr.toString());
  printInfo(`Sender initial balance: ${formatMicroAlgo(senderInfoBefore.amount)}`);

  // Create a new random account as receiver
  const receiver = algorand.account.random();
  printInfo(`Receiver address: ${shortenAddress(receiver.addr.toString())}`);

  // Submit a payment transaction - this will create state changes (balance changes)
  const paymentAmount = algo(5);
  printInfo(`Sending ${paymentAmount.algo} ALGO to receiver...`);

  const result = await algorand.send.payment({
    sender: sender.addr,
    receiver: receiver.addr,
    amount: paymentAmount,
  });

  const txId = result.txIds[0];
  const confirmedRound = result.confirmation.confirmedRound!;

  printSuccess(`Transaction confirmed!`);
  printInfo(`Transaction ID: ${txId}`);
  printInfo(`Confirmed in round: ${confirmedRound.toLocaleString('en-US')}`);
  printInfo('');

  // Get balances after transaction
  const senderInfoAfter = await algod.accountInformation(sender.addr.toString());
  const receiverInfo = await algod.accountInformation(receiver.addr.toString());

  printInfo(`Sender balance after: ${formatMicroAlgo(senderInfoAfter.amount)}`);
  printInfo(`Receiver balance after: ${formatMicroAlgo(receiverInfo.amount)}`);
  printInfo('');

  // =========================================================================
  // Step 2: Demonstrate ledgerStateDelta(round)
  // =========================================================================
  printStep(2, 'Getting ledger state delta for a round using ledgerStateDelta(round)');

  printInfo('ledgerStateDelta(round) returns all state changes that occurred in a specific round.');
  printInfo('This includes account balance changes, app state changes, and more.');
  printInfo('');

  try {
    const stateDelta = await algod.ledgerStateDelta(confirmedRound);
    printSuccess('Successfully retrieved state delta for the round!');
    printInfo('');

    displayStateDelta(stateDelta, 'ledgerStateDelta');
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : String(error);
    if (
      errorMessage.includes('not supported') ||
      errorMessage.includes('not enabled') ||
      errorMessage.includes('404')
    ) {
      printError('ledgerStateDelta endpoint may not be enabled on this node.');
      printInfo(
        'Node configuration may need EnableDeveloperAPI=true or specific delta tracking settings.',
      );
    } else {
      printError(`Error getting state delta: ${errorMessage}`);
    }
    printInfo('');
  }

  // =========================================================================
  // Step 3: Demonstrate ledgerStateDeltaForTransactionGroup(txId)
  // =========================================================================
  printStep(
    3,
    'Getting state delta for a specific transaction group using ledgerStateDeltaForTransactionGroup(txId)',
  );

  printInfo('ledgerStateDeltaForTransactionGroup(txId) returns the state changes');
  printInfo(
    'caused by a specific transaction group, identified by any transaction ID in the group.',
  );
  printInfo('');

  try {
    const txGroupDelta = await algod.ledgerStateDeltaForTransactionGroup(txId);
    printSuccess('Successfully retrieved state delta for the transaction group!');
    printInfo('');

    displayStateDelta(txGroupDelta, 'ledgerStateDeltaForTransactionGroup');
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : String(error);
    if (errorMessage.includes('tracer') || errorMessage.includes('501')) {
      printError('ledgerStateDeltaForTransactionGroup requires delta tracking to be enabled.');
      printInfo(
        'This endpoint needs EnableDeveloperAPI=true AND EnableTxnEvalTracer=true in node config.',
      );
      printInfo('On LocalNet, this may require custom configuration.');
    } else if (
      errorMessage.includes('not supported') ||
      errorMessage.includes('not enabled') ||
      errorMessage.includes('404')
    ) {
      printError('ledgerStateDeltaForTransactionGroup endpoint may not be enabled on this node.');
    } else {
      printError(`Error getting transaction group delta: ${errorMessage}`);
    }
    printInfo('');
  }

  // =========================================================================
  // Step 4: Demonstrate transactionGroupLedgerStateDeltasForRound(round)
  // =========================================================================
  printStep(
    4,
    'Getting all transaction group deltas for a round using transactionGroupLedgerStateDeltasForRound(round)',
  );

  printInfo('transactionGroupLedgerStateDeltasForRound(round) returns deltas for ALL');
  printInfo('transaction groups that were included in a specific round.');
  printInfo('Each entry includes the delta and the transaction IDs in that group.');
  printInfo('');

  try {
    const roundDeltas = await algod.transactionGroupLedgerStateDeltasForRound(confirmedRound);
    printSuccess('Successfully retrieved all transaction group deltas for the round!');
    printInfo('');

    displayRoundDeltas(roundDeltas);
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : String(error);
    if (errorMessage.includes('tracer') || errorMessage.includes('501')) {
      printError(
        'transactionGroupLedgerStateDeltasForRound requires delta tracking to be enabled.',
      );
      printInfo(
        'This endpoint needs EnableDeveloperAPI=true AND EnableTxnEvalTracer=true in node config.',
      );
      printInfo('On LocalNet, this may require custom configuration.');
    } else if (
      errorMessage.includes('not supported') ||
      errorMessage.includes('not enabled') ||
      errorMessage.includes('404')
    ) {
      printError(
        'transactionGroupLedgerStateDeltasForRound endpoint may not be enabled on this node.',
      );
    } else {
      printError(`Error getting round deltas: ${errorMessage}`);
    }
    printInfo('');
  }

  // =========================================================================
  // Step 5: Submit more transactions to see different state changes
  // =========================================================================
  printStep(5, 'Submitting additional transactions to demonstrate more state changes');

  // Create another account and do a multi-transaction round
  const receiver2 = algorand.account.random();
  printInfo(`Created second receiver: ${shortenAddress(receiver2.addr.toString())}`);

  // Send payments to create more activity
  const result2 = await algorand.send.payment({
    sender: sender.addr,
    receiver: receiver2.addr,
    amount: algo(3),
  });

  const confirmedRound2 = result2.confirmation.confirmedRound!;
  printSuccess(`Second transaction confirmed in round ${confirmedRound2.toLocaleString('en-US')}`);
  printInfo('');

  // Try to get deltas for this new round
  try {
    const roundDeltas2 = await algod.transactionGroupLedgerStateDeltasForRound(confirmedRound2);
    printSuccess(
      `Found ${roundDeltas2.deltas.length} transaction group(s) in round ${confirmedRound2.toLocaleString('en-US')}`,
    );

    for (let i = 0; i < roundDeltas2.deltas.length; i++) {
      const groupDelta = roundDeltas2.deltas[i];
      printInfo(`\n  Transaction Group ${i + 1}:`);
      printInfo(`    Transaction IDs: ${groupDelta.ids.length}`);
      for (const id of groupDelta.ids) {
        printInfo(`      - ${id}`);
      }

      // Show account changes summary
      const accounts = groupDelta.delta.accounts;
      if (accounts.accounts && accounts.accounts.length > 0) {
        printInfo(`    Accounts modified: ${accounts.accounts.length}`);
      }
    }
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : String(error);
    if (errorMessage.includes('tracer') || errorMessage.includes('501')) {
      printInfo('(Skipped - requires EnableTxnEvalTracer node configuration)');
    } else {
      printError(`Could not get deltas: ${errorMessage}`);
    }
  }
  printInfo('');

  // =========================================================================
  // Summary
  // =========================================================================
  printHeader('Summary');

  printInfo('This example demonstrated three ways to get ledger state deltas:');
  printInfo('');
  printInfo('1. ledgerStateDelta(round):');
  printInfo('   - Returns ALL state changes for a specific round');
  printInfo('   - Includes: account balances, app state, asset holdings');
  printInfo('   - LedgerStateDelta contains: accounts, block, totals, kvMods, txIds, creatables');
  printInfo('');
  printInfo('2. ledgerStateDeltaForTransactionGroup(txId):');
  printInfo('   - Returns state changes for a SPECIFIC transaction group');
  printInfo('   - Accepts any transaction ID from the group');
  printInfo('   - Useful for tracking changes from your transactions');
  printInfo('');
  printInfo('3. transactionGroupLedgerStateDeltasForRound(round):');
  printInfo('   - Returns deltas for ALL transaction groups in a round');
  printInfo('   - TransactionGroupLedgerStateDeltasForRoundResponse has deltas array');
  printInfo('   - Each LedgerStateDeltaForTransactionGroup has: delta, ids (transaction IDs)');
  printInfo('');
  printInfo('State Delta Structure (LedgerStateDelta):');
  printInfo('  accounts: LedgerAccountDeltas');
  printInfo('    - accounts?: LedgerBalanceRecord[] (address + microAlgos)');
  printInfo('    - appResources?: LedgerAppResourceRecord[]');
  printInfo('    - assetResources?: LedgerAssetResourceRecord[]');
  printInfo('  block: Block (block header information)');
  printInfo('  totals: LedgerAccountTotals (online, offline, notParticipating algo counts)');
  printInfo('  stateProofNext: bigint');
  printInfo('  prevTimestamp: bigint');
  printInfo('  kvMods?: Map<Uint8Array, LedgerKvValueDelta> (key-value store changes)');
  printInfo('  txIds?: Map<Uint8Array, LedgerIncludedTransactions>');
  printInfo('  creatables?: Map<number, LedgerModifiedCreatable>');
  printInfo('');
  printInfo('Note: Node configuration requirements:');
  printInfo('  - ledgerStateDelta(round) - Works with default LocalNet configuration');
  printInfo('  - ledgerStateDeltaForTransactionGroup(txId) - Requires EnableTxnEvalTracer=true');
  printInfo(
    '  - transactionGroupLedgerStateDeltasForRound(round) - Requires EnableTxnEvalTracer=true',
  );
  printInfo('  - All endpoints need EnableDeveloperAPI=true (enabled by default on LocalNet)');
}

/**
 * Display details from a LedgerStateDelta
 */
function displayStateDelta(delta: LedgerStateDelta, source: string): void {
  printInfo(`State Delta from ${source}:`);
  printInfo('');

  // Block information
  printInfo('  Block Information:');
  printInfo(`    Round: ${delta.block.header.round.toLocaleString('en-US')}`);
  printInfo(
    `    Timestamp: ${new Date(Number(delta.block.header.timestamp) * 1000).toISOString()}`,
  );
  printInfo(`    Previous timestamp: ${delta.prevTimestamp.toLocaleString('en-US')}`);
  if (delta.block.header.proposer) {
    printInfo(`    Proposer: ${shortenAddress(delta.block.header.proposer.toString())}`);
  }
  printInfo('');

  // Account changes
  printInfo('  Account Changes (LedgerAccountDeltas):');
  const accounts = delta.accounts;

  if (accounts.accounts && accounts.accounts.length > 0) {
    printInfo(`    Modified accounts: ${accounts.accounts.length}`);
    for (const record of accounts.accounts.slice(0, 5)) {
      // Show first 5
      const baseData = record.accountData.accountBaseData;
      printInfo(`      - ${shortenAddress(record.address.toString())}`);
      printInfo(`        Balance: ${formatMicroAlgo(baseData.microAlgos)}`);
      printInfo(`        Status: ${getAccountStatus(baseData.status)}`);
    }
    if (accounts.accounts.length > 5) {
      printInfo(`      ... and ${accounts.accounts.length - 5} more`);
    }
  } else {
    printInfo('    No account balance changes');
  }

  if (accounts.appResources && accounts.appResources.length > 0) {
    printInfo(`    App resources modified: ${accounts.appResources.length}`);
    for (const app of accounts.appResources.slice(0, 3)) {
      printInfo(`      - App ${app.appId}: ${app.params.deleted ? 'DELETED' : 'MODIFIED'}`);
    }
  }

  if (accounts.assetResources && accounts.assetResources.length > 0) {
    printInfo(`    Asset resources modified: ${accounts.assetResources.length}`);
    for (const asset of accounts.assetResources.slice(0, 3)) {
      printInfo(`      - Asset ${asset.assetId}: ${asset.params.deleted ? 'DELETED' : 'MODIFIED'}`);
    }
  }
  printInfo('');

  // Totals
  printInfo('  Account Totals (LedgerAccountTotals):');
  printInfo(`    Online money: ${formatMicroAlgo(delta.totals.online.money)}`);
  printInfo(`    Offline money: ${formatMicroAlgo(delta.totals.offline.money)}`);
  printInfo(`    Not participating: ${formatMicroAlgo(delta.totals.notParticipating.money)}`);
  printInfo(`    Rewards level: ${delta.totals.rewardsLevel.toLocaleString('en-US')}`);
  printInfo('');

  // KV mods
  if (delta.kvMods && delta.kvMods.size > 0) {
    printInfo(`  KV Store Modifications: ${delta.kvMods.size} keys changed`);
  }

  // Transaction IDs
  if (delta.txIds && delta.txIds.size > 0) {
    printInfo(`  Transactions included: ${delta.txIds.size}`);
  }

  // Creatables
  if (delta.creatables && delta.creatables.size > 0) {
    printInfo(`  Creatables modified: ${delta.creatables.size}`);
    delta.creatables.forEach((creatable, id) => {
      const type = creatable.creatableType === 0 ? 'Asset' : 'Application';
      const action = creatable.created ? 'CREATED' : 'DELETED';
      printInfo(
        `    - ${type} ${id}: ${action} by ${shortenAddress(creatable.creator.toString())}`,
      );
    });
  }
  printInfo('');
}

/**
 * Display details from a TransactionGroupLedgerStateDeltasForRoundResponse
 */
function displayRoundDeltas(response: TransactionGroupLedgerStateDeltasForRoundResponse): void {
  printInfo('Transaction Group Deltas for Round:');
  printInfo(`  Total transaction groups: ${response.deltas.length}`);
  printInfo('');

  for (let i = 0; i < response.deltas.length; i++) {
    const groupDelta = response.deltas[i];
    printInfo(`  Group ${i + 1}:`);
    printInfo(`    Transaction IDs in group: ${groupDelta.ids.length}`);

    for (const txId of groupDelta.ids) {
      printInfo(`      - ${txId}`);
    }

    // Summary of delta
    const accounts = groupDelta.delta.accounts;
    const modifiedCount = accounts.accounts?.length ?? 0;
    const appCount = accounts.appResources?.length ?? 0;
    const assetCount = accounts.assetResources?.length ?? 0;

    printInfo(`    State changes:`);
    printInfo(`      - Accounts modified: ${modifiedCount}`);
    if (appCount > 0) {
      printInfo(`      - App resources: ${appCount}`);
    }
    if (assetCount > 0) {
      printInfo(`      - Asset resources: ${assetCount}`);
    }
    printInfo('');
  }
}

/**
 * Convert an account status number to a string
 */
function getAccountStatus(status: number): string {
  switch (status) {
    case 0:
      return 'Offline';
    case 1:
      return 'Online';
    case 2:
      return 'NotParticipating';
    default:
      return `Unknown (${status})`;
  }
}

main().catch(error => {
  console.error('Fatal error:', error);
  process.exit(1);
});

---

Other examples in Algod Client

• Node Health and Status
• Version and Genesis Information
• Ledger Supply Information
• Account Information
• Transaction Parameters
• Send and Confirm Transaction
• Pending Transactions
• Block Data
• Asset Information
• Application Information
• Application Boxes
• TEAL Compile and Disassemble
• Transaction Simulation
• Ledger State Deltas
• Transaction Proof
• Light Block Header Proof
• State Proof
• DevMode Timestamp Offset
• Sync Round Management