Kora 快速入门指南

最后更新：2025-10-31

Kora 基础知识

Kora 是一个 JSON-RPC 服务器，为 Solana 交易提供费用支付服务。它允许用户使用 SPL 代币而非 SOL 支付交易费用，为用户可能不持有 SOL 的应用程序提供更好的用户体验。

Kora RPC 根据配置（kora.toml）验证客户端请求，该配置定义了允许的程序、钱包、代币等。验证通过后，Kora 服务器将对交易进行签名并将其发送到网络（或向客户端返回序列化的已签名交易）。

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

本快速入门将启动本地 Kora RPC 服务器，并演示用于测试费用支付工作流程的客户端集成。

要求

Solana CLI v2.2.x 或更高版本
Rust/Cargo （用于 Kora RPC 安装）
Node.js v22+ 和包管理器（例如 pnpm、npm）

安装 Kora RPC

全局安装 Kora RPC 服务器：

cargo install kora-cli

重要提示： Kora 的 main 分支是一个集成分支，可能包含未发布或测试版的更改。对于生产环境和教程使用，请始终使用最新的稳定版本标签。您可以在 Kora 发布页面找到最新的稳定版本。

创建项目

克隆代码仓库，检出最新的稳定标签，并导航到入门演示目录：

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

项目结构

演示包含三个主要组件：

客户端目录（client/src/）

setup.ts - 本地环境设置（创建密钥对并将其写入 .env 文件、空投 SOL、初始化测试代币）
quick-start.ts - 快速入门演示脚本，展示建立 Kora 连接并对 Kora RPC 服务器进行简单调用
full-demo.ts - 完整演示脚本，展示多个 Kora RPC 方法

服务器目录 (server/)

kora.toml - Kora RPC 配置文件,定义验证规则、允许的代币和手续费参数
signers.toml - 签名者配置文件,定义 Kora 服务器的签名者

共享配置

.env - keypair 和地址的环境变量(在根目录 - demo/.env 中创建 .env)。环境变量将由设置脚本创建。

设置环境

首先,为您的环境创建 .env 文件:

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

设置客户端

安装客户端依赖项:

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

设置 Kora RPC 服务器

Kora 服务器需要配置以指定哪些代币可用于支付手续费。打开 server/kora.toml 并注意验证部分。在这里我们可以指定在签署交易之前将被验证的几个参数:

max_allowed_lamports:您愿意代表用户支付的最大交易手续费
max_signatures:交易可以拥有的最大签名数量
price_source:用于确定代币价格的预言机("Mock" 或 "Jupiter")
allowed_programs:可执行的程序 ID 白名单(例如 System Program、Token Program)
allowed_tokens:允许转账的代币白名单
allowed_spl_paid_tokens:您的程序接受作为支付方式的铸币地址数组
disallowed_accounts:不允许与您的 Kora RPC 交互的账户黑名单

目前,让我们保留默认值——您可以稍后回到这里更改这些设置(有关配置选项的更多信息,请参阅 Kora 配置文档)。

设置签名者

打开 server/signers.toml 并注意签名者部分。在这里我们可以指定将用于签署交易的签名者,以及(如果使用多个签名者)选择使用哪个签名者的策略。目前,让我们使用默认值的单一签名者——您可以稍后回到这里更改这些设置(有关签名者配置的更多信息,请参阅签名者指南文档)。

测试服务器

打开三个终端并运行以下命令：

终端 1：启动本地测试验证器

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

终端 2：初始化环境

# From ./client directory
pnpm init-env

此脚本将：

生成密钥对并保存到 .env
向测试账户空投 SOL
创建并初始化本地 USDC 代币
为测试账户充值代币

重要提示 请确保从 .env 文件中复制新 USDC 测试代币的公钥，并更新 ./server/kora.toml 中的 allowed_tokens 和 allowed_spl_paid_tokens。

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
]

终端 3：初始化支付关联代币账户（可选）

为了接收付款，您需要为支付代币初始化关联代币账户（ATA）。您可以通过运行以下命令来完成此操作：

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

此命令将：

从 kora.toml 读取您的支付地址（如果您未指定支付地址，则读取 signers.toml 中列出的所有签名者）
为 allowed_spl_paid_tokens 中列出的所有代币创建关联代币账户
跳过已存在的关联代币账户
您可以选择使用 fee_payer_key 标志为关联代币账户生成指定自定义手续费支付方。

终端 4：启动 Kora RPC 服务器

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

注意： 对于使用 price_source = "Jupiter" 的生产环境部署，您必须设置 JUPITER_API_KEY 环境变量。如果没有设置，服务器将无法启动：
JUPITER_API_KEY=your_api_key kora rpc start --signers-config signers.toml

服务器从 kora.toml 和 signers.toml 读取配置，并使用共享的 .env 文件中的环境变量。如果您使用的文件夹结构与此处指定的不同，您可能需要使用 --config 指定 kora.toml 的位置，并使用 --signers-config 指定签名者配置的目录：

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

您可以访问 kora rpc -h 获取有关 RPC 服务器选项的帮助。

终端 5：运行客户端演示

# From ./client directory
pnpm start

您应该看到类似的输出：

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

这确认您的 Kora 服务器正在运行并已正确配置！

后续步骤

一旦基本设置正常运行，请查看完整的 Kora 流程演示：

→ Kora 完整无燃料费交易流程

探索其他 Kora RPC 方法：

estimateTransactionFee - 计算交易费用
getPayerSigner - 获取付款签名者和付款目的地
getSupportedTokens - 返回支持的支付代币数组
signTransaction - 在费用被覆盖时有条件地签署交易
transferTransaction - 创建转账 SOL 或 SPL 代币转账交易（由 Kora 费用支付方签署）
signAndSendTransaction - 使用 Kora 费用支付方有条件地签署交易并将其发送到配置的 Solana RPC
getPaymentInstruction - 获取交易的支付指令

有疑问？ 在 Solana Stack Exchange 上使用 Kora 标签提问。

Table of Contents