Application Call - Algorand Specifications
Keyboard shortcuts
Press ← or → to navigate between chapters
Press S or / to search in the book
Press ? to show this help
Press Esc to hide this help
- Auto
- Light
- Dark
Algorand Specifications
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 Appr,maxAppr,max.
The application ID identifies the application being called.
If the application ID is omitted (zero), this transaction is creating an application.
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. |
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.
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 66 or higher.
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.
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 Apppage,maxApppage,max extra program pages,
The program page byte length MUST NOT exceed Appprog,maxAppprog,max.
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 AppGS,maxAppGS,max global variables for the application.
TODO: Restrictions on key-value lengths
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 AppLS,maxAppLS,max local variables for the application.
TODO: Restrictions on key-value lengths
The application arguments ( OPTIONAL) list provides byte-array arguments to the application being called.
There MUST NOT be more than Apparg,maxApparg,max entries in this list,
The sum of their byte lengths MUST NOT exceed Appay,maxAppay,max.
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 Appacc,maxAppacc,max entries in this list.
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 Appapp,maxAppapp,max entries in this list.
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 Appasa,maxAppasa,max entries in this list.
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.
Each element of the box reference encodes a structure containing:
| FIELD | CODEC | TYPE | DESCRIPTION |
|---|---|---|---|
| Index | i |
uint64 |
A 11-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 00).
There MUST NOT be more than AppBox,maxAppBox,max entries in this list.
The box name byte length MUST NOT exceed Appk,maxAppk,max.
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.
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 11-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 Appaccess,maxAppaccess,max entries in this list.
TODO
TODO