account_decompress

Overview

The account_decompress syscall restores a compressed account by providing the account’s data and a state proof verifying the data’s authenticity. This allows retrieval of previously compressed account state.

Syscall Code

Code: 0x09 (TN_SYSCALL_CODE_ACCOUNT_DECOMPRESS)

C SDK Function

ulong tsys_account_decompress(ulong account_idx, void const* meta, void const* data,
                              void const* proof, ulong proof_sz);

Arguments

account_idx · ulong · required

Index of the account to decompress. Must be writable in the transaction and currently compressed or non-existent.

meta · void const · required*

Pointer to the account metadata.

data · void const · required*

Pointer to the account data payload.

proof · void const · required*

Pointer to the state proof data.

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) - Account decompressed 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 is already active (not compressed)
• TN_VM_ERR_SYSCALL_ACCOUNT_IN_COMPRESSION_TIMEOUT (-34) - Account in compression cooldown period
• TN_VM_ERR_SYSCALL_INVALID_ACCOUNT_DATA_SIZE (-35) - Invalid account data size
• TN_VM_ERR_SYSCALL_INVALID_ADDRESS (-22) - Invalid virtual address for data or proof
• 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_INSUFFICIENT_PAGES (-26) - Not enough pages for account data
• 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)
• Data cost: Additional units equal to account data size in bytes
• Proof cost: Additional units equal to proof size in bytes
• Total formula: base_cost + data_sz + proof_sz

Memory Pages

• Page allocation: Pages allocated for restored account data
• Data pages: Number of pages based on account data size (page-aligned)
• Metadata pages: Pages for account metadata structure
• Proof verification: Temporary memory usage for proof validation

State Counter Impact

• GASC (Global Activated State Counter): Incremented by TSDK_ACCOUNT_META_FOOTPRINT bytes, plus restored data bytes (up to original data size)
• Purpose: Tracks activated state for the account decompression in the global state counter
• Overflow protection: Returns TN_VM_ERR_SYSCALL_STATE_BYTES_ADDED_OVERFLOW if counter would overflow

Side Effects

• Account restoration: Restores account metadata and data from provided input
• Flag clearing: Removes COMPRESSED flag from the account
• Memory allocation: Allocates pages for the account data

Data Format

The account data must be structured as:

struct account_data {
    tsdk_account_meta_t metadata;  // Public account metadata view
    uchar data[];               // Account data payload
};

State Proof Verification

• Proof type: Must be TN_STATE_PROOF_TYPE_EXISTING
• Hash verification: Computed account hash must match the proof
• Block validation: Proof must reference a valid historical block
• State root: Account hash must verify against the block’s state root

Compression Timeout

Accounts have a compression timeout period during which they cannot be decompressed. This prevents rapid compress/decompress cycles.

Usage Notes

• Account must be writable in the transaction (signer approval)
• Account data size must match the metadata’s declared data size
• The provided data is validated by computing and verifying its hash
• Account becomes fully active after successful decompression
• Sufficient pages must be available for the account data

Example

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

// Decompress a previously compressed account
ulong account_idx = 3;

// Prepare account data (metadata + data)
struct {
    tsdk_account_meta_t meta;
    uchar data[1024];
} account_data;

// Load the account data from storage/network
load_compressed_account_data(&account_data);

// Prepare state proof
uchar proof_data[2048];
ulong proof_size = load_decompression_proof(account_idx, proof_data);

ulong result = tsys_account_decompress(account_idx, &account_data.meta, account_data.data,
                                       proof_data, proof_size);

if (result == TN_VM_SYSCALL_SUCCESS) {
    // Account decompressed successfully
    // Account is now active and accessible
    // COMPRESSED flag cleared
    // Data is available for program use
}