Skip to content

Commit 5503224

Browse files
mikemaccanamikemaccana
authored
Rework documentation (#679)
This is mostly the same documentation, just reorganized: - Add a section for impatient Anchor developers - Focus on creating IDL and then generating clients from the IDL, without first needing to understand design patterns and architecture. - Use plainer language, eg 'create Clients' over 'render' etc.
1 parent f408807 commit 5503224

File tree

1 file changed

+63
-34
lines changed

1 file changed

+63
-34
lines changed

‎README.md‎

Lines changed: 63 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -11,28 +11,41 @@
1111
[ci-url]: https://github.com/codama-idl/codama/actions/workflows/main.yml
1212

1313
> [!NOTE]
14-
> Wait, wasn't this called Kinobi before? It was! We've renamed this project **Codama**. [Check out this PR](https://github.com/codama-idl/codama/pull/234) for more details.
14+
> Wait, wasn't this project called Kinobi before? We've [renamed this project to **Codama**](https://github.com/codama-idl/codama/pull/234).
1515
16-
Codama is a tool that describes any Solana program in a powerful standardised format known as the Codama IDL. This IDL can then be used to create a variety of utility such as rendering client code for your programs in various languages/frameworks, generating CLIs and providing more information to explorers.
16+
Codama is a tool that describes any Solana program in a standardised format called a **Codama IDL**.
17+
18+
A Codama IDL can be used to:
19+
20+
- Create clients for your programs in various languages/frameworks
21+
- Make CLIs
22+
- Provide additional information to explorers
1723

1824
![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)
1925

20-
## Nodes and visitors
26+
## I'm a busy Anchor developer. How do I use Codama?
2127

22-
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 just about any aspect of your Solana programs. [You can read more about the Codama nodes here](./packages/nodes).
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.
2329

24-
![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)
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.
2533

26-
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).
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).
2735

28-
![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)
36+
### Example Anchor Projects Using Codama
37+
38+
[Anchor Election app](https://github.com/quiknode-labs/anchor-election-2025)
39+
40+
[Anchor Swap/Escrow app](https://github.com/quiknode-labs/you-will-build-a-solana-program)
2941

30-
## From program to Codama
42+
## Using Codama
3143

32-
There are various ways to extract information from your Solana programs in order to obtain a Codama IDL.
44+
### Creating a Codama IDL for your Solana Program
3345

34-
- **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.
35-
- **From Anchor IDLs**. 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.
46+
There are various ways to get a Codama IDL from your Solana program:
47+
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.
3649

3750
```ts
3851
import { createFromRoot } from 'codama';
@@ -42,41 +55,57 @@ There are various ways to extract information from your Solana programs in order
4255
const codama = createFromRoot(rootNodeFromAnchor(anchorIdl));
4356
```
4457

45-
- **By hand**. If your Solana program cannot be updated to use Codama macros and you don’t have an Anchor IDL, you may design your Codama IDL by hand. We may provide tools such as a Codama Playground to help with that in the future.
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.
59+
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.
61+
62+
### Using the Codama IDL
63+
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.
65+
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!
68+
69+
#### Making clients for your program
70+
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:
4672

47-
## Transforming Codama
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._
4877

49-
Once you have your Codama IDL, you may use visitors to transform it. This can be useful when the Codama IDL was obtained from another source that may not contain some necessary information. Here is an example using two provided visitors that adjusts the accounts and instructions on the program.
78+
Here's an example of how to generate JavaScript and Rust client code for your program.
5079

5180
```ts
52-
import { updateAccountsVisitor, updateInstructionsVisitor } from 'codama';
81+
import { renderJavaScriptVisitor, renderRustVisitor } from '@codama/renderers';
5382
54-
codama.update(updateAccountsVisitor({ ... }));
55-
codama.update(updateInstructionsVisitor({ ... }));
83+
codama.accept(renderJavaScriptVisitor('clients/js/src/generated', { ... }));
84+
codama.accept(renderRustVisitor('clients/rust/src/generated', { ... }));
5685
```
5786

58-
## From Codama to utility
87+
### Registering your Codama IDL onchain (_Coming soon_)
5988

60-
Now that you have the perfect Codama IDL for your Solana program, you can benefit from all the visitors and tools that provide utility such as rendering client code or registering your IDL on-chain so explorers can dynamically display relevant information for your program.
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.
6190

62-
_Note that some features such as rendering CLIs are not yet available. However, because the Codama IDL is designed as a tree of nodes, these features are only a visitor away from being ready. Feel free to reach out if you’d like to contribute to this Codama ecosystem._
91+
#### Creating CLIs (_Not yet available_)
6392

64-
- **Rendering client code**. Want people to start interacting with your Solana program? You can use special visitors that go through your Codama IDL and generate client code that you can then publish for your end-users. Currently, we have the following renderers available:
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.
6594

66-
- `@codama/renderers-js`: Renders a JavaScript client compatible with [`@solana/kit`](https://github.com/anza-xyz/kit).
67-
- `@codama/renderers-js-umi`: Renders a JavaScript client compatible with Metaplex’s [Umi](https://github.com/metaplex-foundation/umi) framework.
68-
- `@codama/renderers-rust`: Renders a Rust client that removes the need for publishing the program crate and offers a better developer experience.
69-
- _And more to come._
95+
#### Creating documentation (_Not yet available_)
7096

71-
Here’s an example of how to generate JavaScript and Rust client code for your program.
97+
Similarly to CLIs, we may easily generate documentation in various formats from the information held by our Codama IDL.
7298

73-
```ts
74-
import { renderJavaScriptVisitor, renderRustVisitor } from '@codama/renderers';
99+
## Codama Architecture
75100

76-
codama.accept(renderJavaScriptVisitor('clients/js/src/generated', { ... }));
77-
codama.accept(renderRustVisitor('clients/rust/src/generated', { ... }));
78-
```
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).
102+
103+
![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)
104+
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).
106+
107+
![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)
108+
109+
## Other Resources
79110

80-
- **Registering your Codama IDL on-chain** (_Coming soon_). Perhaps the biggest benefit of having a Codama IDL from your program is that you can share it on-chain 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 they depend on, filter out the accounts and instructions they don’t need and generate a bespoke client for their app that only contains the functions the app needs.
81-
- **Rendering 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.
82-
- **Rendering documentation** (_Not yet available_). Similarly to CLIs, we may easily generate documentation in various formats from the information held by our Codama IDL.
111+
['Codama' tag on Solana Stack Exchange](https://solana.stackexchange.com/questions/tagged/codama)

0 commit comments

Comments
 (0)