아키텍처

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에는 트랜잭션과 인스트럭션을 검증하는 로직이 있습니다. 또한 수수료 지불자 정책(fee-payer-policy) 안전 속성 테스트는 게이트가 적용된 프로그램당 파일 하나씩 validator/transaction_validator/fee_payer_policy_props/ 아래에 있습니다.

알아 두면 좋은 관례

기본 검증. [validation.fee_payer_policy] 아래의 모든 플래그는 기본값이 false이며, 정책 구조체에는 #[serde(default)]가 붙어 있습니다. 이 조합은 의도적인 것입니다. 새로 게이트가 적용된 인스트럭션을 추가해도 기존 운영자의 설정이 깨져서는 안 되며, 우발적인 허용이 아니라 거부로 처리되어야 합니다. 플래그를 추가할 때도 두 가지를 모두 유지하세요.

원본이 아닌 해석된 트랜잭션을 검증하세요. 원본 VersionedTransaction은 정적 계정 키만 노출하므로, 이를 바탕으로 V0 트랜잭션을 검증하거나 요금을 산정하면 조회 테이블 계정이 조용히 누락되어 요금이 과소 청구됩니다. 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을 통해 연결되어 있습니다. 명령어를 직접 재구성하지 말고 해당 파일을 읽어 보세요.