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 xây dựng tệp nhị phân kora mà các operator chạy, và
• kora-deploy là một công cụ triển khai chương trình chuyên biệt, được quản lý 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 đi qua Kora. Việc hiểu rõ đường đi của lời gọi 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 nữa 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 hiểu máy chủ RPC

rpc.rs là một lớp điều phối mỏng, mỗi phương thức tương ứng một endpoint JSON-RPC, 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 hiểu phần xác thực

transaction_validator.rs và transaction/instruction_util.rs chứa logic để xác thực giao dịch và lệnh (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, mỗi chương trình bị chặn (gated) có một tệp riêng 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ờ dưới [validation.fee_payer_policy] đều mặc định là false, và các struct chính sách mang #[serde(default)]. Việc kết hợp này là có chủ đích: thêm một lệnh mới bị chặn không được làm hỏng cấu hình hiện có của operator, và nó phải được xử lý như một sự từ chối thay vì một sự cho phép ngoài ý muốn. 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 việc xác thực hoặc tính phí cho một giao dịch V0 từ nó sẽ âm thầm bỏ qua các tài khoản trong lookup table và tính phí thiếu. VersionedTransactionResolved::from_transaction phân giải các địa chỉ đó ngay từ đầu, đó là lý do 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. Một 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 một nhánh match mới trong runner. Hai plugin hiện được cung cấp là gas_swap và deploy_authority.

Kiểm thử

Kora lưu cấu hình trong trạng thái toàn cục của tiến trình, vì vậy tests/ khai báo một mục tiêu [[test]] cho mỗi giai đoạn, và mỗi mục tiêu tự khởi động surfnet nhúng riêng cùng 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 mục tiêu mới, chứ không phải một module mới trong mục tiêu hiện có.

cargo test -p tests --test <target>

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