Skip to main content
The compress() and decompress() functions convert SPL tokens between compressed and regular format. Before we convert formats, we need:
  • An SPL mint with a token pool for compression. This token pool can be created for new SPL mints via createMint() or added to existing SPL mints via createTokenPool().
  • For compress() SPL tokens in an Associated Token Account, or
  • For decompress() compressed token accounts with sufficient balance.
// Compress SPL tokens to compressed tokens
const compressionSignature = await compress(
    rpc,
    payer,
    mint, // SPL mint with token pool for compression
    amount,
    payer, // owner of SPL tokens
    tokenAccount.address, // source SPL token account (sourceTokenAccount parameter)
    recipient, // recipient owner address (toAddress parameter)
);
Function Difference and Best Practice:
  • compress(amount, sourceTokenAccount, toAddress) compresses specific amounts from source to a specified recipient. Use for transfers and precise amounts.
  • compressSplTokenAccount(tokenAccount, remainingAmount) compresses the entire SPL token account balance minus optional remaining amount only to the same owner. Use to migrate complete token accounts with optional partial retention. Here is how.

​
Full Code Example

​
Prerequisites

Make sure you have dependencies and developer environment set up!
Dependencies
npm install --save-dev typescript tsx @types/node && \
npm install --save \
    @lightprotocol/stateless.js \
    @lightprotocol/compressed-token \
    @solana/web3.js \
    @solana/spl-token
Alternatives:
yarn add --dev typescript tsx @types/node && \
yarn add \
    @lightprotocol/stateless.js \
    @lightprotocol/compressed-token \
    @solana/web3.js \
    @solana/spl-token

pnpm add --save-dev typescript tsx @types/node && \
pnpm add \
    @lightprotocol/stateless.js \
    @lightprotocol/compressed-token \
    @solana/web3.js \
    @solana/spl-token

​
Developer Environment

By default, this guide uses Localnet.
# Install the development CLI
npm install @lightprotocol/zk-compression-cli

# Start a local test validator
light test-validator

## ensure you have the Solana CLI accessible in your system PATH

// createRpc() defaults to local test validator endpoints
import {
  Rpc,
  createRpc,
} from "@lightprotocol/stateless.js";

const connection: Rpc = createRpc();

async function main() {
  let slot = await connection.getSlot();
  console.log(slot);

  let health = await connection.getIndexerHealth(slot);
  console.log(health);
  // "Ok"
}

main();
Alternative: Using DevnetFollow these steps to create an RPC Connection. Replace <your_api_key> with your API key before running.
Get your API key here, if you don’t have one yet.
import { createRpc } from "@lightprotocol/stateless.js";

// Helius exposes Solana and Photon RPC endpoints through a single URL
const RPC_ENDPOINT = "https://devnet.helius-rpc.com?api-key=<your_api_key>";
const connection = createRpc(RPC_ENDPOINT, RPC_ENDPOINT, RPC_ENDPOINT);

console.log("Connection created!");
console.log("RPC Endpoint:", RPC_ENDPOINT);

​
Compress / Decompress Tokens

Compress SPL tokens to compressed format.
compress-tokens.ts
// 1. Setup funded payer and connect to local validator
// 2. Create SPL mint with token pool and mint SPL tokens to ATA
// 3. Call compress() to convert SPL tokens to compressed format
// 4. Verify balances via getTokenAccountBalance and getCompressedTokenAccountsByOwner

import { Keypair } from '@solana/web3.js';
import { createRpc } from '@lightprotocol/stateless.js';
import {
    createMint,
    compress
} from '@lightprotocol/compressed-token';
import {
    getOrCreateAssociatedTokenAccount,
    mintTo as splMintTo,
    TOKEN_PROGRAM_ID
} from '@solana/spl-token';
import BN from 'bn.js';

async function compressTokens() {
    // Step 1: Setup funded payer and connect to local validator
    const rpc = createRpc(); // defaults to localhost:8899
    const payer = Keypair.generate();
    const airdropSignature = await rpc.requestAirdrop(payer.publicKey, 1000000000); // 1 SOL
    await rpc.confirmTransaction(airdropSignature);

    // Step 2: Create SPL mint with token pool and mint SPL tokens to ATA
    const { mint } = await createMint(rpc, payer, payer.publicKey, 9);
    console.log("Mint with token pool created:", mint.toBase58());

    const tokenOwner = Keypair.generate();
    const tokenAccount = await getOrCreateAssociatedTokenAccount(
        rpc, payer, mint, tokenOwner.publicKey, false, TOKEN_PROGRAM_ID
    );

    // Mint SPL tokens to the ATA
    const splAmount = 1_000_000_000; // 1 token with 9 decimals
    await splMintTo(rpc, payer, mint, tokenAccount.address, payer, splAmount, [], undefined, TOKEN_PROGRAM_ID);
    console.log("SPL tokens minted:", splAmount / 1_000_000_000, "tokens");

    console.log("Compress Tokens");

    const compressAmount = 400_000_000; // 0.4 tokens

    // Step 3: Call compress() to convert to compressed format
    // Lock SPL tokens to pool account and mint compressed tokens
    const compressTx = await compress(
        rpc,
        payer,
        mint, // SPL mint with token pool for compression
        compressAmount, // amount to compress
        tokenOwner, // owner of SPL tokens
        tokenAccount.address, // source token account
        tokenOwner.publicKey, // recipient for compressed tokens
    );

    console.log("Compressed amount:", compressAmount / 1_000_000_000, "tokens");
    console.log("Transaction:", compressTx);

    // Step 4: Verify balances via getTokenAccountBalance and getCompressedTokenAccountsByOwner
    const finalTokenBalance = await rpc.getTokenAccountBalance(tokenAccount.address);
    const finalCompressedAccounts = await rpc.getCompressedTokenAccountsByOwner(
        tokenOwner.publicKey,
        { mint }
    );

    // Calculate total compressed balance
    const finalCompressedBalance = finalCompressedAccounts.items.reduce(
        (sum, account) => sum.add(account.parsed.amount),
        new BN(0)
    );

    console.log("\nFinal balances:");
    console.log("Regular SPL tokens:", finalTokenBalance.value.uiAmount);
    console.log("Compressed tokens:", finalCompressedBalance.toNumber() / 1_000_000_000);

    return {
        compressTransaction: compressTx,
        finalCompressedBalance,
        finalSplBalance: finalTokenBalance.value.amount
    };
}

compressTokens().catch(console.error);

​
Troubleshooting

Check your balances before operations:
// For decompression - check compressed balance
const compressedAccounts = await rpc.getCompressedTokenAccountsByOwner(
    owner.publicKey,
    { mint }
);
const compressedBalance = compressedAccounts.items.reduce(
    (sum, account) => sum.add(account.parsed.amount),
    new BN(0)
);

// For compression - check SPL token balance
const tokenBalance = await rpc.getTokenAccountBalance(tokenAccount);
const splBalance = new BN(tokenBalance.value.amount);

console.log("Can decompress up to:", compressedBalance.toString());
console.log("Can compress up to:", splBalance.toString());
Ensure the signer owns the tokens being decompressed/compressed:
// The owner parameter must be the actual owner
const decompressTx = await decompress(
    rpc,
    payer, // can be different (pays fees)
    mint,
    amount,
    actualOwner, // must own compressed tokens
    destinationAta,
);

const compressTx = await compress(
    rpc,
    payer, // can be different (pays fees)
    mint,
    amount,
    actualOwner, // must own SPL tokens
    sourceAta,
    recipient,
);

​
Advanced Configurations

Compress tokens directly to someone else:
const recipientWallet = new PublicKey("RECIPIENT_WALLET_ADDRESS");

// Compress your SPL tokens to recipient
const compressTx = await compress(
    rpc,
    payer,
    mint,
    amount,
    tokenOwner, // current owner signs
    tokenAccount, // your token account
    recipientWallet, // recipient gets compressed tokens
);
Compress multiple token accounts:
// Compress to multiple recipients at once
const recipients = [recipient1.publicKey, recipient2.publicKey, recipient3.publicKey];
const amounts = [1_000_000_000, 2_000_000_000, 500_000_000]; // Different amounts

const batchCompressTx = await compress(
    rpc,
    payer,
    mint,
    amounts, // Array of amounts
    owner,
    tokenAccount,
    recipients, // Array of recipients
);

console.log("Batch compression completed:", batchCompressTx);
Decompress tokens using delegate authority:
import { decompressDelegated } from '@lightprotocol/compressed-token';
import { getAssociatedTokenAddress, TOKEN_PROGRAM_ID } from '@solana/spl-token';

// Get ATA for decompressed tokens
const ataAddress = await getAssociatedTokenAddress(
    mint,
    recipient,
    false,
    TOKEN_PROGRAM_ID
);

// Delegate decompresses tokens
await decompressDelegated(
    rpc,
    payer,
    mint,
    amount,
    delegate, // Signer - owner of compressed tokens
    ataAddress, // Uncompressed token account (ATA)
);

​
Next Steps

Learn how to compress complete token accounts in one transaction and reclaim rent afterwards.