Documentazione Operatori Kora

Cos'è un Operatore di Nodo Kora?

Come operatore di nodo Kora, gestisci un servizio paymaster che sponsorizza le commissioni delle transazioni Solana per i tuoi utenti. Il tuo nodo accetta pagamenti in token SPL e utilizza il tuo SOL per pagare le commissioni di rete effettive, consentendo transazioni senza gas per la tua applicazione.

Perché Gestire un Nodo Kora?

Migliore UX: I tuoi utenti effettuano transazioni senza bisogno di SOL (onboarding semplificato, migliore fidelizzazione, ecc.)
Fonte di Ricavo: Raccogli commissioni nei token preferiti dalla tua attività (USDC, BONK, ecc.)

Avvio Rapido

Vuoi prima provare in locale? Avvia un nodo Kora locale in pochi minuti: → Guida Rapida Locale

Concetti Fondamentali

Come operatore di nodo Kora, sei responsabile della gestione di un servizio paymaster sicuro che abilita transazioni senza gas per i tuoi utenti. Il tuo nodo ha quattro responsabilità chiave:

1. Validare le Transazioni

Configura il tuo nodo per accettare solo transazioni che soddisfano i requisiti della tua attività tramite kora.toml:

Allowlist di token: Definisci quali token SPL accetti come pagamento (supporta sia SPL che Token-2022)
Allowlist di programmi: Metti in whitelist con quali programmi Solana gli utenti possono interagire
Limiti di transazione: Imposta le commissioni massime che sei disposto a pagare e i limiti di firma
Blocklist di account: Impedisci interazioni con indirizzi problematici
Oracoli di prezzo: Configura Jupiter o prezzi mock per i calcoli delle commissioni
Token di pagamento: Specifica quali tipi di token accetterai come pagamento
Politiche feepayer: Controlla quali operazioni il tuo feepayer può eseguire (trasferimenti, burn, approvazioni, ecc.)
Estensioni Token-2022: Blocca specifiche estensioni Token-2022 per una sicurezza maggiore
Caching: Abilita il caching Redis per migliorare le prestazioni riducendo le chiamate RPC
Limiti di utilizzo: Imposta limiti di transazione per wallet per prevenire abusi, garantire un uso equo o premiare gli utenti con transazioni sovvenzionate fino a un certo limite

→ Riferimento Completo alla Configurazione di Kora.toml → Esempio di kora.toml

2. Firmare le Transazioni

Il tuo nodo necessita di keypair Solana per firmare le transazioni come pagatore delle commissioni. Per distribuzioni in produzione, Kora supporta configurazioni multi-firmatario per una maggiore affidabilità e distribuzione del blocco degli account. Considera l'implementazione di rotazione delle chiavi, controlli di accesso, backup e altre strategie per la sicurezza dei firmatari. Opzioni di firma disponibili:

Chiave Privata Locale: Memorizza la chiave privata direttamente nell'ambiente del server (come base58, file .json o array u8)
Turnkey: Gestione delle chiavi private resa semplice. Crea portafogli, firma transazioni e automatizza azioni onchain.
Privy: Infrastruttura crypto semplice. Crea in modo sicuro portafogli whitelabel e firma transazioni.
HashiCorp Vault: Gestisci Segreti e Proteggi Dati Sensibili

→ Guida Completa alla Configurazione dei Firmatari

3. Pagare le Commissioni delle Transazioni

Mantieni SOL sufficienti per coprire le commissioni di rete per il volume di transazioni previsto:

Monitoraggio del saldo: Tieni traccia del saldo SOL e configura avvisi per saldo basso (Kora fornisce metriche Prometheus integrate - vedi Monitoraggio)
Automazione: Implementa procedure automatiche di ricarica SOL per ambienti di produzione
Pianificazione della capacità: Pianifica in base al caso d'uso previsto, volume di utenti, ecc.

È importante comprendere come Kora stima le commissioni e come configurare il tuo nodo per massimizzare i ricavi. Consulta la Guida alla Stima delle Commissioni per maggiori dettagli.

4. Monitorare le Operazioni

Monitora continuamente la sicurezza, le prestazioni e le metriche aziendali del tuo nodo:

Monitoraggio della sicurezza: Pattern insoliti, validazioni fallite e violazioni dei limiti di velocità
Avvisi operativi: Salute del sistema, avvisi di saldo e eventi di sicurezza
Monitoraggio finanziario: Costi SOL vs. ricavi in token, analisi della redditività
Monitoraggio del saldo dei firmatari: Tieni traccia del saldo dei firmatari e configura avvisi per saldo basso

Kora fornisce un endpoint /metrics facoltativo che fornisce dati sulle prestazioni in tempo reale in formato Prometheus.

→ Guida di riferimento al monitoraggio di Kora

5. Ottimizza le prestazioni (opzionale)

Per deployment ad alto traffico, abilita la cache Redis per ridurre le chiamate RPC e migliorare i tempi di risposta:

Cache degli account: memorizza nella cache i dati degli account Solana con time to live (TTL) configurabile
Fallback automatico: ritorna automaticamente alle chiamate RPC dirette se Redis non è disponibile
Gestione della cache: scadenza automatica e capacità di aggiornamento forzato per operazioni critiche

Kora CLI

Il crate kora-cli è un binario Rust pronto per la produzione che fornisce tutto ciò di cui hai bisogno per eseguire un nodo paymaster Kora. È distribuito come eseguibile autonomo che puoi installare globalmente o distribuire in container.

Opzioni di installazione

Installazione globale (consigliata per lo sviluppo)

cargo install kora-cli

Oppure compila dal codice sorgente (consigliato per contribuire)

git clone https://github.com/solana-foundation/kora.git
cd kora
just install

Utilizzo di base

Il server RPC di Kora espone un endpoint JSON-RPC (predefinito: http://localhost:8080). Avvialo con il comando kora rpc:

# Run with specified kora.toml and signers.toml
kora --config path/to/kora.toml rpc start --signers-config path/to/signers.toml

# Help
kora rpc --help

Per ulteriori informazioni sull'utilizzo della CLI di Kora, consulta la Guida CLI.

Le applicazioni possono accedere al server RPC di Kora tramite il Kora TS SDK

Configurazione

Ogni nodo RPC di Kora deve essere configurato almeno con:

un endpoint RPC di Solana (specificato tramite il flag --rpc-url o la variabile d'ambiente RPC_URL) [predefinito: http://127.0.0.1:8899]
configurazione del/i firmatario/i Solana (specificata tramite il flag --signers-config signers.toml)
un file di configurazione, kora.toml (specificato tramite il flag --config path/to/kora.toml)

kora.toml

Prima del deployment, dovrai creare e configurare un kora.toml per specificare:

Limitazione della frequenza e autenticazione
Indirizzo di destinazione del pagamento
Disponibilità dei metodi RPC
Regole di validazione delle transazioni
Politiche di sicurezza (whitelist o blacklist di token SPL, programmi, account, estensioni token, ecc.)
Modelli di pricing delle commissioni
Politiche avanzate del fee payer (protezione contro comportamenti indesiderati del firmatario)
Raccolta delle metriche
Configurazione della cache Redis (opzionale)

signers.toml

Sarà inoltre necessario creare un file signers.toml per specificare:

Firmatario/i per il tuo nodo
Strategia di selezione del firmatario
Configurazione di ciascun firmatario e chiavi applicabili

Distribuzione su Railway

Altre guide di integrazione in arrivo a breve

Hai Bisogno di Aiuto?

Solana Stack Exchange - Fai domande/condividi conoscenze (assicurati di usare il tag kora)
Problemi su GitHub - Segnala bug o ottieni assistenza
Esegui kora rpc --help per visualizzare tutti i flag e le opzioni di configurazione disponibili