> ## 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이 어디 있는지, TS / Rust / Python 클라이언트를 IDL에서 재생성하는 방법, 그리고 프로토콜의 IDL 변경 정책을 안내합니다.

<Info>
  **이 페이지는 AI 자동 번역입니다. 모든 내용은 영문판을 기준으로 합니다.**

  [영문판 보기 →](/sdk-api/anchor-idl)
</Info>

## IDL이란

Solana의 Anchor 프로그램은 명령어(instruction), 계정 레이아웃, 에러 열거형, 구조체 스키마를 설명하는 **IDL**(Interface Definition Language) 파일을 발행합니다. IDL은 클라이언트 코드 생성의 정보 출처입니다 — TS SDK, Rust CPI 크레이트, 그리고 타사 클라이언트는 모두 IDL을 기반으로 생성되거나 직접 작성됩니다.

Raydium은 CPMM, CLMM, LaunchLab의 IDL을 발행합니다. AMM v4, Stable AMM, Farm (v3 / v5 / v6)은 Anchor 이전에 만들어졌거나 다른 이유로 Anchor 배포가 아닙니다 — SDK에서 계정 구조가 수동으로 유지됩니다.

## IDL 위치

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의 **on-chain IDL** 기능을 통해 배포된 프로그램에서 직접 가져올 수도 있습니다 (프로그램 발행자가 선택한 경우):

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

CPMM, CLMM, LaunchLab은 모두 on-chain 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` TS 헬퍼를 실행 시간에 사용:
```

```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();
```

대부분의 통합자는 이렇게 하지 **않습니다** — Anchor 메서드를 감싸고 모든 부수 작업 (ATA 생성, 이체 수수료 조정, 계산 예산, Token-2022 프로그램 라우팅)을 처리하는 고수준 `raydium.cpmm.swap(...)` 헬퍼를 사용합니다. 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`](/ko/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`** — Rust 바인딩의 저수준 Solana 기본 요소 (트랜잭션, 키페어, 공개키); `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`](/ko/sdk-api/python-integration)을 참조하세요.

## IDL 변경 정책

Raydium은 IDL 안정성을 위해 다음 규칙을 따릅니다:

1. **명령어 구분자는 절대 변경되지 않습니다.** 새 명령어를 추가하면 열거형 끝에 추가됩니다. 기존 구분자는 안정적으로 유지됩니다.
2. **계정 구조체 레이아웃은 덧셈식으로만 진화합니다.** 새 필드는 끝에 추가되며, on-chain 스키마의 크기 증가가 선행됩니다. 기존 필드는 오프셋을 유지합니다.
3. **에러 열거형 코드는 추가만 가능합니다.** 기존 에러 코드는 항상 같은 의미입니다.
4. **중단적 변경은 새 프로그램에서 배송됩니다.** 재설계가 필요할 때 팀은 새 프로그램 ID를 배포합니다 (예: AMM v4를 업그레이드하는 대신 새 프로그램으로 CPMM). 기존 풀은 구 프로그램에서 계속 실행되고, 새 풀은 새 프로그램으로 이동합니다.

이 정책은 재생성된 클라이언트를 하위 호환성 있게 만듭니다: 2개 버전 이전 IDL을 기반으로 생성된 클라이언트도 현재 상태를 올바르게 디코딩할 수 있습니다 (뒤따르는 추가 바이트를 패딩으로 봅니다).

## IDL이 변경되었을 때 해야 할 일

1. **SDK 업데이트.** `npm update @raydium-io/raydium-sdk-v2`.
2. Anchor 코드젠을 직접 사용하면 **클라이언트 코드를 재생성하세요**.
3. **계정 레이아웃 비교.** 새 레이아웃의 뒤따르는 필드가 유일하게 코드가 보지 못한 것입니다. 필요한지 확인하세요.
4. **구 명령어 구분자가 무효하다고 가정하지 마세요.** 규칙 1에 따라 여전히 작동합니다.
5. **mainnet으로 롤링하기 전에 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바이트 구분자를 거부합니다. 수정은 Anchor 구분자를 강제하지 않는 SDK의 원본 레이아웃 파서를 사용하는 것입니다 (`PoolInfoLayout.decode(accountData)`).

### 생성된 클라이언트에 누락된 명령어

Anchor의 TS 코드젠은 IDL 항목의 `name`이 유효한 식별자로 파싱되는 명령어에 대한 메서드만 생성합니다. Raydium의 명령어는 모두 이를 만족하지만, 불일치가 보이면 IDL 파일이 현재 SDK 릴리스에서 온 것인지 확인하세요.

## 관련 문서

* [`sdk-api/rust-cpi`](/ko/sdk-api/rust-cpi) — Rust CPI 크레이트 사용.
* [`sdk-api/python-integration`](/ko/sdk-api/python-integration) — `anchorpy`를 통한 Python.
* [`sdk-api/typescript-sdk`](/ko/sdk-api/typescript-sdk) — 고수준 TS 클라이언트.

출처:

* [Raydium IDL 저장소](https://github.com/raydium-io/raydium-idl)
* [Anchor IDL 명세](https://www.anchor-lang.com/docs/idl)