docs:(PRO-237) release punchlist (#193)

* docs: add getPaymentInstruction to TS SDK
* docs: update CONFIGURATION.md
* update reference to payment addresses and signers
* docs: update Quick Start Guide
* docs: update MONITORING.md
* docs: update SIGNERS.md
* docs: update CLAUDE.md

Author: amilz

CLAUDE.md

@@ -6,6 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ### Branches & Commits
 - **Main branch**: `main` (protected, requires PRs)
+- **Release branch**: `release/{id}` (requires PRs)
 - **Commit format**: Use conventional commits for automatic releases
   - `feat:` → minor version bump (1.0.3 → 1.1.0)
   - `fix:` → patch version bump (1.0.3 → 1.0.4)
@@ -187,47 +188,32 @@ make test-integration
 make run
 
 # Run with test configuration (for integration testing)
-cargo run -p kora-cli --bin kora -- --config tests/common/fixtures/kora-test.toml --rpc-url http://127.0.0.1:8899 rpc start --private-key ./tests/common/local-keys/fee-payer-local.json
+cargo run -p kora --bin kora -- --config tests/common/fixtures/kora-test.toml --rpc-url http://127.0.0.1:8899 rpc --signers-config tests/common/fixtures/signers.toml
 
 # Run with debug logging
-RUST_LOG=debug cargo run -p kora-cli --bin kora -- rpc start
+RUST_LOG=debug cargo run -p kora --bin kora -- rpc start
 
 # Run RPC server with all parameters
-cargo run -p kora-cli --bin kora -- --config kora.toml --rpc-url https://api.devnet.solana.com rpc start \
+cargo run -p kora --bin kora -- --config kora.toml --rpc-url https://api.devnet.solana.com rpc start \
   --port 8080 \
   --logging-format standard
 
 # Run with Turnkey signer
-cargo run -p kora-cli --bin kora -- rpc start \
-  --with-turnkey-signer \
-  --turnkey-api-public-key $TURNKEY_API_PUBLIC_KEY \
-  --turnkey-api-private-key $TURNKEY_API_PRIVATE_KEY \
-  --turnkey-organization-id $TURNKEY_ORGANIZATION_ID \
-  --turnkey-private-key-id $TURNKEY_PRIVATE_KEY_ID \
-  --turnkey-public-key $TURNKEY_PUBLIC_KEY \
-  --port 8080
+cargo run -p kora --bin kora -- rpc start --signers-config path/to/turnkey-signers.toml
 
 # Run with Privy signer
-cargo run -p kora-cli --bin kora -- rpc start \
-  --with-privy-signer \
-  --privy-app-id $PRIVY_APP_ID \
-  --privy-app-secret $PRIVY_APP_SECRET \
-  --privy-wallet-id $PRIVY_WALLET_ID
+cargo run -p kora --bin kora -- rpc start --signers-config path/to/privy-signers.toml
 
 # Run with Vault signer  
-cargo run -p kora-cli --bin kora -- rpc start \
-  --vault-signer \
-  --vault-addr $VAULT_ADDR \
-  --vault-token $VAULT_TOKEN \
-  --vault-key-name $VAULT_KEY_NAME \
-  --vault-pubkey $VAULT_PUBKEY
+cargo run -p kora --bin kora -- rpc start \
+  --signers-config path/to/vault-signers.toml
 
 # Configuration validation commands
-cargo run -p kora-cli --bin kora -- config validate
-cargo run -p kora-cli --bin kora -- config validate-with-rpc
+cargo run -p kora --bin kora -- config validate
+cargo run -p kora --bin kora -- config validate-with-rpc
 
 # Generate OpenAPI documentation
-cargo run -p kora-cli --bin kora --features docs -- openapi -o openapi.json
+cargo run -p kora --bin kora --features docs -- openapi -o openapi.json
 ```
 
 ### TypeScript SDK Development
@@ -244,12 +230,13 @@ pnpm run format
 
 ### Core Library (`kora-lib/src/`)
 
-- **signer/** - Abstraction layer supporting multiple signer types:
+- **signer/** - Abstraction layer supporting multiple signer types (configured in `signers.toml`)
   - `SolanaMemorySigner` - Local keypair signing
   - `VaultSigner` - HashiCorp Vault integration
   - `TurnkeySigner` - Turnkey API integration  
   - `PrivySigner` - Privy API integration
   - Unified `KoraSigner` enum with trait implementation
+  - optionally, `--no-signer` flag to run Kora without a signer
 
 - **transaction/** - Transaction processing pipeline:
   - Fee estimation and calculation
@@ -289,6 +276,8 @@ pnpm run format
   - `getConfig` - Return server configuration
   - `getSupportedTokens` - List accepted payment tokens
   - `signTransactionIfPaid` - Conditional signing based on payment verification
+  - `getPayerSigner` - Get the payer signer and payment destination
+  - (client-only) `getPaymentInstruction` - Get a payment instruction for a transaction
 
 - **openapi/** - Auto-generated API documentation using `utoipa`
 - **args.rs** - RPC-specific command line arguments
@@ -298,31 +287,25 @@ pnpm run format
 - Unified command-line interface with subcommands:
   - `kora config validate` - Validate configuration file
   - `kora config validate-with-rpc` - Validate configuration with RPC calls
-  - `kora rpc` - Start the RPC server with all signer options
+  - `kora rpc start` - Start the RPC server with all signer options (kora.toml & signers.toml in cwd)
+  - `kora --config path/to/kora.toml rpc start --signers-config path/to/signers.toml` - Start the RPC server with specific config and signers
   - `kora openapi` - Generate OpenAPI documentation
 - Global arguments (rpc-url, config) separated from RPC-specific arguments
 - All signer types supported for RPC server mode
 
 **Example CLI usage:**
 ```bash
 # Validate configuration
-cargo run -p kora-cli --bin kora -- --config kora.toml config validate
+cargo run -p kora --bin kora -- --config kora.toml config validate
 
 # Start RPC server with local private key
-cargo run -p kora-cli --bin kora -- --config kora.toml --rpc-url https://api.devnet.solana.com rpc start \
-  --private-key your_base58_private_key
+cargo run -p kora --bin kora -- --config path/to/kora.toml --rpc-url https://api.devnet.solana.com rpc start --signers-config path/to/signers.toml
 
 # Start RPC server with Turnkey signer
-cargo run -p kora-cli --bin kora -- rpc start \
-  --with-turnkey-signer \
-  --turnkey-api-public-key $TURNKEY_API_PUBLIC_KEY \
-  --turnkey-api-private-key $TURNKEY_API_PRIVATE_KEY \
-  --turnkey-organization-id $TURNKEY_ORGANIZATION_ID \
-  --turnkey-private-key-id $TURNKEY_PRIVATE_KEY_ID \
-  --turnkey-public-key $TURNKEY_PUBLIC_KEY
+cargo run -p kora --bin kora -- rpc start --signers-config path/to/turnkey-signers.toml
 
 # Generate OpenAPI documentation
-cargo run -p kora-cli --bin kora --features docs -- openapi -o openapi.json
+cargo run -p kora --bin kora --features docs -- openapi -o openapi.json
 ```
 
 ### Signer Integrations
@@ -378,31 +361,7 @@ allow_token2022_transfers = true # Allow fee payer to be source in Token2022 tra
 allow_assign = true             # Allow fee payer to use Assign instruction
 ```
 
-### Environment Variables
-
-**Turnkey Integration:**
-```bash
-TURNKEY_API_PUBLIC_KEY=your_api_public_key
-TURNKEY_API_PRIVATE_KEY=your_api_private_key  
-TURNKEY_ORGANIZATION_ID=your_org_id
-TURNKEY_PRIVATE_KEY_ID=your_private_key_id
-TURNKEY_PUBLIC_KEY=your_public_key
-```
-
-**Privy Integration:**
-```bash
-PRIVY_APP_ID=your_app_id
-PRIVY_APP_SECRET=your_app_secret
-PRIVY_WALLET_ID=your_wallet_id
-```
-
-**HashiCorp Vault Integration:**
-```bash
-VAULT_ADDR=https://vault.example.com
-VAULT_TOKEN=your_vault_token
-VAULT_KEY_NAME=your_key_name
-VAULT_PUBKEY=your_base58_public_key
-```
+### Environment Variables set in `signers.toml`
 
 **General:**
 ```bash
@@ -439,24 +398,24 @@ The fee payer policy is configured via the `[validation.fee_payer_policy]` secti
 
 ## Private Key Formats
 
-Kora supports multiple private key formats for enhanced usability and compatibility with different tooling:
+Kora supports multiple private key formats for enhanced usability and compatibility with different tooling, each specified in `signers.toml`
 
-### 1. Base58 Format (Default)
+### 1. Base58 Format
 Traditional Solana private key format - base58-encoded 64-byte private key:
 ```bash
---private-key FEE_PAYER_KEYPAIR_BASE58_STRING
+KORA_PRIVATE_KEY=your_base58_private_key
 ```
 
 ### 2. U8Array Format
 Comma-separated byte array format compatible with Solana CLI outputs:
 ```bash
---private-key "[123,45,67,89,12,34,56,78,90,12,34,56,78,90,12,34,56,78,90,12,34,56,78,90,12,34,56,78,90,12,34,56,78,90,12,34,56,78,90,12,34,56,78,90,12,34,56,78,90,12,34,56,78,90,12,34,56]"
+KORA_PRIVATE_KEY="[123,45,67,89,12,34,56,78,90,12,34,56,78,90,12,34,56,78,90,12,34,56,78,90,12,34,56,78,90,12,34,56,78,90,12,34,56,78,90,12,34,56,78,90,12,34,56,78,90,12,34,56,78,90,12,34,56]"
 ```
 
 ### 3. JSON File Path
 Path to a JSON file containing the private key:
 ```bash
---private-key "/path/to/keypair.json"
+KORA_PRIVATE_KEY="/path/to/keypair.json"
 ```
 
 ### Format Detection

docs/getting-started/QUICK_START.md

@@ -1,5 +1,7 @@
 # Kora Quick Start Guide
 
+*Last Updated: 2025-08-22*
+
 ## Kora Basics
 
 Kora is a JSON-RPC server that provides fee payment services for Solana transactions. It allows users to pay transaction fees with SPL tokens instead of SOL, enabling better UX for applications where users may not hold SOL.
@@ -25,7 +27,7 @@ This quick start will launch a local Kora RPC server and demonstrate client inte
 
 - [Solana CLI](https://solana.com/docs/intro/installation) v2.2.x or greater
 - [Rust/Cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html) (for Kora RPC installation)
-- [Node.js v24+](https://nodejs.org/en/download) and a package manager (e.g., [pnpm](https://pnpm.io/), npm)
+- [Node.js v22+](https://nodejs.org/en/download) and a package manager (e.g., [pnpm](https://pnpm.io/), npm)
 
 ## Install Kora RPC
 
@@ -54,6 +56,7 @@ The demo contains three main components:
 
 **Server Directory (`server/`)**
 - `kora.toml` - Kora RPC configuration defining validation rules, allowed tokens, and fee parameters
+- `signers.toml` - Signers configuration defining signers for the Kora server
 
 **Shared Configuration**
 - `.env` - Environment variables for keypairs and addresses (create `.env` in root - `demo/.env`). The environment variables will be created by the setup script.
@@ -63,6 +66,7 @@ The demo contains three main components:
 First, create .env for your environment :
 
 ```bash
+# Create .env file (will be populated by setup script)
 touch .env
 ```
 
@@ -99,6 +103,11 @@ The Kora server requires configuration to specify which tokens can be used for f
 
 For now, let's leave the default values--you can come back here and change these later (for more information on the configuration options, see the [Kora Configuration](../operators/CONFIGURATION.md) documentation). 
 
+### Setup Signers
+
+Open `server/signers.toml` and note the signers section. Here we can specify which signers will be used to sign transactions and (if using multiple signers) a strategy for selecting which signer to use. For now, let's use a single-signer using the default values--you can come back here and change these later (for more information on the signers configuration, see the [Signers Guide](../operators/SIGNERS.md) documentation). 
+
+
 ## Test Server
 
 Open three terminals and run the following commands:
@@ -203,10 +212,12 @@ This confirms your Kora server is running and properly configured!
 Once you have the basic setup working, explore additional Kora RPC methods:
 
 - `estimateTransactionFee` - Calculate fees for transactions
+- `getPayerSigner` - Get the payer signer and payment destination
 - `getSupportedTokens` - Returns an array of supported payment tokens
 - `signTransaction` - Sign transactions with the Kora feepayer
 - `transferTransaction` - Create transfer SOL or SPL token transfer transactions (signed by the Kora feepayer)
 - `signAndSendTransaction` - Signs a transaction with the Kora feepayer and sends it to the configured Solana RPC
 - `signTransactionIfPaid` - Conditionally sign transactions when fees are covered
+- `getPaymentInstruction` - Get a payment instruction for a transaction
 
 **Got questions?** Ask questions the [Solana Stack Exchange](https://solana.stackexchange.com/) with a `Kora` tag.

docs/getting-started/demo/server/signers.toml

@@ -0,0 +1,8 @@
+[signer_pool]
+strategy = "round_robin"
+
+[[signers]]
+name = "main_signer"
+type = "memory"
+private_key_env = "KORA_PRIVATE_KEY"
+weight = 1

docs/operators/CONFIGURATION.md

@@ -1,4 +1,5 @@
 # Kora Configuration Reference
+*Last Updated: 2025-08-22*
 
 Your Kora node will be signing transactions for your users, so it is important to configure it to only sign transactions that meet your business requirements. Kora gives you a lot of flexibility in how you configure your node, but it is important to understand the implications of your configuration. `kora.toml` is the control center for your Kora configuration. This document provides a comprehensive reference for configuring your Kora paymaster node through the `kora.toml` configuration file.
 
@@ -74,11 +75,11 @@ rate_limit = 100
 payment_address = "YourPaymentAddressPubkey11111111111111111111"  # Optional
 ```
 
-
 | Option | Description | Required | Type |
 |--------|-------------|---------|---------|
 | `rate_limit` | Global rate limit (requests per second) across all clients | ✅ | number |
-| `payment_address` | Optional payment address to receive payment tokens (defaults to signer address) | ❌ | b58-encoded string |
+| `payment_address` | Optional payment address to receive payment tokens (defaults to signer address(es) if not specified) | ❌ | b58-encoded string |
+
 
 ## Kora Authentication
 
@@ -191,7 +192,7 @@ disallowed_accounts = [
 | `allowed_spl_paid_tokens` | SPL tokens accepted as payment for transaction fees | ✅ | Array of b58-encoded string |
 | `disallowed_accounts` | Accounts that are explicitly blocked from transactions | ✅ | Array of b58-encoded string |
 
-> *Note: Empty arrays are allowed, but you will need to specify at least one whitelisted `allowed_programs`, `allowed_tokens`, `allowed_spl_paid_tokens` for the Kora node to be able to process transactions. You need to specify the System Program or Token Program for the Kora node to be able to process transactions.*
+> *Note: Empty arrays are allowed, but you will need to specify at least one whitelisted `allowed_programs`, `allowed_tokens`, `allowed_spl_paid_tokens` for the Kora node to be able to process transactions. You need to specify the System Program or Token Program for the Kora node to be able to process transfers.*
 
 ## Token-2022 Extension Blocking
 
@@ -356,13 +357,13 @@ Here's a production-ready configuration with security best practices:
 
 ```toml
 # Kora Paymaster Configuration
-# Last Updated: 2024-01-15
+# Last Updated: 2025-08-22
 
 [kora]
 # Rate limiting: 100 requests per second globally
 rate_limit = 100
 
-# Optional payment address (defaults to signer address if not specified)
+# Optional payment address (defaults to signer address(es) if not specified)
 # payment_address = "YourPaymentAddressPubkey11111111111111111111"
 
 [kora.auth]
@@ -440,8 +441,8 @@ allow_approve = false
 # Block potentially risky mint extensions
 blocked_mint_extensions = [
     "transfer_hook",       # Custom transfer logic
-    "pausable",           # Can freeze transfers
-    "permanent_delegate", # Permanent control
+    "pausable",            # Can freeze transfers
+    "permanent_delegate",  # Permanent control
 ]
 # Block complex account extensions
 blocked_account_extensions = [
@@ -472,17 +473,41 @@ expiry_seconds = 30
 Kora validates your configuration on startup. If you would like to validate your configuration without starting the server, you can use the config validation command:
 
 ```bash
-kora --config kora.toml config validate
+kora --config kora.toml config validate # or validate-with-rpc
 ```
 
+You can also run the `validate-with-rpc` command to validate your configuration with the RPC server (this validation check is a little bit slower but does more thorough account checks)
+
 ## Starting the Server
 
 Once you have configured your `kora.toml` file, you can start the Kora server:
 
 ```bash
-kora --config path/to/kora.toml rpc # --other-rpc-flags-here
+kora --config path/to/kora.toml rpc start --no-load-signer # --other-rpc-flags-here
+```
+
+The `--no-load-signer` flag will initialize the server without loading any signers. This is useful for testing your configuration. In order to load signers, you will need to configure the `signers.toml` file. A minimum configuration with a single signer would look like this:
+
+```toml
+[signer_pool]
+# Selection strategy: round_robin, random, weighted
+strategy = "round_robin"
+
+# Primary memory signer
+[[signers]]
+name = "my-signer"
+type = "memory"
+private_key_env = "MY_SIGNER_PRIVATE_KEY"
+```
+
+This will load a single signer from the `MY_SIGNER_PRIVATE_KEY` environment variable. Then you can start your server with:
+
+```bash
+kora --config path/to/kora.toml rpc start --signers-config path/to/signers.toml
 ```
 
+For more information and advanced signer configuration, see the [Signers Guide](./SIGNERS.md).
+
 ## Best Practices
 
 1. **Start Restrictive**: Begin with tight limits and gradually expand
@@ -494,6 +519,7 @@ kora --config path/to/kora.toml rpc # --other-rpc-flags-here
 ## Need Help?
 
 - Check [Authentication Guide](./AUTHENTICATION.md) for auth setup
+- Check [Signers Guide](./SIGNERS.md) for signer configuration
 - Check [Operator Guide](./README.md) for more information on how to run a Kora node
 - Visit [Solana Stack Exchange](https://solana.stackexchange.com/) with the `kora` tag
 - Report issues on [GitHub](https://github.com/solana-foundation/kora/issues)