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

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:

• basic-usage.ts - Import and inspect IDLs
• error-lookup.ts - Resolve error codes to messages
• debridge-parser.ts - Parse transactions with DeBridge

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)

2. For local IDLs, copy the file first:

cp /path/to/source/idl.json idl/my-protocol.json

3. 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]