Contract Execution Flow#

This page describes the contract-facing execution model. VM startup and runner loading are specified in Startup.

Deployment and Calls#

  1. On deployment, contract code is stored under the contract Root Slot layout, either in the root code field or through its configured code slot. The deployment call is executed with is_init set.

  2. On a normal call, entry_data contains Calldata Encoded method-call data as described by Method Calling Convention.

  3. The contract runtime dispatches the call and returns a value, a user error, or a VM error as specified by VM Execution Result.

Entry Kinds#

entry_kind selects the entry mode:

  • main: normal contract initialization or method dispatch.

  • sandbox: sandbox entry created by a VM API call.

  • consensus_stage: validator-side consensus-stage entry created by a non-deterministic VM API call.

The complete startup message is specified in Startup Message.

CallContract Semantics#

CallContract performs a read-only call into another contract. It preserves sender_address and origin_address: the callee observes the same sender_address as the caller did, not the immediate caller.

The immediate caller is appended to stack. For a top-level entrypoint, stack is empty; for a nested call, the immediate caller is the last element. A callee that needs to authorize its immediate caller must inspect stack[-1] rather than sender_address.

State Visibility#

A CallContract child reads committed on-chain storage. It does not observe the calling transaction’s uncommitted writes, including through a self-call. Direct reads in the same VM observe the current in-transaction state.

Meta-property changes for CallContract are specified in Sub-VM Creation.