wip

Author: SwenSchaeferjohann

Cargo.lock

@@ -21,6 +21,7 @@ default = []
 [dependencies]
 light-sdk = { workspace = true }
 light-sdk-types = { workspace = true }
+light-sdk-macros = { workspace = true }
 light-hasher = { workspace = true, features = ["solana"] }
 solana-program = { workspace = true }
 light-macros = { workspace = true, features = ["solana"] }

program-tests/sdk-test-derived/Cargo.toml

@@ -0,0 +1,276 @@
+# Native Solana Compressible Instructions Macro Usage
+
+This example demonstrates how to use the `add_native_compressible_instructions` macro for native Solana programs with flexible instruction dispatching.
+
+## Design Philosophy
+
+The macro generates thin wrapper processor functions that developers dispatch manually. This provides:
+
+- **Full control over instruction routing** - Use enums, constants, or any dispatch pattern
+- **Transparency** - developers see all available functions
+- **Flexibility** - Mix generated and custom instructions seamlessly
+- **Custom error handling** per instruction
+
+## Basic Usage with Enum Dispatch (Recommended)
+
+```rust
+use light_sdk_macros::add_native_compressible_instructions;
+use light_sdk::error::LightSdkError;
+use solana_program::{
+    account_info::AccountInfo,
+    entrypoint::ProgramResult,
+    program_error::ProgramError,
+    pubkey::Pubkey,
+};
+use borsh::BorshDeserialize;
+
+// Define your account structs with required traits
+#[derive(Default, Clone, Debug, BorshSerialize, BorshDeserialize, LightHasher, LightDiscriminator)]
+pub struct MyPdaAccount {
+    #[skip]  // Skip compression_info in hashing
+    pub compression_info: CompressionInfo,
+    #[hash]  // Hash pubkeys to field size
+    pub owner: Pubkey,
+    pub data: u64,
+}
+
+// Implement required trait
+impl HasCompressionInfo for MyPdaAccount {
+    fn compression_info(&self) -> &CompressionInfo {
+        &self.compression_info
+    }
+
+    fn compression_info_mut(&mut self) -> &mut CompressionInfo {
+        &mut self.compression_info
+    }
+}
+
+// Generate compression processors
+#[add_native_compressible_instructions(MyPdaAccount)]
+pub mod compression {
+    use super::*;
+}
+
+// Define instruction enum (flexible - you choose the discriminators)
+#[repr(u8)]
+pub enum InstructionType {
+    // Compression instructions (generated by macro)
+    CreateCompressionConfig = 0,
+    UpdateCompressionConfig = 1,
+    DecompressMultiplePdas = 2,
+    CompressMyPdaAccount = 3,
+
+    // Your custom instructions
+    CreateMyPdaAccount = 20,
+    UpdateMyPdaAccount = 21,
+}
+
+impl TryFrom<u8> for InstructionType {
+    type Error = LightSdkError;
+
+    fn try_from(value: u8) -> Result<Self, Self::Error> {
+        match value {
+            0 => Ok(InstructionType::CreateCompressionConfig),
+            1 => Ok(InstructionType::UpdateCompressionConfig),
+            2 => Ok(InstructionType::DecompressMultiplePdas),
+            3 => Ok(InstructionType::CompressMyPdaAccount),
+            20 => Ok(InstructionType::CreateMyPdaAccount),
+            21 => Ok(InstructionType::UpdateMyPdaAccount),
+            _ => Err(LightSdkError::ConstraintViolation),
+        }
+    }
+}
+
+// Dispatch in your process_instruction
+pub fn process_instruction(
+    program_id: &Pubkey,
+    accounts: &[AccountInfo],
+    instruction_data: &[u8],
+) -> ProgramResult {
+    if instruction_data.is_empty() {
+        return Err(ProgramError::InvalidInstructionData);
+    }
+
+    let discriminator = InstructionType::try_from(instruction_data[0])
+        .map_err(|_| ProgramError::InvalidInstructionData)?;
+    let data = &instruction_data[1..];
+
+    match discriminator {
+        InstructionType::CreateCompressionConfig => {
+            let params = compression::CreateCompressionConfigData::try_from_slice(data)?;
+            compression::create_compression_config(
+                accounts,
+                params.compression_delay,
+                params.rent_recipient,
+                params.address_space,
+            )
+        }
+        InstructionType::CompressMyPdaAccount => {
+            let params = compression::CompressMyPdaAccountData::try_from_slice(data)?;
+            compression::compress_my_pda_account(
+                accounts,
+                params.proof,
+                params.compressed_account_meta,
+            )
+        }
+        InstructionType::CreateMyPdaAccount => {
+            // Your custom create logic
+            create_my_pda_account(accounts, data)
+        }
+        // ... other instructions
+    }
+}
+```
+
+## Alternative: Constants-based Dispatch
+
+```rust
+// If you prefer constants (less type-safe but simpler)
+pub mod instruction {
+    pub const CREATE_COMPRESSION_CONFIG: u8 = 0;
+    pub const COMPRESS_MY_PDA_ACCOUNT: u8 = 3;
+    pub const CREATE_MY_PDA_ACCOUNT: u8 = 20;
+}
+
+pub fn process_instruction(
+    program_id: &Pubkey,
+    accounts: &[AccountInfo],
+    instruction_data: &[u8],
+) -> ProgramResult {
+    let discriminator = instruction_data[0];
+    let data = &instruction_data[1..];
+
+    match discriminator {
+        instruction::CREATE_COMPRESSION_CONFIG => {
+            let params = compression::CreateCompressionConfigData::try_from_slice(data)?;
+            compression::create_compression_config(/* ... */)
+        }
+        instruction::COMPRESS_MY_PDA_ACCOUNT => {
+            let params = compression::CompressMyPdaAccountData::try_from_slice(data)?;
+            compression::compress_my_pda_account(/* ... */)
+        }
+        instruction::CREATE_MY_PDA_ACCOUNT => {
+            create_my_pda_account(accounts, data)
+        }
+        _ => Err(ProgramError::InvalidInstructionData),
+    }
+}
+```
+
+## Generated Types and Functions
+
+The macro generates the following in your `compression` module:
+
+### Data Structures
+
+- `CompressedAccountVariant` - Enum of all compressible account types
+- `CompressedAccountData` - Wrapper for compressed account data with metadata
+- `CreateCompressionConfigData` - Instruction data for config creation
+- `UpdateCompressionConfigData` - Instruction data for config updates
+- `DecompressMultiplePdasData` - Instruction data for batch decompression
+- `Compress{AccountName}Data` - Instruction data for each account type
+
+### Processor Functions
+
+- `create_compression_config()` - Creates compression configuration
+- `update_compression_config()` - Updates compression configuration
+- `decompress_multiple_pdas()` - Decompresses multiple PDAs in one transaction
+- `compress_{account_name}()` - Compresses specific account type (snake_case)
+
+## Account Layouts
+
+Each processor function documents its expected account layout:
+
+### create_compression_config
+
+```
+0. [writable, signer] Payer account
+1. [writable] Config PDA (seeds: [b"compressible_config"])
+2. [] Program data account
+3. [signer] Program upgrade authority
+4. [] System program
+```
+
+### compress\_{account_name}
+
+```
+0. [signer] Authority
+1. [writable] PDA account to compress
+2. [] System program
+3. [] Config PDA
+4. [] Rent recipient (must match config)
+5... [] Light Protocol system accounts
+```
+
+### decompress_multiple_pdas
+
+```
+0. [writable, signer] Fee payer
+1. [writable, signer] Rent payer
+2. [] System program
+3..N. [writable] PDA accounts to decompress into
+N+1... [] Light Protocol system accounts
+```
+
+## Multiple Account Types
+
+```rust
+#[add_native_compressible_instructions(UserAccount, GameState, TokenVault)]
+pub mod compression {
+    use super::*;
+}
+```
+
+This generates compress functions for each type:
+
+- `compress_user_account()`
+- `compress_game_state()`
+- `compress_token_vault()`
+
+## Key Benefits
+
+1. **Flexible Dispatch**: Choose enums, constants, or any pattern you prefer
+2. **Manual Control**: You decide which instructions to expose and how to route them
+3. **Custom Business Logic**: Easy to add custom create/update instructions alongside compression
+4. **Clear Account Requirements**: Each function documents its exact account layout
+5. **Type Safety**: Borsh serialization ensures type-safe instruction data
+6. **Zero Assumptions**: Macro doesn't impose any instruction routing patterns
+
+## Client-Side Usage
+
+```typescript
+// TypeScript/JavaScript client example
+import { Connection, PublicKey, TransactionInstruction } from "@solana/web3.js";
+import * as borsh from "borsh";
+
+// Define instruction data schemas
+const CreateCompressionConfigSchema = borsh.struct([
+  borsh.u32("compression_delay"),
+  borsh.publicKey("rent_recipient"),
+  borsh.vec(borsh.publicKey(), "address_space"),
+]);
+
+// Build instruction with your chosen discriminator
+const instructionData = {
+  compression_delay: 100,
+  rent_recipient: rentRecipientPubkey,
+  address_space: [addressTreePubkey],
+};
+
+const serialized = borsh.serialize(
+  CreateCompressionConfigSchema,
+  instructionData
+);
+const instruction = new TransactionInstruction({
+  keys: [
+    /* account metas */
+  ],
+  programId: PROGRAM_ID,
+  data: Buffer.concat([
+    Buffer.from([0]), // Your chosen discriminator for CreateCompressionConfig
+    Buffer.from(serialized),
+  ]),
+});
+```
+
+The macro provides maximum flexibility while automating the compression boilerplate, letting you focus on your program's unique business logic.