account_set_flags

Overview

The account_set_flags syscall modifies the PROGRAM and RECEIVE_NATIVE flags on an account. The owning program can enable or disable native balance receipt without changing the account’s existing balance.

Syscall Code

Code: 0x0E (TN_SYSCALL_CODE_ACCOUNT_SET_FLAGS)

C SDK Function

ulong tsys_account_set_flags(ushort account_idx, uchar flags);

Arguments

account_idx · ushort · required

Index of the account to modify. Must be writable by the current program.

flags · uchar · required

New complete flags value. Preserve all current bits except the modifiable flags you intend to change. Changing any non-modifiable bit returns TN_VM_ERR_SYSCALL_INVALID_FLAGS.

Return Value

Returns a syscall result code:

Success · ulong

• TN_VM_SYSCALL_SUCCESS (0) - Flags updated successfully

Error Codes · ulong

• TN_VM_ERR_SYSCALL_INVALID_ACCOUNT_INDEX (-8) - Account index out of bounds
• TN_VM_ERR_SYSCALL_ACCOUNT_DOES_NOT_EXIST (-9) - Account does not exist
• TN_VM_ERR_SYSCALL_ACCOUNT_NOT_WRITABLE (-10) - Account not writable by current program
• TN_VM_ERR_SYSCALL_INVALID_FLAGS (-41) - Attempted to modify non-modifiable flags
• TN_VM_ERR_SYSCALL_ACCOUNT_IS_NOT_PROGRAM (-17) - Account data is not valid program bytecode (when setting PROGRAM flag)
• TN_VM_ERR_SYSCALL_PROGRAM_IN_CALL_STACK (-49) - Cannot unset PROGRAM flag while program is in the call stack

Resource Consumption

Compute Units

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

Memory Pages

• Page usage: No direct page allocation
• Metadata impact: May trigger metadata page allocation if not already writable
• Program validation: Temporary memory usage when validating program bytecode

Side Effects

• Account flags: Updates the account’s flag bits
• Account metadata: Makes account metadata writable if not already
• Program validation: Validates bytecode when setting PROGRAM flag
• Write permissions: May remove account writability when marking as program

Modifiable Flags

Only certain flags can be modified:

TSDK_ACCOUNT_FLAG_PROGRAM · flag

Marks the account as containing executable program bytecode. When setting this flag, the account data is validated as valid program bytecode.

TSDK_ACCOUNT_FLAG_RECEIVE_NATIVE · flag, 0x80

Allows a non-EOA-owned account to receive positive native transfers. Program-owned and zero-owner accounts do not receive native balance by default. EOA-owned accounts can receive native balance regardless of this bit.

Flag Setting Behavior

PROGRAM Flag

Setting the flag:

• Account data is validated as valid program bytecode
• Account is automatically made non-writable (security measure)
• Validation failure causes the syscall to fail

Clearing the flag:

• Cannot be cleared while the program is in the call stack (current program or any caller)
• Returns TN_VM_ERR_SYSCALL_PROGRAM_IN_CALL_STACK if program is executing
• Once cleared, account becomes a regular data account

RECEIVE_NATIVE Flag

• The owning program can set or clear this flag on an existing, writable account.
• Setting the flag permits positive native transfers into the account.
• Clearing the flag prevents further positive incoming transfers but does not remove the existing balance or restrict spending it.
• Zero-amount transfers and self-transfers do not require this flag; other transfer checks still apply.

Usage Notes

• Only the account owner (program) can modify flags
• Attempts to modify non-modifiable flags result in an error
• If no flags actually change, the syscall succeeds immediately
• Program validation is performed when setting the PROGRAM flag
• Account must exist and be writable by the current program
• Preserve the other current flags when enabling receipt: current_flags | TSDK_ACCOUNT_FLAG_RECEIVE_NATIVE.

Security Considerations

• Setting the PROGRAM flag automatically removes account writability
• This prevents modification of executable code after deployment
• The PROGRAM flag cannot be cleared while the program is in the call stack
• This prevents a program from invalidating itself or its callers during execution

Example

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

// Mark account as a program (requires valid bytecode)
ushort account_idx = 3;
uchar current_flags = get_account_flags(account_idx);
uchar new_flags = current_flags | TSDK_ACCOUNT_FLAG_PROGRAM;

ulong result = tsys_account_set_flags(account_idx, new_flags);

if (result == TN_VM_SYSCALL_SUCCESS) {
    // Account is now marked as a program
    // Account has been made non-writable
    // Bytecode has been validated
}

// Remove program flag (make it a data account again)
new_flags = current_flags & ~TSDK_ACCOUNT_FLAG_PROGRAM;
result = tsys_account_set_flags(account_idx, new_flags);

// Attempt to modify non-modifiable flag (will fail)
uchar invalid_flags = current_flags | TSDK_ACCOUNT_FLAG_DELETED;  // Not modifiable
result = tsys_account_set_flags(account_idx, invalid_flags);
// Returns TN_VM_ERR_SYSCALL_INVALID_FLAGS