Configurazione

Stai usando Kora v2.2.0-beta? Consulta Configurazione Beta per le nuove opzioni: bundle Jito, protezione Lighthouse, reCAPTCHA e limiti di utilizzo.

Il tuo nodo Kora firmerà transazioni per i tuoi utenti, quindi è importante configurarlo in modo che firmi solo le transazioni che soddisfano i requisiti della tua attività. Kora ti offre molta flessibilità nel configurare il tuo nodo, ma è importante comprendere le implicazioni della tua configurazione. kora.toml è il centro di controllo per la configurazione di Kora. Questo documento fornisce un riferimento completo per configurare il tuo nodo paymaster Kora attraverso il file di configurazione kora.toml.

Panoramica

Il file kora.toml controlla tutti gli aspetti del comportamento del tuo nodo Kora, inclusi:

  • Limitazione della frequenza e autenticazione
  • Disponibilità dei metodi RPC
  • Regole di validazione delle transazioni
  • Modelli di tariffazione delle commissioni
  • Politiche di sicurezza
  • Disponibilità dei metodi RPC
  • Modelli di tariffazione delle commissioni
  • Configurazione dell'indirizzo di pagamento
  • Monitoraggio delle prestazioni

Il tuo file di configurazione dovrebbe essere inserito nella directory di deployment o specificato tramite il flag --config all'avvio del server.

Sezioni di Configurazione

Il file kora.toml è organizzato in sezioni, ognuna con il proprio set di opzioni. Questa guida illustra ogni sezione e spiega le opzioni disponibili:

Sezioni di esempio del file 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

Politiche principali di Kora

La sezione [kora] configura il comportamento principale del server:

[kora]
rate_limit = 100
payment_address = "YourPaymentAddressPubkey11111111111111111111" # Optional
OpzioneDescrizioneObbligatorioTipo
rate_limitLimite di velocità globale (richieste al secondo) per tutti i clientnumber
payment_addressIndirizzo di pagamento facoltativo per ricevere i token di pagamento (predefinito all'indirizzo del firmatario se non specificato)stringa codificata b58

Autenticazione Kora

La sezione [kora.auth] configura l'autenticazione per il server Kora:

[kora.auth]
api_key = "kora_live_sk_1234567890abcdef"
hmac_secret = "kora_hmac_your-strong-hmac-secret-key-here"
max_timestamp_age = 300
OpzioneDescrizioneObbligatorioTipo
api_keyChiave API per l'autenticazione semplicestring
hmac_secretSegreto HMAC per l'autenticazione basata su firma (min 32 caratteri)string
max_timestamp_ageEtà massima di un timestamp HMAC in secondi❌ (predefinito: 300)number

Nota: api_key e hmac_secret impostano una politica di autenticazione globale per tutti i client. Per la configurazione dettagliata dell'autenticazione, consulta la Guida all'autenticazione.

Memorizzazione nella cache di Kora (facoltativo)

La sezione [kora.cache] configura la memorizzazione nella cache basata su Redis per le chiamate RPC di Solana. Questo può migliorare significativamente le prestazioni riducendo le richieste ridondanti di dati degli account:

[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)
OpzioneDescrizioneObbligatorioTipo
enabledAbilita la cache Redis per le chiamate RPC❌ (predefinito: false)boolean
urlURL di connessione Redis (obbligatorio se abilitato)string
default_ttlTTL predefinito per le voci in cache in secondi❌ (predefinito: 300)number
account_ttlTTL per la cache dei dati degli account in secondi❌ (predefinito: 60)number

Nota: Quando la cache è abilitata, un'istanza Redis deve essere disponibile all'URL specificato. La cache torna automaticamente alle chiamate RPC dirette se Redis non è disponibile.

Limiti d'Uso di Kora (opzionale)

La sezione [kora.usage_limit] configura la limitazione delle transazioni per wallet per prevenire abusi e garantire un uso equo tra i tuoi utenti. Questo può anche essere utilizzato per creare programmi fedeltà che sovvenzionano le commissioni di transazione degli utenti fino a un certo limite.

Importante: Attualmente, l'unica forma di limitazione d'uso supportata da Kora è un limite permanente. Una volta che un wallet raggiunge il suo limite di transazioni, non può essere ripristinato e l'utente non potrà più inviare altre transazioni utilizzando quel wallet. Questo limite persiste fino a quando non viene rimosso manualmente da Redis o i dati Redis vengono reimpostati.

Nota: Questa funzionalità richiede Redis quando è abilitata su più istanze di 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
OpzioneDescrizioneObbligatorioTipo
enabledAbilita la limitazione delle transazioni per wallet❌ (predefinito: false)boolean
cache_urlURL di connessione Redis per il tracciamento condiviso dell'usostring
max_transactionsNumero massimo di transazioni per wallet (0 = illimitato)❌ (predefinito: 100)number
fallback_if_unavailableConsenti transazioni se Redis non è disponibile❌ (predefinito: true)boolean

Nota: I limiti d'uso sono tracciati per indirizzo wallet con scadenza automatica basata su TTL. Quando fallback_if_unavailable è true, il sistema consente alle transazioni di procedere se Redis è temporaneamente non disponibile, prevenendo interruzioni del servizio. Impostare max_transactions a 0 consentirà transazioni illimitate.

Metodi abilitati Kora (opzionale)

La sezione [kora.enabled_methods] controlla quali metodi RPC sono abilitati. Questa sezione è opzionale e per impostazione predefinita tutti i metodi sono abilitati. Ogni metodo può essere abilitato o disabilitato impostando il valore su 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
OpzioneDescrizione del metodoRichiestoTipo
livenessEndpoint per il controllo dello statoboolean
estimate_transaction_feeStima la commissione per una transazioneboolean
get_supported_tokensElenca i token accettatiboolean
sign_transactionFirma una transazione senza inviarla alla reteboolean
sign_and_send_transactionFirma una transazione e la invia alla reteboolean
transfer_transactionGestisce i trasferimenti di tokenboolean
get_blockhashOttiene un blockhash recenteboolean
get_configRestituisce la configurazione del server Koraboolean

Nota: se questa sezione è inclusa nel file kora.toml, tutti i metodi devono essere esplicitamente impostati su true o false.

Politiche di validazione

La sezione [validation] definisce le regole di sicurezza relative a Solana e i limiti di transazione:

[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",
]
OpzioneDescrizioneRichiestoTipo
max_allowed_lamportsImpostare un numero massimo di lamport per transazione limita l'esposizione del nodo Kora a una singola transazione.number
max_signaturesLe commissioni base di Solana dipendono dal numero di firme in una transazione, quindi impostare un numero massimo di firme per transazione è un buon modo per evitare che gli utenti spendano troppo SOL in una singola transazione.number
price_sourceOracle per i dati sui prezzi dei token. Nota: quando impostato su "Jupiter", la variabile d'ambiente JUPITER_API_KEY è obbligatoria. Il server non si avvierà senza di essa."Jupiter" o "Mock"
allow_durable_transactionsConsente transazioni con nonce durevole. Vedere Considerazioni sulla sicurezza di seguito.❌ (predefinito: false)boolean
allowed_programsProgrammi Solana con cui le transazioni possono interagireArray di stringhe b58
allowed_tokensMint di token che possono essere utilizzati nelle transazioniArray di stringhe b58
allowed_spl_paid_tokensToken SPL accettati come pagamento per le commissioni di transazioneArray di stringhe b58
disallowed_accountsAccount esplicitamente bloccati dalle transazioniArray di stringhe b58

Nota: Gli array vuoti sono consentiti, ma sarà necessario specificare almeno un allowed_programs, allowed_tokens, allowed_spl_paid_tokens nella whitelist affinché il nodo Kora possa elaborare le transazioni. È necessario specificare il System Program o il Token Program affinché il nodo Kora possa elaborare i trasferimenti. Per abilitare tipi di istruzioni comuni (ad es., Compute Budget, Address Lookup Table), è necessario specificare il Compute Budget Program o l'Address Lookup Table Program, ecc.

Sicurezza delle transazioni durevoli

AVVISO DI SICUREZZA: Le transazioni con nonce durevole consentono di trattenere transazioni firmate indefinitamente e di inviarle successivamente. Ciò potrebbe essere utilizzato come vettore di attacco economico in cui qualcuno potrebbe ottenere una transazione firmata e attendere di inviarla fino a quando le condizioni di mercato gli sono favorevoli (ad esempio, quando il valore di SOL è sceso o il valore del token di pagamento è aumentato).

Per impostazione predefinita, allow_durable_transactions è impostato su false per bloccare tutte le transazioni con nonce durevole. Abilitare questa funzione solo se l'applicazione richiede specificamente transazioni durevoli e si comprendono i rischi.

Se è necessario abilitare le transazioni durevoli, considerare:

  • Utilizzare l'autenticazione per limitare l'accesso alle API
  • Implementare una validazione off-chain aggiuntiva
  • Monitorare schemi di transazione insoliti
  • Monitorare e limitare i saldi degli account firmatari
  • Ruotare regolarmente le chiavi dei firmatari

Scopri di più sulle transazioni con nonce durevole nella documentazione di Solana.

Blocco delle estensioni Token-2022

La sezione [validation.token2022] consente di bloccare specifiche estensioni Token-2022 per una maggiore sicurezza. Tutte le estensioni sono abilitate per impostazione predefinita. È possibile bloccare estensioni specifiche aggiungendole agli array 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
]

Estensioni Mint Disponibili

Nome EstensioneDescrizione
confidential_transfer_mintConfigurazione trasferimento confidenziale per il mint
confidential_mint_burnConfigurazione mint e burn confidenziali
transfer_fee_configConfigurazione commissione di trasferimento
mint_close_authorityAutorità autorizzata a chiudere il mint
interest_bearing_configConfigurazione token fruttifero
non_transferableRende i token non trasferibili
permanent_delegateDelegato permanente per il mint
transfer_hookProgramma hook di trasferimento personalizzato
pausableConfigurazione token sospendibile

Estensioni Account Disponibili

Nome EstensioneDescrizione
confidential_transfer_accountStato trasferimento confidenziale per l'account
non_transferable_accountAccount token non trasferibile
transfer_hook_accountStato hook di trasferimento per l'account
pausable_accountStato account token sospendibile
memo_transferRichiede memo per i trasferimenti
cpi_guardPreviene determinate chiamate CPI
immutable_ownerIl proprietario dell'account non può essere modificato
default_account_stateStato predefinito per nuovi account

transfer_hook

Considerazioni sulla Sicurezza

Estensione PermanentDelegate - I token con questa estensione consentono al delegato di trasferire/bruciare token in qualsiasi momento senza l'approvazione del proprietario. Ciò crea rischi significativi per l'operatore del nodo Kora poiché i fondi di pagamento possono essere sequestrati dopo il pagamento.

  • Considera di aggiungere "permanent_delegate" a blocked_mint_extensions in [validation.token2022] a meno che non sia esplicitamente necessario per il tuo caso d'uso.
  • Evita di utilizzare token di pagamento con l'estensione permanent_delegate.

Politica del Pagatore delle Commissioni

La sezione [validation.fee_payer_policy] fornisce un controllo granulare sulle azioni che il portafoglio del pagatore delle commissioni del tuo nodo Kora può eseguire. La politica è organizzata per tipo di programma (System, SPL Token, Token-2022) e copre tutti i diversi tipi di istruzioni. Ciò previene comportamenti imprevisti da parte delle transazioni degli utenti che utilizzano il tuo nodo Kora come firmatario.

Ad esempio, se spl_token.allow_transfer è impostato su false, il nodo Kora non firmerà transazioni che includono un trasferimento di token SPL in cui il pagatore delle commissioni del nodo Kora è l'autorità di trasferimento.

[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

Istruzioni del System Program

OpzioneDescrizionePredefinitoTipo
allow_transferConsente al pagatore delle commissioni come mittente nelle istruzioni Transfer/TransferWithSeedfalseboolean
allow_assignConsente al pagatore delle commissioni come autorità nelle istruzioni Assign/AssignWithSeedfalseboolean
allow_create_accountConsente al pagatore delle commissioni come finanziatore nelle istruzioni CreateAccount/CreateAccountWithSeedfalseboolean
allow_allocateConsente al pagatore delle commissioni come proprietario dell'account nelle istruzioni Allocate/AllocateWithSeedfalseboolean
nonce.allow_initializeConsente di impostare il pagatore delle commissioni come autorità nonce in InitializeNonceAccountfalseboolean
nonce.allow_advanceConsente al pagatore delle commissioni come autorità in AdvanceNonceAccountfalseboolean
nonce.allow_authorizeConsente al pagatore delle commissioni come autorità corrente in AuthorizeNonceAccountfalseboolean
nonce.allow_withdrawConsente al pagatore delle commissioni come autorità in WithdrawNonceAccountfalseboolean

Istruzioni del SPL Token Program

OpzioneDescrizionePredefinitoTipo
allow_transferConsente al pagatore delle commissioni come proprietario nelle istruzioni Transfer/TransferCheckedfalseboolean
allow_burnConsente al pagatore delle commissioni come proprietario nelle istruzioni Burn/BurnCheckedfalseboolean
allow_close_accountConsente al pagatore delle commissioni come proprietario nelle istruzioni CloseAccountfalseboolean
allow_approveConsente al pagatore delle commissioni come proprietario nelle istruzioni Approve/ApproveCheckedfalseboolean
allow_revokeConsente al pagatore delle commissioni come proprietario nelle istruzioni Revokefalseboolean
allow_set_authorityConsente al pagatore delle commissioni come autorità corrente nelle istruzioni SetAuthorityfalseboolean
allow_mint_toConsente al pagatore delle commissioni come autorità di conio nelle istruzioni MintTo/MintToCheckedfalseboolean
allow_initialize_mintConsente al pagatore delle commissioni come autorità di conio nelle istruzioni InitializeMint/InitializeMint2falseboolean
allow_initialize_accountConsente al pagatore delle commissioni come proprietario nelle istruzioni InitializeAccount/InitializeAccount3falseboolean
allow_initialize_multisigConsente al pagatore delle commissioni come firmatario nelle istruzioni InitializeMultisig/InitializeMultisig2falseboolean
allow_freeze_accountConsente al pagatore delle commissioni come autorità di congelamento nelle istruzioni FreezeAccountfalseboolean
allow_thaw_accountConsente al pagatore delle commissioni come autorità di congelamento nelle istruzioni ThawAccountfalseboolean

Token-2022 supporta lo stesso set di istruzioni di SPL Token con opzioni di configurazione identiche (nella sezione [validation.fee_payer_policy.token_2022]).

Considerazioni sulla Sicurezza

AVVISO DI SICUREZZA: Per motivi di sicurezza, si consiglia di impostare tutte queste opzioni su false (predefinito) e abilitarle solo quando necessario. Questo impedirà comportamenti indesiderati come il prosciugamento del tuo account fee payer da parte degli utenti o la masterizzazione di token dal tuo account fee payer. Questo previene:

  • Prosciugamento dell'Account: Gli utenti trasferiscono SOL o token dal tuo account fee payer
  • Acquisizione delle Autorità: Gli utenti modificano le autorità sugli account di proprietà del tuo fee payer
  • Conio Non Autorizzato: Gli utenti coniano token se il tuo fee payer ha l'autorità di conio
  • Manipolazione degli Account: Gli utenti congelano, chiudono o modificano account controllati dal tuo fee payer

Migliore Pratica: Inizia con tutti i permessi disabilitati e abilita solo il set minimo necessario per il tuo caso d'uso specifico.

Configurazione del Prezzo (opzionale)

La sezione [validation.price] definisce come vengono calcolate le commissioni di transazione. Sono disponibili tre modelli di prezzo:

  • Prezzo a Margine (predefinito) - Aggiunge una percentuale di margine sopra le commissioni di rete effettive (il margine predefinito è 0.0)
  • Prezzo Fisso - Addebita un importo fisso in un token specifico indipendentemente dalle commissioni di rete
  • Prezzo Gratuito - Sponsorizza tutte le commissioni di transazione (nessun addebito agli utenti)
OpzioneDescrizioneRichiestoTipo
typeModello di prezzo da utilizzare"margin", "fixed" o "free"
marginPercentuale di margine da aggiungere alle commissioni di rete(quando type è "margin")numero
amountImporto fisso da addebitare nelle unità base del token(quando type è "fixed")numero
tokenMint del token in cui addebitare(quando type è "fixed")stringa codificata in b58

Prezzi con Margine

Aggiungi una percentuale di margine sopra le commissioni di rete effettive:

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

Prezzi Fissi

AVVISO DI SICUREZZA: I prezzi fissi NON includono l'uscita del pagatore di commissioni nell'importo addebitato. Questo può permettere agli utenti di prosciugare il tuo account pagatore di commissioni se non configurato correttamente.

Addebita un importo fisso in un token specifico indipendentemente dalle commissioni di rete:

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

Transazioni Gratuite

Sponsorizza tutte le commissioni di transazione (nessun addebito agli utenti):

[validation.price]
type = "free"

Misure di Sicurezza quando si Utilizzano Prezzi Fissi/Gratuiti

  1. Disabilita Tutte le Operazioni di Trasferimento e Monetarie - Impedisci che il pagatore di commissioni venga utilizzato come sorgente nei trasferimenti:

    [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. Abilita l'Autenticazione - Utilizza l'autenticazione per prevenire abusi:

    [kora.auth]
    api_key = "your-secure-api-key"
    # or
    hmac_secret = "your-minimum-32-character-hmac-secret"
  3. Imposta Limiti Conservativi - Riduci al minimo l'esposizione:

    [validation]
    max_allowed_lamports = 1000000 # 0.001 SOL maximum

AVVISO: Operazioni particolarmente pericolose quando si utilizzano prezzi fissi/gratuiti:

  • allow_mint_to: Potrebbe consentire la creazione illimitata di token se il pagatore di commissioni ha l'autorità di conio
  • allow_set_authority: Potrebbe trasferire il controllo di account critici agli aggressori
  • allow_transfer: Abilita il prosciugamento diretto dei saldi token del pagatore di commissioni
  • allow_close_account: Restituisce il rent agli account controllati dall'aggressore

Monitoraggio delle Prestazioni (opzionale)

La sezione [metrics] configura la raccolta delle metriche e il monitoraggio. Questa sezione è opzionale e per impostazione predefinita le metriche sono disabilitate.

[metrics]
enabled = true
endpoint = "/metrics"
port = 8080
scrape_interval = 60
[metrics.fee_payer_balance]
enabled = true
expiry_seconds = 30
OpzioneDescrizioneRichiestoTipo
enabledAbilita la raccolta delle metricheboolean
endpointPercorso personalizzato dell'endpoint metrichestring
portPorta dell'endpoint metrichenumber
scrape_intervalFrequenza di scraping Prometheus (secondi)number

Monitoraggio del Saldo del Fee Payer

La sezione [metrics.fee_payer_balance] configura il monitoraggio automatico del saldo SOL del tuo fee payer:

OpzioneDescrizioneRichiestoTipo
enabledAbilita il monitoraggio del saldo fee payer❌ (default: false)boolean
expiry_secondsIntervallo di monitoraggio in background (secondi)❌ (default: 30)number

Quando abilitato, Kora monitora automaticamente il saldo SOL del tuo fee payer e lo espone tramite il gauge Prometheus fee_payer_balance_lamports. Questo aiuta nella pianificazione della capacità e negli avvisi per saldo insufficiente.

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

→ Guida di Riferimento al Monitoraggio Kora

Esempio Completo

Ecco una configurazione pronta per la produzione con le best practice di sicurezza:

# 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

Validazione della Configurazione

Kora valida la tua configurazione all'avvio. Se desideri validare la tua configurazione senza avviare il server, puoi utilizzare il comando di validazione della configurazione:

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

Puoi anche eseguire il comando validate-with-rpc per validare la tua configurazione con il server RPC (questa verifica di validazione è leggermente più lenta ma effettua controlli sugli account più approfonditi)

Avvio del Server

Una volta configurato il tuo file kora.toml, puoi avviare il server Kora:

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

Il flag --no-load-signer inizializzerà il server senza caricare alcun signer. Questo è utile per testare la tua configurazione. Per caricare i signer, dovrai configurare il file signers.toml. Una configurazione minima con un singolo signer sarebbe simile a questa:

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

Questo caricherà un singolo signer dalla variabile d'ambiente MY_SIGNER_PRIVATE_KEY. Quindi potrai avviare il tuo server con:

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

Per ulteriori informazioni e configurazione avanzata del firmatario, consulta la Guida ai Firmatari.

Best Practice

  1. Inizia in Modo Restrittivo: Comincia con limiti rigidi e amplia gradualmente
  2. Monitora l'Utilizzo: Tieni traccia di quali programmi e token vengono effettivamente utilizzati
  3. Aggiornamenti Regolari: Rivedi e aggiorna le blocklist e i limiti
  4. Testa le Modifiche: Convalida le modifiche alla configurazione prima in staging
  5. Versionamento: Mantieni un registro delle modifiche alla tua configurazione

Hai Bisogno di Aiuto?

Is this page helpful?

Gestito da

© 2026 Solana Foundation.
Tutti i diritti riservati.
Resta connesso