Skip to content

Create Publication

We are looking for publications that demonstrate building dApps or smart contracts!
See the full list of Gitcoin bounties that are eligible for rewards.

Inner transactions

Issuing Transactions from an Application

When a smart contract is deployed to the Algorand blockchain it is assigned a unique identifier, called the app id. Additionally, every smart contract has a unique Algorand address that is generated from this specific ID. The address allows the smart contract to function as an escrow account. To see the specific address of the smart contract the goal app info command can be used.

% ./goal app info --app-id 1 -d data
Application ID:        1
Application account:   WCS6TVPJRBSARHLN2326LRU5BYVJZUKI2VJ53CAWKYYHDE455ZGKANWMGM
Creator:               VJG4SF5O4DUQDK7MQYHHSJ2HB5LEAB3OQMM2XCUM7OVQKWC7E4GSNCM4FQ
Approval hash:         IYRFKZVCHBQW3UNKEWRQPMCXSXH4TDF4K74EAH65UYLJ5R5JQGVZJ4FF2M
Clear hash:            P7GEWDXXW5IONRW6XRIRVPJCT2XXEQGOBGG65VJPBUOYZEJCBZWTPHS3VQ
Max global byteslices: 0
Max global integers:   1
Max local byteslices:  0
Max local integers:    0

The application address will be shown as the Application account. This address can also be retrieved with the SDKs or calculated by using the following code and the smart contract’s application id.

# app ID of 1’s address
python3 -c "import algosdk.encoding as e; print(e.encode_address(e.checksum(b'appID'+(1).to_bytes(8, 'big'))))"
WCS6TVPJRBSARHLN2326LRU5BYVJZUKI2VJ53CAWKYYHDE455ZGKANWMGM

Inner transactions

To fund this account, any other account in the Algorand network can send algos to the specified account. In order for funds to leave the smart contract, the logic within the contract must submit an inner transaction. In addition, the smart contract’s logic must return true. A smart contract can issue up to a total of 256 inner transactions with one call. If any of these transactions fail, then the smart contract will also fail. Groups of transactions can also be made using inner transactions, which are primarily used when calling other smart contracts that will verify the calling groups transactions. Inner transactions support all the same transaction types as a regular account can make. To generate an inner transaction the itxn_begin, itxn_field, itxn_next and itxn_submit opcodes are used. The itxn_begin opcode signifies the beginning of an inner transaction. The itxn_field opcode is used to set specific transaction properties. The itxn_next opcode moves to the next transaction in the same group as the previous, and the itxn_submit opcode is used to submit the transaction or transaction group. As an example, the following contract code generates a simple payment transaction.

        # ...
        InnerTxnBuilder.Begin(),
        InnerTxnBuilder.SetFields(
            {
                TxnField.type_enum: TxnType.Payment,
                TxnField.amount: Int(5000),
                TxnField.receiver: Txn.sender(),
            }
        ),
        InnerTxnBuilder.Submit(),
        # ...
        # The `Sender` for the above is implied to be Global.current_application_address().
        # If a different sender is needed, it'd have to be an account that has been rekeyed to
        # the application address.
Snippet Source

itxn_begin

int pay
itxn_field TypeEnum

int 1000000
itxn_field Amount

txn Sender
itxn_field Receiver

itxn_submit
Snippet Source

Fees for these transactions are paid by the smart contract and are set automatically to the minimum transaction fee. Inner transaction fees are eligible for fee pooling similar to any other transaction. This allows either the application call or any other transaction in a group of transactions to pay the fee for inner transactions. Inner transactions are evaluated during AVM execution, allowing changes to be visible within the contract. For example, if the ‘balance’ opcode is used before and after a ‘pay’ transaction is submitted, the balance change would be visible to the executing contract.

Note

Inner transactions also have access to the Sender field. It is not required to set this field as all inner transactions default the sender to the contract address. If another account is rekeyed to the smart contract address, setting sender to the address that has been rekeyed allows the contract to spend from that account. The recipient of an inner transaction must be in the accounts array. Additionally, if the sender of an inner transaction is not the contract, the sender must also be in the accounts array.

Note

Clear state programs do not support creating inner transactions. However, clear state programs can be called by an inner transaction.

Allowed transaction properties

Since TEAL 6, all transaction types can be used within inner transactions. If you're using TEAL 5 you will only be able to make payment and asset transfer transactions, with some properties such as RekeyTo not being allowed.

Asset transfer

If a smart contract wishes to transfer an asset it holds or needs to opt into an asset this can be done with an asset transfer inner transaction.

        # ...
        InnerTxnBuilder.Begin(),
        InnerTxnBuilder.SetFields(
            {
                TxnField.type_enum: TxnType.AssetTransfer,
                TxnField.asset_amount: Int(5000),
                TxnField.asset_receiver: Txn.sender(),
                TxnField.xfer_asset: Txn.assets[0],
            }
        ),
        # ...
        InnerTxnBuilder.Submit(),
Snippet Source

itxn_begin

int axfer
itxn_field TypeEnum

txn Assets 0
itxn_field XferAsset

txn Accounts 1
itxn_field AssetReceiver

txn ApplicationArgs 3
btoi
itxn_field AssetAmount

itxn_submit
Snippet Source

Note that the asset must be in the assets array. If the smart contract is opting into an asset, the contract would send 0 units of the asset to itself. In this case, the receiver could be set to the global CurrentApplicationAddress.

Asset freeze

A smart contract can freeze any asset, where the smart contract is the freeze address. This can be done with the following TEAL.

        # ...
        InnerTxnBuilder.Begin(),
        InnerTxnBuilder.SetFields(
            {
                TxnField.type_enum: TxnType.AssetFreeze,
                TxnField.freeze_asset: Txn.assets[0],
                TxnField.freeze_asset_account: Txn.accounts[1],
                TxnField.freeze_asset_frozen: Int(1),
            }
        ),
        InnerTxnBuilder.Submit(),
        # ...
Snippet Source

itxn_begin

int afrz
itxn_field TypeEnum

txn Assets 0
itxn_field FreezeAsset

txn Accounts 1
itxn_field FreezeAssetAccount

// Flip the current account frozen state
txn Accounts 1
txn Assets 0
asset_holding_get AssetFrozen
assert
!
itxn_field FreezeAssetFrozen

itxn_submit
Snippet Source

Asset revoke

A smart contract can revoke or clawback any asset where the smart contract address is specified as the asset clawback address.

        # ...
        InnerTxnBuilder.Begin(),
        InnerTxnBuilder.SetFields(
            {
                TxnField.type_enum: TxnType.AssetTransfer,
                TxnField.asset_receiver: Global.current_application_address(),
                # AssetSender is _only_ used in the case of clawback
                # Sender is implied to be current_application_address
                TxnField.asset_sender: Txn.accounts[1],
                TxnField.asset_amount: Int(1000),
            }
        ),
        InnerTxnBuilder.Submit(),
        # ...
Snippet Source

itxn_begin

int axfer
itxn_field TypeEnum

txn Assets 0
itxn_field XferAsset

// Any amount lower or equal to their holding can be revoked
// Here we use the accounts entire asset balance
txn Accounts 1
txn Assets 0
asset_holding_get AssetBalance
assert
itxn_field AssetAmount

txn Accounts 1
itxn_field AssetSender

global CurrentApplicationAddress
itxn_field AssetReceiver

itxn_submit
Snippet Source

Asset create

Assets can also be created by a smart contract. To create an asset with an inner transaction use the following contract code.

        # ...
        InnerTxnBuilder.Begin(),
        InnerTxnBuilder.SetFields(
            {
                TxnField.type_enum: TxnType.AssetConfig,
                TxnField.config_asset_total: Int(1000000),
                TxnField.config_asset_decimals: Int(3),
                TxnField.config_asset_unit_name: Bytes("oz"),
                TxnField.config_asset_name: Bytes("Gold"),
                TxnField.config_asset_url: Bytes("https://gold.rush"),
                TxnField.config_asset_manager: Global.current_application_address(),
                TxnField.config_asset_reserve: Global.current_application_address(),
                TxnField.config_asset_freeze: Global.current_application_address(),
                TxnField.config_asset_clawback: Global.current_application_address(),
            }
        ),
        InnerTxnBuilder.Submit(),
        # ...
Snippet Source

itxn_begin

int acfg
itxn_field TypeEnum

byte "Demo Asset"
itxn_field ConfigAssetName

byte "DA"
itxn_field ConfigAssetUnitName

int 100
itxn_field ConfigAssetTotal

int 2
itxn_field ConfigAssetDecimals

global CurrentApplicationAddress
dupn 3
itxn_field ConfigAssetManager
itxn_field ConfigAssetReserve
itxn_field ConfigAssetFreeze
itxn_field ConfigAssetClawback

itxn_submit
Snippet Source

In this example, a simple asset is created. Using the itxn CreatedAssetID opcode after the transaction is submitted allows the contract to get the asset id of the newly created asset.

Asset configuration

As with all assets, the mutable addresses can be changed using contract code similar to the code below.

        # ...
        InnerTxnBuilder.Begin(),
        InnerTxnBuilder.SetFields(
            {
                TxnField.type_enum: TxnType.AssetConfig,
                TxnField.config_asset: Txn.assets[0],
                TxnField.config_asset_manager: Txn.sender(),
                TxnField.config_asset_reserve: Txn.sender(),
                TxnField.config_asset_freeze: Txn.sender(),
                TxnField.config_asset_clawback: Txn.sender(),
            }
        ),
        InnerTxnBuilder.Submit(),
        # ...
Snippet Source

itxn_begin

int acfg
itxn_field TypeEnum

txn Assets 0
itxn_field ConfigAsset

global CurrentApplicationAddress
dupn 3
itxn_field ConfigAssetManager
itxn_field ConfigAssetReserve
itxn_field ConfigAssetFreeze
itxn_field ConfigAssetClawback

itxn_submit
Snippet Source

Warning

Note that when changing one address, all others must be reset or they will be cleared. Cleared addresses will be locked forever.

Delete an asset

Assets managed by the contract can also be deleted. This can be done with the following contract code.

        # ...
        InnerTxnBuilder.Begin(),
        InnerTxnBuilder.SetFields(
            {
                TxnField.type_enum: TxnType.AssetConfig,
                TxnField.config_asset: Txn.assets[0],
            }
        ),
        InnerTxnBuilder.Submit(),
        # ...
Snippet Source

itxn_begin

int acfg
itxn_field TypeEnum

txn Assets 0
itxn_field ConfigAsset

itxn_submit
Snippet Source

Grouped inner transaction

A smart contract can make inner transactions consisting of grouped transactions. The following example groups a payment transaction with a call to another smart contract.

        # This returns a `MaybeValue`, see pyteal docs
        addr := AppParam.address(Int(1234)),
        Assert(addr.hasValue()),
        # ...
        InnerTxnBuilder.Begin(),
        InnerTxnBuilder.SetFields(
            {
                TxnField.type_enum: TxnType.Payment,
                TxnField.receiver: addr.value(),
                TxnField.amount: Int(1000000),
            }
        ),
        InnerTxnBuilder.Next(),  # This indicates we're moving to constructing the next txn in the group
        InnerTxnBuilder.SetFields(
            {
                TxnField.type_enum: TxnType.ApplicationCall,
                TxnField.application_id: Int(1234),
                TxnField.on_completion: OnComplete.NoOp,
                # Note this is _not_ using the ABI to call the
                # method in the other app
                TxnField.application_args: [Bytes("buy")],
            }
        ),
        InnerTxnBuilder.Submit(),
        # ...
Snippet Source

itxn_begin

int pay
itxn_field TypeEnum

int 1000000
itxn_field Amount

int 123
app_params_get AppAddress
assert
itxn_field Receiver

itxn_next

int appl
itxn_field TypeEnum

int 123
itxn_field ApplicationID

int NoOp
itxn_field OnCompletion

byte "buy"
itxn_field ApplicationArgs

itxn_submit
Snippet Source

All inner transactions will be stored as inner transactions within the outer application transaction. These can be accessed by getting the transaction id as normal and looking for the inner-txns header in the transaction response.

Contract To Contract Calls

With the release of TEAL 6 (AVM 1.1), Smart Contracts may issue inner transactions that invoke other Smart Contracts. This allows for composability across applications but comes with some limitations.

  • An application may not call itself, even indirectly. This is referred to as re-entrancy and is explicitly forbidden.
  • An application may only call into other applications up to a stack depth of 8. In other words if app calls (->) look like 1->2->3->4->5->6->7->8, App 8 may not call another application. This would violate the stack depth limit.
  • An application may issue up to 256 inner transactions to increase its budget (max budget of 179.2k even for a group size of 1), but the max call budget is shared for all applications in the group. Meaning you can't have two app calls in the same group that both try to issue 256 inner app calls.
  • An application of program version 6 or above may not call contracts with a program version 3 or below. This limitation protects an older application from unexpected behavior introduced in newer program versions.

Application call

A smart contract can call other smart contracts using any of the OnComplete types. This allows a smart contract to create, opt in, close out, clear state, delete, or just call (NoOp) other smart contracts. To call an existing smart contract the following contract code can be used.

        # ...
        InnerTxnBuilder.Begin(),
        InnerTxnBuilder.SetFields(
            {
                TxnField.type_enum: TxnType.ApplicationCall,
                TxnField.application_id: Int(1234),
                TxnField.on_completion: OnComplete.NoOp,
            }
        ),
        InnerTxnBuilder.Submit(),
        # ...
Snippet Source

itxn_begin

int appl
itxn_field TypeEnum

txn Applications 1
itxn_field ApplicationID

int NoOp
itxn_field OnCompletion

itxn_submit
Snippet Source

Composability

When writing smart contracts that call other applications or expect to be called via Inner Transactions, an important consideration is composability.

With the finalization of the ABI an API may be defined for an application. This allows contracts to be written to take advantage of the ABI to provide structured calls to other applications.

Additionally, when validating transactions, using relative position of transactions instead of absolute position will help to allow behavior to be composed.

Since TEAL 6, all created assets and apps are available to be accessed by application calls in the same group which allows more dynamic behavior. For example an application can be created via Inner Transaction then funded immediately in the same transaction group since we have access to the created application id and address.