# AI Tools Guide
Source: https://www.zkcompression.com/ai-tools/guide

Guidance to AI tools when working with ZK Compression. Includes Agent Skill, MCP server, DeepWiki, and AI Search guides.

# For Docs

* **Docs AI Search** - Search documentation with AI in the search bar.
* **Markdown Export** - Append `.md` to any page URL for raw markdown.

# For Development

## AI agents

### `skill.md`

`skill.md` is a structured capability file that tells agents what they can do
with Light Protocol and ZK Compression. If you're
building with agents, start here.

* View: [`/skill.md`](https://zkcompression.com/skill.md)

### `llms.txt`

`llms.txt` is an index of the docs. It lists key pages with descriptions
so agents can navigate to answers quickly.

* View: [`/llms.txt`](https://zkcompression.com/llms.txt)

### `llms-full.txt`

`llms-full.txt` is the full, expanded index for agents that want complete coverage of the documentation.

* View: [`/llms-full.txt`](https://zkcompression.com/llms-full.txt)

## MCP

The Model Context Protocol (MCP) is an open standard to connect AI apps to data sources and tools. The DeepWiki MCP server provides access to the Light Protocol repository with its search capabilities (AskDevin).

### Installation

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add -s user -t http deepwiki https://mcp.deepwiki.com/mcp
    claude mcp add -s user -t http zkcompression https://www.zkcompression.com/mcp
    ```

    <Tip>
      **We recommend to create a command** that includes the tools listed below. <br /> Simply **copy paste this snippet**.
    </Tip>

    ```markdown expandable theme={null}
    ---
    argument-hint: <question>
    description: Query Light Protocol repository and Solana resources via DeepWiki MCP for precise technical answers and help with debugging
    allowed-tools: mcp__deepwiki__*
    ---

    # /ask-deepwiki

    Answer: $ARGUMENTS

    Use DeepWiki MCP to provide precise technical answers.

    ## Step 1: Identify Repository Scope

    1. **State understanding and plan**

    2. **If question is vague, ask for clarification:**
    - What specific component or feature?
    - What problem are you solving?
    - What level of detail needed (overview vs implementation)?

    3. **Repository mapping:**
    - ZK Compression/Light Protocol: `Lightprotocol/light-protocol`
    - Solana fundamentals: `solana-labs/solana`
    - Anchor framework: `solana-foundation/anchor`
    - Complex questions: Query multiple repositories

    4. **Refine question to use:**
    - Exact component names: `CompressedAccountMeta` not "account metadata"
    - Specific operations: "verifies proof" not "handles proof"
    - Concrete function names or error messages when available

    ## Step 2: Query DeepWiki

    For the identified repository, call in sequence:

    1. `mcp__deepwiki__read_wiki_structure("repo-owner/repo-name")`
    2. `mcp__deepwiki__read_wiki_contents("repo-owner/repo-name")`
    3. `mcp__deepwiki__ask_question("repo-owner/repo-name", refined_question)`

    Query multiple repositories if question spans different systems.

    ## Step 3: Format Response

    **Structure:**
    1. Direct answer with technical explanation
    2. Specific implementations and data structures
    3. Code examples with inline comments
    4. Source references (`file:line` from DeepWiki)
    5. Related concepts if relevant

    **Language precision:**

    NEVER use vague verbs:
    - "handles", "manages", "processes", "enables", "provides"

    ALWAYS use exact names:
    - Functions: `LightAccount::new_init()`, `derive_address()`
    - Types: `CompressedAccountMeta`, `ValidityProof`, `PackedAddressTreeInfo`
    - Operations: "nullifies hash", "appends to state tree", "verifies proof"
    - Fields: `tree_info`, `address`, `output_state_tree_index`

    Include `file:line` references from DeepWiki responses.

    ## Notes

    - Always include source file references from DeepWiki responses
    - Provide runnable code examples for implementation questions
    - Ask follow-up questions to DeepWiki for clarification when needed
    ```
  </Tab>

  <Tab title="Codex">
    ```bash theme={null}
    codex mcp add zkcompression -- npx -y mcp-remote@latest https://www.zkcompression.com/mcp
    codex mcp add deepwiki -- npx -y mcp-remote@latest https://mcp.deepwiki.com/mcp
    ```
  </Tab>

  <Tab title="Most Clients (Windsurf, Cursor, ...)">
    ```json theme={null}
    {
      "mcpServers": {
        "deepwiki": {
          "serverUrl": "https://mcp.deepwiki.com/sse"
        },
        "zkcompression": {
          "command": "npx",
          "args": ["-y", "mcp-remote@latest", "https://www.zkcompression.com/mcp"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

### DeepWiki MCP-Tools

* **read\_wiki\_structure** - Get a list of documentation topics for a GitHub repository

```bash theme={null}
mcp__deepwiki__read_wiki_structure("Lightprotocol/light-protocol")
```

* **read\_wiki\_contents** - View documentation about a GitHub repository

```bash theme={null}
mcp__deepwiki__read_wiki_contents("Lightprotocol/light-protocol")
```

* **ask\_question** - Ask any question about the GitHub repository and get a context-grounded response

```bash theme={null}
mcp__deepwiki__ask_question("Lightprotocol/light-protocol", "your question")
```

<Tip>
  You can specify any public GitHub repo that is indexed with DeepWiki. When you connect to the MCP, you specify the repository when calling the tools. Learn more [here](https://docs.devin.ai/work-with-devin/deepwiki-mcp).
</Tip>

<div>
  <h3>Alternative: DeepWiki Web</h3>

  <a href="https://deepwiki.com/Lightprotocol/light-protocol">
    <img alt="Ask DeepWiki" />
  </a>
</div>

If you don't have the MCP installed we recommend to use AskDevin in your browser.

<Frame>
  <iframe title="DeepWiki Video" />
</Frame>


# null
Source: https://www.zkcompression.com/api-reference/json-rpc-methods/getcompressedaccount

post /getCompressedAccount
Retrieve compressed account information by address or hash. RPC method guide with use cases, tips and examples.



# null
Source: https://www.zkcompression.com/api-reference/json-rpc-methods/getcompressedaccountsbyowner

post /getCompressedAccountsByOwner
Retrieve all compressed accounts owned by a specific address. RPC method guide with use cases, tips and examples.



# null
Source: https://www.zkcompression.com/api-reference/json-rpc-methods/getcompressedbalance

post /getCompressedBalance
Retrieve the lamport balance for a specific compressed account by address or hash. Overview with RPC method guide.



# null
Source: https://www.zkcompression.com/api-reference/json-rpc-methods/getcompressedbalancebyowner

post /getCompressedBalanceByOwner
Query the total compressed token balance for a specific account owner. Overview with RPC method guide.



# null
Source: https://www.zkcompression.com/api-reference/json-rpc-methods/getcompressedminttokenholders

post /getCompressedMintTokenHolders
Retrieve owner balances for a given mint in descending order. Overview with RPC method guide.



# null
Source: https://www.zkcompression.com/api-reference/json-rpc-methods/getcompressedtokenaccountbalance

post /getCompressedTokenAccountBalance
Retrieve the balance for a given token account by address or hash. Overview with RPC method guide



# null
Source: https://www.zkcompression.com/api-reference/json-rpc-methods/getcompressedtokenaccountbydelegate

post /getCompressedTokenAccountsByDelegate
Retrieve compressed token accounts that are partially or fully delegated to a given delegate. Overview with RPC method guide.



# null
Source: https://www.zkcompression.com/api-reference/json-rpc-methods/getcompressedtokenaccountsbyowner

post /getCompressedTokenAccountsByOwner
Retrieve compressed token accounts owned by a specific address. RPC method guide with use cases, tips and examples.



# null
Source: https://www.zkcompression.com/api-reference/json-rpc-methods/getcompressedtokenbalancesbyowner

post /getCompressedTokenBalancesByOwner
Retrieves all token balances for compressed accounts owned by an address. Overview with RPC method guide.



# null
Source: https://www.zkcompression.com/api-reference/json-rpc-methods/getcompressionsignaturesforaccount

post /getCompressionSignaturesForAccount
Retrieve the signatures of the transactions that closed or opened a compressed account with the given hash. Overview with RPC method guide.



# null
Source: https://www.zkcompression.com/api-reference/json-rpc-methods/getcompressionsignaturesforaddress

post /getCompressionSignaturesForAddress
Retrieve the signatures of the transactions that closed or opened a compressed account with the given address. Overview with RPC method guide.



# null
Source: https://www.zkcompression.com/api-reference/json-rpc-methods/getcompressionsignaturesforowner

post /getCompressionSignaturesForOwner
Retrieve the signatures of the transactions that have modified an owner's compressed accounts. Overview with RPC method guide.



# null
Source: https://www.zkcompression.com/api-reference/json-rpc-methods/getcompressionsignaturesfortokenowner

post /getCompressionSignaturesForTokenOwner
Retrieve the signatures of the transactions that have modified an owner's compressed token accounts. Overview with RPC method guide.



# null
Source: https://www.zkcompression.com/api-reference/json-rpc-methods/getindexerhealth

post /getIndexerHealth
Retrieve an error if the indexer is stale by more than a configurable number of blocks. Otherwise, it returns ok. Overview with RPC method guide.



# null
Source: https://www.zkcompression.com/api-reference/json-rpc-methods/getindexerslot

post /getIndexerSlot
Retrieve the slot of the last block indexed by the indexer. Overview with RPC method guide.



# null
Source: https://www.zkcompression.com/api-reference/json-rpc-methods/getlatestcompressionsignatures

post /getLatestCompressionSignatures
Retrieve the signatures of the latest transactions that used the compression program. This is a paginated endpoint. Overview with RPC method guide.



# null
Source: https://www.zkcompression.com/api-reference/json-rpc-methods/getlatestnonvotingsignatures

post /getLatestNonVotingSignatures
Retrieve the signatures of the latest transactions that are not voting transactions. Overview with RPC method guide.



# null
Source: https://www.zkcompression.com/api-reference/json-rpc-methods/getmultiplecompressedaccounts

post /getMultipleCompressedAccounts
Retrieve multiple compressed accounts with the given addresses or hashes. Overview with RPC method guide.



# null
Source: https://www.zkcompression.com/api-reference/json-rpc-methods/getmultiplenewaddressproofs

post /getMultipleNewAddressProofs
Retrieve proofs that the new addresses are not taken already and can be created. Overview with RPC method guide.



# null
Source: https://www.zkcompression.com/api-reference/json-rpc-methods/gettransactionwithcompressioninfo

post /getTransactionWithCompressionInfo
Retrieve the transaction data for the transaction with the given signature along with parsed compression info. RPC method guide with use cases, tips and examples.

The`getTransactionWithCompressionInfo` RPC method returns transaction data along with compression information showing which compressed accounts were opened (created) and closed (consumed) during the transaction. This method helps with transaction analysis, account lifecycle tracking, and debugging of compression operations.

<Info>
  You can test this method via the OpenAPI example or custom examples below.
</Info>

**Common Use Cases**

* **Transaction Analysis**: Understand what compressed accounts were affected by a transaction
* **Account Lifecycle Tracking**: Monitor when compressed accounts are created and consumed
* **Debugging**: Identify which accounts changed during failed or unexpected transactions
* **Audit Trails**: Track compressed account state changes for compliance

**Parameters**

1. `signature` (string, required): Base58-encoded transaction signature to query compression information for.

**Note**: Only transactions involving compressed accounts will return compression data. Regular Solana transactions return null.

**Response**

The response contains compression information and transaction data, or null if transaction not found:

* `compressionInfo` (object): Contains details about compressed account changes
  * `closedAccounts` (array): Compressed accounts consumed (spent) in this transaction
    * `account` (object): Complete compressed account data with merkle context
    * `maybeTokenData` (object | null): Token data if this is a compressed token account
  * `openedAccounts` (array): New compressed accounts created in this transaction
    * `account` (object): Complete compressed account data with merkle context
    * `maybeTokenData` (object | null): Token data if this is a compressed token account
  * `preTokenBalances` (array, optional): Token balances before transaction
    * `owner` (PublicKey): Public key of token account owner
    * `mint` (PublicKey): Public key of token mint
    * `amount` (BN): Token amount as BN object
  * `postTokenBalances` (array, optional): Token balances after transaction
    * `owner` (PublicKey): Public key of token account owner
    * `mint` (PublicKey): Public key of token mint
    * `amount` (BN): Token amount as BN object
* `transaction` (object): Standard Solana transaction data

**Developer Tips**

* **Compression-only**: This method only works with transactions that involve compressed accounts
* **Real signatures required**: Use actual transaction signatures from compression operations
* **Account lifecycle**: opened = created, closed = consumed/spent in the transaction
* **Token data**: maybeTokenData is null for regular compressed accounts, populated for token accounts
* **Balance tracking**: Use pre/postTokenBalances for detailed token amount changes
* **State analysis**: Compare opened vs closed accounts to understand transaction effects

**Troubleshooting**

<AccordionGroup>
  <Accordion title="Transaction not found">
    **Invalid or non-existent transaction signature**

    Verify the signature format and check transaction existence:

    ```typescript theme={null}
    const result = await connection.getTransactionWithCompressionInfo(signature);

    if (!result) {
        console.log('Transaction not found or contains no compression operations');
    }
    ```
  </Accordion>

  <Accordion title="No compression info">
    **Transaction exists but has no compression data**

    This method only returns data for transactions involving compressed accounts:

    ```typescript theme={null}
    const result = await connection.getTransactionWithCompressionInfo(signature);

    if (!result) {
        console.log('Transaction does not involve compressed accounts');
        console.log('Use regular getTransaction for non-compression transactions');
    }
    ```
  </Accordion>

  <Accordion title="Empty account arrays">
    **Transaction has compression info but no account changes shown**

    Some compression operations may not create/consume accounts:

    ```typescript theme={null}
    const { compressionInfo } = result;

    if (compressionInfo.openedAccounts.length === 0 &&
        compressionInfo.closedAccounts.length === 0) {
        console.log('Compression transaction with no visible account changes');
        console.log('May be a proof verification or state update operation');
    }
    ```
  </Accordion>
</AccordionGroup>


# null
Source: https://www.zkcompression.com/api-reference/json-rpc-methods/getvalidityproof

post /
Retrieve a single ZK Proof used by the compression program to verify that the given accounts are valid and the new addresses can be created. RPC method guide with use cases, tips and examples.

The`getValidityProof` RPC method generates zero-knowledge proofs to verify that the given accounts are valid or the new addresses can be created. This proof is required for any operation on compressed accounts (transfer, approve, decompress, etc.) for on-chain verification of compressed state.

<Info>
  You can test this method via the OpenAPI example or custom examples below.
</Info>

<Info>
  * Proof limits per request are:
    * `hashes`: 1, 2, 3, 4, or 8
    * `newAddressesWithTrees` : 1, 2
  * The `newAddresses` param field is supported but deprecated. Please use `newAddressesWithTrees`instead.
</Info>

**Common Use Cases**

* **Token Transfers:** Generate proofs required for transferring compressed tokens.
* **Account Operations:** Create proofs needed for any compressed account modification.
* **Batch Processing:** Generate proofs for multiple accounts in a single call.
* **State Tree Verification:** Prove account inclusion in the current state tree.
* **Transaction Building:** Obtain proof data needed for compressed transaction instructions.
* **Program Integration:** Get validity proofs for custom program operations on compressed accounts.

**Parameters**

1. `hashes` (BN254\[], required): Array of BN254 objects representing compressed account hashes to generate proofs for.
2. `newAddresses` (BN254\[], optional): Array of BN254 objects representing new addresses to include in the proof for address tree verification.

**Response**

The response contains ValidityProofWithContext data:

* `compressedProof` (ValidityProof | null): The compressed validity proof object for zero-knowledge verification
* `roots` (BN\[]): Array of merkle tree roots used in proof generation
* `rootIndices` (number\[]): Array of indices of the roots in the state tree
* `leafIndices` (number\[]): Array of indices of the leaves being proven
* `leaves` (BN\[]): Array of leaf values in the merkle tree
* `treeInfos` (TreeInfo\[]): Array of information about the state trees used
* `proveByIndices` (boolean\[]): Array indicating whether to prove by indices for each element

**Developer Tips**

* **Fetch Accounts First**: Always get compressed accounts before generating proofs - you need existing account hashes
* **Batch Processing**: You can generate proofs for multiple accounts in a single call. Allowed counts: 1, 2, 3, 4, or 8 accounts
* **Proof Usage**: The proof is required for any operation that modifies compressed accounts (transfers, burns, etc.)
* **Caching**: Validity proofs are only valid for the current state - don't cache them for long periods
* **Error Handling**: If accounts don't exist or have been modified, proof generation will fail
* **Integration**: Use `proof.compressedProof` and `proof.rootIndices` when building transactions
* **State Changes**: After any transaction, previously generated proofs become invalid for those accounts

**Examples**

The below examples work - just make sure you installed the dependencies.

<Accordion title="Dependencies & Setup">
  ```bash theme={null}
  npm install @lightprotocol/stateless.js @solana/web3.js
  ```
</Accordion>

**Example: Generate Validity Proof**

Generate a validity proof for compressed accounts.

<Tabs>
  <Tab title="TypeScript">
    ```typescript expandable theme={null}
    import { Rpc, createRpc, bn } from '@lightprotocol/stateless.js';
    import { PublicKey } from '@solana/web3.js';

    async function generateValidityProof(): Promise<void> {
      const connection: Rpc = createRpc(
        'https://devnet.helius-rpc.com/?api-key=YOUR_API_KEY',
        'https://devnet.helius-rpc.com/?api-key=YOUR_API_KEY'
      );

      try {
        // Get compressed accounts
        const owner = new PublicKey('OWNER_PUBLIC_KEY_HERE');
        const accounts = await connection.getCompressedAccountsByOwner(owner);

        if (accounts.items.length === 0) {
          console.log('No compressed accounts found');
          return;
        }

        // Generate validity proof
        const hashes = accounts.items.slice(0, 2).map(acc => bn(acc.hash));
        const validityProof = await connection.getValidityProof(hashes);

        console.log('Validity Proof Generated:');
        console.log(\`  Accounts: ${hashes.length}\`);
        console.log(\`  Roots: ${validityProof.roots.length}\`);
        console.log(\`  Root Indices: ${validityProof.rootIndices.length} elements\`);
        console.log(\`  Leaf Indices: ${validityProof.leafIndices.length} elements\`);

        // Ready for use in transactions
        console.log('\nProof ready for compressed transactions');

      } catch (error: unknown) {
        console.error('Error generating validity proof:', error);
      }
    }

    generateValidityProof();
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    # Use account hashes from getCompressedAccountsByOwner
    curl -X POST https://devnet.helius-rpc.com/?api-key=YOUR_API_KEY \
      -H "Content-Type: application/json" \
      -d '{
        "jsonrpc": "2.0",
        "id": 1,
        "method": "getValidityProof",
        "params": {
          "hashes": [
            "ACCOUNT_HASH_1",
            "ACCOUNT_HASH_2"
          ]
        }
      }'
    ```
  </Tab>

  <Tab title="Rust">
    <Info>
      **Rust Client**: `light-client` v0.14.0 is available on crates.io. Use `LightClient` for the current stable API.
    </Info>

    ```rust expandable theme={null}
    use light_client::rpc::LightClient;
    use solana_sdk::pubkey::Pubkey;
    use std::str::FromStr;
    use anyhow::Result;

    #[tokio::main]
    async fn main() -> Result<()> {
        let client = LightClient::new("https://devnet.helius-rpc.com/?api-key=YOUR_API_KEY".to_string()).await?;

        // Get compressed accounts first
        let owner = "OWNER_PUBLIC_KEY_HERE";
        let accounts = client.get_compressed_accounts_by_owner(owner).await?;

        if accounts.items.is_empty() {
            println!("No compressed accounts found");
            return Ok(());
        }

        // Generate validity proof for the accounts
        let hashes: Vec<String> = accounts.items.iter()
            .take(2)
            .map(|acc| acc.hash.clone())
            .collect();

        let validity_proof = client.get_validity_proof(hashes.clone()).await?;

        println!("Validity Proof Generated:");
        println!("  Accounts: {}", hashes.len());
        println!("  Roots: {}", validity_proof.roots.len());
        println!("  Root Indices: {}", validity_proof.root_indices.len());

        Ok(())
    }
    ```
  </Tab>
</Tabs>

**Example: Proof Generation for Token Transfer**

Generate a validity proof for a compressed token transfer operation:

```Javascript JavaScript expandable theme={null}
import { Rpc, createRpc, bn } from '@lightprotocol/stateless.js';
import { PublicKey } from '@solana/web3.js';

async function generateProofForTransfer() {
  const connection = createRpc(
    'https://devnet.helius-rpc.com/?api-key=YOUR_API_KEY',
    'https://devnet.helius-rpc.com/?api-key=YOUR_API_KEY'
  );

  try {
    // Get compressed token accounts
    const owner = new PublicKey('OWNER_PUBLIC_KEY_HERE');
    const mint = new PublicKey('TOKEN_MINT_HERE');

    const tokenAccounts = await connection.getCompressedTokenAccountsByOwner(
      owner,
      { mint }
    );

    if (tokenAccounts.items.length === 0) {
      console.log('No compressed token accounts found');
      return;
    }

    // Generate proof for the token accounts (limit to allowed numbers: 1, 2, 3, 4, or 8)
    const limitedAccounts = tokenAccounts.items.slice(0, 4);
    const hashes = limitedAccounts.map(acc => bn(acc.compressedAccount.hash));
    const validityProof = await connection.getValidityProof(hashes);

    console.log('Validity Proof for Transfer:');
    console.log(\`  Token accounts: ${hashes.length}\`);
    console.log(\`  Roots: ${validityProof.roots.length}\`);

    // This proof is now ready to use with CompressedTokenProgram.transfer()
    console.log('\nProof ready for token transfer instruction');
    console.log('Use this with:');
    console.log('  recentValidityProof: validityProof.compressedProof');
    console.log('  recentInputStateRootIndices: validityProof.rootIndices');

  } catch (error) {
    console.error('Error generating proof:', error);
  }
}

generateProofForTransfer();
```


# JSON RPC Methods
Source: https://www.zkcompression.com/api-reference/json-rpc-methods/methods

Reference to all JSON RPC endpoints for ZK Compression on Solana.

<table>
  <thead>
    <tr>
      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>[GetCompressedAccount](/api-reference/json-rpc-methods/getcompressedaccount)</td>
      <td>Retrieves information about a specific compressed account by its address or hash.</td>
    </tr>

    <tr>
      <td>[GetCompressedAccountsByOwner](/api-reference/json-rpc-methods/getcompressedaccountsbyowner)</td>
      <td>Returns all compressed accounts owned by a specific address.</td>
    </tr>

    <tr>
      <td>[GetCompressedBalance](/api-reference/json-rpc-methods/getcompressedbalance)</td>
      <td>Retrieves the balance of a compressed account.</td>
    </tr>

    <tr>
      <td>[GetCompressedBalanceByOwner](/api-reference/json-rpc-methods/getcompressedbalancebyowner)</td>
      <td>Gets the total balance of all compressed accounts owned by an address.</td>
    </tr>

    <tr>
      <td>[GetCompressedMintTokenHolders](/api-reference/json-rpc-methods/getcompressedminttokenholders)</td>
      <td>Lists all holders of a specific compressed token mint.</td>
    </tr>

    <tr>
      <td>[GetCompressedTokenAccountBalance](/api-reference/json-rpc-methods/getcompressedtokenaccountbalance)</td>
      <td>Retrieves the token balance of a compressed token account.</td>
    </tr>

    <tr>
      <td>[GetCompressedTokenAccountsByDelegate](/api-reference/json-rpc-methods/getcompressedtokenaccountbydelegate)</td>
      <td>Returns all compressed token accounts delegated to a specific address.</td>
    </tr>

    <tr>
      <td>[GetCompressedTokenAccountsByOwner](/api-reference/json-rpc-methods/getcompressedtokenaccountsbyowner)</td>
      <td>Lists all compressed token accounts owned by a specific address.</td>
    </tr>

    <tr>
      <td>[GetCompressedTokenBalancesByOwner](/api-reference/json-rpc-methods/getcompressedtokenbalancesbyowner)</td>
      <td>Retrieves all token balances for compressed accounts owned by an address.</td>
    </tr>

    <tr>
      <td>[GetCompressionSignaturesForAccount](/api-reference/json-rpc-methods/getcompressionsignaturesforaccount)</td>
      <td>Returns signatures for transactions involving a compressed account.</td>
    </tr>

    <tr>
      <td>[GetCompressionSignaturesForAddress](/api-reference/json-rpc-methods/getcompressionsignaturesforaddress)</td>
      <td>Retrieves signatures for transactions involving a specific address.</td>
    </tr>

    <tr>
      <td>[GetCompressionSignaturesForOwner](/api-reference/json-rpc-methods/getcompressionsignaturesforowner)</td>
      <td>Returns signatures for transactions where an address is the owner.</td>
    </tr>

    <tr>
      <td>[GetCompressionSignaturesForTokenOwner](/api-reference/json-rpc-methods/getcompressionsignaturesfortokenowner)</td>
      <td>Lists signatures for transactions involving tokens owned by an address.</td>
    </tr>

    <tr>
      <td>[GetIndexerHealth](/api-reference/json-rpc-methods/getindexerhealth)</td>
      <td>Returns the health status of the compression indexer.</td>
    </tr>

    <tr>
      <td>[GetIndexerSlot](/api-reference/json-rpc-methods/getindexerslot)</td>
      <td>Retrieves the current slot of the compression indexer.</td>
    </tr>

    <tr>
      <td>[GetLatestCompressionSignatures](/api-reference/json-rpc-methods/getlatestcompressionsignatures)</td>
      <td>Returns the most recent transaction signatures related to compression.</td>
    </tr>

    <tr>
      <td>[GetLatestNon-VotingSignatures](/api-reference/json-rpc-methods/getlatestnonvotingsignatures)</td>
      <td>Retrieves recent non-voting transaction signatures.</td>
    </tr>

    <tr>
      <td>[GetMultipleCompressedAccounts](/api-reference/json-rpc-methods/getmultiplecompressedaccounts)</td>
      <td>Retrieves multiple compressed accounts in a single request.</td>
    </tr>

    <tr>
      <td>[GetMultipleNewAddressProofs](/api-reference/json-rpc-methods/getmultiplenewaddressproofs)</td>
      <td>Returns proofs that the new addresses are not taken already and can be created.</td>
    </tr>

    <tr>
      <td>[GetTransactionWithCompressionInfo](/api-reference/json-rpc-methods/gettransactionwithcompressioninfo)</td>
      <td>Returns transaction details with additional compression-related information.</td>
    </tr>

    <tr>
      <td>[GetValidityProof](/api-reference/json-rpc-methods/getvalidityproof)</td>
      <td>Retrieves a validity proof for compressed data.</td>
    </tr>
  </tbody>
</table>


# JSON RPC Methods
Source: https://www.zkcompression.com/api-reference/json-rpc-methods/overview

Overview JSON RPC endpoints on Solana, best practices, and error codes.

The API exposed by the indexer closely mirrors existing RPC calls, with one-to-one mapping:

| Solana RPC              | Photon RPC Calls                  |
| :---------------------- | :-------------------------------- |
| getAccountInfo          | getCompressedAccount              |
| getBalance              | getCompressedBalance              |
| getTokenAccountsByOwner | getCompressedTokenAccountsByOwner |
| getProgramAccounts      | getCompressedAccountsByOwner      |

<Card title="View all RPC endpoints for ZK Compression" icon="chevron-right" href="/api-reference/json-rpc-methods/methods" />

## Create an RPC Connection

<Tabs>
  <Tab title="Mainnet">
    ```typescript theme={null}
    // Helius exposes Solana and Photon RPC endpoints through a single URL
    import { createRpc, Rpc } from '@lightprotocol/stateless.js';

    const RPC_ENDPOINT = '<https://mainnet.helius-rpc.com?api-key=YOUR_KEY>';
    const connection: Rpc = createRpc(RPC_ENDPOINT, RPC_ENDPOINT);
    ```
  </Tab>

  <Tab title="Devnet">
    ```typescript theme={null}
    import { createRpc, Rpc } 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=<api_key>";
    const connection: Rpc = createRpc(RPC_ENDPOINT, RPC_ENDPOINT);
    ```
  </Tab>
</Tabs>

## Best Practices

| Best Practice         | Description                                                                                                   |
| :-------------------- | :------------------------------------------------------------------------------------------------------------ |
| **Commitment Levels** | Use appropriate commitment levels: `processed` (fastest), `confirmed` (balanced), `finalized` (most reliable) |
| **Rate Limiting**     | Implement retry logic and respect rate limits. Public endpoints: 100 req/s, Private: 1000+ req/s              |
| **Batch Requests**    | Use batch requests when possible to improve efficiency and reduce API calls                                   |
| **Caching**           | Cache frequently accessed data to reduce API calls and improve performance                                    |

## Error Codes

<Tip>
  <div>
    <span>For help with debugging use</span>

    <a href="https://deepwiki.com/Lightprotocol/light-protocol/3.3-rpc-and-indexer-integration">
      <img alt="Ask DeepWiki" />
    </a>
  </div>
</Tip>

| Code   | Message              | Description                                  |
| :----- | :------------------- | :------------------------------------------- |
| -32600 | Invalid Request      | The JSON sent is not a valid Request object  |
| -32601 | Method not found     | The method does not exist / is not available |
| -32602 | Invalid params       | Invalid method parameter(s)                  |
| -32603 | Internal error       | Internal JSON-RPC error                      |
| -32000 | Account not found    | The compressed account was not found         |
| -32001 | Invalid account hash | The provided account hash is invalid         |

# Next Steps

<Card title="View all RPC endpoints for ZK Compression" icon="chevron-right" href="/api-reference/json-rpc-methods/methods" />


# compressed-token
Source: https://www.zkcompression.com/api-reference/libraries/compressed-token

TypeScript SDK for compressed tokens

View the full reference: [compressed-token](https://lightprotocol.github.io/light-protocol/compressed-token/index.html)


# light-client
Source: https://www.zkcompression.com/api-reference/libraries/light-client

Rust client for compressed accounts

View the full reference: [light-client](https://docs.rs/light-client/latest/light_client/)


# light-program-test
Source: https://www.zkcompression.com/api-reference/libraries/light-program-test

Rust testing framework for programs using compressed accounts

View the full reference: [light-program-test](https://docs.rs/light-program-test/latest/light_program_test/)


# light-sdk
Source: https://www.zkcompression.com/api-reference/libraries/light-sdk

Rust SDK for building on-chain programs with compressed accounts

View the full reference: [light-sdk](https://docs.rs/light-sdk/latest/light_sdk/)


# light-token
Source: https://www.zkcompression.com/api-reference/libraries/light-token

Light Token program crate for rent-free token accounts and mints

View the full reference: [light-token](https://docs.rs/light-token/latest/light_token/)


# stateless.js
Source: https://www.zkcompression.com/api-reference/libraries/stateless-js

TypeScript SDK for compressed accounts

View the full reference: [stateless.js](https://lightprotocol.github.io/light-protocol/stateless.js/index.html)


# Client Guide
Source: https://www.zkcompression.com/client-library/client-guide

Rust and Typescript client guides with step-by-step implementation and full code examples.

ZK Compression provides Rust and Typescript clients to interact with compressed accounts and tokens on Solana.

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**TypeScript**</td>
      <td>[@lightprotocol/stateless.js](https://lightprotocol.github.io/light-protocol/stateless.js/index.html)</td>
      <td>Client SDK for Compressed Accounts</td>
    </tr>

    <tr>
      <td>**TypeScript**</td>
      <td>[@lightprotocol/compressed-token](https://lightprotocol.github.io/light-protocol/compressed-token/index.html)</td>
      <td>Client SDK for Compressed Tokens</td>
    </tr>

    <tr>
      <td>**Rust**</td>
      <td>[light-client](https://docs.rs/light-client)</td>
      <td>Client SDK for Compressed Accounts and Tokens</td>
    </tr>
  </tbody>
</table>

# Key Points

1. **Derive a new address** or **fetch compressed account** for on-chain verification.
2. **Fetch validity proof** from the RPC that verifies a new address does not exist (create) and/or the account hash exists in the state tree (update, close, etc.).
3. **Pack accounts** with the SDKs helper. Instructions require <Tooltip>Light System Program</Tooltip> and <Tooltip>Merkle tree accounts</Tooltip>. `PackedAccounts` converts their pubkeys to `u8` indices pointing to accounts in the instruction.
4. **Build the instruction** with the current account data, new data, packed accounts and validity proof.

<Tabs>
  <Tab title="Create">
    <div>
      <Frame>
        <img alt="" />
      </Frame>
    </div>

    <div>
      <Frame>
        <img alt="" />
      </Frame>
    </div>
  </Tab>

  <Tab title="Update">
    <div>
      <Frame>
        <img alt="" />
      </Frame>
    </div>

    <div>
      <Frame>
        <img alt="" />
      </Frame>
    </div>
  </Tab>

  <Tab title="Close">
    <div>
      <Frame>
        <img alt="" />
      </Frame>
    </div>

    <div>
      <Frame>
        <img alt="" />
      </Frame>
    </div>
  </Tab>

  <Tab title="Reinitialize">
    <div>
      <Frame>
        <img alt="" />
      </Frame>
    </div>

    <div>
      <Frame>
        <img alt="" />
      </Frame>
    </div>
  </Tab>

  <Tab title="Burn">
    <div>
      <Frame>
        <img alt="" />
      </Frame>
    </div>

    <div>
      <Frame>
        <img alt="" />
      </Frame>
    </div>
  </Tab>
</Tabs>

# Get Started

<Steps>
  <Step>
    ## Setup

    <Tabs>
      <Tab title="Typescript">
        <Note>
          Use the [API documentation](https://lightprotocol.github.io/light-protocol/) to look up specific function signatures, parameters, and return types.
        </Note>

        ### 1. Installation

        <Tabs>
          <Tab title="npm">
            ```bash theme={null}
            npm install --save \
                @lightprotocol/stateless.js \
                @lightprotocol/compressed-token \
                @solana/web3.js
            ```
          </Tab>

          <Tab title="yarn">
            ```bash theme={null}
            yarn add \
                @lightprotocol/stateless.js \
                @lightprotocol/compressed-token \
                @solana/web3.js
            ```
          </Tab>

          <Tab title="pnpm">
            ```bash theme={null}
            pnpm add \
                @lightprotocol/stateless.js \
                @lightprotocol/compressed-token \
                @solana/web3.js
            ```
          </Tab>
        </Tabs>

        ### 2. RPC Connection

        `Rpc` is a thin wrapper extending Solana's web3.js `Connection` class with compression-related endpoints.

        <Tabs>
          <Tab title="Mainnet">
            ```typescript theme={null}
            const rpc = createRpc('https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY');
            ```
          </Tab>

          <Tab title="Devnet">
            ```typescript theme={null}
            const rpc = createRpc('https://devnet.helius-rpc.com/?api-key=YOUR_API_KEY');
            ```
          </Tab>

          <Tab title="Localnet">
            1. Install the CLI

            ```bash theme={null}
            npm i -g @lightprotocol/zk-compression-cli
            ```

            2. Start a local Solana test validator, photon indexer, and prover server on default ports 8899, 8784, and 3001.

            ```bash theme={null}
            light test-validator
            ```
          </Tab>
        </Tabs>
      </Tab>

      <Tab title="Rust">
        ### 1. Dependencies

        ```toml theme={null}
        [dependencies]
        light-client = "0.16.0"
        light-sdk = "0.16.0"
        ```

        ### 2. RPC Connection

        Connect to an RPC provider that supports ZK Compression, such as Helius and Triton.

        <Tabs>
          <Tab title="Mainnet">
            ```rust theme={null}
            let config = LightClientConfig::new(
                "https://api.mainnet-beta.solana.com".to_string(),
                Some("https://mainnet.helius.xyz".to_string()),
                Some("YOUR_API_KEY".to_string())
            );

            let mut client = LightClient::new(config).await?;

            client.payer = read_keypair_file("~/.config/solana/id.json")?;
            ```
          </Tab>

          <Tab title="Devnet">
            ```rust theme={null}
            let config = LightClientConfig::devnet(
                Some("https://devnet.helius-rpc.com".to_string()),
                Some("YOUR_API_KEY".to_string())
            );

            let mut client = LightClient::new(config).await?;

            client.payer = read_keypair_file("~/.config/solana/id.json")?;
            ```
          </Tab>

          <Tab title="Localnet">
            ```rust theme={null}
            let config = LightClientConfig::local();

            let mut client = LightClient::new(config).await?;

            client.payer = read_keypair_file("~/.config/solana/id.json")?;
            ```

            1. Install the CLI

            ```bash theme={null}
            npm i -g @lightprotocol/zk-compression-cli
            ```

            2. Start a single-node Solana cluster, an RPC node, and a prover node at ports 8899, 8784, and 3001.

            ```bash theme={null}
            light test-validator
            ```
          </Tab>
        </Tabs>
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ## Address

    Derive a persistent address as a unique identifier for your compressed account, similar to [program-derived addresses (PDAs)](https://solana.com/docs/core/pda).

    You derive addresses in two scenarios:

    * **At account creation** - derive the address to create the account's persistent identifier, then pass it to `getValidityProofV0()` in the address array
    * **Before building instructions** - derive the address to fetch existing accounts using `rpc.getCompressedAccount()`

    <Tabs>
      <Tab title="Typescript">
        ```typescript theme={null}
        const addressTree = await rpc.getAddressTreeInfoV2();
        const seed = deriveAddressSeedV2(
          [Buffer.from('my-seed')]
        );

        const address = deriveAddressV2(
          seed,
          addressTree.tree,
          programId
        );
        ```
      </Tab>

      <Tab title="Rust">
        ```rust theme={null}
        use light_sdk::address::v2::derive_address;

        let address_tree_info = rpc.get_address_tree_v2();
        let (address, _) = derive_address(
            &[b"my-seed"],
            &address_tree_info.tree,
            &program_id,
        );
        ```
      </Tab>
    </Tabs>

    Like PDAs, compressed account addresses don't have a private key; rather, they're derived from the program that owns them.

    * The key difference to PDAs is compressed addresses are stored in an address tree and include this tree in the address derivation.
    * Different trees produce different addresses from identical seeds. You should check the address tree in your program.

    <Tip>
      The protocol maintains Merkle trees. You don't need to initialize custom trees. Find the [pubkeys for Merkle trees here](https://www.zkcompression.com/resources/addresses-and-urls).
    </Tip>
  </Step>

  <Step>
    ## Validity Proof

    Transactions with compressed accounts must include a validity proof:

    * To **create** a compressed account, you prove the **new address doesn't already exist** in the address tree.
    * In **other instructions**, you **prove  the compressed account hash exists** in a state tree.
    * You can **combine multiple addresses and hashes in one proof** to optimize compute cost and instruction data.

    <Info>
      You fetch a validity proof from your RPC provider that supports ZK Compression, such as Helius or Triton.
    </Info>

    <Tabs>
      <Tab title="Typescript">
        <Tabs>
          <Tab title="Create">
            ```typescript theme={null}
            const proof = await rpc.getValidityProofV0(
              [],
              [{
                address: bn(address.toBytes()),
                tree: addressTree.tree,
                queue: addressTree.queue
              }]
            );
            ```

            **1. Pass these parameters**:

            * **Specify the new address**, `tree` and `queue` pubkeys from the address tree `TreeInfo`.
            * When you create an account you don't reference a compressed account hash in the hash array (`[]`). The account doesn't exist in a state Merkle tree yet.

            <Note>
              For account creation, you prove the address does not exist yet in the address tree.
            </Note>

            **2. The RPC returns**:

            * The proof that the new address does not exist in the address tree. It is used in the instruction data.
            * `rootIndices` array with root index.
              * The root index points to the root in the address tree accounts root history array.
              * This root is used by the `LightSystemProgram` to verify the validity proof.
          </Tab>

          <Tab title="Update, Close, Reinit, Burn">
            ```typescript theme={null}
            const proof = await rpc.getValidityProofV0(
              [{
                hash: compressedAccount.hash,
                tree: compressedAccount.treeInfo.tree,
                queue: compressedAccount.treeInfo.queue
              }],
              []
            );
            ```

            **1. Pass these parameters**:

            Specify the **account hash**, `tree` and `queue` pubkeys from the compressed account's `TreeInfo`.

            <Note>
              * You don't specify the address for update, close, reinitialize, and burn instructions.
              * The proof **verifies the account hash exists in the state tree** for these instructions.
              * The validity proof structure is identical. The difference is in your program's instruction handler.
            </Note>

            **2. The RPC returns**:

            * The proof that the account hash exists in the state tree for your instruction data.
            * `rootIndices` and `leafIndices` arrays with proof metadata to pack accounts.
          </Tab>
        </Tabs>
      </Tab>

      <Tab title="Rust">
        <Tabs>
          <Tab title="Create">
            ```rust theme={null}
            let rpc_result = rpc
                .get_validity_proof(
                    vec![],
                    vec![AddressWithTree {
                      address: *address,
                      tree: address_tree_info.tree
                    }],
                    None,
                )
                .await?
                .value;
            ```

            **1. Pass these parameters**:

            * **Specify the new address** and `tree` pubkey from the address tree `TreeInfo`. The `queue` pubkey is only required in TypeScript.
            * When you create an account you don't reference a compressed account hash in the hash array (`vec![]`).

            <Note>
              For account creation, you prove the address does not exist yet in the address tree.
            </Note>

            **2. The RPC returns `ValidityProofWithContext`**:

            * The proof that the new address does not exist in the address tree for your instruction data.
            * `addresses` with the public key and metadata of the address tree to pack accounts.
          </Tab>

          <Tab title="Update, Close, Reinit, Burn">
            ```rust theme={null}
            let rpc_result = rpc
                .get_validity_proof(
                    vec![compressed_account.hash],
                    vec![],
                    None,
                )
                .await?
                .value;
            ```

            **1. Pass these parameters**:

            Specify the **account hash**, `tree` and `queue` pubkeys from the compressed account's `TreeInfo`.

            <Note>
              * You don't specify the address for update, close, reinitialize, and burn instructions.
              * The proof **verifies the account hash exists in the state tree** for these instructions.
              * The validity proof structure is identical. The difference is in your program's instruction handler.
            </Note>

            **2. The RPC returns `ValidityProofWithContext`**:

            * The proof that the **account hash exists in the state tree** for your instruction data
            * `accounts` with the **public key and metadata of the state tree** to pack accounts.
          </Tab>
        </Tabs>
      </Tab>
    </Tabs>

    ### Optimize with Combined Proofs

    You can prove **in a single proof**:

    * multiple addresses,
    * multiple account hashes, or
    * a combination of addresses and account hashes.

    |                        |                                                                                           |
    | ---------------------- | ----------------------------------------------------------------------------------------- |
    | Account Hash-only      | 1 to 8 hashes                                                                             |
    | Address-only           | 1 to 8 addresses                                                                          |
    | Mixed (hash + address) | Any combination of <br />**1 to 4** account hashes **and** <br />**1 or 4** new addresses |

    <Tip>
      **Advantages of combined proofs**:

      * You only add **one 128 byte validity proof** to your instruction data.
      * This can **optimize** your **transaction's size** to stay inside the 1232 byte instruction data limit.
      * **Compute unit consumption is 100k CU** per `ValidityProof` verification by the Light System Program.
    </Tip>

    ### Example Create Address & Update Account in one Proof

    In this example, we generate one proof that proves that an account exists and that a new address does not exist yet.

    <Tabs>
      <Tab title="Typescript">
        ```typescript theme={null}
        const proof = await rpc.getValidityProofV0(
          [{
            hash: compressedAccount.hash,
            tree: compressedAccount.treeInfo.tree,
            queue: compressedAccount.treeInfo.queue
          }],
          [{
            address: bn(address.toBytes()),
            tree: addressTree.tree,
            queue: addressTree.queue
          }]
        );
        ```

        **1. Pass these parameters**:

        * Specify one or more **account hashes**, `tree` and `queue` pubkeys from the compressed account's `TreeInfo`.
        * Specify one or more **new addresses** with their `tree` and `queue` pubkeys from the address tree `TreeInfo`.

        **2. The RPC returns**:

        * A single combined proof that proves both the **account hash exists in the state tree** and the **new address does not exist in the address tree** for your instruction data
        * `rootIndices` and `leafIndices` arrays with proof metadata to pack accounts.
      </Tab>

      <Tab title="Rust">
        ```rust theme={null}
        let rpc_result = rpc
            .get_validity_proof(
                vec![compressed_account.hash],
                vec![AddressWithTree {
                  address: *address,
                  tree: address_tree_info.tree
                }],
                None,
            )
            .await?
            .value;
        ```

        **1. Pass these parameters**:

        * Specify one or more **compressed account hashes**.
        * Specify one or more **derived addresses** with their `tree` pubkeys from the address tree `TreeInfo`. The `queue` pubkey is only required in TypeScript.

        **2. The RPC returns `ValidityProofWithContext`**:

        * A single combined proof that verifies both the **account hash exists in the state tree** and the **new address does not exist in the address tree** for your instruction data
        * New `addresses` with the public key and metadata of the address tree to pack accounts.
        * `accounts` with the public key and metadata of the state tree to pack accounts.
      </Tab>
    </Tabs>

    <Note>
      See the full [create-and-update program example for this proof combination with tests](https://github.com/Lightprotocol/program-examples/tree/main/create-and-update).
    </Note>
  </Step>

  <Step>
    ## Accounts

    To interact with a compressed account you need System accounts such as the <Tooltip>Light System Program</Tooltip>,
    and <Tooltip>Merkle tree accounts</Tooltip>.

    Compressed account metadata (`TreeInfo`) includes Merkle tree pubkeys.
    To optimize instruction data we pack the `pubkeys` of `TreeInfo` into the `u8` indices of `PackedTreeInfo`.

    The `u8` indices point to the Merkle tree account in the instructions accounts.
    You can create the instructions accounts and indices with `PackedAccounts`.

    We recommend to append `PackedAccounts` after your program specific accounts and in anchor in `remaining_accounts`.

    ```
                                      PackedAccounts
                      ┌--------------------------------------------┐
    [custom accounts] [pre accounts][system accounts][tree accounts]
                            ↑              ↑               ↑
                         Signers,      Light System    State trees,
                        fee payer        accounts     address trees,
    ```

    <Accordion title="Custom Accounts">
      Custom accounts are program-specific accounts you pass manually in your instruction, typically through Anchor's account struct.
    </Accordion>

    <Accordion title="Pre Accounts">
      Optional, custom accounts (signers, PDAs for CPIs) and other accounts can be added to pre accounts.
      Pre accounts can simplify building the accounts for pinocchio and native programs.
    </Accordion>

    <Accordion title="Light System Accounts">
      **Light System accounts** are 6 required accounts for proof verification and CPI calls to update state and address trees.

      <table>
        <colgroup>
          <col />

          <col />

          <col />
        </colgroup>

        <thead>
          <tr>
            <th />

            <th />

            <th />
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>1</td>
            <td><strong><Tooltip href="https://solscan.io/account/SySTEM1eSU2p4BGQfQpimFEWWSC1XDFeun3Nqzz3rT7">Light System Program</Tooltip></strong></td>
            <td>Verifies validity proofs, compressed account ownership checks, and CPIs the Account Compression Program to update tree accounts.</td>
          </tr>

          <tr>
            <td>2</td>
            <td><strong>CPI Signer</strong></td>

            <td>
              * PDA to sign CPI calls from your program to the Light System Program.<br />
              * Verified by the Light System Program during CPI.<br />
              * Derived from your program ID.
            </td>
          </tr>

          <tr>
            <td>3</td>
            <td><strong>Registered Program PDA</strong></td>
            <td>Provides access control to the Account Compression Program.</td>
          </tr>

          <tr>
            <td>4</td>
            <td><strong><Tooltip href="https://solscan.io/account/HZH7qSLcpAeDqCopVU4e5XkhT9j3JFsQiq8CmruY3aru">Account Compression Authority</Tooltip></strong></td>
            <td>Signs CPI calls from the Light System Program to the Account Compression Program.</td>
          </tr>

          <tr>
            <td>5</td>
            <td><strong><Tooltip href="https://solscan.io/account/compr6CUsB5m2jS4Y3831ztGSTnDpnKJTKS95d64XVq">Account Compression Program</Tooltip></strong></td>

            <td>
              * Writes to state and address tree accounts.<br />
              * Clients and the Account Compression Program do not interact directly — handled internally.
            </td>
          </tr>

          <tr>
            <td>6</td>
            <td><strong><Tooltip href="https://solscan.io/account/11111111111111111111111111111111">System Program</Tooltip></strong></td>
            <td>Solana System Program used to transfer lamports.</td>
          </tr>
        </tbody>
      </table>
    </Accordion>

    <Accordion title="Merkle Tree Accounts">
      **Merkle tree accounts** are the accounts of state tree and address trees that store compressed account hashes and addresses.
    </Accordion>

    <Tabs>
      <Tab title="Typescript">
        <Tabs>
          <Tab title="Create">
            ```typescript theme={null}
            // 1. Initialize helper
            const packedAccounts 
              = new PackedAccounts();

            // 2. Add light system accounts
            const systemAccountConfig
              = SystemAccountMetaConfig.new(programId);
            packedAccounts.addSystemAccounts(systemAccountConfig);

            // 3. Get indices for tree accounts
            const addressMerkleTreePubkeyIndex 
              = packedAccounts.insertOrGet(addressTree);
            const addressQueuePubkeyIndex 
              = packedAccounts.insertOrGet(addressQueue);

            const packedAddressTreeInfo = {
              rootIndex: proofRpcResult.rootIndices[0],
              addressMerkleTreePubkeyIndex,
              addressQueuePubkeyIndex,
            };

            // 4. Get index for output state tree
            const stateTreeInfos = await rpc.getStateTreeInfos();
            const outputStateTree = selectStateTreeInfo(stateTreeInfos).tree;
            const outputStateTreeIndex
              = packedAccounts.insertOrGet(outputStateTree);

            // 5. Convert to Account Metas
            const { remainingAccounts }
              = packedAccounts.toAccountMetas();
            ```
          </Tab>

          <Tab title="Update, Close, Reinit Burn">
            ```typescript theme={null}
            // 1. Initialize helper
            const packedAccounts
              = new PackedAccounts();

            // 2. Add system accounts
            const systemAccountConfig
              = SystemAccountMetaConfig.new(programId);
            packedAccounts.addSystemAccounts(systemAccountConfig);

            // 3. Get indices for tree accounts 
            const merkleTreePubkeyIndex
              = packedAccounts.insertOrGet(compressedAccount.treeInfo.tree);
            const queuePubkeyIndex
              = packedAccounts.insertOrGet(compressedAccount.treeInfo.queue);

            const packedInputAccounts = {
              merkleTreePubkeyIndex,
              queuePubkeyIndex,
              leafIndex: proofRpcResult.leafIndices[0],
              rootIndex: proofRpcResult.rootIndices[0],
            };

            const outputStateTreeIndex
              = packedAccounts.insertOrGet(outputStateTree);

            // 4. Convert to Account Metas
            const { remainingAccounts }
              = packedAccounts.toAccountMetas();
            ```
          </Tab>
        </Tabs>
      </Tab>

      <Tab title="Rust">
        <Tabs>
          <Tab title="Create">
            ```rust theme={null}
            // 1. Initialize helper
            let mut remaining_accounts = PackedAccounts::default();

            // 2. Add system accounts
            let config
              = SystemAccountMetaConfig::new(program_id);
              remaining_accounts.add_system_accounts(config)?;

            // 3. Get indices for tree accounts
            let packed_accounts
              = rpc_result.pack_tree_infos(&mut remaining_accounts);

            // 4. Get index for output state tree
            let output_state_tree_info = rpc.get_random_state_tree_info()?;
            let output_state_tree_index
              = output_state_tree_info.pack_output_tree_index(&mut remaining_accounts)?;

            // 5. Convert to Account Metas
            let (remaining_accounts_metas, _, _)
              = remaining_accounts.to_account_metas();
            ```
          </Tab>

          <Tab title="Update, Close, Reinit, Burn">
            ```rust theme={null}
            // 1. Initialize helper
            let mut remaining_accounts = PackedAccounts::default();

            // 2. Add system accounts
            let config
              = SystemAccountMetaConfig::new(program_id);
              remaining_accounts.add_system_accounts(config)?;

            // 3. Get indices for tree accounts
            let packed_tree_accounts = rpc_result
                .pack_tree_infos(&mut remaining_accounts)
                .state_trees // includes output_state_tree_index
                .unwrap();

            // 4. Convert to Account Metas
            let (remaining_accounts_metas, _, _)
              = remaining_accounts.to_account_metas();
            ```
          </Tab>
        </Tabs>
      </Tab>
    </Tabs>

    Depending on your instruction you must include different tree and queue accounts.

    <table>
      <thead>
        <tr>
          <th>Instruction</th>
          <th>Address Tree</th>
          <th>State Tree (includes nullifier queue)</th>
          <th>Output Queue</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>Create</td>
          <td>✓</td>
          <td>-</td>
          <td>✓</td>
        </tr>

        <tr>
          <td>Update / Close / Reinit</td>
          <td>-</td>
          <td>✓</td>
          <td>✓</td>
        </tr>

        <tr>
          <td>Burn</td>
          <td>-</td>
          <td>✓</td>
          <td>-</td>
        </tr>
      </tbody>
    </table>

    * **Address tree**: only used to derive and store a new address.
    * **State tree**: used to reference the existing compressed account hash. Therefore not used by create. The state tree and nullifier queue are combined into a single account.
    * **Output Queue**: used to store compressed account hashes. A forester node updates the state tree asynchronously.
      * **Create only** - Choose any available queue, or use a pre-selected queue to store the new compressed account.
      * **Update/Close/Reinit** - Use the queue of the existing compressed account as output queue.
      * **Mixed instructions (create + update in same tx)** - Use the queue from the existing account as output queue.
      * **Burn** - Do not include an output queue.
  </Step>

  <Step>
    ## Instruction Data

    Build your instruction data with the validity proof, tree account indices, and account data.

    <Tabs>
      <Tab title="Typescript">
        <Tabs>
          <Tab title="Create">
            ```typescript theme={null}
            const proof = {
              0: proofRpcResult.compressedProof,
            };

            const instructionData = {
              proof,
              addressTreeInfo: packedAddressTreeInfo,
              outputStateTreeIndex: outputStateTreeIndex,
              message,
            };
            ```

            1. Include `proof` to **prove the address does not exist** in the address tree
            2. Specify **Merkle trees to store address and account hash** to where you packed accounts.
            3. Pass **initial account data**
          </Tab>

          <Tab title="Update">
            ```typescript theme={null}
            const proof = {
              0: proofRpcResult.compressedProof,
            };

            const instructionData = {
              proof,
              accountMeta: {
                treeInfo: packedStateTreeInfo,
                address: compressedAccount.address,
                outputStateTreeIndex: outputStateTreeIndex
              },
              currentMessage: currentAccount.message,
              newMessage,
            };
            ```

            1. Include `proof` to to prove the **account hash exists** in the state tree
            2. Specify the existing accounts address, its `packedStateTreeInfo` and the output state tree to store the updated compressed account hash.
            3. Pass **current account data** and **new data**

            <Tip>
              Use the state tree of the existing compressed account as output state tree.
            </Tip>
          </Tab>

          <Tab title="Close">
            ```typescript theme={null}
            const proof = {
              0: proofRpcResult.compressedProof,
            };

            const instructionData = {
              proof,
              accountMeta: {
                treeInfo: packedStateTreeInfo,
                address: compressedAccount.address,
                outputStateTreeIndex: outputStateTreeIndex
              },
              currentMessage: currentAccount.message,
            };
            ```

            1. Include `proof` to prove the **account hash exists** in the state tree
            2. Specify the existing accounts address, its `packedStateTreeInfo` and the output state tree to store the **hash with zero values** for the closed account.
            3. Pass **current account data**

            <Tip>
              Use the state tree of the existing compressed account as output state tree.
            </Tip>
          </Tab>

          <Tab title="Reinit">
            ```typescript theme={null}
            const proof = {
              0: proofRpcResult.compressedProof,
            };

            const instructionData = {
              proof,
              accountMeta: {
                treeInfo: packedStateTreeInfo,
                address: compressedAccount.address,
                outputStateTreeIndex: outputStateTreeIndex
              },
            };
            ```

            1. Include `proof` to prove the **account hash exists** in the state tree
            2. Specify the existing accounts address, its `packedStateTreeInfo` and the output state tree that will store the reinitialized account hash
            3. Reinitialize creates an account with **default-initialized values**

            * These values are `Pubkey` as all zeros, numbers as `0`, strings as empty.
            * To set custom values, update the account in the same or a separate transaction.

            <Tip>
              Use the state tree of the existing compressed account as output state tree.
            </Tip>
          </Tab>

          <Tab title="Burn">
            ```typescript theme={null}
            const proof = {
              0: proofRpcResult.compressedProof,
            };

            const instructionData = {
              proof,
              accountMeta: {
                treeInfo: packedStateTreeInfo,
                address: compressedAccount.address
              },
              currentMessage: currentAccount.message,
            };
            ```

            1. Include `proof` to prove the **account hash exists** in the state tree
            2. Specify the existing accounts address and its `packedStateTreeInfo`. You don't need to specify the output state tree, since burn permanently removes the account.
            3. Pass **current account data**
          </Tab>
        </Tabs>
      </Tab>

      <Tab title="Rust">
        <Tabs>
          <Tab title="Create">
            ```rust theme={null}
            let instruction_data = create::instruction::CreateAccount {
                proof: rpc_result.proof,
                address_tree_info: packed_accounts.address_trees[0],
                output_state_tree_index: output_state_tree_index,
                message,
            }
            .data();
            ```

            1. Include `proof` to prove the **address does not exist** in the address tree
            2. Specify **address tree and output state tree** to where you packed accounts
            3. Pass **initial account data**
          </Tab>

          <Tab title="Update">
            ```rust theme={null}
            let instruction_data = update::instruction::UpdateAccount {
                proof: rpc_result.proof,
                current_account,
                account_meta: CompressedAccountMeta {
                    tree_info: packed_tree_accounts.packed_tree_infos[0],
                    address: compressed_account.address.unwrap(),
                    output_state_tree_index: packed_tree_accounts.output_tree_index,
                },
                new_message,
            }
            .data();
            ```

            <Tip>
              Use the state tree of the existing compressed account as output state tree.
            </Tip>

            1. Include `proof` to prove the **account hash exists** in the state tree
            2. Specify the existing accounts address, its `packed_tree_infos` and the output state tree to store the updated compressed account hash
            3. Pass **current account data** and **new data**
          </Tab>

          <Tab title="Close">
            ```rust theme={null}
            let instruction_data = close::instruction::CloseAccount {
                proof: rpc_result.proof,
                account_meta: CompressedAccountMeta {
                    tree_info: packed_tree_accounts.packed_tree_infos[0],
                    address: compressed_account.address.unwrap(),
                    output_state_tree_index: packed_tree_accounts.output_tree_index,
                },
                current_message,
            }
            .data();
            ```

            <Tip>
              Use the state tree of the existing compressed account as output state tree.
            </Tip>

            1. Include `proof` to prove the **account hash exists** in the state tree
            2. Specify the existing accounts address, its `packed_tree_infos` and the output state tree to store the **hash with zero values** for the closed account
            3. Pass **current account data**
          </Tab>

          <Tab title="Reinit">
            ```rust theme={null}
            let instruction_data = reinit::instruction::ReinitAccount {
                proof: rpc_result.proof,
                account_meta: CompressedAccountMeta {
                    tree_info: packed_tree_accounts.packed_tree_infos[0],
                    address: compressed_account.address.unwrap(),
                    output_state_tree_index: packed_tree_accounts.output_tree_index,
                },
            }
            .data();
            ```

            <Tip>
              Use the state tree of the existing compressed account as output state tree.
            </Tip>

            1. Include `proof` to prove the **account hash exists** in the state tree
            2. Specify the existing accounts address, its `packed_tree_infos` and the output state tree that will store the reinitialized account hash
            3. Reinitialize creates an account with **default-initialized values**

            * These values are `Pubkey` as all zeros, numbers as `0`, strings as empty.
            * To set custom values, update the account in the same or a separate transaction.
          </Tab>

          <Tab title="Burn">
            ```rust theme={null}
            let instruction_data = burn::instruction::BurnAccount {
                proof: rpc_result.proof,
                account_meta: CompressedAccountMetaBurn {
                    tree_info: packed_tree_accounts.packed_tree_infos[0],
                    address: compressed_account.address.unwrap(),
                },
                current_message,
            }
            .data();
            ```

            1. Include `proof` to prove the **account hash exists** in the state tree
            2. Specify the existing accounts address and its `packed_tree_infos`. You don't need to specify the output state tree, since burn permanently removes the account
            3. Pass **current account data**
          </Tab>
        </Tabs>
      </Tab>
    </Tabs>

    <Warning>
      * When creating or updating multiple accounts in a single transaction, use one output state tree.
      * Minimize the number of different trees per transaction to keep instruction data light.
    </Warning>
  </Step>

  <Step>
    ## Instruction

    Build the instruction with your `program_id`, `accounts`, and `data`.

    * Accounts combine your program-specific accounts and `PackedAccounts`.
    * Data includes your compressed accounts, validity proof and other instruction data.

    <Tabs>
      <Tab title="Typescript">
        ```typescript theme={null}
        //             Accounts
        // ┌-------------------------------┐
        // .accounts()    .remainingAccounts()
        // [custom]         [PackedAccounts]

        const instruction = await program.methods
          .yourInstruction(instructionData)
          .accounts({
            signer: signer.publicKey,
          })
          .remainingAccounts(remainingAccounts)
          .instruction();
        ```
      </Tab>

      <Tab title="Rust">
        ```rust theme={null}
        //          Accounts
        // ┌---------------------------------┐
        // [custom accounts]  [PackedAccounts]
        let accounts = [vec![AccountMeta::new(payer.pubkey(), true)], remaining_accounts].concat();

        let instruction = Instruction {
            program_id: program_id,
            accounts,
            data: instruction_data,
        };
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ## Send Transaction
  </Step>
</Steps>

# Full Code Examples

<Tabs>
  <Tab title="TypeScript">
    <Info>
      Find the source code [here](https://github.com/Lightprotocol/program-examples/tree/main/basic-operations/anchor/create/tests).
    </Info>

    ```typescript theme={null}
    import * as anchor from "@coral-xyz/anchor";
    import { Program, web3 } from "@coral-xyz/anchor";
    import { Create } from "../target/types/create";
    import idl from "../target/idl/create.json";
    import {
      bn,
      CompressedAccountWithMerkleContext,
      confirmTx,
      createRpc,
      defaultTestStateTreeAccounts,
      deriveAddressV2,
      deriveAddressSeedV2,
      batchAddressTree,
      PackedAccounts,
      Rpc,
      sleep,
      SystemAccountMetaConfig,
      featureFlags,
      VERSION,
    } from "@lightprotocol/stateless.js";
    import * as assert from "assert";

    // Force V2 mode
    (featureFlags as any).version = VERSION.V2;

    const path = require("path");
    const os = require("os");
    require("dotenv").config();

    const anchorWalletPath = path.join(os.homedir(), ".config/solana/id.json");
    process.env.ANCHOR_WALLET = anchorWalletPath;

    describe("test-anchor", () => {
      const program = anchor.workspace.Create as Program<Create>;
      const coder = new anchor.BorshCoder(idl as anchor.Idl);

      it("create compressed account", async () => {
        let signer = new web3.Keypair();
        let rpc = createRpc(
          "http://127.0.0.1:8899",
          "http://127.0.0.1:8784",
          "http://127.0.0.1:3001",
          {
            commitment: "confirmed",
          },
        );
        let lamports = web3.LAMPORTS_PER_SOL;
        await rpc.requestAirdrop(signer.publicKey, lamports);
        await sleep(2000);

        const outputStateTree = defaultTestStateTreeAccounts().merkleTree;
        const addressTree = new web3.PublicKey(batchAddressTree);

        const messageSeed = new TextEncoder().encode("message");
        const seed = deriveAddressSeedV2([messageSeed, signer.publicKey.toBytes()]);
        const address = deriveAddressV2(
          seed,
          addressTree,
          new web3.PublicKey(program.idl.address),
        );

        // Create compressed account with message
        const txId = await createCompressedAccount(
          rpc,
          addressTree,
          address,
          program,
          outputStateTree,
          signer,
          "Hello, compressed world!",
        );
        console.log("Transaction ID:", txId);

        // Wait for indexer to process the transaction
        const slot = await rpc.getSlot();
        await rpc.confirmTransactionIndexed(slot);

        let compressedAccount = await rpc.getCompressedAccount(bn(address.toBytes()));
        let myAccount = coder.types.decode(
          "MyCompressedAccount",
          compressedAccount.data.data,
        );

        console.log("Decoded data owner:", myAccount.owner.toBase58());
        console.log("Decoded data message:", myAccount.message);

        // Verify account data
        assert.ok(
          myAccount.owner.equals(signer.publicKey),
          "Owner should match signer public key"
        );
        assert.strictEqual(
          myAccount.message,
          "Hello, compressed world!",
          "Message should match the created message"
        );
      });
    });

    async function createCompressedAccount(
      rpc: Rpc,
      addressTree: anchor.web3.PublicKey,
      address: anchor.web3.PublicKey,
      program: anchor.Program<Create>,
      outputStateTree: anchor.web3.PublicKey,
      signer: anchor.web3.Keypair,
      message: string,
    ) {
      const proofRpcResult = await rpc.getValidityProofV0(
        [],
        [
          {
            tree: addressTree,
            queue: addressTree,
            address: bn(address.toBytes()),
          },
        ],
      );
      const systemAccountConfig = new SystemAccountMetaConfig(program.programId);
      let remainingAccounts = new PackedAccounts();
      remainingAccounts.addSystemAccountsV2(systemAccountConfig);

      const addressMerkleTreePubkeyIndex =
        remainingAccounts.insertOrGet(addressTree);
      const addressQueuePubkeyIndex = addressMerkleTreePubkeyIndex;
      const packedAddressTreeInfo = {
        rootIndex: proofRpcResult.rootIndices[0],
        addressMerkleTreePubkeyIndex,
        addressQueuePubkeyIndex,
      };
      const outputStateTreeIndex =
        remainingAccounts.insertOrGet(outputStateTree);
      let proof = {
        0: proofRpcResult.compressedProof,
      };
      const computeBudgetIx = web3.ComputeBudgetProgram.setComputeUnitLimit({
        units: 1000000,
      });
      let tx = await program.methods
        .createAccount(proof, packedAddressTreeInfo, outputStateTreeIndex, message)
        .accounts({
          signer: signer.publicKey,
        })
        .preInstructions([computeBudgetIx])
        .remainingAccounts(remainingAccounts.toAccountMetas().remainingAccounts)
        .signers([signer])
        .transaction();
      tx.recentBlockhash = (await rpc.getRecentBlockhash()).blockhash;
      tx.sign(signer);

      const sig = await rpc.sendTransaction(tx, [signer]);
      await confirmTx(rpc, sig);
      return sig;
    }
    ```
  </Tab>

  <Tab title="Rust">
    <Info>
      Find the source code [here](https://github.com/Lightprotocol/program-examples/tree/main/basic-operations/anchor/create/programs/create/tests).
    </Info>

    ```rust theme={null}
    #![cfg(feature = "test-sbf")]

    use anchor_lang::AnchorDeserialize;
    use light_program_test::{
        program_test::LightProgramTest, AddressWithTree, Indexer, ProgramTestConfig, Rpc, RpcError,
    };
    use light_sdk::{
        address::v2::derive_address,
        instruction::{PackedAccounts, SystemAccountMetaConfig},
    };
    use create::MyCompressedAccount;
    use solana_sdk::{
        instruction::{AccountMeta, Instruction},
        signature::{Keypair, Signature, Signer},
    };

    #[tokio::test]
    async fn test_create() {
        let config = ProgramTestConfig::new(true, Some(vec![("create", create::ID)]));
        let mut rpc = LightProgramTest::new(config).await.unwrap();
        let payer = rpc.get_payer().insecure_clone();

        let address_tree_info = rpc.get_address_tree_v2();

        let (address, _) = derive_address(
            &[b"message", payer.pubkey().as_ref()],
            &address_tree_info.tree,
            &create::ID,
        );

        create_compressed_account(&mut rpc, &payer, &address, "Hello, compressed world!".to_string())
            .await
            .unwrap();

        let compressed_account = rpc
            .get_compressed_account(address, None)
            .await
            .unwrap()
            .value
            .unwrap();
        let data = &compressed_account.data.as_ref().unwrap().data;
        let account = MyCompressedAccount::deserialize(&mut &data[..]).unwrap();
        assert_eq!(account.owner, payer.pubkey());
        assert_eq!(account.message, "Hello, compressed world!");
    }

    async fn create_compressed_account(
        rpc: &mut LightProgramTest,
        payer: &Keypair,
        address: &[u8; 32],
        message: String,
    ) -> Result<Signature, RpcError> {
        let config = SystemAccountMetaConfig::new(create::ID);
        let mut remaining_accounts = PackedAccounts::default();
        remaining_accounts.add_system_accounts_v2(config)?;

        let address_tree_info = rpc.get_address_tree_v2();

        let rpc_result = rpc
            .get_validity_proof(
                vec![],
                vec![AddressWithTree {
                    address: *address,
                    tree: address_tree_info.tree,
                }],
                None,
            )
            .await?
            .value;
        let packed_accounts = rpc_result.pack_tree_infos(&mut remaining_accounts);

        let output_state_tree_index = rpc
            .get_random_state_tree_info()?
            .pack_output_tree_index(&mut remaining_accounts)?;

        let (remaining_accounts, _, _) = remaining_accounts.to_account_metas();

        let instruction = Instruction {
            program_id: create::ID,
            accounts: [
                vec![AccountMeta::new(payer.pubkey(), true)],
                remaining_accounts,
            ]
            .concat(),
            data: {
                use anchor_lang::InstructionData;
                create::instruction::CreateAccount {
                    proof: rpc_result.proof,
                    address_tree_info: packed_accounts.address_trees[0],
                    output_state_tree_index: output_state_tree_index,
                    message,
                }
                .data()
            },
        };

        rpc.create_and_send_transaction(&[instruction], &payer.pubkey(), &[payer])
            .await
    }
    ```
  </Tab>
</Tabs>

Find all [full code examples with Rust and TypeScript tests here](https://github.com/Lightprotocol/program-examples/tree/main/basic-operations/anchor) for the following instructions:

* **create** - Initialize a new compressed account
* **update** - Modify data of an existing compressed account
* **close** - Close a compressed account (it can be initialized again).
* **reinit** - Reinitialize a closed account
* **burn** - Permanently delete a compressed account (it cannot be initialized again).

<Warning>
  For help with debugging, see the [Error Cheatsheet](../resources/error-cheatsheet/) and [AskDevin](https://deepwiki.com/Lightprotocol/light-protocol/3.1-javascripttypescript-sdks).
</Warning>

# Next Steps

<Card title="Get an overview to Compressed PDA guides and build a program." icon="chevron-right" href="/compressed-pdas/guides" />


# Overview
Source: https://www.zkcompression.com/compressed-pdas/guides

Overview to guides for Solana programs to create, update, close, reinitialize, and burn permanently compressed accounts.

| Guide                                                                                               | Description                                                                  |
| --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| [Create Compressed Accounts](/compressed-pdas/guides/how-to-create-compressed-accounts)             | Create compressed accounts with address                                      |
| [Update Compressed Accounts](/compressed-pdas/guides/how-to-update-compressed-accounts)             | Update compressed accounts                                                   |
| [Close Compressed Accounts](/compressed-pdas/guides/how-to-close-compressed-accounts)               | Close compressed accounts, retain the address                                |
| [Reinitialize Compressed Accounts](/compressed-pdas/guides/how-to-reinitialize-compressed-accounts) | Reinitialize closed compressed accounts with the same address and new values |
| [Burn Compressed Accounts](/compressed-pdas/guides/how-to-burn-compressed-accounts)                 | Burn compressed accounts and their address permanently                       |

Here is the complete flow to create, or interact with compressed accounts:

<Tabs>
  <Tab title="Create">
    <div>
      <Frame>
        <img alt="" />
      </Frame>
    </div>

    <div>
      <Frame>
        <img alt="" />
      </Frame>
    </div>
  </Tab>

  <Tab title="Update">
    <div>
      <Frame>
        <img alt="" />
      </Frame>
    </div>

    <div>
      <Frame>
        <img alt="" />
      </Frame>
    </div>
  </Tab>

  <Tab title="Close">
    <div>
      <Frame>
        <img alt="" />
      </Frame>
    </div>

    <div>
      <Frame>
        <img alt="" />
      </Frame>
    </div>
  </Tab>

  <Tab title="Reinitialize">
    <div>
      <Frame>
        <img alt="" />
      </Frame>
    </div>

    <div>
      <Frame>
        <img alt="" />
      </Frame>
    </div>
  </Tab>

  <Tab title="Burn">
    <div>
      <Frame>
        <img alt="" />
      </Frame>
    </div>

    <div>
      <Frame>
        <img alt="" />
      </Frame>
    </div>
  </Tab>
</Tabs>

## Next Steps

<Card title="Create a program with compressed accounts" icon="chevron-right" href="/compressed-pdas/guides/how-to-create-compressed-accounts" />


# Burn Compressed Accounts
Source: https://www.zkcompression.com/compressed-pdas/guides/how-to-burn-compressed-accounts

Guide to burn compressed accounts in Solana programs with full code examples.

Compressed accounts are permanently burned via CPI to the Light System Program.

Burning a compressed account

* consumes the existing account hash, and
* produces no output state.
* A burned account cannot be reinitialized.

<Note>
  Find [full code examples at the end](/compressed-pdas/guides/how-to-burn-compressed-accounts#full-code-example) for Anchor and native Rust.
</Note>

# Implementation Guide

This guide will cover the components of a Solana program that burns compressed accounts.\
Here is the complete flow to burn compressed accounts:

<div>
  <Frame>
    <img alt="" />
  </Frame>
</div>

<div>
  <Frame>
    <img alt="" />
  </Frame>
</div>

<Steps>
  <Step>
    ### Program Setup

    <Accordion title="Dependencies, Constants, Compressed Account">
      **Dependencies**

      Add dependencies to your program.

      <CodeGroup>
        ```toml Anchor theme={null}
        [dependencies]
        light-sdk = "0.19.0"
        anchor_lang = "0.31.1"
        ```

        ```toml Native Rust theme={null}
        [dependencies]
        light-sdk = "0.19.0"
        borsh = "0.10.0"
        solana-program = "2.2"
        ```
      </CodeGroup>

      * The `light-sdk` provides macros, wrappers and CPI interface to create and interact with compressed accounts.
      * Add the serialization library (`borsh` for native Rust, or use `AnchorSerialize`).

      **Constants**

      Set program address and derive the CPI authority PDA to call the Light System program.

      ```rust theme={null}
      declare_id!("rent4o4eAiMbxpkAM1HeXzks9YeGuz18SEgXEizVvPq");

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

      **`CPISigner`** is the configuration struct for CPI's to the Light System Program.

      * CPIs to the Light System program must be signed with a PDA derived by your program with the seed `b"authority"`
      * `derive_light_cpi_signer!` derives the CPI signer PDA for you at compile time.

      **Compressed Account**

      Define your compressed account struct.

      <CodeGroup>
        ```rust Anchor theme={null}
        #[event] // declared as event so that it is part of the idl.
        #[derive(
            Clone,
            Debug,
            Default,
            LightDiscriminator
        )]
        pub struct MyCompressedAccount {
            pub owner: Pubkey,
            pub message: String,
        }
        ```

        ```rust Native Rust theme={null}
        #[derive(
            Debug,
            Default,
            Clone,
            BorshSerialize,
            BorshDeserialize,
            LightDiscriminator,
        )]
        pub struct MyCompressedAccount {
            pub owner: Pubkey,
            pub message: String,
        }
        ```
      </CodeGroup>

      You derive

      * the standard traits (`Clone`, `Debug`, `Default`),
      * `borsh` or `AnchorSerialize` to serialize account data, and
      * `LightDiscriminator` to implements a unique type ID (8 bytes) to distinguish account types. The default compressed account layout enforces a discriminator in its *own field*, <Tooltip href="https://www.anchor-lang.com/">not the first 8 bytes of the data field</Tooltip>.

      <Info>
        The traits listed above are required for `LightAccount`. `LightAccount` wraps `MyCompressedAccount` in Step 3 to set the discriminator and create the compressed account's data.
      </Info>
    </Accordion>
  </Step>

  <Step>
    ### Instruction Data

    Define the instruction data with the following parameters:

    <Tabs>
      <Tab title="Anchor">
        ```rust theme={null}
        pub fn burn_account<'info>(
            ctx: Context<'_, '_, '_, 'info, GenericAnchorAccounts<'info>>,
            proof: ValidityProof,
            account_meta: CompressedAccountMetaBurn,
            current_message: String,
        ) -> Result<()>
        ```
      </Tab>

      <Tab title="Native Rust">
        ```rust theme={null}
        pub struct BurnInstructionData {
            pub proof: ValidityProof,
            pub account_meta: CompressedAccountMetaBurn,
            pub current_account: MyCompressedAccount,
        }
        ```
      </Tab>
    </Tabs>

    1. **Validity Proof**

    * Define `proof` to include the proof that the account exists in the state tree.
    * Clients fetch a validity proof with `getValidityProof()` from an RPC provider that supports ZK Compression (Helius, Triton, ...).

    2. **Specify input state**

    * Define `account_meta: CompressedAccountMetaBurn` to reference the existing account for the Light System Program to nullify permanently:
      * `tree_info: PackedStateTreeInfo`: References the existing account hash in the state tree.
      * `address`: The account's derived address.

    <Info>
      Burn does not specify an output state tree. `CompressedAccountMetaBurn` omits `output_state_tree_index` because no output state is created.
    </Info>

    3. **Current account data**

    * Define fields to include the current account data passed by the client.
    * This depends on your program logic. This example includes `current_message` (or `current_account` in Native Rust).
  </Step>

  <Step>
    ### Burn Compressed Account

    Burn the compressed account permanently with `LightAccount::new_burn()`. No account can be reinitialized at this address in the future.

    <Note>
      `new_burn()`

      1. hashes the current account data as input state and
      2. creates no output state to burn the account permanently.
    </Note>

    <Tabs>
      <Tab title="Anchor">
        ```rust theme={null}
        let my_compressed_account = LightAccount::<MyCompressedAccount>::new_burn(
            &crate::ID,
            &account_meta,
            MyCompressedAccount {
                owner: ctx.accounts.signer.key(),
                message: current_message,
            },
        )?;
        ```
      </Tab>

      <Tab title="Native Rust">
        ```rust theme={null}
        let my_compressed_account = LightAccount::<MyCompressedAccount>::new_burn(
            &ID,
            &instruction_data.account_meta,
            instruction_data.current_account,
        )?;
        ```
      </Tab>
    </Tabs>

    **Pass these parameters to `new_burn()`:**

    * `&program_id`: The program's ID that owns the compressed account.
    * `&account_meta`: The `CompressedAccountMetaBurn` from instruction data (*Step 2*) that identifies the existing account for the Light System Program to nullify permanently.
      * Anchor: Pass `&account_meta` directly
      * Native Rust: Pass `&instruction_data.account_meta`
    * Include the curent account data.
      * Anchor: Build `MyCompressedAccount` with `owner` and `message`.
      * Native Rust: Pass `instruction_data.current_account` directly.

    **The SDK creates:**

    * A `LightAccount` wrapper that marks the account as permanently burned with no output state.

    <Info>
      `new_burn()` hashes the input state. The Light System Program verifies the input hash and nullifies it in *Step 4*.
    </Info>
  </Step>

  <Step>
    ### Light System Program CPI

    The Light System Program CPI burns the compressed account permanently.

    <Note>
      The Light System Program

      * validates the account exists in state tree with the validity,
      * nullifies the existing account hash, and
      * creates no output state.
    </Note>

    <Tabs>
      <Tab title="Anchor">
        ```rust theme={null}
        let light_cpi_accounts = CpiAccounts::new(
            ctx.accounts.signer.as_ref(),
            ctx.remaining_accounts,
            crate::LIGHT_CPI_SIGNER,
        );

        LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, proof)
            .with_light_account(my_compressed_account)?
            .invoke(light_cpi_accounts)?;
        ```

        **Set up `CpiAccounts::new()`:**

        `CpiAccounts::new()` parses accounts for the CPI call to Light System Program.

        **Pass these parameters:**

        * `ctx.accounts.signer.as_ref()`: the transaction signer
        * `ctx.remaining_accounts`: Slice with `[system_accounts, ...packed_tree_accounts]`. The client builds this with `PackedAccounts` and passes it to the instruction.
        * `&LIGHT_CPI_SIGNER`: Your program's CPI signer PDA defined in Constants.
      </Tab>

      <Tab title="Native Rust">
        ```rust theme={null}
        let (signer, remaining_accounts) = accounts
            .split_first();

        let cpi_accounts = CpiAccounts::new(
            signer,
            remaining_accounts,
            LIGHT_CPI_SIGNER
        );

        LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, instruction_data.proof)
            .with_light_account(my_compressed_account)?
            .invoke(cpi_accounts)?;
        ```

        **Set up `CpiAccounts::new()`:**

        `CpiAccounts::new()` parses accounts for the CPI call to Light System Program.

        **Pass these parameters:**

        * `signer`: account that signs and pays for the transaction
        * `remaining_accounts`: Slice with `[system_accounts, ...packed_tree_accounts]`. The client builds this with `PackedAccounts`.
          * `split_first()` extracts the fee payer from the accounts array to separate it from the Light System Program accounts needed for the CPI.
        * `&LIGHT_CPI_SIGNER`: Your program's CPI signer PDA defined in Constants.
      </Tab>
    </Tabs>

    <Accordion title="System Accounts List">
      <table>
        <colgroup>
          <col />

          <col />

          <col />
        </colgroup>

        <thead>
          <tr>
            <th />

            <th />

            <th />
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>1</td>
            <td><strong><Tooltip href="https://solscan.io/account/SySTEM1eSU2p4BGQfQpimFEWWSC1XDFeun3Nqzz3rT7">Light System Program</Tooltip></strong></td>
            <td>Verifies validity proofs, compressed account ownership checks, and CPIs the Account Compression Program to update tree accounts.</td>
          </tr>

          <tr>
            <td>2</td>
            <td><strong>CPI Signer</strong></td>

            <td>
              * PDA to sign CPI calls from your program to the Light System Program.<br />
              * Verified by the Light System Program during CPI.<br />
              * Derived from your program ID.
            </td>
          </tr>

          <tr>
            <td>3</td>
            <td><strong>Registered Program PDA</strong></td>
            <td>Provides access control to the Account Compression Program.</td>
          </tr>

          <tr>
            <td>4</td>
            <td><strong><Tooltip href="https://solscan.io/account/HZH7qSLcpAeDqCopVU4e5XkhT9j3JFsQiq8CmruY3aru">Account Compression Authority</Tooltip></strong></td>
            <td>Signs CPI calls from the Light System Program to the Account Compression Program.</td>
          </tr>

          <tr>
            <td>5</td>
            <td><strong><Tooltip href="https://solscan.io/account/compr6CUsB5m2jS4Y3831ztGSTnDpnKJTKS95d64XVq">Account Compression Program</Tooltip></strong></td>

            <td>
              * Writes to state and address tree accounts.<br />
              * Clients and the Account Compression Program do not interact directly — handled internally.
            </td>
          </tr>

          <tr>
            <td>6</td>
            <td><strong><Tooltip href="https://solscan.io/account/11111111111111111111111111111111">System Program</Tooltip></strong></td>
            <td>Solana System Program used to transfer lamports.</td>
          </tr>
        </tbody>
      </table>
    </Accordion>

    **Build the CPI instruction**:

    * `new_cpi()` initializes the CPI instruction with the `proof` to prove the account exists in the state tree *- defined in the Instruction Data (Step 2).*
    * `with_light_account` adds the `LightAccount` wrapper configured to burn the account *- defined in Step 3*.
    * `invoke(light_cpi_accounts)` calls the Light System Program with `CpiAccounts`.
  </Step>
</Steps>

# Full Code Example

The example programs below implement all steps from this guide.

<Accordion title="Setup">
  **Install Solana CLI:**

  ```bash theme={null}
  sh -c "$(curl -sSfL https://release.solana.com/v2.2.15/install)"
  ```

  **Install Anchor CLI:**

  ```bash theme={null}
  cargo install --git https://github.com/coral-xyz/anchor avm --force
  avm install latest
  avm use latest
  ```

  **Install the Light CLI:**

  <Tabs>
    <Tab title="npm">
      ```bash theme={null}
      npm install -g @lightprotocol/zk-compression-cli@beta
      ```
    </Tab>

    <Tab title="yarn">
      ```bash theme={null}
      yarn global add @lightprotocol/zk-compression-cli@beta
      ```
    </Tab>

    <Tab title="pnpm">
      ```bash theme={null}
      pnpm add -g @lightprotocol/zk-compression-cli@beta
      ```
    </Tab>
  </Tabs>

  **Verify installation:**

  ```bash theme={null}
  light --version
  ```
</Accordion>

<Warning>
  For help with debugging, see the [Error Cheatsheet](../../resources/error-cheatsheet/).
</Warning>

<Tabs>
  <Tab title="Anchor">
    <Info>
      Find the source code [here](https://github.com/Lightprotocol/program-examples/tree/main/basic-operations/anchor/burn).
    </Info>

    ````rust theme={null}
    #![allow(unexpected_cfgs)]
    #![allow(deprecated)]

    use anchor_lang::{prelude::*, AnchorDeserialize, AnchorSerialize};
    use light_sdk::{
        account::LightAccount,
        address::v2::derive_address,
        cpi::{v2::CpiAccounts, CpiSigner},
        derive_light_cpi_signer,
        instruction::{account_meta::CompressedAccountMetaBurn, PackedAddressTreeInfo, ValidityProof},
        LightDiscriminator,
    };
    use light_sdk_types::ADDRESS_TREE_V2;

    declare_id!("BJhPWQnD31mdo6739Mac1gLuSsbbwTmpgjHsW6shf6WA");

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

    #[program]
    pub mod burn {

        use super::*;
        use light_sdk::cpi::{
            v2::LightSystemProgramCpi, InvokeLightSystemProgram, LightCpiInstruction,
        };

        /// Setup: Creates a compressed account
        pub fn create_account<'info>(
            ctx: Context<'_, '_, '_, 'info, GenericAnchorAccounts<'info>>,
            proof: ValidityProof,
            address_tree_info: PackedAddressTreeInfo,
            output_state_tree_index: u8,
            message: String,
        ) -> Result<()> {
            let light_cpi_accounts = CpiAccounts::new(
                ctx.accounts.signer.as_ref(),
                ctx.remaining_accounts,
                crate::LIGHT_CPI_SIGNER,
            );

            let address_tree_pubkey = address_tree_info
                .get_tree_pubkey(&light_cpi_accounts)
                .map_err(|_| ErrorCode::AccountNotEnoughKeys)?;

            if address_tree_pubkey.to_bytes() != ADDRESS_TREE_V2 {
                msg!("Invalid address tree");
                return Err(ProgramError::InvalidAccountData.into());
            }

            let (address, address_seed) = derive_address(
                &[b"message", ctx.accounts.signer.key().as_ref()],
                &address_tree_pubkey,
                &crate::ID,
            );

            let mut my_compressed_account = LightAccount::<MyCompressedAccount>::new_init(
                &crate::ID,
                Some(address),
                output_state_tree_index,
            );

            my_compressed_account.owner = ctx.accounts.signer.key();
            my_compressed_account.message = message.clone();

            msg!(
                "Created compressed account with message: {}",
                my_compressed_account.message
            );

            LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, proof)
                .with_light_account(my_compressed_account)?
                .with_new_addresses(&[address_tree_info.into_new_address_params_assigned_packed(address_seed, Some(0))])
                .invoke(light_cpi_accounts)?;

            Ok(())
        }

        /// Burns a compressed account permanently
        pub fn burn_account<'info>(
            ctx: Context<'_, '_, '_, 'info, GenericAnchorAccounts<'info>>,
            proof: ValidityProof,
            account_meta: CompressedAccountMetaBurn,
            current_message: String,
        ) -> Result<()> {
            let light_cpi_accounts = CpiAccounts::new(
                ctx.accounts.signer.as_ref(),
                ctx.remaining_accounts,
                crate::LIGHT_CPI_SIGNER,
            );

            let my_compressed_account = LightAccount::<MyCompressedAccount>::new_burn(
                &crate::ID,
                &account_meta,
                MyCompressedAccount {
                    owner: ctx.accounts.signer.key(),
                    message: current_message,
                },
            )?;

            msg!("Burning compressed account permanently");

            LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, proof)
                .with_light_account(my_compressed_account)?
                .invoke(light_cpi_accounts)?;

            Ok(())
        }
    }

    #[derive(Accounts)]
    pub struct GenericAnchorAccounts<'info> {
        #[account(mut)]
        pub signer: Signer<'info>,
    }

    #[event]
    #[derive(Clone, Debug, Default, LightDiscriminator)]
    pub struct MyCompressedAccount {
        pub owner: Pubkey,
        pub message: String,
    }```
    ````
  </Tab>

  <Tab title="Native Rust">
    <Info>
      Find the source code [here](https://github.com/Lightprotocol/program-examples/tree/main/basic-operations/native/programs/burn).
    </Info>

    ```rust theme={null}
    #![allow(unexpected_cfgs)]

    #[cfg(any(test, feature = "test-helpers"))]
    pub mod test_helpers;

    use borsh::{BorshDeserialize, BorshSerialize};
    use light_macros::pubkey;
    use light_sdk::{
        account::sha::LightAccount,
        address::v2::derive_address,
        cpi::{
            v2::{CpiAccounts, LightSystemProgramCpi},
            CpiSigner, InvokeLightSystemProgram, LightCpiInstruction,
        },
        derive_light_cpi_signer,
        error::LightSdkError,
        instruction::{account_meta::CompressedAccountMetaBurn, PackedAddressTreeInfo, ValidityProof},
        LightDiscriminator,
    };
    use light_sdk_types::ADDRESS_TREE_V2;
    use solana_program::{
        account_info::AccountInfo, entrypoint, program_error::ProgramError, pubkey::Pubkey,
    };

    pub const ID: Pubkey = pubkey!("CFWrQ8za2yT1xH8yBjYvsDUCWnBH7vXtyVJwqoX5FcNg");
    pub const LIGHT_CPI_SIGNER: CpiSigner = derive_light_cpi_signer!("CFWrQ8za2yT1xH8yBjYvsDUCWnBH7vXtyVJwqoX5FcNg");

    #[cfg(not(feature = "no-entrypoint"))]
    entrypoint!(process_instruction);

    #[derive(Debug, BorshSerialize, BorshDeserialize)]
    pub enum InstructionType {
        Create,
        Burn,
    }

    #[derive(Debug, BorshSerialize, BorshDeserialize)]
    pub struct CreateInstructionData {
        pub proof: ValidityProof,
        pub address_tree_info: PackedAddressTreeInfo,
        pub output_state_tree_index: u8,
        pub message: String,
    }

    #[derive(Debug, BorshSerialize, BorshDeserialize)]
    pub struct BurnInstructionData {
        pub proof: ValidityProof,
        pub account_meta: CompressedAccountMetaBurn,
        pub current_account: MyCompressedAccount,
    }

    #[derive(Debug, Default, Clone, BorshSerialize, BorshDeserialize, LightDiscriminator)]
    pub struct MyCompressedAccount {
        pub owner: Pubkey,
        pub message: String,
    }

    pub fn process_instruction(
        _program_id: &Pubkey,
        accounts: &[AccountInfo],
        instruction_data: &[u8],
    ) -> Result<(), ProgramError> {
        let (instruction_type, rest) = instruction_data
            .split_first()
            .ok_or(ProgramError::InvalidInstructionData)?;

        match InstructionType::try_from_slice(&[*instruction_type])
            .map_err(|_| ProgramError::InvalidInstructionData)?
        {
            InstructionType::Create => create(accounts, rest)?,
            InstructionType::Burn => burn(accounts, rest)?,
        }

        Ok(())
    }

    fn create(accounts: &[AccountInfo], instruction_data: &[u8]) -> Result<(), LightSdkError> {
        let instruction_data =
            CreateInstructionData::try_from_slice(instruction_data).map_err(|_| LightSdkError::Borsh)?;

        let signer = accounts.first().ok_or(ProgramError::NotEnoughAccountKeys)?;

        let light_cpi_accounts = CpiAccounts::new(signer, &accounts[1..], LIGHT_CPI_SIGNER);

        let address_tree_pubkey = instruction_data
            .address_tree_info
            .get_tree_pubkey(&light_cpi_accounts)
            .map_err(|_| ProgramError::NotEnoughAccountKeys)?;

        if address_tree_pubkey.to_bytes() != ADDRESS_TREE_V2 {
            solana_program::msg!("Invalid address tree");
            return Err(LightSdkError::ProgramError(ProgramError::InvalidAccountData));
        }

        let (address, address_seed) = derive_address(
            &[b"message", signer.key.as_ref()],
            &address_tree_pubkey,
            &ID,
        );

        let new_address_params = instruction_data
            .address_tree_info
            .into_new_address_params_assigned_packed(address_seed, Some(0));

        let mut my_compressed_account = LightAccount::<MyCompressedAccount>::new_init(
            &ID,
            Some(address),
            instruction_data.output_state_tree_index,
        );
        my_compressed_account.owner = *signer.key;
        my_compressed_account.message = instruction_data.message;

        LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, instruction_data.proof)
            .with_light_account(my_compressed_account)?
            .with_new_addresses(&[new_address_params])
            .invoke(light_cpi_accounts)?;

        Ok(())
    }

    fn burn(accounts: &[AccountInfo], instruction_data: &[u8]) -> Result<(), LightSdkError> {
        let instruction_data =
            BurnInstructionData::try_from_slice(instruction_data).map_err(|_| LightSdkError::Borsh)?;

        let (signer, remaining_accounts) = accounts
            .split_first()
            .ok_or(ProgramError::InvalidAccountData)?;

        let cpi_accounts = CpiAccounts::new(signer, remaining_accounts, LIGHT_CPI_SIGNER);

        let my_compressed_account = LightAccount::<MyCompressedAccount>::new_burn(
            &ID,  // Now the burn program owns the account since it created it
            &instruction_data.account_meta,
            instruction_data.current_account,
        )?;

        LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, instruction_data.proof)
            .with_light_account(my_compressed_account)?
            .invoke(cpi_accounts)?;

        Ok(())
    }
    ```
  </Tab>
</Tabs>

# Next Steps

<CardGroup>
  <Card title="Build a client for your program" icon="chevron-right" href="/client-library/client-guide" />

  <Card title="Learn how to create compressed accounts" icon="chevron-right" href="/compressed-pdas/guides/how-to-create-compressed-accounts" />
</CardGroup>


# Close Compressed Accounts
Source: https://www.zkcompression.com/compressed-pdas/guides/how-to-close-compressed-accounts

Guide to close compressed accounts in Solana programs with full code examples.

Compressed accounts are closed via CPI to the Light System Program.

Closing a compressed account

* consumes the existing account hash, and
* produces a new account hash with zero values to mark it as closed.
* A closed compressed account [can be reinitialized](/compressed-pdas/guides/how-to-reinitialize-compressed-accounts).

<Note>
  Find [full code examples at the end](/compressed-pdas/guides/how-to-close-compressed-accounts#full-code-example) for Anchor and native Rust.
</Note>

# Implementation Guide

This guide will cover the components of a Solana program that closes compressed accounts.
Here is the complete flow to close compressed accounts:

<div>
  <Frame>
    <img alt="" />
  </Frame>
</div>

<div>
  <Frame>
    <img alt="" />
  </Frame>
</div>

<Steps>
  <Step>
    ### Program Setup

    <Accordion title="Dependencies, Constants, Compressed Account">
      **Dependencies**

      Add dependencies to your program.

      <CodeGroup>
        ```toml Anchor theme={null}
        [dependencies]
        light-sdk = "0.19.0"
        anchor_lang = "0.31.1"
        ```

        ```toml Native Rust theme={null}
        [dependencies]
        light-sdk = "0.19.0"
        borsh = "0.10.0"
        solana-program = "2.2"
        ```
      </CodeGroup>

      * The `light-sdk` provides macros, wrappers and CPI interface to create and interact with compressed accounts.
      * Add the serialization library (`borsh` for native Rust, or use `AnchorSerialize`).

      **Constants**

      Set program address and derive the CPI authority PDA to call the Light System program.

      ```rust theme={null}
      declare_id!("rent4o4eAiMbxpkAM1HeXzks9YeGuz18SEgXEizVvPq");

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

      **`CPISigner`** is the configuration struct for CPI's to the Light System Program.

      * CPIs to the Light System program must be signed with a PDA derived by your program with the seed `b"authority"`
      * `derive_light_cpi_signer!` derives the CPI signer PDA for you at compile time.

      **Compressed Account**

      Define your compressed account struct.

      <CodeGroup>
        ```rust Anchor theme={null}
        #[event] // declared as event so that it is part of the idl.
        #[derive(
            Clone,
            Debug,
            Default,
            LightDiscriminator
        )]
        pub struct MyCompressedAccount {
            pub owner: Pubkey,
            pub message: String,
        }
        ```

        ```rust Native Rust theme={null}
        #[derive(
            Debug,
            Default,
            Clone,
            BorshSerialize,
            BorshDeserialize,
            LightDiscriminator,
        )]
        pub struct MyCompressedAccount {
            pub owner: Pubkey,
            pub message: String,
        }
        ```
      </CodeGroup>

      You derive

      * the standard traits (`Clone`, `Debug`, `Default`),
      * `borsh` or `AnchorSerialize` to serialize account data, and
      * `LightDiscriminator` to implements a unique type ID (8 bytes) to distinguish account types. The default compressed account layout enforces a discriminator in its *own field*, <Tooltip href="https://www.anchor-lang.com/">not the first 8 bytes of the data field</Tooltip>.

      <Info>
        The traits listed above are required for `LightAccount`. `LightAccount` wraps `MyCompressedAccount` in Step 3 to set the discriminator and create the compressed account's data.
      </Info>
    </Accordion>
  </Step>

  <Step>
    ### Instruction Data

    Define the instruction data with the following parameters:

    <Tabs>
      <Tab title="Anchor">
        ```rust theme={null}
        pub fn close_account<'info>(
            ctx: Context<'_, '_, '_, 'info, GenericAnchorAccounts<'info>>,
            proof: ValidityProof,
            account_meta: CompressedAccountMeta,
            current_message: String,
        ) -> Result<()>
        ```
      </Tab>

      <Tab title="Native Rust">
        ```rust theme={null}
        pub struct CloseInstructionData {
            pub proof: ValidityProof,
            pub account_meta: CompressedAccountMeta,
            pub current_message: String,
        }
        ```
      </Tab>
    </Tabs>

    1. **Validity Proof**

    * Define `proof` to include the proof that the account exists in the state tree.
    * Clients fetch a validity proof with `getValidityProof()` from an RPC provider that supports ZK Compression (Helius, Triton, ...).

    2. **Specify input state and output state tree (stores closed account hash)**

    * Define `account_meta: CompressedAccountMeta` to reference the existing account and specify the state tree to store the new hash with zero values:
      * `tree_info: PackedStateTreeInfo`: References the existing account hash in the state tree.
      * `address`: The account's derived address.
      * `output_state_tree_index` points to the state tree that will store the updated hash with a zero-byte hash to mark the account as closed.

    <Info>
      Clients fetch the current account with `getCompressedAccount()` and populate `CompressedAccountMeta` with the account's metadata.
    </Info>

    3. **Current data**

    * Define fields to include the current account data passed by the client.
    * This depends on your program logic. This example includes the `current_message` field.
  </Step>

  <Step>
    ### Close Compressed Account

    Load the compressed account and mark it as closed with `LightAccount::new_close()`.

    <Note>
      `new_close()`

      1. hashes the current account data as input state and
      2. marks the account for closure for the Light System Program.
    </Note>

    <Tabs>
      <Tab title="Anchor">
        ```rust theme={null}
        let my_compressed_account = LightAccount::<MyCompressedAccount>::new_close(
            &crate::ID,
            &account_meta,
            MyCompressedAccount {
                owner: ctx.accounts.signer.key(),
                message: current_message,
            },
        )?;
        ```
      </Tab>

      <Tab title="Native Rust">
        ```rust theme={null}
        let my_compressed_account = LightAccount::<MyCompressedAccount>::new_close(
            &ID,
            &instruction_data.account_meta,
            MyCompressedAccount {
                owner: *signer.key,
                message: instruction_data.current_message,
            },
        )?;
        ```
      </Tab>
    </Tabs>

    **Pass these parameters to `new_close()`:**

    * `&program_id`: The program's ID that owns the compressed account.
    * `&account_meta`: The `CompressedAccountMeta` from instruction data (*Step 2*) that identifies the existing account and specifies the output state tree.
    * Current account data: The existing account data. The SDK hashes this input state for verification by the Light System Program.
      * Anchor: Construct `MyCompressedAccount` with `ctx.accounts.signer.key()` and `current_message`
      * Native: Construct `MyCompressedAccount` with data from `instruction_data`

    **The SDK creates:**

    * A `LightAccount` wrapper similar to Anchor's `Account` that marks the account for closure.

    <Info>
      `new_close()` hashes the input state and marks the account for closure. The Light System Program creates output state with zero values:

      * a zero discriminator (`0u8; 8`) removes type identification of the account,
      * the output contains zeroes as data hash that indicates no data content, and
      * the data field contains an empty vector, instead of serialized account fields.
    </Info>
  </Step>

  <Step>
    ### Light System Program CPI

    Invoke the Light System Program to close the compressed account. This empty account can be reinitialized with `LightAccount::new_empty()`.

    <Note>
      The Light System Program

      * validates the account exists in state tree,
      * nullifies the existing account hash, and
      * appends the new account hash with zero values to the state tree to mark it as closed.
    </Note>

    <Tabs>
      <Tab title="Anchor">
        ```rust theme={null}
        let light_cpi_accounts = CpiAccounts::new(
            ctx.accounts.signer.as_ref(),
            ctx.remaining_accounts,
            crate::LIGHT_CPI_SIGNER,
        );

        LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, proof)
            .with_light_account(my_compressed_account)?
            .invoke(light_cpi_accounts)?;
        ```

        **Set up `CpiAccounts::new()`:**

        `CpiAccounts::new()` parses accounts for the CPI call to Light System Program.

        **Pass these parameters:**

        * `ctx.accounts.signer.as_ref()`: the transaction signer
        * `ctx.remaining_accounts`: Slice with `[system_accounts, ...packed_tree_accounts]`. The client builds this with `PackedAccounts` and passes it to the instruction.
        * `&LIGHT_CPI_SIGNER`: Your program's CPI signer PDA defined in Constants.
      </Tab>

      <Tab title="Native Rust">
        ```rust theme={null}
        let (signer, remaining_accounts) = accounts
            .split_first();

        let cpi_accounts = CpiAccounts::new(
            signer,
            remaining_accounts,
            LIGHT_CPI_SIGNER
        );

        LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, instruction_data.proof)
            .with_light_account(my_compressed_account)?
            .invoke(cpi_accounts)?;
        ```

        **Set up `CpiAccounts::new()`:**

        `CpiAccounts::new()` parses accounts for the CPI call to Light System Program.

        **Pass these parameters:**

        * `signer`: account that signs and pays for the transaction
        * `remaining_accounts`: Slice with `[system_accounts, ...packed_tree_accounts]`. The client builds this with `PackedAccounts`.
          * `split_first()` extracts the fee payer from the accounts array to separate it from the Light System Program accounts needed for the CPI.
        * `&LIGHT_CPI_SIGNER`: Your program's CPI signer PDA defined in Constants.
      </Tab>
    </Tabs>

    <Accordion title="System Accounts List">
      <table>
        <colgroup>
          <col />

          <col />

          <col />
        </colgroup>

        <thead>
          <tr>
            <th />

            <th />

            <th />
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>1</td>
            <td><strong><Tooltip href="https://solscan.io/account/SySTEM1eSU2p4BGQfQpimFEWWSC1XDFeun3Nqzz3rT7">Light System Program</Tooltip></strong></td>
            <td>Verifies validity proofs, compressed account ownership checks, and CPIs the Account Compression Program to update tree accounts.</td>
          </tr>

          <tr>
            <td>2</td>
            <td><strong>CPI Signer</strong></td>

            <td>
              * PDA to sign CPI calls from your program to the Light System Program.<br />
              * Verified by the Light System Program during CPI.<br />
              * Derived from your program ID.
            </td>
          </tr>

          <tr>
            <td>3</td>
            <td><strong>Registered Program PDA</strong></td>
            <td>Provides access control to the Account Compression Program.</td>
          </tr>

          <tr>
            <td>4</td>
            <td><strong><Tooltip href="https://solscan.io/account/HZH7qSLcpAeDqCopVU4e5XkhT9j3JFsQiq8CmruY3aru">Account Compression Authority</Tooltip></strong></td>
            <td>Signs CPI calls from the Light System Program to the Account Compression Program.</td>
          </tr>

          <tr>
            <td>5</td>
            <td><strong><Tooltip href="https://solscan.io/account/compr6CUsB5m2jS4Y3831ztGSTnDpnKJTKS95d64XVq">Account Compression Program</Tooltip></strong></td>

            <td>
              * Writes to state and address tree accounts.<br />
              * Clients and the Account Compression Program do not interact directly — handled internally.
            </td>
          </tr>

          <tr>
            <td>6</td>
            <td><strong><Tooltip href="https://solscan.io/account/11111111111111111111111111111111">System Program</Tooltip></strong></td>
            <td>Solana System Program used to transfer lamports.</td>
          </tr>
        </tbody>
      </table>
    </Accordion>

    **Build the CPI instruction**:

    * `new_cpi()` initializes the CPI instruction with the `proof` to prove the compressed account exists in the state tree *- defined in the Instruction Data (Step 2).*
    * `with_light_account` adds the `LightAccount` wrapper configured to close the account with the zero values *- defined in Step 3*.
    * `invoke()` calls the Light System Program with `CpiAccounts`.
  </Step>
</Steps>

# Full Code Example

The example programs below implement all steps from this guide.
Make sure you have your developer environment set up first.

<Accordion title="Setup">
  **Install Solana CLI:**

  ```bash theme={null}
  sh -c "$(curl -sSfL https://release.solana.com/v2.2.15/install)"
  ```

  **Install Anchor CLI:**

  ```bash theme={null}
  cargo install --git https://github.com/coral-xyz/anchor avm --force
  avm install latest
  avm use latest
  ```

  **Install the Light CLI:**

  <Tabs>
    <Tab title="npm">
      ```bash theme={null}
      npm install -g @lightprotocol/zk-compression-cli@beta
      ```
    </Tab>

    <Tab title="yarn">
      ```bash theme={null}
      yarn global add @lightprotocol/zk-compression-cli@beta
      ```
    </Tab>

    <Tab title="pnpm">
      ```bash theme={null}
      pnpm add -g @lightprotocol/zk-compression-cli@beta
      ```
    </Tab>
  </Tabs>

  **Verify installation:**

  ```bash theme={null}
  light --version
  ```
</Accordion>

<Warning>
  For help with debugging, see the [Error Cheatsheet](../../resources/error-cheatsheet/).
</Warning>

<Tabs>
  <Tab title="Anchor">
    <Info>
      Find the source code [here](https://github.com/Lightprotocol/program-examples/tree/main/basic-operations/anchor/close).
    </Info>

    ````rust theme={null}
    #![allow(unexpected_cfgs)]
    #![allow(deprecated)]

    use anchor_lang::{prelude::*, AnchorDeserialize, AnchorSerialize};
    use light_sdk::{
        account::LightAccount,
        address::v2::derive_address,
        cpi::{v2::CpiAccounts, CpiSigner},
        derive_light_cpi_signer,
        instruction::{account_meta::CompressedAccountMeta, PackedAddressTreeInfo, ValidityProof},
        LightDiscriminator,
    };
    use light_sdk_types::ADDRESS_TREE_V2;

    declare_id!("DzQ3za3DVCpXkXhmZVSrNchwbbSsJXmi9MBc8v5tvZuQ");

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

    #[program]
    pub mod close {

        use super::*;
        use light_sdk::cpi::{
            v2::LightSystemProgramCpi, InvokeLightSystemProgram, LightCpiInstruction,
        };

        /// Setup: Create a compressed account
        pub fn create_account<'info>(
            ctx: Context<'_, '_, '_, 'info, GenericAnchorAccounts<'info>>,
            proof: ValidityProof,
            address_tree_info: PackedAddressTreeInfo,
            output_state_tree_index: u8,
            message: String,
        ) -> Result<()> {
            let light_cpi_accounts = CpiAccounts::new(
                ctx.accounts.signer.as_ref(),
                ctx.remaining_accounts,
                crate::LIGHT_CPI_SIGNER,
            );

            let address_tree_pubkey = address_tree_info
                .get_tree_pubkey(&light_cpi_accounts)
                .map_err(|_| ErrorCode::AccountNotEnoughKeys)?;

            if address_tree_pubkey.to_bytes() != ADDRESS_TREE_V2 {
                msg!("Invalid address tree");
                return Err(ProgramError::InvalidAccountData.into());
            }

            let (address, address_seed) = derive_address(
                &[b"message", ctx.accounts.signer.key().as_ref()],
                &address_tree_pubkey,
                &crate::ID,
            );

            let mut my_compressed_account = LightAccount::<MyCompressedAccount>::new_init(
                &crate::ID,
                Some(address),
                output_state_tree_index,
            );

            my_compressed_account.owner = ctx.accounts.signer.key();
            my_compressed_account.message = message.clone();

            msg!(
                "Created compressed account with message: {}",
                my_compressed_account.message
            );

            LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, proof)
                .with_light_account(my_compressed_account)?
                .with_new_addresses(&[address_tree_info.into_new_address_params_assigned_packed(address_seed, Some(0))])
                .invoke(light_cpi_accounts)?;

            Ok(())
        }

        /// Close compressed account
        pub fn close_account<'info>(
            ctx: Context<'_, '_, '_, 'info, GenericAnchorAccounts<'info>>,
            proof: ValidityProof,
            account_meta: CompressedAccountMeta,
            current_message: String,
        ) -> Result<()> {
            let light_cpi_accounts = CpiAccounts::new(
                ctx.accounts.signer.as_ref(),
                ctx.remaining_accounts,
                crate::LIGHT_CPI_SIGNER,
            );

            let my_compressed_account = LightAccount::<MyCompressedAccount>::new_close(
                &crate::ID,
                &account_meta,
                MyCompressedAccount {
                    owner: ctx.accounts.signer.key(),
                    message: current_message,
                },
            )?;

            msg!("Close compressed account.");

            LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, proof)
                .with_light_account(my_compressed_account)?
                .invoke(light_cpi_accounts)?;

            Ok(())
        }
    }

    #[derive(Accounts)]
    pub struct GenericAnchorAccounts<'info> {
        #[account(mut)]
        pub signer: Signer<'info>,
    }

    #[event]
    #[derive(Clone, Debug, Default, LightDiscriminator)]
    pub struct MyCompressedAccount {
        pub owner: Pubkey,
        pub message: String,
    }```
    ````
  </Tab>

  <Tab title="Native Rust">
    <Info>
      Find the source code [here](https://github.com/Lightprotocol/program-examples/tree/main/basic-operations/native/programs/close).
    </Info>

    ```rust theme={null}
    #![allow(unexpected_cfgs)]

    #[cfg(any(test, feature = "test-helpers"))]
    pub mod test_helpers;

    use borsh::{BorshDeserialize, BorshSerialize};
    use light_macros::pubkey;
    use light_sdk::{
        account::sha::LightAccount,
        address::v2::derive_address,
        cpi::{
            v2::{CpiAccounts, LightSystemProgramCpi},
            CpiSigner, InvokeLightSystemProgram, LightCpiInstruction,
        },
        derive_light_cpi_signer,
        error::LightSdkError,
        instruction::{account_meta::CompressedAccountMeta, PackedAddressTreeInfo, ValidityProof},
        LightDiscriminator,
    };
    use light_sdk_types::ADDRESS_TREE_V2;
    use solana_program::{
        account_info::AccountInfo, entrypoint, program_error::ProgramError, pubkey::Pubkey,
    };

    pub const ID: Pubkey = pubkey!("NLusgr6vsEjYDvF6nDxpdrhMUxUC19s4XoyshSrGFVN");
    pub const LIGHT_CPI_SIGNER: CpiSigner = derive_light_cpi_signer!("NLusgr6vsEjYDvF6nDxpdrhMUxUC19s4XoyshSrGFVN");

    #[cfg(not(feature = "no-entrypoint"))]
    entrypoint!(process_instruction);

    #[derive(Debug, BorshSerialize, BorshDeserialize)]
    pub enum InstructionType {
        Create,
        Close,
    }

    #[derive(Debug, BorshSerialize, BorshDeserialize)]
    pub struct CreateInstructionData {
        pub proof: ValidityProof,
        pub address_tree_info: PackedAddressTreeInfo,
        pub output_state_tree_index: u8,
        pub message: String,
    }

    #[derive(Debug, BorshSerialize, BorshDeserialize)]
    pub struct CloseInstructionData {
        pub proof: ValidityProof,
        pub account_meta: CompressedAccountMeta,
        pub current_message: String,
    }

    #[derive(Debug, Default, Clone, BorshSerialize, BorshDeserialize, LightDiscriminator)]
    pub struct MyCompressedAccount {
        pub owner: Pubkey,
        pub message: String,
    }

    pub fn process_instruction(
        _program_id: &Pubkey,
        accounts: &[AccountInfo],
        instruction_data: &[u8],
    ) -> Result<(), ProgramError> {
        let (instruction_type, rest) = instruction_data
            .split_first()
            .ok_or(ProgramError::InvalidInstructionData)?;

        match InstructionType::try_from_slice(&[*instruction_type])
            .map_err(|_| ProgramError::InvalidInstructionData)?
        {
            InstructionType::Create => create(accounts, rest)?,
            InstructionType::Close => close(accounts, rest)?,
        }

        Ok(())
    }

    fn create(accounts: &[AccountInfo], instruction_data: &[u8]) -> Result<(), LightSdkError> {
        let instruction_data =
            CreateInstructionData::try_from_slice(instruction_data).map_err(|_| LightSdkError::Borsh)?;

        let signer = accounts.first().ok_or(ProgramError::NotEnoughAccountKeys)?;

        let light_cpi_accounts = CpiAccounts::new(signer, &accounts[1..], LIGHT_CPI_SIGNER);

        let address_tree_pubkey = instruction_data
            .address_tree_info
            .get_tree_pubkey(&light_cpi_accounts)
            .map_err(|_| ProgramError::NotEnoughAccountKeys)?;

        if address_tree_pubkey.to_bytes() != ADDRESS_TREE_V2 {
            solana_program::msg!("Invalid address tree");
            return Err(LightSdkError::ProgramError(ProgramError::InvalidAccountData));
        }

        let (address, address_seed) = derive_address(
            &[b"message", signer.key.as_ref()],
            &address_tree_pubkey,
            &ID,
        );

        let new_address_params = instruction_data
            .address_tree_info
            .into_new_address_params_assigned_packed(address_seed, Some(0));

        let mut my_compressed_account = LightAccount::<MyCompressedAccount>::new_init(
            &ID,
            Some(address),
            instruction_data.output_state_tree_index,
        );
        my_compressed_account.owner = *signer.key;
        my_compressed_account.message = instruction_data.message;

        LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, instruction_data.proof)
            .with_light_account(my_compressed_account)?
            .with_new_addresses(&[new_address_params])
            .invoke(light_cpi_accounts)?;

        Ok(())
    }

    fn close(accounts: &[AccountInfo], instruction_data: &[u8]) -> Result<(), LightSdkError> {
        let instruction_data =
            CloseInstructionData::try_from_slice(instruction_data).map_err(|_| LightSdkError::Borsh)?;

        let (signer, remaining_accounts) = accounts
            .split_first()
            .ok_or(ProgramError::InvalidAccountData)?;

        let cpi_accounts = CpiAccounts::new(signer, remaining_accounts, LIGHT_CPI_SIGNER);

        let my_compressed_account = LightAccount::<MyCompressedAccount>::new_close(
            &ID,
            &instruction_data.account_meta,
            MyCompressedAccount {
                owner: *signer.key,
                message: instruction_data.current_message,
            },
        )?;

        LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, instruction_data.proof)
            .with_light_account(my_compressed_account)?
            .invoke(cpi_accounts)?;

        Ok(())
    }
    ```
  </Tab>
</Tabs>

# Next Steps

<CardGroup>
  <Card title="Build a client for your program" icon="chevron-right" href="/client-library/client-guide" />

  <Card title="Learn how to reinitialize compressed accounts" icon="chevron-right" href="/compressed-pdas/guides/how-to-reinitialize-compressed-accounts" />
</CardGroup>


# Create Compressed Accounts
Source: https://www.zkcompression.com/compressed-pdas/guides/how-to-create-compressed-accounts

Guide to create compressed accounts in Solana programs with full code examples.

Compressed accounts and addresses are created via CPI to the Light System Program.

* Compressed and regular Solana accounts share the same functionality and are fully composable.
* A compressed account has two identifiers: the account hash and its address (optional). In comparison, regular Solana accounts are identified by their address.
* The account hash is not persistent and changes with every write to the account.
* For Solana PDA like behavior your compressed account needs an address as persistent identifier.\
  Fungible state like [compressed token accounts](/compressed-tokens/guides/create-compressed-token-accounts) do not need addresses.

<Note>
  Find [full code examples at the end](/compressed-pdas/guides/how-to-create-compressed-accounts#full-code-example) for Anchor and native Rust.
</Note>

# Implementation Guide

This guide will cover the components of a Solana program that creates compressed accounts.\
Here is the complete flow:

<div>
  <Frame>
    <img alt="" />
  </Frame>
</div>

<div>
  <Frame>
    <img alt="" />
  </Frame>
</div>

<Steps>
  <Step>
    ### Dependencies

    Add dependencies to your program.

    <CodeGroup>
      ```toml Anchor theme={null}
      [dependencies]
      light-sdk = "0.16.0"
      anchor_lang = "0.31.1"
      ```

      ```toml Native Rust theme={null}
      [dependencies]
      light-sdk = "0.16.0"
      borsh = "0.10.0"
      solana-program = "2.2"
      ```
    </CodeGroup>

    * The `light-sdk` provides macros, wrappers and CPI interface to create and interact with compressed accounts.
    * Add the serialization library (`borsh` for native Rust, or use `AnchorSerialize`).
  </Step>

  <Step>
    ### Constants

    Set program address and derive the CPI authority PDA to call the Light System program.

    <CodeGroup>
      ```rust Anchor theme={null}
      declare_id!("rent4o4eAiMbxpkAM1HeXzks9YeGuz18SEgXEizVvPq");

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

      ```rust Native Rust theme={null}
      pub const ID: Pubkey = pubkey!("rent4o4eAiMbxpkAM1HeXzks9YeGuz18SEgXEizVvPq");
      pub const LIGHT_CPI_SIGNER: CpiSigner =
          derive_light_cpi_signer!("rent4o4eAiMbxpkAM1HeXzks9YeGuz18SEgXEizVvPq");
      ```
    </CodeGroup>

    **`CPISigner`** is the configuration struct for CPIs to the Light System Program.

    * CPI to the Light System program must be signed with a PDA derived by your program with the seed `b"authority"`
    * `derive_light_cpi_signer!` derives the CPI signer PDA for you at compile time.
  </Step>

  <Step>
    ### Compressed Account

    <CodeGroup>
      ```rust Anchor theme={null}
      #[event] // declared as event so that it is part of the idl.
      #[derive(
          Clone,
          Debug,
          Default,
          LightDiscriminator
      )]
      pub struct MyCompressedAccount {
          pub owner: Pubkey,
          pub message: String,
      }
      ```

      ```rust Native Rust theme={null}
      #[derive(
          Clone,
          Debug,
          Default,
          BorshSerialize,
          BorshDeserialize,
          LightDiscriminator
      )]
      pub struct MyCompressedAccount {
          pub owner: Pubkey,
          pub message: String,
      }
      ```
    </CodeGroup>

    Define your compressed account struct and derive

    * the standard traits (`Clone`, `Debug`, `Default`),
    * `borsh` or `AnchorSerialize` to serialize account data, and
    * `LightDiscriminator` to implements a unique type ID (8 bytes) to distinguish account types. The default compressed account layout enforces a discriminator in its *own field*, <Tooltip href="https://www.anchor-lang.com/">not the first 8 bytes of the data field</Tooltip>.

    <Info>
      The traits listed above are required for `LightAccount`. `LightAccount` wraps `my-compressed-account` in Step 7 to set the discriminator and create the compressed account's data.
    </Info>
  </Step>

  <Step>
    ### Instruction Data

    Define the instruction data with the following parameters:

    <Tabs>
      <Tab title="Anchor">
        Anchor handles instruction deserialization automatically. Pass the parameters directly to the instruction function:

        ```rust theme={null}
        pub fn create_account<'info>(
            ctx: Context<'_, '_, '_, 'info, GenericAnchorAccounts<'info>>,
            proof: ValidityProof,
            address_tree_info: PackedAddressTreeInfo,
            output_state_tree_index: u8,
            message: String,
        ) -> Result<()>
        ```
      </Tab>

      <Tab title="Native Rust">
        Define an instruction data struct that will be deserialized from the instruction data:

        ```rust Native Rust theme={null}
        pub struct CreateInstructionData {
            pub proof: ValidityProof,
            pub address_tree_info: PackedAddressTreeInfo,
            pub output_state_tree_index: u8,
            pub message: String,
        }
        ```
      </Tab>
    </Tabs>

    1. **Validity Proof**

    * Define `proof` to include the proof that the address does not exist yet in the specified address tree.
    * Clients fetch a validity proof with `getValidityProof()` from an RPC provider that supports ZK Compression (Helius, Triton, ...).

    2. **Specify Merkle trees to store address and account hash**

    * Define `address_tree_info: PackedAddressTreeInfo` to reference the address tree account used to derive the address in the next step.
    * Define `output_state_tree_index` to reference the state tree account that stores the compressed account hash.

    <Info>
      Clients pack accounts into the accounts array to reduce transaction size. Packed structs like `PackedAddressTreeInfo` contain account indices (u8) instead of 32 byte pubkeys. The indices point to the account in the accounts array to retrieve the public key and other metadata.
    </Info>

    3. **Initial account data**

    * Define fields for your program logic. Clients pass the initial values.
    * This example includes the `message` field to define the initial state of the account.
  </Step>

  <Step>
    ### Derive Address

    Derive the address as a persistent unique identifier for the compressed account.

    <CodeGroup>
      ```rust Anchor theme={null}
      let (address, address_seed) = derive_address(
          &[b"message", ctx.accounts.signer.key().as_ref()],
          &address_tree_info
              .get_tree_pubkey(&light_cpi_accounts)
          &crate::ID,
      );
      ```

      ```rust Native Rust theme={null}
      let (address, address_seed) = derive_address(
          &[b"message", signer.key.as_ref()],
          &instruction_data
              .address_tree_info
              .get_tree_pubkey(&light_cpi_accounts)
          &ID,
      );
      ```
    </CodeGroup>

    **Pass these parameters to `derive_address()`:**

    * `&custom_seeds`: Predefined inputs, such as strings, numbers or other account addresses. This example uses `b"message"` and the signer's pubkey.
    * `&address_tree_pubkey`: The pubkey of the address tree where the address will be created.
      * Retrieved by calling `get_tree_pubkey()` on `address_tree_info`, which unpacks the index from the accounts array.
      * This parameter ensures an address is unique to an address tree. Different trees produce different addresses from identical seeds.
    * `&program_id`: Your program's ID.

    **The SDK returns:**

    * `address`: The derived address for the compressed account.
    * `address_seed`: Pass this to the Light System Program CPI in *Step 8* to create the address.
  </Step>

  <Step>
    ### Address Tree Check (optional)

    Ensure global uniqueness of an address by verifying that the address tree pubkey matches the program's tree constant.

    <Info>
      Every address is unique, but the same seeds can be used to create different addresses in different address trees. To enforce that a compressed PDA can only be created once with the same seed, you must check the address tree pubkey.
    </Info>

    ```rust theme={null}
    let address_tree = light_cpi_accounts.tree_pubkeys().unwrap()
        [address_tree_info.address_merkle_tree_pubkey_index as usize];

    if address_tree != light_sdk::constants::ADDRESS_TREE_V2 {
        return Err(ProgramError::InvalidAccountData.into());
    }
    ```
  </Step>

  <Step>
    ### Initialize Compressed Account

    Initialize the compressed account struct with `LightAccount::new_init()`.

    <Note>
      `new_init()` creates a `LightAccount` instance similar to anchor `Account` and lets your program define the initial account data.
    </Note>

    <CodeGroup>
      ```rust Anchor theme={null}
      let mut my_compressed_account = LightAccount::<MyCompressedAccount>::new_init(
          &crate::ID,
          Some(address),
          output_state_tree_index,
      );

      my_compressed_account.owner = ctx.accounts.signer.key();
      my_compressed_account.message = message.clone();
      ```

      ```rust Native Rust theme={null}
      let mut my_compressed_account = LightAccount::<MyCompressedAccount>::new_init(
          &ID,
          Some(address),
          instruction_data.output_state_tree_index,
      );
      my_compressed_account.owner = *signer.key;
      my_compressed_account.message = instruction_data.message;
      ```
    </CodeGroup>

    **Pass these parameters to `new_init()`:**

    * `&owner`: The program's ID that owns the compressed account.
    * `Some(address)`: The derived address from *Step 5*. Pass `None` for accounts without addresses.
    * `output_state_tree_index`: References the state tree account that will store the updated account hash, defined in instruction data (*Step 4*)

    **The SDK creates:**

    * A `LightAccount` wrapper similar to Anchor's `Account.`
    * `new_init()` lets the program set the initial data. This example sets:
      * `owner` to the signer's pubkey
      * `message` to an arbitrary string
  </Step>

  <Step>
    ### Light System Program CPI

    Invoke the Light System Program to create the compressed account and its address.

    <Note>
      The Light System Program

      * verifies the validity proof against the address tree's Merkle root,
      * inserts the address into the address tree, and
      * appends the new account hash to the state tree.
    </Note>

    <Tabs>
      <Tab title="Anchor">
        ```rust theme={null}
        let light_cpi_accounts = CpiAccounts::new(
            ctx.accounts.signer.as_ref(),
            ctx.remaining_accounts,
            crate::LIGHT_CPI_SIGNER,
        );

        let new_address_params = address_tree_info
            .into_new_address_params_assigned_packed(address_seed, Some(0));

        LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, proof)
            .with_light_account(my_compressed_account)?
            .with_new_addresses(&[new_address_params])
            .invoke(light_cpi_accounts)?;
        ```

        **Set up `CpiAccounts::new()`:**

        `CpiAccounts::new()` parses accounts for the CPI call to Light System Program.

        **Pass these parameters:**

        * `ctx.accounts.signer.as_ref()`: the transaction signer
        * `ctx.remaining_accounts`: Slice with `[system_accounts, ...packed_tree_accounts]`. The client builds this with `PackedAccounts` and passes it to the instruction.
        * `&LIGHT_CPI_SIGNER`: Your program's CPI signer PDA defined in Constants.
      </Tab>

      <Tab title="Native Rust">
        ```rust theme={null}
        let signer = accounts.first();

        let light_cpi_accounts = CpiAccounts::new(
            signer,
            &accounts[1..],
            LIGHT_CPI_SIGNER
        );

        let new_address_params = instruction_data
            .address_tree_info
            .into_new_address_params_assigned_packed(address_seed, Some(0));

        LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, instruction_data.proof)
            .with_light_account(my_compressed_account)?
            .with_new_addresses(&[new_address_params])
            .invoke(light_cpi_accounts)?;
        ```

        **Set up `CpiAccounts::new()`:**

        `CpiAccounts::new()` parses accounts for the CPI call to Light System Program.

        **Pass these parameters:**

        * `signer`: account that signs and pays for the transaction
        * `&accounts[1..]`: Slice with `[system_accounts, ...packed_tree_accounts]`. The client builds this with `PackedAccounts`.
        * `&LIGHT_CPI_SIGNER`: Your program's CPI signer PDA defined in Constants.
      </Tab>
    </Tabs>

    <Accordion title="System Accounts List">
      <table>
        <colgroup>
          <col />

          <col />

          <col />
        </colgroup>

        <thead>
          <tr>
            <th />

            <th />

            <th />
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>1</td>
            <td><strong><Tooltip href="https://solscan.io/account/SySTEM1eSU2p4BGQfQpimFEWWSC1XDFeun3Nqzz3rT7">Light System Program</Tooltip></strong></td>
            <td>Verifies validity proofs, compressed account ownership checks, and CPIs the Account Compression Program to update tree accounts.</td>
          </tr>

          <tr>
            <td>2</td>
            <td><strong>CPI Signer</strong></td>

            <td>
              * PDA to sign CPI calls from your program to the Light System Program.<br />
              * Verified by the Light System Program during CPI.<br />
              * Derived from your program ID.
            </td>
          </tr>

          <tr>
            <td>3</td>
            <td><strong>Registered Program PDA</strong></td>
            <td>Provides access control to the Account Compression Program.</td>
          </tr>

          <tr>
            <td>4</td>
            <td><strong><Tooltip href="https://solscan.io/account/HZH7qSLcpAeDqCopVU4e5XkhT9j3JFsQiq8CmruY3aru">Account Compression Authority</Tooltip></strong></td>
            <td>Signs CPI calls from the Light System Program to the Account Compression Program.</td>
          </tr>

          <tr>
            <td>5</td>
            <td><strong><Tooltip href="https://solscan.io/account/compr6CUsB5m2jS4Y3831ztGSTnDpnKJTKS95d64XVq">Account Compression Program</Tooltip></strong></td>

            <td>
              * Writes to state and address tree accounts.<br />
              * Clients and the Account Compression Program do not interact directly — handled internally.
            </td>
          </tr>

          <tr>
            <td>6</td>
            <td><strong><Tooltip href="https://solscan.io/account/11111111111111111111111111111111">System Program</Tooltip></strong></td>
            <td>Solana System Program used to transfer lamports.</td>
          </tr>
        </tbody>
      </table>
    </Accordion>

    **Build the CPI instruction**:

    `new_cpi()` initializes the CPI instruction with the `proof` to prove that an address does not exist yet in the specified address tree *- defined in the Instruction Data (Step 4).*

    * `with_light_account` adds the `LightAccount` with the initial compressed account data to the CPI instruction *- defined in Step 7*.
    * `with_new_addresses` adds the `address_seed` and metadata to the CPI instruction data - returned by `derive_address` *in Step 5*.
    * `invoke(light_cpi_accounts)` calls the Light System Program with `CpiAccounts.`
  </Step>
</Steps>

# Full Code Example

The example programs below implement all steps from this guide.

<Accordion title="Setup">
  **Install Solana CLI:**

  ```bash theme={null}
  sh -c "$(curl -sSfL https://release.solana.com/v2.2.15/install)"
  ```

  **Install Anchor CLI:**

  ```bash theme={null}
  cargo install --git https://github.com/coral-xyz/anchor avm --force
  avm install latest
  avm use latest
  ```

  **Install the Light CLI:**

  <Tabs>
    <Tab title="npm">
      ```bash theme={null}
      npm install -g @lightprotocol/zk-compression-cli@beta
      ```
    </Tab>

    <Tab title="yarn">
      ```bash theme={null}
      yarn global add @lightprotocol/zk-compression-cli@beta
      ```
    </Tab>

    <Tab title="pnpm">
      ```bash theme={null}
      pnpm add -g @lightprotocol/zk-compression-cli@beta
      ```
    </Tab>
  </Tabs>

  **Verify installation:**

  ```bash theme={null}
  light --version
  ```
</Accordion>

<Warning>
  For help with debugging, see the [Error Cheatsheet](../../resources/error-cheatsheet/).
</Warning>

<Tabs>
  <Tab title="Anchor">
    <Info>
      Find the source code [here](https://github.com/Lightprotocol/program-examples/tree/main/basic-operations/anchor/create).
    </Info>

    ```rust theme={null}
    #![allow(unexpected_cfgs)]
    #![allow(deprecated)]

    use anchor_lang::{prelude::*, AnchorDeserialize, AnchorSerialize};
    use light_sdk::{
        account::LightAccount,
        address::v2::derive_address,
        cpi::{v2::CpiAccounts, CpiSigner},
        derive_light_cpi_signer,
        instruction::{PackedAddressTreeInfo, ValidityProof},
        LightDiscriminator,
    };
    use light_sdk_types::ADDRESS_TREE_V2;

    declare_id!("Hps5oaKdYWqjVZJnAxUE1uwbozwEgZZGCRA57p2wdqcS");

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

    #[program]
    pub mod create {

        use super::*;
        use light_sdk::cpi::{
            v2::LightSystemProgramCpi, InvokeLightSystemProgram, LightCpiInstruction,
        };

        /// Creates a new compressed account
        pub fn create_account<'info>(
            ctx: Context<'_, '_, '_, 'info, GenericAnchorAccounts<'info>>,
            proof: ValidityProof,
            address_tree_info: PackedAddressTreeInfo,
            output_state_tree_index: u8,
            message: String,
        ) -> Result<()> {
            let light_cpi_accounts = CpiAccounts::new(
                ctx.accounts.signer.as_ref(),
                ctx.remaining_accounts,
                crate::LIGHT_CPI_SIGNER,
            );

            let address_tree_pubkey = address_tree_info
                .get_tree_pubkey(&light_cpi_accounts)
                .map_err(|_| ErrorCode::AccountNotEnoughKeys)?;

            if address_tree_pubkey.to_bytes() != ADDRESS_TREE_V2 {
                msg!("Invalid address tree");
                return Err(ProgramError::InvalidAccountData.into());
            }

            let (address, address_seed) = derive_address(
                &[b"message", ctx.accounts.signer.key().as_ref()],
                &address_tree_pubkey,
                &crate::ID,
            );

            let mut my_compressed_account = LightAccount::<MyCompressedAccount>::new_init(
                &crate::ID,
                Some(address),
                output_state_tree_index,
            );

            my_compressed_account.owner = ctx.accounts.signer.key();
            my_compressed_account.message = message.clone();

            msg!(
                "Created compressed account with message: {}",
                my_compressed_account.message
            );

            LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, proof)
                .with_light_account(my_compressed_account)?
                .with_new_addresses(&[address_tree_info.into_new_address_params_assigned_packed(address_seed, Some(0))])
                .invoke(light_cpi_accounts)?;

            Ok(())
        }
    }

    #[derive(Accounts)]
    pub struct GenericAnchorAccounts<'info> {
        #[account(mut)]
        pub signer: Signer<'info>,
    }

    // declared as event so that it is part of the idl.
    #[event]
    #[derive(Clone, Debug, Default, LightDiscriminator)]
    pub struct MyCompressedAccount {
        pub owner: Pubkey,
        pub message: String,
    }
    ```
  </Tab>

  <Tab title="Native Rust">
    <Info>
      Find the source code [here](https://github.com/Lightprotocol/program-examples/tree/main/basic-operations/native/programs/create).
    </Info>

    ```rust theme={null}
    #![allow(unexpected_cfgs)]

    #[cfg(any(test, feature = "test-helpers"))]
    pub mod test_helpers;

    use borsh::{BorshDeserialize, BorshSerialize};
    use light_macros::pubkey;
    use light_sdk::{
        account::sha::LightAccount,
        address::v2::derive_address,
        cpi::{
            v2::{CpiAccounts, LightSystemProgramCpi},
            CpiSigner, InvokeLightSystemProgram, LightCpiInstruction,
        },
        derive_light_cpi_signer,
        error::LightSdkError,
        instruction::{PackedAddressTreeInfo, ValidityProof},
        LightDiscriminator,
    };
    use light_sdk_types::ADDRESS_TREE_V2;
    use solana_program::{
        account_info::AccountInfo, entrypoint, program_error::ProgramError, pubkey::Pubkey,
    };

    pub const ID: Pubkey = pubkey!("rent4o4eAiMbxpkAM1HeXzks9YeGuz18SEgXEizVvPq");
    pub const LIGHT_CPI_SIGNER: CpiSigner =
        derive_light_cpi_signer!("rent4o4eAiMbxpkAM1HeXzks9YeGuz18SEgXEizVvPq");

    entrypoint!(process_instruction);

    #[repr(u8)]
    #[derive(Debug)]
    pub enum InstructionType {
        Create = 0,
    }

    impl TryFrom<u8> for InstructionType {
        type Error = LightSdkError;

        fn try_from(value: u8) -> Result<Self, Self::Error> {
            match value {
                0 => Ok(InstructionType::Create),
                _ => panic!("Invalid instruction discriminator."),
            }
        }
    }

    #[derive(Debug, Default, Clone, BorshSerialize, BorshDeserialize, LightDiscriminator)]
    pub struct MyCompressedAccount {
        pub owner: Pubkey,
        pub message: String,
    }

    #[derive(BorshSerialize, BorshDeserialize)]
    pub struct CreateInstructionData {
        pub proof: ValidityProof,
        pub address_tree_info: PackedAddressTreeInfo,
        pub output_state_tree_index: u8,
        pub message: String,
    }

    pub fn process_instruction(
        program_id: &Pubkey,
        accounts: &[AccountInfo],
        instruction_data: &[u8],
    ) -> Result<(), ProgramError> {
        if program_id != &ID {
            return Err(ProgramError::IncorrectProgramId);
        }
        if instruction_data.is_empty() {
            return Err(ProgramError::InvalidInstructionData);
        }

        let discriminator = InstructionType::try_from(instruction_data[0])
            .map_err(|_| ProgramError::InvalidInstructionData)?;

        match discriminator {
            InstructionType::Create => {
                let instruction_data = CreateInstructionData::try_from_slice(&instruction_data[1..])
                    .map_err(|_| ProgramError::InvalidInstructionData)?;
                create(accounts, instruction_data)
            }
        }
    }

    pub fn create(
        accounts: &[AccountInfo],
        instruction_data: CreateInstructionData,
    ) -> Result<(), ProgramError> {
        let signer = accounts.first().ok_or(ProgramError::NotEnoughAccountKeys)?;

        let light_cpi_accounts = CpiAccounts::new(signer, &accounts[1..], LIGHT_CPI_SIGNER);

        let address_tree_pubkey = instruction_data
            .address_tree_info
            .get_tree_pubkey(&light_cpi_accounts)
            .map_err(|_| ProgramError::NotEnoughAccountKeys)?;

        if address_tree_pubkey.to_bytes() != ADDRESS_TREE_V2 {
            solana_program::msg!("Invalid address tree");
            return Err(ProgramError::InvalidAccountData);
        }

        let (address, address_seed) = derive_address(
            &[b"message", signer.key.as_ref()],
            &address_tree_pubkey,
            &ID,
        );

        let new_address_params = instruction_data
            .address_tree_info
            .into_new_address_params_assigned_packed(address_seed, Some(0));

        let mut my_compressed_account = LightAccount::<MyCompressedAccount>::new_init(
            &ID,
            Some(address),
            instruction_data.output_state_tree_index,
        );
        my_compressed_account.owner = *signer.key;
        my_compressed_account.message = instruction_data.message;

        LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, instruction_data.proof)
            .with_light_account(my_compressed_account)?
            .with_new_addresses(&[new_address_params])
            .invoke(light_cpi_accounts)?;

        Ok(())
    }
    ```
  </Tab>
</Tabs>

# Next Steps

<CardGroup>
  <Card title="Build a client for your program" icon="chevron-right" href="/client-library/client-guide" />

  <Card title="Learn how to update compressed accounts" icon="chevron-right" href="/compressed-pdas/guides/how-to-update-compressed-accounts" />
</CardGroup>


# Create Nullifier PDAs
Source: https://www.zkcompression.com/compressed-pdas/guides/how-to-create-nullifier-pdas

Create rent-free nullifier PDAs to prevent duplicate actions.

For some use cases, such as sending payments, you might want to prevent your
onchain instruction from being executed more than once.

The nullifier program utility solves this for you.
We also deployed a reference implementation to public networks so you can get started quickly:

|                 |                                                                                                                                            |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Program ID**  | `NFLx5WGPrTHHvdRNsidcrNcLxRruMC92E4yv7zhZBoT`                                                                                              |
| **Networks**    | Mainnet, Devnet                                                                                                                            |
| **Source code** | [github.com/Lightprotocol/nullifier-program](https://github.com/Lightprotocol/nullifier-program/)                                          |
| **Example Tx**  | [Solana Explorer](https://explorer.solana.com/tx/38fA6kbKRcYb5XSez9ffQzfCcMbMHcaJGseCogShNXC5SemQsEo88ZMSPCLP9xv9PG8qSJnhWvWFqSYJnfBMLrpB) |

<Callout type="info">
  For the usage example source code, see here: [create\_nullifier.rs](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/actions/create_nullifier.rs#L25)
</Callout>

## How It Works

1. Derives PDA from `["nullifier", id]` seeds (where `id` is your unique identifier, e.g. a nonce, uuid, hash of signature, etc.)
2. Creates an empty rent-free PDA at that address
3. If the address exists, the whole transaction fails
4. Prepend or append this instruction to your transaction.

## Dependencies

<Tabs>
  <Tab title="Rust">
    ```toml theme={null}
    [dependencies]
    light-nullifier-program = "0.1.2"
    light-client = "0.19.0"
    ```
  </Tab>

  <Tab title="TS">
    ```bash theme={null}
    npm install @lightprotocol/nullifier-program @lightprotocol/stateless.js@beta
    ```
  </Tab>
</Tabs>

## Using the Helper

<Tabs>
  <Tab title="Rust">
    ```rust theme={null}
    use light_nullifier_program::sdk::{create_nullifier_ix, PROGRAM_ID};
    use light_client::{LightClient, LightClientConfig};
    use solana_sdk::{system_instruction, transaction::Transaction};

    let mut rpc = LightClient::new(
        LightClientConfig::new("https://mainnet.helius-rpc.com/?api-key=...")
    ).await?;

    // Create a unique 32-byte ID
    let id: [u8; 32] = /* hash of payment inputs or random */;

    // Build nullifier instruction
    let nullifier_ix = create_nullifier_ix(&mut rpc, payer.pubkey(), id).await?;

    // Combine with your transaction
    let transfer_ix = system_instruction::transfer(&payer.pubkey(), &recipient, 1_000_000);
    let tx = Transaction::new_signed_with_payer(
        &[nullifier_ix, transfer_ix],
        Some(&payer.pubkey()),
        &[&payer],
        recent_blockhash,
    );
    ```
  </Tab>

  <Tab title="TS">
    ```typescript theme={null}
    import { createNullifierIx } from "@lightprotocol/nullifier-program";
    import { createRpc } from "@lightprotocol/stateless.js";
    import { Transaction, SystemProgram, ComputeBudgetProgram } from "@solana/web3.js";

    const rpc = createRpc("https://mainnet.helius-rpc.com/?api-key=...");

    // Create a unique 32-byte ID (e.g., hash of payment inputs)
    const id = new Uint8Array(32);
    crypto.getRandomValues(id);

    // Build nullifier instruction
    const nullifierIx = await createNullifierIx(rpc, payer.publicKey, id);

    // Combine with your transaction
    const tx = new Transaction().add(
      nullifierIx,
      // your main instruction
      SystemProgram.transfer({
        fromPubkey: payer.publicKey,
        toPubkey: recipient,
        lamports: 1_000_000,
      })
    );
    ```
  </Tab>
</Tabs>

## Manually Fetching Proof

<Tabs>
  <Tab title="Rust">
    ```rust theme={null}
    use light_nullifier_program::sdk::{fetch_proof, build_instruction};

    // Step 1: Fetch proof
    let proof_result = fetch_proof(&mut rpc, &id).await?;

    // Step 2: Build instruction
    let nullifier_ix = build_instruction(payer.pubkey(), id, proof_result);

    // Add to transaction
    let tx = Transaction::new_signed_with_payer(
        &[nullifier_ix, transfer_ix],
        Some(&payer.pubkey()),
        &[&payer],
        recent_blockhash,
    );
    ```
  </Tab>

  <Tab title="TS">
    ```typescript theme={null}
    import { fetchProof, buildInstruction } from "@lightprotocol/nullifier-program";

    // Step 1: Fetch proof
    const proofResult = await fetchProof(rpc, id);

    // Step 2: Build instruction
    const nullifierIx = buildInstruction(payer.publicKey, id, proofResult);

    // Combine with your transaction
    const tx = new Transaction().add(
      nullifierIx,
      // your main instruction
      SystemProgram.transfer({
        fromPubkey: payer.publicKey,
        toPubkey: recipient,
        lamports: 1_000_000,
      })
    );
    ```
  </Tab>
</Tabs>

## Check If Nullifier Exists

<Tabs>
  <Tab title="Rust">
    ```rust theme={null}
    use light_nullifier_program::sdk::derive_nullifier_address;

    let address = derive_nullifier_address(&id);
    let account = rpc.get_compressed_account(None, Some(address)).await?;
    let exists = account.value.is_some();
    ```
  </Tab>

  <Tab title="TS">
    ```typescript theme={null}
    import { deriveNullifierAddress } from "@lightprotocol/nullifier-program";
    import { bn } from "@lightprotocol/stateless.js";

    const address = deriveNullifierAddress(id);
    const account = await rpc.getCompressedAccount(bn(address.toBytes()));
    const exists = account !== null;
    ```
  </Tab>
</Tabs>

***

Note that this is a reference implementation. Feel free to fork the program as you see fit.

<Callout type="info">
  Questions or need support? [Telegram](https://t.me/swen_light) | [email](mailto:support@lightprotocol.com) | [Discord](https://discord.com/invite/7cJ8BhAXhu)
</Callout>


# Reinitialize Compressed Accounts
Source: https://www.zkcompression.com/compressed-pdas/guides/how-to-reinitialize-compressed-accounts

Guide to reinitialize compressed accounts in Solana programs with full code examples.

Compressed accounts are reinitialized via CPI to the Light System Program.

An empty compressed account can be reinitialized

* with an account hash marked as empty with zero values and zero discriminator
* to create a new account hash at the same address with new values.

<Note>
  Find [full code examples at the end](/compressed-pdas/guides/how-to-reinitialize-compressed-accounts#full-code-example) for Anchor and native Rust.
</Note>

# Implementation Guide

This guide will cover the components of a Solana program that reinitializes compressed accounts.
Here is the complete flow to reinitialize compressed accounts:

<div>
  <Frame>
    <img alt="" />
  </Frame>
</div>

<div>
  <Frame>
    <img alt="" />
  </Frame>
</div>

<Steps>
  <Step>
    ### Program Setup

    <Accordion title="Dependencies, Constants, Compressed Account">
      **Dependencies**

      Add dependencies to your program.

      <CodeGroup>
        ```toml Anchor theme={null}
        [dependencies]
        light-sdk = "0.19.0"
        anchor_lang = "0.31.1"
        ```

        ```toml Native Rust theme={null}
        [dependencies]
        light-sdk = "0.19.0"
        borsh = "0.10.0"
        solana-program = "2.2"
        ```
      </CodeGroup>

      * The `light-sdk` provides macros, wrappers and CPI interface to create and interact with compressed accounts.
      * Add the serialization library (`borsh` for native Rust, or use `AnchorSerialize`).

      **Constants**

      Set program address and derive the CPI authority PDA to call the Light System program.

      ```rust theme={null}
      declare_id!("rent4o4eAiMbxpkAM1HeXzks9YeGuz18SEgXEizVvPq");

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

      **`CPISigner`** is the configuration struct for CPI's to the Light System Program.

      * CPIs to the Light System program must be signed with a PDA derived by your program with the seed `b"authority"`
      * `derive_light_cpi_signer!` derives the CPI signer PDA for you at compile time.

      **Compressed Account**

      Define your compressed account struct.

      <CodeGroup>
        ```rust Anchor theme={null}
        #[event] // declared as event so that it is part of the idl.
        #[derive(
            Clone,
            Debug,
            Default,
            LightDiscriminator
        )]
        pub struct MyCompressedAccount {
            pub owner: Pubkey,
            pub message: String,
        }
        ```

        ```rust Native Rust theme={null}
        #[derive(
            Debug,
            Default,
            Clone,
            BorshSerialize,
            BorshDeserialize,
            LightDiscriminator,
        )]
        pub struct MyCompressedAccount {
            pub owner: Pubkey,
            pub message: String,
        }
        ```
      </CodeGroup>

      You derive

      * the standard traits (`Clone`, `Debug`, `Default`),
      * `borsh` or `AnchorSerialize` to serialize account data, and
      * `LightDiscriminator` to implements a unique type ID (8 bytes) to distinguish account types. The default compressed account layout enforces a discriminator in its *own field*, <Tooltip href="https://www.anchor-lang.com/">not the first 8 bytes of the data field</Tooltip>.

      <Info>
        The traits listed above are required for `LightAccount`. `LightAccount` wraps `MyCompressedAccount` in Step 3 to set the discriminator and create the compressed account's data.
      </Info>
    </Accordion>
  </Step>

  <Step>
    ### Instruction Data

    Define the instruction data with the following parameters:

    <Tabs>
      <Tab title="Anchor">
        ```rust theme={null}
        pub fn reinit_account<'info>(
            ctx: Context<'_, '_, '_, 'info, GenericAnchorAccounts<'info>>,
            proof: ValidityProof,
            account_meta: CompressedAccountMeta,
        ) -> Result<()>
        ```
      </Tab>

      <Tab title="Native Rust">
        ```rust theme={null}
        pub struct ReinitInstructionData {
            pub proof: ValidityProof,
            pub account_meta: CompressedAccountMeta,
        }
        ```
      </Tab>
    </Tabs>

    1. **Validity Proof**

    * Define `proof` to include the proof that the closed account with zero values exists in the state tree.
    * Clients fetch a validity proof with `getValidityProof()` from an RPC provider that supports ZK Compression (Helius, Triton, ...).

    2. **Specify input state and output state tree (stores new account hash)**

    * Define `account_meta: CompressedAccountMeta` to reference the closed account and specify the state tree to store the new account hash:
      * `tree_info: PackedStateTreeInfo`: References the existing account hash in the state tree.
      * `address`: The account's derived address.
      * `output_state_tree_index`: References the state tree account that will store the new compressed account hash.

    <Info>
      Reinitialization does not require `current_value` parameters. `new_empty()` automatically uses the closed account as input.
    </Info>
  </Step>

  <Step>
    ### Reinitialize Closed Account

    Reinitialize the closed account with `LightAccount::new_empty()`.

    <Note>
      `new_empty()`

      1. reconstructs the closed account hash with zero values as input, and
      2. creates output state with default-initialized values.

      You can set custom values in the same transaction:

      1. Reinitialize with `new_empty()`, and
      2. Update with `new_mut()` to set custom values.
    </Note>

    <Tabs>
      <Tab title="Anchor">
        ```rust theme={null}
        let my_compressed_account = LightAccount::<MyCompressedAccount>::new_empty(
            &crate::ID,
            &account_meta,
        )?;
        ```
      </Tab>

      <Tab title="Native Rust">
        ```rust theme={null}
        let my_compressed_account = LightAccount::<MyCompressedAccount>::new_empty(
            &ID,
            &instruction_data.account_meta,
        )?;
        ```
      </Tab>
    </Tabs>

    **Pass these parameters to `new_empty()`:**

    * `&program_id`: The program's ID that owns the compressed account.
    * `&account_meta`: The `CompressedAccountMeta` from instruction data (*Step 2*) that identifies the existing account and specifies the output state tree.
      * Anchor: Pass `account_meta` by reference. It is automatically deserialized as a function parameter.
      * Native Rust: Manually deserialize the instruction data struct, then pass the field by reference `&instruction_data.account_meta`.

    **The SDK creates:**

    * A `LightAccount` wrapper with account data automatically initialized to default values using the `Default` trait.
    * This creates a zero-initialized instance: `Pubkey` as all zeros, `u64` as `0`, `String` as empty.

    <Info>
      `new_empty()` reconstructs the closed account hash with zero values. The Light System Program verifies the closed account hash and creates the output hash in *Step 4*.
    </Info>
  </Step>

  <Step>
    ### Light System Program CPI

    Invoke the Light System Program to reinitialize the compressed account.

    <Note>
      The Light System Program

      * validates the closed account hash exists in state tree,
      * nullifies the closed account hash, and
      * appends the new account hash with provided values to the state tree.
    </Note>

    <Tabs>
      <Tab title="Anchor">
        ```rust theme={null}
        let light_cpi_accounts = CpiAccounts::new(
            ctx.accounts.signer.as_ref(),
            ctx.remaining_accounts,
            crate::LIGHT_CPI_SIGNER,
        );

        LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, proof)
            .with_light_account(my_compressed_account)?
            .invoke(light_cpi_accounts)?;
        ```

        **Set up `CpiAccounts::new()`:**

        `CpiAccounts::new()` parses accounts for the CPI call to Light System Program.

        **Pass these parameters:**

        * `ctx.accounts.signer.as_ref()`: the transaction signer
        * `ctx.remaining_accounts`: Slice with `[system_accounts, ...packed_tree_accounts]`. The client builds this with `PackedAccounts` and passes it to the instruction.
        * `&LIGHT_CPI_SIGNER`: Your program's CPI signer PDA defined in Constants.
      </Tab>

      <Tab title="Native Rust">
        ```rust theme={null}
        let (signer, remaining_accounts) = accounts
            .split_first();

        let cpi_accounts = CpiAccounts::new(
            signer,
            remaining_accounts,
            LIGHT_CPI_SIGNER
        );

        LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, instruction_data.proof)
            .with_light_account(my_compressed_account)?
            .invoke(cpi_accounts)?;
        ```

        **Set up `CpiAccounts::new()`:**

        `CpiAccounts::new()` parses accounts for the CPI call to Light System Program.

        **Pass these parameters:**

        * `signer`: account that signs and pays for the transaction
        * `remaining_accounts`: Slice with `[system_accounts, ...packed_tree_accounts]`. The client builds this with `PackedAccounts`.
          * `split_first()` extracts the fee payer from the accounts array to separate it from the Light System Program accounts needed for the CPI.
        * `&LIGHT_CPI_SIGNER`: Your program's CPI signer PDA defined in Constants.
      </Tab>
    </Tabs>

    <Accordion title="System Accounts List">
      <table>
        <colgroup>
          <col />

          <col />

          <col />
        </colgroup>

        <thead>
          <tr>
            <th />

            <th />

            <th />
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>1</td>
            <td><strong><Tooltip href="https://solscan.io/account/SySTEM1eSU2p4BGQfQpimFEWWSC1XDFeun3Nqzz3rT7">Light System Program</Tooltip></strong></td>
            <td>Verifies validity proofs, compressed account ownership checks, and CPIs the Account Compression Program to update tree accounts.</td>
          </tr>

          <tr>
            <td>2</td>
            <td><strong>CPI Signer</strong></td>

            <td>
              * PDA to sign CPI calls from your program to the Light System Program.<br />
              * Verified by the Light System Program during CPI.<br />
              * Derived from your program ID.
            </td>
          </tr>

          <tr>
            <td>3</td>
            <td><strong>Registered Program PDA</strong></td>
            <td>Provides access control to the Account Compression Program.</td>
          </tr>

          <tr>
            <td>4</td>
            <td><strong><Tooltip href="https://solscan.io/account/HZH7qSLcpAeDqCopVU4e5XkhT9j3JFsQiq8CmruY3aru">Account Compression Authority</Tooltip></strong></td>
            <td>Signs CPI calls from the Light System Program to the Account Compression Program.</td>
          </tr>

          <tr>
            <td>5</td>
            <td><strong><Tooltip href="https://solscan.io/account/compr6CUsB5m2jS4Y3831ztGSTnDpnKJTKS95d64XVq">Account Compression Program</Tooltip></strong></td>

            <td>
              * Writes to state and address tree accounts.<br />
              * Clients and the Account Compression Program do not interact directly — handled internally.
            </td>
          </tr>

          <tr>
            <td>6</td>
            <td><strong><Tooltip href="https://solscan.io/account/11111111111111111111111111111111">System Program</Tooltip></strong></td>
            <td>Solana System Program used to transfer lamports.</td>
          </tr>
        </tbody>
      </table>
    </Accordion>

    **Build the CPI instruction**:

    * `new_cpi()` initializes the CPI instruction with the `proof` to prove the closed account hash exists in the state tree *- defined in the Instruction Data (Step 2).*
    * `with_light_account` adds the `LightAccount` configured with the closed account hash as input and provided values as output *- defined in Step 3*.
    * `invoke(light_cpi_accounts)` calls the Light System Program with `CpiAccounts`.
  </Step>
</Steps>

# Full Code Example

The counter programs below implement all steps from this guide.

<Accordion title="Setup">
  **Install Solana CLI:**

  ```bash theme={null}
  sh -c "$(curl -sSfL https://release.solana.com/v2.2.15/install)"
  ```

  **Install Anchor CLI:**

  ```bash theme={null}
  cargo install --git https://github.com/coral-xyz/anchor avm --force
  avm install latest
  avm use latest
  ```

  **Install the Light CLI:**

  <Tabs>
    <Tab title="npm">
      ```bash theme={null}
      npm install -g @lightprotocol/zk-compression-cli@beta
      ```
    </Tab>

    <Tab title="yarn">
      ```bash theme={null}
      yarn global add @lightprotocol/zk-compression-cli@beta
      ```
    </Tab>

    <Tab title="pnpm">
      ```bash theme={null}
      pnpm add -g @lightprotocol/zk-compression-cli@beta
      ```
    </Tab>
  </Tabs>

  **Verify installation:**

  ```bash theme={null}
  light --version
  ```
</Accordion>

<Warning>
  For help with debugging, see the [Error Cheatsheet](../../resources/error-cheatsheet/).
</Warning>

<Tabs>
  <Tab title="Anchor">
    <Info>
      Find the source code [here](https://github.com/Lightprotocol/program-examples/tree/main/basic-operations/anchor/reinit).
    </Info>

    ````rust theme={null}
    #![allow(unexpected_cfgs)]
    #![allow(deprecated)]

    use anchor_lang::{prelude::*, AnchorDeserialize, AnchorSerialize};
    use light_sdk::{
        account::LightAccount,
        address::v2::derive_address,
        cpi::{v2::CpiAccounts, CpiSigner},
        derive_light_cpi_signer,
        instruction::{account_meta::CompressedAccountMeta, PackedAddressTreeInfo, ValidityProof},
        LightDiscriminator,
    };
    use light_sdk_types::ADDRESS_TREE_V2;

    declare_id!("DeSUZ4to3qN7mQimoTgvEnBXiBWeTqMVcMz3ynLaWx1t");

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

    #[program]
    pub mod reinit {

        use super::*;
        use light_sdk::cpi::{
            v2::LightSystemProgramCpi, InvokeLightSystemProgram, LightCpiInstruction,
        };

        /// Setup: Create a compressed account
        pub fn create_account<'info>(
            ctx: Context<'_, '_, '_, 'info, GenericAnchorAccounts<'info>>,
            proof: ValidityProof,
            address_tree_info: PackedAddressTreeInfo,
            output_state_tree_index: u8,
            message: String,
        ) -> Result<()> {
            let light_cpi_accounts = CpiAccounts::new(
                ctx.accounts.signer.as_ref(),
                ctx.remaining_accounts,
                crate::LIGHT_CPI_SIGNER,
            );

            let address_tree_pubkey = address_tree_info
                .get_tree_pubkey(&light_cpi_accounts)
                .map_err(|_| ErrorCode::AccountNotEnoughKeys)?;

            if address_tree_pubkey.to_bytes() != ADDRESS_TREE_V2 {
                msg!("Invalid address tree");
                return Err(ProgramError::InvalidAccountData.into());
            }

            let (address, address_seed) = derive_address(
                &[b"message", ctx.accounts.signer.key().as_ref()],
                &address_tree_pubkey,
                &crate::ID,
            );

            let mut my_compressed_account = LightAccount::<MyCompressedAccount>::new_init(
                &crate::ID,
                Some(address),
                output_state_tree_index,
            );

            my_compressed_account.owner = ctx.accounts.signer.key();
            my_compressed_account.message = message.clone();

            msg!(
                "Created compressed account with message: {}",
                my_compressed_account.message
            );

            LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, proof)
                .with_light_account(my_compressed_account)?
                .with_new_addresses(&[address_tree_info.into_new_address_params_assigned_packed(address_seed, Some(0))])
                .invoke(light_cpi_accounts)?;

            Ok(())
        }

        /// Setup: Close compressed account
        pub fn close_account<'info>(
            ctx: Context<'_, '_, '_, 'info, GenericAnchorAccounts<'info>>,
            proof: ValidityProof,
            account_meta: CompressedAccountMeta,
            current_message: String,
        ) -> Result<()> {
            let light_cpi_accounts = CpiAccounts::new(
                ctx.accounts.signer.as_ref(),
                ctx.remaining_accounts,
                crate::LIGHT_CPI_SIGNER,
            );

            let my_compressed_account = LightAccount::<MyCompressedAccount>::new_close(
                &crate::ID,
                &account_meta,
                MyCompressedAccount {
                    owner: ctx.accounts.signer.key(),
                    message: current_message,
                },
            )?;

            msg!("Close compressed account.");

            LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, proof)
                .with_light_account(my_compressed_account)?
                .invoke(light_cpi_accounts)?;

            Ok(())
        }

        /// Reinitialize closed compressed account
        pub fn reinit_account<'info>(
            ctx: Context<'_, '_, '_, 'info, GenericAnchorAccounts<'info>>,
            proof: ValidityProof,
            account_meta: CompressedAccountMeta,
        ) -> Result<()> {
            let light_cpi_accounts = CpiAccounts::new(
                ctx.accounts.signer.as_ref(),
                ctx.remaining_accounts,
                crate::LIGHT_CPI_SIGNER,
            );

            let my_compressed_account = LightAccount::<MyCompressedAccount>::new_empty(
                &crate::ID,
                &account_meta,
            )?;

            msg!("Reinitializing closed compressed account");

            LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, proof)
                .with_light_account(my_compressed_account)?
                .invoke(light_cpi_accounts)?;

            Ok(())
        }
    }

    #[derive(Accounts)]
    pub struct GenericAnchorAccounts<'info> {
        #[account(mut)]
        pub signer: Signer<'info>,
    }

    #[event]
    #[derive(Clone, Debug, Default, LightDiscriminator)]
    pub struct MyCompressedAccount {
        pub owner: Pubkey,
        pub message: String,
    }```
    ````
  </Tab>

  <Tab title="Native Rust">
    <Info>
      Find the source code [here](https://github.com/Lightprotocol/program-examples/tree/main/basic-operations/native/programs/reinit).
    </Info>

    ```rust theme={null}
    #![allow(unexpected_cfgs)]

    #[cfg(any(test, feature = "test-helpers"))]
    pub mod test_helpers;

    use borsh::{BorshDeserialize, BorshSerialize};
    use light_macros::pubkey;
    use light_sdk::{
        account::sha::LightAccount,
        address::v2::derive_address,
        cpi::{
            v2::{CpiAccounts, LightSystemProgramCpi},
            CpiSigner, InvokeLightSystemProgram, LightCpiInstruction,
        },
        derive_light_cpi_signer,
        error::LightSdkError,
        instruction::{account_meta::CompressedAccountMeta, PackedAddressTreeInfo, ValidityProof},
        LightDiscriminator,
    };
    use light_sdk_types::ADDRESS_TREE_V2;
    use solana_program::{
        account_info::AccountInfo, entrypoint, program_error::ProgramError, pubkey::Pubkey,
    };

    pub const ID: Pubkey = pubkey!("C9WiPUaQ5PRjEWg7vUmgekfuQtAgFZFhn12ytXEMDr8y");
    pub const LIGHT_CPI_SIGNER: CpiSigner = derive_light_cpi_signer!("C9WiPUaQ5PRjEWg7vUmgekfuQtAgFZFhn12ytXEMDr8y");

    #[cfg(not(feature = "no-entrypoint"))]
    entrypoint!(process_instruction);

    #[derive(Debug, BorshSerialize, BorshDeserialize)]
    pub enum InstructionType {
        Create,
        Close,
        Reinit,
    }

    #[derive(Debug, BorshSerialize, BorshDeserialize)]
    pub struct CreateInstructionData {
        pub proof: ValidityProof,
        pub address_tree_info: PackedAddressTreeInfo,
        pub output_state_tree_index: u8,
        pub message: String,
    }

    #[derive(Debug, BorshSerialize, BorshDeserialize)]
    pub struct CloseInstructionData {
        pub proof: ValidityProof,
        pub account_meta: CompressedAccountMeta,
        pub current_message: String,
    }

    #[derive(Debug, BorshSerialize, BorshDeserialize)]
    pub struct ReinitInstructionData {
        pub proof: ValidityProof,
        pub account_meta: CompressedAccountMeta,
    }

    #[derive(Debug, Default, Clone, BorshSerialize, BorshDeserialize, LightDiscriminator)]
    pub struct MyCompressedAccount {
        pub owner: Pubkey,
        pub message: String,
    }

    pub fn process_instruction(
        _program_id: &Pubkey,
        accounts: &[AccountInfo],
        instruction_data: &[u8],
    ) -> Result<(), ProgramError> {
        let (instruction_type, rest) = instruction_data
            .split_first()
            .ok_or(ProgramError::InvalidInstructionData)?;

        match InstructionType::try_from_slice(&[*instruction_type])
            .map_err(|_| ProgramError::InvalidInstructionData)?
        {
            InstructionType::Create => create(accounts, rest)?,
            InstructionType::Close => close(accounts, rest)?,
            InstructionType::Reinit => reinit(accounts, rest)?,
        }

        Ok(())
    }

    fn create(accounts: &[AccountInfo], instruction_data: &[u8]) -> Result<(), LightSdkError> {
        let instruction_data =
            CreateInstructionData::try_from_slice(instruction_data).map_err(|_| LightSdkError::Borsh)?;

        let signer = accounts.first().ok_or(ProgramError::NotEnoughAccountKeys)?;

        let light_cpi_accounts = CpiAccounts::new(signer, &accounts[1..], LIGHT_CPI_SIGNER);

        let address_tree_pubkey = instruction_data
            .address_tree_info
            .get_tree_pubkey(&light_cpi_accounts)
            .map_err(|_| ProgramError::NotEnoughAccountKeys)?;

        if address_tree_pubkey.to_bytes() != ADDRESS_TREE_V2 {
            solana_program::msg!("Invalid address tree");
            return Err(LightSdkError::ProgramError(ProgramError::InvalidAccountData));
        }

        let (address, address_seed) = derive_address(
            &[b"message", signer.key.as_ref()],
            &address_tree_pubkey,
            &ID,
        );

        let new_address_params = instruction_data
            .address_tree_info
            .into_new_address_params_assigned_packed(address_seed, Some(0));

        let mut my_compressed_account = LightAccount::<MyCompressedAccount>::new_init(
            &ID,
            Some(address),
            instruction_data.output_state_tree_index,
        );
        my_compressed_account.owner = *signer.key;
        my_compressed_account.message = instruction_data.message;

        LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, instruction_data.proof)
            .with_light_account(my_compressed_account)?
            .with_new_addresses(&[new_address_params])
            .invoke(light_cpi_accounts)?;

        Ok(())
    }

    fn close(accounts: &[AccountInfo], instruction_data: &[u8]) -> Result<(), LightSdkError> {
        let instruction_data =
            CloseInstructionData::try_from_slice(instruction_data).map_err(|_| LightSdkError::Borsh)?;

        let (signer, remaining_accounts) = accounts
            .split_first()
            .ok_or(ProgramError::InvalidAccountData)?;

        let cpi_accounts = CpiAccounts::new(signer, remaining_accounts, LIGHT_CPI_SIGNER);

        let my_compressed_account = LightAccount::<MyCompressedAccount>::new_close(
            &ID,
            &instruction_data.account_meta,
            MyCompressedAccount {
                owner: *signer.key,
                message: instruction_data.current_message,
            },
        )?;

        LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, instruction_data.proof)
            .with_light_account(my_compressed_account)?
            .invoke(cpi_accounts)?;

        Ok(())
    }

    fn reinit(accounts: &[AccountInfo], instruction_data: &[u8]) -> Result<(), LightSdkError> {
        let instruction_data =
            ReinitInstructionData::try_from_slice(instruction_data).map_err(|_| LightSdkError::Borsh)?;

        let (signer, remaining_accounts) = accounts
            .split_first()
            .ok_or(ProgramError::InvalidAccountData)?;

        let cpi_accounts = CpiAccounts::new(signer, remaining_accounts, LIGHT_CPI_SIGNER);

        let my_compressed_account = LightAccount::<MyCompressedAccount>::new_empty(
            &ID,
            &instruction_data.account_meta,
        )?;

        LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, instruction_data.proof)
            .with_light_account(my_compressed_account)?
            .invoke(cpi_accounts)?;

        Ok(())
    }
    ```
  </Tab>
</Tabs>

# Next Steps

<CardGroup>
  <Card title="Build a client for your program" icon="chevron-right" href="/client-library/client-guide" />

  <Card title="Learn how to burn compressed accounts" icon="chevron-right" href="/compressed-pdas/guides/how-to-burn-compressed-accounts" />
</CardGroup>


# Update Compressed Accounts
Source: https://www.zkcompression.com/compressed-pdas/guides/how-to-update-compressed-accounts

Guide to update compressed accounts in Solana programs with full code examples.

Compressed accounts are updated via CPI to the Light System Program.

The update of a compressed account follows a UTXO pattern, unlike regular Solana accounts that overwrite data in place. Each update of a compressed account

* consumes the existing account hash and
* produces a new account hash with updated data.
* The existing account hash is nullified to prevent double spending.

<Note>
  Find [full code examples at the end](/compressed-pdas/guides/how-to-update-compressed-accounts#full-code-example) for Anchor and native Rust.
</Note>

# Implementation Guide

This guide will cover the components of a Solana program that updates compressed accounts.\
Here is the complete flow:

<div>
  <Frame>
    <img alt="" />
  </Frame>
</div>

<div>
  <Frame>
    <img alt="" />
  </Frame>
</div>

<Steps>
  <Step>
    ### Program Setup

    <Accordion title="Dependencies, Constants, Compressed Account">
      **Dependencies**

      Add dependencies to your program.

      <CodeGroup>
        ```toml Anchor theme={null}
        [dependencies]
        light-sdk = "0.19.0"
        anchor_lang = "0.31.1"
        ```

        ```toml Native Rust theme={null}
        [dependencies]
        light-sdk = "0.19.0"
        borsh = "0.10.0"
        solana-program = "2.2"
        ```
      </CodeGroup>

      * The `light-sdk` provides macros, wrappers and CPI interface to create and interact with compressed accounts.
      * Add the serialization library (`borsh` for native Rust, or use `AnchorSerialize`).

      **Constants**

      Set program address and derive the CPI authority PDA to call the Light System program.

      ```rust theme={null}
      declare_id!("rent4o4eAiMbxpkAM1HeXzks9YeGuz18SEgXEizVvPq");

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

      **`CPISigner`** is the configuration struct for CPI's to the Light System Program.

      * CPIs to the Light System program must be signed with a PDA derived by your program with the seed `b"authority"`
      * `derive_light_cpi_signer!` derives the CPI signer PDA for you at compile time.

      **Compressed Account**

      Define your compressed account struct.

      <CodeGroup>
        ```rust Anchor theme={null}
        #[event] // declared as event so that it is part of the idl.
        #[derive(
            Clone,
            Debug,
            Default,
            LightDiscriminator
        )]
        pub struct MyCompressedAccount {
            pub owner: Pubkey,
            pub message: String,
        }
        ```

        ```rust Native Rust theme={null}
        #[derive(
            Debug,
            Default,
            Clone,
            BorshSerialize,
            BorshDeserialize,
            LightDiscriminator,
        )]
        pub struct MyCompressedAccount {
            pub owner: Pubkey,
            pub message: String,
        }
        ```
      </CodeGroup>

      You derive

      * the standard traits (`Clone`, `Debug`, `Default`),
      * `borsh` or `AnchorSerialize` to serialize account data, and
      * `LightDiscriminator` to implements a unique type ID (8 bytes) to distinguish account types. The default compressed account layout enforces a discriminator in its *own field*, <Tooltip href="https://www.anchor-lang.com/">not the first 8 bytes of the data field</Tooltip>.

      <Info>
        The traits listed above are required for `LightAccount`. `LightAccount` wraps `MyCompressedAccount` in Step 3 to set the discriminator and create the compressed account's data.
      </Info>
    </Accordion>
  </Step>

  <Step>
    ### Instruction Data

    Define the instruction data with the following parameters:

    <Tabs>
      <Tab title="Anchor">
        Anchor handles instruction deserialization automatically. Pass the parameters directly to the instruction function:

        ```rust theme={null}
        pub fn update_account<'info>(
            ctx: Context<'_, '_, '_, 'info, GenericAnchorAccounts<'info>>,
            proof: ValidityProof,
            current_account: MyCompressedAccount,
            account_meta: CompressedAccountMeta,
            new_message: String,
        ) -> Result<()>
        ```
      </Tab>

      <Tab title="Native Rust">
        ```rust theme={null}
        pub struct UpdateInstructionData {
            pub proof: ValidityProof,
            pub account_meta: CompressedAccountMeta,
            pub current_message: String,
            pub new_message: String,
        }
        ```
      </Tab>
    </Tabs>

    1. **Validity Proof**

    * Define `proof` to include the proof that the account exists in the state tree.
    * Clients fetch a validity proof with `getValidityProof()` from an RPC provider that supports ZK Compression (Helius, Triton, ...).

    2. **Specify input state and output state tree (stores updated account hash)**

    * Define `account_meta: CompressedAccountMeta` to reference the existing account and specify the state tree to store the updated account hash:
      * `tree_info: PackedStateTreeInfo`: References the existing account hash in the state tree.
      * `address`: The account's derived address.
      * `output_state_tree_index`: References the state tree account that will store the updated account hash.

    <Info>
      Clients fetch the current account with `getCompressedAccount()` and populate `CompressedAccountMeta` with the account's metadata.
    </Info>

    3. **Current account data**

    * Define fields to include the current account data passed by the client.
    * This depends on your program logic. This example includes `current_message` (or `current_account` in Anchor) and `new_message` fields.
      * `new_message` contains the new data that will replace the message field of the compressed account after the update.
  </Step>

  <Step>
    ### Update Compressed Account

    Load the compressed account and update it with `LightAccount::new_mut()`.

    <Note>
      `new_mut()`:

      * hashes the current account data as input state and
      * lets your program define the output state.
    </Note>

    <Tabs>
      <Tab title="Anchor">
        ```rust theme={null}
        let mut my_compressed_account = LightAccount::<MyCompressedAccount>::new_mut(
            &crate::ID,
            &account_meta,
            current_account,
        )?;

        my_compressed_account.message = new_message.clone();
        ```
      </Tab>

      <Tab title="Native Rust">
        ```rust theme={null}
        let mut my_compressed_account = LightAccount::<MyCompressedAccount>::new_mut(
            &ID,
            &instruction_data.account_meta,
            MyCompressedAccount {
                owner: *signer.key,
                message: instruction_data.current_message,
            },
        )?;

        my_compressed_account.account.message = instruction_data.new_message;
        ```
      </Tab>
    </Tabs>

    **Pass these parameters to `new_mut()`:**

    * `&program_id`: The program's ID that owns the compressed account.
    * `&account_meta`: The `CompressedAccountMeta` from instruction data (*Step 2*) that identifies the existing account and specifies the output state tree.
    * Include the curent account data.
      * Anchor: Pass `current_account` directly
      * Native: Construct `MyCompressedAccount` with data from `instruction_data`

    **The SDK creates:**

    * A `LightAccount` wrapper similar to Anchor's `Account`.
    * `new_mut()` lets the program modify the output state. This example sets `message` to `new_message`.

    <Info>
      `new_mut()` only hashes the input state. The Light System Program verifies that input hash exists in a state tree and creates the output hash in *Step 4.*
    </Info>
  </Step>

  <Step>
    ### Light System Program CPI

    Invoke the Light System Program to update the compressed account.

    <Note>
      The Light System Program

      * validates the account exists in state tree,
      * nullifies the existing account hash in the state tree, and
      * appends the updated account hash to the state tree.
    </Note>

    <Tabs>
      <Tab title="Anchor">
        ```rust theme={null}
        let light_cpi_accounts = CpiAccounts::new(
            ctx.accounts.signer.as_ref(),
            ctx.remaining_accounts,
            crate::LIGHT_CPI_SIGNER,
        );

        LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, proof)
            .with_light_account(my_compressed_account)?
            .invoke(light_cpi_accounts)?;
        ```

        **Set up `CpiAccounts::new()`:**

        `CpiAccounts::new()` parses accounts for the CPI call to Light System Program.

        **Pass these parameters:**

        * `ctx.accounts.signer.as_ref()`: the transaction signer
        * `ctx.remaining_accounts`: Slice with `[system_accounts, ...packed_tree_accounts]`. The client builds this with `PackedAccounts` and passes it to the instruction.
        * `&LIGHT_CPI_SIGNER`: Your program's CPI signer PDA defined in Constants.
      </Tab>

      <Tab title="Native Rust">
        ```rust theme={null}
        let signer = accounts.first();

        let light_cpi_accounts = CpiAccounts::new(
            signer,
            &accounts[1..],
            LIGHT_CPI_SIGNER
        );

        LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, instruction_data.proof)
            .with_light_account(my_compressed_account)?
            .invoke(light_cpi_accounts)?;
        ```

        **Set up `CpiAccounts::new()`:**

        `CpiAccounts::new()` parses accounts for the CPI call to Light System Program.

        **Pass these parameters:**

        * `signer`: account that signs and pays for the transaction
        * `&accounts[1..]`: Slice with `[system_accounts, ...packed_tree_accounts]`. The client builds this with `PackedAccounts`.
        * `&LIGHT_CPI_SIGNER`: Your program's CPI signer PDA defined in Constants.
      </Tab>
    </Tabs>

    <Accordion title="System Accounts List">
      <table>
        <colgroup>
          <col />

          <col />

          <col />
        </colgroup>

        <thead>
          <tr>
            <th />

            <th />

            <th />
          </tr>
        </thead>

        <tbody>
          <tr>
            <td>1</td>
            <td><strong><Tooltip href="https://solscan.io/account/SySTEM1eSU2p4BGQfQpimFEWWSC1XDFeun3Nqzz3rT7">Light System Program</Tooltip></strong></td>
            <td>Verifies validity proofs, compressed account ownership checks, and CPIs the Account Compression Program to update tree accounts.</td>
          </tr>

          <tr>
            <td>2</td>
            <td><strong>CPI Signer</strong></td>

            <td>
              * PDA to sign CPI calls from your program to the Light System Program.<br />
              * Verified by the Light System Program during CPI.<br />
              * Derived from your program ID.
            </td>
          </tr>

          <tr>
            <td>3</td>
            <td><strong>Registered Program PDA</strong></td>
            <td>Provides access control to the Account Compression Program.</td>
          </tr>

          <tr>
            <td>4</td>
            <td><strong><Tooltip href="https://solscan.io/account/HZH7qSLcpAeDqCopVU4e5XkhT9j3JFsQiq8CmruY3aru">Account Compression Authority</Tooltip></strong></td>
            <td>Signs CPI calls from the Light System Program to the Account Compression Program.</td>
          </tr>

          <tr>
            <td>5</td>
            <td><strong><Tooltip href="https://solscan.io/account/compr6CUsB5m2jS4Y3831ztGSTnDpnKJTKS95d64XVq">Account Compression Program</Tooltip></strong></td>

            <td>
              * Writes to state and address tree accounts.<br />
              * Clients and the Account Compression Program do not interact directly — handled internally.
            </td>
          </tr>

          <tr>
            <td>6</td>
            <td><strong><Tooltip href="https://solscan.io/account/11111111111111111111111111111111">System Program</Tooltip></strong></td>
            <td>Solana System Program used to transfer lamports.</td>
          </tr>
        </tbody>
      </table>
    </Accordion>

    **Build the CPI instruction**:

    * `new_cpi()` initializes the CPI instruction with the `proof` to prove that the account exists in the specified state tree - *in the Instruction Data (Step 2).*
    * `with_light_account` adds the `LightAccount` with the modified compressed account data *- defined in Step 3*
    * `invoke(light_cpi_accounts)` calls the Light System Program with `CpiAccounts`.
  </Step>
</Steps>

# Full Code Example

The example programs below implement all steps from this guide.

<Accordion title="Setup">
  **Install Solana CLI:**

  ```bash theme={null}
  sh -c "$(curl -sSfL https://release.solana.com/v2.2.15/install)"
  ```

  **Install Anchor CLI:**

  ```bash theme={null}
  cargo install --git https://github.com/coral-xyz/anchor avm --force
  avm install latest
  avm use latest
  ```

  **Install the Light CLI:**

  <Tabs>
    <Tab title="npm">
      ```bash theme={null}
      npm install -g @lightprotocol/zk-compression-cli@beta
      ```
    </Tab>

    <Tab title="yarn">
      ```bash theme={null}
      yarn global add @lightprotocol/zk-compression-cli@beta
      ```
    </Tab>

    <Tab title="pnpm">
      ```bash theme={null}
      pnpm add -g @lightprotocol/zk-compression-cli@beta
      ```
    </Tab>
  </Tabs>

  **Verify installation:**

  ```bash theme={null}
  light --version
  ```
</Accordion>

<Warning>
  For help with debugging, see the [Error Cheatsheet](../../resources/error-cheatsheet/).
</Warning>

<Tabs>
  <Tab title="Anchor">
    <Info>
      Find the source code [here](https://github.com/Lightprotocol/program-examples/tree/main/basic-operations/anchor/update).
    </Info>

    ````rust theme={null}
    #![allow(unexpected_cfgs)]
    #![allow(deprecated)]

    use anchor_lang::{prelude::*, AnchorDeserialize, AnchorSerialize};
    use light_sdk::{
        account::LightAccount,
        address::v2::derive_address,
        cpi::{v2::CpiAccounts, CpiSigner},
        derive_light_cpi_signer,
        instruction::{account_meta::CompressedAccountMeta, PackedAddressTreeInfo, ValidityProof},
        LightDiscriminator,
    };
    use light_sdk_types::ADDRESS_TREE_V2;

    declare_id!("Cj3DxyqB7wJh511VKexsjKt7Hx1kvPvCBMrbLuL8grKc");

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

    #[program]
    pub mod update {

        use super::*;
        use light_sdk::cpi::{
            v2::LightSystemProgramCpi, InvokeLightSystemProgram, LightCpiInstruction,
        };

        /// Setup: Creates a compressed account
        pub fn create_account<'info>(
            ctx: Context<'_, '_, '_, 'info, GenericAnchorAccounts<'info>>,
            proof: ValidityProof,
            address_tree_info: PackedAddressTreeInfo,
            output_state_tree_index: u8,
            message: String,
        ) -> Result<()> {
            let light_cpi_accounts = CpiAccounts::new(
                ctx.accounts.signer.as_ref(),
                ctx.remaining_accounts,
                crate::LIGHT_CPI_SIGNER,
            );

            let address_tree_pubkey = address_tree_info
                .get_tree_pubkey(&light_cpi_accounts)
                .map_err(|_| ErrorCode::AccountNotEnoughKeys)?;

            if address_tree_pubkey.to_bytes() != ADDRESS_TREE_V2 {
                msg!("Invalid address tree");
                return Err(ProgramError::InvalidAccountData.into());
            }

            let (address, address_seed) = derive_address(
                &[b"message", ctx.accounts.signer.key().as_ref()],
                &address_tree_pubkey,
                &crate::ID,
            );

            let mut my_compressed_account = LightAccount::<MyCompressedAccount>::new_init(
                &crate::ID,
                Some(address),
                output_state_tree_index,
            );

            my_compressed_account.owner = ctx.accounts.signer.key();
            my_compressed_account.message = message.clone();

            msg!(
                "Created compressed account with message: {}",
                my_compressed_account.message
            );

            LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, proof)
                .with_light_account(my_compressed_account)?
                .with_new_addresses(&[address_tree_info.into_new_address_params_assigned_packed(address_seed, Some(0))])
                .invoke(light_cpi_accounts)?;

            Ok(())
        }

        /// Updates an existing compressed account's message
        pub fn update_account<'info>(
            ctx: Context<'_, '_, '_, 'info, GenericAnchorAccounts<'info>>,
            proof: ValidityProof,
            current_account: MyCompressedAccount,
            account_meta: CompressedAccountMeta,
            new_message: String,
        ) -> Result<()> {
            let light_cpi_accounts = CpiAccounts::new(
                ctx.accounts.signer.as_ref(),
                ctx.remaining_accounts,
                crate::LIGHT_CPI_SIGNER,
            );

            let mut my_compressed_account = LightAccount::<MyCompressedAccount>::new_mut(
                &crate::ID,
                &account_meta,
                current_account,
            )?;

            my_compressed_account.message = new_message.clone();

            msg!(
                "Updated compressed account message to: {}",
                my_compressed_account.message
            );

            LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, proof)
                .with_light_account(my_compressed_account)?
                .invoke(light_cpi_accounts)?;

            Ok(())
        }
    }

    #[derive(Accounts)]
    pub struct GenericAnchorAccounts<'info> {
        #[account(mut)]
        pub signer: Signer<'info>,
    }

    #[event]
    #[derive(Clone, Debug, Default, LightDiscriminator)]
    pub struct MyCompressedAccount {
        pub owner: Pubkey,
        pub message: String,
    }```
    ````
  </Tab>

  <Tab title="Native Rust">
    <Info>
      Find the source code [here](https://github.com/Lightprotocol/program-examples/tree/main/basic-operations/native/programs/update).
    </Info>

    ```rust theme={null}
    #![allow(unexpected_cfgs)]

    #[cfg(any(test, feature = "test-helpers"))]
    pub mod test_helpers;

    use borsh::{BorshDeserialize, BorshSerialize};
    use light_macros::pubkey;
    use light_sdk::{
        account::sha::LightAccount,
        address::v2::derive_address,
        cpi::{
            v2::{CpiAccounts, LightSystemProgramCpi},
            CpiSigner, InvokeLightSystemProgram, LightCpiInstruction,
        },
        derive_light_cpi_signer,
        error::LightSdkError,
        instruction::{account_meta::CompressedAccountMeta, PackedAddressTreeInfo, ValidityProof},
        LightDiscriminator,
    };
    use light_sdk_types::ADDRESS_TREE_V2;
    use solana_program::{
        account_info::AccountInfo, entrypoint, program_error::ProgramError, pubkey::Pubkey,
    };

    pub const ID: Pubkey = pubkey!("2m6LXA7E6kMSkK6QHq2WCznD6kvhDcVFqEKpETKAQxYe");
    pub const LIGHT_CPI_SIGNER: CpiSigner =
        derive_light_cpi_signer!("2m6LXA7E6kMSkK6QHq2WCznD6kvhDcVFqEKpETKAQxYe");

    entrypoint!(process_instruction);

    #[repr(u8)]
    #[derive(Debug)]
    pub enum InstructionType {
        Create = 0,
        Update = 1,
    }

    impl TryFrom<u8> for InstructionType {
        type Error = LightSdkError;

        fn try_from(value: u8) -> Result<Self, Self::Error> {
            match value {
                0 => Ok(InstructionType::Create),
                1 => Ok(InstructionType::Update),
                _ => panic!("Invalid instruction discriminator."),
            }
        }
    }

    #[derive(
        Debug, Default, Clone, BorshSerialize, BorshDeserialize, LightDiscriminator,
    )]
    pub struct MyCompressedAccount {
        pub owner: Pubkey,
        pub message: String,
    }

    #[derive(BorshSerialize, BorshDeserialize)]
    pub struct CreateInstructionData {
        pub proof: ValidityProof,
        pub address_tree_info: PackedAddressTreeInfo,
        pub output_state_tree_index: u8,
        pub message: String,
    }

    #[derive(BorshSerialize, BorshDeserialize)]
    pub struct UpdateInstructionData {
        pub proof: ValidityProof,
        pub account_meta: CompressedAccountMeta,
        pub current_message: String,
        pub new_message: String,
    }

    pub fn process_instruction(
        program_id: &Pubkey,
        accounts: &[AccountInfo],
        instruction_data: &[u8],
    ) -> Result<(), ProgramError> {
        if program_id != &ID {
            return Err(ProgramError::IncorrectProgramId);
        }
        if instruction_data.is_empty() {
            return Err(ProgramError::InvalidInstructionData);
        }

        let discriminator = InstructionType::try_from(instruction_data[0])
            .map_err(|_| ProgramError::InvalidInstructionData)?;

        match discriminator {
            InstructionType::Create => {
                let instruction_data =
                    CreateInstructionData::try_from_slice(&instruction_data[1..])
                        .map_err(|_| ProgramError::InvalidInstructionData)?;
                create(accounts, instruction_data)
            }
            InstructionType::Update => {
                let instruction_data =
                    UpdateInstructionData::try_from_slice(&instruction_data[1..])
                        .map_err(|_| ProgramError::InvalidInstructionData)?;
                update(accounts, instruction_data)
            }
        }
    }

    pub fn create(
        accounts: &[AccountInfo],
        instruction_data: CreateInstructionData,
    ) -> Result<(), ProgramError> {
        let signer = accounts.first().ok_or(ProgramError::NotEnoughAccountKeys)?;

        let light_cpi_accounts = CpiAccounts::new(signer, &accounts[1..], LIGHT_CPI_SIGNER);

        let address_tree_pubkey = instruction_data
            .address_tree_info
            .get_tree_pubkey(&light_cpi_accounts)
            .map_err(|_| ProgramError::NotEnoughAccountKeys)?;

        if address_tree_pubkey.to_bytes() != ADDRESS_TREE_V2 {
            solana_program::msg!("Invalid address tree");
            return Err(ProgramError::InvalidAccountData);
        }

        let (address, address_seed) = derive_address(
            &[b"message", signer.key.as_ref()],
            &address_tree_pubkey,
            &ID,
        );

        let new_address_params = instruction_data
            .address_tree_info
            .into_new_address_params_assigned_packed(address_seed, Some(0));

        let mut my_compressed_account = LightAccount::<MyCompressedAccount>::new_init(
            &ID,
            Some(address),
            instruction_data.output_state_tree_index,
        );
        my_compressed_account.owner = *signer.key;
        my_compressed_account.message = instruction_data.message;

        LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, instruction_data.proof)
            .with_light_account(my_compressed_account)?
            .with_new_addresses(&[new_address_params])
            .invoke(light_cpi_accounts)?;

        Ok(())
    }

    pub fn update(
        accounts: &[AccountInfo],
        instruction_data: UpdateInstructionData,
    ) -> Result<(), ProgramError> {
        let signer = accounts.first().ok_or(ProgramError::NotEnoughAccountKeys)?;

        let light_cpi_accounts = CpiAccounts::new(signer, &accounts[1..], LIGHT_CPI_SIGNER);

        let mut my_compressed_account = LightAccount::<MyCompressedAccount>::new_mut(
            &ID,
            &instruction_data.account_meta,
            MyCompressedAccount {
                owner: *signer.key,
                message: instruction_data.current_message,
            },
        )?;

        // Update the account data with new message
        my_compressed_account.account.message = instruction_data.new_message;

        LightSystemProgramCpi::new_cpi(LIGHT_CPI_SIGNER, instruction_data.proof)
            .with_light_account(my_compressed_account)?
            .invoke(light_cpi_accounts)?;

        Ok(())
    }
    ```
  </Tab>
</Tabs>

# Next Steps

<CardGroup>
  <Card title="Build a client for your program" icon="chevron-right" href="/client-library/client-guide" />

  <Card title="Learn how to close compressed accounts" icon="chevron-right" href="/compressed-pdas/guides/how-to-close-compressed-accounts" />
</CardGroup>


# Overview & Program Template
Source: https://www.zkcompression.com/compressed-pdas/overview

Compressed PDAs provide full functionality of accounts at PDAs, without rent-exemption per account.

| Creation     | Regular PDA Account  | Compressed PDA  |
| :----------- | :------------------- | :-------------- |
| 100-byte PDA | \~1,600,000 lamports | 15,000 lamports |

Compressed PDAs are derived using a specific program address and seed, like regular PDAs. Custom programs invoke the <Tooltip>Light System program</Tooltip> to create and update accounts, instead of the System program.

#### Compressed PDAs at a Glance

<CardGroup>
  <Card title="Rent free PDAs">
    Create accounts at program-derived addresses without upfront rent exempt balance.
  </Card>

  <Card title="Full PDA Functionality">
    Persistent unique identification and program ownership.
  </Card>

  <Card title="Composable">
    CPI support between compressed and regular PDAs.
  </Card>
</CardGroup>

# Start Building

Developing with compressed PDAs works similar to regular PDAs and involves minimal setup:

<Steps>
  <Step>
    ### Prerequisites

    <Info>
      Required versions:

      * **Rust**: 1.86.0 or later
      * **Solana CLI**: 2.2.15
      * **Anchor CLI**: 0.31.1
      * **Zk compression CLI**: 0.27.0 or later
      * **Node.js**: 23.5.0 or later
    </Info>

    **Install Solana CLI:**

    ```bash theme={null}
    sh -c "$(curl -sSfL https://release.solana.com/v2.2.15/install)"
    ```

    **Install Anchor CLI:**

    ```bash theme={null}
    cargo install --git https://github.com/coral-xyz/anchor avm --force
    avm install latest
    avm use latest
    ```

    **Install the Light CLI:**

    <Tabs>
      <Tab title="npm">
        ```bash theme={null}
        npm install -g @lightprotocol/zk-compression-cli@beta
        ```
      </Tab>

      <Tab title="yarn">
        ```bash theme={null}
        yarn global add @lightprotocol/zk-compression-cli@beta
        ```
      </Tab>

      <Tab title="pnpm">
        ```bash theme={null}
        pnpm add -g @lightprotocol/zk-compression-cli@beta
        ```
      </Tab>
    </Tabs>

    **Verify installation:**

    ```bash theme={null}
    light --version
    ```
  </Step>

  <Step>
    ### Initialize your Program

    Instantiate a template Solana program with compressed accounts with all required dependencies.

    ```bash theme={null}
    light init testprogram
    ```

    <Info>
      The `light init` command creates only Anchor-based projects . For Pinocchio programs, manually configure dependencies using `light-sdk-pinocchio`.
    </Info>

    <Accordion title="Dependencies">
      **Rust Crates**

      * `light-sdk` - Core SDK for compressed accounts in native and anchor programs
      * `light-sdk-pinocchio` Core SDK for compressed accounts in pinocchio programs
      * `light-client` - RPC client and indexer for interacting with compressed accounts
      * `light-program-test` - Testing utilities for compressed programs.

      **TypeScript/JavaScript Packages**

      * `@lightprotocol/stateless.js` - Client library for interacting with compressed accounts
      * `@lightprotocol/zk-compression-cli` - Command-line tools for ZK compression development
    </Accordion>
  </Step>

  <Step>
    ### Build and Test

    Now `cd testprogram` and run:

    ```bash theme={null}
    anchor build
    # Success: Finished `release` profile [optimized] target(s), after compiling.
    # Note: Stack offset warnings are expected and don't prevent compilation
    ```

    ```bash theme={null}
    cargo test-sbf

    # Success: test result: ok. 1 passed; 0 failed; 0 ignored
    ```
  </Step>
</Steps>

## Common Errors

<Accordion title="assert.h file not found - during compilation.">
  ```shellscript theme={null}
  Fix:
  In your terminal, run:
  1. export CC=$(xcrun -find clang)
  2. export SDKROOT=$(xcrun --show-sdk-path)
  3. cargo clean
  4. anchor build


  Example log:
  The following warnings were emitted during compilation:

  warning: blake3@1.5.1: In file included from c/blake3_neon.c:1:
  warning: blake3@1.5.1: c/blake3_impl.h:4:10: fatal error: 'assert.h' file not found
  warning: blake3@1.5.1:     4 | #include <assert.h>
  warning: blake3@1.5.1:       |          ^~~~~~~~~~
  warning: blake3@1.5.1: 1 error generated.

  error: failed to run custom build command for `blake3 v1.5.1`

  Caused by:
    process didn't exit successfully: `/Users/you/testprogram/target/release/build/blake3-ac41d29c2eabe052/build-script-build` (exit status: 1)
    --- stdout
    cargo:rerun-if-env-changed=CARGO_FEATURE_PURE
    cargo:rerun-if-env-changed=CARGO_FEATURE_NO_NEON
    cargo:rerun-if-env-changed=CARGO_FEATURE_NEON
    cargo:rerun-if-env-changed=CARGO_FEATURE_NEON
    cargo:rerun-if-env-changed=CARGO_FEATURE_NO_NEON
    cargo:rerun-if-env-changed=CARGO_FEATURE_PURE
    cargo:rustc-cfg=blake3_neon
    OUT_DIR = Some(/Users/you/testprogram/target/release/build/blake3-735a4c71d985df30/out)
    TARGET = Some(aarch64-apple-darwin)
    OPT_LEVEL = Some(3)
    HOST = Some(aarch64-apple-darwin)
    cargo:rerun-if-env-changed=CC_aarch64-apple-darwin
    CC_aarch64-apple-darwin = None
    cargo:rerun-if-env-changed=CC_aarch64_apple_darwin
    CC_aarch64_apple_darwin = None
    cargo:rerun-if-env-changed=HOST_CC
    HOST_CC = None
    cargo:rerun-if-env-changed=CC
    CC = Some(/Users/you/.local/share/solana/install/releases/1.18.22/solana-release/bin/sdk/sbf/dependencies/platform-tools/llvm/bin/clang)
    RUSTC_WRAPPER = None
    cargo:rerun-if-env-changed=CC_ENABLE_DEBUG_OUTPUT
    cargo:rerun-if-env-changed=CRATE_CC_NO_DEFAULTS
    CRATE_CC_NO_DEFAULTS = None
    DEBUG = Some(false)
    cargo:rerun-if-env-changed=MACOSX_DEPLOYMENT_TARGET
    MACOSX_DEPLOYMENT_TARGET = None
    cargo:rerun-if-env-changed=CFLAGS_aarch64-apple-darwin
    CFLAGS_aarch64-apple-darwin = None
    cargo:rerun-if-env-changed=CFLAGS_aarch64_apple_darwin
    CFLAGS_aarch64_apple_darwin = None
    cargo:rerun-if-env-changed=HOST_CFLAGS
    HOST_CFLAGS = None
    cargo:rerun-if-env-changed=CFLAGS
    CFLAGS = None
    cargo:warning=In file included from c/blake3_neon.c:1:
    cargo:warning=c/blake3_impl.h:4:10: fatal error: 'assert.h' file not found
    cargo:warning=    4 | #include <assert.h>
    cargo:warning=      |          ^~~~~~~~~~
    cargo:warning=1 error generated.

    --- stderr


    error occurred: Command env -u IPHONEOS_DEPLOYMENT_TARGET "/Users/you/.local/share/solana/install/releases/1.18.22/solana-release/bin/sdk/sbf/dependencies/platform-tools/llvm/bin/clang" "-O3" "-ffunction-sections" "-fdata-sections" "-fPIC" "--target=arm64-apple-darwin" "-mmacosx-version-min=14.4" "-Wall" "-Wextra" "-std=c11" "-o" "/Users/you/testprogram/target/release/build/blake3-735a4c71d985df30/out/db3b6bfb95261072-blake3_neon.o" "-c" "c/blake3_neon.c" with args clang did not execute successfully (status code exit status: 1).
  ```
</Accordion>

## Program Examples

| Example                                                                                                        | Description                                                                                                                                                                                                                                                              |
| :------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [basic-operations/anchor](https://github.com/Lightprotocol/program-examples/tree/main/basic-operations/anchor) | Anchor programs to create, update, close, reinitialize and burn compressed accounts with Rust and TypeScript tests                                                                                                                                                       |
| [basic-operations/native](https://github.com/Lightprotocol/program-examples/tree/main/basic-operations/native) | Native Solana program implementation to create, update, close, reinitialize and burn compressed accounts with Rust tests                                                                                                                                                 |
| [Counter (Anchor)](https://github.com/Lightprotocol/program-examples/tree/main/counter/anchor)                 | Full compressed account lifecycle (create, increment, decrement, reset, close) using Anchor framework                                                                                                                                                                    |
| [Counter (Native)](https://github.com/Lightprotocol/program-examples/tree/main/counter/native)                 | Native Solana program implementation with Rust tests                                                                                                                                                                                                                     |
| [Counter (Pinocchio)](https://github.com/Lightprotocol/program-examples/tree/main/counter/pinocchio)           | Pinocchio implementation using light-sdk-pinocchio with Rust tests                                                                                                                                                                                                       |
| [Create-and-Update](https://github.com/Lightprotocol/program-examples/tree/main/create-and-update)             | Create new compressed accounts and update existing ones within a single instruction and one validity proof                                                                                                                                                               |
| [Read-Only](https://github.com/Lightprotocol/program-examples/tree/main/read-only)                             | Create compressed accounts and read them on-chain                                                                                                                                                                                                                        |
| [Account Comparison](https://github.com/Lightprotocol/program-examples/tree/main/account-comparison)           | Compare compressed accounts with standard Solana accounts                                                                                                                                                                                                                |
| [Nullifier Program](https://github.com/Lightprotocol/nullifier-program)                                        | For some use cases, such as sending payments, you might want to prevent your onchain instruction from being executed more than once. Creates a rent-free PDA derived from an id. If the id has been used before, the PDA already exists, causing the instruction to fail |
| [ZK-ID](https://github.com/Lightprotocol/program-examples/tree/main/zk-id)                                     | Program that uses zero-knowledge proofs for identity verification with compressed accounts                                                                                                                                                                               |

# Next Steps

<Card title="Build a client for your program." icon="chevron-right" href="/client-library/client-guide" />


# Program Examples
Source: https://www.zkcompression.com/compressed-pdas/program-examples

Program example repository for compressed accounts with tests.

## Basic Operations

* [**basic-operations/anchor**](https://github.com/Lightprotocol/program-examples/tree/main/basic-operations/anchor) - Anchor program with Rust and TypeScript tests
* [**basic-operations/native**](https://github.com/Lightprotocol/program-examples/tree/main/basic-operations/native) - Native Solana program with `light-sdk` and Rust tests.

<Info>
  Basic Operations include:

  * **create** - Initialize a new compressed account
  * **update** - Modify data of an existing compressed account
  * **close** - Close a compressed account (it can be initialized again).
  * **reinit** - Reinitialize a closed account
  * **burn** - Permanently delete a compressed account (it cannot be initialized again).
</Info>

## Counter Program

Full compressed account lifecycle (create, increment, decrement, reset, close):

* [**counter/anchor**](https://github.com/Lightprotocol/program-examples/tree/main/counter/anchor) - Anchor program with Rust and TypeScript tests
* [**counter/native**](https://github.com/Lightprotocol/program-examples/tree/main/counter/native) - Native Solana program with `light-sdk` and Rust tests.
* [**counter/pinocchio**](https://github.com/Lightprotocol/program-examples/tree/main/counter/pinocchio) - Pinocchio program with `light-sdk-pinocchio` and Rust tests.

## Create-and-update Program

* [**create-and-update**](https://github.com/Lightprotocol/program-examples/tree/main/create-and-update) - Create a new compressed account and update an existing compressed account with a single validity proof in one instruction.

## Create-and-read Program

* [**read-only**](https://github.com/Lightprotocol/program-examples/tree/main/read-only) - Create a new compressed account and read it on-chain.

## Compare Programs with Solana and Compressed Accounts

* [**account-comparison**](https://github.com/Lightprotocol/program-examples/tree/main/account-comparison) - Compare compressed vs regular Solana accounts.

## Nullifier Program

* [**nullifier-program**](https://github.com/Lightprotocol/nullifier-program) - For some use cases, such as sending payments, you might want to prevent your onchain instruction from being executed more than once. Creates a rent-free PDA derived from an id. If the id has been used before, the PDA already exists, causing the instruction to fail.

## Token Claim Reference Implementations

* **Basic**: [**simple-claim**](https://github.com/Lightprotocol/program-examples-airdrop-implementations/simple-claim) - Distributes compressed tokens that get decompressed to SPL on claim.
* **Advanced**: [**merkle-distributor**](https://github.com/Lightprotocol/distributor) - Distributes SPL tokens, uses compressed PDAs to track claims with linear vesting, partial claims, clawback and admin controls.

<Info>
  For simple client side distribution visit [this example](https://github.com/Lightprotocol/example-token-distribution).
</Info>

## ZK-ID Program

* [**zk-id**](https://github.com/Lightprotocol/program-examples/tree/main/zk-id) - A minimal Solana program that uses zero-knowledge proofs for identity verification with compressed accounts.

# Next Steps

<Card title="Follow our guides to these program examples." icon="chevron-right" href="/compressed-pdas/guides" />


# Solana Attestation Service (Devnet)
Source: https://www.zkcompression.com/compressed-pdas/solana-attestation-service

Build compressed attestations on Solana using ZK Compression. Currently undergoing audit.

View the examples: [Solana Attestation Service](https://github.com/solana-foundation/solana-attestation-service/tree/a8fb187978ecea0b165e63767c7e6b1c036e7b52/examples/typescript/attestation-flow-guides#readme)


# Add Wallet Support for Compressed Tokens
Source: https://www.zkcompression.com/compressed-tokens/advanced-guides/add-wallet-support-for-compressed-tokens

Guide to add Compressed Token Support to Your Wallet Application

<Note>
  Leading Solana Wallets like Phantom and Backpack already support compressed tokens.
</Note>

# Integration Steps

<Tabs>
  <Tab title="Code Snippets">
    ### Display Compressed Token Balances

    ```javascript theme={null}
    import { Rpc, createRpc } from '@lightprotocol/stateless.js';
    import { PublicKey } from '@solana/web3.js';

    const connection: Rpc = createRpc();
    const publicKey = new PublicKey('FWwR2s4TwpWN3nkCzVfhuPrpePG8kNzBXAxEbNsaDFNu');

    (async () => {
        const balances = await connection.getCompressedTokenBalancesByOwnerV2(publicKey);

        if (balances.value.items.length === 0) {
            console.log("No compressed token balances found");
            return;
        }

        for (const item of balances.value.items) {
            const balanceValue = typeof item.balance === 'string'
                ? parseInt(item.balance, 16)
                : item.balance;

            const mintInfo = await connection.getAccountInfo(new PublicKey(item.mint));
            const decimals = mintInfo.data[44];
            const formattedBalance = balanceValue / Math.pow(10, decimals);

            console.log(`Mint: ${item.mint}`);
            console.log(`Balance: ${formattedBalance} tokens\n`);
        }
    })();
    ```

    ### Get Transaction History

    ```typescript theme={null}
    import { Rpc, createRpc } from '@lightprotocol/stateless.js';
    import { PublicKey } from '@solana/web3.js';

    const connection: Rpc = createRpc();
    const publicKey = new PublicKey('FWwR2s4TwpWN3nkCzVfhuPrpePG8kNzBXAxEbNsaDFNu');

    (async () => {
        const signatures = await connection.getCompressionSignaturesForTokenOwner(publicKey);

        if (signatures.items.length > 0) {
            console.log(`Signatures:`);
            signatures.items.forEach((sig, index) => {
                console.log(`${index + 1}. ${sig.signature}`);
                console.log(`   Slot: ${sig.slot}`);
                console.log(`   Time: ${new Date(sig.blockTime * 1000).toISOString()}`);
            });
        } else {
            console.log("No transactions found");
        }
    })();
    ```

    <Accordion title="Get full transaction history on devnet or mainnet with getTransactionWithCompressionInfo">
      ```typescript theme={null}
      import { Rpc, createRpc } from '@lightprotocol/stateless.js';
      import { PublicKey } from '@solana/web3.js';

      const RPC_ENDPOINT = process.env.RPC_ENDPOINT || 'https://devnet.helius-rpc.com?api-key=<your-api-key>';

      const connection: Rpc = createRpc(RPC_ENDPOINT, RPC_ENDPOINT);
      const publicKey = new PublicKey('FWwR2s4TwpWN3nkCzVfhuPrpePG8kNzBXAxEbNsaDFNu');

      (async () => {
          try {
              const signatures = await connection.getCompressionSignaturesForTokenOwner(publicKey);

              if (signatures.items.length === 0) {
                  console.log("No transactions found");
                  return;
              }

              console.log(`Latest Transaction:`);
              console.log(`Signature: ${signatures.items[0].signature}`);
              console.log(`Slot: ${signatures.items[0].slot}`);

              const txInfo = await connection.getTransactionWithCompressionInfo(signatures.items[0].signature);

              if (!txInfo) {
                  console.log('Transaction not found or has no compression info');
                  return;
              }

              if (txInfo.compressionInfo) {
                  console.log(`\nClosed Accounts: ${txInfo.compressionInfo.closedAccounts.length}`);
                  console.log(`Opened Accounts: ${txInfo.compressionInfo.openedAccounts.length}`);
              }
          } catch (error) {
              console.error('Error fetching transaction history:', error);
          }
      })();
      ```
    </Accordion>

    ### Send Compressed Tokens

    ```typescript expandable theme={null}
    import {
      Rpc,
      createRpc,
      bn,
      dedupeSigner,
      sendAndConfirmTx,
      buildAndSignTx,
    } from "@lightprotocol/stateless.js";
    import {
      CompressedTokenProgram,
      selectMinCompressedTokenAccountsForTransfer,
    } from "@lightprotocol/compressed-token";
    import { ComputeBudgetProgram, Keypair, PublicKey } from "@solana/web3.js";

    const connection: Rpc = createRpc();
    const mint = new PublicKey("MINT_ADDRESS");
    const payer = PAYER_KEYPAIR;
    const owner = payer;
    const recipient = Keypair.generate();
    const amount = bn(1e8);

    (async () => {
      const compressedTokenAccounts =
        await connection.getCompressedTokenAccountsByOwner(owner.publicKey, { mint });

      if (compressedTokenAccounts.items.length === 0) {
        console.log("No compressed token accounts found");
        return;
      }

      const [inputAccounts] = selectMinCompressedTokenAccountsForTransfer(
        compressedTokenAccounts.items,
        amount
      );

      const proof = await connection.getValidityProof(
        inputAccounts.map((account) => account.compressedAccount.hash)
      );

      const ix = await CompressedTokenProgram.transfer({
        payer: payer.publicKey,
        inputCompressedTokenAccounts: inputAccounts,
        toAddress: recipient.publicKey,
        amount,
        recentInputStateRootIndices: proof.rootIndices,
        recentValidityProof: proof.compressedProof,
      });

      const { blockhash } = await connection.getLatestBlockhash();
      const additionalSigners = dedupeSigner(payer, [owner]);
      const signedTx = buildAndSignTx(
        [ComputeBudgetProgram.setComputeUnitLimit({ units: 300_000 }), ix],
        payer,
        blockhash,
        additionalSigners
      );

      const transferTxId = await sendAndConfirmTx(connection, signedTx);
      console.log(`Transaction: ${transferTxId}`);
    })();
    ```
  </Tab>

  <Tab title="End-to-End Guide">
    <Steps>
      <Step>
        ### Prerequisites

        Make sure you have dependencies and developer environment set up!

        <Accordion title="Prerequisites & Setup">
          **Dependencies**

          <Tabs>
            <Tab title="npm">
              ```bash theme={null}
              npm install @lightprotocol/stateless.js@beta \
                          @lightprotocol/compressed-token@beta
              ```
            </Tab>

            <Tab title="yarn">
              ```bash theme={null}
              yarn add @lightprotocol/stateless.js@beta \
                       @lightprotocol/compressed-token@beta
              ```
            </Tab>

            <Tab title="pnpm">
              ```bash theme={null}
              pnpm add @lightprotocol/stateless.js@beta \
                       @lightprotocol/compressed-token@beta
              ```
            </Tab>
          </Tabs>

          **Developer Environment**

          <Tabs>
            <Tab title="Localnet">
              By default, all guides use Localnet.

              <Tabs>
                <Tab title="npm">
                  ```bash theme={null}
                  npm install -g @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>

                <Tab title="yarn">
                  ```bash theme={null}
                  yarn global add @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>

                <Tab title="pnpm">
                  ```bash theme={null}
                  pnpm add -g @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>
              </Tabs>

              ```bash theme={null}
              # Start a local test validator
              light test-validator

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

              ```typescript theme={null}
              // 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();
              ```
            </Tab>

            <Tab title="Devnet">
              Replace `<your-api-key>` with your actual API key. [Get your API key here](https://www.helius.dev/zk-compression), if you don't have one yet.

              ```typescript theme={null}
              import { createRpc } from "@lightprotocol/stateless.js";

              const RPC_ENDPOINT = "https://devnet.helius-rpc.com?api-key=<your_api_key>";
              const connection = createRpc(RPC_ENDPOINT);

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

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

              main();
              ```
            </Tab>
          </Tabs>
        </Accordion>
      </Step>

      <Step>
        ### Display Compressed Token Balances

        This example fetches and displays all compressed token balances for a wallet address.

        ```javascript theme={null}
        import { Rpc, createRpc } from '@lightprotocol/stateless.js';
        import { Keypair, PublicKey } from '@solana/web3.js';
        import * as fs from 'fs';
        import * as os from 'os';

        const connection: Rpc = createRpc();

        const walletPath = `${os.homedir()}/.config/solana/id.json`;
        const secretKey = JSON.parse(fs.readFileSync(walletPath, 'utf8'));
        const payer = Keypair.fromSecretKey(Buffer.from(secretKey));

        (async () => {
            const balances = await connection.getCompressedTokenBalancesByOwnerV2(payer.publicKey);

            if (balances.value.items.length === 0) {
                console.log("No compressed token balances found");
                return;
            }

            for (const item of balances.value.items) {
                const balanceValue = typeof item.balance === 'string'
                    ? parseInt(item.balance, 16)
                    : item.balance;

                const mintInfo = await connection.getAccountInfo(new PublicKey(item.mint));
                const decimals = mintInfo.data[44];
                const formattedBalance = balanceValue / Math.pow(10, decimals);

                console.log(`Mint: ${item.mint}`);
                console.log(`Balance: ${formattedBalance} tokens\n`);
            }
        })();
        ```
      </Step>

      <Step>
        ### Get Transaction History

        This example retrieves compression transaction signatures to display transaction history of the wallet.

        ```javascript theme={null}
        import { Rpc, createRpc } from '@lightprotocol/stateless.js';
        import { Keypair } from '@solana/web3.js';
        import * as fs from 'fs';
        import * as os from 'os';

        const connection: Rpc = createRpc();

        const walletPath = `${os.homedir()}/.config/solana/id.json`;
        const secretKey = JSON.parse(fs.readFileSync(walletPath, 'utf8'));
        const payer = Keypair.fromSecretKey(Buffer.from(secretKey));

        (async () => {
            const signatures = await connection.getCompressionSignaturesForTokenOwner(payer.publicKey);

            if (signatures.items.length > 0) {
                console.log(`Signatures:`);
                signatures.items.forEach((sig, index) => {
                    console.log(`${index + 1}. ${sig.signature}`);
                    console.log(`   Slot: ${sig.slot}`);
                    console.log(`   Time: ${new Date(sig.blockTime * 1000).toISOString()}`);
                });
            } else {
                console.log("No transactions found");
            }
        })();
        ```
      </Step>

      <Step>
        ### Send Compressed Tokens

        First, set up a test mint to and mint 10 compressed tokens to your filesystem wallet.

        <Accordion title="Set up Test Mint">
          ```typescript theme={null}
          import { Keypair } from "@solana/web3.js";
          import { Rpc, confirmTx, createRpc } from '@lightprotocol/stateless.js';
          import { createMint, mintTo } from '@lightprotocol/compressed-token';
          import * as fs from 'fs';
          import * as os from 'os';

          // 1. Setup RPC connection and load filesystem wallet for mint operations
          // 2. Call createMint() to create SPL mint with token pool for compression
          // 3. Call mintTo() to mint compressed tokens to filesystem wallet

          const connection: Rpc = createRpc(); // defaults to localhost:8899

          // Load wallet from filesystem
          const walletPath = `${os.homedir()}/.config/solana/id.json`;
          const secretKey = JSON.parse(fs.readFileSync(walletPath, 'utf8'));
          const payer = Keypair.fromSecretKey(Buffer.from(secretKey));
          const mintKeypair = Keypair.generate();

          (async() => {
              // Fund payer with SOL
              await connection.requestAirdrop(payer.publicKey, 1e9);
              await new Promise(resolve => setTimeout(resolve, 1000));

              // Create SPL mint with token pool for compression
              const { mint, transactionSignature } = await createMint(
                  connection,
                  payer,
                  payer.publicKey, // mint authority
                  9,
                  mintKeypair,
              );
              console.log(`Mint address: ${mint.toString()}`);
              console.log(`Transaction: ${transactionSignature}`);

              // Mint compressed tokens to payer
              const mintToTxId = await mintTo(
                  connection,
                  payer,
                  mint, // SPL mint with token pool for compression
                  payer.publicKey, // recipient address
                  payer,
                  10e9,
              );

              console.log(`\nMinted ${10e9 / 1e9} compressed token`);
              console.log(`Transaction: ${mintToTxId}`);
          })();
          ```
        </Accordion>

        <Check>
          Make sure you add your Mint address to `send-tokens.ts`.
        </Check>

        ```typescript send-tokens.ts expandable theme={null}
        // Compressed Token Transfer - Local
        // 1. Load wallet and fetch compressed token accounts with getCompressedTokenAccountsByOwner()
        // 2. Select accounts for transfer using selectMinCompressedTokenAccountsForTransfer()
        //    and get validity proof with getValidityProof()
        // 3. Create transfer instruction with CompressedTokenProgram.transfer()
        //    and submit transaction with sendAndConfirmTx()
        // 4. Verify balances via getCompressedTokenAccountsByOwner()

        import {
          Rpc,
          createRpc,
          bn,
          dedupeSigner,
          sendAndConfirmTx,
          buildAndSignTx,
        } from "@lightprotocol/stateless.js";
        import {
          CompressedTokenProgram,
          selectMinCompressedTokenAccountsForTransfer,
        } from "@lightprotocol/compressed-token";
        import { ComputeBudgetProgram, Keypair, PublicKey } from "@solana/web3.js";
        import * as fs from 'fs';
        import * as os from 'os';

        // Step 1: Setup RPC connection and define transfer parameters
        const connection: Rpc = createRpc(); // defaults to localhost:8899
        const mint = new PublicKey("MINT ADDRESS"); // Replace with mint address

        // Load wallet from filesystem
        const walletPath = `${os.homedir()}/.config/solana/id.json`;
        const secretKey = JSON.parse(fs.readFileSync(walletPath, 'utf8'));
        const payer = Keypair.fromSecretKey(Buffer.from(secretKey));
        const owner = payer;

        const recipient = Keypair.generate();
        const amount = bn(1e8);

        (async () => {
          // Step 2: Fetch compressed account hashes from state trees
          const compressedTokenAccounts =
            await connection.getCompressedTokenAccountsByOwner(owner.publicKey, {
              mint, // SPL mint with token pool for compression
            });

          if (compressedTokenAccounts.items.length === 0) {
            console.log("No compressed token accounts found for this mint");
            return;
          }

          // Show initial sender balance
          const initialBalance = compressedTokenAccounts.items.reduce((sum, account) => sum + Number(account.parsed.amount), 0);
          console.log(`Sender balance: ${initialBalance / 1e8} compressed tokens`);

          // Step 3: Select minimum compressed accounts for transfer amount
          const [inputAccounts] = selectMinCompressedTokenAccountsForTransfer(
            compressedTokenAccounts.items,
            amount
          );

          // Get validity proof for Merkle tree verification
          const proof = await connection.getValidityProof(
            inputAccounts.map((account) => account.compressedAccount.hash)
          );

          // Step 4: Create transfer instruction that consumes input accounts and creates new output accounts
          const ix = await CompressedTokenProgram.transfer({
            payer: payer.publicKey,
            inputCompressedTokenAccounts: inputAccounts, // accounts to consume
            toAddress: recipient.publicKey,
            amount,
            recentInputStateRootIndices: proof.rootIndices,
            recentValidityProof: proof.compressedProof,
          });

          // Step 5: Build, sign, and submit transaction
          const { blockhash } = await connection.getLatestBlockhash();
          const additionalSigners = dedupeSigner(payer, [owner]);
          const signedTx = buildAndSignTx(
            [ComputeBudgetProgram.setComputeUnitLimit({ units: 300_000 }), ix],
            payer,
            blockhash,
            additionalSigners
          );
          const transferTxId = await sendAndConfirmTx(connection, signedTx);

          console.log(`\nTransferred ${amount.toNumber() / 1e8} compressed tokens`);
          console.log(`Transaction: ${transferTxId}`);
          console.log(`Recipient: ${recipient.publicKey.toString()}`);

          // Step 6: Verify via getCompressedTokenAccountsByOwner
          const senderCompressedAccounts = await connection.getCompressedTokenAccountsByOwner(payer.publicKey, { mint });
          const senderBalance = senderCompressedAccounts.items.reduce((sum, account) => sum + Number(account.parsed.amount), 0);

          const recipientCompressedAccounts = await connection.getCompressedTokenAccountsByOwner(recipient.publicKey, { mint });
          const recipientBalance = recipientCompressedAccounts.items.reduce((sum, account) => sum + Number(account.parsed.amount), 0);

          console.log(`\nSummary compressed token balances:`);
          console.log(`Sender balance: ${senderBalance / 1e8} compressed tokens`);
          console.log(`Recipient balance: ${recipientBalance / 1e8} compressed token`);

          return transferTxId;
        })();
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

# Advanced Integrations

Use these integrations to let users convert between regular and compressed format as needed.

<Accordion title="Decompress to Regular SPL">
  This example converts compressed tokens to regular SPL format using `CompressedTokenProgram.decompress().`

  ```javascript theme={null}
  import {
    bn,
    buildAndSignTx,
    sendAndConfirmTx,
    dedupeSigner,
    Rpc,
    createRpc,
  } from "@lightprotocol/stateless.js";
  import { ComputeBudgetProgram } from "@solana/web3.js";
  import {
    CompressedTokenProgram,
    getTokenPoolInfos,
    selectMinCompressedTokenAccountsForTransfer,
    selectTokenPoolInfosForDecompression,
  } from "@lightprotocol/compressed-token";

  // 1. Setup RPC connection and fetch compressed token accounts with getCompressedTokenAccountsByOwner()
  // 2. Select accounts and token pool infos using selectMinCompressedTokenAccountsForTransfer() and selectTokenPoolInfosForDecompression()
  // 3. Create decompress instruction with CompressedTokenProgram.decompress() and submit transaction

  // Step 1: Setup RPC connection and define decompression parameters
  const connection: Rpc = createRpc("https://mainnet.helius-rpc.com?api-key=<api_key>";);
  const payer = PAYER_KEYPAIR;
  const owner = PAYER_KEYPAIR;
  const mint = MINT_ADDRESS;
  const amount = 1e5; // 100K tokens to decompress

  (async () => {
    // 1. Fetch compressed token accounts
    const compressedTokenAccounts =
      await connection.getCompressedTokenAccountsByOwner(owner.publicKey, {
        mint,
      });

    // 2. Select
    const [inputAccounts] = selectMinCompressedTokenAccountsForTransfer(
      compressedTokenAccounts.items,
      bn(amount)
    );

    // 3. Fetch validity proof
    const proof = await connection.getValidityProof(
      inputAccounts.map((account) => account.compressedAccount.hash)
    );

    // 4. Fetch & Select tokenPoolInfos
    const tokenPoolInfos = await getTokenPoolInfos(connection, mint);
    const selectedTokenPoolInfos = selectTokenPoolInfosForDecompression(
      tokenPoolInfos,
      amount
    );

    // 5. Build instruction
    const ix = await CompressedTokenProgram.decompress({
      payer: payer.publicKey,
      inputCompressedTokenAccounts: inputAccounts,
      toAddress: owner.publicKey,
      amount,
      tokenPoolInfos: selectedTokenPoolInfos,
      recentInputStateRootIndices: proof.rootIndices,
      recentValidityProof: proof.compressedProof,
    });


    // 6. Sign, send, and confirm.
    // Example with keypair:
    const { blockhash } = await connection.getLatestBlockhash();
    const additionalSigners = dedupeSigner(payer, [owner]);
    const signedTx = buildAndSignTx(
      [ComputeBudgetProgram.setComputeUnitLimit({ units: 300_000 }), ix],
      payer,
      blockhash,
      additionalSigners
    );

    return await sendAndConfirmTx(connection, signedTx);
  })();
  ```
</Accordion>

<Accordion title="Compress Regular SPL Tokens">
  This example converts regular SPL tokens to compressed format using `CompressedTokenProgram.compress().`

  ```typescript theme={null}
  // 1. Setup RPC connection and get user ATA with getOrCreateAssociatedTokenAccount()
  // 2. Fetch state tree and token pool infos using getStateTreeInfos() and getTokenPoolInfos()
  // 3. Create compress instruction with CompressedTokenProgram.compress() and submit transaction


  import {
    buildAndSignTx,
    sendAndConfirmTx,
    Rpc,
    createRpc,
    selectStateTreeInfo,
  } from "@lightprotocol/stateless.js";
  import { ComputeBudgetProgram } from "@solana/web3.js";
  import {
    CompressedTokenProgram,
    getTokenPoolInfos,
    selectTokenPoolInfo,
  } from "@lightprotocol/compressed-token";
  import { getOrCreateAssociatedTokenAccount } from "@solana/spl-token";

  // Step 1: Setup RPC connection and define compression parameters
  const connection: Rpc = createRpc(
    "https://mainnet.helius-rpc.com?api-key=<api_key>"
  );
    const payer = <PAYER_KEYPAIR>;
    const mint = <MINT_ADDRESS>;
  const amount = 1e5; // 100K tokens to compress

  (async () => {
    // Step 2: Get or create associated token account for SPL tokens
    const sourceTokenAccount = await getOrCreateAssociatedTokenAccount(
      connection,
      payer, // fee payer
      mint, // token mint address
      payer.publicKey // token account owner
    );

    // Step 3: Fetch and select state tree info for compression
    const treeInfos = await connection.getStateTreeInfos();
    const treeInfo = selectStateTreeInfo(treeInfos);

    // Step 4: Fetch and select token pool info for compression
    const tokenPoolInfos = await getTokenPoolInfos(connection, mint);
    const tokenPoolInfo = selectTokenPoolInfo(tokenPoolInfos);

    // Step 5: Create compress instruction - transfer SPL tokens to pool and create compressed accounts
    const compressInstruction = await CompressedTokenProgram.compress({
      payer: payer.publicKey, // fee payer
      owner: payer.publicKey, // owner of source SPL tokens
      source: sourceTokenAccount.address, // source ATA address
      toAddress: payer.publicKey, // recipient of compressed tokens (self)
      amount, // amount to compress
      mint, // token mint address
      outputStateTreeInfo: treeInfo, // state tree for compressed accounts
      tokenPoolInfo, // token pool for compression
    });

    // Step 6: Build, sign, and submit compression transaction
    const { blockhash } = await connection.getLatestBlockhash();
    const tx = buildAndSignTx(
      [
        ComputeBudgetProgram.setComputeUnitLimit({ units: 300_000 }),
        compressInstruction,
      ],
      payer, // transaction signer
      blockhash,
      [payer] // additional signers
    );
    await sendAndConfirmTx(connection, tx);
  })();
  ```
</Accordion>

# Common Errors

<Accordion title="No compressed tokens found">
  If `getCompressedTokenBalancesByOwnerV2` returns empty:

  * Ensure the wallet has compressed tokens (not regular SPL tokens)
  * Verify you're on the correct network (devnet/mainnet)
</Accordion>

# Next Steps

<Card title="Create an Airdrop with Compressed Tokens." icon="chevron-right" href="/compressed-tokens/advanced-guides/airdrop" />


# Airdrop Guide with ZK Compression
Source: https://www.zkcompression.com/compressed-tokens/advanced-guides/airdrop

Complete client and program guides to create an airdrop – with or without code. ZK compression is the most efficient way to distribute SPL tokens.

<TokenAccountCompressedVsSpl />

***

<Tabs>
  <Tab title="Client Side Distribution">
    Choose your implementation based on your needs:

    | Tab                                   | Best For                   | What You'll Get                 | Time   |
    | :------------------------------------ | :------------------------- | :------------------------------ | :----- |
    | **Localnet Guide**                    | First-time users, learning | Step-by-step Localnet tutorial  | 20 min |
    | **Simple Airdrop**                    | \<10,000 recipients        | Production-ready single script  | 10 min |
    | **Airdrop with Batched Instructions** | 10,000+ recipients         | Batched system with retry logic | 15 min |

    <Info>
      Via Webapp you can use [Airship by Helius Labs](https://airship.helius.dev/) to airdrop to up to 200,000 recipients.
    </Info>

    <Tabs>
      <Tab title="Localnet Guide">
        <Check>
          **What you'll build:** A test airdrop sending compressed tokens to 3 recipients on your local validator.
        </Check>

        <Steps>
          <Step>
            ### Prerequisites

            Make sure you have dependencies and developer environment set up!

            <Info>
              System Requirements

              * **Node.js >= 20.18.0** (required by latest Solana packages)
              * npm or yarn package manager
            </Info>

            <Accordion title="Prerequisites & Setup">
              **Dependencies**

              <Tabs>
                <Tab title="npm">
                  ```bash theme={null}
                  npm install @lightprotocol/stateless.js@beta \
                              @lightprotocol/compressed-token@beta
                  ```
                </Tab>

                <Tab title="yarn">
                  ```bash theme={null}
                  yarn add @lightprotocol/stateless.js@beta \
                           @lightprotocol/compressed-token@beta
                  ```
                </Tab>

                <Tab title="pnpm">
                  ```bash theme={null}
                  pnpm add @lightprotocol/stateless.js@beta \
                           @lightprotocol/compressed-token@beta
                  ```
                </Tab>
              </Tabs>

              **Developer Environment**

              <Tabs>
                <Tab title="Localnet">
                  By default, all guides use Localnet.

                  <Tabs>
                    <Tab title="npm">
                      ```bash theme={null}
                      npm install -g @lightprotocol/zk-compression-cli@beta
                      ```
                    </Tab>

                    <Tab title="yarn">
                      ```bash theme={null}
                      yarn global add @lightprotocol/zk-compression-cli@beta
                      ```
                    </Tab>

                    <Tab title="pnpm">
                      ```bash theme={null}
                      pnpm add -g @lightprotocol/zk-compression-cli@beta
                      ```
                    </Tab>
                  </Tabs>

                  ```bash theme={null}
                  # Start a local test validator
                  light test-validator

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

                  ```typescript theme={null}
                  // 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();
                  ```
                </Tab>

                <Tab title="Devnet">
                  Replace `<your-api-key>` with your actual API key. [Get your API key here](https://www.helius.dev/zk-compression), if you don't have one yet.

                  ```typescript theme={null}
                  import { createRpc } from "@lightprotocol/stateless.js";

                  const RPC_ENDPOINT = "https://devnet.helius-rpc.com?api-key=<your_api_key>";
                  const connection = createRpc(RPC_ENDPOINT);

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

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

                  main();
                  ```
                </Tab>
              </Tabs>
            </Accordion>
          </Step>

          <Step>
            ### Mint SPL tokens to your wallet

            Run this `mint-spl-tokens.ts` to mint SPL tokens to your wallet.

            ```typescript mint-spl-tokens.ts expandable theme={null}
            // Mint SPL Tokens for Airdrop - LocalNet
            // 1. Load wallet and connect to local validator
            // 2. Create SPL mint with token pool for compression via createMint()
            // 3. Create ATA and mint SPL tokens to sender for airdrop preparation
            // 4. Output mint address for use in simple-airdrop.ts

            import { Keypair } from "@solana/web3.js";
            import { createRpc } from "@lightprotocol/stateless.js";
            import {
              createMint,
              getOrCreateAssociatedTokenAccount,
              mintTo,
            } from "@solana/spl-token";
            import { createTokenPool } from "@lightprotocol/compressed-token";
            import * as fs from 'fs';
            import * as os from 'os';

            // Step 1: Setup local connection and load wallet
            const connection = createRpc(); // defaults to localhost:8899

            // Load wallet from filesystem
            const walletPath = `${os.homedir()}/.config/solana/id.json`;
            const secretKey = JSON.parse(fs.readFileSync(walletPath, 'utf8'));
            const payer = Keypair.fromSecretKey(Buffer.from(secretKey));

            (async () => {
              // Step 2: Create SPL mint with token pool for compression
              const mint = await createMint(connection, payer, payer.publicKey, null, 9);
              const poolTxId = await createTokenPool(connection, payer, mint);
              console.log(`Mint address: ${mint.toBase58()}`);
              console.log(`TokenPool created: ${poolTxId}`);

              // Step 3: Create associated token account for sender
              // The sender will send tokens from this account to the recipients as compressed tokens.
              const ata = await getOrCreateAssociatedTokenAccount(
                connection,
                payer,
                mint, // SPL mint with token pool for compression
                payer.publicKey
              );
              console.log(`ATA address: ${ata.address.toBase58()}`);

              // Step 4: Mint SPL tokens to ATA.
              // The sender will send tokens from this account to the recipients as compressed tokens.
              const mintToTxId = await mintTo(
                connection,
                payer,
                mint, // SPL mint with token pool for compression
                ata.address, // distributor ATA
                payer.publicKey,
                100_000_000_000 // amount: 100 tokens with 9 decimals
              );
              console.log(`\nSPL tokens minted and ready for distribution!`);
              console.log(`Transaction: ${mintToTxId}`);

              console.log(`\nCopy mint address to your airdrop script: ${mint.toBase58()}`);
            })();
            ```
          </Step>

          <Step>
            ### Execute the Airdrop

            Next, distribute the SPL tokens to all recipients.

            <Warning>
              Ensure you have the latest `@lightprotocol/stateless.js` and `@lightprotocol/compressed-token` versions `≥ 0.21.0`!
            </Warning>

            ```typescript simple-airdrop.ts expandable highlight={29-30,45,74,100} theme={null}
            // Simple Airdrop - LocalNet
            // 1. Load wallet and select compression infrastructure with getStateTreeInfos() and getTokenPoolInfos()
            // 2. Build CompressedTokenProgram.compress() instruction for multiple recipients in one transaction
            // 3. Execute transaction with compute budget and confirm compression operation with sendAndConfirmTx()
            // 4. Verify distribution via getCompressedTokenAccountsByOwner

            import { Keypair, PublicKey, ComputeBudgetProgram } from "@solana/web3.js";
            import {
              CompressedTokenProgram,
              getTokenPoolInfos,
              selectTokenPoolInfo,
            } from "@lightprotocol/compressed-token";
            import {
              bn,
              buildAndSignTx,
              calculateComputeUnitPrice,
              createRpc,
              dedupeSigner,
              Rpc,
              selectStateTreeInfo,
              sendAndConfirmTx,
            } from "@lightprotocol/stateless.js";
            import { getOrCreateAssociatedTokenAccount } from "@solana/spl-token";
            import * as fs from 'fs';
            import * as os from 'os';

            // Step 1: Setup local connection and load wallet
            const connection: Rpc = createRpc(); // defaults to localhost:8899
            const mint = new PublicKey("MINTADDRESS"); // Replace with mint address from mint-spl-tokens.ts
            // Local uses file wallet. Use constants from .env file in production
            const walletPath = `${os.homedir()}/.config/solana/id.json`;
            const secretKey = JSON.parse(fs.readFileSync(walletPath, 'utf8'));
            const payer = Keypair.fromSecretKey(Buffer.from(secretKey));
            const owner = payer;

            (async () => {
              // Step 2: Select state tree and token pool
              const activeStateTrees = await connection.getStateTreeInfos();
              const treeInfo = selectStateTreeInfo(activeStateTrees);

              const infos = await getTokenPoolInfos(connection, mint);
              const info = selectTokenPoolInfo(infos);

              // Step 3: Get or create source token account for distribution
              // The sender will send tokens from this account to the recipients as compressed tokens.
              const sourceTokenAccount = await getOrCreateAssociatedTokenAccount(
                connection,
                payer,
                mint, // SPL mint with token pool for compression
                payer.publicKey
              );

              // Step 4: Define airdrop recipients and amounts
              const airDropAddresses = [
                Keypair.generate().publicKey,
                Keypair.generate().publicKey,
                Keypair.generate().publicKey,
              ];

              const amounts = [
                bn(20_000_000_000), // 20 tokens
                bn(30_000_000_000), // 30 tokens
                bn(40_000_000_000), // 40 tokens
              ];

              const totalAmount = amounts.reduce((sum, amt) => sum + amt.toNumber(), 0);
              console.log(`Distributing ${totalAmount / 1e9} compressed tokens to ${airDropAddresses.length} recipients`);

              const initialSplBalance = await connection.getTokenAccountBalance(sourceTokenAccount.address);
              console.log(`Sender initial balance: ${initialSplBalance.value.uiAmount} tokens`);

              // Step 5: Build transaction with compute budget and compression instruction
              const instructions = [];
              // Set compute unit limits based on recipient count (estimated 120k CU per recipient)
              instructions.push(
                ComputeBudgetProgram.setComputeUnitLimit({ units: 120_000 * airDropAddresses.length }),
                ComputeBudgetProgram.setComputeUnitPrice({
                  microLamports: calculateComputeUnitPrice(20_000, 120_000 * airDropAddresses.length), // dynamic priority fee
                })
              );

              // Create compression instruction for multiple recipients in one transaction
              const compressInstruction = await CompressedTokenProgram.compress({
                payer: payer.publicKey,
                owner: owner.publicKey,
                source: sourceTokenAccount.address, // source ATA holding SPL tokens
                toAddress: airDropAddresses, // recipient addresses for compressed tokens
                amount: amounts, // different amounts for each recipient
                mint, // SPL mint with token pool for compression
                tokenPoolInfo: info,
                outputStateTreeInfo: treeInfo, // destination state tree
              });
              instructions.push(compressInstruction);

              // Step 6: Sign and send transaction
              const additionalSigners = dedupeSigner(payer, [owner]);
              const { blockhash } = await connection.getLatestBlockhash();
              const tx = buildAndSignTx(instructions, payer, blockhash, additionalSigners);

              // For production: Add address lookup table to reduce transaction size and fees
              // const lookupTableAddress = new PublicKey("9NYFyEqPkyXUhkerbGHXUXkvb4qpzeEdHuGpgbgpH1NJ"); // mainnet // or "qAJZMgnQJ8G6vA3WRcjD9Jan1wtKkaCFWLWskxJrR5V" for devnet
              // const lookupTableAccount = (await connection.getAddressLookupTable(lookupTableAddress)).value!;
              // const tx = buildAndSignTx(instructions, payer, blockhash, additionalSigners, [lookupTableAccount]);
              const txId = await sendAndConfirmTx(connection, tx);

              console.log(`\nAirdrop completed!`);
              console.log(`Transaction: ${txId}`);

              // Step 7: Verify distribution via getCompressedTokenAccountsByOwner
              for (let i = 0; i &#x3C; airDropAddresses.length; i++) {
                const recipientAccounts = await connection.getCompressedTokenAccountsByOwner(airDropAddresses[i], { mint });
                const balance = recipientAccounts.items.reduce((sum, account) => sum + Number(account.parsed.amount), 0);
                console.log(`Recipient ${i + 1} (${airDropAddresses[i].toString()}): ${balance / 1e9} compressed tokens`);
              }

              const finalSplBalance = await connection.getTokenAccountBalance(sourceTokenAccount.address);
              console.log(`\nSender balance after airdrop: ${finalSplBalance.value.uiAmount} SPL tokens`);

              return txId;
            })();
            ```
          </Step>
        </Steps>
      </Tab>

      <Tab title="Simple Airdrop">
        <Check>
          For small airdrops (\<10,000 recipients). [View the source code here](https://github.com/Lightprotocol/example-token-distribution/blob/main/src/simple-airdrop/simple-airdrop.ts).
        </Check>

        <Steps>
          <Step>
            ### Environment Setup

            Configure your environment variables:

            ```bash .env theme={null}
            PAYER_KEYPAIR=YOUR_BASE58_ENCODED_PRIVATE_KEY
            MINT_ADDRESS=YOUR_MINT_ADDRESS
            ```
          </Step>

          <Step>
            ### Mint SPL Tokens

            Use your existing mint or mint SPL tokens to your wallet for distribution.

            ```typescript expandable theme={null}
            import { Rpc, createRpc } from '@lightprotocol/stateless.js';
            import { createMint } from '@lightprotocol/compressed-token';
            import {
                getOrCreateAssociatedTokenAccount,
                mintTo as mintToSpl,
            } from '@solana/spl-token';
            import { PAYER_KEYPAIR, RPC_ENDPOINT } from '../constants';

            const payer = PAYER_KEYPAIR;
            const connection: Rpc = createRpc(RPC_ENDPOINT);
            const decimals = 9;
            const mintAmount = 100;

            (async () => {
                // airdrop lamports to pay tx fees
                // await confirmTx(
                //   connection,
                //   await connection.requestAirdrop(payer.publicKey, 1e7)
                // );

                const { mint, transactionSignature } = await createMint(
                    connection,
                    payer,
                    payer.publicKey,
                    decimals,
                );
                console.log(
                    `create-mint success! txId: ${transactionSignature}, mint: ${mint.toBase58()}`,
                );

                const ata = await getOrCreateAssociatedTokenAccount(
                    connection,
                    payer,
                    mint,
                    payer.publicKey,
                );
                console.log(`ata: ${ata.address}`);

                const mintTxId = await mintToSpl(
                    connection,
                    payer,
                    mint,
                    ata.address,
                    payer.publicKey,
                    mintAmount,
                );
                console.log(`mint-spl success! txId: ${mintTxId}`);
            })();
            ```
          </Step>

          <Step>
            ### Execute Airdrop

            Run the airdrop script with your configured environment:

            ```typescript expandable theme={null}
            // 1. Load environment and select compression infrastructure with getStateTreeInfos() and getTokenPoolInfos()
            // 2. Build CompressedTokenProgram.compress() instruction for multiple recipients in one transaction
            // 3. Execute transaction with compute budget, address lookup table, and confirm with sendAndConfirmTx()
            // 4. Verify distribution via getCompressedTokenAccountsByOwner

            import {
                PublicKey,
                TransactionInstruction,
                ComputeBudgetProgram,
            } from '@solana/web3.js';
            import {
                CompressedTokenProgram,
                getTokenPoolInfos,
                selectTokenPoolInfo,
            } from '@lightprotocol/compressed-token';
            import {
                bn,
                buildAndSignTx,
                calculateComputeUnitPrice,
                createRpc,
                dedupeSigner,
                Rpc,
                selectStateTreeInfo,
                sendAndConfirmTx,
            } from '@lightprotocol/stateless.js';
            import { getOrCreateAssociatedTokenAccount } from '@solana/spl-token';
            import { MINT_ADDRESS, PAYER_KEYPAIR, RPC_ENDPOINT } from '../constants';

            (async () => {
                const connection: Rpc = createRpc(RPC_ENDPOINT);
                const mintAddress = MINT_ADDRESS;
                const payer = PAYER_KEYPAIR;
                const owner = payer;
                const recipients = [
                    PublicKey.default,
                    // ...
                ];

                // 1. Select a state tree
                const treeInfos = await connection.getStateTreeInfos(); // Fixed: removed deprecated getCachedActiveStateTreeInfos
                const treeInfo = selectStateTreeInfo(treeInfos);

                // 2. Select a token pool
                const tokenPoolInfos = await getTokenPoolInfos(connection, mintAddress);
                const tokenPoolInfo = selectTokenPoolInfo(tokenPoolInfos);

                // Create an SPL token account for the sender.
                // The sender will send tokens from this account to the recipients as compressed tokens.
                const sourceTokenAccount = await getOrCreateAssociatedTokenAccount(
                    connection,
                    payer,
                    mintAddress,
                    payer.publicKey,
                );

                // 1 recipient = 120_000 CU
                // 5 recipients = 170_000 CU
                const units = 120_000;
                const amount = bn(333);
                // To land faster, replace this with a dynamic fee based on network
                // conditions.
                const microLamports = calculateComputeUnitPrice(20_000, units);

                const instructions: TransactionInstruction[] = [
                    ComputeBudgetProgram.setComputeUnitLimit({ units }),
                    ComputeBudgetProgram.setComputeUnitPrice({
                        microLamports,
                    }),
                ];

                const compressInstruction = await CompressedTokenProgram.compress({
                    payer: payer.publicKey,
                    owner: owner.publicKey,
                    source: sourceTokenAccount.address,
                    toAddress: recipients,
                    amount: recipients.map(() => amount),
                    mint: mintAddress,
                    outputStateTreeInfo: treeInfo,
                    tokenPoolInfo,
                });
                instructions.push(compressInstruction);

                // https://www.zkcompression.com/developers/protocol-addresses-and-urls#lookup-tables
                const lookupTableAddress = new PublicKey(
                    '9NYFyEqPkyXUhkerbGHXUXkvb4qpzeEdHuGpgbgpH1NJ', // mainnet
                    // "qAJZMgnQJ8G6vA3WRcjD9Jan1wtKkaCFWLWskxJrR5V" // devnet
                );

                // Get the lookup table account state
                const lookupTableAccount = (
                    await connection.getAddressLookupTable(lookupTableAddress)
                ).value!;

                const additionalSigners = dedupeSigner(payer, [owner]);

                const { blockhash } = await connection.getLatestBlockhash();

                const tx = buildAndSignTx(
                    instructions,
                    payer,
                    blockhash,
                    additionalSigners,
                    [lookupTableAccount],
                );

                const txId = await sendAndConfirmTx(connection, tx);
                console.log(`txId: ${txId}`);
            })();
            ```
          </Step>
        </Steps>
      </Tab>

      <Tab title="Airdrop with Batched Instructions">
        <Check>
          For large-scale airdrops (10,000+ recipients) we recommend batched instructions.\
          [View the source code here.](https://github.com/Lightprotocol/example-token-distribution/tree/main/src/optimized-airdrop)
        </Check>

        <Info>
          This implementation creates the mint and executes the airdrop in a single operation. You only need to configure your RPC endpoint and payer keypair.
        </Info>

        <Steps>
          <Step>
            ### Create Instructions

            Process recipients in chunks and create batched instructions with optimized compute limits.

            ```typescript create-instructions.ts expandable theme={null}

            // 1. Process recipients in chunks with selectStateTreeInfo() and selectTokenPoolInfo() for each batch
            // 2. Create CompressedTokenProgram.compress() instructions with ComputeBudgetProgram limits for multiple recipients
            // 3. Return batched instructions for optimized large-scale airdrop execution

            import {
              CompressedTokenProgram,
              TokenPoolInfo,
            } from "@lightprotocol/compressed-token";
            import {
              bn,
              selectStateTreeInfo,
              StateTreeInfo,
            } from "@lightprotocol/stateless.js";
            import {
              ComputeBudgetProgram,
              TransactionInstruction,
              PublicKey,
            } from "@solana/web3.js";

            interface CreateAirdropInstructionsParams {
              amount: number | bigint;
              recipients: PublicKey[];
              payer: PublicKey;
              sourceTokenAccount: PublicKey;
              mint: PublicKey;
              stateTreeInfos: StateTreeInfo[];
              tokenPoolInfos: TokenPoolInfo[];
              maxRecipientsPerInstruction?: number;
              maxInstructionsPerTransaction?: number;
              computeUnitLimit?: number;
              computeUnitPrice?: number | undefined;
            }

            export type InstructionBatch = TransactionInstruction[];

            export async function createAirdropInstructions({
              amount,
              recipients,
              payer,
              sourceTokenAccount,
              mint,
              stateTreeInfos,
              tokenPoolInfos,
              maxRecipientsPerInstruction = 5,
              maxInstructionsPerTransaction = 3,
              computeUnitLimit = 500_000,
              computeUnitPrice = undefined,
            }: CreateAirdropInstructionsParams): Promise<InstructionBatch[]> {
              const instructionBatches: InstructionBatch[] = [];
              const amountBn = bn(amount.toString());

              // Process recipients in chunks
              for (
                let i = 0;
                i < recipients.length;
                i += maxRecipientsPerInstruction * maxInstructionsPerTransaction
              ) {
                const instructions: TransactionInstruction[] = [];

                instructions.push(
                  ComputeBudgetProgram.setComputeUnitLimit({ units: computeUnitLimit })
                );
                if (computeUnitPrice) {
                  instructions.push(
                    ComputeBudgetProgram.setComputeUnitPrice({
                      microLamports: computeUnitPrice,
                    })
                  );
                }

                const treeInfo = selectStateTreeInfo(stateTreeInfos);
                const tokenPoolInfo = selectTokenPoolInfo(tokenPoolInfos);

                for (let j = 0; j < maxInstructionsPerTransaction; j++) {
                  const startIdx = i + j * maxRecipientsPerInstruction;
                  const recipientBatch = recipients.slice(
                    startIdx,
                    startIdx + maxRecipientsPerInstruction
                  );

                  if (recipientBatch.length === 0) break;

                  const compressIx = await CompressedTokenProgram.compress({
                    payer,
                    owner: payer,
                    source: sourceTokenAccount,
                    toAddress: recipientBatch,
                    amount: recipientBatch.map(() => amountBn),
                    mint,
                    tokenPoolInfo,
                    outputStateTreeInfo: treeInfo,
                  });

                  instructions.push(compressIx);
                }

                if (
                  (computeUnitPrice && instructions.length > 2) ||
                  (!computeUnitPrice && instructions.length > 1)
                ) {
                  instructionBatches.push(instructions);
                }
              }

              return instructionBatches;
            }
            ```
          </Step>

          <Step>
            ### Update Blockhash

            Maintain fresh blockhashes with background refresh loop using `getLatestBlockhash()` every 30 seconds.

            ```typescript update-blockhash.ts expandable theme={null}
            import { Rpc } from "@lightprotocol/stateless.js";

            // 1. Fetch initial blockhash with getLatestBlockhash() and store in exported variable
            // 2. Set up background refresh loop with setTimeout() to update blockhash every 30 seconds
            // 3. Provide AbortSignal support to stop background updates when airdrop completes

            export let currentBlockhash: string;

            export async function updateBlockhash(
              connection: Rpc,
              signal: AbortSignal
            ): Promise<void> {
              try {
                const { blockhash } = await connection.getLatestBlockhash();
                currentBlockhash = blockhash;
                console.log(`Initial blockhash: ${currentBlockhash}`);
              } catch (error) {
                console.error("Failed to fetch initial blockhash:", error);
                return;
              }

              // Update blockhash in the background
              (function updateInBackground() {
                if (signal.aborted) return;
                const timeoutId = setTimeout(async () => {
                  if (signal.aborted) return;
                  try {
                    const { blockhash } = await connection.getLatestBlockhash();
                    currentBlockhash = blockhash;
                    console.log(`Updated blockhash: ${currentBlockhash}`);
                  } catch (error) {
                    console.error("Failed to update blockhash:", error);
                  }
                  updateInBackground();
                }, 30_000);

                signal.addEventListener("abort", () => clearTimeout(timeoutId));
              })();
            }
            ```
          </Step>

          <Step>
            ### Sign and Send

            Execute batched transactions with `VersionedTransaction`, retry logic, and `sendAndConfirmTx()` confirmation.

            ```typescript sign-and-send.ts expandable theme={null}

            // 1. Initialize blockhash updates with updateBlockhash() and get address lookup table with getAddressLookupTable()
            // 2. Process instruction batches with VersionedTransaction and retry logic for failed transactions
            // 3. Yield batch results with sendAndConfirmTx() confirmation and comprehensive error handling

            import { Rpc, sendAndConfirmTx } from "@lightprotocol/stateless.js";
            import {
              Keypair,
              PublicKey,
              TransactionMessage,
              VersionedTransaction,
            } from "@solana/web3.js";
            import { InstructionBatch } from "./create-instructions";
            import { currentBlockhash, updateBlockhash } from "./update-blockhash";
            import bs58 from "bs58";

            export enum BatchResultType {
              Success = "success",
              Error = "error",
            }

            export type BatchResult =
              | { type: BatchResultType.Success; index: number; signature: string }
              | { type: BatchResultType.Error; index: number; error: string };

            export async function* signAndSendAirdropBatches(
              batches: InstructionBatch[],
              payer: Keypair,
              connection: Rpc,
              maxRetries = 3
            ): AsyncGenerator<BatchResult> {
              const abortController = new AbortController();
              const { signal } = abortController;

              await updateBlockhash(connection, signal);

              const statusMap = new Array(batches.length).fill(0); // Initialize all as pending (0)

              // Use zk-compression look up table for your network
              // https://www.zkcompression.com/developers/protocol-addresses-and-urls#lookup-tables
              const lookupTableAddress = new PublicKey(
                "9NYFyEqPkyXUhkerbGHXUXkvb4qpzeEdHuGpgbgpH1NJ"
              );

              // Get the lookup table account
              const lookupTableAccount = (
                await connection.getAddressLookupTable(lookupTableAddress)
              ).value!;

              while (statusMap.includes(0)) {
                // Continue until all are confirmed or errored
                const pendingBatches = statusMap.filter((status) => status === 0).length;
                console.log(`Sending ${pendingBatches} transactions`);

                const sends = statusMap.map(async (status, index) => {
                  if (status !== 0) return; // Skip non-pending batches

                  let retries = 0;
                  while (retries < maxRetries && statusMap[index] === 0) {
                    if (!currentBlockhash) {
                      console.warn("Waiting for blockhash to be set...");
                      await new Promise((resolve) => setTimeout(resolve, 1000));
                      continue;
                    }

                    try {
                      const tx = new VersionedTransaction(
                        new TransactionMessage({
                          payerKey: payer.publicKey,
                          recentBlockhash: currentBlockhash,
                          instructions: batches[index],
                        }).compileToV0Message([lookupTableAccount])
                      );
                      tx.sign([payer]);

                      const sig = bs58.encode(tx.signatures[0]);
                      console.log(`Batch ${index} signature: ${sig}`);

                      const confirmedSig = await sendAndConfirmTx(connection, tx, {
                        skipPreflight: true,
                        commitment: "confirmed",
                      });

                      if (confirmedSig) {
                        statusMap[index] = 1; // Mark as confirmed
                        return {
                          type: BatchResultType.Success,
                          index,
                          signature: confirmedSig,
                        };
                      }
                    } catch (e) {
                      retries++;
                      console.warn(`Retrying batch ${index}, attempt ${retries + 1}`);
                      if (retries >= maxRetries) {
                        statusMap[index] = `err: ${(e as Error).message}`; // Mark as error
                        return {
                          type: BatchResultType.Error,
                          index,
                          error: (e as Error).message,
                        };
                      }
                    }
                  }
                });

                const results = await Promise.all(sends);
                for (const result of results) {
                  if (result) yield result as BatchResult;
                }
              }

              // Stop the blockhash update loop
              abortController.abort();
            }
            ```
          </Step>

          <Step>
            ### Main Airdrop File

            Put it all together in the main airdrop file.

            ```typescript airdrop.ts expandable theme={null}
            // 1. Create compressed mint with createMint(), mint supply with mintTo(), get infrastructure with getStateTreeInfos() and getTokenPoolInfos()
            // 2. Generate batched compression instructions with createAirdropInstructions() - create CompressedTokenProgram.compress() calls
            // 3. Execute batched airdrop with signAndSendAirdropBatches() - sign transactions and confirm with sendAndConfirmTx() for large-scale distribution

            import { Keypair, LAMPORTS_PER_SOL, PublicKey } from "@solana/web3.js";
            import {
              calculateComputeUnitPrice,
              createRpc,
              Rpc,
            } from "@lightprotocol/stateless.js";
            import { createMint, getTokenPoolInfos } from "@lightprotocol/compressed-token";
            import { getOrCreateAssociatedTokenAccount, mintTo } from "@solana/spl-token";
            import { createAirdropInstructions } from "./create-instructions";
            import { BatchResultType, signAndSendAirdropBatches } from "./sign-and-send";
            import dotenv from "dotenv";
            import bs58 from "bs58";
            dotenv.config();

            // Step 1: Setup environment and RPC connection
            const RPC_ENDPOINT = `https://mainnet.helius-rpc.com?api-key=${process.env.HELIUS_API_KEY}`;
            const connection: Rpc = createRpc(RPC_ENDPOINT);
            const PAYER = Keypair.fromSecretKey(bs58.decode(process.env.PAYER_KEYPAIR!));

            // Step 2: Define airdrop recipient list (20 example addresses)
            const recipients = [
              "GMPWaPPrCeZPse5kwSR3WUrqYAPrVZBSVwymqh7auNW7",
              "GySGrTgPtPfMtYoYTmwUdUDFwVJbFMfip7QZdhgXp8dy",
              "Bk1r2vcgX2uTzwV3AUyfRbSfGKktoQrQufBSrHzere74",
              "8BvkadZ6ycFNmQF7S1MHRvEVNb1wvDBFdjkAUnxjK9Ug",
              "EmxcvFKXsWLzUho8AhV9LCKeKRFHg5gAs4sKNJwhe5PF",
              "6mqdHkSpcvNexmECjp5XLt9V9KnSQre9TvbMLGr6sEPM",
              "3k4MViTWXBjFvoUZiJcNGPvzrqnTa41gcrbWCMMnV6ys",
              "2k6BfYRUZQHquPtpkyJpUx3DzM7W3K6H95igtJk8ztpd",
              "89jPyNNLCcqWn1RZThSS4jSqU5VCJkR5mAaSaVzuuqH4",
              "3MzSRLf9jSt6d1MFFMMtPfUcDY6XziRxTB8C5mfvgxXG",
              "9A1H6f3N8mpAPSdfqvYRD4cM1NwDZoMe3yF5DwibL2R2",
              "PtUAhLvUsVcoesDacw198SsnMoFNVskR5pT3QvsBSQw",
              "6C6W6WpgFK8TzTTMNCPMz2t9RaMs4XnkfB6jotrWWzYJ",
              "8sLy9Jy8WSh6boq9xgDeBaTznn1wb1uFpyXphG3oNjL5",
              "GTsQu2XCgkUczigdBFTWKrdDgNKLs885jKguyhkqdPgV",
              "85UK4bjC71Jwpyn8mPSaW3oYyEAiHPbESByq9s5wLcke",
              "9aEJT4CYHEUWwwSQwueZc9EUjhWSLD6AAbpVmmKDeP7H",
              "CY8QjRio1zd9bYWMKiVRrDbwVenf3JzsGf5km5zLgY9n",
              "CeHbdxgYifYhpB6sXGonKzmaejqEfq2ym5utTmB6XMVv",
              "4z1qss12DjUzGUkK1fFesqrUwrEVJJvzPMNkwqYnbAR5",
            ].map((address) => new PublicKey(address));

            (async () => {
              // Step 3: Create compressed mint and register for compression
              // 3a: Call createMint() to initialize mint with compression pool
              const { mint, transactionSignature } = await createMint(
                connection,
                PAYER, // fee payer
                PAYER.publicKey, // mint authority
                9 // decimals
              );
              console.log(
                `create-mint success! txId: ${transactionSignature}, mint: ${mint.toBase58()}`
              );

              // Step 4: Create associated token account for distributor
              // 4a: Ensure PAYER has ATA for holding tokens before compression
              const ata = await getOrCreateAssociatedTokenAccount(
                connection,
                PAYER, // fee payer
                mint, // token mint
                PAYER.publicKey // token owner
              );
              console.log(`ATA: ${ata.address.toBase58()}`);

              // Step 5: Mint initial token supply to distributor
              // 5a: Create 10 billion tokens in the ATA for airdrop distribution
              const mintToTxId = await mintTo(
                connection,
                PAYER, // fee payer and mint authority
                mint, // token mint
                ata.address, // destination ATA
                PAYER.publicKey, // mint authority
                10e9 * LAMPORTS_PER_SOL // amount: 10 billion tokens with decimals
              );
              console.log(`mint-to success! txId: ${mintToTxId}`);

              // Step 6: Get compression infrastructure for batch operations
              // 6a: Fetch available state trees for compressed account storage
              const stateTreeInfos = await connection.getStateTreeInfos();

              // 6b: Get token pool infos for compression operations
              const tokenPoolInfos = await getTokenPoolInfos(connection, mint);

              // Step 7: Create instruction batches for large-scale airdrop
              // 7a: Generate batched compression instructions with compute optimization
              const instructionBatches = await createAirdropInstructions({
                amount: 1e6, // 1 million tokens per recipient
                recipients, // array of recipient addresses
                payer: PAYER.publicKey, // transaction fee payer
                sourceTokenAccount: ata.address, // source ATA holding SPL tokens
                mint, // token mint
                stateTreeInfos, // state trees for compressed accounts
                tokenPoolInfos, // token pools for compression
                computeUnitPrice: calculateComputeUnitPrice(10_000, 500_000), // dynamic priority fee
              });

              // Step 8: Execute batched airdrop with error handling
              // 8a: Process instruction batches with retry logic and confirmation
              for await (const result of signAndSendAirdropBatches(
                instructionBatches,
                PAYER,
                connection
              )) {
                if (result.type === BatchResultType.Success) {
                  console.log(`Batch ${result.index} confirmed: ${result.signature}`);
                } else if (result.type === BatchResultType.Error) {
                  console.log(`Batch ${result.index} failed: ${result.error}`);
                  // Use result.index to access the specific batch in instructionBatches
                  const failedBatch = instructionBatches[result.index];
                  console.log(`Failed batch instructions:`, failedBatch);
                  // Additional logic to handle failed instructions
                }
              }

              console.log("Airdrop process complete.");
            })();
            ```
          </Step>
        </Steps>
      </Tab>
    </Tabs>

    # Advanced Features

    <Info>
      Solana Wallets like Phantom and Backpack already support compressed tokens.
      Still, you can let users decompress to SPL via your Frontend to customize claims.
    </Info>

    Add decompression of SPL Tokens with this script.

    ```typescript expandable theme={null}
    import {
      bn,
      buildAndSignTx,
      sendAndConfirmTx,
      dedupeSigner,
      Rpc,
      createRpc,
    } from "@lightprotocol/stateless.js";
    import { ComputeBudgetProgram, Keypair, PublicKey } from "@solana/web3.js";
    import {
      CompressedTokenProgram,
      getTokenPoolInfos,
      selectMinCompressedTokenAccountsForTransfer,
      selectTokenPoolInfosForDecompression,
    } from "@lightprotocol/compressed-token";
    import { getOrCreateAssociatedTokenAccount } from "@solana/spl-token";
    import bs58 from "bs58";
    import dotenv from "dotenv";
    dotenv.config();

    // Set these values in your .env file
    const RPC_ENDPOINT = process.env.RPC_ENDPOINT;
    const mint = new PublicKey(process.env.MINT_ADDRESS!);
    const payer = Keypair.fromSecretKey(bs58.decode(process.env.PAYER_KEYPAIR!));

    const owner = payer;
    const amount = 1e5;
    const connection: Rpc = createRpc(RPC_ENDPOINT);

    (async () => {
      // 1. Create an associated token account for the user if it doesn't exist
      const ata = await getOrCreateAssociatedTokenAccount(
        connection,
        payer,
        mint,
        payer.publicKey
      );

      // 2. Fetch compressed token accounts
      const compressedTokenAccounts =
        await connection.getCompressedTokenAccountsByOwner(owner.publicKey, {
          mint,
        });

      // 3. Select
      const [inputAccounts] = selectMinCompressedTokenAccountsForTransfer(
        compressedTokenAccounts.items,
        bn(amount)
      );

      // 4. Fetch validity proof
      const proof = await connection.getValidityProof(
        inputAccounts.map((account) => account.compressedAccount.hash)
      );

      // 5. Fetch token pool infos
      const tokenPoolInfos = await getTokenPoolInfos(connection, mint);

      // 6. Select
      const selectedTokenPoolInfos = selectTokenPoolInfosForDecompression(
        tokenPoolInfos,
        amount
      );

      // 7. Build instruction
      const ix = await CompressedTokenProgram.decompress({
        payer: payer.publicKey,
        inputCompressedTokenAccounts: inputAccounts,
        toAddress: ata.address,
        amount,
        tokenPoolInfos: selectedTokenPoolInfos,
        recentInputStateRootIndices: proof.rootIndices,
        recentValidityProof: proof.compressedProof,
      });

      // 8. Sign, send, and confirm
      const { blockhash } = await connection.getLatestBlockhash();
      const additionalSigners = dedupeSigner(payer, [owner]);
      const signedTx = buildAndSignTx(
        [ComputeBudgetProgram.setComputeUnitLimit({ units: 300_000 }), ix],
        payer,
        blockhash,
        additionalSigners
      );
      return await sendAndConfirmTx(connection, signedTx);
    })();

    ```

    <Tip>
      Set priority fees dynamically for decompression. Learn more [here](https://docs.helius.dev/guides/sending-transactions-on-solana#summary).
    </Tip>

    ### Native Swap via Jup-API

    If you have a custom FE, you can let users swap compressed tokens using the Jup-API. A reference implementation is available [here](https://github.com/Lightprotocol/example-jupiter-swap-node).

    ## Next Steps

    <Card title="Create an airdrop with claim functionality." icon="chevron-right" href="#claim-reference-implementations" />
  </Tab>

  <Tab title="Claim Reference Implementations">
    Customize token distribution and let users claim.

    |                | distributor    | simple-claim    |
    | -------------- | -------------- | --------------- |
    | Vesting        | Linear Vesting | Cliff at Slot X |
    | Partial claims | Yes            | No              |
    | Clawback       | Yes            | No              |
    | Frontend       | REST API + CLI | None            |

    <Info>
      The programs are reference implementations and should be audited before production use.
    </Info>

    <CardGroup>
      <Card title="Merkle Distributor" icon="parachute-box" href="https://github.com/Lightprotocol/distributor">
        Merkle distributor based on jito airdrop and optimized with rent-free PDAs.
      </Card>

      <Card title="Simple Airdrop with Claim" icon="hand-holding" href="https://github.com/Lightprotocol/program-examples/tree/main/airdrop-implementations/simple-claim">
        Simple SPL token airdrop with claim.
      </Card>
    </CardGroup>
  </Tab>
</Tabs>


# Example Token Distribution
Source: https://www.zkcompression.com/compressed-tokens/advanced-guides/example-token-distribution

Reference implementations for airdrops, payments, and rewards with ZK Compression

View the full example on GitHub: [example-token-distribution](https://github.com/Lightprotocol/example-token-distribution)


# Combine Instructions in One Transaction
Source: https://www.zkcompression.com/compressed-tokens/advanced-guides/how-to-combine-operations-in-one-transaction

Guide to combine multiple instructions in a single transaction. Full code example for token pool creation and for first-time compression of existing SPL tokens.

The SDK provides instruction-level APIs that return instructions without sending transactions. Combine these instructions to build custom transactions with multiple instructions.

<Note>
  This guide demonstrates creating a token pool and compressing existing SPL tokens in a single transaction.
</Note>

# Full Code Example

<Steps>
  <Step>
    ### Prerequisites

    Make sure you have dependencies and developer environment set up!

    <Accordion title="Prerequisites & Setup">
      **Dependencies**

      <Tabs>
        <Tab title="npm">
          ```bash theme={null}
          npm install @lightprotocol/stateless.js@beta \
                      @lightprotocol/compressed-token@beta
          ```
        </Tab>

        <Tab title="yarn">
          ```bash theme={null}
          yarn add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```
        </Tab>

        <Tab title="pnpm">
          ```bash theme={null}
          pnpm add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```
        </Tab>
      </Tabs>

      **Developer Environment**

      <Tabs>
        <Tab title="Localnet">
          By default, all guides use Localnet.

          <Tabs>
            <Tab title="npm">
              ```bash theme={null}
              npm install -g @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>

            <Tab title="yarn">
              ```bash theme={null}
              yarn global add @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>

            <Tab title="pnpm">
              ```bash theme={null}
              pnpm add -g @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>
          </Tabs>

          ```bash theme={null}
          # Start a local test validator
          light test-validator

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

          ```typescript theme={null}
          // 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();
          ```
        </Tab>

        <Tab title="Devnet">
          Replace `<your-api-key>` with your actual API key. [Get your API key here](https://www.helius.dev/zk-compression), if you don't have one yet.

          ```typescript theme={null}
          import { createRpc } from "@lightprotocol/stateless.js";

          const RPC_ENDPOINT = "https://devnet.helius-rpc.com?api-key=<your_api_key>";
          const connection = createRpc(RPC_ENDPOINT);

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

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

          main();
          ```
        </Tab>
      </Tabs>
    </Accordion>
  </Step>

  <Step>
    ### Create Token Pool + Compress

    ```typescript create-pool-and-compress.ts highlight={26,71} expandable theme={null}
    // 1. Setup: Create regular SPL token and mint to ATA
    // 2. Build instructions for create token pool and compress
    // 3. Combine instructions in one transaction
    // 4. Verify compressed balance

    import {
        Keypair,
        ComputeBudgetProgram,
    } from '@solana/web3.js';
    import {
        createRpc,
        buildAndSignTx,
        sendAndConfirmTx,
        selectStateTreeInfo,
    } from '@lightprotocol/stateless.js';
    import { CompressedTokenProgram } from '@lightprotocol/compressed-token';
    import {
        createMint,
        getOrCreateAssociatedTokenAccount,
        mintTo,
        TOKEN_PROGRAM_ID,
    } from '@solana/spl-token';
    import BN from 'bn.js';

    async function createPoolAndCompress() {
        // Step 1: Setup - Create regular SPL token and mint to ATA
        const rpc = createRpc();
        const payer = Keypair.generate();
        const airdropSignature = await rpc.requestAirdrop(payer.publicKey, 1000000000);
        await rpc.confirmTransaction(airdropSignature);

        // Create regular SPL token mint
        const mint = await createMint(
            rpc,
            payer,
            payer.publicKey,
            null,
            9,
            undefined,
            undefined,
            TOKEN_PROGRAM_ID
        );

        // Create ATA and mint tokens to it
        const ata = await getOrCreateAssociatedTokenAccount(
            rpc,
            payer,
            mint,
            payer.publicKey,
            undefined,
            undefined,
            undefined,
            TOKEN_PROGRAM_ID
        );

        await mintTo(
            rpc,
            payer,
            mint,
            ata.address,
            payer,
            1_000_000_000, // 1 token with 9 decimals
            undefined,
            undefined,
            TOKEN_PROGRAM_ID
        );

        console.log("Regular SPL token created:", mint.toBase58());
        console.log("ATA balance:", 1, "token");

        // Step 2: Build instructions for create token pool and compress
        const outputStateTreeInfo = selectStateTreeInfo(await rpc.getStateTreeInfos());

        // Derive token pool PDA
        const tokenPoolPda = CompressedTokenProgram.deriveTokenPoolPda(mint);

        // Create token pool instruction
        const createTokenPoolIx = await CompressedTokenProgram.createTokenPool({
            feePayer: payer.publicKey,
            mint,
            tokenProgram: TOKEN_PROGRAM_ID,
        });

        // Manually construct TokenPoolInfo for first-time compression
        const tokenPoolInfo = {
            mint: mint,
            tokenPoolPda: tokenPoolPda,
            tokenProgram: TOKEN_PROGRAM_ID,
            isInitialized: true, // Set to true even though pool will be created in this tx
            balance: new BN(0),
            poolIndex: 0,
            bump: 0, // Placeholder value
        };

        // Create compress instruction
        const compressIx = await CompressedTokenProgram.compress({
            outputStateTreeInfo,
            tokenPoolInfo,
            payer: payer.publicKey,
            owner: payer.publicKey,
            source: ata.address,
            toAddress: payer.publicKey,
            amount: new BN(1_000_000_000),
            mint,
        });

        // Step 3: Combine instructions in one transaction
        const { blockhash } = await rpc.getLatestBlockhash();

        const allInstructions = [
            ComputeBudgetProgram.setComputeUnitLimit({ units: 1_000_000 }),
            createTokenPoolIx,
            compressIx,
        ];

        const tx = buildAndSignTx(
            allInstructions,
            payer,
            blockhash,
            []
        );

        const txId = await sendAndConfirmTx(rpc, tx);

        console.log("Token pool created and tokens compressed");
        console.log("Transaction:", txId);

        // Step 4: Verify compressed balance
        const compressedAccounts = await rpc.getCompressedTokenAccountsByOwner(
            payer.publicKey,
            { mint }
        );

        const compressedBalance = compressedAccounts.items.reduce(
            (sum, account) => sum.add(account.parsed.amount),
            new BN(0)
        );

        console.log("Compressed balance:", compressedBalance.toNumber() / 1_000_000_000, "tokens");

        return {
            transactionSignature: txId,
            mint,
            compressedBalance: compressedBalance.toNumber(),
        };
    }

    createPoolAndCompress().catch(console.error);
    ```
  </Step>
</Steps>

# Next Steps

<Card title="Create an Airdrop with Compressed Tokens." icon="chevron-right" href="/compressed-tokens/advanced-guides/airdrop" />


# Use Token-2022 with Compression
Source: https://www.zkcompression.com/compressed-tokens/advanced-guides/use-token-2022-with-compression

Complete guide to mint, compress and transfer tokens with Token-2022 Metadata with ZK Compression.

# What you will do

With this guide you will mint, compress, and transfer tokens with Token-2022 Metadata.

# Overview Token 2022 Extensions

Token 2022 Extensions are optional features that can be added to Token 2022 mints on Solana to enable additional functionality.

ZK Compression supports compressing the following mint-extensions:

* MetadataPointer
* TokenMetadata
* InterestBearingConfig
* GroupPointer
* GroupMemberPointer
* TokenGroup
* TokenGroupMember

All other extensions are not yet supported.

<Info>
  If you require support for other mint-extensions, [let us know](https://t.me/swen_light)!
</Info>

# Get started

<Steps>
  <Step title="Prerequisites">
    <Info>
      You need the following SDK versions:

      * `@lightprotocol/stateless.js` ≥ 0.21.0
      * `@lightprotocol/compressed-token` ≥ 0.21.0
      * `@solana/web3.js` ≥ 1.95.3
    </Info>

    Make sure you have dependencies and developer environment set up!

    <Accordion title="Prerequisites & Setup">
      **Dependencies**

      <Tabs>
        <Tab title="npm">
          ```bash theme={null}
          npm install @lightprotocol/stateless.js@beta \
                      @lightprotocol/compressed-token@beta
          ```
        </Tab>

        <Tab title="yarn">
          ```bash theme={null}
          yarn add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```
        </Tab>

        <Tab title="pnpm">
          ```bash theme={null}
          pnpm add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```
        </Tab>
      </Tabs>

      **Developer Environment**

      <Tabs>
        <Tab title="Localnet">
          By default, all guides use Localnet.

          <Tabs>
            <Tab title="npm">
              ```bash theme={null}
              npm install -g @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>

            <Tab title="yarn">
              ```bash theme={null}
              yarn global add @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>

            <Tab title="pnpm">
              ```bash theme={null}
              pnpm add -g @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>
          </Tabs>

          ```bash theme={null}
          # Start a local test validator
          light test-validator

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

          ```typescript theme={null}
          // 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();
          ```
        </Tab>

        <Tab title="Devnet">
          Replace `<your-api-key>` with your actual API key. [Get your API key here](https://www.helius.dev/zk-compression), if you don't have one yet.

          ```typescript theme={null}
          import { createRpc } from "@lightprotocol/stateless.js";

          const RPC_ENDPOINT = "https://devnet.helius-rpc.com?api-key=<your_api_key>";
          const connection = createRpc(RPC_ENDPOINT);

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

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

          main();
          ```
        </Tab>
      </Tabs>
    </Accordion>
  </Step>

  <Step title="Mint, compress, and transfer tokens with Token-2022 Metadata">
    Run `compress-t22.ts`.

    ```typescript compress-t22.ts expandable theme={null}
    // Token-2022 with ZK Compression - Local
    // 1. Load wallet and connect to local validator
    // 2. Create Token-2022 mint with metadata extension and register for compression via createTokenPool()
    // 3. Mint SPL tokens to ATA, compress via compress(), and transfer compressed tokens via transfer()
    // 4. Verify balances via getTokenAccountBalance and getCompressedTokenAccountsByOwner

    import { confirmTx, createRpc } from "@lightprotocol/stateless.js";
    import {
      compress,
      createTokenPool,
      transfer,
    } from "@lightprotocol/compressed-token";
    import {
      getOrCreateAssociatedTokenAccount,
      mintTo as mintToSpl,
      TOKEN_2022_PROGRAM_ID,
      createInitializeMetadataPointerInstruction,
      createInitializeMintInstruction,
      ExtensionType,
      getMintLen,
      LENGTH_SIZE,
      TYPE_SIZE,
    } from "@solana/spl-token";
    import {
      Keypair,
      sendAndConfirmTransaction,
      SystemProgram,
      Transaction,
    } from "@solana/web3.js";
    import {
      createInitializeInstruction,
      pack,
      TokenMetadata,
    } from "@solana/spl-token-metadata";

    // Step 1: Setup local connection and load wallet
    import * as fs from 'fs';
    import * as os from 'os';

    const walletPath = `${os.homedir()}/.config/solana/id.json`;
    const secretKey = JSON.parse(fs.readFileSync(walletPath, 'utf8'));
    const payer = Keypair.fromSecretKey(Buffer.from(secretKey));
    const connection = createRpc(); // defaults to localhost:8899

    (async () => {

      // Generate mint keypair and define Token-2022 metadata
      const mint = Keypair.generate();
      const decimals = 9;

      const metadata: TokenMetadata = {
        mint: mint.publicKey,
        name: "Local Test Token",
        symbol: "LTT",
        uri: "https://example.com/token-metadata.json",
        additionalMetadata: [["environment", "localnet"], ["test", "true"]],
      };

      // Calculate space requirements for Token-2022 mint with MetadataPointer extension
      const mintLen = getMintLen([ExtensionType.MetadataPointer]);
      const metadataLen = TYPE_SIZE + LENGTH_SIZE + pack(metadata).length;

      // Check wallet balance
      const balance = await connection.getBalance(payer.publicKey);

      // Step 2: Create Token-2022 mint with metadata extension
      const mintLamports = await connection.getMinimumBalanceForRentExemption(
        mintLen + metadataLen
      );

      const mintTransaction = new Transaction().add(
        // Create account for Token-2022 mint
        SystemProgram.createAccount({
          fromPubkey: payer.publicKey,
          newAccountPubkey: mint.publicKey,
          space: mintLen,
          lamports: mintLamports,
          programId: TOKEN_2022_PROGRAM_ID,
        }),
        // Initialize MetadataPointer extension
        createInitializeMetadataPointerInstruction(
          mint.publicKey,
          payer.publicKey,
          mint.publicKey,
          TOKEN_2022_PROGRAM_ID
        ),
        // Initialize Token-2022 mint account
        createInitializeMintInstruction(
          mint.publicKey,
          decimals,
          payer.publicKey,
          null,
          TOKEN_2022_PROGRAM_ID
        ),
        // Initialize token metadata
        createInitializeInstruction({
          programId: TOKEN_2022_PROGRAM_ID,
          mint: mint.publicKey,
          metadata: mint.publicKey,
          name: metadata.name,
          symbol: metadata.symbol,
          uri: metadata.uri,
          mintAuthority: payer.publicKey,
          updateAuthority: payer.publicKey,
        })
      );

      // Send Token-2022 mint creation transaction
      const mintCreationTxId = await sendAndConfirmTransaction(
        connection,
        mintTransaction,
        [payer, mint]
      );
      console.log(`Token-2022 mint created with address: ${mint.publicKey.toString()}`);

      // Step 3: Call createTokenPool() to initialize omnibus account
      // and register Token-2022 mint with Light Token Program
      // Create PDA that holds SPL tokens for compressed tokens
      const registerTxId = await createTokenPool(
        connection,
        payer,
        mint.publicKey, // Token-2022 mint to register with Light Token Program
        undefined,
        TOKEN_2022_PROGRAM_ID
      );

      // Step 4: Create associated token account and mint tokens
      const ata = await getOrCreateAssociatedTokenAccount(
        connection,
        payer,
        mint.publicKey, // Token-2022 mint with token pool for compression
        payer.publicKey,
        undefined,
        undefined,
        undefined,
        TOKEN_2022_PROGRAM_ID
      );

      // Mint Token-2022 tokens to ATA
      const mintAmount = 400_000_000; // 0.4 tokens
      const mintToTxId = await mintToSpl(
        connection,
        payer,
        mint.publicKey, // Token-2022 mint with token pool for compression
        ata.address, // destination token account
        payer.publicKey, // mint authority
        mintAmount, // amount to mint
        undefined, // multiSigners (not used for single authority)
        undefined,
        TOKEN_2022_PROGRAM_ID
      );
      console.log(`Minted ${mintAmount / 1e9} Token-2022 tokens with metadata extension`);
      console.log(`Transaction: ${mintToTxId}`);

      // Step 5: Call compress() to convert Token-2022 tokens to compressed format
      // Transfer Token-2022 tokens to omnibus pool and mint compressed tokens
      const compressAmount = 300_000_000; // 0.3 tokens
      const compressTxId = await compress(
        connection,
        payer,
        mint.publicKey, // Token-2022 mint with token pool for compression
        compressAmount, // amount to compress
        payer, // owner of SPL tokens
        ata.address, // Source ATA for compression
        payer.publicKey // recipient for compressed tokens
      );
      console.log(`\nCompressed ${compressAmount / 1e9} Token-2022 tokens`);
      console.log(`Transaction: ${compressTxId}`);

      // Step 6: Transfer compressed Token-2022 tokens
      const transferRecipient = Keypair.generate(); // Keypair recipient
      const transferAmount = 100_000_000; // 0.1 tokens
      const transferTxId = await transfer(
        connection,
        payer,
        mint.publicKey, // Token-2022 mint with token pool for compression
        transferAmount,
        payer,
        transferRecipient.publicKey
      );
      console.log(`\nTransferred ${transferAmount / 1e9} Compressed Token-2022 tokens`);
      console.log(`Transaction: ${transferTxId}`);
      console.log(`Recipient: ${transferRecipient.publicKey.toString()}`);

      // Step 7: Verify balances via getTokenAccountBalance and getCompressedTokenAccountsByOwner
      const senderCompressedAccounts = await connection.getCompressedTokenAccountsByOwner(payer.publicKey, { mint: mint.publicKey });
      const senderBalance = senderCompressedAccounts.items.reduce((sum, account) => sum + Number(account.parsed.amount), 0);

      const recipientCompressedAccounts = await connection.getCompressedTokenAccountsByOwner(transferRecipient.publicKey, { mint: mint.publicKey });
      const recipientBalance = recipientCompressedAccounts.items.reduce((sum, account) => sum + Number(account.parsed.amount), 0);

      const splBalance = await connection.getTokenAccountBalance(ata.address);

      console.log(`\nSummary Token-2022 balances:`);
      console.log(`Sender balance: ${senderBalance / 1e9} compressed tokens / ${splBalance.value.uiAmount} SPL tokens`);
      console.log(`Recipient balance: ${recipientBalance / 1e9} compressed tokens`);

    })().catch(console.error);
    ```
  </Step>
</Steps>

# Next Steps

<Card title="Create an Airdrop with Compressed Tokens." icon="chevron-right" href="/compressed-tokens/advanced-guides/airdrop" />


# Rent-Free SPL Accounts with Privy
Source: https://www.zkcompression.com/compressed-tokens/for-privy

Integrate compressed tokens with Privy embedded wallets for rent-free SPL token accounts and transfers.

| Creation Cost   | SPL Token Account    | Compressed Token     |
| :-------------- | :------------------- | :------------------- |
| **Per account** | \~2,000,000 lamports | \~**5,000** lamports |

Privy handles user authentication and wallet management. You build transactions with tokens (SOL, SPL or compressed) and Privy signs them client-side:

1. Authenticate with Privy
2. Build unsigned transaction
3. Sign transaction using Privy's wallet provider
4. Send signed transaction to RPC

## What you will implement

<table>
  <thead>
    <tr>
      <th />

      <th>SPL</th>
      <th>Compressed </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>[**Transfer**](#full-code-examples)</td>
      <td>transferChecked()</td>
      <td>transfer()</td>
    </tr>

    <tr>
      <td>[**Compress**](#full-code-examples)</td>
      <td>N/A</td>
      <td>compress()</td>
    </tr>

    <tr>
      <td>[**Decompress**](#full-code-examples)</td>
      <td>N/A</td>
      <td>decompress()</td>
    </tr>

    <tr>
      <td>[**Get Balance**](#get-balances)</td>
      <td>getAccount()</td>
      <td>getCompressedTokenAccountsByOwner()</td>
    </tr>

    <tr>
      <td>[**Transaction History**](#get-transaction-history)</td>
      <td>getSignaturesForAddress()</td>
      <td>getCompressionSignaturesForOwner()</td>
    </tr>
  </tbody>
</table>

<Tabs>
  <Tab title="Guide">
    <Steps>
      <Step>
        ### Prerequisites

        ```bash theme={null}
        npm install @lightprotocol/compressed-token \
                    @lightprotocol/stateless.js
        ```

        Connect to an RPC endpoint that supports ZK Compression (Helius, Triton)

        ```typescript theme={null}
        import { createRpc } from "@lightprotocol/stateless.js";

        import {
          transfer,
          compress,
          decompress,
          selectMinCompressedTokenAccountsForTransfer,
        } from "@lightprotocol/compressed-token";

        const rpc = createRpc(RPC_ENDPOINT);
        ```

        <Accordion title="Setup test mint">
          <Info>
            Before we call compress or decompresss, we need:

            * An SPL mint with a interface PDA for compression. This PDA can be created for new SPL mints via [`createMint()`](/compressed-tokens/guides/create-mint-with-token-pool) or added to existing SPL mints via [`createTokenPool()`](/compressed-tokens/guides/add-token-pools-to-mint-accounts).
            * For `compress()` SPL tokens in an Associated Token Account, or
            * For `decompress()` compressed token accounts with sufficient balance.
          </Info>

          ```typescript theme={null}
          import "dotenv/config";
          import { Keypair } from "@solana/web3.js";
          import { createRpc } from "@lightprotocol/stateless.js";
          import { createMint } 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!}`;
          // localnet:
          // const RPC_URL = undefined;
          const payer = Keypair.fromSecretKey(
              new Uint8Array(
                  JSON.parse(readFileSync(`${homedir()}/.config/solana/id.json`, "utf8"))
              )
          );

          (async function () {
              // devnet:
              const rpc = createRpc(RPC_URL);
              // localnet:
              // const rpc = createRpc();

              const { mint, transactionSignature } = await createMint(
                  rpc,
                  payer,
                  payer.publicKey,
                  9
              );

              console.log("Mint:", mint.toBase58());
              console.log("Tx:", transactionSignature);
          })();
          ```
        </Accordion>
      </Step>

      <Step>
        ## Full Code Examples

        <Info>
          Find complete examples on Github: [nodejs](https://github.com/Lightprotocol/examples-zk-compression/tree/main/privy/nodejs-privy-compressed) and [react](https://github.com/Lightprotocol/examples-zk-compression/tree/main/privy/react-privy-compressed).
        </Info>

        <Tabs>
          <Tab title="Compressed Transfer">
            Send compressed tokens to another recipient, similar to SPL token transfers:

            1. Fetch compressed token accounts with `getCompressedTokenAccountsByOwner`
            2. Select sender accounts with `selectMinCompressedTokenAccountsForTransfer`
            3. Fetch a validity proof from your RPC provider to prove the account's state correctness
            4. Build the transfer instruction and transaction
            5. Sign with Privy and send transaction

            <Tabs>
              <Tab title="Node.js">
                ````typescript theme={null}
                import 'dotenv/config';
                import {PrivyClient} from '@privy-io/node';
                import {createRpc, bn} from '@lightprotocol/stateless.js';
                import {PublicKey, Transaction, ComputeBudgetProgram} from '@solana/web3.js';
                import {CompressedTokenProgram, selectMinCompressedTokenAccountsForTransfer} from '@lightprotocol/compressed-token';

                const transferCompressedTokens = async (
                  fromAddress: string,
                  toAddress: string,
                  tokenMintAddress: string,
                  amount: number,
                  decimals: number = 6
                ) => {
                  const connection = createRpc(process.env.HELIUS_RPC_URL!);

                  const privy = new PrivyClient({
                    appId: process.env.PRIVY_APP_ID!,
                    appSecret: process.env.PRIVY_APP_SECRET!,
                  });

                  // Create public key objects
                  const fromPubkey = new PublicKey(fromAddress);
                  const toPubkey = new PublicKey(toAddress);
                  const mintPubkey = new PublicKey(tokenMintAddress);
                  const tokenAmount = bn(amount * Math.pow(10, decimals));

                  // Get compressed token accounts (filter out null items from indexer)
                  const accounts = await connection.getCompressedTokenAccountsByOwner(fromPubkey, {mint: mintPubkey});
                  const validItems = (accounts.items || []).filter((item): item is NonNullable<typeof item> => item !== null);
                  if (validItems.length === 0) {
                    throw new Error('No compressed token accounts found');
                  }

                  // Select minimum accounts needed for transfer
                  const [inputAccounts] = selectMinCompressedTokenAccountsForTransfer(validItems, tokenAmount);
                  if (inputAccounts.length === 0) {
                    throw new Error('Insufficient balance');
                  }

                  // Get validity proof to prove compressed token accounts exist in state tree.
                  const proof = await connection.getValidityProof(inputAccounts.map(account => bn(account.compressedAccount.hash)));

                  // Create transfer instruction
                  const instruction = await CompressedTokenProgram.transfer({
                    payer: fromPubkey,
                    inputCompressedTokenAccounts: inputAccounts,
                    toAddress: toPubkey,
                    amount: tokenAmount,
                    recentInputStateRootIndices: proof.rootIndices,
                    recentValidityProof: proof.compressedProof,
                  });

                  // Create transaction
                  const transaction = new Transaction();
                  transaction.add(ComputeBudgetProgram.setComputeUnitLimit({units: 300_000}));
                  transaction.add(instruction);

                  // Get recent blockhash
                  const {blockhash} = await connection.getLatestBlockhash();
                  transaction.recentBlockhash = blockhash;
                  transaction.feePayer = fromPubkey;

                  // Sign with Privy
                  const signResult = await privy.wallets().solana().signTransaction(process.env.TREASURY_WALLET_ID!, {
                    transaction: transaction.serialize({requireAllSignatures: false}),
                    authorization_context: {
                      authorization_private_keys: [process.env.TREASURY_AUTHORIZATION_KEY!]
                    }
                  });
                  const signedTx = (signResult as any).signed_transaction || signResult.signedTransaction;
                  if (!signedTx) {
                    throw new Error('Privy returned invalid response: ' + JSON.stringify(signResult));
                  }
                  const signedTransaction = Buffer.from(signedTx, 'base64');

                  // Send transaction
                  const signature = await connection.sendRawTransaction(signedTransaction, {
                    skipPreflight: false,
                    preflightCommitment: 'confirmed'
                  });
                  await connection.confirmTransaction(signature, 'confirmed');

                  return signature;
                };

                export default transferCompressedTokens;```
                ````
              </Tab>

              <Tab title="React">
                ```typescript theme={null}
                import { useState } from 'react';
                import { PublicKey, Transaction, ComputeBudgetProgram } from '@solana/web3.js';
                import { CompressedTokenProgram, selectMinCompressedTokenAccountsForTransfer } from '@lightprotocol/compressed-token';
                import { bn, createRpc } from '@lightprotocol/stateless.js';
                import type { ConnectedStandardSolanaWallet } from '@privy-io/js-sdk-core';
                import type { SignTransactionResult } from '@privy-io/react-auth/solana';

                export interface TransferParams {
                  ownerPublicKey: string;
                  mint: string;
                  toAddress: string;
                  amount: number;
                  decimals?: number;
                }

                export interface TransferArgs {
                  params: TransferParams;
                  wallet: ConnectedStandardSolanaWallet;
                  signTransaction: (args: {
                    transaction: Buffer;
                    wallet: ConnectedStandardSolanaWallet;
                    chain: string;
                  }) => Promise<SignTransactionResult>;
                }

                export function useTransfer() {
                  const [isLoading, setIsLoading] = useState(false);

                  const transfer = async (args: TransferArgs): Promise<string> => {
                    setIsLoading(true);

                    try {
                      const { params, wallet, signTransaction } = args;
                      const { ownerPublicKey, mint, toAddress, amount, decimals = 6 } = params;

                      // Create RPC connection
                      const rpc = createRpc(import.meta.env.VITE_HELIUS_RPC_URL);

                      const owner = new PublicKey(ownerPublicKey);
                      const mintPubkey = new PublicKey(mint);
                      const recipient = new PublicKey(toAddress);
                      const tokenAmount = bn(Math.floor(amount * Math.pow(10, decimals)));

                      // Get compressed token accounts
                      const accounts = await rpc.getCompressedTokenAccountsByOwner(owner, { mint: mintPubkey });
                      if (!accounts.items || accounts.items.length === 0) {
                        throw new Error('No compressed token accounts found');
                      }

                      // Select minimum accounts needed
                      const [inputAccounts] = selectMinCompressedTokenAccountsForTransfer(accounts.items, tokenAmount);
                      if (inputAccounts.length === 0) {
                        throw new Error('Insufficient balance');
                      }

                      // Get validity proof
                      const proof = await rpc.getValidityProof(
                        inputAccounts.map((account) => bn(account.compressedAccount.hash))
                      );

                      // Build transfer instruction
                      const transferIx = await CompressedTokenProgram.transfer({
                        payer: owner,
                        inputCompressedTokenAccounts: inputAccounts,
                        toAddress: recipient,
                        amount: tokenAmount,
                        recentInputStateRootIndices: proof.rootIndices,
                        recentValidityProof: proof.compressedProof,
                      });

                      // Build transaction
                      const { blockhash } = await rpc.getLatestBlockhash();
                      const transaction = new Transaction();
                      transaction.add(ComputeBudgetProgram.setComputeUnitLimit({ units: 300_000 }));
                      transaction.add(transferIx);
                      transaction.recentBlockhash = blockhash;
                      transaction.feePayer = owner;

                      // Serialize unsigned transaction
                      const unsignedTxBuffer = transaction.serialize({ requireAllSignatures: false });

                      // Sign with Privy
                      const signedTx = await signTransaction({
                        transaction: unsignedTxBuffer,
                        wallet,
                        chain: 'solana:devnet',
                      });

                      // Send transaction
                      const signedTxBuffer = Buffer.from(signedTx.signedTransaction);
                      const signature = await rpc.sendRawTransaction(signedTxBuffer, {
                        skipPreflight: false,
                        preflightCommitment: 'confirmed',
                      });

                      return signature;
                    } finally {
                      setIsLoading(false);
                    }
                  };

                  return { transfer, isLoading };
                }
                ```
              </Tab>
            </Tabs>
          </Tab>

          <Tab title="Compress SPL to Recipient">
            Convert SPL to compressed tokens and send to a recipient in one instruction.

            <Tabs>
              <Tab title="Node.js">
                ```typescript theme={null}
                import 'dotenv/config';
                import {PrivyClient} from '@privy-io/node';
                import {createRpc, bn, selectStateTreeInfo} from '@lightprotocol/stateless.js';
                import {PublicKey, Transaction, ComputeBudgetProgram} from '@solana/web3.js';
                import {getAssociatedTokenAddressSync, getAccount} from '@solana/spl-token';
                import {CompressedTokenProgram, getTokenPoolInfos, selectTokenPoolInfo} from '@lightprotocol/compressed-token';

                const compressTokens = async (
                  fromAddress: string,
                  toAddress: string,
                  tokenMintAddress: string,
                  amount: number,
                  decimals: number = 6
                ) => {
                  const connection = createRpc(process.env.HELIUS_RPC_URL!);

                  const privy = new PrivyClient({
                    appId: process.env.PRIVY_APP_ID!,
                    appSecret: process.env.PRIVY_APP_SECRET!,
                  });

                  // Create public key objects
                  const fromPubkey = new PublicKey(fromAddress);
                  const toPubkey = new PublicKey(toAddress);
                  const mintPubkey = new PublicKey(tokenMintAddress);
                  const tokenAmount = bn(amount * Math.pow(10, decimals));

                  // Get source token account and verify balance
                  const ownerAta = getAssociatedTokenAddressSync(mintPubkey, fromPubkey);
                  const ataAccount = await getAccount(connection, ownerAta);
                  if (ataAccount.amount < BigInt(tokenAmount.toString())) {
                    throw new Error('Insufficient SPL balance');
                  }

                  // Get state tree to store compressed tokens
                  //  Get token pool info. Stores SPL tokens in interface PDA when compressed.
                  const stateTreeInfos = await connection.getStateTreeInfos();
                  const selectedTreeInfo = selectStateTreeInfo(stateTreeInfos);
                  const tokenPoolInfos = await getTokenPoolInfos(connection, mintPubkey);
                  const tokenPoolInfo = selectTokenPoolInfo(tokenPoolInfos);

                  // Create compress instruction
                  const instruction = await CompressedTokenProgram.compress({
                    payer: fromPubkey,
                    owner: fromPubkey,
                    source: ownerAta,
                    toAddress: toPubkey,
                    mint: mintPubkey,
                    amount: tokenAmount,
                    outputStateTreeInfo: selectedTreeInfo,
                    tokenPoolInfo,
                  });

                  // Create transaction
                  const transaction = new Transaction();
                  transaction.add(ComputeBudgetProgram.setComputeUnitLimit({units: 300_000}));
                  transaction.add(instruction);

                  // Get recent blockhash
                  const {blockhash} = await connection.getLatestBlockhash();
                  transaction.recentBlockhash = blockhash;
                  transaction.feePayer = fromPubkey;

                  // Sign with Privy
                  const signResult = await privy.wallets().solana().signTransaction(process.env.TREASURY_WALLET_ID!, {
                    transaction: transaction.serialize({requireAllSignatures: false}),
                    authorization_context: {
                      authorization_private_keys: [process.env.TREASURY_AUTHORIZATION_KEY!]
                    }
                  });
                  const signedTx = (signResult as any).signed_transaction || signResult.signedTransaction;
                  if (!signedTx) {
                    throw new Error('Privy returned invalid response: ' + JSON.stringify(signResult));
                  }
                  const signedTransaction = Buffer.from(signedTx, 'base64');

                  // Send transaction
                  const signature = await connection.sendRawTransaction(signedTransaction, {
                    skipPreflight: false,
                    preflightCommitment: 'confirmed'
                  });
                  await connection.confirmTransaction(signature, 'confirmed');

                  return signature;
                };

                export default compressTokens;
                ```
              </Tab>

              <Tab title="React">
                ```typescript theme={null}
                import { useState } from 'react';
                import { PublicKey, Transaction, ComputeBudgetProgram } from '@solana/web3.js';
                import { getAssociatedTokenAddressSync, getAccount } from '@solana/spl-token';
                import { bn, createRpc, selectStateTreeInfo } from '@lightprotocol/stateless.js';
                import { CompressedTokenProgram, getTokenPoolInfos, selectTokenPoolInfo } from '@lightprotocol/compressed-token';
                import type { ConnectedStandardSolanaWallet } from '@privy-io/js-sdk-core';
                import type { SignTransactionResult } from '@privy-io/react-auth/solana';

                export interface CompressParams {
                  ownerPublicKey: string;
                  toAddress: string;
                  mint: string;
                  amount: number;
                  decimals?: number;
                }

                export interface CompressArgs {
                  params: CompressParams;
                  wallet: ConnectedStandardSolanaWallet;
                  signTransaction: (args: {
                    transaction: Buffer;
                    wallet: ConnectedStandardSolanaWallet;
                    chain: string;
                  }) => Promise<SignTransactionResult>;
                }

                export function useCompress() {
                  const [isLoading, setIsLoading] = useState(false);

                  const compress = async (args: CompressArgs): Promise<string> => {
                    setIsLoading(true);

                    try {
                      const { params, wallet, signTransaction } = args;
                      const { ownerPublicKey, toAddress, mint, amount, decimals = 6 } = params;

                      // Create RPC connection
                      const rpc = createRpc(import.meta.env.VITE_HELIUS_RPC_URL);

                      // Create public key objects
                      const ownerPubkey = new PublicKey(ownerPublicKey);
                      const toPubkey = new PublicKey(toAddress);
                      const mintPubkey = new PublicKey(mint);
                      const tokenAmount = bn(amount * Math.pow(10, decimals));

                      // Get source token account and verify balance
                      const ownerAta = getAssociatedTokenAddressSync(mintPubkey, ownerPubkey);
                      const ataAccount = await getAccount(rpc, ownerAta);
                      if (ataAccount.amount < BigInt(tokenAmount.toString())) {
                        throw new Error('Insufficient SPL balance');
                      }

                      // Get state tree to store compressed tokens
                      // Get token pool info. Stores SPL tokens in interface PDA when compressed.
                      const stateTreeInfos = await rpc.getStateTreeInfos();
                      const selectedTreeInfo = selectStateTreeInfo(stateTreeInfos);
                      const tokenPoolInfos = await getTokenPoolInfos(rpc, mintPubkey);
                      const tokenPoolInfo = selectTokenPoolInfo(tokenPoolInfos);

                      // Create compress instruction
                      const instruction = await CompressedTokenProgram.compress({
                        payer: ownerPubkey,
                        owner: ownerPubkey,
                        source: ownerAta,
                        toAddress: toPubkey,
                        mint: mintPubkey,
                        amount: tokenAmount,
                        outputStateTreeInfo: selectedTreeInfo,
                        tokenPoolInfo,
                      });

                      // Build transaction
                      const { blockhash } = await rpc.getLatestBlockhash();
                      const transaction = new Transaction();
                      transaction.add(ComputeBudgetProgram.setComputeUnitLimit({ units: 300_000 }));
                      transaction.add(instruction);
                      transaction.recentBlockhash = blockhash;
                      transaction.feePayer = ownerPubkey;

                      // Serialize unsigned transaction
                      const unsignedTxBuffer = transaction.serialize({ requireAllSignatures: false });

                      // Sign with Privy
                      const signedTx = await signTransaction({
                        transaction: unsignedTxBuffer,
                        wallet,
                        chain: 'solana:devnet',
                      });

                      // Send transaction
                      const signedTxBuffer = Buffer.from(signedTx.signedTransaction);
                      const signature = await rpc.sendRawTransaction(signedTxBuffer, {
                        skipPreflight: false,
                        preflightCommitment: 'confirmed',
                      });

                      return signature;
                    } finally {
                      setIsLoading(false);
                    }
                  };

                  return { compress, isLoading };
                }
                ```
              </Tab>
            </Tabs>
          </Tab>

          <Tab title="Decompress (Offramp)">
            Convert compressed tokens back to SPL tokens.

            <Tabs>
              <Tab title="Node.js">
                ```typescript theme={null}
                import 'dotenv/config';
                import {PrivyClient} from '@privy-io/node';
                import {createRpc} from '@lightprotocol/stateless.js';
                import {Keypair, PublicKey, Transaction} from '@solana/web3.js';
                import {getAssociatedTokenAddressSync, createAssociatedTokenAccount} from '@solana/spl-token';
                import {decompress} from '@lightprotocol/compressed-token';

                const decompressTokens = async (
                  fromAddress: string,
                  tokenMintAddress: string,
                  amount: number,
                  decimals: number = 6
                ) => {
                  const connection = createRpc(process.env.HELIUS_RPC_URL!);

                  const privy = new PrivyClient({
                    appId: process.env.PRIVY_APP_ID!,
                    appSecret: process.env.PRIVY_APP_SECRET!,
                  });

                  const fromPubkey = new PublicKey(fromAddress);
                  const mintPubkey = new PublicKey(tokenMintAddress);
                  const rawAmount = amount * Math.pow(10, decimals);

                  // Get destination ATA
                  const ownerAta = getAssociatedTokenAddressSync(mintPubkey, fromPubkey);

                  // Check ATA exists (decompress action will handle creation internally)
                  // But we need to be aware ATA creation requires a separate signer

                  // Create fake keypair for decompress action (only publicKey is used)
                  const dummyPayer = {
                    publicKey: fromPubkey,
                    secretKey: new Uint8Array(64),
                  } as any;

                  // Intercept sendAndConfirmTransaction to use Privy signing
                  const originalSendAndConfirm = (connection as any).sendAndConfirmTransaction;
                  (connection as any).sendAndConfirmTransaction = async (tx: Transaction, signers: any[]) => {
                    const signResult = await privy.wallets().solana().signTransaction(process.env.TREASURY_WALLET_ID!, {
                      transaction: tx.serialize({requireAllSignatures: false}),
                      authorization_context: {
                        authorization_private_keys: [process.env.TREASURY_AUTHORIZATION_KEY!]
                      }
                    });

                    const signedTx = (signResult as any).signed_transaction || signResult.signedTransaction;
                    if (!signedTx) {
                      throw new Error('Privy returned invalid response');
                    }

                    const signedTransaction = Buffer.from(signedTx, 'base64');
                    const signature = await connection.sendRawTransaction(signedTransaction, {
                      skipPreflight: false,
                      preflightCommitment: 'confirmed'
                    });
                    await connection.confirmTransaction(signature, 'confirmed');
                    return signature;
                  };

                  try {
                    // Use high-level decompress action (handles account configuration correctly)
                    const signature = await decompress(
                      connection,
                      dummyPayer,
                      mintPubkey,
                      rawAmount,
                      dummyPayer,
                      ownerAta
                    );

                    return signature;
                  } finally {
                    // Restore original function
                    (connection as any).sendAndConfirmTransaction = originalSendAndConfirm;
                  }
                };

                export default decompressTokens;
                ```
              </Tab>

              <Tab title="React">
                ```typescript theme={null}
                import { useState } from 'react';
                import { PublicKey, Transaction, ComputeBudgetProgram } from '@solana/web3.js';
                import { getAssociatedTokenAddressSync, createAssociatedTokenAccountInstruction, getAccount, TokenAccountNotFoundError } from '@solana/spl-token';
                import { CompressedTokenProgram, selectMinCompressedTokenAccountsForTransfer, getSplInterfaceInfos, selectSplInterfaceInfosForDecompression } from '@lightprotocol/compressed-token';
                import { bn, createRpc } from '@lightprotocol/stateless.js';
                import type { ConnectedStandardSolanaWallet } from '@privy-io/js-sdk-core';
                import type { SignTransactionResult } from '@privy-io/react-auth/solana';

                export interface DecompressParams {
                  ownerPublicKey: string;
                  mint: string;
                  amount: number;
                  decimals?: number;
                }

                export interface DecompressArgs {
                  params: DecompressParams;
                  wallet: ConnectedStandardSolanaWallet;
                  signTransaction: (args: {
                    transaction: Buffer;
                    wallet: ConnectedStandardSolanaWallet;
                    chain: string;
                  }) => Promise<SignTransactionResult>;
                }

                export function useDecompress() {
                  const [isLoading, setIsLoading] = useState(false);

                  const decompress = async (args: DecompressArgs): Promise<string> => {
                    setIsLoading(true);

                    try {
                      const { params, wallet, signTransaction } = args;
                      const { ownerPublicKey, mint, amount, decimals = 6 } = params;

                      // Create RPC connection
                      const rpc = createRpc(import.meta.env.VITE_HELIUS_RPC_URL);

                      const owner = new PublicKey(ownerPublicKey);
                      const mintPubkey = new PublicKey(mint);
                      const tokenAmount = bn(Math.floor(amount * Math.pow(10, decimals)));

                      // Get destination ATA
                      const destinationAta = getAssociatedTokenAddressSync(mintPubkey, owner);

                      // Get compressed token accounts
                      const accounts = await rpc.getCompressedTokenAccountsByOwner(owner, { mint: mintPubkey });
                      if (!accounts.items || accounts.items.length === 0) {
                        throw new Error('No compressed token accounts found');
                      }

                      // Select minimum accounts needed
                      const [inputAccounts] = selectMinCompressedTokenAccountsForTransfer(accounts.items, tokenAmount);
                      if (inputAccounts.length === 0) {
                        throw new Error('Insufficient compressed balance');
                      }

                      // Get validity proof and token pool info
                      const proof = await rpc.getValidityProof(
                        inputAccounts.map((account) => bn(account.compressedAccount.hash))
                      );
                      const splInterfaceInfos = await getSplInterfaceInfos(rpc, mintPubkey);
                      const tokenPoolInfos = selectSplInterfaceInfosForDecompression(splInterfaceInfos, tokenAmount);

                      // Build transaction
                      const { blockhash } = await rpc.getLatestBlockhash();
                      const transaction = new Transaction();
                      transaction.add(ComputeBudgetProgram.setComputeUnitLimit({ units: 400_000 }));

                      // Create ATA if needed
                      try {
                        await getAccount(rpc, destinationAta);
                      } catch (e) {
                        if (e instanceof TokenAccountNotFoundError) {
                          transaction.add(
                            createAssociatedTokenAccountInstruction(owner, destinationAta, owner, mintPubkey)
                          );
                        } else {
                          throw e;
                        }
                      }

                      // Build decompress instruction
                      const decompressIx = await CompressedTokenProgram.decompress({
                        payer: owner,
                        inputCompressedTokenAccounts: inputAccounts,
                        toAddress: destinationAta,
                        amount: tokenAmount,
                        recentInputStateRootIndices: proof.rootIndices,
                        recentValidityProof: proof.compressedProof,
                        tokenPoolInfos,
                      });

                      transaction.add(decompressIx);
                      transaction.recentBlockhash = blockhash;
                      transaction.feePayer = owner;

                      // Serialize unsigned transaction
                      const unsignedTxBuffer = transaction.serialize({ requireAllSignatures: false });

                      // Sign with Privy
                      const signedTx = await signTransaction({
                        transaction: unsignedTxBuffer,
                        wallet,
                        chain: 'solana:devnet',
                      });

                      // Send transaction
                      const signedTxBuffer = Buffer.from(signedTx.signedTransaction);
                      const signature = await rpc.sendRawTransaction(signedTxBuffer, {
                        skipPreflight: false,
                        preflightCommitment: 'confirmed',
                      });

                      return signature;
                    } finally {
                      setIsLoading(false);
                    }
                  };

                  return { decompress, isLoading };
                }
                ```
              </Tab>
            </Tabs>
          </Tab>
        </Tabs>
      </Step>
    </Steps>

    ## Get balances

    Fetch SPL and compressed token balances.

    <Tabs>
      <Tab title="Node.js">
        ```typescript theme={null}
        import {PublicKey} from '@solana/web3.js';
        import {createRpc} from '@lightprotocol/stateless.js';
        import {HELIUS_RPC_URL} from './config.js';

        export async function getCompressedBalances(ownerAddress: string) {
          const rpc = createRpc(HELIUS_RPC_URL);
          const owner = new PublicKey(ownerAddress);

          // Get compressed SOL balance
          const compressedSol = await rpc.getCompressedBalanceByOwner(owner);
          const compressedSolLamports = compressedSol.value ? BigInt(compressedSol.value.toString()) : 0n;

          // Get compressed token accounts (filter out null items from indexer)
          const compressedAccounts = await rpc.getCompressedTokenAccountsByOwner(owner);
          const validItems = (compressedAccounts.items || []).filter((item): item is NonNullable<typeof item> => item !== null);

          // Aggregate balances by mint
          const balances = new Map<string, bigint>();
          for (const account of validItems) {
            if (account.parsed) {
              const mint = account.parsed.mint.toBase58();
              const amount = BigInt(account.parsed.amount.toString());
              const current = balances.get(mint) || 0n;
              balances.set(mint, current + amount);
            }
          }

          return {
            sol: compressedSolLamports.toString(),
            tokens: Array.from(balances.entries()).map(([mint, amount]) => ({
              mint,
              amount: amount.toString(),
              accounts: validItems.filter(a => a.parsed?.mint.toBase58() === mint).length
            }))
          };
        }
        ```
      </Tab>

      <Tab title="React">
        ```typescript theme={null}
        import { useState, useCallback } from 'react';
        import { PublicKey, LAMPORTS_PER_SOL } from '@solana/web3.js';
        import { getAccount, getAssociatedTokenAddressSync } from '@solana/spl-token';
        import { createRpc } from '@lightprotocol/stateless.js';

        const USDC_MINT = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
        const TEST_MINT = '7cT3PeXyDLkyEcvr9YzsjGLuZneKsea4c8hPbJQEjMCZ';

        export interface TokenBalance {
          mint: string;
          amount: string;
          decimals: number;
          isCompressed: boolean;
          isNative: boolean;
        }

        export function useCompressedBalances() {
          const [balances, setBalances] = useState<TokenBalance[]>([]);
          const [isLoading, setIsLoading] = useState(false);

          const fetchBalances = useCallback(async (ownerAddress: string) => {
            if (!ownerAddress) return;

            setIsLoading(true);
            try {
              const rpc = createRpc(import.meta.env.VITE_HELIUS_RPC_URL);
              const owner = new PublicKey(ownerAddress);
              const allBalances: TokenBalance[] = [];

              // Get compressed SOL balance
              try {
                const compressedSol = await rpc.getCompressedBalanceByOwner(owner);
                if (compressedSol && BigInt(compressedSol.toString()) > 0n) {
                  allBalances.push({
                    mint: 'So11111111111111111111111111111111111111112',
                    amount: compressedSol.toString(),
                    decimals: 9,
                    isCompressed: true,
                    isNative: true,
                  });
                }
              } catch {
                // No compressed SOL
              }

              // Get regular SOL balance
              try {
                const solBalance = await rpc.getBalance(owner);
                allBalances.push({
                  mint: 'So11111111111111111111111111111111111111112',
                  amount: solBalance.toString(),
                  decimals: 9,
                  isCompressed: false,
                  isNative: true,
                });
              } catch {
                // Failed to get SOL balance
              }

              // Get regular SPL token accounts
              try {
                const tokenAccounts = await rpc.getTokenAccountsByOwner(owner, {
                  programId: new PublicKey('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA'),
                });

                for (const { account, pubkey } of tokenAccounts.value) {
                  const data = account.data;
                  if (data instanceof Buffer || (typeof data === 'object' && 'length' in data)) {
                    // Parse token account data
                    const dataBuffer = Buffer.from(data as Uint8Array);
                    if (dataBuffer.length >= 72) {
                      const mint = new PublicKey(dataBuffer.subarray(0, 32));
                      const amount = dataBuffer.readBigUInt64LE(64);

                      // Get mint info for decimals
                      try {
                        const mintInfo = await rpc.getAccountInfo(mint);
                        const decimals = mintInfo?.data ? (mintInfo.data as Buffer)[44] || 6 : 6;

                        allBalances.push({
                          mint: mint.toBase58(),
                          amount: amount.toString(),
                          decimals,
                          isCompressed: false,
                          isNative: false,
                        });
                      } catch {
                        allBalances.push({
                          mint: mint.toBase58(),
                          amount: amount.toString(),
                          decimals: 6,
                          isCompressed: false,
                          isNative: false,
                        });
                      }
                    }
                  }
                }
              } catch {
                // Failed to get token accounts
              }

              // Get compressed token accounts
              try {
                const compressedAccounts = await rpc.getCompressedTokenAccountsByOwner(owner);

                if (compressedAccounts?.items) {
                  const mintAmounts = new Map<string, bigint>();
                  const mintDecimals = new Map<string, number>();

                  for (const item of compressedAccounts.items) {
                    if (item?.parsed?.mint && item?.parsed?.amount) {
                      const mint = item.parsed.mint.toBase58();
                      const amount = BigInt(item.parsed.amount.toString());
                      const current = mintAmounts.get(mint) || 0n;
                      mintAmounts.set(mint, current + amount);

                      // Store decimals (assume 6 for now, could fetch from mint)
                      if (!mintDecimals.has(mint)) {
                        mintDecimals.set(mint, 6);
                      }
                    }
                  }

                  for (const [mint, amount] of mintAmounts) {
                    allBalances.push({
                      mint,
                      amount: amount.toString(),
                      decimals: mintDecimals.get(mint) || 6,
                      isCompressed: true,
                      isNative: false,
                    });
                  }
                }
              } catch {
                // Failed to get compressed accounts
              }

              // Add fallback tokens with 0 balance if not present
              const hasMint = (mint: string) => allBalances.some(b => b.mint === mint);

              if (!hasMint(USDC_MINT)) {
                allBalances.push({
                  mint: USDC_MINT,
                  amount: '0',
                  decimals: 6,
                  isCompressed: false,
                  isNative: false,
                });
              }

              if (!hasMint(TEST_MINT)) {
                allBalances.push({
                  mint: TEST_MINT,
                  amount: '0',
                  decimals: 6,
                  isCompressed: false,
                  isNative: false,
                });
              }

              setBalances(allBalances);
            } catch (error) {
              console.error('Failed to fetch balances:', error);
              setBalances([]);
            } finally {
              setIsLoading(false);
            }
          }, []);

          return { balances, isLoading, fetchBalances };
        }
        ```
      </Tab>
    </Tabs>

    ## Get transaction history

    Fetch compressed token transaction history for an owner, with optional detailed compression information.

    <Tabs>
      <Tab title="Node.js">
        ```typescript theme={null}
        import 'dotenv/config';
        import {createRpc} from '@lightprotocol/stateless.js';
        import {PublicKey} from '@solana/web3.js';

        const getTransactionHistory = async (
          ownerAddress: string,
          limit: number = 10,
          includeDetails: boolean = false
        ) => {
          const connection = createRpc(process.env.HELIUS_RPC_URL!);

          const owner = new PublicKey(ownerAddress);

          // Get compression signatures for token owner
          const signatures = await connection.getCompressionSignaturesForTokenOwner(owner);

          if (signatures.items.length === 0) {
            return {
              count: 0,
              transactions: [],
            };
          }

          // Limit results
          const limitedSignatures = signatures.items.slice(0, limit);

          // Get detailed info if requested
          if (includeDetails && limitedSignatures.length > 0) {
            const transactions = await Promise.all(
              limitedSignatures.map(async (sig) => {
                const txInfo = await connection.getTransactionWithCompressionInfo(sig.signature);

                return {
                  signature: sig.signature,
                  slot: sig.slot,
                  blockTime: sig.blockTime,
                  timestamp: new Date(sig.blockTime * 1000).toISOString(),
                  compressionInfo: txInfo?.compressionInfo ? {
                    closedAccounts: txInfo.compressionInfo.closedAccounts.length,
                    openedAccounts: txInfo.compressionInfo.openedAccounts.length,
                  } : null,
                };
              })
            );

            return {
              count: signatures.items.length,
              transactions,
            };
          }

          // Return basic signature info
          const transactions = limitedSignatures.map((sig) => ({
            signature: sig.signature,
            slot: sig.slot,
            blockTime: sig.blockTime,
            timestamp: new Date(sig.blockTime * 1000).toISOString(),
          }));

          return {
            count: signatures.items.length,
            transactions,
          };
        };

        export default getTransactionHistory;
        ```
      </Tab>

      <Tab title="React">
        ```typescript theme={null}
        import { useState, useCallback } from 'react';
        import { PublicKey } from '@solana/web3.js';
        import { createRpc } from '@lightprotocol/stateless.js';

        export interface TransactionCompressionInfo {
          closedAccounts: number;
          openedAccounts: number;
        }

        export interface Transaction {
          signature: string;
          slot: number;
          blockTime: number;
          timestamp: string;
          compressionInfo?: TransactionCompressionInfo | null;
        }

        export function useTransactionHistory() {
          const [transactions, setTransactions] = useState<Transaction[]>([]);
          const [isLoading, setIsLoading] = useState(false);
          const [error, setError] = useState<string | null>(null);

          const fetchTransactionHistory = useCallback(
            async (
              ownerAddress: string,
              limit: number = 10,
              includeDetails: boolean = false
            ) => {
              if (!ownerAddress) {
                setTransactions([]);
                return;
              }

              setIsLoading(true);
              setError(null);

              try {
                const rpc = createRpc(import.meta.env.VITE_HELIUS_RPC_URL);
                const owner = new PublicKey(ownerAddress);

                const signatures = await rpc.getCompressionSignaturesForTokenOwner(owner);

                if (signatures.items.length === 0) {
                  setTransactions([]);
                  return;
                }

                const limitedSignatures = signatures.items.slice(0, limit);

                if (includeDetails && limitedSignatures.length > 0) {
                  const transactionsWithDetails = await Promise.all(
                    limitedSignatures.map(async (sig) => {
                      const txInfo = await rpc.getTransactionWithCompressionInfo(sig.signature);

                      return {
                        signature: sig.signature,
                        slot: sig.slot,
                        blockTime: sig.blockTime,
                        timestamp: new Date(sig.blockTime * 1000).toISOString(),
                        compressionInfo: txInfo?.compressionInfo
                          ? {
                              closedAccounts: txInfo.compressionInfo.closedAccounts.length,
                              openedAccounts: txInfo.compressionInfo.openedAccounts.length,
                            }
                          : null,
                      };
                    })
                  );

                  setTransactions(transactionsWithDetails);
                  return;
                }

                const basicTransactions = limitedSignatures.map((sig) => ({
                  signature: sig.signature,
                  slot: sig.slot,
                  blockTime: sig.blockTime,
                  timestamp: new Date(sig.blockTime * 1000).toISOString(),
                }));

                setTransactions(basicTransactions);
              } catch (err) {
                const message = err instanceof Error ? err.message : String(err);
                setError(message);
                setTransactions([]);
              } finally {
                setIsLoading(false);
              }
            },
            []
          );

          return { transactions, isLoading, error, fetchTransactionHistory };
        }
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="AI Prompt">
    <Tabs>
      <Tab title="Node.js">
        ````text theme={null}
        ---
        argument-hint: <project_path>
        description: Add compressed token support to Privy Node.js app
        allowed-tools: [Bash, Read, Glob, Grep, Task, mcp__deepwiki, mcp__zkcompression]
        ---

        ## Task: Add compressed token support to Privy Node.js app

        References:
        - Privy Docs: https://docs.privy.io/recipes/solana/send-spl-tokens
        - Privy Node Examples:
          - SPL: https://github.com/privy-io/examples/tree/main/privy-node-starter
          - Compressed: https://github.com/Lightprotocol/examples-zk-compression/tree/main/privy/nodejs-privy-compressed
        - SPL vs Compressed comparison: https://github.com/Lightprotocol/examples-zk-compression/blob/main/privy/COMPARISON.md
        - Compressed Token Guide for Privy Node.js: https://zkcompression.com/compressed-tokens/for-privy 

        MCP:
        * deepwiki https://mcp.deepwiki.com/mcp
        * ZK Compression https://www.zkcompression.com/mcp

        ## Workflow

        - This plan must execute without user intervention
        - All questions have been resolved in planning phase
        - If blocked, find alternative approach - do not stop
        - Keep working until ALL todos are complete
        - Use Task tool with subagents for parallel research or when stuck
        - Use subagents with Read, Glob, Grep, and Deepwiki permissions when stuck
        - Always assign Tasks to subagents and tell the user

        ## DeepWiki fallback

        ```
        mcp__deepwiki__read_wiki_structure("Lightprotocol/light-protocol"),
        mcp__deepwiki__read_wiki_contents("Lightprotocol/light-protocol"),
        mcp__deepwiki__ask_question("Lightprotocol/light-protocol", "<question>")
        ```

        ## Quick Reference

        | Operation      | SPL                            | Compressed                                     |
        | -------------- | ------------------------------ | ---------------------------------------------- |
        | Transfer       | transferChecked()              | transfer()                                     |
        | Compress SPL to recipient       | N/A                            | compress()                                     |
        | Decompress to SPL    | N/A                            | decompress()                                   |
        | Get Balance    | getAccount()                   | getCompressedTokenAccountsByOwner()            |
        | Tx History     | getSignaturesForAddress()      | getCompressionSignaturesForOwner()             |

        ### Phase 1: Index project

        ```bash
        grep -r "createTransferInstruction\|getAssociatedTokenAddress\|@solana/spl-token" src/
        ```

        ### Phase 2: Add dependencies

        ```bash
        npm install @lightprotocol/stateless.js @lightprotocol/compressed-token
        ```

        ### Phase 3: Implement operations

        See Code Reference below all signed with Privy SDK.

        1. **Setup**: Connect to ZK Compression RPC (Helius, Triton) https://github.com/Lightprotocol/examples-zk-compression/blob/main/privy/nodejs-privy-compressed/src/index.ts
        2. **Get Balance**: Fetch SPL and compressed token balances https://github.com/Lightprotocol/examples-zk-compression/blob/main/privy/nodejs-privy-compressed/src/compressed/balances.ts
        3. **Transfer**: Send compressed tokens to another recipient, signed with Privy SDK https://github.com/Lightprotocol/examples-zk-compression/blob/main/privy/nodejs-privy-compressed/src/compressed/transfer.ts
        4. **Compress**: Convert SPL to compressed tokens and send to a recipient in one instruction https://github.com/Lightprotocol/examples-zk-compression/blob/main/privy/nodejs-privy-compressed/src/compressed/compress.ts
        5. **Decompress**: Convert compressed tokens back to SPL tokens for offramps https://github.com/Lightprotocol/examples-zk-compression/blob/main/privy/nodejs-privy-compressed/src/compressed/decompress.ts
        6. **Tx History**: Fetch compressed token transaction history for an owner

        ### Phase 4: Test

        Run the implemented functions. On failure, debug and retry. Assign always to subagents with Tasktool

        ````
      </Tab>

      <Tab title="React">
        ````text theme={null}
        ---
        argument-hint: <project_path>
        description: Add compressed token support to Privy React app
        allowed-tools: [Bash, Read, Glob, Grep, Task, mcp__deepwiki, mcp__zkcompression]
        ---

        ## Task: Add compressed token support to Privy React app

        References:
        - Privy Docs: https://docs.privy.io/recipes/solana/send-spl-tokens
        - Privy React Examples:
          - SPL: https://github.com/privy-io/examples/tree/main/privy-react-starter
          - Compressed: https://github.com/Lightprotocol/examples-zk-compression/tree/main/privy/react-privy-compressed
        - SPL vs Compressed comparison: https://github.com/Lightprotocol/examples-zk-compression/blob/main/privy/COMPARISON.md
        - Compressed Token Guide for Privy React: https://zkcompression.com/compressed-tokens/for-privy

        MCP:
        * deepwiki https://mcp.deepwiki.com/mcp
        * ZK Compression https://www.zkcompression.com/mcp

        ## Workflow

        - This plan must execute without user intervention
        - All questions have been resolved in planning phase
        - If blocked, find alternative approach - do not stop
        - Keep working until ALL todos are complete
        - Use Task tool with subagents for parallel research or when stuck
        - Use subagents with Read, Glob, Grep, and Deepwiki permissions when stuck
        - Always assign Tasks to subagents and tell the user

        ## DeepWiki fallback

        ```
        mcp__deepwiki__read_wiki_structure("Lightprotocol/light-protocol"),
        mcp__deepwiki__read_wiki_contents("Lightprotocol/light-protocol"),
        mcp__deepwiki__ask_question("Lightprotocol/light-protocol", "<question>")
        ```

        ## Quick Reference

        | Operation      | SPL                            | Compressed                                     |
        | -------------- | ------------------------------ | ---------------------------------------------- |
        | Transfer       | transferChecked()              | transfer()                                     |
        | Compress SPL to recipient       | N/A                            | compress()                                     |
        | Decompress to SPL    | N/A                            | decompress()                                   |
        | Get Balance    | getAccount()                   | getCompressedTokenAccountsByOwner()            |
        | Tx History     | getSignaturesForAddress()      | getCompressionSignaturesForOwner()             |

        ### Phase 1: Index project

        ```bash
        grep -r "createTransferInstruction\|getAssociatedTokenAddress\|@solana/spl-token" src/
        ```

        ### Phase 2: Add dependencies

        ```bash
        npm install @lightprotocol/stateless.js @lightprotocol/compressed-token
        ```

        ### Phase 3: Implement operations

        See Code Reference below all signed with Privy SDK.

        1. **Setup**: Connect to ZK Compression RPC (Helius, Triton) https://github.com/Lightprotocol/examples-zk-compression/blob/main/privy/react-privy-compressed/src/config/rpc.ts
        2. **Get Balance**: Fetch SPL and compressed token balances https://github.com/Lightprotocol/examples-zk-compression/blob/main/privy/react-privy-compressed/src/hooks/useCompressedBalances.ts
        3. **Transfer**: Send compressed tokens to another recipient, signed with Privy SDK https://github.com/Lightprotocol/examples-zk-compression/blob/main/privy/react-privy-compressed/src/hooks/useTransfer.ts
        4. **Compress**: Convert SPL to compressed tokens and send to a recipient in one instruction https://github.com/Lightprotocol/examples-zk-compression/blob/main/privy/react-privy-compressed/src/hooks/useCompress.ts
        5. **Decompress**: Convert compressed tokens back to SPL tokens for offramps https://github.com/Lightprotocol/examples-zk-compression/blob/main/privy/react-privy-compressed/src/hooks/useDecompress.ts
        6. **Tx History**: Fetch compressed token transaction history for an owner

        ### Phase 4: Test

        Run the implemented functions. On failure, debug and retry. Assign always to subagents with Tasktool

        ````
      </Tab>
    </Tabs>
  </Tab>
</Tabs>


# Create Token Pools for Compression to Existing Mints
Source: https://www.zkcompression.com/compressed-tokens/guides/add-token-pools-to-mint-accounts

Create a token pool for an existing SPL mint. Requires only fee_payer with no mint authority constraint.

Create a token for compression fo an existing SPL mint. `createTokenPool()` requires only `fee_payer` and has no mint authority constraint.

<Info>
  The token pool account itself requires rent, but individual compressed token accounts are rent-free.
</Info>

<CodeGroup>
  ```typescript function-create-token-pool.ts theme={null}
  // Creates token pool account for existing SPL mint
  const transactionSignature = await createTokenPool(
      rpc,
      payer,
      mint,
  );
  ```
</CodeGroup>

<Check>
  **Best Practice:** Each mint supports a maximum of 4 token pools total. During compression/decompression operations, token pools get write-locked. Use `addTokenPools()` to create additional pools that increase per-block write-lock capacity.
</Check>

## Get Started

<Steps>
  <Step>
    ### Create Token Pool

    <Accordion title="Installation">
      <Tabs>
        <Tab title="npm">
          Install packages in your working directory:

          ```bash theme={null}
          npm install @lightprotocol/stateless.js@beta \
                      @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          npm install -g @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>

        <Tab title="yarn">
          Install packages in your working directory:

          ```bash theme={null}
          yarn add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          yarn global add @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>

        <Tab title="pnpm">
          Install packages in your working directory:

          ```bash theme={null}
          pnpm add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          pnpm add -g @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>
      </Tabs>
    </Accordion>

    <Tabs>
      <Tab title="Localnet">
        ```bash theme={null}
        # start local test-validator in a separate terminal
        light test-validator
        ```

        <Note>
          In the code examples, use `createRpc()` without arguments for localnet.
        </Note>
      </Tab>

      <Tab title="Devnet">
        Get an API key from [Helius](https://helius.dev) and add to `.env`:

        ```bash title=".env" theme={null}
        API_KEY=<your-helius-api-key>
        ```

        <Note>
          In the code examples, use `createRpc(RPC_URL)` with the devnet URL.
        </Note>
      </Tab>
    </Tabs>

    ```typescript theme={null}
    import "dotenv/config";
    import { Keypair, PublicKey } from "@solana/web3.js";
    import { createRpc } from "@lightprotocol/stateless.js";
    import { createTokenPool } from "@lightprotocol/compressed-token";
    import { createMint as createSplMint, TOKEN_PROGRAM_ID } from "@solana/spl-token";
    import { homedir } from "os";
    import { readFileSync } from "fs";

    // devnet:
    const RPC_URL = `https://devnet.helius-rpc.com?api-key=${process.env.API_KEY!}`;
    // localnet:
    // const RPC_URL = undefined;
    const payer = Keypair.fromSecretKey(
        new Uint8Array(
            JSON.parse(readFileSync(`${homedir()}/.config/solana/id.json`, "utf8"))
        )
    );

    (async function () {
        // devnet:
        const rpc = createRpc(RPC_URL);
        // localnet:
        // const rpc = createRpc();

        // Setup: Create existing SPL mint
        const mintKeypair = Keypair.generate();
        await createSplMint(rpc, payer, payer.publicKey, null, 9, mintKeypair, undefined, TOKEN_PROGRAM_ID);

        // Create token pool for existing mint
        const tx = await createTokenPool(rpc, payer, mintKeypair.publicKey);

        console.log("Mint:", mintKeypair.publicKey.toBase58());
        console.log("Tx:", tx);
    })();
    ```
  </Step>
</Steps>

# Troubleshooting

<AccordionGroup>
  <Accordion title="TokenPool not found">
    You're trying to access a token pool that doesn't exist.

    ```typescript theme={null}
    // Create the missing token pool
    const poolTx = await createTokenPool(rpc, payer, mint);
    console.log("Token pool created:", poolTx);
    ```
  </Accordion>
</AccordionGroup>

# Advanced Configuration

<AccordionGroup>
  <Accordion title="Batch Pool Creation">
    Create pools for multiple mints:

    ```typescript theme={null}
    const mints = [
        new PublicKey("MINT_1_ADDRESS"),
        new PublicKey("MINT_2_ADDRESS"),
        new PublicKey("MINT_3_ADDRESS"),
    ];

    for (const mint of mints) {
        try {
            const poolTx = await createTokenPool(rpc, payer, mint);
            console.log(`Pool created for ${mint.toBase58()}:`, poolTx);
        } catch (error) {
            console.log(`Failed for ${mint.toBase58()}:`, error.message);
        }
    }
    ```
  </Accordion>

  <Accordion title="Create Pool with Token-2022">
    Create token pools for Token-2022 mints:

    ```typescript theme={null}
    import { TOKEN_2022_PROGRAM_ID } from '@solana/spl-token';

    const poolTx = await createTokenPool(
        rpc,
        payer,
        mint, // Token-2022 mint
        undefined,
        TOKEN_2022_PROGRAM_ID,
    );
    ```
  </Accordion>
</AccordionGroup>

# Next Steps

<Card title="How to Merge Compressed Token Accounts" icon="chevron-right" href="/compressed-tokens/guides/merge-compressed-token-accounts" />


# Compress and Decompress SPL Tokens
Source: https://www.zkcompression.com/compressed-tokens/guides/compress-decompress

Convert SPL tokens between compressed and regular format with compress() and decompress().

<CodeGroup>
  ```typescript compress() theme={null}
  // 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)
  );
  ```

  ```typescript decompress() theme={null}
  // Decompress compressed tokens to SPL tokens
  const transactionSignature = await decompress(
      rpc,
      payer,
      mint, // SPL mint with token pool for compression
      amount,
      payer, // owner of compressed tokens
      tokenAccount.address, // destination token account (toAddress parameter)
  );
  ```
</CodeGroup>

<Note>
  **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](/compressed-tokens/guides/compress-spl-token-account).
</Note>

## Get Started

<Steps>
  <Step>
    ### Compress / Decompress Tokens

    <Accordion title="Installation">
      <Tabs>
        <Tab title="npm">
          Install packages in your working directory:

          ```bash theme={null}
          npm install @lightprotocol/stateless.js@beta \
                      @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          npm install -g @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>

        <Tab title="yarn">
          Install packages in your working directory:

          ```bash theme={null}
          yarn add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          yarn global add @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>

        <Tab title="pnpm">
          Install packages in your working directory:

          ```bash theme={null}
          pnpm add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          pnpm add -g @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>
      </Tabs>
    </Accordion>

    <Tabs>
      <Tab title="Localnet">
        ```bash theme={null}
        # start local test-validator in a separate terminal
        light test-validator
        ```

        <Note>
          In the code examples, use `createRpc()` without arguments for localnet.
        </Note>
      </Tab>

      <Tab title="Devnet">
        Get an API key from [Helius](https://helius.dev) and add to `.env`:

        ```bash title=".env" theme={null}
        API_KEY=<your-helius-api-key>
        ```

        <Note>
          In the code examples, use `createRpc(RPC_URL)` with the devnet URL.
        </Note>
      </Tab>
    </Tabs>

    <Info>
      Before we can compress or decompresss, we need:

      * An SPL mint with a token pool for compression. This token pool can be created for new SPL mints via [`createMint()`](/compressed-tokens/guides/create-mint-with-token-pool) or added to existing SPL mints via [`createTokenPool()`](/compressed-tokens/guides/add-token-pools-to-mint-accounts).
      * For `compress()` SPL tokens in an Associated Token Account, or
      * For `decompress()` compressed token accounts with sufficient balance.
    </Info>

    <Tabs>
      <Tab title="Compress">
        ```typescript theme={null}
        import "dotenv/config";
        import { Keypair } from "@solana/web3.js";
        import { createRpc } from "@lightprotocol/stateless.js";
        import { createMint, mintTo, decompress, compress } from "@lightprotocol/compressed-token";
        import { createAssociatedTokenAccount } from "@solana/spl-token";
        import { homedir } from "os";
        import { readFileSync } from "fs";

        // devnet:
        const RPC_URL = `https://devnet.helius-rpc.com?api-key=${process.env.API_KEY!}`;
        // localnet:
        // const RPC_URL = undefined;
        const payer = Keypair.fromSecretKey(
            new Uint8Array(
                JSON.parse(readFileSync(`${homedir()}/.config/solana/id.json`, "utf8"))
            )
        );

        (async function () {
            // devnet:
            const rpc = createRpc(RPC_URL);
            // localnet:
            // const rpc = createRpc();

            // Setup: Get SPL tokens (needed to compress)
            const { mint } = await createMint(rpc, payer, payer.publicKey, 9);
            const splAta = await createAssociatedTokenAccount(rpc, payer, mint, payer.publicKey);
            await mintTo(rpc, payer, mint, payer.publicKey, payer, 1_000_000_000);
            await decompress(rpc, payer, mint, 1_000_000_000, payer, splAta);

            // Compress SPL tokens
            const recipient = Keypair.generate();
            const tx = await compress(rpc, payer, mint, 500_000_000, payer, splAta, recipient.publicKey);

            console.log("Mint:", mint.toBase58());
            console.log("Tx:", tx);
        })();
        ```
      </Tab>

      <Tab title="Decompress">
        ```typescript theme={null}
        import "dotenv/config";
        import { Keypair } from "@solana/web3.js";
        import { createRpc } from "@lightprotocol/stateless.js";
        import { createMint, mintTo, decompress } from "@lightprotocol/compressed-token";
        import { createAssociatedTokenAccount } from "@solana/spl-token";
        import { homedir } from "os";
        import { readFileSync } from "fs";

        // devnet:
        const RPC_URL = `https://devnet.helius-rpc.com?api-key=${process.env.API_KEY!}`;
        // localnet:
        // const RPC_URL = undefined;
        const payer = Keypair.fromSecretKey(
            new Uint8Array(
                JSON.parse(readFileSync(`${homedir()}/.config/solana/id.json`, "utf8"))
            )
        );

        (async function () {
            // devnet:
            const rpc = createRpc(RPC_URL);
            // localnet:
            // const rpc = createRpc();

            // Setup: Create mint and mint compressed tokens
            const { mint } = await createMint(rpc, payer, payer.publicKey, 9);
            await mintTo(rpc, payer, mint, payer.publicKey, payer, 1_000_000_000);
            const splAta = await createAssociatedTokenAccount(rpc, payer, mint, payer.publicKey);

            // Decompress to SPL tokens
            const tx = await decompress(rpc, payer, mint, 500_000_000, payer, splAta);

            console.log("Mint:", mint.toBase58());
            console.log("Tx:", tx);
        })();
        ```
      </Tab>
    </Tabs>

    <Info>
      Make sure the SPL mint has a token pool for compression.<br /> The script creates this token pool for you.

      For development, you can create a new mint with token pool via [`createMint()`](/compressed-tokens/guides/create-mint-with-token-pool) or add a token pool to an existing mint via [`createTokenPool()`](/compressed-tokens/guides/add-token-pools-to-mint-accounts).
    </Info>
  </Step>
</Steps>

# Troubleshooting

<AccordionGroup>
  <Accordion title="Insufficient balance between decompress and compress">
    Check your balances before operations:

    ```typescript theme={null}
    // 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());
    ```
  </Accordion>

  <Accordion title="Invalid owner">
    Ensure the signer owns the tokens being decompressed/compressed:

    ```typescript theme={null}
    // 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,
    );
    ```
  </Accordion>
</AccordionGroup>

# Advanced Configuration

<AccordionGroup>
  <Accordion title="Compress to Different Owner">
    Compress tokens directly to someone else:

    ```typescript theme={null}
    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
    );
    ```
  </Accordion>

  <Accordion title="Batch Operations">
    Compress multiple token accounts:

    ```typescript theme={null}
    // 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);
    ```
  </Accordion>

  <Accordion title="Decompress with Delegate Authority">
    Decompress tokens using delegate authority:

    ```typescript theme={null}
    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)
    );
    ```
  </Accordion>
</AccordionGroup>

# Next Steps

<Card title="How to Compress Complete SPL Token Accounts" icon="chevron-right" href="/compressed-tokens/guides/compress-spl-token-account" />


# Compress Complete SPL Token Accounts
Source: https://www.zkcompression.com/compressed-tokens/guides/compress-spl-token-account

Compress the entire balance of an SPL token account to reclaim rent. Optionally leave some tokens in SPL format.

<CodeGroup>
  ```typescript compressSplTokenAccount() theme={null}
  // Compress entire SPL token account balance
  const transactionSignature = await compressSplTokenAccount(
      rpc,
      payer,
      mint, // SPL mint with token pool for compression
      owner,
      tokenAccount, // SPL token account to compress
  );
  ```

  ```typescript partialCompression() theme={null}
  // Compress account while keeping some tokens in SPL format
  const transactionSignature = await compressSplTokenAccount(
      rpc,
      payer,
      mint, // SPL mint with token pool for compression
      owner,
      tokenAccount, // SPL token account to compress
      remainingAmount, // amount to keep in SPL format
  );
  ```
</CodeGroup>

<Note>
  After compression, empty token accounts can now be closed to reclaim rent with [`closeAccount()`](https://solana.com/developers/cookbook/tokens/close-token-accounts).
</Note>

<Tip>
  **Function Difference and Best Practice:**

  * `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.
  * `compress(amount, sourceTokenAccount, toAddress)` compresses specific amounts from source to a specified recipient. Use for transfers and precise amounts. [Here is how](/compressed-tokens/guides/compress-decompress).
</Tip>

## Get Started

<Steps>
  <Step>
    ### Compress SPL Token Accounts

    <Accordion title="Installation">
      <Tabs>
        <Tab title="npm">
          Install packages in your working directory:

          ```bash theme={null}
          npm install @lightprotocol/stateless.js@beta \
                      @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          npm install -g @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>

        <Tab title="yarn">
          Install packages in your working directory:

          ```bash theme={null}
          yarn add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          yarn global add @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>

        <Tab title="pnpm">
          Install packages in your working directory:

          ```bash theme={null}
          pnpm add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          pnpm add -g @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>
      </Tabs>
    </Accordion>

    <Tabs>
      <Tab title="Localnet">
        ```bash theme={null}
        # start local test-validator in a separate terminal
        light test-validator
        ```

        <Note>
          In the code examples, use `createRpc()` without arguments for localnet.
        </Note>
      </Tab>

      <Tab title="Devnet">
        Get an API key from [Helius](https://helius.dev) and add to `.env`:

        ```bash title=".env" theme={null}
        API_KEY=<your-helius-api-key>
        ```

        <Note>
          In the code examples, use `createRpc(RPC_URL)` with the devnet URL.
        </Note>
      </Tab>
    </Tabs>

    ```typescript theme={null}
    import "dotenv/config";
    import { Keypair } from "@solana/web3.js";
    import { createRpc, bn } from "@lightprotocol/stateless.js";
    import { createMint, compressSplTokenAccount } from "@lightprotocol/compressed-token";
    import { createAssociatedTokenAccount, mintTo, TOKEN_PROGRAM_ID } from "@solana/spl-token";
    import { homedir } from "os";
    import { readFileSync } from "fs";

    // devnet:
    const RPC_URL = `https://devnet.helius-rpc.com?api-key=${process.env.API_KEY!}`;
    // localnet:
    // const RPC_URL = undefined;
    const payer = Keypair.fromSecretKey(
        new Uint8Array(
            JSON.parse(readFileSync(`${homedir()}/.config/solana/id.json`, "utf8"))
        )
    );

    (async function () {
        // devnet:
        const rpc = createRpc(RPC_URL);
        // localnet:
        // const rpc = createRpc();

        // Setup: Create mint and SPL token account with tokens
        const { mint } = await createMint(rpc, payer, payer.publicKey, 9);
        const owner = Keypair.generate();
        const tokenAccount = await createAssociatedTokenAccount(
            rpc,
            payer,
            mint,
            owner.publicKey,
            undefined,
            TOKEN_PROGRAM_ID
        );
        await mintTo(rpc, payer, mint, tokenAccount, payer, bn(1_000_000_000).toNumber());

        // Compress entire SPL token account balance
        const tx = await compressSplTokenAccount(
            rpc,
            payer,
            mint,
            owner,
            tokenAccount
        );

        console.log("Mint:", mint.toBase58());
        console.log("Tx:", tx);
    })();
    ```

    <Info>
      Make sure the SPL mint has a token pool for compression.<br /> The script creates this token pool for you.

      For development, you can create a new mint with token pool via [`createMint()`](/compressed-tokens/guides/create-mint-with-token-pool) or add a token pool to an existing mint via [`createTokenPool()`](/compressed-tokens/guides/add-token-pools-to-mint-accounts).
    </Info>
  </Step>
</Steps>

# Troubleshooting

<AccordionGroup>
  <Accordion title="Insufficient balance in token account">
    The token account doesn't have enough tokens for the operation.

    ```typescript theme={null}
    // Check token account balance before compression
    const balance = await rpc.getTokenAccountBalance(tokenAccount);

    if (Number(balance.value.amount) === 0) {
        console.log("Token account is empty");
        return;
    }

    console.log("Available balance:", Number(balance.value.amount));

    // Proceed with compression
    const compressTx = await compressSplTokenAccount(
        rpc,
        payer,
        mint,
        owner,
        tokenAccount,
    );
    ```
  </Accordion>

  <Accordion title="Remaining amount exceeds balance">
    The `remainingAmount` parameter exceeds the current account balance.

    ```typescript theme={null}
    const balance = await rpc.getTokenAccountBalance(tokenAccount);
    const availableAmount = Number(balance.value.amount);
    const remainingAmount = bn(500_000_000); // 0.5 tokens

    if (remainingAmount.gt(bn(availableAmount))) {
        console.log(`Cannot leave ${remainingAmount.toString()} tokens`);
        console.log(`Available balance: ${availableAmount}`);
        throw new Error("Remaining amount exceeds balance");
    }

    // Use valid remaining amount
    const compressTx = await compressSplTokenAccount(
        rpc,
        payer,
        mint,
        owner,
        tokenAccount,
        remainingAmount, // must be <= balance
    );
    ```
  </Accordion>
</AccordionGroup>

# Advanced Configuration

<AccordionGroup>
  <Accordion title="Partial Account Compression">
    Compress most tokens while leaving some in SPL format:

    ```typescript theme={null}
    import { bn } from '@lightprotocol/stateless.js';

    // Leave 100 tokens (0.1 with 9 decimals) in SPL account
    const remainingAmount = bn(100_000_000);

    const compressTx = await compressSplTokenAccount(
        rpc,
        payer,
        mint,
        owner,
        tokenAccount,
        remainingAmount, // amount to keep in SPL format
    );

    // Account will retain remainingAmount tokens
    ```
  </Accordion>

  <Accordion title="Compress Multiple Accounts">
    Compress several token accounts for the same mint:

    ```typescript theme={null}
    const tokenAccounts = [
        { account: new PublicKey("ACCOUNT_1"), owner: owner1 },
        { account: new PublicKey("ACCOUNT_2"), owner: owner2 },
        { account: new PublicKey("ACCOUNT_3"), owner: owner3 },
    ];

    // Compress each account
    for (const { account, owner } of tokenAccounts) {
        console.log(`Compressing account: ${account.toBase58()}`);

        try {
            const compressTx = await compressSplTokenAccount(
                rpc,
                payer,
                mint,
                owner,
                account,
            );
            console.log(`Compressed: ${compressTx}`);
        } catch (error) {
            console.log(`Failed: ${error.message}`);
        }
    }
    ```
  </Accordion>
</AccordionGroup>

# Next Steps

<Card title="How to Create a Mint Account with Token Pool" icon="chevron-right" href="/compressed-tokens/guides/create-mint-with-token-pool" />


# Create Compressed Token Accounts
Source: https://www.zkcompression.com/compressed-tokens/guides/create-compressed-token-accounts

Short guide to compressed token account creation with ZK Compression on Solana and difference to regular token accounts.

Compressed token accounts store ownership information for compressed tokens like regular token accounts with two core differences. Compressed Tokens

* do not require an <Tooltip>Associated Token Accounts (ATAs)</Tooltip>, and
* do not require a rent-exempt balance.

Compressed token accounts are created in the following scenarios:

1. `mintTo()` creates compressed token accounts for recipients.

<Card href="/compressed-tokens/guides/mint-compressed-tokens">How to Mint Compressed Tokens</Card>

2. `transfer()` consumes existing accounts of the sender as input, and creates new compressed token accounts with updated balances as output for the sender and recipient(s).

<Card href="/compressed-tokens/guides/transfer-compressed-tokens">Transfer Compressed Tokens</Card>


# Create a Mint Account with Token Pool for Compression
Source: https://www.zkcompression.com/compressed-tokens/guides/create-mint-with-token-pool

Create an SPL token mint with a token pool for compression. The token pool locks tokens while compressed and releases them when decompressed.

The mint account itself requires rent (like regular SPL mints), but individual compressed token accounts are rent-free.
Create a token pool for an existing SPL mint with [`createTokenPool()`](/compressed-tokens/guides/add-token-pools-to-mint-accounts) or use `createMint()` to create a new one from scratch.

<CodeGroup>
  ```typescript createMint() theme={null}
  // Create SPL mint with token pool for compression
  const { mint, transactionSignature } = await createMint(
      rpc,
      payer,
      mintAuthority.publicKey,
      decimals,
  );
  ```
</CodeGroup>

<Tip>
  **Best Practice:** Each mint supports a maximum of 4 token pools total. During compression/decompression, token pools get write-locked. Use `addTokenPools()` to create additional pools that increase per-block write-lock capacity.
</Tip>

## Get Started

<Steps>
  <Step>
    ### Create a Mint Account with Token Pool for Compression

    <Accordion title="Installation">
      <Tabs>
        <Tab title="npm">
          Install packages in your working directory:

          ```bash theme={null}
          npm install @lightprotocol/stateless.js@beta \
                      @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          npm install -g @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>

        <Tab title="yarn">
          Install packages in your working directory:

          ```bash theme={null}
          yarn add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          yarn global add @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>

        <Tab title="pnpm">
          Install packages in your working directory:

          ```bash theme={null}
          pnpm add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          pnpm add -g @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>
      </Tabs>
    </Accordion>

    <Tabs>
      <Tab title="Localnet">
        ```bash theme={null}
        # start local test-validator in a separate terminal
        light test-validator
        ```

        <Note>
          In the code examples, use `createRpc()` without arguments for localnet.
        </Note>
      </Tab>

      <Tab title="Devnet">
        Get an API key from [Helius](https://helius.dev) and add to `.env`:

        ```bash title=".env" theme={null}
        API_KEY=<your-helius-api-key>
        ```

        <Note>
          In the code examples, use `createRpc(RPC_URL)` with the devnet URL.
        </Note>
      </Tab>
    </Tabs>

    <Tabs>
      <Tab title="Action">
        ```typescript theme={null}
        import "dotenv/config";
        import { Keypair } from "@solana/web3.js";
        import { createRpc } from "@lightprotocol/stateless.js";
        import { createMint } 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!}`;
        // localnet:
        // const RPC_URL = undefined;
        const payer = Keypair.fromSecretKey(
            new Uint8Array(
                JSON.parse(readFileSync(`${homedir()}/.config/solana/id.json`, "utf8"))
            )
        );

        (async function () {
            // devnet:
            const rpc = createRpc(RPC_URL);
            // localnet:
            // const rpc = createRpc();

            const { mint, transactionSignature } = await createMint(
                rpc,
                payer,
                payer.publicKey,
                9
            );

            console.log("Mint:", mint.toBase58());
            console.log("Tx:", transactionSignature);
        })();
        ```
      </Tab>

      <Tab title="Instruction">
        ```typescript theme={null}
        import "dotenv/config";
        import {
            Keypair,
            ComputeBudgetProgram,
            PublicKey,
            Transaction,
            sendAndConfirmTransaction,
        } from "@solana/web3.js";
        import {
            createRpc,
            getBatchAddressTreeInfo,
            selectStateTreeInfo,
            LIGHT_TOKEN_PROGRAM_ID,
        } from "@lightprotocol/stateless.js";
        import { createMintInstruction } from "@lightprotocol/compressed-token";
        import { homedir } from "os";
        import { readFileSync } from "fs";

        const COMPRESSED_MINT_SEED = Buffer.from("compressed_mint");

        function findMintAddress(mintSigner: PublicKey): [PublicKey, number] {
            return PublicKey.findProgramAddressSync(
                [COMPRESSED_MINT_SEED, mintSigner.toBuffer()],
                LIGHT_TOKEN_PROGRAM_ID
            );
        }

        // 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 mintSigner = Keypair.generate();
            const addressTreeInfo = getBatchAddressTreeInfo();
            const stateTreeInfo = selectStateTreeInfo(await rpc.getStateTreeInfos());
            const [mintPda] = findMintAddress(mintSigner.publicKey);

            const validityProof = await rpc.getValidityProofV2(
                [],
                [{ address: mintPda.toBytes(), treeInfo: addressTreeInfo }]
            );

            const ix = createMintInstruction(
                mintSigner.publicKey,
                9,
                payer.publicKey,
                null,
                payer.publicKey,
                validityProof,
                addressTreeInfo,
                stateTreeInfo
            );

            const tx = new Transaction().add(
                ComputeBudgetProgram.setComputeUnitLimit({ units: 1_000_000 }),
                ix
            );
            const signature = await sendAndConfirmTransaction(rpc, tx, [payer, mintSigner]);

            console.log("Mint:", mintPda.toBase58());
            console.log("Tx:", signature);
        })();
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

# Advanced Configuration

<AccordionGroup>
  <Accordion title="Customize Mint Authority">
    Customize who can mint new compressed tokens.

    ```typescript theme={null}
    const mintAuthority = Keypair.generate();

    const { mint, transactionSignature } = await createMint(
        rpc,
        payer,
        mintAuthority.publicKey,
        9,
    );
    ```
  </Accordion>

  <Accordion title="Add Freeze Authority">
    Customize who can freeze/thaw compressed token accounts.

    ```typescript theme={null}
    const freezeAuthority = Keypair.generate();

    const { mint, transactionSignature } = await createMint(
        rpc,
        payer,
        payer.publicKey, // mint authority
        9, // decimals
        Keypair.generate(), // mint keypair
        undefined, // confirm options
        undefined, // token program ID
        freezeAuthority.publicKey, // freeze authority
    );
    ```
  </Accordion>
</AccordionGroup>

# Next Steps

<Card title="How to Add Token Pools for Existing Mints" icon="chevron-right" href="/compressed-tokens/guides/add-token-pools-to-mint-accounts" />


# Approve and Revoke Delegate Authority
Source: https://www.zkcompression.com/compressed-tokens/guides/delegate

Grant and remove delegate spending authority for compressed tokens with approve() and revoke(). Only the token owner can perform these operations.

The `approve()` and `revoke()` functions grant and remove delegate spending authority for compressed tokens. Only the token owner can perform these instructions.

<CodeGroup>
  ```typescript approve() theme={null}
  // Approve delegate for spending up to the specified amount
  const approveSignature = await approve(
      rpc,
      payer,
      mint, // SPL mint with token pool for compression
      amount,
      owner,
      delegate.publicKey, // delegate account
  );
  ```

  ```typescript revoke() theme={null}
  // Get delegated accounts for revocation
  const delegatedAccounts = await rpc.getCompressedTokenAccountsByDelegate(
      delegate.publicKey,
      { mint }
  );

  // Revoke delegate authority
  const revokeSignature = await revoke(
      rpc,
      payer,
      delegatedAccounts.items, // delegated compressed token accounts
      owner,
  );
  ```
</CodeGroup>

## Get Started

<Steps>
  <Step>
    ### Approve / Revoke Delegates

    <Accordion title="Installation">
      <Tabs>
        <Tab title="npm">
          Install packages in your working directory:

          ```bash theme={null}
          npm install @lightprotocol/stateless.js@beta \
                      @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          npm install -g @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>

        <Tab title="yarn">
          Install packages in your working directory:

          ```bash theme={null}
          yarn add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          yarn global add @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>

        <Tab title="pnpm">
          Install packages in your working directory:

          ```bash theme={null}
          pnpm add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          pnpm add -g @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>
      </Tabs>
    </Accordion>

    <Tabs>
      <Tab title="Localnet">
        ```bash theme={null}
        # start local test-validator in a separate terminal
        light test-validator
        ```

        <Note>
          In the code examples, use `createRpc()` without arguments for localnet.
        </Note>
      </Tab>

      <Tab title="Devnet">
        Get an API key from [Helius](https://helius.dev) and add to `.env`:

        ```bash title=".env" theme={null}
        API_KEY=<your-helius-api-key>
        ```

        <Note>
          In the code examples, use `createRpc(RPC_URL)` with the devnet URL.
        </Note>
      </Tab>
    </Tabs>

    <Tabs>
      <Tab title="Approve">
        ```typescript theme={null}
        import "dotenv/config";
        import { Keypair } from "@solana/web3.js";
        import { createRpc } from "@lightprotocol/stateless.js";
        import { createMint, mintTo, approve } from "@lightprotocol/compressed-token";
        import BN from "bn.js";
        import { homedir } from "os";
        import { readFileSync } from "fs";

        // devnet:
        const RPC_URL = `https://devnet.helius-rpc.com?api-key=${process.env.API_KEY!}`;
        // localnet:
        // const RPC_URL = undefined;
        const payer = Keypair.fromSecretKey(
            new Uint8Array(
                JSON.parse(readFileSync(`${homedir()}/.config/solana/id.json`, "utf8"))
            )
        );

        (async function () {
            // devnet:
            const rpc = createRpc(RPC_URL);
            // localnet:
            // const rpc = createRpc();

            // Setup: Create mint and mint tokens
            const { mint } = await createMint(rpc, payer, payer.publicKey, 9);
            const owner = Keypair.generate();
            await mintTo(rpc, payer, mint, owner.publicKey, payer, 1_000_000_000);

            // Approve delegate
            const delegate = Keypair.generate();
            const tx = await approve(rpc, payer, mint, new BN(500_000_000), owner, delegate.publicKey);

            console.log("Mint:", mint.toBase58());
            console.log("Delegate:", delegate.publicKey.toBase58());
            console.log("Tx:", tx);
        })();
        ```
      </Tab>

      <Tab title="Revoke">
        ```typescript theme={null}
        import "dotenv/config";
        import { Keypair } from "@solana/web3.js";
        import { createRpc } from "@lightprotocol/stateless.js";
        import { createMint, mintTo, approve, revoke } from "@lightprotocol/compressed-token";
        import BN from "bn.js";
        import { homedir } from "os";
        import { readFileSync } from "fs";

        // devnet:
        const RPC_URL = `https://devnet.helius-rpc.com?api-key=${process.env.API_KEY!}`;
        // localnet:
        // const RPC_URL = undefined;
        const payer = Keypair.fromSecretKey(
            new Uint8Array(
                JSON.parse(readFileSync(`${homedir()}/.config/solana/id.json`, "utf8"))
            )
        );

        (async function () {
            // devnet:
            const rpc = createRpc(RPC_URL);
            // localnet:
            // const rpc = createRpc();

            // Setup: Create mint, mint tokens, and approve delegate
            const { mint } = await createMint(rpc, payer, payer.publicKey, 9);
            const owner = Keypair.generate();
            await mintTo(rpc, payer, mint, owner.publicKey, payer, 1_000_000_000);
            const delegate = Keypair.generate();
            await approve(rpc, payer, mint, new BN(500_000_000), owner, delegate.publicKey);

            // Get delegated accounts and revoke
            const delegatedAccounts = await rpc.getCompressedTokenAccountsByDelegate(delegate.publicKey, { mint });
            const tx = await revoke(rpc, payer, delegatedAccounts.items, owner);

            console.log("Mint:", mint.toBase58());
            console.log("Tx:", tx);
        })();
        ```
      </Tab>
    </Tabs>

    <Info>
      Before we approve or revoke delegates, we need:

      * compressed token accounts to delegate or revoke delegation from, and
      * an SPL mint with a token pool for compression. This token pool can be created for new SPL mints via [`createMint()`](/compressed-tokens/guides/create-mint-with-token-pool) or added to existing SPL mints via [`createTokenPool()`](/compressed-tokens/guides/add-token-pools-to-mint-accounts).
    </Info>
  </Step>
</Steps>

# Troubleshooting

<AccordionGroup>
  <Accordion title="Account is not delegated">
    Attempting to revoke non-delegated accounts.

    ```typescript theme={null}
    /// Verify accounts are delegated before revocation.
    const delegateAccounts = await rpc.getCompressedTokenAccountsByDelegate(
        delegate.publicKey,
        { mint }
    );

    if (delegateAccounts.items.length === 0) {
        console.log("No delegated accounts to revoke");
        return;
    }
    ```
  </Accordion>
</AccordionGroup>

# Advanced Configuration

<AccordionGroup>
  <Accordion title="Approve Multiple Delegates">
    ```typescript theme={null}
    const delegates = [
        Keypair.generate().publicKey,
        Keypair.generate().publicKey,
    ];

    const amounts = [
        200_000_000, // 0.2 tokens to first delegate
        300_000_000, // 0.3 tokens to second delegate
    ];

    // Approve each delegate
    for (let i = 0; i < delegates.length; i++) {
        const approveTx = await approve(
            rpc,
            payer,
            mint,
            amounts[i],
            tokenOwner,
            delegates[i],
        );

        console.log(`Delegate ${i + 1} approved:`, approveTx);
    }
    ```
  </Accordion>

  <Accordion title="Revoke Multiple Delegates">
    ```typescript theme={null}
    const delegates = [
        new PublicKey("DELEGATE_1_ADDRESS"),
        new PublicKey("DELEGATE_2_ADDRESS"),
    ];

    // Revoke each delegate
    for (const delegate of delegates) {
        // Get delegated accounts for this delegate
        const delegateAccounts = await rpc.getCompressedTokenAccountsByDelegate(
            delegate,
            { mint }
        );

        if (delegateAccounts.items.length > 0) {
            const revokeTx = await revoke(
                rpc,
                payer,
                delegateAccounts.items,
                tokenOwner,
            );

            console.log(`Delegate ${delegate.toBase58()} revoked:`, revokeTx);
        }
    }
    ```
  </Accordion>
</AccordionGroup>

# Next Steps

<Card title="Check out the advanced guides for airdrops, combining multiple instructions in one transaction, and client examples." icon="chevron-right" href="/compressed-tokens/advanced-guides" />


# Merge Compressed Token Accounts
Source: https://www.zkcompression.com/compressed-tokens/guides/merge-compressed-token-accounts

Consolidate multiple compressed token accounts of the same mint into a single account to reduce fragmentation.

The `mergeTokenAccounts()` function consolidates multiple compressed accounts of the same mint into a single compressed account.

The function

1. consumes multiple compressed token accounts (up to 8 accounts), and
2. creates a single output compressed token account with combined balance for the owner.

<Tip>
  State trees where compressed account's are stored, are append only. `mergeTokenAccounts()` reduces account fragmentation to simplify balance calculations from `getCompressedTokenAccountsByOwner`.
</Tip>

<CodeGroup>
  ```typescript function-merge-accounts.ts theme={null}
  // Combines multiple compressed token accounts into single compressed account
  const transactionSignature = await mergeTokenAccounts(
      rpc,
      payer,
      mint, // SPL mint with token pool for compression
      owner,
  );
  ```
</CodeGroup>

## Get Started

<Steps>
  <Step>
    ### Merge Compressed Accounts

    <Accordion title="Installation">
      <Tabs>
        <Tab title="npm">
          Install packages in your working directory:

          ```bash theme={null}
          npm install @lightprotocol/stateless.js@beta \
                      @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          npm install -g @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>

        <Tab title="yarn">
          Install packages in your working directory:

          ```bash theme={null}
          yarn add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          yarn global add @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>

        <Tab title="pnpm">
          Install packages in your working directory:

          ```bash theme={null}
          pnpm add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          pnpm add -g @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>
      </Tabs>
    </Accordion>

    <Tabs>
      <Tab title="Localnet">
        ```bash theme={null}
        # start local test-validator in a separate terminal
        light test-validator
        ```

        <Note>
          In the code examples, use `createRpc()` without arguments for localnet.
        </Note>
      </Tab>

      <Tab title="Devnet">
        Get an API key from [Helius](https://helius.dev) and add to `.env`:

        ```bash title=".env" theme={null}
        API_KEY=<your-helius-api-key>
        ```

        <Note>
          In the code examples, use `createRpc(RPC_URL)` with the devnet URL.
        </Note>
      </Tab>
    </Tabs>

    ```typescript theme={null}
    import "dotenv/config";
    import { Keypair } from "@solana/web3.js";
    import { createRpc, bn } from "@lightprotocol/stateless.js";
    import { createMint, mintTo, mergeTokenAccounts } 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!}`;
    // localnet:
    // const RPC_URL = undefined;
    const payer = Keypair.fromSecretKey(
        new Uint8Array(
            JSON.parse(readFileSync(`${homedir()}/.config/solana/id.json`, "utf8"))
        )
    );

    (async function () {
        // devnet:
        const rpc = createRpc(RPC_URL);
        // localnet:
        // const rpc = createRpc();

        // Setup: Create mint and mint multiple times to create multiple accounts
        const { mint } = await createMint(rpc, payer, payer.publicKey, 9);
        const owner = Keypair.generate();
        await mintTo(rpc, payer, mint, owner.publicKey, payer, bn(100_000_000));
        await mintTo(rpc, payer, mint, owner.publicKey, payer, bn(200_000_000));
        await mintTo(rpc, payer, mint, owner.publicKey, payer, bn(300_000_000));

        // Merge all accounts for owner
        const tx = await mergeTokenAccounts(rpc, payer, mint, owner);

        console.log("Mint:", mint.toBase58());
        console.log("Tx:", tx);
    })();
    ```

    <Info>
      Before we merge compressed accounts, we need

      * Multiple compressed token accounts of the same mint owned by the same wallet, and
      * an SPL mint with a token pool for compression. This token pool can be created for new SPL mints via [`createMint()`](/compressed-tokens/guides/create-mint-with-token-pool) or added to existing SPL mints via [`createTokenPool()`](/compressed-tokens/guides/add-token-pools-to-mint-accounts).
    </Info>
  </Step>
</Steps>

# Troubleshooting

<AccordionGroup>
  <Accordion title="No compressed token accounts found">
    The owner has no compressed token accounts for the specified mint:

    ```typescript theme={null}
    // Check if accounts exist before merging
    const accounts = await rpc.getCompressedTokenAccountsByOwner(
        owner.publicKey,
        { mint }
    );

    if (accounts.items.length === 0) {
        console.log("No compressed token accounts found for this mint");
        console.log("Mint address:", mint.toBase58());
        console.log("Owner address:", owner.publicKey.toBase58());
        return;
    }

    console.log(`Found ${accounts.items.length} accounts to merge`);
    ```
  </Accordion>
</AccordionGroup>

# Advanced Configuration

<AccordionGroup>
  <Accordion title="Conditional Merging">
    ```typescript theme={null}
    // Get account count
    const accounts = await rpc.getCompressedTokenAccountsByOwner(
        owner.publicKey,
        { mint }
    );

    // Only merge if more than 2 accounts
    if (accounts.items.length > 2) {
        console.log(`Merging ${accounts.items.length} accounts...`);

        const mergeTx = await mergeTokenAccounts(
            rpc,
            payer,
            mint,
            tokenOwner,
        );

        console.log("Merge completed:", mergeTx);
    } else {
        console.log("Merge not needed - optimal account structure");
    }
    ```
  </Accordion>

  <Accordion title="Merge Multiple Mints">
    ```typescript theme={null}
    const mints = [
        new PublicKey("MINT_1_ADDRESS"),
        new PublicKey("MINT_2_ADDRESS"),
    ];

    // Merge accounts for each mint
    for (const mint of mints) {
        console.log(`Merging accounts for mint: ${mint.toBase58()}`);

        const mergeTx = await mergeTokenAccounts(
            rpc,
            payer,
            mint,
            tokenOwner,
        );

        console.log(`Merge completed: ${mergeTx}`);
    }
    ```
  </Accordion>
</AccordionGroup>

# Next Steps

<Card title="How to Approve and Revoke Delegate Authority" icon="chevron-right" href="/compressed-tokens/guides/delegate" />


# Mint Compressed Tokens
Source: https://www.zkcompression.com/compressed-tokens/guides/mint-compressed-tokens

Mint tokens to compressed token accounts for recipients and increases a mint's token supply. Only the mint authority can perform this operation. 

```typescript theme={null}
// Mint compressed tokens - mints SPL tokens to pool, creates compressed token accounts
const transactionSignature = await mintTo(
    rpc,
    payer,
    mint, // SPL mint with token pool for compression
    recipient, // recipient address (toPubkey parameter)
    payer, // mint authority
    amount,
);
```

## Get Started

<Steps>
  <Step>
    ### Mint Compressed Tokens

    <Accordion title="Installation">
      <Tabs>
        <Tab title="npm">
          Install packages in your working directory:

          ```bash theme={null}
          npm install @lightprotocol/stateless.js@beta \
                      @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          npm install -g @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>

        <Tab title="yarn">
          Install packages in your working directory:

          ```bash theme={null}
          yarn add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          yarn global add @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>

        <Tab title="pnpm">
          Install packages in your working directory:

          ```bash theme={null}
          pnpm add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          pnpm add -g @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>
      </Tabs>
    </Accordion>

    <Tabs>
      <Tab title="Localnet">
        ```bash theme={null}
        # start local test-validator in a separate terminal
        light test-validator
        ```

        <Note>
          In the code examples, use `createRpc()` without arguments for localnet.
        </Note>
      </Tab>

      <Tab title="Devnet">
        Get an API key from [Helius](https://helius.dev) and add to `.env`:

        ```bash title=".env" theme={null}
        API_KEY=<your-helius-api-key>
        ```

        <Note>
          In the code examples, use `createRpc(RPC_URL)` with the devnet URL.
        </Note>
      </Tab>
    </Tabs>

    <Tabs>
      <Tab title="Action">
        ```typescript theme={null}
        import "dotenv/config";
        import { Keypair } from "@solana/web3.js";
        import { createRpc } from "@lightprotocol/stateless.js";
        import { createMint, mintTo } 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!}`;
        // localnet:
        // const RPC_URL = undefined;
        const payer = Keypair.fromSecretKey(
            new Uint8Array(
                JSON.parse(readFileSync(`${homedir()}/.config/solana/id.json`, "utf8"))
            )
        );

        (async function () {
            // devnet:
            const rpc = createRpc(RPC_URL);
            // localnet:
            // const rpc = createRpc();

            // Setup: Create mint
            const { mint } = await createMint(rpc, payer, payer.publicKey, 9);

            // Mint compressed tokens
            const recipient = Keypair.generate();
            const tx = await mintTo(rpc, payer, mint, recipient.publicKey, payer, 1_000_000_000);

            console.log("Mint:", mint.toBase58());
            console.log("Recipient:", recipient.publicKey.toBase58());
            console.log("Tx:", tx);
        })();
        ```
      </Tab>

      <Tab title="Instruction">
        ```typescript theme={null}
        import "dotenv/config";
        import { Keypair, ComputeBudgetProgram, Transaction, sendAndConfirmTransaction } from "@solana/web3.js";
        import { createRpc, bn, DerivationMode } from "@lightprotocol/stateless.js";
        import {
            createMintInterface,
            createAtaInterface,
            createMintToInterfaceInstruction,
            getMintInterface,
            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 recipient = Keypair.generate();
            await createAtaInterface(rpc, payer, mint, recipient.publicKey);
            const destination = getAssociatedTokenAddressInterface(mint, recipient.publicKey);

            const mintInterface = await getMintInterface(rpc, mint);

            let validityProof;
            if (mintInterface.merkleContext) {
                validityProof = await rpc.getValidityProofV2(
                    [
                        {
                            hash: bn(mintInterface.merkleContext.hash),
                            leafIndex: mintInterface.merkleContext.leafIndex,
                            treeInfo: mintInterface.merkleContext.treeInfo,
                            proveByIndex: mintInterface.merkleContext.proveByIndex,
                        },
                    ],
                    [],
                    DerivationMode.compressible
                );
            }

            const ix = createMintToInterfaceInstruction(
                mintInterface,
                destination,
                payer.publicKey,
                payer.publicKey,
                1_000_000_000,
                validityProof
            );

            const tx = new Transaction().add(
                ComputeBudgetProgram.setComputeUnitLimit({ units: 500_000 }),
                ix
            );
            const signature = await sendAndConfirmTransaction(rpc, tx, [payer]);

            console.log("Mint:", mint.toBase58());
            console.log("Tx:", signature);
        })();
        ```
      </Tab>
    </Tabs>

    <Info>
      Make sure the SPL mint has a token pool for compression.<br /> The script creates this token pool for you.

      For development, you can create a new mint with token pool via [`createMint()`](/compressed-tokens/guides/create-mint-with-token-pool) or add a token pool to an existing mint via [`createTokenPool()`](/compressed-tokens/guides/add-token-pools-to-mint-accounts).
    </Info>
  </Step>
</Steps>

# Troubleshooting

<AccordionGroup>
  <Accordion title="TokenPool not found">
    ```typescript theme={null}
    // Error message: "TokenPool not found. Please create a compressed token
    // pool for mint: [ADDRESS] via createTokenPool().
    ```

    The mint does no have a token pool for compression. Ensure you created the mint using `createMint`.

    ```typescript theme={null}
    // Create mint with token pool for compression
    import { createMint } from '@lightprotocol/compressed-token';
    const { mint } = await createMint(rpc, payer, payer.publicKey, 9);
    ```
  </Accordion>

  <Accordion title="TokenPool mint does not match the provided mint">
    The token pool info doesn't correspond to the mint address. Ensure you're fetching the correct pool:

    ```typescript theme={null}
    // Get the correct token pool for your mint
    const tokenPoolInfo = await getTokenPoolInfos(rpc, mint);
    ```
  </Accordion>

  <Accordion title="Amount and toPubkey arrays must have the same length">
    When minting to multiple recipients, ensure arrays are the same size.

    ```typescript theme={null}
    // Wrong: Mismatched array lengths
    const recipients = [addr1, addr2, addr3];
    const amounts = [100, 200]; // Only 2 amounts for 3 recipients

    // Correct: Same length arrays
    const recipients = [addr1, addr2, addr3];
    const amounts = [100, 200, 300]; // 3 amounts for 3 recipients
    ```
  </Accordion>
</AccordionGroup>

# Advanced Configuration

<AccordionGroup>
  <Accordion title="Mint to Multiple Recipients">
    ```typescript theme={null}
    // Mint different amounts to multiple recipients
    const recipients = [
        Keypair.generate().publicKey,
        Keypair.generate().publicKey,
        Keypair.generate().publicKey,
    ];

    const amounts = [
        1_000_000_000, // 1 token
        2_000_000_000, // 2 tokens
        500_000_000,   // 0.5 tokens
    ];

    const transactionSignature = await mintTo(
        rpc,
        payer,
        mint, // SPL mint with token pool for compression
        recipients, // array of recipients (toPubkey parameter)
        payer, // mint authority
        amounts, // array of amounts (amount parameter)
    );
    ```
  </Accordion>

  <Accordion title="With Custom Mint Authority">
    Mint tokens using a custom mint authority with `approveAndMintTo()`:

    ```typescript theme={null}
    import { approveAndMintTo } from '@lightprotocol/compressed-token';

    // Mint tokens with a separate mint authority
    const transactionSignature = await approveAndMintTo(
        rpc,
        payer,
        mint, // SPL mint with token pool for compression
        recipient.publicKey, // recipient of minted tokens (toPubkey parameter)
        mintAuthority, // mint authority
        mintAmount,
    );
    ```
  </Accordion>
</AccordionGroup>

# Next Steps

<Card title="How to Transfer Compressed Tokens" icon="chevron-right" href="/compressed-tokens/guides/transfer-compressed-tokens" />


# Transfer Compressed Tokens
Source: https://www.zkcompression.com/compressed-tokens/guides/transfer-compressed-tokens

Transfer compressed tokens between accounts. Transfers consume input accounts and create new output accounts with updated balances.

The `transfer()` function moves compressed tokens between accounts.

* SPL token transfers that update the existing account
* Compressed token transfers consume input accounts from the sender and create new output accounts for sender and recipient with updated balances.

<Tip>
  SPL token accounts can be compressed in the same transaction with `compress_or_decompress_amount`, if needed.
</Tip>

```typescript function-transfer-compressed-tokens.ts theme={null}
// Transfer compressed tokens
const transactionSignature = await transfer(
    rpc,
    payer,
    mint, // SPL mint with token pool for compression
    amount,
    payer,
    recipient, // destination address (toAddress parameter)
)
```

## Get Started

<Steps>
  <Step>
    ### Transfer Compressed Tokens

    <Accordion title="Installation">
      <Tabs>
        <Tab title="npm">
          Install packages in your working directory:

          ```bash theme={null}
          npm install @lightprotocol/stateless.js@beta \
                      @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          npm install -g @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>

        <Tab title="yarn">
          Install packages in your working directory:

          ```bash theme={null}
          yarn add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          yarn global add @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>

        <Tab title="pnpm">
          Install packages in your working directory:

          ```bash theme={null}
          pnpm add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          pnpm add -g @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>
      </Tabs>
    </Accordion>

    <Tabs>
      <Tab title="Localnet">
        ```bash theme={null}
        # start local test-validator in a separate terminal
        light test-validator
        ```

        <Note>
          In the code examples, use `createRpc()` without arguments for localnet.
        </Note>
      </Tab>

      <Tab title="Devnet">
        Get an API key from [Helius](https://helius.dev) and add to `.env`:

        ```bash title=".env" theme={null}
        API_KEY=<your-helius-api-key>
        ```

        <Note>
          In the code examples, use `createRpc(RPC_URL)` with the devnet URL.
        </Note>
      </Tab>
    </Tabs>

    ```typescript theme={null}
    import "dotenv/config";
    import { Keypair } from "@solana/web3.js";
    import { createRpc } from "@lightprotocol/stateless.js";
    import { createMint, mintTo, transfer } 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!}`;
    // localnet:
    // const RPC_URL = undefined;
    const payer = Keypair.fromSecretKey(
        new Uint8Array(
            JSON.parse(readFileSync(`${homedir()}/.config/solana/id.json`, "utf8"))
        )
    );

    (async function () {
        // devnet:
        const rpc = createRpc(RPC_URL);
        // localnet:
        // const rpc = createRpc();

        // Setup: Create mint and mint tokens
        const { mint } = await createMint(rpc, payer, payer.publicKey, 9);
        const sender = Keypair.generate();
        await mintTo(rpc, payer, mint, sender.publicKey, payer, 1_000_000_000);

        // Transfer compressed tokens
        const recipient = Keypair.generate();
        const tx = await transfer(rpc, payer, mint, 500_000_000, sender, recipient.publicKey);

        console.log("Mint:", mint.toBase58());
        console.log("Recipient:", recipient.publicKey.toBase58());
        console.log("Tx:", tx);
    })();
    ```

    <Info>
      Make sure the SPL mint has a token pool for compression.<br /> The script creates this token pool for you.

      For development, you can create a new mint with token pool via [`createMint()`](/compressed-tokens/guides/create-mint-with-token-pool) or add a token pool to an existing mint via [`createTokenPool()`](/compressed-tokens/guides/add-token-pools-to-mint-accounts).
    </Info>
  </Step>
</Steps>

# Troubleshooting

<AccordionGroup>
  <Accordion title="Insufficient balance for transfer">
    The sender doesn't have enough compressed tokens for the requested transfer amount.

    ```typescript theme={null}
    // Check current balance first
    const tokenAccounts = await rpc.getCompressedTokenAccountsByOwner(
        owner.publicKey,
        { mint }
    );

    if (tokenAccounts.items.length === 0) {
        throw new Error("No compressed token accounts found");
    }

    // Calculate total balance across all accounts
    const totalBalance = tokenAccounts.items.reduce(
        (sum, account) => sum.add(account.parsed.amount),
        new BN(0)
    );

    console.log("Available balance:", totalBalance.toString());

    // Ensure transfer amount doesn't exceed balance
    if (new BN(transferAmount).gt(totalBalance)) {
        throw new Error(`Transfer amount ${transferAmount} exceeds balance ${totalBalance.toString()}`);
    }
    ```
  </Accordion>

  <Accordion title="Account limit exceeded">
    The transfer requires more than 4 compressed accounts, which exceeds the transaction limit.

    ```typescript theme={null}
    // Error message: "Account limit exceeded: max X (4 accounts) per transaction.
    // Total balance: Y (Z accounts). Consider multiple transfers to spend full balance."

    // Split into multiple smaller transfers
    const maxTransferPerTx = 1_000_000_000; // Adjust based on your account sizes

    if (transferAmount > maxTransferPerTx) {
        console.log("Large transfer detected, splitting into multiple transactions...");

        let remainingAmount = transferAmount;
        while (remainingAmount > 0) {
            const currentTransfer = Math.min(remainingAmount, maxTransferPerTx);

            await transfer(
                rpc,
                payer,
                mint,
                currentTransfer,
                owner,
                recipient
            );

            remainingAmount -= currentTransfer;
            console.log(`Transferred ${currentTransfer}, remaining: ${remainingAmount}`);
        }
    }
    ```
  </Accordion>
</AccordionGroup>

# Advanced Configuration

<AccordionGroup>
  <Accordion title="Transfer to Multiple Recipients">
    Transfer to multiple recipients in separate transactions:

    ```typescript theme={null}
    const recipients = [
        Keypair.generate().publicKey,
        Keypair.generate().publicKey,
        Keypair.generate().publicKey,
    ];

    const amounts = [
        100_000_000, // 0.1 tokens
        200_000_000, // 0.2 tokens
        150_000_000, // 0.15 tokens
    ];

    for (let i = 0; i < recipients.length; i++) {
        const transactionSignature = await transfer(
            rpc,
            payer,
            mint,
            amounts[i],
            owner,
            recipients[i],
        );

        console.log(`Transfer ${i + 1} completed:`, transactionSignature);
    }
    ```
  </Accordion>

  <Accordion title="Transfer with Delegate Authority">
    Transfer tokens using delegate authority:

    ```typescript theme={null}
    import { approve, transferDelegated } from '@lightprotocol/compressed-token';

    // 1. Owner approves delegate
    await approve(
        rpc,
        payer,
        mint,
        amount,
        owner, // Signer
        delegate.publicKey, // PublicKey
    );

    // 2. Delegate transfers tokens
    await transferDelegated(
        rpc,
        payer,
        mint,
        transferAmount,
        delegate, // Signer - named "owner" in SDK
        recipient,
    );
    ```
  </Accordion>
</AccordionGroup>

# Next Steps

<Card title="How to Compress and Decompress SPL Tokens" icon="chevron-right" href="/compressed-tokens/guides/compress-decompress" />


# Overview
Source: https://www.zkcompression.com/compressed-tokens/overview

Overview to compressed tokens and guides with full code examples. Use for distributing tokens (eg rewards, airdrops) or creating associated token accounts for users.

<Check>
  **Compressed Tokens are supported by leading Solana wallets such as Phantom and Backpack.**
</Check>

| Creation          | Solana               | Compressed         |
| :---------------- | :------------------- | :----------------- |
| **Token Account** | \~2,000,000 lamports | **5,000** lamports |

1. Compressed token accounts store token balance, owner, and other information of tokens like SPL and light-tokens.
2. Compressed token accounts are rent-free.
3. Any light-token or SPL token can be compressed/decompressed at will.

## Recommended Usage of Compressed Tokens

<Card title="Token Distribution">
  Distribute tokens without paying upfront rent per recipient.

  <Card title="Create an Airdrop" icon="chevron-right" href="/compressed-tokens/advanced-guides/airdrop" />
</Card>

<Card title="Store SPL-token accounts rent-free">
  Compress existing SPL-token accounts to save rent costs for your users.

  <Card title="Compress SPL Token Accounts" icon="chevron-right" href="/compressed-tokens/guides/compress-spl-token-account" />
</Card>

# Get Started

<Accordion title="Installation & Setup">
  <Steps>
    <Step>
      ### Install dependencies

      <Tabs>
        <Tab title="npm">
          ```bash theme={null}
          npm install @lightprotocol/stateless.js@beta \
                      @lightprotocol/compressed-token@beta
          ```
        </Tab>

        <Tab title="yarn">
          ```bash theme={null}
          yarn add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```
        </Tab>

        <Tab title="pnpm">
          ```bash theme={null}
          pnpm add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```
        </Tab>
      </Tabs>
    </Step>

    <Step>
      ### Set up your developer environment

      <Tabs>
        <Tab title="Localnet">
          By default, all guides use Localnet.

          <Tabs>
            <Tab title="npm">
              ```bash theme={null}
              npm install -g @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>

            <Tab title="yarn">
              ```bash theme={null}
              yarn global add @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>

            <Tab title="pnpm">
              ```bash theme={null}
              pnpm add -g @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>
          </Tabs>

          ```bash theme={null}
          # Start a local test validator
          light test-validator

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

          ```typescript theme={null}
          // 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();
          ```
        </Tab>

        <Tab title="Devnet">
          Replace `<your-api-key>` with your actual API key. [Get your API key here](https://www.helius.dev/zk-compression), if you don't have one yet.

          ```typescript theme={null}
          import { createRpc } from "@lightprotocol/stateless.js";

          const RPC_ENDPOINT = "https://devnet.helius-rpc.com?api-key=<your_api_key>";
          const connection = createRpc(RPC_ENDPOINT);

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

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

          main();
          ```
        </Tab>
      </Tabs>
    </Step>
  </Steps>
</Accordion>

<Steps>
  <Step>
    ### Basic Guides

    | Guide                                                                                                  | Description                                                        |
    | :----------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------- |
    | [Create Compressed Token Accounts](/compressed-tokens/guides/create-compressed-token-accounts)         | Create compressed and learn difference to regular token accounts   |
    | [Mint Compressed Tokens](/compressed-tokens/guides/mint-compressed-tokens)                             | Create new compressed tokens to existing mint                      |
    | [Transfer Compressed Tokens](/compressed-tokens/guides/transfer-compressed-tokens)                     | Move compressed tokens between compressed accounts                 |
    | [Decompress and Compress Tokens](/compressed-tokens/guides/compress-decompress)                        | Convert SPL tokens between regular and compressed format           |
    | [Compress Complete SPL Token Accounts](/compressed-tokens/guides/compress-spl-token-account)           | Compress complete SPL token accounts and reclaim rent afterwards   |
    | [Create a Mint with Token Pool for Compression](/compressed-tokens/guides/create-mint-with-token-pool) | Create new SPL mint with token pool for compression                |
    | [Create Token Pools for Mint Accounts](/compressed-tokens/guides/add-token-pools-to-mint-accounts)     | Create token pool for compression for existing SPL mints           |
    | [Merge Compressed Accounts](/compressed-tokens/guides/merge-compressed-token-accounts)                 | Consolidate multiple compressed accounts of the same mint into one |
    | [Approve and Revoke Delegate Authority](/compressed-tokens/guides/delegate)                            | Approve or revoke delegates for compressed token accounts          |
  </Step>

  <Step>
    ### Advanced Guides

    | Guide                                                                                                                      | Description                                                                                                       |
    | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
    | [Create an Airdrop without Claim](/compressed-tokens/advanced-guides/airdrop)                                              | ZK Compression is the most efficient way to distribute SPL tokens. Distribute via Webapp or customize with claim. |
    | [Combine Instructions in One Transaction](/compressed-tokens/advanced-guides/how-to-combine-operations-in-one-transaction) | Execute multiple token instructions within a single transaction                                                   |
    | [For Wallet Applications](/compressed-tokens/advanced-guides/add-wallet-support-for-compressed-tokens)                     | Add compressed token support in your wallet application                                                           |
    | [Use Token-2022 with Compression](/compressed-tokens/advanced-guides/use-token-2022-with-compression)                      | Create compressed Token-2022 mints with metadata and other extensions                                             |
    | [Privy Guide](/compressed-tokens/for-privy)                                                                                | Integrate compressed tokens with Privy embedded wallets for rent-free token accounts                              |
  </Step>
</Steps>


# Home
Source: https://www.zkcompression.com/home



<div>
  <HeroCubeGrid />

  <LiquidGlassPill title="Scale Anything on Solana." />
</div>

<div>
  <CardGroup>
    <Card title="Light Token Program" icon="expand" href="/light-token/welcome">
      High performance token standard for rent-free DeFi and Payments.
    </Card>

    <Card title="ZK Compression Core" icon="compress" href="/welcome">
      Core primitives for rent-free tokens & accounts.
    </Card>
  </CardGroup>

  ## Features

  <CardGroup>
    <Card title="Rent-free Accounts">Create Solana accounts without paying upfront rent.</Card>
    <Card title="L1 Performance & Security">Execution onchain on Solana.</Card>
    <Card title="Fully Composable">Works with existing programs and accounts.</Card>
  </CardGroup>

  ## Quickstart

  <Steps>
    <Step>
      ### Installation

      <Tabs>
        <Tab title="npm">
          Install packages in your working directory:

          ```bash theme={null}
          npm install @lightprotocol/stateless.js@beta \
                      @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          npm install -g @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>

        <Tab title="yarn">
          Install packages in your working directory:

          ```bash theme={null}
          yarn add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          yarn global add @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>

        <Tab title="pnpm">
          Install packages in your working directory:

          ```bash theme={null}
          pnpm add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          pnpm add -g @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>
      </Tabs>
    </Step>

    <Step>
      ### Get started

      <Card title="Mint tokens in under 3 minutes." icon="bolt" href="/light-token/quickstart" />
    </Step>
  </Steps>

  ## DeFi Integration

  <CardGroup>
    <Card title="Program Integration" icon="code" href="/light-token/defi/programs">
      Build rent-free AMMs and DeFi programs with minimal code changes.
    </Card>

    <Card title="Router Integration" icon="route" href="/light-token/defi/routers">
      Add support for rent-free AMMs to your aggregator or router.
    </Card>
  </CardGroup>

  ## Toolkits

  <Tabs>
    <Tab title="Light Token">
      <Card title="Stablecoin Payments" icon="credit-card" href="/light-token/toolkits/for-payments">
        Integrate light-token APIs with familiar SPL patterns.
      </Card>

      <Card title="Wallets" icon="wallet" href="/light-token/toolkits/for-wallets">
        Allow users to display and swap light-tokens.
      </Card>
    </Tab>

    <Tab title="Compressed Tokens">
      <Card title="Airdrop Guide" icon="parachute-box" href="/compressed-tokens/advanced-guides/airdrop">
        ZK Compression is the most efficient way to distribute SPL tokens.
      </Card>

      <Card title="Privy Guide" icon="wallet" href="/compressed-tokens/for-privy">
        Add rent-free SPL token accounts and transfers to your Privy embedded wallet.
      </Card>

      <Card title="Wallets" icon="wallet" href="/compressed-tokens/advanced-guides/add-wallet-support-for-compressed-tokens">
        Allow users to display and swap compressed tokens.
      </Card>

      <Card title="Token-2022" icon="coins" href="/compressed-tokens/advanced-guides/use-token-2022-with-compression">
        Integrate Token-2022 extensions with compressed tokens.
      </Card>

      <Card title="Example Token Distribution Flows" icon="angles-right" href="https://github.com/Lightprotocol/example-token-distribution">
        Common token distribution flows (airdrops, payments, rewards).
      </Card>
    </Tab>

    <Tab title="ZK">
      <Card title="Nullifiers" icon="code-commit" href="/zk/overview#nullifiers-on-solana">
        Deterministically derived addresses to prevent double spending.
      </Card>

      <Card title="Groth16 Proof Verification" icon="square-check" href="/zk/overview#groth16-proof-verification-on-solana">
        Small proof size and fast verification.
      </Card>

      <Card title="Merklelized State" icon="hard-drive" href="/zk/overview#merklelized-state-with-indexer-support">
        Use existing state Merkle trees with RPC indexer support.
      </Card>
    </Tab>
  </Tabs>

  ## Cookbooks

  <CardGroup>
    <Card title="Light Token Program" icon="coins" href="/light-token/cookbook/overview">
      Program and client guides for mints, token accounts, and transfers.
    </Card>

    <Card title="Compressed Tokens" icon="wallet" href="/compressed-tokens/overview">
      Client guides for compressed token accounts.
    </Card>

    <Card title="Compressed PDAs" icon="users" href="/compressed-pdas/overview">
      Program and client guides for rent-free PDA accounts.
    </Card>

    <Card title="Solana Attestation Service (Devnet)" icon="stamp" href="https://github.com/solana-foundation/solana-attestation-service/tree/a8fb187978ecea0b165e63767c7e6b1c036e7b52/examples/typescript/attestation-flow-guides">
      Build with compressed attestations using Rust or Typescript.
    </Card>
  </CardGroup>

  ## Using AI in Development

  Download agent skill or view [skill.md](https://www.zkcompression.com/skill.md):

  ```bash theme={null}
  npx skills add https://zkcompression.com
  ```

  |          |                                                                              |
  | :------- | :--------------------------------------------------------------------------- |
  | MCP      | Connect AI tools to the Light Protocol repository via Model Context Protocol |
  | DeepWiki | Use Deepwiki for advanced AI assistance with your development.               |

  <Tabs>
    <Tab title="Claude Code">
      ```bash theme={null}
      claude mcp add -s user -t http deepwiki https://mcp.deepwiki.com/mcp
      claude mcp add -s user -t http zkcompression https://www.zkcompression.com/mcp
      ```
    </Tab>

    <Tab title="Codex">
      ```bash theme={null}
      codex mcp add zkcompression -- npx -y mcp-remote@latest https://www.zkcompression.com/mcp
      codex mcp add deepwiki -- npx -y mcp-remote@latest https://mcp.deepwiki.com/mcp
      ```
    </Tab>

    <Tab title="Most Clients (Windsurf, Cursor, ...)">
      ```json theme={null}
      {
        "mcpServers": {
          "deepwiki": {
            "serverUrl": "https://mcp.deepwiki.com/sse"
          },
          "zkcompression": {
            "command": "npx",
            "args": ["-y", "mcp-remote@latest", "https://www.zkcompression.com/mcp"]
          }
        }
      }
      ```
    </Tab>
  </Tabs>

  <Card title="AI Tools Guide" icon="chevron-right" href="/ai-tools/guide" />

  ## Resources

  <CardGroup>
    <Card title="Security Audits" icon="shield-check" href="https://github.com/Lightprotocol/light-protocol/tree/main/audits">
      View security audits and formal verification.
    </Card>

    <Card title="Light Token Standard" icon="graduation-cap" href="/learn/light-token-standard">
      Learn core concepts of the Light token program.
    </Card>

    <Card title="ZK Compression" icon="graduation-cap" href="/learn/core-concepts">
      Learn core concepts of ZK Compression.
    </Card>
  </CardGroup>

  ## SDK Reference

  ### TypeScript

  <CardGroup>
    <Card title="@lightprotocol/stateless.js" icon="js" href="https://lightprotocol.github.io/light-protocol/stateless.js/index.html">
      Client SDK for Light Token and Compressed Accounts
    </Card>

    <Card title="@lightprotocol/compressed-token" icon="coins" href="https://lightprotocol.github.io/light-protocol/compressed-token/index.html">
      Client for Light Token and Compressed Tokens.
    </Card>
  </CardGroup>

  ### Rust

  <CardGroup>
    <Card title="light-client" icon="rust" href="https://docs.rs/light-client/latest/light_client/">
      Rust client for Light Token and ZK Compression.
    </Card>

    <Card title="light-sdk" icon="cube" href="https://docs.rs/light-sdk/latest/light_sdk/">
      Core SDK for on-chain programs.
    </Card>

    <Card title="light-program-test" icon="flask-vial" href="https://docs.rs/crate/light-program-test/latest">
      Testing framework for programs.
    </Card>
  </CardGroup>
</div>

<Footer />


# High-level System Overview
Source: https://www.zkcompression.com/learn/core-concepts

Overview to ZK Compression's Core Concepts. Get a high-level system overview and learn about the compressed account model, lifecycle of a transaction, and considerations.

<Steps>
  <Step>
    ### Storage of Compressed State

    Compressed accounts store state as call data on <Tooltip>Solana's ledger</Tooltip>.
    This maintains Solana's security and removes the need for rent-exemption per account.
  </Step>

  <Step>
    ### Accessing Compressed State

    Transactions specify state they access (read/write) and include it in the transaction payload.
  </Step>

  <Step>
    ### State Validation

    Solana Programs <Tooltip href="https://solana.com/docs/core/cpi">invoke</Tooltip> the <Tooltip>Light System Program</Tooltip> to update compressed state

    1. **The protocol validates the state** (validity of existing state, sum checks, ownership checks)
    2. **The protocol enforces a schema:** Classic Accounts → Compressed Accounts.\
       Compressed accounts have a layout similar to classic accounts.
  </Step>

  <Step>
    ### State Updates

    The new state is recorded as a log on the Solana ledger with each transaction.
  </Step>

  <Step>
    ### RPC Nodes

    <Tooltip href="https://github.com/helius-labs/photon">Photon RPC nodes</Tooltip>
    index the state changes and make the compressed account state available to clients via the ZK Compression RPC API.
  </Step>

  <Step>
    ### Forester Nodes

    Keeper nodes that interact with the <Tooltip>Account Compression Program</Tooltip> to empty queues and rollover state trees.

    <Check>
      Clients and custom programs do not interact with Forester nodes or the Account Compression Program. This is all done under the hood.
    </Check>
  </Step>
</Steps>

# Next Steps

In the following sections, we'll dive into the core concepts that make ZK Compression possible:

* **Compressed Account Model**: Understand how compressed accounts differ from regular Solana accounts (not much!) and how they enhance efficiency.
* **State Trees**: Learn about the Merkle tree structure used to store compressed accounts and how it minimizes on-chain storage.
* **Validity Proofs**: Learn how zero-knowledge proofs verify data efficiently while keeping proof sizes small.
* **Lifecycle of a Transaction**: Follow the journey of a transaction from creation to execution with ZK Compression.
* **Considerations**: Discover the trade-offs and scenarios where ZK Compression may or may not be the best solution.

<Card title=" Learn more about the compressed account model." icon="chevron-right" href="/learn/core-concepts/compressed-account-model" />


# Compressed Account Model
Source: https://www.zkcompression.com/learn/core-concepts/compressed-account-model

Overview to compressed accounts and comparison to Solana accounts.

# Overview

<Info>
  This guide assumes that you're familiar with [Solana's account
  model](https://solana.com/docs/core/accounts).
</Info>

Compressed accounts store state and are similar to regular Solana accounts but with five main differences:

* Each compressed account can be identified by its hash
* Each write to a compressed account changes its hash
* An `address` can optionally be set as a permanent unique ID of the compressed account.
* All compressed accounts are stored in sparse state trees. Only the tree's state root (i.e., a small fingerprint of all compressed accounts) is stored in the on-chain account space.

These differences make compressed accounts rent-free and allow the protocol to store state as calldata on the Solana ledger instead of the costly on-chain account space.

# In a Nutshell

Transactions can use compressed account data inside Solana's virtual machine as if it were stored on-chain by combining state compression and zero-knowledge proofs:

1. Millions of compressed accounts are stored as hashes in Merkle tree leaves
2. All accounts stored in a Merkle tree are compressed into a single root hash
3. The root hash is stored in one Solana account for cryptographic verification
4. Compressed account state is recorded on the Solana ledger
5. The latest compressed account state is fetched from your RPC provider
6. Compressed account state is verified against the on-chain root hash with a validity proof

<Note>
  * Merkle trees are provided by the protocol and Indexers generate validity proofs.
  * Developers don't configure state Merkle trees or generate validity proofs.

  [You will learn more about Merkle trees and validity proofs in the next section](/learn/core-concepts/merkle-trees-validity-proofs).
</Note>

# Compressed Account Structure

Compressed accounts include the core Solana account fields (owner, lamports, data) plus additional fields to index and store compressed state.

<Tabs>
  <Tab title="Diagram">
    <img alt="Diagram showing CompressedAccount structure with five core fields: Hash (32-byte unique identifier), Address (optional 32-byte persistent identifier), Data (nested CompressedAccountData struct containing 8-byte discriminator, variable-length serialized data, and 32-byte data_hash), Lamports (u64 account balance), and Owner (Pubkey of the program that owns the account)" />
  </Tab>

  <Tab title="Source Code">
    ```rust theme={null}
    pub struct CompressedAccount {
        pub address: Option<[u8; 32]>,            // Optional persistent identifier
        pub data: Option<CompressedAccountData>,  // Account data
        pub hash: [u8; 32],                       // Unique account hash
        pub lamports: u64,                        // Account balance
        pub owner: Pubkey,                        // Program that owns this account
    }
    ```
  </Tab>
</Tabs>

<Info>
  Find the [source code
  here](https://github.com/Lightprotocol/light-protocol/blob/main/sdk-libs/client/src/indexer/types.rs#L508-L520).
</Info>

<Accordion title="Solana Account Structure">
  ```rust theme={null}
  pub struct Account {
      pub lamports: u64,       // Account balance
      pub data: Vec<u8>,       // Arbitrary data (program state)
      pub owner: Pubkey,       // Program that owns this account
      pub executable: bool,    // Is this a program account
      pub rent_epoch: Epoch,   // Legacy field
  }
  ```

  <Info>
    Find the source code here:
    [agave/sdk/account/src/lib.rs:48-60](https://github.com/anza-xyz/agave/blob/67412607f511ded3770031280b6aaf10607713fc/sdk/account/src/lib.rs#L48-L60)
  </Info>
</Accordion>

# Address and Hash

Each compressed account can be **identified by its hash**, regardless of whether it has an address. By definition, whenever any data of a compressed account changes, its **hash changes**.

An **address** can serve as **optional** and additional **persistent identifier**.

* It's represented as 32 bytes in the format of a `PublicKey`.
* Addresses are optional, since ensuring that the address of a new account is unique incurs additional computational overhead.

<Tip>
  Create an address wherever the state must be unique (such as for NFTs or certain PDAs) and requires a persistent identifier.

  You don't need to create an address for fungible state (e.g., fungible tokens)
</Tip>

**Compressed Account Address Derivation**

Compressed account addresses are derived similar to PDAs.

* Like PDAs, compressed account addresses don't belong to a private key; rather, they're derived from the program that owns them.
* The key difference to regular PDAs is that compressed accounts require an **address tree** parameter.
* Address Merkle tree's store addresses of compressed accounts and ensure its uniqueness.

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const seed = deriveAddressSeedV2([customSeed, signer.publicKey.toBytes()]);
    const address = deriveAddressV2(seed, addressTree, new web3.PublicKey(programId));
    ```

    <Info>
      Learn more about address derivation for a [Typescript Client
      here](https://github.com/Lightprotocol/developer-content/blob/main/zk-compression-docs/compressed-pdas/client-library/typescript.md#derive-address).
    </Info>
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    let (address, _) = derive_address(
        &[b"custom_seed", keypair.pubkey().as_ref()],
        &address_tree_info.tree,
        &your_program::ID,
    );
    ```

    <Info>
      Learn more about address derivation for a [Rust Client
      here](https://github.com/Lightprotocol/developer-content/blob/main/zk-compression-docs/compressed-pdas/client-library/rust.md#derive-address).
    </Info>
  </Tab>
</Tabs>

<Accordion title="Solana PDA Derivation">
  ```typescript derive-pda.ts theme={null}
  const [pda, bump] = PublicKey.findProgramAddressSync(
    [Buffer.from("seed_string"), publicKey.toBuffer()],
    programId
  );
  ```

  ```rust derive-pda.rs theme={null}
  let (pda, bump) = Pubkey::find_program_address(
    &[
      b"seed_string",
      pubkey.as_ref()
    ],
    &program_id
  );
  ```
</Accordion>

# Data Field

The `data` field contains the compressed account's program state:

```rust theme={null}
pub struct CompressedAccountData {
    pub discriminator: [u8; 8],  // Type identifier for account data
    pub data: Vec<u8>,           // Serialized program state
    pub data_hash: [u8; 32],     // Hash of the data field
}
```

* `discriminator`: Identifies the data type for programs to correctly deserialize account data. Similar to Anchor's 8-byte account discriminator.
* `data`: Stores the account's current state as arbitrary bytes (e.g., serialized user data, balances, metadata).
  * Compressed accounts have no fixed maximum size to store data like Solana's 10 MB.
  * Still, Solana's 1,232-byte transaction limit constrains practical data size to roughly 1 KB per account.
* `data_hash`: Hash of the `data` field (32 bytes).
  * When computing the compressed account hash for the state tree, the protocol uses this fixed-size hash instead of the variable-length data bytes.

# Compressed Token Account

Compressed token accounts store token balance, owner, and other information of token accounts (SPL, Token-2022, or Light).

1. Any Solana token account can be compressed/decompressed at will.
2. We recommend to use compressed tokens for token distribution.

<Note>
  Learn how the Light token program uses ZK Compression under the hood
  [here](/learn/light-token-standard).
</Note>

<Tabs>
  <Tab title="Diagram">
    <Frame>
      <img alt="Diagram showing compressed token account structure with three components: Hash (identifier for compressed token account in purple box), Account (struct containing Data bytes, Executable flag, Lamports balance, and Address set to None), and AccountData (containing Mint, Owner, Amount, and Extensions fields marked as unimplemented)" />
    </Frame>
  </Tab>

  <Tab title="Source Code">
    ```rust theme={null}
    pub struct TokenData {
        pub mint: Pubkey,
        pub owner: Pubkey,
        pub amount: u64,
        pub delegate: Option<Pubkey>,
        pub state: u8,
        /// Placeholder for TokenExtension tlv data (unimplemented)
        pub tlv: Option<Vec<u8>>,
    }
    ```
  </Tab>
</Tabs>

# Next Steps

<Card title="Learn about the role of validity proofs and Merkle trees in the protocol." icon="chevron-right" href="/learn/core-concepts/merkle-trees-validity-proofs" />


# Considerations
Source: https://www.zkcompression.com/learn/core-concepts/considerations

Overview to considerations of ZK Compression, namely larger transaction size, higher compute unit usage, and per-transaction state cost.

# Overview

Before using ZK Compression to scale your application state, consider the following limitations of compressed accounts:

* Larger Transaction Size
* High Compute Unit Usage
* Per-Transaction State Cost

# General Recommendation

<Note>
  Consider which accounts in your application benefit from ZK Compression and which don't.

  * You can use both types for different parts of your application.
  * You can decompress and compress accounts at will.
</Note>

It may be preferred for an account *not* to be permanently compressed if:

* The account gets updated very frequently within a single block (e.g., shared liquidity pools in a DeFi protocol).
* You expect the lifetime number of writes to the same account to be very large (>>1000x).
* The account stores large amounts of data, and you need to access a large part of it (>1kb) inside one on-chain transaction.

# Larger Transaction Size

Solana's transaction size limit is 1232 Bytes. Transactions exceeding this limit will fail. ZK Compression increases your transaction size in two ways:

* 128 bytes must be reserved for the validity proof, which is a constant size per transaction, assuming the transaction reads from at least one compressed account.
* You must send the account data you want to read/write on-chain.

# High Compute Unit Usage

<Info>
  System CU usage:

  * \~100,000 CU for validity proof verification, which is a constant size per transaction, assuming the transaction reads from at least one compressed account
  * \~100,000 CU system use (state tree [Poseidon](https://eprint.iacr.org/2019/458.pdf) hashing et al.)
  * \~6,000 CU per compressed account read/write

  **Example**: a typical compressed token transfer uses around 292,000 CU.
</Info>

Higher CU usage can:

* **Lead to usage limits:** The total CU limit per transaction is 1,400,000 CU, and the per-block write lock limit per State tree is 12,000,000 CU.
* **Require your users to increase their** [**priority fee**](https://solana.com/developers/guides/advanced/how-to-use-priority-fees) **during congestion:** Whenever Solana's global per-block CU limit (48,000,000 CU) is reached, validator clients may prioritize transactions with higher per-CU priority fees.

# State Cost per Transaction

Each write operation incurs a small additional network cost. If you expect a single compressed account to amass a large amount of state updates, the lifetime cost of the compressed account may be higher than its uncompressed equivalent, which currently has a fixed per-byte rent cost at creation.

<Info>
  Whenever a transaction writes to a compressed account, it nullifies the previous compressed account state and appends the new compressed account as a leaf to the state tree. Both of these actions incur costs that add to Solana's base fee.
</Info>

| Type                                     | Lamports                   | Notes                                                                                                                                               |
| :--------------------------------------- | :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Solana base fee**                      | `5000` per signature       | Compensates validators for processing transactions                                                                                                  |
| **Write new compressed account state**   | \~`300` per leaf (default) | Depends on tree depth:<br />( 2<sup>tree\_depth</sup> × tree\_account\_rent\_cost × rollover\_threshold)<br />≈ `300` for the default depth of `26` |
| **Nullify old compressed account state** | `5000` per transaction     | Reimburses the cost of running a Forester transaction. The current default Forester node implementation can be found here                           |
| **Create addresses**                     | `5000` per transaction     | Same as nullify                                                                                                                                     |

# Next Steps

You're ready to take the next step and start building!

<CardGroup>
  <Card title="Compressed Tokens" icon="chevron-right" href="/compressed-tokens" />

  <Card title="Compressed PDAs" icon="chevron-right" href="/compressed-pdas/overview" />
</CardGroup>


# Merkle trees and Validity Proofs
Source: https://www.zkcompression.com/learn/core-concepts/merkle-trees-validity-proofs

Learn the core concepts of state trees, address trees, and validity proofs for compressed accounts.

# Overview

The protocol uses two types of Merkle trees that serve different purposes:

* [**State trees**](#state-trees) store compressed account hashes
* [**Address trees**](#address-merkle-trees) store addresses that serve as persistent identifiers

The protocol maintains multiple Merkle trees to reduce write-lock contention. Solana's runtime locks accounts during writes, wherefore a single tree would become a bottleneck. Multiple trees allow parallel transactions.

<Note>
  Developers don't need to maintain or initialize Merkle trees themselves. The protocol maintains [Merkle trees at these addresses](/resources/addresses-and-urls#state-trees-&-queues-&-cpi-accounts).
</Note>

# State trees

A state tree is a binary Merkle tree that stores data of millions of compressed Solana accounts in leaves for efficient cryptographic verification the integrity of all leaves in a tree.

<Steps>
  <Step>
    ### Merkle Tree Structure

    A Merkle tree compresses data by hashing adjacent leaves repeatedly into a single root hash, starting from the lowest level. The hash of a compressed Solana account is stored as a leaf in a State tree.
  </Step>

  <Step>
    ### Merkle Root Hash

    Only this root hash is stored on chain as single value on chain to secure the integrity of all compressed state in a tree. The raw state can thus be stored as calldata in the much cheaper Solana ledger space while preserving Solana's security guarantees.

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step>
    ### Leaf Hash Structure: Compressed Account Hashes

    For compressed Solana accounts, the 32 byte leaf hashes effectively mirror the regular Solana account layout: `{DataHash, StateHash; Owner, Lamports`.

    The `data_hash` represents the fingerprint of the actual account data.

    The `state_hash` ensures that each account hash is globally unique. It includes

    * the public key of the state tree's respective on-chain account (i.e., `state_tree_hash`) and
    * the compressed account's position in the tree (i.e., `leafIndex`).

    Lastly, `owner_hashed` determines which program owns this account and `lamports` show the account balance.

    <Info>
      For [details on the compressed account structure see this section](/learn/core-concepts/compressed-account-model#compressed-account-structure).
    </Info>

    <Frame>
      <img />
    </Frame>
  </Step>

  <Step>
    ### Merkle and Validity Proofs

    In state trees, a <Tooltip>validity proof</Tooltip> verifies that a compressed account exists in state trees with a constant 128-byte proof size. This proof must be included in every transaction once a compressed account is created to verify the on-chain state.

    <Note>
      Developers don't need to generate validity proofs or learn about ZK to use ZK Compression.

      ZK Compression uses [Groth16](https://docs.rs/groth16-solana/latest/groth16_solana/), a well-known [pairing-based](https://en.wikipedia.org/wiki/Pairing-based_cryptography) [zk-SNARK](https://www.helius.dev/blog/zero-knowledge-proofs-its-applications-on-solana#-zk-snarks-and-circuits), for its proof system.
    </Note>

    The validity proof contains one or more merkle proofs:

    * Merkle proofs consist of sibling node hashes along the path from the account's leaf to the root.
    * Starting with the leaf hash, the verifier calculates up the tree using these sibling hashes. The proof path is shown with three highlighted elements in a box at the bottom right: Leaf 0, Node 1, and Node 5, representing the sibling hashes needed to verify Leaf 1.
    * If the calculated root matches the on-chain root, the account is verified.

    <Frame>
      <img alt="Merkle tree diagram illustrating a leaf proof for Leaf 1. The tree shows a purple root node at the top, branching down through intermediate nodes (Node 4 and Node 5 in green and blue respectively) to eight leaf nodes at the bottom (Leaf 0 through Leaf 7). Leaf 1 is highlighted in green and labeled as 'compressed account'. The proof path is shown with three highlighted elements in a box at the bottom right: Leaf 0, Node 1, and Node 5, representing the sibling hashes needed to verify Leaf 1's inclusion in the tree. Caption explains that a Merkle proof consists of sibling node hashes required to calculate the final root node, with only adjacent hashes along the path to the root needed." />
    </Frame>

    For a tree with height 26, a single proof requires 26 sibling hashes (32 bytes each) plus metadata totaling 832 bytes. The proof size grows with tree height.

    ZK Compression batches multiple Merkle proofs into a single zero-knowledge proof to achieve a constant 128-byte size regardless of how many accounts are verified:

    | Accounts Verified | Proof Components      | Size                         |
    | :---------------- | :-------------------- | :--------------------------- |
    | 1                 | 1 merkle proof        | 832 <Tooltip>bytes</Tooltip> |
    | 1                 | 1 merkle + 1 ZK proof | 128 bytes                    |
    | 8                 | 8 merkle + 1 ZK proof | 128 bytes                    |

    <Info>
      Two **state tree versions** with different proof mechanisms are currently supported:

      * **V1 state trees**: Always require the full 128-byte ZK proof
      * **V2 batched state trees**: Can use `prove_by_index` optimization that verifies the account exists with only one byte instead of 128-bytes.

      **V2** optimizes optimize compute unit consumption by up to 70% and is **currently on Devnet**.

      When using V2 trees, RPC requests automatically choose the proof mechanism.
    </Info>
  </Step>
</Steps>

# Address trees

Address trees store addresses that serve as optional, persistent identifiers for compressed accounts.

<Info>
  Every address is unique within its address tree, but the same seeds can create different addresses in different address trees. To enforce that a compressed account can only be created once with the same seed, check the address tree pubkey in your program.
</Info>

<Steps>
  <Step>
    ### Address Tree Structure

    Address trees store derived addresses in an indexed structure. Unlike state trees that store account hashes, address trees store the actual address values along with pointers to maintain sorted order.

    These addresses are used only when compressed accounts require a persistent identifier that doesn't change when the account data updates.
  </Step>

  <Step>
    ### Address Tree Root Hash

    Like state trees, only the root hash is stored on-chain to verify all addresses in the tree. The raw addresses are stored in the Solana ledger.
  </Step>

  <Step>
    ### Merkle and Validity Proofs

    In address trees, validity proofs verify when creating a compressed account with an address that the address doesn't already exist in a specified address tree. This constant 128-byte proof must be included in the transaction only when creating accounts with addresses, not for subsequent compressed account interactions.

    <Info>
      Two **address tree versions** are currently supported:

      * **V1 address trees** height 26 (\~67 million addresses).
      * **V2 batched address trees** with height 40 (\~1 trillion addresses).

      **V2** optimizes optimize compute unit consumption by up to 70% and is **currently on Devnet**.

      When using V2 trees, RPC requests automatically choose the proof mechanism.
    </Info>
  </Step>
</Steps>

# Resources on ZK

For those interested in learning more about the fundamentals of ZK and its applications on Solana, we recommend reading the following:

<CardGroup>
  <Card title="Zero-Knowledge Proofs: An Introduction to the Fundamentals" href="https://www.helius.dev/blog/zero-knowledge-proofs-an-introduction-to-the-fundamentals" />

  <Card title="Zero-Knowledge Proofs: Its Applications on Solana" href="https://www.helius.dev/blog/zero-knowledge-proofs-its-applications-on-solana" />
</CardGroup>

# Next Steps

<Card title="Learn about the lifecycle of a transaction with compressed accounts." icon="chevron-right" href="/learn/core-concepts/transaction-lifecycle" />


# Lifecycle of a Transaction
Source: https://www.zkcompression.com/learn/core-concepts/transaction-lifecycle

Overview to the lifecycle of a transaction that interacts with compressed accounts.

# Overview

<Info>
  This guide assumes you are familiar with transactions on Solana. If you aren't, we recommend to read the [Solana documentation on transactions](https://solana.com/docs/core/transactions).
</Info>

Transactions to interact with compressed accounts are fully compatible with Solana's Transaction and Versioned Transaction formats.

There are few nuances to build transactions with compressed accounts as compared to regular accounts:

* Instructions must specify the list of all compressed accounts being read or written to.
* To read or write to a compressed account, the instruction must send the current account state on-chain and prove its validity.
* Each unique state tree that gets read or written to (via any compressed account) needs to be specified as per Solana's regular on-chain [account access lists](https://solana.com/docs/core/transactions#array-of-account-addresses).

# Reading Compressed Accounts

Reading compressed accounts follows a similar pattern to Solana accounts.

* The main difference is that compressed account RPC methods query an indexer instead of the ledger directly.
* The indexer, called Photon, reconstructs compressed account state from the Solana ledger by reading transaction logs.

The API exposed by the indexer closely mirrors existing RPC calls, with one-to-one mapping:

| Solana RPC              | Photon RPC Calls                  |
| :---------------------- | :-------------------------------- |
| getAccountInfo          | getCompressedAccount              |
| getBalance              | getCompressedBalance              |
| getTokenAccountsByOwner | getCompressedTokenAccountsByOwner |
| getProgramAccounts      | getCompressedAccountsByOwner      |

<Tabs>
  <Tab title="Clients">
    Clients read compressed accounts similar to Solana accounts:

    1. Fetch the compressed account data from your RPC provider using its address or hash
       * Here you use [`getCompressedAccount()`](/api-reference/json-rpc-methods/getcompressedaccount), similar to `getAccountInfo()`.
    2. Deserialize the account's data field into the appropriate data structure.

    <CodeGroup>
      ```typescript TypeScript theme={null}
      // 1. Fetch compressed account from indexer
      const compressedAccount = await rpc.getCompressedAccount(
        bn(address.toBytes())
      );

      // 2. Deserialize account data
      const accountData = coder.types.decode(
        "AccountType",
        compressedAccount.data.data
      );
      ```

      ```rust Rust theme={null}
      // 1. Fetch compressed account from indexer
      let compressed_account = rpc
          .get_compressed_account(address, None)
          .await?
          .value
          .unwrap();

      // 2. Deserialize account data
      let account_data = deserialize(&compressed_account.data)?;
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Programs">
    On-chain reading within programs requires a validity proof to verify the account exists in the state tree.

    1. Fetch the compressed account data from your RPC provider using its address or hash
    2. Fetch a validity proof using the account hash via [`getValidityProof()`](/api-reference/json-rpc-methods/getvalidityproof).
    3. Clients pass the proof to the on-chain program in the instruction data.

    <CodeGroup>
      ```typescript TypeScript theme={null}
      // 1. Fetch compressed account from indexer
      const compressedAccount = await rpc.getCompressedAccount(
        bn(address.toBytes())
      );

      // 2. Get validity proof using account hash
      const proof = await rpc.getValidityProof(
        [bn(compressedAccount.hash)]
      );

      // 3. Proof is included in transaction instructions
      ```

      ```rust Rust theme={null}
      // 1. Fetch compressed account from indexer
      let compressed_account = rpc
          .get_compressed_account(address, None)
          .await?
          .value
          .unwrap();

      // 2. Get validity proof using account hash
      let proof = rpc
          .get_validity_proof(vec![compressed_account.hash], vec![], None)
          .await?
          .value;

      // 3. Proof is included in transaction instructions
      ```
    </CodeGroup>

    <Info>
      See this [read-only program example](https://github.com/Lightprotocol/program-examples/tree/main/read-only) implementation.
    </Info>
  </Tab>
</Tabs>

# Writing to Compressed Accounts

Writing to compressed accounts can be described more generally as:

```bash theme={null}
(state, validityProof) -> state transition -> state'
```

**Writing to a compressed account involves these steps:**

1. Fetch the compressed account data from your RPC provider using its address or hash
2. Fetch a validity proof from your RPC provider using the account hash via [`getValidityProof()`](/api-reference/json-rpc-methods/getvalidityproof) to prove the account hash exists in the state tree.

The Solana program executing the state transition ***Data***\*\* -> **\_**&#x44;ata'\*\*\_ requires its client to pack the instructions with:

* `address`: persistent identifier of the compressed account (unchanged)
* `owner program`: program ID that owns this account (unchanged)
* `data`: current account data
* `data'`: updated account data
* `validity proof`: 128-byte ZK proof that verifies the current account hash exists in the state tree

<Info>
  See this [guide to update a compressed account](/compressed-pdas/guides/how-to-update-compressed-accounts).
</Info>

<Frame>
  <img />
</Frame>

# On-chain Execution

To write compressed state, a program invokes the Light System Program via CPI. The system program then does the following:

1. Runs relevant checks ([sum check](https://github.com/Lightprotocol/light-protocol/blob/v.1.0.0/programs/system/src/invoke/verify_state_proof.rs#L204-L210), etc.)
2. [Verifies the validity proof](https://github.com/Lightprotocol/light-protocol/blob/v.1.0.0/programs/system/src/invoke/processor.rs#L209-L214)
3. [Nullifies](https://github.com/Lightprotocol/light-protocol/blob/v.1.0.0/programs/system/src/invoke/processor.rs#L209-L214) the existing leaf of the compressed account that is being written to, to prevent double spending.
4. [Appends](https://github.com/Lightprotocol/light-protocol/blob/v.1.0.0/programs/system/src/invoke/processor.rs#L245-L254) the new compressed account hash to the state tree and advances the tree's state root
5. [Emits](https://github.com/Lightprotocol/light-protocol/blob/v.1.0.0/programs/system/src/invoke/processor.rs#L272-L279) the new compressed account state onto the Solana ledger

An RPC node then parses the transaction and compressed state and provides the read state to clients via the ZK Compression RPC API.

<Tabs>
  <Tab title="Before Tx Execution">
    <Frame>
      <img />
    </Frame>
  </Tab>

  <Tab title="After Tx Execution">
    <Frame>
      <img />
    </Frame>
  </Tab>
</Tabs>

# Next Steps

<Card title="Understand the trade-offs for compressed accounts." icon="chevron-right" href="/learn/core-concepts/considerations" />


# Core Concepts to the Light Token Program (Beta)
Source: https://www.zkcompression.com/learn/light-token-standard

The Light Token Program is a high performance token program that reduces the cost of account creations by 200x, while being more CU efficient than SPL on hot paths.

<table>
  <thead>
    <tr>
      <th />

      <th>Account Type</th>
      <th>Key Features</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**[Mint Accounts](#light-mint-accounts)**</td>
      <td>Solana Account</td>

      <td>
        <ul>
          <li>Represents a unique mint and optionally can store token-metadata.</li>
          <li>Functionally equivalent to SPL mints.</li>
          <li>Pays the rent-exemption cost</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>**[Token Accounts](#light-token-account)**</td>
      <td>Solana account</td>

      <td>
        <ul>
          <li>Stores token balances of mints (SPL, Token-2022, or Light)</li>
          <li>Pays the rent-exemption cost</li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

## Rent Config by Light Token Program

1. The Light Token Program pays the rent-exemption cost for the account.
2. Transaction fee payers bump a virtual rent balance when writing to the account, which keeps the account "hot".
3. "Cold" accounts virtual rent balance below threshold (eg 24h without write bump) get auto-compressed.
4. The cold account's state is cryptographically preserved on the Solana ledger.
   Users can load a cold account into hot state in-flight when using the account
   again.

<RentLifecycleVisualizer />

# Mint Accounts

<Note>
  Light mints are on-chain accounts like SPL mints, but with rent-exemption paid for by the Token
  program, instead of the user.
</Note>

Light-mints **uniquely represent a token on Solana and store its global metadata**, similar to SPL mint accounts with few core differences:

1. Tokens created from light-mints are light-tokens.
2. Token metadata (name, symbol, URI) is stored as an extension in the struct.

|                  |     Light-Token |  SPL-Token |
| :--------------- | --------------: | ---------: |
| **Mint Account** | **0.00001 SOL** | 0.0015 SOL |

<Tabs>
  <Tab title="Diagram">
    <Frame>
      <img alt="Diagram showing light-mint compressed account structure with three components: Hash (identifier for light-mint in purple box), Account (struct containing BaseMint with SPL-compatible fields, light-mint Data for program state, and optional Extensions for Token Metadata), and BasemintData (containing Supply, Decimals, Mint Authority, and Freeze Authority fields) with Token Metadata extension" />
    </Frame>
  </Tab>

  <Tab title="Source Code">
    ```rust theme={null}
    pub struct CompressedMint {
        pub base: BaseMint,
        pub metadata: CompressedMintMetadata,
        /// Reserved bytes for T22 layout compatibility (padding to reach byte 165)
        pub reserved: [u8; 49],
        /// Account type discriminator at byte 165 (1 = Mint, 2 = Account)
        pub account_type: u8,
        /// Compression info embedded directly in the mint
        pub compression: CompressionInfo,
        pub extensions: Option<Vec<ExtensionStruct>>,
    }
    ```
  </Tab>
</Tabs>

<Info>
  Find the [source code of light-mints
  here](https://github.com/Lightprotocol/light-protocol/blob/bda52c305fad28b1b72093911f878d37fb190656/program-libs/token-interface/src/state/mint/compressed_mint.rs#L19).
</Info>

The `metadata` field is used by the Light Token Program to store the internal state of a light-mint.

The `BaseMint` field replicates the field layout and serialization format of [SPL Mint accounts](https://solana.com/docs/tokens#mint-account). The struct is serialized with Borsh to match the on-chain format of SPL tokens and mints.

Here is how light-mints and SPL mints compare:

<Tabs>
  <Tab title="Basemint vs SPL mint">
    <table>
      <thead>
        <tr>
          <th>Field</th>
          <th>Light-Mint</th>
          <th>SPL Mint</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td>mint\_authority</td>
          <td>✓</td>
          <td>✓</td>
        </tr>

        <tr>
          <td>supply</td>
          <td>✓</td>
          <td>✓</td>
        </tr>

        <tr>
          <td>decimals</td>
          <td>✓</td>
          <td>✓</td>
        </tr>

        <tr>
          <td>is\_initialized</td>
          <td>✓</td>
          <td>✓</td>
        </tr>

        <tr>
          <td>freeze\_authority</td>
          <td>✓</td>
          <td>✓</td>
        </tr>

        <tr>
          <td>Light-Mint Data</td>
          <td>✓</td>
          <td>-</td>
        </tr>

        <tr>
          <td>Extensions</td>
          <td>✓</td>
          <td>via Token-2022</td>
        </tr>
      </tbody>
    </table>
  </Tab>

  <Tab title="BaseMint Struct">
    ```rust theme={null}
    pub struct BaseMint {
        /// Optional authority used to mint new tokens. The mint authority may only
        /// be provided during mint creation. If no mint authority is present
        /// then the mint has a fixed supply and no further tokens may be
        /// minted.
        pub mint_authority: Option<Pubkey>,
        /// Total supply of tokens.
        pub supply: u64,
        /// Number of base 10 digits to the right of the decimal place.
        pub decimals: u8,
        /// Is initialized - for SPL compatibility
        pub is_initialized: bool,
        /// Optional authority to freeze token accounts.
        pub freeze_authority: Option<Pubkey>,
    }
    ```
  </Tab>
</Tabs>

# Token Account

<Note>
  Light token accounts are on-chain accounts like SPL token accounts, but with rent-exemption paid
  for by the Token program, instead of the user.
</Note>

A light-token account holds token balances like SPL Token accounts:

* A wallet needs a light-token account for each light-mint, SPL mint, or Token 2022 mint it wants to hold, with the wallet address set as the light-token account owner.
* Each wallet can own multiple light-token accounts for the same light-mint.
* A light-token account can only have one owner and hold units of one light-mint.

|                   |       Light-Token |   SPL-Token |
| :---------------- | ----------------: | ----------: |
| **Token Account** | **\~0.00001 SOL** | \~0.002 SOL |

Additionally Light Token is more compute-efficient than SPL on hot paths:

|                          | Light-Token | SPL-Token |
| :----------------------- | ----------: | --------: |
| **ATA Creation**         |   **4,348** |    14,194 |
| **Transfer**             |     **312** |     4,645 |
| **Transfer** (rent-free) |   **1,885** |     4,645 |

<Tabs>
  <Tab title="Diagram">
    <Frame>
      <img alt="Diagram showing light-token Solana account structure with three components: Address (identifier for light-token account in purple box), Account (struct containing Data bytes, Executable flag, Lamports balance, and Owner set to Light Token Program), and AccountData (containing Mint, Owner, Amount, and Extensions fields)" />
    </Frame>
  </Tab>

  <Tab title="Source Code">
    ```rust theme={null}
    /// Token account structure (with extensions).
    pub struct Token {
        pub mint: Pubkey,
        pub owner: Pubkey,
        pub amount: u64,
        pub delegate: Option<Pubkey>, // instruction not implemented yet
        pub state: u8,
        pub is_native: Option<u64>,
        pub delegated_amount: u64, // instruction not implemented yet
        pub close_authority: Option<Pubkey>,
        pub extensions: Option<Vec<ExtensionStruct>>, // Optional extensions e.g. compressible
    }
    ```
  </Tab>
</Tabs>

<Info>
  Find the [source code of light-tokens
  here](https://github.com/Lightprotocol/light-protocol/blob/bda52c305fad28b1b72093911f878d37fb190656/program-libs/token-interface/src/state/token/token_struct.rs#L34).
</Info>

Light token accounts replicate the field layout and serialization format of [SPL Token accounts](https://solana.com/docs/tokens#token-account). The struct is serialized with Borsh to match the on-chain format of SPL tokens.

Here is how light-tokens and SPL tokens compare:

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Light Token</th>
      <th>SPL Token Account</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>mint</td>
      <td>✓</td>
      <td>✓</td>
    </tr>

    <tr>
      <td>owner</td>
      <td>✓</td>
      <td>✓</td>
    </tr>

    <tr>
      <td>amount</td>
      <td>✓</td>
      <td>✓</td>
    </tr>

    <tr>
      <td>delegate</td>
      <td>unimplemented</td>
      <td>✓</td>
    </tr>

    <tr>
      <td>state</td>
      <td>✓</td>
      <td>✓</td>
    </tr>

    <tr>
      <td>is\_native</td>
      <td>✓</td>
      <td>✓</td>
    </tr>

    <tr>
      <td>delegated\_amount</td>
      <td>unimplemented</td>
      <td>✓</td>
    </tr>

    <tr>
      <td>close\_authority</td>
      <td>✓</td>
      <td>✓</td>
    </tr>

    <tr>
      <td>extensions</td>
      <td>✓</td>
      <td>via Token-2022</td>
    </tr>
  </tbody>
</table>

# Associated Light Token Account

**Associated light-token** accounts (light-ATAs) follow the same pattern as [associated token accounts](https://docs.solana.com/developing/programming-model/associated-token-account) (ATA):

* Each wallet needs its own light-token account to hold tokens from the same light-mint.
* The address for light-ATAs is deterministically derived with the owner's address, light token program ID, and mint address.

```rust theme={null}
let seeds = [
    owner.as_ref(),          // Wallet address (32 bytes)
    program_id.as_ref(),     // Light Token Program ID (32 bytes)
    mint.as_ref(),           // light-mint address (32 bytes)
    bump.as_ref(),           // Bump seed (1 byte)
];
```

<Info>
  Find the [source code to associated light-token accounts
  here](https://github.com/Lightprotocol/light-protocol/blob/main/programs/compressed-token/program/src/create_associated_token_account.rs).
</Info>

# Compressed Token Account

Under the hood, compressed token accounts store token balance, owner, and other information of inactive light-tokens.

1. Light token accounts are automatically compressed/decompressed when active/inactive.
2. Any light-token or SPL token can be compressed/decompressed at will.

<Note>You can still use compressed tokens for token distribution. Learn more about this here.</Note>

<Tabs>
  <Tab title="Diagram">
    <Frame>
      <img alt="Diagram showing compressed token account structure with three components: Hash (identifier for compressed token account in purple box), Account (struct containing Data bytes, Executable flag, Lamports balance, and Address set to None), and AccountData (containing Mint, Owner, Amount, and Extensions fields marked as unimplemented)" />
    </Frame>
  </Tab>

  <Tab title="Source Code">
    ```rust theme={null}
    pub struct TokenData {
        pub mint: Pubkey,
        pub owner: Pubkey,
        pub amount: u64,
        pub delegate: Option<Pubkey>,
        pub state: u8,
        /// Placeholder for TokenExtension tlv data (unimplemented)
        pub tlv: Option<Vec<u8>>,
    }
    ```
  </Tab>
</Tabs>

# Next Steps

<Card title="Create Light Token Accounts" icon="chevron-right" href="/light-token/cookbook/create-token-account" />


# Approve and Revoke Delegates
Source: https://www.zkcompression.com/light-token/cookbook/approve-revoke

Rust client guide to approve and revoke delegates for Light Token accounts. Includes step-by-step implementation and full code examples.

***

1. Approve grants a delegate permission to transfer up to a specified amount of tokens from your account.
   * Each token account can have only one delegate at a time.
   * Any new approval overwrites the previous one.
2. Revoke removes all delegate permissions from a Light Token account.
3. Only the token account owner can approve or revoke delegates.

<Tabs>
  <Tab title="TypeScript Client">
    <Tabs>
      <Tab title="Approve">
        `approve` grants a delegate permission to transfer up to a specified amount of tokens.

        <CodeCompare />
      </Tab>

      <Tab title="Revoke">
        `revoke` removes all delegate permissions from a Light Token account.

        <CodeCompare />
      </Tab>
    </Tabs>

    <Info>
      Find the source code
      [here](https://github.com/Lightprotocol/examples-light-token/tree/main/typescript-client/actions).
    </Info>

    <Steps>
      <Step>
        ### Approve a delegate

        <Accordion title="Installation">
          <Tabs>
            <Tab title="npm">
              Install packages in your working directory:

              ```bash theme={null}
              npm install @lightprotocol/stateless.js@beta \
                          @lightprotocol/compressed-token@beta
              ```

              Install the CLI globally:

              ```bash theme={null}
              npm install -g @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>

            <Tab title="yarn">
              Install packages in your working directory:

              ```bash theme={null}
              yarn add @lightprotocol/stateless.js@beta \
                       @lightprotocol/compressed-token@beta
              ```

              Install the CLI globally:

              ```bash theme={null}
              yarn global add @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>

            <Tab title="pnpm">
              Install packages in your working directory:

              ```bash theme={null}
              pnpm add @lightprotocol/stateless.js@beta \
                       @lightprotocol/compressed-token@beta
              ```

              Install the CLI globally:

              ```bash theme={null}
              pnpm add -g @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>
          </Tabs>
        </Accordion>

        <Tabs>
          <Tab title="Localnet">
            ```bash theme={null}
            # start local test-validator in a separate terminal
            light test-validator
            ```

            <Note>
              In the code examples, use `createRpc()` without arguments for localnet.
            </Note>
          </Tab>

          <Tab title="Devnet">
            Get an API key from [Helius](https://helius.dev) and add to `.env`:

            ```bash title=".env" theme={null}
            API_KEY=<your-helius-api-key>
            ```

            <Note>
              In the code examples, use `createRpc(RPC_URL)` with the devnet URL.
            </Note>
          </Tab>
        </Tabs>

        ```typescript theme={null}
        import "dotenv/config";
        import { Keypair } from "@solana/web3.js";
        import { createRpc } from "@lightprotocol/stateless.js";
        import {
            createMintInterface,
            mintToCompressed,
            approve,
        } 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);
            await mintToCompressed(rpc, payer, mint, payer, [{ recipient: payer.publicKey, amount: 1000n }]);

            const delegate = Keypair.generate();
            const tx = await approve(
                rpc,
                payer,
                mint,
                500,
                payer,
                delegate.publicKey,
            );

            console.log("Tx:", tx);
        })();
        ```
      </Step>

      <Step>
        ### Revoke a delegate

        ```typescript theme={null}
        import "dotenv/config";
        import { Keypair } from "@solana/web3.js";
        import { createRpc } from "@lightprotocol/stateless.js";
        import {
            createMintInterface,
            mintToCompressed,
            approve,
            revoke,
        } 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);
            await mintToCompressed(rpc, payer, mint, payer, [{ recipient: payer.publicKey, amount: 1000n }]);

            const delegate = Keypair.generate();
            await approve(rpc, payer, mint, 500, payer, delegate.publicKey);

            const delegatedAccounts = await rpc.getCompressedTokenAccountsByDelegate(
                delegate.publicKey,
                { mint },
            );
            const tx = await revoke(rpc, payer, delegatedAccounts.items, payer);

            console.log("Tx:", tx);
        })();
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Rust Client">
    <Tabs>
      <Tab title="Approve">
        <CodeCompare />
      </Tab>

      <Tab title="Revoke">
        <CodeCompare />
      </Tab>
    </Tabs>

    <Steps>
      <Step>
        ### Prerequisites

        <Accordion title="Dependencies">
          ```toml Cargo.toml theme={null}
          [dependencies]
          light-token = "0.4.0"
          light-client = { version = "0.19.0", features = ["v2"] }
          solana-sdk = "2"
          borsh = "0.10.4"
          tokio = { version = "1", features = ["full"] }
          ```
        </Accordion>

        <Accordion title="Developer Environment">
          <Tabs>
            <Tab title="In-Memory (LightProgramTest)">
              Test with Lite-SVM (...)

              ```bash theme={null}
              # Initialize project
              cargo init my-light-project
              cd my-light-project

              # Run tests
              cargo test
              ```

              ```rust theme={null}
              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());
              }
              ```
            </Tab>

            <Tab title="Localnet (LightClient)">
              Connects to a local test validator.

              <Tabs>
                <Tab title="npm">
                  ```bash theme={null}
                  npm install -g @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>

                <Tab title="yarn">
                  ```bash theme={null}
                  yarn global add @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>

                <Tab title="pnpm">
                  ```bash theme={null}
                  pnpm add -g @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>
              </Tabs>

              ```bash theme={null}
              # Initialize project
              cargo init my-light-project
              cd my-light-project

              # Start local test validator (in separate terminal)
              light test-validator
              ```

              ```rust theme={null}
              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(())
              }
              ```
            </Tab>

            <Tab title="Devnet (LightClient)">
              Replace `<your-api-key>` with your actual API key. [Get your API key here](https://www.helius.dev/zk-compression).

              ```rust theme={null}
              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(())
              }
              ```
            </Tab>
          </Tabs>
        </Accordion>
      </Step>

      <Step>
        ### Approve or revoke delegates

        <Info>
          View the [source code](https://github.com/Lightprotocol/light-protocol/blob/main/sdk-libs/token-sdk/src/instruction/approve.rs) and [full example](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/instructions/approve.rs) with shared test utilities.
        </Info>

        <Tabs>
          <Tab title="Approve">
            <Tabs>
              <Tab title="Action">
                ```rust theme={null}
                use borsh::BorshDeserialize;
                use light_client::rpc::Rpc;
                use light_token_client::actions::Approve;
                use rust_client::{setup, SetupContext};
                use solana_sdk::{signature::Keypair, signer::Signer};

                #[tokio::main]
                async fn main() -> Result<(), Box<dyn std::error::Error>> {
                    // Setup creates mint and associated token account with tokens
                    let SetupContext {
                        mut rpc,
                        payer,
                        associated_token_account,
                        ..
                    } = setup().await;

                    let delegate = Keypair::new();

                    let sig = Approve {
                        token_account: associated_token_account,
                        delegate: delegate.pubkey(),
                        amount: 500_000,
                        owner: Some(payer.pubkey()),
                    }
                    .execute(&mut rpc, &payer)
                    .await?;

                    let data = rpc.get_account(associated_token_account).await?.ok_or("Account not found")?;
                    let token = light_token_interface::state::Token::deserialize(&mut &data.data[..])?;
                    println!("Delegate: {:?} Tx: {sig}", token.delegate);

                    Ok(())
                }
                ```
              </Tab>

              <Tab title="Instruction">
                ```rust theme={null}
                use borsh::BorshDeserialize;
                use light_client::rpc::Rpc;
                use light_token::instruction::Approve;
                use rust_client::{setup, SetupContext};
                use solana_sdk::{signature::Keypair, signer::Signer};

                #[tokio::main]
                async fn main() -> Result<(), Box<dyn std::error::Error>> {
                    // Setup creates mint and associated token account with tokens
                    let SetupContext {
                        mut rpc,
                        payer,
                        associated_token_account,
                        ..
                    } = setup().await;

                    let delegate = Keypair::new();
                    let delegate_amount = 500_000u64;

                    let approve_instruction = Approve {
                        token_account: associated_token_account,
                        delegate: delegate.pubkey(),
                        owner: payer.pubkey(),
                        amount: delegate_amount,
                    }
                    .instruction()?;

                    let sig = rpc
                        .create_and_send_transaction(&[approve_instruction], &payer.pubkey(), &[&payer])
                        .await?;

                    let data = rpc.get_account(associated_token_account).await?.ok_or("Account not found")?;
                    let token = light_token_interface::state::Token::deserialize(&mut &data.data[..])?;
                    println!("Delegate: {:?} Tx: {sig}", token.delegate);

                    Ok(())
                }
                ```
              </Tab>
            </Tabs>
          </Tab>

          <Tab title="Revoke">
            <Tabs>
              <Tab title="Action">
                ```rust theme={null}
                use borsh::BorshDeserialize;
                use light_client::rpc::Rpc;
                use light_token_client::actions::Revoke;
                use rust_client::{setup, SetupContext};
                use solana_sdk::signer::Signer;

                #[tokio::main]
                async fn main() -> Result<(), Box<dyn std::error::Error>> {
                    // Setup creates mint and associated token account with approved delegate
                    let SetupContext {
                        mut rpc,
                        payer,
                        associated_token_account,
                        ..
                    } = setup().await;

                    let sig = Revoke {
                        token_account: associated_token_account,
                        owner: Some(payer.pubkey()),
                    }
                    .execute(&mut rpc, &payer)
                    .await?;

                    let data = rpc.get_account(associated_token_account).await?.ok_or("Account not found")?;
                    let token = light_token_interface::state::Token::deserialize(&mut &data.data[..])?;
                    println!("Delegate: {:?} Tx: {sig}", token.delegate);

                    Ok(())
                }
                ```
              </Tab>

              <Tab title="Instruction">
                ```rust theme={null}
                use borsh::BorshDeserialize;
                use light_client::rpc::Rpc;
                use light_token::instruction::Revoke;
                use rust_client::{setup, SetupContext};
                use solana_sdk::signer::Signer;

                #[tokio::main]
                async fn main() -> Result<(), Box<dyn std::error::Error>> {
                    // Setup creates mint, associated token account with tokens, and approves delegate
                    let SetupContext {
                        mut rpc,
                        payer,
                        associated_token_account,
                        ..
                    } = setup().await;

                    let revoke_instruction = Revoke {
                        token_account: associated_token_account,
                        owner: payer.pubkey(),
                    }
                    .instruction()?;

                    let sig = rpc
                        .create_and_send_transaction(&[revoke_instruction], &payer.pubkey(), &[&payer])
                        .await?;

                    let data = rpc.get_account(associated_token_account).await?.ok_or("Account not found")?;
                    let token = light_token_interface::state::Token::deserialize(&mut &data.data[..])?;
                    println!("Delegate: {:?} Tx: {sig}", token.delegate);

                    Ok(())
                }
                ```
              </Tab>
            </Tabs>
          </Tab>
        </Tabs>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Program">
    <Note>
      Find [a full code example at the end](#full-code-example).
    </Note>

    <Tabs>
      <Tab title="Approve">
        <Steps>
          <Step>
            ### Build Account Infos and CPI the Light Token Program

            Use `invoke` for external signers or `invoke_signed` when the authority is a PDA.

            <Tabs>
              <Tab title="invoke (External signer)">
                ```rust theme={null}
                use light_token::instruction::ApproveCpi;

                ApproveCpi {
                    token_account: token_account.clone(),
                    delegate: delegate.clone(),
                    owner: owner.clone(),
                    system_program: system_program.clone(),
                    amount,
                }
                .invoke()?;
                ```
              </Tab>

              <Tab title="invoke_signed (PDA owner)">
                ```rust theme={null}
                use light_token::instruction::ApproveCpi;

                let approve_cpi = ApproveCpi {
                    token_account: token_account.clone(),
                    delegate: delegate.clone(),
                    owner: owner.clone(),
                    system_program: system_program.clone(),
                    amount,
                };

                let signer_seeds: &[&[u8]] = &[TOKEN_ACCOUNT_SEED, &[bump]];
                approve_cpi.invoke_signed(&[signer_seeds])?;
                ```
              </Tab>
            </Tabs>
          </Step>
        </Steps>
      </Tab>

      <Tab title="Revoke">
        <Steps>
          <Step>
            ### Build Account Infos and CPI the Light Token Program

            Use `invoke` for external signers or `invoke_signed` when the authority is a PDA.

            <Tabs>
              <Tab title="invoke (External signer)">
                ```rust theme={null}
                use light_token::instruction::RevokeCpi;

                RevokeCpi {
                    token_account: token_account.clone(),
                    owner: owner.clone(),
                    system_program: system_program.clone(),
                }
                .invoke()?;
                ```
              </Tab>

              <Tab title="invoke_signed (PDA owner)">
                ```rust theme={null}
                use light_token::instruction::RevokeCpi;

                let revoke_cpi = RevokeCpi {
                    token_account: token_account.clone(),
                    owner: owner.clone(),
                    system_program: system_program.clone(),
                };

                let signer_seeds: &[&[u8]] = &[TOKEN_ACCOUNT_SEED, &[bump]];
                revoke_cpi.invoke_signed(&[signer_seeds])?;
                ```
              </Tab>
            </Tabs>
          </Step>
        </Steps>
      </Tab>
    </Tabs>

    # Full Code Example

    <Tabs>
      <Tab title="Approve">
        <Info>
          View the [source code](https://github.com/Lightprotocol/light-protocol/blob/main/sdk-libs/token-sdk/src/instruction/approve.rs) and [full example](https://github.com/Lightprotocol/examples-light-token/tree/main/programs/anchor/basic-instructions/approve) with shared test utilities.
        </Info>

        <CodeGroup>
          ```rust lib.rs theme={null}
          #![allow(unexpected_cfgs, deprecated)]

          use anchor_lang::prelude::*;
          use light_token::instruction::ApproveCpi;

          declare_id!("37XmzKqSG2VD1ZBvzyfbt1HN1mT1bqVAmfzX2ziB3KT1");

          #[program]
          pub mod light_token_anchor_approve {
              use super::*;

              pub fn approve(ctx: Context<ApproveAccounts>, amount: u64) -> Result<()> {
                  ApproveCpi {
                      token_account: ctx.accounts.token_account.to_account_info(),
                      delegate: ctx.accounts.delegate.to_account_info(),
                      owner: ctx.accounts.owner.to_account_info(),
                      system_program: ctx.accounts.system_program.to_account_info(),
                      amount,
                  }
                  .invoke()?;
                  Ok(())
              }
          }

          #[derive(Accounts)]
          pub struct ApproveAccounts<'info> {
              /// CHECK: Light token program for CPI
              pub light_token_program: AccountInfo<'info>,
              /// CHECK: Validated by light-token CPI
              #[account(mut)]
              pub token_account: AccountInfo<'info>,
              /// CHECK: Validated by light-token CPI
              pub delegate: AccountInfo<'info>,
              pub owner: Signer<'info>,
              pub system_program: Program<'info, System>,
          }
          ```

          ```rust test.rs theme={null}
          use anchor_lang::{InstructionData, ToAccountMetas};
          use light_program_test::Rpc;
          use light_token::instruction::LIGHT_TOKEN_PROGRAM_ID;
          use light_token_anchor_approve::{accounts, instruction::Approve, ID};
          use anchor_lang::system_program;
          use solana_sdk::{instruction::Instruction, signature::Keypair, signer::Signer};
          use test_utils::{mint_tokens, setup_test_env};

          #[tokio::test]
          async fn test_approve() {
              let mut env = setup_test_env("light_token_anchor_approve", ID).await;

              // Mint tokens first
              let mint_amount = 1_000_000u64;
              mint_tokens(&mut env.rpc, &env.payer, env.mint_pda, env.associated_token_account, mint_amount).await;

              // Call the anchor program to approve delegate
              let delegate = Keypair::new();
              let approve_amount = 500_000u64;

              let ix = Instruction {
                  program_id: ID,
                  accounts: accounts::ApproveAccounts {
                      light_token_program: LIGHT_TOKEN_PROGRAM_ID,
                      token_account: env.associated_token_account,
                      delegate: delegate.pubkey(),
                      owner: env.payer.pubkey(),
                      system_program: system_program::ID,
                  }
                  .to_account_metas(Some(true)),
                  data: Approve { amount: approve_amount }.data(),
              };

              let sig = env
                  .rpc
                  .create_and_send_transaction(&[ix], &env.payer.pubkey(), &[&env.payer])
                  .await
                  .unwrap();

              println!("Tx: {}", sig);
          }
          ```
        </CodeGroup>
      </Tab>

      <Tab title="Revoke">
        <Info>
          View the [source code](https://github.com/Lightprotocol/light-protocol/blob/main/sdk-libs/token-sdk/src/instruction/revoke.rs) and [full example](https://github.com/Lightprotocol/examples-light-token/tree/main/programs/anchor/basic-instructions/revoke) with shared test utilities.
        </Info>

        <CodeGroup>
          ```rust lib.rs theme={null}
          #![allow(unexpected_cfgs, deprecated)]

          use anchor_lang::prelude::*;
          use light_token::instruction::RevokeCpi;

          declare_id!("G3ph4MK5qaSdxYnfxToETg31AHEMMqVhPuMRgBhk38tQ");

          #[program]
          pub mod light_token_anchor_revoke {
              use super::*;

              pub fn revoke(ctx: Context<RevokeAccounts>) -> Result<()> {
                  RevokeCpi {
                      token_account: ctx.accounts.token_account.to_account_info(),
                      owner: ctx.accounts.owner.to_account_info(),
                      system_program: ctx.accounts.system_program.to_account_info(),
                  }
                  .invoke()?;
                  Ok(())
              }
          }

          #[derive(Accounts)]
          pub struct RevokeAccounts<'info> {
              /// CHECK: Light token program for CPI
              pub light_token_program: AccountInfo<'info>,
              /// CHECK: Validated by light-token CPI
              #[account(mut)]
              pub token_account: AccountInfo<'info>,
              pub owner: Signer<'info>,
              pub system_program: Program<'info, System>,
          }
          ```

          ```rust test.rs theme={null}
          use anchor_lang::{InstructionData, ToAccountMetas};
          use light_program_test::Rpc;
          use light_token::instruction::{Approve, LIGHT_TOKEN_PROGRAM_ID};
          use light_token_anchor_revoke::{accounts, instruction::Revoke, ID};
          use anchor_lang::system_program;
          use solana_sdk::{instruction::Instruction, signature::Keypair, signer::Signer};
          use test_utils::{mint_tokens, setup_test_env};

          #[tokio::test]
          async fn test_revoke() {
              let mut env = setup_test_env("light_token_anchor_revoke", ID).await;

              // Mint tokens first
              let mint_amount = 1_000_000u64;
              mint_tokens(&mut env.rpc, &env.payer, env.mint_pda, env.associated_token_account, mint_amount).await;

              // Approve delegate first using SDK
              let delegate = Keypair::new();
              let approve_ix = Approve {
                  token_account: env.associated_token_account,
                  delegate: delegate.pubkey(),
                  owner: env.payer.pubkey(),
                  amount: 500_000,
              }
              .instruction()
              .unwrap();

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

              // Call the anchor program to revoke delegation
              let ix = Instruction {
                  program_id: ID,
                  accounts: accounts::RevokeAccounts {
                      light_token_program: LIGHT_TOKEN_PROGRAM_ID,
                      token_account: env.associated_token_account,
                      owner: env.payer.pubkey(),
                      system_program: system_program::ID,
                  }
                  .to_account_metas(Some(true)),
                  data: Revoke {}.data(),
              };

              let sig = env
                  .rpc
                  .create_and_send_transaction(&[ix], &env.payer.pubkey(), &[&env.payer])
                  .await
                  .unwrap();

              println!("Tx: {}", sig);
          }
          ```
        </CodeGroup>
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

# Next Steps

<Card title="Go back to the overview for the Light Token standard" icon="chevron-right" href="/light-token/welcome" />


# Burn Light Tokens
Source: https://www.zkcompression.com/light-token/cookbook/burn

Rust client guide to burn Light Tokens. Includes step-by-step implementation and full code examples.

***

1. Burn permanently destroys tokens by reducing the balance in a token account.
2. Burned tokens are removed from circulation and decreases the supply tracked on the mint account.
3. Only the token account owner (or approved delegate) can burn tokens.

<Tabs>
  <Tab title="Rust Client">
    Compare to SPL:

    <CodeCompare />

    <Steps>
      <Step>
        ### Prerequisites

        <Accordion title="Dependencies">
          ```toml Cargo.toml theme={null}
          [dependencies]
          light-token = "0.4.0"
          light-client = { version = "0.19.0", features = ["v2"] }
          solana-sdk = "2"
          borsh = "0.10.4"
          tokio = { version = "1", features = ["full"] }
          ```
        </Accordion>

        <Accordion title="Developer Environment">
          <Tabs>
            <Tab title="In-Memory (LightProgramTest)">
              Test with Lite-SVM (...)

              ```bash theme={null}
              # Initialize project
              cargo init my-light-project
              cd my-light-project

              # Run tests
              cargo test
              ```

              ```rust theme={null}
              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());
              }
              ```
            </Tab>

            <Tab title="Localnet (LightClient)">
              Connects to a local test validator.

              <Tabs>
                <Tab title="npm">
                  ```bash theme={null}
                  npm install -g @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>

                <Tab title="yarn">
                  ```bash theme={null}
                  yarn global add @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>

                <Tab title="pnpm">
                  ```bash theme={null}
                  pnpm add -g @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>
              </Tabs>

              ```bash theme={null}
              # Initialize project
              cargo init my-light-project
              cd my-light-project

              # Start local test validator (in separate terminal)
              light test-validator
              ```

              ```rust theme={null}
              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(())
              }
              ```
            </Tab>

            <Tab title="Devnet (LightClient)">
              Replace `<your-api-key>` with your actual API key. [Get your API key here](https://www.helius.dev/zk-compression).

              ```rust theme={null}
              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(())
              }
              ```
            </Tab>
          </Tabs>
        </Accordion>
      </Step>

      <Step>
        ### Burn Light Tokens

        <Info>
          View the [source code](https://github.com/Lightprotocol/light-protocol/blob/main/sdk-libs/token-sdk/src/instruction/burn.rs) and [full example](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/instructions/burn.rs) with shared test utilities.
        </Info>

        <Tabs>
          <Tab title="Instruction">
            ```rust theme={null}
            use borsh::BorshDeserialize;
            use light_client::rpc::Rpc;
            use light_token::instruction::Burn;
            use rust_client::{setup, SetupContext};
            use solana_sdk::signer::Signer;

            #[tokio::main]
            async fn main() -> Result<(), Box<dyn std::error::Error>> {
                // Setup creates mint and associated token account with tokens
                let SetupContext {
                    mut rpc,
                    payer,
                    mint,
                    associated_token_account,
                    ..
                } = setup().await;

                let burn_amount = 400_000u64;

                let burn_instruction = Burn {
                    source: associated_token_account,
                    mint,
                    amount: burn_amount,
                    authority: payer.pubkey(),
                    max_top_up: None,
                    fee_payer: None,
                }
                .instruction()?;

                let sig = rpc
                    .create_and_send_transaction(&[burn_instruction], &payer.pubkey(), &[&payer])
                    .await?;

                let data = rpc.get_account(associated_token_account).await?.ok_or("Account not found")?;
                let token = light_token_interface::state::Token::deserialize(&mut &data.data[..])?;
                println!("Balance: {} Tx: {sig}", token.amount);

                Ok(())
            }
            ```
          </Tab>
        </Tabs>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Program">
    <Note>
      Find [a full code example at the end](#full-code-example).
    </Note>

    <Steps>
      <Step>
        ### Build Account Infos and CPI the Light Token Program

        Use `invoke` for external signers or `invoke_signed` when the authority is a PDA.

        <Tabs>
          <Tab title="invoke (External signer)">
            ```rust theme={null}
            use light_token::instruction::BurnCpi;

            BurnCpi {
                source: source.clone(),
                mint: mint.clone(),
                amount,
                authority: authority.clone(),
                system_program: system_program.clone(),
                fee_payer: None,
                max_top_up: None,
            }
            .invoke()
            ```
          </Tab>

          <Tab title="invoke_signed (PDA owner)">
            ```rust theme={null}
            use light_token::instruction::BurnCpi;

            BurnCpi {
                source: source.clone(),
                mint: mint.clone(),
                amount,
                authority: authority.clone(),
                system_program: system_program.clone(),
                fee_payer: None,
                max_top_up: None,
            }
            .invoke_signed(&[signer_seeds])
            ```
          </Tab>
        </Tabs>
      </Step>
    </Steps>

    # Full Code Example

    <Info>
      View the [source code](https://github.com/Lightprotocol/light-protocol/blob/main/sdk-libs/token-sdk/src/instruction/burn.rs) and [full example](https://github.com/Lightprotocol/examples-light-token/tree/main/programs/anchor/basic-instructions/burn) with shared test utilities.
    </Info>

    <CodeGroup>
      ```rust lib.rs theme={null}
      #![allow(unexpected_cfgs, deprecated)]

      use anchor_lang::prelude::*;
      use light_token::instruction::BurnCpi;

      declare_id!("2TXVn8AqjfyeJvmFBD3kHJmh6fWkC4HNB5T76BmLKV5c");

      #[program]
      pub mod light_token_anchor_burn {
          use super::*;

          pub fn burn(ctx: Context<BurnAccounts>, amount: u64) -> Result<()> {
              BurnCpi {
                  source: ctx.accounts.source.to_account_info(),
                  mint: ctx.accounts.mint.to_account_info(),
                  amount,
                  authority: ctx.accounts.authority.to_account_info(),
                  system_program: ctx.accounts.system_program.to_account_info(),
                  max_top_up: None,
                  fee_payer: None,
              }
              .invoke()?;
              Ok(())
          }
      }

      #[derive(Accounts)]
      pub struct BurnAccounts<'info> {
          /// CHECK: Light token program for CPI
          pub light_token_program: AccountInfo<'info>,
          /// CHECK: Validated by light-token CPI
          #[account(mut)]
          pub source: AccountInfo<'info>,
          /// CHECK: Validated by light-token CPI
          #[account(mut)]
          pub mint: AccountInfo<'info>,
          pub authority: Signer<'info>,
          pub system_program: Program<'info, System>,
      }
      ```

      ```rust test.rs theme={null}
      use anchor_lang::{InstructionData, ToAccountMetas};
      use light_program_test::Rpc;
      use light_token::instruction::LIGHT_TOKEN_PROGRAM_ID;
      use light_token_anchor_burn::{accounts, instruction::Burn, ID};
      use anchor_lang::system_program;
      use solana_sdk::{instruction::Instruction, signer::Signer};
      use test_utils::{mint_tokens, setup_test_env};

      #[tokio::test]
      async fn test_burn() {
          let mut env = setup_test_env("light_token_anchor_burn", ID).await;

          // Mint tokens first
          let mint_amount = 1_000_000u64;
          mint_tokens(&mut env.rpc, &env.payer, env.mint_pda, env.associated_token_account, mint_amount).await;

          // Call the anchor program to burn tokens
          let burn_amount = 250_000u64;
          let ix = Instruction {
              program_id: ID,
              accounts: accounts::BurnAccounts {
                  light_token_program: LIGHT_TOKEN_PROGRAM_ID,
                  source: env.associated_token_account,
                  mint: env.mint_pda,
                  authority: env.payer.pubkey(),
                  system_program: system_program::ID,
              }
              .to_account_metas(Some(true)),
              data: Burn { amount: burn_amount }.data(),
          };

          let sig = env
              .rpc
              .create_and_send_transaction(&[ix], &env.payer.pubkey(), &[&env.payer])
              .await
              .unwrap();

          println!("Tx: {}", sig);
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>

# Next Steps

<Card title="Learn to freeze and thaw Light Token accounts" icon="chevron-right" href="/light-token/cookbook/freeze-thaw" />


# Close Light Token Account
Source: https://www.zkcompression.com/light-token/cookbook/close-token-account

Program guide to close Light Token accounts via CPI. Includes step-by-step implementation and full code examples.

***

1. Closing a Light Token account transfers remaining lamports to a destination account and the rent sponsor can reclaim sponsored rent.
2. Light token accounts can be closed by the owner.

<Info>
  The <Tooltip>`compression_authority`</Tooltip>
  closes the account and preserves the balance as compressed token account when the account becomes <Tooltip>compressible</Tooltip>.
  The account is reinstated in flight with the same state the next time it is accessed.
</Info>

<Tabs>
  <Tab title="Rust Client">
    Use `CloseTokenAccount` to close an empty Light Token account.

    Compare to SPL:

    <CodeCompare />

    <Steps>
      <Step>
        ### Prerequisites

        <Accordion title="Dependencies">
          ```toml Cargo.toml theme={null}
          [dependencies]
          light-token = "0.4.0"
          light-client = { version = "0.19.0", features = ["v2"] }
          solana-sdk = "2"
          borsh = "0.10.4"
          tokio = { version = "1", features = ["full"] }
          ```
        </Accordion>

        <Accordion title="Developer Environment">
          <Tabs>
            <Tab title="In-Memory (LightProgramTest)">
              Test with Lite-SVM (...)

              ```bash theme={null}
              # Initialize project
              cargo init my-light-project
              cd my-light-project

              # Run tests
              cargo test
              ```

              ```rust theme={null}
              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());
              }
              ```
            </Tab>

            <Tab title="Localnet (LightClient)">
              Connects to a local test validator.

              <Tabs>
                <Tab title="npm">
                  ```bash theme={null}
                  npm install -g @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>

                <Tab title="yarn">
                  ```bash theme={null}
                  yarn global add @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>

                <Tab title="pnpm">
                  ```bash theme={null}
                  pnpm add -g @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>
              </Tabs>

              ```bash theme={null}
              # Initialize project
              cargo init my-light-project
              cd my-light-project

              # Start local test validator (in separate terminal)
              light test-validator
              ```

              ```rust theme={null}
              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(())
              }
              ```
            </Tab>

            <Tab title="Devnet (LightClient)">
              Replace `<your-api-key>` with your actual API key. [Get your API key here](https://www.helius.dev/zk-compression).

              ```rust theme={null}
              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(())
              }
              ```
            </Tab>
          </Tabs>
        </Accordion>
      </Step>

      <Step>
        ### Close Light Token Account

        <Info>
          View the [source code](https://github.com/Lightprotocol/light-protocol/blob/main/sdk-libs/token-sdk/src/instruction/close.rs) and [full example](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/instructions/close.rs) with shared test utilities.
        </Info>

        <Tabs>
          <Tab title="Instruction">
            ```rust theme={null}
            use light_client::rpc::Rpc;
            use light_token::instruction::{CloseAccount, LIGHT_TOKEN_PROGRAM_ID};
            use rust_client::{setup_empty_associated_token_account, SetupContext};
            use solana_sdk::signer::Signer;

            #[tokio::main]
            async fn main() -> Result<(), Box<dyn std::error::Error>> {
                // Setup creates mint and empty associated token account (must be empty to close).
                let SetupContext {
                    mut rpc,
                    payer,
                    associated_token_account,
                    ..
                } = setup_empty_associated_token_account().await;
                let close_instruction = CloseAccount::new(LIGHT_TOKEN_PROGRAM_ID, associated_token_account, payer.pubkey(), payer.pubkey())
                    .instruction()?;

                let sig = rpc
                    .create_and_send_transaction(&[close_instruction], &payer.pubkey(), &[&payer])
                    .await?;

                let account = rpc.get_account(associated_token_account).await?;
                println!("Closed: {} Tx: {sig}", account.is_none());

                Ok(())
            }
            ```
          </Tab>
        </Tabs>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Program">
    <Note>
      Find [a full code example at the end](#full-code-example).
    </Note>

    <Steps>
      <Step>
        ### Build Account Infos and CPI the Light Token Program

        Use `invoke` for external signers or `invoke_signed` when the authority is a PDA.

        <Tabs>
          <Tab title="invoke (External signer)">
            ```rust theme={null}
            use light_token::instruction::CloseAccountCpi;

            CloseAccountCpi {
                token_program: token_program.clone(),
                account: account.clone(),
                destination: destination.clone(),
                owner: owner.clone(),
                rent_sponsor: rent_sponsor.clone(),
            }
            .invoke()?;
            ```
          </Tab>

          <Tab title="invoke_signed (PDA owner)">
            ```rust theme={null}
            use light_token::instruction::CloseAccountCpi;

            CloseAccountCpi {
                token_program: token_program.clone(),
                account: account.clone(),
                destination: destination.clone(),
                owner: owner.clone(),
                rent_sponsor: rent_sponsor.clone(),
            }
            .invoke_signed(&[signer_seeds])?;
            ```
          </Tab>
        </Tabs>

        <Accordion title="Account List">
          <table>
            <colgroup>
              <col />

              <col />
            </colgroup>

            <thead>
              <tr>
                <th />

                <th />

                <th />
              </tr>
            </thead>

            <tbody>
              <tr>
                <td>
                  <strong>Token Program</strong>
                </td>

                <td>-</td>
                <td>The light token program for CPI.</td>
              </tr>

              <tr>
                <td>
                  <strong>Account</strong>
                </td>

                <td>mutable</td>
                <td>The light-token account to close.</td>
              </tr>

              <tr>
                <td>
                  <strong>Destination</strong>
                </td>

                <td>mutable</td>
                <td>Receives remaining lamports from the closed account.</td>
              </tr>

              <tr>
                <td>
                  <strong>Owner</strong>
                </td>

                <td>signer\*</td>

                <td>
                  * Owner of the light-token account.
                    <br />- \*Must be signer for `invoke()`. For `invoke_signed()`, program
                    signs via PDA seeds.
                </td>
              </tr>

              <tr>
                <td>
                  <strong>Rent Sponsor</strong>
                </td>

                <td>mutable, optional</td>

                <td>
                  * light token program PDA that fronts rent exemption at creation. \*
                    Claims rent when account compresses and/or is closed.
                </td>
              </tr>
            </tbody>
          </table>
        </Accordion>
      </Step>
    </Steps>

    # Full Code Example

    <Info>
      View the [source code](https://github.com/Lightprotocol/light-protocol/blob/main/sdk-libs/token-sdk/src/instruction/close.rs) and [full example](https://github.com/Lightprotocol/examples-light-token/tree/main/programs/anchor/basic-instructions/close) with shared test utilities.
    </Info>

    <CodeGroup>
      ```rust lib.rs theme={null}
      #![allow(unexpected_cfgs, deprecated)]

      use anchor_lang::prelude::*;
      use light_token::instruction::CloseAccountCpi;

      declare_id!("GXLCuNhnkRVp596eCdbNsZ9ua1ePbKbb344VKS7V3zQQ");

      #[program]
      pub mod light_token_anchor_close {
          use super::*;

          pub fn close_account(ctx: Context<CloseAccountAccounts>) -> Result<()> {
              CloseAccountCpi {
                  token_program: ctx.accounts.light_token_program.to_account_info(),
                  account: ctx.accounts.account.to_account_info(),
                  destination: ctx.accounts.destination.to_account_info(),
                  owner: ctx.accounts.owner.to_account_info(),
                  rent_sponsor: ctx.accounts.rent_sponsor.to_account_info(),
              }
              .invoke()?;
              Ok(())
          }
      }

      #[derive(Accounts)]
      pub struct CloseAccountAccounts<'info> {
          /// CHECK: Light token program for CPI
          pub light_token_program: AccountInfo<'info>,
          /// CHECK: Validated by light-token CPI
          #[account(mut)]
          pub account: AccountInfo<'info>,
          /// CHECK: Validated by light-token CPI
          #[account(mut)]
          pub destination: AccountInfo<'info>,
          pub owner: Signer<'info>,
          /// CHECK: Validated by light-token CPI
          #[account(mut)]
          pub rent_sponsor: AccountInfo<'info>,
      }
      ```

      ```rust test.rs theme={null}
      use anchor_lang::{InstructionData, ToAccountMetas};
      use light_program_test::Rpc;
      use light_token::instruction::{rent_sponsor_pda, LIGHT_TOKEN_PROGRAM_ID};
      use light_token_anchor_close::{accounts, instruction::CloseAccount, ID};
      use solana_sdk::{instruction::Instruction, signer::Signer};
      use test_utils::setup_test_env;

      #[tokio::test]
      async fn test_close() {
          let mut env = setup_test_env("light_token_anchor_close", ID).await;

          // Associated token account must be empty to close (no mint_tokens call).

          // Call the anchor program to close account
          let rent_sponsor = rent_sponsor_pda();

          let ix = Instruction {
              program_id: ID,
              accounts: accounts::CloseAccountAccounts {
                  light_token_program: LIGHT_TOKEN_PROGRAM_ID,
                  account: env.associated_token_account,
                  destination: env.payer.pubkey(),
                  owner: env.payer.pubkey(),
                  rent_sponsor,
              }
              .to_account_metas(Some(true)),
              data: CloseAccount {}.data(),
          };

          let sig = env
              .rpc
              .create_and_send_transaction(&[ix], &env.payer.pubkey(), &[&env.payer])
              .await
              .unwrap();

          println!("Tx: {}", sig);
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>

# Next Steps

<Card title="Go back to the overview for the Light Token standard." icon="chevron-right" href="/light-token/welcome" />


# Create Associated Light Token Accounts
Source: https://www.zkcompression.com/light-token/cookbook/create-ata

Client and program guide to create associated Light Token accounts. Includes step-by-step implementation and full code examples.

***

1. Associated Light Token accounts can hold token balances of light, SPL, or Token 2022 mints.
2. Light-ATAs are on-chain accounts like SPL ATA's, but the light token program sponsors the rent-exemption cost for you.

<Accordion title="Light Rent Config Explained">
  1) The Light Token Program pays the rent-exemption cost for the account.
  2) Transaction fee payers bump a virtual rent balance when writing to the account, which keeps the account "hot".
  3) "Cold" accounts virtual rent balance below threshold (eg 24h without write bump) get auto-compressed.
  4) The cold account's state is cryptographically preserved on the Solana ledger.
     Users can load a cold account into hot state in-flight when using the account
     again.
</Accordion>

<Tabs>
  <Tab title="TypeScript Client">
    The `createAtaInterface` function creates an associated Light Token account in a single call.

    Compare to SPL:

    <CodeCompare />

    <Info>
      Find the source code
      [here](https://github.com/Lightprotocol/light-protocol/blob/0c4e2417b2df2d564721b89e18d1aad3665120e7/js/compressed-token/src/v3/actions/create-ata-interface.ts).
    </Info>

    <Steps>
      <Step>
        ### Create Associated Token Account

        <Accordion title="Installation">
          <Tabs>
            <Tab title="npm">
              Install packages in your working directory:

              ```bash theme={null}
              npm install @lightprotocol/stateless.js@beta \
                          @lightprotocol/compressed-token@beta
              ```

              Install the CLI globally:

              ```bash theme={null}
              npm install -g @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>

            <Tab title="yarn">
              Install packages in your working directory:

              ```bash theme={null}
              yarn add @lightprotocol/stateless.js@beta \
                       @lightprotocol/compressed-token@beta
              ```

              Install the CLI globally:

              ```bash theme={null}
              yarn global add @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>

            <Tab title="pnpm">
              Install packages in your working directory:

              ```bash theme={null}
              pnpm add @lightprotocol/stateless.js@beta \
                       @lightprotocol/compressed-token@beta
              ```

              Install the CLI globally:

              ```bash theme={null}
              pnpm add -g @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>
          </Tabs>
        </Accordion>

        <Tabs>
          <Tab title="Localnet">
            ```bash theme={null}
            # start local test-validator in a separate terminal
            light test-validator
            ```

            <Note>
              In the code examples, use `createRpc()` without arguments for localnet.
            </Note>
          </Tab>

          <Tab title="Devnet">
            Get an API key from [Helius](https://helius.dev) and add to `.env`:

            ```bash title=".env" theme={null}
            API_KEY=<your-helius-api-key>
            ```

            <Note>
              In the code examples, use `createRpc(RPC_URL)` with the devnet URL.
            </Note>
          </Tab>
        </Tabs>

        <Tabs>
          <Tab title="Action">
            ```typescript theme={null}
            import "dotenv/config";
            import { Keypair } from "@solana/web3.js";
            import { createRpc } from "@lightprotocol/stateless.js";
            import {
                createMintInterface,
                createAtaInterface,
            } 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 owner = Keypair.generate();
                const ata = await createAtaInterface(rpc, payer, mint, owner.publicKey);

                console.log("ATA:", ata.toBase58());
            })();
            ```
          </Tab>

          <Tab title="Instruction">
            ```typescript theme={null}
            import "dotenv/config";
            import {
                Keypair,
                Transaction,
                sendAndConfirmTransaction,
            } from "@solana/web3.js";
            import { createRpc, CTOKEN_PROGRAM_ID } from "@lightprotocol/stateless.js";
            import {
                createMintInterface,
                createAssociatedTokenAccountInterfaceInstruction,
                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 owner = Keypair.generate();
                const associatedToken = getAssociatedTokenAddressInterface(
                    mint,
                    owner.publicKey,
                );

                const ix = createAssociatedTokenAccountInterfaceInstruction(
                    payer.publicKey,
                    associatedToken,
                    owner.publicKey,
                    mint,
                    CTOKEN_PROGRAM_ID,
                );

                const tx = new Transaction().add(ix);
                const signature = await sendAndConfirmTransaction(rpc, tx, [payer]);

                console.log("ATA:", associatedToken.toBase58());
                console.log("Tx:", signature);
            })();
            ```
          </Tab>
        </Tabs>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Rust Client">
    `CreateAssociatedTokenAccount` creates an on-chain ATA to store token balances of light, SPL, or Token 2022 mints.

    Compare to SPL:

    <CodeCompare />

    <Steps>
      <Step>
        ### Prerequisites

        <Accordion title="Dependencies">
          ```toml Cargo.toml theme={null}
          [dependencies]
          light-token = "0.4.0"
          light-client = { version = "0.19.0", features = ["v2"] }
          solana-sdk = "2"
          borsh = "0.10.4"
          tokio = { version = "1", features = ["full"] }
          ```
        </Accordion>

        <Accordion title="Developer Environment">
          <Tabs>
            <Tab title="In-Memory (LightProgramTest)">
              Test with Lite-SVM (...)

              ```bash theme={null}
              # Initialize project
              cargo init my-light-project
              cd my-light-project

              # Run tests
              cargo test
              ```

              ```rust theme={null}
              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());
              }
              ```
            </Tab>

            <Tab title="Localnet (LightClient)">
              Connects to a local test validator.

              <Tabs>
                <Tab title="npm">
                  ```bash theme={null}
                  npm install -g @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>

                <Tab title="yarn">
                  ```bash theme={null}
                  yarn global add @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>

                <Tab title="pnpm">
                  ```bash theme={null}
                  pnpm add -g @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>
              </Tabs>

              ```bash theme={null}
              # Initialize project
              cargo init my-light-project
              cd my-light-project

              # Start local test validator (in separate terminal)
              light test-validator
              ```

              ```rust theme={null}
              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(())
              }
              ```
            </Tab>

            <Tab title="Devnet (LightClient)">
              Replace `<your-api-key>` with your actual API key. [Get your API key here](https://www.helius.dev/zk-compression).

              ```rust theme={null}
              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(())
              }
              ```
            </Tab>
          </Tabs>
        </Accordion>
      </Step>

      <Step>
        ### Create ATA

        <Info>
          View the [source code](https://github.com/Lightprotocol/light-protocol/blob/main/sdk-libs/token-sdk/src/instruction/create_ata.rs) and [full example](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/instructions/create_associated_token_account.rs) with shared test utilities.
        </Info>

        <Tabs>
          <Tab title="Action">
            ```rust theme={null}
            use light_token_client::actions::{CreateAta, CreateMint};
            use rust_client::setup_rpc_and_payer;
            use solana_sdk::signer::Signer;

            #[tokio::main]
            async fn main() -> Result<(), Box<dyn std::error::Error>> {
                let (mut rpc, payer) = setup_rpc_and_payer().await;

                // Create mint
                let (_signature, mint) = CreateMint {
                    decimals: 9,
                    freeze_authority: None,
                    token_metadata: None,
                    seed: None,
                }
                .execute(&mut rpc, &payer, &payer)
                .await?;

                // Create associated token account
                let (_signature, associated_token_account) = CreateAta {
                    mint,
                    owner: payer.pubkey(),
                    idempotent: true,
                }
                .execute(&mut rpc, &payer)
                .await?;

                println!("Associated token account: {associated_token_account}");

                Ok(())
            }
            ```
          </Tab>

          <Tab title="Instruction">
            ```rust theme={null}
            use light_client::rpc::Rpc;
            use light_token::instruction::{get_associated_token_address, CreateAssociatedTokenAccount};
            use rust_client::{setup_spl_mint_context, SplMintContext};
            use solana_sdk::{signature::Keypair, signer::Signer};

            #[tokio::main]
            async fn main() -> Result<(), Box<dyn std::error::Error>> {
                // You can use Light, SPL, or Token-2022 mints to create a Light associated token account.
                let SplMintContext {
                    mut rpc,
                    payer,
                    mint,
                } = setup_spl_mint_context().await;

                let owner = Keypair::new();

                let create_associated_token_account_instruction =
                    CreateAssociatedTokenAccount::new(payer.pubkey(), owner.pubkey(), mint).instruction()?;

                let sig = rpc
                    .create_and_send_transaction(&[create_associated_token_account_instruction], &payer.pubkey(), &[&payer])
                    .await?;

                let associated_token_account = get_associated_token_address(&owner.pubkey(), &mint);
                let data = rpc.get_account(associated_token_account).await?;
                println!("Associated token account: {associated_token_account} exists: {} Tx: {sig}", data.is_some());

                Ok(())
            }
            ```
          </Tab>
        </Tabs>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Program">
    <Tabs>
      <Tab title="CPI">
        Compare to SPL:

        <CodeCompare />

        <Note>
          Find [a full code example at the end](#full-code-example).
        </Note>

        <Steps>
          <Step>
            ### Build Account Infos and CPI the Light Token Program

            1. Pass ATA accounts and call `.rent_free()` with rent config accounts.
            2. Use `invoke` or `invoke_signed`:
               * When the `payer` is an external wallet, use `invoke`.
               * When the `payer` is a PDA, use `invoke_signed` with its seeds.

            <Note>
              The light-ATA address is derived from `[owner, light_token_program_id, mint]`.
              Unlike Light Token accounts, owner and mint are passed as accounts, not in
              instruction data.
            </Note>

            <Tabs>
              <Tab title="invoke (External signer)">
                ```rust theme={null}
                use light_token::instruction::CreateAssociatedAccountCpi;

                CreateAssociatedAccountCpi {
                    payer: payer.clone(),
                    owner: owner.clone(),
                    mint: mint.clone(),
                    ata: associated_token_account.clone(),
                    bump,
                }
                .rent_free(
                    compressible_config.clone(),
                    rent_sponsor.clone(),
                    system_program.clone(),
                )
                .invoke()
                ```
              </Tab>

              <Tab title="invoke_signed (PDA signer)">
                ```rust theme={null}
                use light_token::instruction::CreateAssociatedAccountCpi;

                let signer_seeds: &[&[u8]] = &[ATA_SEED, &[authority_bump]];

                CreateAssociatedAccountCpi {
                    payer: payer.clone(),
                    owner: owner.clone(),
                    mint: mint.clone(),
                    ata: associated_token_account.clone(),
                    bump,
                }
                .rent_free(
                    compressible_config.clone(),
                    rent_sponsor.clone(),
                    system_program.clone(),
                )
                .invoke_signed(&[signer_seeds])
                ```
              </Tab>
            </Tabs>

            <table>
              <colgroup>
                <col />

                <col />
              </colgroup>

              <thead>
                <tr>
                  <th />

                  <th />

                  <th />
                </tr>
              </thead>

              <tbody>
                <tr>
                  <td><strong>Owner</strong></td>
                  <td>-</td>

                  <td>
                    * The wallet that will own this light-ATA.<br />
                    * Used to derive the light-ATA address deterministically.
                  </td>
                </tr>

                <tr>
                  <td><strong>Mint</strong></td>
                  <td>-</td>

                  <td>
                    * The SPL or light-mint token mint.<br />
                    * Used to derive the light-ATA address deterministically.
                  </td>
                </tr>

                <tr>
                  <td><strong>Payer</strong></td>
                  <td>signer, mutable</td>

                  <td>
                    * Pays initial rent per epoch, transaction fee and compression incentive.<br />
                    * Does NOT pay rent exemption (paid by the light token program, `rent_sponsor`).
                  </td>
                </tr>

                <tr>
                  <td><strong>light-ATA Account</strong></td>
                  <td>mutable</td>

                  <td>
                    * The light-ATA being created.<br />
                    * Address is derived from `[owner, light_token_program_id, mint]`.
                  </td>
                </tr>

                <tr>
                  <td><strong><Tooltip href="https://solscan.io/account/11111111111111111111111111111111">System Program</Tooltip></strong></td>
                  <td>-</td>
                  <td>Solana System Program. Required for CPI to create the on-chain account.</td>
                </tr>

                <tr>
                  <td><strong>Bump</strong></td>
                  <td>u8</td>
                  <td>The PDA bump seed for the light-ATA address derivation.</td>
                </tr>

                <tr>
                  <td><strong>Idempotent</strong></td>
                  <td>bool</td>

                  <td>
                    * When `true`, silently succeeds if account already exists.<br />
                    * When `false`, fails if account already exists.
                  </td>
                </tr>
              </tbody>
            </table>
          </Step>
        </Steps>

        # Full Code Example

        <Info>
          View the [source code](https://github.com/Lightprotocol/light-protocol/blob/main/sdk-libs/token-sdk/src/instruction/create_ata.rs) and [full example](https://github.com/Lightprotocol/examples-light-token/tree/main/programs/anchor/basic-instructions/create-associated-token-account) with shared test utilities.
        </Info>

        <CodeGroup>
          ```rust lib.rs theme={null}
          #![allow(unexpected_cfgs, deprecated)]

          use anchor_lang::prelude::*;
          use light_token::instruction::CreateAssociatedAccountCpi;

          declare_id!("35MukgdfpNUbPMhTmEk63ECV8vjgpNVFRH9nP8ovMN58");

          #[program]
          pub mod light_token_anchor_create_associated_token_account {
              use super::*;

              pub fn create_associated_token_account(ctx: Context<CreateAssociatedTokenAccountAccounts>, bump: u8, idempotent: bool) -> Result<()> {
                  let cpi = CreateAssociatedAccountCpi {
                      payer: ctx.accounts.payer.to_account_info(),
                      owner: ctx.accounts.owner.to_account_info(),
                      mint: ctx.accounts.mint.to_account_info(),
                      ata: ctx.accounts.associated_token_account.to_account_info(),
                      bump,
                  };

                  if idempotent {
                      cpi.idempotent().rent_free(
                          ctx.accounts.compressible_config.to_account_info(),
                          ctx.accounts.rent_sponsor.to_account_info(),
                          ctx.accounts.system_program.to_account_info(),
                      )
                  } else {
                      cpi.rent_free(
                          ctx.accounts.compressible_config.to_account_info(),
                          ctx.accounts.rent_sponsor.to_account_info(),
                          ctx.accounts.system_program.to_account_info(),
                      )
                  }
                  .invoke()?;
                  Ok(())
              }
          }

          #[derive(Accounts)]
          pub struct CreateAssociatedTokenAccountAccounts<'info> {
              /// CHECK: Light token program for CPI
              pub light_token_program: AccountInfo<'info>,
              /// CHECK: Validated by light-token CPI
              pub owner: AccountInfo<'info>,
              /// CHECK: Validated by light-token CPI
              pub mint: AccountInfo<'info>,
              #[account(mut)]
              pub payer: Signer<'info>,
              /// CHECK: Validated by light-token CPI
              #[account(mut)]
              pub associated_token_account: AccountInfo<'info>,
              pub system_program: Program<'info, System>,
              /// CHECK: Validated by light-token CPI
              pub compressible_config: AccountInfo<'info>,
              /// CHECK: Validated by light-token CPI
              #[account(mut)]
              pub rent_sponsor: AccountInfo<'info>,
          }
          ```

          ```rust test.rs theme={null}
          use anchor_lang::{InstructionData, ToAccountMetas};
          use light_client::indexer::AddressWithTree;
          use light_program_test::{Indexer, LightProgramTest, ProgramTestConfig, Rpc};
          use light_token_anchor_create_associated_token_account::{accounts, instruction::CreateAssociatedTokenAccount, ID};
          use light_token::instruction::{
              CreateMint, CreateMintParams, config_pda, derive_mint_compressed_address, derive_token_ata,
              find_mint_address, rent_sponsor_pda, LIGHT_TOKEN_PROGRAM_ID,
              DEFAULT_RENT_PAYMENT, DEFAULT_WRITE_TOP_UP,
          };
          use anchor_lang::system_program;
          use solana_sdk::{
              instruction::Instruction,
              signature::Keypair,
              signer::Signer,
          };

          #[tokio::test]
          async fn test_create_associated_token_account() {
              let config =
                  ProgramTestConfig::new_v2(true, Some(vec![("light_token_anchor_create_associated_token_account", ID)]));
              let mut rpc = LightProgramTest::new(config).await.unwrap();
              let payer = rpc.get_payer().insecure_clone();

              let mint_seed = Keypair::new();
              let mint_authority = payer.pubkey();
              let decimals = 9u8;

              let address_tree = rpc.get_address_tree_v2();
              let output_queue = rpc.get_random_state_tree_info().unwrap().queue;

              let compression_address =
                  derive_mint_compressed_address(&mint_seed.pubkey(), &address_tree.tree);
              let (mint_pda, bump) = find_mint_address(&mint_seed.pubkey());

              let rpc_result = rpc
                  .get_validity_proof(
                      vec![],
                      vec![AddressWithTree {
                          address: compression_address,
                          tree: address_tree.tree,
                      }],
                      None,
                  )
                  .await
                  .unwrap()
                  .value;

              let params = CreateMintParams {
                  decimals,
                  address_merkle_tree_root_index: rpc_result.addresses[0].root_index,
                  mint_authority,
                  proof: rpc_result.proof.0.unwrap(),
                  compression_address,
                  mint: mint_pda,
                  bump,
                  freeze_authority: None,
                  extensions: None,
                  rent_payment: DEFAULT_RENT_PAYMENT,
                  write_top_up: DEFAULT_WRITE_TOP_UP,
              };

              let create_mint_ix = CreateMint::new(
                  params,
                  mint_seed.pubkey(),
                  payer.pubkey(),
                  address_tree.tree,
                  output_queue,
              )
              .instruction()
              .unwrap();

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

              // You can use light, spl, t22 mints to create a light token associated token account.
              // Derive associated token account address and bump
              let (associated_token_account, associated_token_account_bump) = derive_token_ata(&payer.pubkey(), &mint_pda);

              // Call the anchor program to create associated token account
              let compressible_config = config_pda();
              let rent_sponsor = rent_sponsor_pda();

              let ix = Instruction {
                  program_id: ID,
                  accounts: accounts::CreateAssociatedTokenAccountAccounts {
                      light_token_program: LIGHT_TOKEN_PROGRAM_ID,
                      owner: payer.pubkey(),
                      mint: mint_pda,
                      payer: payer.pubkey(),
                      associated_token_account: associated_token_account,
                      system_program: system_program::ID,
                      compressible_config,
                      rent_sponsor,
                  }
                  .to_account_metas(Some(true)),
                  data: CreateAssociatedTokenAccount {
                      bump: associated_token_account_bump,
                      idempotent: false,
                  }
                  .data(),
              };

              let sig = rpc.create_and_send_transaction(&[ix], &payer.pubkey(), &[&payer])
                  .await
                  .unwrap();

              println!("Tx: {}", sig);
          }
          ```
        </CodeGroup>
      </Tab>

      <Tab title="Anchor Macros">
        Compare to SPL:

        <CodeCompare />

        <Note>
          Find [a full code example at the end](#full-code-example-1).
        </Note>

        <Steps>
          <Step>
            ### Dependencies

            ```toml theme={null}
            [dependencies]
            light-sdk = { version = "0.18.0", features = ["anchor", "v2", "cpi-context"] }
            light-sdk-macros = "0.18.0"
            light-compressible = "0.1.0"
            anchor-lang = "0.31"
            ```
          </Step>

          <Step>
            ### Program

            Add `#[light_program]` above `#[program]`:

            ```rust theme={null}
            use light_sdk_macros::light_program;

            #[light_program]
            #[program]
            pub mod light_token_macro_create_ata {
                use super::*;

                pub fn create_ata<'info>(
                    ctx: Context<'_, '_, '_, 'info, CreateAta<'info>>,
                    params: CreateAtaParams,
                ) -> Result<()> {
                    Ok(())
                }
            }
            ```
          </Step>

          <Step>
            ### Accounts struct

            Derive `LightAccounts` on your `Accounts` struct and add `#[light_account(...)]` next to `#[account(...)]`.

            ```rust theme={null}
            /// CHECK: Validated by light-token CPI
            #[account(mut)]
            #[light_account(
                init,
                associated_token::authority = ata_owner,
                associated_token::mint = ata_mint,
                associated_token::bump = params.ata_bump
            )]
            pub ata: UncheckedAccount<'info>,
            ```
          </Step>
        </Steps>

        # Full code example

        <Info>
          View the [source code](https://github.com/Lightprotocol/light-protocol/blob/main/sdk-libs/token-sdk/src/instruction/create_ata.rs) and [full example](https://github.com/Lightprotocol/examples-light-token/tree/main/programs/anchor/basic-macros/create-associated-token-account) with shared test utilities.
        </Info>

        <CodeGroup>
          ```rust lib.rs theme={null}
          #![allow(deprecated)]

          use anchor_lang::prelude::*;
          use light_compressible::CreateAccountsProof;
          use light_sdk::derive_light_cpi_signer;
          use light_sdk_macros::{light_program, LightAccounts};
          use light_sdk_types::{CpiSigner, LIGHT_TOKEN_PROGRAM_ID};
          use light_token::instruction::{COMPRESSIBLE_CONFIG_V1, RENT_SPONSOR as LIGHT_TOKEN_RENT_SPONSOR};

          declare_id!("CLsn9MTFv97oMTsujRoQAw1u2rSm2HnKtGuWUbbc8Jfn");

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

          #[light_program]
          #[program]
          pub mod light_token_macro_create_associated_token_account {
              use super::*;

              #[allow(unused_variables)]
              pub fn create_associated_token_account<'info>(
                  ctx: Context<'_, '_, '_, 'info, CreateAssociatedTokenAccount<'info>>,
                  params: CreateAssociatedTokenAccountParams,
              ) -> Result<()> {
                  Ok(())
              }
          }

          #[derive(AnchorSerialize, AnchorDeserialize, Clone)]
          pub struct CreateAssociatedTokenAccountParams {
              pub create_accounts_proof: CreateAccountsProof,
              pub associated_token_account_bump: u8,
          }

          #[derive(Accounts, LightAccounts)]
          #[instruction(params: CreateAssociatedTokenAccountParams)]
          pub struct CreateAssociatedTokenAccount<'info> {
              #[account(mut)]
              pub fee_payer: Signer<'info>,

              /// CHECK: Token mint for the associated token account
              pub associated_token_account_mint: AccountInfo<'info>,

              /// CHECK: Owner of the associated token account
              pub associated_token_account_owner: AccountInfo<'info>,

              /// CHECK: Validated by light_account macro
              #[account(mut)]
              #[light_account(init, associated_token::authority = associated_token_account_owner, associated_token::mint = associated_token_account_mint, associated_token::bump = params.associated_token_account_bump)]
              pub associated_token_account: UncheckedAccount<'info>,

              /// CHECK: Validated by address constraint
              #[account(address = COMPRESSIBLE_CONFIG_V1)]
              pub light_token_compressible_config: AccountInfo<'info>,

              /// CHECK: Validated by address constraint
              #[account(mut, address = LIGHT_TOKEN_RENT_SPONSOR)]
              pub light_token_rent_sponsor: AccountInfo<'info>,

              /// CHECK: Light Token program for CPI
              #[account(address = LIGHT_TOKEN_PROGRAM_ID.into())]
              pub light_token_program: AccountInfo<'info>,

              pub system_program: Program<'info, System>,
          }
          ```

          ```rust test.rs theme={null}
          use anchor_lang::{InstructionData, ToAccountMetas};
          use light_client::interface::{get_create_accounts_proof, InitializeRentFreeConfig};
          use light_program_test::{
              program_test::{setup_mock_program_data, LightProgramTest},
              ProgramTestConfig, Rpc,
          };
          use light_sdk_types::LIGHT_TOKEN_PROGRAM_ID;
          use light_token::instruction::{COMPRESSIBLE_CONFIG_V1, RENT_SPONSOR};
          use solana_instruction::Instruction;
          use solana_signer::Signer;
          use test_utils::create_mint;

          /// Test creating a Light Protocol associated token account using the macro.
          #[tokio::test]
          async fn test_create_associated_token_account() {
              use light_token_macro_create_associated_token_account::CreateAssociatedTokenAccountParams;

              let program_id = light_token_macro_create_associated_token_account::ID;
              let mut config =
                  ProgramTestConfig::new_v2(true, Some(vec![("light_token_macro_create_associated_token_account", program_id)]));
              config = config.with_light_protocol_events();

              let mut rpc = LightProgramTest::new(config).await.unwrap();
              let payer = rpc.get_payer().insecure_clone();

              let program_data_pda = setup_mock_program_data(&mut rpc, &payer, &program_id);

              let (init_config_ix, _config_pda) = InitializeRentFreeConfig::new(
                  &program_id,
                  &payer.pubkey(),
                  &program_data_pda,
                  RENT_SPONSOR,
                  payer.pubkey(),
              )
              .build();

              rpc.create_and_send_transaction(&[init_config_ix], &payer.pubkey(), &[&payer])
                  .await
                  .expect("Initialize config should succeed");

              let (mint, _mint_seed) = create_mint(&mut rpc, &payer, None).await;

              // The associated token account owner will be the payer
              let associated_token_account_owner = payer.pubkey();

              // Derive the associated token account address using Light Token SDK's derivation
              let (associated_token_account, associated_token_account_bump) = light_token::instruction::derive_token_ata(&associated_token_account_owner, &mint);

              // Get proof (no PDA accounts for associated token account-only instruction)
              let proof_result = get_create_accounts_proof(&rpc, &program_id, vec![])
                  .await
                  .unwrap();

              // Build instruction
              let accounts = light_token_macro_create_associated_token_account::accounts::CreateAssociatedTokenAccount {
                  fee_payer: payer.pubkey(),
                  associated_token_account_mint: mint,
                  associated_token_account_owner,
                  associated_token_account,
                  light_token_compressible_config: COMPRESSIBLE_CONFIG_V1,
                  light_token_rent_sponsor: RENT_SPONSOR,
                  light_token_program: LIGHT_TOKEN_PROGRAM_ID.into(),
                  system_program: solana_sdk::system_program::ID,
              };

              let instruction_data = light_token_macro_create_associated_token_account::instruction::CreateAssociatedTokenAccount {
                  params: CreateAssociatedTokenAccountParams {
                      create_accounts_proof: proof_result.create_accounts_proof,
                      associated_token_account_bump,
                  },
              };

              let instruction = Instruction {
                  program_id,
                  accounts: [
                      accounts.to_account_metas(None),
                      proof_result.remaining_accounts,
                  ]
                  .concat(),
                  data: instruction_data.data(),
              };

              rpc.create_and_send_transaction(&[instruction], &payer.pubkey(), &[&payer])
                  .await
                  .expect("CreateAssociatedTokenAccount instruction should succeed");

              // Verify associated token account exists on-chain
              let associated_token_account_data = rpc
                  .get_account(associated_token_account)
                  .await
                  .unwrap()
                  .expect("Associated token account should exist on-chain");

              // Parse and verify token data
              use light_token_interface::state::Token;
              let token: Token = borsh::BorshDeserialize::deserialize(&mut &associated_token_account_data.data[..])
                  .expect("Failed to deserialize Token");

              // Verify owner
              assert_eq!(token.owner, associated_token_account_owner.to_bytes(), "Associated token account owner should match");

              // Verify mint
              assert_eq!(token.mint, mint.to_bytes(), "Associated token account mint should match");

              // Verify initial amount is 0
              assert_eq!(token.amount, 0, "Associated token account amount should be 0 initially");
          }
          ```
        </CodeGroup>
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

# Next Steps

<Card title="Learn how to mint Light Tokens" icon="chevron-right" href="/light-token/cookbook/mint-to" />


# Create Mint Account with Token Metadata
Source: https://www.zkcompression.com/light-token/cookbook/create-mint

Program and client guides to create a mint with token metadata. For existing SPL or Token 2022 mints add an interface PDA for interoperability. Includes step-by-step implementation and full code examples.

***

1. Mint accounts uniquely represent a token on Solana and store its global metadata.
2. Light mints are on-chain accounts like SPL mints, but the light token program sponsors the rent-exemption cost for you.
3. Add an interface PDA to existing SPL or Token 2022 mints for interoperability with Light Token. The interface PDA holds SPL or Token 2022 tokens when wrapped to Light Token.

<Accordion title="Light Rent Config Explained">
  1) The Light Token Program pays the rent-exemption cost for the account.
  2) Transaction fee payers bump a virtual rent balance when writing to the account, which keeps the account "hot".
  3) "Cold" accounts virtual rent balance below threshold (eg 24h without write bump) get auto-compressed.
  4) The cold account's state is cryptographically preserved on the Solana ledger.
     Users can load a cold account into hot state in-flight when using the account
     again.
</Accordion>

<Tabs>
  <Tab title="TypeScript Client">
    `createMintInterface` is a unified interface that dispatches to different mint creation paths based on programId:

    * `TOKEN_PROGRAM_ID` or `TOKEN_2022_PROGRAM_ID` → delegates to SPL or T22 `createMint`
    * Otherwise it defaults to `LIGHT_TOKEN_PROGRAM_ID` → creates a Light Token mint

    You can use the same interface regardless of mint type.

    Compare to SPL:

    <CodeCompare />

    <Info>
      Find the source code
      [here](https://github.com/Lightprotocol/light-protocol/blob/0c4e2417b2df2d564721b89e18d1aad3665120e7/js/compressed-token/src/v3/actions/create-mint-interface.ts).
    </Info>

    <Steps>
      <Step>
        ### Create Mint with Token Metadata

        <Accordion title="Installation">
          <Tabs>
            <Tab title="npm">
              Install packages in your working directory:

              ```bash theme={null} theme={null} theme={null} theme={null}
              npm install @lightprotocol/stateless.js@beta \
                          @lightprotocol/compressed-token@beta
              ```

              Install the CLI globally:

              ```bash theme={null} theme={null} theme={null} theme={null}
              npm install -g @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>

            <Tab title="yarn">
              Install packages in your working directory:

              ```bash theme={null} theme={null} theme={null} theme={null}
              yarn add @lightprotocol/stateless.js@beta \
                       @lightprotocol/compressed-token@beta
              ```

              Install the CLI globally:

              ```bash theme={null} theme={null} theme={null} theme={null}
              yarn global add @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>

            <Tab title="pnpm">
              Install packages in your working directory:

              ```bash theme={null} theme={null} theme={null} theme={null}
              pnpm add @lightprotocol/stateless.js@beta \
                       @lightprotocol/compressed-token@beta
              ```

              Install the CLI globally:

              ```bash theme={null} theme={null} theme={null} theme={null}
              pnpm add -g @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>
          </Tabs>
        </Accordion>

        <Tabs>
          <Tab title="Localnet">
            ```bash theme={null} theme={null} theme={null} theme={null}
            # start local test-validator in a separate terminal
            light test-validator
            ```

            <Note>
              In the code examples, use `createRpc()` without arguments for localnet.
            </Note>
          </Tab>

          <Tab title="Devnet">
            Get an API key from [Helius](https://helius.dev) and add to `.env`:

            ```bash title=".env" theme={null} theme={null} theme={null} theme={null}
            API_KEY=<your-helius-api-key>
            ```

            <Note>
              In the code examples, use `createRpc(RPC_URL)` with the devnet URL.
            </Note>
          </Tab>
        </Tabs>

        <Note>
          The `mintAuthority` must be a `Signer` for light-mints but can be just a
          `PublicKey` for SPL/T22.
        </Note>

        <Tabs>
          <Tab title="Action">
            ```typescript theme={null} theme={null} theme={null} theme={null}
            import "dotenv/config";
            import { Keypair } from "@solana/web3.js";
            import { createRpc } from "@lightprotocol/stateless.js";
            import { createMintInterface, createTokenMetadata } 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, transactionSignature } = await createMintInterface(
                    rpc,
                    payer,
                    payer,
                    null,
                    9,
                    undefined,
                    undefined,
                    undefined,
                    createTokenMetadata("Example Token", "EXT", "https://example.com/metadata.json")
                );

                console.log("Mint:", mint.toBase58());
                console.log("Tx:", transactionSignature);
            })();
            ```
          </Tab>

          <Tab title="Instruction">
            ```typescript theme={null} theme={null} theme={null} theme={null}
            import "dotenv/config";
            import {
                Keypair,
                ComputeBudgetProgram,
                PublicKey,
                Transaction,
                sendAndConfirmTransaction,
            } from "@solana/web3.js";
            import {
                createRpc,
                getBatchAddressTreeInfo,
                selectStateTreeInfo,
                CTOKEN_PROGRAM_ID,
            } from "@lightprotocol/stateless.js";
            import {
                createMintInstruction,
                createTokenMetadata,
            } from "@lightprotocol/compressed-token";
            import { homedir } from "os";
            import { readFileSync } from "fs";

            const COMPRESSED_MINT_SEED = Buffer.from("compressed_mint");

            function findMintAddress(mintSigner: PublicKey): [PublicKey, number] {
                return PublicKey.findProgramAddressSync(
                    [COMPRESSED_MINT_SEED, mintSigner.toBuffer()],
                    CTOKEN_PROGRAM_ID,
                );
            }

            // 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 mintSigner = Keypair.generate();
                const addressTreeInfo = getBatchAddressTreeInfo();
                const stateTreeInfo = selectStateTreeInfo(await rpc.getStateTreeInfos());
                const [mintPda] = findMintAddress(mintSigner.publicKey);

                const validityProof = await rpc.getValidityProofV2(
                    [],
                    [{ address: mintPda.toBytes(), treeInfo: addressTreeInfo }],
                );

                const ix = createMintInstruction(
                    mintSigner.publicKey,
                    9,
                    payer.publicKey,
                    null,
                    payer.publicKey,
                    validityProof,
                    addressTreeInfo,
                    stateTreeInfo,
                    createTokenMetadata(
                        "Example Token",
                        "EXT",
                        "https://example.com/metadata.json",
                    ),
                );

                const tx = new Transaction().add(
                    ComputeBudgetProgram.setComputeUnitLimit({ units: 1_000_000 }),
                    ix,
                );
                const signature = await sendAndConfirmTransaction(rpc, tx, [
                    payer,
                    mintSigner,
                ]);

                console.log("Mint:", mintPda.toBase58());
                console.log("Tx:", signature);
            })();
            ```
          </Tab>
        </Tabs>
      </Step>
    </Steps>

    ### Add Interface PDA to SPL / Token 2022 mints

    <Tabs>
      <Tab title="Add to Existing Mints">
        Register an interface PDA for an existing SPL mint for interoperability with Light Token. No mint authority required.

        <Tabs>
          <Tab title="Action">
            ```typescript theme={null} theme={null} theme={null} theme={null}
            import "dotenv/config";
            import { Keypair, PublicKey } from "@solana/web3.js";
            import { createRpc } from "@lightprotocol/stateless.js";
            import { createSplInterface } 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 existingMint = new PublicKey("YOUR_EXISTING_MINT_ADDRESS");

                const tx = await createSplInterface(rpc, payer, existingMint);

                console.log("Mint:", existingMint.toBase58());
                console.log("Tx:", tx);
            })();
            ```
          </Tab>

          <Tab title="Instruction">
            ```typescript theme={null} theme={null} theme={null} theme={null}
            import "dotenv/config";
            import {
                Keypair,
                PublicKey,
                Transaction,
                sendAndConfirmTransaction,
            } from "@solana/web3.js";
            import { createRpc } from "@lightprotocol/stateless.js";
            import { CompressedTokenProgram } from "@lightprotocol/compressed-token";
            import { TOKEN_PROGRAM_ID } from "@solana/spl-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 existingMint = new PublicKey("YOUR_EXISTING_MINT_ADDRESS");

                const ix = await CompressedTokenProgram.createTokenPool({
                    feePayer: payer.publicKey,
                    mint: existingMint,
                    tokenProgramId: TOKEN_PROGRAM_ID,
                });

                const tx = new Transaction().add(ix);
                const signature = await sendAndConfirmTransaction(rpc, tx, [payer]);

                console.log("Mint:", existingMint.toBase58());
                console.log("Tx:", signature);
            })();
            ```
          </Tab>
        </Tabs>
      </Tab>

      <Tab title="Create SPL Mint with Interface PDA">
        Pass `TOKEN_PROGRAM_ID` to create a standard SPL mint with an interface PDA in one transaction for interoperability with Light Token.

        <Tabs>
          <Tab title="Action">
            ```typescript theme={null} theme={null} theme={null} theme={null}
            import "dotenv/config";
            import { Keypair } from "@solana/web3.js";
            import { createRpc } from "@lightprotocol/stateless.js";
            import { createMintInterface } from "@lightprotocol/compressed-token";
            import { TOKEN_PROGRAM_ID } from "@solana/spl-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 () {
                // Creates SPL mint + SPL interface pda (token pool) in one transaction
                const mintKeypair = Keypair.generate();
                const { mint, transactionSignature } = await createMintInterface(
                    rpc,
                    payer,
                    payer,
                    null,
                    9,
                    mintKeypair,
                    undefined,
                    TOKEN_PROGRAM_ID
                );

                console.log("Mint:", mint.toBase58());
                console.log("Tx:", transactionSignature);
            })();
            ```
          </Tab>

          <Tab title="Instruction">
            ```typescript theme={null} theme={null} theme={null} theme={null}
            import "dotenv/config";
            import {
                Keypair,
                SystemProgram,
                Transaction,
                sendAndConfirmTransaction,
            } from "@solana/web3.js";
            import { createRpc } from "@lightprotocol/stateless.js";
            import { CompressedTokenProgram } from "@lightprotocol/compressed-token";
            import {
                MINT_SIZE,
                TOKEN_PROGRAM_ID,
                createInitializeMint2Instruction,
            } from "@solana/spl-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 mintKeypair = Keypair.generate();
                const decimals = 9;

                // Get rent for mint account
                const rentExemptBalance = await rpc.getMinimumBalanceForRentExemption(MINT_SIZE);

                // Instruction 1: Create mint account
                const createMintAccountIx = SystemProgram.createAccount({
                    fromPubkey: payer.publicKey,
                    lamports: rentExemptBalance,
                    newAccountPubkey: mintKeypair.publicKey,
                    programId: TOKEN_PROGRAM_ID,
                    space: MINT_SIZE,
                });

                // Instruction 2: Initialize mint
                const initializeMintIx = createInitializeMint2Instruction(
                    mintKeypair.publicKey,
                    decimals,
                    payer.publicKey, // mint authority
                    null, // freeze authority
                    TOKEN_PROGRAM_ID
                );

                // Instruction 3: Create SPL interface pda (token pool, enables compression of the SPL mint's tokens)
                const createTokenPoolIx = await CompressedTokenProgram.createTokenPool({
                    feePayer: payer.publicKey,
                    mint: mintKeypair.publicKey,
                    tokenProgramId: TOKEN_PROGRAM_ID,
                });

                const tx = new Transaction().add(
                    createMintAccountIx,
                    initializeMintIx,
                    createTokenPoolIx
                );

                const signature = await sendAndConfirmTransaction(rpc, tx, [
                    payer,
                    mintKeypair,
                ]);

                console.log("Mint:", mintKeypair.publicKey.toBase58());
                console.log("Tx:", signature);
            })();
            ```
          </Tab>
        </Tabs>
      </Tab>

      <Tab title="Create Token 2022 with Interface PDA">
        Pass `TOKEN_2022_PROGRAM_ID` to create a Token-2022 mint with an interface PDA in one transaction for interoperability with Light Token.

        <Tabs>
          <Tab title="Action">
            ```typescript theme={null} theme={null} theme={null} theme={null}
            import "dotenv/config";
            import { Keypair } from "@solana/web3.js";
            import { createRpc } from "@lightprotocol/stateless.js";
            import { createMintInterface } from "@lightprotocol/compressed-token";
            import { TOKEN_2022_PROGRAM_ID } from "@solana/spl-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 () {
                // Creates Token-2022 mint and SPL interface PDA in one transaction
                // SPL interface PDA holds Token-2022 tokens when wrapped to light-token
                const mintKeypair = Keypair.generate();
                const { mint, transactionSignature } = await createMintInterface(
                    rpc,
                    payer,
                    payer,
                    null,
                    9,
                    mintKeypair,
                    undefined,
                    TOKEN_2022_PROGRAM_ID
                );

                console.log("Mint:", mint.toBase58());
                console.log("Tx:", transactionSignature);
            })();
            ```
          </Tab>

          <Tab title="Instruction">
            ```typescript theme={null} theme={null} theme={null} theme={null}
            import "dotenv/config";
            import {
                Keypair,
                SystemProgram,
                Transaction,
                sendAndConfirmTransaction,
            } from "@solana/web3.js";
            import { createRpc } from "@lightprotocol/stateless.js";
            import { CompressedTokenProgram } from "@lightprotocol/compressed-token";
            import {
                MINT_SIZE,
                TOKEN_2022_PROGRAM_ID,
                createInitializeMint2Instruction,
            } from "@solana/spl-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 mintKeypair = Keypair.generate();
                const decimals = 9;

                // Get rent for mint account
                const rentExemptBalance =
                    await rpc.getMinimumBalanceForRentExemption(MINT_SIZE);

                // Instruction 1: Create mint account
                const createMintAccountIx = SystemProgram.createAccount({
                    fromPubkey: payer.publicKey,
                    lamports: rentExemptBalance,
                    newAccountPubkey: mintKeypair.publicKey,
                    programId: TOKEN_2022_PROGRAM_ID,
                    space: MINT_SIZE,
                });

                // Instruction 2: Initialize mint
                const initializeMintIx = createInitializeMint2Instruction(
                    mintKeypair.publicKey,
                    decimals,
                    payer.publicKey, // mint authority
                    null, // freeze authority
                    TOKEN_2022_PROGRAM_ID
                );

                // Instruction 3: Create SPL interface PDA
                // Holds Token-2022 tokens when wrapped to light-token
                const createSplInterfaceIx = await CompressedTokenProgram.createTokenPool({
                    feePayer: payer.publicKey,
                    mint: mintKeypair.publicKey,
                    tokenProgramId: TOKEN_2022_PROGRAM_ID,
                });

                const tx = new Transaction().add(
                    createMintAccountIx,
                    initializeMintIx,
                    createSplInterfaceIx
                );

                const signature = await sendAndConfirmTransaction(rpc, tx, [
                    payer,
                    mintKeypair,
                ]);

                console.log("Mint:", mintKeypair.publicKey.toBase58());
                console.log("Tx:", signature);
            })();
            ```
          </Tab>
        </Tabs>
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Rust Client">
    `CreateMint` creates an on-chain mint account that can optionally include token metadata.
    The instruction also writes a compressed mint address to the address Merkle tree, which preserves the mint state when the on-chain account is compressed.

    Compare to SPL:

    <CodeCompare />

    <Steps>
      <Step>
        ### Prerequisites

        <Accordion title="Dependencies">
          ```toml Cargo.toml theme={null} theme={null} theme={null} theme={null}
          [dependencies]
          light-token = "0.4.0"
          light-client = { version = "0.19.0", features = ["v2"] }
          solana-sdk = "2"
          borsh = "0.10.4"
          tokio = { version = "1", features = ["full"] }
          ```
        </Accordion>

        <Accordion title="Developer Environment">
          <Tabs>
            <Tab title="In-Memory (LightProgramTest)">
              Test with Lite-SVM (...)

              ```bash theme={null} theme={null} theme={null} theme={null}
              # Initialize project
              cargo init my-light-project
              cd my-light-project

              # Run tests
              cargo test
              ```

              ```rust theme={null} theme={null} theme={null} theme={null}
              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());
              }
              ```
            </Tab>

            <Tab title="Localnet (LightClient)">
              Connects to a local test validator.

              <Tabs>
                <Tab title="npm">
                  ```bash theme={null} theme={null} theme={null} theme={null}
                  npm install -g @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>

                <Tab title="yarn">
                  ```bash theme={null} theme={null} theme={null} theme={null}
                  yarn global add @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>

                <Tab title="pnpm">
                  ```bash theme={null} theme={null} theme={null} theme={null}
                  pnpm add -g @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>
              </Tabs>

              ```bash theme={null} theme={null} theme={null} theme={null}
              # Initialize project
              cargo init my-light-project
              cd my-light-project

              # Start local test validator (in separate terminal)
              light test-validator
              ```

              ```rust theme={null} theme={null} theme={null} theme={null}
              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(())
              }
              ```
            </Tab>

            <Tab title="Devnet (LightClient)">
              Replace `<your-api-key>` with your actual API key. [Get your API key here](https://www.helius.dev/zk-compression).

              ```rust theme={null} theme={null} theme={null} theme={null}
              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(())
              }
              ```
            </Tab>
          </Tabs>
        </Accordion>
      </Step>

      <Step>
        ### Create Light Token Mint with Token Metadata

        <Info>
          View the [source code](https://github.com/Lightprotocol/light-protocol/blob/main/sdk-libs/token-sdk/src/instruction/create_mint.rs) and [full example](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/instructions/create_mint.rs) with shared test utilities.
        </Info>

        <Tabs>
          <Tab title="Action">
            ```rust theme={null} theme={null} theme={null} theme={null}
            use light_client::rpc::Rpc;
            use light_token_client::actions::{CreateMint, TokenMetadata};
            use rust_client::setup_rpc_and_payer;
            use solana_sdk::signer::Signer;

            #[tokio::main]
            async fn main() -> Result<(), Box<dyn std::error::Error>> {
                let (mut rpc, payer) = setup_rpc_and_payer().await;

                let (signature, mint) = CreateMint {
                    decimals: 9,
                    freeze_authority: None,
                    token_metadata: Some(TokenMetadata {
                        name: "Example Token".to_string(),
                        symbol: "EXT".to_string(),
                        uri: "https://example.com/metadata.json".to_string(),
                        update_authority: Some(payer.pubkey()),
                        additional_metadata: Some(vec![("type".to_string(), "example".to_string())]),
                    }),
                    seed: None,
                }
                .execute(&mut rpc, &payer, &payer)
                .await?;

                let data = rpc.get_account(mint).await?;
                println!("Mint: {mint} exists: {} Tx: {signature}", data.is_some());

                Ok(())
            }
            ```
          </Tab>

          <Tab title="Instruction">
            ```rust theme={null} theme={null} theme={null} theme={null}
            use light_client::{
                indexer::{AddressWithTree, Indexer},
                rpc::Rpc,
            };
            use light_program_test::{LightProgramTest, ProgramTestConfig};
            use light_token::instruction::{
                derive_mint_compressed_address, find_mint_address, CreateMint, CreateMintParams,
                DEFAULT_RENT_PAYMENT, DEFAULT_WRITE_TOP_UP,
            };
            use light_token_interface::{
                instructions::extensions::{
                    token_metadata::TokenMetadataInstructionData, ExtensionInstructionData,
                },
                state::AdditionalMetadata,
            };
            use solana_sdk::{signature::Keypair, signer::Signer};

            #[tokio::main]
            async fn main() -> Result<(), Box<dyn std::error::Error>> {
                let mut rpc = LightProgramTest::new(ProgramTestConfig::new_v2(false, None)).await?;

                let payer = rpc.get_payer().insecure_clone();
                let mint_seed = Keypair::new();
                let decimals = 9u8;

                // Get address tree to store compressed address for when mint turns inactive
                // We must create a compressed address at creation to ensure the mint does not exist yet
                let address_tree = rpc.get_address_tree_v2();
                // Get state tree to store mint when inactive
                let output_queue = rpc.get_random_state_tree_info().unwrap().queue;

                // Derive mint addresses
                let compression_address =
                    derive_mint_compressed_address(&mint_seed.pubkey(), &address_tree.tree);
                let mint = find_mint_address(&mint_seed.pubkey()).0; // on-chain Mint PDA

                // Fetch validity proof to proof address does not exist yet
                let rpc_result = rpc
                    .get_validity_proof(
                        vec![],
                        vec![AddressWithTree {
                            address: compression_address,
                            tree: address_tree.tree,
                        }],
                        None,
                    )
                    .await
                    .unwrap()
                    .value;

                // Build CreateMintParams with token metadata extension
                let params = CreateMintParams {
                    decimals,
                    address_merkle_tree_root_index: rpc_result.addresses[0].root_index, // stores mint compressed address
                    mint_authority: payer.pubkey(),
                    proof: rpc_result.proof.0.unwrap(),
                    compression_address, // address for compression when mint turns inactive
                    mint,
                    bump: find_mint_address(&mint_seed.pubkey()).1,
                    freeze_authority: None,
                    extensions: Some(vec![ExtensionInstructionData::TokenMetadata(
                        TokenMetadataInstructionData {
                            update_authority: Some(payer.pubkey().to_bytes().into()),
                            name: b"Example Token".to_vec(),
                            symbol: b"EXT".to_vec(),
                            uri: b"https://example.com/metadata.json".to_vec(),
                            additional_metadata: Some(vec![AdditionalMetadata {
                                key: b"type".to_vec(),
                                value: b"example".to_vec(),
                            }]),
                        },
                    )]),
                    rent_payment: DEFAULT_RENT_PAYMENT, // 24h of rent
                    write_top_up: DEFAULT_WRITE_TOP_UP, // 3h of rent
                };

                // Build and send instruction (mint_seed must sign)
                let create_mint_instruction = CreateMint::new(
                    params,
                    mint_seed.pubkey(),
                    payer.pubkey(),
                    address_tree.tree,
                    output_queue,
                )
                .instruction()?;

                let sig = rpc
                    .create_and_send_transaction(&[create_mint_instruction], &payer.pubkey(), &[&payer, &mint_seed])
                    .await?;

                let data = rpc.get_account(mint).await?;
                println!("Mint: {} exists: {} Tx: {sig}", mint, data.is_some());

                Ok(())
            }
            ```
          </Tab>
        </Tabs>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Program">
    <Tabs>
      <Tab title="CPI">
        Compare to SPL:

        <Tabs>
          <Tab title="Mint">
            <CodeCompare />
          </Tab>

          <Tab title="With Token Metadata">
            <CodeCompare />
          </Tab>
        </Tabs>

        <Note>
          Find [a full code example at the end](#full-code-example).
        </Note>

        <Steps>
          <Step>
            ### Configure Token Metadata

            ```rust theme={null}
            use light_token_interface::instructions::extensions::{
                token_metadata::TokenMetadataInstructionData, ExtensionInstructionData,
            };

            let extensions = Some(vec![ExtensionInstructionData::TokenMetadata(
                TokenMetadataInstructionData {
                    update_authority: Some(authority.key.to_bytes().into()),
                    name: b"Example Token".to_vec(),
                    symbol: b"EXT".to_vec(),
                    uri: b"https://example.com/metadata.json".to_vec(),
                    additional_metadata: None,
                },
            )]);
            ```

            <Note>
              **Fields must be set at light-mint creation.** Standard fields (`name`,
              `symbol`, `uri`) can be updated by `update_authority`. For
              `additional_metadata`, only existing keys can be modified or removed. New keys
              cannot be added after creation.
            </Note>
          </Step>

          <Step>
            ### Configure Mint

            Configure mint parameters including `decimals`, authorities, rent settings, and pass `extensions` from the previous step.

            ```rust theme={null}
            use light_token::instruction::CreateMintParams;

            let params = CreateMintParams {
                decimals,
                address_merkle_tree_root_index,
                mint_authority: *ctx.accounts.authority.key,
                proof,
                compression_address,
                mint,
                bump,
                freeze_authority,
                extensions,
                rent_payment: rent_payment.unwrap_or(16),    // ~24 hours rent
                write_top_up: write_top_up.unwrap_or(766),   // ~3 hours rent
            };
            ```

            <Info>
              The address of the mint account is stored in an address Merkle tree
              , which is maintained by the protocol.
              The client passes a validity proof that proves the mint address does not
              exist yet.
            </Info>
          </Step>

          <Step>
            ### System Accounts

            Include system accounts such as the Light System Program
            to verify the proof and write the mint address to the address tree.

            <Accordion title="System Accounts List">
              <table>
                <colgroup>
                  <col />

                  <col />

                  <col />
                </colgroup>

                <thead>
                  <tr>
                    <th />

                    <th>Account</th>
                    <th>Description</th>
                  </tr>
                </thead>

                <tbody>
                  <tr>
                    <td>1</td>
                    <td><strong><Tooltip href="https://solscan.io/account/SySTEM1eSU2p4BGQfQpimFEWWSC1XDFeun3Nqzz3rT7">Light System Program</Tooltip></strong></td>
                    <td>Verifies validity proofs and executes compressed account state transitions.</td>
                  </tr>

                  <tr>
                    <td>2</td>
                    <td><strong>CPI Authority PDA</strong></td>
                    <td>PDA that authorizes CPIs from the Light Token Program to the Light System Program.</td>
                  </tr>

                  <tr>
                    <td>3</td>
                    <td><strong>Registered Program PDA</strong></td>
                    <td>Proves the Light Token Program is registered to use compression.</td>
                  </tr>

                  <tr>
                    <td>4</td>
                    <td><strong><Tooltip href="https://solscan.io/account/HZH7qSLcpAeDqCopVU4e5XkhT9j3JFsQiq8CmruY3aru">Account Compression Authority</Tooltip></strong></td>
                    <td>Signs CPI calls from the Light System Program to the Account Compression Program.</td>
                  </tr>

                  <tr>
                    <td>5</td>
                    <td><strong><Tooltip href="https://solscan.io/account/compr6CUsB5m2jS4Y3831ztGSTnDpnKJTKS95d64XVq">Account Compression Program</Tooltip></strong></td>
                    <td>Writes to state and address Merkle tree accounts.</td>
                  </tr>

                  <tr>
                    <td>6</td>
                    <td><strong><Tooltip href="https://solscan.io/account/11111111111111111111111111111111">System Program</Tooltip></strong></td>
                    <td>Solana System Program.</td>
                  </tr>
                </tbody>
              </table>
            </Accordion>

            ```rust theme={null}
            use light_token::instruction::SystemAccountInfos;

            let system_accounts = SystemAccountInfos {
                light_system_program: ctx.accounts.light_system_program.to_account_info(),
                cpi_authority_pda: ctx.accounts.cpi_authority_pda.to_account_info(),
                registered_program_pda: ctx.accounts.registered_program_pda.to_account_info(),
                account_compression_authority: ctx.accounts.account_compression_authority.to_account_info(),
                account_compression_program: ctx.accounts.account_compression_program.to_account_info(),
                system_program: ctx.accounts.system_program.to_account_info(),
            };
            ```
          </Step>

          <Step>
            ### Build Account Infos and CPI the Light Token Program

            Use `invoke` or `invoke_signed`:

            * When `mint_seed` is an external keypair, use `invoke`.
            * When `mint_seed` is a PDA, use `invoke_signed` with its seeds.
            * When both `mint_seed` and `authority` are PDAs, use `invoke_signed` with both seeds.

            <Tabs>
              <Tab title="invoke (External signer)">
                ```rust theme={null}
                use light_token::instruction::CreateMintCpi;

                CreateMintCpi::new(
                    mint_seed.clone(),
                    authority.clone(),
                    payer.clone(),
                    address_tree.clone(), // stores address
                    output_queue.clone(), // stores account when inactive
                    compressible_config.clone(), // rent settings
                    mint.clone(),
                    rent_sponsor.clone(),
                    system_accounts,
                    params,
                )
                .invoke()
                ```
              </Tab>

              <Tab title="invoke_signed (PDA mint seed)">
                ```rust theme={null}
                use light_token::instruction::CreateMintCpi;

                let signer_seeds: &[&[u8]] = &[MINT_SIGNER_SEED, &[bump]];

                CreateMintCpi::new(
                    mint_seed.clone(),
                    authority.clone(),
                    payer.clone(),
                    address_tree.clone(),
                    output_queue.clone(),
                    compressible_config.clone(),
                    mint.clone(),
                    rent_sponsor.clone(),
                    system_accounts,
                    params,
                )
                .invoke_signed(&[signer_seeds])
                ```
              </Tab>

              <Tab title="invoke_signed (Two PDA signers)">
                ```rust theme={null}
                use light_token::instruction::CreateMintCpi;

                let mint_seed_seeds: &[&[u8]] = &[MINT_SIGNER_SEED, &[mint_seed_bump]];
                let authority_seeds: &[&[u8]] = &[MINT_AUTHORITY_SEED, &[authority_bump]];

                CreateMintCpi::new(
                    mint_seed.clone(),
                    authority.clone(),
                    payer.clone(),
                    address_tree.clone(),
                    output_queue.clone(),
                    compressible_config.clone(),
                    mint.clone(),
                    rent_sponsor.clone(),
                    system_accounts,
                    params,
                )
                .invoke_signed(&[mint_seed_seeds, authority_seeds])
                ```
              </Tab>
            </Tabs>
          </Step>
        </Steps>

        # Full Code Example

        <Tabs>
          <Tab title="Anchor">
            <Info>
              View the [source code](https://github.com/Lightprotocol/light-protocol/blob/main/sdk-libs/token-sdk/src/instruction/create_mint.rs) and [full example](https://github.com/Lightprotocol/examples-light-token/tree/main/programs/anchor/basic-instructions/create-mint) with shared test utilities.
            </Info>

            <CodeGroup>
              ```rust lib.rs theme={null} theme={null} theme={null} theme={null}
              #![allow(unexpected_cfgs, deprecated)]

              use anchor_lang::prelude::*;
              use light_token::instruction::{
                  CreateMintCpi, CreateMintParams, SystemAccountInfos, DEFAULT_RENT_PAYMENT, DEFAULT_WRITE_TOP_UP,
              };
              use light_token::{CompressedProof, ExtensionInstructionData, TokenMetadataInstructionData};

              declare_id!("A1rJEoepgKYWZYZ8KVFpxgeeRGwBrU7xk8S39srjVkUX");

              /// Token metadata parameters for creating a mint with metadata.
              #[derive(AnchorSerialize, AnchorDeserialize, Clone)]
              pub struct TokenMetadataParams {
                  pub name: Vec<u8>,
                  pub symbol: Vec<u8>,
                  pub uri: Vec<u8>,
                  pub update_authority: Option<Pubkey>,
              }

              #[program]
              pub mod light_token_anchor_create_mint {
                  use super::*;

                  pub fn create_mint(
                      ctx: Context<CreateMintAccounts>,
                      decimals: u8,
                      address_merkle_tree_root_index: u16,
                      compression_address: [u8; 32],
                      proof: CompressedProof,
                      freeze_authority: Option<Pubkey>,
                      bump: u8,
                      rent_payment: Option<u8>,
                      write_top_up: Option<u32>,
                      metadata: Option<TokenMetadataParams>,
                  ) -> Result<()> {
                      let mint = light_token::instruction::find_mint_address(ctx.accounts.mint_seed.key).0;

                      let extensions = metadata.map(|m| {
                          vec![ExtensionInstructionData::TokenMetadata(
                              TokenMetadataInstructionData {
                                  update_authority: m
                                      .update_authority
                                      .map(|p| p.to_bytes().into()),
                                  name: m.name,
                                  symbol: m.symbol,
                                  uri: m.uri,
                                  additional_metadata: None,
                              },
                          )]
                      });

                      let params = CreateMintParams {
                          decimals,
                          address_merkle_tree_root_index,
                          mint_authority: *ctx.accounts.authority.key,
                          proof,
                          compression_address,
                          mint,
                          bump,
                          freeze_authority,
                          extensions,
                          rent_payment: rent_payment.unwrap_or(DEFAULT_RENT_PAYMENT),
                          write_top_up: write_top_up.unwrap_or(DEFAULT_WRITE_TOP_UP),
                      };

                      let system_accounts = SystemAccountInfos {
                          light_system_program: ctx.accounts.light_system_program.to_account_info(),
                          cpi_authority_pda: ctx.accounts.cpi_authority_pda.to_account_info(),
                          registered_program_pda: ctx.accounts.registered_program_pda.to_account_info(),
                          account_compression_authority: ctx.accounts.account_compression_authority.to_account_info(),
                          account_compression_program: ctx.accounts.account_compression_program.to_account_info(),
                          system_program: ctx.accounts.system_program.to_account_info(),
                      };

                      CreateMintCpi {
                          mint_seed: ctx.accounts.mint_seed.to_account_info(),
                          authority: ctx.accounts.authority.to_account_info(),
                          payer: ctx.accounts.payer.to_account_info(),
                          address_tree: ctx.accounts.address_tree.to_account_info(),
                          output_queue: ctx.accounts.output_queue.to_account_info(),
                          compressible_config: ctx.accounts.compressible_config.to_account_info(),
                          mint: ctx.accounts.mint.to_account_info(),
                          rent_sponsor: ctx.accounts.rent_sponsor.to_account_info(),
                          system_accounts,
                          cpi_context: None,
                          cpi_context_account: None,
                          params,
                      }
                      .invoke()?;
                      Ok(())
                  }
              }

              #[derive(Accounts)]
              pub struct CreateMintAccounts<'info> {
                  /// CHECK: Light token program for CPI
                  pub light_token_program: AccountInfo<'info>,
                  pub mint_seed: Signer<'info>,
                  /// CHECK: Validated by light-token CPI
                  pub authority: AccountInfo<'info>,
                  #[account(mut)]
                  pub payer: Signer<'info>,
                  /// CHECK: Validated by light-token CPI
                  #[account(mut)]
                  pub address_tree: AccountInfo<'info>,
                  /// CHECK: Validated by light-token CPI
                  #[account(mut)]
                  pub output_queue: AccountInfo<'info>,
                  /// CHECK: Validated by light-token CPI
                  pub light_system_program: AccountInfo<'info>,
                  /// CHECK: Validated by light-token CPI
                  pub cpi_authority_pda: AccountInfo<'info>,
                  /// CHECK: Validated by light-token CPI
                  pub registered_program_pda: AccountInfo<'info>,
                  /// CHECK: Validated by light-token CPI
                  pub account_compression_authority: AccountInfo<'info>,
                  /// CHECK: Validated by light-token CPI
                  pub account_compression_program: AccountInfo<'info>,
                  pub system_program: Program<'info, System>,
                  /// CHECK: Validated by light-token CPI - use light_token::token::config_pda()
                  pub compressible_config: AccountInfo<'info>,
                  /// CHECK: Validated by light-token CPI - derived from find_mint_address(mint_seed)
                  #[account(mut)]
                  pub mint: AccountInfo<'info>,
                  /// CHECK: Validated by light-token CPI - use light_token::token::rent_sponsor_pda()
                  #[account(mut)]
                  pub rent_sponsor: AccountInfo<'info>,
              }
              ```

              ```rust test.rs theme={null} theme={null} theme={null} theme={null}
              use anchor_lang::{InstructionData, ToAccountMetas};
              use light_program_test::{Indexer, LightProgramTest, ProgramTestConfig, Rpc};
              use light_token_anchor_create_mint::{accounts, instruction::CreateMint, ID};
              use light_token::instruction::{
                  config_pda, derive_mint_compressed_address, find_mint_address, rent_sponsor_pda,
                  SystemAccounts, LIGHT_TOKEN_PROGRAM_ID, DEFAULT_RENT_PAYMENT, DEFAULT_WRITE_TOP_UP,
              };
              use anchor_lang::system_program;
              use solana_sdk::{
                  instruction::Instruction,
                  signature::Keypair,
                  signer::Signer,
              };

              #[tokio::test]
              async fn test_create_mint() {
                  let config =
                      ProgramTestConfig::new_v2(true, Some(vec![("light_token_anchor_create_mint", ID)]));
                  let mut rpc = LightProgramTest::new(config).await.unwrap();
                  let payer = rpc.get_payer().insecure_clone();

                  let mint_seed = Keypair::new();
                  let mint_authority = payer.pubkey();
                  let decimals = 9u8;

                  let address_tree = rpc.get_address_tree_v2();
                  let output_queue = rpc.get_random_state_tree_info().unwrap().queue;

                  let compression_address =
                      derive_mint_compressed_address(&mint_seed.pubkey(), &address_tree.tree);

                  let (mint_pda, bump) = find_mint_address(&mint_seed.pubkey());

                  let rpc_result = rpc
                      .get_validity_proof(
                          vec![],
                          vec![light_client::indexer::AddressWithTree {
                              address: compression_address,
                              tree: address_tree.tree,
                          }],
                          None,
                      )
                      .await
                      .unwrap()
                      .value;

                  let system_accounts = SystemAccounts::default();

                  // Call the anchor program to create mint
                  let ix = Instruction {
                      program_id: ID,
                      accounts: accounts::CreateMintAccounts {
                          light_token_program: LIGHT_TOKEN_PROGRAM_ID,
                          mint_seed: mint_seed.pubkey(),
                          authority: mint_authority,
                          payer: payer.pubkey(),
                          address_tree: address_tree.tree,
                          output_queue,
                          light_system_program: system_accounts.light_system_program,
                          cpi_authority_pda: system_accounts.cpi_authority_pda,
                          registered_program_pda: system_accounts.registered_program_pda,
                          account_compression_authority: system_accounts.account_compression_authority,
                          account_compression_program: system_accounts.account_compression_program,
                          system_program: system_program::ID,
                          compressible_config: config_pda(),
                          mint: mint_pda,
                          rent_sponsor: rent_sponsor_pda(),
                      }
                      .to_account_metas(Some(true)),
                      data: CreateMint {
                          decimals,
                          address_merkle_tree_root_index: rpc_result.addresses[0].root_index,
                          compression_address: compression_address.into(),
                          proof: rpc_result.proof.0.unwrap(),
                          freeze_authority: None,
                          bump,
                          rent_payment: Some(DEFAULT_RENT_PAYMENT),
                          write_top_up: Some(DEFAULT_WRITE_TOP_UP),
                          metadata: None,
                      }
                      .data(),
                  };

                  let sig = rpc
                      .create_and_send_transaction(&[ix], &payer.pubkey(), &[&payer, &mint_seed])
                      .await
                      .unwrap();

                  let compressed_account = rpc
                      .get_compressed_account(compression_address, None)
                      .await
                      .unwrap()
                      .value;

                  assert!(compressed_account.is_some(), "Light-mint should exist");
                  println!("Tx: {}", sig);
              }
              ```
            </CodeGroup>
          </Tab>
        </Tabs>
      </Tab>

      <Tab title="Anchor Macros">
        Compare to SPL:

        <Tabs>
          <Tab title="Mint">
            <CodeCompare />
          </Tab>

          <Tab title="With Token Metadata">
            <CodeCompare />
          </Tab>
        </Tabs>

        <Note>
          Find [a full code example at the end](#full-code-example).
        </Note>

        <Steps>
          <Step>
            ### Dependencies

            ```toml theme={null}
            [dependencies]
            light-sdk = { version = "0.18.0", features = ["anchor", "v2", "cpi-context"] }
            light-sdk-macros = "0.18.0"
            light-compressible = "0.1.0"
            anchor-lang = "0.31"
            ```
          </Step>

          <Step>
            ### Program

            Add `#[light_program]` above `#[program]`:

            ```rust theme={null}
            use light_sdk_macros::light_program;

            #[light_program]
            #[program]
            pub mod my_program {
                use super::*;

                pub fn create_mint<'info>(
                    ctx: Context<'_, '_, '_, 'info, CreateMint<'info>>,
                    params: CreateMintParams,
                ) -> Result<()> {
                    Ok(())
                }
            }
            ```
          </Step>

          <Step>
            ### Accounts struct

            Derive `LightAccounts` on your `Accounts` struct and add `#[light_account(...)]` next to `#[account(...)]`.

            <Tabs>
              <Tab title="Mint">
                ```rust theme={null}
                /// CHECK: Validated by light-token CPI
                #[account(mut)]
                #[light_account(init,
                    mint::signer = mint_signer,
                    mint::authority = fee_payer,
                    mint::decimals = 9,
                    mint::seeds = &[MINT_SIGNER_SEED, self.authority.to_account_info().key.as_ref()],
                    mint::bump = params.mint_signer_bump
                )]
                pub mint: UncheckedAccount<'info>,
                ```
              </Tab>

              <Tab title="Mint with metadata">
                ```rust theme={null}
                /// CHECK: Validated by light-token CPI
                #[account(mut)]
                #[light_account(init,
                    mint::signer = mint_signer,
                    mint::authority = fee_payer,
                    mint::decimals = 9,
                    mint::seeds = &[MINT_SIGNER_SEED, self.authority.to_account_info().key.as_ref()],
                    mint::bump = params.mint_signer_bump,
                    mint::name = params.name.clone(),
                    mint::symbol = params.symbol.clone(),
                    mint::uri = params.uri.clone(),
                    mint::update_authority = authority,
                    mint::additional_metadata = params.additional_metadata.clone()
                )]
                pub mint: UncheckedAccount<'info>,
                ```
              </Tab>
            </Tabs>
          </Step>
        </Steps>

        # Full code example

        <Info>
          View the [source code](https://github.com/Lightprotocol/light-protocol/blob/main/sdk-libs/token-sdk/src/instruction/create_mint.rs) and [full example](https://github.com/Lightprotocol/examples-light-token/tree/main/programs/anchor/basic-macros/create-mint) with shared test utilities.
        </Info>

        <CodeGroup>
          ```rust lib.rs theme={null} theme={null} theme={null} theme={null}
          #![allow(deprecated)]

          use anchor_lang::prelude::*;
          use light_compressible::CreateAccountsProof;
          use light_sdk::derive_light_cpi_signer;
          use light_sdk_macros::{light_program, LightAccounts};
          use light_sdk_types::CpiSigner;

          declare_id!("HVmVqSJyMejBeUigePMSfX4aENJzCGHNxAJuT2PDMPRx");

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

          pub const MINT_SIGNER_SEED: &[u8] = b"mint_signer";

          #[derive(AnchorSerialize, AnchorDeserialize, Clone)]
          pub struct CreateMintParams {
              pub create_accounts_proof: CreateAccountsProof,
              pub mint_signer_bump: u8,
          }

          #[derive(AnchorSerialize, AnchorDeserialize, Clone)]
          pub struct CreateMintWithMetadataParams {
              pub create_accounts_proof: CreateAccountsProof,
              pub mint_signer_bump: u8,
              pub name: Vec<u8>,
              pub symbol: Vec<u8>,
              pub uri: Vec<u8>,
          }

          #[derive(Accounts, LightAccounts)]
          #[instruction(params: CreateMintParams)]
          pub struct CreateMint<'info> {
              #[account(mut)]
              pub fee_payer: Signer<'info>,

              pub authority: Signer<'info>,

              /// CHECK: PDA derived from authority
              #[account(
                  seeds = [MINT_SIGNER_SEED, authority.key().as_ref()],
                  bump,
              )]
              pub mint_signer: UncheckedAccount<'info>,

              /// CHECK: Initialized by light_mint CPI
              #[account(mut)]
              #[light_account(init,
                  mint::signer = mint_signer,
                  mint::authority = fee_payer,
                  mint::decimals = 9,
                  mint::seeds = &[MINT_SIGNER_SEED, self.authority.to_account_info().key.as_ref()],
                  mint::bump = params.mint_signer_bump
              )]
              pub mint: UncheckedAccount<'info>,

              /// CHECK: Compression config PDA
              pub compression_config: AccountInfo<'info>,

              /// CHECK: Light Token compressible config
              pub light_token_compressible_config: AccountInfo<'info>,

              /// CHECK: Rent sponsor
              #[account(mut)]
              pub rent_sponsor: AccountInfo<'info>,

              /// CHECK: Light Token program
              pub light_token_program: AccountInfo<'info>,

              /// CHECK: Light Token CPI authority
              pub light_token_cpi_authority: AccountInfo<'info>,

              pub system_program: Program<'info, System>,
          }

          #[derive(Accounts, LightAccounts)]
          #[instruction(params: CreateMintWithMetadataParams)]
          pub struct CreateMintWithMetadata<'info> {
              #[account(mut)]
              pub fee_payer: Signer<'info>,

              pub authority: Signer<'info>,

              /// CHECK: PDA derived from authority
              #[account(
                  seeds = [MINT_SIGNER_SEED, authority.key().as_ref()],
                  bump,
              )]
              pub mint_signer: UncheckedAccount<'info>,

              /// CHECK: Initialized by light_mint CPI
              #[account(mut)]
              #[light_account(init,
                  mint::signer = mint_signer,
                  mint::authority = fee_payer,
                  mint::decimals = 9,
                  mint::seeds = &[MINT_SIGNER_SEED, self.authority.to_account_info().key.as_ref()],
                  mint::bump = params.mint_signer_bump,
                  mint::name = params.name.clone(),
                  mint::symbol = params.symbol.clone(),
                  mint::uri = params.uri.clone(),
                  mint::update_authority = authority
              )]
              pub mint: UncheckedAccount<'info>,

              /// CHECK: Compression config PDA
              pub compression_config: AccountInfo<'info>,

              /// CHECK: Light Token compressible config
              pub light_token_compressible_config: AccountInfo<'info>,

              /// CHECK: Rent sponsor
              #[account(mut)]
              pub rent_sponsor: AccountInfo<'info>,

              /// CHECK: Light Token program
              pub light_token_program: AccountInfo<'info>,

              /// CHECK: Light Token CPI authority
              pub light_token_cpi_authority: AccountInfo<'info>,

              pub system_program: Program<'info, System>,
          }

          #[light_program]
          #[program]
          pub mod light_token_macro_create_mint {
              use super::*;

              #[allow(unused_variables)]
              pub fn create_mint<'info>(
                  ctx: Context<'_, '_, '_, 'info, CreateMint<'info>>,
                  params: CreateMintParams,
              ) -> Result<()> {
                  Ok(())
              }

              #[allow(unused_variables)]
              pub fn create_mint_with_metadata<'info>(
                  ctx: Context<'_, '_, '_, 'info, CreateMintWithMetadata<'info>>,
                  params: CreateMintWithMetadataParams,
              ) -> Result<()> {
                  Ok(())
              }
          }
          ```

          ```rust test.rs theme={null} theme={null} theme={null} theme={null}
          use anchor_lang::{prelude::borsh, InstructionData, ToAccountMetas};
          use light_client::interface::{
              get_create_accounts_proof, CreateAccountsProofInput, InitializeRentFreeConfig,
          };
          use light_program_test::{
              program_test::{setup_mock_program_data, LightProgramTest},
              ProgramTestConfig, Rpc,
          };
          use light_sdk_types::LIGHT_TOKEN_PROGRAM_ID;
          use light_token::instruction::{find_mint_address, COMPRESSIBLE_CONFIG_V1, RENT_SPONSOR};
          use solana_instruction::Instruction;
          use solana_keypair::Keypair;
          use solana_pubkey::Pubkey;
          use solana_signer::Signer;

          use light_token_macro_create_mint::MINT_SIGNER_SEED;

          async fn setup() -> (light_program_test::LightProgramTest, Keypair, Pubkey, Pubkey) {
              let program_id = light_token_macro_create_mint::ID;
              let mut config =
                  ProgramTestConfig::new_v2(true, Some(vec![("light_token_macro_create_mint", program_id)]));
              config = config.with_light_protocol_events();

              let mut rpc = LightProgramTest::new(config).await.unwrap();
              let payer = rpc.get_payer().insecure_clone();

              let program_data_pda = setup_mock_program_data(&mut rpc, &payer, &program_id);

              let (init_config_ix, config_pda) = InitializeRentFreeConfig::new(
                  &program_id,
                  &payer.pubkey(),
                  &program_data_pda,
                  RENT_SPONSOR,
                  payer.pubkey(),
              )
              .build();

              rpc.create_and_send_transaction(&[init_config_ix], &payer.pubkey(), &[&payer])
                  .await
                  .expect("Initialize config should succeed");

              (rpc, payer, config_pda, program_id)
          }

          #[tokio::test]
          async fn test_create_mint() {
              use light_token_macro_create_mint::CreateMintParams;

              let (mut rpc, payer, config_pda, program_id) = setup().await;

              let authority = Keypair::new();
              let (mint_signer_pda, mint_signer_bump) = Pubkey::find_program_address(
                  &[MINT_SIGNER_SEED, authority.pubkey().as_ref()],
                  &program_id,
              );
              let (mint_pda, _) = find_mint_address(&mint_signer_pda);

              let proof_result = get_create_accounts_proof(
                  &rpc,
                  &program_id,
                  vec![CreateAccountsProofInput::mint(mint_signer_pda)],
              )
              .await
              .unwrap();

              let accounts = light_token_macro_create_mint::accounts::CreateMint {
                  fee_payer: payer.pubkey(),
                  authority: authority.pubkey(),
                  mint_signer: mint_signer_pda,
                  mint: mint_pda,
                  compression_config: config_pda,
                  light_token_compressible_config: COMPRESSIBLE_CONFIG_V1,
                  rent_sponsor: RENT_SPONSOR,
                  light_token_program: LIGHT_TOKEN_PROGRAM_ID.into(),
                  light_token_cpi_authority: light_token_types::CPI_AUTHORITY_PDA.into(),
                  system_program: solana_sdk::system_program::ID,
              };

              let instruction_data = light_token_macro_create_mint::instruction::CreateMint {
                  params: CreateMintParams {
                      create_accounts_proof: proof_result.create_accounts_proof,
                      mint_signer_bump,
                  },
              };

              let instruction = Instruction {
                  program_id,
                  accounts: [
                      accounts.to_account_metas(None),
                      proof_result.remaining_accounts,
                  ]
                  .concat(),
                  data: instruction_data.data(),
              };

              rpc.create_and_send_transaction(&[instruction], &payer.pubkey(), &[&payer, &authority])
                  .await
                  .expect("CreateMint should succeed");

              let mint_account = rpc
                  .get_account(mint_pda)
                  .await
                  .unwrap()
                  .expect("Mint should exist on-chain");

              use light_token_interface::state::Mint;
              let mint: Mint = borsh::BorshDeserialize::deserialize(&mut &mint_account.data[..])
                  .expect("Failed to deserialize Mint");

              assert_eq!(mint.base.decimals, 9);
              assert_eq!(
                  mint.base.mint_authority,
                  Some(payer.pubkey().to_bytes().into()),
              );
          }

          #[tokio::test]
          async fn test_create_mint_with_metadata() {
              use light_token_macro_create_mint::CreateMintWithMetadataParams;

              let (mut rpc, payer, config_pda, program_id) = setup().await;

              let authority = Keypair::new();
              let (mint_signer_pda, mint_signer_bump) = Pubkey::find_program_address(
                  &[MINT_SIGNER_SEED, authority.pubkey().as_ref()],
                  &program_id,
              );
              let (mint_pda, _) = find_mint_address(&mint_signer_pda);

              let proof_result = get_create_accounts_proof(
                  &rpc,
                  &program_id,
                  vec![CreateAccountsProofInput::mint(mint_signer_pda)],
              )
              .await
              .unwrap();

              let accounts = light_token_macro_create_mint::accounts::CreateMintWithMetadata {
                  fee_payer: payer.pubkey(),
                  authority: authority.pubkey(),
                  mint_signer: mint_signer_pda,
                  mint: mint_pda,
                  compression_config: config_pda,
                  light_token_compressible_config: COMPRESSIBLE_CONFIG_V1,
                  rent_sponsor: RENT_SPONSOR,
                  light_token_program: LIGHT_TOKEN_PROGRAM_ID.into(),
                  light_token_cpi_authority: light_token_types::CPI_AUTHORITY_PDA.into(),
                  system_program: solana_sdk::system_program::ID,
              };

              let instruction_data = light_token_macro_create_mint::instruction::CreateMintWithMetadata {
                  params: CreateMintWithMetadataParams {
                      create_accounts_proof: proof_result.create_accounts_proof,
                      mint_signer_bump,
                      name: b"Test Token".to_vec(),
                      symbol: b"TST".to_vec(),
                      uri: b"https://example.com/metadata.json".to_vec(),
                  },
              };

              let instruction = Instruction {
                  program_id,
                  accounts: [
                      accounts.to_account_metas(None),
                      proof_result.remaining_accounts,
                  ]
                  .concat(),
                  data: instruction_data.data(),
              };

              rpc.create_and_send_transaction(&[instruction], &payer.pubkey(), &[&payer, &authority])
                  .await
                  .expect("CreateMintWithMetadata should succeed");

              let mint_account = rpc
                  .get_account(mint_pda)
                  .await
                  .unwrap()
                  .expect("Mint should exist on-chain");

              use light_token_interface::state::Mint;
              let mint: Mint = borsh::BorshDeserialize::deserialize(&mut &mint_account.data[..])
                  .expect("Failed to deserialize Mint");

              assert_eq!(mint.base.decimals, 9);
              assert_eq!(
                  mint.base.mint_authority,
                  Some(payer.pubkey().to_bytes().into()),
              );
          }
          ```
        </CodeGroup>
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

# Next Steps

<Card title="Learn how to mint tokens to Light Token accounts." icon="chevron-right" href="/light-token/cookbook/mint-to" />


# Create Light Token Account
Source: https://www.zkcompression.com/light-token/cookbook/create-token-account

Client and program guide to create Light Token accounts. Includes step-by-step implementation and full code examples.

***

1. Light token accounts are Solana accounts that hold token balances of light, SPL, or Token 2022 mints.
2. Light token accounts are on-chain accounts like SPL ATA’s, but the light token program sponsors the rent-exemption cost for you.

<Accordion title="Light Rent Config Explained">
  1) The Light Token Program pays the rent-exemption cost for the account.
  2) Transaction fee payers bump a virtual rent balance when writing to the account, which keeps the account "hot".
  3) "Cold" accounts virtual rent balance below threshold (eg 24h without write bump) get auto-compressed.
  4) The cold account's state is cryptographically preserved on the Solana ledger.
     Users can load a cold account into hot state in-flight when using the account
     again.
</Accordion>

<Tabs>
  <Tab title="Rust Client">
    `CreateTokenAccount` creates an on-chain token account to store token balances of light, SPL, or Token 2022 mints.

    Compare to SPL:

    <CodeCompare />

    <Steps>
      <Step>
        ### Prerequisites

        <Accordion title="Dependencies">
          ```toml Cargo.toml theme={null}
          [dependencies]
          light-token = "0.4.0"
          light-client = { version = "0.19.0", features = ["v2"] }
          solana-sdk = "2"
          borsh = "0.10.4"
          tokio = { version = "1", features = ["full"] }
          ```
        </Accordion>

        <Accordion title="Developer Environment">
          <Tabs>
            <Tab title="In-Memory (LightProgramTest)">
              Test with Lite-SVM (...)

              ```bash theme={null}
              # Initialize project
              cargo init my-light-project
              cd my-light-project

              # Run tests
              cargo test
              ```

              ```rust theme={null}
              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());
              }
              ```
            </Tab>

            <Tab title="Localnet (LightClient)">
              Connects to a local test validator.

              <Tabs>
                <Tab title="npm">
                  ```bash theme={null}
                  npm install -g @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>

                <Tab title="yarn">
                  ```bash theme={null}
                  yarn global add @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>

                <Tab title="pnpm">
                  ```bash theme={null}
                  pnpm add -g @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>
              </Tabs>

              ```bash theme={null}
              # Initialize project
              cargo init my-light-project
              cd my-light-project

              # Start local test validator (in separate terminal)
              light test-validator
              ```

              ```rust theme={null}
              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(())
              }
              ```
            </Tab>

            <Tab title="Devnet (LightClient)">
              Replace `<your-api-key>` with your actual API key. [Get your API key here](https://www.helius.dev/zk-compression).

              ```rust theme={null}
              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(())
              }
              ```
            </Tab>
          </Tabs>
        </Accordion>
      </Step>

      <Step>
        ### Create Token Account

        <Info>
          View the [source code](https://github.com/Lightprotocol/light-protocol/blob/main/sdk-libs/token-sdk/src/instruction/create_associated_token_account.rs) and [full example](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/instructions/create_token_account.rs) with shared test utilities.
        </Info>

        <Tabs>
          <Tab title="Instruction">
            ```rust theme={null}
            use light_client::rpc::Rpc;
            use light_token::instruction::CreateTokenAccount;
            use rust_client::{setup_spl_mint_context, SplMintContext};
            use solana_sdk::{signature::Keypair, signer::Signer};

            #[tokio::main]
            async fn main() -> Result<(), Box<dyn std::error::Error>> {
                // Setup creates mint
                // You can use Light, SPL, or Token-2022 mints to create a light token account.
                let SplMintContext {
                    mut rpc,
                    payer,
                    mint,
                } = setup_spl_mint_context().await;

                let account = Keypair::new();

                let create_token_account_instruction =
                    CreateTokenAccount::new(payer.pubkey(), account.pubkey(), mint, payer.pubkey())
                        .instruction()?;

                let sig = rpc
                    .create_and_send_transaction(&[create_token_account_instruction], &payer.pubkey(), &[&payer, &account])
                    .await?;

                let data = rpc.get_account(account.pubkey()).await?;
                println!(
                    "Account: {} exists: {} Tx: {sig}",
                    account.pubkey(),
                    data.is_some()
                );

                Ok(())
            }
            ```
          </Tab>
        </Tabs>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Program">
    <Tabs>
      <Tab title="CPI">
        Compare to SPL:

        <CodeCompare />

        <Note>
          Find [a full code example at the end](#full-code-example).
        </Note>

        <Steps>
          <Step>
            ### Build Account Infos and CPI the Light Token Program

            Use `invoke` for external signers or `invoke_signed` when the authority is a PDA.

            <Tabs>
              <Tab title="invoke (External signer)">
                ```rust theme={null}
                use light_token::instruction::CreateTokenAccountCpi;

                CreateTokenAccountCpi {
                    payer: payer.clone(),
                    account: account.clone(),
                    mint: mint.clone(),
                    owner,
                }
                .rent_free(
                    compressible_config.clone(),
                    rent_sponsor.clone(),
                    system_program.clone(),
                    token_program.key, // light token program
                )
                .invoke()
                ```

                <table>
                  <colgroup>
                    <col />

                    <col />
                  </colgroup>

                  <thead>
                    <tr>
                      <th />

                      <th />

                      <th />
                    </tr>
                  </thead>

                  <tbody>
                    <tr>
                      <td><strong>Payer</strong></td>
                      <td>signer, mutable</td>

                      <td>
                        * Pays initial rent per epoch, transaction fee and compression incentive.<br />
                        * Does NOT pay rent exemption (paid by the light token program, `rent_sponsor`).
                      </td>
                    </tr>

                    <tr>
                      <td><strong>light-token Account</strong></td>
                      <td>signer\*, mutable</td>

                      <td>
                        * The light-token account being created.<br />
                        * \*Must be signer for `invoke()`. For `invoke_signed()`, program signs via PDA seeds.
                      </td>
                    </tr>

                    <tr>
                      <td><strong>Mint</strong></td>
                      <td>-</td>
                      <td>The SPL or light-mint token mint.</td>
                    </tr>

                    <tr>
                      <td><strong>Owner</strong></td>
                      <td>Pubkey</td>
                      <td>The owner of the token account. Controls transfers and other operations.</td>
                    </tr>
                  </tbody>
                </table>
              </Tab>

              <Tab title="invoke_signed (PDA signer)">
                ```rust theme={null}
                use light_token::instruction::CreateTokenAccountCpi;

                let signer_seeds = authority_seeds!(authority_bump);

                CreateTokenAccountCpi {
                    payer: payer.clone(),
                    account: account.clone(),
                    mint: mint.clone(),
                    owner,
                }
                .rent_free(
                    compressible_config.clone(),
                    rent_sponsor.clone(),
                    system_program.clone(),
                    program_id,
                )
                .invoke_signed(signer_seeds)
                ```
              </Tab>
            </Tabs>
          </Step>
        </Steps>

        # Full Code Example

        <Info>
          View the [source code](https://github.com/Lightprotocol/light-protocol/blob/main/sdk-libs/token-sdk/src/instruction/create_associated_token_account.rs) and [full example](https://github.com/Lightprotocol/examples-light-token/tree/main/programs/anchor/basic-instructions/create-token-account) with shared test utilities.
        </Info>

        <CodeGroup>
          ```rust lib.rs theme={null}
          #![allow(unexpected_cfgs, deprecated)]

          use anchor_lang::prelude::*;
          use light_token::instruction::CreateTokenAccountCpi;

          declare_id!("zXK1CnWj4WFfFHCArxxr4sh3Qqx2p3oui8ahqpjArgS");

          #[program]
          pub mod light_token_anchor_create_token_account {
              use super::*;

              pub fn create_token_account(ctx: Context<CreateTokenAccountAccounts>, owner: Pubkey) -> Result<()> {
                  CreateTokenAccountCpi {
                      payer: ctx.accounts.payer.to_account_info(),
                      account: ctx.accounts.account.to_account_info(),
                      mint: ctx.accounts.mint.to_account_info(),
                      owner,
                  }
                  .rent_free(
                      ctx.accounts.compressible_config.to_account_info(),
                      ctx.accounts.rent_sponsor.to_account_info(),
                      ctx.accounts.system_program.to_account_info(),
                      &ctx.accounts.light_token_program.key(),
                  )
                  .invoke()?;
                  Ok(())
              }
          }

          #[derive(Accounts)]
          pub struct CreateTokenAccountAccounts<'info> {
              #[account(mut)]
              pub payer: Signer<'info>,
              /// CHECK: Validated by light-token CPI
              #[account(mut)]
              pub account: Signer<'info>,
              /// CHECK: Validated by light-token CPI
              pub mint: AccountInfo<'info>,
              /// CHECK: Validated by light-token CPI
              pub compressible_config: AccountInfo<'info>,
              /// CHECK: Validated by light-token CPI
              #[account(mut)]
              pub rent_sponsor: AccountInfo<'info>,
              pub system_program: Program<'info, System>,
              /// CHECK: Light token program for CPI
              pub light_token_program: AccountInfo<'info>,
          }
          ```

          ```rust test.rs theme={null}
          use anchor_lang::{InstructionData, ToAccountMetas};
          use light_client::indexer::AddressWithTree;
          use light_program_test::{Indexer, LightProgramTest, ProgramTestConfig, Rpc};
          use light_token_anchor_create_token_account::{accounts, instruction::CreateTokenAccount, ID};
          use light_token::instruction::{
              CreateMint, CreateMintParams, config_pda, derive_mint_compressed_address,
              find_mint_address, rent_sponsor_pda, LIGHT_TOKEN_PROGRAM_ID,
              DEFAULT_RENT_PAYMENT, DEFAULT_WRITE_TOP_UP,
          };
          use anchor_lang::system_program;
          use solana_sdk::{
              instruction::Instruction,
              signature::Keypair,
              signer::Signer,
          };

          #[tokio::test]
          async fn test_create_token_account() {
              let config = ProgramTestConfig::new_v2(
                  true,
                  Some(vec![("light_token_anchor_create_token_account", ID)]),
              );
              let mut rpc = LightProgramTest::new(config).await.unwrap();
              let payer = rpc.get_payer().insecure_clone();

              // Create a mint first
              let mint_seed = Keypair::new();
              let mint_authority = payer.pubkey();
              let decimals = 9u8;

              let address_tree = rpc.get_address_tree_v2();
              let output_queue = rpc.get_random_state_tree_info().unwrap().queue;

              let compression_address =
                  derive_mint_compressed_address(&mint_seed.pubkey(), &address_tree.tree);
              let (mint_pda, bump) = find_mint_address(&mint_seed.pubkey());

              let rpc_result = rpc
                  .get_validity_proof(
                      vec![],
                      vec![AddressWithTree {
                          address: compression_address,
                          tree: address_tree.tree,
                      }],
                      None,
                  )
                  .await
                  .unwrap()
                  .value;

              let params = CreateMintParams {
                  decimals,
                  address_merkle_tree_root_index: rpc_result.addresses[0].root_index,
                  mint_authority,
                  proof: rpc_result.proof.0.unwrap(),
                  compression_address,
                  mint: mint_pda,
                  bump,
                  freeze_authority: None,
                  extensions: None,
                  rent_payment: DEFAULT_RENT_PAYMENT,
                  write_top_up: DEFAULT_WRITE_TOP_UP,
              };

              let create_mint_ix = CreateMint::new(
                  params,
                  mint_seed.pubkey(),
                  payer.pubkey(),
                  address_tree.tree,
                  output_queue,
              )
              .instruction()
              .unwrap();

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

              // You can use light, spl, t22 mints to create a light token account.
              // Create a token account
              let token_account = Keypair::new();
              let owner = payer.pubkey();
              let compressible_config = config_pda();
              let rent_sponsor = rent_sponsor_pda();

              let ix = Instruction {
                  program_id: ID,
                  accounts: accounts::CreateTokenAccountAccounts {
                      payer: payer.pubkey(),
                      account: token_account.pubkey(),
                      mint: mint_pda,
                      compressible_config,
                      rent_sponsor,
                      system_program: system_program::ID,
                      light_token_program: LIGHT_TOKEN_PROGRAM_ID,
                  }
                  .to_account_metas(Some(true)),
                  data: CreateTokenAccount { owner }.data(),
              };

              let sig = rpc
                  .create_and_send_transaction(&[ix], &payer.pubkey(), &[&payer, &token_account])
                  .await
                  .unwrap();

              println!("Tx: {}", sig);
          }
          ```
        </CodeGroup>
      </Tab>

      <Tab title="Anchor Macros">
        Compare to SPL:

        <CodeCompare />

        <Note>
          Find [a full code example at the end](#full-code-example-1).
        </Note>

        <Steps>
          <Step>
            ### Dependencies

            ```toml theme={null}
            [dependencies]
            light-sdk = { version = "0.18.0", features = ["anchor", "v2", "cpi-context"] }
            light-sdk-macros = "0.18.0"
            light-compressible = "0.1.0"
            anchor-lang = "0.31"
            ```
          </Step>

          <Step>
            ### Program

            Add `#[light_program]` above `#[program]`:

            ```rust theme={null}
            use light_sdk_macros::light_program;

            #[light_program]
            #[program]
            pub mod light_token_macro_create_token_account {
                use super::*;

                pub fn create_token_account<'info>(
                    ctx: Context<'_, '_, '_, 'info, CreateTokenAccount<'info>>,
                    params: CreateTokenAccountParams,
                ) -> Result<()> {
                    Ok(())
                }
            }
            ```
          </Step>

          <Step>
            ### Accounts struct

            Derive `LightAccounts` on your `Accounts` struct and add `#[light_account(...)]` next to `#[account(...)]`.

            ```rust theme={null}
            /// CHECK: Validated by light-token CPI
            #[account(
                mut,
                seeds = [VAULT_SEED, mint.key().as_ref()],
                bump,
            )]
            #[light_account(init,
                token::authority = [VAULT_SEED, self.mint.key()],
                token::mint = mint,
                token::owner = vault_authority,
                token::bump = params.vault_bump
            )]
            pub vault: UncheckedAccount<'info>,
            ```
          </Step>
        </Steps>

        # Full code example

        <Info>
          View the [source code](https://github.com/Lightprotocol/light-protocol/blob/main/sdk-libs/token-sdk/src/instruction/create_associated_token_account.rs) and [full example](https://github.com/Lightprotocol/examples-light-token/tree/main/programs/anchor/basic-macros/create-token-account) with shared test utilities.
        </Info>

        <CodeGroup>
          ```rust lib.rs theme={null}
          #![allow(deprecated)]

          use anchor_lang::prelude::*;
          use light_compressible::CreateAccountsProof;
          use light_sdk::derive_light_cpi_signer;
          use light_sdk_macros::{light_program, LightAccounts};
          use light_sdk_types::CpiSigner;
          use light_token::instruction::{COMPRESSIBLE_CONFIG_V1, RENT_SPONSOR as LIGHT_TOKEN_RENT_SPONSOR};

          declare_id!("9p5BUDtVmRRJqp2sN73ZUZDbaYtYvEWuxzrHH3A2ni9y");

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

          pub const VAULT_AUTH_SEED: &[u8] = b"vault_auth";
          pub const VAULT_SEED: &[u8] = b"vault";

          #[derive(AnchorSerialize, AnchorDeserialize, Clone)]
          pub struct CreateTokenVaultParams {
              pub create_accounts_proof: CreateAccountsProof,
              pub vault_bump: u8,
          }

          #[derive(Accounts, LightAccounts)]
          #[instruction(params: CreateTokenVaultParams)]
          pub struct CreateTokenVault<'info> {
              #[account(mut)]
              pub fee_payer: Signer<'info>,

              /// CHECK: Token mint for the vault
              pub mint: AccountInfo<'info>,

              /// CHECK: Validated by seeds constraint
              #[account(
                  seeds = [VAULT_AUTH_SEED],
                  bump,
              )]
              pub vault_authority: UncheckedAccount<'info>,

              /// CHECK: Validated by seeds constraint and light_account macro
              #[account(
                  mut,
                  seeds = [VAULT_SEED, mint.key().as_ref()],
                  bump,
              )]
              #[light_account(
                  init,
                  token::authority = [VAULT_SEED, self.mint.key()],
                  token::mint = mint,
                  token::owner = vault_authority,
                  token::bump = params.vault_bump
              )]
              pub vault: UncheckedAccount<'info>,

              /// CHECK: Validated by address constraint
              #[account(address = COMPRESSIBLE_CONFIG_V1)]
              pub light_token_compressible_config: AccountInfo<'info>,

              /// CHECK: Validated by address constraint
              #[account(mut, address = LIGHT_TOKEN_RENT_SPONSOR)]
              pub light_token_rent_sponsor: AccountInfo<'info>,

              /// CHECK: Light token CPI authority
              pub light_token_cpi_authority: AccountInfo<'info>,

              /// CHECK: Light token program for CPI
              pub light_token_program: AccountInfo<'info>,

              pub system_program: Program<'info, System>,
          }

          #[light_program]
          #[program]
          pub mod light_token_macro_create_token_account {
              use super::*;

              #[allow(unused_variables)]
              pub fn create_token_vault<'info>(
                  ctx: Context<'_, '_, '_, 'info, CreateTokenVault<'info>>,
                  params: CreateTokenVaultParams,
              ) -> Result<()> {
                  Ok(())
              }
          }
          ```

          ```rust test.rs theme={null}
          use anchor_lang::{InstructionData, ToAccountMetas};
          use light_client::interface::get_create_accounts_proof;
          use light_program_test::{LightProgramTest, ProgramTestConfig, Rpc};
          use light_token::instruction::LIGHT_TOKEN_PROGRAM_ID;
          use solana_instruction::Instruction;
          use solana_pubkey::Pubkey;
          use solana_signer::Signer;
          use test_utils::create_mint;

          /// Test creating a token vault using the `#[light_account(init, token, ...)]` macro.
          ///
          /// This test verifies:
          /// 1. The macro-annotated program compiles correctly
          /// 2. A token vault can be created via the generated CPI
          /// 3. The vault has the correct owner and mint
          #[tokio::test]
          async fn test_create_token_vault() {
              use light_token::instruction::{COMPRESSIBLE_CONFIG_V1, RENT_SPONSOR};
              use light_token_macro_create_token_account::{
                  CreateTokenVaultParams, VAULT_AUTH_SEED, VAULT_SEED,
              };
              use light_token_types::CPI_AUTHORITY_PDA;

              let program_id = light_token_macro_create_token_account::ID;
              let config = ProgramTestConfig::new_v2(
                  true,
                  Some(vec![("light_token_macro_create_token_account", program_id)]),
              );

              let mut rpc = LightProgramTest::new(config).await.unwrap();
              let payer = rpc.get_payer().insecure_clone();

              let (mint, _mint_seed) = create_mint(&mut rpc, &payer, None).await;

              // Derive PDAs
              let (vault_authority, _auth_bump) =
                  Pubkey::find_program_address(&[VAULT_AUTH_SEED], &program_id);
              let (vault, vault_bump) =
                  Pubkey::find_program_address(&[VAULT_SEED, mint.as_ref()], &program_id);

              // Get proof for token-only instruction (empty inputs)
              let proof_result = get_create_accounts_proof(&rpc, &program_id, vec![])
                  .await
                  .unwrap();

              // Build instruction accounts
              let accounts = light_token_macro_create_token_account::accounts::CreateTokenVault {
                  fee_payer: payer.pubkey(),
                  mint,
                  vault_authority,
                  vault,
                  light_token_compressible_config: COMPRESSIBLE_CONFIG_V1,
                  light_token_rent_sponsor: RENT_SPONSOR,
                  light_token_cpi_authority: CPI_AUTHORITY_PDA.into(),
                  light_token_program: LIGHT_TOKEN_PROGRAM_ID,
                  system_program: solana_sdk::system_program::ID,
              };

              // Build instruction data
              let instruction_data = light_token_macro_create_token_account::instruction::CreateTokenVault {
                  params: CreateTokenVaultParams {
                      create_accounts_proof: proof_result.create_accounts_proof,
                      vault_bump,
                  },
              };

              let instruction = Instruction {
                  program_id,
                  accounts: [
                      accounts.to_account_metas(None),
                      proof_result.remaining_accounts,
                  ]
                  .concat(),
                  data: instruction_data.data(),
              };

              // Execute the instruction
              // Note: This may fail without InitializeRentFreeConfig setup.
              // The full test requires rent-free config initialization.
              let result = rpc
                  .create_and_send_transaction(&[instruction], &payer.pubkey(), &[&payer])
                  .await;

              // For now, we verify the instruction builds correctly.
              // Full execution requires additional setup (InitializeRentFreeConfig, etc.)
              println!("Transaction result: {:?}", result);
          }
          ```
        </CodeGroup>
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

# Next Steps

<Card title="Learn how to mint tokens to Light Token accounts" icon="chevron-right" href="/light-token/cookbook/mint-to" />


# Freeze and Thaw Light Token Accounts
Source: https://www.zkcompression.com/light-token/cookbook/freeze-thaw

Rust client guide to freeze and thaw Light Token accounts. Includes step-by-step implementation and full code examples.

***

1. Freeze prevents all transfers or token burns from a specific Light Token account.
2. Once frozen, the account cannot send tokens, receive tokens, or be closed until it is thawed.
3. Thaw re-enables transfers on a frozen Light Token account.
4. Only the freeze authority (set at mint creation) can freeze or thaw accounts.
5. If the freeze authority is revoked (set to null) on the mint account, tokens can never be frozen.

<Tabs>
  <Tab title="Rust Client">
    <Tabs>
      <Tab title="Freeze">
        <CodeCompare />
      </Tab>

      <Tab title="Thaw">
        <CodeCompare />
      </Tab>
    </Tabs>

    <Steps>
      <Step>
        ### Prerequisites

        <Accordion title="Dependencies">
          ```toml Cargo.toml theme={null}
          [dependencies]
          light-token = "0.4.0"
          light-client = { version = "0.19.0", features = ["v2"] }
          solana-sdk = "2"
          borsh = "0.10.4"
          tokio = { version = "1", features = ["full"] }
          ```
        </Accordion>

        <Accordion title="Developer Environment">
          <Tabs>
            <Tab title="In-Memory (LightProgramTest)">
              Test with Lite-SVM (...)

              ```bash theme={null}
              # Initialize project
              cargo init my-light-project
              cd my-light-project

              # Run tests
              cargo test
              ```

              ```rust theme={null}
              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());
              }
              ```
            </Tab>

            <Tab title="Localnet (LightClient)">
              Connects to a local test validator.

              <Tabs>
                <Tab title="npm">
                  ```bash theme={null}
                  npm install -g @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>

                <Tab title="yarn">
                  ```bash theme={null}
                  yarn global add @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>

                <Tab title="pnpm">
                  ```bash theme={null}
                  pnpm add -g @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>
              </Tabs>

              ```bash theme={null}
              # Initialize project
              cargo init my-light-project
              cd my-light-project

              # Start local test validator (in separate terminal)
              light test-validator
              ```

              ```rust theme={null}
              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(())
              }
              ```
            </Tab>

            <Tab title="Devnet (LightClient)">
              Replace `<your-api-key>` with your actual API key. [Get your API key here](https://www.helius.dev/zk-compression).

              ```rust theme={null}
              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(())
              }
              ```
            </Tab>
          </Tabs>
        </Accordion>
      </Step>

      <Step>
        ### Freeze or thaw Light Token accounts

        <Info>
          View the [source code](https://github.com/Lightprotocol/light-protocol/blob/main/sdk-libs/token-sdk/src/instruction/freeze.rs) and [full example](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/instructions/freeze.rs) with shared test utilities.
        </Info>

        <Tabs>
          <Tab title="Freeze">
            <Tabs>
              <Tab title="Instruction">
                ```rust theme={null}
                use borsh::BorshDeserialize;
                use light_client::rpc::Rpc;
                use light_token::instruction::Freeze;
                use rust_client::{setup, SetupContext};
                use solana_sdk::signer::Signer;

                #[tokio::main]
                async fn main() -> Result<(), Box<dyn std::error::Error>> {
                    // Setup creates mint, associated token account with tokens, and approves delegate
                    let SetupContext {
                        mut rpc,
                        payer,
                        mint,
                        associated_token_account,
                        ..
                    } = setup().await;

                    // freeze_authority must match what was set during mint creation.
                    let freeze_instruction = Freeze {
                        token_account: associated_token_account,
                        mint,
                        freeze_authority: payer.pubkey(),
                    }
                    .instruction()?;

                    let sig = rpc
                        .create_and_send_transaction(&[freeze_instruction], &payer.pubkey(), &[&payer])
                        .await?;

                    let data = rpc.get_account(associated_token_account).await?.ok_or("Account not found")?;
                    let token = light_token_interface::state::Token::deserialize(&mut &data.data[..])?;
                    println!("State: {:?} Tx: {sig}", token.state);

                    Ok(())
                }
                ```
              </Tab>
            </Tabs>
          </Tab>

          <Tab title="Thaw">
            <Tabs>
              <Tab title="Instruction">
                ```rust theme={null}
                use borsh::BorshDeserialize;
                use light_client::rpc::Rpc;
                use light_token::instruction::Thaw;
                use rust_client::{setup_frozen, SetupContext};
                use solana_sdk::signer::Signer;

                #[tokio::main]
                async fn main() -> Result<(), Box<dyn std::error::Error>> {
                    // Setup creates mint, associated token account with tokens, and freezes account
                    let SetupContext {
                        mut rpc,
                        payer,
                        mint,
                        associated_token_account,
                        ..
                    } = setup_frozen().await;

                    let thaw_instruction = Thaw {
                        token_account: associated_token_account,
                        mint,
                        freeze_authority: payer.pubkey(),
                    }
                    .instruction()?;

                    let sig = rpc
                        .create_and_send_transaction(&[thaw_instruction], &payer.pubkey(), &[&payer])
                        .await?;

                    let data = rpc.get_account(associated_token_account).await?.ok_or("Account not found")?;
                    let token = light_token_interface::state::Token::deserialize(&mut &data.data[..])?;
                    println!("State: {:?} Tx: {sig}", token.state);

                    Ok(())
                }
                ```
              </Tab>
            </Tabs>
          </Tab>
        </Tabs>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Program">
    <Note>
      Find [a full code example at the end](#full-code-example).
    </Note>

    <Tabs>
      <Tab title="Freeze">
        <Steps>
          <Step>
            ### Build Account Infos and CPI the Light Token Program

            Use `invoke` for external signers or `invoke_signed` when the authority is a PDA.

            <Tabs>
              <Tab title="invoke (External signer)">
                ```rust theme={null}
                use light_token::instruction::FreezeCpi;

                FreezeCpi {
                    token_account: ctx.accounts.token_account.to_account_info(),
                    mint: ctx.accounts.mint.to_account_info(),
                    freeze_authority: ctx.accounts.freeze_authority.to_account_info(),
                }
                .invoke()?;
                ```
              </Tab>

              <Tab title="invoke_signed (PDA authority)">
                ```rust theme={null}
                use light_token::instruction::FreezeCpi;

                let signer_seeds = authority_seeds!(bump);

                FreezeCpi {
                    token_account: token_account.clone(),
                    mint: mint.clone(),
                    freeze_authority: freeze_authority.clone(),
                }
                .invoke_signed(&[signer_seeds])
                ```
              </Tab>
            </Tabs>
          </Step>
        </Steps>
      </Tab>

      <Tab title="Thaw">
        <Steps>
          <Step>
            ### Build Account Infos and CPI the Light Token Program

            Use `invoke` for external signers or `invoke_signed` when the authority is a PDA.

            <Tabs>
              <Tab title="invoke (External signer)">
                ```rust theme={null}
                use light_token::instruction::ThawCpi;

                ThawCpi {
                    token_account: ctx.accounts.token_account.to_account_info(),
                    mint: ctx.accounts.mint.to_account_info(),
                    freeze_authority: ctx.accounts.freeze_authority.to_account_info(),
                }
                .invoke()?;
                ```
              </Tab>

              <Tab title="invoke_signed (PDA authority)">
                ```rust theme={null}
                use light_token::instruction::ThawCpi;

                let signer_seeds = authority_seeds!(bump);

                ThawCpi {
                    token_account: token_account.clone(),
                    mint: mint.clone(),
                    freeze_authority: freeze_authority.clone(),
                }
                .invoke_signed(&[signer_seeds])
                ```
              </Tab>
            </Tabs>
          </Step>
        </Steps>
      </Tab>
    </Tabs>

    # Full Code Example

    <Tabs>
      <Tab title="Freeze">
        <Info>
          View the [source code](https://github.com/Lightprotocol/light-protocol/blob/main/sdk-libs/token-sdk/src/instruction/freeze.rs) and [full example](https://github.com/Lightprotocol/examples-light-token/tree/main/programs/anchor/basic-instructions/freeze) with shared test utilities.
        </Info>

        <CodeGroup>
          ```rust lib.rs theme={null}
          #![allow(unexpected_cfgs, deprecated)]

          use anchor_lang::prelude::*;
          use light_token::instruction::FreezeCpi;

          declare_id!("JBMzMJX4sqCQfNVbosP2oqP1KZ5ZDWiwYTrupk687qXZ");

          #[program]
          pub mod light_token_anchor_freeze {
              use super::*;

              pub fn freeze(ctx: Context<FreezeAccounts>) -> Result<()> {
                  FreezeCpi {
                      token_account: ctx.accounts.token_account.to_account_info(),
                      mint: ctx.accounts.mint.to_account_info(),
                      freeze_authority: ctx.accounts.freeze_authority.to_account_info(),
                  }
                  .invoke()?;
                  Ok(())
              }
          }

          #[derive(Accounts)]
          pub struct FreezeAccounts<'info> {
              /// CHECK: Light token program for CPI
              pub light_token_program: AccountInfo<'info>,
              /// CHECK: Validated by light-token CPI
              #[account(mut)]
              pub token_account: AccountInfo<'info>,
              /// CHECK: Validated by light-token CPI
              pub mint: AccountInfo<'info>,
              pub freeze_authority: Signer<'info>,
          }
          ```

          ```rust test.rs theme={null}
          use anchor_lang::{InstructionData, ToAccountMetas};
          use light_program_test::Rpc;
          use light_token::instruction::LIGHT_TOKEN_PROGRAM_ID;
          use light_token_anchor_freeze::{accounts, instruction::Freeze, ID};
          use solana_sdk::{instruction::Instruction, signer::Signer};
          use test_utils::{mint_tokens, setup_test_env_with_freeze};

          #[tokio::test]
          async fn test_freeze() {
              let mut env = setup_test_env_with_freeze("light_token_anchor_freeze", ID).await;

              // Mint tokens first
              mint_tokens(&mut env.rpc, &env.payer, env.mint_pda, env.associated_token_account, 1_000_000).await;

              // Call the anchor program to freeze account
              let ix = Instruction {
                  program_id: ID,
                  accounts: accounts::FreezeAccounts {
                      light_token_program: LIGHT_TOKEN_PROGRAM_ID,
                      token_account: env.associated_token_account,
                      mint: env.mint_pda,
                      freeze_authority: env.freeze_authority,
                  }
                  .to_account_metas(Some(true)),
                  data: Freeze {}.data(),
              };

              let sig = env
                  .rpc
                  .create_and_send_transaction(&[ix], &env.payer.pubkey(), &[&env.payer])
                  .await
                  .unwrap();

              println!("Tx: {}", sig);
          }
          ```
        </CodeGroup>
      </Tab>

      <Tab title="Thaw">
        <Info>
          View the [source code](https://github.com/Lightprotocol/light-protocol/blob/main/sdk-libs/token-sdk/src/instruction/thaw.rs) and [full example](https://github.com/Lightprotocol/examples-light-token/tree/main/programs/anchor/basic-instructions/thaw) with shared test utilities.
        </Info>

        <CodeGroup>
          ```rust lib.rs theme={null}
          #![allow(unexpected_cfgs, deprecated)]

          use anchor_lang::prelude::*;
          use light_token::instruction::ThawCpi;

          declare_id!("7j94EF5hSkDLf7R26bjrd8Qc6s3oLAQpcKiF3re8JYw9");

          #[program]
          pub mod light_token_anchor_thaw {
              use super::*;

              pub fn thaw(ctx: Context<ThawAccounts>) -> Result<()> {
                  ThawCpi {
                      token_account: ctx.accounts.token_account.to_account_info(),
                      mint: ctx.accounts.mint.to_account_info(),
                      freeze_authority: ctx.accounts.freeze_authority.to_account_info(),
                  }
                  .invoke()?;
                  Ok(())
              }
          }

          #[derive(Accounts)]
          pub struct ThawAccounts<'info> {
              /// CHECK: Light token program for CPI
              pub light_token_program: AccountInfo<'info>,
              /// CHECK: Validated by light-token CPI
              #[account(mut)]
              pub token_account: AccountInfo<'info>,
              /// CHECK: Validated by light-token CPI
              pub mint: AccountInfo<'info>,
              pub freeze_authority: Signer<'info>,
          }
          ```

          ```rust test.rs theme={null}
          use anchor_lang::{InstructionData, ToAccountMetas};
          use light_program_test::Rpc;
          use light_token::instruction::{Freeze, LIGHT_TOKEN_PROGRAM_ID};
          use light_token_anchor_thaw::{accounts, instruction::Thaw, ID};
          use solana_sdk::{instruction::Instruction, signer::Signer};
          use test_utils::{mint_tokens, setup_test_env_with_freeze};

          #[tokio::test]
          async fn test_thaw() {
              let mut env = setup_test_env_with_freeze("light_token_anchor_thaw", ID).await;

              // Mint tokens first
              mint_tokens(&mut env.rpc, &env.payer, env.mint_pda, env.associated_token_account, 1_000_000).await;

              // Freeze account first using SDK
              let freeze_ix = Freeze {
                  token_account: env.associated_token_account,
                  mint: env.mint_pda,
                  freeze_authority: env.freeze_authority,
              }
              .instruction()
              .unwrap();

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

              // Call the anchor program to thaw account
              let ix = Instruction {
                  program_id: ID,
                  accounts: accounts::ThawAccounts {
                      light_token_program: LIGHT_TOKEN_PROGRAM_ID,
                      token_account: env.associated_token_account,
                      mint: env.mint_pda,
                      freeze_authority: env.freeze_authority,
                  }
                  .to_account_metas(Some(true)),
                  data: Thaw {}.data(),
              };

              let sig = env
                  .rpc
                  .create_and_send_transaction(&[ix], &env.payer.pubkey(), &[&env.payer])
                  .await
                  .unwrap();

              println!("Tx: {}", sig);
          }
          ```
        </CodeGroup>
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

# Next Steps

<Card title="Learn to approve and revoke delegates" icon="chevron-right" href="/light-token/cookbook/approve-revoke" />


# Load Token Balances to Light Associated Token Account
Source: https://www.zkcompression.com/light-token/cookbook/load-ata

Unify token balances from compressed tokens (cold Light Tokens), SPL, and Token 2022 to one light ATA.

***

1. `loadAta` unifies tokens from multiple sources to a single ATA:
   * Compressed tokens (cold Light Tokens) -> Decompresses -> light ATA
   * SPL balance (if wrap=true) -> Wraps -> light ATA
   * T22 balance (if wrap=true) -> Wraps -> light ATA

2. Returns `null` if there's nothing to load (idempotent)

3. Creates the ATA if it doesn't exist

<Info>
  Find the source code [here](https://github.com/Lightprotocol/light-protocol/blob/0c4e2417b2df2d564721b89e18d1aad3665120e7/js/compressed-token/src/v3/actions/load-ata.ts).
</Info>

<Steps>
  <Step>
    ### Unify Tokens to Light-ATA Balance

    <Accordion title="Installation">
      <Tabs>
        <Tab title="npm">
          Install packages in your working directory:

          ```bash theme={null}
          npm install @lightprotocol/stateless.js@beta \
                      @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          npm install -g @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>

        <Tab title="yarn">
          Install packages in your working directory:

          ```bash theme={null}
          yarn add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          yarn global add @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>

        <Tab title="pnpm">
          Install packages in your working directory:

          ```bash theme={null}
          pnpm add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          pnpm add -g @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>
      </Tabs>
    </Accordion>

    <Tabs>
      <Tab title="Localnet">
        ```bash theme={null}
        # start local test-validator in a separate terminal
        light test-validator
        ```

        <Note>
          In the code examples, use `createRpc()` without arguments for localnet.
        </Note>
      </Tab>

      <Tab title="Devnet">
        Get an API key from [Helius](https://helius.dev) and add to `.env`:

        ```bash title=".env" theme={null}
        API_KEY=<your-helius-api-key>
        ```

        <Note>
          In the code examples, use `createRpc(RPC_URL)` with the devnet URL.
        </Note>
      </Tab>
    </Tabs>

    <Tabs>
      <Tab title="Action">
        ```typescript theme={null}
        import "dotenv/config";
        import { Keypair } from "@solana/web3.js";
        import { createRpc, bn } from "@lightprotocol/stateless.js";
        import {
            createMint,
            mintTo,
            loadAta,
            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 () {
            // Setup: Get compressed tokens (cold storage)
            const { mint } = await createMint(rpc, payer, payer.publicKey, 9);
            await mintTo(rpc, payer, mint, payer.publicKey, payer, bn(1000));

            // Load compressed tokens to hot balance
            const lightTokenAta = getAssociatedTokenAddressInterface(mint, payer.publicKey);
            const tx = await loadAta(rpc, lightTokenAta, payer, mint, payer);

            console.log("Tx:", tx);
        })();
        ```
      </Tab>

      <Tab title="Instruction">
        ```typescript theme={null}
        import "dotenv/config";
        import { Keypair } from "@solana/web3.js";
        import {
            createRpc,
            buildAndSignTx,
            sendAndConfirmTx,
        } from "@lightprotocol/stateless.js";
        import {
            createMintInterface,
            mintToCompressed,
            createLoadAtaInstructions,
            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 () {
            // Inactive Light Tokens are cryptographically preserved on the Solana ledger
            // as compressed tokens (cold storage)
            // Setup: Get compressed tokens in light-token associated token account
            const { mint } = await createMintInterface(rpc, payer, payer, null, 9);
            await mintToCompressed(rpc, payer, mint, payer, [{ recipient: payer.publicKey, amount: 1000n }]);

            const lightTokenAta = getAssociatedTokenAddressInterface(
                mint,
                payer.publicKey,
            );

            // Load compressed tokens to light associated token account (hot balance)
            const ixs = await createLoadAtaInstructions(
                rpc,
                lightTokenAta,
                payer.publicKey,
                mint,
                payer.publicKey,
            );

            if (ixs.length === 0) return console.log("Nothing to load");

            const blockhash = await rpc.getLatestBlockhash();
            const tx = buildAndSignTx(ixs, payer, blockhash.blockhash);
            const signature = await sendAndConfirmTx(rpc, tx);
            console.log("Tx:", signature);
        })();
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>


# Mint to Light Token Accounts
Source: https://www.zkcompression.com/light-token/cookbook/mint-to

Client and program guide to mint tokens to a account. Includes step-by-step implementation and full code examples.

***

1. Mint To creates new tokens of a mint and deposits them to a specified token account.
2. Before we can mint any tokens, we need an initialized mint account (SPL, Token 2022 or Light) for which we hold the mint authority.

<Tabs>
  <Tab title="TypeScript Client">
    `mintToInterface` mints tokens to token accounts in a single call.

    The function auto-detects the token program (SPL, Token 2022, or Light) from the mint address.

    Compare to SPL:

    <CodeCompare />

    <Info>
      Find the source code
      [here](https://github.com/Lightprotocol/light-protocol/blob/0c4e2417b2df2d564721b89e18d1aad3665120e7/js/compressed-token/src/v3/actions/mint-to-interface.ts).
    </Info>

    <Steps>
      <Step>
        ### Mint Tokens to Light Token Account

        <Accordion title="Installation">
          <Tabs>
            <Tab title="npm">
              Install packages in your working directory:

              ```bash theme={null}
              npm install @lightprotocol/stateless.js@beta \
                          @lightprotocol/compressed-token@beta
              ```

              Install the CLI globally:

              ```bash theme={null}
              npm install -g @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>

            <Tab title="yarn">
              Install packages in your working directory:

              ```bash theme={null}
              yarn add @lightprotocol/stateless.js@beta \
                       @lightprotocol/compressed-token@beta
              ```

              Install the CLI globally:

              ```bash theme={null}
              yarn global add @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>

            <Tab title="pnpm">
              Install packages in your working directory:

              ```bash theme={null}
              pnpm add @lightprotocol/stateless.js@beta \
                       @lightprotocol/compressed-token@beta
              ```

              Install the CLI globally:

              ```bash theme={null}
              pnpm add -g @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>
          </Tabs>
        </Accordion>

        <Tabs>
          <Tab title="Localnet">
            ```bash theme={null}
            # start local test-validator in a separate terminal
            light test-validator
            ```

            <Note>
              In the code examples, use `createRpc()` without arguments for localnet.
            </Note>
          </Tab>

          <Tab title="Devnet">
            Get an API key from [Helius](https://helius.dev) and add to `.env`:

            ```bash title=".env" theme={null}
            API_KEY=<your-helius-api-key>
            ```

            <Note>
              In the code examples, use `createRpc(RPC_URL)` with the devnet URL.
            </Note>
          </Tab>
        </Tabs>

        <Tabs>
          <Tab title="Action">
            ```typescript theme={null}
            import "dotenv/config";
            import { Keypair } from "@solana/web3.js";
            import { createRpc } from "@lightprotocol/stateless.js";
            import {
                createMintInterface,
                createAtaInterface,
                mintToInterface,
                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 recipient = Keypair.generate();
                await createAtaInterface(rpc, payer, mint, recipient.publicKey);

                const destination = getAssociatedTokenAddressInterface(mint, recipient.publicKey);
                const tx = await mintToInterface(rpc, payer, mint, destination, payer, 1_000_000_000);

                console.log("Tx:", tx);
            })();
            ```
          </Tab>

          <Tab title="Instruction">
            ```typescript theme={null}
            import "dotenv/config";
            import {
                Keypair,
                ComputeBudgetProgram,
                Transaction,
                sendAndConfirmTransaction,
            } from "@solana/web3.js";
            import { createRpc, bn, DerivationMode } from "@lightprotocol/stateless.js";
            import {
                createMintInterface,
                createAtaInterface,
                createMintToInterfaceInstruction,
                getMintInterface,
                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 recipient = Keypair.generate();
                await createAtaInterface(rpc, payer, mint, recipient.publicKey);
                const destination = getAssociatedTokenAddressInterface(
                    mint,
                    recipient.publicKey,
                );

                const mintInterface = await getMintInterface(rpc, mint);

                let validityProof;
                if (mintInterface.merkleContext) {
                    validityProof = await rpc.getValidityProofV2(
                        [
                            {
                                hash: bn(mintInterface.merkleContext.hash),
                                leafIndex: mintInterface.merkleContext.leafIndex,
                                treeInfo: mintInterface.merkleContext.treeInfo,
                                proveByIndex: mintInterface.merkleContext.proveByIndex,
                            },
                        ],
                        [],
                        DerivationMode.compressible,
                    );
                }

                const ix = createMintToInterfaceInstruction(
                    mintInterface,
                    destination,
                    payer.publicKey,
                    payer.publicKey,
                    1_000_000_000,
                    validityProof,
                );

                const tx = new Transaction().add(
                    ComputeBudgetProgram.setComputeUnitLimit({ units: 500_000 }),
                    ix,
                );
                const signature = await sendAndConfirmTransaction(rpc, tx, [payer]);

                console.log("Tx:", signature);
            })();
            ```
          </Tab>
        </Tabs>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Rust Client">
    Use `MintTo` to mint tokens to a Light Token account.

    Compare to SPL:

    <CodeCompare />

    <Steps>
      <Step>
        ### Prerequisites

        <Accordion title="Dependencies">
          ```toml Cargo.toml theme={null}
          [dependencies]
          light-token = "0.4.0"
          light-client = { version = "0.19.0", features = ["v2"] }
          solana-sdk = "2"
          borsh = "0.10.4"
          tokio = { version = "1", features = ["full"] }
          ```
        </Accordion>

        <Accordion title="Developer Environment">
          <Tabs>
            <Tab title="In-Memory (LightProgramTest)">
              Test with Lite-SVM (...)

              ```bash theme={null}
              # Initialize project
              cargo init my-light-project
              cd my-light-project

              # Run tests
              cargo test
              ```

              ```rust theme={null}
              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());
              }
              ```
            </Tab>

            <Tab title="Localnet (LightClient)">
              Connects to a local test validator.

              <Tabs>
                <Tab title="npm">
                  ```bash theme={null}
                  npm install -g @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>

                <Tab title="yarn">
                  ```bash theme={null}
                  yarn global add @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>

                <Tab title="pnpm">
                  ```bash theme={null}
                  pnpm add -g @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>
              </Tabs>

              ```bash theme={null}
              # Initialize project
              cargo init my-light-project
              cd my-light-project

              # Start local test validator (in separate terminal)
              light test-validator
              ```

              ```rust theme={null}
              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(())
              }
              ```
            </Tab>

            <Tab title="Devnet (LightClient)">
              Replace `<your-api-key>` with your actual API key. [Get your API key here](https://www.helius.dev/zk-compression).

              ```rust theme={null}
              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(())
              }
              ```
            </Tab>
          </Tabs>
        </Accordion>
      </Step>

      <Step>
        ### Mint to Light Token Accounts

        <Info>
          View the [source code](https://github.com/Lightprotocol/light-protocol/blob/main/sdk-libs/token-sdk/src/instruction/mint_to.rs) and [full example](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/instructions/mint_to.rs) with shared test utilities.
        </Info>

        <Tabs>
          <Tab title="Action">
            ```rust theme={null}
            use borsh::BorshDeserialize;
            use light_client::rpc::Rpc;
            use light_token_client::actions::{CreateAta, CreateMint, MintTo};
            use rust_client::setup_rpc_and_payer;
            use solana_sdk::signer::Signer;

            #[tokio::main]
            async fn main() -> Result<(), Box<dyn std::error::Error>> {
                let (mut rpc, payer) = setup_rpc_and_payer().await;

                // Create mint (payer is also mint authority)
                let (_signature, mint) = CreateMint {
                    decimals: 9,
                    freeze_authority: None,
                    token_metadata: None,
                    seed: None,
                }
                .execute(&mut rpc, &payer, &payer)
                .await?;

                // Create associated token account
                let (_signature, associated_token_account) = CreateAta {
                    mint,
                    owner: payer.pubkey(),
                    idempotent: true,
                }
                .execute(&mut rpc, &payer)
                .await?;

                // Mint tokens (payer is mint authority)
                let sig = MintTo {
                    mint,
                    destination: associated_token_account,
                    amount: 1_000_000,
                }
                .execute(&mut rpc, &payer, &payer)
                .await?;

                let data = rpc.get_account(associated_token_account).await?.ok_or("Account not found")?;
                let token = light_token_interface::state::Token::deserialize(&mut &data.data[..])?;
                println!("Balance: {} Tx: {sig}", token.amount);

                Ok(())
            }
            ```
          </Tab>

          <Tab title="Instruction">
            ```rust theme={null}
            use borsh::BorshDeserialize;
            use light_client::rpc::Rpc;
            use light_token::instruction::MintTo;
            use rust_client::{setup_empty_associated_token_account, SetupContext};
            use solana_sdk::signer::Signer;

            #[tokio::main]
            async fn main() -> Result<(), Box<dyn std::error::Error>> {
                // Setup creates mint and empty associated token account
                let SetupContext {
                    mut rpc,
                    payer,
                    mint,
                    associated_token_account,
                    ..
                } = setup_empty_associated_token_account().await;

                let mint_amount = 1_000_000_000u64;

                let mint_to_instruction = MintTo {
                    mint,
                    destination: associated_token_account,
                    amount: mint_amount,
                    authority: payer.pubkey(),
                    max_top_up: None, 
                    fee_payer: None,
                }
                .instruction()?;

                let sig = rpc
                    .create_and_send_transaction(&[mint_to_instruction], &payer.pubkey(), &[&payer])
                    .await?;

                let data = rpc.get_account(associated_token_account).await?.ok_or("Account not found")?;
                let token = light_token_interface::state::Token::deserialize(&mut &data.data[..])?;
                println!("Balance: {} Tx: {sig}", token.amount);

                Ok(())
            }
            ```
          </Tab>
        </Tabs>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Program">
    <Note>Find [a full code example at the end](#full-code-example).</Note>

    <Steps>
      <Step>
        ### Build Account Infos and CPI the Light Token Program

        Use `invoke` for external signers or `invoke_signed` when the authority is a PDA.

        <Tabs>
          <Tab title="invoke (External signer)">
            ```rust theme={null}
            use light_token::instruction::MintToCpi;

            MintToCpi {
                mint: mint.clone(),
                destination: destination.clone(),
                amount,
                authority: authority.clone(),
                system_program: system_program.clone(),
                fee_payer: None,
                max_top_up: None,
            }
            .invoke()
            ```
          </Tab>

          <Tab title="invoke_signed (PDA authority)">
            ```rust theme={null}
            use light_token::instruction::MintToCpi;

            let signer_seeds: &[&[u8]] = &[MINT_AUTHORITY_SEED, &[bump]];

            MintToCpi {
                mint: mint.clone(),
                destination: destination.clone(),
                amount,
                authority: authority.clone(),
                system_program: system_program.clone(),
                fee_payer: None,
                max_top_up: None,
            }
            .invoke_signed(&[signer_seeds])
            ```
          </Tab>
        </Tabs>

        <Info>
          `fee_payer` and `max_top_up` are optional fields to customize rent top-ups.
          Set to `None` to use defaults.
        </Info>
      </Step>
    </Steps>

    # Full Code Example

    <Info>
      View the [source code](https://github.com/Lightprotocol/light-protocol/blob/main/sdk-libs/token-sdk/src/instruction/mint_to.rs) and [full example](https://github.com/Lightprotocol/examples-light-token/tree/main/programs/anchor/basic-instructions/mint-to) with shared test utilities.
    </Info>

    <CodeGroup>
      ```rust lib.rs theme={null}
      #![allow(unexpected_cfgs, deprecated)]

      use anchor_lang::prelude::*;
      use light_token::instruction::MintToCpi;

      declare_id!("8bXEVmHLtAVqDLJp1dYWAZ61WQmqQKoTQ8LpPbRoUDCp");

      #[program]
      pub mod light_token_anchor_mint_to {
          use super::*;

          pub fn mint_to(ctx: Context<MintToAccounts>, amount: u64) -> Result<()> {
              MintToCpi {
                  mint: ctx.accounts.mint.to_account_info(),
                  destination: ctx.accounts.destination.to_account_info(),
                  amount,
                  authority: ctx.accounts.authority.to_account_info(),
                  system_program: ctx.accounts.system_program.to_account_info(),
                  max_top_up: None,
                  fee_payer: None,
              }
              .invoke()?;
              Ok(())
          }
      }

      #[derive(Accounts)]
      pub struct MintToAccounts<'info> {
          /// CHECK: Light token program for CPI
          pub light_token_program: AccountInfo<'info>,
          /// CHECK: Validated by light-token CPI
          #[account(mut)]
          pub mint: AccountInfo<'info>,
          /// CHECK: Validated by light-token CPI
          #[account(mut)]
          pub destination: AccountInfo<'info>,
          pub authority: Signer<'info>,
          pub system_program: Program<'info, System>,
      }
      ```

      ```rust test.rs theme={null}
      use anchor_lang::{InstructionData, ToAccountMetas};
      use light_program_test::Rpc;
      use light_token::instruction::LIGHT_TOKEN_PROGRAM_ID;
      use light_token_anchor_mint_to::{accounts, instruction::MintTo, ID};
      use anchor_lang::system_program;
      use solana_sdk::{instruction::Instruction, signer::Signer};
      use test_utils::setup_test_env;

      #[tokio::test(flavor = "multi_thread")]
      async fn test_mint_to() {
          let mut env = setup_test_env("light_token_anchor_mint_to", ID).await;

          // No mint_tokens call - the test IS minting tokens via CPI.
          let amount = 1_000_000u64;
          let ix = Instruction {
              program_id: ID,
              accounts: accounts::MintToAccounts {
                  light_token_program: LIGHT_TOKEN_PROGRAM_ID,
                  mint: env.mint_pda,
                  destination: env.associated_token_account,
                  authority: env.payer.pubkey(),
                  system_program: system_program::ID,
              }
              .to_account_metas(Some(true)),
              data: MintTo { amount }.data(),
          };

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

          // Verify the account exists and has data
          let associated_token_account_data = env.rpc.get_account(env.associated_token_account).await.unwrap().unwrap();
          assert!(!associated_token_account_data.data.is_empty(), "Associated token account should have data");
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>

# Next Steps

<Card title="Learn to use the transfer interface for Light Token <> SPL token transfers" icon="chevron-right" href="/light-token/cookbook/transfer-interface" />


# Light Token Cookbook
Source: https://www.zkcompression.com/light-token/cookbook/overview

Client and program guides using the light-token-sdk.

## Recipes

<table>
  <colgroup>
    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <a href="/light-token/cookbook/create-mint">Create Mint</a>
      </td>

      <td>Create light-mints with token metadata</td>
    </tr>

    <tr>
      <td>
        <a href="/light-token/cookbook/create-ata">Create ATA</a>
      </td>

      <td>Create associated light-token accounts</td>
    </tr>

    <tr>
      <td>
        <a href="/light-token/cookbook/create-token-account">Create Token Account</a>
      </td>

      <td>Create light-token accounts</td>
    </tr>

    <tr>
      <td>
        <a href="/light-token/cookbook/mint-to">Mint To</a>
      </td>

      <td>Mint tokens to light-token accounts</td>
    </tr>

    <tr>
      <td>
        <a href="/light-token/cookbook/close-token-account">Close Token Account</a>
      </td>

      <td>Close token account to reclaim remaining lamports</td>
    </tr>

    <tr>
      <td>
        <a href="/light-token/cookbook/transfer-interface">Transfer</a>
      </td>

      <td>Transfer between Light Token, SPL and Token 2022 accounts</td>
    </tr>

    <tr>
      <td>
        <a href="/light-token/cookbook/transfer-checked">Transfer Checked</a>
      </td>

      <td>Transfer between Light Token accounts with decimals verification</td>
    </tr>

    <tr>
      <td>
        <a href="/light-token/cookbook/burn">Burn</a>
      </td>

      <td>Burn tokens from light-token accounts</td>
    </tr>

    <tr>
      <td>
        <a href="/light-token/cookbook/freeze-thaw">Freeze & Thaw</a>
      </td>

      <td>Freeze and thaw light-token accounts</td>
    </tr>

    <tr>
      <td>
        <a href="/light-token/cookbook/approve-revoke">Approve & Revoke</a>
      </td>

      <td>Delegate and revoke token authority</td>
    </tr>

    <tr>
      <td>
        <a href="/light-token/cookbook/wrap-unwrap">Wrap & Unwrap</a>
      </td>

      <td>Convert between SPL/Token 2022 and light-token</td>
    </tr>

    <tr>
      <td>
        <a href="/light-token/cookbook/load-ata">Load ATA</a>
      </td>

      <td>Load cold light-token accounts to hot balance for transfers in one instruction</td>
    </tr>
  </tbody>
</table>

## Setup

<Tabs>
  <Tab title="TypeScript Client">
    <Accordion title="Dependencies">
      <Tabs>
        <Tab title="npm">
          ```bash theme={null}
          npm install @lightprotocol/stateless.js@beta \
                      @lightprotocol/compressed-token@beta
          ```
        </Tab>

        <Tab title="yarn">
          ```bash theme={null}
          yarn add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```
        </Tab>

        <Tab title="pnpm">
          ```bash theme={null}
          pnpm add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```
        </Tab>
      </Tabs>
    </Accordion>

    <Accordion title="Developer Environment">
      <Tabs>
        <Tab title="Localnet">
          By default, all guides use Localnet.

          <Tabs>
            <Tab title="npm">
              ```bash theme={null}
              npm install -g @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>

            <Tab title="yarn">
              ```bash theme={null}
              yarn global add @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>

            <Tab title="pnpm">
              ```bash theme={null}
              pnpm add -g @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>
          </Tabs>

          ```bash theme={null}
          # Start a local test validator
          light test-validator

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

          ```typescript theme={null}
          // 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();
          ```
        </Tab>

        <Tab title="Devnet">
          Replace `<your-api-key>` with your actual API key. [Get your API key here](https://www.helius.dev/zk-compression), if you don't have one yet.

          ```typescript theme={null}
          import { createRpc } from "@lightprotocol/stateless.js";

          const RPC_ENDPOINT = "https://devnet.helius-rpc.com?api-key=<your_api_key>";
          const connection = createRpc(RPC_ENDPOINT);

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

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

          main();
          ```
        </Tab>
      </Tabs>
    </Accordion>
  </Tab>

  <Tab title="Rust Client">
    <Accordion title="Dependencies">
      ```toml Cargo.toml theme={null}
      [dependencies]
      light-token = "0.4.0"
      light-client = { version = "0.19.0", features = ["v2"] }
      solana-sdk = "2"
      borsh = "0.10.4"
      tokio = { version = "1", features = ["full"] }
      ```
    </Accordion>

    <Accordion title="Developer Environment">
      <Tabs>
        <Tab title="In-Memory (LightProgramTest)">
          Test with Lite-SVM (...)

          ```bash theme={null}
          # Initialize project
          cargo init my-light-project
          cd my-light-project

          # Run tests
          cargo test
          ```

          ```rust theme={null}
          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());
          }
          ```
        </Tab>

        <Tab title="Localnet (LightClient)">
          Connects to a local test validator.

          <Tabs>
            <Tab title="npm">
              ```bash theme={null}
              npm install -g @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>

            <Tab title="yarn">
              ```bash theme={null}
              yarn global add @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>

            <Tab title="pnpm">
              ```bash theme={null}
              pnpm add -g @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>
          </Tabs>

          ```bash theme={null}
          # Initialize project
          cargo init my-light-project
          cd my-light-project

          # Start local test validator (in separate terminal)
          light test-validator
          ```

          ```rust theme={null}
          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(())
          }
          ```
        </Tab>

        <Tab title="Devnet (LightClient)">
          Replace `<your-api-key>` with your actual API key. [Get your API key here](https://www.helius.dev/zk-compression).

          ```rust theme={null}
          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(())
          }
          ```
        </Tab>
      </Tabs>
    </Accordion>
  </Tab>

  <Tab title="Program">
    <Accordion title="Dependencies">
      <CodeGroup>
        ```toml Anchor Cargo.toml theme={null}
        [dependencies]
        light-token = "0.4.0"
        light-token-types = "0.4.0"
        anchor-lang = "0.31.1"

        [dev-dependencies]
        light-program-test = { version = "0.19.0", features = ["v2"] }
        light-client = { version = "0.19.0", features = ["v2"] }
        solana-sdk = "2"
        tokio = { version = "1", features = ["full"] }
        ```

        ```toml Native Rust Cargo.toml theme={null}
        [dependencies]
        light-token = "0.4.0"
        light-compressible = "0.4.0"
        light-token-interface = "0.3.0"
        light-compressed-account = "0.9.0"
        borsh = "0.10.4"
        solana-program = "2.2"

        [dev-dependencies]
        light-program-test = { version = "0.19.0", features = ["v2"] }
        light-client = { version = "0.19.0", features = ["v2"] }
        solana-sdk = "2"
        tokio = { version = "1", features = ["full"] }
        ```
      </CodeGroup>
    </Accordion>

    <Accordion title="Developer Environment">
      <Tabs>
        <Tab title="In-Memory (LightProgramTest)">
          Test with LiteSVM:

          ```bash theme={null}
          # Initialize project
          cargo init my-light-project
          cd my-light-project

          # Build
          cargo build-sbf

          # Run tests
          cargo test-sbf
          ```

          ```rust theme={null}
          use light_program_test::{LightProgramTest, ProgramTestConfig};
          use solana_sdk::signer::Signer;

          #[tokio::test]
          async fn test_example() {
              let mut rpc = LightProgramTest::new(ProgramTestConfig::default())
                  .await
                  .unwrap();

              let payer = rpc.get_payer().insecure_clone();
              println!("Payer: {}", payer.pubkey());
          }
          ```
        </Tab>

        <Tab title="Localnet">
          ```bash theme={null}
          npm install -g @lightprotocol/zk-compression-cli@beta
          ```

          ```bash theme={null}
          # Start local test validator (in separate terminal)
          light test-validator
          ```
        </Tab>

        <Tab title="Devnet">
          Replace `<your-api-key>` with your actual API key. [Get your API key here](https://www.helius.dev/zk-compression).

          ```rust theme={null}
          use light_client::rpc::{LightClient, LightClientConfig, Rpc};

          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?;
          ```
        </Tab>
      </Tabs>
    </Accordion>
  </Tab>
</Tabs>


# Transfer Checked
Source: https://www.zkcompression.com/light-token/cookbook/transfer-checked

Rust client guide to transfer Light Tokens with decimal validation. Includes step-by-step implementation and full code examples.

***

1. TransferChecked validates that the decimals parameter matches the mint's decimals.
2. Use for Light→Light transfers when you need decimal verification.
3. For transfers involving SPL or Token 2022 accounts, use [Transfer Interface](/light-token/cookbook/transfer-interface) instead.

<Tabs>
  <Tab title="Rust Client">
    <Steps>
      <Step>
        ### Prerequisites

        <Accordion title="Dependencies">
          ```toml Cargo.toml theme={null}
          [dependencies]
          light-token = "0.4.0"
          light-client = { version = "0.19.0", features = ["v2"] }
          solana-sdk = "2"
          borsh = "0.10.4"
          tokio = { version = "1", features = ["full"] }
          ```
        </Accordion>

        <Accordion title="Developer Environment">
          <Tabs>
            <Tab title="In-Memory (LightProgramTest)">
              Test with Lite-SVM (...)

              ```bash theme={null}
              # Initialize project
              cargo init my-light-project
              cd my-light-project

              # Run tests
              cargo test
              ```

              ```rust theme={null}
              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());
              }
              ```
            </Tab>

            <Tab title="Localnet (LightClient)">
              Connects to a local test validator.

              <Tabs>
                <Tab title="npm">
                  ```bash theme={null}
                  npm install -g @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>

                <Tab title="yarn">
                  ```bash theme={null}
                  yarn global add @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>

                <Tab title="pnpm">
                  ```bash theme={null}
                  pnpm add -g @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>
              </Tabs>

              ```bash theme={null}
              # Initialize project
              cargo init my-light-project
              cd my-light-project

              # Start local test validator (in separate terminal)
              light test-validator
              ```

              ```rust theme={null}
              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(())
              }
              ```
            </Tab>

            <Tab title="Devnet (LightClient)">
              Replace `<your-api-key>` with your actual API key. [Get your API key here](https://www.helius.dev/zk-compression).

              ```rust theme={null}
              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(())
              }
              ```
            </Tab>
          </Tabs>
        </Accordion>
      </Step>

      <Step>
        ### Transfer with Decimal Check

        <Info>
          View the [source code](https://github.com/Lightprotocol/light-protocol/blob/main/sdk-libs/token-sdk/src/instruction/transfer_checked.rs) and [full example](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/instructions/transfer_checked.rs) with shared test utilities.
        </Info>

        <Tabs>
          <Tab title="Action">
            ```rust theme={null}
            use borsh::BorshDeserialize;
            use light_client::rpc::Rpc;
            use light_token_client::actions::{CreateAta, TransferChecked};
            use rust_client::{setup, SetupContext};
            use solana_sdk::{signature::Keypair, signer::Signer};

            #[tokio::main]
            async fn main() -> Result<(), Box<dyn std::error::Error>> {
                let SetupContext {
                    mut rpc,
                    payer,
                    mint,
                    associated_token_account,
                    decimals,
                    ..
                } = setup().await;

                // Create recipient associated token account
                let recipient = Keypair::new();
                let (_signature, recipient_associated_token_account) = CreateAta {
                    mint,
                    owner: recipient.pubkey(),
                    idempotent: true,
                }
                .execute(&mut rpc, &payer)
                .await?;

                // TransferChecked validates decimals match the mint's decimals.
                // Only use for Light->Light transfers.
                // Use TransferInterface for all other transfers (Light, SPL or Token-2022).
                let sig = TransferChecked {
                    source: associated_token_account,
                    mint,
                    destination: recipient_associated_token_account,
                    amount: 1000,
                    decimals,
                }
                .execute(&mut rpc, &payer, &payer)
                .await?;

                let data = rpc
                    .get_account(recipient_associated_token_account)
                    .await?
                    .ok_or("Account not found")?;
                let token = light_token_interface::state::Token::deserialize(&mut &data.data[..])?;
                println!("Balance: {} Tx: {sig}", token.amount);

                Ok(())
            }
            ```
          </Tab>

          <Tab title="Instruction">
            ```rust theme={null}
            use borsh::BorshDeserialize;
            use light_client::rpc::Rpc;
            use light_token::instruction::{
                get_associated_token_address, CreateAssociatedTokenAccount, TransferChecked,
            };
            use rust_client::{setup, SetupContext};
            use solana_sdk::{signature::Keypair, signer::Signer};

            #[tokio::main]
            async fn main() -> Result<(), Box<dyn std::error::Error>> {
                // Setup creates mint and associated token account with tokens
                let SetupContext {
                    mut rpc,
                    payer,
                    mint,
                    associated_token_account,
                    decimals,
                    ..
                } = setup().await;

                let transfer_amount = 400_000u64;

                // Create recipient associated token account
                let recipient = Keypair::new();
                let recipient_associated_token_account = get_associated_token_address(&recipient.pubkey(), &mint);

                let create_associated_token_account_instruction = CreateAssociatedTokenAccount::new(payer.pubkey(), recipient.pubkey(), mint)
                    .instruction()?;

                rpc.create_and_send_transaction(&[create_associated_token_account_instruction], &payer.pubkey(), &[&payer])
                    .await?;

                // TransferChecked validates decimals match the mint's decimals
                // Only use for Light->Light transfers.
                // Use TransferInterface for all other transfers (Light, SPL or Token-2022).
                let transfer_instruction = TransferChecked {
                    source: associated_token_account,
                    mint,
                    destination: recipient_associated_token_account,
                    amount: transfer_amount,
                    decimals,
                    authority: payer.pubkey(),
                    max_top_up: None,
                    fee_payer: None,
                }
                .instruction()?;

                let sig = rpc
                    .create_and_send_transaction(&[transfer_instruction], &payer.pubkey(), &[&payer])
                    .await?;

                let data = rpc
                    .get_account(recipient_associated_token_account)
                    .await?
                    .ok_or("Account not found")?;
                let token = light_token_interface::state::Token::deserialize(&mut &data.data[..])?;
                println!("Balance: {} Tx: {sig}", token.amount);

                Ok(())
            }
            ```
          </Tab>
        </Tabs>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Program">
    <Note>
      Find [a full code example at the end](#full-code-example).
    </Note>

    <Steps>
      <Step>
        ### Transfer Checked with CPI

        <Tabs>
          <Tab title="invoke (External signer)">
            ```rust theme={null}
            use light_token::instruction::TransferCheckedCpi;

            TransferCheckedCpi {
                source: source.clone(),
                mint: mint.clone(),
                destination: destination.clone(),
                amount,
                decimals,
                authority: authority.clone(),
                system_program: system_program.clone(),
                max_top_up: None,
                fee_payer: None,
            }
            .invoke()?;
            ```
          </Tab>

          <Tab title="invoke_signed (PDA signer)">
            ```rust theme={null}
            use light_token::instruction::TransferCheckedCpi;

            let signer_seeds = authority_seeds!(bump);

            TransferCheckedCpi {
                source: source.clone(),
                mint: mint.clone(),
                destination: destination.clone(),
                amount,
                decimals,
                authority: authority.clone(),
                system_program: system_program.clone(),
                max_top_up: None,
                fee_payer: None,
            }
            .invoke_signed(&[signer_seeds])?;
            ```
          </Tab>
        </Tabs>
      </Step>
    </Steps>

    # Full Code Example

    <Info>
      View the [source code](https://github.com/Lightprotocol/light-protocol/blob/main/sdk-libs/token-sdk/src/instruction/transfer_checked.rs) and [full example](https://github.com/Lightprotocol/examples-light-token/tree/main/programs/anchor/basic-instructions/transfer-checked) with shared test utilities.
    </Info>

    <CodeGroup>
      ```rust lib.rs theme={null}
      #![allow(unexpected_cfgs, deprecated)]

      use anchor_lang::prelude::*;
      use light_token::instruction::TransferCheckedCpi;

      declare_id!("HXmfewpozFdxhM8BayL9v5541gwoGMXTrUoip5KySs2f");

      #[program]
      pub mod light_token_anchor_transfer_checked {
          use super::*;

          pub fn transfer_checked(
              ctx: Context<TransferCheckedAccounts>,
              amount: u64,
              decimals: u8,
          ) -> Result<()> {
              TransferCheckedCpi {
                  source: ctx.accounts.source.to_account_info(),
                  mint: ctx.accounts.mint.to_account_info(),
                  destination: ctx.accounts.destination.to_account_info(),
                  amount,
                  decimals,
                  authority: ctx.accounts.authority.to_account_info(),
                  system_program: ctx.accounts.system_program.to_account_info(),
                  max_top_up: None,
                  fee_payer: None,
              }
              .invoke()?;
              Ok(())
          }
      }

      #[derive(Accounts)]
      pub struct TransferCheckedAccounts<'info> {
          /// CHECK: Light token program for CPI
          pub light_token_program: AccountInfo<'info>,
          /// CHECK: Validated by light-token CPI
          #[account(mut)]
          pub source: AccountInfo<'info>,
          /// CHECK: Validated by light-token CPI
          pub mint: AccountInfo<'info>,
          /// CHECK: Validated by light-token CPI
          #[account(mut)]
          pub destination: AccountInfo<'info>,
          pub authority: Signer<'info>,
          pub system_program: Program<'info, System>,
      }
      ```

      ```rust test.rs theme={null}
      use anchor_lang::{InstructionData, ToAccountMetas};
      use light_program_test::Rpc;
      use light_token::instruction::LIGHT_TOKEN_PROGRAM_ID;
      use light_token_anchor_transfer_checked::{accounts, instruction::TransferChecked, ID};
      use anchor_lang::system_program;
      use solana_sdk::{instruction::Instruction, signature::Keypair, signer::Signer};
      use test_utils::{create_associated_token_account_for_owner, mint_tokens, setup_test_env};

      #[tokio::test]
      async fn test_transfer_checked() {
          let mut env = setup_test_env("light_token_anchor_transfer_checked", ID).await;
          mint_tokens(&mut env.rpc, &env.payer, env.mint_pda, env.associated_token_account, 1_000_000).await;

          // Create destination associated token account for recipient
          let recipient = Keypair::new();
          let dest_associated_token_account =
              create_associated_token_account_for_owner(&mut env.rpc, &env.payer, &recipient.pubkey(), &env.mint_pda).await;

          // TransferChecked validates decimals match the mint's decimals.
          // Only use for Light->Light transfers.
          // Use TransferInterface for all other transfers (Light, SPL or Token-2022).
          let transfer_amount = 100_000u64;
          let decimals = 9u8;

          let ix = Instruction {
              program_id: ID,
              accounts: accounts::TransferCheckedAccounts {
                  light_token_program: LIGHT_TOKEN_PROGRAM_ID,
                  source: env.associated_token_account,
                  mint: env.mint_pda,
                  destination: dest_associated_token_account,
                  authority: env.payer.pubkey(),
                  system_program: system_program::ID,
              }
              .to_account_metas(Some(true)),
              data: TransferChecked {
                  amount: transfer_amount,
                  decimals,
              }
              .data(),
          };

          let sig = env
              .rpc
              .create_and_send_transaction(&[ix], &env.payer.pubkey(), &[&env.payer])
              .await
              .unwrap();

          println!("Tx: {}", sig);
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>

# Next Steps

<Card title="Learn how to close Light Token accounts" icon="chevron-right" href="/light-token/cookbook/close-token-account" />


# Transfer Interface
Source: https://www.zkcompression.com/light-token/cookbook/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.

***

<table>
  <tbody>
    <tr>
      <td>**Light Token -> Light Token Account**</td>

      <td>
        <ul>
          <li>Transfers tokens between Light Token accounts</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>**SPL token -> Light Token Account**</td>

      <td>
        <ul>
          <li>Transfers SPL tokens to Light Token accounts</li>
          <li>SPL tokens are locked in interface PDA</li>
          <li>Tokens are minted to Light Token account</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>**Light Token -> SPL Account**</td>

      <td>
        <ul>
          <li>Releases SPL tokens from interface PDA to SPL account</li>
          <li>Burns tokens in source Light Token account</li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

<Tabs>
  <Tab title="TypeScript Client">
    The `transferInterface` function transfers tokens between token accounts (SPL, Token 2022, or Light) in a single call.

    Compare to SPL:

    <CodeCompare />

    <Info>
      Find the source code
      [here](https://github.com/Lightprotocol/light-protocol/blob/0c4e2417b2df2d564721b89e18d1aad3665120e7/js/compressed-token/src/v3/actions/transfer-interface.ts).
    </Info>

    <Steps>
      <Step>
        ### Transfer Interface

        <Accordion title="Installation">
          <Tabs>
            <Tab title="npm">
              Install packages in your working directory:

              ```bash theme={null}
              npm install @lightprotocol/stateless.js@beta \
                          @lightprotocol/compressed-token@beta
              ```

              Install the CLI globally:

              ```bash theme={null}
              npm install -g @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>

            <Tab title="yarn">
              Install packages in your working directory:

              ```bash theme={null}
              yarn add @lightprotocol/stateless.js@beta \
                       @lightprotocol/compressed-token@beta
              ```

              Install the CLI globally:

              ```bash theme={null}
              yarn global add @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>

            <Tab title="pnpm">
              Install packages in your working directory:

              ```bash theme={null}
              pnpm add @lightprotocol/stateless.js@beta \
                       @lightprotocol/compressed-token@beta
              ```

              Install the CLI globally:

              ```bash theme={null}
              pnpm add -g @lightprotocol/zk-compression-cli@beta
              ```
            </Tab>
          </Tabs>
        </Accordion>

        <Tabs>
          <Tab title="Localnet">
            ```bash theme={null}
            # start local test-validator in a separate terminal
            light test-validator
            ```

            <Note>
              In the code examples, use `createRpc()` without arguments for localnet.
            </Note>
          </Tab>

          <Tab title="Devnet">
            Get an API key from [Helius](https://helius.dev) and add to `.env`:

            ```bash title=".env" theme={null}
            API_KEY=<your-helius-api-key>
            ```

            <Note>
              In the code examples, use `createRpc(RPC_URL)` with the devnet URL.
            </Note>
          </Tab>
        </Tabs>

        <Tabs>
          <Tab title="Action">
            ```typescript theme={null}
            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);
            })();
            ```
          </Tab>

          <Tab title="Instruction">
            ```typescript theme={null}
            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,
                );

                // Transfer tokens between light-token associate token accounts
                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);
            })();
            ```
          </Tab>
        </Tabs>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Rust Client">
    Use the unified `TransferInterface` to transfer tokens between token accounts (SPL, Token 2022, or Light) in a single call.

    <CodeCompare />

    <Steps>
      <Step>
        ### Prerequisites

        <Accordion title="Dependencies">
          ```toml Cargo.toml theme={null}
          [dependencies]
          light-token = "0.4.0"
          light-client = { version = "0.19.0", features = ["v2"] }
          solana-sdk = "2"
          borsh = "0.10.4"
          tokio = { version = "1", features = ["full"] }
          ```
        </Accordion>

        <Accordion title="Developer Environment">
          <Tabs>
            <Tab title="In-Memory (LightProgramTest)">
              Test with Lite-SVM (...)

              ```bash theme={null}
              # Initialize project
              cargo init my-light-project
              cd my-light-project

              # Run tests
              cargo test
              ```

              ```rust theme={null}
              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());
              }
              ```
            </Tab>

            <Tab title="Localnet (LightClient)">
              Connects to a local test validator.

              <Tabs>
                <Tab title="npm">
                  ```bash theme={null}
                  npm install -g @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>

                <Tab title="yarn">
                  ```bash theme={null}
                  yarn global add @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>

                <Tab title="pnpm">
                  ```bash theme={null}
                  pnpm add -g @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>
              </Tabs>

              ```bash theme={null}
              # Initialize project
              cargo init my-light-project
              cd my-light-project

              # Start local test validator (in separate terminal)
              light test-validator
              ```

              ```rust theme={null}
              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(())
              }
              ```
            </Tab>

            <Tab title="Devnet (LightClient)">
              Replace `<your-api-key>` with your actual API key. [Get your API key here](https://www.helius.dev/zk-compression).

              ```rust theme={null}
              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(())
              }
              ```
            </Tab>
          </Tabs>
        </Accordion>
      </Step>

      <Step>
        ### Transfer Interface

        The example transfers

        1. SPL token -> Light Token,
        2. Light Token -> Light Token, and
        3. Light Token -> SPL token.

        <Info>
          View the [source code](https://github.com/Lightprotocol/light-protocol/blob/main/sdk-libs/token-sdk/src/instruction/transfer_interface.rs) and [full example](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/instructions/transfer_interface.rs) with shared test utilities.
        </Info>

        <Tabs>
          <Tab title="Action">
            ```rust theme={null}
            use borsh::BorshDeserialize;
            use light_client::rpc::Rpc;
            use light_token_client::actions::{CreateAta, TransferInterface};
            use rust_client::{setup, SetupContext};
            use solana_sdk::{signature::Keypair, signer::Signer};

            #[tokio::main]
            async fn main() -> Result<(), Box<dyn std::error::Error>> {
                let SetupContext {
                    mut rpc,
                    payer,
                    mint,
                    associated_token_account,
                    decimals,
                    ..
                } = setup().await;

                // Create recipient associated token account
                let recipient = Keypair::new();
                let (_signature, recipient_associated_token_account) = CreateAta {
                    mint,
                    owner: recipient.pubkey(),
                    idempotent: true,
                }
                .execute(&mut rpc, &payer)
                .await?;

                // Transfers tokens between token accounts (SPL, Token-2022, or Light) in a single call.
                let sig = TransferInterface {
                    source: associated_token_account,
                    mint,
                    destination: recipient_associated_token_account,
                    amount: 1000,
                    decimals,
                    ..Default::default()
                }
                .execute(&mut rpc, &payer, &payer)
                .await?;

                let data = rpc
                    .get_account(recipient_associated_token_account)
                    .await?
                    .ok_or("Account not found")?;
                let token = light_token_interface::state::Token::deserialize(&mut &data.data[..])?;
                println!("Balance: {} Tx: {sig}", token.amount);

                Ok(())
            }
            ```
          </Tab>

          <Tab title="Instruction">
            ```rust theme={null}
            use anchor_spl::token::spl_token;
            use borsh::BorshDeserialize;
            use light_client::rpc::Rpc;
            use light_program_test::{LightProgramTest, ProgramTestConfig};
            use light_token::{
                instruction::{
                    get_associated_token_address, CreateAssociatedTokenAccount, SplInterface,
                    TransferInterface, LIGHT_TOKEN_PROGRAM_ID,
                },
                spl_interface::find_spl_interface_pda_with_index,
            };
            use rust_client::{setup_spl_associated_token_account, setup_spl_mint};
            use solana_sdk::signer::Signer;

            #[tokio::main]
            async fn main() -> Result<(), Box<dyn std::error::Error>> {
                let mut rpc = LightProgramTest::new(ProgramTestConfig::new_v2(true, None)).await?;

                let payer = rpc.get_payer().insecure_clone();
                let decimals = 2u8;
                let amount = 10_000u64;

                // Setup creates mint, mints tokens and creates SPL associated token account
                let mint = setup_spl_mint(&mut rpc, &payer, decimals).await;
                let spl_associated_token_account = setup_spl_associated_token_account(&mut rpc, &payer, &mint, &payer.pubkey(), amount).await;
                let (interface_pda, interface_bump) = find_spl_interface_pda_with_index(&mint, 0, false);

                // Create Light associated token account
                let light_associated_token_account = get_associated_token_address(&payer.pubkey(), &mint);

                let create_associated_token_account_instruction =
                    CreateAssociatedTokenAccount::new(payer.pubkey(), payer.pubkey(), mint).instruction()?;

                rpc.create_and_send_transaction(&[create_associated_token_account_instruction], &payer.pubkey(), &[&payer])
                    .await?;

                // SPL interface PDA for Mint (holds SPL tokens when transferred to Light Token)
                let spl_interface = SplInterface {
                    mint,
                    spl_token_program: spl_token::ID,
                    spl_interface_pda: interface_pda,
                    spl_interface_pda_bump: interface_bump,
                };

                // Transfers tokens between token accounts (SPL, Token-2022, or Light) in a single call.
                let transfer_instruction = TransferInterface {
                    source: spl_associated_token_account,
                    destination: light_associated_token_account,
                    amount,
                    decimals,
                    authority: payer.pubkey(),
                    payer: payer.pubkey(),
                    spl_interface: Some(spl_interface),
                    max_top_up: None,
                    source_owner: spl_token::ID,
                    destination_owner: LIGHT_TOKEN_PROGRAM_ID,
                }
                .instruction()?;

                let sig = rpc
                    .create_and_send_transaction(&[transfer_instruction], &payer.pubkey(), &[&payer])
                    .await?;

                let data = rpc
                    .get_account(light_associated_token_account)
                    .await?
                    .ok_or("Account not found")?;
                let token = light_token_interface::state::Token::deserialize(&mut &data.data[..])?;
                println!("Balance: {} Tx: {sig}", token.amount);

                Ok(())
            }
            ```
          </Tab>
        </Tabs>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Program">
    <Note>
      Find [a full code example at the end](#full-code-example).
    </Note>

    <Steps>
      <Step>
        ### Transfer Interface CPI

        The `TransferInterfaceCpi` transfers tokens between token accounts (SPL, Token 2022, or Light Token).

        <Tabs>
          <Tab title="invoke (External signer)">
            ```rust theme={null}
            use light_token::instruction::TransferInterfaceCpi;

            TransferInterfaceCpi::new(
                amount,
                decimals,
                source.clone(),
                destination.clone(),
                authority.clone(),
                payer.clone(),
                light_token_authority.clone(),
                system_program.clone(),
            )
            .invoke()?;
            ```
          </Tab>

          <Tab title="invoke_signed (PDA signer)">
            ```rust theme={null}
            use light_token::instruction::TransferInterfaceCpi;

            let signer_seeds = authority_seeds!(bump);

            TransferInterfaceCpi::new(
                amount,
                decimals,
                source.clone(),
                destination.clone(),
                authority.clone(),
                payer.clone(),
                light_token_authority.clone(),
                system_program.clone(),
            )
            .invoke_signed(&[signer_seeds])?;
            ```
          </Tab>
        </Tabs>
      </Step>
    </Steps>

    # Full Code Example

    <Info>
      View the [source code](https://github.com/Lightprotocol/light-protocol/blob/main/sdk-libs/token-sdk/src/instruction/transfer_interface.rs) and [full example](https://github.com/Lightprotocol/examples-light-token/tree/main/programs/anchor/basic-instructions/transfer-interface) with shared test utilities.
    </Info>

    <CodeGroup>
      ```rust lib.rs theme={null}
      #![allow(unexpected_cfgs, deprecated)]

      use anchor_lang::prelude::*;
      use light_token::instruction::TransferInterfaceCpi;

      declare_id!("3rb6sG4jiYNLZC8jo8kLsFHpxr2Ci8e8Hh8UmeCMZmUV");

      #[program]
      pub mod light_token_anchor_transfer_interface {
          use super::*;

          pub fn transfer(
              ctx: Context<TransferAccounts>,
              amount: u64,
              decimals: u8,
              spl_interface_pda_bump: Option<u8>,
          ) -> Result<()> {
              let mut transfer = TransferInterfaceCpi::new(
                  amount,
                  decimals,
                  ctx.accounts.source.to_account_info(),
                  ctx.accounts.destination.to_account_info(),
                  ctx.accounts.authority.to_account_info(),
                  ctx.accounts.payer.to_account_info(),
                  ctx.accounts.cpi_authority.to_account_info(),
                  ctx.accounts.system_program.to_account_info(),
              );

              if let Some(bump) = spl_interface_pda_bump {
                  transfer = transfer
                      .with_spl_interface(
                          ctx.accounts.mint.as_ref().map(|a| a.to_account_info()),
                          ctx.accounts
                              .spl_token_program
                              .as_ref()
                              .map(|a| a.to_account_info()),
                          ctx.accounts
                              .spl_interface_pda
                              .as_ref()
                              .map(|a| a.to_account_info()),
                          Some(bump),
                      )
                      .map_err(|e| ProgramError::from(e))?;
              }

              transfer.invoke().map_err(|e| ProgramError::from(e))?;
              Ok(())
          }
      }

      #[derive(Accounts)]
      pub struct TransferAccounts<'info> {
          /// CHECK: Light token program for CPI
          pub light_token_program: AccountInfo<'info>,
          /// CHECK: Validated by light-token CPI
          #[account(mut)]
          pub source: AccountInfo<'info>,
          /// CHECK: Validated by light-token CPI
          #[account(mut)]
          pub destination: AccountInfo<'info>,
          pub authority: Signer<'info>,
          #[account(mut)]
          pub payer: Signer<'info>,
          /// CHECK: Validated by light-token CPI
          pub cpi_authority: AccountInfo<'info>,
          pub system_program: Program<'info, System>,

          // SPL interface accounts (optional, for cross-type transfers)
          /// CHECK: Validated by light-token CPI - token mint
          pub mint: Option<AccountInfo<'info>>,
          /// CHECK: SPL Token or Token-2022 program
          pub spl_token_program: Option<AccountInfo<'info>>,
          /// CHECK: Validated by light-token CPI - pool PDA
          #[account(mut)]
          pub spl_interface_pda: Option<AccountInfo<'info>>,
      }
      ```

      ```rust test.rs theme={null}
      use anchor_lang::system_program;
      use anchor_lang::{InstructionData, ToAccountMetas};
      use anchor_spl::token::{spl_token, Mint};
      use light_program_test::Rpc;
      use solana_sdk::program_pack::Pack as _;
      use light_token::instruction::{
          derive_token_ata, CreateAssociatedTokenAccount, LIGHT_TOKEN_PROGRAM_ID,
      };
      use light_token::spl_interface::{find_spl_interface_pda_with_index, CreateSplInterfacePda};
      use light_token_anchor_transfer_interface::{accounts, instruction::Transfer, ID};
      use light_token_types::CPI_AUTHORITY_PDA;
      use solana_sdk::{
          instruction::Instruction,
          pubkey::Pubkey,
          signature::Keypair,
          signer::Signer,
      };
      use test_utils::{create_associated_token_account_for_owner, mint_tokens, setup_test_env};

      #[tokio::test]
      async fn test_transfer() {
          let mut env = setup_test_env("light_token_anchor_transfer_interface", ID).await;
          mint_tokens(&mut env.rpc, &env.payer, env.mint_pda, env.associated_token_account, 1_000_000).await;

          // Create destination associated token account for recipient
          let recipient = Keypair::new();
          let dest_associated_token_account =
              create_associated_token_account_for_owner(&mut env.rpc, &env.payer, &recipient.pubkey(), &env.mint_pda).await;

          // Transfers tokens between accounts (SPL, Token-2022, or Light) in a single call.
          let transfer_amount = 100_000u64;
          let decimals = 9u8;
          let cpi_authority_pda = Pubkey::new_from_array(CPI_AUTHORITY_PDA);

          let ix = Instruction {
              program_id: ID,
              accounts: accounts::TransferAccounts {
                  light_token_program: LIGHT_TOKEN_PROGRAM_ID,
                  source: env.associated_token_account,
                  destination: dest_associated_token_account,
                  authority: env.payer.pubkey(),
                  payer: env.payer.pubkey(),
                  cpi_authority: cpi_authority_pda,
                  system_program: system_program::ID,
                  mint: None,
                  spl_token_program: None,
                  spl_interface_pda: None,
              }
              .to_account_metas(Some(true)),
              data: Transfer {
                  amount: transfer_amount,
                  decimals,
                  spl_interface_pda_bump: None,
              }
              .data(),
          };

          let sig = env
              .rpc
              .create_and_send_transaction(&[ix], &env.payer.pubkey(), &[&env.payer])
              .await
              .unwrap();

          println!("Tx: {}", sig);
      }

      #[tokio::test]
      async fn test_transfer_spl_to_light() {
          let mut env = setup_test_env("light_token_anchor_transfer_interface", ID).await;

          let payer = env.payer.insecure_clone();
          let cpi_authority_pda = Pubkey::new_from_array(CPI_AUTHORITY_PDA);

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

          let mint_rent = env
              .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();

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

          // 2. Create SPL token pool (spl_interface_pda)
          let create_pool_ix =
              CreateSplInterfacePda::new(payer.pubkey(), mint, spl_token::ID, false).instruction();

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

          // 3. Create SPL token account and mint tokens
          let spl_account_keypair = Keypair::new();
          let spl_account = spl_account_keypair.pubkey();

          let spl_account_rent = env
              .rpc
              .get_minimum_balance_for_rent_exemption(spl_token::state::Account::LEN)
              .await
              .unwrap();

          let create_spl_account_ix = solana_sdk::system_instruction::create_account(
              &payer.pubkey(),
              &spl_account,
              spl_account_rent,
              spl_token::state::Account::LEN as u64,
              &spl_token::ID,
          );

          let init_spl_account_ix = spl_token::instruction::initialize_account(
              &spl_token::ID,
              &spl_account,
              &mint,
              &payer.pubkey(),
          )
          .unwrap();

          let mint_amount = 1_000_000u64;
          let mint_to_ix = spl_token::instruction::mint_to(
              &spl_token::ID,
              &mint,
              &spl_account,
              &payer.pubkey(),
              &[],
              mint_amount,
          )
          .unwrap();

          env.rpc
              .create_and_send_transaction(
                  &[create_spl_account_ix, init_spl_account_ix, mint_to_ix],
                  &payer.pubkey(),
                  &[&payer, &spl_account_keypair],
              )
              .await
              .unwrap();

          // 4. Create Light ATA for destination
          let recipient = Keypair::new();
          let (dest_ata, _) = derive_token_ata(&recipient.pubkey(), &mint);
          let create_ata_ix = CreateAssociatedTokenAccount::new(payer.pubkey(), recipient.pubkey(), mint)
              .instruction()
              .unwrap();

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

          // 5. Transfer SPL tokens to Light ATA via transfer-interface
          let transfer_amount = 100_000u64;
          let (spl_interface_pda, spl_interface_pda_bump) =
              find_spl_interface_pda_with_index(&mint, 0, false);

          let ix = Instruction {
              program_id: ID,
              accounts: accounts::TransferAccounts {
                  light_token_program: LIGHT_TOKEN_PROGRAM_ID,
                  source: spl_account,
                  destination: dest_ata,
                  authority: payer.pubkey(),
                  payer: payer.pubkey(),
                  cpi_authority: cpi_authority_pda,
                  system_program: system_program::ID,
                  mint: Some(mint),
                  spl_token_program: Some(spl_token::ID),
                  spl_interface_pda: Some(spl_interface_pda),
              }
              .to_account_metas(Some(true)),
              data: Transfer {
                  amount: transfer_amount,
                  decimals,
                  spl_interface_pda_bump: Some(spl_interface_pda_bump),
              }
              .data(),
          };

          let sig = env
              .rpc
              .create_and_send_transaction(&[ix], &payer.pubkey(), &[&payer])
              .await
              .unwrap();

          println!("Tx: {}", sig);
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>

# Next Steps

<Card title="Learn about Transfer Checked" icon="chevron-right" href="/light-token/cookbook/transfer-checked" />


# Wrap & Unwrap SPL/Token 2022 <> Light Token
Source: https://www.zkcompression.com/light-token/cookbook/wrap-unwrap

Move tokens between SPL/Token 2022 token and Light Token accounts. Use to interact with applications that only support SPL/Token 2022.

***

* **Wrap**: Move tokens from SPL/T22 account → Light Token ATA (hot balance)
* **Unwrap**: Move tokens from Light Token ATA (hot balance) → SPL/T22 account

<Info>
  Find the source code:
  [wrap.ts](https://github.com/Lightprotocol/light-protocol/blob/0c4e2417b2df2d564721b89e18d1aad3665120e7/js/compressed-token/src/v3/actions/wrap.ts)
  |
  [unwrap.ts](https://github.com/Lightprotocol/light-protocol/blob/0c4e2417b2df2d564721b89e18d1aad3665120e7/js/compressed-token/src/v3/actions/unwrap.ts)
</Info>

<Tabs>
  <Tab title="TypeScript Client">
    <Tabs>
      <Tab title="Wrap">
        <Steps>
          <Step>
            ### Wrap SPL Tokens to Light Token ATA

            <Accordion title="Installation">
              <Tabs>
                <Tab title="npm">
                  Install packages in your working directory:

                  ```bash theme={null}
                  npm install @lightprotocol/stateless.js@beta \
                              @lightprotocol/compressed-token@beta
                  ```

                  Install the CLI globally:

                  ```bash theme={null}
                  npm install -g @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>

                <Tab title="yarn">
                  Install packages in your working directory:

                  ```bash theme={null}
                  yarn add @lightprotocol/stateless.js@beta \
                           @lightprotocol/compressed-token@beta
                  ```

                  Install the CLI globally:

                  ```bash theme={null}
                  yarn global add @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>

                <Tab title="pnpm">
                  Install packages in your working directory:

                  ```bash theme={null}
                  pnpm add @lightprotocol/stateless.js@beta \
                           @lightprotocol/compressed-token@beta
                  ```

                  Install the CLI globally:

                  ```bash theme={null}
                  pnpm add -g @lightprotocol/zk-compression-cli@beta
                  ```
                </Tab>
              </Tabs>
            </Accordion>

            <Tabs>
              <Tab title="Localnet">
                ```bash theme={null}
                # start local test-validator in a separate terminal
                light test-validator
                ```

                <Note>
                  In the code examples, use `createRpc()` without arguments for localnet.
                </Note>
              </Tab>

              <Tab title="Devnet">
                Get an API key from [Helius](https://helius.dev) and add to `.env`:

                ```bash title=".env" theme={null}
                API_KEY=<your-helius-api-key>
                ```

                <Note>
                  In the code examples, use `createRpc(RPC_URL)` with the devnet URL.
                </Note>
              </Tab>
            </Tabs>

            <Tabs>
              <Tab title="Action">
                ```typescript theme={null}
                import "dotenv/config";
                import { Keypair } from "@solana/web3.js";
                import { createRpc, bn } from "@lightprotocol/stateless.js";
                import {
                    createMint,
                    mintTo,
                    decompress,
                    wrap,
                    getAssociatedTokenAddressInterface,
                    createAtaInterfaceIdempotent,
                } from "@lightprotocol/compressed-token";
                import { createAssociatedTokenAccount } from "@solana/spl-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 () {
                    // Setup: Get SPL tokens (needed to wrap)
                    const { mint } = await createMint(rpc, payer, payer.publicKey, 9);
                    const splAta = await createAssociatedTokenAccount(
                        rpc,
                        payer,
                        mint,
                        payer.publicKey
                    );
                    await mintTo(rpc, payer, mint, payer.publicKey, payer, bn(1000));
                    await decompress(rpc, payer, mint, bn(1000), payer, splAta);

                    // Wrap SPL tokens to rent-free token ATA
                    const lightTokenAta = getAssociatedTokenAddressInterface(mint, payer.publicKey);
                    await createAtaInterfaceIdempotent(rpc, payer, mint, payer.publicKey);

                    const tx = await wrap(rpc, payer, splAta, lightTokenAta, payer, mint, bn(500));

                    console.log("Tx:", tx);
                })();
                ```
              </Tab>

              <Tab title="Instruction">
                ```typescript theme={null}
                import "dotenv/config";
                import { Keypair, ComputeBudgetProgram, Transaction, sendAndConfirmTransaction } from "@solana/web3.js";
                import { createRpc, bn } from "@lightprotocol/stateless.js";
                import {
                    createMint,
                    mintTo,
                    decompress,
                    createWrapInstruction,
                    getAssociatedTokenAddressInterface,
                    createAtaInterfaceIdempotent,
                    getSplInterfaceInfos,
                } from "@lightprotocol/compressed-token";
                import { createAssociatedTokenAccount } from "@solana/spl-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 () {
                    // Setup: Get SPL tokens (needed to wrap)
                    const { mint } = await createMint(rpc, payer, payer.publicKey, 9);
                    const splAta = await createAssociatedTokenAccount(
                        rpc,
                        payer,
                        mint,
                        payer.publicKey
                    );
                    await mintTo(rpc, payer, mint, payer.publicKey, payer, bn(1000));
                    await decompress(rpc, payer, mint, bn(1000), payer, splAta);

                    // Create wrap instruction
                    const lightTokenAta = getAssociatedTokenAddressInterface(mint, payer.publicKey);
                    await createAtaInterfaceIdempotent(rpc, payer, mint, payer.publicKey);

                    const splInterfaceInfos = await getSplInterfaceInfos(rpc, mint);
                    const splInterfaceInfo = splInterfaceInfos.find(
                        (info) => info.isInitialized
                    );

                    if (!splInterfaceInfo) throw new Error("No SPL interface found");

                    const ix = createWrapInstruction(
                        splAta,
                        lightTokenAta,
                        payer.publicKey,
                        mint,
                        bn(500),
                        splInterfaceInfo,
                        9, // decimals - must match the mint decimals
                        payer.publicKey
                    );

                    const tx = new Transaction().add(
                        ComputeBudgetProgram.setComputeUnitLimit({ units: 200_000 }),
                        ix
                    );
                    const signature = await sendAndConfirmTransaction(rpc, tx, [payer]);

                    console.log("Tx:", signature);
                })();
                ```
              </Tab>
            </Tabs>
          </Step>
        </Steps>
      </Tab>

      <Tab title="Unwrap">
        <Steps>
          <Step>
            ### Unwrap Light Tokens to SPL Account

            <Tabs>
              <Tab title="Action">
                ```typescript theme={null}
                import "dotenv/config";
                import { Keypair } from "@solana/web3.js";
                import { createRpc, bn } from "@lightprotocol/stateless.js";
                import { createMint, mintTo } from "@lightprotocol/compressed-token";
                import { unwrap } from "@lightprotocol/compressed-token/unified";
                import { createAssociatedTokenAccount } from "@solana/spl-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 () {
                    // Setup: Get compressed tokens (cold storage)
                    const { mint } = await createMint(rpc, payer, payer.publicKey, 9);
                    await mintTo(rpc, payer, mint, payer.publicKey, payer, bn(1000));

                    // Unwrap rent-free tokens to SPL ATA
                    const splAta = await createAssociatedTokenAccount(
                        rpc,
                        payer,
                        mint,
                        payer.publicKey
                    );
                    const tx = await unwrap(rpc, payer, splAta, payer, mint, bn(500));

                    console.log("Tx:", tx);
                })();
                ```
              </Tab>

              <Tab title="Instruction">
                ```typescript theme={null}
                import "dotenv/config";
                import { Keypair, ComputeBudgetProgram, Transaction, sendAndConfirmTransaction } from "@solana/web3.js";
                import { createRpc, bn } from "@lightprotocol/stateless.js";
                import {
                    createMint,
                    mintTo,
                    loadAta,
                    getAssociatedTokenAddressInterface,
                    getSplInterfaceInfos,
                } from "@lightprotocol/compressed-token";
                import { createUnwrapInstruction } from "@lightprotocol/compressed-token/unified";
                import { createAssociatedTokenAccount } from "@solana/spl-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 () {
                    // Setup: Get compressed tokens (cold storage)
                    const { mint } = await createMint(rpc, payer, payer.publicKey, 9);
                    await mintTo(rpc, payer, mint, payer.publicKey, payer, bn(1000));

                    // Load compressed tokens to hot balance, then create unwrap instruction
                    const lightTokenAta = getAssociatedTokenAddressInterface(mint, payer.publicKey);
                    await loadAta(rpc, lightTokenAta, payer, mint, payer);

                    const splAta = await createAssociatedTokenAccount(
                        rpc,
                        payer,
                        mint,
                        payer.publicKey
                    );

                    const splInterfaceInfos = await getSplInterfaceInfos(rpc, mint);
                    const splInterfaceInfo = splInterfaceInfos.find(
                        (info) => info.isInitialized
                    );

                    if (!splInterfaceInfo) throw new Error("No SPL interface found");

                    const ix = createUnwrapInstruction(
                        lightTokenAta,
                        splAta,
                        payer.publicKey,
                        mint,
                        bn(500),
                        splInterfaceInfo,
                        9, // decimals - must match the mint decimals
                        payer.publicKey
                    );

                    const tx = new Transaction().add(
                        ComputeBudgetProgram.setComputeUnitLimit({ units: 200_000 }),
                        ix
                    );
                    const signature = await sendAndConfirmTransaction(rpc, tx, [payer]);

                    console.log("Tx:", signature);
                })();
                ```
              </Tab>
            </Tabs>
          </Step>
        </Steps>
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Rust Client">
    <Tabs>
      <Tab title="Wrap">
        <Steps>
          <Step>
            ### Prerequisites

            <Accordion title="Dependencies">
              ```toml Cargo.toml theme={null}
              [dependencies]
              light-token = "0.4.0"
              light-client = { version = "0.19.0", features = ["v2"] }
              solana-sdk = "2"
              borsh = "0.10.4"
              tokio = { version = "1", features = ["full"] }
              ```
            </Accordion>

            <Accordion title="Developer Environment">
              <Tabs>
                <Tab title="In-Memory (LightProgramTest)">
                  Test with Lite-SVM (...)

                  ```bash theme={null}
                  # Initialize project
                  cargo init my-light-project
                  cd my-light-project

                  # Run tests
                  cargo test
                  ```

                  ```rust theme={null}
                  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());
                  }
                  ```
                </Tab>

                <Tab title="Localnet (LightClient)">
                  Connects to a local test validator.

                  <Tabs>
                    <Tab title="npm">
                      ```bash theme={null}
                      npm install -g @lightprotocol/zk-compression-cli@beta
                      ```
                    </Tab>

                    <Tab title="yarn">
                      ```bash theme={null}
                      yarn global add @lightprotocol/zk-compression-cli@beta
                      ```
                    </Tab>

                    <Tab title="pnpm">
                      ```bash theme={null}
                      pnpm add -g @lightprotocol/zk-compression-cli@beta
                      ```
                    </Tab>
                  </Tabs>

                  ```bash theme={null}
                  # Initialize project
                  cargo init my-light-project
                  cd my-light-project

                  # Start local test validator (in separate terminal)
                  light test-validator
                  ```

                  ```rust theme={null}
                  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(())
                  }
                  ```
                </Tab>

                <Tab title="Devnet (LightClient)">
                  Replace `<your-api-key>` with your actual API key. [Get your API key here](https://www.helius.dev/zk-compression).

                  ```rust theme={null}
                  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(())
                  }
                  ```
                </Tab>
              </Tabs>
            </Accordion>
          </Step>

          <Step>
            ### Wrap SPL tokens to Light Token ATA

            <Info>
              View the [full example](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/actions/wrap.rs) with shared test utilities.
            </Info>

            <Tabs>
              <Tab title="Action">
                ```rust theme={null}
                use borsh::BorshDeserialize;
                use light_client::rpc::Rpc;
                use light_token_client::actions::Wrap;
                use rust_client::{setup_for_wrap, WrapContext};

                #[tokio::main]
                async fn main() -> Result<(), Box<dyn std::error::Error>> {
                    // Setup creates SPL associated token account with tokens and empty Light associated token account
                    let WrapContext {
                        mut rpc,
                        payer,
                        mint,
                        source_associated_token_account,
                        light_associated_token_account,
                        decimals,
                    } = setup_for_wrap().await;

                    // Wrap tokens from SPL associated token account to Light Token associated token account
                    let sig = Wrap {
                        source_spl_ata: source_associated_token_account,
                        destination: light_associated_token_account,
                        mint,
                        amount: 500_000,
                        decimals,
                    }
                    .execute(&mut rpc, &payer, &payer)
                    .await?;

                    let data = rpc
                        .get_account(light_associated_token_account)
                        .await?
                        .ok_or("Account not found")?;
                    let token = light_token_interface::state::Token::deserialize(&mut &data.data[..])?;
                    println!("Balance: {} Tx: {sig}", token.amount);

                    Ok(())
                }
                ```
              </Tab>
            </Tabs>
          </Step>
        </Steps>
      </Tab>

      <Tab title="Unwrap">
        <Steps>
          <Step>
            ### Prerequisites

            <Accordion title="Dependencies">
              ```toml Cargo.toml theme={null}
              [dependencies]
              light-token = "0.4.0"
              light-client = { version = "0.19.0", features = ["v2"] }
              solana-sdk = "2"
              borsh = "0.10.4"
              tokio = { version = "1", features = ["full"] }
              ```
            </Accordion>

            <Accordion title="Developer Environment">
              <Tabs>
                <Tab title="In-Memory (LightProgramTest)">
                  Test with Lite-SVM (...)

                  ```bash theme={null}
                  # Initialize project
                  cargo init my-light-project
                  cd my-light-project

                  # Run tests
                  cargo test
                  ```

                  ```rust theme={null}
                  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());
                  }
                  ```
                </Tab>

                <Tab title="Localnet (LightClient)">
                  Connects to a local test validator.

                  <Tabs>
                    <Tab title="npm">
                      ```bash theme={null}
                      npm install -g @lightprotocol/zk-compression-cli@beta
                      ```
                    </Tab>

                    <Tab title="yarn">
                      ```bash theme={null}
                      yarn global add @lightprotocol/zk-compression-cli@beta
                      ```
                    </Tab>

                    <Tab title="pnpm">
                      ```bash theme={null}
                      pnpm add -g @lightprotocol/zk-compression-cli@beta
                      ```
                    </Tab>
                  </Tabs>

                  ```bash theme={null}
                  # Initialize project
                  cargo init my-light-project
                  cd my-light-project

                  # Start local test validator (in separate terminal)
                  light test-validator
                  ```

                  ```rust theme={null}
                  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(())
                  }
                  ```
                </Tab>

                <Tab title="Devnet (LightClient)">
                  Replace `<your-api-key>` with your actual API key. [Get your API key here](https://www.helius.dev/zk-compression).

                  ```rust theme={null}
                  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(())
                  }
                  ```
                </Tab>
              </Tabs>
            </Accordion>
          </Step>

          <Step>
            ### Unwrap Light Tokens to SPL account

            <Info>
              View the [full example](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/actions/unwrap.rs) with shared test utilities.
            </Info>

            <Tabs>
              <Tab title="Action">
                ```rust theme={null}
                use anchor_spl::token::spl_token::state::Account as SplAccount;
                use light_client::rpc::Rpc;
                use light_token_client::actions::Unwrap;
                use rust_client::{setup_for_unwrap, UnwrapContext};
                use solana_sdk::program_pack::Pack;

                #[tokio::main]
                async fn main() -> Result<(), Box<dyn std::error::Error>> {
                    // Setup creates Light associated token account with tokens and empty SPL associated token account
                    let UnwrapContext {
                        mut rpc,
                        payer,
                        mint,
                        destination_associated_token_account,
                        light_associated_token_account,
                        decimals,
                    } = setup_for_unwrap().await;

                    // Unwrap tokens from Light Token associated token account to SPL associated token account
                    let sig = Unwrap {
                        source: light_associated_token_account,
                        destination_spl_ata: destination_associated_token_account,
                        mint,
                        amount: 500_000,
                        decimals,
                    }
                    .execute(&mut rpc, &payer, &payer)
                    .await?;

                    let data = rpc
                        .get_account(destination_associated_token_account)
                        .await?
                        .ok_or("Account not found")?;
                    let token = SplAccount::unpack(&data.data)?;
                    println!("Balance: {} Tx: {sig}", token.amount);

                    Ok(())
                }
                ```
              </Tab>
            </Tabs>
          </Step>
        </Steps>
      </Tab>
    </Tabs>
  </Tab>
</Tabs>


# Program Integration
Source: https://www.zkcompression.com/light-token/defi/programs

Build high-performance DeFi programs with rent-free accounts

The Light-SDK sponsors rent-exemption for your PDAs, token accounts, and mints. Your program logic stays the same.

|                       | Before | After    |
| --------------------- | ------ | -------- |
| Rent (avg. DeFi pool) | \~\$2  | \~\$0.02 |

## What Changes

| Area                                        | Change                                                                            |
| ------------------------------------------- | --------------------------------------------------------------------------------- |
| State struct                                | Derive `LightAccount` and add a `compression_info: Option<CompressionInfo>` field |
| Accounts                                    | Derive `LightAccounts` and add `#[light_account]` on init accounts                |
| Program module                              | Add `#[light_program]` on top of `#[program]`                                     |
| Instructions (swap, deposit, withdraw, ...) | No changes                                                                        |

Audit overhead is minimal as your program logic is mostly untouched. The rest is
macro-generated.

If you don't use Anchor, see the [Pinocchio Programs](./programs-pinocchio) guide.

***

<Callout type="info">
  You can find a complete rent-free AMM reference implementation [here](https://github.com/Lightprotocol/cp-swap-reference).
</Callout>

## Step 1: Dependencies

```toml theme={null}
[dependencies]

light-sdk = { version = "0.18.0", features = ["anchor", "v2", "cpi-context"] }
light-sdk-macros = { version = "0.18.0" }
light-token = { version = "0.3.0", features = ["anchor"] }

light-anchor-spl = { version = "0.31" }    # TokenInterface uses light_token::ID
anchor-lang = "0.31"
```

## Step 2: State Struct

Add `compression_info` field and derive `LightAccount`:

```rust theme={null}
use light_sdk::compressible::CompressionInfo;
use light_sdk_macros::LightAccount;

#[derive(Default, Debug, InitSpace, LightAccount)]
#[account]
pub struct PoolState {
    /// Add this:
    pub compression_info: Option<CompressionInfo>,
    
    /// Your existing fields
    /// ...
}
```

## Step 3: Program

Add `#[light_program]` above `#[program]`:

```rust theme={null}
use light_sdk_macros::light_program;

#[light_program]
#[program]
pub mod my_amm {
    use super::*;

    pub fn initialize_pool(ctx: Context<InitializePool>, params: InitializeParams) -> Result<()> {
        process_initialize_pool(ctx, params)
    }

    // These don't change
    pub fn swap(ctx: Context<Swap>, amount_in: u64, min_out: u64) -> Result<()> {
        process_swap(ctx, amount_in, min_out)
    }
}
```

## Step 4: Accounts Struct

Derive `LightAccounts` on your `Accounts` struct and add `#[light_account(...)]` next to `#[account(...)]`.

<Tabs>
  <Tab title="PDAs">
    ```rust theme={null}
    #[account(
        init, 
        seeds = [...], 
        bump, 
        payer = creator, 
        space = 8 + PoolState::INIT_SPACE
    )]
    #[light_account(init)]
    pub pool_state: Box<Account<'info, PoolState>>,
    ```
  </Tab>

  <Tab title="Token Account">
    ```rust theme={null}
    #[account(
        mut, 
        seeds = [b"vault", pool_state.key().as_ref(), mint.key().as_ref()], 
        bump,
        payer = creator,
        space = 8 + TokenAccount::INIT_SPACE
    )]
    #[light_account(
        init, 
        token, 
        authority = [AUTH_SEED.as_bytes()], 
        mint = token_mint, 
        owner = authority,
    )]
    pub token_vault: UncheckedAccount<'info>,
    ```

    <Accordion title="Manual">
      ```rust theme={null}
      #[account(
          mut, 
          seeds = [b"vault", pool_state.key().as_ref(), mint.key().as_ref()], 
          bump,
          payer = creator,
          space = 8 + TokenAccount::INIT_SPACE
      )]
      #[light_account(
          token, 
          authority = [AUTH_SEED.as_bytes()], 
          mint = token_mint, 
          owner = authority,
      )]
      pub token_vault: UncheckedAccount<'info>,
      ```

      Use without `init` to create manually in the instruction handler via
      `CreateTokenAccountCpi`.
    </Accordion>
  </Tab>

  <Tab title="Associated Token Account (ATA)">
    ```rust theme={null}
    #[light_account(
        init, 
        associated_token, 
        owner = creator, mint = lp_mint,
    )]
    pub creator_lp_token: UncheckedAccount<'info>,
    ```
  </Tab>

  <Tab title="Mint">
    ```rust theme={null}
    #[account(mut)]
    #[light_account(
        init,
        mint,
        mint_signer = lp_mint_signer,
        authority = authority,
        decimals = 9,
        mint_seeds = &[LP_MINT_SIGNER_SEED, pool_state.key().as_ref(), &[params.mint_signer_bump]],
        authority_seeds = &[AUTH_SEED.as_bytes(), &[params.authority_bump]]
    )]
    pub lp_mint: UncheckedAccount<'info>,
    ```

    <Accordion title="Mint with Metadata">
      ```rust theme={null}
      #[light_account(
          init,
          mint,
          mint_signer = mint_signer,
          authority = fee_payer,
          decimals = 9,
          mint_seeds = &[MINT_SIGNER_SEED, authority.key().as_ref(), &[params.mint_signer_bump]],
          name = params.name.clone(),
          symbol = params.symbol.clone(),
          uri = params.uri.clone(),
          // Optional
          update_authority = authority,
          additional_metadata = params.additional_metadata.clone()
      )]
      pub mint: UncheckedAccount<'info>,
      ```
    </Accordion>
  </Tab>
</Tabs>

<Accordion title="Full Accounts Struct">
  We also need to add `light_token_interface_config`, `rent_sponsor`, and `light_token_cpi_authority`.

  ```rust theme={null}
  use light_sdk::interface::CreateAccountsProof;
  use light_sdk_macros::LightAccounts;
  use light_token::instruction::{COMPRESSIBLE_CONFIG_V1, RENT_SPONSOR as LIGHT_TOKEN_RENT_SPONSOR};

  #[derive(AnchorSerialize, AnchorDeserialize, Clone)]
  pub struct InitializeParams {
      pub create_accounts_proof: CreateAccountsProof,
      pub lp_mint_signer_bump: u8,
      pub creator_lp_token_bump: u8,
      pub authority_bump: u8,
  }

  #[derive(Accounts, LightAccounts)]
  #[instruction(params: InitializeParams)]
  pub struct InitializePool<'info> {
      #[account(mut)]
      pub creator: Signer<'info>,

      #[account(mut, seeds = [AUTH_SEED.as_bytes()], bump)]
      pub authority: UncheckedAccount<'info>,

      #[account(
          init,
          seeds = [POOL_SEED.as_bytes(), token_0_mint.key().as_ref(), token_1_mint.key().as_ref()],
          bump,
          payer = creator,
          space = 8 + PoolState::INIT_SPACE
      )]
      #[light_account(init)]
      pub pool_state: Box<Account<'info, PoolState>>,

      pub token_0_mint: Box<InterfaceAccount<'info, Mint>>,
      pub token_1_mint: Box<InterfaceAccount<'info, Mint>>,

      #[account(seeds = [POOL_LP_MINT_SIGNER_SEED, pool_state.key().as_ref()], bump)]
      pub lp_mint_signer: UncheckedAccount<'info>,

      #[account(mut)]
      #[light_account(init, mint,
          mint_signer = lp_mint_signer,
          authority = authority,
          decimals = 9,
          mint_seeds = &[POOL_LP_MINT_SIGNER_SEED, self.pool_state.to_account_info().key.as_ref(), &[params.lp_mint_signer_bump]],
          authority_seeds = &[AUTH_SEED.as_bytes(), &[params.authority_bump]]
      )]
      pub lp_mint: UncheckedAccount<'info>,

      #[account(mut, seeds = [POOL_VAULT_SEED.as_bytes(), pool_state.key().as_ref(), token_0_mint.key().as_ref()], bump)]
      #[light_account(token, authority = [AUTH_SEED.as_bytes()])]
      pub token_0_vault: UncheckedAccount<'info>,

      #[account(mut, seeds = [POOL_VAULT_SEED.as_bytes(), pool_state.key().as_ref(), token_1_mint.key().as_ref()], bump)]
      #[light_account(token, authority = [AUTH_SEED.as_bytes()])]
      pub token_1_vault: UncheckedAccount<'info>,

      #[account(mut)]
      pub creator_lp_token: UncheckedAccount<'info>,


      pub light_interface_config: AccountInfo<'info>,
      #[account(address = COMPRESSIBLE_CONFIG_V1)]
      pub light_token_interface_config: AccountInfo<'info>,
      #[account(mut, address = LIGHT_TOKEN_RENT_SPONSOR)]
      pub rent_sponsor: AccountInfo<'info>,
      pub light_token_program: AccountInfo<'info>,
      pub light_token_cpi_authority: AccountInfo<'info>,
      pub system_program: Program<'info, System>,
  }
  ```
</Accordion>

## Step 5: Instructions

Replace `spl_token` with `light_token` instructions as you need. The API is a superset of SPL-token so switching is straightforward.

Examples include: `MintToCpi`, `TransferCpi`, `TransferInterfaceCpi`,
`CreateTokenAccountCpi`, and `CreateTokenAtaCpi`.

<Accordion title="Example: Initialize">
  ```rust theme={null}
  use light_token::instruction::{CreateTokenAccountCpi, CreateTokenAtaCpi, MintToCpi};

  pub fn process_initialize_pool(ctx: Context<InitializePool>, params: InitializeParams) -> Result<()> {
      let pool_key = ctx.accounts.pool_state.key();
      
      // Create rent-free token vault
      CreateTokenAccountCpi {
          payer: ctx.accounts.creator.to_account_info(),
          account: ctx.accounts.token_0_vault.to_account_info(),
          mint: ctx.accounts.token_0_mint.to_account_info(),
          owner: ctx.accounts.authority.key(),
      }
      .rent_free(
          ctx.accounts.light_token_interface_config.to_account_info(),
          ctx.accounts.rent_sponsor.to_account_info(),
          ctx.accounts.system_program.to_account_info(),
          &crate::ID,
      )
      .invoke_signed(&[
          POOL_VAULT_SEED.as_bytes(),
          pool_key.as_ref(),
          ctx.accounts.token_0_mint.key().as_ref(),
          &[ctx.bumps.token_0_vault],
      ])?;

      // Create rent-free ATA for LP tokens
      CreateTokenAtaCpi {
          payer: ctx.accounts.creator.to_account_info(),
          owner: ctx.accounts.creator.to_account_info(),
          mint: ctx.accounts.lp_mint.to_account_info(),
          ata: ctx.accounts.creator_lp_token.to_account_info(),
          bump: params.creator_lp_token_bump,
      }
      .idempotent()
      .rent_free(
          ctx.accounts.light_token_interface_config.to_account_info(),
          ctx.accounts.rent_sponsor.to_account_info(),
          ctx.accounts.system_program.to_account_info(),
      )
      .invoke()?;

      // Mint LP tokens (standard CPI, no changes)
      MintToCpi {
          mint: ctx.accounts.lp_mint.to_account_info(),
          destination: ctx.accounts.creator_lp_token.to_account_info(),
          amount: 1000,
          authority: ctx.accounts.authority.to_account_info(),
          system_program: ctx.accounts.system_program.to_account_info(),
          max_top_up: None,
      }
      .invoke_signed(&[&[AUTH_SEED.as_bytes(), &[ctx.bumps.authority]]])?;

      // Populate pool state (unchanged)
      let pool = &mut ctx.accounts.pool_state;
      pool.token_0_vault = ctx.accounts.token_0_vault.key();
      pool.lp_mint = ctx.accounts.lp_mint.key();
      // ...

      Ok(())
  }
  ```
</Accordion>

***

## Client SDK

To make it easy for clients to integrate with your program, implement the
`LightProgramInterface` trait in your program's SDK crate.

For a detailed example of how clients use this trait, check out the [Router Integration](./routers.mdx) page.

<Accordion title="Example: Trait Implementation">
  ```rust theme={null}
  pub struct AmmSdk {
      pub pool_state_pubkey: Pubkey,
      pub observation_key: Pubkey,
      pub token_0_vault: Pubkey,
      pub token_1_vault: Pubkey,
      pub token_0_mint: Pubkey,
      pub token_1_mint: Pubkey,
      pub lp_mint: Pubkey,
      pub amm_config: Pubkey,
  }

  pub enum AmmInstruction {
      Swap,
      Deposit,
      Withdraw,
  }

  impl LightProgramInterface for AmmSdk {
      type Variant = LightAccountVariant;
      type Instruction = AmmInstruction;

      fn program_id() -> Pubkey {
          PROGRAM_ID
      }

      fn instruction_accounts(&self, ix: &Self::Instruction) -> Vec<Pubkey> {
          match ix {
              AmmInstruction::Swap => vec![
                  self.pool_state_pubkey,
                  self.observation_key,
                  self.token_0_vault,
                  self.token_1_vault,
                  self.token_0_mint,
                  self.token_1_mint,
              ],
              AmmInstruction::Deposit | AmmInstruction::Withdraw => vec![
                  self.pool_state_pubkey,
                  self.observation_key,
                  self.token_0_vault,
                  self.token_1_vault,
                  self.token_0_mint,
                  self.token_1_mint,
                  self.lp_mint,
              ],
          }
      }

      fn load_specs(
          &self,
          cold_accounts: &[AccountInterface],
      ) -> Result<Vec<AccountSpec<Self::Variant>>, Box<dyn Error>> {
          // Build AccountSpec for each cold account by matching pubkey
          // and deserializing its data into the macro-generated variant.
          let mut specs = Vec::new();
          for account in cold_accounts {
              let pubkey = account.key();
              if pubkey == self.pool_state_pubkey || pubkey == self.observation_key {
                  let parsed: PoolState = AnchorDeserialize::deserialize(&mut &account.data()[8..])?;
                  specs.push(AccountSpec::Pda(PdaSpec { interface: account.clone(), variant: parsed.into() }));
              } else if pubkey == self.token_0_vault || pubkey == self.token_1_vault {
                  specs.push(AccountSpec::Token(account.clone()));
              }
              // ...
          }
          Ok(specs)
      }
  }
  ```
</Accordion>

| Resource                     | Link                                                                                                             |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Trait Implementation Example | [CpSwapSdk](https://github.com/Lightprotocol/cp-swap-reference/blob/main/programs/cp-swap/tests/program.rs#L409) |

***

## Testing

<Accordion title="Example: Integration Test">
  ```rust theme={null}
  use light_program_test::{LightProgramTest, ProgramTestConfig, Rpc};
  use light_sdk::interface::rent::SLOTS_PER_EPOCH;
  use light_client::interface::{create_load_instructions, LightProgramInterface};

  #[tokio::test]
  async fn test_pool_lifecycle() {
      let config = ProgramTestConfig::new_v2(true, Some(vec![("my_amm", MY_AMM_ID)]));
      let mut rpc = LightProgramTest::new(config).await.unwrap();

      // 1. Init pool (rent-free)
      // ... build and send init instruction ...

      // 2. Swap (hot path - works normally)
      // ... build and send swap instruction ...

      // 3. Trigger compression (advance time)
      rpc.warp_slot_forward(SLOTS_PER_EPOCH * 30).await.unwrap();

      let pool_interface = rpc
          .get_account_interface(&pool_address, None)
          .await
          .unwrap()
          .value
          .unwrap();
      assert!(pool_interface.is_cold());

      // 4. Build SDK and get load instructions
      let sdk = AmmSdk::new(pool_address, pool_interface.data()).unwrap();
      let pubkeys = sdk.instruction_accounts(&AmmInstruction::Deposit);
      let accounts = rpc.get_multiple_account_interfaces(pubkeys.iter().collect(), None).await.unwrap().value;
      let cold: Vec<_> = accounts.into_iter().flatten().filter(|a| a.is_cold()).collect();

      let specs = sdk.load_specs(&cold).unwrap();
      let load_ixs = create_load_instructions(&specs, payer.pubkey(), config_pda, &rpc).await.unwrap();

      // 5. Send transaction
      rpc.create_and_send_transaction(&load_ixs, &payer.pubkey(), &[&payer]).await.unwrap();
  }
  ```
</Accordion>

| Resource     | Link                                                                                                         |
| ------------ | ------------------------------------------------------------------------------------------------------------ |
| Test example | [program.rs](https://github.com/Lightprotocol/cp-swap-reference/blob/main/programs/cp-swap/tests/program.rs) |

***

## How it works

The SDK pays the rent-exemption cost. After extended inactivity, cold accounts auto-compress. Your program only ever
interacts with hot accounts. Clients can safely load cold accounts back into the
onchain Solana account space when needed via `create_load_instructions`.

Under the hood, clients use `AccountInterface` - a superset of Solana's
`Account` that unifies hot and cold state. See [Router Integration](./routers)
for details.

|                   | Hot (active) | Cold (inactive)   |
| ----------------- | ------------ | ----------------- |
| Storage           | On-chain     | Compressed        |
| Latency/CU        | No change    | +load instruction |
| Your program code | No change    | No change         |

## Existing programs

If you want to migrate your program to rent-free accounts and would like hands-on support, [join our tech Discord](https://discord.com/invite/7cJ8BhAXhu),
or [email us](mailto:support@lightprotocol.com).

## FAQ

<Accordion title="How does it prevent re-init attacks?"> When creating an
account for the first time, the SDK provides a proof that the account doesn't
exist in the cold address space. The SVM already verifies this for the onchain
space. Both address spaces are checked before creation, preventing re-init
attacks, even if the account is currently cold. </Accordion>

<Accordion title="Who triggers compression?">
  Miners (Forester nodes) compress accounts that have been inactive for an extended period of time (when their virtual rent balance drops below threshold).
  In practice, having to load cold accounts should be rare. The common path (hot) has no extra overhead and does not increase CU or txn size.
</Accordion>

<Accordion title="How is the SDK able to sponsor rent exemption?">
  When accounts compress after extended inactivity, the on-chain rent-exemption is released back
  to the rent sponsor. This creates a revolving lifecycle: active "hot" accounts hold a
  rent-exempt lamports balance, inactive "cold" accounts release it back. The
  rent sponsor must be derived from the program owner. For all mint, ATA, and
  token accounts, the Light Token Program is the rent sponsor. For your own program-owned PDAs, the SDK derives a rent sponsor address automatically.
</Accordion>

<Accordion title="Do rent-free accounts increase CU?">
  **Hot path (e.g. swap, deposit, withdraw):** No. Active accounts do not add CU overhead to your instructions.

  **First time init + loading cold accounts:** Yes, adds up to 15k-400k CU,
  depending on number and type of accounts being initialized or loaded.
</Accordion>

***

<Callout type="info">
  API is in Beta and subject to change.

  Questions or need hands-on support? [Telegram](https://t.me/swen_light) | [email](mailto:support@lightprotocol.com) | [Discord](https://discord.com/invite/7cJ8BhAXhu)
</Callout>


# Pinocchio Programs
Source: https://www.zkcompression.com/light-token/defi/programs-pinocchio

Build high-performance DeFi programs with rent-free accounts using Pinocchio

The Light-SDK sponsors rent-exemption for your PDAs, token accounts, and mints. Your program logic stays the same.

|                       | Before | After    |
| --------------------- | ------ | -------- |
| Rent (avg. DeFi pool) | \~\$2  | \~\$0.02 |

## What Changes

| Area               | Change                                                                                  |
| ------------------ | --------------------------------------------------------------------------------------- |
| State struct       | Add `compression_info: CompressionInfo` field, derive `LightPinocchioAccount`           |
| Program enum       | Derive `LightProgramPinocchio` to generate compress/decompress handlers                 |
| Entrypoint         | Route generated discriminators alongside your custom ones                               |
| Init handler       | Replace `spl_token` CPIs with `light_token_pinocchio` CPIs to create rent-free accounts |
| Other instructions | No changes                                                                              |

If you use Anchor instead of Pinocchio, see [Program Integration](./programs).

***

<Callout type="info">
  Complete pinocchio Swap reference implementation: [pinocchio-swap](https://github.com/Lightprotocol/examples-light-token/tree/simplify-trait/pinocchio/swap)
</Callout>

## Step 1: Dependencies

```toml theme={null}
[dependencies]
light-account-pinocchio = { version = "0.20", features = ["token", "std"] }
light-token-pinocchio = "0.20"

pinocchio = "0.9"
pinocchio-pubkey = { version = "0.3", features = ["const"] }
pinocchio-system = "0.3"
borsh = { version = "0.10.4", default-features = false }
bytemuck = { version = "1.21", features = ["derive"] }
```

## Step 2: State Struct

Add `compression_info` field and derive `LightPinocchioAccount`:

```rust theme={null}
use borsh::{BorshDeserialize, BorshSerialize};
use light_account_pinocchio::{CompressionInfo, LightPinocchioAccount};

#[derive(
    Default, Debug, Copy, Clone, PartialEq,
    BorshSerialize, BorshDeserialize,
    LightPinocchioAccount,
    bytemuck::Pod, bytemuck::Zeroable,
)]
#[repr(C)]
pub struct PoolState {
    pub compression_info: CompressionInfo,

    // Your regular state...
    pub fee_bps: u16,
}
```

## Step 3: Program Enum

Declare your account types with their seed schemas:

```rust theme={null}
use light_account_pinocchio::{
    derive_light_cpi_signer, pubkey_array, CpiSigner, LightProgramPinocchio,
};
use pinocchio::pubkey::Pubkey;

pub const ID: Pubkey = pubkey_array!("YourProgram11111111111111111111111111111111");
pub const LIGHT_CPI_SIGNER: CpiSigner =
    derive_light_cpi_signer!("YourProgram11111111111111111111111111111111");

#[derive(LightProgramPinocchio)]
pub enum ProgramAccounts {
    #[light_account(pda::seeds = [POOL_SEED, ctx.mint_a, ctx.mint_b], pda::zero_copy)]
    PoolState(PoolState),

    #[light_account(token::seeds = [POOL_VAULT_SEED, ctx.pool, ctx.mint], token::owner_seeds = [POOL_AUTHORITY_SEED])]
    Vault,

    #[light_account(associated_token)]
    UserToken,
}
```

This auto-generates 4 instructions, discriminators, and the `LightAccountVariant` enum used by the client SDK.

## Step 4: Entrypoint

Dispatch the generated handlers in your entrypoint

```rust theme={null}
pinocchio::entrypoint!(process_instruction);

pub fn process_instruction(
    _program_id: &Pubkey,
    accounts: &[AccountInfo],
    instruction_data: &[u8],
) -> Result<(), ProgramError> {
    if instruction_data.len() < 8 {
        return Err(ProgramError::InvalidInstructionData);
    }

    let (disc, data) = instruction_data.split_at(8);
    let disc: [u8; 8] = disc.try_into().unwrap();

    match disc {
        // your custom program logic...
        discriminators::INITIALIZE => process_initialize(accounts, data),
        discriminators::SWAP => process_swap(accounts, data),

        // add this:
        ProgramAccounts::INITIALIZE_COMPRESSION_CONFIG => {
            ProgramAccounts::process_initialize_config(accounts, data) // generated
        }
        ProgramAccounts::UPDATE_COMPRESSION_CONFIG => {
            ProgramAccounts::process_update_config(accounts, data)
        }
        ProgramAccounts::COMPRESS_ACCOUNTS_IDEMPOTENT => {
            ProgramAccounts::process_compress(accounts, data)
        }
        ProgramAccounts::DECOMPRESS_ACCOUNTS_IDEMPOTENT => {
            ProgramAccounts::process_decompress(accounts, data)
        }
        _ => Err(ProgramError::InvalidInstructionData),
    }
}
```

## Step 5: Init Handler

Update your init instruction. Use `light_token_pinocchio` CPI builders to create rent-free token accounts.

<Tabs>
  <Tab title="Create Token Account">
    ```rust theme={null}
    use light_account_pinocchio::CreateTokenAccountCpi;

    CreateTokenAccountCpi {
        payer: ctx.payer,
        account: vault,
        mint,
        owner: *pool_authority.key(),
    }
    .rent_free(
        ctx.light_token_config,
        ctx.light_token_rent_sponsor,
        ctx.system_program,
        &crate::ID,
    )
    .invoke_signed(&[
        POOL_VAULT_SEED,
        pool_key.as_ref(),
        mint_key.as_ref(),
        &[bump],
    ])?;
    ```
  </Tab>

  <Tab title="Create Mint">
    ```rust theme={null}
    use light_account_pinocchio::{CreateMints, CreateMintsStaticAccounts, SingleMintParams};

    let sdk_mints: [SingleMintParams<'_>; 2] = [
        SingleMintParams {
            decimals: 9,
            mint_authority: authority_key,
            mint_bump: None,
            freeze_authority: None,
            mint_seed_pubkey: mint_signer_a_key,
            authority_seeds: None,
            mint_signer_seeds: Some(mint_signer_a_seeds),
            token_metadata: None,
        },
        // ...
    ];

    CreateMints {
        mints: &sdk_mints,
        proof_data: &params.create_accounts_proof,
        mint_seed_accounts: ctx.mint_signers,
        mint_accounts: ctx.mints,
        static_accounts: CreateMintsStaticAccounts {
            fee_payer: ctx.payer,
            compressible_config: ctx.light_token_config,
            rent_sponsor: ctx.light_token_rent_sponsor,
            cpi_authority: ctx.cpi_authority,
        },
        cpi_context_offset: 1,
    }
    .invoke(&cpi_accounts)?;
    ```
  </Tab>
</Tabs>

<Accordion title="Full Initialize Processor">
  ```rust theme={null}
  use light_account_pinocchio::{
      prepare_compressed_account_on_init, CompressedCpiContext, CpiAccounts, CpiAccountsConfig,
      CpiContextWriteAccounts, CreateMints, CreateMintsStaticAccounts, CreateTokenAccountCpi,
      InstructionDataInvokeCpiWithAccountInfo, InvokeLightSystemProgram, LightAccount, LightConfig,
      SingleMintParams,
  };
  use pinocchio::sysvars::{clock::Clock, Sysvar};

  pub fn process(
      ctx: &InitializeAccounts<'_>,
      params: &InitializeParams,
      remaining_accounts: &[AccountInfo],
  ) -> Result<(), LightSdkTypesError> {
      // 1. Build CPI accounts
      let config = CpiAccountsConfig::new_with_cpi_context(crate::LIGHT_CPI_SIGNER);
      let cpi_accounts = CpiAccounts::new_with_config(
          ctx.payer,
          &remaining_accounts[params.create_accounts_proof.system_accounts_offset as usize..],
          config,
      );

      // 2. Get address tree info + config
      let address_tree_info = &params.create_accounts_proof.address_tree_info;
      let address_tree_pubkey = address_tree_info.get_tree_pubkey(&cpi_accounts)?;
      let light_config = LightConfig::load_checked(ctx.compressible_config, &crate::ID)?;
      let current_slot = Clock::get()?.slot;

      // 3. Create pool PDA (write to CPI context)
      {
          let cpi_context = CompressedCpiContext::first();
          let mut new_address_params = Vec::with_capacity(1);
          let mut account_infos = Vec::with_capacity(1);
          let pool_key = *ctx.pool.key();

          prepare_compressed_account_on_init(
              &pool_key, &address_tree_pubkey, address_tree_info,
              params.create_accounts_proof.output_state_tree_index,
              0, &crate::ID,
              &mut new_address_params, &mut account_infos,
          )?;

          // Initialize pool state (zero-copy)
          {
              let mut data = ctx.pool.try_borrow_mut_data()?;
              let pool_state: &mut PoolState = bytemuck::from_bytes_mut(
                  &mut data[8..8 + core::mem::size_of::<PoolState>()]
              );
              pool_state.set_decompressed(&light_config, current_slot);
              pool_state.token_a_mint = *ctx.mint_a().key();
              pool_state.token_b_mint = *ctx.mint_b().key();
              // ... remaining fields
          }

          // Write to CPI context
          let instruction_data = InstructionDataInvokeCpiWithAccountInfo {
              mode: 1,
              bump: crate::LIGHT_CPI_SIGNER.bump,
              invoking_program_id: crate::LIGHT_CPI_SIGNER.program_id.into(),
              proof: params.create_accounts_proof.proof.0,
              new_address_params,
              account_infos,
              // ...
          };
          instruction_data.invoke_write_to_cpi_context_first(
              CpiContextWriteAccounts {
                  fee_payer: cpi_accounts.fee_payer(),
                  authority: cpi_accounts.authority()?,
                  cpi_context: cpi_accounts.cpi_context()?,
                  cpi_signer: crate::LIGHT_CPI_SIGNER,
              }
          )?;
      }

      // 4. Create mints
      CreateMints { /* ... */ }.invoke(&cpi_accounts)?;

      // 5. Create vaults (rent-free)
      CreateTokenAccountCpi { /* ... */ }.rent_free(/* ... */).invoke_signed(/* ... */)?;

      Ok(())
  }
  ```
</Accordion>

***

## Client SDK

Implement `LightProgramInterface` so clients can detect cold accounts and build load instructions.

<Accordion title="Example: LightProgramInterface Implementation">
  ```rust theme={null}
  use light_client::interface::{
      AccountInterface, AccountSpec, ColdContext, LightProgramInterface, PdaSpec,
  };
  use light_account::token::Token;
  use pinocchio_swap::{LightAccountVariant, PoolState, PoolStateSeeds, VaultSeeds};

  /// Flat SDK struct. All fields populated at construction from pool state data.
  pub struct SwapSdk {
      pub pool_state_pubkey: Pubkey,
      pub token_a_mint: Pubkey,
      pub token_b_mint: Pubkey,
      pub token_a_vault: Pubkey,
      pub token_b_vault: Pubkey,
      pub pool_authority: Pubkey,
  }

  impl SwapSdk {
      pub fn new(pool_state_pubkey: Pubkey, pool_data: &[u8]) -> Result<Self, SwapSdkError> {
          let pool = PoolState::deserialize(&mut &pool_data[8..])?;
          // ... derive addresses from pool state
          Ok(Self { pool_state_pubkey, /* ... */ })
      }
  }

  impl LightProgramInterface for SwapSdk {
      type Variant = LightAccountVariant;
      type Instruction = SwapInstruction;

      fn program_id() -> Pubkey { PROGRAM_ID }

      fn instruction_accounts(&self, ix: &Self::Instruction) -> Vec<Pubkey> {
          match ix {
              SwapInstruction::Swap => vec![
                  self.pool_state_pubkey,
                  self.token_a_vault,
                  self.token_b_vault,
                  self.token_a_mint,
                  self.token_b_mint,
              ],
              // ...
          }
      }

      fn load_specs(
          &self,
          cold_accounts: &[AccountInterface],
      ) -> Result<Vec<AccountSpec<Self::Variant>>, Box<dyn std::error::Error>> {
          let mut specs = Vec::new();
          for account in cold_accounts {
              if account.key == self.pool_state_pubkey {
                  let pool = PoolState::deserialize(&mut &account.data()[8..])?;
                  let variant = LightAccountVariant::PoolState {
                      seeds: PoolStateSeeds { /* ... */ },
                      data: pool,
                  };
                  specs.push(AccountSpec::Pda(PdaSpec::new(account.clone(), variant, PROGRAM_ID)));
              } else if account.key == self.token_a_vault {
                  let token: Token = Token::deserialize(&mut &account.data()[..])?;
                  let variant = LightAccountVariant::Vault(TokenDataWithSeeds {
                      seeds: VaultSeeds { pool: /* ... */, mint: /* ... */ },
                      token_data: token,
                  });
                  specs.push(AccountSpec::Pda(PdaSpec::new(account.clone(), variant, PROGRAM_ID)));
              }
              // ... token_b_vault, mints
          }
          Ok(specs)
      }
  }
  ```
</Accordion>

| Resource                | Link                                                                                                            |
| ----------------------- | --------------------------------------------------------------------------------------------------------------- |
| Full SDK implementation | [sdk.rs](https://github.com/Lightprotocol/examples-light-token/blob/simplify-trait/pinocchio/swap/tests/sdk.rs) |

***

## Testing

<Accordion title="Example: Full Lifecycle Test">
  ```rust theme={null}
  use light_program_test::{LightProgramTest, Rpc};
  use light_client::interface::{
      create_load_instructions, get_create_accounts_proof,
      AccountSpec, CreateAccountsProofInput, LightProgramInterface,
  };


  #[tokio::test]
  async fn test_pool_lifecycle() {
      let mut rpc = LightProgramTest::new(config).await.unwrap();

      // 1. Initialize pool (rent-free: pool PDA, 2 mints, 2 vaults)
      let proof = get_create_accounts_proof(&rpc, &program_id, vec![
          CreateAccountsProofInput::pda(pool_state),
          CreateAccountsProofInput::mint(mint_a_signer),
          CreateAccountsProofInput::mint(mint_b_signer),
      ]).await.unwrap();

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

      // 2. Swap (hot path)
      rpc.create_and_send_transaction(&[swap_ix], &user.pubkey(), &[&user])
          .await.unwrap();

      // 3. Trigger compression for the purpose of the test.
      const SLOTS_PER_EPOCH: u64 = 13500;
      rpc.warp_slot_forward(SLOTS_PER_EPOCH * 30).await.unwrap();

      // 4. Build SDK from pool state, fetch cold accounts
      let pool_iface = rpc.get_account_interface(&pool_state, None).await.unwrap().value.unwrap();
      assert!(pool_iface.is_cold());

      let sdk = SwapSdk::new(pool_state, pool_iface.data()).unwrap();
      let pubkeys = sdk.instruction_accounts(&SwapInstruction::Swap);
      let accounts = rpc.get_multiple_account_interfaces(pubkeys.iter().collect(), None)
          .await.unwrap().value;
      let cold: Vec<_> = accounts.into_iter().flatten().filter(|a| a.is_cold()).collect();

      // 5. Load cold accounts
      let mut specs = sdk.load_specs(&cold).unwrap();
      // Add user ATAs
      let ata_a = rpc.get_associated_token_account_interface(&user.pubkey(), &mint_a, None)
          .await.unwrap().value.unwrap();
      let ata_b = rpc.get_associated_token_account_interface(&user.pubkey(), &mint_b, None)
          .await.unwrap().value.unwrap();
      specs.push(AccountSpec::Ata(ata_a));
      specs.push(AccountSpec::Ata(ata_b));

      let load_ixs = create_load_instructions(&specs, payer.pubkey(), config_pda, &rpc)
          .await.unwrap();


      // 6. Load and Swap
      let mut all_ixs = load_ixs;
      all_ixs.push(swap_ix);
      rpc.create_and_send_transaction(&all_ixs, &user.pubkey(), &[&user])
          .await.unwrap();
  }
  ```
</Accordion>

| Resource  | Link                                                                                                                                   |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Full test | [test\_lifecycle.rs](https://github.com/Lightprotocol/examples-light-token/blob/simplify-trait/pinocchio/swap/tests/test_lifecycle.rs) |

***

## How it works

The SDK pays the rent-exemption cost. After extended inactivity, cold accounts auto-compress. Your program only ever
interacts with hot accounts. Clients can safely load cold accounts back into the
onchain Solana account space when needed via `create_load_instructions`.

Under the hood, clients use `AccountInterface` - a superset of Solana's
`Account` that unifies hot and cold state. See [Router Integration](./routers)
for details.

|                   | Hot (active) | Cold (inactive)   |
| ----------------- | ------------ | ----------------- |
| Storage           | On-chain     | Compressed        |
| Latency/CU        | No change    | +load instruction |
| Your program code | No change    | No change         |

## Existing programs

If you want to migrate your program to rent-free accounts and would like hands-on support, [join our tech Discord](https://discord.com/invite/7cJ8BhAXhu),
or [email us](mailto:support@lightprotocol.com).

## FAQ

<Accordion title="Do I have to manually handle compression/decompression?">
  No. `LightProgramPinocchio` generates the handlers. Simply add the generated handlers to your entrypoint, and update your init instruction.
</Accordion>

<Accordion title="How does it prevent re-init attacks?"> When creating an
account for the first time, the SDK provides a proof that the account doesn't
exist in the cold address space. The SVM already verifies this for the onchain
space. Both address spaces are checked before creation, preventing re-init
attacks, even if the account is currently cold. </Accordion>

<Accordion title="Who triggers compression?">
  Miners (Forester nodes) compress accounts that have been inactive for an extended period of time (when their virtual rent balance drops below threshold).
  In practice, having to load cold accounts should be rare. The common path (hot) has no extra overhead and does not increase CU or txn size.
</Accordion>

<Accordion title="How is the SDK able to sponsor rent exemption?">
  When accounts compress after extended inactivity, the on-chain rent-exemption is released back
  to the rent sponsor. This creates a revolving lifecycle: active "hot" accounts hold a
  rent-exempt lamports balance, inactive "cold" accounts release it back. The
  rent sponsor must be derived from the program owner. For all mint, ATA, and
  token accounts, the Light Token Program is the rent sponsor. For your own program-owned PDAs, the SDK derives a rent sponsor address automatically.
</Accordion>

<Accordion title="Do rent-free accounts increase CU?">
  **Hot path (e.g. swap, deposit, withdraw):** No. Active accounts do not add CU overhead to your instructions.

  **First time init + loading cold accounts:** Yes, adds up to 15k-400k CU,
  depending on number and type of accounts being initialized or loaded.
</Accordion>

***

<Callout type="info">
  API is in Beta and subject to change.

  Questions or need hands-on support? [Telegram](https://t.me/swen_light) | [email](mailto:support@lightprotocol.com) | [Discord](https://discord.com/invite/7cJ8BhAXhu)
</Callout>


# Router Integration
Source: https://www.zkcompression.com/light-token/defi/routers

Add support for rent-free AMMs on Solana.

Your existing quoting, routing, and swap-building logic stays the same.
The only addition: when a market has cold accounts, detect them, and prepend load instructions before the swap.

## What changes

|                  | Hot market (99%+) | Cold market                        |
| ---------------- | ----------------- | ---------------------------------- |
| Quoting          | No change         | No change                          |
| Swap instruction | No change         | No change                          |
| Transaction      | No change         | Prepend `create_load_instructions` |

***

## Detecting cold accounts

Add a cache for cold accounts. This can be separate from your regular account cache.

```rust theme={null}
cold_cache: HashMap<[u8; 32], AccountInterface>, // Accounts with `ColdContext` (used for loading)
```

If you stream, subscribe to accounts and transactions with the Light Token Program.

| Subscription                                   | Detects                 |
| :--------------------------------------------- | :---------------------- |
| Account sub (`owner: cToken...`)               | Hot state + cold-to-hot |
| Transaction sub (`account_include: cToken...`) | Hot-to-cold             |

**Hot-to-cold** -- in your transaction handler, listen to accounts whose balance dropped to zero. Async-fetch the `AccountInterface`
(which includes the `ColdContext` needed for load instructions):

```rust theme={null}
Some(UpdateOneof::Transaction(tx_update)) => {
    if let Some(ref tx_info) = tx_update.transaction {
        for pubkey in find_closed_accounts(tx_info) {
            if cache.remove(&pubkey).is_some() {
                let rpc = rpc.clone();
                let cold_cache = cold_cache.clone();
                tokio::spawn(async move {
                    if let Ok(Some(iface)) = rpc.get_account_interface(&pubkey, None).await {
                        cold_cache.insert(pubkey, iface);
                    }
                });
            }
        }
    }
}
```

`find_closed_accounts` checks `pre_balances[i] > 0 && post_balances[i] == 0` across all transaction
keys (including ALT-loaded addresses). See [full implementation](/light-token/toolkits/for-streaming-tokens#detecting-transitions).

**Cold-to-hot** -- your existing account subscription picks up the hot account again. No cache changes needed because account state does not change while cold.

```rust theme={null}
Some(UpdateOneof::Account(account_update)) => {
    if let Some(account) = account_update.account {
        let pubkey: [u8; 32] = account.pubkey.as_slice().try_into().unwrap();
        // remove from cold cache.
        cold_cache.remove(&pubkey);
    }
}
```

For the full streaming guide, see [Streaming Token Accounts](/light-token/toolkits/for-streaming-tokens)
and [Streaming Mints](/light-token/toolkits/for-streaming-mints).

If you don't stream, call `get_multiple_account_interfaces` at swap time and check `is_cold()` to detect cold accounts.

***

## Building swap transactions with cold accounts

When you detect cold accounts in a market (via your `cold_set` or via `is_cold()` on fetched accounts),
fetch their `ColdContext` via `get_account_interface` and build load instructions.

```rust theme={null}
use light_client::interface::{create_load_instructions, LightProgramInterface};

// 1. Identify which accounts the swap touches
let pubkeys = sdk.instruction_accounts(&AmmInstruction::Swap);

// 2. Check which are cold (from your streaming cache, or fetch)
let cold_pubkeys: Vec<_> = pubkeys.iter().filter(|p| cold_set.contains(p)).collect();

// 3. If any are cold, fetch their ColdContext and build load instructions
let mut ixs = vec![];
if !cold_pubkeys.is_empty() {
    let interfaces = rpc
        .get_multiple_account_interfaces(cold_pubkeys, None)
        .await?
        .value;
    let cold: Vec<_> = interfaces.into_iter().flatten().collect();
    let specs = sdk.load_specs(&cold)?;
    ixs.extend(create_load_instructions(&specs, payer, config_pda, &rpc).await?);
}

// 4. Swap instruction is unchanged
ixs.push(sdk.swap_ix(&swap_params)?);
```

***

## The LightProgramInterface trait

Each rent-free AMM SDK exposes this trait. It tells you which accounts an instruction
touches and how to build load specs for cold ones.

```rust theme={null}
pub trait LightProgramInterface {
    type Variant: Pack<AccountMeta> + Clone + Debug;
    type Instruction;

    fn program_id() -> Pubkey;
    fn instruction_accounts(&self, ix: &Self::Instruction) -> Vec<Pubkey>;
    fn load_specs(
        &self,
        cold_accounts: &[AccountInterface],
    ) -> Result<Vec<AccountSpec<Self::Variant>>, Box<dyn Error>>;
}
```

* `instruction_accounts` -- returns the pubkeys the instruction reads/writes.
* `load_specs` -- given cold `AccountInterface`s (with `ColdContext`), returns the `AccountSpec`s
  that `create_load_instructions` needs to bring them back on-chain.

***

## Full example

### Dependencies

```toml theme={null}
[dependencies]
light-client = {version = "0.18.0", features = ["v2"]}

# AMM SDK that implements LightProgramInterface (provided by the AMM team)
example-amm-sdk = "0.1"
```

### Code

```rust expandable theme={null}
use light_client::interface::{create_load_instructions, LightProgramInterface};
use example_amm_sdk::{ExampleAmmSdk, AmmInstruction};

// Construct SDK from pool data (same as before -- pool data is always available,
// hot or cold, via get_account_interface or your cache).
let sdk = ExampleAmmSdk::new(pool_address, pool_data)?;

// Quote works the same regardless of hot/cold.
let quote = sdk.quote(amount_in, min_out)?;

// Build transaction.
let mut ixs = vec![];

// Check if any swap accounts are cold.
let pubkeys = sdk.instruction_accounts(&AmmInstruction::Swap);
let cold_pubkeys: Vec<_> = pubkeys.iter().filter(|p| cold_set.contains(p)).collect();

if !cold_pubkeys.is_empty() {
    // Fetch ColdContext for cold accounts.
    let interfaces = rpc
        .get_multiple_account_interfaces(cold_pubkeys, None)
        .await?
        .value;
    let cold: Vec<_> = interfaces.into_iter().flatten().collect();
    let specs = sdk.load_specs(&cold)?;
    ixs.extend(create_load_instructions(&specs, payer.pubkey(), config_pda, &rpc).await?);
}

// Swap instruction is the same as without rent-free accounts.
ixs.push(sdk.swap_ix(&swap_params)?);

rpc.send_transaction(&ixs, &payer).await?;
```

### Key types

| Type                    | Source         | Purpose                                  |
| ----------------------- | -------------- | ---------------------------------------- |
| `AccountInterface`      | `light-client` | Account data with optional `ColdContext` |
| `LightProgramInterface` | `light-client` | Trait that AMM SDKs implement            |
| `AccountSpec`           | `light-client` | Input to `create_load_instructions`      |

### Reference implementation

| Resource                         | Link                                                                                                             |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| AMM Program                      | [cp-swap-reference](https://github.com/Lightprotocol/cp-swap-reference)                                          |
| LightProgramInterface Trait Impl | [CpSwapSdk](https://github.com/Lightprotocol/cp-swap-reference/blob/main/programs/cp-swap/tests/program.rs#L409) |

***

## Hot vs Cold

|          | Hot    | Cold                |
| -------- | ------ | ------------------- |
| On-chain | Yes    | Ledger (compressed) |
| Quote    | Works  | Works               |
| Swap     | Direct | Load first / Bundle |
| Latency  | Normal | +0-200ms\*          |
| Tx size  | Normal | +100-2400 bytes\*   |
| CU       | Normal | +15k-400k CU\*      |

*Depends on the number and type of cold accounts.*

### When does a market go cold?

Accounts go cold after extended inactivity. Their virtual rent balance drops
below a threshold and miners compress them onto the Solana ledger.

They stay cold until any client loads them back in-flight via `create_load_instructions`.

**Touching cold markets is rare.** The hot path has zero overhead.

***

## FAQ

<Accordion title="Do I need to change my swap instructions?">
  No. Swap instructions are identical. If the market is hot, the transaction
  is the same as today. If cold, you prepend `create_load_instructions`.
</Accordion>

<Accordion title="Can I quote cold markets?">
  Yes. `get_account_interface` returns full account data regardless of hot/cold.
  Quoting works the same.
</Accordion>

<Accordion title="Do rent-free markets increase latency?">
  **Hot (common path)**: No.

  **Cold**: Loading accounts adds 1-200ms depending on whether a validity proof
  is needed. If load + swap exceed Solana's 1232 byte limit, use Jito bundles.
</Accordion>

<Accordion title="How long do accounts stay hot after loading?">
  Until they go inactive again. Each write resets the timer. The inactivity
  threshold is configurable by the program owner (e.g. 24h of no writes).
</Accordion>

<Accordion title="What if load + swap exceed Solana's tx size limit?">
  Send as a Jito bundle:

  ```rust expandable theme={null}
  use solana_sdk::{instruction::Instruction, pubkey::Pubkey, system_instruction};

  const JITO_TIP_ACCOUNTS: &[&str] = &[
      "96gYZGLnJYVFmbjzopPSU6QiEV5fGqZNyN9nmNhvrZU5",
      "HFqU5x63VTqvQss8hp11i4wVV8bD44PvwucfZ2bU7gRe",
      "Cw8CFyM9FkoMi7K7Crf6HNQqf4uEMzpKw6QNghXLvLkY",
      "ADaUMid9yfUytqMBgopwjb2DTLSokTSzL1zt6iGPaS49",
      "DfXygSm4jCyNCybVYYK6DwvWqjKee8pbDmJGcLWNDXjh",
      "ADuUkR4vqLUMWXxW9gh6D6L8pMSawimctcNZ5pGwDcEt",
      "DttWaMuVvTiduZRnguLF7jNxTgiMBZ1hyAumKUiL2KRL",
      "3AVi9Tg9Uo68tJfuvoKvqKNWKkC5wPdSSdeBnizKZ6jT",
  ];

  fn jito_tip_ix(payer: &Pubkey, tip_lamports: u64) -> Instruction {
      let tip_account = JITO_TIP_ACCOUNTS[rand::random::<usize>() % JITO_TIP_ACCOUNTS.len()]
          .parse::<Pubkey>().unwrap();
      system_instruction::transfer(payer, &tip_account, tip_lamports)
  }

  let tip_ix = jito_tip_ix(&payer.pubkey(), 10_000);
  swap_ixs.push(tip_ix);

  let bundle = vec![load_tx_base64, swap_tx_base64];
  let resp = client
      .post("https://mainnet.block-engine.jito.wtf/api/v1/bundles")
      .json(&serde_json::json!({
          "jsonrpc": "2.0",
          "id": 1,
          "method": "sendBundle",
          "params": [bundle, {"encoding": "base64"}]
      }))
      .send().await?;
  ```
</Accordion>

<Accordion title="Do RPC providers support get_account_interface?">
  Yes. Supported by Helius and Triton. Can also be self-hosted via the
  <a href="https://github.com/helius-labs/photon">open-source Photon indexer</a>.
</Accordion>

<Accordion title="What if the indexer is down?">
  Hot markets work as long as Solana is up. Cold accounts can't be loaded until
  the indexer recovers. Compression is cryptographically verifiable -- integrity
  doesn't depend on the indexer.
</Accordion>

<Accordion title="I don't stream. Can I still support cold markets?">
  Yes. At swap time, call `get_multiple_account_interfaces` for the instruction's
  accounts and check `is_cold()`. This adds a round-trip per swap but requires
  no streaming setup.
</Accordion>

***

<Callout type="info">
  API is in Beta and subject to change.

  Questions or need hands-on support? [Telegram](https://t.me/swen_light) | [email](mailto:support@lightprotocol.com) | [Discord](https://discord.com/invite/7cJ8BhAXhu)
</Callout>


# Client examples
Source: https://www.zkcompression.com/light-token/examples/client

TypeScript and Rust client examples for light-token SDK.

Find all examples on Github: [examples-light-token](https://github.com/Lightprotocol/examples-light-token)

### TypeScript

|                        |                                                                                                                           |                                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **approve**            | [Action](https://github.com/Lightprotocol/examples-light-token/blob/main/typescript-client/actions/delegate-approve.ts)   | —                                                                                                                                   |
| **create-ata**         | [Action](https://github.com/Lightprotocol/examples-light-token/blob/main/typescript-client/actions/create-ata.ts)         | [Instruction](https://github.com/Lightprotocol/examples-light-token/blob/main/typescript-client/instructions/create-ata.ts)         |
| **create-mint**        | [Action](https://github.com/Lightprotocol/examples-light-token/blob/main/typescript-client/actions/create-mint.ts)        | [Instruction](https://github.com/Lightprotocol/examples-light-token/blob/main/typescript-client/instructions/create-mint.ts)        |
| **load-ata**           | [Action](https://github.com/Lightprotocol/examples-light-token/blob/main/typescript-client/actions/load-ata.ts)           | [Instruction](https://github.com/Lightprotocol/examples-light-token/blob/main/typescript-client/instructions/load-ata.ts)           |
| **mint-to**            | [Action](https://github.com/Lightprotocol/examples-light-token/blob/main/typescript-client/actions/mint-to.ts)            | [Instruction](https://github.com/Lightprotocol/examples-light-token/blob/main/typescript-client/instructions/mint-to.ts)            |
| **revoke**             | [Action](https://github.com/Lightprotocol/examples-light-token/blob/main/typescript-client/actions/delegate-revoke.ts)    | —                                                                                                                                   |
| **transfer-interface** | [Action](https://github.com/Lightprotocol/examples-light-token/blob/main/typescript-client/actions/transfer-interface.ts) | [Instruction](https://github.com/Lightprotocol/examples-light-token/blob/main/typescript-client/instructions/transfer-interface.ts) |
| **unwrap**             | [Action](https://github.com/Lightprotocol/examples-light-token/blob/main/typescript-client/actions/unwrap.ts)             | [Instruction](https://github.com/Lightprotocol/examples-light-token/blob/main/typescript-client/instructions/unwrap.ts)             |
| **wrap**               | [Action](https://github.com/Lightprotocol/examples-light-token/blob/main/typescript-client/actions/wrap.ts)               | [Instruction](https://github.com/Lightprotocol/examples-light-token/blob/main/typescript-client/instructions/wrap.ts)               |

### Rust

|                          |                                                                                                                                  |                                                                                                                                            |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **approve**              | [Action](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/actions/approve.rs)                         | [Instruction](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/instructions/approve.rs)                         |
| **burn**                 | —                                                                                                                                | [Instruction](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/instructions/burn.rs)                            |
| **burn-checked**         | —                                                                                                                                | [Instruction](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/instructions/burn_checked.rs)                    |
| **close**                | —                                                                                                                                | [Instruction](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/instructions/close.rs)                           |
| **create-ata**           | [Action](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/actions/create_associated_token_account.rs) | [Instruction](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/instructions/create_associated_token_account.rs) |
| **create-mint**          | [Action](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/actions/create_mint.rs)                     | [Instruction](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/instructions/create_mint.rs)                     |
| **create-token-account** | —                                                                                                                                | [Instruction](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/instructions/create_token_account.rs)            |
| **freeze**               | —                                                                                                                                | [Instruction](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/instructions/freeze.rs)                          |
| **mint-to**              | [Action](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/actions/mint_to.rs)                         | [Instruction](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/instructions/mint_to.rs)                         |
| **mint-to-checked**      | —                                                                                                                                | [Instruction](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/instructions/mint_to_checked.rs)                 |
| **revoke**               | [Action](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/actions/revoke.rs)                          | [Instruction](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/instructions/revoke.rs)                          |
| **spl-to-light**         | —                                                                                                                                | [Instruction](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/instructions/spl_to_light_transfer.rs)           |
| **thaw**                 | —                                                                                                                                | [Instruction](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/instructions/thaw.rs)                            |
| **transfer-checked**     | [Action](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/actions/transfer_checked.rs)                | [Instruction](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/instructions/transfer_checked.rs)                |
| **transfer-interface**   | [Action](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/actions/transfer_interface.rs)              | [Instruction](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/instructions/transfer_interface.rs)              |
| **unwrap**               | [Action](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/actions/unwrap.rs)                          | —                                                                                                                                          |
| **wrap**                 | [Action](https://github.com/Lightprotocol/examples-light-token/blob/main/rust-client/actions/wrap.rs)                            | —                                                                                                                                          |


# Program examples
Source: https://www.zkcompression.com/light-token/examples/program

Anchor program examples for light-token CPI.

Find all examples on Github: [examples-light-token](https://github.com/Lightprotocol/examples-light-token)

### Examples

|                                                                                                                            | Description                                                            |
| -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [cp-swap-reference](https://github.com/Lightprotocol/cp-swap-reference)                                                    | Fork of Raydium AMM that creates markets without paying rent-exemption |
| [create-and-transfer](https://github.com/Lightprotocol/examples-light-token/tree/main/programs/anchor/create-and-transfer) | Create account via macro and transfer via CPI                          |

### Macros

|                                                                                                                                            | Description                              |
| ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------- |
| [counter](https://github.com/Lightprotocol/examples-light-token/tree/main/programs/anchor/basic-macros/counter)                            | Create PDA with sponsored rent-exemption |
| [create-associated-token-account](https://github.com/Lightprotocol/examples-light-token/tree/main/programs/anchor/basic-macros/create-ata) | Create associated light-token account    |
| [create-mint](https://github.com/Lightprotocol/examples-light-token/tree/main/programs/anchor/basic-macros/create-mint)                    | Create light-token mint                  |
| [create-token-account](https://github.com/Lightprotocol/examples-light-token/tree/main/programs/anchor/basic-macros/create-token-account)  | Create light-token account               |

### Instructions

The instructions use pure CPI calls which you can combine with existing and / or light macros.
For existing programs, you can replace spl\_token with light\_token instructions as you need. The API is a superset of SPL-token so switching is straightforward.

|                                                                                                                                                             | Description                                                 |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| [approve](https://github.com/Lightprotocol/examples-light-token/blob/main/programs/anchor/basic-instructions/approve/src/lib.rs)                            | Approve delegate via CPI                                    |
| [burn](https://github.com/Lightprotocol/examples-light-token/blob/main/programs/anchor/basic-instructions/burn/src/lib.rs)                                  | Burn tokens via CPI                                         |
| [close](https://github.com/Lightprotocol/examples-light-token/blob/main/programs/anchor/basic-instructions/close/src/lib.rs)                                | Close token account via CPI                                 |
| [create-associated-token-account](https://github.com/Lightprotocol/examples-light-token/blob/main/programs/anchor/basic-instructions/create-ata/src/lib.rs) | Create associated light-token account via CPI               |
| [create-mint](https://github.com/Lightprotocol/examples-light-token/blob/main/programs/anchor/basic-instructions/create-mint/src/lib.rs)                    | Create light-token mint via CPI                             |
| [create-token-account](https://github.com/Lightprotocol/examples-light-token/blob/main/programs/anchor/basic-instructions/create-token-account/src/lib.rs)  | Create light-token account via CPI                          |
| [freeze](https://github.com/Lightprotocol/examples-light-token/blob/main/programs/anchor/basic-instructions/freeze/src/lib.rs)                              | Freeze token account via CPI                                |
| [mint-to](https://github.com/Lightprotocol/examples-light-token/blob/main/programs/anchor/basic-instructions/mint-to/src/lib.rs)                            | Mint tokens via CPI                                         |
| [revoke](https://github.com/Lightprotocol/examples-light-token/blob/main/programs/anchor/basic-instructions/revoke/src/lib.rs)                              | Revoke delegate via CPI                                     |
| [thaw](https://github.com/Lightprotocol/examples-light-token/blob/main/programs/anchor/basic-instructions/thaw/src/lib.rs)                                  | Thaw token account via CPI                                  |
| [transfer-checked](https://github.com/Lightprotocol/examples-light-token/blob/main/programs/anchor/basic-instructions/transfer-checked/src/lib.rs)          | Transfer with mint validation via CPI                       |
| [transfer-interface](https://github.com/Lightprotocol/examples-light-token/blob/main/programs/anchor/basic-instructions/transfer-interface/src/lib.rs)      | Transfer between light-token, T22, and SPL accounts via CPI |


# FAQ
Source: https://www.zkcompression.com/light-token/faq

Frequently asked questions about light-token.

#### What is light-token?

Light token is a high-performance token standard that is functionally equivalent to SPL, but stores mint and token accounts more efficiently. This reduces account creation cost while being more CU efficient than SPL on hot paths.

**Creation Cost**

|                   |     Light-Token |  SPL-Token |
| :---------------- | --------------: | ---------: |
| **Mint Account**  | **0.00001 SOL** | 0.0015 SOL |
| **Token Account** | **0.00001 SOL** |  0.002 SOL |

**CU Performance**

|                          | Light-Token | SPL-Token |
| :----------------------- | ----------: | --------: |
| **ATA Creation**         |   **4,348** |    14,194 |
| **Transfer**             |     **312** |     4,645 |
| **Transfer** (rent-free) |   **1,885** |     4,645 |

#### Can I start using the Light Token Standard?

Yes! Light Token is deployed on devnet — start integrating today with our [Quickstart](/light-token/quickstart) and [Toolkits](/light-token/toolkits/overview).

For production on mainnet, use [Compressed Tokens V1](/compressed-tokens/overview), which are live and supported by leading wallets such as Phantom and Backpack.

#### Do I need to change my client code significantly?

No. The `light-token-sdk` methods are a superset of the SPL-token API.
Find examples below.

<CodeCompare />

<table>
  <thead>
    <tr>
      <th />

      <th>Light</th>
      <th>SPL</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**Get/Create ATA**</td>
      <td>getOrCreateAtaInterface()</td>
      <td>getOrCreateAssociatedTokenAccount()</td>
    </tr>

    <tr>
      <td>**Derive ATA**</td>
      <td>getAssociatedTokenAddressInterface()</td>
      <td>getAssociatedTokenAddress()</td>
    </tr>

    <tr>
      <td>**Transfer**</td>
      <td>transferInterface()</td>
      <td>transferChecked()</td>
    </tr>

    <tr>
      <td>**Get Balance**</td>
      <td>getAtaInterface()</td>
      <td>getAccount()</td>
    </tr>
  </tbody>
</table>

***

#### Can light-token accounts hold SPL tokens?

Yes, light-token accounts can hold tokens from light, SPL, or Token 2022 mints.

SPL tokens can be deposited into light-token accounts and withdrawn back to SPL token accounts via the `transferInterface` method.

#### Do light-token accounts require rent?

The token standard pays rent-exemption cost for you. To prevent griefing, "rent" is paid over time to keep an account in memory. This is dealt with under the hood in a way that doesn't disrupt the UX of what your users are used to with SPL-token.

1. The Light Token Program pays the rent-exemption cost for the account.
2. Transaction fee payers bump a virtual rent balance when writing to the account, which keeps the account "hot".
3. "Cold" accounts virtual rent balance below threshold (eg 24h without write bump) get auto-compressed.
4. The cold account's state is cryptographically preserved on the Solana ledger.
   Users can load a cold account into hot state in-flight when using the account
   again.

<RentLifecycleVisualizer />

#### What happens if my light-token account runs out of rent?

The account is automatically compressed.
Your tokens are cryptographically preserved as a compressed token account (rent-free).
The account is loaded into hot account state in-flight when someone interacts with it again.

#### Does light-token support extensions?

Extensions are under development. Additional extensions can be requested.

Coming soon:

* MetadataPointer
* TokenMetadata
* InterestBearingConfig
* GroupPointer
* GroupMemberPointer
* TokenGroup
* TokenGroupMember
* MintCloseAuthority
* TransferFeeConfig
* DefaultAccountState
* PermanentDelegate
* TransferHook
* Pausable
* ConfidentialTransferMint
* ConfidentialTransferFeeConfig
* ConfidentialMintBurn

#### What is the difference between light-token and compressed token?

* **light-token**: Solana account that holds token balances of light-mints, SPL or Token 22 mints.
* **Compressed token**: Compressed account storing token data. Rent-free, for storage and distribution.

#### I don't see the question I want answered

DM us [@lightprotocol on X (Twitter)](http://x.com/lightprotocol) or [Discord](https://discord.com/invite/rpddh53TeG).

### Get Started

<CardGroup>
  <Card title="Toolkits" icon="toolbox" href="/light-token/toolkits">
    Guides for dedicated use cases
  </Card>

  <Card title="Cookbook" icon="book" href="/light-token/cookbook">
    Step-by-step recipes
  </Card>
</CardGroup>


# Quickstart
Source: https://www.zkcompression.com/light-token/quickstart

Mint tokens to a Light-ATA in under 3 minutes.

<Steps>
  <Step>
    ## Prerequisites

    <Accordion title="Installation">
      <Tabs>
        <Tab title="npm">
          Install packages in your working directory:

          ```bash theme={null}
          npm install @lightprotocol/stateless.js@beta \
                      @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          npm install -g @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>

        <Tab title="yarn">
          Install packages in your working directory:

          ```bash theme={null}
          yarn add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          yarn global add @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>

        <Tab title="pnpm">
          Install packages in your working directory:

          ```bash theme={null}
          pnpm add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          pnpm add -g @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>
      </Tabs>
    </Accordion>

    <Tabs>
      <Tab title="Localnet">
        ```bash theme={null}
        # start local test-validator in a separate terminal
        light test-validator
        ```

        <Note>
          In the code examples, use `createRpc()` without arguments for localnet.
        </Note>
      </Tab>

      <Tab title="Devnet">
        Get an API key from [Helius](https://helius.dev) and add to `.env`:

        ```bash title=".env" theme={null}
        API_KEY=<your-helius-api-key>
        ```

        <Note>
          In the code examples, use `createRpc(RPC_URL)` with the devnet URL.
        </Note>
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ## Mint Tokens to Light-ATA

    ```typescript theme={null}
    import "dotenv/config";
    import { Keypair } from "@solana/web3.js";
    import { createRpc } from "@lightprotocol/stateless.js";
    import {
        createMintInterface,
        createAtaInterface,
        mintToInterface,
        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 recipient = Keypair.generate();
        await createAtaInterface(rpc, payer, mint, recipient.publicKey);

        const destination = getAssociatedTokenAddressInterface(mint, recipient.publicKey);
        const tx = await mintToInterface(rpc, payer, mint, destination, payer, 1_000_000_000);

        console.log("Tx:", tx);
    })();
    ```
  </Step>
</Steps>

# Next Steps

<CardGroup>
  <Card title="Toolkits" icon="toolbox" href="/light-token/toolkits">
    Guides for dedicated use cases
  </Card>

  <Card title="Cookbook" icon="book" href="/light-token/cookbook">
    Step-by-step recipes
  </Card>
</CardGroup>


# Toolkit for Stablecoin Payments
Source: https://www.zkcompression.com/light-token/toolkits/for-payments

Guide to integrate light-token APIs with comparison to SPL.

1. The light-token API matches the SPL-token API almost entirely, and extends their functionality to include the light token program in addition to the SPL-token and Token-2022 programs.
2. Your users receive the same stablecoin, just stored more efficiently.

| Creation Cost     | SPL                  | light-token           |
| :---------------- | :------------------- | :-------------------- |
| **Token Account** | \~2,000,000 lamports | \~**11,000** lamports |

### What you will implement

<table>
  <thead>
    <tr>
      <th />

      <th>SPL</th>
      <th>Light</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**Get/Create ATA**</td>
      <td>getOrCreateAssociatedTokenAccount()</td>
      <td>getOrCreateAtaInterface()</td>
    </tr>

    <tr>
      <td>**Derive ATA**</td>
      <td>getAssociatedTokenAddress()</td>
      <td>getAssociatedTokenAddressInterface()</td>
    </tr>

    <tr>
      <td>**Transfer**</td>
      <td>transferChecked()</td>
      <td>transferInterface()</td>
    </tr>

    <tr>
      <td>**Get Balance**</td>
      <td>getAccount()</td>
      <td>getAtaInterface()</td>
    </tr>

    <tr>
      <td>**Tx History**</td>
      <td>getSignaturesForAddress()</td>
      <td>rpc.getSignaturesForOwnerInterface()</td>
    </tr>

    <tr>
      <td>**Wrap from SPL**</td>
      <td>N/A</td>
      <td>wrap()</td>
    </tr>

    <tr>
      <td>**Unwrap to SPL**</td>
      <td>N/A</td>
      <td>unwrap()</td>
    </tr>
  </tbody>
</table>

<Note>
  Find full code examples
  [here](https://github.com/Lightprotocol/examples-light-token/tree/main/toolkits/payments-and-wallets).
</Note>

## Setup

```bash theme={null}
npm install @lightprotocol/compressed-token@beta \
            @lightprotocol/stateless.js@beta
```

```typescript theme={null}
import { createRpc } from "@lightprotocol/stateless.js";

import {
  getOrCreateAtaInterface,
  getAtaInterface,
  getAssociatedTokenAddressInterface,
  transferInterface,
  wrap,
  unwrap,
} from "@lightprotocol/compressed-token/unified";

const rpc = createRpc(RPC_ENDPOINT);
```

### Receive Payments

<Note>
  Find a full code example [here](https://github.com/Lightprotocol/examples-light-token/blob/main/toolkits/payments-and-wallets/send-and-receive.ts).
</Note>

<Tabs>
  <Tab title="Instruction">
    ```typescript theme={null}
    import { Transaction } from "@solana/web3.js";
    import {
      createAssociatedTokenAccountInterfaceIdempotentInstruction,
      createLoadAtaInstructions,
      getAssociatedTokenAddressInterface,
    } from "@lightprotocol/compressed-token/unified";
    import { LIGHT_TOKEN_PROGRAM_ID } from "@lightprotocol/stateless.js";

    const ata = getAssociatedTokenAddressInterface(mint, recipient);

    const tx = new Transaction().add(
      createAssociatedTokenAccountInterfaceIdempotentInstruction(
        payer.publicKey,
        ata,
        recipient,
        mint,
        LIGHT_TOKEN_PROGRAM_ID
      ),
      ...(await createLoadAtaInstructions(
        rpc,
        ata,
        recipient,
        mint,
        payer.publicKey
      ))
    );
    ```

    <Accordion title="Compare to SPL">
      ```typescript theme={null}
      import {
        createAssociatedTokenAccountInstruction,
        getAssociatedTokenAddressSync,
      } from "@solana/spl-token";

      const ata = getAssociatedTokenAddressSync(mint, recipient);

      const tx = new Transaction().add(
        createAssociatedTokenAccountInstruction(payer.publicKey, ata, recipient, mint)
      );
      ```
    </Accordion>
  </Tab>

  <Tab title="Action helper">
    ```typescript theme={null}
    import { getOrCreateAtaInterface } from "@lightprotocol/compressed-token/unified";

    const ata = await getOrCreateAtaInterface(rpc, payer, mint, recipient);
    // Share ata.parsed.address with sender

    console.log(ata.parsed.amount);
    ```

    <Accordion title="Compare to SPL">
      ```typescript theme={null}
      import { getOrCreateAssociatedTokenAccount } from "@solana/spl-token";

      const ata = await getOrCreateAssociatedTokenAccount(
        connection,
        payer,
        mint,
        recipient
      );
      // Share ata.address with sender

      console.log(ata.amount);
      ```
    </Accordion>
  </Tab>
</Tabs>

### Send Payments

<Note>
  Find a full code example [here](https://github.com/Lightprotocol/examples-light-token/blob/main/toolkits/payments-and-wallets/send-and-receive.ts).
</Note>

<Tabs>
  <Tab title="Instruction">
    ```typescript theme={null}
    import { Transaction } from "@solana/web3.js";
    import {
      createLoadAtaInstructions,
      createTransferInterfaceInstruction,
      getAssociatedTokenAddressInterface,
    } from "@lightprotocol/compressed-token/unified";

    const sourceAta = getAssociatedTokenAddressInterface(mint, owner.publicKey);
    const destinationAta = getAssociatedTokenAddressInterface(mint, recipient);

    const tx = new Transaction().add(
      ...(await createLoadAtaInstructions(
        rpc,
        sourceAta,
        owner.publicKey,
        mint,
        payer.publicKey
      )),
      createTransferInterfaceInstruction(
        sourceAta,
        destinationAta,
        owner.publicKey,
        amount
      )
    );
    ```

    To ensure your recipient's ATA exists, prepend an idempotent creation instruction:

    ```typescript theme={null}
    import { Transaction } from "@solana/web3.js";
    import {
      createAssociatedTokenAccountInterfaceIdempotentInstruction,
      createLoadAtaInstructions,
      createTransferInterfaceInstruction,
      getAssociatedTokenAddressInterface,
    } from "@lightprotocol/compressed-token/unified";
    import { LIGHT_TOKEN_PROGRAM_ID } from "@lightprotocol/stateless.js";

    const sourceAta = getAssociatedTokenAddressInterface(mint, owner.publicKey);
    const destinationAta = getAssociatedTokenAddressInterface(mint, recipient);

    const tx = new Transaction().add(
      createAssociatedTokenAccountInterfaceIdempotentInstruction(
        payer.publicKey,
        destinationAta,
        recipient,
        mint,
        LIGHT_TOKEN_PROGRAM_ID
      ),
      ...(await createLoadAtaInstructions(
        rpc,
        sourceAta,
        owner.publicKey,
        mint,
        payer.publicKey
      )),
      createTransferInterfaceInstruction(
        sourceAta,
        destinationAta,
        owner.publicKey,
        amount
      )
    );
    ```

    <Accordion title="Compare to SPL">
      ```typescript theme={null}
      import {
        getAssociatedTokenAddressSync,
        createTransferInstruction,
      } from "@solana/spl-token";

      const sourceAta = getAssociatedTokenAddressSync(mint, owner.publicKey);
      const destinationAta = getAssociatedTokenAddressSync(mint, recipient);

      const tx = new Transaction().add(
        createTransferInstruction(sourceAta, destinationAta, owner.publicKey, amount)
      );
      ```

      With idempotent ATA creation:

      ```typescript theme={null}
      import {
        getAssociatedTokenAddressSync,
        createAssociatedTokenAccountIdempotentInstruction,
        createTransferInstruction,
      } from "@solana/spl-token";

      const sourceAta = getAssociatedTokenAddressSync(mint, owner.publicKey);
      const destinationAta = getAssociatedTokenAddressSync(mint, recipient);

      const tx = new Transaction().add(
        createAssociatedTokenAccountIdempotentInstruction(
          payer.publicKey,
          destinationAta,
          recipient,
          mint
        ),
        createTransferInstruction(sourceAta, destinationAta, owner.publicKey, amount)
      );
      ```
    </Accordion>
  </Tab>

  <Tab title="Action helper">
    ```typescript theme={null}
    import {
      getAssociatedTokenAddressInterface,
      transferInterface,
    } from "@lightprotocol/compressed-token/unified";

    const sourceAta = getAssociatedTokenAddressInterface(mint, owner.publicKey);
    const destinationAta = getAssociatedTokenAddressInterface(mint, recipient);

    await transferInterface( 
      payer,
      sourceAta,
      mint,
      destinationAta,
      owner,
      amount
    );
    ```

    To ensure your recipient's ATA exists before transferring:

    ```typescript theme={null}
    import {
      getOrCreateAtaInterface,
      transferInterface,
      getAssociatedTokenAddressInterface,
    } from "@lightprotocol/compressed-token/unified";

    // Ensure recipient ATA exists (creates if needed)
    await getOrCreateAtaInterface(rpc, payer, mint, recipient);

    // Then transfer
    const sourceAta = getAssociatedTokenAddressInterface(mint, owner.publicKey);
    const destinationAta = getAssociatedTokenAddressInterface(mint, recipient);
    await transferInterface(
      rpc,
      payer,
      sourceAta,
      mint,
      destinationAta,
      owner,
      amount
    );
    ```

    <Accordion title="Compare to SPL">
      ```typescript theme={null}
      import {
        getAssociatedTokenAddressSync,
        getOrCreateAssociatedTokenAccount,
        transfer,
      } from "@solana/spl-token";

      // Ensure recipient ATA exists
      await getOrCreateAssociatedTokenAccount(connection, payer, mint, recipient);

      // Then transfer
      const sourceAta = getAssociatedTokenAddressSync(mint, owner.publicKey);
      const destinationAta = getAssociatedTokenAddressSync(mint, recipient);
      await transfer(
        connection,
        payer,
        sourceAta,
        destinationAta,
        owner,
        amount,
        decimals
      );
      ```
    </Accordion>
  </Tab>
</Tabs>

### Show Balance

<Note>
  Find a full code example [here](https://github.com/Lightprotocol/examples-light-token/blob/main/toolkits/payments-and-wallets/get-balance.ts).
</Note>

```typescript theme={null}
import {
  getAssociatedTokenAddressInterface,
  getAtaInterface,
} from "@lightprotocol/compressed-token/unified";

const ata = getAssociatedTokenAddressInterface(mint, owner);
const account = await getAtaInterface(rpc, ata, owner, mint);

console.log(account.parsed.amount);
```

<Accordion title="Compare to SPL">
  ```typescript theme={null}
  import { getAccount } from "@solana/spl-token";

  const account = await getAccount(connection, ata);

  console.log(account.amount);
  ```
</Accordion>

### Transaction History

<Note>
  Find a full code example [here](https://github.com/Lightprotocol/examples-light-token/blob/main/toolkits/payments-and-wallets/get-history.ts).
</Note>

```typescript theme={null}
const result = await rpc.getSignaturesForOwnerInterface(owner);

console.log(result.signatures); // All signatures
```

Use `getSignaturesForAddressInterface(address)` if you want address-specific rather than owner-wide history.

<Accordion title="Compare to SPL">
  ```typescript theme={null}
  const signatures = await connection.getSignaturesForAddress(ata);
  ```
</Accordion>

### Wrap from SPL

Wrap tokens from SPL/Token-2022 accounts to light-token ATA.

<Note>
  Find a full code example [here](https://github.com/Lightprotocol/examples-light-token/blob/main/toolkits/payments-and-wallets/wrap.ts).
</Note>

<Tabs>
  <Tab title="Instruction">
    ```typescript theme={null}
    import { Transaction } from "@solana/web3.js";
    import { getAssociatedTokenAddressSync } from "@solana/spl-token";
    import {
      createWrapInstruction,
      getAssociatedTokenAddressInterface,
    } from "@lightprotocol/compressed-token/unified";
    import { getSplInterfaceInfos } from "@lightprotocol/compressed-token";

    const splAta = getAssociatedTokenAddressSync(mint, owner.publicKey);
    const tokenAta = getAssociatedTokenAddressInterface(mint, owner.publicKey);

    const splInterfaceInfos = await getSplInterfaceInfos(rpc, mint);
    const splInterfaceInfo = splInterfaceInfos.find((i) => i.isInitialized);

    const tx = new Transaction().add(
      createWrapInstruction(
        splAta,
        tokenAta,
        owner.publicKey,
        mint,
        amount,
        splInterfaceInfo,
        decimals
      )
    );
    ```
  </Tab>

  <Tab title="Action helper">
    ```typescript theme={null}
    import { getAssociatedTokenAddressSync } from "@solana/spl-token";
    import {
      wrap,
      getAssociatedTokenAddressInterface,
    } from "@lightprotocol/compressed-token/unified";

    // SPL ATA with tokens to wrap
    const splAta = getAssociatedTokenAddressSync(mint, owner.publicKey);
    // light-token ATA destination
    const tokenAta = getAssociatedTokenAddressInterface(mint, owner.publicKey);

    await wrap(rpc, payer, splAta, tokenAta, owner, mint, amount);
    ```
  </Tab>
</Tabs>

### Unwrap to SPL

You can compose with applications that do not yet support the light-token
standard by unwrapping your tokens.

Unwrap moves the token balance from a light-token account to a SPL-token account.

<Note>
  Find a full code example [here](https://github.com/Lightprotocol/examples-light-token/blob/main/toolkits/payments-and-wallets/unwrap.ts).
</Note>

<Tabs>
  <Tab title="Instruction">
    ```typescript theme={null}
    import { Transaction } from "@solana/web3.js";
    import { getAssociatedTokenAddressSync } from "@solana/spl-token";
    import {
      createLoadAtaInstructions,
      createUnwrapInstruction,
      getAssociatedTokenAddressInterface,
    } from "@lightprotocol/compressed-token/unified";
    import { getSplInterfaceInfos } from "@lightprotocol/compressed-token";

    const tokenAta = getAssociatedTokenAddressInterface(mint, owner.publicKey);
    const splAta = getAssociatedTokenAddressSync(mint, owner.publicKey);

    const splInterfaceInfos = await getSplInterfaceInfos(rpc, mint);
    const splInterfaceInfo = splInterfaceInfos.find((i) => i.isInitialized);

    const tx = new Transaction().add(
      ...(await createLoadAtaInstructions(
        rpc,
        tokenAta,
        owner.publicKey,
        mint,
        payer.publicKey
      )),
      createUnwrapInstruction(
        tokenAta,
        splAta,
        owner.publicKey,
        mint,
        amount,
        splInterfaceInfo,
        decimals
      )
    );
    ```
  </Tab>

  <Tab title="Action helper">
    ```typescript theme={null}
    import { getAssociatedTokenAddressSync } from "@solana/spl-token";

    // SPL ATA must exist
    const splAta = getAssociatedTokenAddressSync(mint, owner.publicKey);

    await unwrap(rpc, payer, splAta, owner, mint, amount);
    ```
  </Tab>
</Tabs>


# Streaming Mint Accounts
Source: https://www.zkcompression.com/light-token/toolkits/for-streaming-mints

Stream light-mint accounts and metadata via Laserstream.

| Event                    | Description                             |
| :----------------------- | :-------------------------------------- |
| **New mints**            | Raw mint data                           |
| **Mint updates**         | Supply changes, authority changes       |
| **TokenMetadata**        | Name, symbol, URI, additional\_metadata |
| **Cold/hot transitions** | Mint compressed or decompressed         |

<Note>
  This guide is for teams building custom data pipelines (aggregators, market makers).
  If you just need account lookups, use [`get_account_interface`](/light-token/defi/routers) instead.
</Note>

## Architecture

Light mints are Solana accounts owned by the Light Token Program. The streaming
setup requires two gRPC subscriptions:

| Subscription                                          | Detects                 | How                                      |
| :---------------------------------------------------- | :---------------------- | :--------------------------------------- |
| Account sub (`owner: cToken...`, `account_type == 1`) | Hot state + cold-to-hot | Pubkey cache lookup                      |
| Transaction sub (`account_include: cToken...`)        | Hot-to-cold             | Balance heuristic (`pre > 0, post == 0`) |

The account subscription delivers all state changes while mints are hot.
The transaction subscription is needed to detect mints going cold
(`CompressAndCloseMint` changes the owner to System Program, which the account
subscription no longer matches).

## Setup

```toml Cargo.toml theme={null}
[dependencies]
helius-laserstream = "0.1"
tokio = { version = "1", features = ["full"] }
futures = "0.3"
bs58 = "0.5"
borsh = "0.10"
light-token-interface = "0.3.0"
```

```rust theme={null}
use borsh::BorshDeserialize;
use futures::StreamExt;
use helius_laserstream::grpc::subscribe_request_filter_accounts_filter::Filter;
use helius_laserstream::grpc::subscribe_request_filter_accounts_filter_memcmp::Data;
use helius_laserstream::grpc::{
    SubscribeRequestFilterAccounts, SubscribeRequestFilterAccountsFilter,
    SubscribeRequestFilterAccountsFilterMemcmp, SubscribeRequestFilterTransactions,
};
use helius_laserstream::{subscribe, LaserstreamConfig};
use light_token_interface::state::{ExtensionStruct, Mint};

const LIGHT_TOKEN_PROGRAM_ID: &str = "cTokenmWW8bLPjZEBAUgYy3zKxQZW6VKi7bqNFEVv3m";
const ACCOUNT_TYPE_OFFSET: u64 = 165;
```

<Steps>
  <Step>
    ### Connect

    <Tabs>
      <Tab title="Mainnet">
        ```rust theme={null}
        let config = LaserstreamConfig::new(
            "https://laserstream-mainnet-ewr.helius-rpc.com".to_string(),
            std::env::var("HELIUS_API_KEY")?,
        );
        ```
      </Tab>

      <Tab title="Devnet">
        ```rust theme={null}
        let config = LaserstreamConfig::new(
            "https://laserstream-devnet-ewr.helius-rpc.com".to_string(),
            std::env::var("HELIUS_API_KEY")?,
        );
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Subscribe

    ```rust theme={null}
    let mut request = helius_laserstream::grpc::SubscribeRequest::default();

    // 1. Account sub: mint state tracking + cold-to-hot detection.
    //    account_type == 1 (Mint) at byte offset 165.
    request.accounts.insert(
        "light_mints".to_string(),
        SubscribeRequestFilterAccounts {
            owner: vec![LIGHT_TOKEN_PROGRAM_ID.to_string()],
            filters: vec![SubscribeRequestFilterAccountsFilter {
                filter: Some(Filter::Memcmp(SubscribeRequestFilterAccountsFilterMemcmp {
                    offset: ACCOUNT_TYPE_OFFSET,
                    data: Some(Data::Bytes(vec![1])),
                })),
            }],
            nonempty_txn_signature: Some(true),
            ..Default::default()
        },
    );

    // 2. Transaction sub: hot-to-cold detection.
    request.transactions.insert(
        "light_token_txns".to_string(),
        SubscribeRequestFilterTransactions {
            vote: Some(false),
            failed: Some(false),
            account_include: vec![LIGHT_TOKEN_PROGRAM_ID.to_string()],
            ..Default::default()
        },
    );

    let (stream, _handle) = subscribe(config, request);
    tokio::pin!(stream);
    ```
  </Step>

  <Step>
    ### Deserialize mint accounts

    ```rust theme={null}
    use helius_laserstream::grpc::subscribe_update::UpdateOneof;

    Some(UpdateOneof::Account(account_update)) => {
        if let Some(account_info) = account_update.account {
            let pubkey: [u8; 32] = account_info.pubkey.as_slice().try_into().unwrap();

            match Mint::deserialize(&mut account_info.data.as_slice()) {
                Ok(mint) => {
                    cold_cache.remove(&pubkey); // no longer cold
                    cache.insert(pubkey, mint);
                }
                Err(e) => {
                    eprintln!(
                        "Failed to deserialize mint {}: {}",
                        bs58::encode(&pubkey).into_string(),
                        e
                    );
                }
            }
        }
    }
    ```
  </Step>

  <Step>
    ### Detect mints going cold

    Two data structures:

    * `cache: HashMap<[u8; 32], T>` -- hot account state (for quoting/routing)
    * `cold_cache: HashMap<[u8; 32], AccountInterface>` -- cold accounts with `ColdContext` (for building load instructions)

    ```rust theme={null}
    use helius_laserstream::grpc::subscribe_update::UpdateOneof;

    Some(UpdateOneof::Transaction(tx_update)) => {
        if let Some(ref tx_info) = tx_update.transaction {
            for pubkey in find_closed_accounts(tx_info) {
                if cache.remove(&pubkey).is_some() {
                    // Async: fetch AccountInterface with ColdContext.
                    // Cold accounts are inactive, so this completes well
                    // before anyone tries to swap through them.
                    let rpc = rpc.clone();
                    let cold_cache = cold_cache.clone();
                    tokio::spawn(async move {
                        if let Ok(Some(iface)) = rpc.get_account_interface(&pubkey, None).await {
                            cold_cache.insert(pubkey, iface);
                        }
                    });
                }
            }
        }
    }
    ```

    ```rust theme={null}
    fn find_closed_accounts(
        tx_info: &helius_laserstream::grpc::SubscribeUpdateTransactionInfo,
    ) -> Vec<[u8; 32]> {
        let meta = match &tx_info.meta {
            Some(m) => m,
            None => return vec![],
        };
        let msg = match tx_info.transaction.as_ref().and_then(|t| t.message.as_ref()) {
            Some(m) => m,
            None => return vec![],
        };

        let mut all_keys: Vec<&[u8]> = msg.account_keys.iter().map(|k| k.as_slice()).collect();
        all_keys.extend(meta.loaded_writable_addresses.iter().map(|k| k.as_slice()));
        all_keys.extend(meta.loaded_readonly_addresses.iter().map(|k| k.as_slice()));

        let mut closed = Vec::new();
        for (i, key) in all_keys.iter().enumerate() {
            if key.len() == 32
                && meta.pre_balances.get(i).copied().unwrap_or(0) > 0
                && meta.post_balances.get(i).copied().unwrap_or(1) == 0
            {
                closed.push(<[u8; 32]>::try_from(*key).unwrap());
            }
        }
        closed
    }
    ```

    `cache.remove` filters out unrelated closures in the same transaction. No discriminator
    check is needed -- `compress_and_close` always drains lamports to zero.

    To build transactions that decompress cold accounts, see
    [Router Integration](/light-token/defi/routers).
  </Step>

  <Step>
    ### Extract TokenMetadata

    ```rust theme={null}
    fn extract_metadata(mint: &Mint) -> Option<(String, String, String)> {
        let extensions = mint.extensions.as_ref()?;

        for ext in extensions {
            if let ExtensionStruct::TokenMetadata(m) = ext {
                let name = String::from_utf8_lossy(&m.name).to_string();
                let symbol = String::from_utf8_lossy(&m.symbol).to_string();
                let uri = String::from_utf8_lossy(&m.uri).to_string();
                return Some((name, symbol, uri));
            }
        }
        None
    }
    ```
  </Step>
</Steps>

## Data Layouts

### Mint

```rust theme={null}
#[repr(C)]
pub struct Mint {
    pub base: BaseMint,
    pub metadata: MintMetadata,
    pub reserved: [u8; 16],
    pub account_type: u8,
    pub compression: CompressionInfo,
    pub extensions: Option<Vec<ExtensionStruct>>,
}

#[repr(C)]
pub struct BaseMint {
    pub mint_authority: Option<Pubkey>,
    pub supply: u64,
    pub decimals: u8,
    pub is_initialized: bool,
    pub freeze_authority: Option<Pubkey>,
}

#[repr(C)]
pub struct MintMetadata {
    pub version: u8,
    pub mint_decompressed: bool,
    pub mint: Pubkey,
    pub mint_signer: [u8; 32],
    pub bump: u8,
}
```

### TokenMetadata

```rust theme={null}
#[repr(C)]
pub struct TokenMetadata {
    pub update_authority: Pubkey,  // [0u8; 32] = immutable
    pub mint: Pubkey,
    pub name: Vec<u8>,
    pub symbol: Vec<u8>,
    pub uri: Vec<u8>,
    pub additional_metadata: Vec<AdditionalMetadata>,
}

pub struct AdditionalMetadata {
    pub key: Vec<u8>,
    pub value: Vec<u8>,
}
```

<Card title="Streaming Token Accounts" icon="chevron-right" href="/light-token/toolkits/for-streaming-tokens" />


# Streaming Token Accounts
Source: https://www.zkcompression.com/light-token/toolkits/for-streaming-tokens

Stream light-token accounts via Laserstream. Same base layout as SPL Token.

<Note>
  This guide is for teams building custom data pipelines (aggregators, market makers).
  If you just need account lookups, use [`get_account_interface`](/light-token/defi/routers) instead.
</Note>

## Architecture

Light token accounts share the same base layout as SPL Token (165 bytes), so you can
use your existing parser. The streaming setup requires two gRPC subscriptions, both
targeting the Light Token Program:

| Subscription                                   | Detects                 | How                                      |
| :--------------------------------------------- | :---------------------- | :--------------------------------------- |
| Account sub (`owner: cToken...`)               | Hot state + cold-to-hot | Pubkey cache lookup                      |
| Transaction sub (`account_include: cToken...`) | Hot-to-cold             | Balance heuristic (`pre > 0, post == 0`) |

The account subscription delivers all state changes while accounts are hot.
The transaction subscription is needed to detect accounts going cold
(`compress_and_close` changes the owner to System Program, which the account
subscription no longer matches).

## Parsing

```rust theme={null}
use spl_pod::bytemuck::pod_from_bytes;
use spl_token_2022_interface::pod::PodAccount; // works for SPL-token, SPL-token-2022, and Light-token

let parsed: &PodAccount = pod_from_bytes(&data[..165])?;
```

For accounts with extensions, truncate to 165 bytes before parsing.

## Streaming

```toml Cargo.toml theme={null}
[dependencies]
helius-laserstream = "0.1"
tokio = { version = "1", features = ["full"] }
futures = "0.3"
bs58 = "0.5"
borsh = "0.10"
light-token-interface = "0.3.0"
```

```rust theme={null}
use futures::StreamExt;
use helius_laserstream::grpc::subscribe_request_filter_accounts_filter::Filter;
use helius_laserstream::grpc::subscribe_request_filter_accounts_filter_memcmp::Data;
use helius_laserstream::grpc::{
    SubscribeRequestFilterAccounts, SubscribeRequestFilterAccountsFilter,
    SubscribeRequestFilterAccountsFilterMemcmp, SubscribeRequestFilterTransactions,
};
use helius_laserstream::{subscribe, LaserstreamConfig};

const LIGHT_TOKEN_PROGRAM_ID: &str = "cTokenmWW8bLPjZEBAUgYy3zKxQZW6VKi7bqNFEVv3m";
const TOKEN_ACCOUNT_SIZE: u64 = 165;
const ACCOUNT_TYPE_OFFSET: u64 = 165;
const ACCOUNT_TYPE_TOKEN: u8 = 2;
```

<Steps>
  <Step>
    ### Connect

    <Tabs>
      <Tab title="Mainnet">
        ```rust theme={null}
        let config = LaserstreamConfig::new(
            "https://laserstream-mainnet-ewr.helius-rpc.com".to_string(),
            std::env::var("HELIUS_API_KEY")?,
        );
        ```
      </Tab>

      <Tab title="Devnet">
        ```rust theme={null}
        let config = LaserstreamConfig::new(
            "https://laserstream-devnet-ewr.helius-rpc.com".to_string(),
            std::env::var("HELIUS_API_KEY")?,
        );
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Subscribe

    ```rust theme={null}
    let mut request = helius_laserstream::grpc::SubscribeRequest::default();

    // 1. Account sub: hot state tracking + cold-to-hot detection.
    request.accounts.insert(
        "light_tokens".to_string(),
        SubscribeRequestFilterAccounts {
            owner: vec![LIGHT_TOKEN_PROGRAM_ID.to_string()],
            filters: vec![SubscribeRequestFilterAccountsFilter {
                filter: Some(Filter::Datasize(TOKEN_ACCOUNT_SIZE)),
            }],
            nonempty_txn_signature: Some(true),
            ..Default::default()
        },
    );
    request.accounts.insert(
        "light_tokens_extended".to_string(),
        SubscribeRequestFilterAccounts {
            owner: vec![LIGHT_TOKEN_PROGRAM_ID.to_string()],
            filters: vec![SubscribeRequestFilterAccountsFilter {
                filter: Some(Filter::Memcmp(SubscribeRequestFilterAccountsFilterMemcmp {
                    offset: ACCOUNT_TYPE_OFFSET,
                    data: Some(Data::Bytes(vec![ACCOUNT_TYPE_TOKEN])),
                })),
            }],
            nonempty_txn_signature: Some(true),
            ..Default::default()
        },
    );

    // 2. Transaction sub: hot-to-cold detection.
    request.transactions.insert(
        "light_token_txns".to_string(),
        SubscribeRequestFilterTransactions {
            vote: Some(false),
            failed: Some(false),
            account_include: vec![LIGHT_TOKEN_PROGRAM_ID.to_string()],
            ..Default::default()
        },
    );

    let (stream, _handle) = subscribe(config, request);
    tokio::pin!(stream);
    ```
  </Step>
</Steps>

## Detecting transitions

### Hot-to-cold

For each transaction update, find accounts whose lamport balance dropped to zero.
The `cache.remove` call ensures only accounts you're already tracking are processed:

Two data structures:

* `cache: HashMap<[u8; 32], T>` -- hot account state (for quoting/routing)
* `cold_cache: HashMap<[u8; 32], AccountInterface>` -- cold accounts with `ColdContext` (for building load instructions)

```rust theme={null}
use helius_laserstream::grpc::subscribe_update::UpdateOneof;

Some(UpdateOneof::Transaction(tx_update)) => {
    if let Some(ref tx_info) = tx_update.transaction {
        for pubkey in find_closed_accounts(tx_info) {
            if cache.remove(&pubkey).is_some() {
                // Async: fetch AccountInterface with ColdContext.
                // Cold accounts are inactive, so this completes well
                // before anyone tries to swap through them.
                let rpc = rpc.clone();
                let cold_cache = cold_cache.clone();
                tokio::spawn(async move {
                    if let Ok(Some(iface)) = rpc.get_account_interface(&pubkey, None).await {
                        cold_cache.insert(pubkey, iface);
                    }
                });
            }
        }
    }
}
```

```rust theme={null}
fn find_closed_accounts(
    tx_info: &helius_laserstream::grpc::SubscribeUpdateTransactionInfo,
) -> Vec<[u8; 32]> {
    let meta = match &tx_info.meta {
        Some(m) => m,
        None => return vec![],
    };
    let msg = match tx_info.transaction.as_ref().and_then(|t| t.message.as_ref()) {
        Some(m) => m,
        None => return vec![],
    };

    let mut all_keys: Vec<&[u8]> = msg.account_keys.iter().map(|k| k.as_slice()).collect();
    all_keys.extend(meta.loaded_writable_addresses.iter().map(|k| k.as_slice()));
    all_keys.extend(meta.loaded_readonly_addresses.iter().map(|k| k.as_slice()));

    let mut closed = Vec::new();
    for (i, key) in all_keys.iter().enumerate() {
        if key.len() == 32
            && meta.pre_balances.get(i).copied().unwrap_or(0) > 0
            && meta.post_balances.get(i).copied().unwrap_or(1) == 0
        {
            closed.push(<[u8; 32]>::try_from(*key).unwrap());
        }
    }
    closed
}
```

`cache.remove` filters out unrelated closures in the same transaction. No discriminator
check is needed -- `compress_and_close` always drains lamports to zero.

To build transactions that decompress cold accounts, see
[Router Integration](/light-token/defi/routers).

### Cold-to-hot

When a token account is decompressed, the account subscription delivers the
re-created account. Match its pubkey against `cold_cache`:

```rust theme={null}
Some(UpdateOneof::Account(account_update)) => {
    if let Some(account) = account_update.account {
        let pubkey: [u8; 32] = account.pubkey.as_slice().try_into().unwrap();
        let parsed: &PodAccount = pod_from_bytes(&account.data[..165])?;

        cold_cache.remove(&pubkey); // no longer cold
        cache.insert(pubkey, *parsed);
    }
}
```

## Point queries

`getAccountInfo` returns null for cold accounts. `get_account_interface()` races
hot and cold lookups and returns raw account bytes that work with your standard SPL parser:

```rust theme={null}
use light_client::rpc::{LightClient, LightClientConfig, Rpc};
use spl_pod::bytemuck::pod_from_bytes;
use spl_token_2022_interface::pod::PodAccount;

let config = LightClientConfig::new(
    "https://api.devnet.solana.com".to_string(),
    Some("https://photon.helius.com?api-key=YOUR_KEY".to_string()),
);
let client = LightClient::new(config).await?;
let result = client.get_account_interface(&pubkey, None).await?;

if let Some(account) = result.value {
    let parsed: &PodAccount = pod_from_bytes(&account.data()[..165])?;
    if account.is_cold() {
        // Compressed -- still valid for routing.
    }
}
```

## Data layout

165 bytes base, identical to SPL Token Account.

| Field              | Offset | Size |
| :----------------- | :----- | :--- |
| `mint`             | 0      | 32   |
| `owner`            | 32     | 32   |
| `amount`           | 64     | 8    |
| `delegate`         | 72     | 36   |
| `state`            | 108    | 1    |
| `is_native`        | 109    | 12   |
| `delegated_amount` | 121    | 8    |
| `close_authority`  | 129    | 36   |
| `account_type`     | 165    | 1    |

`account_type = 2` at byte 165 indicates extensions follow (borsh-encoded `Option<Vec<ExtensionStruct>>`).

<Expandable title="Light extensions">
  These are not needed for indexing or trading.

  ```rust theme={null}
  use borsh::BorshDeserialize;
  use light_token_interface::state::{Token, ExtensionStruct};

  let token = Token::deserialize(&mut data.as_slice())?;

  if let Some(exts) = &token.extensions {
      for ext in exts {
          if let ExtensionStruct::Compressible(info) = ext {
              // info.compression_authority, info.rent_sponsor, info.last_claimed_slot
          }
      }
  }
  ```

  | Variant                                                       | Description                                                   |
  | :------------------------------------------------------------ | :------------------------------------------------------------ |
  | `TokenMetadata(TokenMetadata)`                                | Name, symbol, URI, additional metadata                        |
  | `PausableAccount(PausableAccountExtension)`                   | Marker: mint is pausable (no data; pause state lives on mint) |
  | `PermanentDelegateAccount(PermanentDelegateAccountExtension)` | Marker: mint has permanent delegate                           |
  | `TransferFeeAccount(TransferFeeAccountExtension)`             | Withheld fees from transfers                                  |
  | `TransferHookAccount(TransferHookAccountExtension)`           | Marker: mint has transfer hook                                |
  | `CompressedOnly(CompressedOnlyExtension)`                     | Compressed-only token (stores delegated amount)               |
  | `Compressible(CompressibleExtension)`                         | Compression config: authority, rent sponsor, timing           |

  Source: [`light-token-interface`](https://github.com/Lightprotocol/light-protocol/tree/main/program-libs/token-interface/src/state/extensions)
</Expandable>

<Card title="Streaming Mint Accounts" icon="chevron-right" href="/light-token/toolkits/for-streaming-mints" />


# Toolkit for Wallet Applications
Source: https://www.zkcompression.com/light-token/toolkits/for-wallets

Guide for Wallet Applications to add Light-token support.

1. The Light-token API matches the SPL-token API almost entirely, and extends their functionality to include the light token program in addition to the SPL-token and Token-2022 programs.
2. Your users hold and receive tokens of the same mints, just stored more efficiently.

| Creation Cost     | SPL                  | Light-token           |
| :---------------- | :------------------- | :-------------------- |
| **Token Account** | \~2,000,000 lamports | \~**11,000** lamports |

### What you will implement

<table>
  <thead>
    <tr>
      <th />

      <th>SPL</th>
      <th>Light</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**Get/Create ATA**</td>
      <td>getOrCreateAssociatedTokenAccount()</td>
      <td>getOrCreateAtaInterface()</td>
    </tr>

    <tr>
      <td>**Derive ATA**</td>
      <td>getAssociatedTokenAddress()</td>
      <td>getAssociatedTokenAddressInterface()</td>
    </tr>

    <tr>
      <td>**Transfer**</td>
      <td>transferChecked()</td>
      <td>transferInterface()</td>
    </tr>

    <tr>
      <td>**Get Balance**</td>
      <td>getAccount()</td>
      <td>getAtaInterface()</td>
    </tr>

    <tr>
      <td>**Tx History**</td>
      <td>getSignaturesForAddress()</td>
      <td>rpc.getSignaturesForOwnerInterface()</td>
    </tr>

    <tr>
      <td>**Wrap from SPL**</td>
      <td>N/A</td>
      <td>wrap()</td>
    </tr>

    <tr>
      <td>**Unwrap to SPL**</td>
      <td>N/A</td>
      <td>unwrap()</td>
    </tr>
  </tbody>
</table>

<Note>
  Find full code examples
  [here](https://github.com/Lightprotocol/examples-light-token/tree/main/toolkits/payments-and-wallets).
</Note>

## Setup

```bash theme={null}
npm install @lightprotocol/compressed-token@beta \
            @lightprotocol/stateless.js@beta
```

```typescript theme={null}
import { createRpc } from "@lightprotocol/stateless.js";

import {
  getOrCreateAtaInterface,
  getAtaInterface,
  getAssociatedTokenAddressInterface,
  transferInterface,
  wrap,
  unwrap,
} from "@lightprotocol/compressed-token";

const rpc = createRpc(RPC_ENDPOINT);
```

### Receive Payments

<Note>
  Find a full code example [here](https://github.com/Lightprotocol/examples-light-token/blob/main/toolkits/payments-and-wallets/send-and-receive.ts).
</Note>

<Tabs>
  <Tab title="Instruction">
    ```typescript theme={null}
    import { Transaction } from "@solana/web3.js";
    import {
      createAssociatedTokenAccountInterfaceIdempotentInstruction,
      createLoadAtaInstructions,
      getAssociatedTokenAddressInterface,
    } from "@lightprotocol/compressed-token";
    import { LIGHT_TOKEN_PROGRAM_ID } from "@lightprotocol/stateless.js";

    const ata = getAssociatedTokenAddressInterface(mint, recipient);

    const tx = new Transaction().add(
      createAssociatedTokenAccountInterfaceIdempotentInstruction(
        payer.publicKey,
        ata,
        recipient,
        mint,
        LIGHT_TOKEN_PROGRAM_ID
      ),
      ...(await createLoadAtaInstructions(
        rpc,
        ata,
        recipient,
        mint,
        payer.publicKey
      ))
    );

    ```

    <Accordion title="Compare to SPL">
      ```typescript theme={null}
      import {
        createAssociatedTokenAccountInstruction,
        getAssociatedTokenAddressSync,
      } from "@solana/spl-token";

      const ata = getAssociatedTokenAddressSync(mint, recipient);

      const tx = new Transaction().add(
        createAssociatedTokenAccountInstruction(
          payer.publicKey,
          ata,
          recipient,
          mint
        )
      );
      ```
    </Accordion>
  </Tab>

  <Tab title="Action helper">
    ```typescript theme={null}
    import { getOrCreateAtaInterface } from "@lightprotocol/compressed-token";

    const ata = await getOrCreateAtaInterface(rpc, payer, mint, recipient);
    // Share ata.parsed.address with sender

    console.log(ata.parsed.amount);
    ```

    <Accordion title="Compare to SPL">
      ```typescript theme={null}
      import { getOrCreateAssociatedTokenAccount } from "@solana/spl-token";

      const ata = await getOrCreateAssociatedTokenAccount(
        connection,
        payer,
        mint,
        recipient
      );
      // Share ata.address with sender

      console.log(ata.amount);
      ```
    </Accordion>
  </Tab>
</Tabs>

### Send Payments

<Note>
  Find a full code example [here](https://github.com/Lightprotocol/examples-light-token/blob/main/toolkits/payments-and-wallets/send-and-receive.ts).
</Note>

<Tabs>
  <Tab title="Instruction">
    ```typescript theme={null}
    import { Transaction } from "@solana/web3.js";
    import {
      createLoadAtaInstructions,
      createTransferInterfaceInstruction,
      getAssociatedTokenAddressInterface,
    } from "@lightprotocol/compressed-token";

    const sourceAta = getAssociatedTokenAddressInterface(mint, owner.publicKey);
    const destinationAta = getAssociatedTokenAddressInterface(mint, recipient);

    const tx = new Transaction().add(
      ...(await createLoadAtaInstructions(
        rpc,
        sourceAta,
        owner.publicKey,
        mint,
        payer.publicKey
      )),
      createTransferInterfaceInstruction(
        sourceAta,
        destinationAta,
        owner.publicKey,
        amount
      )
    );
    ```

    <Accordion title="Compare to SPL">
      ```typescript theme={null}
      import {
        getAssociatedTokenAddressSync,
        createTransferInstruction,
      } from "@solana/spl-token";

      const sourceAta = getAssociatedTokenAddressSync(mint, owner.publicKey);
      const destinationAta = getAssociatedTokenAddressSync(mint, recipient);

      const tx = new Transaction().add(
        createTransferInstruction(sourceAta, destinationAta, owner.publicKey, amount)
      );
      ```
    </Accordion>
  </Tab>

  <Tab title="Action helper">
    ```typescript theme={null}
    import {
      getAssociatedTokenAddressInterface,
      transferInterface,
    } from "@lightprotocol/compressed-token";

    const sourceAta = getAssociatedTokenAddressInterface(mint, owner.publicKey);
    const destinationAta = getAssociatedTokenAddressInterface(mint, recipient);

    await transferInterface(
      rpc,
      payer,
      sourceAta,
      mint,
      destinationAta,
      owner,
      amount
    );
    ```

    To ensure your recipient's ATA exists you can prepend an idempotent creation instruction in the same atomic transaction:

    ```typescript theme={null}
    import {
      getAssociatedTokenAddressInterface,
      createAssociatedTokenAccountInterfaceIdempotentInstruction,
    } from "@lightprotocol/compressed-token";
    import { LIGHT_TOKEN_PROGRAM_ID } from "@lightprotocol/stateless.js";

    const destinationAta = getAssociatedTokenAddressInterface(mint, recipient);
    const createAtaIx = createAssociatedTokenAccountInterfaceIdempotentInstruction(
      payer.publicKey,
      destinationAta,
      recipient,
      mint,
      LIGHT_TOKEN_PROGRAM_ID
    );

    new Transaction().add(createAtaIx, transferIx);
    ```

    <Accordion title="Compare to SPL">
      ```typescript theme={null}
      import { transfer } from "@solana/spl-token";

      const sourceAta = getAssociatedTokenAddressSync(mint, owner.publicKey);
      const destinationAta = getAssociatedTokenAddressSync(mint, recipient);

      await transfer(
        connection,
        payer,
        sourceAta,
        destinationAta,
        owner,
        amount,
        decimals
      );
      ```

      With idempotent ATA creation:

      ```typescript theme={null}
      import {
        getAssociatedTokenAddressSync,
        createAssociatedTokenAccountIdempotentInstruction,
      } from "@solana/spl-token";

      const destinationAta = getAssociatedTokenAddressSync(mint, recipient);
      const createAtaIx = createAssociatedTokenAccountIdempotentInstruction(
        payer.publicKey,
        destinationAta,
        recipient,
        mint
      );

      new Transaction().add(createAtaIx, transferIx);
      ```
    </Accordion>
  </Tab>
</Tabs>

### Show Balance

<Note>
  Find a full code example [here](https://github.com/Lightprotocol/examples-light-token/blob/main/toolkits/payments-and-wallets/get-balance.ts).
</Note>

```typescript theme={null}
import {
  getAssociatedTokenAddressInterface,
  getAtaInterface,
} from "@lightprotocol/compressed-token";

const ata = getAssociatedTokenAddressInterface(mint, owner);
const account = await getAtaInterface(rpc, ata, owner, mint);

console.log(account.parsed.amount);
```

<Accordion title="Compare to SPL">
  ```typescript theme={null}
  import { getAccount } from "@solana/spl-token";

  const account = await getAccount(connection, ata);

  console.log(account.amount);
  ```
</Accordion>

### Transaction History

<Note>
  Find a full code example [here](https://github.com/Lightprotocol/examples-light-token/blob/main/toolkits/payments-and-wallets/get-history.ts).
</Note>

```typescript theme={null}
const result = await rpc.getSignaturesForOwnerInterface(owner);

console.log(result.signatures);
console.log(result.solana);
console.log(result.compressed);
```

Use `getSignaturesForAddressInterface(address)` if you want address-specific rather than owner-wide history.

<Accordion title="Compare to SPL">
  ```typescript theme={null}
  const signatures = await connection.getSignaturesForAddress(ata);
  ```
</Accordion>

### Wrap from SPL

Wrap tokens from SPL/Token-2022 accounts to light-token ATA.

<Note>
  Find a full code example [here](https://github.com/Lightprotocol/examples-light-token/blob/main/toolkits/payments-and-wallets/wrap.ts).
</Note>

<Tabs>
  <Tab title="Instruction">
    ```typescript theme={null}
    import { Transaction } from "@solana/web3.js";
    import { getAssociatedTokenAddressSync } from "@solana/spl-token";
    import {
      createWrapInstruction,
      getAssociatedTokenAddressInterface,
      getSplInterfaceInfos,
    } from "@lightprotocol/compressed-token";

    const splAta = getAssociatedTokenAddressSync(mint, owner.publicKey);
    const tokenAta = getAssociatedTokenAddressInterface(mint, owner.publicKey);

    const splInterfaceInfos = await getSplInterfaceInfos(rpc, mint);
    const splInterfaceInfo = splInterfaceInfos.find((i) => i.isInitialized);

    const tx = new Transaction().add(
      createWrapInstruction(
        splAta,
        tokenAta,
        owner.publicKey,
        mint,
        amount,
        splInterfaceInfo,
        decimals
      )
    );
    ```
  </Tab>

  <Tab title="Action helper">
    ```typescript theme={null}
    import { getAssociatedTokenAddressSync } from "@solana/spl-token";
    import {
      wrap,
      getAssociatedTokenAddressInterface,
    } from "@lightprotocol/compressed-token";

    // SPL ATA with tokens to wrap
    const splAta = getAssociatedTokenAddressSync(mint, owner.publicKey);
    // light-token ATA destination
    const tokenAta = getAssociatedTokenAddressInterface(mint, owner.publicKey);

    await wrap(rpc, payer, splAta, tokenAta, owner, mint, amount);
    ```
  </Tab>
</Tabs>

### Unwrap to SPL

You can compose with applications that do not yet support the light-token
standard by unwrapping your tokens.

Unwrap moves the token balance from a light-token account to a SPL-token account.

<Note>
  Find a full code example [here](https://github.com/Lightprotocol/examples-light-token/blob/main/toolkits/payments-and-wallets/unwrap.ts).
</Note>

<Tabs>
  <Tab title="Instruction">
    ```typescript theme={null}
    import { Transaction } from "@solana/web3.js";
    import { getAssociatedTokenAddressSync } from "@solana/spl-token";
    import {
      createLoadAtaInstructions,
      createUnwrapInstruction,
      getAssociatedTokenAddressInterface,
      getSplInterfaceInfos,
    } from "@lightprotocol/compressed-token";

    const tokenAta = getAssociatedTokenAddressInterface(mint, owner.publicKey);
    const splAta = getAssociatedTokenAddressSync(mint, owner.publicKey);

    const splInterfaceInfos = await getSplInterfaceInfos(rpc, mint);
    const splInterfaceInfo = splInterfaceInfos.find((i) => i.isInitialized);

    const tx = new Transaction().add(
      ...(await createLoadAtaInstructions(
        rpc,
        tokenAta,
        owner.publicKey,
        mint,
        payer.publicKey
      )),
      createUnwrapInstruction(
        tokenAta,
        splAta,
        owner.publicKey,
        mint,
        amount,
        splInterfaceInfo,
        decimals
      )
    );
    ```
  </Tab>

  <Tab title="Action helper">
    ```typescript theme={null}
    import { getAssociatedTokenAddressSync } from "@solana/spl-token";

    // SPL ATA must exist
    const splAta = getAssociatedTokenAddressSync(mint, owner.publicKey);

    await unwrap(rpc, payer, splAta, owner, mint, amount);
    ```
  </Tab>
</Tabs>


# Overview of Toolkits
Source: https://www.zkcompression.com/light-token/toolkits/overview

Integration toolkits for light-token on Solana.

<Card title="Stablecoin Payments" icon="credit-card" href="/light-token/toolkits/for-payments">
  Integrate light-token APIs with familiar SPL patterns.
</Card>

<Card title="Wallets" icon="wallet" href="/light-token/toolkits/for-wallets">
  Allow users to display and swap light-tokens.
</Card>


# The Light Token Program
Source: https://www.zkcompression.com/light-token/welcome

Light token is a high-performance token standard that reduces the cost of mint and token accounts by 200x.

<Info>
  **Note: This page is for the new Light Token Program Beta.** For production use today, use
  [Compressed Tokens](/compressed-tokens/overview), which are live on Solana Mainnet and supported
  by leading wallets such as Phantom & Backpack.
</Info>

### Creation Cost

|                   |     Light-Token |  SPL-Token |
| :---------------- | --------------: | ---------: |
| **Mint Account**  | **0.00001 SOL** | 0.0015 SOL |
| **Token Account** | **0.00001 SOL** |  0.002 SOL |

### CU Performance

|                          | Light-Token | SPL-Token |
| :----------------------- | ----------: | --------: |
| **ATA Creation**         |   **4,348** |    14,194 |
| **Transfer**             |     **312** |     4,645 |
| **Transfer** (rent-free) |   **1,885** |     4,645 |

<CardGroup>
  <Card title="Mint Accounts" icon="coins">
    Light-mint accounts represent a unique mint and optionally can store token-metadata.
    Functionally equivalent to SPL mints.
  </Card>

  <Card title="Token Accounts" icon="wallet">
    Light-token accounts can hold balances from any light, SPL, or Token-2022 mint, without the need
    to pay rent-exemption.
  </Card>
</CardGroup>

# Quickstart

<Steps>
  <Step>
    ### Installation

    <Tabs>
      <Tab title="npm">
        Install packages in your working directory:

        ```bash theme={null}
        npm install @lightprotocol/stateless.js@beta \
                    @lightprotocol/compressed-token@beta
        ```

        Install the CLI globally:

        ```bash theme={null}
        npm install -g @lightprotocol/zk-compression-cli@beta
        ```
      </Tab>

      <Tab title="yarn">
        Install packages in your working directory:

        ```bash theme={null}
        yarn add @lightprotocol/stateless.js@beta \
                 @lightprotocol/compressed-token@beta
        ```

        Install the CLI globally:

        ```bash theme={null}
        yarn global add @lightprotocol/zk-compression-cli@beta
        ```
      </Tab>

      <Tab title="pnpm">
        Install packages in your working directory:

        ```bash theme={null}
        pnpm add @lightprotocol/stateless.js@beta \
                 @lightprotocol/compressed-token@beta
        ```

        Install the CLI globally:

        ```bash theme={null}
        pnpm add -g @lightprotocol/zk-compression-cli@beta
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Get Started

    <Card title="Mint tokens in under 3 minutes." icon="bolt" href="/light-token/quickstart" />
  </Step>
</Steps>

## DeFi Integration

<CardGroup>
  <Card title="Program Integration" icon="code" href="/light-token/defi/programs">
    Build rent-free AMMs and DeFi programs with minimal code changes.
  </Card>

  <Card title="Router Integration" icon="route" href="/light-token/defi/routers">
    Add support for rent-free AMMs to your aggregator or router.
  </Card>
</CardGroup>

## Integration Toolkits

|                                                                   |                                                            |
| :---------------------------------------------------------------- | :--------------------------------------------------------- |
| [for Stablecoin Payments](/light-token/toolkits/for-payments)     | Process payments and transfers using light-token           |
| [for Wallets](/light-token/toolkits/for-wallets)                  | Allow your users to store and swap tokens more efficiently |
| [for Streaming Mints](/light-token/toolkits/for-streaming-mints)  | Stream light-mint accounts                                 |
| [for Indexing Tokens](/light-token/toolkits/for-streaming-tokens) | Index light-token accounts                                 |

## Cookbook

<table>
  <colgroup>
    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <a href="/light-token/cookbook/create-mint">Create Mint</a>
      </td>

      <td>Create light-mints with token metadata</td>
    </tr>

    <tr>
      <td>
        <a href="/light-token/cookbook/create-ata">Create ATA</a>
      </td>

      <td>Create associated light-token accounts</td>
    </tr>

    <tr>
      <td>
        <a href="/light-token/cookbook/create-token-account">Create Token Account</a>
      </td>

      <td>Create light-token accounts</td>
    </tr>

    <tr>
      <td>
        <a href="/light-token/cookbook/mint-to">Mint To</a>
      </td>

      <td>Mint tokens to light-token accounts</td>
    </tr>

    <tr>
      <td>
        <a href="/light-token/cookbook/close-token-account">Close Token Account</a>
      </td>

      <td>Close token account to reclaim remaining lamports</td>
    </tr>

    <tr>
      <td>
        <a href="/light-token/cookbook/transfer-interface">Transfer</a>
      </td>

      <td>Transfer between Light Token, SPL and Token 2022 accounts</td>
    </tr>

    <tr>
      <td>
        <a href="/light-token/cookbook/transfer-checked">Transfer Checked</a>
      </td>

      <td>Transfer between Light Token accounts with decimals verification</td>
    </tr>

    <tr>
      <td>
        <a href="/light-token/cookbook/burn">Burn</a>
      </td>

      <td>Burn tokens from light-token accounts</td>
    </tr>

    <tr>
      <td>
        <a href="/light-token/cookbook/freeze-thaw">Freeze & Thaw</a>
      </td>

      <td>Freeze and thaw light-token accounts</td>
    </tr>

    <tr>
      <td>
        <a href="/light-token/cookbook/approve-revoke">Approve & Revoke</a>
      </td>

      <td>Delegate and revoke token authority</td>
    </tr>

    <tr>
      <td>
        <a href="/light-token/cookbook/wrap-unwrap">Wrap & Unwrap</a>
      </td>

      <td>Convert between SPL/Token 2022 and light-token</td>
    </tr>

    <tr>
      <td>
        <a href="/light-token/cookbook/load-ata">Load ATA</a>
      </td>

      <td>Load cold light-token accounts to hot balance for transfers in one instruction</td>
    </tr>
  </tbody>
</table>

# Next Steps

<Card title="Explore Frequently Answered Questions" icon="chevron-right" href="/light-token/faq" />


# Quickstart
Source: https://www.zkcompression.com/quickstart

Create your first compressed tokens in under 5 minutes.

<Steps>
  <Step>
    ## Prerequisites

    <Accordion title="Installation">
      <Tabs>
        <Tab title="npm">
          Install packages in your working directory:

          ```bash theme={null}
          npm install @lightprotocol/stateless.js@beta \
                      @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          npm install -g @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>

        <Tab title="yarn">
          Install packages in your working directory:

          ```bash theme={null}
          yarn add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          yarn global add @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>

        <Tab title="pnpm">
          Install packages in your working directory:

          ```bash theme={null}
          pnpm add @lightprotocol/stateless.js@beta \
                   @lightprotocol/compressed-token@beta
          ```

          Install the CLI globally:

          ```bash theme={null}
          pnpm add -g @lightprotocol/zk-compression-cli@beta
          ```
        </Tab>
      </Tabs>
    </Accordion>

    <Tabs>
      <Tab title="Localnet">
        ```bash theme={null}
        # start local test-validator in a separate terminal
        light test-validator
        ```

        <Note>
          In the code examples, use `createRpc()` without arguments for localnet.
        </Note>
      </Tab>

      <Tab title="Devnet">
        Get an API key from [Helius](https://helius.dev) and add to `.env`:

        ```bash title=".env" theme={null}
        API_KEY=<your-helius-api-key>
        ```

        <Note>
          In the code examples, use `createRpc(RPC_URL)` with the devnet URL.
        </Note>
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ## Mint Compressed Tokens

    ```typescript theme={null}
    // 1. Load wallet and connect to Localnet
    // 2. Create SPL mint with token pool for compression via createMint()
    // 3. Mint compressed tokens to recipient account via mintTo()
    // 4. Verify compressed token balance via getCompressedTokenAccountsByOwner

    import { createRpc } from "@lightprotocol/stateless.js";
    import { createMint, mintTo } from "@lightprotocol/compressed-token";
    import { Keypair } from "@solana/web3.js";
    import { readFileSync } from "fs";
    import { homedir } from "os";

    // Step 1: Load wallet from filesystem
    const payer = Keypair.fromSecretKey(
      new Uint8Array(JSON.parse(readFileSync(`${homedir()}/.config/solana/id.json`, "utf8")))
    );

    // Connect to local test-validator
    const RPC_ENDPOINT = "http://localhost:8899";
    const COMPRESSION_ENDPOINT = "http://localhost:8784";
    const PROVER_ENDPOINT = "http://localhost:3001";
    const connection = createRpc(RPC_ENDPOINT, COMPRESSION_ENDPOINT, PROVER_ENDPOINT);

    const main = async () => {
      try {
        // Step 2: Create SPL mint with token pool for compression
        console.log("\nCreating SPL mint with token pool for compression");
        const { mint, transactionSignature } = await createMint(
          connection,
          payer,
          payer.publicKey, // mintAuthority
          9
        );

        console.log(`Mint address: ${mint.toBase58()}`);
        console.log(
          `Create mint transaction: https://explorer.solana.com/tx/${transactionSignature}?cluster=custom&customUrl=http://localhost:8899`
        );

        // Step 3: Mint compressed tokens to recipient account
        console.log("\nMinting compressed token...");
        const mintAmount = 1000000000; // mintAmount with decimals
        const mintToTxId = await mintTo(
          connection,
          payer,
          mint, // SPL mint with token pool for compression
          payer.publicKey, // recipient.publicKey
          payer, // mintAuthority
          mintAmount
        );

        console.log(`Compressed Token minted ${mintAmount / 1e9} token`);
        console.log(
          `Transaction: https://explorer.solana.com/tx/${mintToTxId}?cluster=custom&customUrl=http://localhost:8899`
        );

        // Step 4: Verify compressed token balance via getCompressedTokenAccountsByOwner
        const tokenAccounts = await connection.getCompressedTokenAccountsByOwner(
          payer.publicKey,
          { mint } // SPL mint with token pool for compression
        );
      } catch (error: any) {
        console.error("Error:", error.message);
      }
    };

    main().catch(console.error);
    ```
  </Step>
</Steps>

# Next Steps

<Card title=" Learn more about compressed tokens." icon="chevron-right" href="/compressed-tokens" />


# Guide to Migrate from v1 to v2 Merkle trees
Source: https://www.zkcompression.com/references/migration-v1-to-v2

V2 reduces CU consumption by up to 70%. V1 remains supported for existing deployments.

## V2 Improvements

|                       | v1                    | v2                |
| --------------------- | --------------------- | ----------------- |
| CU consumption        | Baseline              | Up to 70% less    |
| Merkle tree type      | Concurrent            | Batched           |
| State tree depth      | 26 (\~67M leaves)     | 32 (\~4B leaves)  |
| Address tree depth    | 26                    | 40                |
| Address tree accounts | Separate tree + queue | Single batch tree |

<Tabs>
  <Tab title="Rust">
    ### Update Cargo.toml

    In 0.17.x onward, `v2` is a default feature of `light-sdk`. Make sure it stays enabled.

    <Info>
      When you specify `features = [...]` in Cargo.toml, Cargo **disables default features**.
      If you need extra features like `keccak` or `anchor`, either keep defaults explicitly
      or add `v2` to your features list:

      ```toml theme={null}
      # This DISABLES v2 (default features are off):
      light-sdk = { version = "0.17.1", features = ["keccak"] }

      # Either of these keeps v2 enabled:
      light-sdk = { version = "0.17.1", features = ["keccak", "v2"] }
      light-sdk = { version = "0.17.1", default-features = true, features = ["keccak"] }
      ```

      Without `v2`, `add_system_accounts_v2` and `cpi::v2` are not available.
    </Info>

    **On-chain program:**

    ```toml theme={null}
    [dependencies]
    light-sdk = "0.17.1"
    light-hasher = "5.0.0"
    ```

    For Anchor programs, add the `anchor` feature:

    ```toml theme={null}
    [dependencies]
    light-sdk = { version = "0.17.1", features = ["anchor"] }
    ```

    **Off-chain client:**

    ```toml theme={null}
    [dependencies]
    light-client = { version = "0.17.2", features = ["v2"] }
    ```

    ### Update imports

    ```rust theme={null}
    // v1
    use light_sdk::{
        address::v1::derive_address,
        constants::ADDRESS_TREE_V1,
        cpi::v1::{CpiAccounts, LightSystemProgramCpi},
    };
    ```

    ```rust theme={null}
    // v2
    use light_sdk::{
        address::v2::derive_address,
        cpi::v2::{CpiAccounts, LightSystemProgramCpi},
        constants::ADDRESS_TREE_V2,
    };
    ```

    ### Update address derivation

    The `derive_address` function signature remains the same, but the internal derivation logic differs. No code changes needed beyond updating the import path.

    ### Update address params

    Replace `into_new_address_params_packed()` with `into_new_address_params_assigned_packed()`:

    ```rust theme={null}
    // v1
    let new_address_params = instruction_data
        .address_tree_info
        .into_new_address_params_packed(address_seed);
    ```

    ```rust theme={null}
    // v2
    let new_address_params = instruction_data
        .address_tree_info
        .into_new_address_params_assigned_packed(address_seed, Some(0));
    ```

    The second parameter specifies the output queue index. Use `Some(0)` to assign the address to the first available queue.

    ### Update tree validation

    If your program validates the address tree pubkey, update the constant:

    ```rust theme={null}
    // v1
    if address_tree_pubkey.to_bytes() != ADDRESS_TREE_V1 {
        return Err(ProgramError::InvalidAccountData);
    }
    ```

    ```rust theme={null}
    // v2
    if address_tree_pubkey.to_bytes() != ADDRESS_TREE_V2 {
        return Err(ProgramError::InvalidAccountData);
    }
    ```

    ### Update client-side account packing

    ```rust theme={null}
    use light_sdk::instruction::{PackedAccounts, SystemAccountMetaConfig};

    let config = SystemAccountMetaConfig::new(YOUR_PROGRAM_ID);
    let mut packed = PackedAccounts::default();
    ```

    ```rust theme={null}
    // v1
    packed.add_system_accounts(config)?;
    ```

    ```rust theme={null}
    // v2
    packed.add_system_accounts_v2(config)?;
    ```

    **Full v2 client example**

    ```rust theme={null}
    use light_client::rpc::{LightClient, LightClientConfig, Rpc, Indexer};
    use light_sdk::{
        address::v2::derive_address,
        instruction::{PackedAccounts, SystemAccountMetaConfig},
    };

    // 1. Build PackedAccounts with v2 system accounts
    let config = SystemAccountMetaConfig::new(YOUR_PROGRAM_ID);
    let mut packed = PackedAccounts::default();
    packed.add_system_accounts_v2(config)?;

    // 2. Fetch validity proof
    let address_tree = rpc.get_address_tree_v2();
    let (address, _) = derive_address(&[b"my_seed", &id], &address_tree.tree, &YOUR_PROGRAM_ID);

    let rpc_result = rpc
        .get_validity_proof(
            vec![],
            vec![AddressWithTree { address, tree: address_tree.tree }],
            None,
        )
        .await?
        .value;

    // 3. Pack tree infos into remaining accounts
    let tree_infos = rpc_result.pack_tree_infos(&mut packed);
    let address_tree_info = tree_infos.address_trees[0];

    // 4. Pack output state tree
    let state_tree = rpc.get_random_state_tree_info()?;
    let output_state_tree_index = state_tree.pack_output_tree_index(&mut packed)?;

    // 5. Convert to account metas for the instruction
    let (remaining_accounts, _system_offset, _packed_offset) = packed.to_account_metas();
    ```

    ### Update client code (light-client)

    ```rust theme={null}
    use light_client::rpc::{LightClient, LightClientConfig, Rpc};

    let rpc_url = "https://mainnet.helius-rpc.com/?api-key=YOUR_KEY".to_string();
    let photon_url = "https://mainnet.helius-rpc.com".to_string();
    let api_key = "YOUR_KEY".to_string();

    let config = LightClientConfig::new(rpc_url, Some(photon_url), Some(api_key));
    let mut rpc = LightClient::new(config).await?;
    ```

    **Tree info methods:**

    ```rust theme={null}
    // v1
    let address_tree = rpc.get_address_tree_v1();
    let state_tree = rpc.get_random_state_tree_info_v1()?;
    ```

    ```rust theme={null}
    // v2
    let address_tree = rpc.get_address_tree_v2();
    let state_tree = rpc.get_random_state_tree_info()?; // returns v2 when feature enabled
    ```

    **Validity proofs:**

    ```rust theme={null}
    // get_validity_proof automatically uses v2 endpoint (default)
    let proof_result = rpc
        .get_validity_proof(hashes, addresses_with_trees, None)
        .await?;
    ```
  </Tab>

  <Tab title="TypeScript">
    ### Update imports

    ```typescript theme={null}
    // v1
    import {
        deriveAddress,
        deriveAddressSeed,
        defaultTestStateTreeAccounts,
        PackedAccounts,
    } from "@lightprotocol/stateless.js";
    ```

    ```typescript theme={null}
    // v2
    import {
        deriveAddressV2,
        deriveAddressSeedV2,
        batchAddressTree,
        PackedAccounts,
        featureFlags,
        VERSION,
    } from "@lightprotocol/stateless.js";
    ```

    ### Enable v2 mode

    Set the feature flag before making any calls:

    ```typescript theme={null}
    import { featureFlags, VERSION } from "@lightprotocol/stateless.js";

    (featureFlags as any).version = VERSION.V2;
    ```

    ### Update address derivation

    The seed and address derivation functions have different signatures in v2:

    ```typescript theme={null}
    // v1 - Program ID passed to seed derivation
    const seed = deriveAddressSeed(
        [counterSeed, signer.publicKey.toBytes()],
        new PublicKey(program.idl.address)
    );
    const address = deriveAddress(seed, addressTree);
    ```

    ```typescript theme={null}
    // v2 - Program ID passed to address derivation
    const seed = deriveAddressSeedV2([counterSeed, signer.publicKey.toBytes()]);
    const address = deriveAddressV2(
        seed,
        addressTree,
        new PublicKey(program.idl.address)
    );
    ```

    ### Update address tree references

    Use `batchAddressTree` instead of `defaultTestStateTreeAccounts().addressTree`:

    ```typescript theme={null}
    // v1
    const addressTree = defaultTestStateTreeAccounts().addressTree;
    const addressQueue = defaultTestStateTreeAccounts().addressQueue;

    // In proof request
    {
        tree: addressTree,
        queue: addressQueue,
        address: bn(address.toBytes()),
    }
    ```

    ```typescript theme={null}
    // v2 - queue equals tree for batch trees
    const addressTree = new PublicKey(batchAddressTree);

    // In proof request
    {
        tree: addressTree,
        queue: addressTree,
        address: bn(address.toBytes()),
    }
    ```

    ### Update PackedAccounts

    Use the v2 variant when building remaining accounts:

    ```typescript theme={null}
    // v1
    const remainingAccounts = PackedAccounts.newWithSystemAccounts(systemAccountConfig);
    ```

    ```typescript theme={null}
    // v2
    const remainingAccounts = PackedAccounts.newWithSystemAccountsV2(systemAccountConfig);
    ```
  </Tab>

  <Tab title="AI Prompt">
    ```text theme={null}
    ---
    argument-hint: <path_to_program>
    description: Migrate Light Protocol program from v1 to v2 Merkle trees
    allowed-tools: [Bash, Read, Glob, Grep, Task, WebFetch]
    ---

    Migrate this Light Protocol program from v1 to v2 Merkle trees.

    ## Goal

    Produce a **fully working migration** that builds and tests pass.

    ## Available commands

    Via Bash tool:
    - **cargo build-sbf**, **cargo test-sbf**, **cargo fmt**, **cargo clippy**
    - **anchor build**, **anchor test**
    - **grep**, **sed**

    ## Documentation

    - Migration Guide: https://zkcompression.com/references/migration-v1-to-v2
    - Reference PR: https://github.com/Lightprotocol/program-examples/commit/54f0e7f15c2972a078f776cfb40b238d83c7e486

    ## Reference repos

    program-examples/counter/anchor/
    ├── programs/counter/src/lib.rs    # v2 patterns: derive_address, CpiAccounts
    ├── Cargo.toml                      # v2 feature flags
    └── tests/counter.ts                # v2 client patterns

    ## Workflow

    ### Phase 1: Index program

    Find all v1 patterns:

        grep -r "::v1::" src/ tests/
        grep -r "ADDRESS_TREE_V1" src/
        grep -r "into_new_address_params_packed" src/
        grep -r "get_address_tree_v1" tests/

    ### Phase 2: Update dependencies

    Update Cargo.toml. V2 is the default - no feature flag needed:

        # On-chain program
        [dependencies]
        light-sdk = { version = "0.17.1", features = ["anchor"] }
        light-hasher = "5.0.0"

        # Off-chain client
        [dependencies]
        light-client = "0.17.2"

    Note: V2 is now the default in all crates. Only specify `features = ["v2"]` if you disabled default features.

    ### Phase 3: Rust SDK replacements

    | v1 Pattern | v2 Replacement |
    |------------|----------------|
    | address::v1::derive_address | address::v2::derive_address |
    | cpi::v1::CpiAccounts | cpi::v2::CpiAccounts |
    | cpi::v1::LightSystemProgramCpi | cpi::v2::LightSystemProgramCpi |
    | constants::ADDRESS_TREE_V1 | constants::ADDRESS_TREE_V2 |
    | .into_new_address_params_packed(seed) | .into_new_address_params_assigned_packed(seed, Some(0)) |
    | .add_system_accounts(config) | .add_system_accounts_v2(config) |

    ### Phase 4: TypeScript SDK replacements

    | v1 Pattern | v2 Replacement |
    |------------|----------------|
    | deriveAddress( | deriveAddressV2( |
    | deriveAddressSeed( | deriveAddressSeedV2( |
    | defaultTestStateTreeAccounts().addressTree | batchAddressTree |
    | .newWithSystemAccounts( | .newWithSystemAccountsV2( |
    | get_address_tree_v1() | get_address_tree_v2() |
    | get_random_state_tree_info_v1() | get_random_state_tree_info() |

    ### Phase 5: Build and test loop

    **Required commands (no shortcuts):**

    For Anchor programs: **anchor build && anchor test**

    For Native programs: **cargo build-sbf && cargo test-sbf**

    **NO shortcuts allowed:**

    - Do NOT use **cargo build** (must use **cargo build-sbf**)
    - Do NOT use **cargo test** (must use **cargo test-sbf**)
    - Tests MUST run against real BPF bytecode

    **On failure:** Spawn debugger agent with error context.

    **Loop rules:**

    1. Each debugger gets fresh context + previous debug reports
    2. Each attempt tries something DIFFERENT
    3. **NEVER GIVE UP** - keep spawning until fixed

    Do NOT proceed until all tests pass.

    ## DeepWiki fallback

    If no matching pattern in reference repos:

        mcp__deepwiki__ask_question("Lightprotocol/light-protocol", "How to migrate {pattern} from v1 to v2?")
    ```
  </Tab>
</Tabs>

## View Program Examples

<Card title="Program examples" icon="chevron-right" href="/compressed-pdas/program-examples" />


# Node Operators
Source: https://www.zkcompression.com/references/node-operators

Learn how to run ZK Compression infrastructure, such as Forester nodes, Photon indexers and Prover nodes.

<Check>
  Developers don't need to run any nodes to use ZK Compression.
</Check>

To connect to public networks (i.e., Devnet, Mainnet-Beta), you can either work with an RPC infrastructure provider that supports ZK Compression, such as [Helius Labs](https://helius.xyz/), or run your own nodes.

<Info>
  There are three different types of nodes:

  * Photon RPC nodes
  * Prover nodes
  * Light forester nodes
</Info>

#### Photon Indexer Node

Indexer nodes use an existing connection to a Solana RPC full node to parse the transactions involving Light Protocol programs, enabling clients to read and write zk-compressed state.

The canonical ZK Compression indexer is named Photon and is maintained by Helius Labs. It is fully open-source, and can be run locally. To set it up, simply point it to an existing Solana RPC. See the [Github repo](https://github.com/helius-labs/photon) for more info.

<Card title="GitHub - helius-labs/photon" href="https://github.com/helius-labs/photon" icon="github" />

#### Prover Node

Provers generate validity proofs for state inclusion and PDA uniqueness on behalf of app developers

**Prover nodes** can be operated either standalone or with an RPC node: in its default configuration, the Photon RPC node implementation by [Helius Labs](https://github.com/helius-labs/photon) bundles a Prover node. The ZK Compression RPC API specification supports proof generation via the `getValidityProof` endpoint, making it easy to serve proofs using regular RPC methods via the same port.

Please refer to the [Github repo](https://github.com/Lightprotocol/light-protocol/tree/a0379c3ac085c8e97914e8b456cf19f3d9172313/prover) for more info:

<Card title="https://github.com/Lightprotocol/light-protocol/tree/main/light-prover" href="https://github.com/Lightprotocol/light-protocol/tree/a0379c3ac085c8e97914e8b456cf19f3d9172313/prover" icon="github" />

#### Forester Node

These nodes manage the creation, rollover, and updating of shared and program-owned state trees. Running a forester node is permissionless for your own state trees.

<Card title="light-protocol/forester at main · Lightprotocol/light-protocol" href="https://github.com/Lightprotocol/light-protocol/tree/main/forester" icon="github" />


# Security
Source: https://www.zkcompression.com/references/security

Overview to Light Protocol's bug bounty program, third party security audits, and formal verification of circuits.

### Bug Bounty

Light Protocol is hosting a [bug bounty program](https://immunefi.com/bug-bounty/light-protocol/information/).

### Security Audits

The Light protocol on-chain programs were audited by independent security firms Neodyme, OtterSec, Accretion, and Zellic.

* [Accretion audit report](https://github.com/Lightprotocol/light-protocol/blob/main/audits/accretion_v1_update_audit.pdf) (January '25)
* [Zellic audit report](https://github.com/Lightprotocol/light-protocol/blob/main/audits/zellic_v1_audit.pdf) (September '24)
* [Neodyme audit report](https://github.com/Lightprotocol/light-protocol/blob/main/audits/neodyme_v1_audit.pdf) (August '24)
* [OtterSec audit report](https://github.com/Lightprotocol/light-protocol/blob/main/audits/ottersec_v1_audit.pdf) (July '24)

A complete list of 3rd party audits can be found [here](https://github.com/Lightprotocol/light-protocol/tree/main/audits).

### Groth16 Circuit Security

The ZK Compression circuit was formally verified by Reilabs. See the report [here](https://github.com/Lightprotocol/light-protocol/blob/main/audits/reilabs_circuits_formal_verification_report.pdf).

Information about the Trusted Setup Ceremony for the groth16 circuits is [here](https://github.com/Lightprotocol/gnark-mt-setup/blob/main/README.md).

<Info>
  **For additional information on Light Protocol's security policy, read** [**here**](https://github.com/Lightprotocol/light-protocol/blob/main/SECURITY.md)**.**
</Info>


# Terminology
Source: https://www.zkcompression.com/references/terminology

Overview to terminology related to ZK Compression and Solana

## Account

An entry in the Solana ledger that holds data or executable program code, stored on chain.

There are different kinds of accounts, including

* Data Accounts: Store arbitrary data used by programs.
* SPL Token Accounts: Manage token balances (similar to ERC-20 tokens on Ethereum).
* Program Accounts: Contain the executable code of a Solana program.

## Account Compression Program

Light Protocol's program that implements state and address trees for ZK Compression. The program provides the underlying Merkle tree infrastructure used by the Light System Program to manage compressed account state transitions.

<Info>
  **Source**: [https://github.com/Lightprotocol/light-protocol/tree/main/programs/account-compression](https://github.com/Lightprotocol/light-protocol/tree/main/programs/account-compression)
</Info>

## Address tree

A Merkle tree that stores derived addresses that serves as optional, persistent identifiers for compressed accounts. These addresses serve as persistent identifiers that don't change when account data updates.

Address trees are separate from state trees. Unlike state trees that store account hashes, address trees store actual address values in an indexed structure with pointers to maintain sorted order.

Two address tree versions are currently supported:

* **V1 address trees**: Height 26 (\~67 million addresses)
* **V2 batched address trees**: Height 40 (\~1 trillion addresses), optimizing compute unit consumption by up to 70%. V2 is currently on Devnet.

## [Client](https://solana.com/docs/core/transactions#client)

A computer program that accesses the Solana server network [cluster](https://solana.com/docs/core/transactions#cluster).

## [**Cluster**](https://solana.com/docs/references/terminology#cluster)

A set of [validators](https://solana.com/docs/references/terminology#validator) maintaining a single [ledger](https://solana.com/docs/references/terminology#ledger).

## Compressed PDA

Compressed accounts at Program Derived Addresses.

## Compressed account

A data structure that holds arbitrary data, represented as a 32-byte hash stored in a leaf of a state Merkle tree. Compressed accounts do not require a rent exempt balance upon creation.

## Compressed Account hash

A 32-byte identifier uniquely that represents a compressed account's state, stored in a state tree.

## Token mint

An SPL token mint uniquely represents a token on the Solana network and stores global metadata about the token, including `mint_authority`, `supply`, and `decimals`.

SPL tokens can be compressed if the mint has a token pool account set up. Anyone can create a token pool PDA for any given SPL mint.

## Token Pool Account

SPL token account that holds SPL tokens corresponding to compressed tokens in circulation. Tokens are deposited during compression and withdrawn during decompression, owned by the Light Token Program's CPI authority PDA.

## Concurrency

The ability to process multiple Merkle tree update requests simultaneously without invalidating each other, as long as they don't modify the same leaf.

Concurrency in ZK Compression allows parallel operations on different tree leaves without requiring locks.

## Compressed Token

An SPL token in compressed form. Compressed tokens do not require an associated token account per holder.

## Compressed Token account

An account type in the Light Token Program to store information about an individual's ownership of a specific token (mint). Compressed token accounts do not require a rent exempt balance upon creation.

## Light Token Program

Light Protocol's SPL-compatible token program that enables compression and decompression of token accounts. The program enforces SPL token layout standards and allows for arbitrary transitions between compressed and regular format.

## [**Compute units**](https://solana.com/docs/references/terminology#compute-units)

The smallest unit of measure for consumption of computational resources of the transactions on the Solana blockchain.

## [**Compute unit budget**](https://solana.com/docs/references/terminology#compute-budget)

The maximum number of [compute units](https://solana.com/docs/references/terminology#compute-units) consumed per transaction.

Developers set the compute unit budget via the`ComputeBudget`instruction, by default 200,000 CU, with a maximum of 1,400,000 CU.

If the transaction exceeds its compute unit limit, it fails and no changes occur.

## Compute unit limits per block

The total amount of compute units that all transactions in a single Solana block - the *blockspace* - can collectively consume is currently set at 48 million CU.

The maximum compute units that can be used to modify a single account within a block - the *write lock limit -* is currently set at 12 million CU.

## [Cross-program invocation (CPI)](https://solana.com/docs/core/transactions#cross-program-invocation-cpi)

A call from one [program](https://solana.com/docs/core/transactions#onchain-program) to another.

<Info>For more information, see [calling between programs](https://solana.com/docs/core/cpi).</Info>

## Decompression

The process of converting a compressed to a regular Solana account. SPL tokens are withdrawn from the token pool to an Associated Token Account and compressed token accounts are invalidated.

## Forester node / Forester

A keeper node to incorporate state updates into state Merkle Trees for ZK Compression.

## Groth16

A zero-knowledge SNARK that produces constant-size proofs using bilinear pairings on elliptic curves.

ZK Compression uses Groth16 to generate 128 byte validity proofs to verify compressed account state transitions against the on-chain root.

## [**Hash**](https://solana.com/docs/references/terminology#hash)

A hash is a digital fingerprint of a sequence of bytes representing arbitrary data, while requiring far less storage space than the original data.

## Indexer

A service that tracks state changes of compressed accounts on the Solana ledger and provides RPC APIs for querying compressed accounts and generating validity proofs.

The ZK Compression indexer is named Photon and is maintained by Helius Labs.

<Info>**Source**: [https://github.com/helius-labs/photon](https://github.com/helius-labs/photon)</Info>

## [**Instruction**](https://solana.com/docs/references/terminology#instruction)

A call to invoke a specific [instruction handler](https://solana.com/docs/references/terminology#instruction-handler) in a [program](https://solana.com/docs/references/terminology#program).

An instruction also specifies which accounts it wants to read or modify, and additional data that serves as auxiliary input to the [instruction handler](https://solana.com/docs/references/terminology#instruction-handler). A [client](https://solana.com/docs/references/terminology#client) must include at least one instruction in a [transaction](https://solana.com/docs/references/terminology#transaction), and all instructions must complete for the transaction to be considered successful.

For example, compressed accounts are created or updated with the `InvokeCpiInstruction` to the Light System Program.

## Leaf index

The numerical position (u32) of a compressed account within a state tree, used for Merkle proof generation.

## Light System Program

ZK Compression's core program that validates compressed account state transitions by verifying validity proofs and managing compressed state changes.

The program enforces compressed account layout with ownership and sum checks, and is invoked to create and write to compressed accounts and PDAs.

<Info>**Source**: [https://github.com/Lightprotocol/light-protocol/tree/main/programs/system](https://github.com/Lightprotocol/light-protocol/tree/main/programs/system)</Info>

## **Ledger**

The ledger is an immutable historical record of all Solana transactions signed by clients since the genesis block.

A helpful analogy to differentiate Solana ledger and state:

* Ledger is the entire bank statement history.
* State is the current account balance, derived from all transactions in the bank statement history.

## Merkle tree

A tree data structure to allow for cryptographic verification of the integrity of all leaves in a tree.

Each leaf on a Merkle tree is a hash of that leaf's data. A Merkle tree compresses data by hashing pairs of data repeatedly into a single root hash, starting from the lowest level. Only this root hash is stored on chain. On Solana, this process is called state compression.

## Merkle tree account

The public key of the on-chain Merkle tree account used in ZK Compression. This identifier references the state tree that stores compressed account hashes.

## Merkle proof

A cryptographic proof consisting of sibling node hashes required to verify that a specific leaf exists within a Merkle tree and calculate the root hash.

ZK Compression encodes Merkle proofs into zero-knowledge proofs (validity proofs). These verify compressed account operations with a constant 128-byte size without exposing the underlying variable-size Merkle proof data.

## Nullification

The process of marking compressed accounts as spent to prevent double-spending.

When compressed accounts are used as inputs in transactions, their previous states are invalidated by inserting their hashes into nullifier queues. Forester nodes process these queues to permanently update the corresponding Merkle tree leaves, ensuring each compressed account state can only be used once.

## Nullifier queue

A queue where compressed accounts hashes used as input for transactions are temporarily stored to prevent double spending. A Forester node empties the queue by inserting queue elements into a state Merkle tree.

## [**Program**](https://solana.com/docs/references/terminology#onchain-program)

Programs run executable code similar to smart contracts on other blockchains with optimizations specific to Solana.

Solana programs key characteristics include:

* Solana programs are stateless and do not store state internally. Separate accounts store state for programs to execute on, such as program, user or token data. This makes Solana's account model [different from Ethereum's](https://solana.com/news/evm-to-svm).
* Programs are typically written in Rust.
* Programs interpret the [instructions](https://solana.com/docs/references/terminology#instruction) sent inside of each [transaction](https://solana.com/docs/references/terminology#transaction) to read and modify accounts over which it has control, hence update state.

## Parallelism

The ability of the SVM to execute multiple transactions simultaneously, as long as they modify different regular and/or compressed accounts.

## [**Program derived addresses (PDA)**](https://solana.com/docs/references/terminology#program-derived-account-pda)

PDAs are special account addresses derived deterministically using optional seeds, a bump seed, and a program ID.

They are off the Ed25519 curve, meaning they have no private key. The PDA itself, once derived, is 32 bytes, matching a regular public key.

## [**Prioritization fee**](https://solana.com/docs/references/terminology#prioritization-fee)

An additional fee user can specify in the compute budget [instruction](https://solana.com/docs/references/terminology#instruction) to prioritize their [transactions](https://solana.com/docs/references/terminology#transaction).

The priority fee is derived from the compute unit limit and the compute unit price. The price per compute unit set by the user in micro-lamports (1 lamport = 1,000,000 micro-lamports), rounded up to the nearest lamport.

## Poseidon hash

A cryptographic hash function optimized for zero-knowledge proof systems that works natively with finite field arithmetic.

The Poseidon hash is designed to minimize computational complexity in ZK circuits. ZK Compression uses Poseidon hashes to generate the account hashes stored as leaves in state trees.

## Proof verification

The on-chain process of validating zero-knowledge proofs to confirm the correctness of compressed account state transitions.

## Rent

A fee paid in SOL for the creation of [Accounts](https://solana.com/docs/references/terminology#account) to store data on the blockchain, tied to account size. When accounts do not have enough balance to pay rent, they may be Garbage Collected.

## [**Rent exempt**](https://solana.com/docs/references/terminology#rent-exempt)

An account that maintains a minimum lamport balance proportional to the amount of data stored on the account.

All newly created accounts are stored on chain permanently until the account is closed. It is not possible to create an account that falls below the rent exemption threshold.

The rent exemption balance remains locked while an account is active and can be fully recovered when the account is closed.

The minimum balance is paid by the creator and is calculated as follows:

```markdown theme={null}
Minimum Rent Balance = 2 × 0.00000348 SOL/byte/year × Account Size (Bytes)
```

## Remote Procedure Calls (RPC)

A bridge between users (or applications) and the blockchain to facilitate interactions and data retrieval.

The [ZK Compression RPC API](https://www.zkcompression.com/developers/json-rpc-methods) extends [Solana's JSON RPC API](https://solana.com/docs/rpc) with additional endpoints to interact with compressed accounts, provided by Helius Labs.

<Info>
  Find more information on [ZK Compression's JSON RPC Methods
  here](/api-reference/json-rpc-methods/overview).
</Info>

## [**Smart contract**](https://solana.com/docs/references/terminology#smart-contract)

Smart contracts on Solana are called programs with key characteristics and optimizations.

## Solana Account Model

The native framework to store and manage data on the Solana blockchain.

Solana's Account Model separates program logic from state to optimize for parallel and faster transactions. Separate accounts store state for programs to execute on, such as program, user or token data. This makes Solana's Account Model [different from Ethereum's](https://solana.com/news/evm-to-svm).

ZK Compression extends Solana's Account Model with Compressed Accounts.

## [**Solana Program Library (SPL)**](https://solana.com/docs/references/terminology#solana-program-library-spl)

A [library of programs](https://spl.solana.com/) on Solana such as spl-token that facilitates tasks such as creating and using tokens.

## State

A snapshot representing the current status of all accounts and programs on Solana.

The state is derived from the ledger by sequentially applying every transaction. State is mutable and changes with every transaction to represent the latest state.

State is kept in RAM by validators for transaction validation.

## State root

The root hash of a Merkle tree that serves as a cryptographic fingerprint representing all compressed accounts in the tree.

State roots are stored on-chain and used by the Light System Program to verify validity proofs during compressed account operations. Each state root represents the complete state of compressed accounts at a specific point in time.

## State tree

A Merkle tree that stores compressed account hashes as leaf nodes.

State trees organize compressed account data into a binary tree structure where each parent node is the hash of its two children nodes. The tree's root hash is stored on-chain as a cryptographic fingerprint representing all accounts in the tree.

Two state tree versions with different proof mechanisms are currently supported:

* **V1 state trees**: Always require the full 128-byte validity proof. With a depth of 26, a single V1 state tree stores approximately 67 million compressed accounts.
* **V2 batched state trees**: Support `prove_by_index` optimization that verifies account existence with one byte instead of 128 bytes, optimizing compute unit consumption by up to 70%.

## State compression

A process to lower the amount of data stored on chain using Merkle trees.

The process of state compression involves the following steps:

1. Millions of accounts are compressed into a 'fingerprint' - the Merkle tree root hash
2. This 'fingerprint' is stored in one Solana account
3. The account history is stored on the Solana ledger
4. The latest compressed data is fetched from an indexer
5. To verify the data, recompute the hashes and compare the final hash to the on chain root hash

<Info>
  Learn more [on generalized state compression
  here](https://solana.com/developers/courses/state-compression/generalized-state-compression).
</Info>

## Token account

A token account is an account type in Solana's Token Programs that stores information about an individual's ownership of a specific token (mint). Each token account is associated with a single mint and tracks details like the token balance and owner.

## [**Token mint**](https://solana.com/docs/references/terminology#token-mint)

A [mint account](https://solana.com/docs/tokens/basics/create-mint) is an account type in Solana's Token Programs that can produce (or 'mint') tokens.

Different tokens are distinguished by their unique token mint addresses. Token mints uniquely represents a token on the network and stores global metadata about the token, including the `mint_authority`, supply, and decimals.

## [**Transaction**](https://solana.com/docs/references/terminology#transaction)

One or more [instructions](https://solana.com/docs/references/terminology#instruction) signed by a [client](https://solana.com/docs/references/terminology#client) using one or more [keypairs](https://solana.com/docs/references/terminology#keypair) and executed atomically with only two possible outcomes: success or failure.

## Validity proof

A zero-knowledge proof of compressed state included in a transaction to read or write compressed accounts.

Developers don't need to generate *validity proofs*.

The *validity proof* is

* constant 128 byte in size (other than Merkle proofs with varying proof size), fitting well in Solana's 1232 byte transaction limit
* verified against the respective on chain fingerprint to ensure the provided data was previously emitted
* provided and generated by indexers that support the [ZK Compression RPC API](https://www.zkcompression.com/developers/json-rpc-methods) which extend Solana's [JSON RPC API](https://solana.com/docs/rpc) to interact with compressed accounts. .

## Zero-knowledge proof (ZKP)

A cryptographic proof to verify the validity of a statement without revealing the underlying data.

ZK Compression uses a Groth16 SNARK zk proof

* for its constant *validity* proof size, to ensures the integrity of many compressed accounts, not for private or confidential transactions, and
* to store data in zk friendly data structures. Applications on Solana can prove custom off chain computations over zk compressed state (native zk compute).

## ZK-SNARK

Zero-Knowledge Succinct Non-Interactive Arguments of Knowledge, a cryptographic proof system that enables proving knowledge of information without revealing the information itself.

zk-SNARKs produce constant-size proofs that can be verified efficiently without interaction between prover and verifier. ZK Compression uses the Groth16 zk-SNARK construction to generate validity proofs for compressed account state transitions.

## ZK Compression

A generalized compression framework to compress and verify arbitrary data with zero-knowledge proofs, to

* enable the Compressed Account Model, the rent-free equivalent to Solana's Account Model,
* solve Solana's state growth problem, and
* build a foundation for native zk compute.


# Whitepaper
Source: https://www.zkcompression.com/references/whitepaper

Whitepaper introducing ZK Compression

# Scaling the Design Space for On-chain Applications with ZK Compression

Light Protocol Team

#### Abstract

This paper proposes Light Protocol, a set of smart contracts for Solana that introduces ZK Compression.

Solana application developers can opt-in to compress their application's on-chain state via the Light Protocol smart contracts. This reduces state cost by orders of magnitude while preserving the Solana L1's security, performance, and composability.

For the Solana validator network, widespread adoption of ZK Compression could help solve the state growth problem by limiting the state held in active memory by validators relative to the total state produced.

Finally, Light Protocol opens up a new design space for zero-knowledge-based protocols and applications on Solana; because ZK Compression stores data in zero-knowledge-friendly data structures, applications can efficiently prove custom off-chain computations over ZK-compressed state.

#### 1 The Problem: Expensive On-chain State

For developers to scale their on-chain applications to large user bases, the marginal cost of data storage must be near zero. Solana has emerged as a leading Layer 1 blockchain, attracting application developers who aim to scale to large numbers of end users.

However, storing data on the Solana L1 has become increasingly expensive for the network, and the cost trickles down to the application developer, limiting the design space for on-chain applications with low Lifetime Value (LTV) / Customer Acquisition Cost (CAC) ratios.

#### 2 ZK Compression

When a Solana account gets compressed, its data is hashed and stored as a leaf in a sparse binary Merkle tree structure. The tree's state root (i.e., a small fingerprint of all compressed accounts in the tree) is stored on the blockchain.

The underlying compressed account data is stored off-chain, e.g., as call data in the cheaper Solana ledger space. To read or write compressed state, transactions provide the compressed off-chain data and a succinct zero-knowledge proof (validity proof).

Light Protocol verifies the validity proof against the respective on-chain state root to ensure that the provided data was previously emitted via the protocol smart contracts. The succinctness property of the zero-knowledge proof (a Groth16 SNARK \[1]) ensures that the integrity of many compressed accounts can be verified on-chain with a constant proof size of 128 bytes, which is ideal for Solana's highly constrained 1232-byte transaction size limit.

#### 3 Light Protocol System Architecture

The transaction flow in Light Protocol consists of the following key components:

1. **Off-chain state storage**: State is stored off-chain, e.g., as calldata in the Solana ledger.
2. **New Transactions specify state:** Transactions include the compressed data they read or write, the state tree accounts, a pointer to a recent on-chain state root, and a corresponding validity proof, all included in the transaction payload.
3. **Applications must invoke the Light Protocol system program to write compressed state.**
   1. The system program validates the state (verifies the validity proof, performing sum checks and ownership checks)
   2. It enforces an account schema resembling the layout of classic Solana accounts.
   3. The old compressed state is nullified (inserted into the nullifier queue).
   4. The new compressed state is appended to the state Merkle Tree and recorded as call data on the Solana ledger.
   5. Any newly created addresses are inserted into the address queue.
4. **Photon Indexer** nodes index and store events to make compressed account state available to clients. A new node can always sync with the latest compressed state by sequentially processing all historical transactions from Genesis.

<Frame>
  <img alt="A diagram illustrating the transaction flow in the Light Protocol system architecture. The off-chain client reads the compressed state from the indexer and constructs a transaction. The transaction, which includes the compressed state, state tree accounts, a pointer to a recent on-chain state root, and a validity proof, is sent to the caller program. The caller program invokes the Light System Program, which interacts with the Account Compression Program to validate the state, nullify the old compressed state, append the new compressed state to the state Merkle Tree, and record it as call data on the Solana ledger. The Account Compression Program also updates state roots and emits events. The indexer retrieves the compressed state and validity proof from the Solana ledger and makes this information available to the off-chain client, completing the transaction flow." />
</Frame>

A simplified compressed state transition can be expressed as:

(𝑠𝑡𝑎𝑡𝑒, 𝑣𝑎𝑙𝑖𝑑𝑖𝑡𝑦𝑃𝑟𝑜𝑜𝑓) → 𝑠𝑡𝑎𝑡𝑒 𝑡𝑟𝑎𝑛𝑠𝑖𝑡𝑖𝑜𝑛 → 𝑠𝑡𝑎𝑡𝑒'

Here, *state'* gets emitted onto the ledger.

* In principle, new compressed account hashes (output state) get appended to specified state trees with each state transition.
* Old compressed account hashes (input state) get invalidated via insertion into a nullifier queue.
* Compressed state transitions are atomic and instantly final.

<Frame>
  <img alt="A diagram illustrating the compressed state transition process in the Light Protocol system. The process is initiated by atomic user interactions with the protocol. The user interacts with the Caller Program, which invokes the Light System Program. The Light System Program then interacts with the Account Compression Program to facilitate the state transition. The Account Compression Program performs three key actions: appending the output state to the state tree, invalidating the input state by inserting it into the nullifier queue, and adding new addresses to the address queue. The Forester node asynchronously empties the queues and updates the Merkle trees, maintaining the on-chain accounts, including the state tree and address space tree, which store the compressed state. The compressed state transition follows the sequence: (𝑠𝑡𝑎𝑡𝑒, 𝑣𝑎𝑙𝑖𝑑𝑖𝑡𝑦𝑃𝑟𝑜𝑜𝑓) → 𝑠𝑡𝑎𝑡𝑒 𝑡𝑟𝑎𝑛𝑠𝑖𝑡𝑖𝑜𝑛 → 𝑠𝑡𝑎𝑡𝑒', where state' gets emitted onto the ledger." />
</Frame>

**Foresters and Liveness**

In an asynchronous process, *Forester* nodes empty the nullifier queues. They achieve this by updating the leaf of the state Merkle tree, corresponding to the account hash previously inserted into the nullifier queue, with zeros (nullification).

These queues enable instant finality of compressed state transitions but have a capped size. *Foresters* are critical for protocol liveness and need to consistently empty queues. A full queue causes a liveness failure for all state stored in its associated state tree. A liveness failure is recovered by *Foresters* emptying the queue again. Hosting a *Forester* and foresting one's trees is permissionless.

**3.1 Compressed Account Model**

The Light System Program enforces an account layout that largely resembles Solana's regular account model. Key differences include:

* Each compressed account can be identified by its hash.
* Each write to a compressed account changes its hash.
* An address can optionally be set as a permanent unique ID of the compressed account.
* All compressed accounts are stored in sparse Merkle trees. Only the trees' sparse state structure and roots (small fingerprints of all compressed accounts) are stored in the on-chain account space.

These differences allow the protocol to store the underlying data off-chain (e.g., in the less expensive Solana ledger space) instead of in the more expensive on-chain account space.

**Compressed PDA Accounts**

Like regular accounts, each compressed account with a program-derived address (PDA) can be identified by its unique persistent address, represented as 32 bytes in the format of a PublicKey.

Like PDAs, compressed account addresses don't belong to a private key; instead, they're derived from the program that owns them.

<Frame>
  <img alt="A diagram illustrating the structure of a compressed account in the Light Protocol system. The compressed account is owned by a program and is associated with a compressed PDA (Program Derived Address) account. The compressed account contains data bytes, lamports (account balance), an owner (the program that owns the account), and an address (represented as a public key). The owner of the compressed account has the authority to modify its data and transfer lamports from it. The compressed account is identified by its unique hash, which changes with each write operation. An address can be optionally set as a permanent unique identifier for the compressed account. Compressed accounts are stored in sparse Merkle trees, with only the trees' sparse state structure and roots stored in the on-chain account space, while the underlying data is stored off-chain." />
</Frame>

The compressed PDA account layout is similar to Solana's regular PDA account layout: Data, Lamports, Owner, and an address field. The data field stores program-owned state. In contrast to Solana's account data field, Light Protocol enshrines a specific AccountData structure: Discriminator, Data, DataHash:

<Frame>
  <img alt="A diagram depicting the structure of a compressed PDA (Program Derived Address) account in the Light Protocol system. The compressed PDA account consists of a data field, which stores program-owned state, lamports (account balance), an owner field indicating the program that owns the account, and an address field represented as a public key. The AccountData structure within the compressed PDA account is composed of a discriminator (a unique identifier for the account type), the actual data (program state), and a DataHash (a hash of the account data). This AccountData structure is specific to the Light Protocol and differs from Solana's regular account data field." />
</Frame>

**Compressed PDA Account with AccountData**

The Anchor framework reserves the first 8 bytes of a regular account's data field for the discriminator. This helps programs distinguish between different account types. The default compressed account layout is opinionated in this regard and enforces a discriminator in the Data field.

The dataHash is what the Protocol uses to verify the integrity of program-owned data. This enables the protocol to be agnostic as to whether or how the data underlying the dataHash is stored or passed to the Light system program. The account owner program needs to ensure the correctness of the data hash.

**Compressed Token Accounts**

Light Protocol provides an implementation of a Light Token Program built on top of ZK Compression.

The Light Token Program enforces a token layout that is compatible with the SPL Token standard. The program also supports SPL compression and decompression; existing SPL token accounts can be compressed and decompressed arbitrarily.

**Fungible Compressed Accounts**

Each compressed account can be identified by its hash, regardless of whether it has an address. By definition, whenever the data of a compressed account changes, its hash changes.

In contrast to Solana's regular account model, the address field is optional for compressed accounts because ensuring that a new account's address is unique incurs additional computational overhead. Addresses are not needed for fungible compressed accounts (i.e., tokens).

**3.2 The Light Forest: Merkle Trees**

The protocol stores compressed state in a "forest" of multiple binary Merkle trees.

**State Trees**

A state tree is a binary concurrent Merkle tree \[2] that organizes data into a tree structure where each parent node is the hash of its two children nodes. This leads to a single unique root hash that allows for efficient cryptographic verification of the integrity of all the leaves in the tree. The hash of each compressed account is stored as a leaf in such a state tree:

<Frame>
  <img alt="A diagram illustrating a binary Merkle tree with a depth of 2. The tree consists of a root node, two intermediate nodes (Node 0 and Node 1), and four leaf nodes (Leaf 0, Leaf 1, Leaf 2, and Leaf 3). The root node is the parent of Node 0 and Node 1, while Node 0 is the parent of Leaf 0 and Leaf 1, and Node 1 is the parent of Leaf 2 and Leaf 3. The tree represents a hierarchical structure where each parent node is derived from the hash of its two child nodes." />
</Frame>

Each compressed account hash is a leaf in the state tree:

<Frame>
  <img alt="A diagram illustrating the composition of a compressed account hash, which is stored as a leaf in a state tree. The compressed account hash consists of the DataHash, Lamports (account balance), OwnerHash, Address, Discriminator, State tree hash, and Leaf Index. The DataHash represents the hash of the account data, Lamports store the account balance, OwnerHash is the hash of the account owner, Address is an optional unique identifier for the account, Discriminator helps distinguish between different account types, State tree hash identifies the specific state tree the account belongs to, and Leaf Index represents the position of the account within the state tree. The state tree hash and leaf index ensure that each compressed account hash is globally unique." />
</Frame>

Compressed account hashes include the Public Key of the State tree's respective on-chain account (State tree hash) and the compressed account's position in the tree (leafIndex). This ensures that each account hash is globally unique.

Each state tree has a corresponding on-chain State tree account that stores only the tree's final root hash and other metadata. Storing the final tree root hash on-chain allows the protocol to efficiently verify the validity of any leaf in the tree without needing to access the underlying compressed account state. The actual account data can thus be stored off-chain, e.g., in the much cheaper Solana ledger space, while preserving the security guarantees of the Solana L1.

**Continuous Merkle Trees: Rollover and Rollover fees**

For each new compressed account state, a new leaf is stored in the respective state Merkle tree. Given a tree depth of 26, the tree can support up to approximately 67 million leaves and, thus, 67 million compressed account state transitions.

Compressed account hashes are added to the state tree until a threshold is reached. Once this threshold is met, a new state tree account and an associated nullifier queue account can be created to ensure continuous compressed transactions, a process known as a rollover.

The costs for creating new on-chain accounts during a rollover are amortized across all transactions that add new leaves to the state tree. This marginal cost, which funds the next on-chain accounts, is usually very low and depends on the tree's depth and other factors affecting the size of the state tree and nullifier accounts.

**Address Space Trees**

Light Protocol supports the creation of provably unique addresses across a 254-bit address space. This is useful for applications requiring PDA-like uniqueness properties with compressed accounts, such as token-gating or creating unique identifiers.

Transactions that create new addresses must provide a validity proof of exclusion from a given address space tree. Multiple independent address spaces can exist at the same time. Address space trees are indexed-concurrent binary Merkle tree data structures \[3]. These trees store exclusion ranges as linked lists in the tree leaves, enabling exclusion proofs across the 254-bit address space with trees of arbitrarily small depth.

**Parallelism**

State and address space trees can optionally be derived from and owned by custom Solana programs. This is useful for applications that want to control the write locks to their state trees. State tree accounts and nullifier accounts are separated to help elevate unnecessary write-locks.

Suppose a tree *A* with queue *A'* and a tree *B* with queue *B'.* Further, suppose a transaction *T* nullifies a compressed account from tree *A* but writes only to tree B; the transaction only write-locks *A'* and *B*. *A* and *B'* do not get write-locked.

**Limitations**

ZK Compression reduces the data storage cost of all accounts to near zero, allowing developers to scale their application state to larger user bases on Solana. However, the following notable characteristics of ZK Compression can impact their utility for specific applications. ZK Compression transactions have:

1. **Larger Transaction Size:** The transaction payload must include the compressed state to be read on-chain and a constant-size 128-byte validity proof.
2. **High Compute Unit Usage:** The protocol uses ZK primitives and on-chain hashing, which incur a relatively high base CU cost. If blocks are full, this can impact the inclusion rate of transactions. Future approaches to reducing CU cost can include optimizing the Merkle tree updates and hardware acceleration of cryptographic primitives and Syscalls used by the protocol.
3. **Per-transaction cost:** operating a *Forester* node incurs additional hardware and transaction costs. The mechanism for efficiently nullifying multiple leaves in one Solana transaction can be improved significantly over time.

#### 4 A World with Light Protocol

**4.1 Light Helps Developers Scale Their Applications**

The set of applications and protocols that benefit from ZK Compression is quite broad, including:

1. Token-based applications and marketplaces, including applications for large-scale token distribution.
2. Applications that issue large numbers of digital assets, PDA accounts, and unique identifiers, such as decentralized social applications, name-service programs, and staking protocols.
3. Applications serving a user base with a low LTV/CAC ratio.
4. Payments infrastructure and applications.

**4.2 Light Enables ZK-Applications**

Light Protocol is a shared bridge to merklelized, zk-friendly state. We believe that as more state becomes compressed via ZK Compression, Light Protocol will provide ZK-based applications and protocols with the option to bootstrap and scale on Solana across globally shared compressed state.

We believe the design space for ZK-based applications is now wide open and will continue to expand. Some exciting technologies include:

1. Identity Protocols,
2. ZK Coprocessors,
3. Based ZK Rollups

#### 5 Summary

1. Light Protocol enables Solana developers to reduce their application state by orders of magnitude by introducing the ZK Compression primitive, which allows secure on-chain composability with off-chain state.
2. ZK Compression can contribute to solving Solana's state growth problem.
3. Light seeks to enable a future with a thriving ZK ecosystem on Solana where new applications, marketplaces and computation designs can all interoperate, compose, and innovate permissionlessly over shared zk-compressed state.

**Acknowledgments**

We are grateful to Nicolas Pennie and Pedro Mantica for their extensive feedback, which has helped shape the design of ZK Compression, and to the team at Helius Labs as a whole for building the canonical ZK Compression Indexer implementation and RPC API.

**Legal Disclaimer**

Please read the entirety of this "Legal Disclaimer" section carefully. If you have any doubts about the action you should take, you should consult your own legal, financial, tax, or other professional advisor(s) before engaging in any activity herewith. This paper is for general information purposes only, to receive feedback and comments from the public. It does not constitute investment advice, a recommendation, or a solicitation to buy or sell any investment. It should not be used to evaluate the merits of making any investment decision. It should not be relied upon for accounting, legal, or tax advice or any investment recommendations. This paper reflects the current opinions of the Light Protocol Team. The opinions reflected herein outline current plans, which are subject to change at its discretion, without any guarantee of being updated. The success of outlined plans will depend on many factors outside the authors' or Light Protocol Labs' control, including but not limited to factors within the data and blockchain industries. Any statements about future events are based solely on the analysis of the issues described in this White Paper. That analysis might prove to be incorrect.

**References**

\[1] Groth, Jens. "On the size of pairing-based non-interactive arguments. " *Advances in Cryptology–EUROCRYPT 2016: 35th Annual International Conference on the Theory and Applications of Cryptographic Techniques, Vienna, Austria, May 8-12, 2016, Proceedings, Part II 35*. Springer Berlin Heidelberg, 2016.

\[2] *Concurrent Merkle Tree whitepaper.pdf*. (n.d.). Google Docs. [https://drive.google.com/file/d/1BOpa5OFmara50fTvL0VIVYjtg-qzHCVc/view](https://drive.google.com/file/d/1BOpa5OFmara50fTvL0VIVYjtg-qzHCVc/view)

\[3] *Indexed Merkle Tree | Privacy-First ZKRollup | Aztec Documentation*. (n.d.). [https://docs.aztec.network/aztec/concepts/storage/trees/indexed\_merkle\_tree#indexed-merkle-tree-constructions](https://docs.aztec.network/aztec/concepts/storage/trees/indexed_merkle_tree#indexed-merkle-tree-constructions)


# Addresses and URLs
Source: https://www.zkcompression.com/resources/addresses-and-urls

Overview to all of ZK Compression's RPC URLs, Program IDs & Accounts and Lookup Tables.

## RPC URLs

<Tabs>
  <Tab title="Mainnet">
    | Network | Service               | URL                                                     |
    | :------ | :-------------------- | :------------------------------------------------------ |
    | Mainnet | Network Address (RPC) | `https://mainnet.helius-rpc.com?api-key=&#x3C;api_key>` |
    | Mainnet | Photon RPC API        | `https://mainnet.helius-rpc.com?api-key=&#x3C;api_key>` |
  </Tab>

  <Tab title="Devnet">
    | Network | Service               | URL                                                    |
    | :------ | :-------------------- | :----------------------------------------------------- |
    | Devnet  | Network Address (RPC) | `https://devnet.helius-rpc.com?api-key=&#x3C;api_key>` |
    | Devnet  | Photon RPC API        | `https://devnet.helius-rpc.com?api-key=&#x3C;api_key>` |
  </Tab>
</Tabs>

<Info>
  Find all JSON RPC Methods for ZK Compression [here](/api-reference/json-rpc-methods/overview).
</Info>

## Program IDs

|                             |                                                 |
| :-------------------------- | :---------------------------------------------- |
| Light System Program        | **SySTEM1eSU2p4BGQfQpimFEWWSC1XDFeun3Nqzz3rT7** |
| Light Token Program         | **cTokenmWW8bLPjZEBAUgYy3zKxQZW6VKi7bqNFEVv3m** |
| Account Compression Program | **compr6CUsB5m2jS4Y3831ztGSTnDpnKJTKS95d64XVq** |

## State Trees & Queues & CPI Accounts

<Check>
  **In your local test validator environment** use in Rust `TestAccounts::get_local_test_validator_accounts()` to get all pre-configured protocol, state tree, and address tree accounts.
</Check>

<Tabs>
  <Tab title="V2 (Default)">
    |                 | Public Key                                      |
    | :-------------- | :---------------------------------------------- |
    | #1 State Tree   | **bmt1LryLZUMmF7ZtqESaw7wifBXLfXHQYoE4GAmrahU** |
    | #1 Output Queue | **oq1na8gojfdUhsfCpyjNt6h4JaDWtHf1yQj4koBWfto** |
    | #1 CPI Context  | **cpi15BoVPKgEPw5o8wc2T816GE7b378nMXnhH3Xbq4y** |

    |                 | Public Key                                      |
    | :-------------- | :---------------------------------------------- |
    | #2 State Tree   | **bmt2UxoBxB9xWev4BkLvkGdapsz6sZGkzViPNph7VFi** |
    | #2 Output Queue | **oq2UkeMsJLfXt2QHzim242SUi3nvjJs8Pn7Eac9H9vg** |
    | #2 CPI Context  | **cpi2yGapXUR3As5SjnHBAVvmApNiLsbeZpF3euWnW6B** |

    |                 | Public Key                                      |
    | :-------------- | :---------------------------------------------- |
    | #3 State Tree   | **bmt3ccLd4bqSVZVeCJnH1F6C8jNygAhaDfxDwePyyGb** |
    | #3 Output Queue | **oq3AxjekBWgo64gpauB6QtuZNesuv19xrhaC1ZM1THQ** |
    | #3 CPI Context  | **cpi3mbwMpSX8FAGMZVP85AwxqCaQMfEk9Em1v8QK9Rf** |

    |                 | Public Key                                      |
    | :-------------- | :---------------------------------------------- |
    | #4 State Tree   | **bmt4d3p1a4YQgk9PeZv5s4DBUmbF5NxqYpk9HGjQsd8** |
    | #4 Output Queue | **oq4ypwvVGzCUMoiKKHWh4S1SgZJ9vCvKpcz6RT6A8dq** |
    | #4 CPI Context  | **cpi4yyPDc4bCgHAnsenunGA8Y77j3XEDyjgfyCKgcoc** |

    |                 | Public Key                                      |
    | :-------------- | :---------------------------------------------- |
    | #5 State Tree   | **bmt5yU97jC88YXTuSukYHa8Z5Bi2ZDUtmzfkDTA2mG2** |
    | #5 Output Queue | **oq5oh5ZR3yGomuQgFduNDzjtGvVWfDRGLuDVjv9a96P** |
    | #5 CPI Context  | **cpi5ZTjdgYpZ1Xr7B1cMLLUE81oTtJbNNAyKary2nV6** |
  </Tab>

  <Tab title="V1 (For ZK)">
    |                 | Public Key                                      |
    | :-------------- | :---------------------------------------------- |
    | State Tree      | **smt2rJAFdyJJupwMKAqTNAJwvjhmiZ4JYGZmbVRw1Ho** |
    | Nullifier Queue | **nfq2hgS7NYemXsFaFUCe3EMXSDSfnZnAe27jC6aPP1X** |
    | CPI Context     | **cpi2cdhkH5roePvcudTgUL8ppEBfTay1desGh8G8QxK** |
  </Tab>
</Tabs>

## Address Trees & Queues

<Tabs>
  <Tab title="V2">
    | Address Tree |                                                 |
    | :----------- | :---------------------------------------------- |
    | Address Tree | **amt2kaJA14v3urZbZvnc5v2np8jqvc4Z8zDep5wbtzx** |
  </Tab>

  <Tab title="V1 (Deprecated)">
    | Address Tree #1  |                                                 |
    | :--------------- | :---------------------------------------------- |
    | Address Tree #1  | **amt1Ayt45jfbdw5YSo7iz6WZxUmnZsQTYXy82hVwyC2** |
    | Address Queue #1 | **aq1S9z4reTSQAdgWHGD2zDaS39sjGrAxbR31vxJ2F4F** |
  </Tab>
</Tabs>

## Interface PDA

The account to convert format between:

* compressed token ↔ SPL token
* light-token ↔ SPL token

|               |                                                  |
| :------------ | :----------------------------------------------- |
| Interface PDA | **GXtd2izAiMJPwMEjfgTRH3d7k9mjn4Jq3JrWFv9gySYy** |

## Lookup Tables

<Info>
  [Lookup tables](https://solana.com/docs/advanced/lookup-tables) reduce your transaction size. We provide pre-initialized lookup tables that cover the Light's program IDs and accounts:
</Info>

|                           |                                                  |
| :------------------------ | :----------------------------------------------- |
| Lookup Table #1 (Mainnet) | **9NYFyEqPkyXUhkerbGHXUXkvb4qpzeEdHuGpgbgpH1NJ** |
| Lookup Table #1 (Devnet)  | **qAJZMgnQJ8G6vA3WRcjD9Jan1wtKkaCFWLWskxJrR5V**  |

We provide a helper function below if you need to extend a custom lookup table.

<Accordion title="ExtendLookUpTables.ts">
  ```typescript theme={null}
  import { Rpc, confirmTx, createRpc } from "@lightprotocol/stateless.js";
  import { createTokenProgramLookupTable } from "@lightprotocol/compressed-token";
  import { Keypair, PublicKey} from "@solana/web3.js";
  import { RPC_ENDPOINT } from "./constants";
  const payer = Keypair.generate();
  const authority = payer;
  const additionalTokenMints : PublicKey[] = [];
  const additionalAccounts : PublicKey[] = [];

  // Localnet
  const connection: Rpc = createRpc();

  const main = async () => {
    /// airdrop lamports to pay gas and rent
    await confirmTx(
      connection,
      await connection.requestAirdrop(payer.publicKey, 1e7)
    );

    /// Create LUT
    const { address } = await createTokenProgramLookupTable(
      connection,
      payer,
      authority,
      additionalTokenMints,
      additionalAccounts
    );

    console.log("Created lookup table:", address.toBase58());
  };

  main();
  ```
</Accordion>

## System Accounts List

<table>
  <colgroup>
    <col />

    <col />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>1</td>
      <td><strong><Tooltip href="https://solscan.io/account/SySTEM1eSU2p4BGQfQpimFEWWSC1XDFeun3Nqzz3rT7">Light System Program</Tooltip></strong></td>
      <td>Verifies validity proofs, compressed account ownership checks, and CPIs the Account Compression Program to update tree accounts.</td>
    </tr>

    <tr>
      <td>2</td>
      <td><strong>CPI Signer</strong></td>

      <td>
        * PDA to sign CPI calls from your program to the Light System Program.<br />
        * Verified by the Light System Program during CPI.<br />
        * Derived from your program ID.
      </td>
    </tr>

    <tr>
      <td>3</td>
      <td><strong>Registered Program PDA</strong></td>
      <td>Provides access control to the Account Compression Program.</td>
    </tr>

    <tr>
      <td>4</td>
      <td><strong><Tooltip href="https://solscan.io/account/HZH7qSLcpAeDqCopVU4e5XkhT9j3JFsQiq8CmruY3aru">Account Compression Authority</Tooltip></strong></td>
      <td>Signs CPI calls from the Light System Program to the Account Compression Program.</td>
    </tr>

    <tr>
      <td>5</td>
      <td><strong><Tooltip href="https://solscan.io/account/compr6CUsB5m2jS4Y3831ztGSTnDpnKJTKS95d64XVq">Account Compression Program</Tooltip></strong></td>

      <td>
        * Writes to state and address tree accounts.<br />
        * Clients and the Account Compression Program do not interact directly — handled internally.
      </td>
    </tr>

    <tr>
      <td>6</td>
      <td><strong><Tooltip href="https://solscan.io/account/11111111111111111111111111111111">System Program</Tooltip></strong></td>
      <td>Solana System Program used to transfer lamports.</td>
    </tr>
  </tbody>
</table>

# Next Steps

Start building with Compressed Tokens or PDAs

<CardGroup>
  <Card title="Compressed Tokens" icon="chevron-right" href="/compressed-tokens" />

  <Card title="Compressed PDAs" icon="chevron-right" href="/compressed-pdas/overview" />
</CardGroup>


# CLI Installation & Commands
Source: https://www.zkcompression.com/resources/cli-installation

Steps to set up your local environment for ZK Compression development. CLI to interact with compressed accounts and compressed tokens on Solana.

<Info>
  Make sure you have a wallet set up at `~/.config/solana/id.json`. [Get one here](https://docs.solanalabs.com/cli/wallets/file-system), if you don't have one.\
  The CLI will use this wallet as the default fee payer and mint authority.
</Info>

# Installation

<Check>
  <div>
    <span>Ask anything about the ZK Compression CLI via</span>

    <a href="https://deepwiki.com/Lightprotocol/program-examples">
      <img alt="Ask DeepWiki" />
    </a>
  </div>
</Check>

<Steps>
  <Step>
    ### Install the ZK Compression CLI

    <Info>
      Ensure you have Node >= v20.9.0 installed on your machine. Windows users do not require WSL.
    </Info>

    Run this single command to install the ZK Compression CLI.

    ```bash theme={null}
    npm i -g @lightprotocol/zk-compression-cli
    ```

    <Accordion title="Building from source">
      If you prefer to build the CLI from source, follow the steps below to install the necessary prerequisites.

      **1. Activate the Development Environment**

      Ensure you are at the root of the monorepo.

      ```bash theme={null}
      . ./scripts/devenv
      ```

      **2. Install and build the monorepo from source. This also builds the CLI.**

      ```bash theme={null}
      ./scripts/install.sh
      ```

      ```bash theme={null}
      ./scripts/build.sh
      ```

      **3. Make your CLI available globally**

      ```bash theme={null}
      pnpm link --global
      ```

      ```bash theme={null}
      # Verify the CLI was correctly installed
      which light
      ```
    </Accordion>
  </Step>

  <Step>
    ### Set Up Your Environment

    By default, the CLI interacts with localnet. You can view the current config by running:

    ```bash theme={null}
    light config --get
    ```

    **1. Once globally installed, start the Light test validator**

    ```bash theme={null}
    light test-validator
    ```

    This starts a Solana test-validator with the Light System programs and accounts, a prover server, and the Photon indexer as background processes against a clean ledger.

    ```bash theme={null}
    # Pass --skip-indexer to start without the indexer
    light test-validator --skip-indexer

    # Pass --skip-prover to start without the prover
    light test-validator --skip-prover

    ```

    <Note>
      **Note:**

      The CLI currently runs the photon indexer and light-prover as background processes at port: `8784` and `3001` respectively.
    </Note>

    **2. Ensure you have sufficient localnet funds**

    ```bash theme={null}
    # Airdrop 1 SOL
    solana airdrop 1

    # Print your address
    solana address

    # Print your balance
    solana balance
    ```

    Now you're all set up to run CLI commands!

    <Accordion title="Alternative: Using Devnet">
      To switch to Devnet, point the URLs to an RPC supporting ZK Compression. For example, run:

      ```bash theme={null}
        light config --indexerUrl "https://devnet.helius-rpc.com/?api-key=<api-key>" \
          --proverUrl "https://devnet.helius-rpc.com/?api-key=<api-key>" \
          --solanaRpcUrl "https://devnet.helius-rpc.com/?api-key=<api-key>"
      ```

      Also adjust your solana config:

      ```bash theme={null}
      # Set config
      solana config set --url "https://devnet.helius-rpc.com/?api-key=<api-key>"

      # Airdrop 1 SOL
      solana airdrop 1

      # Print your address
      solana address
      ```
    </Accordion>
  </Step>
</Steps>

# Commands

### Create a compressed token mint

```bash theme={null}
light create-mint
```

```bash theme={null}
USAGE
  $ light create-mint [--mint-keypair <value>] [--mint-authority <value>]
    [--mint-decimals <value>]

FLAGS
  --mint-authority=<value>  Path to the mint authority keypair file.
                            Defaults to default local Solana wallet file
                            path.
  --mint-decimals=<value>   Number of base 10 digits to the right
                            of the decimal place [default: 9].
  --mint-keypair=<value>    Path to a mint keypair file. Defaults to a
                            random keypair.
```

### Mint compressed tokens to a Solana wallet

```bash theme={null}
light mint-to --mint "YOUR_MINT_ADDRESS" --to "YOUR_WALLET_ADDRESS" --amount 4200000000
```

```bash theme={null}
USAGE
  $ light mint-to --mint <value> --to <value> --amount <value>
    [--mint-authority <value>]

FLAGS
  --amount=<value>          (required) Amount to mint.
  --mint=<value>            (required) Mint address.
  --mint-authority=<value>  File path of the mint authority keypair.
                            Defaults to local Solana wallet.
  --to=<value>              (required) Recipient address.
```

### Transfer compressed tokens from one wallet to another

```bash theme={null}
light transfer --mint "YOUR_MINT_ADDRESS" --to "RECIPIENT_WALLET_ADDRESS" --amount 4200000000
```

```bash theme={null}
USAGE
  $ light transfer --mint <value> --to <value> --amount <value>
    [--fee-payer <value>]

FLAGS
  --amount=<value>     (required) Amount to send.
  --fee-payer=<value>  Fee payer account. Defaults to the client
                       keypair.
  --mint=<value>       (required) Mint to transfer
  --to=<value>         (required) Recipient address

```

### Assign native SOL to a compressed account

```bash theme={null}
light compress-sol --amount 1000 --to "YOUR_WALLET_ADDRESS_BASE58"
```

```bash theme={null}
USAGE
  $ light compress-sol --to <value> --amount <value>

FLAGS
  --amount=<value>  (required) Amount to compress in lamports.
  --to=<value>      (required) Specify the recipient address.
```

### Decompress into native SOL

```bash theme={null}
light decompress-sol --amount 42 --to "YOUR_WALLET_ADDRESS_BASE58"
```

```bash theme={null}
USAGE
  $ light decompress-sol --to <value> --amount <value>

FLAGS
  --amount=<value>  (required) Amount to decompress in lamports.
  --to=<value>      (required) Specify the recipient address.
```

# Next Steps

<CardGroup>
  <Card title="Build with compressed tokens" icon="chevron-right" href="/compressed-tokens" />

  <Card title="Build with compressed PDAs" icon="chevron-right" href="/compressed-pdas/overview" />
</CardGroup>


# Error Cheatsheet
Source: https://www.zkcompression.com/resources/error-cheatsheet

Complete error code reference for ZK Compression. Search error codes with hex values and messages.

## How to use this page

1. **Search your error code or hex value** with `Cmd+F`/ `Ctrl+F`
2. **Check for debug guides -** some errors have detailed troubleshooting pages
3. **Still having issues?** We're here to help!

* Reach out on [Discord](https://discord.com/invite/CYvjBgzRFP) for support
* Share the exact error code and a reproducer (GitHub repo or [Gist](https://gist.github.com/))

<Tip>
  <div>
    <span>
      For help with debugging use the [MCP Configuration](/ai-tools/guide#mcp) or AskDevin via
    </span>

    <a href="https://deepwiki.com/Lightprotocol/light-protocol">
      <img alt="Ask DeepWiki" />
    </a>
  </div>
</Tip>

## 6000 - 6053 / SystemProgramError Variants

<Info>
  Source code:
  [https://github.com/Lightprotocol/light-protocol/blob/main/programs/system/src/errors.rs](https://github.com/Lightprotocol/light-protocol/blob/604892ff3902292dd0b0b047cb0bfacc469ea0d4/programs/system/src/errors.rs#L133)
</Info>

| Code | Hex    | Error                                           | Message                                                                                                                            |
| :--- | :----- | :---------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- |
| 6000 | 0x1770 | `SumCheckFailed`                                | "Sum check failed"                                                                                                                 |
| 6001 | 0x1771 | `SignerCheckFailed`                             | "Signer check failed"                                                                                                              |
| 6002 | 0x1772 | `CpiSignerCheckFailed`                          | "Cpi signer check failed"                                                                                                          |
| 6003 | 0x1773 | `ComputeInputSumFailed`                         | "Computing input sum failed."                                                                                                      |
| 6004 | 0x1774 | `ComputeOutputSumFailed`                        | "Computing output sum failed."                                                                                                     |
| 6005 | 0x1775 | `ComputeRpcSumFailed`                           | "Computing rpc sum failed."                                                                                                        |
| 6006 | 0x1776 | `InvalidAddress`                                | "InvalidAddress"                                                                                                                   |
| 6007 | 0x1777 | `DeriveAddressError`                            | "DeriveAddressError"                                                                                                               |
| 6008 | 0x1778 | `CompressedSolPdaUndefinedForCompressSol`       | "CompressedSolPdaUndefinedForCompressSol"                                                                                          |
| 6009 | 0x1779 | `DecompressLamportsUndefinedForCompressSol`     | "DecompressLamportsUndefinedForCompressSol"                                                                                        |
| 6010 | 0x177A | `CompressedSolPdaUndefinedForDecompressSol`     | "CompressedSolPdaUndefinedForDecompressSol"                                                                                        |
| 6011 | 0x177B | `DeCompressLamportsUndefinedForDecompressSol`   | "DeCompressLamportsUndefinedForDecompressSol"                                                                                      |
| 6012 | 0x177C | `DecompressRecipientUndefinedForDecompressSol`  | "DecompressRecipientUndefinedForDecompressSol"                                                                                     |
| 6013 | 0x177D | `WriteAccessCheckFailed`                        | "WriteAccessCheckFailed"                                                                                                           |
| 6014 | 0x177E | `InvokingProgramNotProvided`                    | "InvokingProgramNotProvided"                                                                                                       |
| 6015 | 0x177F | `InvalidCapacity`                               | "InvalidCapacity"                                                                                                                  |
| 6016 | 0x1780 | `InvalidMerkleTreeOwner`                        | "InvalidMerkleTreeOwner"                                                                                                           |
| 6017 | 0x1781 | `ProofIsNone`                                   | "ProofIsNone"                                                                                                                      |
| 6018 | 0x1782 | `ProofIsSome`                                   | "Proof is some but no input compressed accounts or new addresses provided."                                                        |
| 6019 | 0x1783 | `EmptyInputs`                                   | "EmptyInputs"                                                                                                                      |
| 6020 | 0x1784 | `CpiContextAccountUndefined`                    | "CpiContextAccountUndefined"                                                                                                       |
| 6021 | 0x1785 | `CpiContextEmpty`                               | "CpiContextEmpty"                                                                                                                  |
| 6022 | 0x1786 | `CpiContextMissing`                             | "CpiContextMissing"                                                                                                                |
| 6023 | 0x1787 | `DecompressionRecipientDefined`                 | "DecompressionRecipientDefined"                                                                                                    |
| 6024 | 0x1788 | `SolPoolPdaDefined`                             | "SolPoolPdaDefined"                                                                                                                |
| 6025 | 0x1789 | `AppendStateFailed`                             | "AppendStateFailed"                                                                                                                |
| 6026 | 0x178A | `InstructionNotCallable`                        | "The instruction is not callable"                                                                                                  |
| 6027 | 0x178B | `CpiContextFeePayerMismatch`                    | "CpiContextFeePayerMismatch"                                                                                                       |
| 6028 | 0x178C | `CpiContextAssociatedMerkleTreeMismatch`        | "CpiContextAssociatedMerkleTreeMismatch"                                                                                           |
| 6029 | 0x178D | `NoInputs`                                      | "NoInputs"                                                                                                                         |
| 6030 | 0x178E | `InputMerkleTreeIndicesNotInOrder`              | "Input merkle tree indices are not in ascending order."                                                                            |
| 6031 | 0x178F | `OutputMerkleTreeIndicesNotInOrder`             | "Output merkle tree indices are not in ascending order."                                                                           |
| 6032 | 0x1790 | `OutputMerkleTreeNotUnique`                     | "OutputMerkleTreeNotUnique"                                                                                                        |
| 6033 | 0x1791 | `DataFieldUndefined`                            | "DataFieldUndefined"                                                                                                               |
| 6034 | 0x1792 | `ReadOnlyAddressAlreadyExists`                  | "ReadOnlyAddressAlreadyExists"                                                                                                     |
| 6035 | 0x1793 | `ReadOnlyAccountDoesNotExist`                   | "ReadOnlyAccountDoesNotExist"                                                                                                      |
| 6036 | 0x1794 | `HashChainInputsLenghtInconsistent`             | "HashChainInputsLenghtInconsistent"                                                                                                |
| 6037 | 0x1795 | `InvalidAddressTreeHeight`                      | "InvalidAddressTreeHeight"                                                                                                         |
| 6038 | 0x1796 | `InvalidStateTreeHeight`                        | "InvalidStateTreeHeight"                                                                                                           |
| 6039 | 0x1797 | `InvalidArgument`                               | "InvalidArgument"                                                                                                                  |
| 6040 | 0x1798 | `InvalidAccount`                                | "InvalidAccount"                                                                                                                   |
| 6041 | 0x1799 | `AddressMerkleTreeAccountDiscriminatorMismatch` | "AddressMerkleTreeAccountDiscriminatorMismatch"                                                                                    |
| 6042 | 0x179A | `StateMerkleTreeAccountDiscriminatorMismatch`   | "StateMerkleTreeAccountDiscriminatorMismatch"                                                                                      |
| 6043 | 0x179B | `ProofVerificationFailed`                       | "Proof verification failed."<br />[How to debug this error](/resources/error-cheatsheet/debug-0x179b-6043-proofverificationfailed) |
| 6044 | 0x179C | `InvalidAccountMode`                            | "Invalid account mode."                                                                                                            |
| 6045 | 0x179D | `InvalidInstructionDataDiscriminator`           | "InvalidInstructionDataDiscriminator"                                                                                              |
| 6046 | 0x179E | `NewAddressAssignedIndexOutOfBounds`            | "NewAddressAssignedIndexOutOfBounds"                                                                                               |
| 6047 | 0x179F | `AddressIsNone`                                 | "AddressIsNone"                                                                                                                    |
| 6048 | 0x17A0 | `AddressDoesNotMatch`                           | "AddressDoesNotMatch"                                                                                                              |
| 6049 | 0x17A1 | `CpiContextAlreadySet`                          | "CpiContextAlreadySet"                                                                                                             |
| 6050 | 0x17A2 | `InvalidTreeHeight`                             | "InvalidTreeHeight"                                                                                                                |
| 6051 | 0x17A3 | `TooManyOutputAccounts`                         | "TooManyOutputAccounts"                                                                                                            |
| 6052 | 0x17A4 | `BorrowingDataFailed`                           | "Borrowing data failed"                                                                                                            |
| 6053 | 0x17A5 | `DuplicateAccountInInputsAndReadOnly`           | "DuplicateAccountInInputsAndReadOnly"                                                                                              |

## 7001 - 7009 / HasherError Variants

<Info>
  Source code:
  [https://github.com/Lightprotocol/light-protocol/blob/program-libs/hasher/src/errors.rs](https://github.com/Lightprotocol/light-protocol/blob/604892ff3902292dd0b0b047cb0bfacc469ea0d4/program-libs/hasher/src/errors.rs)
</Info>

| Code | Hex    | Error                                   | Message                                                                                   |
| :--- | :----- | :-------------------------------------- | :---------------------------------------------------------------------------------------- |
| 7001 | 0x1B59 | `IntegerOverflow`                       | "Integer overflow, value too large"                                                       |
| 7003 | 0x1B5B | `PoseidonSyscall(PoseidonSyscallError)` | "Poseidon syscall error: "                                                                |
| 7005 | 0x1B5D | `InvalidInputLength(usize, usize)`      | "Allowed input length  provided "                                                         |
| 7006 | 0x1B5E | `InvalidNumFields`                      | "Invalid number of fields"                                                                |
| 7007 | 0x1B5F | `EmptyInput`                            | "Empty input"                                                                             |
| 7008 | 0x1B60 | `BorshError`                            | "Borsh serialization failed."                                                             |
| 7009 | 0x1B61 | `OptionHashToFieldSizeZero`             | "Option hash to field size returned \[0u8;32], a collision with None for an Option type." |

## 10001 - 10014 / ConcurrentMerkleTreeError Variants

<Info>
  Source code:
  [https://github.com/Lightprotocol/light-protocol/blob/program-libs/concurrent-merkle-tree/src/errors.rs](https://github.com/Lightprotocol/light-protocol/blob/604892ff3902292dd0b0b047cb0bfacc469ea0d4/program-libs/concurrent-merkle-tree/src/errors.rs)
</Info>

| Code  | Hex    | Error                                     | Message                                                                                                           |
| :---- | :----- | :---------------------------------------- | :---------------------------------------------------------------------------------------------------------------- |
| 10001 | 0x2711 | `IntegerOverflow`                         | "Integer overflow"                                                                                                |
| 10002 | 0x2712 | `HeightZero`                              | "Invalid height, it has to be greater than 0"                                                                     |
| 10003 | 0x2713 | `InvalidHeight(usize)`                    | "Invalid height, expected "                                                                                       |
| 10004 | 0x2714 | `ChangelogZero`                           | "Invalid changelog size, it has to be greater than 0. Changelog is used for storing Merkle paths during appends." |
| 10005 | 0x2715 | `RootsZero`                               | "Invalid number of roots, it has to be greater than 0"                                                            |
| 10006 | 0x2716 | `CanopyGeThanHeight`                      | "Canopy depth has to be lower than height"                                                                        |
| 10007 | 0x2717 | `TreeIsFull`                              | "Merkle tree is full, cannot append more leaves."                                                                 |
| 10008 | 0x2718 | `BatchGreaterThanChangelog(usize, usize)` | "Number of leaves () exceeds the changelog capacity ()."                                                          |
| 10009 | 0x2719 | `InvalidProofLength(usize, usize)`        | "Invalid proof length, expected , got ."                                                                          |
| 10010 | 0x271A | `InvalidProof([u8; 32], [u8; 32])`        | "Invalid Merkle proof, expected root: `{0:?}`, the provided proof produces root: `{1:?}`"                         |
| 10011 | 0x271B | `CannotUpdateLeaf`                        | "Attempting to update the leaf which was updated by an another newest change."                                    |
| 10012 | 0x271C | `CannotUpdateEmpty`                       | "Cannot update the empty leaf"                                                                                    |
| 10013 | 0x271D | `EmptyLeaves`                             | "The batch of leaves is empty"                                                                                    |
| 10014 | 0x271E | `BufferSize(usize, usize)`                | "Invalid buffer size, expected , got "                                                                            |

## 11001 - 11009 / IndexedMerkleTreeError Variants

<Info>
  Source code:
  [https://github.com/Lightprotocol/light-protocol/blob/program-libs/indexed-merkle-tree/src/errors.rs](https://github.com/Lightprotocol/light-protocol/blob/604892ff3902292dd0b0b047cb0bfacc469ea0d4/program-libs/indexed-merkle-tree/src/errors.rs)
</Info>

| Code  | Hex    | Error                                   | Message                                                             |
| :---- | :----- | :-------------------------------------- | :------------------------------------------------------------------ |
| 11001 | 0x2AF9 | `IntegerOverflow`                       | "Integer overflow"                                                  |
| 11002 | 0x2AFA | `IndexHigherThanMax`                    | "Invalid index, it exceeds the number of elements."                 |
| 11003 | 0x2AFB | `LowElementNotFound`                    | "Could not find the low element."                                   |
| 11004 | 0x2AFC | `LowElementGreaterOrEqualToNewElement`  | "Low element is greater or equal to the provided new element."      |
| 11005 | 0x2AFD | `NewElementGreaterOrEqualToNextElement` | "The provided new element is greater or equal to the next element." |
| 11006 | 0x2AFE | `ElementAlreadyExists`                  | "The element already exists, but was expected to be absent."        |
| 11007 | 0x2AFF | `ElementDoesNotExist`                   | "The element does not exist, but was expected to be present."       |
| 11008 | 0x2B00 | `ChangelogBufferSize(usize, usize)`     | "Invalid changelog buffer size, expected , got "                    |
| 11009 | 0x2B01 | `ArrayFull`                             | "Indexed array is full, cannot append more elements"                |

## 12006 - 12019 / AccountError Variants

<Info>
  Source code:
  [https://github.com/Lightprotocol/light-protocol/blob/program-libs/account-checks/src/error.rs](https://github.com/Lightprotocol/light-protocol/blob/604892ff3902292dd0b0b047cb0bfacc469ea0d4/program-libs/account-checks/src/error.rs)
</Info>

| Code  | Hex    | Error                        | Message                           |
| :---- | :----- | :--------------------------- | :-------------------------------- |
| 12006 | 0x2EE6 | `InvalidDiscriminator`       | "Invalid Discriminator."          |
| 12007 | 0x2EE7 | `AccountOwnedByWrongProgram` | "Account owned by wrong program." |
| 12008 | 0x2EE8 | `AccountNotMutable`          | "Account not mutable."            |
| 12009 | 0x2EE9 | `BorrowAccountDataFailed`    | "Borrow account data failed."     |
| 12010 | 0x2EEA | `InvalidAccountSize`         | "Invalid Account size."           |
| 12011 | 0x2EEB | `AccountMutable`             | "Account is mutable."             |
| 12012 | 0x2EEC | `AlreadyInitialized`         | "Account is already initialized." |
| 12013 | 0x2EED | `InvalidAccountBalance`      | "Invalid account balance."        |
| 12014 | 0x2EEE | `FailedBorrowRentSysvar`     | "Failed to borrow rent sysvar."   |
| 12015 | 0x2EEF | `InvalidSigner`              | "Invalid Signer"                  |
| 12016 | 0x2EF0 | `InvalidSeeds`               | "Invalid Seeds"                   |
| 12017 | 0x2EF1 | `InvalidProgramId`           | "Invalid Program Id"              |
| 12018 | 0x2EF2 | `ProgramNotExecutable`       | "Program not executable."         |
| 12019 | 0x2EF3 | `AccountNotZeroed`           | "Account not zeroed."             |

## 14001 - 14009 / MerkleTreeMetadataError Variants

<Info>
  Source code:
  [https://github.com/Lightprotocol/light-protocol/blob/program-libs/merkle-tree-metadata/src/errors.rs](https://github.com/Lightprotocol/light-protocol/blob/604892ff3902292dd0b0b047cb0bfacc469ea0d4/program-libs/merkle-tree-metadata/src/errors.rs)
</Info>

| Code  | Hex    | Error                             | Message                                     |
| :---- | :----- | :-------------------------------- | :------------------------------------------ |
| 14001 | 0x36B1 | `MerkleTreeAndQueueNotAssociated` | "Merkle tree and queue are not associated." |
| 14002 | 0x36B2 | `RolloverNotConfigured`           | "Rollover not configured."                  |
| 14003 | 0x36B3 | `MerkleTreeAlreadyRolledOver`     | "Merkle tree already rolled over."          |
| 14004 | 0x36B4 | `InvalidQueueType`                | "Invalid queue type."                       |
| 14005 | 0x36B5 | `InsufficientRolloverFee`         | "Insufficient rollover fee."                |
| 14006 | 0x36B6 | `NotReadyForRollover`             | "Merkle tree not ready for rollover."       |
| 14007 | 0x36B7 | `InvalidTreeType`                 | "Invalid tree type."                        |
| 14008 | 0x36B8 | `InvalidRolloverThreshold`        | "Invalid Rollover Threshold."               |
| 14009 | 0x36B9 | `InvalidHeight`                   | "Invalid Height."                           |

## 14017 - 14034 / LightSdkTypesError Variants

<Info>
  Source code:
  [https://github.com/Lightprotocol/light-protocol/blob/sdk-libs/sdk-types/src/error.rs](https://github.com/Lightprotocol/light-protocol/blob/604892ff3902292dd0b0b047cb0bfacc469ea0d4/sdk-libs/sdk-types/src/error.rs#L4)
</Info>

| Code  | Hex    | Error                                | Message                                                                                                                                           |
| :---- | :----- | :----------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
| 14017 | 0x36C1 | `FewerAccountsThanSystemAccounts`    | "Fewer accounts than system accounts"                                                                                                             |
| 14021 | 0x36C5 | `InitAddressIsNone`                  | "Address is none during initialization"                                                                                                           |
| 14022 | 0x36C6 | `InitWithAddressIsNone`              | "Address is none during initialization with address"                                                                                              |
| 14023 | 0x36C7 | `InitWithAddressOutputIsNone`        | "Output is none during initialization with address"                                                                                               |
| 14024 | 0x36C8 | `MetaMutAddressIsNone`               | "Address is none during meta mutation"                                                                                                            |
| 14025 | 0x36C9 | `MetaMutInputIsNone`                 | "Input is none during meta mutation"                                                                                                              |
| 14026 | 0x36CA | `MetaMutOutputLamportsIsNone`        | "Output lamports is none during meta mutation"                                                                                                    |
| 14027 | 0x36CB | `MetaMutOutputIsNone`                | "Output is none during meta mutation"                                                                                                             |
| 14028 | 0x36CC | `MetaCloseAddressIsNone`             | "Address is none during meta close"                                                                                                               |
| 14029 | 0x36CD | `MetaCloseInputIsNone`               | "Input is none during meta close"                                                                                                                 |
| 14031 | 0x36CF | `CpiAccountsIndexOutOfBounds(usize)` | "CPI accounts index out of bounds: "                                                                                                              |
| 14032 | 0x36D0 | `InvalidCpiContextAccount`           | "Invalid CPI context account"                                                                                                                     |
| 14033 | 0x36D1 | `InvalidSolPoolPdaAccount`           | "Invalid sol pool pda account"                                                                                                                    |
| 14034 | 0x36D2 | `InvalidCpiAccountsOffset`           | "CpiAccounts accounts slice starts with an invalid account. It should start with LightSystemProgram SySTEM1eSU2p4BGQfQpimFEWWSC1XDFeun3Nqzz3rT7." |

## 14301 - 14312 / BatchedMerkleTreeError Variants

<Info>
  Source code:
  [https://github.com/Lightprotocol/light-protocol/blob/program-libs/batched-merkle-tree/src/errors.rs](https://github.com/Lightprotocol/light-protocol/blob/604892ff3902292dd0b0b047cb0bfacc469ea0d4/program-libs/batched-merkle-tree/src/errors.rs)
</Info>

| Code  | Hex    | Error                                 | Message                                                 |
| :---- | :----- | :------------------------------------ | :------------------------------------------------------ |
| 14301 | 0x37DD | `BatchNotReady`                       | "Batch is not ready to be inserted"                     |
| 14302 | 0x37DE | `BatchAlreadyInserted`                | "Batch is already inserted"                             |
| 14303 | 0x37DF | `BatchInsertFailed`                   | "Batch insert failed"                                   |
| 14304 | 0x37E0 | `LeafIndexNotInBatch`                 | "Leaf index not in batch."                              |
| 14305 | 0x37E1 | `InvalidNetworkFee`                   | "Invalid network fee."                                  |
| 14306 | 0x37E2 | `BatchSizeNotDivisibleByZkpBatchSize` | "Batch size not divisible by ZKP batch size."           |
| 14307 | 0x37E3 | `InclusionProofByIndexFailed`         | "Inclusion proof by index failed."                      |
| 14308 | 0x37E4 | `InvalidBatchIndex`                   | "Invalid batch index"                                   |
| 14309 | 0x37E5 | `InvalidIndex`                        | "Invalid index"                                         |
| 14310 | 0x37E6 | `TreeIsFull`                          | "Batched Merkle tree is full."                          |
| 14311 | 0x37E7 | `NonInclusionCheckFailed`             | "Value already exists in bloom filter."                 |
| 14312 | 0x37E8 | `BloomFilterNotZeroed`                | "Bloom filter must be zeroed prior to reusing a batch." |

## 15001 - 15017 / ZeroCopyError Variants

<Info>
  Source code:
  [https://github.com/Lightprotocol/light-protocol/blob/program-libs/zero-copy/src/errors.rs](https://github.com/Lightprotocol/light-protocol/blob/604892ff3902292dd0b0b047cb0bfacc469ea0d4/program-libs/zero-copy/src/errors.rs)
</Info>

| Code  | Hex    | Error                                       | Message                                                  |
| :---- | :----- | :------------------------------------------ | :------------------------------------------------------- |
| 15001 | 0x3A99 | `Full`                                      | "The vector is full, cannot push any new elements"       |
| 15002 | 0x3A9A | `ArraySize(usize, usize)`                   | "Requested array of size , but the vector has  elements" |
| 15003 | 0x3A9B | `IterFromOutOfBounds`                       | "The requested start index is out of bounds"             |
| 15004 | 0x3A9C | `InsufficientMemoryAllocated(usize, usize)` | "Memory allocated , Memory required "                    |
| 15006 | 0x3A9E | `UnalignedPointer`                          | "Unaligned pointer"                                      |
| 15007 | 0x3A9F | `MemoryNotZeroed`                           | "Memory not zeroed"                                      |
| 15008 | 0x3AA0 | `InvalidConversion`                         | "Invalid conversion"                                     |
| 15009 | 0x3AA1 | `InvalidData(Infallible)`                   | "Invalid data"                                           |
| 15010 | 0x3AA2 | `Size`                                      | "Invalid size"                                           |
| 15011 | 0x3AA3 | `InvalidOptionByte(u8)`                     | "Invalid option byte  must be 0 (None) or 1 (Some)"      |
| 15012 | 0x3AA4 | `InvalidCapacity`                           | "Invalid capacity. Capacity must be greater than 0"      |
| 15013 | 0x3AA5 | `LengthGreaterThanCapacity`                 | "Length is greater than capacity"                        |
| 15014 | 0x3AA6 | `CurrentIndexGreaterThanLength`             | "Current index is greater than length"                   |
| 15015 | 0x3AA7 | `InvalidEnumValue`                          | "Invalid enum value"                                     |
| 15016 | 0x3AA8 | `InsufficientCapacity`                      | "Insufficient capacity for operation"                    |
| 15017 | 0x3AA9 | `PlatformSizeOverflow`                      | "Value too large for platform usize"                     |

## 16001 - 16034 / LightSdkError Variants

<Info>
  Source code:
  [https://github.com/Lightprotocol/light-protocol/blob/main/sdk-libs/sdk/src/error.rs](https://github.com/Lightprotocol/light-protocol/blob/main/sdk-libs/sdk/src/error.rs#L126)
</Info>

| Code  | Hex    | Error                                | Message                                                                                                                                           |
| :---- | :----- | :----------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
| 16001 | 0x3E81 | `ConstraintViolation`                | "Constraint violation"                                                                                                                            |
| 16002 | 0x3E82 | `InvalidLightSystemProgram`          | "Invalid light-system-program ID"                                                                                                                 |
| 16003 | 0x3E83 | `ExpectedAccounts`                   | "Expected accounts in the instruction"                                                                                                            |
| 16004 | 0x3E84 | `ExpectedAddressTreeInfo`            | "Expected address Merkle context to be provided"                                                                                                  |
| 16005 | 0x3E85 | `ExpectedAddressRootIndex`           | "Expected address root index to be provided"                                                                                                      |
| 16006 | 0x3E86 | `ExpectedData`                       | "Accounts with a specified input are expected to have data"                                                                                       |
| 16007 | 0x3E87 | `ExpectedDiscriminator`              | "Accounts with specified data are expected to have a discriminator"                                                                               |
| 16008 | 0x3E88 | `ExpectedHash`                       | "Accounts with specified data are expected to have a hash"                                                                                        |
| 16009 | 0x3E89 | `ExpectedLightSystemAccount(String)` | "Expected the `{0}` light account to be provided"                                                                                                 |
| 16010 | 0x3E8A | `ExpectedMerkleContext`              | "`mut` and `close` accounts are expected to have a Merkle context"                                                                                |
| 16011 | 0x3E8B | `ExpectedRootIndex`                  | "Expected root index to be provided"                                                                                                              |
| 16012 | 0x3E8C | `TransferFromNoInput`                | "Cannot transfer lamports from an account without input"                                                                                          |
| 16013 | 0x3E8D | `TransferFromNoLamports`             | "Cannot transfer from an account without lamports"                                                                                                |
| 16014 | 0x3E8E | `TransferFromInsufficientLamports`   | "Account, from which a transfer was attempted, has insufficient amount of lamports"                                                               |
| 16015 | 0x3E8F | `TransferIntegerOverflow`            | "Integer overflow resulting from too large resulting amount"                                                                                      |
| 16016 | 0x3E90 | `Borsh`                              | "Borsh error."                                                                                                                                    |
| 16017 | 0x3E91 | `FewerAccountsThanSystemAccounts`    | "Fewer accounts than number of system accounts."                                                                                                  |
| 16018 | 0x3E92 | `InvalidCpiSignerAccount`            | "InvalidCpiSignerAccount"                                                                                                                         |
| 16019 | 0x3E93 | `MissingField(String)`               | "Missing meta field: "                                                                                                                            |
| 16020 | 0x3E94 | `OutputStateTreeIndexIsNone`         | "Output state tree index is none. Use an CompressedAccountMeta type with output tree index to initialize or update accounts."                     |
| 16021 | 0x3E95 | `InitAddressIsNone`                  | "Address is none during initialization"                                                                                                           |
| 16022 | 0x3E96 | `InitWithAddressIsNone`              | "Address is none during initialization with address"                                                                                              |
| 16023 | 0x3E97 | `InitWithAddressOutputIsNone`        | "Output is none during initialization with address"                                                                                               |
| 16024 | 0x3E98 | `MetaMutAddressIsNone`               | "Address is none during meta mutation"                                                                                                            |
| 16025 | 0x3E99 | `MetaMutInputIsNone`                 | "Input is none during meta mutation"                                                                                                              |
| 16026 | 0x3E9A | `MetaMutOutputLamportsIsNone`        | "Output lamports is none during meta mutation"                                                                                                    |
| 16027 | 0x3E9B | `MetaMutOutputIsNone`                | "Output is none during meta mutation"                                                                                                             |
| 16028 | 0x3E9C | `MetaCloseAddressIsNone`             | "Address is none during meta close"                                                                                                               |
| 16029 | 0x3E9D | `MetaCloseInputIsNone`               | "Input is none during meta close"                                                                                                                 |
| 16031 | 0x3E9F | `CpiAccountsIndexOutOfBounds(usize)` | "CPI accounts index out of bounds: "                                                                                                              |
| 16032 | 0x3EA0 | `InvalidCpiContextAccount`           | "Invalid CPI context account"                                                                                                                     |
| 16033 | 0x3EA1 | `InvalidSolPoolPdaAccount`           | "Invalid SolPool PDA account"                                                                                                                     |
| 16034 | 0x3EA2 | `InvalidCpiAccountsOffset`           | "CpiAccounts accounts slice starts with an invalid account. It should start with LightSystemProgram SySTEM1eSU2p4BGQfQpimFEWWSC1XDFeun3Nqzz3rT7." |


# Debug ProofVerificationFailed (0x179b)
Source: https://www.zkcompression.com/resources/error-cheatsheet/debug-0x179b-6043-proofverificationfailed

Common cause and debug steps for ProofVerificationFailed (0x179B / 6043)

### Description

You're passing an invalid proof. The proof provided cannot be verified against the expected state.

<Check>
  <div>
    <span>For help with debugging use the [MCP Configuration](/ai-tools/guide#mcp) or AskDevin via</span>

    <a href="https://deepwiki.com/Lightprotocol/light-protocol">
      <img alt="Ask DeepWiki" />
    </a>
  </div>
</Check>

### Common causes and Debug Steps

<Info>
  For a complete example of proper client+on chain flows, see the [Counter Program](https://github.com/Lightprotocol/program-examples/blob/main/counter/anchor/programs/counter/src/lib.rs#L26).
</Info>

<Accordion title="Inconsistent Address Seed - Client seeds don't match on chain address derivation">
  Compare client vs on chain seeds/addresses. Both should be identical.

  ```typescript theme={null}
  // Client - log seeds/address used to request proof
  console.log("Client seeds:", seeds, "address:", address);
  ```

  ```rust theme={null}
  // Onchain - log seeds/address
  msg!("Program seeds: {:?}, address: {:?}", seeds, address);
  ```
</Accordion>

### Still having issues? We're here to help!

* Reach out on [Discord](https://discord.com/invite/CYvjBgzRFP) for support
* Share the exact error code and a reproducer (GitHub repo or [Gist](https://gist.github.com/))


# Client Development
Source: https://www.zkcompression.com/resources/sdks/client-development

Overview of Rust and TypeScript SDKs for client side development.

<table>
  <thead>
    <tr>
      <th />

      <th />

      <th />
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**TypeScript**</td>
      <td>[@lightprotocol/stateless.js](https://lightprotocol.github.io/light-protocol/stateless.js/index.html)</td>
      <td>Client SDK for Compressed Accounts</td>
    </tr>

    <tr>
      <td>**TypeScript**</td>
      <td>[@lightprotocol/compressed-token](https://lightprotocol.github.io/light-protocol/compressed-token/index.html)</td>
      <td>Client SDK for Compressed Tokens</td>
    </tr>

    <tr>
      <td>**Rust**</td>
      <td>[light-client](https://docs.rs/light-client)</td>
      <td>Client SDK for Compressed Accounts and Tokens</td>
    </tr>
  </tbody>
</table>

### Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install --save \
      @lightprotocol/stateless.js \
      @lightprotocol/compressed-token \
      @solana/web3.js \
      @lightprotocol/zk-compression-cli
  ```

  ```bash Yarn theme={null}
  yarn add \
      @lightprotocol/stateless.js \
      @lightprotocol/compressed-token \
      @solana/web3.js \
      @lightprotocol/zk-compression-cli
  ```
</CodeGroup>

### Dependencies

```toml theme={null}
[dependencies]
light-client = "0.16.0"
light-sdk = "0.16.0"
```

### Examples and Guide

<CardGroup>
  <Card icon="github" title="example-web-client" href="https://github.com/Lightprotocol/example-web-client" />

  <Card icon="github" title="example-nodejs-client" href="https://github.com/Lightprotocol/example-nodejs-client" />
</CardGroup>

<Card title="Build your client with this guide." icon="chevron-right" href="/client-library/client-guide" />


# Program Development
Source: https://www.zkcompression.com/resources/sdks/program-development

Overview of on-chain program development using Anchor, Pinocchio, or native Rust SDKs.

## Rust Crates

ZK Compression's Rust crates are published to [crates.io](https://docs.rs/releases/search?query=zk+compression) and can be found on [docs.rs](https://crates.io/search?q=zk%20compression) with the `light-` prefix.

* [`light-sdk`](https://github.com/Lightprotocol/light-protocol/tree/main/sdk-libs/sdk) — For Anchor and native programs. Includes CPI utilities, compressed account abstractions similar to anchor Account, and metadata structs for CPIs to the Light System program.
* [`light-sdk-pinocchio`](https://github.com/Lightprotocol/light-protocol/tree/main/sdk-libs/sdk-pinocchio) — For Pinocchio programs. Pinocchio-optimized SDK with compressed account abstractions and CPI utilities.

## Light Programs Overview

<Info>
  Your custom program invokes the *Light system program* via Cross-Program Invocation (CPI) to leverage ZK Compression.
</Info>

| Program                                                                                                       | Description                                                                                                                                                                                |
| :------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [light-system-program](https://github.com/Lightprotocol/light-protocol/tree/main/programs/system)             | Enforces compressed account layout, ownership checks, and validity proof verification. Used to create/write compressed accounts and PDAs.                                                  |
| [light-compressed-token](https://crates.io/crates/light-compressed-token)                                     | SPL-compatible compressed token implementation with arbitrary compression/decompression support.                                                                                           |
| [account-compression](https://github.com/Lightprotocol/light-protocol/tree/main/programs/account-compression) | State and address tree implementation used by the Light System program. Clients and custom programs do not interact with the Account Compression Program — this is handled under the hood. |

## Version Requirements

<Info>
  Required versions:

  * **Rust**: 1.86.0 or later
  * **Solana CLI**: 2.2.15
  * **Anchor CLI**: 0.31.1
  * **Zk compression CLI**: 0.27.0 or later
  * **Node.js**: 23.5.0 or later
</Info>

<Accordion title="Installation">
  **Install Solana CLI:**

  ```bash theme={null}
  sh -c "$(curl -sSfL https://release.solana.com/v2.2.15/install)"
  ```

  **Install Anchor CLI:**

  ```bash theme={null}
  cargo install --git https://github.com/coral-xyz/anchor avm --force
  avm install latest
  avm use latest
  ```

  **Install the Light CLI:**

  <Tabs>
    <Tab title="npm">
      ```bash theme={null}
      npm install -g @lightprotocol/zk-compression-cli@beta
      ```
    </Tab>

    <Tab title="yarn">
      ```bash theme={null}
      yarn global add @lightprotocol/zk-compression-cli@beta
      ```
    </Tab>

    <Tab title="pnpm">
      ```bash theme={null}
      pnpm add -g @lightprotocol/zk-compression-cli@beta
      ```
    </Tab>
  </Tabs>

  **Verify installation:**

  ```bash theme={null}
  light --version
  ```
</Accordion>

## Next Steps

Build your own program or view program examples.

<CardGroup>
  <Card title="Program Guides" icon="chevron-right" href="/compressed-pdas/guides" />

  <Card title="Program Examples" icon="chevron-right" href="/compressed-pdas/program-examples" />
</CardGroup>


# Support
Source: https://www.zkcompression.com/support

Get expert help with Light-Token and ZK Compression. Discord community, Telegram, and Email support available.

<CardGroup>
  <Card title="Dev Support" icon="https://mintcdn.com/luminouslabs-cc5545c6/5qA-T-Fq7V1ZTy2k/images/light-logo.svg?fit=max&auto=format&n=5qA-T-Fq7V1ZTy2k&q=85&s=8297f15d5084df0677e29e6a298fb5fc" href="https://discord.gg/CYvjBgzRFP">
    Head to Light's Discord.
  </Card>

  <Card title="RPC & Indexer Support" icon="https://mintcdn.com/luminouslabs-cc5545c6/xRfewy6MgujOWc7J/images/helius-logo.svg?fit=max&auto=format&n=xRfewy6MgujOWc7J&q=85&s=e5b0924f2d7a263a5a674a128a086ab6" href="https://discord.gg/Uzzf6a7zKr">
    Head to the Helius Discord.
  </Card>
</CardGroup>

## Reporting Technical Issues

Before reaching out, try the Error Cheatsheet or DeepWiki.

<Info>
  When reporting technical issues,

  1. Include as much detail as possible in your question,
  2. Provide a reproducer or [GitHub code snippet](https://gist.github.com/) if possible,
  3. Please use text (not screenshots) to show error messages so other people with the same problem can find your question.
</Info>

## Quick Fixes

### Look Up Errors

<Card title="Error Cheatsheet" icon="chevron-right" href="/resources/error-cheatsheet" />

### AI Assistance

Install our MCP server for advanced AI assistance.

<Card title="AI Tools Guide" icon="chevron-right" href="/ai-tools/guide#mcp" />

#### Alternative: DeepWiki Web

If you don't have the MCP installed we recommend to use AskDevin in your browser.

<Card title="Follow this link and Ask Devin" icon="chevron-right" href="https://deepwiki.com/Lightprotocol/light-protocol" />

<Frame>
  <iframe title="DeepWiki Video" />
</Frame>

<Info>
  You can index and query any public GitHub repository with DeepWiki to produce wikis with architecture diagrams, source links, and codebase summaries.
</Info>


# Welcome to ZK Compression
Source: https://www.zkcompression.com/welcome

ZK Compression is a Solana account primitive that lets you create tokens and PDAs without rent-exemption with L1 performance and security.

<Frame>
  <img alt="" />
</Frame>

| **Creation Cost** | Solana               | ZK Compression        |
| :---------------- | :------------------- | :-------------------- |
| **Token Account** | \~2,000,000 lamports | \~**5,000** lamports  |
| **100-byte PDA**  | \~1,600,000 lamports | \~**15,000** lamports |

## Features

<Card title="Light Token Program" href="/light-token/welcome" icon="coins">
  High performance token standard for rent-free DeFi and Payments.
</Card>

<CardGroup>
  <Card title="Compressed PDAs" href="/compressed-pdas/overview" icon="user">
    For App State.
  </Card>

  <Card title="Compressed Tokens" href="/compressed-tokens" icon="wallet">
    For Token Distribution.
  </Card>
</CardGroup>

## Quickstart

<Steps>
  <Step title="Installation">
    <Tabs>
      <Tab title="npm">
        Install packages in your working directory:

        ```bash theme={null}
        npm install @lightprotocol/stateless.js@beta \
                    @lightprotocol/compressed-token@beta
        ```

        Install the CLI globally:

        ```bash theme={null}
        npm install -g @lightprotocol/zk-compression-cli@beta
        ```
      </Tab>

      <Tab title="yarn">
        Install packages in your working directory:

        ```bash theme={null}
        yarn add @lightprotocol/stateless.js@beta \
                 @lightprotocol/compressed-token@beta
        ```

        Install the CLI globally:

        ```bash theme={null}
        yarn global add @lightprotocol/zk-compression-cli@beta
        ```
      </Tab>

      <Tab title="pnpm">
        Install packages in your working directory:

        ```bash theme={null}
        pnpm add @lightprotocol/stateless.js@beta \
                 @lightprotocol/compressed-token@beta
        ```

        Install the CLI globally:

        ```bash theme={null}
        pnpm add -g @lightprotocol/zk-compression-cli@beta
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Get started">
    <Card title="Mint Compressed Tokens in less than 5 minutes" href="/quickstart" icon="bolt" />
  </Step>
</Steps>

## What is ZK Compression?

ZK Compression is a framework that reduces the storage cost of Solana accounts by combining generalized state compression and <Tooltip>zero-knowledge proofs</Tooltip>.

<Steps>
  <Step title="State Compression">
    State compression stores account data on the Solana ledger instead of in millions of on-chain accounts. Only a small fingerprint of all accounts is stored on-chain for cryptographic integrity. Using Light Protocol, programs can use the account data inside Solana's virtual machine as if it were stored on-chain.
  </Step>

  <Step title="ZK">
    The protocol uses 128 byte zero-knowledge proofs (validity proofs) to verify the integrity of
    the compressed accounts. By default, this is all done under the hood. You can fetch validity
    proofs from RPC providers that support ZK Compression.
  </Step>
</Steps>

## Resources

<CardGroup>
  <Card title="RPC Methods" href="/api-reference/json-rpc-methods/overview" icon="tower-broadcast">
    Browse ZK Compression's JSON RPC methods.
  </Card>

  <Card title="SDKs" href="/resources/sdks" icon="code">
    Explore our TypeScript and Rust SDKs.
  </Card>

  <Card title="CLI Installation" href="/resources/cli-installation" icon="terminal">
    Install the ZK Compression CLI for local development.
  </Card>
</CardGroup>

## Learn & Community

<CardGroup>
  <Card title="Start Learning" href="/learn/core-concepts" icon="graduation-cap">
    Learn about ZK Compression's core concepts.
  </Card>

  <Card title="Security" href="/references/security" icon="shield-halved">
    Read our external audit and formal verification reports.
  </Card>

  <Card title="Discord" href="https://discord.com/invite/CYvjBgzRFP" icon="discord">
    Join our Discord for support and discussions.
  </Card>
</CardGroup>

## Next Steps

<Card title="Quickstart: Mint Compressed Tokens in less than 5 minutes" icon="chevron-right" href="/quickstart" />


# Examples
Source: https://www.zkcompression.com/zk/examples

Example projects for building ZK programs on Solana.

|                                                                                          | Description                                                                                                                     |
| :--------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |
| [ZK-ID](https://github.com/Lightprotocol/program-examples/tree/main/zk/zk-id)            | Identity verification using Groth16 proofs. Issuers create credentials; users prove ownership without revealing the credential. |
| [Nullifier](https://github.com/Lightprotocol/program-examples/tree/main/zk/zk-nullifier) | Simple Program to Create Nullifiers.                                                                                            |


# Primitives for ZK on Solana
Source: https://www.zkcompression.com/zk/overview

Overview how to build a ZK program on Solana.

***

Building a ZK Solana program requires:

1. Nullifiers to prevent double spending
2. Proof verification
3. A Merkle tree to store state
4. An indexer to serve Merkle proofs
5. Encrypted state

## Nullifiers on Solana

A nullifier is a deterministically derived hash to ensure an action can only be performed once.
The nullifier cannot be linked to the action or user.
For example Zcash uses nullifiers to prevent double spending.

To implement nullifiers we need a data structure that ensures every nullifier is only created once and never deleted.
On Solana a straight forward way to implement nullifiers is to create a PDA account with the nullifier as seed.

* PDA accounts cannot be closed and permanently lock 890,880 lamports (per nullifier rent-exemption).
* Compressed PDAs are derived similar to Solana PDAs and cost 15,000 lamports to create (no rent-exemption).

| Storage        | Cost per nullifier |
| -------------- | ------------------ |
| PDA            | 890,880 lamports   |
| Compressed PDA | 15,000 lamports    |

<Info>
  [See full example with tests on on Github](https://github.com/Lightprotocol/program-examples/tree/main/zk/nullifier).
</Info>

```rust theme={null}
// add to your program
use anchor_lang::prelude::*;
use nullifier_creation::{create_nullifiers, NullifierInstructionData};

declare_id!("Bw8aty8LJY5Kg2b6djghjWGwt6cBc1tVQUoreUehvVq4");

#[program]
pub mod zk_nullifier {
    use super::*;

    pub fn create_nullifier<'info>(
        ctx: Context<'_, '_, '_, 'info, CreateNullifierAccounts<'info>>,
        data: NullifierInstructionData,
        nullifiers: Vec<[u8; 32]>,
    ) -> Result<()> {
        // Verify your proof here. Use nullifiers as public inputs
        // among your other public inputs.
        // Example:
        // let public_inputs = [...nullifiers, ...your_other_inputs];
        // Groth16Verifier::new(...).verify()?;

        create_nullifiers(
            &nullifiers,
            data,
            ctx.accounts.signer.as_ref(),
            ctx.remaining_accounts,
        )
    }
}

#[derive(Accounts)]
pub struct CreateNullifierAccounts<'info> {
    #[account(mut)]
    pub signer: Signer<'info>,
}
```

## Groth16 Proof Verification on Solana

Groth16's small proof size and fast verification (\~200k compute units) make it the practical choice for Solana.

<Info>
  Find more information on [docs.rs](https://docs.rs/groth16-solana) and [Github](https://github.com/Lightprotocol/groth16-solana).
</Info>

```rust theme={null}
let mut public_inputs_vec = Vec::new();
for input in PUBLIC_INPUTS.chunks(32) {
    public_inputs_vec.push(input);
}

let proof_a: G1 =
    <G1 as FromBytes>::read(&*[&change_endianness(&PROOF[0..64])[..], &[0u8][..]].concat())
        .unwrap();
let mut proof_a_neg = [0u8; 65];
<G1 as ToBytes>::write(&proof_a.neg(), &mut proof_a_neg[..]).unwrap();

let proof_a = change_endianness(&proof_a_neg[..64]).try_into().unwrap();
let proof_b = PROOF[64..192].try_into().unwrap();
let proof_c = PROOF[192..256].try_into().unwrap();

let mut verifier = Groth16Verifier::new(
    &proof_a,
    &proof_b,
    &proof_c,
    public_inputs_vec.as_slice(),
    &VERIFYING_KEY,
)
.unwrap();
verifier.verify().unwrap();
```

## Merklelized State with Indexer Support

ZK applications on Solana can use existing state Merkle trees to store state in rent-free accounts.

* This way you don't need to maintain your own Merkle tree and indexer.
* RPCs that support ZK Compression (Helius, Triton) index state changes.

| Creation     | Regular PDA Account  | Compressed PDA  |
| :----------- | :------------------- | :-------------- |
| 100-byte PDA | \~1,600,000 lamports | 15,000 lamports |

<Note>
  Your circuit must include compressed accounts. Find [guides to compressed accounts in the documentation](/compressed-pdas/overview) and the [full example with zk implementation here](https://github.com/Lightprotocol/program-examples/blob/99d260f9f356743b8fe3501c684f7926930d6079/zk-id/circuits/compressed_account.circom).
</Note>

## Get Started & Examples

|                                                                                          | Description                                                                                                                     |
| :--------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |
| [ZK-ID](https://github.com/Lightprotocol/program-examples/tree/main/zk/zk-id)            | Identity verification using Groth16 proofs. Issuers create credentials; users prove ownership without revealing the credential. |
| [Nullifier](https://github.com/Lightprotocol/program-examples/tree/main/zk/zk-nullifier) | Simple Program to Create Nullifiers.                                                                                            |