Generating IDL and Client Code with the Quasar CLI

Quasar uses an Interface Definition Language (IDL) as the canonical description of your program’s public surface: its instructions, account types, error codes, and events. The quasar idl command extracts this description from your Rust source code, and quasar client turns it into ready-to-use client code in TypeScript, Python, Go, or C. Both commands are also run automatically during quasar build, so generated clients stay in sync with your program on every compile.

`quasar idl`

quasar idl PATH generates the IDL JSON for a program crate and writes it to target/idl/<name>.json. It also generates a Rust client crate in target/client/rust/. The PATH argument is the path to the program crate directory — typically . when running from the project root.

quasar idl .
quasar idl programs/my-program

How IDL Generation Works

Quasar extracts the IDL by compiling the program crate with the idl-build Cargo feature enabled and running a special __quasar_emit_idl test that prints the IDL as JSON to stdout. The Quasar framework macro infrastructure captures instruction discriminators, account field names and types, error variants, and event definitions at compile time, so the IDL always reflects the actual compiled program — not a hand-written description. Your Cargo.toml must include the idl-build feature for this to work:

[features]
idl-build = ["quasar-lang/idl-build"]

This feature is included by default in all projects scaffolded with quasar init.

Output

target/
└── idl/
    └── my_program.json

The IDL JSON file is also used by quasar lint to track your program’s public surface in quasar.lock.json.

IDL JSON Structure

The IDL JSON describes every public-facing element of your program. Here is an example structure:

{
  "name": "my_program",
  "version": "0.1.0",
  "address": "4rEGsVnJb3...",
  "instructions": [
    {
      "name": "initialize",
      "discriminator": 0,
      "accounts": [
        { "name": "payer", "signer": true, "writable": false },
        { "name": "system_program", "signer": false, "writable": false }
      ],
      "args": []
    }
  ],
  "accounts": [
    {
      "name": "MyAccount",
      "discriminator": 1,
      "fields": [
        { "name": "authority", "type": "address" },
        { "name": "value", "type": "u64" }
      ]
    }
  ],
  "types": [],
  "errors": [
    { "code": 0, "name": "Unauthorized", "msg": "Unauthorized" }
  ],
  "events": []
}

Field	Description
`name`	Program crate name (snake_case)
`version`	Version from `Cargo.toml`
`address`	On-chain program ID from `declare_id!()`
`instructions[]`	All `#[instruction]` handlers with discriminators, accounts, and args
`accounts[]`	All `#[account]` structs with discriminators and fields
`types[]`	Shared types referenced by instructions or accounts
`errors[]`	All `#[error_code]` variants
`events[]`	All `#[event]` structs

`quasar client`

quasar client IDL [--lang ...] generates client code from an IDL JSON file. By default it generates clients for all supported languages; use --lang to restrict to specific ones.

quasar client target/idl/my_program.json
quasar client target/idl/my_program.json --lang typescript
quasar client target/idl/my_program.json --lang typescript,golang
quasar client target/idl/my_program.json --lang python

Flags

Flag	Description
`IDL`	Path to the IDL JSON file (e.g. `target/idl/my_program.json`)
`--lang LANG`	Comma-separated list of languages to generate. Options: `typescript`, `python`, `golang`, `c`. Default: all.

Language aliases are accepted: ts → typescript, py → python, go → golang.

Output Paths

Client code is written to the path configured in Quasar.toml under clients.path (default: target/client/):

target/client/
├── typescript/
│   └── my_program/
│       ├── web3.ts
│       ├── kit.ts
│       └── package.json
├── python/
│   └── my_program/
│       ├── client.py
│       └── __init__.py
├── golang/
│   └── my_program/
│       ├── client.go
│       └── go.mod
└── c/
    └── my_program/
        └── client.h

Generated Client Code

TypeScript (Kit)
Python
Go
C

The TypeScript client includes two variants: kit.ts for @solana/kit (the modern Solana TypeScript SDK) and web3.ts for @solana/web3.js. Both provide strongly typed instruction builders and account decoders.Example usage with @solana/kit:

import { address, createSolanaRpc } from "@solana/kit";
import { createInitializeInstruction } from "./target/client/typescript/my_program/kit";

const rpc = createSolanaRpc("https://api.devnet.solana.com");
const programAddress = address("4rEGsVnJb3...");

const ix = createInitializeInstruction({
  programAddress,
  accounts: {
    payer: payerAddress,
    systemProgram: address("11111111111111111111111111111111"),
  },
});

The generated package.json in the client directory declares the correct peer dependencies so the client can be published as a standalone npm package.

The Python client provides instruction builders and account decoders using the standard solders and solana-py ecosystem. It is generated as a Python package with an __init__.py that re-exports everything from client.py.

from my_program import create_initialize_instruction
from solders.pubkey import Pubkey

payer = Pubkey.from_string("...")
system_program = Pubkey.from_string("11111111111111111111111111111111")

ix = create_initialize_instruction(
    payer=payer,
    system_program=system_program,
)

Install the client by adding the package directory to your Python path or copying it into your project.

The Go client is generated as a Go module with its own go.mod. It provides typed instruction constructors and account data structs.

package main

import (
    myprogram "path/to/target/client/golang/my_program"
    "github.com/gagliardetto/solana-go"
)

func main() {
    payer := solana.NewWallet().PublicKey()

    ix := myprogram.NewInitializeInstruction(
        payer,
        solana.SystemProgramID,
    ).Build()

    // sign and send...
}

The C client is generated as a single header file (client.h) containing serialization helpers, instruction data structs, and discriminator constants. It targets embedded and systems use cases where a full SDK is not appropriate.

#include "target/client/c/my_program/client.h"

uint8_t ix_data[1] = { MY_PROGRAM_INITIALIZE_DISCRIMINATOR };

SolInstruction ix = {
    .program_id = &MY_PROGRAM_ID,
    .accounts   = accounts,
    .account_len = 2,
    .data        = ix_data,
    .data_len    = 1,
};

Typical IDL & Client Workflow

Write and build your program

quasar build

quasar build automatically generates the IDL and all configured client languages. You only need to run quasar idl or quasar client manually when you want to target a specific crate path or language outside of the normal build flow.

Inspect the generated IDL

cat target/idl/my_program.json

Verify that all your instructions, accounts, and errors appear with the correct discriminators and field types.

Generate clients from a saved IDL

If you have an IDL JSON from a deployed program and want to regenerate clients without a local source build:

quasar client target/idl/my_program.json --lang typescript,python

Commit the IDL

The IDL JSON is the public contract for your program. Commit target/idl/<name>.json to source control so that client developers can regenerate their own clients without having to build the Rust crate.

Client code is regenerated on every quasar build. If you change an instruction signature, account layout, or error variant, the generated clients are updated automatically. Run quasar lint to see a diff of what changed relative to quasar.lock.json.

Get Started

Core Framework

Account Types

SPL Integration

CLI Reference

Examples

Generating IDL and Client Code with the Quasar CLI

`quasar idl`

How IDL Generation Works

Output

IDL JSON Structure

`quasar client`

Flags

Output Paths

Generated Client Code

Typical IDL & Client Workflow

Build docs developers (and LLMs) love

Get Started

Core Framework

Account Types

SPL Integration

CLI Reference

Examples

Documentation Index

​quasar idl

​How IDL Generation Works

​Output

​IDL JSON Structure

​quasar client

​Flags

​Output Paths

​Generated Client Code

​Typical IDL & Client Workflow

Build docs developers (and LLMs) love

`quasar idl`

How IDL Generation Works

Output

IDL JSON Structure

`quasar client`

Flags

Output Paths

Generated Client Code

Typical IDL & Client Workflow