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, void const* seed, ulong seed_sz);

​
Arguments

​
account_idx
ulong
required
Index of the account slot to create. Must be writable in the transaction and currently non-existent.
​
seed
void const*
required
Pointer to the seed data used for address derivation.
​
seed_sz
ulong
required
Length of the seed data in bytes.

​
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 (-7) - Account index out of bounds
  • TN_VM_ERR_SYSCALL_ACCOUNT_NOT_WRITABLE (-26) - Account not writable in transaction
  • TN_VM_ERR_SYSCALL_ACCOUNT_ALREADY_EXISTS (-14) - Account already exists
  • TN_VM_ERR_SYSCALL_INVALID_ADDRESS (-21) - Invalid virtual address for seed
  • TN_VM_ERR_SYSCALL_BAD_ACCOUNT_ADDRESS (-15) - Computed address doesn’t match expected

​
Resource Consumption

​
Compute Units

  • Base cost: TN_VM_SYSCALL_BASE_COST (512 units)
  • Seed cost: Additional units equal to seed length in bytes
  • Metadata cost: Additional units equal to sizeof(tn_account_meta_t)
  • Total formula: base_cost + seed_sz + sizeof(tn_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

​
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

​
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 "tn_sdk_syscall.h"
#include <string.h>

// Create ephemeral account for temporary storage
ulong account_idx = 3;
char seed[] = "temp_storage";
ulong seed_len = strlen(seed);

ulong result = tsys_account_create_ephemeral(account_idx, seed, seed_len);

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
}