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

110
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)
[![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)
@ -8,18 +8,30 @@
[![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)
## Introduction
This folder holds the development of light client proxy. Light client proxy
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.
The Nimbus Light Client Proxy is a very efficient light client for the Ethereum
PoS network.
### 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
# 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
@ -27,33 +39,67 @@ make lc-proxy
```
### Important command line options
Most of command line options have reasonable defaults. There are two options which
needs to be explicitly configured by user.
### Run the Nimbus Light Client Proxy
`--trusted-block-root` - option necessary to initialize the consensus light client.
The trusted block should be within the weak subjectivity period,
and its root should be from a finalized Checkpoint.
Two options need to be explicitly configured by the user:
`--web3-url` - as the proxy does not have any storage, it needs to know an endpoint which
will provide all the requested data. This can either be a known full node, or
an external provider like [Alchemy](https://www.alchemy.com/).
* `--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.
First requirement for the external provider is that it must support the standard Ethereum JSON RPC Execution API, and specifically
it MUST also support the [eth_getProof](https://eips.ethereum.org/EIPS/eip-1186) call.
The latter is necessary to validate the provided data against the light client.
* `--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](https://www.alchemy.com/).
The second requirement is that data served from provider needs to be consistent with
the configured light client network. By default the light client proxy is configured
to work on mainnet. In this case, the configured provider needs to serve mainnet data.
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.
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 light
client proxy process will quit.
received chain id with the one configured locally. If this validation fails, the Nimbus Light
Client Proxy will quit.
[Detailed document](./docs/metamask_configuration.md) showing how to configure the proxy and pair it with
MetaMask.
> Note: Infura currently does not support the `eth_getProof` call.
### 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
# From the nimbus-eth1 repository
git pull
@ -63,7 +109,7 @@ make update
make lc-proxy
```
### Run light client proxy test suite
### Run the Nimbus Light Client Proxy test suite
```bash
# From the nimbus-eth1 repository
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)
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
This documents shows how to build and start light client proxy on Goerli
network and pair it with the MetaMask browser extension.
This document explains how to configure the proxy, and how to configure MetaMask
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
provider, run:
To start the proxy for the Goerli network, run the following command (inserting your own `TRUSTED_BLOCK_ROOT` and Alchemy `API_KEY`):
```bash
# 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
start synchronization
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.
After startup, the Nimbus Light Client Proxy will start looking for suitable peers in the network,
i.e peers which serve consensus light client data, and will then start syncing.
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.
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
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.
### 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:
1. Go to `settings`
2. In `settings`, go to `networks` tab
1. Go to MetaMask `settings`.
2. In `settings`, go to `networks` tab.
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`.
`New RPC URL` should be configured to point to the HTTP server started with proxy. In this
example it will be `http://127.0.0.1:8545`. `Chain ID` should be set to the chain id of
the network used by proxy. The chain id for Goerli is `5`.
4. Click on `Add a network manually`.
5. Type a Network name of choice, e.g. "Trusted Goerli".
The `New RPC URL` field must be configured to point to the HTTP server of the proxy. In this
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
perform transfers between them.
NOTE: Currently when 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
as this is really a warning, and it is a known [bug](https://github.com/MetaMask/metamask-extension/issues/13249)
in MetaMask.
> Note: Currently, adding a custom network with a chain id which already exists in the MetaMask
configuration will be highlighted as an error. This should be ignored
as this should be rather a warning, and is a known [bug](https://github.com/MetaMask/metamask-extension/issues/13249) in MetaMask.