AlgoAmount Utility

← Back to Algorand Client

Description

This example demonstrates how to use the AlgoAmount utility class to work with ALGO and microALGO amounts safely, avoiding floating point precision issues. Topics covered:

• Creating AlgoAmount using static factory methods
• Accessing values in ALGO and microALGO
• String formatting
• Arithmetic operations (addition, subtraction)
• Comparison operations
• Using AlgoAmount with payment transactions
• Avoiding floating point precision issues

Prerequisites

• No LocalNet required

Run This Example

From the repository root:

cd examples
npm run example algorand_client/02-algo-amount.ts

Code

View source on GitHub

02-algo-amount.ts

/**
 * Example: AlgoAmount Utility
 *
 * This example demonstrates how to use the AlgoAmount utility class to work
 * with ALGO and microALGO amounts safely, avoiding floating point precision issues.
 *
 * Topics covered:
 * - Creating AlgoAmount using static factory methods
 * - Accessing values in ALGO and microALGO
 * - String formatting
 * - Arithmetic operations (addition, subtraction)
 * - Comparison operations
 * - Using AlgoAmount with payment transactions
 * - Avoiding floating point precision issues
 *
 * Prerequisites:
 * - No LocalNet required
 */

import {
  algo,
  ALGORAND_MIN_TX_FEE,
  AlgorandClient,
  algos,
  microAlgo,
  microAlgos,
  transactionFees,
} from '@algorandfoundation/algokit-utils';
import { AlgoAmount } from '@algorandfoundation/algokit-utils/types/amount';
import {
  printError,
  printHeader,
  printInfo,
  printStep,
  printSuccess,
  shortenAddress,
} from '../shared/utils.js';

async function main() {
  printHeader('AlgoAmount Utility Example');

  // Step 1: Creating AlgoAmount using static factory methods
  printStep(1, 'Creating AlgoAmount using static factory methods');
  printInfo('AlgoAmount provides four static factory methods:');
  printInfo('  - AlgoAmount.Algo(amount) - Create from ALGO value');
  printInfo('  - AlgoAmount.Algos(amount) - Alias for Algo()');
  printInfo('  - AlgoAmount.MicroAlgo(amount) - Create from microALGO value');
  printInfo('  - AlgoAmount.MicroAlgos(amount) - Alias for MicroAlgo()');

  // Create using AlgoAmount.Algo()
  const oneAndHalfAlgo = AlgoAmount.Algo(1.5);
  printInfo(
    `\nAlgoAmount.Algo(1.5): ${oneAndHalfAlgo.algo} ALGO = ${oneAndHalfAlgo.microAlgo} µALGO`,
  );

  // Create using AlgoAmount.Algos() - alias
  const twoAlgos = AlgoAmount.Algos(2);
  printInfo(`AlgoAmount.Algos(2): ${twoAlgos.algo} ALGO = ${twoAlgos.microAlgo} µALGO`);

  // Create using AlgoAmount.MicroAlgo()
  const fiftyThousandMicroAlgo = AlgoAmount.MicroAlgo(50_000);
  printInfo(
    `AlgoAmount.MicroAlgo(50000): ${fiftyThousandMicroAlgo.algo} ALGO = ${fiftyThousandMicroAlgo.microAlgo} µALGO`,
  );

  // Create using AlgoAmount.MicroAlgos() - alias
  const hundredThousandMicroAlgo = AlgoAmount.MicroAlgos(100_000);
  printInfo(
    `AlgoAmount.MicroAlgos(100000): ${hundredThousandMicroAlgo.algo} ALGO = ${hundredThousandMicroAlgo.microAlgo} µALGO`,
  );

  printSuccess('Created AlgoAmount instances using all factory methods');

  // Step 2: Using helper functions
  printStep(2, 'Using convenience helper functions');
  printInfo('The library exports helper functions for cleaner syntax:');
  printInfo('  - algo(amount) - Equivalent to AlgoAmount.Algo()');
  printInfo('  - algos(amount) - Equivalent to AlgoAmount.Algos()');
  printInfo('  - microAlgo(amount) - Equivalent to AlgoAmount.MicroAlgo()');
  printInfo('  - microAlgos(amount) - Equivalent to AlgoAmount.MicroAlgos()');

  const threeAlgo = algo(3);
  printInfo(`\nalgo(3): ${threeAlgo.algo} ALGO = ${threeAlgo.microAlgo} µALGO`);

  const fiveAlgos = algos(5);
  printInfo(`algos(5): ${fiveAlgos.algo} ALGO = ${fiveAlgos.microAlgo} µALGO`);

  const tenMicroAlgo = microAlgo(10);
  printInfo(`microAlgo(10): ${tenMicroAlgo.algo} ALGO = ${tenMicroAlgo.microAlgo} µALGO`);

  const twentyMicroAlgos = microAlgos(20);
  printInfo(`microAlgos(20): ${twentyMicroAlgos.algo} ALGO = ${twentyMicroAlgos.microAlgo} µALGO`);

  // Transaction fees helper
  const threeTransactionFees = transactionFees(3);
  printInfo(
    `\ntransactionFees(3): ${threeTransactionFees.microAlgo} µALGO (covers 3 standard transactions)`,
  );
  printInfo(
    `ALGORAND_MIN_TX_FEE: ${ALGORAND_MIN_TX_FEE.microAlgo} µALGO (minimum transaction fee)`,
  );

  printSuccess('Demonstrated convenience helper functions');

  // Step 3: Accessing values in ALGO and microALGO
  printStep(3, 'Accessing values using .algo and .microAlgo properties');
  printInfo('AlgoAmount provides getter properties to access the value:');
  printInfo('  - .algo / .algos - Get value in ALGO (as number)');
  printInfo('  - .microAlgo / .microAlgos - Get value in µALGO (as bigint)');

  const amount = AlgoAmount.Algo(2.5);
  printInfo(`\nFor amount = AlgoAmount.Algo(2.5):`);
  printInfo(`  .algo: ${amount.algo} (type: ${typeof amount.algo})`);
  printInfo(`  .algos: ${amount.algos} (alias for .algo)`);
  printInfo(`  .microAlgo: ${amount.microAlgo} (type: ${typeof amount.microAlgo})`);
  printInfo(`  .microAlgos: ${amount.microAlgos} (alias for .microAlgo)`);

  printSuccess('Accessed values using all getter properties');

  // Step 4: String formatting with toString()
  printStep(4, 'String formatting with toString()');
  printInfo('The toString() method formats the amount for human-readable display');

  const formattedAmount = AlgoAmount.Algo(1.234567);
  printInfo(`\nAlgoAmount.Algo(1.234567).toString(): "${formattedAmount.toString()}"`);

  const largeAmount = AlgoAmount.MicroAlgo(1_234_567_890);
  printInfo(`AlgoAmount.MicroAlgo(1234567890).toString(): "${largeAmount.toString()}"`);

  // Custom formatting using properties
  printInfo('\nCustom formatting examples:');
  printInfo(`  ${amount.algo.toFixed(2)} ALGO`);
  printInfo(`  ${amount.microAlgo.toLocaleString('en-US')} µALGO`);

  printSuccess('Demonstrated string formatting');

  // Step 5: Arithmetic operations
  printStep(5, 'Arithmetic operations (addition, subtraction)');
  printInfo('AlgoAmount uses bigint internally for precision.');
  printInfo('Arithmetic is done by accessing .microAlgo and creating new AlgoAmount:');

  const amountA = AlgoAmount.Algo(5);
  const amountB = AlgoAmount.Algo(2.5);
  printInfo(`\namountA = AlgoAmount.Algo(5): ${amountA.algo} ALGO`);
  printInfo(`amountB = AlgoAmount.Algo(2.5): ${amountB.algo} ALGO`);

  // Addition
  const sum = AlgoAmount.MicroAlgo(amountA.microAlgo + amountB.microAlgo);
  printInfo(`\nAddition: amountA + amountB`);
  printInfo(`  AlgoAmount.MicroAlgo(${amountA.microAlgo} + ${amountB.microAlgo})`);
  printInfo(`  = ${sum.algo} ALGO (${sum.microAlgo} µALGO)`);

  // Subtraction
  const difference = AlgoAmount.MicroAlgo(amountA.microAlgo - amountB.microAlgo);
  printInfo(`\nSubtraction: amountA - amountB`);
  printInfo(`  AlgoAmount.MicroAlgo(${amountA.microAlgo} - ${amountB.microAlgo})`);
  printInfo(`  = ${difference.algo} ALGO (${difference.microAlgo} µALGO)`);

  // Adding transaction fees
  const amountWithFee = AlgoAmount.MicroAlgo(amountA.microAlgo + ALGORAND_MIN_TX_FEE.microAlgo);
  printInfo(`\nAdding transaction fee:`);
  printInfo(
    `  ${amountA.algo} ALGO + ${ALGORAND_MIN_TX_FEE.microAlgo} µALGO fee = ${amountWithFee.algo} ALGO`,
  );

  printSuccess('Demonstrated arithmetic operations');

  // Step 6: Comparison operations
  printStep(6, 'Comparison operations');
  printInfo('AlgoAmount implements valueOf() which enables comparison operators');
  printInfo('valueOf() returns the microAlgo value as a number');

  const small = AlgoAmount.Algo(1);
  const medium = AlgoAmount.Algo(5);
  const large = AlgoAmount.Algo(10);
  const equalToMedium = AlgoAmount.MicroAlgo(5_000_000);

  printInfo(`\nsmall = 1 ALGO, medium = 5 ALGO, large = 10 ALGO, equalToMedium = 5_000_000 µALGO`);

  printInfo(`\nComparison results:`);
  printInfo(`  small < medium: ${small < medium}`);
  printInfo(`  medium < large: ${medium < large}`);
  printInfo(`  large > small: ${large > small}`);
  printInfo(`  medium >= equalToMedium: ${medium >= equalToMedium}`);
  printInfo(`  medium <= equalToMedium: ${medium <= equalToMedium}`);

  // Direct microAlgo comparison for exact equality (recommended)
  printInfo(`\nFor exact equality, compare microAlgo values (bigint):`);
  printInfo(
    `  medium.microAlgo === equalToMedium.microAlgo: ${medium.microAlgo === equalToMedium.microAlgo}`,
  );

  printSuccess('Demonstrated comparison operations');

  // Step 7: Avoiding floating point precision issues
  printStep(7, 'Avoiding floating point precision issues');
  printInfo('JavaScript floating point arithmetic has precision issues.');
  printInfo('AlgoAmount avoids this by using bigint internally.');

  // Classic floating point problem
  const floatResult = 0.1 + 0.2;
  printInfo(`\nClassic floating point problem:`);
  printInfo(`  0.1 + 0.2 = ${floatResult} (not 0.3!)`);
  printInfo(`  0.1 + 0.2 === 0.3: ${floatResult === 0.3}`);

  // AlgoAmount handles this correctly
  const algoA = AlgoAmount.Algo(0.1);
  const algoB = AlgoAmount.Algo(0.2);
  const algoSum = AlgoAmount.MicroAlgo(algoA.microAlgo + algoB.microAlgo);

  printInfo(`\nUsing AlgoAmount:`);
  printInfo(`  AlgoAmount.Algo(0.1).microAlgo = ${algoA.microAlgo}`);
  printInfo(`  AlgoAmount.Algo(0.2).microAlgo = ${algoB.microAlgo}`);
  printInfo(`  Sum in microAlgo: ${algoA.microAlgo} + ${algoB.microAlgo} = ${algoSum.microAlgo}`);
  printInfo(`  Sum in Algo: ${algoSum.algo}`);
  printInfo(
    `  ${algoSum.microAlgo} === ${AlgoAmount.Algo(0.3).microAlgo}: ${algoSum.microAlgo === AlgoAmount.Algo(0.3).microAlgo}`,
  );

  // Another precision example
  printInfo(`\nAnother example with 1.23456789 ALGO:`);
  const preciseAmount = AlgoAmount.Algo(1.23456789);
  printInfo(`  AlgoAmount.Algo(1.23456789).microAlgo = ${preciseAmount.microAlgo}`);
  printInfo(`  Stored as: 1,234,568 µALGO (rounded to 6 decimal places)`);

  printSuccess('Demonstrated floating point precision handling');

  // Step 8: Using AlgoAmount with payment transactions
  printStep(8, 'Using AlgoAmount with payment transactions');
  printInfo('AlgoAmount integrates seamlessly with AlgorandClient payment methods');
  printInfo('This step requires LocalNet to be running');

  try {
    const algorand = AlgorandClient.defaultLocalNet();

    // Verify connection
    await algorand.client.algod.status();

    // Get accounts
    const dispenser = await algorand.account.dispenserFromEnvironment();
    const receiver = algorand.account.random();

    printInfo(`\nSender (dispenser): ${shortenAddress(dispenser.addr.toString())}`);
    printInfo(`Receiver (random): ${shortenAddress(receiver.addr.toString())}`);

    // Get initial balance
    const initialBalance = (await algorand.account.getInformation(dispenser.addr)).balance;
    printInfo(`\nInitial sender balance: ${initialBalance.algo} ALGO`);

    // Send payment using AlgoAmount
    const paymentAmount = AlgoAmount.Algo(1.5);
    printInfo(`\nSending ${paymentAmount.algo} ALGO (${paymentAmount.microAlgo} µALGO)...`);

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

    printInfo(`Transaction ID: ${result.txIds[0]}`);
    printInfo(`Confirmed in round: ${result.confirmation.confirmedRound}`);

    // Check balances after
    const senderBalance = (await algorand.account.getInformation(dispenser.addr)).balance;
    const receiverBalance = (await algorand.account.getInformation(receiver.addr)).balance;

    printInfo(`\nFinal balances:`);
    printInfo(`  Sender: ${senderBalance.algo} ALGO`);
    printInfo(`  Receiver: ${receiverBalance.algo} ALGO (${receiverBalance.microAlgo} µALGO)`);

    // Verify the receiver got exactly the right amount
    printInfo(`\nVerification:`);
    printInfo(`  Expected receiver balance: ${paymentAmount.microAlgo} µALGO`);
    printInfo(`  Actual receiver balance: ${receiverBalance.microAlgo} µALGO`);
    printInfo(`  Match: ${receiverBalance.microAlgo === paymentAmount.microAlgo}`);

    printSuccess('Payment transaction completed successfully!');
  } catch (error) {
    printError(
      `Failed to run payment example: ${error instanceof Error ? error.message : String(error)}`,
    );
    printInfo('Make sure LocalNet is running (e.g., algokit localnet start)');
    printInfo('This step demonstrates AlgoAmount integration with transactions');
  }

  // Step 9: Summary
  printStep(9, 'Summary');
  printInfo('AlgoAmount is a wrapper class for safe ALGO/µALGO handling:');
  printInfo('');
  printInfo('Factory methods:');
  printInfo('  - AlgoAmount.Algo(n) / AlgoAmount.Algos(n) - From ALGO');
  printInfo('  - AlgoAmount.MicroAlgo(n) / AlgoAmount.MicroAlgos(n) - From µALGO');
  printInfo('  - algo(n), algos(n), microAlgo(n), microAlgos(n) - Helper functions');
  printInfo('');
  printInfo('Properties:');
  printInfo('  - .algo / .algos - Get value in ALGO (number)');
  printInfo('  - .microAlgo / .microAlgos - Get value in µALGO (bigint)');
  printInfo('');
  printInfo('Operations:');
  printInfo('  - Arithmetic: Use .microAlgo + wrap result in AlgoAmount.MicroAlgo()');
  printInfo('  - Comparison: <, >, <=, >= work directly; use .microAlgo for ===');
  printInfo('  - Formatting: .toString() or access properties for custom format');
  printInfo('');
  printInfo('Best practices:');
  printInfo('  - Always use AlgoAmount for financial calculations');
  printInfo('  - Perform arithmetic on .microAlgo (bigint) to avoid precision loss');
  printInfo('  - Use helper functions (algo, microAlgo) for cleaner code');
  printInfo('  - Use transactionFees(n) when calculating fees for multiple transactions');

  printSuccess('AlgoAmount Utility example completed!');
}

main().catch(error => {
  printError(`Unhandled error: ${error instanceof Error ? error.message : String(error)}`);
  process.exit(1);
});

---

Other examples in Algorand Client

• Client Instantiation
• AlgoAmount Utility
• Signer Configuration
• Suggested Params Configuration
• Account Manager
• Send Payment
• Send Asset Operations
• Send Application Operations
• Create Transaction (Unsigned Transactions)
• Transaction Composer (Atomic Transaction Groups)
• Asset Manager
• App Manager
• App Deployer
• Client Manager
• Error Transformers
• Transaction Leases