Syscalls Overview

Syscalls in the ThruVM provide programs with access to runtime services and system resources. They enable programs to manage memory, manipulate accounts, transfer funds, and interact with the broader system.

Tip

Syscall error-code numeric values may change over time. Verify the authoritative values in src/thru/runtime/vm/tn_vm_base.h when implementing or auditing error handling.

Syscall Listing

Memory Management

tsys_set_anonymous_segment_sz

Code 0x00 - Sets anonymous segment size to specific value

tsys_increment_anonymous_segment_sz

Code 0x01 - Increments/decrements segment size by delta

Account Management

tsys_set_account_data_writable

Code 0x02 - Marks account data writable by program

tsys_account_transfer

Code 0x03 - Transfers balance between accounts

tsys_account_create

Code 0x04 - Creates permanent account with proof

tsys_account_create_ephemeral

Code 0x05 - Creates temporary account

tsys_account_delete

Code 0x06 - Marks account as deleted

tsys_account_resize

Code 0x07 - Changes account data size

tsys_account_set_flags

Code 0x0E - Modifies account flags

Compression & Storage

tsys_account_compress

Code 0x08 - Compresses account with state proof

tsys_account_decompress

Code 0x09 - Decompresses account with data and proof

Program Control

tsys_invoke

Code 0x0A - Invokes another program

tsys_exit

Code 0x0B - Exits program execution

Logging & Events

tsys_log

Code 0x0C - Outputs debug information

tsys_emit_event

Code 0x0D - Records transaction event

Calling Convention

ThruVM syscalls follow a standardized calling convention using RISC-V registers:

• Syscall number: Placed in register a7
• Arguments: Passed in registers a0 through a6 (up to 7 arguments)
• Return value: Placed in register a0
• Invocation: Use the ecall instruction to trigger the syscall

C SDK Interface

The C SDK provides convenient wrapper functions for all syscalls. Include <thru-sdk/c/tn_sdk_syscall.h> to access these functions:

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

// Example: Transfer funds between accounts
ulong result = tsys_account_transfer(from_account, to_account, amount);
if (result == TN_VM_SYSCALL_SUCCESS) {
    // Transfer successful
}

Raw Assembly Template

For direct assembly usage:

# Set arguments in a0-a6
li a0, account_idx
li a1, amount
# Set syscall number in a7
li a7, TN_SYSCALL_CODE_ACCOUNT_TRANSFER
# Invoke syscall
ecall
# Check return value in a0

Compute Units

Most syscalls consume compute units:

• Typical base cost: TN_VM_SYSCALL_BASE_COST (512 units)
• Additional costs: Vary by syscall complexity and data size
• Current exceptions: exit and log currently apply zero CU charge in implementation

Error Handling

Syscalls return standardized error codes:

• TN_VM_SYSCALL_SUCCESS (0) - Operation successful
• Negative values indicate specific error conditions
• Programs should always check return values

Usage Patterns

Memory Management

Use memory syscalls to allocate and manage anonymous data segments for program scratch space and dynamic data structures.

Account Operations

Account syscalls enable creating, modifying, and managing accounts within transactions. Always verify account ownership and permissions.

Cross-Program Calls

Use tsys_invoke and tsys_exit syscalls to build modular programs that can call each other while maintaining security boundaries.

State Management

Compression syscalls allow efficient storage of large account states with cryptographic proofs for verification.

Debugging & Monitoring

Logging and event syscalls provide visibility into program execution and enable external monitoring.