Asset Manager

← Back to Algorand Client

Description

This example demonstrates the AssetManager functionality for querying asset information and performing bulk opt-in/opt-out operations:

• algorand.asset.getById() to fetch asset information by asset ID
• algorand.asset.getAccountInformation() to get an account’s asset holding
• algorand.asset.bulkOptIn() to opt into multiple assets at once
• algorand.asset.bulkOptOut() to opt out of multiple assets at once
• Efficiency comparison: bulk operations vs individual opt-ins
• Error handling for non-existent assets and non-opted-in accounts

Prerequisites

• LocalNet running (via algokit localnet start)

Run This Example

From the repository root:

cd examples
npm run example algorand_client/11-asset-manager.ts

Code

View source on GitHub

11-asset-manager.ts

/**
 * Example: Asset Manager
 *
 * This example demonstrates the AssetManager functionality for querying
 * asset information and performing bulk opt-in/opt-out operations:
 * - algorand.asset.getById() to fetch asset information by asset ID
 * - algorand.asset.getAccountInformation() to get an account's asset holding
 * - algorand.asset.bulkOptIn() to opt into multiple assets at once
 * - algorand.asset.bulkOptOut() to opt out of multiple assets at once
 * - Efficiency comparison: bulk operations vs individual opt-ins
 * - Error handling for non-existent assets and non-opted-in accounts
 *
 * Prerequisites:
 * - LocalNet running (via `algokit localnet start`)
 */

import { AlgorandClient, algo } from '@algorandfoundation/algokit-utils';
import {
  printError,
  printHeader,
  printInfo,
  printStep,
  printSuccess,
  shortenAddress,
} from '../shared/utils.js';

async function main() {
  printHeader('Asset Manager Example');

  // Initialize client and verify LocalNet is running
  const algorand = AlgorandClient.defaultLocalNet();

  try {
    await algorand.client.algod.status();
    printSuccess('Connected to LocalNet');
  } catch (error) {
    printError(
      `Failed to connect to LocalNet: ${error instanceof Error ? error.message : String(error)}`,
    );
    printInfo('Make sure LocalNet is running (e.g., algokit localnet start)');
    return;
  }

  // Step 1: Create and fund test accounts
  printStep(1, 'Create and fund test accounts');
  printInfo('Creating accounts for asset manager demonstrations');

  const creator = algorand.account.random();
  const holder = algorand.account.random();

  printInfo(`\nCreated accounts:`);
  printInfo(`  Creator: ${shortenAddress(creator.addr.toString())}`);
  printInfo(`  Holder: ${shortenAddress(holder.addr.toString())}`);

  // Fund accounts
  await algorand.account.ensureFundedFromEnvironment(creator.addr, algo(20));
  await algorand.account.ensureFundedFromEnvironment(holder.addr, algo(10));

  printSuccess('Created and funded test accounts');

  // Step 2: Create test assets
  printStep(2, 'Create test assets');
  printInfo('Creating multiple assets to demonstrate bulk operations');

  // Create first asset
  const asset1Result = await algorand.send.assetCreate({
    sender: creator.addr,
    total: 1_000_000n,
    decimals: 2,
    assetName: 'Asset Manager Token 1',
    unitName: 'AMT1',
    url: 'https://example.com/amt1',
    manager: creator.addr,
  });
  const asset1Id = asset1Result.assetId;

  // Create second asset
  const asset2Result = await algorand.send.assetCreate({
    sender: creator.addr,
    total: 500_000n,
    decimals: 0,
    assetName: 'Asset Manager Token 2',
    unitName: 'AMT2',
    url: 'https://example.com/amt2',
    manager: creator.addr,
  });
  const asset2Id = asset2Result.assetId;

  // Create third asset
  const asset3Result = await algorand.send.assetCreate({
    sender: creator.addr,
    total: 10_000_000n,
    decimals: 6,
    assetName: 'Asset Manager Token 3',
    unitName: 'AMT3',
    url: 'https://example.com/amt3',
    manager: creator.addr,
  });
  const asset3Id = asset3Result.assetId;

  printInfo(`\nCreated assets:`);
  printInfo(`  Asset 1 (AMT1): ID ${asset1Id}`);
  printInfo(`  Asset 2 (AMT2): ID ${asset2Id}`);
  printInfo(`  Asset 3 (AMT3): ID ${asset3Id}`);

  printSuccess('Test assets created');

  // Step 3: Demonstrate algorand.asset.getById()
  printStep(3, 'Demonstrate algorand.asset.getById() to fetch asset information');
  printInfo('Fetching detailed information about an asset by its ID');

  const assetInfo = await algorand.asset.getById(asset1Id);

  printInfo(`\nAsset information for ID ${asset1Id}:`);
  printInfo(`  Asset ID (index): ${assetInfo.assetId}`);
  printInfo(`  Name: ${assetInfo.assetName}`);
  printInfo(`  Unit Name: ${assetInfo.unitName}`);
  printInfo(`  Total Supply: ${assetInfo.total} (smallest units)`);
  printInfo(`  Decimals: ${assetInfo.decimals}`);
  printInfo(`  Creator: ${shortenAddress(assetInfo.creator.toString())}`);
  printInfo(
    `  Manager: ${assetInfo.manager ? shortenAddress(assetInfo.manager.toString()) : 'none'}`,
  );
  printInfo(
    `  Reserve: ${assetInfo.reserve ? shortenAddress(assetInfo.reserve.toString()) : 'none'}`,
  );
  printInfo(`  Freeze: ${assetInfo.freeze ? shortenAddress(assetInfo.freeze.toString()) : 'none'}`);
  printInfo(
    `  Clawback: ${assetInfo.clawback ? shortenAddress(assetInfo.clawback.toString()) : 'none'}`,
  );
  printInfo(`  Default Frozen: ${assetInfo.defaultFrozen}`);
  printInfo(`  URL: ${assetInfo.url ?? 'none'}`);

  // Show all three assets for comparison
  printInfo(`\nComparing all created assets:`);
  const asset2Info = await algorand.asset.getById(asset2Id);
  const asset3Info = await algorand.asset.getById(asset3Id);

  printInfo(`\n  Asset 1: ${assetInfo.assetName} (${assetInfo.unitName})`);
  printInfo(`    Total: ${assetInfo.total} | Decimals: ${assetInfo.decimals}`);
  printInfo(`  Asset 2: ${asset2Info.assetName} (${asset2Info.unitName})`);
  printInfo(`    Total: ${asset2Info.total} | Decimals: ${asset2Info.decimals}`);
  printInfo(`  Asset 3: ${asset3Info.assetName} (${asset3Info.unitName})`);
  printInfo(`    Total: ${asset3Info.total} | Decimals: ${asset3Info.decimals}`);

  printSuccess('Asset information retrieved');

  // Step 4: Handle case where asset doesn't exist
  printStep(4, 'Handle case where asset does not exist');
  printInfo('Demonstrating error handling for non-existent asset IDs');

  const nonExistentAssetId = 999999999n;
  printInfo(`\nAttempting to fetch asset with ID ${nonExistentAssetId}...`);

  try {
    await algorand.asset.getById(nonExistentAssetId);
    printError('Expected an error but none was thrown!');
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : String(error);
    printInfo(`  Error caught: Asset not found`);
    printInfo(`  Error details: ${errorMessage.slice(0, 80)}...`);
  }

  printSuccess('Non-existent asset handled correctly');

  // Step 5: Demonstrate algorand.asset.bulkOptIn()
  printStep(5, 'Demonstrate algorand.asset.bulkOptIn() to opt into multiple assets at once');
  printInfo('Bulk opt-in is more efficient than individual opt-ins');
  printInfo('Transactions are batched in groups of up to 16');

  const assetIds = [asset1Id, asset2Id, asset3Id];
  printInfo(`\nOpting holder into ${assetIds.length} assets in a single batch...`);

  const bulkOptInResults = await algorand.asset.bulkOptIn(holder.addr, assetIds, {
    suppressLog: true, // Suppress SDK logs for cleaner output
  });

  printInfo(`\nBulk opt-in results:`);
  for (const result of bulkOptInResults) {
    printInfo(`  Asset ${result.assetId}: Transaction ${result.transactionId.slice(0, 20)}...`);
  }

  printInfo(`\nTotal transactions: ${bulkOptInResults.length}`);
  printInfo(`Efficiency: ${assetIds.length} assets opted in with a single method call`);

  printSuccess('Bulk opt-in completed');

  // Step 6: Demonstrate algorand.asset.getAccountInformation()
  printStep(6, 'Demonstrate algorand.asset.getAccountInformation() to get account asset holding');
  printInfo("Fetching holder's asset holding information after opt-in");

  const holdingInfo1 = await algorand.asset.getAccountInformation(holder.addr, asset1Id);

  printInfo(`\nHolder's holding for Asset ${asset1Id}:`);
  printInfo(`  Asset ID: ${holdingInfo1.assetId}`);
  printInfo(`  Balance: ${holdingInfo1.balance} (smallest units)`);
  printInfo(`  Frozen: ${holdingInfo1.frozen}`);

  // Transfer some assets to show non-zero balance
  printInfo(`\nTransferring assets to holder...`);
  await algorand.send.assetTransfer({
    sender: creator.addr,
    receiver: holder.addr,
    assetId: asset1Id,
    amount: 10_000n, // 100 whole tokens (100 * 10^2)
  });
  await algorand.send.assetTransfer({
    sender: creator.addr,
    receiver: holder.addr,
    assetId: asset2Id,
    amount: 500n,
  });

  // Re-fetch holding info
  const holdingInfo1Updated = await algorand.asset.getAccountInformation(holder.addr, asset1Id);
  const holdingInfo2 = await algorand.asset.getAccountInformation(holder.addr, asset2Id);
  const holdingInfo3 = await algorand.asset.getAccountInformation(holder.addr, asset3Id);

  printInfo(`\nUpdated holder balances:`);
  printInfo(
    `  Asset ${asset1Id} (AMT1): ${holdingInfo1Updated.balance} (100 tokens with 2 decimals)`,
  );
  printInfo(`  Asset ${asset2Id} (AMT2): ${holdingInfo2.balance} (500 whole units)`);
  printInfo(`  Asset ${asset3Id} (AMT3): ${holdingInfo3.balance} (no transfers yet)`);

  printSuccess('Account asset information retrieved');

  // Step 7: Handle case where account not opted in
  printStep(7, 'Handle case where account is not opted in');
  printInfo('Demonstrating error handling when querying for assets not opted in');

  // Create a new account that hasn't opted in to any assets
  const nonOptedAccount = algorand.account.random();
  await algorand.account.ensureFundedFromEnvironment(nonOptedAccount.addr, algo(1));

  printInfo(`\nQuerying asset holding for account that hasn't opted in...`);

  try {
    await algorand.asset.getAccountInformation(nonOptedAccount.addr, asset1Id);
    printError('Expected an error but none was thrown!');
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : String(error);
    printInfo(`  Error caught: Account not opted in to asset`);
    printInfo(`  Error details: ${errorMessage.slice(0, 80)}...`);
  }

  printSuccess('Non-opted-in account handled correctly');

  // Step 8: Compare bulk operations vs individual opt-ins
  printStep(8, 'Show how bulk operations are more efficient than individual opt-ins');
  printInfo('Comparing the approaches for clarity');

  printInfo(`\nIndividual opt-in approach (NOT RECOMMENDED for multiple assets):`);
  printInfo(`  // Requires 3 separate transactions and 3 API calls`);
  printInfo(`  await algorand.send.assetOptIn({ sender, assetId: asset1Id })`);
  printInfo(`  await algorand.send.assetOptIn({ sender, assetId: asset2Id })`);
  printInfo(`  await algorand.send.assetOptIn({ sender, assetId: asset3Id })`);

  printInfo(`\nBulk opt-in approach (RECOMMENDED):`);
  printInfo(`  // Single method call, transactions batched in groups of 16`);
  printInfo(`  await algorand.asset.bulkOptIn(account, [asset1Id, asset2Id, asset3Id])`);

  printInfo(`\nEfficiency benefits:`);
  printInfo(`  - Single method call for any number of assets`);
  printInfo(`  - Automatic batching (up to 16 transactions per group)`);
  printInfo(`  - Reduced code complexity`);
  printInfo(`  - Better error handling with clear result mapping`);

  printSuccess('Efficiency comparison demonstrated');

  // Step 9: Prepare for bulk opt-out by transferring assets back
  printStep(9, 'Prepare for bulk opt-out');
  printInfo('Before opting out, all asset balances must be zero');
  printInfo('Transferring all held assets back to creator');

  // Transfer assets back
  const currentBalance1 = await algorand.asset.getAccountInformation(holder.addr, asset1Id);
  const currentBalance2 = await algorand.asset.getAccountInformation(holder.addr, asset2Id);

  if (currentBalance1.balance > 0n) {
    await algorand.send.assetTransfer({
      sender: holder.addr,
      receiver: creator.addr,
      assetId: asset1Id,
      amount: currentBalance1.balance,
    });
    printInfo(
      `  Transferred ${currentBalance1.balance} units of Asset ${asset1Id} back to creator`,
    );
  }

  if (currentBalance2.balance > 0n) {
    await algorand.send.assetTransfer({
      sender: holder.addr,
      receiver: creator.addr,
      assetId: asset2Id,
      amount: currentBalance2.balance,
    });
    printInfo(
      `  Transferred ${currentBalance2.balance} units of Asset ${asset2Id} back to creator`,
    );
  }

  // Verify zero balances
  const finalBalance1 = await algorand.asset.getAccountInformation(holder.addr, asset1Id);
  const finalBalance2 = await algorand.asset.getAccountInformation(holder.addr, asset2Id);
  const finalBalance3 = await algorand.asset.getAccountInformation(holder.addr, asset3Id);

  printInfo(`\nVerified zero balances:`);
  printInfo(`  Asset ${asset1Id}: ${finalBalance1.balance}`);
  printInfo(`  Asset ${asset2Id}: ${finalBalance2.balance}`);
  printInfo(`  Asset ${asset3Id}: ${finalBalance3.balance}`);

  printSuccess('Ready for bulk opt-out');

  // Step 10: Demonstrate algorand.asset.bulkOptOut()
  printStep(10, 'Demonstrate algorand.asset.bulkOptOut() to opt out of multiple assets at once');
  printInfo('Bulk opt-out validates zero balances by default (ensureZeroBalance: true)');

  const optOutAssetIds = [asset1Id, asset2Id, asset3Id];
  printInfo(`\nOpting holder out of ${optOutAssetIds.length} assets in a single batch...`);

  const bulkOptOutResults = await algorand.asset.bulkOptOut(holder.addr, optOutAssetIds, {
    ensureZeroBalance: true, // Default - validates balances before opting out
    suppressLog: true,
  });

  printInfo(`\nBulk opt-out results:`);
  for (const result of bulkOptOutResults) {
    printInfo(`  Asset ${result.assetId}: Transaction ${result.transactionId.slice(0, 20)}...`);
  }

  printInfo(`\nTotal transactions: ${bulkOptOutResults.length}`);
  printInfo(`Efficiency: ${optOutAssetIds.length} assets opted out with a single method call`);

  // Verify opt-out
  printInfo(`\nVerifying holder is no longer opted in...`);
  for (const assetId of optOutAssetIds) {
    try {
      await algorand.asset.getAccountInformation(holder.addr, assetId);
      printError(`Holder should not be opted in to asset ${assetId}!`);
    } catch {
      printInfo(`  Asset ${assetId}: Confirmed not opted in`);
    }
  }

  printSuccess('Bulk opt-out completed');

  // Step 11: Demonstrate error handling for bulk opt-out with non-zero balance
  printStep(11, 'Demonstrate error handling: bulk opt-out with non-zero balance');
  printInfo('bulkOptOut throws an error if ensureZeroBalance is true and balance is non-zero');

  // First, opt back in to an asset and transfer some tokens
  await algorand.send.assetOptIn({
    sender: holder.addr,
    assetId: asset1Id,
  });
  await algorand.send.assetTransfer({
    sender: creator.addr,
    receiver: holder.addr,
    assetId: asset1Id,
    amount: 100n,
  });

  printInfo(`\nHolder has balance of 100 for Asset ${asset1Id}`);
  printInfo(`Attempting bulk opt-out with ensureZeroBalance: true...`);

  try {
    await algorand.asset.bulkOptOut(holder.addr, [asset1Id], {
      ensureZeroBalance: true,
    });
    printError('Expected an error but none was thrown!');
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : String(error);
    printInfo(`  Error caught: Non-zero balance prevents opt-out`);
    printInfo(`  Error details: ${errorMessage.slice(0, 100)}...`);
  }

  // Clean up - transfer back and opt out
  await algorand.send.assetTransfer({
    sender: holder.addr,
    receiver: creator.addr,
    assetId: asset1Id,
    amount: 100n,
  });
  await algorand.send.assetOptOut({
    sender: holder.addr,
    assetId: asset1Id,
    creator: creator.addr,
    ensureZeroBalance: true,
  });

  printSuccess('Error handling demonstrated');

  // Step 12: Summary
  printStep(12, 'Summary - Asset Manager API');
  printInfo('The AssetManager provides efficient asset operations:');
  printInfo('');
  printInfo('algorand.asset.getById(assetId):');
  printInfo('  - Fetches complete asset information by ID');
  printInfo('  - Returns: AssetInformation object with all asset properties');
  printInfo('  - Properties: assetId, assetName, unitName, total, decimals,');
  printInfo('    creator, manager, reserve, freeze, clawback, defaultFrozen, url');
  printInfo('');
  printInfo('algorand.asset.getAccountInformation(account, assetId):');
  printInfo("  - Fetches an account's holding for a specific asset");
  printInfo('  - Returns: AccountAssetInformation object');
  printInfo('  - Properties: assetId, balance, frozen');
  printInfo('  - Throws if account is not opted in to the asset');
  printInfo('');
  printInfo('algorand.asset.bulkOptIn(account, assetIds, options?):');
  printInfo('  - Opts an account into multiple assets at once');
  printInfo('  - Batches transactions in groups of 16 (max atomic group size)');
  printInfo('  - Returns: Array of { assetId, transactionId }');
  printInfo('  - More efficient than individual assetOptIn calls');
  printInfo('');
  printInfo('algorand.asset.bulkOptOut(account, assetIds, options?):');
  printInfo('  - Opts an account out of multiple assets at once');
  printInfo('  - ensureZeroBalance: true (default) validates balances first');
  printInfo('  - Batches transactions in groups of 16');
  printInfo('  - Returns: Array of { assetId, transactionId }');
  printInfo('  - Automatically fetches asset creators for opt-out transactions');
  printInfo('');
  printInfo('Bulk operation benefits:');
  printInfo('  - Single method call for any number of assets');
  printInfo('  - Automatic batching for optimal efficiency');
  printInfo('  - Consistent result format with asset ID to transaction ID mapping');
  printInfo('  - Built-in validation for safe opt-out operations');

  // Clean up - destroy test assets
  await algorand.send.assetDestroy({ sender: creator.addr, assetId: asset1Id });
  await algorand.send.assetDestroy({ sender: creator.addr, assetId: asset2Id });
  await algorand.send.assetDestroy({ sender: creator.addr, assetId: asset3Id });

  printSuccess('Asset Manager 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