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 para el 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 la solicitud
El siguiente diagrama muestra el flujo general de una transacción a través de Kora. Comprender la ruta de las llamadas es importante para configurar un nodo de Kora y añadir nuevas funcionalidades.
Dónde vive 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/ | respaldado por el crate solana-keychain |
Dos archivos más que conviene conocer: config.rs define el esquema completo de kora.toml, y
state.rs guarda la configuración deserializada en un estado global del proceso.
Lectura del servidor RPC
rpc.rs es una capa de despacho delgada, 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 se encuentra 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.
Lectura del validador
transaction_validator.rs y transaction/instruction_util.rs contienen la lógica para
validar transacciones e instrucciones. Además, las pruebas de propiedades de seguridad de la
política del pagador de comisiones, que viven en un archivo por cada programa restringido dentro de
validator/transaction_validator/fee_payer_policy_props/.
Convenciones que conviene conocer
Validación por defecto. Cada indicador bajo [validation.fee_payer_policy]
tiene como valor predeterminado false, y las estructuras de la política llevan #[serde(default)]. Este
emparejamiento es deliberado: añadir una instrucción recién restringida no debe romper la configuración
de un operador existente, y debe entrar como una denegación en lugar de
una autorización accidental. Conserva ambas cosas cuando añadas un indicador.
Valida la transacción resuelta, nunca la original. La
VersionedTransaction original expone únicamente las claves de cuenta estáticas, por lo que validar o
calcular el precio de una transacción V0 a partir de ella omite silenciosamente 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 inicio y devuelve errores y advertencias para el
operador. Un PluginExecutionContext le indica al plugin cuál de los cuatro métodos de firma
lo invocó.
TransactionPluginRunner::from_config hace coincidir según TransactionPluginType,
definido en config.rs. Un nuevo plugin integrado consiste en una nueva variante allí más un nuevo
brazo 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 integrado junto con un
nodo de Kora, inicializado desde cero. Una configuración por binario: una nueva fase necesita un nuevo
target, no un nuevo módulo en uno existente.
cargo test -p tests --test <target>
Todo lo demás está conectado a través del justfile. Lee ese archivo en lugar de
reconstruir los comandos a mano.
Is this page helpful?