Crate light_account_pinocchio

Source

Expand description

§Light Accounts Pinocchio

Rent-free Light Accounts and Light Token Accounts for Pinocchio programs.

§How It Works

Light Accounts (PDAs)

Create a Solana PDA normally
Register it with #[derive(LightProgramPinocchio)] - becomes a Light Account
Use it as normal Solana account
When rent runs out, account compresses (cold state)
State preserved on-chain, client loads when needed (hot state)

Light Token Accounts (associated token accounts, Vaults)

Use #[light_account(associated_token)] for associated token accounts
Use #[light_account(token::seeds = [...], token::owner_seeds = [...])] for vaults
Cold/hot lifecycle

Light Mints

Created via invoke_create_mints
Cold/hot lifecycle

§Quick Start

§1. Program Setup

use light_account_pinocchio::{derive_light_cpi_signer, CpiSigner, LightProgramPinocchio};
use pinocchio_pubkey::pubkey;

pub const ID: Pubkey = pubkey!("Your11111111111111111111111111111111111111");

pub const LIGHT_CPI_SIGNER: CpiSigner =
    derive_light_cpi_signer!("Your11111111111111111111111111111111111111");

§2. State Definition

use borsh::{BorshDeserialize, BorshSerialize};
use light_account_pinocchio::{CompressionInfo, LightDiscriminator, LightHasherSha};

#[derive(BorshSerialize, BorshDeserialize, LightDiscriminator, LightHasherSha)]
pub struct MyRecord {
    pub compression_info: CompressionInfo,  // Required first or last field
    pub owner: [u8; 32],
    pub data: u64,
}

§3. Program Accounts Enum

#[derive(LightProgramPinocchio)]
pub enum ProgramAccounts {
    #[light_account(pda::seeds = [b"record", ctx.owner])]
    MyRecord(MyRecord),
}

§Account Types

§1. Light Account (PDA)

#[light_account(pda::seeds = [b"record", ctx.owner])]
MyRecord(MyRecord),

§2. Light Account (zero-copy)

#[light_account(pda::seeds = [b"record", ctx.owner], pda::zero_copy)]
ZeroCopyRecord(ZeroCopyRecord),

§3. Light Token Account (vault)

#[light_account(token::seeds = [b"vault", ctx.mint], token::owner_seeds = [b"vault_auth"])]
Vault,

§4. Light Token Account (associated token account)

#[light_account(associated_token)]
Ata,

§Required Derives

Derive	Use
`LightDiscriminator`	State structs (8-byte discriminator)
`LightHasherSha`	State structs (compression hashing)
`LightProgramPinocchio`	Program accounts enum

§Required Macros

Macro	Use
`derive_light_cpi_signer!`	CPI signer PDA constant
`pinocchio_pubkey::pubkey!`	Program ID as `Pubkey`

For a complete example, see sdk-tests/pinocchio-light-program-test.

Re-exports§

pub extern crate light_account_checks;

Modules§

account_info
account_meta
close_account
compression_info
constants
packed_accounts
rent

Macros§

derive_light_cpi_signer: Derives a complete Light Protocol CPI configuration at runtime
derive_light_cpi_signer_pda: Derives a Light Protocol CPI signer PDA at compile time
pubkey_array: Converts a base58 encoded public key into a raw byte array [u8; 32].

Structs§

AccountInfo: Wrapper struct for an Account.
CompressAndCloseParams: Parameters for compress_and_close instruction. Matches SDK’s SaveAccountsData field order for compatibility.
CompressedAccountData: Compressed account data used when decompressing.
CompressedCpiContext
CompressionInfo: SDK CompressionInfo - a compact 24-byte struct for custom zero-copy PDAs.
CpiAccountsConfig
CpiSigner: Configuration struct containing program ID, CPI signer, and bump for Light Protocol
CreateAccountsProof: Proof data for instruction params when creating new compressed accounts. Used in the INIT flow - pass directly to instruction data. All accounts use the same address tree, so only one address_tree_info is needed.
DecompressIdempotentParams: Parameters for decompress_idempotent instruction. Generic over the variant type - each program defines its own PackedProgramAccountVariant.
InitializeLightConfigParams: Parameters for initialize_compression_config instruction. Uses [u8; 32] for pubkeys - borsh-compatible with solana_pubkey::Pubkey.
InstructionDataInvokeCpiWithAccountInfo
LightConfig: Global configuration for compressible accounts
OwnedAccountMeta: Owned account meta for pinocchio.
PackedAddressTreeInfo: Packed address tree info for instruction data. Contains indices to address tree accounts and root index.
PackedStateTreeInfo
UpdateLightConfigParams: Parameters for update_compression_config instruction.
ValidityProof

Enums§

AccountType
CompressionState: Compression state for SDK CompressionInfo.
LightSdkTypesError

Constants§

COMPRESSION_INFO_SIZE: Size of SDK CompressionInfo in bytes (24 bytes). Used for stripping CompressionInfo from Pod data during packing.
LIGHT_CONFIG_SEED
MAX_ADDRESS_TREES_PER_SPACE
OPTION_COMPRESSION_INFO_SPACE: Space required for Option when Some (1 byte discriminator + INIT_SPACE). Use this constant in account space calculations.

Traits§

AccountInfoTrait: Trait to abstract over different AccountInfo implementations (pinocchio vs solana)
AccountMetaTrait: Trait abstracting over AccountMeta implementations (solana vs pinocchio).
CompressAs: Override what gets stored when compressing. Return Self or a different type.
CompressedInitSpace: Account space when compressed.
CompressionInfoField: Simple field accessor trait for types with a compression_info: Option<CompressionInfo> field. Implement this trait and get HasCompressionInfo for free via blanket impl.
CpiAccountsTrait: Trait for types that can provide account infos and metas for Light system program CPI.
DecompressVariant: Trait for packed program account variants that support decompression.
HasCompressionInfo
HasTokenVariant: Trait for account variants that can be checked for token or PDA type.
IntoVariant: Trait for seeds that can construct a compressed account variant.
InvokeLightSystemProgram: Trait for invoking the Light system program via CPI.
LightAccount: Trait for compressible account data structs.
LightAccountVariantTrait: Trait for unpacked compressed account variants with seeds.
LightCpi: Base trait for Light CPI instruction types.
LightDiscriminator
LightFinalize: Trait for finalizing compression operations on accounts.
LightPreInit: Trait for pre-initialization operations (mint creation).
PackedAddressTreeInfoExt: Extension trait for PackedAddressTreeInfo SDK-specific methods. Since PackedAddressTreeInfo is defined in light-compressed-account, we use an extension trait to add methods that depend on SDK types.
PackedLightAccountVariantTrait: Trait for packed compressed account variants.
PdaSeedDerivation: Trait for PDA types that can derive seeds with full account context access.
Size: Trait to get the serialized size of a compressed account.
Space
Unpack

Functions§

claim_completed_epoch_rent: Claim completed-epoch rent to the provided rent sponsor and update last_claimed_slot. Returns Some(claimed) if any lamports were claimed; None if account is compressible or nothing to claim. Generic over AccountInfoTrait to work with both solana and pinocchio.
close_account: Close a native Solana account by transferring lamports and clearing data.
derive_rent_sponsor_pda: Derives the rent sponsor PDA for a given program.
extract_tail_accounts: Extract PDA accounts from the tail of remaining_accounts.
invoke_light_system_program: Low-level function to invoke the Light system program with a PDA signer.
invoke_write_pdas_to_cpi_context: Write compressed PDA data to CPI context for chaining with subsequent operations.
is_pda_initialized: Check if PDA account is already initialized (has non-zero discriminator).
light_err: Converts a LightSdkTypesError into a pinocchio::program_error::ProgramError.
prepare_account_for_compression: Generic prepare_account_for_compression.
prepare_account_for_decompression: Generic prepare_account_for_decompression.
prepare_compressed_account_on_init: Prepare a compressed account for a PDA during initialization.
process_compress_pda_accounts_idempotent: Process compress-and-close for PDA accounts (idempotent).
process_decompress_pda_accounts_idempotent: Process decompression for PDA accounts (idempotent, PDA-only).
process_initialize_light_config: Creates a new compressible config PDA.
process_initialize_light_config_checked: Initialize a LightConfig PDA with upgrade authority check.
process_update_light_config: Update an existing LightConfig PDA.
reimburse_rent: Reimburse the fee_payer for rent paid during PDA creation.
should_skip_compression: Check if account should be skipped during compression.
split_at_system_accounts_offset: Validate and split remaining_accounts at system_accounts_offset.
validate_compress_accounts: Extract and validate accounts for compress operations (4 accounts including compression_authority).
validate_decompress_accounts: Extract and validate accounts for decompress operations (3 accounts, no compression_authority).

Type Aliases§

CompressCtx
CompressDispatchFn
CpiAccounts
CpiContextWriteAccounts
DecompressCtx
ValidatedPdaContext

Derive Macros§

CompressAs: Legacy CompressAs trait implementation (use Compressible instead).
Discriminator: Derives a discriminator using SHA256(“account:{struct_name}”)[0..8].
HasCompressionInfo: Automatically implements the HasCompressionInfo trait for structs that have a compression_info: Option<CompressionInfo> field.
LightAccount: Generates a unified LightAccount trait implementation for light account structs.
LightDiscriminator: Derives a discriminator using SHA256(“{struct_name}”)[0..8].
LightHasher: Makes the annotated struct hashable by implementing the following traits:
LightHasherSha: SHA256 variant of the LightHasher derive macro.
LightPinocchioAccount: Pinocchio variant of LightAccount derive macro.
LightProgramPinocchio: Pinocchio variant of #[derive(LightProgram)].

Crate light_account_pinocchio

Crate light_account_pinocchio Copy item path

§Light Accounts Pinocchio

§How It Works

§Quick Start

§1. Program Setup

§2. State Definition

§3. Program Accounts Enum

§Account Types

§1. Light Account (PDA)

§2. Light Account (zero-copy)

§3. Light Token Account (vault)

§4. Light Token Account (associated token account)

§Required Derives

§Required Macros

Re-exports§

Modules§

Macros§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Derive Macros§

Crate light_account_pinocchio