account_transfer

Overview

The account_transfer syscall transfers a specified amount of balance from one account to another. Both accounts must exist and meet writability requirements.

Syscall Code

Code: 0x03 (TN_SYSCALL_CODE_ACCOUNT_TRANSFER)

C SDK Function

ulong tsys_account_transfer(ulong from_account_idx, ulong to_account_idx, ulong amount);

Arguments

from_account_idx · ulong · required

Index of the source account to transfer balance from. Must be writable by the current program.

to_account_idx · ulong · required

Index of the destination account to transfer balance to. Must be writable in the transaction.

amount · ulong · required

Amount of balance to transfer from source to destination account.

Return Value

Returns a syscall result code:

Success · ulong

• TN_VM_SYSCALL_SUCCESS (0) - Transfer completed successfully

Error Codes · ulong

• TN_VM_ERR_SYSCALL_INVALID_ACCOUNT_INDEX (-8) - Invalid from or to account index
• TN_VM_ERR_SYSCALL_ACCOUNT_NOT_WRITABLE (-10) - From account not writable by program or to account not writable in transaction
• TN_VM_ERR_SYSCALL_ACCOUNT_DOES_NOT_EXIST (-9) - Source or destination account does not exist
• TN_VM_ERR_SYSCALL_INSUFFICIENT_BALANCE (-38) - Source account has insufficient balance
• TN_VM_ERR_SYSCALL_INVALID_ACCOUNT (-27) - Either account is ephemeral (not allowed for transfers)
• TN_VM_ERR_SYSCALL_BALANCE_OVERFLOW (-11) - Destination balance would overflow

Resource Consumption

Compute Units

• Base cost: TN_VM_SYSCALL_BASE_COST (512 units)
• Additional cost: None
• Total cost: Fixed at 512 units regardless of transfer amount

Memory Pages

• Page usage: No direct page allocation or deallocation
• Metadata impact: May trigger metadata page allocation for both accounts if not already writable

Side Effects

• Balance modification: Decreases source account balance and increases destination balance
• Account metadata: Makes account metadata writable if not already

Usage Notes

• Both accounts must be non-ephemeral accounts
• Source account must be writable by the current program
• Destination account must be writable in the transaction (signer approval)
• Transfer amount cannot exceed source account balance
• Destination balance cannot overflow (exceed maximum value)
• Account metadata is automatically made writable for both accounts

Example

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

// Transfer 1000 units from account 0 to account 1
ulong from_account = 0;
ulong to_account = 1;
ulong amount = 1000;

ulong result = tsys_account_transfer(from_account, to_account, amount);

if (result == TN_VM_SYSCALL_SUCCESS) {
    // Transfer completed successfully
    // from_account balance decreased by 1000
    // to_account balance increased by 1000
}