Anchor IDL Filter

CLI tool to filter and transform Anchor IDL (v0.30.0 or newer) files by instructions, accounts, types, events, and errors. Perfect for creating focused, lightweight IDL files for specific use cases or client-side applications.

Features

🎯 Selective Filtering: Include or exclude specific instructions, accounts, types, events, and errors
📝 Multiple Output Formats: Export filtered IDL as JSON or TypeScript types
⚙️ Flexible Configuration: Use CLI flags or configuration files (JS, JSON, MJS, CJS)
🔄 CamelCase Transformation: Convert snake_case properties to camelCase for JavaScript/TypeScript
🏷️ Custom Overrides: Override program name, address, and TypeScript type names
🔍 Dry Run Mode: Preview filtering results before applying changes
📦 Zero Dependencies: Lightweight with minimal external dependencies
🏗️ Anchor IDL Support: Compatible with Anchor IDL format v0.30.0 or newer

Use Cases

Frontend Applications: Generate lightweight IDL types for client-side applications
SDK Development: Create focused IDL files for specific SDK modules
Documentation: Generate clean IDL files for documentation purposes
Testing: Create minimal IDL files for unit testing
Integration: Filter IDL files for specific integration scenarios

Installation

Global Installation

npm install -g anchor-idl-filter
# or
pnpm add -g anchor-idl-filter
# or
yarn global add anchor-idl-filter

Local Installation

npm install anchor-idl-filter
# or
pnpm add anchor-idl-filter
# or
yarn add anchor-idl-filter

Quick Start

Basic Usage

# Print filtered IDL to stdout
idl-filter idl.json

# Filter with specific instructions
idl-filter --include-instructions "buy,sell" idl.json

# Export to files
idl-filter --export-json output.json --export-ts output.ts idl.json

# Use configuration file
idl-filter -c my-config.mjs idl.json

# Dry run to preview changes
idl-filter --dry-run -c config.mjs idl.json

Configuration

Configuration File

Create a configuration file to define complex filtering rules:

⚠️ Important: All names in configuration files and CLI arguments must exactly match the names as they appear in the source IDL JSON file. Names are case-sensitive and must match precisely (e.g., "BondingCurve" for accounts, types, and events, "create_token" for instructions, etc.).

idl.config.mjs (ES Module)

export default {
  include: {
    instructions: ["buy", "sell", "create"],
    accounts: ["BondingCurve", "Global"],
    types: ["BondingCurve", "CompleteEvent", "CreateEvent", "Global"],
    events: ["Trade", "Complete"],
    errors: ["6001", "6002"]
  },
  exclude: {
    instructions: ["deprecated_instruction", "migrate_internal"],
    types: ["InternalType"],
    errors: ["6000"]
  },
  override: {
    name: "myprogram",
    address: "MyProgram11111111111111111111111111111111",
    tsType: "MyProgram"
  },
  output: {
    json: "output/myprogram.json",
    ts: "output/myprogram.ts"
  }
};

idl.config.json (JSON)

{
  "include": {
    "instructions": ["buy", "sell"],
    "accounts": ["Pool"]
  },
  "output": {
    "json": "output/filtered.json"
  }
}

Configuration File Discovery

The tool automatically looks for configuration files in this order:

idl.config.mjs
idl.config.cjs
idl.config.json
idl.config.js

CLI Options

Basic Options

Option	Description
`<idlPath>`	Path to Anchor IDL JSON file (required)
`-c, --config <path>`	Path to configuration file
`-d, --dry-run`	Preview changes without applying them

Filtering Options

Option	Description
`--include-instructions <names>`	Include specific instructions (comma-separated)
`--exclude-instructions <names>`	Exclude specific instructions (comma-separated)
`--include-accounts <names>`	Include specific accounts (comma-separated)
`--exclude-accounts <names>`	Exclude specific accounts (comma-separated)
`--include-types <names>`	Include specific types (comma-separated)
`--exclude-types <names>`	Exclude specific types (comma-separated)
`--include-events <names>`	Include specific events (comma-separated)
`--exclude-events <names>`	Exclude specific events (comma-separated)
`--include-errors <codes>`	Include specific error codes (comma-separated)
`--exclude-errors <codes>`	Exclude specific error codes (comma-separated)

Override Options

Option	Description
`--name <name>`	Override program name
`--address <address>`	Override program address
`--ts-type <type>`	Override TypeScript type name

Output Options

Option	Description
`--export-json <path>`	Export filtered IDL as JSON
`--export-ts <path>`	Export filtered IDL as TypeScript types

Examples

Example 1: Trading Program Filter

Filter a DEX program to include only trading-related functionality:

idl-filter \
  --include-instructions "buy,sell,swap" \
  --include-accounts "Pool,UserAccount" \
  --include-types "TradeEvent,SwapParams" \
  --export-ts src/types/trading.ts \
  dex-program.json

Example 2: Configuration-Based Filtering

token_swap.config.mjs

export default {
  include: {
    instructions: ["create_market", "set_market_prices", "swap"],
    accounts: ["Market", "QuoteTokenBadge"],
    types: [
      "Market",
      "MarketFees",
      "MarketCreationEvent",
      "QuoteTokenBadge",
      "QuoteTokenBadgeStatus",
      "SwapAmountType",
      "SwapEvent",
      "SwapType",
    ],
    events: ["MarketCreationEvent", "SwapEvent"],
  },
  override: {
    name: "token_swap",
    tsType: "TokenSwap",
  },
  output: {
    ts: "output/token_swap.ts",
    json: "output/token_swap.json",
  },
};

idl-filter -c token_swap.config.mjs target/idl/token_swap.json

Example 3: Client-Side Types Generation

Generate lightweight TypeScript types for frontend applications:

idl-filter \
  --include-instructions "initialize,deposit,withdraw" \
  --exclude-errors "6000,6001,6002" \
  --ts-type "ClientProgram" \
  --export-ts src/types/program.ts \
  program.json

Output Formats

JSON Output

The filtered IDL maintains the standard Anchor IDL structure:

{
  "address": "ProgramAddress11111111111111111111111111111111",
  "metadata": {
    "name": "my_program",
    "version": "0.1.0",
    "spec": "0.1.0",
    "description": "Created with Anchor"
  },
  "instructions": [...],
  "accounts": [...],
  "types": [...],
  "events": [...],
  "errors": [...]
}

TypeScript Output

Generated TypeScript files include properly typed IDL structures:

// Auto-generated by idl-filter
export type MyProgram = {
  "address": "ProgramAddress11111111111111111111111111111111",
  "metadata": {
    "name": "myProgram",
    "version": "0.1.0",
    "spec": "0.1.0",
    "description": "Created with Anchor"
  },
  "instructions": [
    {
      "name": "swap",
      "discriminator": [102, 6, 61, 18, 1, 218, 235, 234],
      "accounts": [...],
      "args": [...]
    }
  ],
  // ... rest of IDL structure
};

Advanced Usage

Dry Run Mode

Preview filtering results before applying changes:

idl-filter --dry-run -c config.mjs program.json

Output:

--- DRY RUN REPORT ---
Address: MyProgram11111111111111111111111111111111
Metadata: { name: 'my_program', version: '0.1.0', spec: '0.1.0', description: 'Created with Anchor' }
TS Type: MyProgram
Instructions: [ 'buy', 'sell' ]
Accounts: [ 'BondingCurve', 'Global' ]
Types: [ 'BondingCurve', 'CompleteEvent' ]
Events: [ 'Trade' ]
Errors: [ 6001, 6002 ]
-----------------------

CamelCase Transformation

The tool automatically converts snake_case (common in Rust-generated schemas) properties to camelCase in TypeScript output, making them suitable for JavaScript/TypeScript environments:

virtual_token_reserves → virtualTokenReserves
bonding_curve → bondingCurve
fee_basis_points → feeBasisPoints

Configuration Schema

IDLFilterConfig Type

type IDLFilterConfig = {
  include?: {
    instructions?: string[];
    accounts?: string[];
    types?: string[];
    events?: string[];
    errors?: string[];
  };
  exclude?: {
    instructions?: string[];
    accounts?: string[];
    types?: string[];
    events?: string[];
    errors?: string[];
  };
  override?: {
    name?: string;
    address?: string;
    tsType?: string;
  };
  output?: {
    json?: string;
    ts?: string;
  };
};

Development

Building from Source

git clone https://github.com/wobondar/idl-filter.git
cd idl-filter
pnpm install
pnpm build

Bundled Dependencies

Anchor IDL Filter bundles the following open-source dependency to reduce runtime installation size:

camelcase - MIT License

Bundled via tsup at build time.

Running Tests

pnpm test

Linting and Type Checking

pnpm lint
pnpm lint:fix
pnpm typecheck

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

MIT License - see the LICENSE.md file for details.

Repository

GitHub: https://github.com/wobondar/idl-filter
Issues: https://github.com/wobondar/idl-filter/issues
NPM: https://www.npmjs.com/package/anchor-idl-filter

Made with ❤️ for the Solana and Anchor ecosystem.

Name		Name	Last commit message	Last commit date
Latest commit History 240 Commits
.github		.github
examples		examples
src		src
.editorconfig		.editorconfig
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc.cjs		.prettierrc.cjs
CHANGELOG.md		CHANGELOG.md
LICENSE.md		LICENSE.md
README.md		README.md
eslint.config.mjs		eslint.config.mjs
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
release.config.mjs		release.config.mjs
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

Folders and files

Latest commit

History

Repository files navigation

Anchor IDL Filter

Features

Use Cases

Installation

Global Installation

Local Installation

Quick Start

Basic Usage

Configuration

Configuration File

Configuration File Discovery

CLI Options

Basic Options

Filtering Options

Override Options

Output Options

Examples

Example 1: Trading Program Filter

Example 2: Configuration-Based Filtering

Example 3: Client-Side Types Generation

Output Formats

JSON Output

TypeScript Output

Advanced Usage

Dry Run Mode

CamelCase Transformation

Configuration Schema

IDLFilterConfig Type

Development

Building from Source

Bundled Dependencies

Running Tests

Linting and Type Checking

Contributing

License

Repository

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 9

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages