History

KonradStaniec 52a2ba4bd7 Handle blocks from cache (#1312 ) * Handle blocks from cache		2022-11-23 12:46:09 +01:00
..
docs	Update Nimbus Light Client Proxy documentation (#1308 )	2022-11-18 14:37:22 +01:00
rpc	Handle blocks from cache (#1312 )	2022-11-23 12:46:09 +01:00
tests	Add improved mpt trie proof verification (#1223 )	2022-09-15 13:04:41 +02:00
README.md	Update Nimbus Light Client Proxy documentation (#1308 )	2022-11-18 14:37:22 +01:00
block_cache.nim	Handle blocks from cache (#1312 )	2022-11-23 12:46:09 +01:00
lc_proxy.nim	Add simple block cache. Handle numeric params (#1241 )	2022-09-28 10:01:32 +02:00
lc_proxy_conf.nim	Use rpcProxy in lc proxy (#1238 )	2022-09-24 13:57:27 +02:00
nim.cfg	…
validate_proof.nim	Add eth_getCode to lc proxy (#1310 )	2022-11-21 13:28:15 +01:00

README.md

Nimbus Light Client Proxy

The Nimbus Light Client Proxy is a very efficient light client for the Ethereum PoS network.

It exposes the standard Ethereum JSON RPC Execution API and proxies the API calls to a configured, untrusted, web3 data provider. Responses from the web3 data provider are verified by requesting Merkle proofs and checking them against the state hash.

The consensus p2p light client is used to efficiently follow the tip of the consensus chain and have access to the latest state hash.

As such the Nimbus Light Client Proxy turns the untrusted web3 data provider into a verified data source, and it can be directly used by any wallet that relies on the Ethereum JSON RPC Execution API.

Build the Nimbus Light Client Proxy from source

# Clone the nimbus-eth1 repository
git clone git@github.com:status-im/nimbus-eth1.git
cd nimbus-eth1

# Run the build process
make lc-proxy

# See available command line options
./build/lc_proxy --help

Run the Nimbus Light Client Proxy

Two options need to be explicitly configured by the user:

--trusted-block-root: The consensus light client starts syncing from a trusted block. This trusted block should be somewhat recent (~1-2 weeks) and needs to be configured each time when starting the Nimbus Light Client Proxy.
--web3-url - As the proxy does not use any storage, it needs access to an Ethereum JSON RPC endpoint to provide the requested data. This can be a regular full node, or an external web3 data provider like Alchemy.

A first requirement for the web3 data provider is that it must support the standard Ethereum JSON RPC Execution API, including the eth_getProof call. The latter is necessary to validate the provided data against the light client.

A second requirement is that data served from provider needs to match with the --network option configured for the Nimbus Light Client Proxy. By default the light client proxy is configured to work on mainnet. Thus, the configured provider needs to serve mainnet data. This is verified on start-up by querying the provider its eth_chainId endpoint, and comparing the received chain id with the one configured locally. If this validation fails, the Nimbus Light Client Proxy will quit.

Note: Infura currently does not support the eth_getProof call.

Obtaining a trusted block root

A block root may be obtained from a trusted beacon node or from a trusted provider.

Trusted beacon node:

The REST interface must be enabled on the trusted beacon node (--rest --rest-port=5052 for Nimbus).
```
curl -s "http://localhost:5052/eth/v1/beacon/headers/finalized" | \
    jq -r '.data.root'
```
Trusted provider, e.g. Beaconcha.in:

On the beaconcha.in website (Goerli), navigate to the Epochs section and select a recent Finalized epoch. Then, scroll down to the bottom of the page. If the bottom-most slot has a Proposed status, copy its Root Hash. Otherwise, for example if the bottom-most slot was Missed, go back and pick a different epoch.

Start the process

To start the proxy for the Goerli network, run the following command (inserting your own trusted block root and replacing the web3-url to your provider of choice):

# From the nimbus-eth1 repository
TRUSTED_BLOCK_ROOT=0x1234567890123456789012345678901234567890123456789012345678901234 # Replace this
./build/lc_proxy \
    --network=goerli \
    --trusted-block-root=${TRUSTED_BLOCK_ROOT} \
    --web3-url="wss://eth-goerli.g.alchemy.com/v2/<ApiKey>"

Using the Nimbus Light Client Proxy with existing Wallets

The Nimbus Light Client Proxy exposes the standard Ethereum JSON RPC Execution API and can thus be used as drop-in replacement for any Wallet that relies on this API.

By doing so, it turns an untrusted web3 data provider into a verified data source.

The Nimbus Light Client Proxy has been tested in combination with MetaMask.

The MetaMask configuration page explains how to configure the proxy, and how to configure MetaMask to make use of the proxy.

Update and rebuild the Nimbus Light Client Proxy

# From the nimbus-eth1 repository
git pull
# To bring the git submodules up to date
make update

make lc-proxy

Run the Nimbus Light Client Proxy test suite

# From the nimbus-eth1 repository
make lc-proxy-test

Windows support

Follow the steps outlined here to build light client proxy on Windows.

For Developers

When working on this repository, you can run the env.sh script to run a command with the right environment variables set. This means the vendored Nim and Nim modules will be used, just as when you use make.

E.g.:

# start a new interactive shell with the right env vars set
./env.sh bash

License

Licensed and distributed under either of

MIT license: LICENSE-MIT or http://opensource.org/licenses/MIT

Apache License, Version 2.0, (LICENSE-APACHEv2 or http://www.apache.org/licenses/LICENSE-2.0)

at your option. These files may not be copied, modified, or distributed except according to those terms.