Skip to main content

​
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

FeaturePermanent AccountEphemeral Account
State proofRequiredNot required
LifetimePersists after transactionTransaction only
Balance transfersAllowedForbidden
Creation costHigher (includes proof)Lower (no proof)
Address derivationis_ephemeral = 0is_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
}