Skip to main content
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.

​
Syscall Listing

Memory Management

Code 0x00 - Sets anonymous segment size to specific value
Code 0x01 - Increments/decrements segment size by delta

Account Management

Code 0x02 - Marks account data writable by program
Code 0x03 - Transfers balance between accounts
Code 0x04 - Creates permanent account with proof
Code 0x05 - Creates temporary account
Code 0x06 - Marks account as deleted
Code 0x07 - Changes account data size
Code 0x0E - Modifies account flags

Compression & Storage

Code 0x08 - Compresses account with state proof
Code 0x09 - Decompresses account with data and proof

Program Control

Code 0x0A - Invokes another program
Code 0x0B - Exits program execution

Logging & Events

Code 0x0C - Outputs debug information
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 tn_sdk_syscall.h to access these functions: 
#include "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

All syscalls consume compute units:
  • Base cost: TN_VM_SYSCALL_BASE_COST (512 units)
  • Additional costs: Vary by syscall complexity and data size
  • Total consumption: Base cost + operation-specific costs

​
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.