> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kimia.live/llms.txt
> Use this file to discover all available pages before exploring further.

# Regenerating the Codama Clients

> How the in-repo TS clients are generated and how to customize them.

Kimia uses [Codama](https://github.com/codama-idl/codama) to turn Anchor IDLs
into tree-shakeable, type-safe `@solana/kit` clients. The output is committed
to `frontend/app/generated/<program>/`; Codama is only re-run when a program
changes. Nothing is published to npm — if you want the TS client in your own
package, copy the folder or run Codama yourself.

## The pipeline

```
anchor build
   └→ target/idl/<program>.json          (Anchor IDL v1)
         └→ codama.<program>.json        (config pins IDL path + output dir)
               └→ codama-renderers-js    (renders TS)
                     └→ app/generated/<program>/
```

## Config format

```json theme={null}
{
  "idl": "../Perp-engine/target/idl/kimia_perp.json",
  "outDir": "./app/generated/perp",
  "programName": "kimiaPerp"
}
```

* `idl`: Path to Anchor's output IDL.
* `outDir`: Where the generated TS lands.
* `programName`: camelCased; drives symbol naming.

## What gets generated

For each account, instruction, type, error, and event in the IDL:

| IDL item                    | Generated TS                                                                                   |
| --------------------------- | ---------------------------------------------------------------------------------------------- |
| `Account "Market"`          | `accounts/market.ts`, `fetchMarket`, `getMarketCodec`, `getMarketSize`, `MARKET_DISCRIMINATOR` |
| `Instruction "place_order"` | `instructions/placeOrder.ts`, `getPlaceOrderInstruction`, `getPlaceOrderInstructionDataCodec`  |
| `Type "Direction"`          | `types/direction.ts`, enum-codec pair                                                          |
| `Error "StaleOracle"`       | `errors/index.ts`, `KIMIA_PERP_ERROR__STALE_ORACLE` + message map                              |

## Typed errors

Every program's `errors/index.ts` exports:

* A numeric enum matching Anchor's error codes.
* A message map for user-facing strings.
* A helper `is<ProgramName>Error(error, code)` for switch-style matching.

Example:

```ts theme={null}
import {
  KIMIA_PERP_ERROR__STALE_ORACLE,
  isKimiaPerpError,
} from '@/app/generated/perp/errors';

try {
  await sendTransaction([ix]);
} catch (err) {
  if (isKimiaPerpError(err, KIMIA_PERP_ERROR__STALE_ORACLE)) {
    showToast('Price feed is stale — retrying');
  } else {
    throw err;
  }
}
```

## PDA helpers

Generated from the Anchor `#[account(seeds = [...])]` constraint:

```ts theme={null}
import { findUserAccountPda } from '@/app/generated/perp/pdas';

const [userAccount] = await findUserAccountPda({
  authority: wallet.address,
});
```

Seeds that reference other accounts (e.g. `["market", market_index_le]`) are
supported via direct parameter objects.

## Re-running generation

A single script runs all the program configs:

```bash theme={null}
cd frontend
npm run codama:all
```

Individual scripts exist for iterative program dev:

```bash theme={null}
npm run codama:perp
npm run codama:delta
npm run codama:split
npm run codama:amm
npm run codama:intent
npm run codama:kusd
```

## Using the output outside this repo

Codama output has zero framework dependencies. Copy
`frontend/app/generated/<program>/` into any TS project; all it imports is
`@solana/kit`. There is no official npm package — the in-repo copy is the
source of truth.