Skip to content

Commit bfcf9d6

Browse files
lorisleivalorisleiva
authored
Update README and list available visitors (#857)
1 parent 38e08e4 commit bfcf9d6

File tree

1 file changed

+106
-56
lines changed

1 file changed

+106
-56
lines changed

‎README.md‎

Lines changed: 106 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -10,102 +10,152 @@
1010
[ci-image]: https://img.shields.io/github/actions/workflow/status/codama-idl/codama/main.yml?logo=GitHub
1111
[ci-url]: https://github.com/codama-idl/codama/actions/workflows/main.yml
1212

13-
> [!NOTE]
14-
> Wait, wasn't this project called Kinobi before? We've [renamed this project to **Codama**](https://github.com/codama-idl/codama/pull/234).
15-
16-
Codama is a tool that describes any Solana program in a standardised format called a **Codama IDL**.
13+
Codama is a tool that describes any Solana program in a standardised format called a **Codama IDL**.
1714

1815
A Codama IDL can be used to:
1916

20-
- Create clients for your programs in various languages/frameworks
21-
- Make CLIs
22-
- Provide additional information to explorers
17+
- ✨ Generate **program clients** in various languages and frameworks.
18+
- 📚 Generate **documentation and tooling** for your programs.
19+
- 🗃️ **Register your IDL** for others to discover and index.
20+
- 🔭 Provide valuable information to **explorers and wallets**.
21+
22+
![Codama header: A small double-sided mind-map with the Codama logo in the middle. On the left, we see the various ways to get a Codama IDL from your Solana programs such as "Codama Macros" and "Anchor Program". On the right, we see the various utility tools that are offered for the IDL such as "Generate clients" or "Register IDL".](https://github.com/user-attachments/assets/7a2ef5fa-049e-45a8-a5fc-7c11ff46a54b)
2323

24-
![Codama header: A small double-sided mind-map with the Codama logo in the middle. On the left, we see the various ways to get a Codama IDL from your Solana programs such as "Anchor Program" and "Shank macros". On the right, we see the various utility tools that are offered for the IDL such as "Rendering client code" or "Rendering documentation".](https://github.com/user-attachments/assets/029af336-ea71-4e7f-9612-ef5bb187e3a0)
24+
## Table of contents
2525

26-
## I'm a busy Anchor developer. How do I use Codama?
26+
- [Getting started](#getting-started). Install and use Codama in your project.
27+
- [Coming from Anchor](#coming-from-anchor). Have an Anchor IDL instead? Let’s make that work.
28+
- [Codama scripts](#codama-scripts). Enrich your Codama config file with more scripts.
29+
- [Available visitors](#available-visitors). See what’s available for you to use.
30+
- [Getting a Codama IDL](#getting-a-codama-idl). Extract Codama IDLs from any program.
31+
- [Codama’s architecture](#codamas-architecture). A bit more on the node/visitor design.
32+
- [Other resources](#other-resources).
2733

28-
If you're using [Anchor](https://www.anchor-lang.com/), Codama can be used to create a TypeScript client that works with [Solana Kit](https://github.com/anza-xyz/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.
34+
## Getting started
2935

30-
- The `programClient` created by Codama will be used to create instructions for your Anchor program, and decode your Anchor program's data accounts.
31-
- [`@solana/kit`](https://github.com/anza-xyz/kit) will be used to connect to the network, send transactions, and do most tasks that aren't specific to your program.
32-
- [`@solana/react`](https://github.com/anza-xyz/kit/tree/main/packages/react) will be used to connect to Solana wallet apps like Phantom, Solflare, etc. in React.
36+
### Installation
3337

34-
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](https://www.youtube.com/watch?v=2T3DOMv7iR4).
38+
To get started with Codama, simply install `codama` to your project and run the `init` command like so:
3539

36-
### Example Anchor Projects Using Codama
40+
```sh
41+
pnpm install codama
42+
codama init
43+
```
3744

38-
[Anchor Election app](https://github.com/quiknode-labs/anchor-election-2025)
45+
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.
3946

40-
[Anchor Swap/Escrow app](https://github.com/quiknode-labs/you-will-build-a-solana-program)
47+
### Usage
4148

42-
## Using Codama
49+
You may then use the `codama run` command to execute any script defined in your configuration file.
4350

44-
### Creating a Codama IDL for your Solana Program
51+
```sh
52+
codama run --all # Run all Codama scripts.
53+
codama run js # Generates a JavaScript client.
54+
codama run rust # Generates a Rust client.
55+
```
4556

46-
There are various ways to get a Codama IDL from your Solana program:
57+
## Coming from Anchor
4758

48-
- **From an Anchor IDL**. If you are using [Anchor programs](https://github.com/coral-xyz/anchor) or [Shank macros](https://github.com/metaplex-foundation/shank), 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.
59+
If you are using [Anchor](https://www.anchor-lang.com/docs) or [Shank macros](https://github.com/metaplex-foundation/shank), 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.
4960

50-
```ts
51-
import { createFromRoot } from 'codama';
52-
import { rootNodeFromAnchor } from '@codama/nodes-from-anchor';
53-
import anchorIdl from 'anchor-idl.json';
61+
```json
62+
{
63+
"idl": "path/to/my/anchor/idl.json"
64+
}
65+
```
5466

55-
const codama = createFromRoot(rootNodeFromAnchor(anchorIdl));
56-
```
67+
## Codama scripts
5768

58-
- **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.
69+
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.
5970

60-
- **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.
71+
**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.
6172

62-
### Using the Codama IDL
73+
For instance, the example script below will invoke three visitors:
6374

64-
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.
75+
- The first will use the `default` import from the `my-external-visitor` package and pass `42` as the first argument.
76+
- The second will use the `withDefaults` import from the `my-external-visitor` package.
77+
- The third will use a local visitor located next to the configuration file.
6578

66-
> [!NOTE]
67-
> Some features, such as rendering CLIs, are not yet available. However, because of Codama's design, these features are only [a visitor away](#codama-architecture) from being ready. Feel free to reach out if you'd like to contribute to the Codama ecosystem!
79+
```json
80+
{
81+
"scripts": {
82+
"my-script": [
83+
{ "from": "my-external-visitor", "args": [42] },
84+
"my-external-visitor#withDefaults",
85+
"./my-local-visitor.js"
86+
]
87+
}
88+
}
89+
```
6890

69-
#### Making clients for your program
91+
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.
7092

71-
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:
93+
```sh
94+
❯ codama run my-script
7295

73-
- `@codama/renderers-js`: Renders a JavaScript client compatible with [`@solana/kit`](https://github.com/anza-xyz/kit).
74-
- `@codama/renderers-js-umi`: Renders a JavaScript client compatible with Metaplex's [Umi](https://github.com/metaplex-foundation/umi) framework.
75-
- `@codama/renderers-rust`: Renders a Rust client that removes the need for publishing the program crate and offers a better developer experience.
76-
- _And more to come._
96+
▲ Your script requires additional dependencies.
97+
▲ Install command: pnpm install my-external-visitor
98+
? Install dependencies? › (Y/n)
99+
```
77100

78-
Here's an example of how to generate JavaScript and Rust client code for your program.
101+
You can [learn more about the Codama CLI here](/packages/cli/README.md).
79102

80-
```ts
81-
import { renderJavaScriptVisitor, renderRustVisitor } from '@codama/renderers';
103+
## Available visitors
82104

83-
codama.accept(renderJavaScriptVisitor('clients/js/src/generated', { ... }));
84-
codama.accept(renderRustVisitor('clients/rust/src/generated', { ... }));
85-
```
105+
The tables below aim to help you discover visitors from the Codama ecosystem that you can use in your scripts.
86106

87-
### Registering your Codama IDL onchain (_Coming soon_)
107+
Feel free to PR your own visitor here for others to discover. Note that they are ordered alphabetically.
88108

89-
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.
109+
### Generates documentation
90110

91-
#### Creating CLIs (_Not yet available_)
111+
| Visitor | Description | Maintainer |
112+
| ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ---------- |
113+
| `@codama/renderers-demo` ([docs](https://github.com/codama-idl/renderers-demo)) | Generates simple documentation as a template to help others create new visitors. | Codama |
92114

93-
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.
115+
### Generates program clients
94116

95-
#### Creating documentation (_Not yet available_)
117+
| Visitor | Description | Maintainer |
118+
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------- |
119+
| `@codama/renderers-js` ([docs](https://github.com/codama-idl/renderers-js)) | Generates a JavaScript client compatible with [Solana Kit](https://www.solanakit.com/). | [Anza](https://www.anza.xyz/) |
120+
| `@codama/renderers-js-umi` ([docs](https://github.com/codama-idl/renderers-js-umi)) | Generates a JavaScript client compatible with [the Umi framework](https://developers.metaplex.com/umi). | [Metaplex](https://www.metaplex.com/) |
121+
| `@codama/renderers-rust` ([docs](https://github.com/codama-idl/renderers-rust)) | Generates a Rust client compatible with [the Solana SDK](https://github.com/anza-xyz/solana-sdk). | [Anza](https://www.anza.xyz/) |
122+
| `@codama/renderers-vixen-parser` ([docs](https://github.com/codama-idl/renderers-vixen-parser)) | Generates [Yellowstone](https://github.com/rpcpool/yellowstone-grpc) account and instruction parsers. | [Triton One](https://triton.one/) |
123+
| `codama-py` ([docs](https://github.com/Solana-ZH/codama-py)) | Generates a Python client. | [Solar](https://github.com/Solana-ZH) |
124+
125+
### Provides utility
126+
127+
| Visitor | Description | Maintainer |
128+
| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
129+
| `@codama/visitors#*` ([docs](https://github.com/codama-idl/codama/blob/main/packages/visitors/README.md)) | 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](https://github.com/codama-idl/codama/blob/main/packages/visitors/README.md) to see all available visitors. | Codama |
130+
| `@codama/visitors-core#*` ([docs](https://github.com/codama-idl/codama/blob/main/packages/visitors-core/README.md)) | 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](https://github.com/codama-idl/codama/blob/main/packages/visitors-core/README.md#writing-your-own-visitor). | Codama |
131+
132+
## Getting a Codama IDL
133+
134+
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:
135+
136+
```rust
137+
use codama::Codama;
138+
139+
let codama = Codama::load(crate_path)?;
140+
let idl_json = codama.get_json_idl()?;
141+
```
96142

97-
Similarly to CLIs, we may easily generate documentation in various formats from the information held by our Codama IDL.
143+
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](https://github.com/lorisleiva/codama-demo-2025-08/tree/main/3-from-macros/program/src) using a [build script](https://github.com/lorisleiva/codama-demo-2025-08/blob/main/3-from-macros/program/build.rs).
98144

99-
## Codama Architecture
145+
## Codama's architecture
100146

101-
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](./packages/nodes).
147+
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](./packages/nodes).
102148

103149
![A small example of a Codama IDL as a tree of nodes. It starts with a RootNode and goes down to ProgramNode, AccountNode, InstructionNode, etc.](https://github.com/codama-idl/codama/assets/3642397/9d53485d-a4f6-459a-b7eb-58faab716bc1)
104150

105-
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](./packages/visitors).
151+
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](./packages/visitors-core).
106152

107153
![A small example of how a visitor can transform a Codama IDL into another Codama IDL. This example illustrates the "deleteNodesVisitor" which recursively removes NumberTypeNodes from a tree of nested TypleTypeNodes.](https://github.com/codama-idl/codama/assets/3642397/f54e83d1-eade-4674-80dc-7ddc360f5f66)
108154

109-
## Other Resources
155+
## Other resources
110156

111-
['Codama' tag on Solana Stack Exchange](https://solana.stackexchange.com/questions/tagged/codama)
157+
- [Solana Stack Exchange](https://solana.stackexchange.com/questions/tagged/codama).
158+
- Working with Anchor
159+
- [Anchor and Solana Kit tutorial](https://www.youtube.com/watch?v=2T3DOMv7iR4).
160+
- [Anchor Election app](https://github.com/quiknode-labs/anchor-election-2025).
161+
- [Anchor Swap/Escrow app](https://github.com/quiknode-labs/you-will-build-a-solana-program).

0 commit comments

Comments
 (0)