2026-05-18 — CLMM: limit orders, single-sided fee, dynamic fee

Rilis CLMM berikutnya menambahkan tiga kemampuan tingkat pool. Semuanya bersifat opt-in pada saat pembuatan pool dan kompatibel ke belakang dengan pool dan posisi yang sudah ada.

​

TL;DR untuk integrator

• Limit orders kini menjadi primitif CLMM kelas satu. LP dapat membuka order single-tick pada pool yang mendukungnya; order diisi FIFO ketika swap melintasi tick, dan keeper off-chain (limit_order_admin) dapat menyelesaikan output yang terisi tanpa pemilik harus online. Tujuh metode SDK baru (openLimitOrder, increaseLimitOrder, decreaseLimitOrder, settleLimitOrder, closeLimitOrder, closeAllLimitOrder, settleAllLimitOrder) dan tiga endpoint Temp API baru di bawah /limit-order/ (active orders, per-user history, per-PDA event log) mencakup alur lengkap.
• Single-sided fee (CollectFeeOn) memungkinkan pool mengumpulkan swap fees dari sisi input (legacy, mode 0), atau selalu dari token_0 (mode 1), atau selalu dari token_1 (mode 2). Berguna ketika salah satu sisi pasangan adalah token akuntansi kanonik.
• Dynamic fee memungkinkan pool untuk opt-in ke surcharge yang melacak volatilitas yang naik dengan pergerakan tick cepat dan meluruh seiring waktu, dikalibrasi oleh DynamicFeeConfig per-tier dan DynamicFeeInfo per-pool. Endpoint /main/clmm-dynamic-config baru menampilkan daftar tier.
• Instruksi baru, CreateCustomizablePool, mengekspos ketiga kontrol pada saat pembuatan pool. CreatePool klasik terus bekerja untuk pool default-fee tanpa limit-order.
• Perubahan breaking indexer: counter volume per-arah (swap_in_amount_token_{0,1}, swap_out_amount_token_{0,1}) dan counter biaya seumur hidup (total_fees_token_{0,1}, total_fees_claimed_token_{0,1}) pada PoolState dihapus ke padding untuk membuat ruang bagi fee_on dan dynamic_fee_info. Indexer yang membaca field tersebut secara langsung harus bermigrasi ke ring Observation on-chain atau API.

​

Mengapa ini penting (untuk trader, LP, dan integrator)

• Trader mendapatkan quote yang lebih ketat pada pasangan long-tail dan event-driven: dynamic fee memungkinkan pool menyerap surcharge volatilitas dari taker tanpa LP harus secara aktif memperlebar range, dan limit-order ladder memperdalam likuiditas on-chain pada harga spesifik tanpa mengikat modal range-wide.
• LP mendapatkan strategi ketiga di samping concentrated range dan full-range position: parkir order exact-price, dapatkan filled ketika harga mengunjungi, settle ke quote token. Tidak ada rebalancing aktif yang diperlukan untuk bagian yang terisi.
• Integrator dapat memodelkan dynamic-fee pool secara deterministik — algoritma dan parameter sepenuhnya on-chain, tier kalibrasi dapat dikueri, dan jalur swap tidak berubah bentuk (hanya biaya per langkah yang bervariasi).

​

Apa yang berubah dalam program

​

Akun baru

• DynamicFeeConfig — record kalibrasi per-tier (filter period, decay period, reduction factor, dynamic-fee control, max volatility accumulator). Dibuat oleh CreateDynamicFeeConfig (admin), direferensikan oleh CreateCustomizablePool ketika dynamic fee diaktifkan.
• LimitOrderState — akun per-order (PDA seeds: [owner, limit_order_nonce, order_nonce]) yang memegang pool, tick, side, input amount, unfilled ratio, FIFO cohort phase, dan snapshot book-keeping. Lifecycle bersifat implisit (filled_amount vs total_amount, ditambah keberadaan akun): Open → Filled → Settled → Closed.
• LimitOrderNonce — counter yang secara monoton meningkat per-(owner, nonce_index) yang mendapatkan seed PDA limit-order. nonce_index: u8 memungkinkan pemilik yang sama untuk mempartisi order ke dalam hingga 256 aliran nonce independen.

Lihat Accounts → DynamicFeeConfig and DynamicFeeInfo dan Accounts → LimitOrderState.

​

Reshape PoolState

Ukuran akun total tidak berubah. Indexer: pindahkan volume-tracking dari PoolState ke ring Observation atau API. Counter yang dihapus tidak dinolkan pada pool yang ada (mereka memegang apa pun yang terakhir mereka bawa), jadi membaca ulang mereka setelah upgrade akan mengembalikan data basi.

​

Penambahan TickState (tidak ada perubahan breaking)

Empat field baru ditambahkan di akhir TickState, menggantikan beberapa padding ekornya:

• order_phase: u64 — counter yang membedakan limit-order cohort pada tick ini.
• orders_amount: u64 — total input yang berkomitmen oleh semua order terbuka pada tick ini (tidak semuanya fully unfilled).
• part_filled_orders_remaining: u64 — input yang masih unfilled dalam cohort yang saat ini dikonsumsi oleh swap.
• unfilled_ratio_x64: u128 — rasio Q64.64 yang digunakan untuk menghitung share fill setiap order.

Layout tick-array, sizing, dan PDA seed tidak berubah.

​

Instruksi baru

• CreateDynamicFeeConfig (admin) — buat tier DynamicFeeConfig yang dikalibrasi. Authority: multisig treasury yang sama dengan CreateAmmConfig.
• UpdateDynamicFeeConfig (admin) — perbarui parameter tier yang ada.
• CreateCustomizablePool — entry point pembuatan pool yang mengekspos collect_fee_on, enable_dynamic_fee, dan dynamic_fee_config. Berdampingan dengan CreatePool; kami merekomendasikan CreateCustomizablePool untuk pool baru apa pun yang memerlukan kontrol baru.
• OpenLimitOrder — buka single-tick limit order. Bump LimitOrderNonce, alokasikan LimitOrderState, slot order ke dalam FIFO cohort pada tick.
• IncreaseLimitOrder / DecreaseLimitOrder — sesuaikan bagian unfilled order. Revert pada order yang fully-filled dengan InvalidOrderPhase.
• SettleLimitOrder — sweep filled output ke ATA pemilik. Caller dapat berupa pemilik atau keeper limit_order_admin pool.
• CloseLimitOrder — tutup order yang fully-settled untuk mengklaim kembali rent.

​

Perubahan perilaku SwapV2

Jalur swap itu sendiri tidak berubah bentuk, tetapi tiga hal sekarang terjadi di sepanjang jalan:

1. Dynamic fee (ketika diaktifkan): DynamicFeeInfo pool diperbarui setiap langkah (decay → accumulate → cap), dan surcharge yang dihasilkan ditambahkan di atas biaya dasar untuk langkah itu.
2. Limit-order matching (ketika langkah melintasi initialized tick yang memiliki open order): bagian dari input swap dikonsumsi FIFO untuk mengisi cohort pada tick itu, dengan unfilled_ratio_x64 diperbarui secara atomik.
3. Single-sided fee routing (ketika fee_on != 0): biaya diambil dari token_0 atau token_1 terlepas dari arah swap, bukan selalu dari sisi input.

Masing-masing adalah no-op ketika pool dibuat dengan default legacy. Lihat Instructions → SwapV2 untuk matriks perubahan state yang diperbarui.

​

Kode kesalahan baru

Enum ErrorCode dinomori ulang dalam rilis ini: lima varian legacy (LOK, ZeroMintAmount, InvalidLiquidity, TransactionTooOld, InvalidRewardDesiredAmount) dihapus, dan sebelas varian baru ditambahkan. Karena Anchor menomori error berdasarkan urutan enum dari 6000, setiap kode kesalahan pada atau setelah posisi yang dihapus telah bergeser — klien yang hard-coded kode numerik perlu dipetakan ulang. Kode baru adalah:

• 6040 OrderAlreadyFilled
• 6041 InvalidOrderPhase
• 6042 InvalidLimitOrderAmount
• 6043 OrderPhaseSaturated
• 6044 InvalidDynamicFeeConfigParams
• 6045 InvalidFeeOn
• 6046 ZeroSqrtPrice
• 6047 ZeroLiquidity
• 6048 MissingBaseFlag
• 6049 MissingMintAccount
• 6050 MissingTokenProgram2022

String lengkap dan tabel post-shift untuk semua error CLMM ada di Error codes.

​

Apa yang berubah dalam SDK (@raydium-io/raydium-sdk-v2)

• Metode baru pada raydium.clmm: createCustomizablePool, openLimitOrder, increaseLimitOrder, decreaseLimitOrder, settleLimitOrder, settleAllLimitOrder, closeLimitOrder, closeAllLimitOrder.
• Helper REST baru pada raydium.api: getClmmDynamicConfigs, getClmmLimitOrderConfigs.
• Tipe baru: enum CollectFeeOn, DynamicFeeConfig, DynamicFeeInfo, LimitOrderState, LimitOrderConfig.
• Reorganisasi internal: utils/ dipindahkan ke libraries/. Barrel paket tidak berubah; hanya deep import di bawah @raydium-io/raydium-sdk-v2/utils/... perlu diperbarui ke …/libraries/....

Walkthrough TypeScript end-to-end tinggal di products/clmm/code-demos.

​

Apa yang berubah dalam API

• api-v3 — dua endpoint baru di bawah /main/:
  • GET /main/clmm-dynamic-config — daftar tier DynamicFeeConfig.
  • GET /main/clmm-limit-order-config — konfigurasi limit-order per-pool.
• temp-api-v1 — tiga endpoint baru di bawah /limit-order/:
  • GET /limit-order/order/list?wallet=… — order yang saat ini diparkir wallet (open dan partially-filled, disajikan dari cache Redis indexer; payload yang sama mencakup kedua fase melalui totalAmount / filledAmount / pendingSettle).
  • GET /limit-order/history/order/list-by-user?wallet=… — limit order historis wallet. Filter opsional: poolId, mint1, mint2, hideCancel. Cursor-paginated melalui nextPageId / size (max 100).
  • GET /limit-order/history/event/list-by-pda?pda=… — event log per-PDA (open / increase / decrease / settle / close) untuk satu atau lebih limit-order PDA yang dipisahkan koma. Cursor-paginated melalui nextPageId / size (max 100).

Kelima-limanya didokumentasikan dalam tab API Reference.

​

Permukaan authority

limit_order_admin adalah keeper operasional off-chain, bukan multisig. Ia hanya dapat memanggil SettleLimitOrder dan CloseLimitOrder pada order yang ada, dan output settle selalu mendarat di ATA pemilik. Ia tidak dapat mutasi field pool, membuka atau memodifikasi order, atau menandatangani apa pun yang lain. Lihat Admin keys and multisig → CLMM.

​

Halaman yang diperbarui

• products/clmm/overview — bagian “What’s new” baru dan pointer next-step yang diperbarui.
• products/clmm/accounts — tiga akun baru, reshape PoolState dengan peringatan migrasi, penambahan TickState, helper PDA baru.
• products/clmm/instructions — tujuh instruksi baru, addendum perilaku SwapV2, matriks perubahan state yang diperbarui.
• products/clmm/fees — bagian single-sided fee, bagian dynamic-fee dengan tabel parameter.
• products/clmm/math — pseudo-code limit-order matching, derivasi dynamic-fee.
• products/clmm/code-demos — demo createCustomizablePool, walkthrough limit-order lengkap, pitfall baru.
• algorithms/clmm-math — cross-reference ke limit-order matching dan dynamic fee dalam loop multi-tick swap.
• sdk-api/typescript-sdk — bagian penambahan modul CLMM, catatan migrasi utils/ → libraries/.
• api-reference/openapi/api-v3.yaml — dua endpoint baru dengan schema respons.
• api-reference/openapi/temp-api-v1.yaml — tiga endpoint limit-order baru (/limit-order/order/list, /limit-order/history/order/list-by-user, /limit-order/history/event/list-by-pda) dengan request dan response schema mereka.
• api-reference/api-v3/overview — catatan pada endpoint config CLMM baru.
• api-reference/temp-api-v1/overview — catatan pada endpoint active-orders, history-by-user, dan event-by-PDA baru.
• reference/error-codes — sebelas kode kesalahan CLMM baru (6040–6050) ditambah lima kode legacy yang dihapus; kode numerik setelah titik penghapusan telah bergeser.
• security/admin-and-multisig — baris admin DynamicFeeConfig baru dan baris keeper limit_order_admin, dengan explainer bounded-authority.

Diverifikasi terhadap:

• Source raydium-clmm.
• Source @raydium-io/raydium-sdk-v2.
• Source api-v3 dan temp-api-v1.