diff --git a/lc_proxy/README.md b/lc_proxy/README.md index 7f5b9a346..5ddf0263c 100644 --- a/lc_proxy/README.md +++ b/lc_proxy/README.md @@ -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/" +``` + +### 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. - - diff --git a/lc_proxy/docs/metamask_configuration.md b/lc_proxy/docs/metamask_configuration.md index 40b36f147..8dc7afa8f 100644 --- a/lc_proxy/docs/metamask_configuration.md +++ b/lc_proxy/docs/metamask_configuration.md @@ -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.