|
1 | | -# Kinobi |
| 1 | +# Codama |
2 | 2 |
|
3 | 3 | [![npm][npm-image]][npm-url] |
4 | 4 | [![npm-downloads][npm-downloads-image]][npm-url] |
5 | 5 | [![ci][ci-image]][ci-url] |
6 | 6 |
|
7 | | -[npm-downloads-image]: https://img.shields.io/npm/dm/kinobi.svg?style=flat |
8 | | -[npm-image]: https://img.shields.io/npm/v/kinobi.svg?style=flat |
9 | | -[npm-url]: https://www.npmjs.com/package/kinobi |
10 | | -[ci-image]: https://img.shields.io/github/actions/workflow/status/kinobi-so/kinobi/main.yml?logo=GitHub |
11 | | -[ci-url]: https://github.com/kinobi-so/kinobi/actions/workflows/main.yml |
| 7 | +[npm-downloads-image]: https://img.shields.io/npm/dm/codama.svg?style=flat |
| 8 | +[npm-image]: https://img.shields.io/npm/v/codama.svg?style=flat |
| 9 | +[npm-url]: https://www.npmjs.com/package/codama |
| 10 | +[ci-image]: https://img.shields.io/github/actions/workflow/status/codama-idl/codama/main.yml?logo=GitHub |
| 11 | +[ci-url]: https://github.com/codama-idl/codama/actions/workflows/main.yml |
12 | 12 |
|
13 | | -Kinobi is a tool that describes any Solana program in a powerful standardised format known as the Kinobi 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. |
| 13 | +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. |
14 | 14 |
|
15 | | - |
| 15 | + |
16 | 16 |
|
17 | 17 | ## Nodes and visitors |
18 | 18 |
|
19 | | -The Kinobi IDL is designed as a tree of nodes starting with the `RootNode` which contains a `ProgramNode` and additional data such as the Kinobi version used when the IDL was created. Kinobi provides over 60 different types of nodes that help describe just about any aspect of your Solana programs. [You can read more about the Kinobi nodes here](./packages/nodes). |
| 19 | +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). |
20 | 20 |
|
21 | | - |
| 21 | + |
22 | 22 |
|
23 | | -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 Kinobi visitors](./packages/visitors). |
| 23 | +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). |
24 | 24 |
|
25 | | - |
| 25 | + |
26 | 26 |
|
27 | | -## From program to Kinobi |
| 27 | +## From program to Codama |
28 | 28 |
|
29 | | -There are various ways to extract information from your Solana programs in order to obtain a Kinobi IDL. |
| 29 | +There are various ways to extract information from your Solana programs in order to obtain a Codama IDL. |
30 | 30 |
|
31 | | -- **Using Kinobi 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 Kinobi IDLs to be generated whenever you build your programs. |
32 | | -- **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 `@kinobi-so/nodes-from-anchor` package to convert that IDL into a Kinobi IDL as shown in the code snippet below. Note that the Anchor IDL might not offer all the information that Kinobi can hold and therefore, you may want to transform your Kinobi IDL to provide additional information. You can learn more about this in the next section. |
| 31 | +- **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. |
| 32 | +- **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. |
33 | 33 |
|
34 | 34 | ```ts |
35 | | - import { createFromRoot } from 'kinobi'; |
36 | | - import { rootNodeFromAnchor } from '@kinobi-so/nodes-from-anchor'; |
| 35 | + import { createFromRoot } from 'codama'; |
| 36 | + import { rootNodeFromAnchor } from '@codama/nodes-from-anchor'; |
37 | 37 | import anchorIdl from 'anchor-idl.json'; |
38 | 38 |
|
39 | | - const kinobi = createFromRoot(rootNodeFromAnchor(anchorIdl)); |
| 39 | + const codama = createFromRoot(rootNodeFromAnchor(anchorIdl)); |
40 | 40 | ``` |
41 | 41 |
|
42 | | -- **By hand**. If your Solana program cannot be updated to use Kinobi macros and you don’t have an Anchor IDL, you may design your Kinobi IDL by hand. We may provide tools such as a Kinobi Playground to help with that in the future. |
| 42 | +- **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. |
43 | 43 |
|
44 | | -## Transforming Kinobi |
| 44 | +## Transforming Codama |
45 | 45 |
|
46 | | -Once you have your Kinobi IDL, you may use visitors to transform it. This can be useful when the Kinobi 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. |
| 46 | +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. |
47 | 47 |
|
48 | 48 | ```ts |
49 | | -import { updateAccountsVisitor, updateInstructionsVisitor } from 'kinobi'; |
| 49 | +import { updateAccountsVisitor, updateInstructionsVisitor } from 'codama'; |
50 | 50 |
|
51 | | -kinobi.update(updateAccountsVisitor({ ... })); |
52 | | -kinobi.update(updateInstructionsVisitor({ ... })); |
| 51 | +codama.update(updateAccountsVisitor({ ... })); |
| 52 | +codama.update(updateInstructionsVisitor({ ... })); |
53 | 53 | ``` |
54 | 54 |
|
55 | | -## From Kinobi to utility |
| 55 | +## From Codama to utility |
56 | 56 |
|
57 | | -Now that you have the perfect Kinobi 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. |
| 57 | +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. |
58 | 58 |
|
59 | | -_Note that some features such as rendering CLIs are not yet available. However, because the Kinobi 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 Kinobi ecosystem._ |
| 59 | +_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._ |
60 | 60 |
|
61 | | -- **Rendering client code**. Want people to start interacting with your Solana program? You can use special visitors that go through your Kinobi IDL and generate client code that you can then publish for your end-users. Currently, we have the following renderers available: |
| 61 | +- **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: |
62 | 62 |
|
63 | | - - `@kinobi-so/renderers-js`: Renders a JavaScript client compatible with the soon-to-be-released 2.0 line of [`@solana/web3.js`](https://github.com/solana-labs/solana-web3.js). |
64 | | - - `@kinobi-so/renderers-js-umi`: Renders a JavaScript client compatible with Metaplex’s [Umi](https://github.com/metaplex-foundation/umi) framework. |
65 | | - - `@kinobi-so/renderers-rust`: Renders a Rust client that removes the need for publishing the program crate and offers a better developer experience. |
| 63 | + - `@codama/renderers-js`: Renders a JavaScript client compatible with the soon-to-be-released 2.0 line of [`@solana/web3.js`](https://github.com/solana-labs/solana-web3.js). |
| 64 | + - `@codama/renderers-js-umi`: Renders a JavaScript client compatible with Metaplex’s [Umi](https://github.com/metaplex-foundation/umi) framework. |
| 65 | + - `@codama/renderers-rust`: Renders a Rust client that removes the need for publishing the program crate and offers a better developer experience. |
66 | 66 | - _And more to come._ |
67 | 67 |
|
68 | 68 | Here’s an example of how to generate JavaScript and Rust client code for your program. |
69 | 69 |
|
70 | 70 | ```ts |
71 | | - import { renderJavaScriptVisitor, renderRustVisitor } from '@kinobi-so/renderers'; |
| 71 | + import { renderJavaScriptVisitor, renderRustVisitor } from '@codama/renderers'; |
72 | 72 |
|
73 | | - kinobi.accept(renderJavaScriptVisitor('clients/js/src/generated', { ... })); |
74 | | - kinobi.accept(renderRustVisitor('clients/rust/src/generated', { ... })); |
| 73 | + codama.accept(renderJavaScriptVisitor('clients/js/src/generated', { ... })); |
| 74 | + codama.accept(renderRustVisitor('clients/rust/src/generated', { ... })); |
75 | 75 | ``` |
76 | 76 |
|
77 | | -- **Registering your Kinobi IDL on-chain** (_Coming soon_). Perhaps the biggest benefit of having a Kinobi 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 Kinobi IDL, select the portion they are interested in and benefit from the same ecosystem of Kinobi 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. |
78 | | -- **Rendering CLIs** (_Not yet available_). Whilst not available yet, we can imagine a set of CLI commands that can be generated from our Kinobi IDL (much like our clients) so that end-users can fetch decoded accounts and send instructions directly from their terminal. |
79 | | -- **Rendering documentation** (_Not yet available_). Similarly to CLIs, we may easily generate documentation in various formats from the information held by our Kinobi IDL. |
| 77 | +- **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. |
| 78 | +- **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. |
| 79 | +- **Rendering documentation** (_Not yet available_). Similarly to CLIs, we may easily generate documentation in various formats from the information held by our Codama IDL. |
0 commit comments