Configuration

Vous utilisez Kora v2.2.0-beta ? Consultez Configuration Beta pour les nouvelles options : Bundles Jito, protection Lighthouse, reCAPTCHA et limites d'utilisation.

Votre nœud Kora signera des transactions pour vos utilisateurs, il est donc important de le configurer pour qu'il ne signe que les transactions qui répondent aux exigences de votre entreprise. Kora vous offre une grande flexibilité dans la configuration de votre nœud, mais il est important de comprendre les implications de votre configuration. kora.toml est le centre de contrôle de votre configuration Kora. Ce document fournit une référence complète pour configurer votre nœud paymaster Kora via le fichier de configuration kora.toml.

Aperçu

Le fichier kora.toml contrôle tous les aspects du comportement de votre nœud Kora, notamment :

  • Limitation de débit et authentification
  • Disponibilité des méthodes RPC
  • Règles de validation des transactions
  • Modèles de tarification des frais
  • Politiques de sécurité
  • Disponibilité des méthodes RPC
  • Modèles de tarification des frais
  • Configuration des adresses de paiement
  • Surveillance des performances

Votre fichier de configuration doit être placé dans votre répertoire de déploiement ou spécifié via le flag --config lors du démarrage du serveur.

Sections de configuration

Le fichier kora.toml est organisé en sections, chacune avec son propre ensemble d'options. Ce guide parcourt chaque section et explique les options disponibles :

Exemples de sections du fichier 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

Politiques de base de Kora

La section [kora] configure le comportement de base du serveur :

[kora]
rate_limit = 100
payment_address = "YourPaymentAddressPubkey11111111111111111111" # Optional
OptionDescriptionRequisType
rate_limitLimite de débit globale (requêtes par seconde) pour tous les clientsnombre
payment_addressAdresse de paiement optionnelle pour recevoir les jetons de paiement (par défaut l'adresse du signataire si non spécifiée)chaîne encodée b58

Authentification Kora

La section [kora.auth] configure l'authentification pour le serveur Kora :

[kora.auth]
api_key = "kora_live_sk_1234567890abcdef"
hmac_secret = "kora_hmac_your-strong-hmac-secret-key-here"
max_timestamp_age = 300
OptionDescriptionRequisType
api_keyClé API pour l'authentification simplechaîne
hmac_secretSecret HMAC pour l'authentification basée sur signature (min 32 caractères)chaîne
max_timestamp_ageDurée maximale d'un horodatage HMAC en secondes❌ (défaut : 300)nombre

Note : api_key et hmac_secret définissent une politique d'authentification globale pour tous les clients. Pour une configuration détaillée de l'authentification, consultez le Guide d'authentification.

Mise en cache Kora (optionnel)

La section [kora.cache] configure la mise en cache basée sur Redis pour les appels RPC Solana. Cela peut considérablement améliorer les performances en réduisant les récupérations redondantes de données de compte :

[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)
OptionDescriptionRequisType
enabledActiver la mise en cache Redis pour les appels RPC❌ (défaut : false)booléen
urlURL de connexion Redis (requis lorsque activé)chaîne
default_ttlTTL par défaut pour les entrées en cache en secondes❌ (défaut : 300)nombre
account_ttlTTL pour le cache des données de compte en secondes❌ (défaut : 60)nombre

Remarque : Lorsque la mise en cache est activée, une instance Redis doit être disponible à l'URL spécifiée. Le cache bascule automatiquement vers des appels RPC directs si Redis est indisponible.

Limites d'utilisation de Kora (optionnel)

La section [kora.usage_limit] configure la limitation des transactions par portefeuille pour prévenir les abus et garantir une utilisation équitable entre vos utilisateurs. Cela peut également être utilisé pour créer des programmes de récompenses afin de subventionner les frais de transaction des utilisateurs jusqu'à une certaine limite.

Important : Actuellement, la seule forme de limitation d'utilisation prise en charge par Kora est une limite permanente. Une fois qu'un portefeuille atteint sa limite de transactions, elle ne peut pas être réinitialisée et l'utilisateur ne pourra plus soumettre de transactions en utilisant ce même portefeuille. Cette limite persiste jusqu'à ce qu'elle soit supprimée manuellement de Redis ou que les données Redis soient réinitialisées.

Remarque : Cette fonctionnalité nécessite Redis lorsqu'elle est activée sur plusieurs instances 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
OptionDescriptionRequisType
enabledActiver la limitation des transactions par portefeuille❌ (par défaut : false)boolean
cache_urlURL de connexion Redis pour le suivi partagé de l'utilisationstring
max_transactionsNombre maximum de transactions par portefeuille (0 = illimité)❌ (par défaut : 100)number
fallback_if_unavailableAutoriser les transactions si Redis est indisponible❌ (par défaut : true)boolean

Remarque : Les limites d'utilisation sont suivies par adresse de portefeuille avec expiration automatique basée sur le TTL. Lorsque fallback_if_unavailable est défini sur true, le système autorise les transactions à se poursuivre si Redis est temporairement indisponible, évitant ainsi une interruption de service. Définir max_transactions sur 0 autorisera un nombre illimité de transactions.

Méthodes Kora activées (facultatif)

La section [kora.enabled_methods] contrôle quelles méthodes RPC sont activées. Cette section est facultative et par défaut, toutes les méthodes sont activées. Chaque méthode peut être activée ou désactivée en définissant la valeur sur 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
OptionDescription de la méthodeRequisType
livenessPoint de contrôle de santéboolean
estimate_transaction_feeEstimer les frais d'une transactionboolean
get_supported_tokensLister les tokens acceptésboolean
sign_transactionSigner une transaction sans l'envoyer au réseauboolean
sign_and_send_transactionSigner une transaction et l'envoyer au réseauboolean
transfer_transactionGérer les transferts de tokensboolean
get_blockhashObtenir un blockhash récentboolean
get_configRetourner la configuration du serveur Koraboolean

Remarque : si cette section est incluse dans votre fichier kora.toml, toutes les méthodes doivent explicitement être définies sur true ou false.

Politiques de validation

La section [validation] définit les règles de sécurité liées à Solana et les limites de transaction :

[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",
]
OptionDescriptionRequisType
max_allowed_lamportsDéfinir un nombre maximum de lamports par transaction limite l'exposition du nœud Kora à une seule transaction.number
max_signaturesLes frais de base Solana sont fonction du nombre de signatures dans une transaction, donc définir un nombre maximum de signatures par transaction est un bon moyen d'empêcher les utilisateurs de dépenser trop de SOL sur une seule transaction.number
price_sourceOracle pour les données de prix des tokens. Remarque : Lorsque défini sur "Jupiter", la variable d'environnement JUPITER_API_KEY est requise. Le serveur ne démarrera pas sans elle."Jupiter" ou "Mock"
allow_durable_transactionsAutoriser les transactions nonce durables. Voir Considérations de sécurité ci-dessous.❌ (par défaut : false)boolean
allowed_programsProgrammes Solana avec lesquels les transactions peuvent interagirArray of b58-encoded string
allowed_tokensMints de tokens pouvant être utilisés dans les transactionsArray of b58-encoded string
allowed_spl_paid_tokensTokens SPL acceptés comme paiement pour les frais de transactionArray of b58-encoded string
disallowed_accountsComptes explicitement bloqués pour les transactionsArray of b58-encoded string

Remarque : Les tableaux vides sont autorisés, mais vous devrez spécifier au moins un allowed_programs, allowed_tokens, allowed_spl_paid_tokens sur liste blanche pour que le nœud Kora puisse traiter les transactions. Vous devez spécifier le System Program ou Token Program pour que le nœud Kora puisse traiter les transferts. Pour activer les types d'instructions courants (par ex., Budget de calcul, Table de recherche d'adresses), vous devez spécifier le Compute Budget Program ou Address Lookup Table Program, etc.

Sécurité des transactions durables

AVERTISSEMENT DE SÉCURITÉ : Les transactions à nonce durable permettent de conserver indéfiniment les transactions signées et de les soumettre ultérieurement. Cela pourrait être utilisé comme vecteur d'attaque économique où quelqu'un pourrait obtenir une transaction signée et attendre pour la soumettre jusqu'à ce que les conditions du marché lui soient favorables (par ex., lorsque la valeur du SOL a chuté ou que la valeur du jeton de paiement a augmenté).

Par défaut, allow_durable_transactions est défini sur false pour bloquer toutes les transactions à nonce durable. N'activez cette option que si votre application nécessite spécifiquement des transactions durables et que vous comprenez les risques.

Si vous devez activer les transactions durables, envisagez de :

  • Utiliser l'authentification pour restreindre l'accès à l'API
  • Implémenter une validation hors chaîne supplémentaire
  • Surveiller les schémas de transactions inhabituels
  • Surveiller et limiter les soldes des comptes signataires
  • Effectuer une rotation régulière des clés de signataire

Apprenez-en davantage sur les transactions à nonce durable dans la documentation Solana.

Blocage des extensions Token-2022

La section [validation.token2022] vous permet de bloquer des extensions Token-2022 spécifiques pour une sécurité renforcée. Toutes les extensions sont activées par défaut. Vous pouvez bloquer des extensions spécifiques en les ajoutant aux tableaux 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
]

Extensions de frappe disponibles

Nom de l'extensionDescription
confidential_transfer_mintConfiguration de transfert confidentiel pour la frappe
confidential_mint_burnConfiguration de frappe et de destruction confidentielles
transfer_fee_configConfiguration des frais de transfert
mint_close_authorityAutorité autorisée à fermer la frappe
interest_bearing_configConfiguration de jeton portant intérêt
non_transferableRend les jetons non transférables
permanent_delegateDélégué permanent pour la frappe
transfer_hookProgramme de hook de transfert personnalisé
pausableConfiguration de jeton pouvant être mis en pause

Extensions de compte disponibles

Nom de l'extensionDescription
confidential_transfer_accountÉtat de transfert confidentiel pour le compte
non_transferable_accountCompte de jeton non transférable
transfer_hook_accountÉtat du hook de transfert pour le compte
pausable_accountÉtat du compte de jeton pouvant être mis en pause
memo_transferNécessite un mémo pour les transferts
cpi_guardEmpêche certains appels CPI
immutable_ownerLe propriétaire du compte ne peut pas être modifié
default_account_stateÉtat par défaut pour les nouveaux comptes

transfer_hook

Considérations de sécurité

Extension PermanentDelegate - Les jetons avec cette extension permettent au délégué de transférer/détruire des jetons à tout moment sans l'approbation du propriétaire. Cela crée des risques significatifs pour l'opérateur de nœud Kora car les fonds de paiement peuvent être saisis après le paiement.

  • Envisagez d'ajouter "permanent_delegate" à blocked_mint_extensions dans [validation.token2022] sauf si explicitement nécessaire pour votre cas d'utilisation.
  • Évitez d'utiliser des jetons de paiement avec l'extension permanent_delegate.

Politique du payeur de frais

La section [validation.fee_payer_policy] offre un contrôle granulaire sur les actions que le portefeuille payeur de frais de votre nœud Kora peut effectuer. La politique est organisée par type de programme (System Program, Token Program, Token-2022) et couvre tous les différents types d'instructions. Cela empêche les comportements inattendus provenant des transactions des utilisateurs utilisant votre nœud Kora comme signataire.

Par exemple, si spl_token.allow_transfer est défini sur false, le nœud Kora ne signera pas les transactions qui incluent un transfert de jeton SPL où le payeur de frais du nœud Kora est l'autorité de transfert.

[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

Instructions du System Program

OptionDescriptionPar défautType
allow_transferAutoriser le payeur de frais comme expéditeur dans les instructions Transfer/TransferWithSeedfalsebooléen
allow_assignAutoriser le payeur de frais comme autorité dans les instructions Assign/AssignWithSeedfalsebooléen
allow_create_accountAutoriser le payeur de frais comme financeur dans les instructions CreateAccount/CreateAccountWithSeedfalsebooléen
allow_allocateAutoriser le payeur de frais comme propriétaire du compte dans les instructions Allocate/AllocateWithSeedfalsebooléen
nonce.allow_initializeAutoriser le payeur de frais à être défini comme autorité nonce dans InitializeNonceAccountfalsebooléen
nonce.allow_advanceAutoriser le payeur de frais comme autorité dans AdvanceNonceAccountfalsebooléen
nonce.allow_authorizeAutoriser le payeur de frais comme autorité actuelle dans AuthorizeNonceAccountfalsebooléen
nonce.allow_withdrawAutoriser le payeur de frais comme autorité dans WithdrawNonceAccountfalsebooléen

Instructions du Token Program

OptionDescriptionPar défautType
allow_transferAutoriser le payeur de frais comme propriétaire dans les instructions Transfer/TransferCheckedfalsebooléen
allow_burnAutoriser le payeur de frais comme propriétaire dans les instructions Burn/BurnCheckedfalsebooléen
allow_close_accountAutoriser le payeur de frais comme propriétaire dans les instructions CloseAccountfalsebooléen
allow_approveAutoriser le payeur de frais comme propriétaire dans les instructions Approve/ApproveCheckedfalsebooléen
allow_revokeAutoriser le payeur de frais comme propriétaire dans les instructions Revokefalsebooléen
allow_set_authorityAutoriser le payeur de frais comme autorité actuelle dans les instructions SetAuthorityfalsebooléen
allow_mint_toAutoriser le payeur de frais comme autorité de frappe dans les instructions MintTo/MintToCheckedfalsebooléen
allow_initialize_mintAutoriser le payeur de frais comme autorité de frappe dans les instructions InitializeMint/InitializeMint2falsebooléen
allow_initialize_accountAutoriser le payeur de frais comme propriétaire dans les instructions InitializeAccount/InitializeAccount3falsebooléen
allow_initialize_multisigAutoriser le payeur de frais comme signataire dans les instructions InitializeMultisig/InitializeMultisig2falsebooléen
allow_freeze_accountAutoriser le payeur de frais comme autorité de gel dans les instructions FreezeAccountfalsebooléen
allow_thaw_accountAutoriser le payeur de frais comme autorité de gel dans les instructions ThawAccountfalsebooléen

Token-2022 prend en charge le même jeu d'instructions que SPL Token avec des options de configuration identiques (dans la section [validation.fee_payer_policy.token_2022]).

Considérations de sécurité

AVERTISSEMENT DE SÉCURITÉ : Pour des raisons de sécurité, il est recommandé de définir toutes ces options sur false (par défaut) et de les activer uniquement en cas de besoin. Cela empêchera les comportements indésirables tels que le drainage de votre compte payeur de frais par les utilisateurs ou la destruction de jetons depuis votre compte payeur de frais. Cela empêche :

  • Drainage de compte : Les utilisateurs transférant des SOL ou des jetons depuis votre compte payeur de frais
  • Prise de contrôle d'autorité : Les utilisateurs modifiant les autorisations sur les comptes détenus par votre payeur de frais
  • Frappe non autorisée : Les utilisateurs frappant des jetons si votre payeur de frais dispose de l'autorité de frappe
  • Manipulation de compte : Les utilisateurs gelant, fermant ou modifiant des comptes contrôlés par votre payeur de frais

Bonne pratique : Commencez avec toutes les permissions désactivées et activez uniquement l'ensemble minimum nécessaire pour votre cas d'usage spécifique.

Configuration des prix (optionnel)

La section [validation.price] définit comment les frais de transaction sont calculés. Trois modèles de tarification sont disponibles :

  • Tarification à la marge (par défaut) - Ajouter un pourcentage de marge en plus des frais réseau réels (la marge par défaut est de 0,0)
  • Tarification fixe - Facturer un montant fixe dans un jeton spécifique indépendamment des frais réseau
  • Tarification gratuite - Parrainer tous les frais de transaction (aucun frais pour les utilisateurs)
OptionDescriptionRequisType
typeModèle de tarification à utiliser"margin", "fixed" ou "free"
marginPourcentage de marge à ajouter aux frais réseau(lorsque type est "margin")nombre
amountMontant fixe à facturer en unités de base du jeton(lorsque type est "fixed")nombre
tokenMint du jeton à facturer(lorsque type est "fixed")chaîne encodée en b58

Tarification avec marge

Ajouter un pourcentage de marge en plus des frais de réseau réels :

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

Tarification fixe

AVERTISSEMENT DE SÉCURITÉ : La tarification fixe n'inclut PAS les sorties du payeur de frais dans le montant facturé. Cela peut permettre aux utilisateurs de vider votre compte payeur de frais s'il n'est pas correctement configuré.

Facturer un montant fixe dans un jeton spécifique indépendamment des frais de réseau :

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

Transactions gratuites

Sponsoriser tous les frais de transaction (aucun frais pour les utilisateurs) :

[validation.price]
type = "free"

Mesures de sécurité lors de l'utilisation de la tarification fixe/gratuite

  1. Désactiver tous les transferts et opérations monétaires - Empêcher que le payeur de frais soit utilisé comme source dans les transferts :

    [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. Activer l'authentification - Utiliser l'authentification pour prévenir les abus :

    [kora.auth]
    api_key = "your-secure-api-key"
    # or
    hmac_secret = "your-minimum-32-character-hmac-secret"
  3. Définir des limites conservatrices - Minimiser l'exposition :

    [validation]
    max_allowed_lamports = 1000000 # 0.001 SOL maximum

AVERTISSEMENT : Opérations particulièrement dangereuses lors de l'utilisation de la tarification fixe/gratuite :

  • allow_mint_to : Pourrait permettre une création illimitée de jetons si le payeur de frais dispose de l'autorité de frappe
  • allow_set_authority : Pourrait transférer le contrôle de comptes critiques à des attaquants
  • allow_transfer : Permet le drainage direct des soldes de jetons du payeur de frais
  • allow_close_account : Renvoie le loyer vers des comptes contrôlés par l'attaquant

Surveillance des performances (facultatif)

La section [metrics] configure la collecte de métriques et la surveillance. Cette section est facultative et par défaut, les métriques sont désactivées.

[metrics]
enabled = true
endpoint = "/metrics"
port = 8080
scrape_interval = 60
[metrics.fee_payer_balance]
enabled = true
expiry_seconds = 30
OptionDescriptionRequisType
enabledActiver la collecte de métriquesboolean
endpointChemin personnalisé du point de terminaison des métriquesstring
portPort du point de terminaison des métriquesnumber
scrape_intervalFréquence de scrape Prometheus (secondes)number

Suivi du solde du payeur de frais

La section [metrics.fee_payer_balance] configure la surveillance automatique du solde SOL de votre payeur de frais :

OptionDescriptionRequisType
enabledActiver le suivi du solde du payeur de frais❌ (par défaut : false)boolean
expiry_secondsIntervalle de suivi en arrière-plan en secondes❌ (par défaut : 30)number

Lorsqu'elle est activée, Kora suit automatiquement le solde SOL de votre payeur de frais et l'expose via la jauge Prometheus fee_payer_balance_lamports. Cela facilite la planification de capacité et les alertes en cas de solde faible.

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

→ Guide de référence de surveillance Kora

Exemple complet

Voici une configuration prête pour la production avec les meilleures pratiques de sécurité :

# 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

Validation de la configuration

Kora valide votre configuration au démarrage. Si vous souhaitez valider votre configuration sans démarrer le serveur, vous pouvez utiliser la commande de validation de configuration :

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

Vous pouvez également exécuter la commande validate-with-rpc pour valider votre configuration avec le serveur RPC (cette vérification de validation est un peu plus lente mais effectue des vérifications de compte plus approfondies)

Démarrage du serveur

Une fois que vous avez configuré votre fichier kora.toml, vous pouvez démarrer le serveur Kora :

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

Le flag --no-load-signer initialisera le serveur sans charger aucun signataire. Cela est utile pour tester votre configuration. Afin de charger des signataires, vous devrez configurer le fichier signers.toml. Une configuration minimale avec un seul signataire ressemblerait à ceci :

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

Cela chargera un seul signataire à partir de la variable d'environnement MY_SIGNER_PRIVATE_KEY. Ensuite, vous pouvez démarrer votre serveur avec :

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

Pour plus d'informations et une configuration avancée des signataires, consultez le Guide des signataires.

Bonnes pratiques

  1. Commencez de manière restrictive : Démarrez avec des limites strictes et élargissez progressivement
  2. Surveillez l'utilisation : Suivez les programmes et jetons réellement utilisés
  3. Mises à jour régulières : Révisez et mettez à jour les listes de blocage et les limites
  4. Testez les modifications : Validez les changements de configuration en staging d'abord
  5. Gestion des versions : Tenez un journal des modifications de votre configuration

Besoin d'aide ?

Is this page helpful?

Géré par

© 2026 Fondation Solana.
Tous droits réservés.
Restez connecté