Przewodnik szybkiego startu Kora

Ostatnia aktualizacja: 2025-10-31

Podstawy Kora

Kora to serwer JSON-RPC, który zapewnia usługi płatności za opłaty transakcyjne w Solana. Umożliwia użytkownikom opłacanie opłat transakcyjnych tokenami SPL zamiast SOL, zapewniając lepsze doświadczenie użytkownika w aplikacjach, gdzie użytkownicy mogą nie posiadać SOL.

RPC Kora waliduje żądania klientów na podstawie konfiguracji (kora.toml), która definiuje dopuszczalne programy, portfele, tokeny itp. Po walidacji serwer Kora podpisze transakcję i wyśle ją do sieci (lub zwróci serializowaną podpisaną transakcję klientowi).

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

Ten przewodnik szybkiego startu uruchomi lokalny serwer RPC Kora i zademonstruje integrację klienta do testowania przepływów płatności za opłaty.

Wymagania

Solana CLI w wersji 2.2.x lub nowszej
Rust/Cargo (do instalacji Kora RPC)
Node.js v22+ i menedżer pakietów (np. pnpm, npm)

Instalacja Kora RPC

Zainstaluj serwer Kora RPC globalnie:

cargo install kora-cli

Ważne: Gałąź main Kora jest gałęzią integracyjną i może zawierać niewydane lub beta zmiany. Zawsze używaj najnowszego stabilnego tagu wydania do zastosowań produkcyjnych i tutoriali. Najnowsze stabilne wydanie znajdziesz na stronie wydań Kora.

Tworzenie projektu

Sklonuj repozytorium, przełącz się na najnowszy stabilny tag i przejdź do katalogu demonstracyjnego wprowadzenia:

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

Struktura projektu

Demo zawiera trzy główne komponenty:

Katalog klienta (client/src/)

setup.ts - Konfiguracja środowiska lokalnego (tworzy pary kluczy i zapisuje je do .env, rozdaje SOL, inicjalizuje token testowy)
quick-start.ts - Skrypt demonstracyjny szybkiego startu pokazujący nawiązywanie połączenia z Kora i wykonywanie prostego wywołania do serwera RPC Kora
full-demo.ts - Pełny skrypt demonstracyjny prezentujący wiele metod RPC Kora

Katalog serwera (server/)

kora.toml - Konfiguracja Kora RPC definiująca reguły walidacji, dozwolone tokeny i parametry opłat
signers.toml - Konfiguracja signerów definiująca signery dla serwera Kora

Wspólna konfiguracja

.env - Zmienne środowiskowe dla keypairów i adresów (utwórz .env w katalogu głównym - demo/.env). Zmienne środowiskowe zostaną utworzone przez skrypt konfiguracyjny.

Konfiguracja środowiska

Najpierw utwórz .env dla swojego środowiska:

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

Konfiguracja klienta

Zainstaluj zależności klienta:

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

Konfiguracja serwera Kora RPC

Serwer Kora wymaga konfiguracji określającej, które tokeny mogą być używane do płatności za opłaty. Otwórz server/kora.toml i zwróć uwagę na sekcję walidacji. Tutaj możemy określić kilka parametrów, które będą walidowane przed podpisaniem transakcji:

max_allowed_lamports: maksymalna opłata transakcyjna, którą jesteś skłonny zapłacić w imieniu użytkownika
max_signatures: maksymalna liczba podpisów, które może posiadać transakcja
price_source: oracle do określania ceny tokena ("Mock" lub "Jupiter")
allowed_programs: biała lista identyfikatorów programów, które mogą być wykonywane (np. System Program, Token Program)
allowed_tokens: biała lista tokenów, które mogą być transferowane
allowed_spl_paid_tokens: tablica adresów mint akceptowanych przez Twój program jako płatność
disallowed_accounts: czarna lista kont, którym nie wolno wchodzić w interakcje z Twoim kora RPC

Na razie zostawmy wartości domyślne--możesz tutaj wrócić i zmienić je później (aby uzyskać więcej informacji na temat opcji konfiguracji, zobacz dokumentację Konfiguracja Kora).

Konfiguracja signerów

Otwórz server/signers.toml i zwróć uwagę na sekcję signerów. Tutaj możemy określić, które signery będą używane do podpisywania transakcji oraz (w przypadku użycia wielu signerów) strategię wyboru, którego signera użyć. Na razie użyjmy pojedynczego signera z wartościami domyślnymi--możesz tutaj wrócić i zmienić je później (aby uzyskać więcej informacji na temat konfiguracji signerów, zobacz dokumentację Przewodnik po signerach).

Serwer testowy

Otwórz trzy terminale i wykonaj następujące polecenia:

Terminal 1: Uruchom lokalny walidator testowy

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

Terminal 2: Zainicjuj środowisko

# From ./client directory
pnpm init-env

Ten skrypt wykona następujące operacje:

Wygeneruje pary kluczy i zapisze je w .env
Dostarczy SOL na konta testowe
Utworzy i zainicjuje lokalny token USDC
Zafinansuje konta testowe tokenami

Ważne Upewnij się, że skopiowałeś klucz publiczny nowego testowego tokena USDC ze swojego pliku .env i zaktualizowałeś allowed_tokens oraz allowed_spl_paid_tokens w pliku ./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: Zainicjuj ATA dla płatności (opcjonalne)

Aby móc otrzymywać płatności, musisz zainicjować powiązane konta tokenów (Associated Token Accounts - ATA) dla swoich tokenów płatności. Możesz to zrobić, wykonując następujące polecenie:

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

To polecenie wykona następujące operacje:

Odczyta Twój adres płatności z kora.toml (lub jeśli nie określiłeś adresu płatności, wszystkich podpisujących wymienionych w signers.toml)
Utworzy ATA dla wszystkich tokenów wymienionych w allowed_spl_paid_tokens
Pominie wszystkie ATA, które już istnieją
Możesz opcjonalnie określić niestandardowego płatnika opłat za generowanie ATA, używając flagi fee_payer_key.

Terminal 4: Uruchom serwer RPC Kora

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

Uwaga: W przypadku wdrożeń produkcyjnych używających price_source = "Jupiter", musisz ustawić zmienną środowiskową JUPITER_API_KEY. Serwer nie uruchomi się bez niej:
JUPITER_API_KEY=your_api_key kora rpc start --signers-config signers.toml

Serwer odczytuje konfigurację z kora.toml i signers.toml oraz wykorzystuje zmienne środowiskowe ze współdzielonego pliku .env. Jeśli używasz innej struktury folderów niż tutaj określona, może być konieczne użycie --config w celu określenia lokalizacji kora.toml oraz --signers-config w celu określenia katalogu Twojej konfiguracji podpisujących:

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

Możesz uzyskać dostęp do kora rpc -h, aby uzyskać pomoc dotyczącą opcji serwera RPC.

Terminal 5: Uruchom demo klienta

# From ./client directory
pnpm start

Powinieneś zobaczyć wynik podobny do:

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

To potwierdza, że Twój serwer Kora działa i jest prawidłowo skonfigurowany!

Kolejne kroki

Po uruchomieniu podstawowej konfiguracji, sprawdź pełne demo przepływu Kora:

→ Pełny przepływ transakcji bez opłat w Kora

poznaj dodatkowe metody RPC Kora:

estimateTransactionFee - Oblicz opłaty za transakcje
getPayerSigner - Pobierz podpisującego płatnika i miejsce docelowe płatności
getSupportedTokens - Zwraca tablicę obsługiwanych tokenów płatności
signTransaction - Warunkowo podpisuje transakcje, gdy opłaty są pokryte
transferTransaction - Tworzy transakcje transferu SOL lub tokenów SPL (podpisane przez płatnika opłat Kora)
signAndSendTransaction - Warunkowo podpisuje transakcję płatnikiem opłat Kora i wysyła ją do skonfigurowanego Solana RPC
getPaymentInstruction - Pobierz instrukcję płatności dla transakcji

Masz pytania? Zadaj pytania na Solana Stack Exchange z tagiem Kora.

Spis treści