nimbus-eth1/nimbus_verified_proxy
Jordan Hrycaj 221e6c9e2f
Unified database frontend integration (#1670)
* Nimbus folder environment update

details:
* Integrated `CoreDbRef` for the sources in the `nimbus` sub-folder.
* The `nimbus` program does not compile yet as it needs the updates
  in the parallel `stateless` sub-folder.

* Stateless environment update

details:
* Integrated `CoreDbRef` for the sources in the `stateless` sub-folder.
* The `nimbus` program compiles now.

* Premix environment update

details:
* Integrated `CoreDbRef` for the sources in the `premix` sub-folder.

* Fluffy environment update

details:
* Integrated `CoreDbRef` for the sources in the `fluffy` sub-folder.

* Tools environment update

details:
* Integrated `CoreDbRef` for the sources in the `tools` sub-folder.

* Nodocker environment update

details:
* Integrated `CoreDbRef` for the sources in the
  `hive_integration/nodocker` sub-folder.

* Tests environment update

details:
* Integrated `CoreDbRef` for the sources in the `tests` sub-folder.
* The unit tests compile and run cleanly now.

* Generalise `CoreDbRef` to any `select_backend` supported database

why:
  Generalisation was just missed due to overcoming some compiler oddity
  which was tied to rocksdb for testing.

* Suppress compiler warning for `newChainDB()`

why:
  Warning was added to this function which must be wrapped so that
  any `CatchableError` is re-raised as `Defect`.

* Split off persistent `CoreDbRef` constructor into separate file

why:
  This allows to compile a memory only database version without linking
  the backend library.

* Use memory `CoreDbRef` database by default

detail:
 Persistent DB constructor needs to import `db/core_db/persistent

why:
 Most tests use memory DB anyway. This avoids linking `-lrocksdb` or
 any other backend by default.

* fix `toLegacyBackend()` availability check

why:
  got garbled after memory/persistent split.

* Clarify raw access to MPT for snap sync handler

why:
  Logically, `kvt` is not the raw access for the hexary trie (although
  this holds for the legacy database)
2023-08-04 12:10:09 +01:00
..
docs Rename lc_proxy to nimbus_verified_proxy (#1321) 2022-11-23 17:11:38 +01:00
rpc Unified database frontend integration (#1670) 2023-08-04 12:10:09 +01:00
tests Reduce Nim 1.6 compiler warnings & hints 2023-01-31 13:38:08 +01:00
README.md Rename lc_proxy to nimbus_verified_proxy (#1321) 2022-11-23 17:11:38 +01:00
block_cache.nim Reduce Nim 1.6 compiler warnings & hints 2023-01-31 13:38:08 +01:00
nim.cfg Compile Fluffy tests and fluffy beacon LC tests together (#1633) 2023-07-06 18:06:44 +02:00
nimbus_verified_proxy.nim bump submodules 2023-06-07 18:12:02 +07:00
nimbus_verified_proxy_conf.nim Unified database frontend integration (#1670) 2023-08-04 12:10:09 +01:00
validate_proof.nim Reduce Nim 1.6 compiler warnings & hints 2023-01-31 13:38:08 +01:00

README.md

Nimbus Verified Proxy

Nimbus Verified Proxy CI Stability: experimental License: Apache License: MIT

Discord: Nimbus Status: #nimbus-general

The Nimbus Verified 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 Verified 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 Verified 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 nimbus_verified_proxy

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

Run the Nimbus Verified 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 Verified 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 Verified Proxy. By default the 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 Verified 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/nimbus_verified_proxy \
    --network=goerli \
    --trusted-block-root=${TRUSTED_BLOCK_ROOT} \
    --web3-url="wss://eth-goerli.g.alchemy.com/v2/<ApiKey>"

Using the Nimbus Verified Proxy with existing Wallets

The Nimbus Verified 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 Verified 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 Verified Proxy

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

make nimbus_verified_proxy

Run the Nimbus Verified Proxy test suite

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

Windows support

Follow the steps outlined here to build Nimbus Verified 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

or

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