이 페이지는 AI 자동 번역입니다. 모든 내용은 영문판을 기준으로 합니다.영문판 보기 →
IDL이란
Solana의 Anchor 프로그램은 명령어, 계정 레이아웃, 오류 열거형, 구조체 스키마를 설명하는 IDL(Interface Definition Language) 파일을 발행합니다. IDL은 클라이언트 코드 생성의 진실 공급원입니다. TS SDK, Rust CPI 크레이트, 그리고 제3자 클라이언트는 모두 IDL에서 생성되거나 이를 기준으로 작성됩니다. Raydium은 CPMM, CLMM, LaunchLab의 IDL을 발행합니다. AMM v4, Stable AMM, Farm (v3 / v5 / v6)은 Anchor 이전 시대이거나 Anchor로 배포되지 않으므로, 계정 구조는 SDK에서 수동으로 유지됩니다.IDL 위치
IDL은 전용 저장소에 있습니다:
IDL 파일은 저장소의 git 히스토리에 버전이 지정되어 있습니다. 바이트 단위 재현성이 필요한 경우 특정 커밋에 고정하세요.
일부 IDL은 메인넷에서 직접 가져올 수도 있습니다:
세 개의 레거시 IDL 계정은 모두 IDL 권한
2XVnob28A5Qnpcy95UVeHWNT6G8Poy3tpA3AFyAMoZDt에 의해 쓰기 가능하며, 이는 프로그램의 BPF 업그레이드 권한과 별개입니다. 따라서 IDL은 재배포 없이 새로 고칠 수 있으며, 재배포보다 뒤떨어질 수도 있습니다. 온체인 IDL을 편의 기능으로 취급하고, 배포된 바이트코드의 형태에 대한 증거로 취급하지 마세요.
TypeScript 클라이언트 재생성
Anchor의 코드젠은 IDL에서 타입이 지정된 클라이언트를 생성합니다:raydium.cpmm.swap(...) 헬퍼를 사용합니다. SDK 아래의 계층이 필요할 때만 재생성하세요.
Rust 클라이언트 재생성 (CPI 크레이트)
Raydium은 IDL이 있는 프로그램에 대해 Anchor 크레이트를 발행합니다:raydium_cp_swap과 raydium_clmm으로 참조하세요. raydium_amm_v3이라는 크레이트는 어떤 철자로도 없습니다. 브랜치가 다릅니다: raydium-cp-swap의 master는 여전히 anchor-lang 0.32.1을 고정하므로, Anchor-1.0 통합에는 chore/upgrade-anchor가 필요합니다. CLMM은 어느 쪽이든 0.32.1이므로, 두 개가 크레이트를 공유할 수 없습니다.
cpi 기능은 cpi::accounts::<Ix> 계정 구조체와 cpi::<ix>() 호출자를 노출합니다. 즉시 사용 가능한 CPI 래퍼입니다. 사용 패턴은 sdk-api/rust-cpi를 참조하세요.
새 바인딩을 생성하려면:
Python 클라이언트 재생성
공식 Raydium Python SDK는 없습니다. 제3자 생성기는 다음을 포함합니다:anchorpy— Anchor의 TypeScript 클라이언트의 Python 포트. IDL에서 타입이 지정된 메서드 빌더를 생성합니다.solders— Rust 바인딩의 저수준 Solana 기본 요소(트랜잭션, 키페어, 공개 키);anchorpy아래에서 사용됩니다.
sdk-api/python-integration을 참조하세요.
IDL 변경 정책
Raydium은 IDL 안정성을 위해 다음 규칙을 따릅니다:- 명령어 판별자는 절대 변경되지 않습니다. 새 명령어를 추가하면 열거형의 끝에 확장되고, 기존 판별자는 안정적으로 유지됩니다.
- 계정 크기는 안정적이며, 새 필드는 예약된 패딩에서 나옵니다. 모든 Raydium 상태 구조체는 생성 시 크기가 지정된 후행 패딩 영역을 포함하며, 새 필드는 패딩에서 잘려나가지 추가되지 않습니다. 따라서 계정의 바이트 길이와 모든 기존 필드의 오프셋은 고정됩니다. 그 결과 이전에 패딩으로 읽은 바이트가 의미 있게 될 수 있으며, 필드는 패딩으로 다시 폐기될 수 있습니다(2026-08-31 릴리스에서
PlatformConfig.curve_params처럼). 업그레이드 후 구조체 정의를 다시 읽으세요. 패딩이 0으로 유지된다고 가정하지 마세요. - 오류 열거형 코드는 추가 전용입니다. 기존 오류 코드는 항상 같은 의미입니다.
- 주요 변경 사항은 새 프로그램에서 제공됩니다. 재설계가 필요할 때, 팀은 새 프로그램 ID를 배포합니다(예: AMM v4를 업그레이드하는 대신 새 프로그램으로 CPMM). 이전 풀은 이전 프로그램에서 계속 실행되고, 새 풀은 새 프로그램으로 이동합니다.
IDL이 변경될 때 수행할 작업
- SDK를 업데이트하세요.
npm update @raydium-io/raydium-sdk-v2. - Anchor 코드젠을 직접 사용하는 경우 클라이언트 코드를 재생성하세요.
- 계정 레이아웃을 비교하세요. 새 레이아웃의 후행 필드는 코드가 보지 못한 유일한 것입니다. 필요한지 확인하세요.
- 이전 명령어 판별자가 유효하지 않다고 가정하지 마세요. 규칙 1에 따라 여전히 작동합니다.
- 메인넷으로 롤아웃하기 전에 devnet에 대해 통합 테스트를 다시 실행하세요.
IDL 문제 해결
”Invalid discriminator” 오류
일반적으로 IDL의 버전 N에 대해 빌드된 클라이언트가 프로그램의 배포 전 버전에만 존재했던 명령어를 호출하려고 할 때를 의미합니다. 라이브 프로그램에서 IDL을 다시 가져오세요:계정 디코딩 실패
program.account.<Name>.fetch(pubkey)가 “Invalid account discriminator”로 오류를 발생시키면, 계정이 이전 프로그램 버전에서 생성되었고 Anchor가 8바이트 판별자를 거부하고 있습니다. 해결책은 SDK의 원본 레이아웃 파서(PoolInfoLayout.decode(accountData))를 사용하는 것입니다. 이는 Anchor 판별자를 강제하지 않습니다.
생성된 클라이언트에서 누락된 명령어
Anchor의 TS 코드젠은 IDL 항목의name이 유효한 식별자로 구문 분석되는 명령어에 대해서만 메서드를 생성합니다. Raydium의 명령어는 모두 이를 만족하지만, 불일치가 보이면 IDL 파일이 현재 SDK 릴리스에서 나온 것인지 확인하세요.
포인터
sdk-api/rust-cpi— Rust CPI 크레이트 사용.sdk-api/python-integration—anchorpy를 통한 Python.sdk-api/typescript-sdk— 더 높은 수준의 TS 클라이언트.

