Support for creating inner transactions

[jasonpaulos]

Summary

algorand/go-algorand#2661 introduced application actions, aka inner transactions which application can create. This issue is to expose that functionality in PyTeal as well.

Scope

Due to the simplicity of the tx_begin, tx_field, and tx_submit opcodes, the design is also pretty simple.

Four new functions should be created:

1. InnerTxnBuilder.Begin(): This will begin an inner transaction. It will evaluate to the tx_begin opcode.

2. InnerTxnBuilder.SetField(field: TxnField, value: Expr): This will set a single field on an inner transaction. This must be called after InnerTxnBuilder.Begin() to be a valid operation. The field argument must be from the existing TxnField enum. The value argument must be a PyTeal expression which evaluates to a type that is compatible with the indicated field type. The compiler will throw an error if the types do not match, for instance if a byteslice is set to the TxnField.amount field.

3. InnerTxnBuilder.SetFields(values: Dict[TxnField, Expr]): This function is similar to InnerTxnBuilder.SetField, except it can accept multiple fields and values for convenience. The values argument must be a dictionary from TxnField to PyTeal expressions. Note that starting in Python 3.6 (which is coincidentally the lowest version PyTeal supports), dictionaries have a defined order, so this will not introduce any nondeterminism.

4. InnerTxnBuilder.Submit(): This will submit an inner transaction. It will evaluate to the tx_submit opcode.

PyTeal will not do any validation of inner transaction fields beyond the simple typechecking described above. This means that when the AVM adds support for more inner transaction features (e.g. the acfg txn type), PyTeal does not need to be updated.

Example

A PyTeal-ized version of https://github.com/algorand/go-algorand/blob/e32b2c2ef9423526bbec7d749d912d3a6153410b/test/scripts/e2e_subs/tealprogs/app-escrow.teal#L116-L142

withdraw_amount = Btoi(Txn.application_args[1])
handle_withdraw = Seq(
    App.localPut(Int(0), balance_key, App.localGet(Int(0), balance_key) - withdraw_amount),
    InnerTxnBuilder.Begin(),
    # set one field
    InnerTxnBuilder.SetField(TxnField.type_enum, TxnType.Payment),
    # set multiple fields at once
    InnerTxnBuilder.SetFields({
        TxnField.amount: withdraw_amount,
        TxnField.receiver: Txn.sender()
    }),
    InnerTxnBuilder.Submit(),
    Approve(),
)

Priority

Needed for TEAL 5 support.