Configuração

Usando Kora v2.2.0-beta? Consulte Configuração Beta para novas opções: Pacotes Jito, proteção Lighthouse, reCAPTCHA e limites de uso.

O seu nó Kora estará assinando transações para os seus usuários, portanto é importante configurá-lo para assinar apenas transações que atendam aos seus requisitos de negócio. O Kora oferece muita flexibilidade na forma como você configura o seu nó, mas é importante entender as implicações da sua configuração. kora.toml é o centro de controle para a sua configuração do Kora. Este documento fornece uma referência abrangente para configurar o seu nó pagador Kora através do arquivo de configuração kora.toml.

Visão Geral

O arquivo kora.toml controla todos os aspectos do comportamento do seu nó Kora, incluindo:

• Limitação de taxa e autenticação
• Disponibilidade de métodos RPC
• Regras de validação de transação
• Modelos de precificação de taxas
• Políticas de segurança
• Disponibilidade de métodos RPC
• Modelos de precificação de taxas
• Configuração de endereço de pagamento
• Monitoramento de desempenho

O seu arquivo de configuração deve ser colocado no seu diretório de implantação ou especificado através do sinalizador --config ao iniciar o servidor.

Seções de Configuração

O arquivo kora.toml está organizado em seções, cada uma com seu próprio conjunto de opções. Este guia explica cada seção e as opções disponíveis:

• Políticas Principais do Kora - Configurações principais do servidor
• Autenticação do Kora - Configurações de autenticação
• Cache do Kora - Cache Redis para chamadas RPC
• Limites de Uso do Kora - Limitação de transações por carteira
• Métodos Habilitados do Kora - Métodos RPC do Kora a habilitar
• Políticas de Validação - Validação de transação e segurança
• Bloqueio de Extensão Token-2022 - Bloquear extensões Token-2022 de risco
• Política do Pagador de Taxa - Restrições na carteira do pagador de taxa
• Configuração de Preço - Modelos de precificação de taxa de transação
• Monitoramento de Desempenho - Coleta de métricas e monitoramento
• Exemplo Completo - Configuração completa pronta para produção

Exemplos de seções do arquivo kora.toml:

[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 Principais do Kora

A seção [kora] configura o comportamento principal do servidor:

[kora]
rate_limit = 100
payment_address = "YourPaymentAddressPubkey11111111111111111111"  # Optional

Autenticação do Kora

A seção [kora.auth] configura a autenticação para o servidor Kora:

[kora.auth]
api_key = "kora_live_sk_1234567890abcdef"
hmac_secret = "kora_hmac_your-strong-hmac-secret-key-here"
max_timestamp_age = 300

Nota: api_key e hmac_secret definem uma política de autenticação global para todos os clientes. Para configuração detalhada de autenticação, consulte o Guia de Autenticação.

Cache do Kora (opcional)

A seção [kora.cache] configura o cache baseado em Redis para chamadas RPC do Solana. Isso pode melhorar significativamente o desempenho ao reduzir buscas redundantes de dados de contas:

[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)

Nota: Quando o cache está habilitado, uma instância Redis deve estar disponível na URL especificada. O cache recorre automaticamente a chamadas RPC diretas se o Redis estiver indisponível.

Limites de Uso do Kora (opcional)

A seção [kora.usage_limit] configura a limitação de transações por carteira para prevenir abusos e garantir uso justo entre seus usuários. Isso também pode ser usado para criar programas de recompensas para subsidiar as taxas de transação dos usuários até um determinado limite.

Importante: Atualmente, a única forma de limitação de uso suportada pelo Kora é um limite permanente. Uma vez que uma carteira atinge seu limite de transações, ele não pode ser redefinido e o usuário não poderá mais enviar transações usando essa mesma carteira. Este limite persiste até ser removido manualmente do Redis ou os dados do Redis serem redefinidos.

Nota: Este recurso requer Redis quando habilitado em múltiplas instâncias do 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

Nota: Os limites de uso são rastreados por endereço de carteira com expiração automática baseada em TTL. Quando fallback_if_unavailable está definido como true, o sistema permite que as transações prossigam se o Redis estiver temporariamente indisponível, prevenindo interrupção do serviço. Definir max_transactions como 0 permitirá transações ilimitadas.

Métodos Habilitados do Kora (opcional)

A seção [kora.enabled_methods] controla quais métodos RPC estão habilitados. Esta seção é opcional e, por padrão, todos os métodos estão habilitados. Cada método pode ser habilitado ou desabilitado definindo o valor como true ou 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

Nota: se esta seção estiver incluída no seu arquivo kora.toml, todos os métodos devem ser explicitamente definidos como true ou false.

Políticas de Validação

A seção [validation] define regras de segurança relacionadas ao Solana e limites de transação:

[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",
]

Nota: Arrays vazios são permitidos, mas você precisará especificar pelo menos um allowed_programs, allowed_tokens, allowed_spl_paid_tokens na lista de permissões para que o nó Kora possa processar transações. Você precisa especificar o System Program ou Token Program para que o nó Kora possa processar transferências. Para habilitar tipos de instruções comuns (por exemplo, Compute Budget, Address Lookup Table), você precisa especificar o Compute Budget Program ou Address Lookup Table Program, etc.

Segurança de Transações Duráveis

AVISO DE SEGURANÇA: Transações com nonce durável permitem que transações assinadas sejam mantidas indefinidamente e enviadas posteriormente. Isso pode ser usado como um vetor de ataque econômico onde alguém poderia obter uma transação assinada e esperar para enviá-la até que as condições de mercado sejam favoráveis a eles (por exemplo, quando o valor do SOL tenha caído ou o valor do token de pagamento tenha aumentado).

Por padrão, allow_durable_transactions está definido como false para bloquear todas as transações com nonce durável. Habilite isso apenas se sua aplicação especificamente requer transações duráveis e você compreende os riscos.

Se você deve habilitar transações duráveis, considere:

• Usar autenticação para restringir o acesso à API
• Implementar validação off-chain adicional
• Monitorar padrões de transações incomuns
• Monitorar e limitar saldos de contas de assinantes
• Rotacionar chaves de assinantes regularmente

Saiba mais sobre transações com nonce durável na Documentação Solana.

Bloqueio de Extensões Token-2022

A seção [validation.token2022] permite que você bloqueie extensões específicas do Token-2022 para segurança aprimorada. Todas as extensões estão habilitadas por padrão. Você pode bloquear extensões específicas adicionando-as aos arrays blocked_mint_extensions ou 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
]

Extensões de Mint Disponíveis

Extensões de Conta Disponíveis

transfer_hook

Considerações de Segurança

Extensão PermanentDelegate - Tokens com esta extensão permitem que o delegado transfira/queime tokens a qualquer momento sem aprovação do proprietário. Isto cria riscos significativos para o operador do nó Kora, pois os fundos de pagamento podem ser apreendidos após o pagamento.

• Considere adicionar "permanent_delegate" a blocked_mint_extensions em [validation.token2022] a menos que seja explicitamente necessário para o seu caso de uso.
• Evite usar tokens de pagamento com a extensão permanent_delegate.

Política do Pagador de Taxas

A seção [validation.fee_payer_policy] fornece controle granular sobre quais ações a carteira do pagador de taxas do seu nó Kora pode executar. A política está organizada por tipo de programa (System, SPL Token, Token-2022) e cobre todos os diferentes tipos de instruções. Isso impede comportamentos inesperados de transações de usuários que utilizam seu nó Kora como signatário.

Por exemplo, se spl_token.allow_transfer estiver definido como false, o nó Kora não assinará transações que incluam uma transferência de token SPL onde o pagador de taxas do nó Kora seja a autoridade de transferência.

[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

Instruções do System Program

Instruções do SPL Token Program

Token-2022 suporta o mesmo conjunto de instruções que o SPL Token com opções de configuração idênticas (na seção [validation.fee_payer_policy.token_2022]).

Considerações de Segurança

AVISO DE SEGURANÇA: Por razões de segurança, recomenda-se definir todas essas opções como false (padrão) e habilitar apenas conforme necessário. Isso impedirá comportamentos indesejados, como usuários esgotando sua conta de pagador de taxas ou queimando tokens da sua conta de pagador de taxas. Isso previne:

• Drenagem de Conta: Usuários transferindo SOL ou tokens da sua conta de pagador de taxas
• Tomada de Autoridade: Usuários alterando autoridades em contas pertencentes ao seu pagador de taxas
• Cunhagem Não Autorizada: Usuários cunhando tokens se o seu pagador de taxas tiver autoridade de cunhagem
• Manipulação de Conta: Usuários congelando, fechando ou modificando contas controladas pelo seu pagador de taxas

Melhor Prática: Comece com todas as permissões desabilitadas e habilite apenas o conjunto mínimo necessário para o seu caso de uso específico.

Configuração de Preços (opcional)

A seção [validation.price] define como as taxas de transação são calculadas. Três modelos de precificação estão disponíveis:

• Precificação com Margem (padrão) - Adiciona uma margem percentual sobre as taxas reais da rede (margem padrão é 0.0)
• Precificação Fixa - Cobra um valor fixo em um token específico, independentemente das taxas da rede
• Precificação Gratuita - Patrocina todas as taxas de transação (sem cobrança aos usuários)

Preços com Margem

Adicione uma margem percentual sobre as taxas reais da rede:

[validation.price]
type = "margin"
margin = 0.1  # 10% margin (0.1 = 10%, 1.0 = 100%)

Preços Fixos

AVISO DE SEGURANÇA: Os preços fixos NÃO incluem a saída do pagador de taxas no valor cobrado. Isso pode permitir que usuários esgotem sua conta pagadora de taxas se não for configurado adequadamente.

Cobre um valor fixo em um token específico independentemente das taxas da rede:

[validation.price]
type = "fixed"
amount = 1000000  # Amount in token's base units
token = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"  # USDC mint

Transações Gratuitas

Patrocine todas as taxas de transação (sem cobrança aos usuários):

[validation.price]
type = "free"

Medidas de Segurança ao Usar Preços Fixos/Gratuitos

1. Desabilite Todas as Transferências e Operações Monetárias - Impeça que o pagador de taxas seja usado como origem em transferências:

   [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. Habilite Autenticação - Use autenticação para prevenir abusos:

   [kora.auth]
   api_key = "your-secure-api-key"
   # or
   hmac_secret = "your-minimum-32-character-hmac-secret"

3. Defina Limites Conservadores - Minimize a exposição:

   [validation]
   max_allowed_lamports = 1000000  # 0.001 SOL maximum

AVISO: Operações particularmente perigosas ao usar preços fixos/gratuitos:

• allow_mint_to: Poderia permitir criação ilimitada de tokens se o pagador de taxas tiver autoridade de cunhagem
• allow_set_authority: Poderia transferir controle de contas críticas para invasores
• allow_transfer: Permite drenagem direta dos saldos de tokens do pagador de taxas
• allow_close_account: Devolve aluguel para contas controladas por invasores

Monitoramento de Desempenho (opcional)

A seção [metrics] configura a coleta e monitoramento de métricas. Esta seção é opcional e, por padrão, as métricas estão desabilitadas.

[metrics]
enabled = true
endpoint = "/metrics"
port = 8080
scrape_interval = 60

[metrics.fee_payer_balance]
enabled = true
expiry_seconds = 30

Rastreamento do Saldo do Pagador de Taxas

A seção [metrics.fee_payer_balance] configura o monitoramento automático do saldo SOL do seu pagador de taxas:

Quando ativado, o Kora rastreia automaticamente o saldo SOL do seu pagador de taxas e o expõe através da métrica Prometheus fee_payer_balance_lamports. Isso auxilia no planejamento de capacidade e alertas de saldo baixo.

http://localhost:{port}/{metrics-endpoint}

→ Guia de Referência de Monitoramento do Kora

Exemplo Completo

Aqui está uma configuração pronta para produção com práticas recomendadas de segurança:

# 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

Validação da Configuração

O Kora valida sua configuração na inicialização. Se você deseja validar sua configuração sem iniciar o servidor, pode usar o comando de validação de configuração:

kora --config kora.toml config validate # or validate-with-rpc

Você também pode executar o comando validate-with-rpc para validar sua configuração com o servidor RPC (essa verificação de validação é um pouco mais lenta, mas realiza verificações de conta mais minuciosas)

Iniciando o Servidor

Depois de configurar seu arquivo kora.toml, você pode iniciar o servidor Kora:

kora --config path/to/kora.toml rpc start --no-load-signer # --other-rpc-flags-here

A flag --no-load-signer irá inicializar o servidor sem carregar nenhum assinante. Isso é útil para testar sua configuração. Para carregar assinantes, você precisará configurar o arquivo signers.toml. Uma configuração mínima com um único assinante seria assim:

[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"

Isso carregará um único assinante da variável de ambiente MY_SIGNER_PRIVATE_KEY. Então você pode iniciar seu servidor com:

kora --config path/to/kora.toml rpc start --signers-config path/to/signers.toml

Para mais informações e configuração avançada de signatários, consulte o Guia de Signatários.

Melhores Práticas

1. Comece Restritivo: Inicie com limites rigorosos e expanda gradualmente
2. Monitore o Uso: Acompanhe quais programas e tokens são realmente utilizados
3. Atualizações Regulares: Revise e atualize listas de bloqueio e limites
4. Teste as Alterações: Valide as mudanças de configuração primeiro em ambiente de testes
5. Versionamento: Mantenha um registro de alterações das suas configurações

Precisa de Ajuda?

• Consulte o Guia de Autenticação para configuração de autenticação
• Consulte o Guia de Signatários para configuração de signatários
• Consulte o Guia do Operador para mais informações sobre como executar um nó Kora
• Visite o Solana Stack Exchange com a tag kora
• Reporte problemas no GitHub