Skip to main content

​
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 (-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 is already active (not compressed)
  • TN_VM_ERR_SYSCALL_ACCOUNT_IN_COMPRESSION_TIMEOUT (-33) - Account in compression cooldown period
  • TN_VM_ERR_SYSCALL_INVALID_ACCOUNT_DATA_SIZE (-34) - Invalid account data size
  • TN_VM_ERR_SYSCALL_INVALID_ADDRESS (-21) - Invalid virtual address for data or proof
  • TN_VM_ERR_SYSCALL_INVALID_PROOF_LEN (-31) - Proof size mismatch
  • TN_VM_ERR_SYSCALL_INVALID_PROOF_SLOT (-32) - Proof references invalid block slot
  • TN_VM_ERR_SYSCALL_INVALID_STATE_PROOF (-22) - State proof verification failed
  • TN_VM_ERR_SYSCALL_INSUFFICIENT_PAGES (-25) - Not enough pages for account data

​
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

​
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 {
    tn_account_meta_t metadata;  // Account metadata
    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 "tn_sdk_syscall.h"

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

// Prepare account data (metadata + data)
struct {
    tn_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
}