exit

Overview

The exit syscall terminates the current program execution, either returning to the calling program or ending transaction execution. It can optionally revert the transaction or return with an error code.

Syscall Code

Code: 0x0B (TN_SYSCALL_CODE_EXIT)

C SDK Function

ulong __attribute__((noreturn)) tsys_exit(ulong exit_code, ulong revert);

Arguments

exit_code · ulong · required

User-defined error code to return. This value is passed to the calling program or transaction result.

revert · ulong · required

Revert flag. If non-zero, causes transaction revert; if zero, normal exit.

Return Value

Returns a syscall result code:

Success · ulong

• TN_VM_SYSCALL_SUCCESS (0) - Normal exit (when returning to caller)
• TN_VM_SYSCALL_SUCCESS_EXIT (1) - Transaction exit (when ending transaction)

Error Codes · ulong

• TN_VM_ERR_SYSCALL_REVERT (-25) - Transaction revert requested

Resource Consumption

Compute Units

• Base cost: None (exit syscalls don’t charge compute units)
• Total cost: 0 units
• Rationale: Exit operations are not charged since they terminate execution

Memory Pages

• Page usage: No page allocation or deallocation
• Shadow stack: Uses existing shadow stack to restore previous execution state
• Memory cleanup: No explicit cleanup (handled by transaction end)

Side Effects

• Register a0: Set to the user error code
• Program execution: Terminates current program
• Call stack: Pops current frame (if not root) or ends transaction
• Transaction state: May trigger revert if revert flag is set

Exit Behavior

Normal Exit (revert = 0)

Root Program: Ends transaction execution with success

• Sets transaction result to user error code
• Transaction commits successfully

Called Program: Returns to calling program

• Restores previous execution frame
• Calling program continues execution
• User error code available in a0

Revert Exit (revert ≠ 0)

Any Program: Causes transaction revert

• Sets VM fault to TN_VM_FAULT_REVERT
• Transaction state is rolled back
• Returns TN_VM_ERR_SYSCALL_REVERT

Call Stack Behavior

When exiting from a called program:

1. Current frame index decremented
2. Previous execution state restored from shadow stack
3. Program context switched back to caller
4. User error code placed in a0

Usage Notes

• The user error code is application-defined and can convey success/failure information
• Revert flag provides transaction-level error handling
• Normal exits from root programs complete the transaction successfully
• Multiple nested calls can be unwound with appropriate exit calls

Error Code Conventions

While error codes are user-defined, common conventions include:

• 0: Success
• 1-999: Application-specific success codes
• 1000+: Application-specific error codes

Example

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

// Normal successful exit
ulong success_code = 0;
tsys_exit(success_code, 0);
// Returns to caller or ends transaction successfully

// Exit with application error
ulong error_code = 1001;  // Application-specific error
tsys_exit(error_code, 0);
// Returns error code to caller

// Revert transaction due to critical error
ulong critical_error = 9999;
tsys_exit(critical_error, 1);
// Causes transaction revert, returns TN_VM_ERR_SYSCALL_REVERT

// In calling program after normal return:
// a0 now contains the error code from the called program