Balance Change Tracking

← Back to Examples

Description

This example demonstrates balance change filtering for ALGO and ASA transfers.

• Filter by assetId, role, minAbsoluteAmount, and address
• Inspect balanceChanges array on matched transactions
• Explore BalanceChangeRole enum values

Prerequisites

• LocalNet running (via algokit localnet start)

Run This Example

From the repository’s examples/subscriber directory:

cd examples/subscriber
npx tsx 07-balance-changes.ts

Code

View source on GitHub

07-balance-changes.ts

/**
 * Example: Balance Change Tracking
 *
 * This example demonstrates balance change filtering for ALGO and ASA transfers.
 * - Filter by assetId, role, minAbsoluteAmount, and address
 * - Inspect balanceChanges array on matched transactions
 * - Explore BalanceChangeRole enum values
 *
 * Prerequisites:
 * - LocalNet running (via `algokit localnet start`)
 */
import { algo, AlgorandClient } from '@algorandfoundation/algokit-utils'
import { AlgorandSubscriber } from '@algorandfoundation/algokit-subscriber'
import { BalanceChangeRole } from '@algorandfoundation/algokit-subscriber/types/subscription'
import { printHeader, printStep, printInfo, printSuccess, printError, shortenAddress, formatMicroAlgo } from './shared/utils.js'

async function main() {
  printHeader('07 — Balance Change Tracking')

  // Step 1: Connect to LocalNet
  printStep(1, 'Connect to LocalNet')
  const algorand = AlgorandClient.defaultLocalNet()
  const status = await algorand.client.algod.status()
  printInfo(`Current round: ${status.lastRound.toString()}`)
  printSuccess('Connected to LocalNet')

  // Step 2: Create accounts
  printStep(2, 'Create and fund accounts')
  const sender = await algorand.account.fromEnvironment('BAL_SENDER', algo(100))
  const receiver = await algorand.account.fromEnvironment('BAL_RECEIVER', algo(10))
  const senderAddr = sender.addr.toString()
  const receiverAddr = receiver.addr.toString()
  printInfo(`Sender: ${shortenAddress(senderAddr)}`)
  printInfo(`Receiver: ${shortenAddress(receiverAddr)}`)
  printSuccess('Accounts created and funded')

  // Step 3: Create an ASA for asset transfer testing
  printStep(3, 'Create ASA and opt in receiver')
  const asaResult = await algorand.send.assetCreate({
    sender: sender.addr,
    total: 1_000_000n,
    decimals: 0,
    assetName: 'BalTestToken',
    unitName: 'BTT',
  })
  const assetId = asaResult.assetId
  printInfo(`Asset ID: ${assetId.toString()}`)

  await algorand.send.assetOptIn({ sender: receiver.addr, assetId })
  printSuccess('Receiver opted in to ASA')

  // Step 4: Send Algo payments and ASA transfers
  printStep(4, 'Send Algo payments and ASA transfers')

  // Payment 1: Sender -> Receiver, 5 ALGO
  const pay1 = await algorand.send.payment({
    sender: sender.addr,
    receiver: receiver.addr,
    amount: algo(5),
    note: 'bal-pay-1',
  })
  printInfo(`Txn 1: Sender -> Receiver, 5 ALGO`)

  // Payment 2: Sender -> Receiver, 2 ALGO
  const pay2 = await algorand.send.payment({
    sender: sender.addr,
    receiver: receiver.addr,
    amount: algo(2),
    note: 'bal-pay-2',
  })
  printInfo(`Txn 2: Sender -> Receiver, 2 ALGO`)

  // ASA Transfer: Sender -> Receiver, 500 tokens
  const axfer1 = await algorand.send.assetTransfer({
    sender: sender.addr,
    receiver: receiver.addr,
    assetId,
    amount: 500n,
    note: 'bal-axfer-1',
  })
  printInfo(`Txn 3: Sender -> Receiver, 500 BTT (ASA)`)
  printSuccess('All transactions sent')

  // Step 5: Subscribe with balanceChanges filter — Algo Sender with minAbsoluteAmount
  printStep(5, 'Filter: Algo balance changes for Sender role with minAbsoluteAmount')
  const watermarkBefore = pay1.confirmation!.confirmedRound! - 1n
  let watermark1 = watermarkBefore

  const algoSenderSub = new AlgorandSubscriber(
    {
      filters: [
        {
          name: 'algo-sender-changes',
          filter: {
            balanceChanges: [
              {
                assetId: 0n,
                role: BalanceChangeRole.Sender,
                minAbsoluteAmount: 2_000_000,
              },
            ],
          },
        },
      ],
      syncBehaviour: 'sync-oldest',
      maxRoundsToSync: 100,
      watermarkPersistence: {
        get: async () => watermark1,
        set: async (w: bigint) => { watermark1 = w },
      },
    },
    algorand.client.algod,
  )

  const algoSenderResult = await algoSenderSub.pollOnce()
  const algoSenderTxns = algoSenderResult.subscribedTransactions
  printInfo(`Matched transactions: ${algoSenderTxns.length.toString()}`)

  // Both pay1 (5 ALGO) and pay2 (2 ALGO) should match — sender loses >= 2 ALGO (amount + fee)
  // The ASA transfer only moves tokens, but the sender also pays a fee in Algo
  for (const txn of algoSenderTxns) {
    const note = txn.note ? Buffer.from(txn.note).toString('utf-8') : ''
    printInfo(`  ${note}: id=${txn.id.slice(0, 12)}...`)
  }
  if (algoSenderTxns.length < 2) {
    throw new Error(`Expected at least 2 Algo Sender transactions (>= 2M microAlgo), got ${algoSenderTxns.length}`)
  }
  printSuccess('Algo Sender filter matched expected transactions')

  // Step 6: Subscribe with balanceChanges filter — ASA Receiver
  printStep(6, 'Filter: ASA balance changes for Receiver role')
  let watermark2 = watermarkBefore

  const asaReceiverSub = new AlgorandSubscriber(
    {
      filters: [
        {
          name: 'asa-receiver-changes',
          filter: {
            balanceChanges: [
              {
                assetId: assetId,
                role: BalanceChangeRole.Receiver,
              },
            ],
          },
        },
      ],
      syncBehaviour: 'sync-oldest',
      maxRoundsToSync: 100,
      watermarkPersistence: {
        get: async () => watermark2,
        set: async (w: bigint) => { watermark2 = w },
      },
    },
    algorand.client.algod,
  )

  const asaReceiverResult = await asaReceiverSub.pollOnce()
  const asaReceiverTxns = asaReceiverResult.subscribedTransactions
  printInfo(`Matched transactions: ${asaReceiverTxns.length.toString()}`)

  for (const txn of asaReceiverTxns) {
    const note = txn.note ? Buffer.from(txn.note).toString('utf-8') : ''
    printInfo(`  ${note}: id=${txn.id.slice(0, 12)}...`)
  }
  if (asaReceiverTxns.length < 1) {
    throw new Error(`Expected at least 1 ASA Receiver transaction, got ${asaReceiverTxns.length}`)
  }
  printSuccess('ASA Receiver filter matched expected transactions')

  // Step 7: Subscribe with balanceChanges filter — Address (any role)
  printStep(7, 'Filter: All balance changes for a specific address')
  let watermark3 = watermarkBefore

  const addressSub = new AlgorandSubscriber(
    {
      filters: [
        {
          name: 'address-changes',
          filter: {
            balanceChanges: [
              {
                address: senderAddr,
              },
            ],
          },
        },
      ],
      syncBehaviour: 'sync-oldest',
      maxRoundsToSync: 100,
      watermarkPersistence: {
        get: async () => watermark3,
        set: async (w: bigint) => { watermark3 = w },
      },
    },
    algorand.client.algod,
  )

  const addressResult = await addressSub.pollOnce()
  const addressTxns = addressResult.subscribedTransactions
  printInfo(`Matched transactions: ${addressTxns.length.toString()}`)

  for (const txn of addressTxns) {
    const note = txn.note ? Buffer.from(txn.note).toString('utf-8') : ''
    printInfo(`  ${note}: id=${txn.id.slice(0, 12)}...`)
  }
  if (addressTxns.length < 3) {
    throw new Error(`Expected at least 3 address-filtered transactions, got ${addressTxns.length}`)
  }
  printSuccess('Address filter matched expected transactions')

  // Step 8: Inspect balanceChanges array on matched transactions
  printStep(8, 'Inspect balanceChanges array on matched transactions')

  // Collect all unique transactions from both polls
  const allTxns = [...algoSenderTxns, ...asaReceiverTxns]
  const seen = new Set<string>()

  for (const txn of allTxns) {
    if (seen.has(txn.id)) continue
    seen.add(txn.id)

    const note = txn.note ? Buffer.from(txn.note).toString('utf-8') : ''
    console.log()
    printInfo(`Transaction: ${note} (${txn.id.slice(0, 12)}...)`)

    if (txn.balanceChanges && txn.balanceChanges.length > 0) {
      for (const bc of txn.balanceChanges) {
        const assetLabel = bc.assetId === 0n ? 'ALGO' : `ASA #${bc.assetId}`
        const roles = bc.roles.join(', ')
        printInfo(
          `  ${shortenAddress(bc.address)}: asset=${assetLabel}, amount=${bc.amount.toString()}, roles=[${roles}]`,
        )
      }
    } else {
      printInfo('  (no balance changes)')
    }
  }

  // Step 9: Demonstrate BalanceChangeRole enum values
  printStep(9, 'BalanceChangeRole enum values')
  printInfo(`Sender: ${BalanceChangeRole.Sender}`)
  printInfo(`Receiver: ${BalanceChangeRole.Receiver}`)
  printInfo(`CloseTo: ${BalanceChangeRole.CloseTo}`)
  printInfo(`AssetCreator: ${BalanceChangeRole.AssetCreator}`)
  printInfo(`AssetDestroyer: ${BalanceChangeRole.AssetDestroyer}`)
  printSuccess('All BalanceChangeRole values demonstrated')

  // Step 10: Summary
  printStep(10, 'Summary')
  console.log()
  console.log('  ┌──────────────────┬──────────────────────────────────────────────────┐')
  console.log('  │ Filter           │ Description                                      │')
  console.log('  ├──────────────────┼──────────────────────────────────────────────────┤')
  console.log('  │ algo-sender      │ assetId=0, role=Sender, minAbsoluteAmount=2M     │')
  console.log('  │ asa-receiver     │ assetId=ASA, role=Receiver                        │')
  console.log('  │ address          │ address=Sender (any role, any asset)              │')
  console.log('  └──────────────────┴──────────────────────────────────────────────────┘')
  console.log()

  printHeader('Example complete')
}

main().catch((err) => {
  printError(err.message)
  process.exit(1)
})

---

Other examples

• Basic Poll Once
• Continuous Subscriber
• Payment Filters
• Asset Transfer Subscription
• App Call Subscription
• Multiple Named Filters
• Balance Change Tracking
• ARC-28 Event Subscription
• Inner Transaction Subscription
• Batch Handling & Data Mappers
• Watermark Persistence
• Sync Behaviours
• Custom Filters
• Stateless Subscriptions
• Lifecycle Hooks & Error Handling