Tài liệu SolanaBắt đầu

Hướng dẫn Bắt đầu Nhanh với Kora

Cập nhật lần cuối: 2025-10-31

Kiến thức Cơ bản về Kora

Kora là một máy chủ JSON-RPC cung cấp dịch vụ thanh toán phí cho các giao dịch Solana. Nó cho phép người dùng thanh toán phí giao dịch bằng token SPL thay vì SOL, mang lại trải nghiệm người dùng tốt hơn cho các ứng dụng mà người dùng có thể không nắm giữ SOL.

Kora RPC xác thực các yêu cầu từ client dựa trên cấu hình (kora.toml) định nghĩa các chương trình, ví, token được phép, v.v. Sau khi xác thực, máy chủ Kora sẽ ký giao dịch và gửi nó đến mạng lưới (hoặc trả về một giao dịch đã ký được serialize cho client).

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

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

│                 │    │   Server        │    │                 │

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

                              │

                              ▼

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

                       │   Kora Private Key   │

                       │ ( or Turnkey/Privy ) │

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

Hướng dẫn bắt đầu nhanh này sẽ khởi chạy một máy chủ Kora RPC cục bộ và trình diễn việc tích hợp client để kiểm tra quy trình thanh toán phí.

Yêu cầu

Cài đặt Kora RPC

Cài đặt máy chủ Kora RPC toàn cục:

cargo install kora-cli

Quan trọng: Nhánh main của Kora là nhánh tích hợp và có thể chứa các thay đổi chưa phát hành hoặc đang trong giai đoạn beta. Luôn sử dụng thẻ phát hành ổn định mới nhất cho môi trường production và sử dụng trong hướng dẫn. Bạn có thể tìm phiên bản ổn định mới nhất trên trang phát hành Kora.

Tạo Dự án

Sao chép repository, checkout thẻ ổn định mới nhất, và điều hướng đến thư mục demo bắt đầu:

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

cd kora

git checkout v2.0.5

cd examples/getting-started/demo

Cấu trúc Dự án

Demo bao gồm ba thành phần chính:

Thư mục Client (client/src/)

  • setup.ts - Thiết lập môi trường cục bộ (tạo keypair & ghi chúng vào .env, airdrop SOL, khởi tạo token thử nghiệm)
  • quick-start.ts - Script trình diễn bắt đầu nhanh cho thấy cách thiết lập kết nối Kora và thực hiện một cuộc gọi đơn giản đến máy chủ Kora RPC
  • full-demo.ts - Script demo đầy đủ trình diễn nhiều phương thức Kora RPC

Thư mục Server (server/)

  • kora.toml - Cấu hình Kora RPC xác định các quy tắc xác thực, token được phép và các tham số phí
  • signers.toml - Cấu hình người ký xác định các signer cho máy chủ Kora

Cấu hình Dùng chung

  • .env - Biến môi trường cho keypair và địa chỉ (tạo .env trong thư mục gốc - demo/.env). Các biến môi trường sẽ được tạo bởi script thiết lập.

Thiết lập Môi trường

Đầu tiên, tạo .env cho môi trường của bạn:

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

touch .env

Thiết lập Client

Cài đặt các dependency cho client:

# From project root (kora/)

cd examples/getting-started/demo/client

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

Thiết lập Máy chủ Kora RPC

Máy chủ Kora yêu cầu cấu hình để chỉ định token nào có thể được sử dụng để thanh toán phí. Mở server/kora.toml và chú ý phần validation. Tại đây chúng ta có thể chỉ định nhiều tham số sẽ được xác thực trước khi ký một giao dịch:

  • max_allowed_lamports: phí giao dịch tối đa bạn sẵn sàng thanh toán thay mặt người dùng
  • max_signatures: số lượng chữ ký tối đa mà một giao dịch có thể có
  • price_source: oracle để xác định giá token ("Mock" hoặc "Jupiter")
  • allowed_programs: danh sách trắng các ID chương trình có thể được thực thi (ví dụ: System Program, Token Program)
  • allowed_tokens: danh sách trắng các token được phép chuyển
  • allowed_spl_paid_tokens: mảng các địa chỉ mint mà chương trình của bạn chấp nhận làm phương thức thanh toán
  • disallowed_accounts: danh sách đen các tài khoản không được phép tương tác với Kora RPC của bạn

Hiện tại, hãy giữ nguyên các giá trị mặc định--bạn có thể quay lại đây và thay đổi chúng sau (để biết thêm thông tin về các tùy chọn cấu hình, xem tài liệu Cấu hình Kora).

Thiết lập Signers

Mở server/signers.toml và chú ý phần signers. Tại đây chúng ta có thể chỉ định signer nào sẽ được sử dụng để ký giao dịch và (nếu sử dụng nhiều signer) một chiến lược để chọn signer nào sẽ dùng. Hiện tại, hãy sử dụng signer đơn với các giá trị mặc định--bạn có thể quay lại đây và thay đổi chúng sau (để biết thêm thông tin về cấu hình signers, xem tài liệu Hướng dẫn Signers).

Máy chủ kiểm thử

Mở ba cửa sổ terminal và chạy các lệnh sau:

Terminal 1: Khởi động Local Test Validator

# From project root or anywhere

solana-test-validator -r

Terminal 2: Khởi tạo môi trường

# From ./client directory

pnpm init-env

Script này sẽ:

  • Tạo keypair và lưu vào .env
  • Airdrop SOL cho các tài khoản kiểm thử
  • Tạo và khởi tạo token USDC cục bộ
  • Nạp token cho các tài khoản kiểm thử

Quan trọng Hãy đảm bảo bạn sao chép khóa công khai (public key) của token USDC kiểm thử mới từ tệp .env của bạn và cập nhật allowed_tokens và allowed_spl_paid_tokens trong ./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: Khởi tạo ATA thanh toán (Tùy chọn)

Để nhận thanh toán, bạn cần khởi tạo Associated Token Account (ATA) cho các token thanh toán của mình. Bạn có thể thực hiện điều này bằng cách chạy lệnh sau:

# From ./server directory

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

Lệnh này sẽ:

  • Đọc địa chỉ thanh toán của bạn từ kora.toml (hoặc nếu bạn chưa chỉ định địa chỉ thanh toán, tất cả các signer được liệt kê trong signers.toml)
  • Tạo ATA cho tất cả các token được liệt kê trong allowed_spl_paid_tokens
  • Bỏ qua bất kỳ ATA nào đã tồn tại
  • Bạn có thể tùy chọn chỉ định người trả phí tùy chỉnh cho việc tạo ATA bằng cách sử dụng cờ fee_payer_key.

Terminal 4: Khởi động máy chủ Kora RPC

# From ./server directory

kora rpc start --signers-config signers.toml

Lưu ý: Đối với triển khai production sử dụng price_source = "Jupiter", bạn phải thiết lập biến môi trường JUPITER_API_KEY. Máy chủ sẽ không khởi động được nếu thiếu:

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

Máy chủ đọc cấu hình từ kora.toml và signers.toml và sử dụng các biến môi trường từ tệp .env được chia sẻ. Nếu bạn đang sử dụng cấu trúc thư mục khác với những gì được chỉ định ở đây, bạn có thể cần sử dụng --config để chỉ định vị trí của kora.toml và --signers-config để chỉ định thư mục cấu hình signer của bạn:

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

Bạn có thể truy cập kora rpc -h để được trợ giúp về các tùy chọn máy chủ RPC.

Terminal 5: Chạy Demo Client

# From ./client directory

pnpm start

Bạn sẽ thấy kết quả tương tự như sau:

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

Điều này xác nhận máy chủ Kora của bạn đang chạy và được cấu hình đúng cách!

Các Bước Tiếp Theo

Sau khi thiết lập cơ bản hoạt động, hãy xem demo luồng Kora đầy đủ:

→ Luồng Giao Dịch Không Gas Hoàn Chỉnh của Kora

khám phá các phương thức RPC bổ sung của Kora:

  • estimateTransactionFee - Tính phí cho các giao dịch
  • getPayerSigner - Lấy người ký trả phí và địa chỉ thanh toán
  • getSupportedTokens - Trả về một mảng các token thanh toán được hỗ trợ
  • signTransaction - Ký giao dịch có điều kiện khi phí được chi trả
  • transferTransaction - Tạo giao dịch chuyển SOL hoặc chuyển token SPL (được ký bởi người trả phí Kora)
  • signAndSendTransaction - Ký có điều kiện một giao dịch bằng người trả phí Kora và gửi nó đến RPC Solana đã cấu hình
  • getPaymentInstruction - Lấy chỉ thị thanh toán cho một giao dịch

Có câu hỏi? Đặt câu hỏi trên Solana Stack Exchange với thẻ Kora.

Is this page helpful?

Trước

Cài đặt

Tiếp theo

Tài Liệu Vận Hành Kora

Mục lục

Chỉnh sửa trang

Quản lý bởi

© 2026 Solana Foundation.
Đã đăng ký bản quyền.
Solana
Kết nối