@lightprotocol/stateless.js Overview

JavaScript API for Light Protocol & ZK Compression

Introduction

@lightprotocol/stateless.js is the core JavaScript SDK for building applications on Light Protocol. It provides a comprehensive API for working with compressed accounts, managing state trees, and interacting with the Light system program.

Installation

npm

npm install @lightprotocol/stateless.js @solana/web3.js

yarn

yarn add @lightprotocol/stateless.js @solana/web3.js

pnpm

pnpm add @lightprotocol/stateless.js @solana/web3.js

Package Information

Version

0.23.0-beta.8

License

Apache-2.0

Quick Start

Creating an RPC Connection

The SDK provides a custom RPC client that extends Solana’s Connection with compression-specific methods:

import { createRpc } from '@lightprotocol/stateless.js';

// Connect to local test validator
const rpc = createRpc();

// Or connect to a custom endpoint
const rpc = createRpc(
  'https://devnet.helius-rpc.com',
  'https://devnet.helius-rpc.com'
);

Compressing Lamports

Compress SOL into a compressed account to save on rent:

import { compress } from '@lightprotocol/stateless.js';
import { Keypair } from '@solana/web3.js';

const payer = Keypair.generate();
const recipient = Keypair.generate().publicKey;

// Compress 0.01 SOL (10 million lamports)
const signature = await compress(
  rpc,
  payer,
  10_000_000,
  recipient
);

console.log('Compressed lamports:', signature);

Transferring Compressed Lamports

Transfer compressed SOL between accounts:

import { transfer } from '@lightprotocol/stateless.js';

const owner = Keypair.generate();
const recipient = Keypair.generate().publicKey;

// Transfer 0.001 SOL (1 million lamports)
const signature = await transfer(
  rpc,
  payer,
  1_000_000,
  owner,
  recipient
);

console.log('Transferred compressed lamports:', signature);

Decompressing Back to SOL

Decompress back to regular SOL:

import { decompress } from '@lightprotocol/stateless.js';

const owner = Keypair.generate();
const recipient = Keypair.generate().publicKey;

// Decompress 0.001 SOL
const signature = await decompress(
  rpc,
  payer,
  1_000_000,
  recipient
);

console.log('Decompressed to regular SOL:', signature);

Core Concepts

State Trees

Compressed accounts are stored in Merkle trees. The SDK automatically manages tree selection:

import { selectStateTreeInfo } from '@lightprotocol/stateless.js';

// Get available state trees
const stateTreeInfos = await rpc.getStateTreeInfos();

// Select an appropriate tree
const stateTree = selectStateTreeInfo(stateTreeInfos);

// Use the tree for operations
await compress(
  rpc,
  payer,
  10_000_000,
  recipient,
  stateTree  // Optional: specify output tree
);

Validity Proofs

When spending compressed accounts, you need validity proofs:

import { bn } from '@lightprotocol/stateless.js';

// Get compressed accounts
const accounts = await rpc.getCompressedAccountsByOwner(
  owner.publicKey
);

// Request proof for the accounts
const proof = await rpc.getValidityProof(
  accounts.items.map(acc => bn(acc.hash))
);

// Use proof in transaction
const ix = await LightSystemProgram.transfer({
  payer: payer.publicKey,
  inputCompressedAccounts: accounts.items,
  toAddress: recipient,
  lamports: 1_000_000,
  recentInputStateRootIndices: proof.rootIndices,
  recentValidityProof: proof.compressedProof,
});

Key Features

Account Compression

• Rent-free accounts: Store account state in Merkle trees instead of on-chain accounts
• Zero-knowledge proofs: Prove account validity without revealing full state
• Batched operations: Multiple account operations in a single transaction

RPC Methods

The SDK provides comprehensive RPC methods for querying compressed accounts:

• getCompressedAccount() - Fetch a single compressed account
• getCompressedAccountsByOwner() - Get all accounts owned by a public key
• getCompressedBalance() - Query compressed SOL balance
• getValidityProof() - Request ZK proofs for transactions

See RPC Methods for the complete reference.

Utility Functions

• BN254 field element helpers for working with account hashes
• Transaction building utilities
• State tree selection algorithms
• Proof formatting and validation

TypeScript Support

The SDK is written in TypeScript with full type definitions:

import type {
  CompressedAccountWithMerkleContext,
  ValidityProofWithContext,
  TreeInfo,
  Rpc,
} from '@lightprotocol/stateless.js';

// All types are exported for use in your application
const account: CompressedAccountWithMerkleContext = {
  hash: bn(accountHash),
  treeInfo: stateTree,
  leafIndex: 42,
  owner: owner.publicKey,
  lamports: bn(1_000_000),
  address: null,
  data: null,
};

Browser Support

The package supports both Node.js and browser environments:

// Node.js
import { createRpc } from '@lightprotocol/stateless.js';

// Browser
import { createRpc } from '@lightprotocol/stateless.js/browser';

Next Steps

Compressed Accounts

Learn how to work with compressed accounts

RPC Methods

Explore all available RPC methods

Compressed Tokens

Build with compressed SPL tokens

API Reference

Full TypeScript API documentation

Resources

• GitHub Repository
• NPM Package
• TypeScript Docs