Nhật ký thay đổi

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.

​

Chưa phát hành — CLMM: limit order, phí một chiều, phí động

Bản phát hành CLMM tiếp theo bổ sung ba khả năng cấp pool. Các tính năng này được bật tùy chọn khi tạo pool và tương thích ngược với các pool và vị thế hiện có.

​

Tóm tắt dành cho tích hợp viên

• Limit order nay là một primitive hạng nhất trong CLMM. LP có thể mở một lệnh single-tick trên pool có hỗ trợ; lệnh được khớp theo thứ tự FIFO khi một swap vượt qua tick đó, và một keeper ngoài chuỗi (limit_order_admin) có thể thanh toán đầu ra đã khớp mà không cần chủ sở hữu trực tuyến. Bảy phương thức SDK mới (openLimitOrder, increaseLimitOrder, decreaseLimitOrder, settleLimitOrder, closeLimitOrder, closeAllLimitOrder, settleAllLimitOrder) và ba endpoint Temp API mới dưới /limit-order/ (lệnh đang hoạt động, lịch sử theo user, nhật ký sự kiện theo PDA) bao phủ toàn bộ luồng.
• Phí một chiều (CollectFeeOn) cho phép pool thu phí swap từ phía đầu vào (cũ, chế độ 0), hoặc luôn từ token_0 (chế độ 1), hoặc luôn từ token_1 (chế độ 2). Hữu ích khi một phía của cặp là token kế toán chuẩn.
• Phí động cho phép pool chọn mức phụ phí theo dõi biến động, tăng khi tick di chuyển nhanh và giảm dần theo thời gian, được hiệu chỉnh bởi DynamicFeeConfig theo từng tier và DynamicFeeInfo theo từng pool. Endpoint mới /main/clmm-dynamic-config cung cấp danh sách tier.
• Lệnh mới CreateCustomizablePool cho phép cấu hình cả ba tùy chọn tại thời điểm tạo pool. Lệnh CreatePool truyền thống vẫn hoạt động cho các pool phí mặc định, không có limit order.
• Thay đổi phá vỡ cho indexer: các bộ đếm khối lượng theo chiều (swap_in_amount_token_{0,1}, swap_out_amount_token_{0,1}) và bộ đếm phí trọn đời (total_fees_token_{0,1}, total_fees_claimed_token_{0,1}) trong PoolState đã được chuyển vào padding để nhường chỗ cho fee_on và dynamic_fee_info. Các indexer đọc trực tiếp những trường đó phải chuyển sang vòng Observation on-chain hoặc API.

​

Tại sao điều này quan trọng (với trader, LP và tích hợp viên)

• Trader nhận được báo giá chính xác hơn trên các cặp long-tail và cặp theo sự kiện: phí động cho phép pool hấp thụ phụ phí biến động từ taker mà LP không cần chủ động mở rộng phạm vi, và các bậc thang limit order làm sâu thêm thanh khoản on-chain tại các mức giá cụ thể mà không cần cam kết vốn toàn phạm vi.
• LP có thêm một chiến lược thứ ba bên cạnh phạm vi tập trung và vị thế toàn phạm vi: đặt lệnh tại giá chính xác, được khớp khi giá chạm đến, thanh toán về token báo giá. Không cần tái cân bằng chủ động cho phần đã được khớp.
• Tích hợp viên có thể mô hình hóa các pool phí động một cách xác định — thuật toán và tham số hoàn toàn nằm on-chain, các tier hiệu chỉnh có thể truy vấn được, và đường dẫn swap không thay đổi về cấu trúc (chỉ phí mỗi bước thay đổi).

​

Những thay đổi trong chương trình

​

Tài khoản mới

• DynamicFeeConfig — bản ghi hiệu chỉnh theo tier (filter period, decay period, reduction factor, dynamic-fee control, max volatility accumulator). Được tạo bởi CreateDynamicFeeConfig (admin), được tham chiếu bởi CreateCustomizablePool khi bật phí động.
• LimitOrderState — tài khoản theo từng lệnh (PDA seeds: [owner, limit_order_nonce, order_nonce]) lưu giữ thông tin pool, tick, phía, lượng đầu vào, tỷ lệ chưa khớp, phase cohort FIFO và các snapshot kế toán. Vòng đời ngầm định (filled_amount so với total_amount, cộng với sự tồn tại của tài khoản): Open → Filled → Settled → Closed.
• LimitOrderNonce — bộ đếm tăng đơn điệu theo (owner, nonce_index) cung cấp PDA seeds cho limit order. nonce_index: u8 cho phép cùng một owner phân chia lệnh thành tối đa 256 luồng nonce độc lập.

Xem Tài khoản → DynamicFeeConfig và DynamicFeeInfo và Tài khoản → LimitOrderState.

​

Cấu trúc lại PoolState

Tổng kích thước tài khoản không thay đổi. Indexer: hãy chuyển việc theo dõi khối lượng khỏi PoolState, sang vòng Observation hoặc API. Các bộ đếm đã bị loại bỏ không bị xóa về 0 trên các pool hiện có (chúng giữ nguyên giá trị cuối cùng), vì vậy đọc lại chúng sau khi nâng cấp sẽ trả về dữ liệu cũ.

​

Bổ sung trong TickState (không phá vỡ tương thích)

Bốn trường mới được thêm vào cuối TickState, thay thế một phần padding đuôi của nó:

• order_phase: u64 — bộ đếm phân biệt các cohort limit order tại tick này.
• orders_amount: u64 — tổng đầu vào được cam kết bởi tất cả lệnh đang mở tại tick này (không nhất thiết tất cả đều chưa được khớp).
• part_filled_orders_remaining: u64 — đầu vào còn lại chưa được khớp trong cohort đang được swap tiêu thụ.
• unfilled_ratio_x64: u128 — tỷ lệ Q64.64 dùng để tính phần khớp của mỗi lệnh.

Bố cục tick-array, kích thước và PDA seeds không thay đổi.

​

Lệnh mới

• CreateDynamicFeeConfig (admin) — tạo một tier DynamicFeeConfig đã hiệu chỉnh. Thẩm quyền: cùng treasury multisig với CreateAmmConfig.
• UpdateDynamicFeeConfig (admin) — cập nhật tham số của một tier hiện có.
• CreateCustomizablePool — điểm vào tạo pool cho phép cấu hình collect_fee_on, enable_dynamic_fee, và dynamic_fee_config. Cùng tồn tại với CreatePool; chúng tôi khuyến nghị dùng CreateCustomizablePool cho bất kỳ pool mới nào cần các tùy chọn mới này.
• OpenLimitOrder — mở một limit order single-tick. Tăng LimitOrderNonce, phân bổ LimitOrderState, đưa lệnh vào cohort FIFO tại tick.
• IncreaseLimitOrder / DecreaseLimitOrder — điều chỉnh phần chưa khớp của một lệnh. Trả lỗi InvalidOrderPhase nếu lệnh đã được khớp hoàn toàn.
• SettleLimitOrder — chuyển đầu ra đã khớp vào ATA của chủ sở hữu. Người gọi có thể là chủ sở hữu hoặc keeper limit_order_admin của pool.
• CloseLimitOrder — đóng một lệnh đã thanh toán hoàn toàn để lấy lại rent.

​

Thay đổi hành vi SwapV2

Đường dẫn swap không thay đổi về cấu trúc, nhưng ba điều sau đây xảy ra trong quá trình thực thi:

1. Phí động (khi được bật): DynamicFeeInfo của pool được cập nhật mỗi bước (decay → accumulate → cap), và phụ phí kết quả được cộng thêm vào phí cơ sở cho bước đó.
2. Khớp limit order (khi bước vượt qua một tick đã khởi tạo có lệnh đang mở): một phần đầu vào swap được tiêu thụ theo FIFO để khớp cohort tại tick đó, với unfilled_ratio_x64 được cập nhật nguyên tử.
3. Định tuyến phí một chiều (khi fee_on != 0): phí được lấy từ token_0 hoặc token_1 bất kể chiều swap, thay vì luôn từ phía đầu vào.

Mỗi điều trên là no-op khi pool được tạo với giá trị mặc định cũ. Xem Lệnh → SwapV2 để biết ma trận thay đổi trạng thái đã cập nhật.

​

Mã lỗi mới

Enum ErrorCode đã được đánh số lại trong bản phát hành này: năm biến thể cũ (LOK, ZeroMintAmount, InvalidLiquidity, TransactionTooOld, InvalidRewardDesiredAmount) đã bị xóa, và mười một biến thể mới được thêm vào. Do Anchor đánh số lỗi theo thứ tự enum bắt đầu từ 6000, mọi mã lỗi tại hoặc sau các vị trí đã xóa đều bị dịch chuyển — các client đã hard-code mã số cần phải ánh xạ lại. Các mã mới là:

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

Chuỗi đầy đủ và bảng dịch chuyển cho tất cả lỗi CLMM có tại Mã lỗi.

​

Những thay đổi trong SDK (@raydium-io/raydium-sdk-v2)

• Phương thức mới trên raydium.clmm: createCustomizablePool, openLimitOrder, increaseLimitOrder, decreaseLimitOrder, settleLimitOrder, settleAllLimitOrder, closeLimitOrder, closeAllLimitOrder.
• Hàm REST mới trên raydium.api: getClmmDynamicConfigs, getClmmLimitOrderConfigs.
• Kiểu mới: enum CollectFeeOn, DynamicFeeConfig, DynamicFeeInfo, LimitOrderState, LimitOrderConfig.
• Tái cấu trúc nội bộ: utils/ đã chuyển sang libraries/. Barrel export của package không thay đổi; chỉ các import sâu qua @raydium-io/raydium-sdk-v2/utils/... cần cập nhật thành …/libraries/....

Hướng dẫn TypeScript end-to-end có tại products/clmm/code-demos.

​

Những thay đổi trong API

• api-v3 — hai endpoint mới dưới /main/:
  • GET /main/clmm-dynamic-config — danh sách các tier DynamicFeeConfig.
  • GET /main/clmm-limit-order-config — cấu hình limit order theo từng pool.
• temp-api-v1 — ba endpoint mới dưới /limit-order/:
  • GET /limit-order/order/list?wallet=… — các lệnh hiện đang đặt của một ví (đang mở và được khớp một phần, được phục vụ từ Redis cache của indexer; cùng payload bao gồm cả hai phase qua totalAmount / filledAmount / pendingSettle).
  • GET /limit-order/history/order/list-by-user?wallet=… — lịch sử limit order của một ví. Bộ lọc tùy chọn: poolId, mint1, mint2, hideCancel. Phân trang bằng cursor qua nextPageId / size (tối đa 100).
  • GET /limit-order/history/event/list-by-pda?pda=… — nhật ký sự kiện theo PDA (open / increase / decrease / settle / close) cho một hoặc nhiều limit-order PDA phân cách bằng dấu phẩy. Phân trang bằng cursor qua nextPageId / size (tối đa 100).

Cả năm endpoint đều được ghi chép trong tab Tham chiếu API.

​

Phạm vi thẩm quyền

limit_order_admin là một keeper vận hành ngoài chuỗi, không phải multisig. Nó chỉ có thể gọi SettleLimitOrder và CloseLimitOrder trên các lệnh hiện có, và đầu ra của một lần settle luôn đến ATA của chủ sở hữu. Nó không thể thay đổi các trường pool, mở hoặc sửa lệnh, hay ký cho bất kỳ thứ gì khác. Xem Khóa admin và multisig → CLMM.

​

Các trang đã cập nhật

• products/clmm/overview — phần “Có gì mới” và các con trỏ bước tiếp theo đã cập nhật.
• products/clmm/accounts — ba tài khoản mới, cấu trúc lại PoolState với cảnh báo di chuyển, bổ sung TickState, các hàm PDA mới.
• products/clmm/instructions — bảy lệnh mới, phần bổ sung hành vi SwapV2, ma trận thay đổi trạng thái đã cập nhật.
• products/clmm/fees — phần phí một chiều, phần phí động với bảng tham số.
• products/clmm/math — mã giả khớp limit order, dẫn xuất phí động.
• products/clmm/code-demos — demo createCustomizablePool, hướng dẫn limit order đầy đủ, các lỗi thường gặp mới.
• algorithms/clmm-math — tham chiếu chéo đến khớp limit order và phí động trong vòng lặp swap đa tick.
• sdk-api/typescript-sdk — phần bổ sung module CLMM, ghi chú di chuyển utils/ → libraries/.
• api-reference/openapi/api-v3.yaml — hai endpoint mới với schema phản hồi.
• api-reference/openapi/temp-api-v1.yaml — ba endpoint limit order mới (/limit-order/order/list, /limit-order/history/order/list-by-user, /limit-order/history/event/list-by-pda) cùng schema yêu cầu và phản hồi.
• api-reference/api-v3/overview — ghi chú về các endpoint cấu hình CLMM mới.
• api-reference/temp-api-v1/overview — ghi chú về các endpoint active-orders, history-by-user và event-by-PDA mới.
• reference/error-codes — mười một mã lỗi CLMM mới (6040–6050) cộng với năm mã cũ đã xóa; các mã số sau các vị trí đã xóa đều bị dịch chuyển.
• security/admin-and-multisig — hàng admin DynamicFeeConfig mới và hàng keeper limit_order_admin mới, kèm giải thích về phạm vi thẩm quyền có giới hạn.

Đã xác minh đối chiếu với:

• Mã nguồn raydium-clmm.
• Mã nguồn @raydium-io/raydium-sdk-v2.
• Mã nguồn api-v3 và temp-api-v1.

​

2026-04-26 — Lần đầu phát hành

Bản phát hành công khai đầu tiên của bộ tài liệu Raydium. Đã xác minh đối chiếu với:

• Các chương trình đã triển khai trực tiếp trên Solana mainnet-beta.
• @raydium-io/raydium-sdk-v2@0.2.42-alpha.
• Tài liệu Raydium công khai và các tham chiếu on-chain đến tháng 4 năm 2026.

Từ đây trở đi, mọi nâng cấp giao thức, kiểm toán hoặc sửa đổi tài liệu đều được ghi thành một mục mới trong file này.

​

Quy ước tài liệu

• Versioning: tài liệu này dùng versioning theo lịch (YYYY-MM-DD). Mỗi lần cập nhật tạo một mục mới ở đầu file.
• Ngày xác minh: mỗi mục ghi lại thời điểm nội dung được đối chiếu lần cuối với trạng thái on-chain / API và mã nguồn chương trình. Nếu không ghi rõ, giả sử là ngày chính của mục đó.
• Thay đổi phá vỡ: được nêu bật trong hộp cảnh báo trên các trang bị ảnh hưởng và được đánh dấu trong mục bên dưới.
• Phạm vi: nhật ký thay đổi này bao gồm bộ tài liệu. Lịch sử phát triển của giao thức nằm tại introduction/history-and-milestones và là nguồn sự thật cho câu hỏi “X xảy ra trên Raydium khi nào”.

​

Sửa lỗi

Nếu bạn phát hiện lỗi trong tài liệu này, vui lòng mở một issue hoặc pull request trên kho tài liệu. Các sửa lỗi được ghi vào nhật ký thay đổi này.

​

Liên kết tham khảo

• introduction/history-and-milestones — lịch sử phát triển của giao thức.
• security/audits — lịch sử kiểm toán.
• ray/protocol-fees — phân bổ phí giao thức.
• reference/program-addresses — nguồn sự thật về Program ID.