JSPM

solana-idls

1.2.1
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 8
  • Score
    100M100P100Q75700F
  • License MIT

Comprehensive Solana IDL database with errors, instructions, and account metadata from 41+ protocols

Package Exports

  • solana-idls
  • solana-idls/package.json

Readme

solana-idls

📺 See it in action: Obsidian Debug uses this library to resolve Solana transaction errors in real-time.

Type-safe Solana IDL database with error, instruction, and account resolution

npm version License: MIT

Comprehensive Solana IDL database providing error codes, instruction names, and account metadata from 41+ protocols. All data extracted directly from official IDLs for 100% accuracy.

Features

  • 1,914 errors from 41 Solana protocols
  • Error resolution - Map error codes to names and descriptions
  • Instruction resolution - Discriminator → instruction name + account metadata
  • Program identification - Program ID → protocol name
  • Hierarchical fallback - Program-specific errors + Anchor framework
  • Raw IDL objects - Compatible with transaction parsers
  • Type-safe - Full TypeScript support
  • Zero config - Works out of the box

Protocol Coverage

Ecosystem Protocol / App Program ID Version Errors
Pump.fun Bonding Curve 6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P 0.1.0 43
Pump.fun PumpSwap AMM pAMMBay6oceH9fJKBRHGP5D4bD4sWpmSwMn52FMfXEA 0.1.0 41
Jupiter Swap Aggregator V6 JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4 0.1.0 18
Jupiter Swap Aggregator V4 JUP4Fb2cqiRUcaTHdrPC8h2gNsA2ETXiPDD33WcGuJB 0.1.0 10
Jupiter DCA DCA265Vj8a9CEuX1eb1LWRnDT7uK6q1xMipnNyatn23M 0.1.0 47
Jupiter Limit Order jupoNjAxXgZ4rjzxzPMP4oxduvQsQtZzyknqvzYNrNu 0.1.0 17
OKX DEX Router V2 6m2CDdhRgxpH4WjvdzxAYbGxwdGUz5MziiL5jek2kBma 0.1.0 75
Orca Whirlpool (CLMM) whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc 0.3.6 65
Meteora DLMM LBUZKhRxPF3XUpBCjp4YzTKgLccjZhTSDM9YuVaPwxo 0.10.0 86
Meteora AMM Pools Eo7WjKq67rjJQSZxS6z3YkapzY3eMj6Xy8X5EQVn5UaB 0.5.3 54
Meteora CP AMM (DAMM V2) cpamdpZCGKUy5JxQXB4dcpGPiikHawvSWAd6mEn1sGG 0.1.5 53
Meteora Dynamic Bonding dbcij3LWUppWqq96dh6gJWwBifmcGfLSB5D4DuSMaqN 0.1.6 49
Raydium AMM V4 675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8 0.1.0 57
Raydium CLMM V3 CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK 0.1.0 45
Raydium CP Swap CPMMoo8L3F4NbTegBCKVNunggL7H1ZpdTHKxQB5qKP1C 0.1.0 11
Raydium Launchpad LanMV9sAd7wArD4vJFi2qDdfnVhFxYSUg6eADduJ3uj 0.2.0 21
OpenBook V2 CLOB opnb2LAfJYbRMAHHvqjCwQxanZn7ReEHp1k81EohpZb 0.1.0 43
Serum DEX V3 9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin 0.0.0 0
Phoenix On-chain CLOB PhoeNiXZ8ByJGLkxNfZRnkUfjvmuYqLR89jjFHGqdXY 0.2.4 26
BonkSwap AMM BSwp6bEBihVLdqJRKGgzjcGLHkcTuzmSo1TQkHepzH8p 0.1.1 16
Aldrin V2 CLOB CURVGoZn8zycx6FXwwevgBTB2gVvdbGTEpvMJDbgs2t4 0.0.0 0
Moonshot Token Launch MoonCVVNZFSYkqNXP6bxHLPL6QQJiMagDL3qcqUQTrG 0.1.0 31
Boop Meme Platform boop8hVGQGqehUK2iVEMEnMrL5RbjywRzHKBmBE7ry4 0.3.0 37
Heaven DEX HEAVENoP2qxoeuF8Dj2oT1GHEnu49U5mJYkdeC8BAX2o 0.2.0 54
Drift V2 Perpetual dRiftyHA39MWEi3m9aunc5MzRF1JYuBsbn6VPcn33UH 2.143.0 344
Obric V2 obriQD1zbpyLz95G5n7nJe6a4DPjpFwa5XYPoNm113y 0.1.0 22
TON Whales Holders 6bES2dKy1ee13HQ4uW4ycw4Kw4od9ziZeWMyAxVySYEd 1.0.0 27
Magic Eden Marketplace V2 M2mx93ekt1fmXSVkTrUL9xVFHkmME8HTUi5Cyc5aF7K 0.1.0 40
Tensor NFT AMM TSWAPaqyCSx2KABk68Shruf4rp7CxcNi8hAsbdwmHbN 3.1.0 39
Metaplex Token Metadata metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s 1.14.0 201
Metaplex Candy Machine cndy3Z4yapfJBmL3ShUp5exZKqR3z33thTzeNMm2gRZ 4.6.0 52
Metaplex Fixed Price Sale SaLeTjyUa5wXHnGuewUSyJ5JWZaHwz3TxqUntCE9czo 0.4.0 46
Metaplex Auction House hausS13jsjafwWwGqZTUQRmWyvyxn9EQpqMwV1PBBmk 1.0.0 44
Metaplex Bubblegum (cNFT) BGUMAp9Gq7iTEuizy4pqaxsTyUCBK68MDfK752saRPUY 0.12.0 40
Metaplex NFT Packs packFeFNZzMfD9aVWL7QbGz1WcU7R9zpf6pvNsw2BLu 0.1.0 40
Metaplex Hydra hyDQ4Nz1eYyegS6JfenyKwKzYxRsCWCriYSAjtzP4Vg 0.4.1 25
Metaplex Token Entangler qntmGodpGkrM42mN68VCZHXnKqDCT8rdY23wFcXCLPd 0.2.0 16
Metaplex Auctioneer neer8g6yJq2mQM6KbnViEDAD4gr3gRZyMMf4F2p3MEh 0.2.1 10
Solana SPL Token TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA 1.0.0 20
Solana Token-2022 TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb 1.0.0 20
Solana SPL Token Swap SwaPpA9LAaLfeLi3a68M4DjnLqgtticKg6CnyNwgAC8 3.0.0 29
Anchor Framework * (any Anchor program) 0.30.1 59

Total: 41 protocols, 1,914 error definitions

Installation

npm install solana-idls

For transaction parser integration (recommended):

npm install solana-idls @coral-xyz/anchor

Note: @coral-xyz/anchor is an optional peer dependency that provides full TypeScript type safety when using IDLs with parser libraries like @debridge-finance/solana-transaction-parser. While technically optional, it's strongly recommended for TypeScript projects and required for parser integration.

Quick Start

import { JUPITER_IDL, JUPITER_PROGRAM_ID } from 'solana-idls';

// Access IDL directly
console.log(JUPITER_IDL.instructions[0].name); // "route"
console.log(JUPITER_PROGRAM_ID); // "JUP6Lk..."

// Look up error by code
const error = JUPITER_IDL.errors?.find(e => e.code === 6001);
console.log(error?.name); // "SlippageToleranceExceeded"

Or use the registry for error resolution across all protocols:

import { registry } from 'solana-idls';

const error = registry.resolve(JUPITER_PROGRAM_ID, 6001);
console.log(`${error?.name}: ${error?.description}`);
// "SlippageToleranceExceeded: Slippage tolerance exceeded"

Examples

See examples/ for complete working examples:

cd examples && pnpm install
pnpm tsx error-lookup.ts

IDL Objects for Transaction Parsers

This library exports all IDL objects directly with full TypeScript type safety, making it compatible with transaction parsers like @debridge-finance/solana-transaction-parser:

import { JUPITER_IDL, JUPITER_PROGRAM_ID, ORCA_WHIRLPOOLS_IDL, ORCA_WHIRLPOOLS_PROGRAM_ID } from 'solana-idls';
import { SolanaParser, convertLegacyIdlToV30 } from '@debridge-finance/solana-transaction-parser';

// ✅ Fully type-safe - no casting needed!
const parser = new SolanaParser([
  {
    idl: convertLegacyIdlToV30(JUPITER_IDL, JUPITER_PROGRAM_ID),
    programId: JUPITER_PROGRAM_ID
  },
  {
    idl: convertLegacyIdlToV30(ORCA_WHIRLPOOLS_IDL, ORCA_WHIRLPOOLS_PROGRAM_ID),
    programId: ORCA_WHIRLPOOLS_PROGRAM_ID
  }
]);

// Parse transaction with full type inference
const parsed = await parser.parseTransaction(connection, 'YOUR_TX_SIGNATURE');

// Or use the IDL_MAP for dynamic access
const jupiterIdl = IDL_MAP['jupiter'];
const orcaIdl = IDL_MAP['orca-whirlpools'];

Type Safety:

  • All IDL exports are typed as Idl from @coral-xyz/anchor
  • Zero type casting required - works seamlessly with parser libraries
  • Full IDE IntelliSense support for instruction names, accounts, and arguments
  • Install @coral-xyz/anchor to enable type checking

Available exports:

  • Individual IDLs: JUPITER_IDL, ORCA_WHIRLPOOLS_IDL, METEORA_DLMM_IDL, etc.
  • Program IDs: JUPITER_PROGRAM_ID, ORCA_WHIRLPOOLS_PROGRAM_ID, etc.
  • Complete map: IDL_MAP - Object mapping config keys to IDL objects

API

registry.resolve(programId: string, errorCode: number)

Resolve an error by program ID and error code. Returns enriched error with source metadata.

const error = registry.resolve(
  'whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc',
  6000
);
// {
//   code: 6000,
//   name: "InvalidEnum",
//   description: "Enum value could not be converted",
//   source: { type: "program-specific", programId: "whir...", programName: "Orca Whirlpools" }
// }

Hierarchical resolution:

  1. Program-specific errors (Jupiter, Orca, SPL Token, etc.)
  2. Anchor framework errors (fallback for any Anchor program)

registry.getByProgramId(programId: string)

Get protocol instance for a program ID.

const protocol = registry.getByProgramId(
  '675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8'
);

console.log(protocol.name); // "Raydium AMM V4"
console.log(protocol.getErrorCount()); // 57

registry.search(query: string)

Search errors across all protocols.

const results = registry.search('slippage');
results.forEach(({ protocol, error }) => {
  console.log(`[${protocol.name}] ${error.name}`);
});

IDL_MAP

Access all IDLs by their configuration key (from protocols.config.ts).

import { IDL_MAP } from 'solana-idls';

// Access IDLs dynamically
const jupiterIdl = IDL_MAP['jupiter'];
const orcaIdl = IDL_MAP['orca-whirlpools'];
const meteoraIdl = IDL_MAP['meteora-dlmm'];

// All 41 protocols available
Object.keys(IDL_MAP); // ['jupiter', 'orca-whirlpools', 'meteora-dlmm', ...]

Individual IDL Exports

Import specific IDLs and their program IDs directly.

import {
  JUPITER_IDL,
  JUPITER_PROGRAM_ID,
  ORCA_WHIRLPOOLS_IDL,
  ORCA_WHIRLPOOLS_PROGRAM_ID,
  METEORA_DLMM_IDL,
  METEORA_DLMM_PROGRAM_ID
} from 'solana-idls';

// Type-safe IDL access
const jupiterIdl: Idl = JUPITER_IDL;
const programId: string = JUPITER_PROGRAM_ID;

Naming convention:

  • IDL constants: {PROTOCOL_NAME}_IDL (e.g., JUPITER_IDL, ORCA_WHIRLPOOLS_IDL)
  • Program IDs: {PROTOCOL_NAME}_PROGRAM_ID (e.g., JUPITER_PROGRAM_ID)
  • All uppercase with underscores, matches the idlFileName from config

Usage Example

import { Connection } from '@solana/web3.js';
import { registry } from 'solana-idls';

async function debugTransaction(signature: string) {
  const connection = new Connection('https://api.mainnet-beta.solana.com');
  const tx = await connection.getTransaction(signature, {
    maxSupportedTransactionVersion: 0
  });

  if (tx?.meta?.err && 'InstructionError' in tx.meta.err) {
    const [index, error] = tx.meta.err.InstructionError;

    if ('Custom' in error) {
      const errorCode = error.Custom;
      const programId = tx.transaction.message.staticAccountKeys[
        tx.transaction.message.compiledInstructions[index].programIdIndex
      ].toBase58();

      const errorInfo = registry.resolve(programId, errorCode);

      if (errorInfo) {
        console.log(`Error in instruction ${index}:`);
        console.log(`  Program: ${errorInfo.source.programName}`);
        console.log(`  Error: ${errorInfo.name} (${errorInfo.code})`);
        console.log(`  Description: ${errorInfo.description}`);
      }
    }
  }
}

Types

type ErrorInfo = {
  readonly code: number;
  readonly name: string;
  readonly description: string;
  readonly source: ErrorSource;
};

type ErrorSource =
  | { type: "program-specific"; programId: string; programName: string }
  | { type: "anchor-framework"; programId: string }
  | { type: "token-program"; programId: string; programName: string };

Development

Adding New Protocols

  1. Edit src/protocols.config.ts:
export const PROTOCOLS = [
  // ... existing protocols
  {
    idlFileName: "my-protocol",
    programId: "YourProgramID...",
    fetchSource: "github", // "github", "anchor", or "local"
    githubUrl: "https://raw.githubusercontent.com/.../idl.json", // Required for "github"
    displayName: "My Protocol",
    version: "1.0.0",
  },
] as const;

Fetch Source Options:

  • "github" - Fetch from GitHub URL during generation
  • "anchor" - Fetch from on-chain using Anchor CLI
  • "local" - Use pre-copied IDL from idl/ directory (no fetching)
  • "manual" - Manually defined errors in TypeScript code (no IDL file)
  1. For local IDLs, copy the file first:
cp /path/to/source/idl.json idl/my-protocol.json
  1. Run generation:
pnpm generate  # Fetches/validates IDLs and auto-generates registration code
pnpm build     # Build package

Scripts

pnpm generate          # Fetch IDLs and generate code
pnpm generate --force  # Re-fetch all IDLs
pnpm build            # Build package
pnpm type-check       # Type check

Releasing

# 1. Create changeset (or manually create .changeset/*.md file)
pnpm changeset

# 2. Update version and generate CHANGELOG
pnpm changeset version

# 3. Build and publish to npm (creates git tags)
pnpm build

# 4. Commit version changes
git add -A && git commit -m "chore: version packages"

# 5. Publish changeset
pnpm changeset publish

# 6. Push version commit
git push --follow-tags

# 7. Create GitHub release with auto-generated notes
gh release create "v$(node -p "require('./package.json').version")" --generate-notes

Contributing

  1. Fork the repo: https://github.com/tenequm/solana-idls
  2. Add protocol to src/protocols.config.ts
  3. Run pnpm generate && pnpm build
  4. Create pull request

Ensure IDLs are from official sources (GitHub or on-chain).

License

MIT © [Obsidian Debug Team]