Guide de démarrage rapide Kora

Dernière mise à jour : 31/10/2025

Fondamentaux de Kora

Kora est un serveur JSON-RPC qui fournit des services de paiement de frais pour les transactions Solana. Il permet aux utilisateurs de payer les frais de transaction avec des jetons SPL au lieu de SOL, offrant ainsi une meilleure expérience utilisateur pour les applications où les utilisateurs ne détiennent pas nécessairement de SOL.

Le RPC Kora valide les demandes des clients sur la base d'une configuration (kora.toml) qui définit les programmes, portefeuilles, jetons, etc. autorisés. Une fois validée, le serveur Kora signera la transaction et l'enverra au réseau (ou renverra une transaction signée sérialisée au client).

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Client App    │───▶│   Kora RPC      │───▶│   Solana RPC    │
│                 │    │   Server        │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌──────────────────────┐
                       │   Kora Private Key   │
                       │ ( or Turnkey/Privy ) │
                       └──────────────────────┘

Ce démarrage rapide lancera un serveur RPC Kora local et démontrera l'intégration client pour tester les flux de paiement de frais.

Prérequis

Solana CLI v2.2.x ou supérieure
Rust/Cargo (pour l'installation du RPC Kora)
Node.js v22+ et un gestionnaire de paquets (par ex., pnpm, npm)

Installer le RPC Kora

Installez le serveur RPC Kora globalement :

cargo install kora-cli

Important : La branche main de Kora est une branche d'intégration et peut contenir des modifications non publiées ou en version bêta. Utilisez toujours la dernière balise de version stable pour la production et l'utilisation des tutoriels. Vous pouvez trouver la dernière version stable sur la page des versions de Kora.

Créer un projet

Clonez le dépôt, récupérez la dernière balise stable et accédez au répertoire de démonstration de prise en main :

git clone https://github.com/solana-foundation/kora
cd kora
git checkout v2.0.5
cd examples/getting-started/demo

Structure du projet

La démonstration contient trois composants principaux :

Répertoire client (client/src/)

setup.ts - Configuration de l'environnement local (crée des keypairs et les écrit dans .env, effectue des airdrops de SOL, initialise le jeton de test)
quick-start.ts - Script de démonstration de démarrage rapide montrant l'établissement d'une connexion Kora et l'exécution d'un appel simple au serveur RPC Kora
full-demo.ts - Script de démonstration complet illustrant plusieurs méthodes RPC Kora

Répertoire du serveur (server/)

kora.toml - Configuration Kora RPC définissant les règles de validation, les jetons autorisés et les paramètres de frais
signers.toml - Configuration des signataires définissant les signataires pour le serveur Kora

Configuration partagée

.env - Variables d'environnement pour les keypairs et adresses (créez .env à la racine - demo/.env). Les variables d'environnement seront créées par le script de configuration.

Configuration de l'environnement

Tout d'abord, créez le fichier .env pour votre environnement :

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

Configuration du client

Installez les dépendances du client :

# From project root (kora/)
cd examples/getting-started/demo/client
pnpm install --ignore-workspace # use --ignore-workspace to avoid pnpm workspace conflicts

Configuration du serveur Kora RPC

Le serveur Kora nécessite une configuration pour spécifier quels jetons peuvent être utilisés pour le paiement des frais. Ouvrez server/kora.toml et notez la section de validation. Ici, nous pouvons spécifier plusieurs paramètres qui seront validés avant de signer une transaction :

max_allowed_lamports : frais de transaction maximum que vous êtes prêt à payer au nom de l'utilisateur
max_signatures : nombre maximum de signatures qu'une transaction peut avoir
price_source : oracle pour déterminer le prix du jeton ("Mock" ou "Jupiter")
allowed_programs : liste blanche des ID de programmes pouvant être exécutés (par ex., System Program, Token Program)
allowed_tokens : liste blanche des jetons autorisés à être transférés
allowed_spl_paid_tokens : tableau d'adresses de mint que votre programme accepte comme paiement
disallowed_accounts : liste noire des comptes non autorisés à interagir avec votre RPC Kora

Pour l'instant, conservons les valeurs par défaut--vous pourrez revenir ici et les modifier ultérieurement (pour plus d'informations sur les options de configuration, consultez la documentation Configuration Kora).

Configuration des signataires

Ouvrez server/signers.toml et notez la section des signataires. Ici, nous pouvons spécifier quels signataires seront utilisés pour signer les transactions et (si vous utilisez plusieurs signataires) une stratégie pour sélectionner le signataire à utiliser. Pour l'instant, utilisons un signataire unique avec les valeurs par défaut--vous pourrez revenir ici et les modifier ultérieurement (pour plus d'informations sur la configuration des signataires, consultez la documentation Guide des signataires).

Serveur de test

Ouvrez trois terminaux et exécutez les commandes suivantes :

Terminal 1 : Démarrer le validateur de test local

# From project root or anywhere
solana-test-validator -r

Terminal 2 : Initialiser l'environnement

# From ./client directory
pnpm init-env

Ce script va :

Générer des paires de clés et les enregistrer dans .env
Airdrop de SOL vers les comptes de test
Créer et initialiser un jeton USDC local
Approvisionner les comptes de test avec des jetons

Important Assurez-vous de copier la clé publique du nouveau jeton USDC de test depuis votre .env et de mettre à jour les allowed_tokens et allowed_spl_paid_tokens dans ./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
]

Terminal 3 : Initialiser les ATA de paiement (Optionnel)

Pour recevoir des paiements, vous devrez initialiser des Associated Token Accounts (ATA) pour vos jetons de paiement. Vous pouvez le faire en exécutant la commande suivante :

# From ./server directory
kora rpc initialize-atas --signers-config signers.toml

Cette commande va :

Lire votre adresse de paiement depuis kora.toml (ou si vous n'avez pas spécifié d'adresse de paiement, tous les signataires listés dans signers.toml)
Créer des ATA pour tous les jetons listés dans allowed_spl_paid_tokens
Ignorer les ATA qui existent déjà
Vous pouvez éventuellement spécifier un payeur de frais personnalisé pour la génération d'ATA en utilisant le drapeau fee_payer_key.

Terminal 4 : Démarrer le serveur RPC Kora

# From ./server directory
kora rpc start --signers-config signers.toml

Remarque : Pour les déploiements en production utilisant price_source = "Jupiter", vous devez définir la variable d'environnement JUPITER_API_KEY. Le serveur ne démarrera pas sans cela :
JUPITER_API_KEY=your_api_key kora rpc start --signers-config signers.toml

Le serveur lit la configuration depuis kora.toml et signers.toml et utilise les variables d'environnement du fichier partagé .env. Si vous utilisez une structure de dossiers différente de celle spécifiée ici, vous devrez peut-être utiliser --config pour spécifier l'emplacement de kora.toml et --signers-config pour spécifier le répertoire de votre configuration de signataires :

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

Vous pouvez accéder à kora rpc -h pour obtenir de l'aide sur les options du serveur RPC.

Terminal 5 : Exécuter la démo client

# From ./client directory
pnpm start

Vous devriez voir une sortie similaire à :

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

Ceci confirme que votre serveur Kora fonctionne et est correctement configuré !

Prochaines étapes

Une fois la configuration de base opérationnelle, consultez la démo complète du flux Kora :

→ Flux complet de transaction sans frais Kora

explorez les méthodes RPC supplémentaires de Kora :

estimateTransactionFee - Calculer les frais pour les transactions
getPayerSigner - Obtenir le signataire payeur et la destination de paiement
getSupportedTokens - Renvoie un tableau des jetons de paiement pris en charge
signTransaction - Signer conditionnellement les transactions lorsque les frais sont couverts
transferTransaction - Créer des transactions de transfert SOL ou de jetons SPL (signées par le payeur de frais Kora)
signAndSendTransaction - Signe conditionnellement une transaction avec le payeur de frais Kora et l'envoie au RPC Solana configuré
getPaymentInstruction - Obtenir une instruction de paiement pour une transaction

Vous avez des questions ? Posez vos questions sur Solana Stack Exchange avec un tag Kora.

Table des matières