docs: Add Light Protocol compression integration guide

Author: SwenSchaeferjohann

docs/LIGHT_COMPRESSION.md

@@ -0,0 +1,142 @@
+# Light Protocol Compression Integration
+
+## Fork Changes
+
+This fork adds compressed token support to anchor-spl's `token_interface`:
+
+```rust
+// anchor-spl/src/token_interface.rs
+pub const COMPRESSED_TOKEN_ID: Pubkey = ...;
+static IDS: [Pubkey; 3] = [spl_token::ID, spl_token_2022::ID, COMPRESSED_TOKEN_ID];
+```
+
+`InterfaceAccount<'info, Mint>` and `InterfaceAccount<'info, TokenAccount>` now work with compressed tokens.
+
+## TS SDK
+
+The TS SDK adds `decompressIfNeeded()` to method builders. It auto-decompresses accounts before instruction execution when needed.
+
+```typescript
+await program.methods
+  .swap(amount)
+  .decompressIfNeeded()  // auto-decompresses any compressed accounts
+  .rpc();
+```
+
+### Limitations
+
+- Cross-program PDAs (seeds::program) not supported for auto-resolution
+- Instruction argument seeds require explicit account addresses
+
+## Rust Macros (light-sdk-macros)
+
+### `#[add_compressible_instructions]`
+
+Add to `#[program]` module. Generates compress/decompress instructions for listed accounts.
+
+```rust
+#[add_compressible_instructions(
+    PoolState = (POOL_SEED, ctx.accounts.amm_config, ctx.accounts.token_0_mint, ctx.accounts.token_1_mint),
+    LpVault = (is_token, POOL_VAULT_SEED, ctx.accounts.lp_mint, authority = AUTH_SEED),
+)]
+#[program]
+pub mod my_program { ... }
+```
+
+### `#[derive(LightFinalize)]` + `#[compressible]`
+
+Auto-compresses PDAs at instruction end.
+
+```rust
+#[derive(Accounts, LightFinalize)]
+#[instruction(params: MyParams)]
+pub struct MyInstruction<'info> {
+    #[account(mut)]
+    pub creator: Signer<'info>,
+
+    #[account(init, payer = creator, space = 8 + MyAccount::INIT_SPACE, seeds = [...], bump)]
+    #[compressible(
+        address_tree_info = params.address_tree_info,
+        output_tree = params.output_state_tree_index
+    )]
+    pub my_account: Account<'info, MyAccount>,
+
+    pub compression_config: AccountInfo<'info>,
+}
+```
+
+### `#[light_instruction(params)]`
+
+Auto-calls `light_finalize()` at instruction end.
+
+```rust
+#[light_instruction(params)]
+pub fn create_account(ctx: Context<MyInstruction>, params: MyParams) -> Result<()> {
+    // your logic
+    Ok(())  // light_finalize auto-called here
+}
+```
+
+## Required Program Setup
+
+```rust
+use light_sdk_types::CpiSigner;
+use light_macros::derive_light_cpi_signer;
+
+pub const LIGHT_CPI_SIGNER: CpiSigner = derive_light_cpi_signer!("YOUR_PROGRAM_ID");
+```
+
+## What's NOT Supported
+
+- `#[light_mint]` attribute - use `light_ctoken_sdk` directly for mint creation
+- Mixed PDAs + mints in single `LightFinalize` - handle mints manually
+
+## Gotchas
+
+1. **Fee payer field**: LightFinalize looks for `fee_payer`, `payer`, or `creator` field names
+2. **compression_config field**: Required field in accounts struct - must be `AccountInfo<'info>`
+3. **params struct**: First `#[instruction(...)]` arg is used for compression params. Must contain `proof: ValidityProof` and tree info fields.
+4. **remaining_accounts**: Light system accounts go in remaining_accounts - client must pass them
+5. **Token accounts/mints**: Use `light_ctoken_sdk` directly (`CreateCTokenAccountCpi`, `CTokenMintToCpi`). Don't use `#[compressible]` on token accounts.
+6. **Only PDAs**: `#[compressible]` only works on `Account<'info, T>` fields, not token accounts or mints
+
+## Example: Mixed PDA + Token Setup (raydium-cp-swap pattern)
+
+```rust
+#[derive(Accounts, LightFinalize)]
+#[instruction(params: MyParams)]
+pub struct Initialize<'info> {
+    #[account(mut)]
+    pub creator: Signer<'info>,
+
+    // PDA - auto-compressed via LightFinalize
+    #[account(init, ...)]
+    #[compressible(address_tree_info = params.tree_info, output_tree = params.output_tree)]
+    pub my_pda: Account<'info, MyState>,
+
+    // Token vault - manual compression via SDK
+    /// CHECK: Created via CreateCTokenAccountCpi
+    #[account(mut)]
+    pub token_vault: UncheckedAccount<'info>,
+
+    // Mint - manual creation via SDK
+    /// CHECK: Created via Light SDK CreateCMint
+    #[account(mut)]
+    pub my_mint: UncheckedAccount<'info>,
+
+    pub compression_config: AccountInfo<'info>,
+    // ... light system accounts in remaining_accounts
+}
+
+#[light_instruction(params)]
+pub fn initialize(ctx: Context<Initialize>, params: MyParams) -> Result<()> {
+    // Manual token vault creation
+    CreateCTokenAccountCpi { ... }.invoke_signed(...)?;
+    
+    // Manual mint creation (if needed)
+    // ... use light_ctoken_sdk
+    
+    // PDA (my_pda) auto-compressed at end via light_finalize
+    Ok(())
+}
+```