Load Token Balances to Light Associated Token Account

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
   • Token 2022 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

Find the source code here.

Agent skill

Install or view dedicated agent skills.

npx skills add Lightprotocol/skills

Install orchestrator agent skill or view skill.md:

npx skills add https://zkcompression.com

1. Unify Tokens to Light-ATA Balance

   Installation

   npm

   Install packages in your working directory:

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

   Install the CLI globally:

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

   yarn

   Install packages in your working directory:

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

   Install the CLI globally:

   yarn global add @lightprotocol/zk-compression-cli
   

   pnpm

   Install packages in your working directory:

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

   Install the CLI globally:

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

   SDK 2.0 (token-interface)

   Install packages in your working directory:

   # npm
   npm install @lightprotocol/stateless.js@^0.23.0 \
               @lightprotocol/token-interface@^0.1.2
   
   # yarn
   yarn add @lightprotocol/stateless.js@^0.23.0 \
            @lightprotocol/token-interface@^0.1.2
   
   # pnpm
   pnpm add @lightprotocol/stateless.js@^0.23.0 \
            @lightprotocol/token-interface@^0.1.2
   

   Install the CLI globally:

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

   Localnet

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

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

   Devnet

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

   .env

   API_KEY=<your-helius-api-key>
   

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

   Action

   import "dotenv/config";
   import { Keypair } from "@solana/web3.js";
   import { createRpc } from "@lightprotocol/stateless.js";
   import {
       createMintInterface,
       mintToCompressed,
       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 () {
       // 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 },
       ]);
   
       // Load compressed tokens to light associated token account (hot balance)
       const lightTokenAta = getAssociatedTokenAddressInterface(
           mint,
           payer.publicKey
       );
       const tx = await loadAta(rpc, lightTokenAta, payer, mint, payer);
   
       console.log("Tx:", tx);
   })();
   

   Instruction

   import "dotenv/config";
   import {
       Keypair,
       Transaction,
       sendAndConfirmTransaction,
   } from "@solana/web3.js";
   import { createRpc } from "@lightprotocol/stateless.js";
   import {
       createMintInterface,
       mintToCompressed,
       getAssociatedTokenAddressInterface,
   } from "@lightprotocol/compressed-token";
   import { createLoadAtaInstructions } from "@lightprotocol/compressed-token/unified";
   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 instructions = await createLoadAtaInstructions(
           rpc,
           lightTokenAta,
           payer.publicKey,
           mint,
           payer.publicKey
       );
   
       if (instructions.length === 0) return console.log("Nothing to load");
   
       for (const ixs of instructions) {
           const tx = new Transaction().add(...ixs);
           const sig = await sendAndConfirmTransaction(rpc, tx, [payer]);
           console.log("Tx:", sig);
       }
   })();
   

   SDK 2.0 (token-interface)

   import { Keypair, Transaction, sendAndConfirmTransaction } from "@solana/web3.js";
   import { createRpc } from "@lightprotocol/stateless.js";
   import { createLoadInstructions } from "@lightprotocol/token-interface";
   
   const rpc = createRpc();
   const payer = Keypair.fromSecretKey(/* ... */);
   
   const mint = /* existing mint public key */;
   const owner = payer.publicKey;
   
   const instructions = await createLoadInstructions({
     rpc,
     payer: payer.publicKey,
     owner,
     mint,
     authority: owner,
   });
   
   if (instructions.length > 0) {
     const tx = new Transaction().add(...instructions);
     const signature = await sendAndConfirmTransaction(rpc, tx, [payer]);
     console.log("Tx:", signature);
   }
   

Related Guides

Payments overview

Wrap and unwrap

---

Didn’t find what you were looking for?

Reach out! Telegram | email | Discord