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

Add docs to lc proxy (#1248) 

* Add docs to lc proxy
This commit is contained in:
KonradStaniec 2022-09-30 12:56:16 +02:00 committed by GitHub
parent eca5882238
commit 94ec3349a4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 163 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

102
lc_proxy/README.md
View File

@ -1,3 +1,103 @@
# Light Client Proxy # Light Client Proxy
Wip [![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)
[![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.
### Build light client proxy
```bash
git clone git@github.com:status-im/nimbus-eth1.git
cd nimbus-eth1
make lc-proxy
# See available command line options
./build/lc_proxy --help
```
### Important command line options
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.
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
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
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.
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.
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.
[Detailed document](./docs/metamask_configuration.md) showing how to configure the proxy and pair it with
MetaMask.
### Update and rebuild light client proxy
```bash
# From the nimbus-eth1 repository
git pull
# To bring the git submodules up to date
make update
make lc-proxy
```
### Run light client proxy test suite
```bash
# From the nimbus-eth1 repository
make lc-proxy-test
```
### Windows support
Follow the steps outlined [here](../README.md#windows) 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.:
```bash
# 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](../LICENSE-MIT) or http://opensource.org/licenses/MIT
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.

62
lc_proxy/docs/metamask_configuration.md Normal file
View File

@ -0,0 +1,62 @@
# 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.
### 1. Build light client proxy
First build light client proxy as explained [here](../README.md#Build-light-client-proxy).
### 2. Configuring and running light client proxy
To run the binary built in previous step with Goerli config and using Alchemy data
provider, run:
```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
```
`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.
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
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:
```bash
NOT 2022-09-29 10:06:15.974+02:00 New LC optimistic block opt=81de61ec:3994230 wallSlot=3994231
```
After receiving the first optimistic block, the proxy is ready to be used with MetaMask.
### 3. Configuring MetaMask extension to use custom network
To add custom network in MetaMask browser extension:
1. Go to `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`.
If everyting went smooth there should be 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.