Module `algoappdev.apps`

Utilities for building and transacting with apps.

Functions

def compile_expr(expr: pyteal.Expr) ‑> str

Compile a teal expression to teal source code:

Args

expr: the teal expression

Returns

the teal source code

def compile_source(client: algosdk.v2client.algod.AlgodClient, source: str) ‑> bytes

Compile teal source code into bytes.

Args

client: the client connected to a node with the developer API
source: the teal source code

Returns

the teal program bytes

Classes

class AppBuilder (on_create: pyteal.Expr = None, on_delete: pyteal.Expr = None, on_update: pyteal.Expr = None, on_opt_in: pyteal.Expr = None, on_close_out: pyteal.Expr = None, on_clear: pyteal.Expr = None, invocations: Dict[str, pyteal.Expr] = None, on_no_op: pyteal.Expr = None, global_state: StateGlobal = None, local_state: StateLocal = None, fixed_global_schema: algosdk.future.transaction.StateSchema = None, fixed_local_schema: algosdk.future.transaction.StateSchema = None)

Build the program data required for an app to execute the provided expressions, with the provided app state.

The app is specified as individual branches. At most one of those branches will execute when the application is called (all branches are joined in a tl.Seq expression, which must evaluate exactly one branch).

Branches that can execute for an ApplicationCall transaction:

on_create: this expression is run when the app is first created only, and if it returns zero, the app cannot be created.
on_delete: this expression is run when a DeleteApplication transaction is sent, and if it returns zero the app cannot be deleted.
on_update: this expression is run when a UpdateApplication transaction is sent, and if it returns zero the app cannot be updated.
on_opt_in: this expression is run when a OptIn transaction is sent, and if it returns zero the app cannot be opted-in by accounts.
on_close_out: this expression is run when a CloseOut transaction is sent, and if it returns zero the app cannot be closed out by accounts.
invocations[name]: these expressions are run when a NoOp transaction is sent, and the first argument passed to the call is the bytes encoding of name.
on_no_op: this expression is run when a NoOp transaction is sent, and no invocation matches the first call argument (if supplied). This is the "default invocation".

Branch that executes for a ClearState transaction:

on_clear: this expression is run regardless of return value, but any state changes made in the expression are not committed if the return value is zero.

The default app implements the following functionality:

creation is allowed and sets the global state defaults
deletion is not allowed
updating is not allowed
opt in is allowed and sets the local state defaults
close out is not allowed
clear is allowed
no invocations
no default invocation

Ancestors

builtins.tuple

Instance variables

var fixed_global_schema : algosdk.future.transaction.StateSchema: Alias for field number 10
var fixed_local_schema : algosdk.future.transaction.StateSchema: Alias for field number 11
var global_state : StateGlobal: Alias for field number 8
var invocations : Dict[str, pyteal.Expr]: Alias for field number 6
var local_state : StateLocal: Alias for field number 9
var on_clear : pyteal.Expr: Alias for field number 5
var on_close_out : pyteal.Expr: Alias for field number 4
var on_create : pyteal.Expr: Alias for field number 0
var on_delete : pyteal.Expr: Alias for field number 1
var on_no_op : pyteal.Expr: Alias for field number 7
var on_opt_in : pyteal.Expr: Alias for field number 3
var on_update : pyteal.Expr: Alias for field number 2

Methods

def approval_expr(self) ‑> pyteal.Expr

Assemble the provided expressions into the approval expression, by joining them in a single branching control flow.

def build_application(self, client: algosdk.v2client.algod.AlgodClient, app_idx: int, creator: str = None, global_state: List[algosdk.v2client.models.teal_key_value.TealKeyValue] = None) ‑> algosdk.v2client.models.application.Application

Build the Application object describing this application.

This is used to interface with the dryrun APIs.

Args

client: the client connected to a node with the developer API, used for compiling and to send the transaction
app_idx: the application index to assign to this app, used to cross reference in transactions and other apps in the dry run
creator: the application's creator's address, needed if the logic accesses tl.Global.creator_address, and for making a dryrun of the app creation
global_state: attach this global state to the app in the dryrun

def clear_expr(self) ‑> pyteal.Expr

Build the clear program expression.

def create_txn(self, client: algosdk.v2client.algod.AlgodClient, address: str, params: algosdk.future.transaction.SuggestedParams) ‑> algosdk.future.transaction.ApplicationCreateTxn

Build the transaction which creates the app.

Args

client: the client connected to a node with the developer API, used for compiling and to send the transaction
address: the address of the app creator sending the transaction
params: the transaction parameters

def global_schema(self) ‑> algosdk.future.transaction.StateSchema

Build the global schema.

def local_schema(self) ‑> algosdk.future.transaction.StateSchema

Build the local schema.

def update_txn(self, client: algosdk.v2client.algod.AlgodClient, address: str, params: algosdk.future.transaction.SuggestedParams, app_id: int) ‑> algosdk.future.transaction.ApplicationUpdateTxn

Build the transaction which updates an app with this data.

NOTE: the schema cannot be changed in an update transaction, meaning the state must be the same as that already used in app_id.

Args

client: the client connected to a node with the developer API, used for compiling and to send the transaction
address: the address of the app creator sending the transaction
params: the transaction parameters
app_id: the id of the existing application to update

class State (keys: List[State.KeyInfo])

Describes an app's state.

Args

keys: list of key information describing the state

Class variables

var KeyInfo: Information about an app state key and associated value.

Methods

def key_info(self, key: Union[int, str, bytes]): Get the KeyInfo for key.
def key_infos(self) ‑> List[State.KeyInfo]: Get the list of KeyInfos for the entire state.
def schema(self) ‑> algosdk.future.transaction.StateSchema: Build the schema for the state.

class StateGlobal (keys: List[State.KeyInfo])

Read global state values which might or might not be present. This is the only way to interface with external apps, and can also be used to access values which might not yet be set in the current app.

An object MaybeValue is itself a teal expression. It is also stateful, in that the expression, once constructed, stores the value into a slot, and that slot is cached in the MaybeValue object.

For example:

myabe = App.globalGetEx(app_id, key)
Seq(maybe, maybe.value())

In this snippet, the sequence first stores the values retrieved by get, then the value is loaded onto the stack and can be used. To re-use the value from the given key, it is necessary to use the same maybe objet, as this one remembers which slot the value is stored in.

Making a second MaybeValue object with the same key will not re-use the stored values from the first object. The second object could also evaluated to store the same value into a new slot. But without this step, it's load method is oblivious to the slots used by the globalGetEx call.

See StateGlobalExternal but for only the current app.

Ancestors

StateGlobalExternal
State

Methods

def constructor(self) ‑> pyteal.Expr: Build the expression to set the initial state values for those keys with an default member.
def drop(self, key: Union[int, str, bytes]) ‑> pyteal.Expr: Build the expression to drop the state key
def get(self, key: Union[int, str, bytes]) ‑> pyteal.Expr: Build the expression to get the state value at key
def set(self, key: Union[int, str, bytes], value: Union[pyteal.Int, pyteal.Bytes]) ‑> pyteal.Expr: Build the expression to set the state value at key

Inherited members

StateGlobalExternal:
- KeyInfo
- get_ex
- key_info
- key_infos
- load_ex_has_value
- load_ex_value
- schema

class StateGlobalExternal (keys: List[State.KeyInfo], app_id: pyteal.Expr)

An object MaybeValue is itself a teal expression. It is also stateful, in that the expression, once constructed, stores the value into a slot, and that slot is cached in the MaybeValue object.

For example:

myabe = App.globalGetEx(app_id, key)
Seq(maybe, maybe.value())

See State.

Args

app_id: expression evaluating to the id of an app in the app array

Ancestors

State

Subclasses

StateGlobal

Methods

def get_ex(self, key: Union[int, str, bytes]) ‑> pyteal.MaybeValue

Get the MaybeValue object for key.

The object itself is an expression to load the value into a slot. It also has members for accessing that value.

After evaluating MaybeValue, then that object can be used to generate expression to access the value: MaybeValue.value. This means that a MaybeValue object must be cached if its value is to be accessed more than once, so it can remember which slot the value was stored in.

def load_ex_has_value(self, key: Union[int, str, bytes]) ‑> pyteal.Expr

Load a MaybeValue into a slot and return if it has a value.

See load_ex_value for notes on the globalGetEx calls.

def load_ex_value(self, key: Union[int, str, bytes]) ‑> pyteal.Expr

Load a MaybeValue into a slot and return its value.

If the key was previously loaded, the same scratch slot will be used. However, this will call globalGetEx and store its result anew, albeit in the same slot.

The cost of repeating these operations can be avoided by pre-storing the value into a slot at the start of the program, and then accessing its load member subsequently.

maybe = state.get_ex(key)
expr = Seq(
    maybe,
    # ... some teal logic, with possible branches
    maybe.value()
    # ... some more teal logic
    maybe.value()
)

Inherited members

State:
- KeyInfo
- key_info
- key_infos
- schema

class StateLocal (keys: List[State.KeyInfo], account: pyteal.Expr = None)

See StateGlobalExternal, but for the local state.

See StateLocalExternal but for only the current app.

The account whose local state is accessed can be specified with account, and defaults to the transaction sender.

Ancestors

StateLocalExternal
State

Methods

def constructor(self) ‑> pyteal.Expr: See StateGlobal.constructor().
def drop(self, key: Union[int, str, bytes]) ‑> pyteal.Expr: See StateGlobal.drop().
def get(self, key: Union[int, str, bytes]) ‑> pyteal.Expr: See StateGlobal.get().
def set(self, key: Union[int, str, bytes], value: Union[pyteal.Int, pyteal.Bytes]) ‑> pyteal.Expr: See StateGlobal.set().

Inherited members

StateLocalExternal:
- KeyInfo
- get_ex
- key_info
- key_infos
- load_ex_has_value
- load_ex_value
- schema

class StateLocalExternal (keys: List[State.KeyInfo], app_id: pyteal.Expr, account: pyteal.Expr)

See StateGlobalExternal, but for the local state.

See State.

Args

app_id: expression evaluating to the id of an app in the app array
account: expression evaluating to the account whose state is to be accessed

Ancestors

State

Subclasses

StateLocal

Methods

def get_ex(self, key: Union[int, str, bytes]) ‑> pyteal.MaybeValue: See StateGlobalExternal.get_ex().
def load_ex_has_value(self, key: Union[int, str, bytes]) ‑> pyteal.Expr: See StateGlobalExternal.load_ex_has_value().
def load_ex_value(self, key: Union[int, str, bytes]) ‑> pyteal.Expr: See StateGlobalExternal.load_ex_value().

Inherited members

State:
- KeyInfo
- key_info
- key_infos
- schema