Architektura

Kora to workspace w Rust składający się z trzech crate'ów:

kora-lib zawiera główną logikę oraz serwer RPC,
kora-cli buduje plik binarny kora, uruchamiany przez operatorów, a
kora-deploy to wyspecjalizowane narzędzie do wdrażania programów, wersjonowane osobno. Wszystko poniżej znajduje się w crates/lib/src, chyba że zaznaczono inaczej.

Cykl życia żądania

Poniższy diagram przedstawia ogólny przepływ transakcji przez Kora. Zrozumienie ścieżki wywołań jest ważne przy konfigurowaniu węzła Kora i dodawaniu nowych funkcji.

Gdzie znajduje się każdy etap

Etap na diagramie	Źródło	Punkt wejścia
Brama (Gateway)	`rpc_server/server.rs`	`run_rpc_server`
Dyspozytor (Dispatch)	`rpc_server/rpc.rs`	`KoraRpc`
Logika poszczególnych metod	`rpc_server/method/`	jeden plik na każdą metodę JSON-RPC
Walidacja	`validator/transaction_validator.rs`	`TransactionValidator`
Wtyczki	`plugin/mod.rs`	`TransactionPluginRunner`
Podpisywanie	`signer/`	oparte na crate'cie `solana-keychain`

Warto znać jeszcze dwa pliki: config.rs definiuje cały schemat kora.toml, a state.rs przechowuje zdeserializowaną konfigurację w stanie globalnym procesu.

rpc.rs to cienka warstwa dyspozytora, z jedną metodą na każdy endpoint JSON-RPC, i najszybszy sposób, aby zobaczyć całe API. Logika każdej metody znajduje się w osobnym pliku w katalogu rpc_server/method/. Przeczytaj sign_transaction.rs od początku do końca; pozostałe metody podpisywania są jego wariacjami.

Przegląd walidatora

transaction_validator.rs i transaction/instruction_util.rs zawierają logikę walidacji transakcji i instrukcji. Dodatkowo są tu testy właściwości bezpieczeństwa fee-payer-policy, które znajdują się w osobnym pliku dla każdego objętego bramką programu w validator/transaction_validator/fee_payer_policy_props/.

Konwencje, które warto znać

Domyślna walidacja. Każda flaga w sekcji [validation.fee_payer_policy] domyślnie ma wartość false, a struktury polityki mają atrybut #[serde(default)]. To zestawienie jest celowe: dodanie nowej instrukcji objętej bramką nie może zepsuć istniejącej konfiguracji operatora i musi skutkować odmową, a nie przypadkowym zezwoleniem. Zachowaj oba te założenia, dodając flagę.

Waliduj przetworzoną transakcję, nigdy surową. Surowa VersionedTransaction udostępnia tylko statyczne klucze kont, więc walidacja lub wycena transakcji V0 na jej podstawie po cichu pomija konta z tabel wyszukiwania (lookup tables) i pobiera zbyt niską opłatę. VersionedTransactionResolved::from_transaction rozwiązuje te adresy z góry, dlatego każdy kolejny etap przyjmuje typ rozwiązany (resolved).

Dodawanie wtyczki transakcji

Wtyczki implementują trait TransactionPlugin z plugin/mod.rs. Ma on dwie metody: validate jest uruchamiana dla każdej transakcji podczas przepływów podpisywania, a validate_config jest uruchamiana raz przy starcie i zwraca operatorowi błędy oraz ostrzeżenia. PluginExecutionContext informuje wtyczkę, która z czterech metod podpisywania ją wywołała.

TransactionPluginRunner::from_config dopasowuje wartość TransactionPluginType, zdefiniowaną w config.rs. Nowa wbudowana wtyczka to nowy wariant w tym miejscu oraz nowe ramię match w runnerze. Dwie wtyczki dostępne obecnie to gas_swap i deploy_authority.

Testowanie

Kora przechowuje konfigurację w stanie globalnym procesu, więc tests/ deklaruje jeden cel [[test]] na fazę, a każdy cel uruchamia własny wbudowany surfnet oraz węzeł Kora, zainicjowane od zera. Jedna konfiguracja na plik binarny: nowa faza wymaga nowego celu, a nie nowego modułu w istniejącym.

cargo test -p tests --test <target>

Wszystko inne jest powiązane przez justfile. Przeczytaj go, zamiast odtwarzać polecenia ręcznie.