JITO Merkle Distributor SDK

TypeScript SDK for interacting with the JITO Merkle Distributor program on Solana. It focuses on verifying Merkle proofs and performing claims against an existing, deployed program.

Official program ID: mERKcfxMC5SqJn4Ld4BUris3WKZZ1ojjWJ3A3J5CKxv (also exported as PROGRAM_ID).

Features

• ✅ Proof-safe double-hashing matching on-chain implementation
• ✅ Clean claim/claimLocked flows with type-safe args
• ✅ PDA utilities (distributor, claim status)
• ✅ Proof and timestamp validation helpers
• ✅ Optional versioning helpers for managing distributor versions

Installation

npm install @fractalshq/jito-distributor-sdk
# or
pnpm add @fractalshq/jito-distributor-sdk

Quick start: claim with an existing proof

import { AnchorProvider } from '@coral-xyz/anchor';
import { PublicKey } from '@solana/web3.js';
import { getAssociatedTokenAddress } from '@solana/spl-token';
import {
  MerkleDistributor,
  validateMerkleProof,
} from '@fractalshq/jito-distributor-sdk';

// Assumes you already have a Connection + wallet
const provider = new AnchorProvider(connection, wallet, { commitment: 'confirmed' });
const sdk = new MerkleDistributor(provider);

const distributor = new PublicKey('<distributor_pda>');
const claimant = wallet.publicKey;
const mint = new PublicKey('<mint>');

// Your Merkle proof for this claimant (Uint8Array[])
const proof: Uint8Array[] = [...];
if (!validateMerkleProof(proof)) throw new Error('Invalid Merkle proof');

const claimantTokenAccount = await getAssociatedTokenAddress(mint, claimant);

const sig = await sdk.claim({
  claimant,
  distributor,
  claimantTokenAccount,
  amountUnlocked: 300n,
  amountLocked: 0n,
  proof,
});

console.log('Claim signature:', sig);

Common tasks

import {
  MerkleDistributor,
  getDistributorPDA,
  getClaimStatusPDA,
} from '@fractalshq/jito-distributor-sdk';
import { PublicKey } from '@solana/web3.js';

const sdk = new MerkleDistributor(provider);

// 1) Locate a distributor if you know mint + version
const mint = new PublicKey('<mint>');
const version = 1n;
const [distributorPda] = getDistributorPDA(mint, version);

// 2) Check if a claimant has already claimed
const hasClaimed = await sdk.hasClaimed(wallet.publicKey, distributorPda);

// 3) Fetch distributor or claim status accounts
const distributorAccount = await sdk.getDistributor(distributorPda);
const [claimStatusPda] = getClaimStatusPDA(wallet.publicKey, distributorPda);
const claimStatus = await sdk.getClaimStatus(claimStatusPda);

// 4) Claim locked tokens after vesting
const ata = /* claimant ATA for distributor mint */ new PublicKey('<claimant_ata>');
const lockedSig = await sdk.claimLocked({
  claimant: wallet.publicKey,
  distributor: distributorPda,
  claimantTokenAccount: ata,
});

API surface

• class MerkleDistributor(provider, programId?)

  • claim(args: ClaimArgs): Promise<string>
  • claimLocked(args: ClaimLockedArgs): Promise<string>
  • getDistributor(pda: PublicKey)
  • getClaimStatus(pda: PublicKey)
  • getClaimStatusForClaimant(claimant, distributor)
  • hasClaimed(claimant, distributor)
  • clawback(distributor, claimant)
  • setAdmin(distributor, currentAdmin, newAdmin)
  • setClawbackReceiver(distributor, newReceiver, admin)

• Utilities

  • PROGRAM_ID, getDistributorPDA, getClaimStatusPDA
  • validateMerkleProof, validateTimestamps
  • hexToUint8Array, uint8ArrayToHex, bigintToBN
  • Optional versioning helpers under versioning-system

Notes

• This SDK does not deploy programs. It interacts with an already deployed JITO Merkle Distributor program.
• Example scripts in scripts/ and examples/ are provided to interact with existing deployments (create distributor accounts, fund, claim, query). They do not deploy the program.

Scripts (optional)

# Build / test
npm run build
npm run test

# Tooling against existing deployments
npm run claim
npm run query

# Admin-only (creating/funding distributors)
npm run admin:create-distributor
npm run admin:fund

License

MIT