DEV Community

Cover image for idl-codegen: typed TypeScript and Dart clients from an Anchor IDL
Abdeldjalil Chougui
Abdeldjalil Chougui

Posted on Originally published at abdeldjalilchougui.biz

idl-codegen: typed TypeScript and Dart clients from an Anchor IDL

An Anchor program describes itself in an IDL: its instructions, accounts, types, events, errors and PDA seeds. The program side is generated for you by Anchor's macros. The client side is where the hand work starts. Someone has to write the function that serializes the arguments in Borsh, puts the 8-byte discriminator in front, lists the accounts in the right order with the right signer and writable flags, and derives the PDAs from the same seeds as the program.

Writing that once is fine. Writing it twice, in TypeScript for the web app and in Dart for the Flutter app, means two copies that have to stay in sync with the program and with each other. A wrong byte in either one gives a transaction that fails on chain with an error that says little.

idl-codegen reads an Anchor IDL (0.30+ spec) and writes both clients. The README opens with a warning that belongs here too: the project is not audited. Generated clients build instructions and decode accounts; they do not sign or send anything. Check the generated code against your program before you use it with real funds, and test on devnet first.

What it does

One command produces two sets of files:

  • TypeScript: <name>.ts and borsh.ts, which depend on @solana/web3.js v1.
  • Dart: <name>.dart and borsh.dart, which depend on package:crypto, for Flutter apps.

Each client contains the same building blocks.

Program id. PROGRAM_ID in TypeScript and <name>ProgramId in Dart.

Types. In TypeScript you get interfaces, enums as { kind: ... } unions, and encodeX / decodeX functions. In Dart you get classes with encode and static decode. Unit enums become Dart enums and data enums become sealed classes.

Instruction builders. createXInstruction(accounts, args) returns a TransactionInstruction in TypeScript. The Dart version takes named arguments and returns an Instruction. Accounts with a fixed address in the IDL, such as the System Program, default to it. Optional accounts default to the program id, which is Anchor's convention for "None".

Account decoders. decodeXAccount(data) checks the discriminator before decoding, and TypeScript also gets isXAccount.

Events. decodeXEvent(data) in both languages.

PDA helpers. findXPda(...seeds) is generated from pda.seeds in the IDL: constant seeds, account seeds, argument seeds, and seeds::program cases such as associated token accounts. The Dart client ships its own findProgramAddress.

Errors and constants. ERRORS and <Name>Error.fromCode() in TypeScript, <name>Errors and <Name>Exception.fromCode() in Dart, plus the #[constant] values of the program.

The type mapping is the same idea on both sides: u64, i64, u128 and i128 become bigint / BigInt; smaller integers become number / int; pubkey becomes PublicKey / Pubkey; bytes becomes Uint8Array / Uint8List; Option<T> becomes T | null / T?. Tuple structs and tuple variants become values: [...] in TypeScript and field0, field1 in Dart.

How to use it

You need Node.js 20 or later. Clone the repository and run the generator from the checkout:

git clone https://github.com/AbdeldjalilChougui/idl-codegen
cd idl-codegen
pnpm install
pnpm gen target/idl/my_program.json --ts app/src/generated --dart mobile/lib/generated
# or after `pnpm build`:  node dist/cli.js <idl.json> --ts <dir> --dart <dir>
Enter fullscreen mode Exit fullscreen mode

The first argument is the IDL file that anchor build wrote. --ts and --dart are the output directories. The generated TypeScript needs @solana/web3.js v1 in your app, and the generated Dart needs package:crypto.

Then, in the web app:

import { createIncrementInstruction, findCounterPda } from "./generated/counter_todo.js";
const [counter] = findCounterPda(wallet.publicKey);
const ix = createIncrementInstruction({ authority: wallet.publicKey, counter }, { by: 1n });
Enter fullscreen mode Exit fullscreen mode

And the same call in the Flutter app:

import 'generated/counter_todo.dart';
final (counter, _) = findCounterPda(authority: me);
final ix = createIncrementInstruction(authority: me, counter: counter, by: BigInt.one);
Enter fullscreen mode Exit fullscreen mode

Both snippets derive the same PDA and build the same instruction bytes. Signing and sending stay in your own code, with whatever wallet and RPC layer the app already uses.

How it is tested

Generated code is only useful if you can trust the bytes, so most of the README's test section is about that.

  • Golden tests. Every IDL in test/fixtures/ is generated and compared byte for byte with test/golden/. The fixtures are counter_todo and escrow, which are real IDLs from sibling Anchor projects, and kitchen_sink, written by hand to cover every type: nested account groups, optional accounts, data enums, tuple structs, u128/i128, f64, fixed arrays and seeds::program.
  • Strict compilers. The generated TypeScript passes tsc --strict and the generated Dart passes dart analyze --fatal-infos. The Dart check is skipped if dart is not on the PATH.
  • Behaviour. PDA helpers match PublicKey.findProgramAddressSync, including ATA PDAs. Instruction data is the discriminator followed by the Borsh arguments. Accounts round-trip through encode and decode, and the discriminator is checked.
  • Cross-language. A Dart program in test/golden/dart/bin/check.dart builds the same instructions, PDAs and account bytes, and the test checks that its output matches the TypeScript client byte for byte.

That last check found a real bug. On the Dart 3.9 VM, BigInt.modPow returned wrong results for some 255-bit inputs, which broke the ed25519 on-curve check that findProgramAddress relies on. The Dart runtime in the generated client now uses its own square-and-multiply instead.

Things to know

  • Not audited. The clients only build instructions and decode data, but a wrong instruction can still move funds once you sign it. Compare the output with your program and try it on devnet first.
  • Generic types are rejected. An IDL that uses generics will not generate.
  • Some PDA seeds become raw bytes. Seeds that read an account's data (path: "list.next_id") or a field of a struct argument become a raw bytes parameter. When another instruction derives the same account from a plain argument, the generator uses that simpler form instead.
  • coption is not tested against a real program. It is supported in encoding and decoding, but only that.
  • Legacy IDLs need converting. IDLs from before Anchor 0.30 must be converted first with anchor idl convert.
  • web3.js v1. The TypeScript output targets @solana/web3.js v1.

Why I built it

The problem is duplication. The IDL already contains everything a client needs: argument types, account order, discriminators, seeds, error codes. Writing the client by hand means copying that information into code, and copying it a second time when a mobile app in Dart sits next to a web app in TypeScript. Every change to the program then has to be repeated in two places, and nothing tells you when one of them is out of date.

Generating both clients from the same IDL removes that copy step, and it makes it possible to test the two outputs against each other. If the TypeScript and the Dart client produce the same bytes for the same inputs, and the TypeScript one agrees with @solana/web3.js on PDAs, there is much less room for a silent mismatch. The BigInt.modPow bug is a good example of why that cross-check is worth having: nothing in the Dart code looked wrong, and only the byte comparison showed it.

Get the code

The generator, the fixtures, the golden files and the tests are on GitHub: https://github.com/AbdeldjalilChougui/idl-codegen. It is MIT licensed. Issues and pull requests are welcome.


Originally published at abdeldjalilchougui.biz.

Top comments (0)