Architektura

Kora to workspace Rusta złożony z trzech crate'ów:

kora-lib zawiera główną logikę oraz serwer RPC,
kora-cli buduje binarkę kora, którą uruchamiają operatorzy, 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 Korę. Zrozumienie ścieżki wywołań jest ważne przy konfiguracji węzła Kora oraz 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`
Dyspozycja (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 dyspozycji, z jedną metodą na każdy endpoint JSON-RPC, i najszybszy sposób, by zobaczyć całe API. Logika każdej metody znajduje się w osobnym pliku w 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 znajdują się tu testy właściwości bezpieczeństwa polityki płatnika opłat (fee payer), które mieszczą się w osobnych plikach – po jednym na każdy objęty kontrolą program – w katalogu 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 polityk mają atrybut #[serde(default)]. To połączenie jest celowe: dodanie nowej objętej kontrolą instrukcji nie może zepsuć istniejącej konfiguracji operatora i musi skutkować odmową, a nie przypadkowym zezwoleniem. Zachowaj oba te elementy, dodając nową flagę.

Waliduj transakcję po rozwiązaniu adresów, nigdy surową. Surowa VersionedTransaction udostępnia wyłącznie statyczne klucze kont, więc walidacja lub wycena transakcji V0 na jej podstawie po cichu pomija konta z tablic wyszukiwania (lookup table) i pobiera zbyt niską opłatę. VersionedTransactionResolved::from_transaction rozwiązuje te adresy na samym początku, dlatego każdy kolejny etap przyjmuje już typ po rozwiązaniu adresów.

Dodawanie wtyczki transakcji

Wtyczki implementują trait TransactionPlugin z plugin/mod.rs. Ma on dwie metody: validate uruchamiana dla każdej transakcji w trakcie przepływów podpisywania oraz validate_config uruchamiana raz przy starcie, która zwraca operatorowi błędy i ostrzeżenia. Obiekt 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, dlatego tests/ deklaruje jeden target [[test]] na każdą fazę, a każdy target uruchamia własny wbudowany surfnet oraz węzeł Kora, zainicjowane od zera. Jedna konfiguracja na binarkę: nowa faza wymaga nowego targetu, a nie nowego modułu w istniejącym.

cargo test -p tests --test <target>

Cała reszta jest podpięta przez justfile. Przeczytaj go, zamiast odtwarzać polecenia ręcznie.