Skip to content

Commit

Permalink
Update docs for TEAL v2 (#21)
Browse files Browse the repository at this point in the history 
* Code changes to prep for new documentation

* Update documentation

* Add stateful examples, update control flow and transaction pages

* Remove Txn.first_valid_time from docs
  • Loading branch information
@jasonpaulos
jasonpaulos committed Aug 21, 2020
1 parent 7865220 commit 4780bb9
Show file tree
Hide file tree
Showing 13 changed files with 652 additions and 276 deletions.
154 changes: 102 additions & 52 deletions docs/accessing_transaction_field.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,62 +3,112 @@
Transaction Fields and Global Parameters
========================================

A PyTeal expression can be the value of a field of
the current transaction or the value of a global parameter.
Blow are the PyTeal expressions that refer to transaction fields:
PyTeal smart contracts can access properties of the current transaction and the state of the
blockchain when they are running.

================================= ======================= =======================================================================
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.first_valid_time()` :code:`TealType.uint64` causes program to fail, reserved for future use
:code:`Txn.last_valid()` :code:`TealType.uint64` round number
:code:`Txn.note()` :code:`TealType.bytes`
:code:`Txn.lease()` :code:`TealType.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
================================= ======================= =======================================================================
Transaction Fields
------------------

:code:`Txn.type_enum()` values:
Information about the current transaction being evaluated can be obtained using the :any:`Txn`
object. Blow are the PyTeal expressions that refer to transaction fields:

============== ============ =========================
Value Type String Description
============== ============ =========================
:code:`Int(0)` unkown unknown type, invalid
:code:`Int(1)` pay payment
:code:`Int(2)` keyreg key registration
:code:`Int(3)` acfg asset config
:code:`Int(4)` axfer asset transfer
:code:`Int(5)` afrz asset freeze
============== ============ =========================
========================================= ======================== =======================================================================
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[]`
:code:`Txn.accounts()` :code:`TealType.bytes[]`
========================================= ======================== =======================================================================

PyTeal expressions that refer to global parameters:
The :code:`Txn.type_enum()` values can be checked using the :any:`TxnType` enum:

============================== ======================= ============================================================
Operator Type Notes
============================== ======================= ============================================================
:code:`Global.min_txn_fee()` :code:`TealType.uint64` in microAlgos
:code:`Global.min_balance()` :code:`TealType.uint64` in mircoAlgos
:code:`Global.max_txn_life()` :code:`TealType.uint64` number of rounds
:code:`Global.zero_address()` :code:`TealType.bytes` 32 byte address of all zero bytes
:code:`Global.group_size()` :code:`TealType.uint64` number of txns in this atomic transaction group, At least 1
============================== ======================= ============================================================
============================== =============== ============ =========================
Value Numerical Value Type String Description
============================== =============== ============ =========================
:any:`TxnType.Unknown` :code:`0` unkown 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
============================== =============== ============ =========================

Atomic Tranfers
~~~~~~~~~~~~~~~

`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
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
:code:`Gtxn` is zero-indexed and the maximum size of an atomic transfer group is 16.

Global Parameters
-----------------

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

======================================= ======================= ============================================================
Operator Type Notes
======================================= ======================= ============================================================
:any:`Global.min_txn_fee()` :code:`TealType.uint64` in microAlgos
:any:`Global.min_balance()` :code:`TealType.uint64` in mircoAlgos
:any:`Global.max_txn_life()` :code:`TealType.uint64` number of rounds
:any:`Global.zero_address()` :code:`TealType.bytes` 32 byte address of all zero bytes
:any:`Global.group_size()` :code:`TealType.uint64` number of txns in this atomic transaction group, At least 1
:any:`Global.logic_sig_version()` :code:`TealType.uint64` the maximum supported TEAL version
:any:`Global.round()` :code:`TealType.uint64` the current round number
:any:`Global.latest_timestamp()` :code:`TealType.uint64` the latest confirmed block UNIX timestamp
:any:`Global.current_application_id()` :code:`TealType.uint64` the ID of the current application executing
======================================= ======================= ============================================================
21 changes: 21 additions & 0 deletions docs/api.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
.. _api:

PyTeal Package
==============

.. automodule:: pyteal
:members:
:undoc-members:
:imported-members:
:special-members: __getitem__
:show-inheritance:

.. data:: Txn
:annotation: = <pyteal.TxnObject object>

The current transaction being evaluated.

.. data:: Gtxn
:annotation: = <pyteal.TxnGroup object>

The current group of transactions being evaluated.
44 changes: 25 additions & 19 deletions docs/arithmetic_expression.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,28 +7,34 @@ An arithmetic expression is an expression that results in a :code:`TealType.uint
In PyTeal, arithmetic expressions include integer arithmetics operators and boolean operators.
We overloaded all integer arithmetics operator in Python.

==================== =========== ================================================= ===========================
Operator Overloaded Semantics Example
==================== =========== ================================================= ===========================
:code:`Lt(a, b)` :code:`<` `1` if a is less than b, `0` otherwise :code:`Int(1) < Int(5)`
:code:`Gt(a, b)` :code:`>` `1` if a is greater than b, `0` otherwise :code:`Int(1) > Int(5)`
:code:`Le(a, b)` :code:`<=` `1` if a is no greater than b, `0` otherwise :code:`Int(1) <= Int(5)`
:code:`Ge(a, b)` :code:`>=` `1` if a is no less than b, `0` otherwise :code:`Int(1) >= Int(5)`
:code:`Add(a, b)` :code:`+` `a + b`, error (panic) if overflow :code:`Int(1) + Int(5)`
:code:`Minus(a, b)` :code:`-` `a - b`, error if underflow :code:`Int(5) - Int(1)`
:code:`Mul(a, b)` :code:`*` `a * b`, error if overflow :code:`Int(2) * Int(3)`
:code:`Div(a, b)` :code:`/` `a / b`, error if devided by zero :code:`Int(3) / Int(2)`
:code:`Mod(a, b)` :code:`%` `a % b`, modulo operation :code:`Int(7) % Int(3)`
:code:`Eq(a, b)` :code:`==` `1` if a equals b, `0` otherwise :code:`Int(7) == Int(7)`
:code:`And(a, b)` `1` if `a > 0 && b > 0`, `0` otherwise :code:`And(Int(1), Int(1))`
:code:`Or(a, b)` `1` if `a > 0 || b > 0`, `0` otherwise :code:`Or(Int(1), Int(0))`
==================== =========== ================================================= ===========================
======================== =========== ================================================= ===========================
Operator Overloaded Semantics Example
======================== =========== ================================================= ===========================
:code:`Lt(a, b)` :code:`<` `1` if `a` is less than `b`, `0` otherwise :code:`Int(1) < Int(5)`
:code:`Gt(a, b)` :code:`>` `1` if `a` is greater than `b`, `0` otherwise :code:`Int(1) > Int(5)`
:code:`Le(a, b)` :code:`<=` `1` if `a` is no greater than `b`, `0` otherwise :code:`Int(1) <= Int(5)`
:code:`Ge(a, b)` :code:`>=` `1` if `a` is no less than `b`, `0` otherwise :code:`Int(1) >= Int(5)`
:code:`Add(a, b)` :code:`+` `a + b`, error (panic) if overflow :code:`Int(1) + Int(5)`
:code:`Minus(a, b)` :code:`-` `a - b`, error if underflow :code:`Int(5) - Int(1)`
:code:`Mul(a, b)` :code:`*` `a * b`, error if overflow :code:`Int(2) * Int(3)`
:code:`Div(a, b)` :code:`/` `a / b`, error if devided by zero :code:`Int(3) / Int(2)`
:code:`Mod(a, b)` :code:`%` `a % b`, modulo operation :code:`Int(7) % Int(3)`
:code:`Eq(a, b)` :code:`==` `1` if `a` equals `b`, `0` otherwise :code:`Int(7) == Int(7)`
:code:`Neq(a, b)` :code:`!=` `0` if `a` equals `b`, `1` otherwise :code:`Int(7) != Int(7)`
:code:`And(a, b)` `1` if `a > 0 && b > 0`, `0` otherwise :code:`And(Int(1), Int(1))`
:code:`Or(a, b)` `1` if `a > 0 || b > 0`, `0` otherwise :code:`Or(Int(1), Int(0))`
:code:`Not(a)` `1` if `a` equals `0`, `0` otherwise :code:`Not(Int(0))`
:code:`BitwiseAnd(a,b)` :code:`&` `a & b`, bitwise and operation :code:`Int(1) & Int(3)`
:code:`BitwiseOr(a,b)` :code:`|` `a | b`, bitwise or operation :code:`Int(2) | Int(5)`
:code:`BitwiseXor(a,b)` :code:`^` `a ^ b`, bitwise xor operation :code:`Int(3) ^ Int(7)`
:code:`BitwiseNot(a)` :code:`~` `~a`, bitwise complement operation :code:`~Int(1)`
======================== =========== ================================================= ===========================

All these operators takes two :code:`TealType.uint64` values.
In addition, :code:`Eq(a, b)` (:code:`==`) is polymorphic:
it also takes two `TealType.bytes` values. For example, :code:`Arg(0) == Arg(1)` is a valid PyTeal expression.
In addition, :code:`Eq(a, b)` (:code:`==`) and :code:`Neq(a, b)` (:code:`!=`) also work for byte slices.
For example, :code:`Arg(0) == Arg(1)` and :code:`Arg(0) != Arg(1)` are valid PyTeal expressions.

Both :code:`And` and :code:`Or` also support more than 2 arguements:
Both :code:`And` and :code:`Or` also support more than 2 arguements when called as functions:

* :code:`And(a, b, ...)`
* :code:`Or(a, b, ...)`
Expand Down
48 changes: 0 additions & 48 deletions docs/atomic_transfer.rst
View file

This file was deleted.

0 comments on commit 4780bb9

Please sign in to comment.