Transfer Interface

Program and client guide for transfers between light-token and SPL token accounts. The interface detects account types and invokes the right programs.

---

light-token -> light-token Account	Transfers tokens between light-token accounts
SPL token -> light-token Account	Transfers SPL tokens to light-token accounts SPL tokens are locked in interface PDA Tokens are minted to light-token account
light-token -> SPL Account	Releases SPL tokens from interface PDA to SPL account Burns tokens in source light-token account

Get Started

TypeScript Client

The transferInterface function transfers tokens between token accounts (SPL, Token-2022, or Light) in a single call.

Compare to SPL:

Find the source code here.

1. Transfer Interface

   Installation

   npm

   Install packages in your working directory:

   npm install @lightprotocol/stateless.js@beta \
               @lightprotocol/compressed-token@beta
   

   Install the CLI globally:

   npm install -g @lightprotocol/zk-compression-cli@beta
   

   yarn

   Install packages in your working directory:

   yarn add @lightprotocol/stateless.js@beta \
            @lightprotocol/compressed-token@beta
   

   Install the CLI globally:

   yarn global add @lightprotocol/zk-compression-cli@beta
   

   pnpm

   Install packages in your working directory:

   pnpm add @lightprotocol/stateless.js@beta \
            @lightprotocol/compressed-token@beta
   

   Install the CLI globally:

   pnpm add -g @lightprotocol/zk-compression-cli@beta
   

   Localnet

   # start local test-validator in a separate terminal
   light test-validator
   

   In the code examples, use createRpc() without arguments for localnet.

   Devnet

   Get an API key from Helius and add to .env:

   .env

   API_KEY=<your-helius-api-key>
   

   In the code examples, use createRpc(RPC_URL) with the devnet URL.

   Action

   import "dotenv/config";
   import { Keypair } from "@solana/web3.js";
   import { createRpc } from "@lightprotocol/stateless.js";
   import {
       createMintInterface,
       createAtaInterface,
       mintToInterface,
       transferInterface,
       getAssociatedTokenAddressInterface,
   } from "@lightprotocol/compressed-token";
   import { homedir } from "os";
   import { readFileSync } from "fs";
   
   // devnet:
   const RPC_URL = `https://devnet.helius-rpc.com?api-key=${process.env.API_KEY!}`;
   const rpc = createRpc(RPC_URL);
   // localnet:
   // const rpc = createRpc();
   
   const payer = Keypair.fromSecretKey(
       new Uint8Array(
           JSON.parse(readFileSync(`${homedir()}/.config/solana/id.json`, "utf8"))
       )
   );
   
   (async function () {
       const { mint } = await createMintInterface(rpc, payer, payer, null, 9);
   
       const sender = Keypair.generate();
       await createAtaInterface(rpc, payer, mint, sender.publicKey);
       const senderAta = getAssociatedTokenAddressInterface(mint, sender.publicKey);
       await mintToInterface(rpc, payer, mint, senderAta, payer, 1_000_000_000);
   
       const recipient = Keypair.generate();
       await createAtaInterface(rpc, payer, mint, recipient.publicKey);
       const recipientAta = getAssociatedTokenAddressInterface(mint, recipient.publicKey);
   
       const tx = await transferInterface(rpc, payer, senderAta, mint, recipientAta, sender, 500_000_000);
   
       console.log("Tx:", tx);
   })();
   

   Instruction

   import "dotenv/config";
   import {
       Keypair,
       ComputeBudgetProgram,
       Transaction,
       sendAndConfirmTransaction,
   } from "@solana/web3.js";
   import { createRpc } from "@lightprotocol/stateless.js";
   import {
       createMintInterface,
       createAtaInterface,
       mintToInterface,
       createTransferInterfaceInstruction,
       getAssociatedTokenAddressInterface,
   } from "@lightprotocol/compressed-token";
   import { homedir } from "os";
   import { readFileSync } from "fs";
   
   // devnet:
   const RPC_URL = `https://devnet.helius-rpc.com?api-key=${process.env.API_KEY!}`;
   const rpc = createRpc(RPC_URL);
   // localnet:
   // const rpc = createRpc();
   
   const payer = Keypair.fromSecretKey(
       new Uint8Array(
           JSON.parse(readFileSync(`${homedir()}/.config/solana/id.json`, "utf8"))
       )
   );
   
   (async function () {
       const { mint } = await createMintInterface(rpc, payer, payer, null, 9);
   
       const sender = Keypair.generate();
       await createAtaInterface(rpc, payer, mint, sender.publicKey);
       const senderAta = getAssociatedTokenAddressInterface(
           mint,
           sender.publicKey
       );
       await mintToInterface(rpc, payer, mint, senderAta, payer, 1_000_000_000);
   
       const recipient = Keypair.generate();
       await createAtaInterface(rpc, payer, mint, recipient.publicKey);
       const recipientAta = getAssociatedTokenAddressInterface(
           mint,
           recipient.publicKey
       );
   
       const ix = createTransferInterfaceInstruction(
           senderAta,
           recipientAta,
           sender.publicKey,
           500_000_000
       );
   
       const tx = new Transaction().add(ix);
       const signature = await sendAndConfirmTransaction(rpc, tx, [payer, sender]);
   
       console.log("Tx:", signature);
   })();
   

Rust Client

The example transfers SPL token -> light-token and light-token -> light-token:

1. Create SPL mint, SPL token accounts, and mint SPL tokens
2. Send SPL tokens to light-token account to mint light-tokens.
3. Transfer light-tokens to another light-token account.

1. Prerequisites

   Dependencies

   Cargo.toml

   [dependencies]
   light-compressed-token-sdk = "0.1"
   light-client = "0.1"
   light-token-types = "0.1"
   solana-sdk = "2.2"
   borsh = "0.10"
   tokio = { version = "1.36", features = ["full"] }
   
   [dev-dependencies]
   light-program-test = "0.1"  # For in-memory tests with LiteSVM
   

   Developer Environment

   In-Memory (LightProgramTest)

   Test with Lite-SVM (…)

   # Initialize project
   cargo init my-light-project
   cd my-light-project
   
   # Run tests
   cargo test
   

   use light_program_test::{LightProgramTest, ProgramTestConfig};
   use solana_sdk::signer::Signer;
   
   #[tokio::test]
   async fn test_example() {
       // In-memory test environment 
       let mut rpc = LightProgramTest::new(ProgramTestConfig::default())
           .await
           .unwrap();
   
       let payer = rpc.get_payer().insecure_clone();
       println!("Payer: {}", payer.pubkey());
   }
   

   Localnet (LightClient)

   Connects to a local test validator.

   npm

   npm install -g @lightprotocol/zk-compression-cli@beta
   

   yarn

   yarn global add @lightprotocol/zk-compression-cli@beta
   

   pnpm

   pnpm add -g @lightprotocol/zk-compression-cli@beta
   

   # Initialize project
   cargo init my-light-project
   cd my-light-project
   
   # Start local test validator (in separate terminal)
   light test-validator
   

   use light_client::rpc::{LightClient, LightClientConfig, Rpc};
   
   #[tokio::main]
   async fn main() -> Result<(), Box<dyn std::error::Error>> {
       // Connects to http://localhost:8899
       let rpc = LightClient::new(LightClientConfig::local()).await?;
   
       let slot = rpc.get_slot().await?;
       println!("Current slot: {}", slot);
   
       Ok(())
   }
   

   Devnet (LightClient)

   Replace <your-api-key> with your actual API key. Get your API key here.

   use light_client::rpc::{LightClient, LightClientConfig, Rpc};
   
   #[tokio::main]
   async fn main() -> Result<(), Box<dyn std::error::Error>> {
       let rpc_url = "https://devnet.helius-rpc.com?api-key=<your_api_key>";
       let rpc = LightClient::new(
           LightClientConfig::new(rpc_url.to_string(), None, None)
       ).await?;
   
       println!("Connected to Devnet");
       Ok(())
   }
   
2. Transfer Interface

use anchor_spl::token::{spl_token, Mint};
use light_client::rpc::{LightClient, LightClientConfig, Rpc};
use light_token_sdk::{
    token::{
        derive_token_ata, CreateAssociatedTokenAccount,
        Transfer, TransferFromSpl,
    },
    spl_interface::{find_spl_interface_pda_with_index, CreateSplInterfacePda},
};
use serde_json;
use solana_sdk::compute_budget::ComputeBudgetInstruction;
use solana_sdk::program_pack::Pack;
use solana_sdk::{signature::Keypair, signer::Signer};
use spl_token_2022::pod::PodAccount;
use std::convert::TryFrom;
use std::env;
use std::fs;

/// Test SPL → light-token → light-token
//  with ATA creation + transfer in one transaction
#[tokio::test(flavor = "multi_thread")]
async fn test_spl_to_token_to_token() {
    dotenvy::dotenv().ok();

    let keypair_path = env::var("KEYPAIR_PATH")
        .unwrap_or_else(|_| format!("{}/.config/solana/id.json", env::var("HOME").unwrap()));
    let payer = load_keypair(&keypair_path).expect("Failed to load keypair");
    let api_key = env::var("api_key") // Set api_key in your .env
        .expect("api_key environment variable must be set");

    let config = LightClientConfig::devnet(
        Some("https://devnet.helius-rpc.com".to_string()),
        Some(api_key),
    );
    let mut rpc = LightClient::new_with_retry(config, None)
        .await
        .expect("Failed to initialize LightClient");

    // 2. Create SPL mint
    let mint_keypair = Keypair::new();
    let mint = mint_keypair.pubkey();
    let decimals = 2u8;

    let mint_rent = rpc
        .get_minimum_balance_for_rent_exemption(Mint::LEN)
        .await
        .unwrap();

    let create_mint_account_ix = solana_sdk::system_instruction::create_account(
        &payer.pubkey(),
        &mint,
        mint_rent,
        Mint::LEN as u64,
        &spl_token::ID,
    );

    let initialize_mint_ix = spl_token::instruction::initialize_mint(
        &spl_token::ID,
        &mint,
        &payer.pubkey(),
        None,
        decimals,
    )
    .unwrap();

    rpc.create_and_send_transaction(
        &[create_mint_account_ix, initialize_mint_ix],
        &payer.pubkey(),
        &[&payer, &mint_keypair],
    )
    .await
    .unwrap();

    // 3. Create SPL interface PDA
    let create_spl_interface_pda_ix =
        CreateSplInterfacePda::new(payer.pubkey(), mint, anchor_spl::token::ID).instruction();

    rpc.create_and_send_transaction(&[create_spl_interface_pda_ix], &payer.pubkey(), &[&payer])
        .await
        .unwrap();

    let mint_amount = 10_000u64;
    let spl_to_token_amount = 7_000u64;
    let token_transfer_amount = 3_000u64;

    // 4. Create SPL token account
    let spl_token_account_keypair = Keypair::new();
    let token_account_rent = rpc
        .get_minimum_balance_for_rent_exemption(spl_token::state::Account::LEN)
        .await
        .unwrap();
    let create_token_account_ix = solana_sdk::system_instruction::create_account(
        &payer.pubkey(),
        &spl_token_account_keypair.pubkey(),
        token_account_rent,
        spl_token::state::Account::LEN as u64,
        &spl_token::ID,
    );
    let init_token_account_ix = spl_token::instruction::initialize_account(
        &spl_token::ID,
        &spl_token_account_keypair.pubkey(),
        &mint,
        &payer.pubkey(),
    )
    .unwrap();
    rpc.create_and_send_transaction(
        &[create_token_account_ix, init_token_account_ix],
        &payer.pubkey(),
        &[&spl_token_account_keypair, &payer],
    )
    .await
    .unwrap();

    // 5. Mint SPL tokens to the SPL account
    let mint_to_ix = spl_token::instruction::mint_to(
        &spl_token::ID,
        &mint,
        &spl_token_account_keypair.pubkey(),
        &payer.pubkey(),
        &[&payer.pubkey()],
        mint_amount,
    )
    .unwrap();
    rpc.create_and_send_transaction(&[mint_to_ix], &payer.pubkey(), &[&payer])
        .await
        .unwrap();

    // Verify SPL account has tokens
    let spl_account_data = rpc
        .get_account(spl_token_account_keypair.pubkey())
        .await
        .unwrap()
        .unwrap();
    let spl_account =
        spl_pod::bytemuck::pod_from_bytes::<PodAccount>(&spl_account_data.data).unwrap();
    let initial_spl_balance: u64 = spl_account.amount.into();
    assert_eq!(initial_spl_balance, mint_amount);

    // 6. Create sender's token ATA
    let (sender_token_ata, _bump) = derive_token_ata(&payer.pubkey(), &mint);
    let create_ata_instruction =
        CreateAssociatedTokenAccount::new(payer.pubkey(), payer.pubkey(), mint)
            .instruction()
            .unwrap();

    rpc.create_and_send_transaction(&[create_ata_instruction], &payer.pubkey(), &[&payer])
        .await
        .unwrap();

    // Verify sender's token ATA was created
    let token_account_data = rpc.get_account(sender_token_ata).await.unwrap().unwrap();
    assert!(
        !token_account_data.data.is_empty(),
        "Sender token ATA should exist"
    );

    // 7. Transfer SPL tokens to sender's token account
    let (spl_interface_pda, spl_interface_pda_bump) = find_spl_interface_pda_with_index(&mint, 0);

    let spl_to_token_ix = TransferFromSpl {
        amount: spl_to_token_amount,
        spl_interface_pda_bump,
        source_spl_token_account: spl_token_account_keypair.pubkey(),
        destination_token_account: sender_token_ata,
        authority: payer.pubkey(),
        mint,
        payer: payer.pubkey(),
        spl_interface_pda,
        spl_token_program: anchor_spl::token::ID,
    }
    .instruction()
    .unwrap();

    rpc.create_and_send_transaction(&[spl_to_token_ix], &payer.pubkey(), &[&payer])
        .await
        .unwrap();

    // 8. Create recipient ATA + transfer token→token in one transaction
    let recipient = Keypair::new();
    let (recipient_token_ata, _) = derive_token_ata(&recipient.pubkey(), &mint);

    let create_recipient_ata_ix = CreateAssociatedTokenAccount::new(
        payer.pubkey(),
        recipient.pubkey(),
        mint,
    )
    .instruction()
    .unwrap();

    let token_transfer_ix = Transfer {
        source: sender_token_ata,
        destination: recipient_token_ata,
        amount: token_transfer_amount,
        authority: payer.pubkey(),
        max_top_up: None,
    }
    .instruction()
    .unwrap();

    let compute_unit_ix = ComputeBudgetInstruction::set_compute_unit_limit(10_000);
    rpc.create_and_send_transaction(
        &[compute_unit_ix, create_recipient_ata_ix, token_transfer_ix],
        &payer.pubkey(),
        &[&payer],
    )
    .await
    .unwrap();
}

fn load_keypair(path: &str) -> Result<Keypair, Box<dyn std::error::Error>> {
    let path = if path.starts_with("~") {
        path.replace("~", &env::var("HOME").unwrap_or_default())
    } else {
        path.to_string()
    };
    let file = fs::read_to_string(&path)?;
    let bytes: Vec<u8> = serde_json::from_str(&file)?;
    Ok(Keypair::try_from(&bytes[..])?)
}

Program Guide

Find a full code example at the end.

1. Light Token Transfer Interface

   Define the number of light-tokens / SPL tokens to transfer

   • from which SPL or light-token account, and
   • to which SPL or light-token account.

   use light_token_sdk::token::TransferInterfaceCpi;
   
   let mut transfer = TransferInterfaceCpi::new(
       data.amount,
       source_account.clone(),
       destination_account.clone(),
       authority.clone(),
       payer.clone(),
       compressed_token_program_authority.clone(),
   );
   

   light-token Interface Accounts

   	mutable	The source account (SPL token account or light-token account).
   	mutable	The destination account (SPL token account or light-token account).
   	signer*	Owner of the source account. - *Must be signer for invoke(). For invoke_signed(), program signs via PDA seeds.
   	signer, mutable	Pays transaction fees.
   	-	The light token program authority PDA.

2. SPL Transfer Interface (Optional)

   The SPL transfer interface is only needed for SPL ↔ light-token transfers.

   transfer = transfer.with_spl_interface(
       Some(mint.clone()),
       Some(spl_token_program.clone()),
       Some(spl_interface_pda.clone()),
       data.spl_interface_pda_bump,
   )?;
   

   SPL ↔ light-token transfers require a spl_interface_pda:

   • SPL → light-token: SPL tokens are locked by the light token program in the PDA, light-tokens are minted to light-token accounts
   • light-token → SPL: light-tokens are burned, SPL tokens transferred to SPL token accounts

   The interface PDA is derived from the mint pubkey and pool seed.

   SPL Interface Accounts

   Mint	-	The SPL token mint.
   SPL Token Program	-	The SPL Token program.
   Interface PDA	mutable	Interface PDA for SPL ↔ light-token transfers.

3. CPI

   CPI the Light Token program to execute the transfer. Use invoke(), or invoke_signed() when a CPI requires a PDA signer.

   invoke (External signer)

   transfer.invoke()?;
   

   invoke_signed (PDA is signer)

   let authority_seeds: &[&[u8]] = &[TRANSFER_INTERFACE_AUTHORITY_SEED, &[authority_bump]];
   transfer.invoke_signed(&[authority_seeds])?;
   

Full Code Example

Find the source code here.

use borsh::{BorshDeserialize, BorshSerialize};
use light_token_sdk::token::TransferInterfaceCpi;
use solana_program::{account_info::AccountInfo, program_error::ProgramError, pubkey::Pubkey};

use crate::ID;

/// PDA seed for authority in invoke_signed variants
pub const TRANSFER_INTERFACE_AUTHORITY_SEED: &[u8] = b"transfer_interface_authority";

/// Instruction data for TransferInterfaceCpi
#[derive(BorshSerialize, BorshDeserialize, Debug)]
pub struct TransferInterfaceData {
    pub amount: u64,
    /// Required for SPL<->Token transfers, None for Token->Token
    pub token_pool_pda_bump: Option<u8>,
}

/// Handler for TransferInterfaceCpi (invoke)
///
/// This unified interface automatically detects account types and routes to:
/// - Token -> Token transfer
/// - Token -> SPL transfer
/// - SPL -> Token transfer
///
/// Account order:
/// - accounts[0]: compressed_token_program (for CPI)
/// - accounts[1]: source_account (SPL or light-token)
/// - accounts[2]: destination_account (SPL or light-token)
/// - accounts[3]: authority (signer)
/// - accounts[4]: payer (signer)
/// - accounts[5]: compressed_token_program_authority
///   For SPL bridge (optional, required for SPL<->Token):
/// - accounts[6]: mint
/// - accounts[7]: token_pool_pda
/// - accounts[8]: spl_token_program
pub fn process_transfer_interface_invoke(
    accounts: &[AccountInfo],
    data: TransferInterfaceData,
) -> Result<(), ProgramError> {
    if accounts.len() < 6 {
        return Err(ProgramError::NotEnoughAccountKeys);
    }

    let mut transfer = TransferInterfaceCpi::new(
        data.amount,
        accounts[1].clone(), // source_account
        accounts[2].clone(), // destination_account
        accounts[3].clone(), // authority
        accounts[4].clone(), // payer
        accounts[5].clone(), // compressed_token_program_authority
    );

    // Add SPL bridge config if provided
    if accounts.len() >= 9 && data.token_pool_pda_bump.is_some() {
        transfer = transfer.with_spl_interface(
            Some(accounts[6].clone()), // mint
            Some(accounts[8].clone()), // spl_token_program
            Some(accounts[7].clone()), // token_pool_pda
            data.token_pool_pda_bump,
        )?;
    }

    transfer.invoke()?;

    Ok(())
}

/// Handler for TransferInterfaceCpi with PDA authority (invoke_signed)
///
/// The authority is a PDA derived from TRANSFER_INTERFACE_AUTHORITY_SEED.
///
/// Account order:
/// - accounts[0]: compressed_token_program (for CPI)
/// - accounts[1]: source_account (SPL or light-token)
/// - accounts[2]: destination_account (SPL or light-token)
/// - accounts[3]: authority (PDA, not signer - program signs)
/// - accounts[4]: payer (signer)
/// - accounts[5]: compressed_token_program_authority
///   For SPL bridge (optional, required for SPL<->Token):
/// - accounts[6]: mint
/// - accounts[7]: token_pool_pda
/// - accounts[8]: spl_token_program
pub fn process_transfer_interface_invoke_signed(
    accounts: &[AccountInfo],
    data: TransferInterfaceData,
) -> Result<(), ProgramError> {
    if accounts.len() < 6 {
        return Err(ProgramError::NotEnoughAccountKeys);
    }

    // Derive the PDA for the authority
    let (authority_pda, authority_bump) =
        Pubkey::find_program_address(&[TRANSFER_INTERFACE_AUTHORITY_SEED], &ID);

    // Verify the authority account is the PDA we expect
    if &authority_pda != accounts[3].key {
        return Err(ProgramError::InvalidSeeds);
    }

    let mut transfer = TransferInterfaceCpi::new(
        data.amount,
        accounts[1].clone(), // source_account
        accounts[2].clone(), // destination_account
        accounts[3].clone(), // authority (PDA)
        accounts[4].clone(), // payer
        accounts[5].clone(), // compressed_token_program_authority
    );

    // Add SPL bridge config if provided
    if accounts.len() >= 9 && data.token_pool_pda_bump.is_some() {
        transfer = transfer.with_spl_interface(
            Some(accounts[6].clone()), // mint
            Some(accounts[8].clone()), // spl_token_program
            Some(accounts[7].clone()), // token_pool_pda
            data.token_pool_pda_bump,
        )?;
    }

    // Invoke with PDA signing
    let authority_seeds: &[&[u8]] = &[TRANSFER_INTERFACE_AUTHORITY_SEED, &[authority_bump]];
    transfer.invoke_signed(&[authority_seeds])?;

    Ok(())
}

Next Steps

Learn how to close light-token accounts