Skip to content
light theme Algorand Developer Portal dark theme Algorand Developer Portal Algorand Developer Portal

Transaction Proof

← Back to Algod Client

Description

Section titled “Description”

This example demonstrates how to get transaction proofs using:

  • transactionProof(round, txId) - Get the Merkle proof for a transaction Transaction proofs are cryptographic proofs that a transaction is included in a specific block. They are used for light client verification, allowing clients to verify transaction inclusion without downloading the entire blockchain. The proof uses a Merkle tree structure where:
  • Each transaction in a block is a leaf in the tree
  • The root of the tree is committed in the block header
  • The proof provides the sibling hashes needed to reconstruct the root

Prerequisites

Section titled “Prerequisites”
  • LocalNet running (via algokit localnet start)

Run This Example

Section titled “Run This Example”

From the repository root:

Terminal window
cd examples
npm run example algod_client/15-transaction-proof.ts

Code

Section titled “Code”

View source on GitHub

15-transaction-proof.ts
/**
 * Example: Transaction Proof
 *
 * This example demonstrates how to get transaction proofs using:
 * - transactionProof(round, txId) - Get the Merkle proof for a transaction
 *
 * Transaction proofs are cryptographic proofs that a transaction is included in a specific
 * block. They are used for light client verification, allowing clients to verify transaction
 * inclusion without downloading the entire blockchain.
 *
 * The proof uses a Merkle tree structure where:
 * - Each transaction in a block is a leaf in the tree
 * - The root of the tree is committed in the block header
 * - The proof provides the sibling hashes needed to reconstruct the root
 *
 * Prerequisites:
 * - LocalNet running (via `algokit localnet start`)
 */


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


async function main() {
  printHeader('Transaction Proof Example')


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


  // =========================================================================
  // Step 1: Submit a transaction and wait for confirmation
  // =========================================================================
  printStep(1, 'Submitting a transaction and waiting for confirmation')


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


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


  // Submit a payment transaction
  const paymentAmount = algo(1)
  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('')


  // =========================================================================
  // Step 2: Get transaction proof using transactionProof(round, txId)
  // =========================================================================
  printStep(2, 'Getting transaction proof using transactionProof(round, txId)')


  printInfo('transactionProof(round, txId) returns a Merkle proof that the transaction')
  printInfo('is included in the specified block. This is used for light client verification.')
  printInfo('')


  try {
    const proof = await algod.transactionProof(confirmedRound, txId)
    printSuccess('Successfully retrieved transaction proof!')
    printInfo('')


    displayTransactionProof(proof)
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : String(error)
    printError(`Error getting transaction proof: ${errorMessage}`)
    printInfo('')
  }


  // =========================================================================
  // Step 3: Demonstrate proof with different hash type (sha256)
  // =========================================================================
  printStep(3, 'Getting transaction proof with SHA-256 hash type')


  printInfo('The hashtype parameter specifies the hash function used to create the proof.')
  printInfo('Supported values: "sha512_256" (default) and "sha256"')
  printInfo('')


  try {
    const proofSha256 = await algod.transactionProof(confirmedRound, txId, { hashtype: 'sha256' })
    printSuccess('Successfully retrieved transaction proof with SHA-256!')
    printInfo('')


    displayTransactionProof(proofSha256)
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : String(error)
    if (errorMessage.includes('not supported') || errorMessage.includes('400')) {
      printError('SHA-256 hash type may not be supported on this node configuration.')
      printInfo('The default SHA-512/256 is the native Algorand hash function.')
    } else {
      printError(`Error getting transaction proof with SHA-256: ${errorMessage}`)
    }
    printInfo('')
  }


  // =========================================================================
  // Step 4: Demonstrate structure of Merkle proof data
  // =========================================================================
  printStep(4, 'Understanding the Merkle proof structure')


  printInfo('The transaction proof contains data needed to verify transaction inclusion:')
  printInfo('')


  try {
    const proof = await algod.transactionProof(confirmedRound, txId)


    printInfo('  Merkle Proof Structure:')
    printInfo('')
    printInfo('  1. idx (index): Position of the transaction in the block\'s payset')
    printInfo(`     Value: ${proof.idx}`)
    printInfo('     This tells you which leaf in the Merkle tree corresponds to this transaction.')
    printInfo('')


    printInfo('  2. treedepth: Number of levels in the Merkle tree')
    printInfo(`     Value: ${proof.treedepth}`)
    printInfo(`     A tree with depth ${proof.treedepth} can hold up to ${Math.pow(2, proof.treedepth)} transactions.`)
    printInfo('')


    printInfo('  3. proof: Sibling hashes needed to reconstruct the Merkle root')
    printInfo(`     Length: ${proof.proof.length} bytes`)
    if (proof.treedepth > 0) {
      printInfo(`     Number of hashes: ${proof.treedepth} (one for each level)`)
      printInfo(`     Hash size: ${proof.proof.length / proof.treedepth} bytes per hash`)
    } else {
      printInfo('     (Empty - single transaction in block, stibhash IS the Merkle root)')
    }
    printInfo('')


    printInfo('  4. stibhash: Hash of SignedTxnInBlock')
    printInfo(`     Length: ${proof.stibhash.length} bytes`)
    printInfo('     This is the leaf value - the hash of the transaction as stored in the block.')
    printInfo('')


    printInfo('  5. hashtype: Hash function used')
    printInfo(`     Value: "${proof.hashtype}"`)
    printInfo('     SHA-512/256 is Algorand\'s native hash function (first 256 bits of SHA-512).')
    printInfo('')
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : String(error)
    printError(`Error demonstrating proof structure: ${errorMessage}`)
    printInfo('')
  }


  // =========================================================================
  // Step 5: Handle errors - invalid round or transaction ID
  // =========================================================================
  printStep(5, 'Handling errors when proof is not available')


  printInfo('Transaction proofs may not be available if:')
  printInfo('  - The round number is invalid or not yet committed')
  printInfo('  - The transaction ID does not exist in the specified round')
  printInfo('  - The node does not have the block data')
  printInfo('')


  // Try getting proof for a non-existent transaction ID
  const fakeTxId = 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA'
  try {
    await algod.transactionProof(confirmedRound, fakeTxId)
    printInfo('Unexpectedly succeeded with fake transaction ID')
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : String(error)
    printSuccess(`Correctly rejected invalid transaction ID`)
    printInfo(`Error: ${errorMessage.substring(0, 100)}...`)
  }
  printInfo('')


  // Try getting proof for a future round
  const status = await algod.status()
  const futureRound = status.lastRound + 1000n
  try {
    await algod.transactionProof(futureRound, txId)
    printInfo('Unexpectedly succeeded with future round')
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : String(error)
    printSuccess(`Correctly rejected future round`)
    printInfo(`Error: ${errorMessage.substring(0, 100)}...`)
  }
  printInfo('')


  // =========================================================================
  // Step 6: Submit multiple transactions and compare proofs
  // =========================================================================
  printStep(6, 'Comparing proofs for multiple transactions in the same block')


  printInfo('Each transaction in a block has a unique position (idx) in the Merkle tree.')
  printInfo('Submitting multiple transactions to observe different proof indices...')
  printInfo('')


  // Submit multiple transactions in sequence (they may end up in different blocks on LocalNet dev mode)
  const txIds: string[] = []
  const confirmedRounds: bigint[] = []


  for (let i = 0; i < 3; i++) {
    const newReceiver = algorand.account.random()
    const txResult = await algorand.send.payment({
      sender: sender.addr,
      receiver: newReceiver.addr,
      amount: algo(0.1),
    })
    txIds.push(txResult.txIds[0])
    confirmedRounds.push(txResult.confirmation.confirmedRound!)
  }


  printInfo(`Submitted ${txIds.length} transactions`)
  printInfo('')


  // Get proofs for each transaction
  for (let i = 0; i < txIds.length; i++) {
    try {
      const proof = await algod.transactionProof(confirmedRounds[i], txIds[i])
      printInfo(`  Transaction ${i + 1}:`)
      printInfo(`    Round: ${confirmedRounds[i].toLocaleString('en-US')}`)
      printInfo(`    TX ID: ${txIds[i].substring(0, 20)}...`)
      printInfo(`    Index in block (idx): ${proof.idx}`)
      printInfo(`    Tree depth: ${proof.treedepth}`)
      printInfo('')
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error)
      printError(`Error getting proof for transaction ${i + 1}: ${errorMessage}`)
    }
  }


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


  printInfo('Transaction Proof Use Cases:')
  printInfo('')
  printInfo('1. Light Client Verification:')
  printInfo('   - Verify a transaction is included in the blockchain without downloading all blocks')
  printInfo('   - Only need the block header (with Merkle root) and the proof')
  printInfo('   - Reduces bandwidth and storage requirements significantly')
  printInfo('')
  printInfo('2. Cross-Chain Bridges:')
  printInfo('   - Prove to another blockchain that a transaction occurred on Algorand')
  printInfo('   - The proof can be verified by a smart contract on the target chain')
  printInfo('')
  printInfo('3. Auditing and Compliance:')
  printInfo('   - Provide cryptographic proof of transaction inclusion')
  printInfo('   - Third parties can verify without trusting the provider')
  printInfo('')
  printInfo('TransactionProof Type Structure:')
  printInfo('  proof: Uint8Array      - Merkle proof (sibling hashes concatenated)')
  printInfo('  stibhash: Uint8Array   - Hash of SignedTxnInBlock (leaf value)')
  printInfo('  treedepth: number      - Depth of the Merkle tree')
  printInfo('  idx: number            - Transaction index in the block\'s payset')
  printInfo('  hashtype: string       - Hash function used ("sha512_256" or "sha256")')
  printInfo('')
  printInfo('API Method:')
  printInfo('  transactionProof(round, txId, params?)')
  printInfo('    round: number | bigint - The round (block) containing the transaction')
  printInfo('    txId: string           - The transaction ID')
  printInfo('    params?: { hashtype?: "sha512_256" | "sha256" }')
  printInfo('')
  printInfo('Verification Process:')
  printInfo('  1. Get the stibhash (leaf value) from the proof')
  printInfo('  2. Use idx to determine if leaf is left or right child at each level')
  printInfo('  3. Combine with sibling hashes from proof, hashing up the tree')
  printInfo('  4. Compare computed root with the txnCommitments in the block header')
  printInfo('  5. If they match, the transaction is verified as included in the block')
}


/**
 * Display details from a TransactionProof
 */
function displayTransactionProof(proof: TransactionProof): void {
  printInfo('  TransactionProof fields:')
  printInfo(`    idx: ${proof.idx}`)
  printInfo(`         Index of the transaction in the block's payset`)
  printInfo('')
  if (proof.proof.length > 0) {
    printInfo(`    proof: ${Buffer.from(proof.proof).toString('hex').substring(0, 64)}...`)
    printInfo(`           (${proof.proof.length} bytes total - Merkle proof data)`)
  } else {
    printInfo('    proof: (empty - single transaction in block)')
    printInfo('           When treedepth=0, stibhash IS the Merkle root')
  }
  printInfo('')
  printInfo(`    stibhash: ${Buffer.from(proof.stibhash).toString('hex')}`)
  printInfo(`              (${proof.stibhash.length} bytes - Hash of SignedTxnInBlock)`)
  printInfo('')
  printInfo(`    treedepth: ${proof.treedepth}`)
  printInfo(`               Number of edges from leaf to root in the Merkle tree`)
  printInfo('')
  printInfo(`    hashtype: "${proof.hashtype}"`)
  printInfo(`              Hash function used to create the proof`)
  printInfo('')
}


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

Other examples in Algod Client

Section titled “Other examples in Algod Client”