Generating Clients

Codama generates TypeScript and Rust clients from a program's IDL file. The generated clients include functions for calling instructions and fetching accounts, eliminating the need to manually serialize and deserialize program accounts or instruction data.

Codama is in active development and subject to change. Refer to the linked repositories in the quick reference for the latest information.

Quick Reference

CLI Commands

Command	Description
`codama init`	Generate a codama configuration file
`codama run`	Generate program clients from the configuration file

Client Generators

Package	Description
`@codama/renderers-js`	Generate `@solana/kit` compatible TypeScript clients
`@codama/renderers-rust`	Generate `solana_sdk` compatible Rust clients
`@codama/nodes-from-anchor`	Convert Anchor IDLs to Codama IDLs for generating clients

Additional Resources

Resource	Description
Codama	Codama GitHub
Codama CLI	Codama CLI GitHub
Codama Macros	Codama Macros GitHub. Generate Codama IDL from native Rust programs with Codama macros
Codama Macros Example Program	Example program demonstrating Codama macros usage

Example

This example walks through the process of generating clients from an Anchor program IDL.

Setup Project Files

To follow along, create a new directory called example and add the idl.json file and the package.json file from code snippets.

This example uses a counter program IDL. View source.

In an Anchor project, the IDL is found at target/idl/<program_name>.json after running anchor build.

Create Codama Configuration File

Codama uses a configuration file to specify where the IDL file is located, which client languages to generate, and where to output the generated code. Create this configuration by running:

Terminal

$ npx codama init

This will prompt you with questions to create a codama.json file in the root of your project and install the necessary Codama dependencies.

example output

Welcome to Codama!
✔ Where is your IDL located? (Supports Codama and Anchor IDLs). … idl.json
✔ Which script preset would you like to use? › Generate JavaScript client, Generate Rust client
✔ [js] Where should the JavaScript code be generated? … clients/js/src/generated
✔ [rust] Where is the Rust client crate located? … clients/rust
✔ [rust] Where should the Rust code be generated? … clients/rust/src/generated
▲ Your configuration requires additional dependencies.
▲ Install command: pnpm install @codama/nodes-from-anchor @codama/renderers-js @codama/renderers-rust
✔ Install dependencies? … yes
→ Installing
  ├─ @codama/nodes-from-anchor
  ├─ @codama/renderers-js
  └─ @codama/renderers-rust
✔ Dependencies installed successfully.

✔ Configuration file created.
  └─ Path: /example/codama.json

Generate Clients

Once the configuration file is created, run the generation command to generate the clients:

Terminal

$ npx codama run --all

This will generate the program clients in file paths specified in the codama configuration file.

codama.json

{
  "idl": "idl.json",
  "before": [],
  "scripts": {
    "js": {
      "from": "@codama/renderers-js",
      "args": ["clients/js/src/generated"]
    },
    "rust": {
      "from": "@codama/renderers-rust",
      "args": [
        "clients/rust/src/generated",
        {
          "crateFolder": "clients/rust",
          "formatCode": true
        }
      ]
    }
  }
}

Not all generated files are shown in corresponding code snippets.

Setup Project Files

To follow along, create a new directory called example and add the idl.json file and the package.json file from code snippets.

This example uses a counter program IDL. View source.

In an Anchor project, the IDL is found at target/idl/<program_name>.json after running anchor build.

Create Codama Configuration File

Codama uses a configuration file to specify where the IDL file is located, which client languages to generate, and where to output the generated code. Create this configuration by running:

Terminal

$ npx codama init

This will prompt you with questions to create a codama.json file in the root of your project and install the necessary Codama dependencies.

example output

Welcome to Codama!
✔ Where is your IDL located? (Supports Codama and Anchor IDLs). … idl.json
✔ Which script preset would you like to use? › Generate JavaScript client, Generate Rust client
✔ [js] Where should the JavaScript code be generated? … clients/js/src/generated
✔ [rust] Where is the Rust client crate located? … clients/rust
✔ [rust] Where should the Rust code be generated? … clients/rust/src/generated
▲ Your configuration requires additional dependencies.
▲ Install command: pnpm install @codama/nodes-from-anchor @codama/renderers-js @codama/renderers-rust
✔ Install dependencies? … yes
→ Installing
  ├─ @codama/nodes-from-anchor
  ├─ @codama/renderers-js
  └─ @codama/renderers-rust
✔ Dependencies installed successfully.

✔ Configuration file created.
  └─ Path: /example/codama.json

Generate Clients

Once the configuration file is created, run the generation command to generate the clients:

Terminal

$ npx codama run --all

This will generate the program clients in file paths specified in the codama configuration file.

codama.json

{
  "idl": "idl.json",
  "before": [],
  "scripts": {
    "js": {
      "from": "@codama/renderers-js",
      "args": ["clients/js/src/generated"]
    },
    "rust": {
      "from": "@codama/renderers-rust",
      "args": [
        "clients/rust/src/generated",
        {
          "crateFolder": "clients/rust",
          "formatCode": true
        }
      ]
    }
  }
}

Not all generated files are shown in corresponding code snippets.

idl.json

package.json

{
  "address": "8PY1q5J3Aq2z7TBDLBrVjv77mYzjXSCz6iHQaFEFw9hY",
  "metadata": {
    "name": "counter",
    "version": "0.1.0",
    "spec": "0.1.0",
    "description": "Created with Anchor"
  },
  "instructions": [
    {
      "name": "decrement",
      "discriminator": [106, 227, 168, 59, 248, 27, 150, 101],
      "accounts": [
        {
          "name": "user",
          "writable": true,
          "signer": true
        },
        {
          "name": "counter",
          "writable": true,
          "pda": {
            "seeds": [
              {
                "kind": "const",
                "value": [99, 111, 117, 110, 116, 101, 114]
              }
            ]
          }
        },
        {
          "name": "vault",
          "writable": true,
          "pda": {
            "seeds": [
              {
                "kind": "const",
                "value": [118, 97, 117, 108, 116]
              },
              {
                "kind": "account",
                "path": "user"
              }
            ]
          }
        },
        {
          "name": "system_program",
          "address": "11111111111111111111111111111111"
        }
      ],
      "args": []
    },
    {
      "name": "increment",
      "discriminator": [11, 18, 104, 9, 104, 174, 59, 33],
      "accounts": [
        {
          "name": "user",
          "writable": true,
          "signer": true
        },
        {
          "name": "counter",
          "writable": true,
          "pda": {
            "seeds": [
              {
                "kind": "const",
                "value": [99, 111, 117, 110, 116, 101, 114]
              }
            ]
          }
        },
        {
          "name": "vault",
          "writable": true,
          "pda": {
            "seeds": [
              {
                "kind": "const",
                "value": [118, 97, 117, 108, 116]
              },
              {
                "kind": "account",
                "path": "user"
              }
            ]
          }
        },
        {
          "name": "system_program",
          "address": "11111111111111111111111111111111"
        }
      ],
      "args": []
    }
  ],
  "accounts": [
    {
      "name": "Counter",
      "discriminator": [255, 176, 4, 245, 188, 253, 124, 25]
    }
  ],
  "errors": [
    {
      "code": 6000,
      "name": "UnderflowError",
      "msg": "Counter cannot be decremented below zero"
    }
  ],
  "types": [
    {
      "name": "Counter",
      "type": {
        "kind": "struct",
        "fields": [
          {
            "name": "count",
            "type": "u64"
          }
        ]
      }
    }
  ]
}

Generating Clients

Quick Reference

CLI Commands

Client Generators

Additional Resources

Example

Setup Project Files

Create Codama Configuration File

Generate Clients

Setup Project Files

Create Codama Configuration File

Generate Clients

Using the Generated Clients

Integrated Into Your Application

Standalone Packages or Crates

सामग्री तालिका