구성 | Solana

Kora v2.2.0-beta를 사용 중이신가요? 새로운 옵션은 베타 구성을 참조하세요: Jito 번들, Lighthouse 보호, reCAPTCHA 및 사용량 제한.

Kora 노드는 사용자를 위해 트랜잭션에 서명하므로, 비즈니스 요구사항을 충족하는 트랜잭션에만 서명하도록 구성하는 것이 중요합니다. Kora는 노드 구성에 많은 유연성을 제공하지만, 구성의 의미를 이해하는 것이 중요합니다. kora.toml는 Kora 구성의 제어 센터입니다. 이 문서는 kora.toml 구성 파일을 통해 Kora 페이마스터 노드를 구성하기 위한 포괄적인 참조를 제공합니다.

개요

kora.toml 파일은 다음을 포함한 Kora 노드 동작의 모든 측면을 제어합니다:

속도 제한 및 인증
RPC 메서드 가용성
트랜잭션 유효성 검사 규칙
수수료 가격 모델
보안 정책
RPC 메서드 가용성
수수료 가격 모델
결제 주소 구성
성능 모니터링

구성 파일은 배포 디렉토리에 배치하거나 서버 시작 시 --config 플래그를 통해 지정해야 합니다.

구성 섹션

kora.toml 파일은 각각 고유한 옵션 세트를 가진 섹션으로 구성됩니다. 이 가이드는 각 섹션을 안내하고 사용 가능한 옵션을 설명합니다:

Kora 핵심 정책 - 핵심 서버 설정
Kora 인증 - 인증 설정
Kora 캐싱 - RPC 호출을 위한 Redis 캐싱
Kora 사용량 제한 - 지갑당 트랜잭션 제한
Kora 활성화된 메서드 - 활성화할 Kora RPC 메서드
유효성 검사 정책 - 트랜잭션 유효성 검사 및 보안
Token-2022 확장 차단 - 위험한 Token-2022 확장 차단
수수료 지불자 정책 - 수수료 지불자 지갑에 대한 제한
가격 구성 - 트랜잭션 수수료 가격 모델
성능 모니터링 - 메트릭 수집 및 모니터링
완전한 예시 - 프로덕션 준비가 완료된 전체 구성

샘플 kora.toml 파일 섹션:

[kora]
# Core server settings

[kora.auth]
# Authentication settings

[kora.cache]
# Redis caching configuration

[kora.usage_limit]
# Per-wallet transaction limiting

[kora.enabled_methods]
# Kora RPC methods to enable

[validation]
# Transaction validation rules

[validation.token2022]
# Token-2022 extension blocking

[validation.fee_payer_policy]
# Restrictions on fee payer wallet

[validation.price]
# Transaction fee pricing models

[metrics]
# Performance monitoring

Kora 핵심 정책

[kora] 섹션은 핵심 서버 동작을 구성합니다:

[kora]
rate_limit = 100
payment_address = "YourPaymentAddressPubkey11111111111111111111"  # Optional

옵션	설명	필수 여부	타입
`rate_limit`	모든 클라이언트에 적용되는 전역 속도 제한(초당 요청 수)	✅	number
`payment_address`	결제 토큰을 받을 선택적 결제 주소(지정하지 않으면 서명자 주소로 기본 설정됨)	❌	b58 인코딩 문자열

Kora 인증

[kora.auth] 섹션은 Kora 서버의 인증을 구성합니다:

[kora.auth]
api_key = "kora_live_sk_1234567890abcdef"
hmac_secret = "kora_hmac_your-strong-hmac-secret-key-here"
max_timestamp_age = 300

옵션	설명	필수 여부	타입
`api_key`	간단한 인증을 위한 API 키	❌	string
`hmac_secret`	서명 기반 인증을 위한 HMAC 시크릿(최소 32자)	❌	string
`max_timestamp_age`	HMAC 타임스탬프의 최대 유효 기간(초 단위)	❌ (기본값: 300)	number

참고: api_key 및 hmac_secret는 모든 클라이언트에 대한 전역 인증 정책을 설정합니다. 자세한 인증 설정은 인증 가이드를 참조하세요.

Kora 캐싱(선택 사항)

[kora.cache] 섹션은 Solana RPC 호출을 위한 Redis 기반 캐싱을 구성합니다. 중복된 계정 데이터 가져오기를 줄여 성능을 크게 향상시킬 수 있습니다:

[kora.cache]
enabled = true                      # Enable/disable caching
url = "redis://localhost:6379"      # Redis connection URL
default_ttl = 300                   # Default TTL in seconds (5 minutes)
account_ttl = 60                    # Account data TTL in seconds (1 minute)

옵션	설명	필수 여부	타입
`enabled`	RPC 호출에 대한 Redis 캐싱 활성화	❌ (기본값: false)	boolean
`url`	Redis 연결 URL(활성화 시 필수)	✅	string
`default_ttl`	캐시된 항목의 기본 TTL(초 단위)	❌ (기본값: 300)	number
`account_ttl`	계정 데이터 캐시의 TTL(초 단위)	❌ (기본값: 60)	number

참고: 캐싱이 활성화된 경우, 지정된 URL에서 Redis 인스턴스를 사용할 수 있어야 합니다. Redis를 사용할 수 없는 경우 캐시는 직접 RPC 호출로 자동 전환됩니다.

Kora 사용량 제한 (선택사항)

[kora.usage_limit] 섹션은 지갑당 트랜잭션 제한을 구성하여 남용을 방지하고 사용자들 간에 공정한 사용을 보장합니다. 이는 특정 한도까지 사용자의 트랜잭션 수수료를 보조하는 보상 프로그램을 만드는 데에도 사용할 수 있습니다.

중요: 현재 Kora에서 지원하는 유일한 사용량 제한 형태는 영구 제한입니다. 지갑이 트랜잭션 한도에 도달하면 재설정할 수 없으며, 사용자는 동일한 지갑을 사용하여 더 이상 트랜잭션을 제출할 수 없습니다. 이 제한은 Redis에서 수동으로 삭제하거나 Redis 데이터가 재설정될 때까지 유지됩니다.

참고: 이 기능은 여러 Kora 인스턴스에서 활성화될 때 Redis가 필요합니다:

[kora.usage_limit]
enabled = true                      # Enable/disable usage limiting
cache_url = "redis://localhost:6379" # Redis URL for shared state (required when enabled)
max_transactions = 100              # Max transactions per wallet (0 = unlimited)
fallback_if_unavailable = true      # Continue if Redis is unavailable

옵션	설명	필수	타입
`enabled`	지갑당 트랜잭션 제한 활성화	❌ (기본값: false)	boolean
`cache_url`	공유 사용량 추적을 위한 Redis 연결 URL	❌	string
`max_transactions`	지갑당 최대 트랜잭션 수 (0 = 무제한)	❌ (기본값: 100)	number
`fallback_if_unavailable`	Redis를 사용할 수 없을 때 트랜잭션 허용	❌ (기본값: true)	boolean

참고: 사용량 제한은 자동 TTL 기반 만료와 함께 지갑 주소별로 추적됩니다. fallback_if_unavailable가 true일 때, 시스템은 Redis가 일시적으로 사용 불가능한 경우에도 트랜잭션을 진행하도록 허용하여 서비스 중단을 방지합니다. max_transactions를 0으로 설정하면 무제한 트랜잭션이 허용됩니다.

Kora 활성화 메서드 (선택사항)

[kora.enabled_methods] 섹션은 어떤 RPC 메서드가 활성화되는지 제어합니다. 이 섹션은 선택사항이며 기본적으로 모든 메서드가 활성화됩니다. 각 메서드는 true 또는 false로 값을 설정하여 활성화하거나 비활성화할 수 있습니다:

[kora.enabled_methods]
liveness = true
estimate_transaction_fee = true
get_supported_tokens = true
sign_transaction = false
sign_and_send_transaction = false
transfer_transaction = false
get_blockhash = true
get_config = true
get_payer_signer = true

옵션	메서드 설명	필수	유형
`liveness`	상태 확인 엔드포인트	✅	boolean
`estimate_transaction_fee`	트랜잭션 수수료 추정	✅	boolean
`get_supported_tokens`	허용된 토큰 목록 조회	✅	boolean
`sign_transaction`	네트워크로 전송하지 않고 트랜잭션 서명	✅	boolean
`sign_and_send_transaction`	트랜잭션 서명 후 네트워크로 전송	✅	boolean
`transfer_transaction`	토큰 전송 처리	✅	boolean
`get_blockhash`	최근 블록해시 가져오기	✅	boolean
`get_config`	Kora 서버 설정 반환	✅	boolean

참고: 이 섹션이 kora.toml 파일에 포함된 경우, 모든 메서드는 명시적으로 true 또는 false로 설정되어야 합니다.

검증 정책

[validation] 섹션은 Solana 관련 보안 규칙 및 트랜잭션 제한을 정의합니다:

[validation]
max_allowed_lamports = 1000000  # 0.001 SOL
max_signatures = 10
price_source = "Jupiter"
allow_durable_transactions = false  # Block durable nonce transactions
allowed_programs = [
    "11111111111111111111111111111111",              # System Program (required for SOL transfers)
    "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",   # SPL Token Program
    "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb",   # Token-2022 Program
    "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL",  # Associated Token Program
    "AddressLookupTab1e1111111111111111111111111",   # Address Lookup Table Program
    "ComputeBudget11111111111111111111111111111111", # Compute Budget Program
]
allowed_tokens = [
    "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",  # USDC (mainnet)
    # additional tokens here
]
allowed_spl_paid_tokens = [
    "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",  # USDC (mainnet)
    # additional tokens here
]
disallowed_accounts = [
    # "BadActorPubkey11111111111111111111111111111",
]

옵션	설명	필수	유형
`max_allowed_lamports`	트랜잭션당 최대 lamport 수를 설정하면 단일 트랜잭션에 대한 Kora 노드의 노출을 제한합니다.	✅	number
`max_signatures`	Solana 기본 수수료는 트랜잭션의 서명 수에 따라 결정되므로, 트랜잭션당 최대 서명 수를 설정하는 것은 사용자가 단일 트랜잭션에 너무 많은 SOL을 소비하는 것을 방지하는 좋은 방법입니다.	✅	number
`price_source`	토큰 가격 데이터를 위한 오라클. 참고: `"Jupiter"`로 설정된 경우, `JUPITER_API_KEY` 환경 변수가 필수입니다. 이것 없이는 서버가 시작되지 않습니다.	✅	"Jupiter" 또는 "Mock"
`allow_durable_transactions`	지속 가능한 논스 트랜잭션 허용. 아래 보안 고려사항을 참조하세요.	❌ (기본값: false)	boolean
`allowed_programs`	트랜잭션이 상호작용할 수 있는 Solana 프로그램	✅	b58 인코딩 문자열 배열
`allowed_tokens`	트랜잭션에서 사용할 수 있는 토큰 민트	✅	b58 인코딩 문자열 배열
`allowed_spl_paid_tokens`	트랜잭션 수수료 지불로 허용되는 SPL 토큰	✅	b58 인코딩 문자열 배열
`disallowed_accounts`	트랜잭션에서 명시적으로 차단된 계정	✅	b58 인코딩 문자열 배열

참고: 빈 배열은 허용되지만, Kora 노드가 트랜잭션을 처리할 수 있도록 최소한 하나의 허용된 allowed_programs, allowed_tokens, allowed_spl_paid_tokens를 지정해야 합니다. Kora 노드가 전송을 처리할 수 있도록 System Program 또는 Token Program을 지정해야 합니다. 일반적인 명령어 유형(예: Compute Budget, Address Lookup Table)을 활성화하려면 Compute Budget Program 또는 Address Lookup Table Program 등을 지정해야 합니다.

영구 트랜잭션 보안

보안 경고: 영구 논스 트랜잭션은 서명된 트랜잭션을 무기한 보유하고 나중에 제출할 수 있게 합니다. 이는 누군가가 서명된 트랜잭션을 획득하여 시장 상황이 자신에게 유리할 때까지 기다렸다가 제출할 수 있는 경제적 공격 벡터로 사용될 수 있습니다(예: SOL의 가치가 하락했거나 결제 토큰의 가치가 상승했을 때).

기본적으로 allow_durable_transactions는 모든 영구 논스 트랜잭션을 차단하기 위해 false로 설정되어 있습니다. 애플리케이션에서 영구 트랜잭션이 특별히 필요하고 위험을 이해하는 경우에만 이 기능을 활성화하세요.

영구 트랜잭션을 활성화해야 하는 경우 다음을 고려하세요:

인증을 사용하여 API 접근 제한
추가적인 오프체인 검증 구현
비정상적인 트랜잭션 패턴 모니터링
서명자 계정 잔액 모니터링 및 제한
서명자 키 정기적 교체

영구 논스 트랜잭션에 대한 자세한 내용은 Solana 문서에서 확인하세요.

Token-2022 확장 차단

[validation.token2022] 섹션을 사용하면 보안 강화를 위해 특정 Token-2022 확장을 차단할 수 있습니다. 기본적으로 모든 확장이 활성화되어 있습니다. blocked_mint_extensions 또는 blocked_account_extensions 배열에 추가하여 특정 확장을 차단할 수 있습니다:

[validation.token2022]
blocked_mint_extensions = [
    "transfer_hook",           # Block tokens with transfer hooks
    "pausable",                # Block pausable tokens
    "permanent_delegate",      # Block tokens with permanent delegates
]
blocked_account_extensions = [
    "cpi_guard",              # Block accounts with CPI guard
    "memo_transfer",          # Block accounts requiring memos
]

사용 가능한 민트 확장 기능

확장 기능 이름	설명
`confidential_transfer_mint`	민트에 대한 기밀 전송 구성
`confidential_mint_burn`	기밀 발행 및 소각 구성
`transfer_fee_config`	전송 수수료 구성
`mint_close_authority`	민트를 닫을 수 있는 권한
`interest_bearing_config`	이자 발생 토큰 구성
`non_transferable`	토큰을 양도 불가능하게 만듦
`permanent_delegate`	민트에 대한 영구 위임자
`transfer_hook`	커스텀 전송 후크 프로그램
`pausable`	일시 정지 가능한 토큰 구성

사용 가능한 계정 확장 기능

확장 기능 이름	설명
`confidential_transfer_account`	계정에 대한 기밀 전송 상태
`non_transferable_account`	양도 불가능한 토큰 계정
`transfer_hook_account`	계정에 대한 전송 후크 상태
`pausable_account`	일시 정지 가능한 토큰 계정 상태
`memo_transfer`	전송 시 메모 필수
`cpi_guard`	특정 CPI 호출 방지
`immutable_owner`	계정 소유자 변경 불가
`default_account_state`	새 계정의 기본 상태

transfer_hook

보안 고려사항

PermanentDelegate 확장 기능 - 이 확장 기능이 있는 토큰은 위임자가 소유자의 승인 없이 언제든지 토큰을 전송/소각할 수 있습니다. 이는 지불 후 지불 자금이 압류될 수 있어 Kora 노드 운영자에게 심각한 위험을 초래합니다.

사용 사례에 명시적으로 필요하지 않는 한 [validation.token2022]의 blocked_mint_extensions에 "permanent_delegate"를 추가하는 것을 고려하세요.
permanent_delegate 확장 기능이 있는 지불 토큰 사용을 피하세요.

수수료 지불자 정책

[validation.fee_payer_policy] 섹션은 Kora 노드의 수수료 지불자 지갑이 수행할 수 있는 작업에 대한 세밀한 제어를 제공합니다. 정책은 프로그램 유형(System Program, Token Program, Associated Token Program)별로 구성되며 모든 다양한 인스트럭션 유형을 다룹니다. 이를 통해 사용자의 트랜잭션이 Kora 노드를 서명자로 활용할 때 예상치 못한 동작을 방지합니다.

예를 들어, spl_token.allow_transfer가 false로 설정된 경우, Kora 노드는 Kora 노드의 수수료 지불자가 전송 권한자인 SPL 토큰 전송이 포함된 트랜잭션에 서명하지 않습니다.

[validation.fee_payer_policy.system]
allow_transfer = false           # System Transfer/TransferWithSeed
allow_assign = false             # System Assign/AssignWithSeed
allow_create_account = false     # System CreateAccount/CreateAccountWithSeed
allow_allocate = false           # System Allocate/AllocateWithSeed

[validation.fee_payer_policy.system.nonce]
allow_initialize = false         # InitializeNonceAccount
allow_advance = false            # AdvanceNonceAccount
allow_authorize = false          # AuthorizeNonceAccount
allow_withdraw = false           # WithdrawNonceAccount

[validation.fee_payer_policy.spl_token]
allow_transfer = false           # Transfer/TransferChecked
allow_burn = false               # Burn/BurnChecked
allow_close_account = false      # CloseAccount
allow_approve = false            # Approve/ApproveChecked
allow_revoke = false             # Revoke
allow_set_authority = false      # SetAuthority
allow_mint_to = false            # MintTo/MintToChecked
allow_initialize_mint = false    # InitializeMint/InitializeMint2
allow_initialize_account = false # InitializeAccount/InitializeAccount3
allow_initialize_multisig = false # InitializeMultisig/InitializeMultisig2
allow_freeze_account = false     # FreezeAccount
allow_thaw_account = false       # ThawAccount

[validation.fee_payer_policy.token_2022]
allow_transfer = false           # Transfer/TransferChecked
allow_burn = false               # Burn/BurnChecked
allow_close_account = false      # CloseAccount
allow_approve = false            # Approve/ApproveChecked
allow_revoke = false             # Revoke
allow_set_authority = false      # SetAuthority
allow_mint_to = false            # MintTo/MintToChecked
allow_initialize_mint = false    # InitializeMint/InitializeMint2
allow_initialize_account = false # InitializeAccount/InitializeAccount3
allow_initialize_multisig = false # InitializeMultisig/InitializeMultisig2
allow_freeze_account = false     # FreezeAccount
allow_thaw_account = false       # ThawAccount

System Program 인스트럭션

옵션	설명	기본값	타입
`allow_transfer`	Transfer/TransferWithSeed 인스트럭션에서 수수료 지불자를 발신자로 허용	`false`	boolean
`allow_assign`	Assign/AssignWithSeed 인스트럭션에서 수수료 지불자를 권한자로 허용	`false`	boolean
`allow_create_account`	CreateAccount/CreateAccountWithSeed 인스트럭션에서 수수료 지불자를 자금 제공자로 허용	`false`	boolean
`allow_allocate`	Allocate/AllocateWithSeed 인스트럭션에서 수수료 지불자를 계정 소유자로 허용	`false`	boolean
`nonce.allow_initialize`	InitializeNonceAccount에서 수수료 지불자를 논스 권한자로 설정 허용	`false`	boolean
`nonce.allow_advance`	AdvanceNonceAccount에서 수수료 지불자를 권한자로 허용	`false`	boolean
`nonce.allow_authorize`	AuthorizeNonceAccount에서 수수료 지불자를 현재 권한자로 허용	`false`	boolean
`nonce.allow_withdraw`	WithdrawNonceAccount에서 수수료 지불자를 권한자로 허용	`false`	boolean

Token Program 인스트럭션

옵션	설명	기본값	타입
`allow_transfer`	Transfer/TransferChecked 인스트럭션에서 수수료 지불자를 소유자로 허용	`false`	boolean
`allow_burn`	Burn/BurnChecked 인스트럭션에서 수수료 지불자를 소유자로 허용	`false`	boolean
`allow_close_account`	CloseAccount 인스트럭션에서 수수료 지불자를 소유자로 허용	`false`	boolean
`allow_approve`	Approve/ApproveChecked 인스트럭션에서 수수료 지불자를 소유자로 허용	`false`	boolean
`allow_revoke`	Revoke 인스트럭션에서 수수료 지불자를 소유자로 허용	`false`	boolean
`allow_set_authority`	SetAuthority 인스트럭션에서 수수료 지불자를 현재 권한자로 허용	`false`	boolean
`allow_mint_to`	MintTo/MintToChecked 인스트럭션에서 수수료 지불자를 발행 권한자로 허용	`false`	boolean
`allow_initialize_mint`	InitializeMint/InitializeMint2 인스트럭션에서 수수료 지불자를 발행 권한자로 허용	`false`	boolean
`allow_initialize_account`	InitializeAccount/InitializeAccount3 인스트럭션에서 수수료 지불자를 소유자로 허용	`false`	boolean
`allow_initialize_multisig`	InitializeMultisig/InitializeMultisig2 인스트럭션에서 수수료 지불자를 서명자로 허용	`false`	boolean
`allow_freeze_account`	FreezeAccount 인스트럭션에서 수수료 지불자를 동결 권한자로 허용	`false`	boolean
`allow_thaw_account`	ThawAccount 인스트럭션에서 수수료 지불자를 동결 해제 권한자로 허용	`false`	boolean

Token-2022는 동일한 구성 옵션([validation.fee_payer_policy.token_2022] 섹션 아래)으로 SPL Token과 동일한 명령어 세트를 지원합니다.

보안 고려사항

보안 경고: 보안상의 이유로 이러한 모든 설정을 false(기본값)으로 설정하고 필요한 경우에만 활성화하는 것이 권장됩니다. 이는 사용자가 수수료 지불 계정을 고갈시키거나 수수료 지불 계정에서 토큰을 소각하는 등의 원치 않는 동작을 방지합니다. 다음을 방지합니다:

계정 고갈: 사용자가 수수료 지불 계정에서 SOL 또는 토큰을 전송
권한 탈취: 사용자가 수수료 지불자가 소유한 계정의 권한을 변경
무단 발행: 수수료 지불자가 발행 권한을 가진 경우 사용자가 토큰을 발행
계정 조작: 사용자가 수수료 지불자가 관리하는 계정을 동결, 폐쇄 또는 수정

모범 사례: 모든 권한을 비활성화한 상태로 시작하고 특정 사용 사례에 필요한 최소한의 권한만 활성화하세요.

가격 구성 (선택사항)

[validation.price] 섹션은 거래 수수료 계산 방식을 정의합니다. 세 가지 가격 책정 모델이 제공됩니다:

마진 가격 책정(기본값) - 실제 네트워크 수수료에 백분율 마진을 추가(기본 마진은 0.0)
고정 가격 책정 - 네트워크 수수료와 관계없이 특정 토큰으로 고정 금액 청구
무료 가격 책정 - 모든 거래 수수료 후원(사용자에게 수수료 없음)

옵션	설명	필수	타입
`type`	사용할 가격 책정 모델	✅	"margin", "fixed" 또는 "free"
`margin`	네트워크 수수료에 추가할 마진 비율	(`type`이 "margin"일 때)	number
`amount`	토큰 기본 단위로 청구할 고정 금액	(`type`이 "fixed"일 때)	number
`token`	청구할 토큰 민트	(`type`이 "fixed"일 때)	b58 인코딩 문자열

마진 가격 책정

실제 네트워크 수수료에 백분율 마진을 추가합니다:

[validation.price]
type = "margin"
margin = 0.1  # 10% margin (0.1 = 10%, 1.0 = 100%)

고정 가격 책정

보안 경고: 고정 가격 책정은 청구 금액에 수수료 지불자의 출금을 포함하지 않습니다. 이는 적절히 구성되지 않으면 사용자가 수수료 지불자 계정을 고갈시킬 수 있습니다.

네트워크 수수료와 관계없이 특정 토큰으로 고정 금액을 청구합니다:

[validation.price]
type = "fixed"
amount = 1000000  # Amount in token's base units
token = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"  # USDC mint

무료 트랜잭션

모든 트랜잭션 수수료를 후원합니다(사용자에게 청구 없음):

[validation.price]
type = "free"

고정/무료 가격 책정 사용 시 보안 조치

모든 전송 및 금전적 작업 비활성화 - 수수료 지불자가 전송의 소스로 사용되는 것을 방지합니다:

[validation.fee_payer_policy.system]
allow_transfer = false              # Block SOL transfers
allow_create_account = false        # Block account creation with lamports
allow_allocate = false              # Block space allocation

[validation.fee_payer_policy.system.nonce]
allow_withdraw = false              # Block nonce account withdrawals

[validation.fee_payer_policy.spl_token] # and for [validation.fee_payer_policy.token_2022]
allow_transfer = false              # Block SPL transfers
allow_burn = false                  # Block SPL token burning
allow_close_account = false         # Block SPL token account closures (returns rent)
allow_mint_to = false               # Block unauthorized SPL token minting
allow_initialize_account = false    # Block account initialization

인증 활성화 - 남용을 방지하기 위해 인증을 사용합니다:

[kora.auth]
api_key = "your-secure-api-key"
# or
hmac_secret = "your-minimum-32-character-hmac-secret"

보수적인 제한 설정 - 노출을 최소화합니다:

[validation]
max_allowed_lamports = 1000000  # 0.001 SOL maximum

경고: 고정/무료 가격 책정 사용 시 특히 위험한 작업:

allow_mint_to: 수수료 지불자가 발행 권한을 가진 경우 무제한 토큰 생성을 허용할 수 있음

allow_set_authority: 중요한 계정의 제어권을 공격자에게 이전할 수 있음

allow_transfer: 수수료 지불자의 토큰 잔액을 직접 고갈시킬 수 있음

allow_close_account: 공격자가 제어하는 계정으로 rent를 반환함

성능 모니터링 (선택 사항)

[metrics] 섹션은 메트릭 수집 및 모니터링을 구성합니다. 이 섹션은 선택 사항이며 기본적으로 메트릭은 비활성화되어 있습니다.

[metrics]
enabled = true
endpoint = "/metrics"
port = 8080
scrape_interval = 60

[metrics.fee_payer_balance]
enabled = true
expiry_seconds = 30

옵션	설명	필수 여부	타입
`enabled`	메트릭 수집 활성화	✅	boolean
`endpoint`	사용자 지정 메트릭 엔드포인트 경로	✅	string
`port`	메트릭 엔드포인트 포트	✅	number
`scrape_interval`	Prometheus 스크레이프 빈도(초)	✅	number

수수료 지불자 잔액 추적

[metrics.fee_payer_balance] 섹션은 수수료 지불자의 SOL 잔액에 대한 자동 모니터링을 구성합니다:

옵션	설명	필수 여부	타입
`enabled`	수수료 지불자 잔액 추적 활성화	❌ (기본값: false)	boolean
`expiry_seconds`	백그라운드 추적 간격(초)	❌ (기본값: 30)	number

활성화하면 Kora는 수수료 지불자의 SOL 잔액을 자동으로 추적하고 fee_payer_balance_lamports Prometheus 게이지를 통해 노출합니다. 이는 용량 계획 및 잔액 부족 알림에 유용합니다.

http://localhost:{port}/{metrics-endpoint}

→ Kora 모니터링 참조 가이드

전체 예제

보안 모범 사례가 적용된 프로덕션 환경용 구성입니다:

# Kora Paymaster Configuration
# Last Updated: 2025-08-22

[kora]
# Rate limiting: 100 requests per second globally
rate_limit = 100

# Optional payment address (defaults to signer address(es) if not specified)
# payment_address = "YourPaymentAddressPubkey11111111111111111111"

[kora.auth]
# Authentication (choose based on security needs)
# api_key = "kora_live_sk_generate_secure_key_here"
hmac_secret = "kora_hmac_minimum_32_character_secret_here"
max_timestamp_age = 300

# Caching configuration (optional but recommended for production)
[kora.cache]
enabled = true
url = "redis://localhost:6379"
default_ttl = 300  # 5 minutes
account_ttl = 60   # 1 minute

# Usage limiting (optional, prevents abuse)
[kora.usage_limit]
enabled = true
cache_url = "redis://localhost:6379"  # Can share same Redis instance as cache
max_transactions = 100                # Per-wallet limit
fallback_if_unavailable = true        # Don't block if Redis is down

# Disable unnecessary RPC methods for security
[kora.enabled_methods]
liveness = true
estimate_transaction_fee = true
get_supported_tokens = true
sign_transaction = false
sign_and_send_transaction = false
transfer_transaction = false
get_blockhash = true
get_config = true
get_payer_signer = true

[validation]
# Use production oracle
price_source = "Jupiter"

# Conservative transaction limits
max_allowed_lamports = 1000000  # 0.001 SOL max
max_signatures = 10

# Block durable nonce transactions (security default)
allow_durable_transactions = false

# Minimal program allowlist (expand as needed)
allowed_programs = [
    "11111111111111111111111111111111",              # System Program
    "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",   # SPL Token
    "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL",  # Associated Token
    "AddressLookupTab1e1111111111111111111111111",   # Address Lookup Table
    "ComputeBudget11111111111111111111111111111111", # Compute Budget
    "MyProgram111111111111111111111111111111111",
    # Add your specific program IDs here
]

# Production token allowlist
allowed_tokens = [
    "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",  # USDC
    "So11111111111111111111111111111111111111112",   # Wrapped SOL
    "MyToken1111111111111111111111111111111111111111",
    # Add tokens your application uses
]

# Payment tokens (only liquid, trusted tokens)
allowed_spl_paid_tokens = [
    "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",  # USDC only
]

# Known bad actors or compromised addresses
disallowed_accounts = [
    "BadActor1111111111111111111111111111111111111111",
]

# Restrictive fee payer policy (recommended for production)
[validation.fee_payer_policy.system]
allow_transfer = false           # Block SOL transfers from fee payer
allow_assign = false             # Block account ownership changes
allow_create_account = false     # Block creating accounts with fee payer funds
allow_allocate = false           # Block allocating space for fee payer accounts

[validation.fee_payer_policy.system.nonce]
allow_initialize = false         # Block nonce account initialization
allow_advance = false            # Block nonce advancement
allow_authorize = false          # Block nonce authority changes
allow_withdraw = false           # Block nonce withdrawals

[validation.fee_payer_policy.spl_token]
allow_transfer = false           # Critical: Block SPL transfers
allow_burn = false               # Block token burning
allow_close_account = false      # Block account closures
allow_approve = false            # Block token approvals
allow_revoke = false             # Block delegate revocations
allow_set_authority = false      # Block authority changes
allow_mint_to = false            # Block minting operations
allow_initialize_mint = false    # Block mint initialization
allow_initialize_account = false # Block account initialization
allow_initialize_multisig = false # Block multisig initialization
allow_freeze_account = false     # Block account freezing
allow_thaw_account = false       # Block account thawing

[validation.fee_payer_policy.token_2022]
allow_transfer = false           # Critical: Block Token2022 transfers
allow_burn = false               # Block token burning
allow_close_account = false      # Block account closures
allow_approve = false            # Block token approvals
allow_revoke = false             # Block delegate revocations
allow_set_authority = false      # Block authority changes
allow_mint_to = false            # Block minting operations
allow_initialize_mint = false    # Block mint initialization
allow_initialize_account = false # Block account initialization
allow_initialize_multisig = false # Block multisig initialization
allow_freeze_account = false     # Block account freezing
allow_thaw_account = false       # Block account thawing

# Token-2022 extension blocking
[validation.token2022]
# Block potentially risky mint extensions
blocked_mint_extensions = [
    "transfer_hook",       # Custom transfer logic
    "pausable",            # Can freeze transfers
    "permanent_delegate",  # Permanent control
]
# Block complex account extensions
blocked_account_extensions = [
    "cpi_guard",      # Restricts composability
    "memo_transfer",  # Requires additional data
]

# Sustainable pricing with 15% margin
[validation.price]
type = "margin"
margin = 0.15  # 15% margin on network fees

# Metrics collection
[metrics]
enabled = true
endpoint = "/metrics"
port = 8080
scrape_interval = 60

# Fee payer balance monitoring
[metrics.fee_payer_balance]
enabled = true
expiry_seconds = 30

구성 검증

Kora는 시작 시 구성을 검증합니다. 서버를 시작하지 않고 구성을 검증하려면 구성 검증 명령을 사용할 수 있습니다:

kora --config kora.toml config validate # or validate-with-rpc

또한 validate-with-rpc 명령을 실행하여 RPC 서버로 구성을 검증할 수 있습니다(이 검증 확인은 조금 더 느리지만 더 철저한 계정 검사를 수행합니다)

서버 시작

kora.toml 파일을 구성한 후 Kora 서버를 시작할 수 있습니다:

kora --config path/to/kora.toml rpc start --no-load-signer # --other-rpc-flags-here

--no-load-signer 플래그는 서명자를 로드하지 않고 서버를 초기화합니다. 이는 구성을 테스트하는 데 유용합니다. 서명자를 로드하려면 signers.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"

이렇게 하면 MY_SIGNER_PRIVATE_KEY 환경 변수에서 단일 서명자를 로드합니다. 그런 다음 다음 명령으로 서버를 시작할 수 있습니다:

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

더 자세한 정보와 고급 서명자 구성에 대해서는 서명자 가이드를 참조하세요.

모범 사례

제한적으로 시작: 엄격한 제한으로 시작하여 점진적으로 확장하세요
사용량 모니터링: 실제로 사용되는 프로그램과 토큰을 추적하세요
정기적인 업데이트: 차단 목록과 제한을 정기적으로 검토하고 업데이트하세요
변경 사항 테스트: 스테이징 환경에서 먼저 구성 변경을 검증하세요
버전 관리: 구성 변경 내역을 기록하세요

도움이 필요하신가요?

인증 설정에 대해서는 인증 가이드를 확인하세요
서명자 구성에 대해서는 서명자 가이드를 확인하세요
Kora 노드 운영 방법에 대한 자세한 내용은 운영자 가이드를 확인하세요
kora 태그와 함께 Solana Stack Exchange를 방문하세요
GitHub에서 이슈를 보고하세요

목차