Resource Usage

Algorand smart contracts do not have default access to the entire blockchain ledger. Therefore, when a smart contract method needs to access resources such as accounts, assets (ASA), other applications (smart contracts), or box references, these must be provided through the reference array during invocation. This page explains what reference arrays are, why they are necessary, the different ways to provide them, and includes a series of code examples.

Note

Starting with AVM v12, an alternative called the Access List is available, which differs from traditional reference arrays (sometimes called resource lists) by being mutually exclusive, requiring explicit resource listing instead of cross-product access, and allowing up to 16 entries for more flexibility. For details, see the Access List section.

Resource Availability

When smart contracts are executed, they may require data stored within the blockchain ledger for evaluation. For this data (resource) to be accessible to the smart contract, it must be made available. When you say, ‘A resource is available to the smart contract,’ it means that the reference array, referencing the resource, was provided during the invocation and execution of a smart contract method that requires access to that resource.

What are Reference Arrays?

There are four reference arrays:

• Accounts: Reference to Algorand accounts
• Assets: Reference to Algorand Standard Assets
• Applications: Reference to an external smart contract
• Boxes: Reference to Boxes created within the smart contract

Including necessary resources in the appropriate arrays enables the smart contract to access the necessary data during execution, such as reading an account’s Algo balance or examining the immutable properties of an ASA. This page explains how data access is managed by a smart contract in version 9 or later of the Algorand Virtual Machine (AVM). For details on earlier AVM versions, refer to the TEAL specification

By default, the reference arrays are empty, with the exception of the accounts and applications arrays. The Accounts array contains the transaction sender’s address, and the Applications array contains the called smart contract ID.

Types of Resources to Make Available

Using these four reference arrays, you can make the following six unique ledger items available during smart contract execution: account, asset, application, account+asset, account+application, and application+box. Accounts and Applications can contain sublists with potentially large datasets. For example, an account may opt into an extensive set of assets or applications which store the user’s local state. Additionally, smart contracts can store potentially unlimited boxes of data within the ledger. For instance, a smart contract might create a unique box of arbitrary data for each user. These combinations, account+asset, account+application, and application+box, represent cases where you need to access data that exists at the intersection of two resources. For example:

• Account+Asset: To read what the balance of an asset is for a specific account, both the asset and the account reference must be included in the respective reference arrays.
• Account+Application: To access an account’s local state of an application, both the account and the application reference must be included in the respective reference arrays.
• Application+Box: To retrieve data from a specific box created by an application, the application and the box reference must be included in the respective reference arrays.

Inner Transaction Resource Availability

When a smart contract executes an inner transaction to call another smart contract, the inner contract inherits all resource availability from the top-level contract. Here’s an example:

Let’s say contract A sends an inner transaction that calls a method in contract B. If contract B’s method requires access to asset XYZ, you only need to provide the asset reference when calling contract A, while still properly referencing contract B in the Applications array. This makes asset XYZ available to contract B through the resource availability inherited from contract A.

Reference Array Constraints and Requirements

There are certain limitations and requirements you need to consider when providing references in the reference arrays:

• The four reference arrays are limited to a combined total of eight values per application transaction. This limit excludes the default references to the transaction sender’s address and the called smart contract ID.
• The accounts array can contain no more than four accounts.
• The values passed into the reference arrays can change per application transaction.
• When accessing one of the sublists of items, the application transaction must include both the top-level item and the nested list item within the same call. For example, to read an ASA balance for a specific account, the account and the asset must be present in the respective accounts and asset arrays for the given transaction.

Reason for limited Access to Resources

To maintain a high level of performance, the AVM restricts how much of the ledger can be viewed within a single contract execution. This is implemented with reference arrays passed with each application call transaction, defining the specific ledger items available during execution. These arrays are the Account, Asset, Application, and Boxes arrays.

Resource Sharing

Resources are shared across transactions within the same atomic group. This means that if there are two app calls calling different smart contracts in the same atomic group, the two smart contracts share resource availability.

For example, say you have two smart contract call transactions grouped together, transaction #1 and transaction #2. Transaction #1 has asset 123456 in its assets array, and transaction #2 has asset 555555 in its assets array. Both assets are available to both smart contract calls during evaluation.

When accessing a sublist resource (account+asa, account+application local state, application+box), both resources must be in the same transaction’s arrays. For example, you cannot have account A in transaction #1 and asset Z in transaction #2 and then try to get the balance of asset Z for account A. Asset Z and account A must be in the same application transaction. If asset Z and account A are in transaction #1’s arrays, A’s balance for Z is also available to transaction #2 during evaluation.

Because Algorand supports grouping up to 16 transactions simultaneously, this pushes the available resources up to 8x16 or 128 items if all 16 transactions are application transactions.

If an application transaction is grouped with other types of transactions, other resources will be made available to the smart contract called in the application transaction. For example, if an application transaction is grouped with a payment transaction, the payment transaction’s sender and receiver accounts are available to the smart contract.

If the CloseRemainderTo field is set, that account will also be available to the smart contract. The table below summarizes what each transaction type adds to resource availability.

Transaction	Transaction Type	Availability Notes
Payment	pay	txn.Sender, txn.Receiver, and txn.CloseRemainderTo (if set)
Key Registration	keyreg	txn.Sender
Asset Config/Create	acfg	txn.Sender, txn.ConfigAsset, and the txn.ConfigAsset holding of txn.Sender
Asset Transfer	axfer	txn.Sender, txn.AssetReceiver, txn.AssetSender (if set), txnAssetCloseTo (if set), txn.XferAsset, and the txn.XferAsset holding of each of those accounts
Asset Freeze	afrz	txn.Sender, txn.FreezeAccount, txn.FreezeAsset, and the txn.FreezeAsset holding of txn.FreezeAccount. The txn.FreezeAsset holding of txn.Sender is not made available

Note

If any application or asset is created within a group of transactions, it is an available resource as long as it is created before it is accessed.

Different Ways to Provide References

There are different ways you can provide resource references when calling smart contract methods:

1. Automatic Resource Population: Automatically input resource references in the reference(foreign) arrays with automatic resource population using the AlgoKit Utils library (TypeScript and Python)

   Note

   Automatic resource population first sends a dry-run transaction to the Algorand node to determine the necessary resources. Then it populates the reference arrays with the required resources and sends the actual transaction. Therefore, it sends two requests to algod for each transaction. Developers should consider the impact on their app if they require sending a large number of transactions.

2. Reference Types: Pass reference types as arguments to contract methods. (You can only do this for Accounts, Assets, and Applications and not Boxes.)

3. Manually Input: Manually input resource references in the reference(foreign) arrays

Account Reference Example

Here is a simple smart contract with two methods that read the balance of an account. This smart contract requires the account reference to be provided during invocation.

Algorand TypeScript

import { Contract, Account, readonly } from '@algorandfoundation/algorand-typescript'
import { Address } from '@algorandfoundation/algorand-typescript/arc4'

/**
 * A contract that demonstrates how to use resource usage in a contract using an account reference
 */
export default class ReferenceAccount extends Contract {
  /**
   * Returns the balance of the account
   * @returns The balance of the account
   */
  @readonly
  public getAccountBalance() {
    const address = new Address('R3J76MDPEXQEWBV2LQ6FLQ4PYC4QXNHHPIL2BX2KSFU4WUNJJMDBTLRNEM')
    const addressBytes = address.bytes
    const account = Account(addressBytes)

    return account.balance
  }

  /**
   * Returns the balance of the account
   * @param account The account to get the balance of
   * @returns The balance of the account
   */
  @readonly
  public getAccountBalanceWithArgument(account: Account) {
    return account.balance
  }
}

Source

Algorand Python

from algopy import Account, ARC4Contract, UInt64
from algopy.arc4 import abimethod

"""
A contract that demonstrates how to use resource usage in a contract using an account reference
"""


class ReferenceAccount(ARC4Contract):
    """
    Returns the balance of the account
    @returns The balance of the account
    """

    @abimethod
    def get_account_balance(self) -> UInt64:
        return Account(
            "WMHF4FLJNKY2BPFK7YPV5ID6OZ7LVDB2B66ZTXEAMLL2NX4WJZRJFVX66M"
        ).balance  # Replace with your account address

    """
    Returns the balance of the account
    @param account The account to get the balance of
    @returns The balance of the account
    """

    @abimethod
    def get_account_balance_with_argument(self, account: Account) -> UInt64:
        return account.balance

Source

Here are three different ways you can provide the account reference when calling a contract method using the AlgoKit Utils library.

Method #1: Automatic Resource Population

TypeScript

// Configure automatic resource population per app call
const result1 = await referenceAccountAppClient.send.getAccountBalance({
  args: {},
})

console.log('Method #1 Account Balance', result1.return)

// Or set the default value for populateAppCallResources to true globally and apply to all app calls
Config.configure({
  populateAppCallResources: true,
})

const result2 = await referenceAccountAppClient.send.getAccountBalance({
  args: {},
})

console.log('Method #1 Account Balance', result2.return)

Source

Python

# Configure automatic resource population per app call
result1 = reference_account_app_client.send.get_account_balance(
    send_params=SendParams(populate_app_call_resources=True)
)

print("Method #1 Account Balance", result1.abi_return)

# Or set the default value for populate_app_call_resources to true globally and apply to all app calls
config.config.configure(populate_app_call_resources=True)

result2 = reference_account_app_client.send.get_account_balance()

print("Method #1 Account Balance", result2.abi_return)

Source

Method #2: Using Reference Types

TypeScript

// Include the account reference in the app call argument to be populated automatically
const result = await referenceAccountAppClient.send.getAccountBalanceWithArgument({
  args: {
    account: referenceAccount.addr.toString(),
  },
})

console.log('Method #2 Account Balance', result.return)

Source

Python

# Include the account reference in the app call argument to be populated automatically
result = reference_account_app_client.send.get_account_balance_with_argument(
    args=GetAccountBalanceWithArgumentArgs(account=reference_account.address)
)

print("Method #2 Account Balance", result.abi_return)

Source

Method #3: Manually Input

TypeScript

// Include the account reference in the accountReferences array to be populated manually
const result = await referenceAccountAppClient.send.getAccountBalance({
  args: {},
  accountReferences: [referenceAccount],
})

console.log('Method #3 Account Balance', result.return)

Source

Python

# Include the account reference in the account_references array to be populated manually
result = reference_account_app_client.send.get_account_balance(
    params=CommonAppCallParams(account_references=[reference_account.address])
)

print("Method #3 Account Balance", result.abi_return)

Source

Asset Reference Example

Here is a simple smart contract with two methods that read the total supply of an asset(ASA). This smart contract requires the asset reference to be provided during invocation.

Algorand TypeScript

import { Contract, Asset, readonly } from '@algorandfoundation/algorand-typescript'

/**
 * A contract that demonstrates how to use resource usage in a contract using an asset reference
 */
export default class ReferenceAsset extends Contract {
  /**
   * Returns the total supply of the asset
   * @returns The total supply of the asset
   */
  @readonly
  public getAssetTotalSupply() {
    return Asset(1005).total // Replace with your asset id
  }

  /**
   * Returns the total supply of the asset
   * @param asset The asset to get the total supply of
   * @returns The total supply of the asset
   */
  @readonly
  public getAssetTotalSupplyWithArgument(asset: Asset) {
    return asset.total
  }
}

Source

Algorand Python

from algopy import ARC4Contract, Asset, UInt64
from algopy.arc4 import abimethod

"""
A contract that demonstrates how to use resource usage in a contract using an asset reference
"""


class ReferenceAsset(ARC4Contract):
    """
    Returns the total supply of the asset
    @returns The total supply of the asset
    """

    @abimethod
    def get_asset_total_supply(self) -> UInt64:
        return Asset(1185).total  # Replace with your asset id

    """
    Returns the total supply of the asset
    @param asset The asset to get the total supply of
    @returns The total supply of the asset
    """

    @abimethod
    def get_asset_total_supply_with_arg(self, asset: Asset) -> UInt64:
        return asset.total

Source

Here are three different ways you can provide the asset reference when calling a contract method using the AlgoKit Utils library.

Method #1: Automatic Resource Population

TypeScript

// Configure automatic resource population per app call
const result1 = await referenceAssetAppClient.send.getAssetTotalSupply({
  args: {},
  populateAppCallResources: true,
})

console.log('Method #1 Asset Total Supply', result1.return)

// Or set the default value for populateAppCallResources to true globally and apply to all app calls
Config.configure({
  populateAppCallResources: true,
})

const result2 = await referenceAssetAppClient.send.getAssetTotalSupply({
  args: {},
})

console.log('Method #1 Asset Total Supply', result2.return)

Source

Python

# Configure automatic resource population per app call
result1 = reference_asset_client.send.get_asset_total_supply(
    send_params=SendParams(populate_app_call_resources=True),
)

print("Method #1 Asset Total Supply:", result1.abi_return)

# Or set the default value for populate_app_call_resources to true globally and apply to all app calls
config.config.configure(
    populate_app_call_resources=True,
)

result2 = reference_asset_client.send.get_asset_total_supply()

print("Method #1 Asset Total Supply:", result2.abi_return)

Source

Method #2: Using Reference Types

TypeScript

// Include the account reference in the app call argument to be populated automatically
const result = await referenceAssetAppClient.send.getAssetTotalSupplyWithArgument({
  args: {
    asset: referenceAssetId,
  },
})

console.log('Method #2 Asset Total Supply', result.return)

Source

Python

# Include the account reference in the app call argument to be populated automatically
result = reference_asset_client.send.get_asset_total_supply_with_arg(
    args=GetAssetTotalSupplyWithArgArgs(asset=reference_asset_id),
)

print("Method #2 Asset Total Supply:", result.abi_return)

Source

Method #3: Manually Input

TypeScript

// Include the account reference in the accountReferences array to be populated
const result = await referenceAssetAppClient.send.getAssetTotalSupply({
  args: {},
  assetReferences: [referenceAssetId],
})

console.log('Method #3 Asset Total Supply', result.return)

Source

Python

# Include the asset reference in the asset_references array to be populated
result = reference_asset_client.send.get_asset_total_supply(
    params=CommonAppCallParams(asset_references=[reference_asset_id]),
)

print("Method #3 Asset Total Supply:", result.abi_return)

Source

App Reference Example

Here is a simple smart contract named ApplicationReference with two methods that call the increment method in the Counter smart contract via inner transaction. The ApplicationReference smart contract requires the Counter application reference to be provided during invocation.

Algorand TypeScript

import { Contract, Application, GlobalState, Uint64, itxn, arc4 } from '@algorandfoundation/algorand-typescript'
import type { uint64 } from '@algorandfoundation/algorand-typescript'

/**
 * A contract that increments a counter
 */
export class Counter extends Contract {
  public counter = GlobalState<uint64>({ initialValue: Uint64(0) })

  /**
   * Increments the counter and returns the new value
   * @returns The new counter value
   */
  public increment(): uint64 {
    this.counter.value = this.counter.value + 1
    return this.counter.value
  }
}

/**
 * A contract that demonstrates how to use resource usage in a contract using an asset reference
 */
export default class ReferenceApp extends Contract {
  /**
   * Calls the increment method on another Counter app with a hardcoded app ID
   * @returns The incremented counter value from the inner call
   */
  public incrementViaInner(): uint64 {
    const app = Application(1717) // Replace with your application id

    // Call the increment method on the Counter application
    const appCallTxn = itxn
      .applicationCall({
        appId: app.id,
        // Use methodSelector to get the ABI selector for the increment method
        appArgs: [arc4.methodSelector('increment()uint64')],
        fee: 0,
      })
      .submit()

    // Decode the ABI return value from the transaction logs
    // The ABI return value is in the last log with a prefix for the ABI return format
    return arc4.decodeArc4<uint64>(appCallTxn.lastLog, 'log')
  }

  /**
   * Calls the increment method on another Counter app passed as an argument
   * @param app The application to call
   * @returns The incremented counter value from the inner call
   */
  public incrementViaInnerWithArg(app: Application): uint64 {
    // Call the increment method on the provided Counter application
    const appCallTxn = itxn
      .applicationCall({
        appId: app.id,
        // Use methodSelector to get the ABI selector for the increment method
        appArgs: [arc4.methodSelector('increment()uint64')],
        fee: 0,
      })
      .submit()

    // Decode the ABI return value from the transaction logs
    // The ABI return value is in the last log with a prefix for the ABI return format
    return arc4.decodeArc4<uint64>(appCallTxn.lastLog, 'log')
  }
}

Source

Algorand Python

from algopy import Application, ARC4Contract, UInt64, arc4
from algopy.arc4 import abimethod

"""
A contract that increments a counter
"""


class Counter(ARC4Contract):
    def __init__(self) -> None:
        self.counter = UInt64(0)

    """
    Increments the counter and returns the new value
    @returns The new counter value
    """

    @abimethod
    def increment(self) -> UInt64:
        self.counter += 1
        return self.counter


"""
A contract that demonstrates how to use resource usage in a contract using an asset reference
"""


class ReferenceApp(ARC4Contract):
    """
    Calls the increment method on another Counter app with a hardcoded app ID
    @returns The incremented counter value from the inner call
    """

    @abimethod
    def increment_via_inner(self) -> UInt64:
        app = Application(1717)  # Replace with your application id

        counter_result, call_txn = arc4.abi_call(
            Counter.increment,
            fee=0,
            app_id=app,
        )
        return counter_result

    """
    Calls the increment method on another Counter app passed as an argument
    @param app The application to call
    @returns The incremented counter value from the inner call
    """

    @abimethod
    def increment_via_inner_with_arg(self, app: Application) -> UInt64:
        # Call the increment method on the provided Counter application
        counter_result, call_txn = arc4.abi_call(Counter.increment, fee=0, app_id=app)
        return counter_result

Source

Here are three different ways you can provide the app reference when calling a contract method using the AlgoKit Utils library.

Method #1: Automatic Resource Population

TypeScript

// Configure automatic resource population per app call
const result1 = await referenceAppAppClient.send.incrementViaInner({
  args: {},
  populateAppCallResources: true,
})

console.log('Method #1 Increment via inner', result1.return)

// Or set the default value for populateAppCallResources to true globally and apply to all app calls
Config.configure({
  populateAppCallResources: true,
})

const result2 = await referenceAppAppClient.send.incrementViaInner({
  args: {},
  extraFee: microAlgos(1000), // additional fee to cover the inner app call
})

console.log('Method #1 Increment via inner', result2.return)

Source

Python

# Configure automatic resource population per app call
result1 = reference_app_client.send.increment_via_inner(
    send_params=SendParams(populate_app_call_resources=True),
)

print("Method #1 Increment via inner:", result1.abi_return)

# Or set the default value for populate_app_call_resources to true globally and apply to all app calls
config.config.configure(
    populate_app_call_resources=True,
)

result2 = reference_app_client.send.increment_via_inner(
    params=CommonAppCallParams(
        extra_fee=AlgoAmount(micro_algo=1000)
    ),  # additional fee to cover the inner app call
)

print("Method #1 Increment via inner:", result2.abi_return)

Source

Method #2: Using Reference Types

TypeScript

// Include the app reference in the app call argument to be populated automatically
const result = await referenceAppAppClient.send.incrementViaInnerWithArg({
  args: {
    app: 1717n,
  },
  extraFee: microAlgos(1000), // additional fee to cover the inner app call
})

console.log('Method #2 Increment via inner', result.return)

Source

Python

# Include the app reference in the app call argument to be populated automatically
result = reference_app_client.send.increment_via_inner_with_arg(
    args=IncrementViaInnerWithArgArgs(app=1717),
    params=CommonAppCallParams(
        extra_fee=AlgoAmount(micro_algo=1000)
    ),  # additional fee to cover the inner app call
)

print("Method #2 Increment via inner:", result.abi_return)

Source

Method #3: Manually Input

TypeScript

// Include the app reference in the appReferences array to be populated
const result = await referenceAppAppClient.send.incrementViaInner({
  args: {},
  appReferences: [1717n],
  extraFee: microAlgos(1000), // additional fee to cover the inner app call
})

console.log('Method #3 Increment via inner', result.return)

Source

Python

# Include the app reference in the app_references array to be populated
result = reference_app_client.send.increment_via_inner(
    params=CommonAppCallParams(
        app_references=[1717],
        extra_fee=AlgoAmount(
            micro_algo=1000
        ),  # additional fee to cover the inner app call
    ),
)

print("Method #3 Increment via inner:", result.abi_return)

Source

Account + Asset Example

Here is a simple smart contract with two methods that read the balance of an ASA in an account. This smart contract requires both the asset reference and the account reference to be provided during invocation.

Algorand TypeScript

import { Contract, readonly, Account, Asset, assert } from '@algorandfoundation/algorand-typescript'
import { Address } from '@algorandfoundation/algorand-typescript/arc4'

/**
 * A contract that demonstrates how to reference both accounts and assets in a smart contract
 */
export default class ReferenceAccountAsset extends Contract {
  /**
   * Returns the balance of a specific asset in a hardcoded account
   * @returns The asset balance of the account
   */
  @readonly
  public getAssetBalance() {
    const address = new Address('R3J76MDPEXQEWBV2LQ6FLQ4PYC4QXNHHPIL2BX2KSFU4WUNJJMDBTLRNEM') // Replace with your account address
    const addressBytes = address.bytes
    const account = Account(addressBytes)
    const asset = Asset(1472) // Replace with your asset ID

    assert(account.isOptedIn(asset), 'Account is not opted in to the asset')

    return asset.balance(account)
  }

  /**
   * Returns the balance of a specific asset in a provided account
   * @param account The account to check the asset balance for
   * @param asset The asset to check the balance of
   * @returns The asset balance of the account
   */
  @readonly
  public getAssetBalanceWithArg(account: Account, asset: Asset) {
    assert(account.isOptedIn(asset), 'Account is not opted in to the asset')
    // Get the asset balance
    return asset.balance(account)
  }
}

Source

Algorand Python

from algopy import Account, ARC4Contract, Asset, UInt64
from algopy.arc4 import abimethod

"""
A contract that demonstrates how to reference both accounts and assets in a smart contract
"""


class ReferenceAccountAsset(ARC4Contract):
    """
    Returns the balance of a specific asset in a hardcoded account
    @returns The asset balance of the account
    """

    @abimethod
    def get_asset_balance(self) -> UInt64:
        acct = Account(
            "WMHF4FLJNKY2BPFK7YPV5ID6OZ7LVDB2B66ZTXEAMLL2NX4WJZRJFVX66M"
        )  # Replace with your account address
        asset = Asset(1185)  # Replace with your asset id

        assert acct.is_opted_in(asset), "Account is not opted in to the asset"

        return asset.balance(acct)

    """
    Returns the balance of a specific asset in a provided account
    @param account The account to check the asset balance for
    @param asset The asset to check the balance of
    @returns The asset balance of the account
    """

    @abimethod
    def get_asset_balance_with_arg(self, acct: Account, asset: Asset) -> UInt64:
        assert acct.is_opted_in(asset), "Account is not opted in to the asset"
        # Get the asset balance
        return asset.balance(acct)

Source

Here are three different ways you can provide both the account reference and the asset reference when calling a contract method using the AlgoKit Utils library.

Method #1: Automatic Resource Population

TypeScript

// Configure automatic resource population per app call
const result1 = await accountAssetReferenceAppClient.send.getAssetBalance({
  args: {},
  populateAppCallResources: true,
})

console.log('Method #1 Asset Balance', result1)

// Or set the default value for populateAppCallResources to true globally and apply to all app calls
Config.configure({
  populateAppCallResources: true,
})

const result2 = await accountAssetReferenceAppClient.send.getAssetBalance({
  args: {},
})

console.log('Method #1 Asset Balance', result2)

Source

Python

# Configure automatic resource population per app call
result1 = account_asset_reference_app_client.send.get_asset_balance(
    send_params=SendParams(populate_app_call_resources=True)
)

print("Method #1 Asset Balance", result1.abi_return)

# Or set the default value for populate_app_call_resources to true globally and apply to all app calls
config.config.configure(populate_app_call_resources=True)

result2 = account_asset_reference_app_client.send.get_asset_balance()

print("Method #1 Asset Balance", result2.abi_return)

Source

Method #2: Using Reference Types

TypeScript

// Include the account and asset references in the app call arguments to be populated automatically
const result = await accountAssetReferenceAppClient.getAssetBalanceWithArg({
  args: {
    account: 'R3J76MDPEXQEWBV2LQ6FLQ4PYC4QXNHHPIL2BX2KSFU4WUNJJMDBTLRNEM',
    asset: referenceAssetId,
  },
})

console.log('Method #2 Asset Balance', result)

Source

Python

# Include the account and asset references in the app call arguments to be populated automatically
result = account_asset_reference_app_client.send.get_asset_balance_with_arg(
    args=GetAssetBalanceWithArgArgs(
        acct="R3J76MDPEXQEWBV2LQ6FLQ4PYC4QXNHHPIL2BX2KSFU4WUNJJMDBTLRNEM",
        asset=reference_asset_id,
    )
)

print("Method #2 Asset Balance", result.abi_return)

Source

Method #3: Manually Input

TypeScript

// Manually provide both account and asset references in the respective arrays
const result = await accountAssetReferenceAppClient.getAssetBalance({
  args: {},
  accountReferences: ['R3J76MDPEXQEWBV2LQ6FLQ4PYC4QXNHHPIL2BX2KSFU4WUNJJMDBTLRNEM'],
  assetReferences: [referenceAssetId],
})

console.log('Method #3 Asset Balance', result)

Source

Python

# Manually provide both account and asset references in the respective arrays
result = account_asset_reference_app_client.send.get_asset_balance(
    params=CommonAppCallParams(
        account_references=[
            "R3J76MDPEXQEWBV2LQ6FLQ4PYC4QXNHHPIL2BX2KSFU4WUNJJMDBTLRNEM"
        ],
        asset_references=[reference_asset_id],
    )
)

print("Method #3 Asset Balance", result.abi_return)

Source

Account + Application Example

Here is a simple smart contract named AccountAndAppReference with two methods that read the local state my_counter of an account in the Counter smart contract. The AccountAndAppReference smart contract requires both the Counter application reference and the account reference to be provided during invocation.

Algorand TypeScript

import {
  Contract,
  op,
  abimethod,
  Account,
  Application,
  LocalState,
  Txn,
  Global,
  assert,
  Bytes,
} from '@algorandfoundation/algorand-typescript'
import type { uint64 } from '@algorandfoundation/algorand-typescript'
import { Address, readonly } from '@algorandfoundation/algorand-typescript/arc4'

/**
 * A contract that maintains a per-account counter in local state
 * Accounts must opt in to use the counter
 */
export class MyCounter extends Contract {
  // Define a local state variable for the counter
  public myCounter = LocalState<uint64>({ key: 'my_counter' })

  /**
   * Initialize the counter when an account opts in
   */
  @abimethod({ allowActions: 'OptIn' })
  public optIn(): void {
    this.myCounter(Txn.sender).value = 0
  }

  /**
   * Increment the counter for the sender and return its new value
   * @returns The new counter value
   */
  public incrementMyCounter(): uint64 {
    assert(Txn.sender.isOptedIn(Global.currentApplicationId), 'Account must opt in to contract first')

    this.myCounter(Txn.sender).value = this.myCounter(Txn.sender).value + 1

    return this.myCounter(Txn.sender).value
  }
}

/**
 * A contract that demonstrates how to reference accounts and applications
 * to access local state from external contracts
 */
export default class ReferenceAccountApp extends Contract {
  /**
   * Get the counter value from another account's local state with hardcoded values
   * @returns The counter value or 0 if it doesn't exist
   */
  @readonly
  public getMyCounter(): uint64 {
    const address = new Address('WMHF4FLJNKY2BPFK7YPV5ID6OZ7LVDB2B66ZTXEAMLL2NX4WJZRJFVX66M')
    const addressBytes = address.bytes
    const account = Account(addressBytes)
    const app = Application(1717) // Replace with your application id

    // Check if the counter value exists in the account's local state for the specified app
    const [value, hasValue] = op.AppLocal.getExUint64(account, app, Bytes('my_counter'))

    if (!hasValue) {
      return 0
    }

    return value
  }

  /**
   * Get the counter value from another account's local state with provided parameters
   * @param account The account to check
   * @param app The application to query
   * @returns The counter value or 0 if it doesn't exist
   */
  @readonly
  public getMyCounterWithArg(account: Account, app: Application): uint64 {
    // Check if the counter value exists in the account's local state for the specified app
    const [value, hasValue] = op.AppLocal.getExUint64(account, app, Bytes('my_counter'))

    if (!hasValue) {
      return 0
    }

    return value
  }
}

Source

Algorand Python

from algopy import (
    Account,
    Application,
    ARC4Contract,
    Global,
    LocalState,
    Txn,
    UInt64,
    op,
)
from algopy.arc4 import abimethod

"""
A contract that maintains a per-account counter in local state
Accounts must opt in to use the counter
"""


class MyCounter(ARC4Contract):
    def __init__(self) -> None:
        # Define a local state variable for the counter
        self.my_counter = LocalState(UInt64)

    """
    Initialize the counter when an account opts in
    """

    @abimethod(allow_actions=["OptIn"])
    def opt_in(self) -> None:
        self.my_counter[Txn.sender] = UInt64(0)

    """
    Increment the counter for the sender and return its new value
    @returns The new counter value
    """

    @abimethod
    def increment_my_counter(self) -> UInt64:
        assert Txn.sender.is_opted_in(Global.current_application_id)

        self.my_counter[Txn.sender] += 1
        return self.my_counter[Txn.sender]


"""
A contract that demonstrates how to reference accounts and applications
to access local state from external contracts
"""


class ReferenceAccountApp(ARC4Contract):
    """
    Get the counter value from another account's local state with hardcoded values
    @returns The counter value or 0 if it doesn't exist
    """

    @abimethod
    def get_my_counter(self) -> UInt64:
        acct = Account(
            "WMHF4FLJNKY2BPFK7YPV5ID6OZ7LVDB2B66ZTXEAMLL2NX4WJZRJFVX66M"
        )  # Replace with your account address
        app = Application(1717)  # Replace with your application id

        # Check if the counter value exists in the account's local state for the specified app
        my_count, exist = op.AppLocal.get_ex_uint64(acct, app, b"my_counter")
        if not exist:
            return UInt64(0)
        return my_count

    """
    Get the counter value from another account's local state with provided parameters
    @param account The account to check
    @param app The application to query
    @returns The counter value or 0 if it doesn't exist
    """

    @abimethod
    def get_my_counter_with_arg(self, acct: Account, app: Application) -> UInt64:
        # Check if the counter value exists in the account's local state for the specified app
        my_count, exist = op.AppLocal.get_ex_uint64(acct, app, b"my_counter")
        if not exist:
            return UInt64(0)
        return my_count

Source

Here are three different ways you can provide both the account reference and the application reference when calling a contract method using the AlgoKit Utils library.

Method #1: Automatic Resource Population

TypeScript

// Configure automatic resource population per app call
const result1 = await referenceAccountAppAppClient.send.getMyCounter({
  args: {},
  populateAppCallResources: true,
})

console.log('Method #1 My Counter', result1.return)

// Or set the default value for populateAppCallResources to true globally and apply to all app calls
Config.configure({
  populateAppCallResources: true,
})

const result2 = await referenceAccountAppAppClient.send.getMyCounter({
  args: {},
})

console.log('Method #1 My Counter', result2.return)

Source

Python

# Configure automatic resource population per app call
result1 = reference_account_app_app_client.send.get_my_counter(
    send_params=SendParams(populate_app_call_resources=True)
)

print("Method #1 My Counter", result1.abi_return)

# Or set the default value for populate_app_call_resources to true globally and apply to all app calls
config.config.configure(populate_app_call_resources=True)

result2 = reference_account_app_app_client.send.get_my_counter()

print("Method #1 My Counter", result2.abi_return)

Source

Method #2: Using Reference Types

TypeScript

// Include the account and app references in the app call arguments to be populated automatically
const result = await referenceAccountAppAppClient.send.getMyCounterWithArg({
  args: {
    account: randomAccountA.addr.toString(),
    app: 1717n, // Using the default app ID from the contract
  },
})

console.log('Method #2 My Counter', result.return)

Source

Python

# Include the account and app references in the app call arguments to be populated automatically
result = reference_account_app_app_client.send.get_my_counter_with_arg(
    args=GetMyCounterWithArgArgs(
        acct=account_a.address,
        app=1717,  # Using the default app ID from the contract
    )
)

print("Method #2 My Counter", result.abi_return)

Source

Method #3: Manually Input

TypeScript

// Manually provide both account and app references in the respective arrays
const result = await referenceAccountAppAppClient.send.getMyCounter({
  args: {},
  accountReferences: [randomAccountA.addr],
  appReferences: [1717n], // Using the default app ID from the contract
})

console.log('Method #3 My Counter', result.return)

Source

Python

# Manually provide both account and app references in the respective arrays
result = reference_account_app_app_client.send.get_my_counter(
    CommonAppCallParams(
        account_references=[account_a.address],
        app_references=[1717],  # Using the default app ID from the contract
    )
)

print("Method #3 My Counter", result.abi_return)

Source

Application + Box Reference Example

Here is a simple smart contract with a methods that increments the counter value stored in a BoxMap. Each box uses box_counter + account address as its key and stores the counter as its value. This smart contract requires the box reference to be provided during invocation.

Algorand TypeScript

import {
  Contract,
  readonly,
  Account,
  BoxMap,
  Txn,
  Global,
  gtxn,
  assert,
  Uint64,
  GlobalState,
  contract,
} from '@algorandfoundation/algorand-typescript'
import type { uint64 } from '@algorandfoundation/algorand-typescript'

/**
 * A contract that uses box storage to maintain a counter for each account
 * Each account needs to pay for the Minimum Balance Requirement (MBR) for their box
 * Constants for box storage are stored in global state
 */
@contract({ stateTotals: { globalUints: 4 } })
export default class ReferenceAppBox extends Contract {
  // Define constants for box storage in global state
  public keyLength = GlobalState<uint64>({ initialValue: Uint64(32 + 19) }) // Account address (32 bytes) + key prefix overhead (19 bytes)
  public valueLength = GlobalState<uint64>({ initialValue: Uint64(8) }) // uint64 (8 bytes)
  public boxSize = GlobalState<uint64>() // Calculated in constructor
  public boxMbr = GlobalState<uint64>() // Calculated in constructor

  // Create a box map to store counter values per account
  public accountBoxCounter = BoxMap<Account, uint64>({ keyPrefix: 'counter' })

  /**
   * Initialize calculated values in constructor
   */
  public constructor() {
    super()
    // Calculate the total box size and MBR in constructor
    this.boxSize.value = this.keyLength.value + this.valueLength.value
    this.boxMbr.value = Uint64(2500) + this.boxSize.value * Uint64(400) // Base MBR + (size * per-byte cost)
  }

  /**
   * Increments the counter for the transaction sender
   * Requires a payment transaction to cover the MBR for the box
   * @param payMbr Payment transaction covering the box MBR
   * @returns The new counter value
   */
  @readonly
  public incrementBoxCounter(payMbr: gtxn.PaymentTxn): uint64 {
    // Verify the payment covers the MBR cost and is sent to the contract
    assert(payMbr.amount === this.boxMbr.value, 'Payment must cover the box MBR')
    assert(payMbr.receiver === Global.currentApplicationAddress, 'Payment must be to the contract')

    const [counter, hasCounter] = this.accountBoxCounter(Txn.sender).maybe()

    if (hasCounter) {
      // Increment existing counter
      this.accountBoxCounter(Txn.sender).value = counter + 1
      return counter + 1
    } else {
      // Initialize new counter to 1
      this.accountBoxCounter(Txn.sender).value = Uint64(1)
      return Uint64(1)
    }
  }

  /**
   * Gets the current counter value for the transaction sender
   * @returns The current counter value or 0 if not set
   */
  @readonly
  public getBoxCounter(): uint64 {
    const [counter, hasCounter] = this.accountBoxCounter(Txn.sender).maybe()

    if (hasCounter) {
      return counter
    }

    return 0
  }

  /**
   * Gets the current counter value for any account
   * @param account The account to check
   * @returns The current counter value or 0 if not set
   */
  @readonly
  public getBoxCounterForAccount(account: Account): uint64 {
    const [counter, hasCounter] = this.accountBoxCounter(account).maybe()

    if (hasCounter) {
      return counter
    }

    return 0
  }

  /**
   * Returns the MBR cost for creating a box
   * @returns The MBR cost in microAlgos
   */
  @readonly
  public getBoxMbr(): uint64 {
    return this.boxMbr.value
  }

  /**
   * Returns all the box size configuration values
   * @returns A tuple containing [keyLength, valueLength, boxSize, boxMbr]
   */
  @readonly
  public getBoxConfiguration(): [uint64, uint64, uint64, uint64] {
    return [this.keyLength.value, this.valueLength.value, this.boxSize.value, this.boxMbr.value]
  }

  /**
   * Updates the box size configuration values
   * @param newKeyLength The new key length
   * @param newValueLength The new value length
   */
  @readonly
  public updateBoxConfiguration(newKeyLength: uint64, newValueLength: uint64): void {
    this.keyLength.value = newKeyLength
    this.valueLength.value = newValueLength

    // Recalculate derived values
    this.boxSize.value = this.keyLength.value + this.valueLength.value
    this.boxMbr.value = Uint64(2500) + this.boxSize.value * Uint64(400)
  }
}

Source

Algorand Python

from algopy import Account, ARC4Contract, BoxMap, Global, GlobalState, Txn, UInt64, gtxn
from algopy.arc4 import abimethod

"""
A contract that uses box storage to maintain a counter for each account
Each account needs to pay for the Minimum Balance Requirement (MBR) for their box
Constants for box storage are stored in global state
"""

COUNTER_BOX_KEY_LENGTH = 32 + 19
COUNTER_BOX_VALUE_LENGTH = 8


class ReferenceAppBox(ARC4Contract):
    def __init__(self) -> None:
        # Define constants for box storage in global state
        self.key_length = GlobalState(
            UInt64(COUNTER_BOX_KEY_LENGTH)
        )  # Account address (32 bytes) + key prefix overhead (19 bytes)
        self.value_length = GlobalState(
            UInt64(COUNTER_BOX_VALUE_LENGTH)
        )  # uint64 (8 bytes)
        self.box_size = GlobalState(UInt64)  # Calculated in constructor
        self.box_mbr = GlobalState(UInt64)  # Calculated in constructor

        # Create a box map to store counter values per account
        self.account_box_counter = BoxMap(Account, UInt64, key_prefix="counter")

    @abimethod(create="require")
    def create(self) -> None:
        self.box_size.value = self.key_length.value + self.value_length.value
        self.box_mbr.value = UInt64(2_500) + self.box_size.value * UInt64(
            400
        )  # Base MBR + (size * per-byte cost)

    """
    Increments the counter for the transaction sender
    Requires a payment transaction to cover the MBR for the box
    @param payMbr Payment transaction covering the box MBR
    @returns The new counter value
    """

    @abimethod
    def increment_box_counter(self, pay_mbr: gtxn.PaymentTransaction) -> UInt64:
        # Verify the payment covers the MBR cost and is sent to the contract
        assert pay_mbr.amount == self.box_mbr.value, "Payment must cover the box MBR"
        assert (
            pay_mbr.receiver == Global.current_application_address
        ), "Payment must be to the contract"

        counter, has_counter = self.account_box_counter.maybe(Txn.sender)

        if has_counter:
            self.account_box_counter[Txn.sender] += 1
            return self.account_box_counter[Txn.sender]
        else:
            self.account_box_counter[Txn.sender] = UInt64(1)
            return UInt64(1)

    """
    Gets the current counter value for the transaction sender
    @returns The current counter value or 0 if not set
    """

    @abimethod(readonly=True)
    def get_box_counter(self) -> UInt64:
        counter, has_counter = self.account_box_counter.maybe(Txn.sender)
        if has_counter:
            return counter
        return UInt64(0)

    """
    Gets the current counter value for any account
    @param account The account to check
    @returns The current counter value or 0 if not set
    """

    @abimethod(readonly=True)
    def get_box_counter_for_account(self, account: Account) -> UInt64:
        counter, has_counter = self.account_box_counter.maybe(account)
        if has_counter:
            return counter
        return UInt64(0)

    """
    Returns the MBR cost for creating a box
    @returns The MBR cost in microAlgos
    """

    @abimethod(readonly=True)
    def get_box_mbr(self) -> UInt64:
        return self.box_mbr.value

    """
    Returns all the box size configuration values
    @returns A tuple containing [keyLength, valueLength, boxSize, boxMbr]
    """

    @abimethod(readonly=True)
    def get_box_configuration(self) -> tuple[UInt64, UInt64, UInt64, UInt64]:
        return (
            self.key_length.value,
            self.value_length.value,
            self.box_size.value,
            self.box_mbr.value,
        )

    """
    Updates the box size configuration values
    @param newKeyLength The new key length
    @param newValueLength The new value length
    """

    @abimethod
    def update_box_configuration(
        self, new_key_length: UInt64, new_value_length: UInt64
    ) -> None:
        self.key_length.value = new_key_length
        self.value_length.value = new_value_length

        # Recalculate derived values
        self.box_size.value = self.key_length.value + self.value_length.value
        self.box_mbr.value = UInt64(2_500) + self.box_size.value * UInt64(400)

Source

Here are two different ways you can provide the box reference when calling a contract method using the AlgoKit Utils library.

Method #1: Automatic Resource Population

TypeScript

// Create payment for MBR
const payMbr = await algorand.createTransaction.payment({
  amount: microAlgos(boxMBR),
  sender: randomAccountA,
  receiver: counterAppAddress,
})

// Method 1: Using populateAppCallResources in sendParams
const response1 = await referenceAppBoxAppClient.send.incrementBoxCounter({
  args: {
    payMbr: payMbr,
  },
  sender: randomAccountA,
  populateAppCallResources: true,
})

console.log('Method #2 Box Counter (explicit)', response1.return)

// Method 2: Configure globally
// Set the default value for populateAppCallResources to true once and apply to all contract invocations
Config.configure({ populateAppCallResources: true })

// Create another payment for MBR
const payMbr2 = await algorand.createTransaction.payment({
  amount: microAlgos(boxMBR),
  sender: randomAccountA,
  receiver: counterAppAddress,
})

// With global configuration, we don't need to specify populateAppCallResources
const response2 = await referenceAppBoxAppClient.send.incrementBoxCounter({
  args: {
    payMbr: payMbr2,
  },
  sender: randomAccountA,
})

console.log('Method #1 Box Counter (global)', response2.return)

Source

Python

# Create payment for MBR
pay_mbr = algorand_client.create_transaction.payment(
    PaymentParams(
        sender=account_a.address,
        receiver=counter_app_address,
        amount=AlgoAmount(micro_algo=box_mbr),
    )
)

# Method 1: Using populate_app_call_resources in send_params
response1 = reference_app_box_app_client.send.increment_box_counter(
    args=IncrementBoxCounterArgs(pay_mbr=pay_mbr),
    params=CommonAppCallParams(sender=account_a.address),
    send_params=SendParams(populate_app_call_resources=True),
)

print("Method #1 Box Counter (explicit):", response1.abi_return)

# Method 2: Configure globally
# Set the default value for populate_app_call_resources to true once and apply to all contract invocations
config.config.configure(populate_app_call_resources=True)

# Create another payment for MBR
pay_mbr2 = algorand_client.create_transaction.payment(
    PaymentParams(
        sender=account_a.address,
        receiver=counter_app_address,
        amount=AlgoAmount(micro_algo=box_mbr),
    )
)

# With global configuration, we don't need to specify populate_app_call_resources
response2 = reference_app_box_app_client.send.increment_box_counter(
    args=IncrementBoxCounterArgs(pay_mbr=pay_mbr2),
    params=CommonAppCallParams(sender=account_a.address),
)

print("Method #1 Box Counter (global):", response2.abi_return)

Source

Method #2: Manually Input

TypeScript

const boxPrefix = 'counter' // box identifier prefix
const encoder = new TextEncoder()
const boxPrefixBytes = encoder.encode(boxPrefix) // UInt8Array of boxPrefix
const publicKey = randomAccountB.addr.publicKey

// Create the box reference
const boxReference = new Uint8Array([...boxPrefixBytes, ...publicKey])

// Create payment for MBR
const payMbr = await algorand.createTransaction.payment({
  amount: microAlgos(boxMBR),
  sender: randomAccountB,
  receiver: counterAppAddress,
})

// Call the smart contract with manually specified box reference
const response = await referenceAppBoxAppClient.send.incrementBoxCounter({
  args: {
    payMbr: payMbr,
  },
  boxReferences: [boxReference],
  sender: randomAccountB,
})

console.log('Method #2 Box Counter', response.return)

Source

Python

box_prefix = b"counter"  # box identifier prefix
public_key = account_b.public_key

# Create the box reference
box_reference = box_prefix + public_key

# Create payment for MBR
pay_mbr = algorand_client.create_transaction.payment(
    PaymentParams(
        sender=account_b.address,
        receiver=counter_app_address,
        amount=AlgoAmount(micro_algo=box_mbr),
    )
)

# Call the smart contract with manually specified box reference
response = reference_app_box_app_client.send.increment_box_counter(
    args=IncrementBoxCounterArgs(pay_mbr=pay_mbr),
    params=CommonAppCallParams(
        sender=account_b.address, box_references=[box_reference]
    ),
)

print("Method #2 Box Counter:", response.abi_return)

Source

Access List: A Mutually Exclusive Alternative to Reference Arrays

Starting with AVM v12 in consensus v41, the Access List, txn.Access or al, provides a more flexible way to specify resources. It serves as a mutually exclusive alternative to the traditional reference arrays: Accounts, Assets, Applications, Boxes. You cannot use both in the same transaction. Providing an Access List means no foreign arrays are used, and vice versa.

Key Features

• Simple Resources:

  • Address (d): References an account (e.g., for balance checks).
  • Asset (s): References an ASA (e.g., for params like total supply).
  • App (p): References another application (e.g., for global state reads).

• Complex Resources (for sublist access):

  • Holding (h): Explicitly references an account’s holding of a specific asset (account + asset ID).
  • Locals (l): References an account’s local state for a specific app (account + app ID).
  • Box (b): References a box with an app index and box name (e.g., for reading/writing box data).

• Empty BoxRefs: Use {} for boxes where the App ID is unknown or defaults to the current app.

• Limits: Up to 16 entries via consensus parameter MaxAppAccess, higher than the 8 total for foreign references.

• Cross-Product vs. Explicit Access: Traditional foreign arrays enable “cross-product” access (e.g., all combinations of listed accounts and assets for holdings). Access Lists require explicit listing of each needed resource (e.g., specify each holding individually), but allow more granular control and higher limits without combinatorial explosion.

Access List Examples

These examples show how to structure the al (Access List) field in an application transaction JSON. In practice, the SDKs set these fields for you.

Note

High-level examples for integrating Access Lists in languages like TypeScript and Python are coming soon. In the meantime, refer to low-level transaction structures.

Simple Resources

Address Reference

This references a single account, e.g., for balance checks.

{
  "al": [
    {
      "d": "BOBBYB3QD5QGQ27EBYHHUT7J76EWXKFOSF2NNYYYI6EOAQ5D3M2YW2UGEA"
    }
  ]
}

Asset Reference

This references a single ASA, e.g., for params like total supply.

{
  "al": [
    {
      "s": 1010
    }
  ]
}

Application Reference

This references another application, e.g., for global state reads.

{
  "al": [
    {
      "p": 1042
    }
  ]
}

Complex Resources

Holding Reference

This explicitly references an account’s holding of a specific asset. Requires including the address and asset.

{
  "al": [
    {
      "d": "BOBBYB3QD5QGQ27EBYHHUT7J76EWXKFOSF2NNYYYI6EOAQ5D3M2YW2UGEA"
    },
    {
      "s": 1010
    },
    {
      "h": {
        "d": 1,
        "s": 2
      }
    }
  ]
}

Explanation: The holding (h) points to the 1st address (d:1) and 2nd asset (s:2) in the list.

Locals Reference

This references an account’s local state for a specific app. Requires including the app and address.

{
  "al": [
    {
      "p": 1042
    },
    {
      "d": "BOBBYB3QD5QGQ27EBYHHUT7J76EWXKFOSF2NNYYYI6EOAQ5D3M2YW2UGEA"
    },
    {
      "l": {
        "d": 2,
        "p": 1
      }
    }
  ]
}

Box Reference

This references a box with an app index and box name.

{
  "al": [
    {
      "p": 1042
    },
    {
      "b": {
        "i": 1,
        "n": "Ym94TmFtZQ=="
      }
    }
  ]
}

Empty BoxRefs

This provides extra budget without specifying a particular box.

{
  "al": [{}]
}