invoke

Overview

The invoke syscall calls another program, creating a new execution frame. This enables cross-program invocation and modularity in the ThruVM runtime.

Syscall Code

Code: 0x0A (TN_SYSCALL_CODE_INVOKE)

C SDK Function

ulong tsys_invoke(void const* instr_data,
                  ulong instr_data_sz,
                  ushort program_account_idx,
                  tsdk_invoke_auth_t const* auth,
                  ulong* invoke_err_code);

Arguments

instr_data · void const · required*

Pointer to the instruction data to pass to the invoked program.

instr_data_sz · ulong · required

Length of the instruction data in bytes.

program_account_idx · ushort · required

Index of the program account to invoke. Must be a valid program account.

auth · tsdk_invoke_auth_t const · required*

Optional invoke authorization descriptor. Pass NULL to use default authorization behavior. When provided, the descriptor is validated by the SDK before the syscall is issued.

invoke_err_code · ulong · required*

Pointer to store the error code returned by the invoked program. This will be set to the exit code of the invoked program.

Return Value

Returns a syscall result code:

Success · ulong

• TN_VM_SYSCALL_SUCCESS (0) - Program invocation initiated successfully

Error Codes · ulong

• TN_VM_ERR_SYSCALL_INVALID_ACCOUNT_INDEX (-8) - Program account index out of bounds
• TN_VM_ERR_SYSCALL_ACCOUNT_DOES_NOT_EXIST (-9) - Program account does not exist
• TN_VM_ERR_SYSCALL_ACCOUNT_IS_NOT_PROGRAM (-17) - Account is not a valid program
• TN_VM_ERR_SYSCALL_CALL_DEPTH_TOO_DEEP (-24) - Maximum call depth exceeded

Resource Consumption

Compute Units

• Base cost: TN_VM_SYSCALL_BASE_COST (512 units)
  • Represents the overhead of saving and restoring VM register state
  • Implementation details:
    • Save operation: All 32 registers (256 bytes) are saved to the public shadow stack
    • Restore operation: When returning from the invoked program (via exit syscall), the registers (256 bytes) are restored from the public shadow stack back to the VM
    • Total memory operations per invoke/exit cycle: 512 bytes (256 saved + 256 restored)
  • Cost calculation: 32 registers × 8 bytes × 2 operations (save + restore) = 512 CUs
• Additional cost: None for the invoke syscall itself
• Note: The invoked program will consume additional compute units during its execution

Memory Pages

• Page usage: No direct page allocation
• Shadow stack: Uses existing shadow stack pages to save execution state
• Call overhead: Minimal memory overhead for call frame management

Side Effects

• Execution context: Creates new execution frame and updates call stack
• Register setup: Sets a0 to instruction data address, a1 to data length
• Program counter: Resets PC to 0 for the new program
• Call tracking: Increments frame and call indices
• Shadow stack: Saves current execution state on shadow stack
  • Stores all 32 registers (256 bytes) in the public shadow stack
  • Public shadow stack is read-only memory accessible to programs via memory segment 0x0002
  • Preserves program context including stack/heap page counts
  • Creates accessible snapshot for cross-program inspection and state restoration

Call Stack Management

The syscall manages a call stack with the following updates:

• Frame index: Incremented to create new frame
• Call depth: Updated to reflect nesting level
• Shadow stack: Current state saved for restoration on return
• Program context: Switches to the invoked program’s bytecode

Program Validation

• The target account must have the PROGRAM flag set
• Program bytecode is validated before invocation
• Account must exist and be accessible in the transaction

Depth Limiting

• Maximum call depth is enforced (TN_VM_CALL_DEPTH_MAX)
• Prevents infinite recursion and stack overflow
• Call depth is tracked per execution frame

Register State

Upon successful invocation:

• a0: Set to instruction data virtual address
• a1: Set to instruction data length
• PC: Reset to 0 (start of invoked program)
• Other registers: Preserved from calling context

Usage Notes

• Instruction data can be any format understood by the target program
• The invoked program executes with the same transaction context
• Account permissions and writability are preserved
• Return values are passed through program exit mechanisms
• If auth is non-NULL, SDK-side validation runs before the syscall:
  • bad auth magic: 0xBAD0A170
  • auth account not owned by current program: 0xBAD0A171
  • invalid account index in auth/deauth lists: 0xBAD0A173

Example

#include <thru-sdk/c/tn_sdk_syscall.h>
#include <stdint.h>

// Invoke a calculator program with operation data
ushort calculator_program_idx = 5;

// Prepare instruction data
struct calc_instruction {
    uint32_t operation;  // 1 = add, 2 = multiply
    uint64_t operand_a;
    uint64_t operand_b;
} instruction = {
    .operation = 1,      // Addition
    .operand_a = 100,
    .operand_b = 200
};

ulong invoke_err = (ulong)-1;
ulong result = tsys_invoke( &instruction,
                            sizeof(instruction),
                            calculator_program_idx,
                            NULL,
                            &invoke_err );

if (result == TN_VM_SYSCALL_SUCCESS && invoke_err == TN_VM_SYSCALL_SUCCESS) {
    // Calculator program is now executing
    // It will receive instruction data in a0, a1
    // Current program state saved on shadow stack
    // Execution will continue in calculator program
}