Архітектура

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. Читайте його, замість того щоб відтворювати команди вручну.