System Program Instructions

Overview

The Light Protocol system program (SySTEM1eSU2p4BGQfQpimFEWWSC1XDFeun3Nqzz3rT7) is the core program for compressed account operations. It handles account creation, updates, and deletion using Merkle trees and zero-knowledge proofs. Program ID: SySTEM1eSU2p4BGQfQpimFEWWSC1XDFeun3Nqzz3rT7
Documentation: System Program

Instruction Types

Invoke

Direct compressed account operations

InvokeCpi

Cross-program invocation context

CPI Context

Account for storing CPI state

Discriminators

Instruction	Discriminator (8 bytes)	Description
InitializeCpiContextAccount	`[163, 223, 82, 38, 39, 61, 233, 233]`	Initialize CPI context account
Invoke	`[163, 223, 82, 38, 39, 61, 233, 233]`	Execute compressed account ops
InvokeCpi	`[230, 224, 109, 130, 81, 205, 191, 65]`	CPI from another program
InvokeCpiWithReadOnly	Custom	CPI with readonly accounts
InvokeCpiWithAccountInfo	Custom	CPI with account info mode

Invoke

Discriminator: [163, 223, 82, 38, 39, 61, 233, 233] Direct invocation for compressed account operations.

Instruction Data

pub struct InvokeInstructionData {
    pub input_compressed_accounts_with_merkle_context: 
        Vec<PackedCompressedAccountWithMerkleContext>,
    pub output_compressed_accounts: Vec<OutputCompressedAccountData>,
    pub relay_fee: Option<u64>,
    pub new_address_params: Vec<NewAddressParams>,
    pub compress_or_decompress_lamports: Option<u64>,
    pub is_compress: bool,
    pub proof: Option<CompressedProof>,
}

input_compressed_accounts_with_merkle_context

Vec<PackedCompressedAccountWithMerkleContext>

Compressed accounts to spend (with Merkle proofs and context)

output_compressed_accounts

Vec<OutputCompressedAccountData>

New compressed accounts to create

new_address_params

Vec<NewAddressParams>

Parameters for creating new addresses in address Merkle tree

compress_or_decompress_lamports

Option<u64>

Lamports to compress (move into Merkle tree) or decompress (move to Solana account)

is_compress

bool

True for compress operation, false for decompress

proof

Option<CompressedProof>

ZK proof for validity of operation (Groth16 proof, 128 bytes)

Operations

Create Compressed Accounts

Create new compressed accounts in Merkle tree.Steps:

Derive addresses for output accounts (if needed)
Verify address non-inclusion proofs
Hash output accounts
Insert hashes into state tree output queue
Emit event with account data

Requirements:

Authority must sign
Addresses must not exist (proven by ZK proof)
Sum check: input lamports = output lamports + fees

Update Compressed Accounts

Spend existing compressed accounts and create new ones.Steps:

Verify inclusion proofs for input accounts
Compute and insert nullifiers (prevent double-spend)
Create output accounts
Verify sum check

Requirements:

Valid inclusion proofs for inputs
Authority signature
Nullifiers not already used
Sum check passes

Delete Compressed Accounts

Spend compressed accounts without creating outputs.Steps:

Verify inclusion proofs
Insert nullifiers
Decompress lamports to Solana account

Use case: Close compressed accounts and reclaim lamports

Compress Lamports

Move lamports from Solana account into compressed account.Steps:

Transfer lamports from fee payer
Create compressed account with lamports
Insert into Merkle tree

Benefit: Reduces rent costs (compressed accounts don’t pay rent)

Decompress Lamports

Move lamports from compressed account to Solana account.Steps:

Verify inclusion proof for compressed account
Insert nullifier (spend account)
Transfer lamports to destination Solana account

Use case: Access lamports for non-Light Protocol operations

Example

// Create new compressed account
let output = OutputCompressedAccountData {
    owner: program_id,
    lamports: 1_000_000,
    data: Some(account_data),
    address: Some(derived_address),
};

let ix_data = InvokeInstructionData {
    input_compressed_accounts_with_merkle_context: vec![],
    output_compressed_accounts: vec![output],
    new_address_params: vec![address_params],
    proof: Some(address_proof),
    compress_or_decompress_lamports: Some(1_000_000),
    is_compress: true,
    relay_fee: None,
};

InvokeCpi

Discriminator: [230, 224, 109, 130, 81, 205, 191, 65] Cross-program invocation for compressed account operations.

Instruction Data

pub struct InvokeCpiInstructionData {
    pub inputs: InvokeInstructionData,
    pub cpi_context: Option<CpiContext>,
}

pub struct CpiContext {
    pub invoking_program: Pubkey,
    pub cpi_context_account_index: u8,
    pub execute: bool,
}

inputs

InvokeInstructionData

Same data structure as Invoke instruction

cpi_context

Option<CpiContext>

CPI context for tracking cross-program state:

invoking_program: Program making the CPI
cpi_context_account_index: Index of CPI context account
execute: Whether to execute (true) or just validate (false)

CPI Context Account

Accounts called via CPI must use a CPI context account to store intermediate state:

pub struct CpiContextAccount {
    pub discriminator: [u8; 8],
    pub fee_payer: Pubkey,
    pub associated_merkle_tree: Pubkey,
    pub cpi_signature_account_index: u8,
    pub execute: bool,
}

Purpose: Store state between CPI setup and execution

CPI Flow

Initialize CPI Context

Calling program initializes CPI context account with InitializeCpiContextAccount

Setup Phase

Call InvokeCpi with execute: false to validate and prepare state

Execution Phase

Call InvokeCpi with execute: true to perform the operation

Cleanup

CPI context account can be reused for next operation

Example

// In your program making CPI to system program

// 1. Initialize CPI context (once)
let cpi_context_ix = create_initialize_cpi_context_account_instruction(
    &payer.pubkey(),
    &cpi_context_account.pubkey(),
);

// 2. Setup phase
let cpi_data = InvokeCpiInstructionData {
    inputs: /* ... */,
    cpi_context: Some(CpiContext {
        invoking_program: my_program_id,
        cpi_context_account_index: cpi_context_index,
        execute: false,  // Setup only
    }),
};

invoke_cpi_instruction(/* ... */)?;

// 3. Execute phase  
cpi_data.cpi_context.as_mut().unwrap().execute = true;
invoke_cpi_instruction(/* ... */)?;

InvokeCpiWithReadOnly

Variant of InvokeCpi that supports readonly input accounts. Use case: Read compressed account data without spending it

pub struct InvokeCpiInstructionDataWithReadOnly {
    pub inputs: InvokeInstructionData,
    pub cpi_context: CpiContext,
    pub readonly_indices: Vec<u8>,
}

InitializeCpiContextAccount

Initialize CPI context account for cross-program calls. Accounts:

Fee payer (mut, signer)
CPI context account (mut)
System program

Account size: 200 bytes (expandable)

Accounts

Input Accounts

authority

Signer

required

Authority for input compressed accounts (must sign)

fee_payer

Signer, Writable

required

Pays transaction fees and provides lamports for compression

registered_program_pda

Account

PDA proving program is registered to use Merkle trees

noop_program

Program

Noop program for emitting events (SPL Noop)

account_compression_program

Program

Account compression program managing Merkle trees

merkle_tree_accounts

[Account]

State and address Merkle tree accounts (dynamic count)

nullifier_queue_accounts

[Account, Writable]

Nullifier queue accounts for spent account tracking

output_queue_accounts

[Account, Writable]

Output queue accounts for new compressed accounts

Error Codes

Common error codes (11000+ range):

Code	Error	Description
11001	`InvalidAuthority`	Authority check failed
11002	`InvalidProof`	ZK proof verification failed
11003	`SumCheckFailed`	Input/output lamports don’t match
11004	`InvalidMerkleTree`	Wrong Merkle tree account
11005	`InvalidNullifierQueue`	Wrong nullifier queue
11006	`DuplicateNullifier`	Nullifier already exists
11007	`InvalidAddress`	Address derivation failed
11008	`AddressAlreadyExists`	Address already in tree
11009	`InvalidCpiContext`	CPI context validation failed
11010	`InvalidProgramOwner`	Program not registered

Best Practices

Always Provide Valid Proofs

Inclusion and non-inclusion proofs must be fresh and correspond to current Merkle roots. Get proofs from Photon indexer.

Verify Sum Checks

Client-side verification: ensure total input lamports = total output lamports + fees. On-chain verification will reject mismatches.

Use CPI Context Properly

When calling via CPI, always initialize CPI context account first, then use two-phase (setup + execute) pattern.

Handle Nullifiers Correctly

Each compressed account can only be spent once. Track nullifiers to prevent double-spend attempts.

Programs that use compressed accounts must be registered with the account compression program.

Resources

Program Source

View on GitHub

SDK

TypeScript SDK (stateless.js)

Rust SDK

Rust program SDK

Examples

Program examples

Program Libraries

Program Instructions

System Program Instructions

Overview

Instruction Types

Invoke

InvokeCpi

CPI Context

Discriminators

Invoke

Instruction Data

Operations

Example

InvokeCpi

Instruction Data

CPI Context Account

CPI Flow

Example

InvokeCpiWithReadOnly

InitializeCpiContextAccount

Accounts

Input Accounts

Error Codes

Best Practices

Resources

Program Source

SDK

Rust SDK

Examples

Build docs developers (and LLMs) love

Program Libraries

Program Instructions

​Overview

​Instruction Types

Invoke

InvokeCpi

CPI Context

​Discriminators

​Invoke

​Instruction Data

​Operations

​Example

​InvokeCpi

​Instruction Data

​CPI Context Account

​CPI Flow

​Example

​InvokeCpiWithReadOnly

​InitializeCpiContextAccount

​Accounts

​Input Accounts

​Error Codes

​Best Practices

​Resources

Program Source

SDK

Rust SDK

Examples

Build docs developers (and LLMs) love

Overview

Instruction Types

Discriminators

Invoke

Instruction Data

Operations

Example

InvokeCpi

Instruction Data

CPI Context Account

CPI Flow

Example

InvokeCpiWithReadOnly

InitializeCpiContextAccount

Accounts

Input Accounts

Error Codes

Best Practices

Resources