@recursa-ai/idl

Recursa Anchor IDL + canonical program IDs, instruction discriminators, PDA derivation helpers, and token mint registry. Dependency-free so it composes cleanly with both browser + Node + edge runtimes without forcing consumers to install @solana/web3.js or @coral-xyz/anchor.

Used by @recursa-ai/sdk to build unsigned transactions without pulling in all of Anchor. Shipped as its own package so agent authors who only need discriminators + PDA shapes can take this without the SDK's Jupiter-price + strategy-filter machinery.

Install

npm install @recursa-ai/idl

What's exported

// The Anchor IDL JSON as a typed const.
import { RECURSA_IDL } from "@recursa-ai/idl/idl";
import { Program } from "@coral-xyz/anchor";
const program = new Program(RECURSA_IDL, provider);

// Program IDs + well-known system/lending pubkeys.
import {
  RECURSA_PROGRAM_ID_DEVNET,
  getRecursaProgramId,
  TOKEN_PROGRAM_ID,
  KAMINO_LEND_PROGRAM_ID,
} from "@recursa-ai/idl";

// PDA seed materializers (strings/bytes → no web3.js dep).
import {
  configPdaSeeds,
  userStatsPdaSeeds,
  positionPdaSeeds,
  u64ToLeBytes,
} from "@recursa-ai/idl";
import { PublicKey } from "@solana/web3.js";

const [configPda] = PublicKey.findProgramAddressSync(
  configPdaSeeds(),
  new PublicKey(RECURSA_PROGRAM_ID_DEVNET)
);

// Instruction discriminators + borsh-encoded arg bodies.
import {
  DISCRIMINATORS,
  encodeCreatePositionData,
} from "@recursa-ai/idl";

const data = encodeCreatePositionData({
  amount: 1_000_000_000n,
  leverage: 2_500_000n, // 2.5×
  supplyProtocol: "kamino",
  borrowProtocol: "kamino",
  crossAsset: false,
  userNonce: BigInt(Date.now()),
  swapRouteData: null,
  minOutputAmount: null,
});

// Token mint registry.
import { MINT_BY_SYMBOL, mintFor } from "@recursa-ai/idl";
const { mint, decimals } = mintFor("SOL");

Regenerating the IDL

The source of truth is programs/recursa/src/**/*.rs. When the Rust program changes:

anchor build
cp target/idl/recursa.json packages/idl/src/recursa.json
cd packages/idl && npm test  # parity tests catch drifted discriminators / enums
npm run build

The parity tests (src/instructions.test.ts) compare DISCRIMINATORS against the IDL JSON — if the JSON gets out of sync they fail loudly. If an instruction's snake_case name changes, add the new entry + delete the old one.

Contract stability

v0.1 is pre-1.0 — minor versions may reshape TS surfaces. The IDL JSON itself is stable: new instructions get added; existing ones don't change discriminators, account order, or arg layout without a program-level migration.

License

MIT. © 2026 Recursa.