Configuración

¿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:

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 = 100
payment_address = "YourPaymentAddressPubkey11111111111111111111" # Optional
OpciónDescripciónRequeridoTipo
rate_limitLímite de tasa global (solicitudes por segundo) en todos los clientesnúmero
payment_addressDirecció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ónDescripciónRequeridoTipo
api_keyClave API para autenticación simplecadena
hmac_secretSecreto HMAC para autenticación basada en firma (mínimo 32 caracteres)cadena
max_timestamp_ageAntigüedad máxima de una marca de tiempo HMAC en segundos❌ (por defecto: 300)número

Nota: api_key e hmac_secret establecen 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 caching
url = "redis://localhost:6379" # Redis connection URL
default_ttl = 300 # Default TTL in seconds (5 minutes)
account_ttl = 60 # Account data TTL in seconds (1 minute)
OpciónDescripciónRequeridoTipo
enabledHabilitar almacenamiento en caché Redis para llamadas RPC❌ (por defecto: false)booleano
urlURL de conexión Redis (requerida cuando está habilitada)cadena
default_ttlTTL predeterminado para entradas en caché en segundos❌ (por defecto: 300)número
account_ttlTTL 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 limiting
cache_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ónDescripciónRequeridoTipo
enabledHabilitar limitación de transacciones por billetera❌ (predeterminado: false)boolean
cache_urlURL de conexión Redis para seguimiento de uso compartidostring
max_transactionsTransacciones máximas por billetera (0 = ilimitado)❌ (predeterminado: 100)number
fallback_if_unavailablePermitir 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_unavailable es verdadero, el sistema permite que las transacciones continúen si Redis no está disponible temporalmente, evitando interrupciones del servicio. Establecer max_transactions en 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 = true
estimate_transaction_fee = true
get_supported_tokens = true
sign_transaction = false
sign_and_send_transaction = false
transfer_transaction = false
get_blockhash = true
get_config = true
get_payer_signer = true
OpciónDescripción del MétodoRequeridoTipo
livenessEndpoint de verificación de estadoboolean
estimate_transaction_feeEstimar la tarifa de una transacciónboolean
get_supported_tokensListar tokens aceptadosboolean
sign_transactionFirmar una transacción sin enviarla a la redboolean
sign_and_send_transactionFirmar una transacción y enviarla a la redboolean
transfer_transactionManejar transferencias de tokensboolean
get_blockhashObtener un blockhash recienteboolean
get_configDevolver la configuración del servidor Koraboolean

Nota: si esta sección se incluye en tu archivo kora.toml, todos los métodos deben establecerse explícitamente en true o false.

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 SOL
max_signatures = 10
price_source = "Jupiter"
allow_durable_transactions = false # Block durable nonce transactions
allowed_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ónDescripciónRequeridoTipo
max_allowed_lamportsEstablecer un número máximo de lamports por transacción limita la exposición del nodo Kora a una sola transacción.number
max_signaturesLas 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_sourceOrá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_transactionsPermitir transacciones con nonce duradero. Ver Consideraciones de Seguridad a continuación.❌ (predeterminado: false)boolean
allowed_programsProgramas de Solana con los que las transacciones pueden interactuarArray de string codificado en b58
allowed_tokensToken mints que pueden usarse en transaccionesArray de string codificado en b58
allowed_spl_paid_tokensTokens SPL aceptados como pago por tarifas de transacciónArray de string codificado en b58
disallowed_accountsCuentas que están explícitamente bloqueadas para transaccionesArray de string codificado en b58

Nota: Se permiten arrays vacíos, pero deberá especificar al menos un allowed_programs, allowed_tokens, allowed_spl_paid_tokens en 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ónDescripción
confidential_transfer_mintConfiguración de transferencia confidencial para el mint
confidential_mint_burnConfiguración de mint y quema confidencial
transfer_fee_configConfiguración de tarifa de transferencia
mint_close_authorityAutoridad permitida para cerrar el mint
interest_bearing_configConfiguración de token con intereses
non_transferableHace que los tokens no sean transferibles
permanent_delegateDelegado permanente para el mint
transfer_hookPrograma de gancho de transferencia personalizado
pausableConfiguración de token pausable

Extensiones de Cuenta Disponibles

Nombre de la ExtensiónDescripción
confidential_transfer_accountEstado de transferencia confidencial para la cuenta
non_transferable_accountCuenta de token no transferible
transfer_hook_accountEstado de gancho de transferencia para la cuenta
pausable_accountEstado de cuenta de token pausable
memo_transferRequiere nota para las transferencias
cpi_guardPreviene ciertas llamadas CPI
immutable_ownerEl propietario de la cuenta no puede ser cambiado
default_account_stateEstado 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_extensions en [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/TransferWithSeed
allow_assign = false # System Assign/AssignWithSeed
allow_create_account = false # System CreateAccount/CreateAccountWithSeed
allow_allocate = false # System Allocate/AllocateWithSeed
[validation.fee_payer_policy.system.nonce]
allow_initialize = false # InitializeNonceAccount
allow_advance = false # AdvanceNonceAccount
allow_authorize = false # AuthorizeNonceAccount
allow_withdraw = false # WithdrawNonceAccount
[validation.fee_payer_policy.spl_token]
allow_transfer = false # Transfer/TransferChecked
allow_burn = false # Burn/BurnChecked
allow_close_account = false # CloseAccount
allow_approve = false # Approve/ApproveChecked
allow_revoke = false # Revoke
allow_set_authority = false # SetAuthority
allow_mint_to = false # MintTo/MintToChecked
allow_initialize_mint = false # InitializeMint/InitializeMint2
allow_initialize_account = false # InitializeAccount/InitializeAccount3
allow_initialize_multisig = false # InitializeMultisig/InitializeMultisig2
allow_freeze_account = false # FreezeAccount
allow_thaw_account = false # ThawAccount
[validation.fee_payer_policy.token_2022]
allow_transfer = false # Transfer/TransferChecked
allow_burn = false # Burn/BurnChecked
allow_close_account = false # CloseAccount
allow_approve = false # Approve/ApproveChecked
allow_revoke = false # Revoke
allow_set_authority = false # SetAuthority
allow_mint_to = false # MintTo/MintToChecked
allow_initialize_mint = false # InitializeMint/InitializeMint2
allow_initialize_account = false # InitializeAccount/InitializeAccount3
allow_initialize_multisig = false # InitializeMultisig/InitializeMultisig2
allow_freeze_account = false # FreezeAccount
allow_thaw_account = false # ThawAccount

Instrucciones del System Program

OpciónDescripciónPredeterminadoTipo
allow_transferPermitir al pagador de tarifas como remitente en instrucciones Transfer/TransferWithSeedfalsebooleano
allow_assignPermitir al pagador de tarifas como autoridad en instrucciones Assign/AssignWithSeedfalsebooleano
allow_create_accountPermitir al pagador de tarifas como pagador de financiación en instrucciones CreateAccount/CreateAccountWithSeedfalsebooleano
allow_allocatePermitir al pagador de tarifas como propietario de cuenta en instrucciones Allocate/AllocateWithSeedfalsebooleano
nonce.allow_initializePermitir que el pagador de tarifas sea establecido como autoridad nonce en InitializeNonceAccountfalsebooleano
nonce.allow_advancePermitir al pagador de tarifas como autoridad en AdvanceNonceAccountfalsebooleano
nonce.allow_authorizePermitir al pagador de tarifas como autoridad actual en AuthorizeNonceAccountfalsebooleano
nonce.allow_withdrawPermitir al pagador de tarifas como autoridad en WithdrawNonceAccountfalsebooleano

Instrucciones del SPL Token Program

OpciónDescripciónPredeterminadoTipo
allow_transferPermitir al pagador de tarifas como propietario en instrucciones Transfer/TransferCheckedfalsebooleano
allow_burnPermitir al pagador de tarifas como propietario en instrucciones Burn/BurnCheckedfalsebooleano
allow_close_accountPermitir al pagador de tarifas como propietario en instrucciones CloseAccountfalsebooleano
allow_approvePermitir al pagador de tarifas como propietario en instrucciones Approve/ApproveCheckedfalsebooleano
allow_revokePermitir al pagador de tarifas como propietario en instrucciones Revokefalsebooleano
allow_set_authorityPermitir al pagador de tarifas como autoridad actual en instrucciones SetAuthorityfalsebooleano
allow_mint_toPermitir al pagador de tarifas como autoridad de acuñación en instrucciones MintTo/MintToCheckedfalsebooleano
allow_initialize_mintPermitir al pagador de tarifas como autoridad de acuñación en instrucciones InitializeMint/InitializeMint2falsebooleano
allow_initialize_accountPermitir al pagador de tarifas como propietario en instrucciones InitializeAccount/InitializeAccount3falsebooleano
allow_initialize_multisigPermitir al pagador de tarifas como firmante en instrucciones InitializeMultisig/InitializeMultisig2falsebooleano
allow_freeze_accountPermitir al pagador de tarifas como autoridad de congelación en instrucciones FreezeAccountfalsebooleano
allow_thaw_accountPermitir al pagador de tarifas como autoridad de congelación en instrucciones ThawAccountfalsebooleano

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ónDescripciónRequeridoTipo
typeModelo de precios a utilizar"margin", "fixed" o "free"
marginPorcentaje de margen a agregar a las tarifas de red(cuando type es "margin")número
amountCantidad fija a cobrar en unidades base del token(cuando type es "fixed")número
tokenMint 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 units
token = "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

  1. 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 transfers
    allow_create_account = false # Block account creation with lamports
    allow_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 transfers
    allow_burn = false # Block SPL token burning
    allow_close_account = false # Block SPL token account closures (returns rent)
    allow_mint_to = false # Block unauthorized SPL token minting
    allow_initialize_account = false # Block account initialization
  2. Habilita la Autenticación - Utiliza autenticación para prevenir el abuso:

    [kora.auth]
    api_key = "your-secure-api-key"
    # or
    hmac_secret = "your-minimum-32-character-hmac-secret"
  3. 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ón
  • allow_set_authority: Podría transferir el control de cuentas críticas a atacantes
  • allow_transfer: Habilita el drenaje directo de los saldos de tokens del pagador de tarifas
  • allow_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 = true
endpoint = "/metrics"
port = 8080
scrape_interval = 60
[metrics.fee_payer_balance]
enabled = true
expiry_seconds = 30
OpciónDescripciónRequeridoTipo
enabledHabilitar recopilación de métricasboolean
endpointRuta personalizada del endpoint de métricasstring
portPuerto del endpoint de métricasnumber
scrape_intervalFrecuencia 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ónDescripciónRequeridoTipo
enabledHabilitar seguimiento del saldo del pagador de comisiones❌ (predeterminado: false)boolean
expiry_secondsIntervalo 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 globally
rate_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 = true
url = "redis://localhost:6379"
default_ttl = 300 # 5 minutes
account_ttl = 60 # 1 minute
# Usage limiting (optional, prevents abuse)
[kora.usage_limit]
enabled = true
cache_url = "redis://localhost:6379" # Can share same Redis instance as cache
max_transactions = 100 # Per-wallet limit
fallback_if_unavailable = true # Don't block if Redis is down
# Disable unnecessary RPC methods for security
[kora.enabled_methods]
liveness = true
estimate_transaction_fee = true
get_supported_tokens = true
sign_transaction = false
sign_and_send_transaction = false
transfer_transaction = false
get_blockhash = true
get_config = true
get_payer_signer = true
[validation]
# Use production oracle
price_source = "Jupiter"
# Conservative transaction limits
max_allowed_lamports = 1000000 # 0.001 SOL max
max_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 allowlist
allowed_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 addresses
disallowed_accounts = [
"BadActor1111111111111111111111111111111111111111",
]
# Restrictive fee payer policy (recommended for production)
[validation.fee_payer_policy.system]
allow_transfer = false # Block SOL transfers from fee payer
allow_assign = false # Block account ownership changes
allow_create_account = false # Block creating accounts with fee payer funds
allow_allocate = false # Block allocating space for fee payer accounts
[validation.fee_payer_policy.system.nonce]
allow_initialize = false # Block nonce account initialization
allow_advance = false # Block nonce advancement
allow_authorize = false # Block nonce authority changes
allow_withdraw = false # Block nonce withdrawals
[validation.fee_payer_policy.spl_token]
allow_transfer = false # Critical: Block SPL transfers
allow_burn = false # Block token burning
allow_close_account = false # Block account closures
allow_approve = false # Block token approvals
allow_revoke = false # Block delegate revocations
allow_set_authority = false # Block authority changes
allow_mint_to = false # Block minting operations
allow_initialize_mint = false # Block mint initialization
allow_initialize_account = false # Block account initialization
allow_initialize_multisig = false # Block multisig initialization
allow_freeze_account = false # Block account freezing
allow_thaw_account = false # Block account thawing
[validation.fee_payer_policy.token_2022]
allow_transfer = false # Critical: Block Token2022 transfers
allow_burn = false # Block token burning
allow_close_account = false # Block account closures
allow_approve = false # Block token approvals
allow_revoke = false # Block delegate revocations
allow_set_authority = false # Block authority changes
allow_mint_to = false # Block minting operations
allow_initialize_mint = false # Block mint initialization
allow_initialize_account = false # Block account initialization
allow_initialize_multisig = false # Block multisig initialization
allow_freeze_account = false # Block account freezing
allow_thaw_account = false # Block account thawing
# Token-2022 extension blocking
[validation.token2022]
# Block potentially risky mint extensions
blocked_mint_extensions = [
"transfer_hook", # Custom transfer logic
"pausable", # Can freeze transfers
"permanent_delegate", # Permanent control
]
# Block complex account extensions
blocked_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 = true
endpoint = "/metrics"
port = 8080
scrape_interval = 60
# Fee payer balance monitoring
[metrics.fee_payer_balance]
enabled = true
expiry_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, weighted
strategy = "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

  1. Comienza de forma restrictiva: Inicia con límites estrictos y expándelos gradualmente
  2. Monitorea el uso: Rastrea qué programas y tokens se utilizan realmente
  3. Actualizaciones regulares: Revisa y actualiza las listas de bloqueo y límites
  4. Prueba los cambios: Valida los cambios de configuración primero en staging
  5. Control de versiones: Mantén un registro de cambios de tu configuración

¿Necesitas ayuda?

Is this page helpful?

Gestionado por

© 2026 Fundación Solana.
Todos los derechos reservados.
Conéctate