light-sdk 0.19.0

//! LightFinalize and LightPreInit traits for compression operations.
//!
//! These traits are implemented by the `#[derive(LightFinalize)]` macro from light-sdk-macros.
//! They provide hooks for running compression operations at different points in an instruction:
//!
//! - `LightPreInit`: Called at START of instruction - creates mints via CPI context write
//! - `LightFinalize`: Called at END of instruction - compresses PDAs and executes with proof
//!
//! This two-phase design allows mints to be created BEFORE the instruction body runs,
//! so they can be used during the instruction (e.g., for vault creation, minting tokens).

use solana_account_info::AccountInfo;

/// Trait for pre-initialization operations (mint creation).
///
/// This is generated by `#[derive(LightFinalize)]` when `#[light_account(init)]` fields exist.
/// Called at the START of an instruction to write mint creation to CPI context.
///
/// The mints are written to CPI context but NOT executed yet - execution happens
/// in `light_finalize()` at the end, allowing the shared proof to cover both
/// mints and PDAs.
///
/// # Type Parameters
/// * `'info` - The account info lifetime
/// * `P` - The instruction params type (from `#[instruction(params: P)]`)
pub trait LightPreInit<'info, P> {
    /// Execute pre-initialization operations (mint creation).
    ///
    /// This writes mint creation operations to CPI context. The actual execution
    /// with proof happens in `light_finalize()`.
    ///
    /// # Arguments
    /// * `remaining_accounts` - The remaining accounts from the context, used for CPI
    /// * `params` - The instruction parameters containing compression data
    ///
    /// # Returns
    /// `true` if mints were written to CPI context and `light_finalize` should execute
    /// with CPI context. `false` if no mints exist and normal flow should proceed.
    fn light_pre_init(
        &mut self,
        remaining_accounts: &[AccountInfo<'info>],
        params: &P,
    ) -> Result<bool, crate::error::LightSdkError>;
}

/// Trait for finalizing compression operations on accounts.
///
/// # Type Parameters
/// * `'info` - The account info lifetime
/// * `P` - The instruction params type (from `#[instruction(params: P)]`)
///
pub trait LightFinalize<'info, P> {
    /// Execute compression finalization.
    ///
    /// This method is called at the end of an instruction to batch and execute
    /// all compression CPIs for accounts marked with `#[compressible(...)]`.
    ///
    /// # Arguments
    /// * `remaining_accounts` - The remaining accounts from the context, used for CPI
    /// * `params` - The instruction parameters containing compression data
    /// * `has_pre_init` - Whether `light_pre_init` was called and wrote to CPI context
    ///
    /// # Errors
    /// Returns an error if the compression CPI fails.
    fn light_finalize(
        &mut self,
        remaining_accounts: &[AccountInfo<'info>],
        params: &P,
        has_pre_init: bool,
    ) -> Result<(), crate::error::LightSdkError>;
}