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
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
Total: 41 protocols, 1,914 error definitions
Installation
npm install solana-idlsFor transaction parser integration (recommended):
npm install solana-idls @coral-xyz/anchorNote:
@coral-xyz/anchoris 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 IDLserror-lookup.ts- Resolve error codes to messagesdebridge-parser.ts- Parse transactions with DeBridge
cd examples && pnpm install
pnpm tsx error-lookup.tsIDL 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
Idlfrom@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/anchorto 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:
- Program-specific errors (Jupiter, Orca, SPL Token, etc.)
- 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()); // 57registry.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
idlFileNamefrom 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
- 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 fromidl/directory (no fetching)"manual"- Manually defined errors in TypeScript code (no IDL file)
- For local IDLs, copy the file first:
cp /path/to/source/idl.json idl/my-protocol.json- Run generation:
pnpm generate # Fetches/validates IDLs and auto-generates registration code
pnpm build # Build packageScripts
pnpm generate # Fetch IDLs and generate code
pnpm generate --force # Re-fetch all IDLs
pnpm build # Build package
pnpm type-check # Type checkReleasing
# 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-notesContributing
- Fork the repo: https://github.com/tenequm/solana-idls
- Add protocol to
src/protocols.config.ts - Run
pnpm generate && pnpm build - Create pull request
Ensure IDLs are from official sources (GitHub or on-chain).
License
MIT © [Obsidian Debug Team]