Архітектура

Kora — це робочий простір Rust із трьох крейтів:

kora-lib містить основну логіку та RPC-сервер,
kora-cli збирає бінарний файл kora, який запускають оператори, а
kora-deploy — це спеціалізований інструмент для розгортання програм із окремим версіюванням. Усе нижче розташоване в crates/lib/src, якщо не зазначено інше.

Життєвий цикл запиту

На схемі нижче показано загальний шлях транзакції через Kora. Розуміння шляху виклику важливе для налаштування вузла Kora та додавання нових функцій.

Де розташований кожен етап

Етап на схемі	Джерело	Точка входу
Шлюз	`rpc_server/server.rs`	`run_rpc_server`
Диспетчеризація	`rpc_server/rpc.rs`	`KoraRpc`
Логіка окремих методів	`rpc_server/method/`	по одному файлу на кожен метод JSON-RPC
Валідація	`validator/transaction_validator.rs`	`TransactionValidator`
Плагіни	`plugin/mod.rs`	`TransactionPluginRunner`
Підписання	`signer/`	працює на основі крейту `solana-keychain`

Ще два файли, які варто знати: config.rs визначає всю схему kora.toml, а state.rs зберігає десеріалізовану конфігурацію в глобальному стані процесу.

rpc.rs — це тонкий диспетчерський шар: один метод на кожну кінцеву точку JSON-RPC, і найшвидший спосіб побачити весь API. Логіка кожного методу міститься в окремому файлі в rpc_server/method/. Прочитайте sign_transaction.rs від початку до кінця; решта методів підписання — це його варіації.

Як читати валідатор транзакцій

transaction_validator.rs і transaction/instruction_util.rs містять логіку валіадції транзакцій та інструкцій. Окрім того, там є тести властивостей безпеки fee-payer-policy, які розміщені по одному файлу на кожну програму з обмеженим доступом у validator/transaction_validator/fee_payer_policy_props/.

Корисні домовленості

Валідація за замовчуванням. Кожен прапорець у [validation.fee_payer_policy] за замовчуванням має значення false, а структури політик мають #[serde(default)]. Це поєднання зроблене свідомо: додавання нової інструкції з обмеженим доступом не повинно ламати існуючу конфігурацію оператора, і вона має призводити до відмови, а не до випадкового дозволу. Зберігайте обидві умови, коли додаєте прапорець.

Валідуйте розв’язану транзакцію, а ніколи не необроблену. Необроблена VersionedTransaction містить лише статичні ключі акаунтів, тому валідація або розрахунок вартості V0-транзакції на її основі непомітно пропускає акаунти з таблиць пошуку і призводить до заниження плати. VersionedTransactionResolved::from_transaction розв’язує ці адреси заздалегідь, тому кожен наступний етап приймає саме розв’язаний тип.

Додавання плагіна транзакцій

Плагіни реалізують трейт TransactionPlugin у plugin/mod.rs. Він має два методи: validate виконується для кожної транзакції під час потоків підписання, а validate_config виконується один раз під час запуску й повертає оператору помилки та попередження. PluginExecutionContext повідомляє плагіну, який із чотирьох методів підписання його викликав.

TransactionPluginRunner::from_config виконує зіставлення за TransactionPluginType, визначеним у config.rs. Новий вбудований плагін — це новий варіант там плюс нова гілка match у раннері. Наразі постачаються два плагіни: gas_swap і deploy_authority.

Тестування

Kora зберігає конфігурацію в глобальному стані процесу, тому tests/ оголошує по одній цілі [[test]] на кожну фазу, і кожна ціль запускає власний вбудований surfnet разом із вузлом Kora, ініціалізованими з нуля. Одна конфігурація на бінарний файл: для нової фази потрібна нова ціль, а не новий модуль в наявній.

cargo test -p tests --test <target>

Усе інше налаштовано через justfile. Читайте його, а не відтворюйте команди вручну.