Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation additions for TEAL 3 #55

Merged
merged 2 commits into from
Apr 8, 2021
Merged

Documentation additions for TEAL 3 #55

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c0c867b
Document asset expressions and new txn fields
jasonpaulos Apr 7, 2021
8dcc91f
Document bit/byte manipulation
jasonpaulos Apr 8, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
140 changes: 77 additions & 63 deletions docs/accessing_transaction_field.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,60 +12,66 @@ Transaction Fields
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:

========================================= ======================== =======================================================================
Operator Type Notes
========================================= ======================== =======================================================================
:code:`Txn.sender()` :code:`TealType.bytes` 32 byte address
:code:`Txn.fee()` :code:`TealType.uint64` in microAlgos
:code:`Txn.first_valid()` :code:`TealType.uint64` round number
:code:`Txn.last_valid()` :code:`TealType.uint64` round number
:code:`Txn.note()` :code:`TealType.bytes` transaction note in bytes
:code:`Txn.lease()` :code:`TealType.bytes` transaction lease in bytes
:code:`Txn.receiver()` :code:`TealType.bytes` 32 byte address
:code:`Txn.amount()` :code:`TealType.uint64` in microAlgos
:code:`Txn.close_remainder_to()` :code:`TealType.bytes` 32 byte address
:code:`Txn.vote_pk()` :code:`TealType.bytes` 32 byte address
:code:`Txn.selection_pk()` :code:`TealType.bytes` 32 byte address
:code:`Txn.vote_first()` :code:`TealType.uint64`
:code:`Txn.vote_last()` :code:`TealType.uint64`
:code:`Txn.vote_key_dilution()` :code:`TealType.uint64`
:code:`Txn.type()` :code:`TealType.bytes`
:code:`Txn.type_enum()` :code:`TealType.uint64` see table below
:code:`Txn.xfer_asset()` :code:`TealType.uint64` asset ID
:code:`Txn.asset_amount()` :code:`TealType.uint64` value in Asset's units
:code:`Txn.asset_sender()` :code:`TealType.bytes` 32 byte address, causes clawback of all value if sender is the Clawback
:code:`Txn.asset_receiver()` :code:`TealType.bytes` 32 byte address
:code:`Txn.asset_close_to()` :code:`TealType.bytes` 32 byte address
:code:`Txn.group_index()` :code:`TealType.uint64` position of this transaction within a transaction group
:code:`Txn.tx_id()` :code:`TealType.bytes` the computed ID for this transaction, 32 bytes
:code:`Txn.application_id()` :code:`TealType.uint64`
:code:`Txn.on_completion()` :code:`TealType.uint64`
:code:`Txn.approval_program()` :code:`TealType.bytes`
:code:`Txn.clear_state_program()` :code:`TealType.bytes`
:code:`Txn.rekey_to()` :code:`TealType.bytes` 32 byte address
:code:`Txn.config_asset()` :code:`TealType.uint64`
:code:`Txn.config_asset_total()` :code:`TealType.uint64`
:code:`Txn.config_asset_decimals()` :code:`TealType.uint64`
:code:`Txn.config_asset_default_frozen()` :code:`TealType.uint64`
:code:`Txn.config_asset_unit_name()` :code:`TealType.bytes`
:code:`Txn.config_asset_name()` :code:`TealType.bytes`
:code:`Txn.config_asset_url()` :code:`TealType.bytes`
:code:`Txn.config_asset_metadata_hash()` :code:`TealType.bytes`
:code:`Txn.config_asset_manager()` :code:`TealType.bytes` 32 byte address
:code:`Txn.config_asset_reserve()` :code:`TealType.bytes` 32 byte address
:code:`Txn.config_asset_freeze()` :code:`TealType.bytes` 32 byte address
:code:`Txn.config_asset_clawback()` :code:`TealType.bytes` 32 byte address
:code:`Txn.freeze_asset()` :code:`TealType.uint64`
:code:`Txn.freeze_asset_account()` :code:`TealType.bytes` 32 byte address
:code:`Txn.freeze_asset_frozen()` :code:`TealType.uint64`
:code:`Txn.application_args` :code:`TealType.bytes[]` Array of application arguments
:code:`Txn.accounts` :code:`TealType.bytes[]` Array of additional application accounts
========================================= ======================== =======================================================================
================================================================================ ========================= =======================================================================
Operator Type Notes
================================================================================ ========================= =======================================================================
:any:`Txn.sender() <TxnObject.sender>` :code:`TealType.bytes` 32 byte address
:any:`Txn.fee() <TxnObject.fee>` :code:`TealType.uint64` in microAlgos
:any:`Txn.first_valid() <TxnObject.first_valid>` :code:`TealType.uint64` round number
:any:`Txn.last_valid() <TxnObject.last_valid>` :code:`TealType.uint64` round number
:any:`Txn.note() <TxnObject.note>` :code:`TealType.bytes` transaction note in bytes
:any:`Txn.lease() <TxnObject.lease>` :code:`TealType.bytes` transaction lease in bytes
:any:`Txn.receiver() <TxnObject.receiver>` :code:`TealType.bytes` 32 byte address
:any:`Txn.amount() <TxnObject.amount>` :code:`TealType.uint64` in microAlgos
:any:`Txn.close_remainder_to() <TxnObject.close_remainder_to>` :code:`TealType.bytes` 32 byte address
:any:`Txn.vote_pk() <TxnObject.vote_pk>` :code:`TealType.bytes` 32 byte address
:any:`Txn.selection_pk() <TxnObject.selection_pk>` :code:`TealType.bytes` 32 byte address
:any:`Txn.vote_first() <TxnObject.vote_first>` :code:`TealType.uint64`
:any:`Txn.vote_last() <TxnObject.vote_last>` :code:`TealType.uint64`
:any:`Txn.vote_key_dilution() <TxnObject.vote_key_dilution>` :code:`TealType.uint64`
:any:`Txn.type() <TxnObject.type>` :code:`TealType.bytes`
:any:`Txn.type_enum() <TxnObject.type_enum>` :code:`TealType.uint64` see table below
:any:`Txn.xfer_asset() <TxnObject.xfer_asset>` :code:`TealType.uint64` ID of asset being transferred
:any:`Txn.asset_amount() <TxnObject.asset_amount>` :code:`TealType.uint64` value in Asset's units
:any:`Txn.asset_sender() <TxnObject.asset_sender>` :code:`TealType.bytes` 32 byte address, causes clawback of all value if sender is the clawback
:any:`Txn.asset_receiver() <TxnObject.asset_receiver>` :code:`TealType.bytes` 32 byte address
:any:`Txn.asset_close_to() <TxnObject.asset_close_to>` :code:`TealType.bytes` 32 byte address
:any:`Txn.group_index() <TxnObject.group_index>` :code:`TealType.uint64` position of this transaction within a transaction group, starting at 0
:any:`Txn.tx_id() <TxnObject.tx_id>` :code:`TealType.bytes` the computed ID for this transaction, 32 bytes
:any:`Txn.application_id() <TxnObject.application_id>` :code:`TealType.uint64`
:any:`Txn.on_completion() <TxnObject.on_completion>` :code:`TealType.uint64`
:any:`Txn.approval_program() <TxnObject.approval_program>` :code:`TealType.bytes`
:any:`Txn.clear_state_program() <TxnObject.clear_state_program>` :code:`TealType.bytes`
:any:`Txn.rekey_to() <TxnObject.rekey_to>` :code:`TealType.bytes` 32 byte address
:any:`Txn.config_asset() <TxnObject.config_asset>` :code:`TealType.uint64` ID of asset being configured
:any:`Txn.config_asset_total() <TxnObject.config_asset_total>` :code:`TealType.uint64`
:any:`Txn.config_asset_decimals() <TxnObject.config_asset_decimals>` :code:`TealType.uint64`
:any:`Txn.config_asset_default_frozen() <TxnObject.config_asset_default_frozen>` :code:`TealType.uint64`
:any:`Txn.config_asset_unit_name() <TxnObject.config_asset_unit_name>` :code:`TealType.bytes`
:any:`Txn.config_asset_name() <TxnObject.config_asset_name>` :code:`TealType.bytes`
:any:`Txn.config_asset_url() <TxnObject.config_asset_url>` :code:`TealType.bytes`
:any:`Txn.config_asset_metadata_hash() <TxnObject.config_asset_metadata_hash>` :code:`TealType.bytes`
:any:`Txn.config_asset_manager() <TxnObject.config_asset_manager>` :code:`TealType.bytes` 32 byte address
:any:`Txn.config_asset_reserve() <TxnObject.config_asset_reserve>` :code:`TealType.bytes` 32 byte address
:any:`Txn.config_asset_freeze() <TxnObject.config_asset_freeze>` :code:`TealType.bytes` 32 byte address
:any:`Txn.config_asset_clawback() <TxnObject.config_asset_clawback>` :code:`TealType.bytes` 32 byte address
:any:`Txn.freeze_asset() <TxnObject.freeze_asset>` :code:`TealType.uint64`
:any:`Txn.freeze_asset_account() <TxnObject.freeze_asset_account>` :code:`TealType.bytes` 32 byte address
:any:`Txn.freeze_asset_frozen() <TxnObject.freeze_asset_frozen>` :code:`TealType.uint64`
:any:`Txn.global_num_uints() <TxnObject.global_num_uints>` :code:`TealType.uint64` Maximum global integers in app schema
:any:`Txn.global_num_byte_slices() <TxnObject.global_num_byte_slices>` :code:`TealType.uint64` Maximum global byte strings in app schema
:any:`Txn.local_num_uints() <TxnObject.local_num_uints>` :code:`TealType.uint64` Maximum local integers in app schema
:any:`Txn.local_num_byte_slices() <TxnObject.local_num_byte_slices>` :code:`TealType.uint64` Maximum local byte strings in app schema
:any:`Txn.application_args <TxnObject.application_args>` :code:`TealType.bytes[]` Array of application arguments
:any:`Txn.accounts <TxnObject.accounts>` :code:`TealType.bytes[]` Array of application accounts
:any:`Txn.assets <TxnObject.assets>` :code:`TealType.uint64[]` Array of application assets
:any:`Txn.applications <TxnObject.applications>` :code:`TealType.uint64[]` Array of applications
================================================================================ ========================= =======================================================================

Transaction Type
~~~~~~~~~~~~~~~~

The :code:`Txn.type_enum()` values can be checked using the :any:`TxnType` enum:
The :any:`Txn.type_enum() <TxnObject.type_enum>` values can be checked using the :any:`TxnType` enum:

============================== =============== ============ =========================
Value Numerical Value Type String Description
Expand All @@ -79,11 +85,11 @@ Value Numerical Value Type String Description
:any:`TxnType.ApplicationCall` :code:`6` appl application call
============================== =============== ============ =========================

Tranasction Array Fields
Transaction Array Fields
~~~~~~~~~~~~~~~~~~~~~~~~

Some of the exposed transaction fields are arrays with the type :code:`TealType.bytes[]`. These
fields are :code:`Txn.application_args` and :code:`Txn.accounts`.
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`, and :code:`Txn.applications`.

The length of these array fields can be found using the :code:`.length()` method, and individual
items can be accesses using bracket notation. For example:
Expand All @@ -94,17 +100,25 @@ items can be accesses using bracket notation. For example:
Txn.application_args[0] # get the first application argument
Txn.application_args[1] # get the second application argument

Special case: :code:`Txn.accounts`
""""""""""""""""""""""""""""""""""
.. _txn_special_case_arrays:

The :code:`Txn.accounts` is a special case array. Normal arrays in PyTeal are :code:`0`-indexed, but
this one is :code:`1`-indexed with a special value at index :code:`0`, the sender's address. That
means if :code:`Txn.accounts.length()` is 2, then indexes :code:`0`, :code:`1`, and :code:`2` will
be present. In fact, :code:`Txn.accounts[0]` will always evaluate to the sender's address, even when
:code:`Txn.accounts.length()` is :code:`0`.
Special case: :code:`Txn.accounts` and :code:`Txn.applications`
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

Atomic Tranfer Groups
---------------------
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 <https://developer.algorand.org/docs/features/atomic_transfers/>`_ are irreducible
batch transactions that allow groups of transactions to be submitted at one time. If any of the
Expand All @@ -122,7 +136,7 @@ available on the elements of :code:`Gtxn`. For example:
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 :code:`Txn.group_index()`. If the
To find the current transaction's index in the transfer group, use :any:`Txn.group_index() <TxnObject.group_index>`. If the
current transaction is standalone, it's group index will be :code:`0`.

Global Parameters
Expand Down
Loading