Skip to main content
Use this page when you need one compact reference for how success and failure are represented in the C SDK.

​
Success baseline

TSDK_SUCCESS is the canonical success code and is defined as 0UL. Use it for:
  • successful tsdk_return(...)
  • success checks after most syscalls
  • success checks on the callee error channel returned through tsys_invoke

​
Local program failure

Use tsdk_revert(error_code) when your program detects an invalid condition and wants to terminate with a local error. Typical examples:
  • instruction payload too short
  • invalid account index
  • unexpected instruction tag
  • failed precondition before a syscall

​
Successful termination

Use tsdk_return(return_code) when the program has completed successfully and wants to exit. In most application-level code, the return code should be TSDK_SUCCESS.

​
Syscall error pattern

Most syscalls return a single ulong status: 
ulong rc = tsys_account_resize( account_idx, 128UL );
if( rc != TSDK_SUCCESS ) tsdk_revert( rc );

​
CPI error pattern

tsys_invoke returns two different statuses:
  • return value: syscall-level result
  • invoke_err_code: callee-level result
Use both: 
ulong invoke_err = 0UL;
ulong invoke_result = tsys_invoke( payload, payload_sz, target_program_idx, NULL, &invoke_err );

if( invoke_result != TSDK_SUCCESS ) tsdk_revert( invoke_result );
if( invoke_err    != TSDK_SUCCESS ) tsdk_revert( invoke_err );

​
Wrapper-level CPI validation failures

The current C wrapper can revert before issuing the CPI syscall if the auth descriptor is malformed or invalid. Examples include:
  • bad auth magic
  • invalid account indices in auth or deauth lists
  • auth entries for accounts not owned by the current program
SituationRecommended handling
Bad instruction layoutRevert with a local program error code.
Invalid index or ownershipRevert with a local program error code.
Failed syscallRevert with the syscall return code, unless you intentionally remap it.
Failed CPI calleeRevert with invoke_err, unless you intentionally remap it.

​
Notes

  • Do not mix up program-level validation errors with runtime or syscall return codes.
  • Do not ignore the second result channel from tsys_invoke.
  • Prefer a small local error-code namespace per program for validation failures, then bubble up syscall and CPI runtime codes directly when that is the clearest behavior.