Новые параметры конфигурации (бета)

Эти параметры конфигурации доступны начиная с v2.2.0-beta.1. Добавьте их в существующий kora.toml вместе со стабильной конфигурацией.

Плагины транзакций

Раздел [kora.plugins] настраивает плагины транзакций, которые выполняются во время процессов подписания. Плагины проверяют структуру и содержимое транзакций перед тем, как Kora их подписывает. Они выполняются для signTransaction, signAndSendTransaction, signBundle и signAndSendBundle — но не для estimateBundleFee.

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

Плагин gas_swap

Плагин gas_swap обеспечивает строгую структуру транзакции для операций обмена токенов на SOL без комиссий. При включении каждая транзакция, отправленная через процессы подписания, должна содержать точно:

1. Один перевод токена SPL (SPL Token или Token-2022) — от владельца, не являющегося плательщиком комиссии
2. Один перевод 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 превышает полученный токен.

Конфигурация бандлов

Секция [kora.bundle] включает поддержку бандлов Jito для атомарного выполнения мультитранзакций:

[kora.bundle]
enabled = true

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

Конфигурация Jito

Доступные URL блок-движков Jito:

• Mainnet (публичный): https://mainnet.block-engine.jito.wtf
• Mainnet (приватный): Свяжитесь с Jito для получения доступа

Важно: При использовании бандлов с оплатой чаевых Jito через Kora установите allow_transfer = true в [validation.fee_payer_policy.system], чтобы разрешить подписывающему лицу переводить SOL для чаевых.

Полное руководство по реализации бандлов Jito с Kora смотрите в Руководстве по бандлам 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-ключа и HMAC, которые аутентифицируют все запросы, reCAPTCHA защищает только определенные высокорисковые методы (по умолчанию методы подписи).

Конфигурация сервера

Добавьте KORA_RECAPTCHA_SECRET в переменные окружения (имеет приоритет), или добавьте recaptcha_secret в ваш kora.toml:

[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. Клиент получает токен reCAPTCHA из API Google reCAPTCHA v3
2. Клиент включает токен в заголовок x-recaptcha-token
3. Сервер проверяет токен у Google и проверяет балл
4. Если балл >= порогового значения, запрос продолжается; в противном случае возвращается 401 Unauthorized

reCAPTCHA запускается после успешной аутентификации API Key/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. Используйте Site Key на вашем фронтенде (клиентская сторона)
4. Используйте Secret Key в конфигурации Kora (серверная сторона)

Лимиты использования

Раздел [kora.usage_limit] настраивает лимиты использования для каждого кошелька, чтобы предотвратить злоупотребления и обеспечить справедливое использование. Эту функцию также можно использовать для создания программ поощрений, субсидирующих комиссии пользователей до определенного лимита.

Примечание: Эта функция требует Redis при использовании на нескольких экземплярах Kora.

[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 см. в разделе Методы работы с пакетами.