Transaction Fields and Global Parameters

PyTeal smart contracts can access properties of the current transaction and the state of the blockchain when they are running.

Transaction Fields

Information about the current transaction being evaluated can be obtained using the Txn object using the PyTeal expressions shown below.

Since numerous transaction fields exist, the fields are logically organized into tables by transaction type.

Fields by Transaction Type

Common Fields

Operator

Type

Min Program Version

Notes

Txn.type()

TealType.bytes

2

Txn.type_enum()

TealType.uint64

2

see table below

Txn.sender()

TealType.bytes

2

32 byte address

Txn.fee()

TealType.uint64

2

in microAlgos

Txn.first_valid()

TealType.uint64

2

round number

Txn.first_valid_time()

TealType.uint64

7

UNIX timestamp of block before Txn.first_valid(). Fails if negative

Txn.last_valid()

TealType.uint64

2

round number

Txn.note()

TealType.bytes

2

transaction note in bytes

Txn.lease()

TealType.bytes

2

transaction lease in bytes

Txn.group_index()

TealType.uint64

2

position of this transaction within a transaction group, starting at 0

Txn.tx_id()

TealType.bytes

2

the computed ID for this transaction, 32 bytes

Txn.rekey_to()

TealType.bytes

2

32 byte address

Application Call

Operator

Type

Min Program Version

Notes

Txn.application_id()

TealType.uint64

2

Txn.on_completion()

TealType.uint64

2

Txn.approval_program()

TealType.bytes

2

Txn.global_num_uints()

TealType.uint64

3

Maximum global integers in app schema

Txn.global_num_byte_slices()

TealType.uint64

3

Maximum global byte strings in app schema

Txn.local_num_uints()

TealType.uint64

3

Maximum local integers in app schema

Txn.local_num_byte_slices()

TealType.uint64

3

Maximum local byte strings in app schema

Txn.accounts

TealType.bytes[]

2

Array of accounts available to the application

Txn.assets

TealType.uint64[]

3

Array of assets available to the application

Txn.applications

TealType.uint64[]

3

Array of applications

Txn.clear_state_program()

TealType.bytes

2

Txn.extra_program_pages()

TealType.uint64

4

Number of extra program pages for app

Txn.application_args

TealType.bytes[]

2

Array of application arguments

Txn.created_application_id()

TealType.uint64

5

The ID of the newly created application in this transaction. In v5, only valid on inner transactions. >= v6 works with top-level and inner transactions.

Txn.logs

TealType.bytes[]

5

Array of application logged items. In v5, only valid on inner transactions. >= v6 works with top-level and inner transactions.

Txn.last_log()

TealType.bytes

6

The last message emitted. Empty bytes if none were emitted. Application mode only.

Txn.approval_program_pages()

TealType.bytes[]

7

The pages of the approval program as an array

Txn.clear_state_program_pages()

TealType.bytes[]

7

The pages of a clear state program as an array

Asset Config

Operator

Type

Min Program Version

Notes

Txn.config_asset()

TealType.uint64

2

ID of asset being configured

Txn.config_asset_total()

TealType.uint64

2

Txn.config_asset_decimals()

TealType.uint64

2

Txn.config_asset_default_frozen()

TealType.uint64

2

Txn.config_asset_unit_name()

TealType.bytes

2

Txn.config_asset_name()

TealType.bytes

2

Txn.config_asset_url()

TealType.bytes

2

Txn.config_asset_metadata_hash()

TealType.bytes

2

Txn.config_asset_manager()

TealType.bytes

2

32 byte address

Txn.config_asset_reserve()

TealType.bytes

2

32 byte address

Txn.config_asset_freeze()

TealType.bytes

2

32 byte address

Txn.config_asset_clawback()

TealType.bytes

2

32 byte address

Txn.created_asset_id()

TealType.uint64

5

The ID of the newly created asset in this transaction. In v5, only valid on inner transactions. >= v6 works with top-level and inner transactions.

Asset Freeze

Operator

Type

Min Program Version

Notes

Txn.freeze_asset()

TealType.uint64

2

Txn.freeze_asset_account()

TealType.bytes

2

32 byte address

Txn.freeze_asset_frozen()

TealType.uint64

2

Asset Transfer

Operator

Type

Min Program Version

Notes

Txn.xfer_asset()

TealType.uint64

2

ID of asset being transferred

Txn.asset_amount()

TealType.uint64

2

value in Asset’s units

Txn.asset_sender()

TealType.bytes

2

32 byte address, causes clawback of all value if sender is the clawback

Txn.asset_receiver()

TealType.bytes

2

32 byte address

Txn.asset_close_to()

TealType.bytes

2

32 byte address

Key Registration

Operator

Type

Min Program Version

Notes

Txn.vote_pk()

TealType.bytes

2

32 byte address

Txn.selection_pk()

TealType.bytes

2

32 byte address

Txn.state_proof_pk

TealType.bytes

6

64 byte state proof public key commitment.

Txn.vote_first()

TealType.uint64

2

Txn.vote_last()

TealType.uint64

2

Txn.vote_key_dilution()

TealType.uint64

2

Txn.nonparticipation()

TealType.uint64

5

Marks an account nonparticipating for rewards

Payment

Operator

Type

Min Program Version

Notes

Txn.receiver()

TealType.bytes

2

32 byte address

Txn.amount()

TealType.uint64

2

in microAlgos

Txn.close_remainder_to()

TealType.bytes

2

32 byte address

Transaction Types

The Txn.type_enum() values can be checked using the TxnType enum:

Value

Numerical Value

Type String

Description

TxnType.Unknown

0

unknown

unknown type, invalid

TxnType.Payment

1

pay

payment

TxnType.KeyRegistration

2

keyreg

key registration

TxnType.AssetConfig

3

acfg

asset config

TxnType.AssetTransfer

4

axfer

asset transfer

TxnType.AssetFreeze

5

afrz

asset freeze

TxnType.ApplicationCall

6

appl

application call

Transaction Array Fields

Some of the exposed transaction fields are arrays with the type TealType.uint64[] or TealType.bytes[]. These fields are Txn.application_args, Txn.assets, Txn.accounts, Txn.applications, and InnerTxn.logs.

The length of these array fields can be found using the .length() method, and individual items can be accessed using bracket notation. For example:

Txn.application_args.length() # get the number of application arguments in the transaction
Txn.application_args[0] # get the first application argument
Txn.application_args[1] # get the second application argument

# as of AVM v5, PyTeal expressions can be used to dynamically index into array properties as well
Txn.application_args[Txn.application_args.length() - Int(1)] # get the last application argument

Special case: Txn.accounts and Txn.applications

The Txn.accounts and Txn.applications arrays are special cases. Normal arrays in PyTeal are 0-indexed, but these are 1-indexed with special values at index 0.

For the accounts array, Txn.accounts[0] is always equivalent to Txn.sender().

For the applications array, Txn.applications[0] is always equivalent to Txn.application_id().

IMPORTANT: Since these arrays are 1-indexed, their lengths are handled differently. For example, if Txn.accounts.length() or Txn.applications.length() is 2, then indexes 0, 1, and 2 will be present. In fact, the index 0 will always evaluate to the special values above, even when length() is 0.

Atomic Transfer Groups

Atomic Transfers are irreducible batch transactions that allow groups of transactions to be submitted at one time. If any of the transactions fail, then all the transactions will fail. PyTeal allows programs to access information about the transactions in an atomic transfer group using the Gtxn object. This object acts like a list of TxnObject, meaning all of the above transaction fields on Txn are available on the elements of Gtxn. For example:

Gtxn[0].sender() # get the sender of the first transaction in the atomic transfer group
Gtxn[1].receiver() # get the receiver of the second transaction in the atomic transfer group

# as of AVM v3, PyTeal expressions can be used to dynamically index into Gtxn as well
Gtxn[Txn.group_index() - Int(1)].sender() # get the sender of the previous transaction in the atomic transfer group

Gtxn is zero-indexed and the maximum size of an atomic transfer group is 16. The size of the current transaction group is available as Global.group_size(). A standalone transaction will have a group size of 1.

To find the current transaction’s index in the transfer group, use Txn.group_index(). If the current transaction is standalone, it’s group index will be 0.

Inner Transactions

Note

Inner transactions are only available in AVM version 5 or higher.

Inner transactions can be created and submitted with expressions from the InnerTxnBuilder class. The properties of the most recently submitted inner transaction can be accessed using the InnerTxn object. This object is an instance of TxnObject, meaning all of the above transaction fields on Txn are available on InnerTxn as well.

Global Parameters

Information about the current state of the blockchain can be obtained using the following Global expressions:

Operator

Type

Min Program Version

Notes

Global.min_txn_fee()

TealType.uint64

2

in microAlgos

Global.min_balance()

TealType.uint64

2

in microAlgos

Global.max_txn_life()

TealType.uint64

2

number of rounds

Global.zero_address()

TealType.bytes

2

32 byte address of all zero bytes

Global.group_size()

TealType.uint64

2

number of txns in this atomic transaction group, at least 1

Global.logic_sig_version()

TealType.uint64

2

the maximum supported program version

Global.round()

TealType.uint64

2

the current round number

Global.latest_timestamp()

TealType.uint64

2

the latest confirmed block UNIX timestamp

Global.current_application_id()

TealType.uint64

2

the ID of the current application executing

Global.creator_address()

TealType.bytes

3

32 byte address of the creator of the current application

Global.current_application_address()

TealType.bytes

5

32 byte address of the current application controlled account

Global.group_id()

TealType.bytes

5

32 byte ID of the current transaction group