$$ \newcommand \App {\mathrm{App}} \newcommand \MaxAppTotalTxnReferences {\App_{r,\max}} \newcommand \MaxExtraAppProgramPages {\App_{\mathrm{page},\max}} \newcommand \MaxAppProgramLen {\App_{\mathrm{prog},\max}} \newcommand \MaxGlobalSchemaEntries {\App_{\mathrm{GS},\max}} \newcommand \MaxLocalSchemaEntries {\App_{\mathrm{LS},\max}} \newcommand \MaxAppArgs {\App_{\mathrm{arg},\max}} \newcommand \MaxAppTotalArgLen {\App_{\mathrm{ay},\max}} \newcommand \MaxAppTxnAccounts {\App_{\mathrm{acc},\max}} \newcommand \MaxAppTxnForeignApps {\App_{\mathrm{app},\max}} \newcommand \MaxAppTxnForeignAssets {\App_{\mathrm{asa},\max}} \newcommand \MaxAppAccess {\App_{\mathrm{access},\max}} \newcommand \Box {\mathrm{Box}} \newcommand \MaxAppBoxReferences {\App_{\Box,\max}} \newcommand \MaxAppKeyLen {\App_{\mathrm{k},\max}} $$
Application Call Transaction
Fields
An application call transaction additionally has the following fields:
| FIELD | CODEC | TYPE | REQUIRED |
|---|---|---|---|
| Application ID | apid | uint64 | Yes (except for Creation) |
| On Completion Action | apan | uint64 | Yes |
| Approval Program | apap | []byte | No |
| Clear State Program | apsu | []byte | No |
| Reject Version | aprv | uint64 | No |
| Extra Program Pages | apep | uint64 | No |
| Global State Schema | apgs | struct | No |
| Local State Schema | apls | struct | No |
| Arguments | apaa | [][]byte | No |
| Foreign Accounts | apat | []address | No |
| Foreign Applications | apfa | []uint64 | No |
| Foreign Assets | apas | []uint64 | No |
| Box References | apbx | []struct | No |
| Access List | al | []struct | No |
The sum of the elements in foreign accounts (apat), foreign applications (apfa),
foreign assets (apas), and box references (apbx) MUST NOT exceed \( \MaxAppTotalTxnReferences \).
Application ID
The application ID identifies the application being called.
If the application ID is omitted (zero), this transaction is creating an application.
On Completion Action
The on completion action specifies an additional effect of this transaction on the application’s state in the sender or application creator’s account data.
The apan field values are enumerated as follows:
| ACTION | VALUE | EFFECT |
|---|---|---|
NoOpOC | 0 | Only execute the Approval Program associated with this application ID, with no additional effects. |
OptInOC | 1 | Before executing the Approval Program, allocate local state for this application ID into the sender’s account data. |
CloseOutOC | 2 | After executing the Approval Program, clear any local state for this application ID out of the sender’s account data. |
ClearStateOC | 3 | Do not execute the Approval Program, and instead execute the Clear State Program (which may not reject this transaction). Additionally, clear any local state for this application ID out of the sender’s account data (as in CloseOutOC). |
UpdateApplicationOC | 4 | After executing the Approval Program, replace the Approval Program and Clear State Program associated with this application ID with the programs specified in this transaction. |
DeleteApplicationOC | 5 | After executing the Approval Program, delete the parameters of with this application ID from the account data of the application’s creator. |
Approval Program
The approval program (OPTIONAL) contains the approval program bytecode.
This field is used for application creation and updates, and sets the corresponding application’s Approval Program.
Clear State Program
The clear state program (OPTIONAL) contains the clear state program bytecode.
This field is used for application creation and updates, and sets the corresponding application’s Clear State Program.
- The Approval Program and the Clear State Program MUST have the same version number if either is \( 6 \) or higher.
Reject Version
The reject version (OPTIONAL), if set to a positive number, specifies that the application call MUST fail unless the reject version value exceeds the Application Version.
For further details on Application Versions, refer to the Applications Specifications.
Extra Program Pages
A program page (OPTIONAL) is a chunk of application program bytecode. The extra program pages define the number of program pages besides the first one.
This field is only used during application creation, and requests an increased maximum size for the Approval Program or Clear State Program.
-
There MUST NOT be more than \( \MaxExtraAppProgramPages \) extra program pages,
-
The program page byte length MUST NOT exceed \( \MaxAppProgramLen \).
Global State Schema
The global state schema (OPTIONAL) defines the global state allocated into the creator account that of the application ID.
The global state schema is a structure containing:
| FIELD | CODEC | TYPE | DESCRIPTION |
|---|---|---|---|
| Number of Uints | nui | uint64 | The number of global 64-bit unsigned integer variables for the application. |
| Number of Bytes | nbs | uint64 | The number of global byte-array variables for the application. |
This field is only used during application creation, and sets bounds on the size of the global state associated with this application.
- There MUST NOT be more than \( \MaxGlobalSchemaEntries \) global variables for the application.
TODO: Restrictions on key-value lengths
Local State Schema
The local state schema (OPTIONAL) defines the local state allocated into the accounts that opt-in the application ID.
The local state schema is a structure containing:
| FIELD | CODEC | TYPE | DESCRIPTION |
|---|---|---|---|
| Number of Uints | nui | uint64 | The number of local 64-bit unsigned integer variables for the application. |
| Number of Bytes | nbs | uint64 | The number of local byte-array variables for the application. |
This field is only used during application creation, and sets bounds on the size of the local state for accounts that opt in to this application.
- There MUST NOT be more than \( \MaxLocalSchemaEntries \) local variables for the application.
TODO: Restrictions on key-value lengths
Arguments
The application arguments (OPTIONAL) list provides byte-array arguments to the application being called.
-
There MUST NOT be more than \( \MaxAppArgs \) entries in this list,
-
The sum of their byte lengths MUST NOT exceed \( \MaxAppTotalArgLen \).
Foreign Accounts
The foreign accounts (OPTIONAL) list specifies the accounts, besides the sender, whose local states MAY be referred to by executing the Approval Program or the Clear State Program. These accounts are referred to by their 32-byte addresses.
- There MUST NOT be more than \( \MaxAppTxnAccounts \) entries in this list.
Foreign Applications
The foreign applications (OPTIONAL) list specifies the application IDs, besides the application whose Approval Program or Clear State Program is executing, that the executing program MAY read global state from. These applications are referred to by their 64-bit unsigned integer IDs.
- There MUST NOT be more than \( \MaxAppTxnForeignApps \) entries in this list.
Foreign Assets
The foreign assets (OPTIONAL) list specifies the asset IDs from which the executing Approval Program or Clear State Program MAY read asset parameters. These assets are referred to by their 64-bit unsigned integer IDs.
- There MUST NOT be more than \( \MaxAppTxnForeignAssets \) entries in this list.
Box References
The box references (OPTIONAL) list specifies the boxes that the executing Approval Program (with AVM Version 9 or later), or any other Approval Program in the same group, MAY access for reading or writing when the box reference matches the running program application IDs.
For further details on AVM resource availability, refer to the AVM Specifications.
Each element of the box reference encodes a structure containing:
| FIELD | CODEC | TYPE | DESCRIPTION |
|---|---|---|---|
| Index | i | uint64 | A \( 1 \)-based index in the foreign applications (apfa) list. |
| Name | n | []byte | The box identifier. |
An omitted index (i) is interpreted as the application ID of this transaction
(apid, or the ID allocated for the created application when apid is \( 0 \)).
-
There MUST NOT be more than \( \MaxAppBoxReferences \) entries in this list.
-
The box name byte length MUST NOT exceed \( \MaxAppKeyLen \).
Access List
The access list (OPTIONAL) specifies resources (accounts, application IDs, asset IDs, and box references) that the executing Approval Program (with AVM Version 9 or later), or any other Approval Program in the same group, MAY access for reading or writing.
For further details on AVM resource availability, refer to the AVM Specifications.
Each element of the access list encodes one of the following resources:
| FIELD | CODEC | TYPE | DESCRIPTION |
|---|---|---|---|
| Address | d | []byte | An Account |
| Asset | s | uint64 | An Asset ID |
| Application | p | uint64 | An Application ID |
| Holding | h | struct | A Holding contains subfields d and s that refer to the Address and Asset of the Holding, respectively. |
| Locals | l | struct | A Local contains subfields d and p that refer to the Address and Application of the Local State, respectively. |
| Box Reference | b | struct | A Box Reference contains subfields i and n, that refer to the Application and Box Name, respectively. |
The subfields of h, l, b refer to Accounts, Assets, and Applications by using
an \( 1 \)-based index into the Access List.
An omitted d indicates the sender of the transaction.
An omitted app (p or i) indicates the called Application.
The access list MUST be empty if any of the foreign arrays (apat, apfa,
apas), or box reference list (apbx) fields are populated.
- There MUST NOT be more than \( \MaxAppAccess \) entries in this list.
Validation
TODO
Semantic
TODO