Kora es un workspace de Rust con tres crates:
kora-libcontiene la lógica principal y el servidor RPC,kora-clicompila el binariokoraque ejecutan los operadores, ykora-deployes una herramienta especializada de despliegue de programas, con versionado independiente. Todo lo que aparece a continuación se encuentra encrates/lib/src, salvo que se indique lo contrario.
El ciclo de vida de una solicitud
El siguiente diagrama muestra el flujo general de una transacción a través de Kora. Comprender la ruta de llamadas es importante para configurar un nodo de Kora y añadir nuevas funciones.
Dónde reside cada etapa
| Etapa en el diagrama | Código fuente | Punto de entrada |
|---|---|---|
| Gateway | rpc_server/server.rs | run_rpc_server |
| Despacho | rpc_server/rpc.rs | KoraRpc |
| Lógica por método | rpc_server/method/ | un archivo por método JSON-RPC |
| Validación | validator/transaction_validator.rs | TransactionValidator |
| Plugins | plugin/mod.rs | TransactionPluginRunner |
| Firma | signer/ | respaldada por el crate solana-keychain |
Dos archivos más que conviene conocer: config.rs define el esquema completo de kora.toml, y
state.rs almacena la configuración deserializada en un estado global del proceso.
Cómo leer el servidor RPC
rpc.rs es una capa de despacho ligera, con un método por cada endpoint JSON-RPC, y la
forma más rápida de ver toda la API. La lógica de cada método está en su propio archivo dentro de
rpc_server/method/. Lee sign_transaction.rs de principio a fin; los demás métodos de
firma son variaciones de este.
Cómo leer el validador
transaction_validator.rs y transaction/instruction_util.rs contienen la lógica para
validar transacciones e instrucciones. Además, están las pruebas de propiedades de seguridad de
la política del pagador de comisiones, que se organizan en un archivo por cada programa restringido en
validator/transaction_validator/fee_payer_policy_props/.
Convenciones que conviene conocer
Validación predeterminada. Todos los flags bajo [validation.fee_payer_policy]
tienen false como valor predeterminado, y los structs de la política llevan #[serde(default)]. Esa
combinación es deliberada: añadir una nueva instrucción restringida no debe romper la
configuración de un operador existente, y debe aplicarse como una denegación en lugar de
una autorización accidental. Conserva ambas cosas cuando añadas un flag.
Valida la transacción resuelta, nunca la original. La
VersionedTransaction original solo expone claves de cuenta estáticas, por lo que validar o
calcular el precio de una transacción V0 a partir de ella omite en silencio las cuentas de tablas de búsqueda y
cobra de menos. VersionedTransactionResolved::from_transaction resuelve esas
direcciones de antemano, y por eso todas las etapas posteriores reciben el tipo resuelto.
Cómo añadir un plugin de transacciones
Los plugins implementan el trait TransactionPlugin en plugin/mod.rs. Tiene dos
métodos: validate se ejecuta por cada transacción durante los flujos de firma, y
validate_config se ejecuta una vez al iniciar y devuelve errores y advertencias para el
operador. Un PluginExecutionContext indica al plugin cuál de los cuatro métodos de firma
lo invocó.
TransactionPluginRunner::from_config hace match sobre TransactionPluginType,
definido en config.rs. Un nuevo plugin integrado consiste en una nueva variante allí más una nueva
rama de match en el runner. Los dos plugins que se incluyen actualmente son gas_swap y
deploy_authority.
Pruebas
Kora mantiene la configuración en un estado global del proceso, por lo que tests/ declara un
target [[test]] por fase, y cada target arranca su propio surfnet embebido y su propio
nodo de Kora, inicializados desde cero. Una configuración por binario: una nueva fase necesita un nuevo
target, no un nuevo módulo dentro de uno existente.
cargo test -p tests --test <target>
Todo lo demás está conectado mediante el justfile. Léelo en lugar de
reconstruir los comandos a mano.
Is this page helpful?