---
title: Syscalls Overview
description: Listing of all of the available system calls (syscalls) in the ThruVM
source_url:
  html: https://thru.org/docs/spec/vm/syscalls/overview/
  md: https://thru.org/docs/spec/vm/syscalls/overview.md
---

# 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](https://thru.org/docs/spec/vm/syscalls/set_anonymous_segment_sz.md) - Sets anonymous segment size to specific value

tsys\_increment\_anonymous\_segment\_sz

[Code 0x01](https://thru.org/docs/spec/vm/syscalls/increment_anonymous_segment_sz.md) - Increments/decrements segment size by delta

Account Management

tsys\_set\_account\_data\_writable

[Code 0x02](https://thru.org/docs/spec/vm/syscalls/set_account_data_writable.md) - Marks account data writable by program

tsys\_account\_transfer

[Code 0x03](https://thru.org/docs/spec/vm/syscalls/account_transfer.md) - Transfers balance between accounts

tsys\_account\_create

[Code 0x04](https://thru.org/docs/spec/vm/syscalls/account_create.md) - Creates permanent account with proof

tsys\_account\_create\_ephemeral

[Code 0x05](https://thru.org/docs/spec/vm/syscalls/account_create_ephemeral.md) - Creates temporary account

tsys\_account\_delete

[Code 0x06](https://thru.org/docs/spec/vm/syscalls/account_delete.md) - Marks account as deleted

tsys\_account\_resize

[Code 0x07](https://thru.org/docs/spec/vm/syscalls/account_resize.md) - Changes account data size

tsys\_account\_set\_flags

[Code 0x0E](https://thru.org/docs/spec/vm/syscalls/account_set_flags.md) - Modifies account flags

Compression & Storage

tsys\_account\_compress

[Code 0x08](https://thru.org/docs/spec/vm/syscalls/account_compress.md) - Compresses account with state proof

tsys\_account\_decompress

[Code 0x09](https://thru.org/docs/spec/vm/syscalls/account_decompress.md) - Decompresses account with data and proof

Program Control

tsys\_invoke

[Code 0x0A](https://thru.org/docs/spec/vm/syscalls/invoke.md) - Invokes another program

tsys\_exit

[Code 0x0B](https://thru.org/docs/spec/vm/syscalls/exit.md) - Exits program execution

Logging & Events

tsys\_log

[Code 0x0C](https://thru.org/docs/spec/vm/syscalls/log.md) - Outputs debug information

tsys\_emit\_event

[Code 0x0D](https://thru.org/docs/spec/vm/syscalls/emit_event.md) - 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:

```c
#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:

```asm
# 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.