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

$$ \newcommand \Box {\mathrm{Box}} \newcommand \BytesPerBoxReference {\Box_{\mathrm{IO}}} $$

Application Call Transaction Semantics

When an application call transaction is evaluated, it is processed according to the following procedure.

The transaction effects MUST NOT be visible to other transactions until the points marked SUCCEED below.

FAIL indicates that any modifications to state up to that point MUST be discarded and the entire transaction rejected.

Procedure

Step 1

  • If the application ID specified by the transaction is zero, create a new application with ID equal to one plus the system transaction counter (this is the same ID selection algorithm as used by Assets).

    When creating an application, the application parameters specified by the transaction (Approval Program, Clear State Program, Global State Schema, Local State Schema, and Extra Program Pages) are allocated into the sender’s account data, keyed by the new application ID.

    Continue to Step 2.

  • If the application ID specified by the transaction is nonzero, continue to Step 2.

Step 2

  • If the on completion action is equal to ClearStateOC, then:

    • Check if the transaction’s sender is opted in to this application ID. If not, FAIL.

    • Check if the application parameters still exist in the creator’s account data.

      • If the application does not exist, delete the sender’s local state for this application (marking them as no longer opted in), and SUCCEED.

      • If the application does exist, continue to Step 3.

  • If the on completion action is not equal to ClearStateOC, continue to Step 4.

Step 3

  • Execute the Clear State Program.

    • If the program execution returns PASS == true, apply the local/global key/value store deltas generated by the program’s execution.

    • If the program execution returns PASS == false, do not apply any local/global key/value store deltas generated by the program’s execution.

    • Delete the sender’s local state for this application (marking them as no longer opted in). SUCCEED.

Step 4

  • If on completion action is equal to OptInOC, then at this point during execution we will allocate a local key/value store for the sender for this application ID, marking the sender as opted in.

    Continue to Step 5.

Step 5

  • Execute the Approval Program.

    • If the program execution returns PASS == true, apply any local/global key/value store deltas generated by the program’s execution. Continue to Step 6.

    • If the program execution returns PASS == false, FAIL.

Step 6

  • If on completion action is equal to NoOpOC

    • SUCCEED.

  • If on completion action is equal toOptInOC

    • This was handled above. SUCCEED.

  • If on completion action is equal to CloseOutOC

    • Check if the transaction’s sender is opted in to this application ID. If not, FAIL.

    • Delete the sender’s local state for this application (marking them as no longer opted in). SUCCEED.

  • If on completion action is equal to ClearStateOC

    • This was handled above (unreachable).

  • If on completion action is equal to DeleteApplicationOC

    • Delete the application’s parameters from the creator’s account data. (Note: this does not affect any local state). SUCCEED.

  • If on completion action is equal to UpdateApplicationOC

    • If an existing program is version 4 or higher, and the supplied program is a downgrade from the existing version. FAIL.

    • Update the Approval Program and Clear State Program for this application according to the programs specified in this application call transaction and increment the Application Version. The new programs are not executed in this transaction. SUCCEED.

Application Stateful Execution Semantics

  • Before the execution of the first application call transaction in a group, the combined size of all boxes referred to in the box references of all transactions in the group MUST NOT exceed the I/O budget (i.e., \( \BytesPerBoxReference \) times the total number of box references in the group), or else the group fails.

  • During the execution of an Approval Program or Clear State Program, the application’s Local State Schema and Global State Schema SHALL never be violated. The program’s execution will fail on the first instruction that would cause the relevant schema to be violated. Writing a Bytes value to a local or global Key/Value Store such that the sum of the lengths of the key and value in bytes exceeds \( \MaxAppBytesValueLen \), or writing any value to a key longer than \( \MaxAppKeyLen \) bytes, will likewise cause the program to fail on the offending instruction.

  • During the execution of an Approval Program, the total size of all boxes that are created or modified in the group MUST NOT exceed the I/O budget. The program’s execution will fail on the first instruction that would cause the constraint to be violated. If a box is deleted after creation or modification, its size is not considered in this sum.

  • An attempt to access resources that are not available will cause the program execution to fail.

  • Boxes MAY NOT be accessed by an application’s Clear State Program.

  • In addition to the group’s named Boxes, transactions MAY also access the Boxes of Applications that were previously created in the same group. Across the execution of the entire group, the group can access as many of these unnamed boxes as the group has empty box references.

For further details on AVM Resource Availability, refer to the AVM Specifications.