Critical / required
High · bug research targets
Medium · worth reviewing
Low · informational
01 Configuration Settings

Parameters for rippled.cfg. All section and key names sourced from src/xrpld/core/Sections.h.

Performance Tuning
Primary targets for node_size bug research. Use get_counts cache hit rates to validate behaviour across node_size values.
SectionDefaultValid ValuesDescription
[node_size]auto (medium)tiny | small | medium | large | hugeMaster tuning knob. Sets cache sizes, object limits, thread allocations. Auto-detects from RAM on startup. BUG Auto collapses large→medium on 4-core/32GB. Docs now explicitly say large is not recommended — use huge if ≥32GB.
[workers]CPU cores + 2integer ≥ 1App worker threads for peer/client request processing. Standalone mode defaults to 1. Interaction with node_size needs source verification in Config.cpp.
[io_workers]src? hardcoded pre-PR#3994integerRaw inbound/outbound IO threads. Hub operators should increase. Default not documented — read Config.cpp.
[prefetch_workers]src?integerThreads for nodestore prefetching. Tuning this improves ledger fetch performance under load.
[sweep_interval]src?integer (seconds)Frequency of cache sweep to evict stale objects. Lower = faster memory release, higher CPU cost.
[max_transactions]250100 – 1000Max transactions in job queue before throttling. Hard floor 100, ceiling 1000.
[node_db] — Ledger Store
Almost all production servers should use NuDB on SSD. RocksDB is legacy and degrades over time.
KeyDefaultValid ValuesDescription
typeNuDBNuDB | RocksDBDatabase backend. NuDB has near-constant performance regardless of data size. RocksDB is legacy — avoid for new deployments.
path(required)directory pathLedger store location on disk. High-grade SSD required. >10,000 reads/sec and >7,000 writes/sec observed on production clusters.
online_delete2000integer (ledger count)How many ledger versions to retain (2000 ≈ 2 hours). Must be ≥ ledger_history. Full history servers omit this. Plan for 2× this value in disk space.
advisory_delete00 | 10 = auto-delete on threshold. 1 = wait for can_delete RPC before deleting. Useful for maintenance windows.
cache_mbsrc?integer (MB)RocksDB Cache size in MB. BUG2 Investigate whether node_size scales this proportionally — if not, large underperforms medium.
cache_size16384integer (records)NuDB cache record count. 0 = use default.
cache_agesrc?integer (minutes)How long to keep DB records in cache.
bg_threadssrc?integerRocksDB Background compaction threads. BUG2 If node_size sets cache_mb but not bg_threads proportionally, large underperforms medium.
open_files512integerRocksDB Open file handles.
filter_bits12integerRocksDB Bloom filter bits per key.
file_size_mb64integerRocksDB SST file target size in MB.
file_size_mult2integerRocksDB File size level multiplier.
earliest_seq32570integer ≥ 1Earliest ledger sequence to store. Override to 1 for private networks starting from genesis.
nudb_block_sizesrc?integerNuDB Block size tuning parameter.
[database_path] / [sqlite] — Bookkeeping Databases
Deleting wallet.db in database_path loses runtime config including amendment votes and peer reservations.
Section / KeyDefaultValid ValuesDescription
[database_path](required)directory pathWhere SQLite bookkeeping DBs are stored: transaction data, amendment votes, peer reservations. Separate from node_db.
journal_modesrc?WAL | DELETE | TRUNCATESQLite journal mode. WAL recommended for best performance.
journal_size_limitsrc?integer (bytes)SQLite WAL file size before forcing a checkpoint.
synchronoussrc?NORMAL | FULL | OFFSQLite sync mode. FULL = safest, NORMAL = faster.
temp_storesrc?0 | 1 | 2SQLite temp storage: 0=default, 1=file, 2=memory.
page_sizesrc?integerSQLite page size in bytes.
Peer / Network
SectionDefaultValid ValuesDescription
[ips]r.ripple.com 51235 + 3 othershostname/IP listBootstrap peer list. One per line, optional port. Default hardcoded in source. Validators should override with ips_fixed peers only.
[ips_fixed]emptyhostname:port listPersistent connections never dropped by churn. Use for validator→hub links. Port required.
[peer_private]00 | 11 = hide your IP from being advertised to the network. Validators should always use 1. Must have ips_fixed set if enabled.
[peers_max]src?integerTotal max peer connections (in + out). Cluster/fixed peers excluded from count. Implementation-enforced minimum.
[peers_in_max]src?integerMax inbound peers independently. Added v1.7.0.
[peers_out_max]src?integerMax outbound peers independently. Added v1.7.0.
[network_id]not set0=main | 1=testnet | 2=devnet | uint32Prevents accidental cross-network peering. Server refuses connections from nodes on a different network_id.
[network_quorum]src?integerMin peer count before node starts processing ledgers.
[compression]falsetrue | falseLZ4 peer message compression. Both peers must have it enabled. Saves bandwidth, costs CPU.
[reduce_relay]src?0 | 1Reduces redundant message relay between peers.
[cluster_nodes]emptypubkey [name] listrippled-level cluster: full trust between listed nodes. Only for co-administered servers.
[elb_support]src?0 | 1AWS ELB/load balancer proxy protocol. Passes real client IP.
[server_domain]emptydomain stringPublished in crawl data. Domain TOML should reference this node's pubkey.
[overlay] public_ipsrc?IPv4 addressKnown fixed public IP. Helps peers connect correctly when behind NAT.
[overlay] vp_enablesrc?0 | 1Validator propagation squelch. Reduces redundant validation message relay.
[overlay] tx_relay_percentagesrc?integer %Percentage of peers to relay transactions to when reduce_relay is active.
Ledger History
SectionDefaultValid ValuesDescription
[ledger_history]256integer | full | noneLedger versions to back-fill and keep. Must be ≤ node_db online_delete. 256 is sufficient for consensus. Full history ≈ 26TB.
[fetch_depth]src?integer | fullHow far back to serve ledger history to requesting peers.
[ledger_replay]0 (disabled)0 | 1Experimental. Acquires ledgers by replaying transactions rather than downloading state snapshots. Not for production.
[ledger_tx_tables]src?0 | 1Whether ledger/transaction lookup tables are maintained in the SQLite DB.
[transaction_queue]
Fine-grained queue control. Rarely needs tuning except on high-traffic public API servers. All defaults require source verification.
KeyDefaultValid ValuesDescription
ledgers_in_queuesrc?integerLedgers worth of transactions to hold in queue ahead of open ledger.
minimum_txn_in_ledgersrc?integerMinimum transactions to target per ledger close.
maximum_txn_in_ledgersrc?integerHard maximum transactions per ledger close.
target_txn_in_ledgersrc?integerTarget transaction count for fee escalation calculations.
minimum_escalation_multipliersrc?integerMinimum fee escalation multiplier.
maximum_txn_per_accountsrc?integerMax queued transactions per account.
minimum_queue_sizesrc?integerMinimum queue size regardless of load.
retry_sequence_percentsrc?integer %Retry percentage for out-of-sequence transactions.
normal_consensus_increase_percentsrc?integer %Queue size increase % per normal consensus round.
slow_consensus_decrease_percentsrc?integer %Queue size decrease % per slow consensus round.
minimum_last_ledger_buffersrc?integerBuffer ledgers before LastLedgerSequence expiry.
Path Finding
High values increase CPU cost per path_find request. Public API nodes should keep these conservative.
SectionDefaultValid ValuesDescription
[path_search]7integerDefault path search depth for standard requests.
[path_search_fast]2integerReduced depth for fast/cheap path searches.
[path_search_max]10integerHard ceiling on path search complexity. Prevents runaway searches.
[path_search_old]src?0 | 1Legacy path search algorithm. Deprecated.
[hashrouter]
KeyDefaultValid ValuesDescription
hold_timesrc?integer (seconds)How long transaction hashes are held to suppress relay duplicates. Increasing reduces duplicate processing at cost of memory.
Amendment Voting
SectionDefaultValid ValuesDescription
[amendments]emptyhash listExplicitly enable amendments. Testnet/devnet only.
[veto_amendments]emptyhash listAmendments this validator votes against.
[amendment_majority_time]2 weeksduration stringHow long an amendment must hold >80% support before activating.
[features]src?src?New section in current Sections.h. Likely supplements or replaces [amendments]. Needs source investigation.
[voting]src?key/value blockVoting configuration block. New in current header — undocumented.
Validator Identity
Sensitive. Always back up before any changes. Backup command: cp rippled.cfg rippled.cfg.bak.$(date +%Y%m%d_%H%M%S)
SectionDefaultValid ValuesDescription
[validator_token]required on validatorstoken blobCurrent ephemeral signing token from validator-keys-tool. Rotate periodically.
[validator_keys]required on validatorskey listValidator signing key(s). Replaces deprecated node_seed / validation_seed.
[validator_key_revocation]emptyrevocation blobPublish immediately if key is compromised. Alerts the network.
[validator_list_sites]vl.ripple.com + othersURL listWhere to fetch UNL. Override for Xahau or private networks.
[validator_list_keys]Ripple UNL signing keykey listKeys that sign trusted UNL lists.
[validator_list_threshold]src?integer %Minimum % of trusted validators needed to trust a UNL.
[vl]src?src?New section in current Sections.h. Related to validator list handling — needs source investigation.
[validators]emptypubkey [name] listHardcoded trusted validators. Use validator_list_sites instead.
[validators_file]emptyfile pathExternal file of trusted validators.
[node_seed]deprecatedseed stringDeprecated. Use [validator_keys].
[validation_seed]deprecatedseed stringDeprecated. Use [validator_token].
RPC / API / Ports
Section / KeyDefaultValid ValuesDescription
[server]requiredlist of port section namesDeclares all listening ports. Each name maps to a [port_xxx] stanza.
[port_xxx] iprequiredIP | 0.0.0.0 | ::Interface to bind. 0.0.0.0 = all IPv4, :: = all IPv4+IPv6.
[port_xxx] portrequiredintegerPort number to listen on.
[port_xxx] protocolrequiredhttp | https | ws | wss | peerProtocols. Only one port can handle peer protocol. ws and http cannot mix with wss/https.
[port_xxx] adminempty (no admin)IP list | 127.0.0.1IPs allowed to use admin RPC commands. Typically 127.0.0.1.
[port_xxx] limit0 (unlimited)integerMax concurrent connections on this port.
[port_xxx] send_queue_limit1001 – 65535WebSocket send queue depth before disconnecting a client.
[port_xxx] secure_gatewayemptyIP listTrusted proxy IPs. Passes X-User / X-Forwarded-For headers, lifts resource limits.
[port_grpc]disabledport section nameEnables gRPC interface for Clio server.
[beta_rpc_api]falsetrue | falseEnables experimental RPC methods not in stable API.
[rpc_startup]emptyJSON command listRPC commands run at startup. Standard use: {"command":"log_level","severity":"warning"}
[signing_support]falsetrue | falseAllow clients to use this node to sign transactions. Disable on public nodes.
[crawl]
Controls what the public peer crawler endpoint exposes. All fields default enabled except counts.
KeyDefaultValid ValuesDescription
overlay10 | 1Include overlay peer data in crawl response.
server10 | 1Include server_info in crawl response.
counts00 | 1Include get_counts data in crawl response. Disabled by default.
unl10 | 1Include UNL data in crawl response.
Relay Behaviour
These should not be changed on production validators. Both must be true (1) for correct network participation.
SectionDefaultValid ValuesDescription
[relay_proposals]true (1)0 | 1Relay consensus proposals to peers. Must be 1 on validators.
[relay_validations]true (1)0 | 1Relay validations to peers. Must be 1 on validators.
SSL / HTTPS Client
SectionDefaultValid ValuesDescription
[ssl_verify]10 | 1Verify peer TLS certificates for outbound HTTPS connections.
[ssl_verify_file]emptyfile pathCustom CA cert file for peer verification.
[ssl_verify_dir]emptydirectory pathDirectory of CA certs for peer verification.
[sntp_servers]time.windows.com + othershostname listNTP servers. Critical — clock skew causes validation failures and consensus issues.
Diagnostics / Misc
SectionDefaultValid ValuesDescription
[debug_logfile]emptyfile pathSeparate debug log file. Debug level logging costs several GB/day — use warning in production.
[fee_default]10integer (drops)Base transaction fee in drops of XRP.
[import_db]emptypath/config blockImport ledger history from another node database.
[perf] log_intervalsrc?integer (seconds)How often to emit StatsD performance metrics.
[perf] prefixsrc?stringStatsD metric prefix.

02 Admin RPC Commands

Require admin access — connect on a port with admin = 127.0.0.1. CLI: rippled <command>  ·  JSON-RPC: {"command": "name", ...}

Status & Diagnostics
CommandAdmin?DescriptionKey Output Fields
server_infoPublicPrimary server status. Sync state, peers, load, build version, complete ledger range, last close time.server_state, complete_ledgers, peers, load_factor, build_version, io_latency_ms
get_countsYesInternal cache stats and object counts. BUG RESEARCH Primary tool for node_size tuning. Shows cache hit rates, object counts, write queue depth. See Section 3 for full field reference.SLE_hit_rate, node_hit_rate, treenode_cache_size, write_load, uptime
consensus_infoYesReal-time consensus state snapshot. Current phase, proposers, positions.phase, proposers, our_position, peer_positions
fetch_infoYesLedger sync status. What ledgers are being fetched and from which peers.peers (with ledger fetch details)
validator_infoYesThis server's validator config. Confirms token and key are loaded correctly.pubkey_validator, manifest, seq
validatorsYesCurrent full validator set with trust status.count, trusted_validator_keys, signing_keys
validator_list_sitesYesUNL fetch site status: last refresh time, expiry, fetch interval.validator_sites (url, last_refresh_time, refresh_interval_min)
featureYesAmendment status. All known amendments, vote counts, enabled/vetoed/pending state.features (per amendment: enabled, vetoed, supported, count, threshold)
manifestPublicLatest public key info for a known validator. Params: public_key.master_key, signing_key, seq, signature
printYesInternal subsystem state dump. Low-level debugging.varies by subsystem
Logging & Data Management
CommandAdmin?DescriptionKey Output Fields
log_levelYesGet or set log verbosity per partition. Partitions: Ledger, TxQ, Peer, Overlay, Consensus, etc. Levels: fatal | error | warning | info | debug | trace. Params: partition (optional), severity.partition, severity (get); message (set)
logrotateYesCloses and reopens the debug log file. Run before external log rotation tools.message: logrotate initiated
ledger_requestYesRequest a specific ledger version from peers. Forces acquisition of historical data. Params: ledger_index.ledger_index, complete, peers_total
ledger_cleanerYesConfigure the ledger cleaner to scan and repair corrupted ledger data.message: Ledger cleaner queued
can_deleteYesWhen advisory_delete=1, authorise online deletion up to a specified ledger. Params: can_delete (ledger index or "never").ledger_index (new can-delete value)
Peer Management
CommandAdmin?DescriptionKey Output Fields
peersYesAll connected peers with connection details, sync state, and latency.peers[]: address, public_key, ledger, load, latency, version
connectYesForce connection to a specific peer. Params: ip, port (optional).message: connecting
peer_reservations_addYesReserve a peer slot for a specific node pubkey. Reserved slots are never dropped by churn. Params: public_key, description (optional).prev (previous reservation if existed)
peer_reservations_delYesRemove a peer reservation. Params: public_key.prev
peer_reservations_listYesList all reserved peer slots.reservations[]
Server Control
CommandAdmin?DescriptionKey Output Fields
stopYesGracefully shut down the rippled server.message: ripple server stopping
ledger_acceptYesStand-alone mode only. Force-close and advance the current ledger.ledger_current_index
Key Generation
CommandAdmin?DescriptionKey Output Fields
wallet_proposeYes*Generate a new account key pair. Params: key_type (secp256k1 | ed25519), passphrase (optional).account_id, master_key, master_seed, master_seed_hex, public_key, public_key_hex
validation_createYesGenerate a node key pair. Note: validators should use validator-keys-tool for tokens instead of this method.validation_public_key, validation_seed, validation_key
Signing — admin by default, can be made public via signing_support
CommandAdmin?DescriptionKey Output Fields
signYes*Sign a transaction. Returns tx_blob ready for submit. Requires signing_support=true or admin access. Params: tx_json, secret (or key_type + seed).tx_blob, tx_json (with hash, SigningPubKey, TxnSignature)
sign_forYes*Contribute one signature to a multi-signature transaction. Params: account, tx_json, secret.tx_blob, tx_json
channel_authorizeYes*Sign a payment channel claim off-chain. Params: channel_id, amount, secret.signature

03 get_counts — Internal Cache Reference

The primary diagnostic tool for node_size tuning research. Wait at least 10–15 minutes after sync before benchmarking — cache hit rates start low on cold start.

BUG RESEARCH: Compare SLE_hit_rate, node_hit_rate, treenode_cache_size, and write_load across node_size values at equivalent load. If 'large' shows similar or lower hit rates than 'medium', cache scaling is broken.
rippled get_counts   |   {"command": "get_counts", "min_count": 10}
FieldTypeDescription & Research Relevance
SLE_hit_ratefloat %State Ledger Entry cache hit rate. Primary benchmark metric. Directly driven by node_size cache allocation. Low rate = undersized cache for current workload.
node_hit_ratefloat %Nodestore object cache hit rate. Should be >90% on a correctly sized node. Drops indicate cache pressure or undersized node_size.
ledger_hit_ratefloat %Ledger header cache hit rate. How often recently-accessed ledgers are served from RAM.
treenode_cache_sizeintegerCurrent treecache object count. Directly set by node_size allocation. Compare medium vs large values to confirm whether allocation actually differs.
treenode_track_sizeintegerTracked treecache objects. If approaching treenode_cache_size, eviction pressure is high — cache is too small for load.
write_loadintegerWrite queue depth to nodestore. High values = storage I/O bottleneck, not cache size. Distinguishes disk from memory issues.
fullbelow_sizeintegerSize of 'full below' cache — tracks subtrees known complete to avoid redundant fetches.
openledger_sizeintegerObjects held in the current open ledger.
local_txsintegerTransactions in local queue awaiting validation.
uptimesecondsNode uptime. Required context — low uptime means cold cache, hit rates will be artificially low.
dbKBTotalKBTotal nodestore database size on disk.
dbKBLedgerKBLedger portion of nodestore database.
dbKBTransactionKBTransaction portion of nodestore database.
ALintegerAvailable ledger versions in local history.

04 Public API Methods

Available without admin credentials via HTTP JSON-RPC or WebSocket. Clio servers provide the same API for historical queries with lower load on validators.

CommandCategoryDescription & Key Parameters
server_infoServerGeneral server status. Public version omits some admin fields.
server_stateServerMachine-readable server_info variant.
server_definitionsServerAll ledger field definitions for the current protocol version.
feeServerCurrent transaction fee and queue info: base_fee, median_fee, minimum_fee, open_ledger_fee.
versionServerAPI version info and supported range.
pingServerLiveness check. Returns immediately.
ledgerLedgerLedger header and optionally transactions or state data. Params: ledger_index, transactions, expand, full.
ledger_closedLedgerMost recently closed ledger hash and index.
ledger_currentLedgerCurrent open ledger index.
ledger_dataLedgerRaw state data from a ledger. Paginate with marker. Expensive — avoid on production validators.
ledger_entryLedgerSingle ledger object by type and ID. Supports: account_root, offer, ripple_state, check, escrow, payment_channel, ticket, nft_offer, amm.
account_infoAccountAccount root: balance, sequence, flags, reserve. Params: account, ledger_index, queue, signer_lists.
account_linesAccountTrust lines for an account. Paginate with marker. Params: account, ledger_index, peer.
account_channelsAccountPayment channels where account is source.
account_currenciesAccountCurrencies the account can send or receive.
account_objectsAccountAll ledger objects owned by account. Params: account, type, ledger_index, limit, marker.
account_offersAccountOpen DEX offers placed by account. Params: account, ledger_index, limit, marker.
account_txAccountTransaction history. Params: account, ledger_index_min/max, limit, marker, forward.
gateway_balancesAccountIssued currency totals for an issuer. Params: account, hotwallet.
noripple_checkAccountIdentify trust line No-Ripple flag configuration issues.
transaction / txTransactionSingle transaction by hash. Params: transaction (hash), binary, include_deleted.
submitTransactionSubmit a signed transaction blob. Returns preliminary result before validation. Params: tx_blob.
submit_multisignedTransactionSubmit a multi-signed transaction. Params: tx_json.
simulateTransactionDry-run a transaction without submitting. Returns what the result would be.
book_offersDEXCurrent order book for a currency pair. Params: taker_pays, taker_gets, limit.
path_findPathsWebSocket only. Subscribe to path updates for a payment. Continuously updated until closed.
ripple_path_findPathsOne-shot path find. Less resource-intensive than path_find. Params: source_account, destination_account, destination_amount.
channel_verifyChannelsVerify a payment channel claim signature.
subscribeStreamsSubscribe to event streams: ledger, transactions, transactions_proposed, server, peer_status, validations, manifests, book_changes.
unsubscribeStreamsCancel a stream subscription.
nft_infoNFTInfo about a specific NFT by NFTokenID.
nft_buy_offersNFTBuy offers for a specific NFT.
nft_sell_offersNFTSell offers for a specific NFT.
nfts_by_issuerNFTNFTs minted by an issuer. Params: issuer, nft_taxon, limit, marker.
amm_infoAMMState of an Automated Market Maker pool. Params: amm_account or asset/asset2 pair.
deposit_authorizedMiscCheck if source account is authorized to send to destination (DepositAuth).
randomMiscReturns a cryptographically random 256-bit hex value from the server.

05 Command-Line Usage
Flag / ModeDescription
rippledStart in daemon mode (default). Reads rippled.cfg from standard locations.
--conf <path>Specify config file path explicitly.
--fgRun in foreground — don't daemonize. Useful for debugging.
-qQuiet mode — suppress startup output.
--silentSuppress all console output.
-v / --verboseVerbose output.
--versionPrint build version, Git commit hash, and build branch.
-h / --helpPrint usage statement.
-u / --unittestRun unit tests and print results.
rippled <command>Client mode: connect to running rippled and issue RPC command. Examples: rippled server_info   rippled get_counts   rippled peers   rippled stop
--standalone / -aRun in stand-alone mode: no network, no consensus. For testing.
--startStart with a fresh ledger in standalone mode.
--ledger <file>Load ledger from file (standalone / testing mode).
--importImport history from another node database.

06 node_size RAM Requirements

Official guidance from xrpl.org Capacity Planning docs. Note: large is explicitly listed as not recommended — it performs worse than huge in most circumstances.

node_sizeRAM RequiredRecommended UseNotes
tiny< 8 GBNot recommendedMay fail to sync on a busy network.
small8 GBTest servers / occasional use
medium16 GBDefault in rippled-example.cfgAuto-selected for 16GB systems. BUG: also auto-selected for 4-core/32GB machines.
large32 GBNOT RECOMMENDEDExplicitly listed as underperforming huge in most circumstances. Auto-detection may collapse this to medium.
huge64 GBRecommended for all productionOnly setting to use for mainnet stability if ≥64GB RAM available.

07 Key Source Files for Research

Files to read in the XRPLF/rippled repository to confirm undocumented defaults and investigate the node_size bug.

src/xrpld/core/Sections.h
All config section and key name constants. The header file provided — canonical list of everything configurable.
src/xrpld/core/Config.cpp
Config loading and default value assignments. PRIMARY FILE for confirming defaults for workers, io_workers, prefetch_workers, sweep_interval, path_search values.
src/xrpld/app/main/Application.cpp
Application startup and node_size→cache size mapping. PRIMARY FILE for BUG2 research — where node_size values translate to actual memory allocations.
src/xrpld/rpc/handlers/GetCounts.cpp
get_counts implementation. Shows exactly which fields are returned and how they are calculated. Cross-reference with benchmark results.
src/xrpld/app/misc/TxQ.cpp
Transaction queue implementation. Relevant to transaction_queue section defaults and behaviour.
src/xrpld/overlay/impl/PeerImp.cpp
Peer connection implementation. Relevant to peers_max, io_workers actual behaviour under load.
src/xrpld/app/misc/HashRouter.cpp
Hash router implementation. Contains hold_time default value.
src/xrpld/nodestore/impl/Database.cpp
Nodestore cache implementation details. Relevant to cache_size, cache_mb, and bg_threads behaviour.
cfg/rippled-example.cfg
Documented defaults and descriptions. Master reference for anything officially documented.
Elephant Tools · onledger.net · rippled reference · not official Ripple documentation