Skip to content

Latest commit

 

History

History

README.md

@cascade-fyi/compression-kit

Solana Kit native implementation of Light Protocol compression. Works in any runtime (browsers, Cloudflare Workers, Deno, Node.js).

Status: Beta

Features

  • Edge/browser compatible - No Node.js dependencies, works everywhere
  • Native bigint - Uses native bigint instead of BN.js for better performance
  • Solana Kit types - Uses Address type from @solana/kit instead of PublicKey
  • Full Photon RPC - Complete implementation of Light Protocol's Photon indexer API
  • Lightweight - Minimal dependencies (~25KB gzip)

Install

npm install @cascade-fyi/compression-kit
pnpm add @cascade-fyi/compression-kit
yarn add @cascade-fyi/compression-kit

Quickstart

import { createPhotonRpc, deriveAddress, deriveAddressSeed } from '@cascade-fyi/compression-kit';
import { address } from '@solana/kit';

// 1. Create RPC client
const rpc = createPhotonRpc('https://mainnet.helius-rpc.com/?api-key=YOUR_KEY');

// 2. Query compressed accounts
const ownerAddress = address('YOUR_WALLET_ADDRESS');
const accounts = await rpc.getCompressedAccountsByOwner(ownerAddress);

// 3. Derive a compressed account address
const programId = address('YOUR_PROGRAM_ID');
const seed = deriveAddressSeed([new TextEncoder().encode('my-seed')], programId);
const compressedAddress = deriveAddress(seed);

Common Flows

Query Compressed Accounts

import { createPhotonRpc } from '@cascade-fyi/compression-kit';

const rpc = createPhotonRpc('https://mainnet.helius-rpc.com/?api-key=YOUR_KEY');

// Get all compressed accounts for an owner
const accounts = await rpc.getCompressedAccountsByOwner(ownerAddress);

// With server-side memcmp filtering (up to 5 filters, AND logic)
const filtered = await rpc.getCompressedAccountsByOwner(ownerAddress, {
  filters: [
    { offset: 8, bytes: schemaAddress },     // base58 string
    { offset: 40, bytes: agentMintBytes },    // or Uint8Array
  ],
  limit: 50,
});

// Get compressed token accounts
const tokenAccounts = await rpc.getCompressedTokenAccountsByOwner(ownerAddress, {
  mint: mintAddress,
});

// Get a specific compressed account by hash
const account = await rpc.getCompressedAccount(accountHash);

Derive Addresses (V1 & V2)

import {
  deriveAddressSeed,
  deriveAddress,
  deriveAddressSeedV2,
  deriveAddressV2,
  getDefaultAddressTreeInfo,
} from '@cascade-fyi/compression-kit';

// V1 Address derivation (mainnet)
const seedV1 = deriveAddressSeed([Buffer.from('my-seed')], programId);
const addressV1 = deriveAddress(seedV1);

// V2 Address derivation (devnet, more efficient)
const seedV2 = deriveAddressSeedV2([Buffer.from('my-seed')]);
const treeInfo = getDefaultAddressTreeInfo();
const addressV2 = deriveAddressV2(seedV2, treeInfo.tree, programId);

Get Validity Proofs

import { createPhotonRpc } from '@cascade-fyi/compression-kit';

const rpc = createPhotonRpc('https://mainnet.helius-rpc.com/?api-key=YOUR_KEY');

// Get proof for existing accounts (update/close operations)
const proof = await rpc.getValidityProof({
  hashes: [{ hash: accountHash, tree: treeAddress, queue: queueAddress }],
});

// Get proof for new addresses (create operations)
const newAddressProof = await rpc.getValidityProof({
  newAddresses: [{ address: newAddress, tree: addressTree, queue: addressQueue }],
});

Build Instruction Accounts

import {
  PackedAccounts,
  createSystemAccountConfig,
  getLightSystemAccountMetas,
} from '@cascade-fyi/compression-kit';

// Create packed accounts helper
const packedAccounts = new PackedAccounts();

// Add Light system accounts
const systemConfig = createSystemAccountConfig(programId);
packedAccounts.addSystemAccounts(getLightSystemAccountMetas(systemConfig));

// Add tree accounts and get indices
const treeIndex = packedAccounts.insertOrGet(treeAddress);

// Convert to account metas for instruction
const { remainingAccounts } = packedAccounts.toAccountMetas();

BN254 Field Operations

import {
  createBN254,
  bn254FromBytes,
  bn254ToBytes,
  bn254Add,
  isSmallerThanFieldSize,
} from '@cascade-fyi/compression-kit';

// Create field element from bigint
const element = createBN254(123456789n);

// Convert from/to bytes
const bytes = bn254ToBytes(element);
const restored = bn254FromBytes(bytes);

// Field arithmetic
const sum = bn254Add(element1, element2);

// Validate field size
if (isSmallerThanFieldSize(someBytes)) {
  // Safe to use as BN254
}

Web Crypto Utilities

import { importEd25519PublicKey } from '@cascade-fyi/compression-kit';
import { verifySignature, signatureBytes } from '@solana/kit';

// Import Ed25519 public key for signature verification
const pubkeyBytes = new Uint8Array(32); // your public key
const cryptoKey = await importEd25519PublicKey(pubkeyBytes);

// Use with Web Crypto API
const isValid = await verifySignature(cryptoKey, signatureBytes(sig), message);

Configuration

RPC Endpoints

Network Endpoint
Mainnet https://mainnet.helius-rpc.com/?api-key=YOUR_KEY
Devnet https://devnet.helius-rpc.com/?api-key=YOUR_KEY
Localnet http://localhost:8784

Default Tree Addresses

The package exports default tree addresses for mainnet and devnet:

import {
  MERKLE_TREE_PUBKEY,      // V1 State tree (mainnet)
  NULLIFIER_QUEUE_PUBKEY,  // V1 Nullifier queue (mainnet)
  ADDRESS_TREE,            // V1 Address tree
  BATCH_MERKLE_TREE_1,     // V2 Batch tree (devnet)
  defaultTestStateTreeAccounts, // Local testing
} from '@cascade-fyi/compression-kit';

API Reference

RPC Methods

Method Description
getCompressedAccount(hash) Get compressed account by hash
getCompressedAccountsByOwner(owner) Get all compressed accounts for owner
getCompressedTokenAccountsByOwner(owner, config?) Get token accounts for owner
getCompressedTokenBalancesByOwner(owner) Get token balances for owner
getValidityProof(params) Get validity proof for accounts/addresses
getMultipleCompressedAccounts(hashes) Batch fetch multiple accounts
getCompressionSignaturesForOwner(owner) Get compression transaction signatures
getLatestCompressionSignatures() Get recent compression signatures
getIndexerHealth() Check indexer health status
getIndexerSlot() Get current indexer slot

Crypto Utilities

Function Description
importEd25519PublicKey(bytes) Import Ed25519 public key for Web Crypto verification

Types

Type Description
CompressedAccount Compressed account data structure
TreeInfo Merkle tree metadata
ValidityProof ZK validity proof
BN254 BN254 field element (branded bigint)
PackedAccounts Helper for building instruction accounts
MemcmpFilter Memory comparison filter for RPC queries

Constants

Constant Description
LIGHT_SYSTEM_PROGRAM Light system program ID
ACCOUNT_COMPRESSION_PROGRAM Account compression program ID
COMPRESSED_TOKEN_PROGRAM Compressed token program ID
FIELD_SIZE BN254 field size

Requirements

  • Node.js >= 20.18.0
  • TypeScript >= 5.0 (for type definitions)

Changelog

See CHANGELOG.md for version history.

Related Packages

License

Apache-2.0