Kora Operators Documentation

Getting started as a Kora node operator

What is a Kora Node Operator?

As a Kora node operator, you run a paymaster service that sponsors Solana transaction fees for your users. Your node accepts SPL token payments and uses your SOL to pay actual network fees, enabling gasless transactions for your application.

Why Run a Kora Node?

  • Better UX: Your users transact without needing SOL (streamlined onboarding, better retention, etc.)
  • Revenue Stream: Collect fees in tokens your business prefers (USDC, BONK, etc.)

Contents

Quick Start

Want to try locally first? Spin up a local Kora node in a few minutes: → Local Quick Start Guide

Core Concepts

As a Kora node operator, you're responsible for running a secure paymaster service that enables gasless transactions for your users. Your node has four key responsibilities:

1. Validate Transactions

Configure your node to accept only transactions that meet your business requirements via kora.toml:

  • Token allowlists: Define which SPL tokens you accept as payment (supports both SPL and Token-2022)
  • Program allowlists: Whitelist which Solana programs users can interact with
  • Transaction limits: Set maximum fees you're willing to pay and signature limits
  • Account blocklists: Prevent interactions with problematic addresses
  • Pricing oracles: Configure Jupiter or mock pricing for fee calculations
  • Payment tokens: Specify which type of tokens you will accept as payment
  • Feepayer policies: Control what operations your feepayer can perform (transfers, burns, approvals, etc.)
  • Token-2022 extensions: Block specific Token-2022 extensions for enhanced security
  • Caching: Enable Redis caching to improve performance by reducing RPC calls
  • Usage limits: Set per-wallet transaction limits to prevent abuse, ensure fair usage, or reward users with subsidized transactions up to a certain limit

→ Complete Kora.toml Configuration Reference → Sample kora.toml

2. Sign Transactions

Your node needs Solana keypair(s) to sign transactions as the fee payer. For production deployments, Kora supports multi-signer configurations for improved reliability and account-lock distribution. Consider implementing key rotation, access controls, backups, and other strategies for signer security. Signing options available:

  • Local Private Key: Store private key directly in server environment (as base58, .json file, or u8 array)
  • Turnkey: Private key management made simple. Create wallets, sign transactions, and automate onchain actions.
  • Privy: Easy crypto infrastructure. Securely spin up whitelabel wallets and sign transactions.
  • HashiCorp Vault: Manage Secrets & Protect Sensitive Data

→ Complete Signers Configuration Guide

3. Pay Transaction Fees

Maintain sufficient SOL to cover network fees for your expected transaction volume:

  • Balance monitoring: Track SOL balance and set up low-balance alerts (Kora provides built-in Prometheus metrics - see Monitoring)
  • Automation: Implement automatic SOL top-up procedures for production environments
  • Capacity planning: Plan for expected use case, user volume, etc.

It is important that you understand how Kora estimates fees and how to configure your node to maximize your revenue. See the Fee Estimation Guide for more details.

4. Monitor Operations

Continuously track your node's security, performance, and business metrics:

  • Security monitoring: Unusual patterns, failed validations, and rate limit breaches
  • Operational alerts: System health, balance warnings, and security events
  • Financial tracking: SOL costs vs. token revenue, profitability analysis
  • Signer balance monitoring: Track signer balance and set up low-balance alerts

Kora provides an optional /metrics endpoint that provides real-time performance data in Prometheus format.

→ Kora Monitoring Reference Guide

5. Optimize Performance (Optional)

For high-traffic deployments, enable Redis caching to reduce RPC calls and improve response times:

  • Account caching: Cache Solana account data with configurable time to live (TTL)
  • Automatic fallback: Gracefully falls back to direct RPC calls if Redis is unavailable
  • Cache management: Automatic expiration and force-refresh capabilities for critical operations

Kora CLI

The kora-cli crate is a production-ready Rust binary that provides everything you need to run a Kora paymaster node. It's distributed as a standalone executable that you can install globally or deploy in containers.

Installation Options

Global Installation (recommended for development)

cargo install kora-cli

Or build from source (recommended for contributing)

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

Basic Usage

The Kora RPC server exposes a JSON-RPC endpoint (default: http://localhost:8080). Launch it with the kora rpc command:

# Run with specified kora.toml and signers.toml
kora --config path/to/kora.toml rpc start --signers-config path/to/signers.toml

# Help
kora rpc --help

For more information on the using the Kora CLI, see the CLI Guide.

Applications can access the Kora RPC Server via the Kora TS SDK

Configuration

Every Kora RPC node must be configured with at least:

  • a Solana RPC endpoint (specified via the --rpc-url flag or RPC_URL environment variable) [default: http://127.0.0.1:8899]
  • Solana signer(s) configuration (specified via the --signers-config signers.toml flag)
  • a config file, kora.toml (specified via the --config path/to/kora.toml flag)

kora.toml

Before deploying, you'll need to create and configure a kora.toml to specify:

  • Rate limiting and authentication
  • Payment destination address
  • RPC method availability
  • Transaction validation rules
  • Security policies (whitelist or blacklist of SPL tokens, programs, accounts, token extensions, etc.)
  • Fee pricing models
  • Enhanced fee payer policies (protect against unwanted signer behavior)
  • Metrics collection
  • Redis caching configuration (optional)

signers.toml

You will also need to create a signers.toml file to specify:

  • Signer(s) for your node
  • Signer selection strategy
  • Each signer's configuration and applicable keys

Deployment

Local Deployment

Start up and test a local Kora Server in minutes: Quick Start Guide

Docker

Use the sample Dockerfile to deploy on any container platform. The docker-compose.yml file includes Redis for caching support:

→ Sample Dockerfile → Docker Compose with Redis

Platform-Specific Guides

More integration guides coming soon

Need Help?

  • Solana Stack Exchange - Ask questions/share learnings (make sure to use the kora tag)
  • GitHub Issues - Report bugs or get help
  • Run kora rpc --help to see all available flags and configuration options