--- title: account_create_eoa description: Creates a new Externally Owned Account (EOA) with signature verification source_url: html: https://thru.org/docs/spec/vm/syscalls/account_create_eoa/ md: https://thru.org/docs/spec/vm/syscalls/account_create_eoa.md --- # 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 ```c 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: ```plaintext message = null_owner_address // 32 bytes of zeros (0x00000...000) signature = ed25519_sign(private_key, message) ``` The verification confirms: ```plaintext 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 ```c #include #include // 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 } ```