Documentazione SolanaIniziare

Guida rapida a Kora

Ultimo aggiornamento: 31-10-2025

Nozioni di base su Kora

Kora è un server JSON-RPC che fornisce servizi di pagamento delle commissioni per le transazioni Solana. Consente agli utenti di pagare le commissioni di transazione con token SPL anziché con SOL, migliorando l'esperienza utente per le applicazioni in cui gli utenti potrebbero non possedere SOL.

Kora RPC convalida le richieste dei client in base a una configurazione (kora.toml) che definisce i programmi, i portafogli, i token, ecc. consentiti. Una volta convalidata, il server Kora firmerà la transazione e la invierà alla rete (oppure restituirà una transazione firmata serializzata al client).

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐

│   Client App    │───▶│   Kora RPC      │───▶│   Solana RPC    │

│                 │    │   Server        │    │                 │

└─────────────────┘    └─────────────────┘    └─────────────────┘

                              │

                              ▼

                       ┌──────────────────────┐

                       │   Kora Private Key   │

                       │ ( or Turnkey/Privy ) │

                       └──────────────────────┘

Questa guida rapida avvierà un server Kora RPC locale e dimostrerà l'integrazione client per testare i flussi di lavoro di pagamento delle commissioni.

Requisiti

Installare Kora RPC

Installa il server Kora RPC globalmente:

cargo install kora-cli

Importante: Il branch main di Kora è un branch di integrazione e potrebbe contenere modifiche non rilasciate o in versione beta. Utilizza sempre l'ultimo tag di rilascio stabile per l'uso in produzione e nei tutorial. Puoi trovare l'ultimo rilascio stabile nella pagina dei rilasci di Kora.

Creare il progetto

Clona il repository, esegui il checkout dell'ultimo tag stabile e vai alla directory della demo introduttiva:

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

cd kora

git checkout v2.0.5

cd examples/getting-started/demo

Struttura del progetto

La demo contiene tre componenti principali:

Directory client (client/src/)

  • setup.ts - Configurazione dell'ambiente locale (crea keypair e li scrive in .env, invia SOL tramite airdrop, inizializza il token di test)
  • quick-start.ts - Script dimostrativo di avvio rapido che mostra come stabilire una connessione Kora e effettuare una semplice chiamata al server Kora RPC
  • full-demo.ts - Script dimostrativo completo che mostra molteplici metodi Kora RPC

Directory del Server (server/)

  • kora.toml - Configurazione RPC di Kora che definisce le regole di validazione, i token consentiti e i parametri delle commissioni
  • signers.toml - Configurazione dei firmatari che definisce i firmatari per il server Kora

Configurazione Condivisa

  • .env - Variabili d'ambiente per keypair e indirizzi (crea .env nella directory principale - demo/.env). Le variabili d'ambiente verranno create dallo script di configurazione.

Configurazione dell'Ambiente

Innanzitutto, crea il file .env per il tuo ambiente:

# Create .env file (will be populated by setup script)

touch .env

Configurazione del Client

Installa le dipendenze del client:

# From project root (kora/)

cd examples/getting-started/demo/client

pnpm install --ignore-workspace # use --ignore-workspace to avoid pnpm workspace conflicts

Configurazione del Server RPC Kora

Il server Kora richiede una configurazione per specificare quali token possono essere utilizzati per il pagamento delle commissioni. Apri server/kora.toml e nota la sezione di validazione. Qui possiamo specificare diversi parametri che verranno validati prima di firmare una transazione:

  • max_allowed_lamports: commissione massima della transazione che sei disposto a pagare per conto dell'utente
  • max_signatures: numero massimo di firme che una transazione può avere
  • price_source: oracolo per determinare il prezzo del token ("Mock" o "Jupiter")
  • allowed_programs: whitelist degli ID dei programmi che possono essere eseguiti (ad es., System Program, Token Program)
  • allowed_tokens: whitelist dei token che possono essere trasferiti
  • allowed_spl_paid_tokens: array di indirizzi mint che il tuo programma accetta come pagamento
  • disallowed_accounts: blacklist degli account che non possono interagire con il tuo RPC Kora

Per ora, lasciamo i valori predefiniti--puoi tornare qui e modificarli in seguito (per maggiori informazioni sulle opzioni di configurazione, consulta la documentazione sulla Configurazione di Kora).

Configurazione dei Firmatari

Apri server/signers.toml e nota la sezione dei firmatari. Qui possiamo specificare quali firmatari verranno utilizzati per firmare le transazioni e (se si utilizzano più firmatari) una strategia per selezionare quale firmatario utilizzare. Per ora, utilizziamo un singolo firmatario con i valori predefiniti--puoi tornare qui e modificarli in seguito (per maggiori informazioni sulla configurazione dei firmatari, consulta la guida Guida ai Firmatari).

Server di Test

Apri tre terminali ed esegui i seguenti comandi:

Terminale 1: Avvia il Validatore di Test Locale

# From project root or anywhere

solana-test-validator -r

Terminale 2: Inizializza l'Ambiente

# From ./client directory

pnpm init-env

Questo script:

  • Genera keypair e le salva in .env
  • Effettua l'airdrop di SOL agli account di test
  • Crea e inizializza un token USDC locale
  • Finanzia gli account di test con token

Importante Assicurati di copiare la chiave pubblica del nuovo token USDC di test dal tuo .env e aggiornare allowed_tokens e allowed_spl_paid_tokens in ./server/kora.toml.

allowed_tokens = [

    "YOUR_USDC_LOCAL_PUBLICK_KEY"    # Update this based on the USDC_LOCAL_KEY public key comment in your .env

]

allowed_spl_paid_tokens = [

    "YOUR_USDC_LOCAL_PUBLICK_KEY"    # Update this based on the USDC_LOCAL_KEY public key comment in your .env

]

Terminale 3: Inizializza gli ATA di Pagamento (Facoltativo)

Per ricevere pagamenti, dovrai inizializzare gli Associated Token Account (ATA) per i tuoi token di pagamento. Puoi farlo eseguendo il seguente comando:

# From ./server directory

kora rpc initialize-atas --signers-config signers.toml

Questo comando:

  • Legge il tuo indirizzo di pagamento da kora.toml (oppure, se non hai specificato un indirizzo di pagamento, tutti i firmatari elencati in signers.toml)
  • Crea ATA per tutti i token elencati in allowed_spl_paid_tokens
  • Salta eventuali ATA già esistenti
  • Puoi opzionalmente specificare un pagatore di commissioni personalizzato per la generazione degli ATA utilizzando il flag fee_payer_key.

Terminale 4: Avvia il Server RPC Kora

# From ./server directory

kora rpc start --signers-config signers.toml

Nota: Per i deployment in produzione che utilizzano price_source = "Jupiter", devi impostare la variabile d'ambiente JUPITER_API_KEY. Il server non si avvierà senza di essa:

JUPITER_API_KEY=your_api_key kora rpc start --signers-config signers.toml

Il server legge la configurazione da kora.toml e signers.toml e utilizza le variabili d'ambiente del file condiviso .env. Se stai utilizzando una struttura di cartelle diversa da quella specificata qui, potresti dover usare --config per specificare la posizione di kora.toml e --signers-config per specificare la directory della configurazione dei firmatari:

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

Puoi accedere a kora rpc -h per ricevere aiuto sulle opzioni del server RPC.

Terminale 5: Eseguire la Demo del Client

# From ./client directory

pnpm start

Dovresti vedere un output simile a:

Kora Config: {

  fee_payer: 'Df2UmGQH86TBDsub7XZoSAo7KZa1ZJZr2w1PL1APUjjU',

  validation_config: {

    max_allowed_lamports: 1000000,

    max_signatures: 10,

    allowed_programs: [

      '11111111111111111111111111111111',

      'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA',

      'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL',

      'AddressLookupTab1e1111111111111111111111111',

      'ComputeBudget11111111111111111111111111111111'

    ],

    allowed_tokens: [

      'usdCAEFbouFGxdkbHCRtMTcN7DJHd3aCmP9vqjLgmAp'

    ],

    allowed_spl_paid_tokens: [

      'usdCAEFbouFGxdkbHCRtMTcN7DJHd3aCmP9vqjLgmAp'

    ],

    disallowed_accounts: [],

    price_source: 'Mock',

    fee_payer_policy: {...},

    price: { type: 'margin', margin: 0 }

  },

  enabled_methods: { ... }

 }

}

Blockhash:  C8W8d5w2H4jKXyFg5CEBoiaPvEpJ1am7xLxZ3fym4a2g

Questo conferma che il tuo server Kora è in esecuzione e configurato correttamente!

Prossimi Passi

Una volta che la configurazione di base funziona, dai un'occhiata alla demo completa del flusso Kora:

→ Flusso Completo delle Transazioni Gasless di Kora

esplora i metodi RPC aggiuntivi di Kora:

  • estimateTransactionFee - Calcola le commissioni per le transazioni
  • getPayerSigner - Ottieni il firmatario pagante e la destinazione del pagamento
  • getSupportedTokens - Restituisce un array di token di pagamento supportati
  • signTransaction - Firma condizionalmente le transazioni quando le commissioni sono coperte
  • transferTransaction - Crea transazioni di trasferimento SOL o trasferimento di token SPL (firmate dal feepayer di Kora)
  • signAndSendTransaction - Firma condizionalmente una transazione con il feepayer di Kora e la invia al Solana RPC configurato
  • getPaymentInstruction - Ottieni un'istruzione di pagamento per una transazione

Hai domande? Fai domande su Solana Stack Exchange con un tag Kora.

Is this page helpful?

Precedente

Installazione

Successivo

Documentazione Operatori Kora

Indice dei contenuti

Modifica pagina

Gestito da

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