Xây dựng, kiểm thử và tìm hiểu các hợp đồng Soroban của Stellar Trade

Giới thiệu

Stellar Trade Contracts là không gian làm việc cho các contract Soroban của Stellar Trade, một nguyên mẫu thị trường dự đoán mã nguồn mở được xây dựng trên Stellar. Các contract quy định cách XLM được đưa vào pool thị trường, cách người tham gia giảm vị thế, cũng như cách các thị trường đã được phân xử hoặc hủy phân phối khoản chi trả và hoàn tiền.

Kho lưu trữ này dành cho các nhà phát triển cần xây dựng, kiểm thử, đánh giá hoặc triển khai các contract phía sau ứng dụng. Kho lưu trữ bao gồm contract thị trường cùng các crate hỗ trợ token, giới thiệu, bảng xếp hạng và kiểm thử tích hợp.

Tìm hiểu workspace

Kho lưu trữ được tổ chức thành năm crate chính, mỗi crate đảm nhiệm một chức năng riêng:

• prediction_market: Tạo thị trường, tiếp nhận vị thế, xử lý việc giảm vị thế, xử lý các thao tác của người phân xử, tính toán khoản nhận theo tỷ lệ, xử lý hoàn tiền khi hủy, hạch toán phí, đồng thời hỗ trợ tranh chấp và quản trị.
• stellar_trade_token: Cung cấp token phần thưởng với các quyền kiểm soát của quản trị viên, các bên được ủy quyền đúc token, chức năng tạm dừng và giới hạn nguồn cung tùy chọn. Các lần triển khai mới sử dụng tên Stellar Trade và ký hiệu STRD.
• referral_registry: Đăng ký lượt giới thiệu, giới hạn độ sâu chuỗi giới thiệu và phân phối phí giới thiệu.
• leaderboard: Theo dõi điểm của người tham gia và thành tích thắng/thua, áp dụng cơ chế giảm điểm theo thời gian, đồng thời hỗ trợ việc đúc phần thưởng có ủy quyền.
• cross_contract_invariants: Kiểm thử việc hạch toán và hành vi giữa các contract thị trường, giới thiệu, bảng xếp hạng và token.

Thiết lập Rust workspace

Dự án cố định Rust 1.91.0 và target wasm32v1-none thông qua rust-toolchain.toml. Hãy cài đặt toolchain và target được kho lưu trữ chỉ định trước khi chạy các bước kiểm tra từ thư mục gốc của kho lưu trữ.

Sau khi môi trường đã sẵn sàng, chạy toàn bộ bộ kiểm thử của workspace:

cargo test --workspace --all-features

Kiểm tra định dạng để xác minh mã nguồn tuân theo các quy tắc định dạng của dự án:

cargo fmt --all -- --check

Chạy Clippy với cảnh báo được xem là lỗi để phát hiện các vấn đề về chất lượng và tính đúng đắn của mã:

cargo clippy --workspace --all-features -- -D warnings

Xây dựng contract thị trường dự đoán cho WebAssembly bằng cấu hình phát hành:

cargo build --release --target wasm32v1-none -p prediction_market

Các lệnh này tương ứng với những bước kiểm tra được workflow GitHub Actions của kho lưu trữ sử dụng. Workflow cũng xây dựng các artifact WASM và chạy các bài kiểm thử bất biến liên contract đối với những thay đổi trên nhánh mặc định và các pull request.

Theo dõi vòng đời thị trường

1. Tạo thị trường

Một người tạo được ủy quyền công bố câu hỏi, danh mục và thời điểm đóng thị trường. Việc tạo thị trường được phân quyền, vì vậy bên gọi phải đáp ứng các quy tắc ủy quyền do contract cấu hình.

2. Đặt vị thế

Người tham gia gọi place_bet để đặt cược XLM vào một trong hai phía YES hoặc NO. Contract áp dụng các khoản phí đã cấu hình và ghi nhận vị thế phát sinh cho phía mà người tham gia đã chọn.

Cơ chế giảm vị thế không phải là giao dịch bán ngang hàng, sổ lệnh hay vị thế bán khống. Đây là thao tác trên khoản tiền đã đặt được ghi nhận của người tham gia.

3. Giảm vị thế trước khi đóng

Trước khi thị trường đóng, người tham gia có thể gọi reduce_position để giảm một khoản tiền đã đặt hiện có. Contract sử dụng phía được ghi nhận trong vị thế của người tham gia và tính số tiền hoàn lại dựa trên phần vị thế bị giảm cùng các quy tắc phí được giữ lại.

Vì contract chọn phía từ vị thế hiện có của người tham gia, bên gọi không nên xem thao tác này là chuyển phía hoặc giao dịch với người tham gia khác.

4. Phân xử thị trường

Một người phân xử được ủy quyền gửi kết quả sau khi thị trường đóng. Sau đó, contract thị trường tính các khoản chi trả theo tỷ lệ cho những vị thế thắng.

Việc phân xử được phân quyền. Workspace này không cung cấp oracle tự động. Dữ liệu giá hoặc dữ liệu mạng bên ngoài không thể quyết toán thị trường trừ khi người phân xử được ủy quyền sử dụng dữ liệu đó và gửi kết quả.

5. Nhận tiền thắng hoặc hoàn tiền khi hủy

Người tham gia nhận các khoản chi trả theo tỷ lệ thông qua contract sau khi thị trường được phân xử. Thị trường bị hủy tuân theo luồng hoàn tiền riêng thay vì luồng chi trả thông thường cho vị thế thắng.

Việc lựa chọn người phân xử, tiêu chí phân xử, bằng chứng và xử lý tranh chấp là những giả định tin cậy quan trọng. Hãy xem xét các quy trình này trước khi dựa vào một thị trường đã triển khai.

Đánh giá các thuộc tính hạch toán và an toàn

Trước khi thay đổi hành vi của contract, hãy đọc ma trận bất biến. Tài liệu này liên kết các quy tắc hạch toán quan trọng với những bài kiểm thử bảo vệ chúng.

Ma trận bao quát các lĩnh vực như:

• Bảo toàn phí và cô lập phí ở cấp thị trường.
• Giới hạn đối với các khoản chi trả theo tỷ lệ.
• Hành vi khi hủy.
• Hạch toán giới thiệu.
• Theo dõi nguồn cung phần thưởng.
• Xử lý thời gian tồn tại của bộ nhớ lưu trữ.
• Các luồng tạm dừng khẩn cấp.

Nếu bạn thay đổi phí, phần thưởng, công thức chi trả hoặc thời gian tồn tại của bộ nhớ lưu trữ, hãy đồng thời cập nhật các bài kiểm thử hồi quy và kiểm thử bất biến liên quan. Crate cross_contract_invariants đặc biệt hữu ích khi thay đổi ảnh hưởng đến nhiều contract.

Sử dụng đúng các báo cáo vấn đề lịch sử

Thư mục issues/ chứa các báo cáo lịch sử về bảo mật và tính đúng đắn. Hãy đọc issues/README.md để hiểu bối cảnh của chúng.

Các báo cáo này ghi nhận những rủi ro thiết kế trước đây. Không nên xem chúng là bằng chứng cho thấy các hợp đồng đã được kiểm toán, cũng không phải là xác nhận rằng mọi vấn đề được liệt kê vẫn còn hiện hữu. Hãy sử dụng chúng làm tài liệu đầu vào cho việc rà soát, kết hợp với mã nguồn hiện tại, các bài kiểm thử và ma trận bất biến.

Chuẩn bị triển khai

Các lần triển khai trên testnet vẫn giữ nguyên ID hợp đồng và siêu dữ liệu token trong lịch sử. Một lần triển khai mới sẽ tạo các địa chỉ mới và khởi tạo STRD; lần triển khai này không di chuyển những người nắm giữ hoặc số dư hiện có.

Trước khi triển khai, hãy xác nhận tất cả các mục sau:

• Mạng đích.
• ID hợp đồng.
• Danh tính quản trị viên.
• Cài đặt phí.
• Cấu hình trình phân giải.

Không bao giờ commit khóa bí mật, cụm từ khôi phục ví, .deploy.env, kết quả triển khai hoặc các tệp danh tính cục bộ vào kho lưu trữ.

Để biết hướng dẫn phát triển frontend cục bộ và triển khai ở cấp ứng dụng, hãy tham khảo README của ứng dụng.

Mẹo phát triển nâng cao

Kiểm thử hành vi liên hợp đồng

Một thay đổi có vẻ chỉ ảnh hưởng đến một crate vẫn có thể tác động đến hoạt động giới thiệu, phần thưởng, bản ghi bảng xếp hạng hoặc nguồn cung token. Hãy chạy toàn bộ bộ kiểm thử của workspace và các bài kiểm thử bất biến liên hợp đồng thay vì chỉ dựa vào kiểm thử đơn vị của một crate.

Duy trì ranh giới quyền hạn rõ ràng

Việc tạo thị trường, phân xử, quản trị token, đúc token và các hành động nhạy cảm khác đều sử dụng cơ chế kiểm soát ủy quyền. Khi rà soát hoặc mở rộng một hợp đồng, hãy xác minh danh tính nào được phép thực hiện từng thao tác và các cơ chế tạm dừng ảnh hưởng thế nào đến hoạt động khẩn cấp.

Rà soát các thay đổi về vòng đời bộ nhớ

Việc xử lý TTL của bộ nhớ là một phần trong mô hình an toàn của dự án. Mọi thay đổi đối với cách truy cập hoặc vòng đời bộ nhớ đều cần được kiểm tra đối chiếu với ma trận bất biến và được bao phủ bằng các bài kiểm thử hồi quy.

Kiểm tra các tạo phẩm phát hành

Hãy chạy trình định dạng, Clippy, các bài kiểm thử và bản dựng WASM phát hành trước khi công bố hoặc triển khai thay đổi. Hãy xem một bản dựng cục bộ thành công là điều kiện tiên quyết cho phát triển, không phải là sự thay thế cho việc rà soát cấu hình và danh tính triển khai.

Kết luận

Stellar Trade Contracts cung cấp logic Soroban để tạo các thị trường dự đoán, ghi nhận các vị thế YES và NO, giảm mức đặt cược, phân xử kết quả, phân phối các khoản nhận theo tỷ lệ và hoàn tiền cho các thị trường bị hủy. Các crate hỗ trợ bổ sung chức năng token phần thưởng, giới thiệu, bảng xếp hạng và tích hợp.

Để làm việc an toàn với kho lưu trữ, hãy bắt đầu bằng môi trường Rust được ghim phiên bản, chạy tất cả các bước kiểm tra của workspace, tìm hiểu vòng đời thị trường và rà soát ma trận bất biến trước khi thay đổi hành vi hạch toán hoặc bộ nhớ. Trong quá trình triển khai, hãy xác minh mọi quyền hạn và cài đặt mạng, đồng thời giữ toàn bộ bí mật bên ngoài hệ thống kiểm soát phiên bản.