Payment with Close

Description

This example demonstrates how to close an account by transferring all remaining ALGO to another account using the closeRemainderTo field in PaymentTransactionFields. Key concepts:

closeRemainderTo: Specifies an account to receive all remaining ALGO after the transaction
When an account is closed, its balance becomes 0
The close-to account receives: (original balance - sent amount - fee)

Prerequisites

LocalNet running (via algokit localnet start)

Run This Example

From the repository root:

cd examples
npm run example transact/02-payment-close.ts

Code

View source on GitHub

/**
 * Example: Payment with Close
 *
 * This example demonstrates how to close an account by transferring all remaining
 * ALGO to another account using the closeRemainderTo field in PaymentTransactionFields.
 *
 * Key concepts:
 * - closeRemainderTo: Specifies an account to receive all remaining ALGO after the transaction
 * - When an account is closed, its balance becomes 0
 * - The close-to account receives: (original balance - sent amount - fee)
 *
 * Prerequisites:
 * - LocalNet running (via `algokit localnet start`)
 */

import { AlgorandClient } from '@algorandfoundation/algokit-utils'
import {
  Transaction,
  TransactionType,
  assignFee,
  type PaymentTransactionFields,
} from '@algorandfoundation/algokit-utils/transact'
import {
  createAlgodClient,
  formatAlgo,
  getAccountBalance,
  printHeader,
  printInfo,
  printStep,
  printSuccess,
  shortenAddress,
  waitForConfirmation,
} from '../shared/utils.js'

/**
 * Gets a funded account from LocalNet's KMD wallet
 */
async function getLocalNetFundedAccount(algorand: AlgorandClient) {
  return await algorand.account.kmd.getLocalNetDispenserAccount()
}

async function main() {
  printHeader('Payment with Close Example')

  // Step 1: Initialize clients
  printStep(1, 'Initialize Algod Client')
  const algod = createAlgodClient()
  const algorand = AlgorandClient.defaultLocalNet()
  printInfo('Connected to LocalNet Algod')

  // Step 2: Get a funded account from KMD (funding source)
  printStep(2, 'Get Funded Account from KMD')
  const fundingAccount = await getLocalNetFundedAccount(algorand)
  printInfo(`Funding account: ${shortenAddress(fundingAccount.addr.toString())}`)

  // Step 3: Generate temporary account to be closed using AlgorandClient helper
  printStep(3, 'Generate Temporary Account (will be closed)')
  const tempAccount = algorand.account.random()
  printInfo(`Temporary account: ${shortenAddress(tempAccount.addr.toString())}`)

  // Step 4: Generate close-to account (receives remaining balance) using AlgorandClient helper
  printStep(4, 'Generate Close-To Account (receives remainder)')
  const closeToAccount = algorand.account.random()
  printInfo(`Close-to account: ${shortenAddress(closeToAccount.addr.toString())}`)

  // Step 5: Fund the temporary account
  printStep(5, 'Fund Temporary Account')
  const fundAmount = 2_000_000n // 2 ALGO in microALGO (enough to cover min balance + tx amount + fee)

  const fundParams = await algod.suggestedParams()
  const fundTx = new Transaction({
    type: TransactionType.Payment,
    sender: fundingAccount.addr,
    firstValid: fundParams.firstValid,
    lastValid: fundParams.lastValid,
    genesisHash: fundParams.genesisHash,
    genesisId: fundParams.genesisId,
    payment: {
      receiver: tempAccount.addr,
      amount: fundAmount,
    },
  })
  const fundTxWithFee = assignFee(fundTx, {
    feePerByte: fundParams.fee,
    minFee: fundParams.minFee,
  })
  const signedFundTxns = await fundingAccount.signer([fundTxWithFee], [0])
  await algod.sendRawTransaction(signedFundTxns)
  await waitForConfirmation(algod, fundTxWithFee.txId())

  const tempBalanceAfterFund = await getAccountBalance(algorand, tempAccount.addr.toString())
  printInfo(`Funded temporary account with: ${formatAlgo(fundAmount)}`)
  printInfo(`Temporary account balance: ${formatAlgo(tempBalanceAfterFund.microAlgo)}`)

  // Step 6: Record initial close-to account balance
  printStep(6, 'Check Initial Close-To Account Balance')
  let closeToBalanceBefore: bigint
  try {
    const info = await getAccountBalance(algorand, closeToAccount.addr.toString())
    closeToBalanceBefore = info.microAlgo
  } catch {
    closeToBalanceBefore = 0n
  }
  printInfo(`Close-to account initial balance: ${formatAlgo(closeToBalanceBefore)}`)

  // Step 7: Create payment transaction with closeRemainderTo
  printStep(7, 'Create Payment Transaction with closeRemainderTo')
  const suggestedParams = await algod.suggestedParams()
  const paymentAmount = 100_000n // 0.1 ALGO sent to funding account (can be 0)

  // The key field: closeRemainderTo specifies where remaining balance goes
  const paymentFields: PaymentTransactionFields = {
    receiver: fundingAccount.addr, // Send a small amount to funding account
    amount: paymentAmount,
    closeRemainderTo: closeToAccount.addr, // All remaining balance goes here
  }

  const closeTx = new Transaction({
    type: TransactionType.Payment,
    sender: tempAccount.addr,
    firstValid: suggestedParams.firstValid,
    lastValid: suggestedParams.lastValid,
    genesisHash: suggestedParams.genesisHash,
    genesisId: suggestedParams.genesisId,
    payment: paymentFields,
  })

  printInfo(`Payment amount: ${formatAlgo(paymentAmount)}`)
  printInfo(`closeRemainderTo: ${shortenAddress(closeToAccount.addr.toString())}`)

  // Step 8: Assign fee and sign the transaction
  printStep(8, 'Assign Fee and Sign Transaction')
  const closeTxWithFee = assignFee(closeTx, {
    feePerByte: suggestedParams.fee,
    minFee: suggestedParams.minFee,
  })
  const txFee = closeTxWithFee.fee ?? 0n
  printInfo(`Transaction fee: ${txFee} microALGO`)

  // Calculate expected remainder before signing
  const expectedRemainder = tempBalanceAfterFund.microAlgo - paymentAmount - BigInt(txFee)
  printInfo(`Expected remainder to close-to account: ${formatAlgo(expectedRemainder)}`)

  // Sign using the temp account's signer
  const signedCloseTxns = await tempAccount.signer([closeTxWithFee], [0])
  const txId = closeTxWithFee.txId()
  printInfo(`Transaction ID: ${txId}`)

  // Step 9: Submit and confirm the close transaction
  printStep(9, 'Submit Close Transaction')
  await algod.sendRawTransaction(signedCloseTxns)
  printInfo('Transaction submitted to network')

  const pendingInfo = await waitForConfirmation(algod, txId)
  printInfo(`Transaction confirmed in round: ${pendingInfo.confirmedRound}`)

  // Step 10: Verify closed account has 0 balance
  printStep(10, 'Verify Closed Account Balance')
  let tempBalanceAfterClose: bigint
  try {
    const info = await getAccountBalance(algorand, tempAccount.addr.toString())
    tempBalanceAfterClose = info.microAlgo
  } catch {
    // Account may not exist anymore after being closed
    tempBalanceAfterClose = 0n
  }
  printInfo(`Temporary account balance after close: ${formatAlgo(tempBalanceAfterClose)}`)

  if (tempBalanceAfterClose === 0n) {
    printSuccess('Temporary account successfully closed (balance is 0)')
  } else {
    throw new Error(`Expected closed account to have 0 balance, but got ${tempBalanceAfterClose}`)
  }

  // Step 11: Verify close-to account received the remainder
  printStep(11, 'Verify Close-To Account Received Remainder')
  const closeToBalanceAfter = await getAccountBalance(algorand, closeToAccount.addr.toString())
  printInfo(`Close-to account balance after: ${formatAlgo(closeToBalanceAfter.microAlgo)}`)

  const actualRemainder = closeToBalanceAfter.microAlgo - closeToBalanceBefore
  printInfo(`Actual remainder received: ${formatAlgo(actualRemainder)}`)
  printInfo(`Expected remainder: ${formatAlgo(expectedRemainder)}`)

  // Verify the close-to account received the expected remainder
  if (actualRemainder === expectedRemainder) {
    printSuccess(`Close-to account received correct remainder of ${formatAlgo(expectedRemainder)}`)
  } else {
    throw new Error(`Expected remainder ${expectedRemainder}, but got ${actualRemainder}`)
  }

  printSuccess('Payment with close example completed successfully!')
}

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

Payment with Close

Description

Prerequisites

Run This Example

Code

Other examples in Transactions