codama-idl-codama

Codama

Codama is a tool that describes any Solana program in a standardised format called a Codama IDL.

A Codama IDL can be used to:

• ✨ Generate program clients in various languages and frameworks.
• 📚 Generate documentation and tooling for your programs.
• 🗃️ Register your IDL for others to discover and index.
• 🔭 Provide valuable information to explorers and wallets.

Table of contents

• Getting started. Install and use Codama in your project.
• Coming from Anchor. Have an Anchor IDL instead? Let’s make that work.
• Codama scripts. Enrich your Codama config file with more scripts.
• Available visitors. See what’s available for you to use.
• Getting a Codama IDL. Extract Codama IDLs from any program.
• Codama’s architecture. A bit more on the node/visitor design.
• Other resources.

Getting started

Installation

To get started with Codama, simply install codama to your project and run the init command like so:

pnpm install codama
codama init

You will be prompted for the path of your IDL and asked to select any script presets you would like to use. This will create a Codama configuration file at the root of your project.

Usage

You may then use the codama run command to execute any script defined in your configuration file.

codama run --all # Run all Codama scripts.
codama run js    # Generates a JavaScript client.
codama run rust  # Generates a Rust client.

Coming from Anchor

If you are using Anchor or Shank macros, then you should already have an Anchor IDL. To make it work with Codama, you simply need to provide the path to your Anchor IDL in your Codama configuration file. Codama will automatically identify this as an Anchor IDL and will convert it to a Codama IDL before executing your scripts.

{
    "idl": "path/to/my/anchor/idl.json"
}

Codama scripts

You can use your Codama configuration file to define any script you want by using one or more visitors that will be invoked when the script is ran.

Visitors are objects that will visit your Codama IDL and either perform some operation — like generating a program client — or update the IDL further — like renaming accounts. You can either use visitors from external packages or from a local file, and — in both cases — you can provide any argument the visitor may require.

For instance, the example script below will invoke three visitors:

• The first will use the default import from the my-external-visitor package and pass 42 as the first argument.
• The second will use the withDefaults import from the my-external-visitor package.

• The third will use a local visitor located next to the configuration file.

  {
  "scripts": {
      "my-script": [
          { "from": "my-external-visitor", "args": [42] },
          "my-external-visitor#withDefaults",
          "./my-local-visitor.js"
      ]
  }
  }
  

Note that if an external visitor in your script isn’t installed locally, you will be asked to install it next time you try to run that script.

❯ codama run my-script

▲ Your script requires additional dependencies.
▲ Install command: pnpm install my-external-visitor
? Install dependencies? › (Y/n)

You can learn more about the Codama CLI here.

Available visitors

The tables below aim to help you discover visitors from the Codama ecosystem that you can use in your scripts.

Feel free to PR your own visitor here for others to discover. Note that they are ordered alphabetically.

Generates documentation

Visitor	Description	Maintainer
@codama/renderers-demo (docs)	Generates simple documentation as a template to help others create new visitors.	Codama

Generates program clients

Visitor	Description	Maintainer
@codama/renderers-js (docs)	Generates a JavaScript client compatible with Solana Kit.	Anza
@codama/renderers-js-umi (docs)	Generates a JavaScript client compatible with the Umi framework.	Metaplex
@codama/renderers-rust (docs)	Generates a Rust client compatible with the Solana SDK.	Anza
@codama/renderers-vixen-parser (docs)	Generates Yellowstone account and instruction parsers.	Triton One
@limechain/codama-dart (docs)	Generates a Dart client.	LimeChain
codama-py (docs)	Generates a Python client.	Solar

Provides utility

Visitor	Description	Maintainer
@codama/visitors#* (docs)	Provides a big library of utility visitors that can be used to manipulate Codama IDLs. For instance, updateErrorsVisitor can be used to update error messages in your IDL . Check out the docs to see all available visitors.	Codama
@codama/visitors-core#* (docs)	Everything included in visitors-core is also included in visitors. The helpers offered in this package are slightly more advanced and can be used to help you build your own visitors.	Codama

Getting a Codama IDL

We are currently working on a set of transparent macros that can be added to any program in order to extract a Codama IDL from it. There are still a lot more macros and scenarios for us to support but most programs can already benefit from these macros. You can then extract an IDL from the provided crate path using the Codama API like so:

use codama::Codama;

let codama = Codama::load(crate_path)?;
let idl_json = codama.get_json_idl()?;

We will add documentation on Codama macros when they are fully implemented but feel free to check this example that extract a Codama IDL from the System program interface using a build script.

Codama's architecture

The Codama IDL is designed as a tree of nodes starting with the RootNode which contains a ProgramNode and additional data such as the Codama version used when the IDL was created. Codama provides over 60 different types of nodes that help describe nearly every aspect of your Solana programs. You can read more about the Codama nodes here.

Because everything is designed as a Node, we can transform the IDL, aggregate information, and output various utility tools using special objects that can traverse node trees known as visitors. See this documentation to learn more about Codama visitors.

Other resources

• Solana Stack Exchange.
• Working with Anchor
  • Anchor and Solana Kit tutorial.
  • Anchor Election app.
  • Anchor Swap/Escrow app.