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

# Anchor IDL

> 查找各个 Raydium 程序的 IDL，以及从 IDL 重新生成 TypeScript、Rust 和 Python 客户端的方法，还有协议的 IDL 变更政策。

<Info>
  **本页内容由 AI 自动翻译，所有内容以英文版本为准。**

  [查看英文版 →](/sdk-api/anchor-idl)
</Info>

## IDL 是什么

Solana 上的 Anchor 程序发布一个 **IDL**（接口定义语言）文件，其中描述了指令、账户布局、错误枚举和结构体模式。IDL 是客户端代码生成的权威来源——TypeScript SDK、Rust CPI 库和第三方客户端都是基于它生成的（或针对它手写的）。

Raydium 为 CPMM、CLMM 和 LaunchLab 发布 IDL。AMM v4、Stable AMM 和 Farm（v3/v5/v6）都早于 Anchor 时代或其他原因不使用 Anchor 发布——它们的账户结构在 SDK 中手工维护。

## 在哪里找到它们

IDL 存放在专门的仓库中：

```
https://github.com/raydium-io/raydium-idl
```

具体文件如下：

| 程序         | IDL 文件                                                                                                                                                          |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CPMM       | [`raydium_cpmm/raydium_cp_swap.json`](https://github.com/raydium-io/raydium-idl/blob/master/raydium_cpmm/raydium_cp_swap.json)                                  |
| CLMM       | [`raydium_clmm/raydium_clmm.json`](https://github.com/raydium-io/raydium-idl/blob/master/raydium_clmm/raydium_clmm.json)                                        |
| LaunchLab  | [`raydium_launchpad/raydium_launchpad.json`](https://github.com/raydium-io/raydium-idl/blob/master/raydium_launchpad/raydium_launchpad.json)                    |
| AMM v4     | 无官方 IDL——参考 [`raydium-sdk-V2/src/raydium/liquidity/layout.ts`](https://github.com/raydium-io/raydium-sdk-V2/blob/master/src/raydium/liquidity/layout.ts) 中的手写布局 |
| Stable AMM | 无官方 IDL——布局在 SDK 中                                                                                                                                              |
| Farm       | 无官方 IDL——布局在 SDK 中                                                                                                                                              |

IDL 文件在仓库的 git 历史中有版本控制；如果你需要字节级别的可重现性，可以固定到特定的提交。

IDL 也可以通过 Anchor 的**链上 IDL** 功能从已部署的程序直接拉取（如果程序发布者选择了这个选项）：

```bash theme={null}
anchor idl fetch <PROGRAM_ID> --provider.cluster mainnet
```

CPMM、CLMM 和 LaunchLab 都有链上 IDL。AMM v4、Stable AMM 和 Farm 没有（这些是 Anchor 前时代的程序）。

## 重新生成 TypeScript 客户端

Anchor 的代码生成工具从 IDL 生成类型化客户端：

```bash theme={null}
# 使用 anchor CLI
anchor build
anchor idl parse \
  --file target/idl/cpmm.json \
  --out target/types/cpmm.ts

# 或在运行时使用 `@coral-xyz/anchor` TypeScript 辅助工具：
```

```ts theme={null}
import { Program, AnchorProvider } from "@coral-xyz/anchor";
// 从 raydium-idl 仓库拉取 IDL（或将其集成到你的项目中）。
import cpmmIdl from "./idls/raydium_cp_swap.json";

const provider = new AnchorProvider(connection, wallet, {});
const program  = new Program(cpmmIdl as any, CPMM_PROGRAM_ID, provider);

// 自动生成的类型化方法构造器：
await program.methods
  .swapBaseInput(new BN(amountIn), new BN(minAmountOut))
  .accounts({ ... })
  .rpc();
```

大多数集成者**不会**这样做——他们使用更高层级的 `raydium.cpmm.swap(...)` 辅助方法，该方法包装了 Anchor 方法以及所有的簿记工作（ATA 创建、转账费用调整、计算预算、Token-2022 程序路由）。只在你需要 SDK 下层的时候才重新生成。

## 重新生成 Rust 客户端（CPI 库）

Raydium 为拥有 IDL 的程序发布 Anchor 库：

```toml theme={null}
# Cargo.toml
[dependencies]
raydium_cp_swap = { git = "https://github.com/raydium-io/raydium-cp-swap", branch = "master", features = ["cpi"] }
raydium_amm_v3 = { git = "https://github.com/raydium-io/raydium-clmm",    branch = "master", features = ["cpi"] }
```

`cpi` 特性暴露 `cpi::accounts::<Ix>` 账户结构体和 `cpi::<ix>()` 调用器——即时可用的 CPI 包装器。参阅 [`sdk-api/rust-cpi`](/zh/sdk-api/rust-cpi) 了解使用模式。

如果你更希望生成全新的绑定：

```bash theme={null}
# 从 IDL 使用 anchor-client
anchor idl parse \
  --file raydium_cpmm/raydium_cp_swap.json \
  --out src/generated/cpmm_bindings.rs
```

## 重新生成 Python 客户端

没有官方的 Raydium Python SDK。第三方生成器包括：

* **`anchorpy`** — `@coral-xyz/anchor` 的 Python 移植版。从 IDL 生成类型化方法构造器。
* **`solders`** — 低级别的 Solana 原语（交易、密钥对、公钥）的 Rust 绑定；在 `anchorpy` 下层使用。

```bash theme={null}
pip install anchorpy solders solana
```

```python theme={null}
from anchorpy import Program, Provider
from solana.rpc.async_api import AsyncClient
from pathlib import Path
import json

idl = json.loads(Path("cpmm.json").read_text())
provider = Provider(AsyncClient("https://api.mainnet-beta.solana.com"), wallet)
program  = Program(idl, CPMM_PROGRAM_ID, provider)

await program.rpc["swap_base_input"](amount_in, min_amount_out, ctx=Context(accounts={...}))
```

参阅 [`sdk-api/python-integration`](/zh/sdk-api/python-integration) 了解更完整的指南。

## IDL 变更政策

Raydium 遵循以下 IDL 稳定性规则：

1. **指令判别器永远不会改变。** 添加新指令时是在枚举末尾扩展；现有的判别器保持稳定。
2. **账户结构布局仅以附加方式演变。** 新字段放在末尾，前面有链上模式中的大小增量。现有字段保持其偏移量。
3. **错误枚举代码仅限追加。** 现有的错误代码始终表示相同的含义。
4. **破坏性变更在新程序中发布。** 当需要重新设计时，团队部署新的程序 ID（例如，CPMM 作为全新程序而不是升级 AMM v4）。旧池继续在旧程序上运行；新池转向新程序。

这个政策使重新生成的客户端向后兼容：针对两个版本之前的 IDL 生成的客户端仍然能正确解码当前状态（它将额外的尾部字节视为填充）。

## IDL 变更时该怎么做

1. **更新 SDK。** `npm update @raydium-io/raydium-sdk-v2`。
2. **重新生成你的客户端代码**（如果你直接使用 Anchor 代码生成）。
3. **比对账户布局。** 新布局的尾部字段是你的代码尚未见过的唯一内容；确认你是否需要它们。
4. **不要假设旧的指令判别器无效。** 根据规则 1，它们仍然有效。
5. **在向主网推送前，在 devnet 上重新运行集成测试**。

## IDL 故障排除

### "Invalid discriminator"（无效判别器）错误

通常表示针对 IDL 版本 N 构建的客户端正在尝试调用仅在程序的部署前版本中存在的指令。从实时程序重新拉取 IDL：

```bash theme={null}
anchor idl fetch <PROGRAM_ID>
```

### 账户解码失败

如果 `program.account.<Name>.fetch(pubkey)` 抛出"Invalid account discriminator"错误，该账户是由先前的程序版本创建的，Anchor 拒绝了其 8 字节判别器。解决方案是使用 SDK 中的原始布局解析器（`PoolInfoLayout.decode(accountData)`），它不强制执行 Anchor 判别器。

### 生成的客户端中缺少指令

Anchor 的 TypeScript 代码生成只为 IDL 条目具有可解析为有效标识符的 `name` 的指令生成方法。Raydium 的所有指令都满足这一点，但如果你看到不匹配，检查 IDL 文件是否来自当前 SDK 版本。

## 更多资源

* [`sdk-api/rust-cpi`](/zh/sdk-api/rust-cpi) — 使用 Rust CPI 库。
* [`sdk-api/python-integration`](/zh/sdk-api/python-integration) — 通过 `anchorpy` 使用 Python。
* [`sdk-api/typescript-sdk`](/zh/sdk-api/typescript-sdk) — 更高层级的 TypeScript 客户端。

来源：

* [Raydium IDL 仓库](https://github.com/raydium-io/raydium-idl)
* [Anchor IDL 规范](https://www.anchor-lang.com/docs/idl)