아키텍처

Kora는 세 개의 크레이트로 구성된 Rust 워크스페이스입니다.

• kora-lib는 핵심 로직과 RPC 서버를 담고 있고,
• kora-cli는 운영자가 실행하는 kora 바이너리를 빌드하며,
• kora-deploy는 별도로 버전 관리되는 프로그램 배포 전용 도구입니다. 별도 표기가 없는 한 아래의 모든 경로는 crates/lib/src 기준입니다.

요청 라이프사이클

아래 다이어그램은 Kora를 통과하는 트랜잭션의 일반적인 흐름을 보여줍니다. 호출 경로를 이해하는 것은 Kora 노드를 구성하고 새로운 기능을 추가하는 데 중요합니다.

각 단계의 위치

알아 두어야 할 파일이 두 개 더 있습니다. config.rs는 kora.toml 스키마 전체를 정의하고, state.rs는 역직렬화된 설정을 프로세스 전역 상태로 보관합니다.

RPC 서버 읽기

rpc.rs는 JSON-RPC 엔드포인트당 메서드 하나로 이루어진 얇은 디스패치 계층으로, API 전체를 가장 빠르게 파악할 수 있는 방법입니다. 각 메서드의 로직은 rpc_server/method/ 아래 별도 파일에 있습니다. sign_transaction.rs를 처음부터 끝까지 읽어 보세요. 나머지 서명 메서드는 이를 변형한 것입니다.

검증기 읽기

transaction_validator.rs와 transaction/instruction_util.rs에는 트랜잭션과 명령어를 검증하는 로직이 있습니다. 또한 게이트된 프로그램당 파일 하나씩 validator/transaction_validator/fee_payer_policy_props/ 아래에 있는 fee-payer-policy 안전성 속성 테스트도 있습니다.

알아 두면 좋은 규칙

기본 검증. [validation.fee_payer_policy] 아래의 모든 플래그는 기본값이 false이며, 정책 구조체에는 #[serde(default)]가 붙어 있습니다. 이 조합은 의도적입니다. 새로 게이트된 명령어를 추가하더라도 기존 운영자의 설정이 깨지지 않아야 하고, 실수로 허용되는 것이 아니라 거부로 반영되어야 하기 때문입니다. 플래그를 추가할 때는 두 가지를 모두 유지하세요.

원본이 아닌, 해석(resolved)된 트랜잭션을 검증하세요. 원본 VersionedTransaction은 정적 계정 키만 노출하므로, 이를 기반으로 V0 트랜잭션을 검증하거나 가격을 산정하면 조회 테이블(lookup table) 계정이 조용히 누락되어 수수료가 과소 청구됩니다. VersionedTransactionResolved::from_transaction은 이러한 주소를 미리 해석하며, 그래서 이후의 모든 단계가 해석된 타입을 받습니다.

트랜잭션 플러그인 추가하기

플러그인은 plugin/mod.rs의 TransactionPlugin 트레이트를 구현합니다. 이 트레이트에는 두 가지 메서드가 있습니다. validate는 서명 흐름 중 트랜잭션마다 실행되고, validate_config는 시작 시 한 번 실행되어 운영자에게 오류와 경고를 반환합니다. PluginExecutionContext는 네 가지 서명 메서드 중 어떤 것이 플러그인을 호출했는지 알려줍니다.

TransactionPluginRunner::from_config는 config.rs에 정의된 TransactionPluginType에 대해 매칭을 수행합니다. 새로운 내장 플러그인을 추가하려면 해당 위치에 새 variant를 추가하고 러너에 새로운 match arm을 추가하면 됩니다. 현재 제공되는 두 플러그인은 gas_swap과 deploy_authority입니다.

테스트

Kora는 설정을 프로세스 전역 상태로 유지하므로, tests/에서는 단계마다 [[test]] 타깃을 하나씩 선언하며, 각 타깃은 처음부터 시드된 자체 임베디드 surfnet과 Kora 노드를 부팅합니다. 바이너리당 설정은 하나입니다. 새로운 단계가 필요하면 기존 타깃에 새 모듈을 추가하는 것이 아니라 새 타깃을 추가해야 합니다.

cargo test -p tests --test <target>

그 외의 모든 것은 justfile을 통해 연결되어 있습니다. 명령어를 직접 다시 구성하지 말고 해당 파일을 읽어 보세요.