account_create_eoa

Overview

The account_create_eoa syscall creates a new Externally Owned Account (EOA) by verifying a cryptographic signature that proves ownership of the account’s private key.

Syscall Code

Code: 0x0F (TN_SYSCALL_CODE_ACCOUNT_CREATE_EOA)

C SDK Function

ulong tsys_account_create_eoa(ulong account_idx,
                               tn_signature_t const* signature,
                               void const* proof,
                               ulong proof_sz);

Arguments

account_idx · ulong · required

Index of the account slot to create. The account’s public key address must be specified in the transaction at this index.

signature · tn_signature_t const · required*

Pointer to the Ed25519 signature (64 bytes). The signature must be created by signing the null owner address (32 bytes of zeros) with the private key corresponding to the account’s public key.

proof · void const · required*

Pointer to the state proof data verifying the account doesn’t exist.

proof_sz · ulong · required

Size of the state proof data in bytes.

Return Value

Returns a syscall result code:

Success · ulong

• TN_VM_SYSCALL_SUCCESS (0) - EOA account created successfully

Error Codes · ulong

• TN_VM_ERR_SYSCALL_INVALID_ACCOUNT_INDEX (-8) - Account index out of bounds
• TN_VM_ERR_SYSCALL_ACCOUNT_ALREADY_EXISTS (-15) - Account already exists
• TN_VM_ERR_SYSCALL_INVALID_ADDRESS (-22) - Invalid virtual address for signature or proof
• TN_VM_ERR_SYSCALL_INVALID_SIGNATURE (-44) - Ed25519 signature verification failed
• TN_VM_ERR_SYSCALL_INVALID_PROOF_LEN (-32) - Proof size mismatch
• TN_VM_ERR_SYSCALL_INVALID_PROOF_SLOT (-33) - Proof references invalid block slot
• TN_VM_ERR_SYSCALL_INVALID_STATE_PROOF (-23) - State proof verification failed
• 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)
• Signature cost: Additional 64 units for signature verification
• Proof cost: Additional units equal to proof size in bytes
• Metadata cost: Additional units equal to sizeof(tsdk_account_meta_t)
• Total formula: base_cost + 64 + proof_sz + sizeof(tsdk_account_meta_t)

Memory Pages

• Page usage: No direct page allocation (account data starts at size 0)
• Metadata pages: Allocates pages for account metadata structure
• State proof validation: Temporary memory usage for proof verification

State Counter Impact

• GASC (Global Activated State Counter): Incremented by TSDK_ACCOUNT_META_FOOTPRINT bytes
• Purpose: Tracks activated state for the EOA 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 TSDK_ACCOUNT_FLAG_NEW set
• Ownership: Sets owner to null (00000…) for EOA accounts
• Account metadata: Initializes writable metadata structure for an externally owned account

Signature Verification

The signature verification process:

1. Reads the Ed25519 signature (64 bytes) from the provided virtual address
2. Verifies the signature by checking that it was created by signing the null owner address (32 bytes of zeros) with the private key
3. Uses the account’s public key from the transaction to verify the signature
4. The signature proves ownership of the private key corresponding to the account address

Signature Generation

To create a valid signature for EOA account creation:

message = null_owner_address  // 32 bytes of zeros (0x00000...000)
signature = ed25519_sign(private_key, message)

The verification confirms:

ed25519_verify(message=null_owner, signature, public_key=account_address) == SUCCESS

State Proof Requirements

• New accounts: Requires a creation-type state proof showing the address doesn’t exist
• Deleted accounts: Can recreate with proof verification (removes TSDK_ACCOUNT_FLAG_DELETED, owner remains null)
• Proof verification: Must reference a valid block slot and verify against state root

EOA Properties

• Owner: Always set to null address (00000…)
• NEW Flag: TSDK_ACCOUNT_FLAG_NEW is set on first creation
• EOA identification: Identified by null owner; there is no dedicated TN_ACCOUNT_FLAG_EOA
• External control: Account is controlled by the holder of the private key, not by a program

Usage Notes

• The account address must correspond to the public key from which the signature is derived
• Signature verification ensures only the private key holder can create the account
• EOA accounts are distinguished from program-defined accounts by null owner
• State proof ensures global uniqueness of the address
• Account is created with zero balance and zero data size

Example

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

// Create EOA for a specific public key address
ulong account_idx = 3;

// Ed25519 signature (64 bytes) - use tn_signature_t type
// The signature MUST be generated by signing the null owner (32 zeros)
tn_signature_t signature;
uchar null_owner[32] = {0}; // 32 bytes of zeros
// signature = ed25519_sign(private_key, null_owner, 32)
// ... populate signature using your Ed25519 signing library ...

// Prepare state proof data
uchar proof_data[1024];
ulong proof_size = prepare_creation_proof(proof_data);

ulong result = tsys_account_create_eoa(account_idx, &signature,
                                       proof_data, proof_size);

if (result == TN_VM_SYSCALL_SUCCESS) {
    // EOA account created successfully
    // Account has NEW flag set
    // Owner is null (00000...)
    // Account is controlled by private key holder
}