Finding IDLs

Hyperstack uses IDL (Interface Definition Language) files to generate type-safe bindings for your data streams. An IDL is a JSON file that describes a Solana program’s accounts, instructions, and custom types. Hyperstack supports Anchor and other framework IDL formats.

To build a custom stack, you need the IDL for the program you want to track.

Methods to Find IDLs

Follow these steps in order to find the IDL for any Solana program.

1. Program GitHub Repository

Most Solana projects are open source. Search GitHub for the protocol name followed by “idl.json” or look in the project’s repository. Common locations include:

target/idl/program_name.json
idl/program_name.json
The “Releases” page as an attached asset

2. Anchor CLI Fetch

If a program is built with Anchor and the developers uploaded the IDL on-chain, you can fetch it directly using the Anchor CLI:

anchor idl fetch <PROGRAM_ID> --provider.cluster mainnet -o idl/program.json

Replace <PROGRAM_ID> with the program’s on-chain address. Not every program has an IDL on-chain, so this may return an error if it’s missing.

3. NPM or Rust Packages

Many protocols publish SDKs for developers. These packages often include the IDL file so the SDK can encode and decode instructions.

NPM: Check node_modules/@protocol-name/sdk/dist/idl.json or similar paths.
Crates.io: Some Rust crates include the IDL as a resource.

4. Block Explorers

Explorers like Solscan or Solana.fm sometimes host IDLs for verified programs. Look for a “Contract” or “IDL” tab when viewing a program address. You can often download the JSON directly from these pages.

5. Manual Creation

If an IDL isn’t available, you can create one manually by examining the program’s source code. Tools like Kinobi or Codama can generate IDLs by parsing the Rust source.

Where to Put IDLs

In a Hyperstack project, store your IDL files in an idl/ directory at the root of your stack. This keeps your project organized and makes it easy to reference them in your code.

my-stack/
├── idl/
│   └── program_name.json    # IDL goes here
├── src/
│   └── stack.rs              # References the IDL
├── hyperstack.toml
└── Cargo.toml

Reference the IDL in your src/stack.rs using the #[hyperstack] macro:

#[hyperstack(idl = "idl/program_name.json")]
pub struct MyStack;

Common IDL Locations

Protocol	Program ID	Source
ORE	`oreo7nRnU86QCen6Np3iH6q8C6c6K6c6K6c6K6c6K6c`	GitHub
System Program	`11111111111111111111111111111111`	Built-in
Token Program	`TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA`	Built-in

Exploring IDLs with the CLI

Once you have an IDL file, use hs idl to explore it before writing your stack:

# Get a quick overview
hs idl summary idl/program.json

# Browse all instructions
hs idl instructions idl/program.json

# Find how accounts relate to each other
hs idl relations idl/program.json

# Search for anything
hs idl search idl/program.json <query>

See the hs idl reference for the full command list.