status-im
/
nimbus-eth1
mirror of https://github.com/status-im/nimbus-eth1.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Update Nimbus Light Client Proxy documentation (#1308)

This commit is contained in:
Kim De Mey 2022-11-18 14:37:22 +01:00 committed by GitHub
parent 5374e7d37f
commit 9da1e7b755
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 105 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

108
lc_proxy/README.md
View File

@ -1,6 +1,6 @@
# Light Client Proxy # Nimbus Light Client Proxy
[![Light client proxy CI](https://github.com/status-im/nimbus-eth1/actions/workflows/lc_proxy.yml/badge.svg)](https://github.com/status-im/nimbus-eth1/actions/workflows/lc_proxy.yml) [![Nimbus Light Client Proxy CI](https://github.com/status-im/nimbus-eth1/actions/workflows/lc_proxy.yml/badge.svg)](https://github.com/status-im/nimbus-eth1/actions/workflows/lc_proxy.yml)
![Stability: experimental](https://img.shields.io/badge/stability-experimental-orange.svg) ![Stability: experimental](https://img.shields.io/badge/stability-experimental-orange.svg)
[![License: Apache](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![License: Apache](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
@ -8,18 +8,30 @@
[![Discord: Nimbus](https://img.shields.io/badge/Discord-Nimbus-blue.svg)](https://discord.gg/XRxWahP) [![Discord: Nimbus](https://img.shields.io/badge/Discord-Nimbus-blue.svg)](https://discord.gg/XRxWahP)
[![Status: #nimbus-general](https://img.shields.io/badge/Status-nimbus--general-blue.svg)](https://join.status.im/nimbus-general) [![Status: #nimbus-general](https://img.shields.io/badge/Status-nimbus--general-blue.svg)](https://join.status.im/nimbus-general)
## Introduction The Nimbus Light Client Proxy is a very efficient light client for the Ethereum
This folder holds the development of light client proxy. Light client proxy PoS network.
uses the [consensus light client](https://github.com/ethereum/consensus-specs/tree/dev/specs/altair/light-client)
to follow the tip of the consensus chain and exposes the standard Ethereum [JSON RPC Execution API](https://github.com/ethereum/execution-apis).
The API calls are proxied to a configured web3 data provider and the provider its responses are verified
against recent consensus data provided by the light client before returning
the result to the caller.
### Build light client proxy It exposes the standard [Ethereum JSON RPC Execution API](https://github.com/ethereum/execution-apis)
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](https://github.com/ethereum/consensus-specs/tree/dev/specs/altair/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
```bash ```bash
# Clone the nimbus-eth1 repository
git clone git@github.com:status-im/nimbus-eth1.git git clone git@github.com:status-im/nimbus-eth1.git
cd nimbus-eth1 cd nimbus-eth1
# Run the build process
make lc-proxy make lc-proxy
# See available command line options # See available command line options
@ -27,33 +39,67 @@ make lc-proxy
``` ```
### Important command line options ### Run the Nimbus Light Client Proxy
Most of command line options have reasonable defaults. There are two options which
needs to be explicitly configured by user.
`--trusted-block-root` - option necessary to initialize the consensus light client. Two options need to be explicitly configured by the user:
The trusted block should be within the weak subjectivity period,
and its root should be from a finalized Checkpoint.
`--web3-url` - as the proxy does not have any storage, it needs to know an endpoint which * `--trusted-block-root`: The consensus light client starts syncing from a trusted block. This trusted block should be somewhat recent ([~1-2 weeks](https://github.com/ethereum/consensus-specs/blob/dev/specs/phase0/weak-subjectivity.md)) and needs to be configured each time when starting the Nimbus Light Client Proxy.
will provide all the requested data. This can either be a known full node, or
an external provider like [Alchemy](https://www.alchemy.com/).
First requirement for the external provider is that it must support the standard Ethereum JSON RPC Execution API, and specifically * `--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
it MUST also support the [eth_getProof](https://eips.ethereum.org/EIPS/eip-1186) call. [Alchemy](https://www.alchemy.com/).
A first requirement for the web3 data provider is that it must support the standard Ethereum JSON RPC Execution API, including the [eth_getProof](https://eips.ethereum.org/EIPS/eip-1186) call.
The latter is necessary to validate the provided data against the light client. The latter is necessary to validate the provided data against the light client.
The second requirement is that data served from provider needs to be consistent with A second requirement is that data served from provider needs to match with
the configured light client network. By default the light client proxy is configured 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.
to work on mainnet. In this case, 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 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 light received chain id with the one configured locally. If this validation fails, the Nimbus Light
client proxy process will quit. Client Proxy will quit.
[Detailed document](./docs/metamask_configuration.md) showing how to configure the proxy and pair it with > Note: Infura currently does not support the `eth_getProof` call.
MetaMask.
### Update and rebuild light client proxy #### 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).
```sh
curl -s "http://localhost:5052/eth/v1/beacon/headers/finalized" | \
jq -r '.data.root'
```
* Trusted provider, e.g. Beaconcha.in:
On the [beaconcha.in](https://beaconcha.in) website ([Goerli](https://prater.beaconcha.in)), 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):
```bash
# 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](./docs/metamask_configuration.md) 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
```bash ```bash
# From the nimbus-eth1 repository # From the nimbus-eth1 repository
git pull git pull
@ -63,7 +109,7 @@ make update
make lc-proxy make lc-proxy
``` ```
### Run light client proxy test suite ### Run the Nimbus Light Client Proxy test suite
```bash ```bash
# From the nimbus-eth1 repository # From the nimbus-eth1 repository
make lc-proxy-test make lc-proxy-test
@ -99,5 +145,3 @@ or
* Apache License, Version 2.0, ([LICENSE-APACHEv2](../LICENSE-APACHEv2) or http://www.apache.org/licenses/LICENSE-2.0) * Apache License, Version 2.0, ([LICENSE-APACHEv2](../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. at your option. These files may not be copied, modified, or distributed except according to those terms.

59
lc_proxy/docs/metamask_configuration.md
View File

@ -1,38 +1,35 @@
# MetaMask configuration with Alchemy provider # MetaMask configuration with Alchemy provider
This documents shows how to build and start light client proxy on Goerli This document explains how to configure the proxy, and how to configure MetaMask
network and pair it with the MetaMask browser extension. to make use of the proxy.
### 1. Build light client proxy ### 1. Building the Nimbus Light Client Proxy
First build light client proxy as explained [here](../README.md#Build-light-client-proxy). First build the Nimbus Light Client Proxy as explained [here](../README.md#Build-light-client-proxy).
### 2. Configuring and running light client proxy ### 2. Configuring and running the Nimbus Light Client Proxy
To run the binary built in previous step with Goerli config and using Alchemy data To start the proxy for the Goerli network, run the following command (inserting your own `TRUSTED_BLOCK_ROOT` and Alchemy `API_KEY`):
provider, run:
```bash ```bash
# From the nimbus-eth1 repository # From the nimbus-eth1 repository
./build/lc_proxy --trusted-block-root:TrustedBlockRoot --web3-url="wss://eth-goerli.g.alchemy.com/v2/ApiKey" --network=goerli TRUSTED_BLOCK_ROOT=0x1234567890123456789012345678901234567890123456789012345678901234 # Replace this
API_KEY=abcd # Replace this
./build/lc_proxy \
--network=goerli \
--trusted-block-root=${TRUSTED_BLOCK_ROOT} \
--web3-url="wss://eth-goerli.g.alchemy.com/v2/${API_KEY}"
``` ```
`ApiKey`: personal API key assigned by Alchemy
`TrustedBlockRoot`: Trusted block root, from which the consensus light client will After startup, the Nimbus Light Client Proxy will start looking for suitable peers in the network,
start synchronization i.e peers which serve consensus light client data, and will then start syncing.
This command also starts an HTTP server with address `http://127.0.0.1:8545` to listen
for incoming JSON RPC requests.
After startup, light client will start looking for suitable peers in the network,
i.e peers which serve light client data, and will then start syncing.
During syncing most of the RPC endpoints will be inactive During syncing most of the RPC endpoints will be inactive
and will fail to respond to queries. This happens because the light client proxy can't verify responses and will fail to respond to queries. This happens because the proxy cannot verify responses
from the data provider until the consensus light client is in sync with the consensus chain. from the data provider until the consensus light client is in sync with the consensus chain.
When the light client is in sync, the following line should be visible in the logs: When the consensus light client is in sync, the following line should be visible in the logs:
```bash ```bash
NOT 2022-09-29 10:06:15.974+02:00 New LC optimistic block opt=81de61ec:3994230 wallSlot=3994231 NOT 2022-09-29 10:06:15.974+02:00 New LC optimistic block opt=81de61ec:3994230 wallSlot=3994231
@ -40,23 +37,23 @@ NOT 2022-09-29 10:06:15.974+02:00 New LC optimistic block opt
After receiving the first optimistic block, the proxy is ready to be used with MetaMask. After receiving the first optimistic block, the proxy is ready to be used with MetaMask.
### 3. Configuring MetaMask extension to use custom network ### 3. Configuring MetaMask extension to use a custom network
To add custom network in MetaMask browser extension: To add custom network in MetaMask browser extension:
1. Go to `settings` 1. Go to MetaMask `settings`.
2. In `settings`, go to `networks` tab 2. In `settings`, go to `networks` tab.
3. Click on the `Add a network` button. 3. Click on the `Add a network` button.
4. The most important fields when adding a new network are `New RPC URL` and `Chain ID`. 4. Click on `Add a network manually`.
`New RPC URL` should be configured to point to the HTTP server started with proxy. In this 5. Type a Network name of choice, e.g. "Trusted Goerli".
example it will be `http://127.0.0.1:8545`. `Chain ID` should be set to the chain id of The `New RPC URL` field must be configured to point to the HTTP server of the proxy. In this
the network used by proxy. The chain id for Goerli is `5`. example it will be `http://127.0.0.1:8545`. The `Chain ID` field must be set to the chain id of
the network used by the proxy. The chain id for Goerli is `5`.
If everyting went smooth there should be new network in `Networks` drop down menu. If everything went smooth there should be a new network in `Networks` drop down menu.
After switching to this network it should be possible to create new accounts, and After switching to this network it should be possible to create new accounts, and
perform transfers between them. perform transfers between them.
NOTE: Currently when adding a custom network with a chain id which already exists in the MetaMask > Note: Currently, adding a custom network with a chain id which already exists in the MetaMask
configuration, MetaMask will highlight this as an error. This should be ignored configuration will be highlighted as an error. This should be ignored
as this is really a warning, and it is a known [bug](https://github.com/MetaMask/metamask-extension/issues/13249) as this should be rather a warning, and is a known [bug](https://github.com/MetaMask/metamask-extension/issues/13249) in MetaMask.
in MetaMask.