新配置选项（测试版）

这些配置选项从 v2.2.0-beta.1 开始提供。将它们添加到现有的 kora.toml 中，与稳定配置一起使用。

交易插件

[kora.plugins] 部分配置在签名流程中运行的交易插件。插件在 Kora 签名之前验证交易的结构和内容。它们适用于 signTransaction、signAndSendTransaction、signBundle 和 signAndSendBundle — 但不适用于 estimateBundleFee。

[kora.plugins]
enabled = ["gas_swap"]

gas_swap 插件

gas_swap 插件对无 gas 代币换 SOL 交易操作强制执行严格的交易结构。启用后，通过签名流程提交的每笔交易必须恰好包含：

1. 一笔 SPL 代币转账（SPL Token 或 Token-2022）— 来自非手续费支付者所有者
2. 一笔 System SOL 转账（Transfer 或 TransferWithSeed）— 来自手续费支付者

计算预算指令（设置计算单元限制/价格）允许与这两个必需指令一起使用。任何额外的或非交换的外层指令都将被拒绝。

配置要求

gas_swap 插件在启动时验证您的配置，如果不满足要求将报错：

• System Program 必须在 allowed_programs 中
• 至少一个代币程序（SPL Token 或 Token-2022）必须在 allowed_programs 中
• 至少一个代币必须在 allowed_tokens 中
• 定价模型不能是 Free — 设置保证金或固定价格

[kora.plugins]
enabled = ["gas_swap"]

[validation]
allowed_programs = [
    "11111111111111111111111111111111",              # System Program
    "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",  # SPL Token Program
    "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb",  # Token-2022 Program
]
allowed_tokens = [
    "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", # USDC
]

[validation.price]
type = "margin"
margin = 0.0

**警告：**当使用 gas_swap 和固定定价时，请确保固定代币手续费至少价值 max_allowed_lamports 的 SOL，以避免出现发送的 SOL 超过接收的代币价值的消耗情况。

捆绑配置

INLINE_CODE_PLACEHOLDER_78b835d294b52f52_END 部分启用 Jito 捆绑支持，用于原子化多交易执行：

[kora.bundle]
enabled = true

[kora.bundle.jito]
block_engine_url = "https://mainnet.block-engine.jito.wtf"

Jito 配置

可用的 Jito 区块引擎 URL：

• 主网（公开）： https://mainnet.block-engine.jito.wtf
• 主网（私有）： 请联系 Jito 获取访问权限

重要提示： 当使用由 Kora 支付 Jito 小费的捆绑时，请在 [validation.fee_payer_policy.system] 中设置 allow_transfer = true，以允许签名者转移 SOL 支付小费。

有关使用 Kora 实现 Jito 捆绑的完整指南，请参阅 Jito 捆绑指南。

Lighthouse 费用支付者保护

[kora.lighthouse] 部分启用 Lighthouse 费用支付者保护。启用后，Kora 会向交易添加余额断言指令，通过验证费用支付者的余额不会低于预期水平来保护其免受耗尽攻击。

[kora.lighthouse]
enabled = true
fail_if_transaction_size_overflow = true

工作原理

当启用 Lighthouse 时，Kora 会获取费用支付者的当前余额，并添加一个 Lighthouse 断言指令，验证余额在交易完成时不会低于 (current_balance - estimated_fee)。这可以防止恶意交易将费用支付者的余额耗尽到超出预期成本。

方法兼容性

Lighthouse 保护仅适用于 signTransaction 和 signBundle。它 不适用于 signAndSendTransaction 或 signAndSendBundle。

当 Lighthouse 添加断言指令时,它会修改交易消息。这会使任何预先存在的客户端签名失效。signAndSend* 流程将失败,原因如下:

1. 客户端对交易进行签名
2. Kora 添加 Lighthouse 断言(修改消息)
3. 客户端的原始签名失效
4. 网络以"签名验证失败"拒绝交易

使用 Lighthouse 的推荐模式:

signTransaction → client receives modified tx → client re-signs → client sends to network

配置要求

启用 Lighthouse 时,请将 Lighthouse 程序添加到您的 allowed_programs 中:

[validation]
allowed_programs = [
    # ... other programs ...
    "L2TExMFKdjpN9kozasaurPirfHy9P8sbXoAN1qA3S95",  # Lighthouse Program
]

Kora 会在启动时验证此配置,如果启用了 Lighthouse 但程序不在 allowed_programs 中,将会报错。

注意: 如果 signAndSendTransaction 或 signAndSendBundle 与Lighthouse 同时启用,Kora 将记录警告,提示这些方法不会具有手续费支付者保护。

reCAPTCHA 机器人防护

reCAPTCHA v3 为敏感端点提供隐式机器人防护。与对所有请求进行身份验证的 API Key 和 HMAC 不同,reCAPTCHA 仅保护特定的高风险方法(默认为签名方法)。

服务器配置

将 KORA_RECAPTCHA_SECRET 添加到您的环境变量中(具有优先级),或在您的 kora.toml 中添加 recaptcha_secret:

[kora.auth]
recaptcha_secret = "your-recaptcha-v3-secret-key"
recaptcha_score_threshold = 0.5  # Optional: 0.0-1.0, default 0.5
protected_methods = ["signTransaction", "signAndSendTransaction", "signBundle", "signAndSendBundle"]  # Optional

工作原理

1. 客户端从 Google 的 reCAPTCHA v3 API 获取 reCAPTCHA 令牌
2. 客户端在 x-recaptcha-token 标头中包含该令牌
3. 服务器通过 Google 验证令牌并检查分数
4. 如果分数 >= 阈值,请求继续处理;否则返回 401 未授权

reCAPTCHA 在 API 密钥/HMAC 身份验证成功之后运行（如果已配置）。未受保护的方法会完全绕过 reCAPTCHA 验证。

客户端实现

使用 Kora SDK：

const { KoraClient } = require("@solana/kora");

const kora = new KoraClient({
  rpcUrl: "http://localhost:8080",
  apiKey: process.env.KORA_API_KEY,
  // Callback called for each request - return fresh token
  getRecaptchaToken: async () => {
    return await grecaptcha.execute("your-site-key", { action: "sign" });
  }
});

// Token is automatically included for all requests
const result = await kora.signTransaction({ transaction: "base64..." });

使用 fetch：

async function callKoraProtectedMethod(method, params = {}) {
  const recaptchaToken = await grecaptcha.execute("your-site-key", {
    action: "sign"
  });

  const response = await fetch("http://localhost:8080", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-recaptcha-token": recaptchaToken
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      method,
      params,
      id: 1
    })
  });

  return response.json();
}

获取 reCAPTCHA 密钥

1. 访问 Google reCAPTCHA 管理控制台
2. 使用 reCAPTCHA v3 创建新站点
3. 在前端（客户端）使用网站密钥
4. 在 Kora 配置（服务器端）使用密钥

使用限制

[kora.usage_limit] 部分配置每个钱包的使用限制，以防止滥用并确保公平使用。这也可用于创建奖励计划，为用户的交易费用提供补贴，直至达到一定限额。

注意：当在多个 Kora 实例中启用此功能时，需要 Redis。

[kora.usage_limit]
enabled = true
cache_url = "redis://localhost:6379"
fallback_if_unavailable = true

fallback_if_unavailable

使用限制规则

该测试版引入了细粒度的基于规则的使用限制。您可以定义多个规则来针对特定的交易类型或单个指令，并可选择时间窗口，而不是单一的 max_transactions 计数。

[[kora.usage_limit.rules]]
type = "transaction"
max = 100
window_seconds = 86400  # 100 transactions per day

[[kora.usage_limit.rules]]
type = "instruction"
program = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
instruction = "Transfer"
max = 50
window_seconds = 3600  # 50 SPL transfers per hour

当设置 window_seconds 时,计数器会在时间窗口到期后重置。如果不设置,限制将是永久性的——一旦达到限制,钱包将被阻止,直到从 Redis 中手动清除。

新增启用的方法

以下方法已添加到 [kora.enabled_methods]:

[kora.enabled_methods]
get_version = true
estimate_bundle_fee = true
sign_bundle = false
sign_and_send_bundle = false

完整的 API 文档请参阅 捆绑包方法。