2026-05-18 — CLMM: лимитные ордера, односторонняя комиссия, динамическая комиссия

Следующий релиз CLMM добавляет три возможности на уровне пула. Они опциональны при создании пула и обратно совместимы с существующими пулами и позициями.

​

TL;DR для интеграторов

• Лимитные ордера теперь являются первоклассными примитивами CLMM. LP могут открыть ордер на одном тике в пуле, который их поддерживает; ордер заполняется FIFO, когда своп пересекает тик, и оффчейн-хранитель (limit_order_admin) может рассчитать заполненный выход без участия владельца. Семь новых методов SDK (openLimitOrder, increaseLimitOrder, decreaseLimitOrder, settleLimitOrder, closeLimitOrder, closeAllLimitOrder, settleAllLimitOrder) и три новых эндпоинта Temp API под /limit-order/ (активные ордера, история по пользователю, журнал событий по PDA) охватывают весь процесс.
• Односторонняя комиссия (CollectFeeOn) позволяет пулу собирать комиссию своп с входной стороны (наследие, режим 0), или всегда с token_0 (режим 1), или всегда с token_1 (режим 2). Полезно, когда одна сторона пары является каноническим токеном учёта.
• Динамическая комиссия позволяет пулу включить отслеживающую волатильность надбавку, которая растёт при быстром движении тика и затухает со временем, откалибрована по DynamicFeeConfig для каждого уровня и DynamicFeeInfo для каждого пула. Новый эндпоинт /main/clmm-dynamic-config выводит список уровней.
• Новая инструкция CreateCustomizablePool предоставляет все три параметра при создании пула. Классическая CreatePool продолжает работать для пулов с комиссией по умолчанию и без лимитных ордеров.
• Критическое изменение индексатора: счётчики объёма по направлениям (swap_in_amount_token_{0,1}, swap_out_amount_token_{0,1}) и счётчики комиссии за всё время (total_fees_token_{0,1}, total_fees_claimed_token_{0,1}) на PoolState были удалены в заполнение, чтобы освободить место для fee_on и dynamic_fee_info. Индексаторы, которые читают эти поля напрямую, должны перейти на кольцо Observation в цепи или API.

​

Почему это важно (для трейдеров, LP и интеграторов)

• Трейдеры получают более узкие котировки на длинных хвостах и событийных парах: динамическая комиссия позволяет пулу поглощать надбавки волатильности от тейкера без необходимости LP активно расширять диапазоны, а лестницы лимитных ордеров углубляют ликвидность в цепи по конкретным ценам без привлечения капитала по всему диапазону.
• LP получают третью стратегию наряду с концентрированными диапазонами и полнодиапазонными позициями: припаркуйте ордера по точной цене, получите заполнение, когда цена посетит, рассчитайте в токен котировки. Активная перебалансировка не требуется для заполненной части.
• Интеграторы могут детерминированно моделировать пулы с динамической комиссией — алгоритм и параметры полностью находятся в цепи, уровни калибровки запрашиваются, и путь своп не изменяется по форме (только комиссия за шаг варьируется).

​

Что изменилось в программе

​

Новые аккаунты

• DynamicFeeConfig — запись калибровки для каждого уровня (период фильтра, период затухания, коэффициент снижения, управление динамической комиссией, максимальный накопитель волатильности). Создаётся CreateDynamicFeeConfig (администратор), на которую ссылается CreateCustomizablePool при включении динамической комиссии.
• LimitOrderState — аккаунт для каждого ордера (PDA seeds: [owner, limit_order_nonce, order_nonce]) содержащий пул, тик, сторону, входную сумму, незаполненное соотношение, фазу когорты FIFO и снимки учёта. Жизненный цикл неявный (filled_amount vs total_amount, плюс существование аккаунта): Open → Filled → Settled → Closed.
• LimitOrderNonce — монотонно возрастающий счётчик для каждого (владелец, индекс_nonce), который получает seeds PDA лимитного ордера. nonce_index: u8 позволяет одному владельцу разделить ордера на до 256 независимых потоков nonce.

См. Accounts → DynamicFeeConfig and DynamicFeeInfo и Accounts → LimitOrderState.

​

Переструктурирование PoolState

Общий размер аккаунта не изменился. Индексаторы: переключите отслеживание объёма с PoolState на кольцо Observation или API. Удалённые счётчики не обнуляются на существующих пулах (они содержат то, что они последний раз несли), поэтому повторное чтение после обновления вернёт устаревшие данные.

​

Дополнения TickState (без критических изменений)

Четыре новых поля добавлены в конец TickState, заменяя часть его хвостового заполнения:

• order_phase: u64 — счётчик, который различает когорты лимитных ордеров на этом тике.
• orders_amount: u64 — общая входная сумма, привлечённая всеми открытыми ордерами на этом тике (не все из них полностью незаполнены).
• part_filled_orders_remaining: u64 — входная сумма, всё ещё незаполненная в когорте, которая в настоящее время потребляется свопами.
• unfilled_ratio_x64: u128 — соотношение Q64.64, используемое для вычисления доли заполнения каждого ордера.

Раскладка массива тиков, размер и seeds PDA не изменяются.

​

Новые инструкции

• CreateDynamicFeeConfig (администратор) — создать откалиброванный уровень DynamicFeeConfig. Полномочия: тот же казначейский мультиподпис, что и CreateAmmConfig.
• UpdateDynamicFeeConfig (администратор) — обновить параметры существующего уровня.
• CreateCustomizablePool — точка входа создания пула, которая предоставляет collect_fee_on, enable_dynamic_fee и dynamic_fee_config. Сосуществует с CreatePool; мы рекомендуем CreateCustomizablePool для любого нового пула, которому нужны новые параметры.
• OpenLimitOrder — открыть лимитный ордер на одном тике. Увеличивает LimitOrderNonce, выделяет LimitOrderState, помещает ордер в когорту FIFO на тике.
• IncreaseLimitOrder / DecreaseLimitOrder — отрегулировать незаполненную часть ордера. Откатывается на полностью заполненном ордере с InvalidOrderPhase.
• SettleLimitOrder — перевести заполненный выход в ATA владельца. Вызывающий может быть владельцем или хранителем limit_order_admin пула.
• CloseLimitOrder — закрыть полностью рассчитанный ордер, чтобы вернуть аренду.

​

Изменения поведения SwapV2

Путь своп сам по себе не изменяется по форме, но три вещи теперь происходят на пути:

1. Динамическая комиссия (при включении): DynamicFeeInfo пула обновляется на каждом шаге (затухание → накопление → ограничение), и полученная надбавка добавляется поверх базовой комиссии для этого шага.
2. Сопоставление лимитных ордеров (когда шаг пересекает инициализированный тик, который имеет открытые ордера): часть входной суммы своп потребляется FIFO для заполнения когорты на этом тике, с unfilled_ratio_x64, обновляемым атомарно.
3. Маршрутизация односторонней комиссии (когда fee_on != 0): комиссия берётся с token_0 или token_1 независимо от направления своп, вместо того чтобы всегда браться с входной стороны.

Каждое из этих является no-op, когда пул был создан с наследуемыми значениями по умолчанию. См. Instructions → SwapV2 для обновленной матрицы изменения состояния.

​

Новые коды ошибок

Перечисление ErrorCode было перенумеровано в этом релизе: пять наследуемых вариантов (LOK, ZeroMintAmount, InvalidLiquidity, TransactionTooOld, InvalidRewardDesiredAmount) были удалены, и одиннадцать новых вариантов были добавлены. Поскольку Anchor нумерует ошибки по порядку перечисления с 6000, каждый код ошибки на или после удалённых позиций сместился — клиенты, которые жёстко кодировали числовые коды, должны переотобразить. Новые коды:

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

Полные строки и таблица смещения для всех ошибок CLMM находятся в Error codes.

​

Что изменилось в SDK (@raydium-io/raydium-sdk-v2)

• Новые методы на raydium.clmm: createCustomizablePool, openLimitOrder, increaseLimitOrder, decreaseLimitOrder, settleLimitOrder, settleAllLimitOrder, closeLimitOrder, closeAllLimitOrder.
• Новые помощники REST на raydium.api: getClmmDynamicConfigs, getClmmLimitOrderConfigs.
• Новые типы: перечисление CollectFeeOn, DynamicFeeConfig, DynamicFeeInfo, LimitOrderState, LimitOrderConfig.
• Внутренняя реорганизация: utils/ перемещён в libraries/. Бочка пакета не изменилась; только глубокие импорты под @raydium-io/raydium-sdk-v2/utils/... нужно обновить на …/libraries/....

Сквозные пошаговые руководства TypeScript находятся в products/clmm/code-demos.

​

Что изменилось в API

• api-v3 — два новых эндпоинта под /main/:
  • GET /main/clmm-dynamic-config — список уровней DynamicFeeConfig.
  • GET /main/clmm-limit-order-config — конфигурация лимитных ордеров для каждого пула.
• temp-api-v1 — три новых эндпоинта под /limit-order/:
  • GET /limit-order/order/list?wallet=… — припаркованные ордера кошелька (открытые и частично заполненные, обслуживаемые из Redis-кэша индексатора; один и тот же payload охватывает обе фазы через totalAmount / filledAmount / pendingSettle).
  • GET /limit-order/history/order/list-by-user?wallet=… — исторические лимитные ордера кошелька. Опциональные фильтры: poolId, mint1, mint2, hideCancel. Курсорная пагинация через nextPageId / size (макс 100).
  • GET /limit-order/history/event/list-by-pda?pda=… — журнал событий для каждого PDA (open / increase / decrease / settle / close) для одного или нескольких разделённых запятыми PDA лимитных ордеров. Курсорная пагинация через nextPageId / size (макс 100).

Все пять документированы на вкладке API Reference.

​

Поверхность полномочий

limit_order_admin — это оффчейн-хранитель операций, не мультиподпис. Он может только вызывать SettleLimitOrder и CloseLimitOrder на существующих ордерах, и выход рассчёта всегда попадает в ATA владельца. Он не может изменять поля пула, открывать или изменять ордера, или подписывать что-либо ещё. См. Admin keys and multisig → CLMM.

​

Обновлённые страницы

• products/clmm/overview — новый раздел “What’s new” и обновлённые указатели следующих шагов.
• products/clmm/accounts — три новых аккаунта, переструктурирование PoolState с предупреждением о миграции, дополнения TickState, новые помощники PDA.
• products/clmm/instructions — семь новых инструкций, дополнение поведения SwapV2, обновлённая матрица изменения состояния.
• products/clmm/fees — раздел односторонней комиссии, раздел динамической комиссии с таблицей параметров.
• products/clmm/math — псевдокод сопоставления лимитных ордеров, вывод динамической комиссии.
• products/clmm/code-demos — демонстрация createCustomizablePool, полное пошаговое руководство лимитных ордеров, новые подводные камни.
• algorithms/clmm-math — перекрёстная ссылка на сопоставление лимитных ордеров и динамическую комиссию в цикле многотикового своп.
• sdk-api/typescript-sdk — раздел дополнений модуля CLMM, примечание о миграции utils/ → libraries/.
• api-reference/openapi/api-v3.yaml — два новых эндпоинта со схемами ответов.
• api-reference/openapi/temp-api-v1.yaml — три новых эндпоинта лимитных ордеров (/limit-order/order/list, /limit-order/history/order/list-by-user, /limit-order/history/event/list-by-pda) с их схемами запроса и ответа.
• api-reference/api-v3/overview — примечание о новых эндпоинтах конфигурации CLMM.
• api-reference/temp-api-v1/overview — примечание о новых эндпоинтах активных ордеров, истории по пользователю и событий по PDA.
• reference/error-codes — одиннадцать новых кодов ошибок CLMM (6040–6050) плюс пять удалённых наследуемых кодов; числовые коды после точек удаления сместились.
• security/admin-and-multisig — новая строка администратора DynamicFeeConfig и строка хранителя limit_order_admin, с объяснением ограниченных полномочий.

Проверено против:

• исходного кода raydium-clmm.
• исходного кода @raydium-io/raydium-sdk-v2.
• исходного кода api-v3 и temp-api-v1.