Codama

Note

Wait, wasn't this project called Kinobi before? We've renamed this project to 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:

• Create clients for your programs in various languages/frameworks
• Make CLIs
• Provide additional information to explorers

I'm a busy Anchor developer. How do I use Codama?

If you're using Anchor, Codama can be used to create a TypeScript client that works with Solana Kit. This combination replaces the traditional @coral-xyz/anchor and @solana/web3.js packages, and can be used in both TypeScript tests, and the browser.

• The programClient created by Codama will be used to create instructions for your Anchor program, and decode your Anchor program's data accounts.
• @solana/kit will be used to connect to the network, send transactions, and do most tasks that aren't specific to your program.
• @solana/react will be used to connect to Solana wallet apps like Phantom, Solflare, etc. in React.

This Codama README shows you how to create the TypeScript client for your Anchor program, but if you're interested in the bigger picture, see QuickNode's video on Anchor and Solana Kit.

Example Anchor Projects Using Codama

Anchor Election app

Anchor Swap/Escrow app

Using Codama

Creating a Codama IDL for your Solana Program

There are various ways to get a Codama IDL from your Solana program:

• From an Anchor IDL. If you are using Anchor programs or Shank macros, then you can get an Anchor IDL from them. You can then use the @codama/nodes-from-anchor package to convert that IDL into a Codama IDL as shown in the code snippet below. Note that the Anchor IDL might not offer all the information that Codama can hold, and therefore, you may want to transform your Codama IDL to provide additional information. You can learn more about this in the next section.

  import { createFromRoot } from 'codama';
  import { rootNodeFromAnchor } from '@codama/nodes-from-anchor';
  import anchorIdl from 'anchor-idl.json';
  
  const codama = createFromRoot(rootNodeFromAnchor(anchorIdl));

• Using Codama macros. This is not yet available, but you will soon have access to a set of Rust macros that help attach IDL information directly within your Rust code. These macros enable Codama IDLs to be generated whenever you build your programs.

• By hand. If your Solana program cannot be updated to use Codama macros and you don't have an Anchor IDL, you can design your Codama IDL manually. We may provide tools such as a Codama Playground to help with that in the future.

Using the Codama IDL

Now that you have the perfect Codama IDL for your Solana program, you can benefit from all the existing Codama tooling for tasks like such as making clients in various languages, making CLIs, and registering your IDL onchain so explorers can dynamically display relevant information for your program.

Note

Some features, such as rendering CLIs, are not yet available. However, because of Codama's design, these features are only a visitor away from being ready. Feel free to reach out if you'd like to contribute to the Codama ecosystem!

Making clients for your program

Want people to start interacting with your Solana program? You can generate clients that you can then publish for your end-users. Currently, we have the following renderers available:

• @codama/renderers-js: Renders a JavaScript client compatible with @solana/kit.
• @codama/renderers-js-umi: Renders a JavaScript client compatible with Metaplex's Umi framework.
• @codama/renderers-rust: Renders a Rust client that removes the need for publishing the program crate and offers a better developer experience.
• And more to come.

Here's an example of how to generate JavaScript and Rust client code for your program.

import { renderJavaScriptVisitor, renderRustVisitor } from '@codama/renderers';

codama.accept(renderJavaScriptVisitor('clients/js/src/generated', { ... }));
codama.accept(renderRustVisitor('clients/rust/src/generated', { ... }));

Registering your Codama IDL onchain (Coming soon)

Perhaps the most significant benefit of having a Codama IDL from your program is that you can share it onchain with the rest of the ecosystem. This means explorers may now use this information to provide a better experience for users of your programs. Additionally, anyone can now grab your Codama IDL, select the portion they are interested in and benefit from the same ecosystem of Codama visitors to iterate over it. For instance, an app could decide to grab the IDLs of all programs it depends on, filter out the accounts and instructions the app doesn't need, and generate a bespoke client for their app that only contains the functions the app needs.

Creating CLIs (Not yet available)

Whilst not available yet, we can imagine a set of CLI commands that can be generated from our Codama IDL (much like our clients) so that end-users can fetch decoded accounts and send instructions directly from their terminal.

Creating documentation (Not yet available)

Similarly to CLIs, we may easily generate documentation in various formats from the information held by our Codama IDL.

Codama 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

'Codama' tag on Solana Stack Exchange