$$ \newcommand \App {\mathrm{App}} \newcommand \MaxAppProgramCost {\App_{c,\max}} \newcommand \MaxTxGroupSize {GT_\max} \newcommand \MaxInnerTransactions {\App_\mathrm{itxn}} \newcommand \MaxAppTotalProgramLen {\App_{\mathrm{prog},t,\max}} \newcommand \MaxExtraAppProgramPages {\App_{\mathrm{page},\max}} $$

Execution Environment for Applications (Smart Contracts)

Applications (Smart Contracts) are executed in Application Call transactions. Like Logic Signatures, Applications indicate success by leaving a single non-zero uint64 value on the Stack.

A failed Application Call to an Approval Program is not a valid transaction, thus not written to the blockchain.

An Application Call with On Complete set to ClearStateOC invokes the Clear State Program, rather than the usual Approval Program. If the Clear State Program fails, application state changes are rolled back, but the transaction still succeeds, and the sender’s Local State for the called application is removed.

Applications have access to everything a Logic Signature may access (see section), as well as the ability to examine blockchain state, such as balances and application state (their own state and the state of other applications).

Applications also have access to some Global Fields that are not visible to Logic Signatures because their values change over time.

Since Applications access changing state, nodes have to rerun their code to determine if the Application Call transactions in their Transaction Pool would still succeed each time a block is added to the blockchain.

Bytecode Size

The size of an Application is defined as the length of its approval program bytecode plus its clearstate program bytecode. The sum of these two programs MUST NOT exceed \( \MaxAppTotalProgramLen \times \MaxExtraAppProgramPages \).

Opcode Budget

Applications have limits on their execution cost.

Before Version 4, this was a static limit on the cost of all the instructions in the program.

Starting in Version 4, the cost is tracked dynamically during execution and MUST NOT exceed \( \MaxAppProgramCost \).

Beginning with Version 5, programs costs are pooled and tracked dynamically across Application executions in a group. If \( n \) application invocations appear in a group, then the total execution cost of all such calls MUST NOT exceed \( n \times \MaxAppProgramCost \).

In Version 6, inner Application Calls become possible, and each such call increases the pooled opcode budget by \( \MaxAppProgramCost \) at the time the inner group is submitted (with the itxn_submit opcode), allowing a maximum opcode budget of:

$$ \MaxTxGroupSize \times (1 + \MaxInnerTransactions) \times \MaxAppProgramCost = 190{,}400 $$

Clear Program Execution

Executions of the Clear State Program are more stringent, to ensure that Applications may be closed out (by accounts) and have a chance to clean up their internal state.

At the beginning of a Clear State Program execution, the pooled budget available MUST be \( \MaxAppProgramCost \) or higher. If it is not, the containing transaction group fails without clearing the Application’s state.

During the Clear State Program execution, no more than \( \MaxAppProgramCost \) may be drawn. If further execution is attempted, the Clear State Program fails, and the Application’s state is cleared.

Resource Availability

Applications have limits on the amount of blockchain state they may examine.

Opcodes may only access blockchain resources such as Accounts, Assets, Boxes, and Application state if the given resource is available.

  • A resource in the foreign array fields of the Application Call transaction (foreign accounts, foreign assets, and foreign applications) is available.

  • The transaction sender (snd) is available.

  • The Global Fields CurrentApplicationID, and CurrentApplicationAddress are available.

  • Prior to Version 4, all Assets were considered available to the asset_holding_get opcode, and all Applications were available to the app_local_get_ex opcode.

  • Since Version 6, any Asset or Application created earlier in the same transaction group (whether by a top-level or inner transaction) is available. In addition, any Account associated with an Application created earlier in the group is available.

  • Since Version 7, the Account associated with any Application in the foreign applications field is available.

  • Since Version 9, resources are shared and pooled at group-level. Any resource available in some top-level transaction in a transaction group is available in all Version 9 or later application calls in the group, whether those application calls are top-level or inner.

  • When considering whether an asset holding or application local state is available by group-level resource sharing, the holding or local state MUST BE available in a top-level transaction without considering group sharing.

📎 EXAMPLE

If account A is made available in one transaction, and asset X is made available in another, group resource sharing does not make A’s X holding available.

  • Top-level transactions that are not Application Calls also make resources available to group-level resource sharing. The following resources are made available by other transaction types:

    1. pay: sender (snd), receiver (rcv), and close-to (close) (if set).

    2. keyreg: sender (snd).

    3. acfg: sender (snd), configured asset (caid), and the configured asset holding of the sender.

    4. axfer: sender (snd), asset receiver (arcv), asset sender (asnd) (if set), asset close-to (aclose) (if set), transferred asset (xaid), and the transferred asset holding of each of those accounts.

    5. afrz: sender (snd), freeze account (fadd), freeze asset (faid), and the freeze asset holding of the freeze account. The freeze asset holding of the sender is not made available.

  • A Box is available to an Approval Program if any transaction in the same group contains a box reference (apbx) that denotes the box. A box reference contains an index i, and name n. The index refers to the i-th application in the transaction’s foreign applications array, with the usual convention that 0 indicates the application ID of the Application called by that transaction. No box is ever available to a Clear State Program.

Regardless of availability, any attempt to access an Asset or Application with an ID less than \( 256 \) from within an Application will fail immediately. This avoids any ambiguity in opcodes that interpret their integer arguments as resource IDs or indexes into the foreign assets or foreign applications arrays.

It is RECOMMENDED that Application authors avoid supplying array indexes to these opcodes, and always use explicit resource IDs. By using explicit IDs, contracts will better take advantage of group resource sharing. The array indexing interpretation MAY be deprecated in a future version.