diff --git a/docs/accessing_transaction_field.rst b/docs/accessing_transaction_field.rst index 47839b553..e8ec3dfa4 100644 --- a/docs/accessing_transaction_field.rst +++ b/docs/accessing_transaction_field.rst @@ -7,43 +7,62 @@ PyTeal smart contracts can access properties of the current transaction and 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. -Information about the current transaction being evaluated can be obtained using the :any:`Txn` -object. Below are the PyTeal expressions that refer to transaction fields: +Fields by Transaction Type +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Common Fields +....................................................... ================================================================================ ========================= ================ ============================================================================ Operator Type Min TEAL 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() ` :code:`TealType.uint64` 2 round number :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.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 -:any:`Txn.vote_pk() ` :code:`TealType.bytes` 2 32 byte address -:any:`Txn.selection_pk() ` :code:`TealType.bytes` 2 32 byte address -: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 -:any:`Txn.type() ` :code:`TealType.bytes` 2 -:any:`Txn.type_enum() ` :code:`TealType.uint64` 2 see table below -: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 :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 TEAL 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 application accounts +:any:`Txn.assets ` :code:`TealType.uint64[]` 3 Array of application assets +:any:`Txn.applications ` :code:`TealType.uint64[]` 3 Array of applications :any:`Txn.clear_state_program() ` :code:`TealType.bytes` 2 -:any:`Txn.rekey_to() ` :code:`TealType.bytes` 2 32 byte address +: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. +================================================================================ ========================= ================ ============================================================================ + +Asset Config +....................................................... +================================================================================ ========================= ================ ============================================================================ +Operator Type Min TEAL 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 @@ -56,29 +75,61 @@ Operator :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 TEAL 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 -: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.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.accounts ` :code:`TealType.bytes[]` 2 Array of application accounts -:any:`Txn.assets ` :code:`TealType.uint64[]` 3 Array of application assets -:any:`Txn.applications ` :code:`TealType.uint64[]` 3 Array of applications -:any:`InnerTxn.created_asset_id() ` :code:`TealType.uint64` 5 The ID of the newly created asset in this transaction. This is only valid on inner transactions. -:any:`InnerTxn.created_application_id() ` :code:`TealType.uint64` 5 The ID of the newly created application in this transaction. This is only valid on inner transactions. -:any:`InnerTxn.logs ` :code:`TealType.bytes[]` 5 Array of application logged items. This is only valid on inner transactions. ================================================================================ ========================= ================ ============================================================================ -Transaction Type -~~~~~~~~~~~~~~~~ +Asset Transfer +....................................................... +================================================================================ ========================= ================ ============================================================================ +Operator Type Min TEAL 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 TEAL 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 TEAL 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` unkown unknown type, invalid @@ -91,7 +142,7 @@ Value Numerical Value Type String Description ============================== =============== ============ ========================= 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`, @@ -112,7 +163,7 @@ items can be accessed using bracket notation. For example: .. _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`. @@ -171,7 +222,7 @@ Information about the current state of the blockchain can be obtained using the =========================================== ======================= ================ ============================================================= Operator Type Min TEAL Version Notes =========================================== ======================= ================ ============================================================= -:any:`Global.min_txn_fee()` :code:`TealType.uint64` 2 in microAlgos +:any:`Global.min_txn_fee()` :code:`TealType.uint64` 2 in microAlgos :any:`Global.min_balance()` :code:`TealType.uint64` 2 in mircoAlgos :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