Skip to main content
Accounts are the fundamental units of state in the Thru network. They serve as containers for data, code, and value, enabling programs to store persistent information and users to hold tokens. All network state is organized around accounts, from user wallets and program code to application data and system configuration. Thru implements an account model that manages state, ownership, and data for all entities on the network. Each account is uniquely identified by a 32-byte public key and contains metadata and arbitrary data that programs can read and modify. See Account Addresses for more information about how account addresses are determined.

​
Account Structure

Each account consists of two main components: a fixed 64-byte metadata header that defines the account’s properties and permissions, followed by variable-length data that can be up to 16MB in size. The metadata contains essential information like ownership, balance, and behavioral flags, while the data section stores arbitrary information that programs can read and modify.

​
Account Metadata

Every account contains a 64-byte metadata header that defines its properties and state:
​
version
uint8
required
Account format version. Currently supports version 1 (TN_ACCOUNT_VERSION_V1 = 0x01).
​
flags
uint8
required
Bitfield controlling account behavior and permissions.
​
data_sz
uint32
required
Size of the account’s data in bytes. Maximum value is 16MB (TN_ACCOUNT_DATA_SZ_MAX = 16,777,216).
​
seq
uint64
required
Account sequence number that is incremented each time the account is modified during transaction execution. The sequence is updated at the end of the transaction for accounts that were modified.
​
owner
tn_pubkey_t
required
32-byte public key of the program that owns this account. Only the owner program can modify account data.
​
balance
uint64
required
Account balance in the network’s native token. Used for transaction fees and transfers.
​
nonce
uint64
required
Transaction nonce for replay protection. Must match the transaction nonce exactly for fee payer accounts. See Transaction Execution for more details.

​
Account Data

Following the 64-byte metadata header, accounts can store up to 16MB of arbitrary data that programs can read and modify through direct memory access in the VM.
For detailed information about how programs access account data in memory, see the VM Memory Layout documentation.
struct tn_account_meta {
  uchar       version;        /* Account format version */
  uchar       flags;          /* Behavior flags bitfield */
  uint        data_sz;        /* Data size in bytes */
  ulong       seq;            /* Account sequence number */
  tn_pubkey_t owner;          /* Owner program public key */
  ulong       balance;        /* Balance in native tokens */
  ulong       nonce;          /* Transaction nonce */
};

​
Ownership Model

​
Program Ownership

Every account is owned by exactly one program, identified by the owner field in the account metadata. Ownership is permanent and cannot be transferred. Only the owner program can:
  • Modify account data during transaction execution
  • Change account metadata (except balance and nonce)
  • Delete the account by setting the TN_ACCOUNT_FLAG_DELETED flag
In almost all cases, the owner of an account is the program that created it. The exception is for accounts owned by the externally owned account (EOA) program, which may be created by any program.

​
Externally Owned Accounts

Externally owned accounts (EOAs), also known as user accounts, are owned by the externally owned account program, which is located at the address 0 (all zeros). They can be accessed by using the private key corresponding to their address. EOAs are created using tsys_account_create_eoa() with signature verification to prove ownership of the private key.

​
Account Types

Thru supports two fundamental account types that determine their lifecycle and storage characteristics:
  • Permanent Accounts
  • Ephemeral Accounts
Purpose: Long-lived accounts that persist in the network state indefinitely.Characteristics:
  • Default account type (no special flags required)
  • Require state proofs for creation to prevent conflicts
  • Persist in state trees even when deleted
  • Can be compressed to optimize storage
  • Support all account flags and operations
Lifecycle:
  • Created with tsys_account_create() using state proofs
  • When deleted, account is completely removed but can be recreated without another state proof for a time before compression
  • Newly created accounts that have never existed before can be deleted like ephemeral accounts
Common Use:
  • User wallets and token accounts
  • Program accounts containing executable code
  • Application data and state storage
  • System contracts and infrastructure

​
Account Purposes

While there are only two fundamental types, accounts serve various purposes based on their flags and ownership:
Purpose: Store user funds and serve as transaction fee payers.Also known as: Externally Owned Accounts (EOAs)Characteristics:
  • Owned by the externally owned account program at address 0 (all zeros)
  • Created with tsys_account_create_eoa() using signature verification
  • Controlled by the holder of the private key corresponding to the account’s public key address
  • Typically have no custom data (data_sz = 0)
  • Used for balance transfers and fee payments
Purpose: Store executable bytecode for smart contracts.
  • Marked with TN_ACCOUNT_FLAG_PROGRAM
  • Contain compiled program code in account data
  • Immutable once deployed and verified
Purpose: Store arbitrary application state and user data.
  • Owned by specific programs that can modify them
  • Most flexible storage option up to 16MB
  • Used for application state, user profiles, game data
Purpose: Core network infrastructure and privileged operations.
  • Marked with TN_ACCOUNT_FLAG_PRIVILEGED
  • Special permissions for network-level operations
  • Protected from normal program access

​
Account Limitations

​
Size Constraints

​
Maximum Data Size
16MB
Each account can store at most 16,777,216 bytes of data (TN_ACCOUNT_DATA_SZ_MAX).

​
Access Permissions

Any program can read account metadata and data from accounts included in the transaction.
Only the owner program can modify account data. System operations can modify balance and nonce fields.
New accounts can only be created by their designated owner program during transaction execution.

​
Account Lifecycle

​
Creation

Programs create accounts using the system call interface:
1

Create Account

Use tsys_account_create() or tsys_account_create_ephemeral() to create a new account:
// Create a new account with state proof
ulong result = tsys_account_create(account_idx, seed, proof, proof_sz);

// Create ephemeral account (no state proof required)
ulong result = tsys_account_create_ephemeral(account_idx, seed);
For detailed syscall documentation, see the System Calls reference.
The account is immediately available for use within the same transaction.
2

Set Initial Size

If the account needs data storage, resize it using tsys_account_resize():
ulong result = tsys_account_resize(account_idx, new_size);
See tsys_account_resize() for complete parameter details.

​
Active State

Active accounts exist in the current state and can be:
  • Read by any program in transactions that include them
  • Modified by their owner program through direct memory access
  • Transferred funds using tsys_account_transfer()
  • Resized using tsys_account_resize()
  • Used as data storage for applications
An account is considered active if it’s not compressed and not both ephemeral and deleted.

​
Compression

Programs can compress accounts to optimize state storage using the compression syscalls: 
// Compress an account with state proof
ulong result = tsys_account_compress(account_idx, proof, proof_sz);

// Decompress an account with metadata, data, and proof
ulong result = tsys_account_decompress(account_idx, meta, data, proof, proof_sz);
See tsys_account_compress() and tsys_account_decompress() for detailed usage.
Ephemeral Account Compression For ephemeral accounts, compression behaves differently:
  • Calling tsys_account_compress() on an ephemeral account immediately deletes it instead of compressing
  • Relaxed permissions: Any program can compress (delete) an ephemeral account if it’s writable in the transaction
  • No ownership check: Unlike tsys_account_delete(), compression doesn’t require the current program to own the account
  • No state proof required since the account is simply removed
Compressed accounts are not accessible by programs and cannot be directly modified. They must be decompressed by providing the account data and a state proof to re-upload them to active state.

​
Deletion

1

Delete Account

Programs delete accounts using the deletion syscall:
ulong result = tsys_account_delete(account_idx);
This sets the TN_ACCOUNT_FLAG_DELETED flag, making the account data inaccessible.
See tsys_account_delete() for complete documentation.
2

Ephemeral Cleanup

Accounts marked both TN_ACCOUNT_FLAG_EPHEMERAL and TN_ACCOUNT_FLAG_DELETED can be garbage collected by the runtime.
3

Permanent Deletion

Non-ephemeral deleted accounts are marked with the TN_ACCOUNT_FLAG_DELETED flag as a tombstone in the state tree.

​
Account Operations

​
Balance Transfers

Programs can transfer funds between accounts using the transfer syscall: 
// Transfer amount from one account to another
ulong result = tsys_account_transfer(from_account_idx, to_account_idx, amount);
See tsys_account_transfer() for usage details and requirements.

​
Flag Management

Programs can modify account flags using the set flags syscall: 
// Set account flags (owner program only)
ulong result = tsys_account_set_flags(account_idx, flags);
See tsys_account_set_flags() for available flags and restrictions.

​
Making Accounts Writable

Before modifying account data, programs must mark accounts as writable: 
// Mark account as writable for current transaction
ulong result = tsys_set_account_writable(account_idx);
See tsys_set_account_writable() for detailed requirements.