> For the complete documentation index, see [llms.txt](https://docs.pharos.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pharos.xyz/node-and-validator-guide/validator-node-deployment/node-configuration.md). # Node Configuration This document provides detailed configuration guidance for Pharos nodes, including node types, configuration files, RPC tuning, and node pool scheduling strategies. ## Node Types Pharos supports the following node types: | Node Type | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | **Validator Node** | Joins the consensus network and participates in block production through consensus. | | **Fullnode** | Similar to validator node, but not included in the consensus node set. Serves as a regular RPC node or as a failover backup for validators. | | **Full Cache Node** | A fullnode with an additional flat state database to accelerate state data queries. | | **Tracedb Node** | A fullnode with an additional trace database to accelerate trace-related request responses. | *** ## Node Configuration (pharos.conf) ### Base Configuration All node types share the same base configuration. Pre-built configuration files are available: * **Fullnode / Validator**: [full.conf](https://raw.githubusercontent.com/PharosNetwork/resources/main/conf/full.conf) * **Full Cache Node**: [full-cache-node.conf](https://raw.githubusercontent.com/PharosNetwork/resources/main/conf/full-cache-node.conf) * **Tracedb Node**: [traceDB.conf](https://raw.githubusercontent.com/PharosNetwork/resources/main/conf/traceDB.conf) The base configuration for fullnode/validator: ```json { "chain": { "secret_config": { "domain_key_path": "../keys/domain.key", "stabilizing_key_path": "../keys/stabilizing.key" }, "startup_config": { "init_config": { "meta_path": "../data", "host_ip": "127.0.0.1", "http_port": "18100", "rpc_port": "20000", "tcp_port": "19000", "ws_port": "18200" } } }, "storage": { "mygrid_conf": {}, "mygrid_env": { "storage_data_path": "../data" } } } ``` ### Enabling Full Cache Node (Flat State KV DB) To accelerate state data queries (e.g., `getBalance`, `getCode`, `getStorageAt`), enable the flat state KV database on top of the base configuration: ```json { "storage": { "mygrid_conf": { "config": { "mygrid": { "expert_flags": { "mygrid_client_enable_full_state_kv_db": true } } } } } } ``` This adds a secondary key-value index alongside the Merkle state database, providing O(1) lookups for account and storage data across all historical blocks. Recommended for RPC nodes serving high-volume state queries. ### Enabling Tracedb Node To support `debug_traceTransaction`, `debug_traceBlockByHash`, `debug_traceBlockByNumber`, and `trace_filter`, enable trace persistence on top of the base configuration: ```json { "chain": { "startup_config": { "parameters": { "/GlobalFlag/enable_persist_trace": "true" } } } } ``` This persists transaction execution traces to a dedicated database, enabling trace replay without re-executing transactions. Recommended for nodes serving debug/trace API requests. ### Combining Full Cache + Tracedb Both features can be enabled simultaneously for maximum query capability: ```json { "chain": { "startup_config": { "parameters": { "/GlobalFlag/enable_persist_trace": "true" } } }, "storage": { "mygrid_conf": { "config": { "mygrid": { "expert_flags": { "mygrid_client_enable_full_state_kv_db": true } } } } } } ``` > **Note:** Enabling both features increases disk usage significantly. Plan for additional storage capacity beyond the base 5 TB requirement. *** ## RPC Node Tuning Since RPC nodes primarily handle state queries, block queries, and simulated transaction execution, they require strong JSON-RPC layer processing capabilities. The following configurations can be used to tune the JSON-RPC layer processing logic. ### Thread Counts and Queue Sizes | Configuration Item | Default Value | Purpose | Impact on RPC Node Performance | | ------------------------------- | ------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | `cache_query_worker_count` | 16 | Handles `getBlock*`/`getTx*`/`getReceipt*` and other cache queries | **High**: Insufficient workers cause queuing and increased latency | | `cache_query_worker_queue_size` | 1000 | Pending queue for above workers | Queue full at high QPS will reject or block | | `db_query_worker_count` | 4 | Handles `getBalance`/`getCode`/`getStorageAt` and other state queries | **High**: Easy to become bottleneck when state queries are frequent | | `db_query_worker_queue_size` | 1000 | Queue for above | Can increase appropriately | | `heavy_task_worker_count` | 4 | Handles `getLogs`, `feeHistory` | **Medium**: `getLogs` is time-consuming, need more workers when concurrent | | `heavy_task_worker_queue_size` | 1000 | Queue for above | Can increase when heavy tasks are frequent | | `eth_default_worker_count` | 4 | `blockNumber`, `syncing`, `chainId`, `gasPrice`, `subscribe`, etc. | **Medium**: Can slightly increase when connection count is high | | `sim_tx_worker_count` | 16 | `eth_call`, `estimateGas`, `createAccessList` | **Medium-High**: Easy to become bottleneck when dApps have many `eth_call` requests | | `raw_tx_worker_count` | 10 | `sendRawTransaction` | **Low**: Can reduce if node doesn't primarily receive transactions | ### Session Management | Configuration Item | Default Value | Purpose | Impact | | ------------------------------- | ------------- | ----------------------------------- | ---------------------------------------------------------------- | | `max_session` | 102400 | Maximum session count | Needs to be large enough for multi-client scenarios | | `max_batch_request_size` | 20 | Single batch JSON-RPC request count | Increasing can reduce connections and round-trips | | `enable_http_long_connection` | true | HTTP long connection | Recommend keeping `true` to reduce connection overhead | | `session_idle_timeout_for_http` | 400000 | HTTP session idle timeout (ms) | Reduces invalid connections | | `session_idle_timeout_for_ws` | 360000 | WebSocket session idle timeout (ms) | Reduces invalid connections | | `socket_thread_count` | 16 | Accept connections, read socket | Insufficient when connection count is high will limit throughput | ### Block Cache | Configuration Item | Default Value | Purpose | Impact | | ------------------ | ------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `cache_depth` | 2048 | Number of recent blocks cached (header/body/tx/receipt) | `getBlock*`/`getTx*`/`getReceipt*` cache hit avoids disk read, increasing can significantly improve hit rate and reduce latency | *** ## Node Pool JSON-RPC API Scheduling Strategy Recommendations for node pool `eth` JSON-RPC API scheduling: ### By Node Type | Node Type | Scheduling Rule | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Tracedb Node** | `trace_filter` can **only** be served by tracedb node. `debug_traceBlockByHash`, `debug_traceBlockByNumber`, `debug_traceTransaction` should be **preferentially** scheduled to tracedb node. | | **RPC Node** | Interfaces other than trace/debug can be scheduled to regular RPC nodes. | | **Fullnode** | Can be scheduled as a regular RPC node. | | **Validator Node** | **Do not** schedule any JSON-RPC requests, only handle transactions forwarded from other RPC nodes. | ### By Data Availability When fullnode enables state data pruning and only retains `(latest - pruning_window, latest]`, please note the state data availability range and request range in scheduling strategy. ### By Interface Affinity Affinity-related requests need to be scheduled to the **same node**: * **Transaction submission group**: `eth_sendRawTransaction` and related queries `eth_getTransactionCount`, `eth_getTransactionByHash`, `eth_estimateGas`/`eth_call`, especially pending state-based queries. * **Filter group**: `eth_newFilter`, `eth_newBlockFilter`, `eth_newPendingTransactionFilter` for monitoring and event retrieval `eth_getFilterChanges`. (Pharos currently uses `eth_subscribe` instead of filter interfaces.) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.pharos.xyz/node-and-validator-guide/validator-node-deployment/node-configuration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.