Kiến trúc

Kora là một Rust workspace gồm ba crate:

• kora-lib chứa logic cốt lõi và máy chủ RPC,
• kora-cli build ra tệp nhị phân kora dành cho các operator vận hành, và
• kora-deploy là một công cụ triển khai chương trình chuyên biệt, được đánh phiên bản riêng. Mọi thứ bên dưới đều nằm trong crates/lib/src, trừ khi có ghi chú khác.

Vòng đời của một yêu cầu

Sơ đồ bên dưới mô tả luồng chung của một giao dịch khi đi qua Kora. Việc hiểu rõ đường đi của lời gọi là rất quan trọng để cấu hình một node Kora và thêm tính năng mới.

Vị trí của từng giai đoạn

Còn hai tệp khác cần biết: config.rs định nghĩa toàn bộ schema của kora.toml, và state.rs lưu cấu hình đã được giải tuần tự hóa trong trạng thái toàn cục của tiến trình.

Đọc máy chủ RPC

rpc.rs là một lớp điều phối mỏng, mỗi endpoint JSON-RPC tương ứng một phương thức, và là cách nhanh nhất để nắm toàn bộ API. Logic của từng phương thức nằm trong tệp riêng dưới rpc_server/method/. Hãy đọc sign_transaction.rs từ đầu đến cuối; các phương thức ký khác đều là biến thể của nó.

Đọc bộ xác thực giao dịch

transaction_validator.rs và transaction/instruction_util.rs chứa logic để xác thực giao dịch và instruction. Ngoài ra còn có các bài kiểm thử thuộc tính an toàn của fee-payer-policy, được tổ chức theo mỗi chương trình bị chặn một tệp, nằm trong validator/transaction_validator/fee_payer_policy_props/.

Các quy ước đáng lưu ý

Xác thực mặc định. Mọi cờ trong [validation.fee_payer_policy] đều mặc định là false, và các struct chính sách mang thuộc tính #[serde(default)]. Sự kết hợp này là có chủ đích: việc thêm một instruction mới bị chặn không được làm hỏng cấu hình của operator hiện có, và nó phải bị từ chối thay vì vô tình được cho phép. Hãy giữ nguyên cả hai khi bạn thêm một cờ.

Hãy xác thực giao dịch đã được phân giải, đừng bao giờ xác thực giao dịch thô. VersionedTransaction thô chỉ cung cấp các khóa tài khoản tĩnh, nên nếu xác thực hoặc tính phí một giao dịch V0 từ nó thì các tài khoản trong lookup table sẽ bị bỏ qua âm thầm và phí bị tính thiếu. VersionedTransactionResolved::from_transaction phân giải các địa chỉ đó ngay từ đầu, vì vậy mọi giai đoạn phía sau đều nhận kiểu đã phân giải.

Thêm một plugin giao dịch

Plugin triển khai trait TransactionPlugin trong plugin/mod.rs. Trait này có hai phương thức: validate chạy cho mỗi giao dịch trong các luồng ký, và validate_config chạy một lần khi khởi động và trả về lỗi cùng cảnh báo cho operator. PluginExecutionContext cho plugin biết phương thức nào trong bốn phương thức ký đã gọi nó.

TransactionPluginRunner::from_config khớp theo TransactionPluginType, được định nghĩa trong config.rs. Một plugin tích hợp sẵn mới là một variant mới ở đó cộng với một nhánh match mới trong runner. Hai plugin hiện có là gas_swap và deploy_authority.

Kiểm thử

Kora giữ cấu hình trong trạng thái toàn cục của tiến trình, nên tests/ khai báo mỗi giai đoạn một target [[test]], và mỗi target tự khởi chạy surfnet nhúng riêng cùng một node Kora, được khởi tạo từ đầu. Mỗi tệp nhị phân một cấu hình: một giai đoạn mới cần một target mới, chứ không phải một module mới trong target hiện có.

cargo test -p tests --test <target>

Mọi thứ còn lại được kết nối qua justfile. Hãy đọc tệp đó thay vì tự dựng lại các lệnh bằng tay.