account_create_ephemeral

Overview

The account_create_ephemeral syscall creates a temporary account that exists only for the duration of the current transaction. Ephemeral accounts do not require state proofs and are automatically cleaned up at transaction end.

Syscall Code

Code: 0x05 (TN_SYSCALL_CODE_ACCOUNT_CREATE_EPHEMERAL)

C SDK Function

ulong tsys_account_create_ephemeral( ulong account_idx,
                                     uchar const seed[TN_SEED_SIZE] );

Arguments

account_idx · ulong · required

Index of the account slot to create. Must be writable in the transaction and currently non-existent.

seed · uchar const[TN_SEED_SIZE] · required

Fixed 32-byte seed used for address derivation.

Return Value

Returns a syscall result code:

Success · ulong

• TN_VM_SYSCALL_SUCCESS (0) - Ephemeral account created successfully

Error Codes · ulong

• TN_VM_ERR_SYSCALL_INVALID_ACCOUNT_INDEX (-8) - Account index out of bounds
• TN_VM_ERR_SYSCALL_ACCOUNT_NOT_WRITABLE (-10) - Account not writable in transaction
• TN_VM_ERR_SYSCALL_ACCOUNT_ALREADY_EXISTS (-15) - Account already exists
• TN_VM_ERR_SYSCALL_INVALID_ADDRESS (-22) - Invalid virtual address for seed
• TN_VM_ERR_SYSCALL_BAD_ACCOUNT_ADDRESS (-16) - Computed address doesn’t match expected
• TN_VM_ERR_SYSCALL_STATE_BYTES_ADDED_OVERFLOW (-47) - State bytes counter overflow during activation

Resource Consumption

Compute Units

• Base cost: TN_VM_SYSCALL_BASE_COST (512 units)
• Seed cost: Additional units equal to TN_SEED_SIZE bytes
• Metadata cost: Additional units equal to sizeof(tsdk_account_meta_t)
• Total formula: base_cost + TN_SEED_SIZE + sizeof(tsdk_account_meta_t)
• Note: No proof cost since ephemeral accounts don’t require state proofs

Memory Pages

• Page usage: No direct page allocation (account data starts at size 0)
• Metadata pages: Allocates pages for account metadata structure
• Cleanup: All allocated pages are automatically freed at transaction end

State Counter Impact

• GASC (Global Activated State Counter): Incremented by TSDK_ACCOUNT_META_FOOTPRINT bytes
• Purpose: Tracks activated state for the ephemeral account creation in the global state counter
• Overflow protection: Returns TN_VM_ERR_SYSCALL_STATE_BYTES_ADDED_OVERFLOW if counter would overflow

Side Effects

• Account creation: Creates a new account with EPHEMERAL flag set
• Ownership: Sets the current program as the account owner
• Automatic cleanup: Account will be deleted at transaction end

Address Derivation

The ephemeral account address is computed as:

SHA256(current_program_pubkey || is_ephemeral(1) || seed)

Usage Notes

• No state proof required (faster creation)
• Account exists only during transaction execution
• Cannot be used in balance transfers (ephemeral accounts rejected)
• Automatically deleted when transaction completes
• Perfect for temporary storage and intermediate computations
• The computed address must match the transaction’s expected address
• Seed must be exactly TN_SEED_SIZE (32 bytes)

Differences from Permanent Accounts

Feature	Permanent Account	Ephemeral Account
State proof	Required	Not required
Lifetime	Persists after transaction	Transaction only
Balance transfers	Allowed	Forbidden
Creation cost	Higher (includes proof)	Lower (no proof)
Address derivation	is_ephemeral = 0	is_ephemeral = 1

Example

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

// Create ephemeral account for temporary storage
ulong account_idx = 3;
uchar seed[TN_SEED_SIZE] = { 0 };
memcpy( seed, "temp_storage", 12 );

ulong result = tsys_account_create_ephemeral( account_idx, seed );

if (result == TN_VM_SYSCALL_SUCCESS) {
    // Ephemeral account created successfully
    // Account will be automatically deleted at transaction end
    // Can be used for temporary data storage
    // Cannot participate in balance transfers
}