Run a Light Node
#
OverviewNode version: conflux-rust v2.0.0
.
Light nodes are special nodes in the Conflux network that store block headers only, and retrieve everything else from their peers on-demand. This means that by default, light nodes do not store transactions, nor do they store the state trees. This can drastically reduce the disk and bandwidth use of light nodes compared to full and archive nodes, especially under high TPS. As a trade-off, RPC queries have a higher latency on light nodes.
Light nodes execute GHAST consensus on their local header graph, and they also verify each item retrieved on-demand using Merkle proofs and other similar mechanisms. Items retrieved on-demand include accounts, bloom filters, transactions, and transaction receipts. This means that, while light nodes need to rely on their peers to fulfill RPC queries, they do this in a trustless manner.
The current light node implementation is still considered experimental, bugs are expected to exist. If you encounter any issues, please let us know by opening an issue on the conflux-rust repository.
#
Running a light nodeLight nodes are implemented as a part of the official conflux-rust
binary and can be enabled using the --light
command line flag.
Please start by downloading the latest release from the conflux-rust repository, or by building from source following this guide. Then, you can simply run the node using these commands:
Alternatively, if you want your node to connect to the testnet, you will need to pass testnet.toml
instead. Similarly to full nodes, you will know when your node is fully synced with the network once it prints:
#
Interacting with a light nodeSimilarly to full and archive nodes, you can interact with a light node through an HTTP, TCP, or WebSocket connection. By default, local HTTP queries are enabled through port 12539
. For details, please refer to the JSON-RPC documentation.
#
RPC queriesLight nodes support most Conflux RPC APIs, and support for the rest is also on the way. As light nodes need to query their peers to fulfill RPC requests, the overall latency is slightly larger. (It is significantly larger for cfx_getLogs
, see below.)
#
JavaScriptLight nodes support most of the functionalities of the JavaScript SDK (js-conflux-sdk). You can install the SDK using the following command:
Then, you can query the blockchain and send transactions:
#
Other SDKsWhile it has not been tested, light nodes are expected to work with the Java and Go SDKs as well.
#
Troubleshooting#
Why do I get an error when calling a contract method?If you run the following code:
... you will get this error:
This is because contract calls use the cfx_call
RPC API which is not yet supported on light nodes. For details, please refer to this table.
Suppose you would like to send a transaction to a smart contract:
You will get a similar error. This is because for contract transactions, js-conflux-sdk
will automatically attempt to estimate the gas limit and storage limit using the cfx_estimateGasAndCollateral
RPC which is not yet supported on light nodes. You can address this by manually setting these parameters:
If you encounter a This API is not implemented yet
error, you can set the debug logger on the conflux object to find out which RPC is causing it.
#
Why do I see timeout instead of null?For most operations, you might sometimes see a timeout error:
This is because light nodes have to retrieve transactions and other items from their peers. If no peer responds within 4 seconds, you will get a timeout error. In most cases, retrying the query will succeed.
You will also get a timeout if you call conflux.getTransactionByHash
and pass a transaction hash that does not exist. This is because the "non-existence" or transactions is not something light nodes can verify, so returning null
might be misleading. This behavior might change in the future.
#
I'm searching through event logs, why is it so slow?Log filtering is a very expensive operation on light nodes. For each epoch in the range you specify, the node needs to perform 1 to 3 queries. We recommend you make multiple queries with smaller epoch ranges.
Instead of...
... you are encouraged to do this: