¿Usas Kora v2.2.0-beta? Consulta Configuración Beta para nuevas opciones: paquetes Jito, protección Lighthouse, reCAPTCHA y límites de uso.
Tu nodo Kora firmará transacciones para tus usuarios, por lo que es importante
configurarlo para que solo firme transacciones que cumplan con los requisitos de
tu negocio. Kora te ofrece mucha flexibilidad en cómo configuras tu nodo, pero
es importante entender las implicaciones de tu configuración. kora.toml es el
centro de control para tu configuración de Kora. Este documento proporciona una
referencia completa para configurar tu nodo paymaster de Kora a través del
archivo de configuración kora.toml.
Descripción general
El archivo kora.toml controla todos los aspectos del comportamiento de tu nodo
Kora incluyendo:
- Limitación de velocidad y autenticación
- Disponibilidad de métodos RPC
- Reglas de validación de transacciones
- Modelos de precios de tarifas
- Políticas de seguridad
- Disponibilidad de métodos RPC
- Modelos de precios de tarifas
- Configuración de dirección de pago
- Monitoreo de rendimiento
Tu archivo de configuración debe colocarse en tu directorio de implementación o
especificarse mediante la opción --config al iniciar el servidor.
Secciones de configuración
El archivo kora.toml está organizado en secciones, cada una con su propio
conjunto de opciones. Esta guía recorre cada sección y explica las opciones
disponibles:
- Políticas centrales de Kora - Configuración del servidor central
- Autenticación de Kora - Configuración de autenticación
- Caché de Kora - Caché Redis para llamadas RPC
- Límites de uso de Kora - Limitación de transacciones por wallet
- Métodos habilitados de Kora - Métodos RPC de Kora para habilitar
- Políticas de validación - Validación de transacciones y seguridad
- Bloqueo de extensiones Token-2022 - Bloquear extensiones riesgosas de Token-2022
- Política del pagador de tarifas - Restricciones en la wallet del pagador de tarifas
- Configuración de precios - Modelos de precios de tarifas de transacción
- Monitoreo de rendimiento - Recopilación de métricas y monitoreo
- Ejemplo completo - Configuración completa lista para producción
Secciones de archivo kora.toml de ejemplo:
[kora]# Core server settings[kora.auth]# Authentication settings[kora.cache]# Redis caching configuration[kora.usage_limit]# Per-wallet transaction limiting[kora.enabled_methods]# Kora RPC methods to enable[validation]# Transaction validation rules[validation.token2022]# Token-2022 extension blocking[validation.fee_payer_policy]# Restrictions on fee payer wallet[validation.price]# Transaction fee pricing models[metrics]# Performance monitoring
Políticas principales de Kora
La sección [kora] configura el comportamiento principal del servidor:
[kora]rate_limit = 100payment_address = "YourPaymentAddressPubkey11111111111111111111" # Optional
| Opción | Descripción | Requerido | Tipo |
|---|---|---|---|
rate_limit | Límite de tasa global (solicitudes por segundo) en todos los clientes | ✅ | número |
payment_address | Dirección de pago opcional para recibir tokens de pago (por defecto, dirección(es) del firmante si no se especifica) | ❌ | cadena codificada en b58 |
Autenticación de Kora
La sección [kora.auth] configura la autenticación para el servidor Kora:
[kora.auth]api_key = "kora_live_sk_1234567890abcdef"hmac_secret = "kora_hmac_your-strong-hmac-secret-key-here"max_timestamp_age = 300
| Opción | Descripción | Requerido | Tipo |
|---|---|---|---|
api_key | Clave API para autenticación simple | ❌ | cadena |
hmac_secret | Secreto HMAC para autenticación basada en firma (mínimo 32 caracteres) | ❌ | cadena |
max_timestamp_age | Antigüedad máxima de una marca de tiempo HMAC en segundos | ❌ (por defecto: 300) | número |
Nota:
api_keyehmac_secretestablecen una política de autenticación global para todos los clientes. Para la configuración detallada de autenticación, consulte la Guía de autenticación.
Almacenamiento en caché de Kora (opcional)
La sección [kora.cache] configura el almacenamiento en caché basado en Redis
para las llamadas RPC de Solana. Esto puede mejorar significativamente el
rendimiento al reducir las recuperaciones redundantes de datos de cuentas:
[kora.cache]enabled = true # Enable/disable cachingurl = "redis://localhost:6379" # Redis connection URLdefault_ttl = 300 # Default TTL in seconds (5 minutes)account_ttl = 60 # Account data TTL in seconds (1 minute)
| Opción | Descripción | Requerido | Tipo |
|---|---|---|---|
enabled | Habilitar almacenamiento en caché Redis para llamadas RPC | ❌ (por defecto: false) | booleano |
url | URL de conexión Redis (requerida cuando está habilitada) | ✅ | cadena |
default_ttl | TTL predeterminado para entradas en caché en segundos | ❌ (por defecto: 300) | número |
account_ttl | TTL para caché de datos de cuenta en segundos | ❌ (por defecto: 60) | número |
Nota: Cuando el almacenamiento en caché está habilitado, debe estar disponible una instancia de Redis en la URL especificada. La caché recurre elegantemente a llamadas RPC directas si Redis no está disponible.
Límites de Uso de Kora (opcional)
La sección [kora.usage_limit] configura la limitación de transacciones por
billetera para prevenir el abuso y garantizar un uso justo entre sus usuarios.
Esto también podría utilizarse para crear programas de recompensas que subsidien
las tarifas de transacción de los usuarios hasta un cierto límite.
Importante: Actualmente, la única forma de limitación de uso admitida por Kora es un límite permanente. Una vez que una billetera alcanza su límite de transacciones, no se puede restablecer y el usuario ya no podrá enviar más transacciones usando esa misma billetera. Este límite persiste hasta que se borre manualmente de Redis o se reinicien los datos de Redis.
Nota: Esta función requiere Redis cuando está habilitada en múltiples instancias de Kora:
[kora.usage_limit]enabled = true # Enable/disable usage limitingcache_url = "redis://localhost:6379" # Redis URL for shared state (required when enabled)max_transactions = 100 # Max transactions per wallet (0 = unlimited)fallback_if_unavailable = true # Continue if Redis is unavailable
| Opción | Descripción | Requerido | Tipo |
|---|---|---|---|
enabled | Habilitar limitación de transacciones por billetera | ❌ (predeterminado: false) | boolean |
cache_url | URL de conexión Redis para seguimiento de uso compartido | ❌ | string |
max_transactions | Transacciones máximas por billetera (0 = ilimitado) | ❌ (predeterminado: 100) | number |
fallback_if_unavailable | Permitir transacciones si Redis no está disponible | ❌ (predeterminado: true) | boolean |
Nota: Los límites de uso se rastrean por dirección de billetera con expiración automática basada en TTL. Cuando
fallback_if_unavailablees verdadero, el sistema permite que las transacciones continúen si Redis no está disponible temporalmente, evitando interrupciones del servicio. Establecermax_transactionsen 0 permitirá transacciones ilimitadas.
Métodos Habilitados de Kora (opcional)
La sección [kora.enabled_methods] controla qué métodos RPC están habilitados.
Esta sección es opcional y, por defecto, todos los métodos están habilitados.
Cada método puede habilitarse o deshabilitarse estableciendo el valor en true
o false:
[kora.enabled_methods]liveness = trueestimate_transaction_fee = trueget_supported_tokens = truesign_transaction = falsesign_and_send_transaction = falsetransfer_transaction = falseget_blockhash = trueget_config = trueget_payer_signer = true
| Opción | Descripción del Método | Requerido | Tipo |
|---|---|---|---|
liveness | Endpoint de verificación de estado | ✅ | boolean |
estimate_transaction_fee | Estimar la tarifa de una transacción | ✅ | boolean |
get_supported_tokens | Listar tokens aceptados | ✅ | boolean |
sign_transaction | Firmar una transacción sin enviarla a la red | ✅ | boolean |
sign_and_send_transaction | Firmar una transacción y enviarla a la red | ✅ | boolean |
transfer_transaction | Manejar transferencias de tokens | ✅ | boolean |
get_blockhash | Obtener un blockhash reciente | ✅ | boolean |
get_config | Devolver la configuración del servidor Kora | ✅ | boolean |
Nota: si esta sección se incluye en tu archivo
kora.toml, todos los métodos deben establecerse explícitamente entrueofalse.
Políticas de Validación
La sección [validation] define las reglas de seguridad relacionadas con Solana
y los límites de transacción:
[validation]max_allowed_lamports = 1000000 # 0.001 SOLmax_signatures = 10price_source = "Jupiter"allow_durable_transactions = false # Block durable nonce transactionsallowed_programs = ["11111111111111111111111111111111", # System Program (required for SOL transfers)"TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA", # SPL Token Program"TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb", # Token-2022 Program"ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL", # Associated Token Program"AddressLookupTab1e1111111111111111111111111", # Address Lookup Table Program"ComputeBudget11111111111111111111111111111111", # Compute Budget Program]allowed_tokens = ["EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", # USDC (mainnet)# additional tokens here]allowed_spl_paid_tokens = ["EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", # USDC (mainnet)# additional tokens here]disallowed_accounts = [# "BadActorPubkey11111111111111111111111111111",]
| Opción | Descripción | Requerido | Tipo |
|---|---|---|---|
max_allowed_lamports | Establecer un número máximo de lamports por transacción limita la exposición del nodo Kora a una sola transacción. | ✅ | number |
max_signatures | Las tarifas base de Solana son una función del número de firmas en una transacción, por lo que establecer un número máximo de firmas por transacción es una buena manera de evitar que los usuarios gasten demasiado SOL en una sola transacción. | ✅ | number |
price_source | Oráculo para datos de precios de tokens. Nota: Cuando se establece en "Jupiter", la variable de entorno JUPITER_API_KEY es requerida. El servidor no se iniciará sin ella. | ✅ | "Jupiter" o "Mock" |
allow_durable_transactions | Permitir transacciones con nonce duradero. Ver Consideraciones de Seguridad a continuación. | ❌ (predeterminado: false) | boolean |
allowed_programs | Programas de Solana con los que las transacciones pueden interactuar | ✅ | Array de string codificado en b58 |
allowed_tokens | Token mints que pueden usarse en transacciones | ✅ | Array de string codificado en b58 |
allowed_spl_paid_tokens | Tokens SPL aceptados como pago por tarifas de transacción | ✅ | Array de string codificado en b58 |
disallowed_accounts | Cuentas que están explícitamente bloqueadas para transacciones | ✅ | Array de string codificado en b58 |
Nota: Se permiten arrays vacíos, pero deberá especificar al menos un
allowed_programs,allowed_tokens,allowed_spl_paid_tokensen la lista blanca para que el nodo Kora pueda procesar transacciones. Debe especificar el System Program o Token Program para que el nodo Kora pueda procesar transferencias. Para habilitar tipos de instrucciones comunes (por ejemplo, Compute Budget, Address Lookup Table), debe especificar el Compute Budget Program o Address Lookup Table Program, etc.
Seguridad de Transacciones Duraderas
ADVERTENCIA DE SEGURIDAD: Las transacciones con nonce duradero permiten que las transacciones firmadas se retengan indefinidamente y se envíen más tarde. Esto podría utilizarse como un vector de ataque económico donde alguien podría obtener una transacción firmada y esperar para enviarla hasta que las condiciones del mercado sean favorables para ellos (por ejemplo, cuando el valor de SOL haya caído o el valor del token de pago haya aumentado).
Por defecto, allow_durable_transactions está configurado como false para
bloquear todas las transacciones con nonce duradero. Habilite esto solo si su
aplicación requiere específicamente transacciones duraderas y comprende los
riesgos.
Si debe habilitar transacciones duraderas, considere:
- Usar autenticación para restringir el acceso a la API
- Implementar validación adicional fuera de la cadena
- Monitorear patrones de transacciones inusuales
- Monitorear y limitar los saldos de cuentas firmantes
- Rotar las claves de los firmantes regularmente
Obtenga más información sobre las transacciones con nonce duradero en los Documentos de Solana.
Bloqueo de Extensiones Token-2022
La sección [validation.token2022] le permite bloquear extensiones específicas
de Token-2022 para mayor seguridad. Todas las extensiones están habilitadas por
defecto. Puede bloquear extensiones específicas agregándolas a los arrays
blocked_mint_extensions o blocked_account_extensions:
[validation.token2022]blocked_mint_extensions = ["transfer_hook", # Block tokens with transfer hooks"pausable", # Block pausable tokens"permanent_delegate", # Block tokens with permanent delegates]blocked_account_extensions = ["cpi_guard", # Block accounts with CPI guard"memo_transfer", # Block accounts requiring memos]
Extensiones de Mint Disponibles
| Nombre de la Extensión | Descripción |
|---|---|
confidential_transfer_mint | Configuración de transferencia confidencial para el mint |
confidential_mint_burn | Configuración de mint y quema confidencial |
transfer_fee_config | Configuración de tarifa de transferencia |
mint_close_authority | Autoridad permitida para cerrar el mint |
interest_bearing_config | Configuración de token con intereses |
non_transferable | Hace que los tokens no sean transferibles |
permanent_delegate | Delegado permanente para el mint |
transfer_hook | Programa de gancho de transferencia personalizado |
pausable | Configuración de token pausable |
Extensiones de Cuenta Disponibles
| Nombre de la Extensión | Descripción |
|---|---|
confidential_transfer_account | Estado de transferencia confidencial para la cuenta |
non_transferable_account | Cuenta de token no transferible |
transfer_hook_account | Estado de gancho de transferencia para la cuenta |
pausable_account | Estado de cuenta de token pausable |
memo_transfer | Requiere nota para las transferencias |
cpi_guard | Previene ciertas llamadas CPI |
immutable_owner | El propietario de la cuenta no puede ser cambiado |
default_account_state | Estado predeterminado para cuentas nuevas |
transfer_hook
Consideraciones de Seguridad
Extensión PermanentDelegate - Los tokens con esta extensión permiten que el delegado transfiera/queme tokens en cualquier momento sin aprobación del propietario. Esto crea riesgos significativos para el operador del nodo Kora ya que los fondos de pago pueden ser incautados después del pago.
- Considera agregar "permanent_delegate" a
blocked_mint_extensionsen [validation.token2022] a menos que lo necesites explícitamente para tu caso de uso. - Evita usar tokens de pago con la extensión
permanent_delegate.
Política del Pagador de Tarifas
La sección [validation.fee_payer_policy] proporciona control granular sobre
qué acciones puede realizar la billetera del pagador de tarifas de tu nodo Kora.
La política está organizada por tipo de programa (System, SPL Token, Token-2022)
y cubre todos los diferentes tipos de instrucciones. Esto previene
comportamientos inesperados de las transacciones de los usuarios que utilizan tu
nodo Kora como firmante.
Por ejemplo, si spl_token.allow_transfer está configurado como false, el
nodo Kora no firmará transacciones que incluyan una transferencia de tokens SPL
donde el pagador de tarifas del nodo Kora sea la autoridad de transferencia.
[validation.fee_payer_policy.system]allow_transfer = false # System Transfer/TransferWithSeedallow_assign = false # System Assign/AssignWithSeedallow_create_account = false # System CreateAccount/CreateAccountWithSeedallow_allocate = false # System Allocate/AllocateWithSeed[validation.fee_payer_policy.system.nonce]allow_initialize = false # InitializeNonceAccountallow_advance = false # AdvanceNonceAccountallow_authorize = false # AuthorizeNonceAccountallow_withdraw = false # WithdrawNonceAccount[validation.fee_payer_policy.spl_token]allow_transfer = false # Transfer/TransferCheckedallow_burn = false # Burn/BurnCheckedallow_close_account = false # CloseAccountallow_approve = false # Approve/ApproveCheckedallow_revoke = false # Revokeallow_set_authority = false # SetAuthorityallow_mint_to = false # MintTo/MintToCheckedallow_initialize_mint = false # InitializeMint/InitializeMint2allow_initialize_account = false # InitializeAccount/InitializeAccount3allow_initialize_multisig = false # InitializeMultisig/InitializeMultisig2allow_freeze_account = false # FreezeAccountallow_thaw_account = false # ThawAccount[validation.fee_payer_policy.token_2022]allow_transfer = false # Transfer/TransferCheckedallow_burn = false # Burn/BurnCheckedallow_close_account = false # CloseAccountallow_approve = false # Approve/ApproveCheckedallow_revoke = false # Revokeallow_set_authority = false # SetAuthorityallow_mint_to = false # MintTo/MintToCheckedallow_initialize_mint = false # InitializeMint/InitializeMint2allow_initialize_account = false # InitializeAccount/InitializeAccount3allow_initialize_multisig = false # InitializeMultisig/InitializeMultisig2allow_freeze_account = false # FreezeAccountallow_thaw_account = false # ThawAccount
Instrucciones del System Program
| Opción | Descripción | Predeterminado | Tipo |
|---|---|---|---|
allow_transfer | Permitir al pagador de tarifas como remitente en instrucciones Transfer/TransferWithSeed | false | booleano |
allow_assign | Permitir al pagador de tarifas como autoridad en instrucciones Assign/AssignWithSeed | false | booleano |
allow_create_account | Permitir al pagador de tarifas como pagador de financiación en instrucciones CreateAccount/CreateAccountWithSeed | false | booleano |
allow_allocate | Permitir al pagador de tarifas como propietario de cuenta en instrucciones Allocate/AllocateWithSeed | false | booleano |
nonce.allow_initialize | Permitir que el pagador de tarifas sea establecido como autoridad nonce en InitializeNonceAccount | false | booleano |
nonce.allow_advance | Permitir al pagador de tarifas como autoridad en AdvanceNonceAccount | false | booleano |
nonce.allow_authorize | Permitir al pagador de tarifas como autoridad actual en AuthorizeNonceAccount | false | booleano |
nonce.allow_withdraw | Permitir al pagador de tarifas como autoridad en WithdrawNonceAccount | false | booleano |
Instrucciones del SPL Token Program
| Opción | Descripción | Predeterminado | Tipo |
|---|---|---|---|
allow_transfer | Permitir al pagador de tarifas como propietario en instrucciones Transfer/TransferChecked | false | booleano |
allow_burn | Permitir al pagador de tarifas como propietario en instrucciones Burn/BurnChecked | false | booleano |
allow_close_account | Permitir al pagador de tarifas como propietario en instrucciones CloseAccount | false | booleano |
allow_approve | Permitir al pagador de tarifas como propietario en instrucciones Approve/ApproveChecked | false | booleano |
allow_revoke | Permitir al pagador de tarifas como propietario en instrucciones Revoke | false | booleano |
allow_set_authority | Permitir al pagador de tarifas como autoridad actual en instrucciones SetAuthority | false | booleano |
allow_mint_to | Permitir al pagador de tarifas como autoridad de acuñación en instrucciones MintTo/MintToChecked | false | booleano |
allow_initialize_mint | Permitir al pagador de tarifas como autoridad de acuñación en instrucciones InitializeMint/InitializeMint2 | false | booleano |
allow_initialize_account | Permitir al pagador de tarifas como propietario en instrucciones InitializeAccount/InitializeAccount3 | false | booleano |
allow_initialize_multisig | Permitir al pagador de tarifas como firmante en instrucciones InitializeMultisig/InitializeMultisig2 | false | booleano |
allow_freeze_account | Permitir al pagador de tarifas como autoridad de congelación en instrucciones FreezeAccount | false | booleano |
allow_thaw_account | Permitir al pagador de tarifas como autoridad de congelación en instrucciones ThawAccount | false | booleano |
Token-2022 admite el mismo conjunto de instrucciones que SPL Token con opciones
de configuración idénticas (en la sección
[validation.fee_payer_policy.token_2022]).
Consideraciones de Seguridad
ADVERTENCIA DE SEGURIDAD: Por razones de seguridad, se recomienda establecer
todas estas opciones en false (predeterminado) y solo habilitar según sea
necesario. Esto evitará comportamientos no deseados como que los usuarios drenen
su cuenta de pagador de tarifas o quemen tokens de su cuenta de pagador de
tarifas. Esto previene:
- Drenaje de Cuenta: Los usuarios transfieren SOL o tokens desde su cuenta de pagador de tarifas
- Apropiación de Autoridad: Los usuarios cambian las autoridades en cuentas propiedad de su pagador de tarifas
- Acuñación No Autorizada: Los usuarios acuñan tokens si su pagador de tarifas tiene autoridad de acuñación
- Manipulación de Cuentas: Los usuarios congelan, cierran o modifican cuentas controladas por su pagador de tarifas
Mejor Práctica: Comience con todos los permisos deshabilitados y habilite solo el conjunto mínimo necesario para su caso de uso específico.
Configuración de Precios (opcional)
La sección [validation.price] define cómo se calculan las tarifas de
transacción. Hay tres modelos de precios disponibles:
- Precios con Margen (predeterminado) - Agregar un porcentaje de margen sobre las tarifas reales de la red (el margen predeterminado es 0.0)
- Precios Fijos - Cobrar una cantidad fija en un token específico independientemente de las tarifas de red
- Precios Gratuitos - Patrocinar todas las tarifas de transacción (sin cargo para los usuarios)
| Opción | Descripción | Requerido | Tipo |
|---|---|---|---|
type | Modelo de precios a utilizar | ✅ | "margin", "fixed" o "free" |
margin | Porcentaje de margen a agregar a las tarifas de red | (cuando type es "margin") | número |
amount | Cantidad fija a cobrar en unidades base del token | (cuando type es "fixed") | número |
token | Mint del token en el que cobrar | (cuando type es "fixed") | cadena codificada en b58 |
Precio con Margen
Añade un porcentaje de margen sobre las tarifas de red reales:
[validation.price]type = "margin"margin = 0.1 # 10% margin (0.1 = 10%, 1.0 = 100%)
Precio Fijo
ADVERTENCIA DE SEGURIDAD: El precio fijo NO incluye la salida del pagador de tarifas en el monto cobrado. Esto puede permitir a los usuarios vaciar tu cuenta de pagador de tarifas si no se configura correctamente.
Cobra un monto fijo en un token específico independientemente de las tarifas de red:
[validation.price]type = "fixed"amount = 1000000 # Amount in token's base unitstoken = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" # USDC mint
Transacciones Gratuitas
Patrocina todas las tarifas de transacción (sin cargo para los usuarios):
[validation.price]type = "free"
Medidas de Seguridad al Usar Precios Fijos/Gratuitos
-
Deshabilita Todas las Operaciones de Transferencia y Monetarias - Evita que el pagador de tarifas sea utilizado como origen en transferencias:
[validation.fee_payer_policy.system]allow_transfer = false # Block SOL transfersallow_create_account = false # Block account creation with lamportsallow_allocate = false # Block space allocation[validation.fee_payer_policy.system.nonce]allow_withdraw = false # Block nonce account withdrawals[validation.fee_payer_policy.spl_token] # and for [validation.fee_payer_policy.token_2022]allow_transfer = false # Block SPL transfersallow_burn = false # Block SPL token burningallow_close_account = false # Block SPL token account closures (returns rent)allow_mint_to = false # Block unauthorized SPL token mintingallow_initialize_account = false # Block account initialization -
Habilita la Autenticación - Utiliza autenticación para prevenir el abuso:
[kora.auth]api_key = "your-secure-api-key"# orhmac_secret = "your-minimum-32-character-hmac-secret" -
Establece Límites Conservadores - Minimiza la exposición:
[validation]max_allowed_lamports = 1000000 # 0.001 SOL maximum
ADVERTENCIA: Operaciones particularmente peligrosas al usar precios fijos/gratuitos:
allow_mint_to: Podría permitir la creación ilimitada de tokens si el pagador de tarifas tiene autoridad de acuñaciónallow_set_authority: Podría transferir el control de cuentas críticas a atacantesallow_transfer: Habilita el drenaje directo de los saldos de tokens del pagador de tarifasallow_close_account: Devuelve el alquiler a cuentas controladas por el atacante
Monitoreo de Rendimiento (opcional)
La sección [metrics] configura la recopilación de métricas y el monitoreo.
Esta sección es opcional y, por defecto, las métricas están deshabilitadas.
[metrics]enabled = trueendpoint = "/metrics"port = 8080scrape_interval = 60[metrics.fee_payer_balance]enabled = trueexpiry_seconds = 30
| Opción | Descripción | Requerido | Tipo |
|---|---|---|---|
enabled | Habilitar recopilación de métricas | ✅ | boolean |
endpoint | Ruta personalizada del endpoint de métricas | ✅ | string |
port | Puerto del endpoint de métricas | ✅ | number |
scrape_interval | Frecuencia de scraping de Prometheus (segundos) | ✅ | number |
Seguimiento del Saldo del Pagador de Comisiones
La sección [metrics.fee_payer_balance] configura el monitoreo automático del
saldo de SOL de tu pagador de comisiones:
| Opción | Descripción | Requerido | Tipo |
|---|---|---|---|
enabled | Habilitar seguimiento del saldo del pagador de comisiones | ❌ (predeterminado: false) | boolean |
expiry_seconds | Intervalo de seguimiento en segundo plano en segundos | ❌ (predeterminado: 30) | number |
Cuando está habilitado, Kora rastrea automáticamente el saldo de SOL de tu
pagador de comisiones y lo expone a través del medidor Prometheus
fee_payer_balance_lamports. Esto ayuda con la planificación de capacidad y las
alertas de saldo bajo.
http://localhost:{port}/{metrics-endpoint}
→ Guía de Referencia de Monitoreo de Kora
Ejemplo Completo
Aquí hay una configuración lista para producción con las mejores prácticas de seguridad:
# Kora Paymaster Configuration# Last Updated: 2025-08-22[kora]# Rate limiting: 100 requests per second globallyrate_limit = 100# Optional payment address (defaults to signer address(es) if not specified)# payment_address = "YourPaymentAddressPubkey11111111111111111111"[kora.auth]# Authentication (choose based on security needs)# api_key = "kora_live_sk_generate_secure_key_here"hmac_secret = "kora_hmac_minimum_32_character_secret_here"max_timestamp_age = 300# Caching configuration (optional but recommended for production)[kora.cache]enabled = trueurl = "redis://localhost:6379"default_ttl = 300 # 5 minutesaccount_ttl = 60 # 1 minute# Usage limiting (optional, prevents abuse)[kora.usage_limit]enabled = truecache_url = "redis://localhost:6379" # Can share same Redis instance as cachemax_transactions = 100 # Per-wallet limitfallback_if_unavailable = true # Don't block if Redis is down# Disable unnecessary RPC methods for security[kora.enabled_methods]liveness = trueestimate_transaction_fee = trueget_supported_tokens = truesign_transaction = falsesign_and_send_transaction = falsetransfer_transaction = falseget_blockhash = trueget_config = trueget_payer_signer = true[validation]# Use production oracleprice_source = "Jupiter"# Conservative transaction limitsmax_allowed_lamports = 1000000 # 0.001 SOL maxmax_signatures = 10# Block durable nonce transactions (security default)allow_durable_transactions = false# Minimal program allowlist (expand as needed)allowed_programs = ["11111111111111111111111111111111", # System Program"TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA", # SPL Token"ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL", # Associated Token"AddressLookupTab1e1111111111111111111111111", # Address Lookup Table"ComputeBudget11111111111111111111111111111111", # Compute Budget"MyProgram111111111111111111111111111111111",# Add your specific program IDs here]# Production token allowlistallowed_tokens = ["EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", # USDC"So11111111111111111111111111111111111111112", # Wrapped SOL"MyToken1111111111111111111111111111111111111111",# Add tokens your application uses]# Payment tokens (only liquid, trusted tokens)allowed_spl_paid_tokens = ["EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", # USDC only]# Known bad actors or compromised addressesdisallowed_accounts = ["BadActor1111111111111111111111111111111111111111",]# Restrictive fee payer policy (recommended for production)[validation.fee_payer_policy.system]allow_transfer = false # Block SOL transfers from fee payerallow_assign = false # Block account ownership changesallow_create_account = false # Block creating accounts with fee payer fundsallow_allocate = false # Block allocating space for fee payer accounts[validation.fee_payer_policy.system.nonce]allow_initialize = false # Block nonce account initializationallow_advance = false # Block nonce advancementallow_authorize = false # Block nonce authority changesallow_withdraw = false # Block nonce withdrawals[validation.fee_payer_policy.spl_token]allow_transfer = false # Critical: Block SPL transfersallow_burn = false # Block token burningallow_close_account = false # Block account closuresallow_approve = false # Block token approvalsallow_revoke = false # Block delegate revocationsallow_set_authority = false # Block authority changesallow_mint_to = false # Block minting operationsallow_initialize_mint = false # Block mint initializationallow_initialize_account = false # Block account initializationallow_initialize_multisig = false # Block multisig initializationallow_freeze_account = false # Block account freezingallow_thaw_account = false # Block account thawing[validation.fee_payer_policy.token_2022]allow_transfer = false # Critical: Block Token2022 transfersallow_burn = false # Block token burningallow_close_account = false # Block account closuresallow_approve = false # Block token approvalsallow_revoke = false # Block delegate revocationsallow_set_authority = false # Block authority changesallow_mint_to = false # Block minting operationsallow_initialize_mint = false # Block mint initializationallow_initialize_account = false # Block account initializationallow_initialize_multisig = false # Block multisig initializationallow_freeze_account = false # Block account freezingallow_thaw_account = false # Block account thawing# Token-2022 extension blocking[validation.token2022]# Block potentially risky mint extensionsblocked_mint_extensions = ["transfer_hook", # Custom transfer logic"pausable", # Can freeze transfers"permanent_delegate", # Permanent control]# Block complex account extensionsblocked_account_extensions = ["cpi_guard", # Restricts composability"memo_transfer", # Requires additional data]# Sustainable pricing with 15% margin[validation.price]type = "margin"margin = 0.15 # 15% margin on network fees# Metrics collection[metrics]enabled = trueendpoint = "/metrics"port = 8080scrape_interval = 60# Fee payer balance monitoring[metrics.fee_payer_balance]enabled = trueexpiry_seconds = 30
Validación de Configuración
Kora valida tu configuración al iniciarse. Si deseas validar tu configuración sin iniciar el servidor, puedes usar el comando de validación de configuración:
kora --config kora.toml config validate # or validate-with-rpc
También puedes ejecutar el comando validate-with-rpc para validar tu
configuración con el servidor RPC (esta verificación de validación es un poco
más lenta pero realiza verificaciones de cuenta más exhaustivas)
Iniciar el Servidor
Una vez que hayas configurado tu archivo kora.toml, puedes iniciar el servidor
Kora:
kora --config path/to/kora.toml rpc start --no-load-signer # --other-rpc-flags-here
La bandera --no-load-signer inicializará el servidor sin cargar ningún
firmante. Esto es útil para probar tu configuración. Para cargar firmantes,
necesitarás configurar el archivo signers.toml. Una configuración mínima con
un solo firmante se vería así:
[signer_pool]# Selection strategy: round_robin, random, weightedstrategy = "round_robin"# Primary memory signer[[signers]]name = "my-signer"type = "memory"private_key_env = "MY_SIGNER_PRIVATE_KEY"
Esto cargará un solo firmante desde la variable de entorno
MY_SIGNER_PRIVATE_KEY. Luego puedes iniciar tu servidor con:
kora --config path/to/kora.toml rpc start --signers-config path/to/signers.toml
Para más información y configuración avanzada de firmantes, consulta la Guía de Firmantes.
Mejores Prácticas
- Comienza de forma restrictiva: Inicia con límites estrictos y expándelos gradualmente
- Monitorea el uso: Rastrea qué programas y tokens se utilizan realmente
- Actualizaciones regulares: Revisa y actualiza las listas de bloqueo y límites
- Prueba los cambios: Valida los cambios de configuración primero en staging
- Control de versiones: Mantén un registro de cambios de tu configuración
¿Necesitas ayuda?
- Consulta la Guía de Autenticación para la configuración de autenticación
- Consulta la Guía de Firmantes para la configuración de firmantes
- Consulta la Guía del Operador para más información sobre cómo ejecutar un nodo Kora
- Visita Solana Stack Exchange con la
etiqueta
kora - Reporta problemas en GitHub
Is this page helpful?