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 :
- Politiques principales de Kora - Paramètres principaux du serveur
- Authentification Kora - Paramètres d'authentification
- Mise en cache Kora - Mise en cache Redis pour les appels RPC
- Limites d'utilisation Kora - Limitation des transactions par portefeuille
- Méthodes activées Kora - Méthodes RPC Kora à activer
- Politiques de validation - Validation des transactions et sécurité
- Blocage des extensions Token-2022 - Bloquer les extensions Token-2022 à risque
- Politique du payeur de frais - Restrictions sur le portefeuille payeur de frais
- Configuration des prix - Modèles de tarification des frais de transaction
- Surveillance des performances - Collecte de métriques et surveillance
- Exemple complet - Configuration complète prête pour la production
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 = 100payment_address = "YourPaymentAddressPubkey11111111111111111111" # Optional
| Option | Description | Requis | Type |
|---|---|---|---|
rate_limit | Limite de débit globale (requêtes par seconde) pour tous les clients | ✅ | nombre |
payment_address | Adresse 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
| Option | Description | Requis | Type |
|---|---|---|---|
api_key | Clé API pour l'authentification simple | ❌ | chaîne |
hmac_secret | Secret HMAC pour l'authentification basée sur signature (min 32 caractères) | ❌ | chaîne |
max_timestamp_age | Durée maximale d'un horodatage HMAC en secondes | ❌ (défaut : 300) | nombre |
Note :
api_keyethmac_secretdé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 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)
| Option | Description | Requis | Type |
|---|---|---|---|
enabled | Activer la mise en cache Redis pour les appels RPC | ❌ (défaut : false) | booléen |
url | URL de connexion Redis (requis lorsque activé) | ✅ | chaîne |
default_ttl | TTL par défaut pour les entrées en cache en secondes | ❌ (défaut : 300) | nombre |
account_ttl | TTL 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 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
| Option | Description | Requis | Type |
|---|---|---|---|
enabled | Activer la limitation des transactions par portefeuille | ❌ (par défaut : false) | boolean |
cache_url | URL de connexion Redis pour le suivi partagé de l'utilisation | ❌ | string |
max_transactions | Nombre maximum de transactions par portefeuille (0 = illimité) | ❌ (par défaut : 100) | number |
fallback_if_unavailable | Autoriser 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_unavailableest défini sur true, le système autorise les transactions à se poursuivre si Redis est temporairement indisponible, évitant ainsi une interruption de service. Définirmax_transactionssur 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 = trueestimate_transaction_fee = trueget_supported_tokens = truesign_transaction = falsesign_and_send_transaction = falsetransfer_transaction = falseget_blockhash = trueget_config = trueget_payer_signer = true
| Option | Description de la méthode | Requis | Type |
|---|---|---|---|
liveness | Point de contrôle de santé | ✅ | boolean |
estimate_transaction_fee | Estimer les frais d'une transaction | ✅ | boolean |
get_supported_tokens | Lister les tokens acceptés | ✅ | boolean |
sign_transaction | Signer une transaction sans l'envoyer au réseau | ✅ | boolean |
sign_and_send_transaction | Signer une transaction et l'envoyer au réseau | ✅ | boolean |
transfer_transaction | Gérer les transferts de tokens | ✅ | boolean |
get_blockhash | Obtenir un blockhash récent | ✅ | boolean |
get_config | Retourner la configuration du serveur Kora | ✅ | boolean |
Remarque : si cette section est incluse dans votre fichier
kora.toml, toutes les méthodes doivent explicitement être définies surtrueoufalse.
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 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",]
| Option | Description | Requis | Type |
|---|---|---|---|
max_allowed_lamports | Définir un nombre maximum de lamports par transaction limite l'exposition du nœud Kora à une seule transaction. | ✅ | number |
max_signatures | Les 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_source | Oracle 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_transactions | Autoriser les transactions nonce durables. Voir Considérations de sécurité ci-dessous. | ❌ (par défaut : false) | boolean |
allowed_programs | Programmes Solana avec lesquels les transactions peuvent interagir | ✅ | Array of b58-encoded string |
allowed_tokens | Mints de tokens pouvant être utilisés dans les transactions | ✅ | Array of b58-encoded string |
allowed_spl_paid_tokens | Tokens SPL acceptés comme paiement pour les frais de transaction | ✅ | Array of b58-encoded string |
disallowed_accounts | Comptes explicitement bloqués pour les transactions | ✅ | Array 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_tokenssur 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'extension | Description |
|---|---|
confidential_transfer_mint | Configuration de transfert confidentiel pour la frappe |
confidential_mint_burn | Configuration de frappe et de destruction confidentielles |
transfer_fee_config | Configuration des frais de transfert |
mint_close_authority | Autorité autorisée à fermer la frappe |
interest_bearing_config | Configuration de jeton portant intérêt |
non_transferable | Rend les jetons non transférables |
permanent_delegate | Délégué permanent pour la frappe |
transfer_hook | Programme de hook de transfert personnalisé |
pausable | Configuration de jeton pouvant être mis en pause |
Extensions de compte disponibles
| Nom de l'extension | Description |
|---|---|
confidential_transfer_account | État de transfert confidentiel pour le compte |
non_transferable_account | Compte 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_transfer | Nécessite un mémo pour les transferts |
cpi_guard | Empêche certains appels CPI |
immutable_owner | Le 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_extensionsdans [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/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
Instructions du System Program
| Option | Description | Par défaut | Type |
|---|---|---|---|
allow_transfer | Autoriser le payeur de frais comme expéditeur dans les instructions Transfer/TransferWithSeed | false | booléen |
allow_assign | Autoriser le payeur de frais comme autorité dans les instructions Assign/AssignWithSeed | false | booléen |
allow_create_account | Autoriser le payeur de frais comme financeur dans les instructions CreateAccount/CreateAccountWithSeed | false | booléen |
allow_allocate | Autoriser le payeur de frais comme propriétaire du compte dans les instructions Allocate/AllocateWithSeed | false | booléen |
nonce.allow_initialize | Autoriser le payeur de frais à être défini comme autorité nonce dans InitializeNonceAccount | false | booléen |
nonce.allow_advance | Autoriser le payeur de frais comme autorité dans AdvanceNonceAccount | false | booléen |
nonce.allow_authorize | Autoriser le payeur de frais comme autorité actuelle dans AuthorizeNonceAccount | false | booléen |
nonce.allow_withdraw | Autoriser le payeur de frais comme autorité dans WithdrawNonceAccount | false | booléen |
Instructions du Token Program
| Option | Description | Par défaut | Type |
|---|---|---|---|
allow_transfer | Autoriser le payeur de frais comme propriétaire dans les instructions Transfer/TransferChecked | false | booléen |
allow_burn | Autoriser le payeur de frais comme propriétaire dans les instructions Burn/BurnChecked | false | booléen |
allow_close_account | Autoriser le payeur de frais comme propriétaire dans les instructions CloseAccount | false | booléen |
allow_approve | Autoriser le payeur de frais comme propriétaire dans les instructions Approve/ApproveChecked | false | booléen |
allow_revoke | Autoriser le payeur de frais comme propriétaire dans les instructions Revoke | false | booléen |
allow_set_authority | Autoriser le payeur de frais comme autorité actuelle dans les instructions SetAuthority | false | booléen |
allow_mint_to | Autoriser le payeur de frais comme autorité de frappe dans les instructions MintTo/MintToChecked | false | booléen |
allow_initialize_mint | Autoriser le payeur de frais comme autorité de frappe dans les instructions InitializeMint/InitializeMint2 | false | booléen |
allow_initialize_account | Autoriser le payeur de frais comme propriétaire dans les instructions InitializeAccount/InitializeAccount3 | false | booléen |
allow_initialize_multisig | Autoriser le payeur de frais comme signataire dans les instructions InitializeMultisig/InitializeMultisig2 | false | booléen |
allow_freeze_account | Autoriser le payeur de frais comme autorité de gel dans les instructions FreezeAccount | false | booléen |
allow_thaw_account | Autoriser le payeur de frais comme autorité de gel dans les instructions ThawAccount | false | boolé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)
| Option | Description | Requis | Type |
|---|---|---|---|
type | Modèle de tarification à utiliser | ✅ | "margin", "fixed" ou "free" |
margin | Pourcentage de marge à ajouter aux frais réseau | (lorsque type est "margin") | nombre |
amount | Montant fixe à facturer en unités de base du jeton | (lorsque type est "fixed") | nombre |
token | Mint 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 unitstoken = "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
-
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 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 -
Activer l'authentification - Utiliser l'authentification pour prévenir les abus :
[kora.auth]api_key = "your-secure-api-key"# orhmac_secret = "your-minimum-32-character-hmac-secret" -
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 frappeallow_set_authority: Pourrait transférer le contrôle de comptes critiques à des attaquantsallow_transfer: Permet le drainage direct des soldes de jetons du payeur de fraisallow_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 = trueendpoint = "/metrics"port = 8080scrape_interval = 60[metrics.fee_payer_balance]enabled = trueexpiry_seconds = 30
| Option | Description | Requis | Type |
|---|---|---|---|
enabled | Activer la collecte de métriques | ✅ | boolean |
endpoint | Chemin personnalisé du point de terminaison des métriques | ✅ | string |
port | Port du point de terminaison des métriques | ✅ | number |
scrape_interval | Fré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 :
| Option | Description | Requis | Type |
|---|---|---|---|
enabled | Activer le suivi du solde du payeur de frais | ❌ (par défaut : false) | boolean |
expiry_seconds | Intervalle 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 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
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, weightedstrategy = "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
- Commencez de manière restrictive : Démarrez avec des limites strictes et élargissez progressivement
- Surveillez l'utilisation : Suivez les programmes et jetons réellement utilisés
- Mises à jour régulières : Révisez et mettez à jour les listes de blocage et les limites
- Testez les modifications : Validez les changements de configuration en staging d'abord
- Gestion des versions : Tenez un journal des modifications de votre configuration
Besoin d'aide ?
- Consultez le Guide d'authentification pour la configuration de l'authentification
- Consultez le Guide des signataires pour la configuration des signataires
- Consultez le Guide de l'opérateur pour plus d'informations sur l'exécution d'un nœud Kora
- Visitez Solana Stack Exchange avec le tag
kora - Signalez les problèmes sur GitHub
Is this page helpful?