.. _transaction-fields: 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 :any:`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 ================================================================================ ========================= ==================== ============================================================================ :any:`Txn.type() ` :code:`TealType.bytes` 2 :any:`Txn.type_enum() ` :code:`TealType.uint64` 2 see table below :any:`Txn.sender() ` :code:`TealType.bytes` 2 32 byte address :any:`Txn.fee() ` :code:`TealType.uint64` 2 in microAlgos :any:`Txn.first_valid() ` :code:`TealType.uint64` 2 round number :any:`Txn.first_valid_time() ` :code:`TealType.uint64` 7 UNIX timestamp of block before :code:`Txn.first_valid()`. Fails if negative :any:`Txn.last_valid() ` :code:`TealType.uint64` 2 round number :any:`Txn.note() ` :code:`TealType.bytes` 2 transaction note in bytes :any:`Txn.lease() ` :code:`TealType.bytes` 2 transaction lease in bytes :any:`Txn.group_index() ` :code:`TealType.uint64` 2 position of this transaction within a transaction group, starting at 0 :any:`Txn.tx_id() ` :code:`TealType.bytes` 2 the computed ID for this transaction, 32 bytes :any:`Txn.rekey_to() ` :code:`TealType.bytes` 2 32 byte address ================================================================================ ========================= ==================== ============================================================================ Application Call ....................................................... ==================================================================================== ========================= ==================== ============================================================================ Operator Type Min Program Version Notes ==================================================================================== ========================= ==================== ============================================================================ :any:`Txn.application_id() ` :code:`TealType.uint64` 2 :any:`Txn.on_completion() ` :code:`TealType.uint64` 2 :any:`Txn.approval_program() ` :code:`TealType.bytes` 2 :any:`Txn.global_num_uints() ` :code:`TealType.uint64` 3 Maximum global integers in app schema :any:`Txn.global_num_byte_slices() ` :code:`TealType.uint64` 3 Maximum global byte strings in app schema :any:`Txn.local_num_uints() ` :code:`TealType.uint64` 3 Maximum local integers in app schema :any:`Txn.local_num_byte_slices() ` :code:`TealType.uint64` 3 Maximum local byte strings in app schema :any:`Txn.accounts ` :code:`TealType.bytes[]` 2 Array of accounts available to the application :any:`Txn.assets ` :code:`TealType.uint64[]` 3 Array of assets available to the application :any:`Txn.applications ` :code:`TealType.uint64[]` 3 Array of applications :any:`Txn.clear_state_program() ` :code:`TealType.bytes` 2 :any:`Txn.extra_program_pages() ` :code:`TealType.uint64` 4 Number of extra program pages for app :any:`Txn.application_args ` :code:`TealType.bytes[]` 2 Array of application arguments :any:`Txn.created_application_id() ` :code:`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. :any:`Txn.logs ` :code:`TealType.bytes[]` 5 Array of application logged items. In v5, only valid on inner transactions. >= v6 works with top-level and inner transactions. :any:`Txn.last_log() ` :code:`TealType.bytes` 6 The last message emitted. Empty bytes if none were emitted. Application mode only. :any:`Txn.approval_program_pages() ` :code:`TealType.bytes[]` 7 The pages of the approval program as an array :any:`Txn.clear_state_program_pages() ` :code:`TealType.bytes[]` 7 The pages of a clear state program as an array ==================================================================================== ========================= ==================== ============================================================================ Asset Config ....................................................... ================================================================================ ========================= ==================== ============================================================================ Operator Type Min Program Version Notes ================================================================================ ========================= ==================== ============================================================================ :any:`Txn.config_asset() ` :code:`TealType.uint64` 2 ID of asset being configured :any:`Txn.config_asset_total() ` :code:`TealType.uint64` 2 :any:`Txn.config_asset_decimals() ` :code:`TealType.uint64` 2 :any:`Txn.config_asset_default_frozen() ` :code:`TealType.uint64` 2 :any:`Txn.config_asset_unit_name() ` :code:`TealType.bytes` 2 :any:`Txn.config_asset_name() ` :code:`TealType.bytes` 2 :any:`Txn.config_asset_url() ` :code:`TealType.bytes` 2 :any:`Txn.config_asset_metadata_hash() ` :code:`TealType.bytes` 2 :any:`Txn.config_asset_manager() ` :code:`TealType.bytes` 2 32 byte address :any:`Txn.config_asset_reserve() ` :code:`TealType.bytes` 2 32 byte address :any:`Txn.config_asset_freeze() ` :code:`TealType.bytes` 2 32 byte address :any:`Txn.config_asset_clawback() ` :code:`TealType.bytes` 2 32 byte address :any:`Txn.created_asset_id() ` :code:`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 ================================================================================ ========================= ==================== ============================================================================ :any:`Txn.freeze_asset() ` :code:`TealType.uint64` 2 :any:`Txn.freeze_asset_account() ` :code:`TealType.bytes` 2 32 byte address :any:`Txn.freeze_asset_frozen() ` :code:`TealType.uint64` 2 ================================================================================ ========================= ==================== ============================================================================ Asset Transfer ....................................................... ================================================================================ ========================= ==================== ============================================================================ Operator Type Min Program Version Notes ================================================================================ ========================= ==================== ============================================================================ :any:`Txn.xfer_asset() ` :code:`TealType.uint64` 2 ID of asset being transferred :any:`Txn.asset_amount() ` :code:`TealType.uint64` 2 value in Asset's units :any:`Txn.asset_sender() ` :code:`TealType.bytes` 2 32 byte address, causes clawback of all value if sender is the clawback :any:`Txn.asset_receiver() ` :code:`TealType.bytes` 2 32 byte address :any:`Txn.asset_close_to() ` :code:`TealType.bytes` 2 32 byte address ================================================================================ ========================= ==================== ============================================================================ Key Registration ....................................................... ================================================================================ ========================= ==================== ============================================================================ Operator Type Min Program Version Notes ================================================================================ ========================= ==================== ============================================================================ :any:`Txn.vote_pk() ` :code:`TealType.bytes` 2 32 byte address :any:`Txn.selection_pk() ` :code:`TealType.bytes` 2 32 byte address :any:`Txn.state_proof_pk ` :code:`TealType.bytes` 6 64 byte state proof public key commitment. :any:`Txn.vote_first() ` :code:`TealType.uint64` 2 :any:`Txn.vote_last() ` :code:`TealType.uint64` 2 :any:`Txn.vote_key_dilution() ` :code:`TealType.uint64` 2 :any:`Txn.nonparticipation() ` :code:`TealType.uint64` 5 Marks an account nonparticipating for rewards ================================================================================ ========================= ==================== ============================================================================ Payment ....................................................... ================================================================================ ========================= ==================== ============================================================================ Operator Type Min Program Version Notes ================================================================================ ========================= ==================== ============================================================================ :any:`Txn.receiver() ` :code:`TealType.bytes` 2 32 byte address :any:`Txn.amount() ` :code:`TealType.uint64` 2 in microAlgos :any:`Txn.close_remainder_to() ` :code:`TealType.bytes` 2 32 byte address ================================================================================ ========================= ==================== ============================================================================ Transaction Types ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The :any:`Txn.type_enum() ` values can be checked using the :any:`TxnType` enum: ============================== =============== ============ ========================= Value Numerical Value Type String Description ============================== =============== ============ ========================= :any:`TxnType.Unknown` :code:`0` unknown unknown type, invalid :any:`TxnType.Payment` :code:`1` pay payment :any:`TxnType.KeyRegistration` :code:`2` keyreg key registration :any:`TxnType.AssetConfig` :code:`3` acfg asset config :any:`TxnType.AssetTransfer` :code:`4` axfer asset transfer :any:`TxnType.AssetFreeze` :code:`5` afrz asset freeze :any:`TxnType.ApplicationCall` :code:`6` appl application call ============================== =============== ============ ========================= Transaction Array Fields ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Some of the exposed transaction fields are arrays with the type :code:`TealType.uint64[]` or :code:`TealType.bytes[]`. These fields are :code:`Txn.application_args`, :code:`Txn.assets`, :code:`Txn.accounts`, :code:`Txn.applications`, and :code:`InnerTxn.logs`. The length of these array fields can be found using the :code:`.length()` method, and individual items can be accessed using bracket notation. For example: .. code-block:: python 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 .. _txn_special_case_arrays: Special case: :code:`Txn.accounts` and :code:`Txn.applications` ................................................................ The :code:`Txn.accounts` and :code:`Txn.applications` arrays are special cases. Normal arrays in PyTeal are :code:`0`-indexed, but these are :code:`1`-indexed with special values at index :code:`0`. For the accounts array, :code:`Txn.accounts[0]` is always equivalent to :code:`Txn.sender()`. For the applications array, :code:`Txn.applications[0]` is always equivalent to :code:`Txn.application_id()`. **IMPORTANT:** Since these arrays are :code:`1`-indexed, their lengths are handled differently. For example, if :code:`Txn.accounts.length()` or :code:`Txn.applications.length()` is 2, then indexes :code:`0`, :code:`1`, and :code:`2` will be present. In fact, the index :code:`0` will always evaluate to the special values above, even when :code:`length()` is :code:`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 :any:`Gtxn` object. This object acts like a list of :any:`TxnObject`, meaning all of the above transaction fields on :code:`Txn` are available on the elements of :code:`Gtxn`. For example: .. code-block:: python 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 :code:`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 :any:`Global.group_size()`. A standalone transaction will have a group size of :code:`1`. To find the current transaction's index in the transfer group, use :any:`Txn.group_index() `. If the current transaction is standalone, it's group index will be :code:`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 :any:`InnerTxnBuilder` class. The properties of the most recently submitted inner transaction can be accessed using the :any:`InnerTxn` object. This object is an instance of :any:`TxnObject`, meaning all of the above transaction fields on :code:`Txn` are available on :code:`InnerTxn` as well. Global Parameters ----------------- Information about the current state of the blockchain can be obtained using the following :any:`Global` expressions: =========================================== ======================= ==================== =================================================================================================================== Operator Type Min Program Version Notes =========================================== ======================= ==================== =================================================================================================================== :any:`Global.min_txn_fee()` :code:`TealType.uint64` 2 in microAlgos :any:`Global.min_balance()` :code:`TealType.uint64` 2 in microAlgos :any:`Global.max_txn_life()` :code:`TealType.uint64` 2 number of rounds :any:`Global.zero_address()` :code:`TealType.bytes` 2 32 byte address of all zero bytes :any:`Global.group_size()` :code:`TealType.uint64` 2 number of txns in this atomic transaction group, at least 1 :any:`Global.logic_sig_version()` :code:`TealType.uint64` 2 the maximum supported program version :any:`Global.round()` :code:`TealType.uint64` 2 the current round number :any:`Global.latest_timestamp()` :code:`TealType.uint64` 2 the latest confirmed block UNIX timestamp :any:`Global.current_application_id()` :code:`TealType.uint64` 2 the ID of the current application executing :any:`Global.creator_address()` :code:`TealType.bytes` 3 32 byte address of the creator of the current application :any:`Global.current_application_address()` :code:`TealType.bytes` 5 32 byte address of the current application controlled account :any:`Global.group_id()` :code:`TealType.bytes` 5 32 byte ID of the current transaction group :any:`Global.opcode_budget()` :code:`TealType.uint64` 6 The remaining cost that can be spent by opcodes in this program :any:`Global.caller_app_id()` :code:`TealType.uint64` 6 The ID of the application that called the current application, or zero. Application mode only :any:`Global.caller_app_address()` :code:`TealType.bytes` 6 32 byte address of the application that called the current application, or the zero address. Application mode only. :any:`Global.asset_create_min_balance()` :code:`TealType.uint64` 10 The minimum balance required to create and opt into an asset :any:`Global.asset_opt_in_min_balance()` :code:`TealType.uint64` 10 The minimum balance required to opt in to an asset :any:`Global.genesis_hash()` :code:`TealType.bytes` 10 The genesis hash for the network =========================================== ======================= ==================== ===================================================================================================================