--l1-trust-rpc flag controls whether Kona performs additional verification on L1 RPC responses to protect against malicious or faulty RPC providers. This guide helps you choose the right setting for your infrastructure and shows how to configure it.
The L2 engine is not covered by a trust flag. It is the node’s own execution client, reached over the authenticated Engine API, and an execution client that misreports blocks already controls the node’s view of the chain. Kona therefore always trusts it, as op-node does.
Trust Modes
The default matches op-node: L1 trust is disabled (false). To retain the previous L1 trust behavior, set --l1-trust-rpc=true or KONA_NODE_L1_TRUST_RPC=true.
Trust Mode (trust enabled, true):
- RPC responses are used without verification
- Optimized for performance
- Suitable for local nodes and trusted infrastructure
- Assumes the RPC provider is reliable and honest
false):
- Every L1 header is checked against its block hash, and every L1 block found by number must be at that number
- Each L1 block’s transactions and receipts are checked against the header’s transactions and receipts roots
- The unsafe block signer, read from the
SystemConfigcontract on L1, is proven against the block’s state root witheth_getProof - Protects against malicious or faulty RPC providers returning incorrect data
- Recommended for public or third-party RPC endpoints
- Small performance overhead from the checks
With
--l1-trust-rpc=false, the L1 RPC must serve eth_getProof for recent blocks. Without it, kona-node cannot read the unsafe block signer and fails to start. At startup, kona-node reads the signer at the L1 head and makes up to five attempts, 10 seconds apart, each at the then-current head.By default, Reth serves eth_getProof only for its head block (--rpc.eth-proof-window is 0), so a read fails whenever a new L1 block arrives before it completes. If your L1 RPC is Reth, set --rpc.eth-proof-window to a few blocks or more.Examples
Using a trusted local L1 RPC:Security Recommendations
- Local Infrastructure: Use trust mode (
true) only for an L1 RPC you control - Public RPCs: Use
--l1-trust-rpc=falsefor third-party endpoints - Shared Infrastructure: Consider disabling trust when the L1 RPC is shared
- Performance Testing: The verification overhead is minimal but can be measured in high-throughput scenarios
Next Steps
- The flag is catalogued with the rest of the node’s options in the Kona node CLI reference.
- To get a node running end to end, follow the binary guide or the Docker guide.