Solana Program Architecture

Deep dive into the Solana program implementation, account management, and program-derived addresses (PDAs) for StyxPay.

Table of Contents

1. Program Structure

2. Account Model

3. Program Derived Addresses

4. Instruction Processing

5. Cross-Program Invocations

6. Compute Budget Management

7. Security Model

---

Program Structure

Program Entry Point

use anchor_lang::prelude::*;

declare_id!("STYXpaydm3KVEKCUNb4QJdYsV7KJbBywKq8Qn5X2VUK");

#[program]
pub mod styxpay_settlement {
    use super::*;

    pub fn initialize(
        ctx: Context<Initialize>,
        params: InitializeParams,
    ) -> Result<()> {
        initialize::handler(ctx, params)
    }

    pub fn create_user_account(
        ctx: Context<CreateUserAccount>,
    ) -> Result<()> {
        create_user_account::handler(ctx)
    }

    pub fn deposit(
        ctx: Context<Deposit>,
        amount: u64,
    ) -> Result<()> {
        deposit::handler(ctx, amount)
    }

    pub fn settle_transaction(
        ctx: Context<SettleTransaction>,
        proof: CompressedProof,
        public_inputs: PublicInputs,
    ) -> Result<()> {
        settle_transaction::handler(ctx, proof, public_inputs)
    }

    pub fn withdraw(
        ctx: Context<Withdraw>,
        amount: u64,
        proof: WithdrawalProof,
    ) -> Result<()> {
        withdraw::handler(ctx, amount, proof)
    }

    pub fn update_policy(
        ctx: Context<UpdatePolicy>,
        new_policy: AuthorizationPolicy,
    ) -> Result<()> {
        update_policy::handler(ctx, new_policy)
    }
}

Module Organization

programs/styxpay-settlement/
├── src/
│   ├── lib.rs                    # Program entry point
│   ├── state/
│   │   ├── mod.rs
│   │   ├── settlement_state.rs   # Global state
│   │   ├── user_account.rs       # User account state
│   │   ├── nullifier_set.rs      # Nullifier tracking
│   │   └── merkle_tree.rs        # Merkle tree state
│   ├── instructions/
│   │   ├── mod.rs
│   │   ├── initialize.rs         # Program initialization
│   │   ├── create_user_account.rs
│   │   ├── deposit.rs
│   │   ├── settle_transaction.rs
│   │   ├── withdraw.rs
│   │   └── update_policy.rs
│   ├── crypto/
│   │   ├── mod.rs
│   │   ├── groth16.rs            # ZK proof verification
│   │   ├── poseidon.rs           # Hash function
│   │   ├── pedersen.rs           # Commitments
│   │   └── merkle.rs             # Merkle proofs
│   ├── error.rs                  # Error definitions
│   └── events.rs                 # Event definitions
└── Cargo.toml

---

Account Model

Account Layout

Solana accounts have a strict layout:

┌──────────────────────────────────────┐
│ Discriminator (8 bytes)              │ Anchor account type identifier
├──────────────────────────────────────┤
│ Account Data                         │ Custom fields
│ - Field 1                            │
│ - Field 2                            │
│ - ...                                │
├──────────────────────────────────────┤
│ Reserved Space (optional)            │ For future upgrades
└──────────────────────────────────────┘

Settlement State Account

#[account]
#[derive(Default)]
pub struct SettlementState {
    /// Program authority (can upgrade program)
    pub authority: Pubkey,              // 32 bytes

    /// Bump seed for PDA derivation
    pub bump: u8,                       // 1 byte

    /// Paused state (for emergency stops)
    pub paused: bool,                   // 1 byte

    /// Verifying key for Groth16 proofs
    pub verifying_key: VerifyingKey,    // 512 bytes

    /// Current merkle root of account tree
    pub merkle_root: [u8; 32],         // 32 bytes

    /// Tree depth (max accounts = 2^depth)
    pub tree_depth: u8,                 // 1 byte

    /// Next available leaf index
    pub next_leaf_index: u64,           // 8 bytes

    /// Total number of user accounts
    pub account_count: u64,             // 8 bytes

    /// Total transactions processed
    pub transaction_count: u64,         // 8 bytes

    /// Total volume (in smallest unit)
    pub total_volume: u128,             // 16 bytes

    /// Fees collected
    pub fees_collected: u64,            // 8 bytes

    /// Minimum deposit amount
    pub min_deposit: u64,               // 8 bytes

    /// Maximum transaction amount
    pub max_transaction: u64,           // 8 bytes

    /// Fee basis points (1 bp = 0.01%)
    pub fee_bps: u16,                   // 2 bytes

    /// Last update timestamp
    pub last_update: i64,               // 8 bytes

    /// Reserved for future use
    pub reserved: [u64; 32],            // 256 bytes
}

impl SettlementState {
    pub const LEN: usize = 8 +          // discriminator
                           32 +          // authority
                           1 +           // bump
                           1 +           // paused
                           512 +         // verifying_key
                           32 +          // merkle_root
                           1 +           // tree_depth
                           8 +           // next_leaf_index
                           8 +           // account_count
                           8 +           // transaction_count
                           16 +          // total_volume
                           8 +           // fees_collected
                           8 +           // min_deposit
                           8 +           // max_transaction
                           2 +           // fee_bps
                           8 +           // last_update
                           256;          // reserved

    pub fn is_authorized(&self, authority: &Pubkey) -> bool {
        self.authority == *authority
    }

    pub fn can_process_transaction(&self) -> bool {
        !self.paused
    }
}

User Account

#[account]
pub struct UserAccount {
    /// Account owner
    pub owner: Pubkey,                      // 32 bytes

    /// Bump seed for PDA
    pub bump: u8,                           // 1 byte

    /// Account status flags
    pub flags: AccountFlags,                // 1 byte

    /// Pedersen commitment to current balance
    /// C = balance * G + blinding_factor * H
    pub balance_commitment: [u8; 32],       // 32 bytes

    /// Poseidon hash of account state
    pub state_hash: [u8; 32],               // 32 bytes

    /// Position in merkle tree
    pub leaf_index: u64,                    // 8 bytes

    /// Account creation time
    pub created_at: i64,                    // 8 bytes

    /// Last activity timestamp
    pub last_activity: i64,                 // 8 bytes

    /// Total amount deposited (plaintext for auditing)
    pub total_deposited: u64,               // 8 bytes

    /// Total amount withdrawn (plaintext for auditing)
    pub total_withdrawn: u64,               // 8 bytes

    /// Transaction count
    pub transaction_count: u64,             // 8 bytes

    /// Authorization policy hash
    pub policy_hash: [u8; 32],              // 32 bytes

    /// Daily spending limit (encrypted)
    pub daily_limit: EncryptedValue,        // 48 bytes

    /// Current day's spending (encrypted)
    pub daily_spent: EncryptedValue,        // 48 bytes

    /// Last reset timestamp for daily limit
    pub daily_reset_at: i64,                // 8 bytes

    /// Reserved space
    pub reserved: [u64; 16],                // 128 bytes
}

impl UserAccount {
    pub const LEN: usize = 8 +              // discriminator
                           32 +              // owner
                           1 +               // bump
                           1 +               // flags
                           32 +              // balance_commitment
                           32 +              // state_hash
                           8 +               // leaf_index
                           8 +               // created_at
                           8 +               // last_activity
                           8 +               // total_deposited
                           8 +               // total_withdrawn
                           8 +               // transaction_count
                           32 +              // policy_hash
                           48 +              // daily_limit
                           48 +              // daily_spent
                           8 +               // daily_reset_at
                           128;              // reserved

    pub fn update_commitment(
        &mut self,
        new_commitment: [u8; 32],
    ) -> Result<()> {
        self.balance_commitment = new_commitment;
        self.last_activity = Clock::get()?.unix_timestamp;
        Ok(())
    }

    pub fn increment_transaction_count(&mut self) -> Result<()> {
        self.transaction_count = self.transaction_count
            .checked_add(1)
            .ok_or(ErrorCode::Overflow)?;
        Ok(())
    }

    pub fn check_daily_limit(&mut self, amount: u64) -> Result<()> {
        let now = Clock::get()?.unix_timestamp;

        // Reset if new day
        if now - self.daily_reset_at > 86400 {
            self.daily_spent = EncryptedValue::zero();
            self.daily_reset_at = now;
        }

        // Check limit (requires decryption in practice)
        // For now, simplified check
        require!(
            self.is_within_daily_limit(amount),
            ErrorCode::DailyLimitExceeded
        );

        Ok(())
    }

    fn is_within_daily_limit(&self, amount: u64) -> bool {
        // In practice, this would use homomorphic encryption
        // to check without decrypting
        true
    }
}

#[derive(AnchorSerialize, AnchorDeserialize, Clone, Copy, PartialEq, Eq)]
pub struct AccountFlags {
    bits: u8,
}

impl AccountFlags {
    pub const ACTIVE: u8 = 1 << 0;
    pub const FROZEN: u8 = 1 << 1;
    pub const KYC_VERIFIED: u8 = 1 << 2;
    pub const PREMIUM: u8 = 1 << 3;

    pub fn is_active(&self) -> bool {
        self.bits & Self::ACTIVE != 0
    }

    pub fn is_frozen(&self) -> bool {
        self.bits & Self::FROZEN != 0
    }

    pub fn is_kyc_verified(&self) -> bool {
        self.bits & Self::KYC_VERIFIED != 0
    }
}

Nullifier Set Account

#[account]
pub struct NullifierSet {
    /// Authority
    pub authority: Pubkey,                  // 32 bytes

    /// Bump seed
    pub bump: u8,                           // 1 byte

    /// Bloom filter for fast duplicate checking
    /// 8KB bloom filter with 3 hash functions
    /// False positive rate: ~0.001% for 100K nullifiers
    pub bloom_filter: [u64; 1024],         // 8,192 bytes

    /// Sparse merkle tree root of all nullifiers
    pub nullifier_tree_root: [u8; 32],     // 32 bytes

    /// Number of nullifiers in set
    pub count: u64,                         // 8 bytes

    /// Maximum capacity before resize needed
    pub capacity: u64,                      // 8 bytes

    /// Reserved
    pub reserved: [u64; 8],                 // 64 bytes
}

impl NullifierSet {
    pub const LEN: usize = 8 +              // discriminator
                           32 +              // authority
                           1 +               // bump
                           8192 +            // bloom_filter
                           32 +              // nullifier_tree_root
                           8 +               // count
                           8 +               // capacity
                           64;               // reserved

    pub fn insert(&mut self, nullifier: &[u8; 32]) -> Result<()> {
        // Check capacity
        require!(
            self.count < self.capacity,
            ErrorCode::NullifierSetFull
        );

        // Check if already exists (bloom filter)
        if self.bloom_filter_contains(nullifier) {
            // Might be false positive, check sparse merkle tree
            require!(
                !self.tree_contains(nullifier),
                ErrorCode::NullifierAlreadyUsed
            );
        }

        // Add to bloom filter
        self.bloom_filter_insert(nullifier);

        // Add to sparse merkle tree
        self.tree_insert(nullifier)?;

        // Increment count
        self.count = self.count
            .checked_add(1)
            .ok_or(ErrorCode::Overflow)?;

        Ok(())
    }

    fn bloom_filter_insert(&mut self, nullifier: &[u8; 32]) {
        for i in 0..3 {
            let hash = Self::bloom_hash(nullifier, i);
            let index = (hash >> 6) as usize % 1024;
            let bit = hash & 63;
            self.bloom_filter[index] |= 1u64 << bit;
        }
    }

    fn bloom_filter_contains(&self, nullifier: &[u8; 32]) -> bool {
        for i in 0..3 {
            let hash = Self::bloom_hash(nullifier, i);
            let index = (hash >> 6) as usize % 1024;
            let bit = hash & 63;
            if self.bloom_filter[index] & (1u64 << bit) == 0 {
                return false;
            }
        }
        true
    }

    fn bloom_hash(nullifier: &[u8; 32], seed: u8) -> u64 {
        use std::collections::hash_map::DefaultHasher;
        use std::hash::{Hash, Hasher};

        let mut hasher = DefaultHasher::new();
        nullifier.hash(&mut hasher);
        seed.hash(&mut hasher);
        hasher.finish()
    }

    fn tree_contains(&self, nullifier: &[u8; 32]) -> bool {
        // Check sparse merkle tree (requires additional account data)
        // Implementation depends on tree storage strategy
        false
    }

    fn tree_insert(&mut self, nullifier: &[u8; 32]) -> Result<()> {
        // Insert into sparse merkle tree
        // Update nullifier_tree_root
        Ok(())
    }
}

---

Program Derived Addresses

PDA Derivation

pub struct PDA;

impl PDA {
    /// Settlement state PDA
    /// Seeds: ["settlement_state"]
    pub fn settlement_state() -> (Pubkey, u8) {
        Pubkey::find_program_address(
            &[b"settlement_state"],
            &crate::ID,
        )
    }

    /// User account PDA
    /// Seeds: ["user_account", user_pubkey]
    pub fn user_account(owner: &Pubkey) -> (Pubkey, u8) {
        Pubkey::find_program_address(
            &[b"user_account", owner.as_ref()],
            &crate::ID,
        )
    }

    /// Vault PDA (holds tokens)
    /// Seeds: ["vault", settlement_state_pubkey]
    pub fn vault(settlement_state: &Pubkey) -> (Pubkey, u8) {
        Pubkey::find_program_address(
            &[b"vault", settlement_state.as_ref()],
            &crate::ID,
        )
    }

    /// Nullifier set PDA
    /// Seeds: ["nullifier_set", epoch]
    pub fn nullifier_set(epoch: u64) -> (Pubkey, u8) {
        Pubkey::find_program_address(
            &[b"nullifier_set", &epoch.to_le_bytes()],
            &crate::ID,
        )
    }

    /// Merkle tree PDA
    /// Seeds: ["merkle_tree", tree_id]
    pub fn merkle_tree(tree_id: u64) -> (Pubkey, u8) {
        Pubkey::find_program_address(
            &[b"merkle_tree", &tree_id.to_le_bytes()],
            &crate::ID,
        )
    }

    /// Authorization policy PDA
    /// Seeds: ["policy", user_pubkey, policy_id]
    pub fn authorization_policy(
        owner: &Pubkey,
        policy_id: u64,
    ) -> (Pubkey, u8) {
        Pubkey::find_program_address(
            &[
                b"policy",
                owner.as_ref(),
                &policy_id.to_le_bytes(),
            ],
            &crate::ID,
        )
    }
}

PDA Signing

pub fn sign_with_pda<'info>(
    settlement_state: &Account<'info, SettlementState>,
    instruction: Instruction,
    accounts: &[AccountInfo<'info>],
) -> Result<()> {
    // Derive PDA seeds
    let seeds = &[
        b"settlement_state",
        &[settlement_state.bump],
    ];
    let signer = &[&seeds[..]];

    // Execute instruction with PDA as signer
    invoke_signed(
        &instruction,
        accounts,
        signer,
    )?;

    Ok(())
}

---

Instruction Processing

Initialize Instruction

#[derive(Accounts)]
pub struct Initialize<'info> {
    #[account(mut)]
    pub authority: Signer<'info>,

    #[account(
        init,
        payer = authority,
        space = SettlementState::LEN,
        seeds = [b"settlement_state"],
        bump
    )]
    pub settlement_state: Account<'info, SettlementState>,

    #[account(
        init,
        payer = authority,
        space = NullifierSet::LEN,
        seeds = [b"nullifier_set", &0u64.to_le_bytes()],
        bump
    )]
    pub nullifier_set: Account<'info, NullifierSet>,

    /// CHECK: Vault PDA will be initialized by CPI
    #[account(
        mut,
        seeds = [b"vault", settlement_state.key().as_ref()],
        bump
    )]
    pub vault: AccountInfo<'info>,

    pub token_program: Program<'info, Token>,
    pub system_program: Program<'info, System>,
    pub rent: Sysvar<'info, Rent>,
}

pub fn handler(
    ctx: Context<Initialize>,
    params: InitializeParams,
) -> Result<()> {
    let state = &mut ctx.accounts.settlement_state;

    // Set authority
    state.authority = ctx.accounts.authority.key();
    state.bump = *ctx.bumps.get("settlement_state").unwrap();

    // Initialize verifying key
    state.verifying_key = params.verifying_key;

    // Initialize merkle tree
    state.merkle_root = params.initial_merkle_root;
    state.tree_depth = params.tree_depth;
    state.next_leaf_index = 0;

    // Initialize counters
    state.account_count = 0;
    state.transaction_count = 0;
    state.total_volume = 0;
    state.fees_collected = 0;

    // Set limits
    state.min_deposit = params.min_deposit;
    state.max_transaction = params.max_transaction;
    state.fee_bps = params.fee_bps;

    // Set timestamp
    state.last_update = Clock::get()?.unix_timestamp;

    // Initialize nullifier set
    let nullifier_set = &mut ctx.accounts.nullifier_set;
    nullifier_set.authority = ctx.accounts.authority.key();
    nullifier_set.bump = *ctx.bumps.get("nullifier_set").unwrap();
    nullifier_set.count = 0;
    nullifier_set.capacity = 1_000_000; // 1M nullifiers

    // Create vault token account
    create_vault_token_account(
        &ctx.accounts.vault,
        &state.to_account_info(),
        &params.mint,
        &ctx.accounts.authority,
        &ctx.accounts.system_program,
        &ctx.accounts.token_program,
        &ctx.accounts.rent,
    )?;

    msg!("Settlement program initialized");
    Ok(())
}

Create User Account Instruction

#[derive(Accounts)]
pub struct CreateUserAccount<'info> {
    #[account(mut)]
    pub owner: Signer<'info>,

    #[account(
        init,
        payer = owner,
        space = UserAccount::LEN,
        seeds = [b"user_account", owner.key().as_ref()],
        bump
    )]
    pub user_account: Account<'info, UserAccount>,

    #[account(mut)]
    pub settlement_state: Account<'info, SettlementState>,

    pub system_program: Program<'info, System>,
}

pub fn handler(ctx: Context<CreateUserAccount>) -> Result<()> {
    let user_account = &mut ctx.accounts.user_account;
    let state = &mut ctx.accounts.settlement_state;

    // Initialize user account
    user_account.owner = ctx.accounts.owner.key();
    user_account.bump = *ctx.bumps.get("user_account").unwrap();
    user_account.flags = AccountFlags { bits: AccountFlags::ACTIVE };

    // Set zero balance commitment
    user_account.balance_commitment = [0u8; 32];

    // Assign leaf index
    user_account.leaf_index = state.next_leaf_index;
    state.next_leaf_index = state.next_leaf_index
        .checked_add(1)
        .ok_or(ErrorCode::Overflow)?;

    // Set timestamps
    let now = Clock::get()?.unix_timestamp;
    user_account.created_at = now;
    user_account.last_activity = now;
    user_account.daily_reset_at = now;

    // Initialize counters
    user_account.total_deposited = 0;
    user_account.total_withdrawn = 0;
    user_account.transaction_count = 0;

    // Increment account count
    state.account_count = state.account_count
        .checked_add(1)
        .ok_or(ErrorCode::Overflow)?;

    emit!(UserAccountCreated {
        owner: ctx.accounts.owner.key(),
        account: user_account.key(),
        leaf_index: user_account.leaf_index,
        created_at: now,
    });

    Ok(())
}

---

Cross-Program Invocations

Invoking SPL Token

use anchor_spl::token::{self, Token, TokenAccount, Transfer};

pub fn transfer_from_vault<'info>(
    vault: &Account<'info, TokenAccount>,
    destination: &Account<'info, TokenAccount>,
    authority: &AccountInfo<'info>,
    token_program: &Program<'info, Token>,
    amount: u64,
    signer_seeds: &[&[&[u8]]],
) -> Result<()> {
    let cpi_accounts = Transfer {
        from: vault.to_account_info(),
        to: destination.to_account_info(),
        authority: authority.clone(),
    };

    let cpi_program = token_program.to_account_info();
    let cpi_ctx = CpiContext::new_with_signer(
        cpi_program,
        cpi_accounts,
        signer_seeds,
    );

    token::transfer(cpi_ctx, amount)?;

    Ok(())
}

Invoking System Program

use anchor_lang::system_program::{self, Transfer as SystemTransfer};

pub fn transfer_lamports<'info>(
    from: &Signer<'info>,
    to: &AccountInfo<'info>,
    system_program: &Program<'info, System>,
    amount: u64,
) -> Result<()> {
    let cpi_accounts = SystemTransfer {
        from: from.to_account_info(),
        to: to.clone(),
    };

    let cpi_program = system_program.to_account_info();
    let cpi_ctx = CpiContext::new(cpi_program, cpi_accounts);

    system_program::transfer(cpi_ctx, amount)?;

    Ok(())
}

---

Compute Budget Management

Compute Unit Calculation

pub fn estimate_compute_units(
    instruction_type: InstructionType,
) -> u32 {
    match instruction_type {
        InstructionType::Initialize => 50_000,
        InstructionType::CreateUserAccount => 30_000,
        InstructionType::Deposit => 40_000,
        InstructionType::SettleTransaction => 200_000, // ZK verification is expensive
        InstructionType::Withdraw => 50_000,
        InstructionType::UpdatePolicy => 20_000,
    }
}

Request Compute Units

use solana_sdk::compute_budget::ComputeBudgetInstruction;

pub fn build_transaction_with_compute_budget(
    instructions: Vec<Instruction>,
    payer: &Pubkey,
    recent_blockhash: Hash,
) -> Transaction {
    let mut all_instructions = vec![
        // Set compute unit limit
        ComputeBudgetInstruction::set_compute_unit_limit(400_000),

        // Set priority fee (micro-lamports per CU)
        ComputeBudgetInstruction::set_compute_unit_price(1_000),
    ];

    all_instructions.extend(instructions);

    Transaction::new_with_payer(
        &all_instructions,
        Some(payer),
    )
}

---

Security Model

Access Control

pub fn check_authority(
    state: &SettlementState,
    signer: &Signer,
) -> Result<()> {
    require!(
        state.authority == signer.key(),
        ErrorCode::Unauthorized
    );
    Ok(())
}

pub fn check_user_ownership(
    user_account: &UserAccount,
    signer: &Signer,
) -> Result<()> {
    require!(
        user_account.owner == signer.key(),
        ErrorCode::Unauthorized
    );
    Ok(())
}

Emergency Pause

pub fn emergency_pause(
    ctx: Context<EmergencyPause>,
) -> Result<()> {
    let state = &mut ctx.accounts.settlement_state;

    // Only authority can pause
    check_authority(state, &ctx.accounts.authority)?;

    state.paused = true;

    emit!(ProgramPaused {
        timestamp: Clock::get()?.unix_timestamp,
    });

    Ok(())
}

pub fn unpause(
    ctx: Context<Unpause>,
) -> Result<()> {
    let state = &mut ctx.accounts.settlement_state;

    check_authority(state, &ctx.accounts.authority)?;

    state.paused = false;

    emit!(ProgramUnpaused {
        timestamp: Clock::get()?.unix_timestamp,
    });

    Ok(())
}

---

Related Documentation

• Transaction Settlement

• ZK Proof System

• Security Audit

---

Last Updated: January 2026 Version: 1.0.0