Phương thức RPC getSignatureStatuses cho phép bạn truy xuất trạng thái xử lý và xác nhận của một danh sách chữ ký giao dịch. Phương thức này hữu ích để xác định liệu các giao dịch đã được mạng xử lý, xác nhận hay hoàn tất hay chưa.
Trừ khi tùy chọn searchTransactionHistory được bật, phương thức này chủ yếu truy vấn bộ nhớ đệm trạng thái gần đây trên nút RPC. Đối với các giao dịch cũ hơn, việc bật searchTransactionHistory là rất quan trọng.
Tránh xử lý theo lô để có hiệu suất tốt hơnXử lý các phương thức lưu trữ theo lô làm tăng đáng kể độ trễ. Không cho phép lô có hơn 10 yêu cầu.
Các trường hợp sử dụng phổ biến
- Xác nhận tính hoàn tất của giao dịch: Xác minh liệu một giao dịch đã gửi có đạt đến mức xác nhận mong muốn hay chưa (ví dụ:
confirmed hoặc finalized).
- Tra cứu trạng thái theo lô: Kiểm tra hiệu quả trạng thái của nhiều giao dịch cùng lúc, chẳng hạn như sau khi gửi theo lô.
- Cập nhật giao diện người dùng dựa trên trạng thái giao dịch: Hiển thị trạng thái theo thời gian thực của giao dịch cho người dùng.
- Kiểm tra lỗi: Xác định xem có giao dịch nào trong danh sách thất bại hay không và nguyên nhân thất bại.
Tham số yêu cầu
signatures (array gồm các string): (Bắt buộc) Một mảng gồm các chữ ký giao dịch được mã hóa base-58. Bạn có thể truy vấn tối đa 256 chữ ký trong một yêu cầu.
options (object, không bắt buộc): Một đối tượng cấu hình không bắt buộc có trường sau:
searchTransactionHistory (boolean, không bắt buộc): Nếu là true, nút RPC sẽ tìm kiếm các chữ ký trong toàn bộ lịch sử giao dịch. Nếu là false (mặc định), nút chỉ tìm kiếm trong bộ nhớ đệm trạng thái gần đây. Đối với các giao dịch cũ hoặc có khả năng đã bị loại bỏ, hãy đặt giá trị này thành true.
Cấu trúc phản hồi
Trường result của phản hồi JSON-RPC chứa một đối tượng có hai trường:
context (object): Một đối tượng chứa:
slot (u64): Slot mà nút RPC đã xử lý yêu cầu này.
value (array gồm các object | null): Một mảng các đối tượng trạng thái, tương ứng với thứ tự chữ ký trong yêu cầu. Mỗi phần tử có thể là:
- Một đối tượng có các trường sau nếu tìm thấy chữ ký:
slot (u64): Slot mà giao dịch được xử lý.
confirmations (number | null): Số khối đã được xác nhận kể từ khi giao dịch được xử lý. Giá trị là null nếu giao dịch đã hoàn tất (vì trạng thái hoàn tất đồng nghĩa giao dịch sẽ không bị đảo ngược, nên số lượng xác nhận cụ thể không còn quan trọng).
err (object | null): Một đối tượng lỗi nếu giao dịch thất bại (ví dụ: {"InstructionError":[0,{"Custom":1}]}), hoặc null nếu giao dịch thành công.
status (object): Một đối tượng cho biết trạng thái thực thi của giao dịch. Thường là {"Ok":null} đối với giao dịch thành công hoặc một đối tượng trình bày chi tiết lỗi đối với giao dịch thất bại.
confirmationStatus (string | null): Trạng thái xác nhận của cụm đối với giao dịch (ví dụ: processed, confirmed, finalized). Có thể là null nếu trạng thái không có trong bộ nhớ đệm và searchTransactionHistory là false.
null: Nếu không tìm thấy chữ ký trong bộ nhớ đệm trạng thái và searchTransactionHistory là false (hoặc chữ ký thực sự không tồn tại ngay cả khi tìm kiếm trong lịch sử).
Ví dụ
1. Lấy trạng thái cho danh sách chữ ký (bộ nhớ đệm gần đây)
Ví dụ này truy xuất trạng thái của hai chữ ký bằng cách sử dụng bộ nhớ đệm gần đây của nút.
2. Lấy trạng thái bằng cách tìm kiếm trong lịch sử giao dịch
Ví dụ này truy xuất trạng thái của các chữ ký và yêu cầu rõ ràng nút tìm kiếm trong lịch sử giao dịch.
Mẹo dành cho nhà phát triển
searchTransactionHistory: Rất quan trọng đối với độ tin cậy. Nếu là false (mặc định), phương thức chỉ kiểm tra một bộ nhớ đệm gần đây có giới hạn. Nếu một giao dịch đã cũ hoặc có khả năng bị loại bỏ và không có trong bộ nhớ đệm này, phương thức sẽ trả về null cho trạng thái của chữ ký đó. Luôn đặt thành true nếu cần xác nhận trạng thái của những giao dịch có thể không còn mới.
- Giới hạn chữ ký: Bạn có thể truy vấn tối đa 256 chữ ký cho mỗi lần gọi.
- Trạng thái
null: Giá trị null trong mảng value của một chữ ký nhất định có nghĩa là không tìm thấy trạng thái của chữ ký đó. Nguyên nhân có thể là chữ ký không nằm trong bộ nhớ đệm gần đây (nếu searchTransactionHistory là false), giao dịch chưa bao giờ được ghi nhận hoặc giao dịch quá cũ so với lịch sử của nút ngay cả khi sử dụng searchTransactionHistory: true.
confirmations: null: Điều này thường có nghĩa là giao dịch đã đạt trạng thái finalized. Tại thời điểm này, số lượng xác nhận cụ thể không còn quá quan trọng vì khối được xem là không thể đảo ngược.
- Xử lý lỗi: Kiểm tra trường
err trong từng đối tượng trạng thái để xác định xem giao dịch có thất bại hay không. Trường status cũng sẽ cung cấp thông tin chi tiết (ví dụ: {"Err":...}).
Sử dụng getSignatureStatuses là một cách hiệu quả để theo dõi trạng thái của nhiều giao dịch Solana. Hãy nhớ sử dụng searchTransactionHistory: true để kiểm tra trạng thái một cách đáng tin cậy.