mirror of
https://github.com/status-im/nimbus-eth2.git
synced 2025-02-07 04:04:33 +00:00
doc updates (#4314)
* optimise index / landing page real estate, add feature list * fee recipient in quickstart * recommend http over websockets (fewer command line options needed) * simplify PBS, fee recipient docs * add VC role / sentry node docs (#4140) * Update docs/the_nimbus_book/src/rest-api.md Co-authored-by: tersec <tersec@users.noreply.github.com>
This commit is contained in:
Jacek Sieka
GitHub
parent
367a13df34
commit
1b90f65f7b
@ -39,7 +39,6 @@ nav:
|
||||
- About:
|
||||
- 'index.md'
|
||||
- 'philosophy.md'
|
||||
- 'preparation.md'
|
||||
|
||||
- Getting started:
|
||||
- 'quick-start.md'
|
||||
@ -83,29 +82,33 @@ nav:
|
||||
- 'prater.md'
|
||||
|
||||
- Security:
|
||||
- 'preparation.md'
|
||||
- 'security_issues.md'
|
||||
- 'audit.md'
|
||||
- 'distribution_internals.md'
|
||||
|
||||
- Reference:
|
||||
- 'hardware.md'
|
||||
- 'options.md'
|
||||
- 'networking.md'
|
||||
- 'optimistic-sync.md'
|
||||
- 'logging.md'
|
||||
- 'validator-monitor.md'
|
||||
- 'attestation-performance.md'
|
||||
- 'rest-api.md'
|
||||
- 'keymanager-api.md'
|
||||
- 'data-dir.md'
|
||||
- 'era-store.md'
|
||||
- Advanced options:
|
||||
- 'options.md'
|
||||
- 'networking.md'
|
||||
- 'optimistic-sync.md'
|
||||
- 'light-client-data.md'
|
||||
- 'logging.md'
|
||||
- 'validator-client-options.md'
|
||||
- 'validator-monitor.md'
|
||||
- "REST API:s":
|
||||
- 'rest-api.md'
|
||||
- 'keymanager-api.md'
|
||||
- Storage:
|
||||
- 'data-dir.md'
|
||||
- 'era-store.md'
|
||||
- 'migration-options.md'
|
||||
- 'light-client-data.md'
|
||||
- 'attestation-performance.md'
|
||||
- 'troubleshooting.md'
|
||||
- 'faq.md'
|
||||
- 'developers.md'
|
||||
- 'resources.md'
|
||||
- 'faq.md'
|
||||
- 'api.md'
|
||||
- 'contribute.md'
|
||||
|
||||
- Downloads:
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
# Attestation performance analysis
|
||||
# Attestation performance
|
||||
|
||||
`ncli_db validatorPerf` is an advanced tool that helps you analyze the performance of your validator over time.
|
||||
|
||||
|
||||
@ -1,22 +1,28 @@
|
||||
# Start validating
|
||||
|
||||
Once your keys have been [imported](./keys.md), it is time to restart the beacon node and start validating!
|
||||
Once your keys have been [imported](./keys.md), it is time to configure a [fee recipient](./suggested-fee-recipient.md) and restart the beacon node to start validating!
|
||||
|
||||
## (Re)start the node
|
||||
## Steps
|
||||
|
||||
Press `Ctrl-c` to stop the beacon node if it's running, then use the same command as before to run it again:
|
||||
### 1. Choose a fee recipient
|
||||
|
||||
The [fee recipient](./suggested-fee-recipient.md) is an Ethereum address that receives transaction fees from the blocks that your validators produce. You can set up a separate address or reuse the address from which you funded your deposits.
|
||||
|
||||
### 2. (Re)start the node
|
||||
|
||||
Press `Ctrl-c` to stop the beacon node if it's running, then use the same command [as before]() to run it again, this time adding the `--suggested-fee-recipient` option in addition to `--web3-url`:
|
||||
|
||||
=== "Mainnet"
|
||||
```sh
|
||||
./run-mainnet-beacon-node.sh
|
||||
./run-mainnet-beacon-node.sh --web3-url=http://127.0.0.1:8551 --suggested-fee-recipient=0x...
|
||||
```
|
||||
|
||||
=== "Prater"
|
||||
```sh
|
||||
./run-prater-beacon-node.sh
|
||||
./run-prater-beacon-node.sh --web3-url=http://127.0.0.1:8551 --suggested-fee-recipient=0x...
|
||||
```
|
||||
|
||||
## Check the logs
|
||||
### 3. Check the logs
|
||||
|
||||
Your beacon node will launch and connect your validator to the beacon chain network. To check that keys were imported correctly, look for `Local validator attached` in the logs:
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
To make a deposit, you will need to generate keys then submit a deposit transaction to the execution chain.
|
||||
|
||||
!!! tip
|
||||
!!! tip "Launchpad"
|
||||
The process of setting up a validator is also documented at the Ethereum launchpad site:
|
||||
|
||||
* [Mainnet](https://launchpad.ethereum.org/)
|
||||
@ -11,7 +11,9 @@ To make a deposit, you will need to generate keys then submit a deposit transact
|
||||
!!! tip
|
||||
Use Prater to stress test / future proof your set up against peak mainnet load. See [here](./prater.md) for all you need to know
|
||||
|
||||
## Download the deposit tool
|
||||
## Steps
|
||||
|
||||
### 1. Download the deposit tool
|
||||
|
||||
Start by downloading and unpacking the [deposit tool](https://github.com/ethereum/staking-deposit-cli/releases/latest) provided by the Ethereum Foundation:
|
||||
|
||||
@ -26,14 +28,14 @@ wget https://github.com/ethereum/staking-deposit-cli/releases/download/v2.2.0/st
|
||||
tar xvf staking_deposit-cli-9ab0b05-linux-amd64.tar.gz --strip-components 2
|
||||
```
|
||||
|
||||
## Generate keys
|
||||
### 2. Generate keys
|
||||
|
||||
!!! tip
|
||||
!!! tip "Live image"
|
||||
You can increase the security of this process by downloading a [Live linux image](https://ubuntu.com/tutorials/try-ubuntu-before-you-install). To do so, copy `deposit` to a USB stick, boot into the live image, and run the tool from inside the image. Make sure you **don't** enable Wifi and unplug any Ethernet cables when using this process.
|
||||
|
||||
The deposit tool generates a seed phrase, and uses this to create validator and withdrawal keys.
|
||||
|
||||
!!! danger
|
||||
!!! danger "Seed phrase"
|
||||
If you lose you seed phrase and your withdrawal key, your funds will be lost forever!
|
||||
|
||||
=== "Mainnet"
|
||||
@ -48,7 +50,7 @@ The deposit tool generates a seed phrase, and uses this to create validator and
|
||||
./deposit new-mnemonic --chain prater
|
||||
```
|
||||
|
||||
## Make the deposit
|
||||
### 3. Make the deposit
|
||||
|
||||
Once created, the keys are used to create a deposit transaction on the Ethereum execution chain. Follow the instructions at https://launchpad.ethereum.org/en/upload-deposit-data to upload the deposit data.
|
||||
|
||||
|
||||
@ -4,6 +4,12 @@ This page contains tips and tricks for developers, further resources, along with
|
||||
|
||||
Before building Nimbus for the first time, make sure to install the [prerequisites](./install.md).
|
||||
|
||||
## Helpful resources
|
||||
|
||||
* [Ethereum consensus spec](https://github.com/ethereum/consensus-specs/)
|
||||
* [Ben Edgington's annotated spec](hhttps://eth2book.info/bellatrix/)
|
||||
* [Vitalik's annotated spec](https://github.com/ethereum/annotated-spec/blob/master/phase0/beacon-chain.md)
|
||||
|
||||
## Code style
|
||||
|
||||
The code follows the [Status Nim Style Guide](https://status-im.github.io/nim-style-guide/).
|
||||
|
||||
@ -3,9 +3,9 @@
|
||||
!!! warning
|
||||
The light client is currently in BETA and details around running it may change.
|
||||
|
||||
The Nimbus Light Client is a light-weight alternative to running a full beacon node, when setting up an Ethereum execution client for read-only use cases after the merge.
|
||||
The Nimbus Light Client is a light-weight alternative to running a full beacon node, when you're not planning on becoming a validator but still want to run an Ethereum execution layer client.
|
||||
|
||||
Execution layer (EL) clients provide the [web3 API](https://ethereum.github.io/execution-apis/api-documentation/) to expose information stored on the Ethereum blockchain. Post-merge 🐼, EL clients can no longer run standalone and require an external component to determine the latest state to sync to.
|
||||
Execution layer (EL) clients provide the [Web3 API](https://ethereum.github.io/execution-apis/api-documentation/) to expose information stored on the Ethereum blockchain. Since the merge 🐼, execution clients can no longer run standalone.
|
||||
|
||||
## Comparison
|
||||
|
||||
@ -69,12 +69,12 @@ In addition to the [regular instructions](./eth1.md) to run an EL client, the JW
|
||||
|
||||
=== "Mainnet"
|
||||
```sh
|
||||
geth --ws --authrpc.jwtsecret="$HOME/jwtsecret"
|
||||
geth --authrpc.jwtsecret="$HOME/jwtsecret"
|
||||
```
|
||||
|
||||
=== "Goerli"
|
||||
```sh
|
||||
geth --goerli --ws --authrpc.jwtsecret="$HOME/jwtsecret"
|
||||
geth --goerli --authrpc.jwtsecret="$HOME/jwtsecret"
|
||||
```
|
||||
|
||||
=== "Nethermind"
|
||||
@ -123,7 +123,7 @@ To start the light client, run the following commands (inserting your own truste
|
||||
```sh
|
||||
TRUSTED_BLOCK_ROOT=0x1234567890123456789012345678901234567890123456789012345678901234
|
||||
build/nimbus_light_client \
|
||||
--web3-url=ws://127.0.0.1:8551 --jwt-secret="$HOME/jwtsecret" \
|
||||
--web3-url=http://127.0.0.1:8551 --jwt-secret="$HOME/jwtsecret" \
|
||||
--trusted-block-root=$TRUSTED_BLOCK_ROOT
|
||||
```
|
||||
|
||||
@ -131,7 +131,7 @@ To start the light client, run the following commands (inserting your own truste
|
||||
```sh
|
||||
TRUSTED_BLOCK_ROOT=0x1234567890123456789012345678901234567890123456789012345678901234
|
||||
build/nimbus_light_client --network=goerli \
|
||||
--web3-url=ws://127.0.0.1:8551 --jwt-secret="$HOME/jwtsecret" \
|
||||
--web3-url=http://127.0.0.1:8551 --jwt-secret="$HOME/jwtsecret" \
|
||||
--trusted-block-root=$TRUSTED_BLOCK_ROOT
|
||||
```
|
||||
|
||||
|
||||
@ -32,17 +32,14 @@ Select an execution client and install it, configuring it such that that WebSock
|
||||
|
||||
=== "Mainnet"
|
||||
```
|
||||
geth --ws --authrpc.addr localhost --authrpc.port 8551 --authrpc.vhosts localhost --authrpc.jwtsecret /tmp/jwtsecret
|
||||
geth --authrpc.addr localhost --authrpc.port 8551 --authrpc.vhosts localhost --authrpc.jwtsecret /tmp/jwtsecret
|
||||
```
|
||||
|
||||
=== "Goerli"
|
||||
```
|
||||
geth --goerli --ws --authrpc.addr localhost --authrpc.port 8551 --authrpc.vhosts localhost --authrpc.jwtsecret /tmp/jwtsecret
|
||||
geth --goerli --authrpc.addr localhost --authrpc.port 8551 --authrpc.vhosts localhost --authrpc.jwtsecret /tmp/jwtsecret
|
||||
```
|
||||
|
||||
!!! note
|
||||
The `--ws` flag allows Nimbus to connect using WebSockets.
|
||||
|
||||
#### 3. Leave Geth running
|
||||
|
||||
Let it syns - it may take anywhere between a few hours and a couple of days.
|
||||
@ -56,25 +53,25 @@ Select an execution client and install it, configuring it such that that WebSock
|
||||
INFO [05-29|01:16:14] Imported new chain segment blocks=1 txs=11 mgas=1.135 elapsed=22.281ms mgasps=50.943 number=3785444 hash=277bb9…623d8c
|
||||
```
|
||||
|
||||
Geth accepts connections from the localhost interface (`127.0.0.1`), with default authenticated RPC port `8551`. This means that your default Web3 provider URL should be: `ws://127.0.0.1:8551`
|
||||
Geth accepts connections from the localhost interface (`127.0.0.1`), with default authenticated RPC port `8551`. This means that your default Web3 provider URL should be: `http://127.0.0.1:8551`
|
||||
|
||||
=== "Nethermind"
|
||||
|
||||
See the [Getting started](https://docs.nethermind.io/nethermind/first-steps-with-nethermind/getting-started) guide to set up Nethermind.
|
||||
|
||||
Make sure to enable the [JSON-RPC](https://docs.nethermind.io/nethermind/first-steps-with-nethermind/running-nethermind-post-merge#jsonrpc-configuration-module) interface over WebSockets, and pass `--JsonRpc.JwtSecretFile=/tmp/jwtsecret` to select a JWT secret file location.
|
||||
Make sure to enable the [JSON-RPC](https://docs.nethermind.io/nethermind/first-steps-with-nethermind/running-nethermind-post-merge#jsonrpc-configuration-module) interface and pass `--JsonRpc.JwtSecretFile=/tmp/jwtsecret` to select a JWT secret file location.
|
||||
|
||||
=== "Besu"
|
||||
|
||||
See the [Besu documentation](https://besu.hyperledger.org/en/stable/) for instructions on setting up Besu.
|
||||
|
||||
Make sure to enable the [JSON-RPC](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API/) WebSocket interface and store the JWT token in `/tmp/jwtsecret`.
|
||||
Make sure to enable the [JSON-RPC](https://besu.hyperledger.org/en/stable/HowTo/Interact/APIs/Using-JSON-RPC-API/) interface and store the JWT token in `/tmp/jwtsecret`.
|
||||
|
||||
=== "Erigon"
|
||||
|
||||
See the [Erigon README](https://github.com/ledgerwatch/erigon#getting-started) for instructions on setting up Erigon.
|
||||
|
||||
Make sure to enable the [JSON-RPC](https://github.com/ledgerwatch/erigon#beacon-chain-consensus-layer) WebSocket interface and use `--authrpc.jwtsecret=/tmp/jwtsecret` to set a path to the JWT token file.
|
||||
Make sure to enable the [JSON-RPC](https://github.com/ledgerwatch/erigon#beacon-chain-consensus-layer) interface and use `--authrpc.jwtsecret=/tmp/jwtsecret` to set a path to the JWT token file.
|
||||
|
||||
### 2. Leave the execution client running
|
||||
|
||||
@ -91,23 +88,23 @@ Once started, the execution client will create a file containing a JWT secret to
|
||||
=== "Mainnet"
|
||||
```sh
|
||||
./run-mainnet-beacon-node.sh \
|
||||
--web3-url=ws://127.0.0.1:8551 \
|
||||
--web3-url=http://127.0.0.1:8551 \
|
||||
--jwt-secret=/tmp/jwtsecret
|
||||
```
|
||||
|
||||
=== "Prater"
|
||||
```sh
|
||||
./run-prater-beacon-node.sh \
|
||||
--web3-url=ws://127.0.0.1:8551 \
|
||||
--web3-url=http://127.0.0.1:8551 \
|
||||
--jwt-secret=/tmp/jwtsecret
|
||||
```
|
||||
|
||||
!!! tip
|
||||
!!! tip "Multiple execution clients"
|
||||
You can pass one or more `--web3-url` parameters to the node as long as they share JWT secret. Any additional web3 url:s will be used for backup, should the first one become unavailable:
|
||||
|
||||
```sh
|
||||
./run-mainnet-beacon-node.sh \
|
||||
--web3-url=ws://127.0.0.1:8551 \
|
||||
--web3-url=http://other:8551 \
|
||||
--web3-url=http://127.0.0.1:8551 \
|
||||
--web3-url=ws://other:8551 \
|
||||
--jwt-secret=/tmp/jwtsecret
|
||||
```
|
||||
|
||||
@ -1,32 +1,47 @@
|
||||
# Set up block builders / MEV
|
||||
|
||||
[Maximal extractable value](https://ethereum.org/en/developers/docs/mev/) involves consensus clients contacting an external block builder which might maximize profit or some other defined metric in ways hindered for a purely local consensus and execution client setup. This external builder network uses the [builder API](https://ethereum.github.io/builder-specs/) which consensus clients use to access external block builder bundles found by searchers. In exchange, such searchers and builders might choose to retain some of the profit gained from such bundles. A builder API relay provides access to multiple searchers via a single URL.
|
||||
Nimbus supports outsourcing block production to an external block builder, thus presenting the opportunity to capture [Maximal Extractable Value](https://ethereum.org/en/developers/docs/mev/) (MEV).
|
||||
|
||||
Nimbus supports this API to access these external block builders. If one is configured, the block production flow becomes modified:
|
||||
When external block building is enabled, the beacon node connects to a service using the [builder API](https://ethereum.github.io/builder-specs/) with the execution client acting as a fallback.
|
||||
|
||||
1. attempt to use the specified external block builder relay or builder to create an execution payload
|
||||
2. if the external block builder builder or relay doesn't function, and Nimbus has not signed a blinded beacon block, then fall back to existing local execution client to produce a block
|
||||
Setting up external block building typically involves running an additional service on your server which is configured to choose the best block from one or more relays and having the beacon node connect to this service.
|
||||
|
||||
There exists a failure mode, intrinsic to the builder API, wherein the consensus client has signed a blinded proposal and therefore even if the external block builder relay or builder doesn't provide a full block, a consensus client such as Nimbus cannot safely proceed with step 2 and fall back on its local execution client.
|
||||
!!! warning
|
||||
External block builders introduce additional risk to the block building process which may cause loss of rewards.
|
||||
|
||||
In particular, once Nimbus has signed the block header proposed by the external builder, the execution client can no longer be used as fallback and the external builder is trusted to complete the building process.
|
||||
|
||||
!!! note
|
||||
By default, [priority and maximum gas fees](https://eips.ethereum.org/EIPS/eip-1559#abstract) determine transaction inclusion in blocks, but external block builders may use other strategies for transaction selection, which might involve regulatory constraints and extracted value. For further information, check the documentation of the block builder.
|
||||
By default, [priority and maximum gas fees](https://eips.ethereum.org/EIPS/eip-1559#abstract) determine transaction inclusion in blocks.
|
||||
|
||||
## Command line option
|
||||
External block builders may use other strategies for transaction selection, including regulatory constraints and extracted value. For further information, check the documentation of the block builder.
|
||||
|
||||
=== "Mainnet"
|
||||
## Command line
|
||||
|
||||
External block building is must be enabled on both beacon node and [validator client](./validator-client.md) using the `--payload-builder=true` flag.
|
||||
|
||||
Additionally, the URL of the service exposing the [builder API](https://ethereum.github.io/builder-specs/) must be provided to the beacon node:
|
||||
|
||||
=== "Mainnet Beacon Node"
|
||||
```sh
|
||||
./run-mainnet-beacon-node.sh --payload-builder=true --payload-builder-url=https://${HOST}:${PORT}/
|
||||
```
|
||||
|
||||
=== "Prater"
|
||||
=== "Prater Beacon Node"
|
||||
```sh
|
||||
./run-prater-beacon-node.sh --payload-builder=true --payload-builder-url=https://${HOST}:${PORT}/
|
||||
```
|
||||
|
||||
=== "Validator Client"
|
||||
```sh
|
||||
build/nimbus_validator_client --payload-builder=true
|
||||
```
|
||||
|
||||
## Useful resources
|
||||
|
||||
- [MEV relay list](https://github.com/remyroy/ethstaker/blob/main/MEV-relay-list.md)
|
||||
- [EthStaker MEV setup guide](https://github.com/eth-educators/ethstaker-guides/blob/main/prepare-for-the-merge.md#choosing-and-configuring-an-mev-solution)
|
||||
|
||||
- [EthStaker MEV relay list](https://ethstaker.cc/mev-relay-list/)
|
||||
|
||||
- [Mainnet Relay Overview](https://beaconcha.in/relays)
|
||||
|
||||
|
||||
@ -2,6 +2,8 @@
|
||||
|
||||
You can use your node's graffiti flag to include a short text in the blocks that your node creates. You will be able to see it using the block explorer.
|
||||
|
||||
## Command line
|
||||
|
||||
=== "Mainnet"
|
||||
```sh
|
||||
./run-mainnet-beacon-node.sh --graffiti="<YOUR_WORDS>"
|
||||
|
||||
@ -1,33 +1,25 @@
|
||||
# The Nimbus Guide
|
||||
|
||||
!!! note ""
|
||||
If you're eager to get started, check out our [quickstart guide](./quick-start.md).
|
||||
Eager to get started? The [quickstart guide](./quick-start.md) is for you.
|
||||
|
||||
Coming from a different client? Check out the [migration guide](./migration.md).
|
||||
|
||||
Nimbus is a client for the Ethereum `consensus layer` (eth2) and `execution layer` (eth1) that is [lightweight](https://our.status.im/ethereum-is-green/), [secure](./audit.md) and [easy to use](./run-a-validator.md).
|
||||
|
||||
This book describes the consensus layer client, `nimbus-eth2`, in particular.
|
||||
Nimbus is a client for the Ethereum network that is [lightweight](https://our.status.im/ethereum-is-green/), [secure](./audit.md) and [easy to use](./run-a-validator.md).
|
||||
|
||||
Its efficiency and low resource consumption allows it to perform well on all kinds of systems, ranging from Raspberry Pi's and mobile devices where it contributes to low power consumption and security -- to powerful servers where it leaves resources free to perform other tasks, such as running an [execution node](./eth1.md).
|
||||
|
||||
</br>
|
||||
This book describes the consensus layer client, [`nimbus-eth2`](https://github.com/status-im/nimbus-eth2). A execution client, [nimbus-eth1](https://github.com/status-im/nimbus-eth2), is also under development.
|
||||
|
||||
<blockquote class="twitter-tweet"><p lang="en" dir="ltr">"just because it [Nimbus] is optimized to be minimally resource intensive, doesn't mean you can't run it on a server. It means that when you do run it on a server, it is consuming a lot less resources." <a href="https://t.co/F2sdZouBtD">https://t.co/F2sdZouBtD</a></p>— Nimbus (@ethnimbus) <a href="https://twitter.com/ethnimbus/status/1376836270245154817?ref_src=twsrc%5Etfw">March 30, 2021</a></blockquote> <script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>
|
||||
## Feature highlights
|
||||
|
||||
</br>
|
||||
|
||||
This book explains the ways in which you can use Nimbus to either monitor the beacon chain or become a fully-fledged validator.
|
||||
|
||||
!!! note
|
||||
Staking and becoming a validator on Ethereum requires 32 ETH, a stable high-speed internet connection and an always-on server. Before staking, make sure that you understand the requirements and practice setting up a validator on a testnet. [Pooled staking](https://ethereum.org/en/staking/pools/) and [Staking as a service](https://ethereum.org/en/staking/saas/) are alternative ways to stake in the network. You can also run a Nimbus node without staking.
|
||||
|
||||
## Helpful resources
|
||||
|
||||
- [Ethereum consensus spec](https://github.com/ethereum/consensus-specs/)
|
||||
- [Ben Edgington's annotated spec](https://benjaminion.xyz/eth2-annotated-spec/phase0/beacon-chain/)
|
||||
- [Vitalik's annotated spec](https://github.com/ethereum/annotated-spec/blob/master/phase0/beacon-chain.md)
|
||||
- [Danny Ryan's annotated spec](https://notes.ethereum.org/@djrtwo/Bkn3zpwxB)
|
||||
* [Beacon node](./quick-start.md) with integrated validator client, slashing protection and doppelganger detection
|
||||
* Stand-alone [validator client](./validator-client.md) with [sentry node](./validator-client.md#sentry-node-setup) support
|
||||
* Fast [Beacon](./rest-api.md) and [KeyManager](./keymanager-api.md) API:s with extensions
|
||||
* [Web3Signer](https://docs.web3signer.consensys.net/en/latest/) remote signing
|
||||
* [Validator monitoring](./validator-monitor.md) and [performance analysis](./attestation-performance.md) tooling
|
||||
* [External block builder](./external-block-builder.md) (PBS / mev-boost) support with execution client fallback
|
||||
* [Light consensus client](./el-light-client,md) for running an execution client without a beacon node
|
||||
|
||||
## Get in touch
|
||||
|
||||
|
||||
@ -7,6 +7,9 @@ Having followed the [deposit](./deposit.md) guide, you will have a `validator_ke
|
||||
|
||||
We'll import the signing key of each validator to the [data directory](./data-dir.md) using the `deposits import` command:
|
||||
|
||||
!!! note ""
|
||||
You'll be asked to enter the password you used when creating your keystore(s).
|
||||
|
||||
=== "Mainnet"
|
||||
```sh
|
||||
build/nimbus_beacon_node deposits import --data-dir=build/data/shared_mainnet_0
|
||||
@ -17,8 +20,20 @@ We'll import the signing key of each validator to the [data directory](./data-di
|
||||
build/nimbus_beacon_node deposits import --data-dir=build/data/shared_prater_0
|
||||
```
|
||||
|
||||
!!! warning ""
|
||||
You'll be asked to enter the password you created to encrypt your keystore(s).
|
||||
On success, a message will be printed that your keys have been imported:
|
||||
```
|
||||
NOT 2022-07-19 17:36:37.578+02:00 Keystore imported
|
||||
```
|
||||
|
||||
!!! note ""
|
||||
`NOT` is short for `NOTICE` and not not :)
|
||||
|
||||
After importing keys, it's time to [restart](./connect-eth2.md) the node and check that the keys have been picked up by the beacon node.
|
||||
|
||||
!!! info "All the keys"
|
||||
You can read more about the different types of keys [here](https://blog.ethereum.org/2020/05/21/keys/) - the `deposit import` command will import the **signing key** only.
|
||||
|
||||
## Command line
|
||||
|
||||
If your `validator_keys` folder is stored elsewhere, you can pass its location to the import command:
|
||||
|
||||
@ -38,19 +53,6 @@ If your `validator_keys` folder is stored elsewhere, you can pass its location t
|
||||
|
||||
Replacing `/path/to/keys` with the full pathname of where the `validator_keys` directory is found.
|
||||
|
||||
On success, a message will be printed that your keys have been imported:
|
||||
```
|
||||
NOT 2022-07-19 17:36:37.578+02:00 Keystore imported
|
||||
```
|
||||
|
||||
!!! note ""
|
||||
`NOT` is short for `NOTICE` and not not :)
|
||||
|
||||
After importing keys, it's time to [restart](./connect-eth2.md) the node and check that the keys have been picked up by the beacon node.
|
||||
|
||||
!!! tip
|
||||
You can read more about the different types of keys [here](https://blog.ethereum.org/2020/05/21/keys/) - the `deposit import` command will import the **signing key** only.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If you come across an error, make sure that:
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
# Light client data (advanced)
|
||||
# Light client data
|
||||
|
||||
Nimbus is configured by default to serve data that allows light clients to stay in sync with the Ethereum network. Light client data is imported incrementally and does not affect validator performance. Information about the light client sync protocol can be found in the [Ethereum consensus specs](https://github.com/ethereum/consensus-specs/blob/dev/specs/altair/light-client/sync-protocol.md).
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
# Logging options
|
||||
# Logging
|
||||
|
||||
!!! warning
|
||||
The logging options outlined here are based on a preview feature, and are subject to change
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
# Command line options
|
||||
# Command line
|
||||
|
||||
Command line options allow you to customize the way your beacon node operates.
|
||||
|
||||
@ -138,7 +138,7 @@ Here is an example config file illustrating all of the above:
|
||||
```toml
|
||||
# Comments look like this
|
||||
doppelganger-detection = true
|
||||
web3-url = ["ws://192.168.1.10:8000"]
|
||||
web3-url = ["http://127.0.0.1:8551"]
|
||||
num-threads = 0
|
||||
|
||||
[trustedNodeSync]
|
||||
|
||||
@ -37,10 +37,10 @@ Next, download the [latest release](./binaries.md) and install it by unpacking t
|
||||
mkdir -p nimbus-eth2
|
||||
|
||||
# Download the latest release - replace the link with the latest release on the download page!
|
||||
wget https://github.com/status-im/nimbus-eth2/releases/download/v22.6.1/nimbus-eth2_Linux_amd64_22.6.1_2444e994.tar.gz
|
||||
wget https://github.com/status-im/nimbus-eth2/releases/download/v22.10.1/nimbus-eth2_Linux_amd64_22.10.1_97a1cdc4.tar.gz
|
||||
|
||||
# Unpack the archive into the `nimbus-eth2` directory you just created
|
||||
tar xvf nimbus-eth2_Linux_amd64_22.6.1_2444e994.tar.gz --strip-components 1 -C nimbus-eth2
|
||||
tar xvf nimbus-eth2_Linux_amd64_22.10.1_97a1cdc4.tar.gz --strip-components 1 -C nimbus-eth2
|
||||
```
|
||||
|
||||
!!! tip
|
||||
@ -58,20 +58,20 @@ cd nimbus-eth2
|
||||
|
||||
```sh
|
||||
# Start a mainnet node
|
||||
./run-mainnet-beacon-node.sh
|
||||
./run-mainnet-beacon-node.sh --web3-url=http://127.0.0.1:8551
|
||||
```
|
||||
|
||||
=== "Prater"
|
||||
|
||||
```sh
|
||||
# Start a prater testnet node
|
||||
./run-prater-beacon-node.sh
|
||||
./run-prater-beacon-node.sh --web3-url=http://127.0.0.1:8551
|
||||
```
|
||||
|
||||
Once the beacon node starts, you'll see it logging information to the console, like so:
|
||||
|
||||
```sh
|
||||
INF 2022-07-19 15:42:58.145+02:00 Launching beacon node topics="beacnde" version=v22.6.1-2444e9-stateofus ...
|
||||
INF 2022-07-19 15:42:58.145+02:00 Launching beacon node topics="beacnde" version=v22.10.1-97a1cdc4-stateofus ...
|
||||
```
|
||||
|
||||
Congratulations! Your beacon node is up and running, and syncing the network!
|
||||
|
||||
@ -1,10 +1,11 @@
|
||||
# REST API
|
||||
# Beacon API
|
||||
|
||||
Nimbus exposes an **extremely fast** implementation of the standard [Beacon Node API](https://ethereum.github.io/beacon-APIs/). The API allows you to use Nimbus together with third-party tooling such as validator clients, block explorers as well as your own monitoring infrastructure.
|
||||
Nimbus exposes an **extremely fast** implementation of the standard [Beacon API](https://ethereum.github.io/beacon-APIs/). The API allows you to use Nimbus together with third-party tooling such as validator clients, block explorers as well as your own monitoring infrastructure.
|
||||
|
||||
The API is a `REST` interface accessed via `HTTP`. **The API should not be exposed to the public Internet** unless protected by additional security: it includes multiple endpoints which could open your node to denial-of-service (DoS) attacks.
|
||||
The Beacon API is a `REST` interface accessed via `http`. If you wish to expose the beacon node to the public internet, it is recommended to use a proxy such as `nginx` to provide caching and SSL support.
|
||||
|
||||
> **Warning:** If you choose to run a public endpoint, do not use that same node for validation duties -- the load of the public REST endpoint is enough to interfere with your validator duties. Additionally, if you're running validators on your beacon node, and using the same instance for historical data queries (>2 epochs old), this may also interfere with your duties.
|
||||
!!! warning
|
||||
If you are running validators with your beacon node, do not expose the REST API to the public internet or use the same beacon node for deep historical queries - doing so may negatively affect validator performance.
|
||||
|
||||
## Test your tooling against our servers
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Run a validator
|
||||
|
||||
Once your beacon node is [running and synced](./quick-start.md), the next step is to set up a validator.
|
||||
Once your beacon node is [running](./quick-start.md), the next step is to set up a validator.
|
||||
|
||||
!!! tip "No validator client needed"
|
||||
Unlike other beacon chain clients, Nimbus does not require setting up a separate validator client process - the beacon node can itself perform validator duties.
|
||||
|
||||
@ -1,20 +1,30 @@
|
||||
# Set up suggested fee recipient
|
||||
|
||||
The fee recipient is an Ethereum address that receives the transaction fees from block production, separately from the proposer reward that accrues on the beacon chain.
|
||||
The fee recipient is an Ethereum address that receives transaction fees from block production, separately from the proposer reward that accrues on the beacon chain.
|
||||
|
||||
A suggested fee recipient offers an execution client, in a merged Ethereum network, a coinbase it might use, based on the validator that is proposing the block.
|
||||
The fee recipient is forwarded to the execution client during block production - each validator can have its own fee recipient set or a single recipient may be used.
|
||||
|
||||
!!! warning
|
||||
The execution client is not required to follow the suggestion and may instead send the fees to a different address - only use execution clients you trust!
|
||||
The execution client is not required to follow the fee recipient suggestion and may instead send the fees to a different address - only use execution clients you trust!
|
||||
|
||||
Nimbus offers two ways to a suggested fee recipient, the `--suggested-fee-recipient` option and a per-validator recipient set using the [keymanager API](./keymanager-api.md). Any validator without a per-validator recipient set will fall back to a `--suggested-fee-recipient` if configured. In order, it selects from the first available, for each validator, of:
|
||||
If no fee recipient is set up, the transaction fees are sent to the zero address, effectively causing them to be lost.
|
||||
|
||||
## Setting the fee recipient
|
||||
|
||||
Nimbus supports setting fee recipient per validator, or using defaults in both the validator client and beacon node.
|
||||
|
||||
Per-validator fee recipients are set using the [keymanager API](./keymanager-api.md).
|
||||
|
||||
Any validator without a per-validator recipient set will fall back to the `--suggested-fee-recipient` option if configured. In order, it selects from the first available, for each validator, of:
|
||||
|
||||
1. the keymanager API per-validator suggested fee recipient
|
||||
2. `--suggested-fee-recipient`
|
||||
2. `--suggested-fee-recipient` in the validator client
|
||||
3. `--suggested-fee-recipient` in the beacon node
|
||||
|
||||
For example, `nimbus_beacon_node --suggested-fee-recipient=0x70E47C843E0F6ab0991A3189c28F2957eb6d3842` suggests to the execution client that `0x70E47C843E0F6ab0991A3189c28F2957eb6d3842` might be the coinbase. If this Nimbus node has two validators, one of which has its own suggested fee recipient via the keymanager API and the other does not, the former would use its own per-validator suggested fee cipient while the latter would fall back to `0x70E47C843E0F6ab0991A3189c28F2957eb6d3842`.
|
||||
|
||||
## Command line option
|
||||
|
||||
## Command line
|
||||
|
||||
=== "Mainnet"
|
||||
```sh
|
||||
@ -25,3 +35,17 @@ For example, `nimbus_beacon_node --suggested-fee-recipient=0x70E47C843E0F6ab0991
|
||||
```sh
|
||||
./run-prater-beacon-node.sh --suggested-fee-recipient=0x70E47C843E0F6ab0991A3189c28F2957eb6d3842
|
||||
```
|
||||
|
||||
=== "Validator Client"
|
||||
```sh
|
||||
./nimbus_validator_client --suggested-fee-recipient=0x70E47C843E0F6ab0991A3189c28F2957eb6d3842
|
||||
```
|
||||
|
||||
## Logs
|
||||
|
||||
The configured fee recipient for every validator is logged at startup:
|
||||
|
||||
```
|
||||
NOT 2022-11-10 08:27:02.530+01:00 Local validator attached ...
|
||||
initial_fee_recipient=70E47C843E0F6ab0991A3189c28F2957eb6d3842
|
||||
```
|
||||
|
||||
78
docs/the_nimbus_book/src/validator-client-options.md
Normal file
78
docs/the_nimbus_book/src/validator-client-options.md
Normal file
@ -0,0 +1,78 @@
|
||||
# Validator client
|
||||
|
||||
In the most simple setup, a single beacon node paired with an execution client is all that is needed to run a successful validator setup.
|
||||
|
||||
Nimbus however also provides options for running advanded setups that provide additional security and redundancy.
|
||||
|
||||
See the [validator client](./validator-client.md) page to get started!
|
||||
|
||||
## Multiple beacon nodes
|
||||
|
||||
By default, the validator client will connect to a beacon node running on the same machine using the default port (`5052`).
|
||||
|
||||
You can select one or more beacon nodes to connect to using the `--beacon-node` option:
|
||||
|
||||
```sh
|
||||
build/nimbus_validator_client \
|
||||
--beacon-node=http://127.0.0.1:5052 \
|
||||
--beacon-node=http://127.0.0.1:5053
|
||||
```
|
||||
|
||||
### Beacon node roles
|
||||
|
||||
When configuring multiple beacon nodes, each beacon node can be assigned to perform specific tasks on behalf of the validator client.
|
||||
|
||||
| Role name | Role calls |
|
||||
|:------------------- |:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| attestation-data | [produceAttestationData()](https://ethereum.github.io/beacon-APIs/#/Validator/produceAttestationData) |
|
||||
| attestation-publish | [submitPoolAttestations()](https://ethereum.github.io/beacon-APIs/#/Beacon/submitPoolAttestations) | |
|
||||
| aggregated-data | [getAggregatedAttestation()](https://ethereum.github.io/beacon-APIs/#/Validator/getAggregatedAttestation) |
|
||||
| aggregated-publish | [publishAggregateAndProofs()](https://ethereum.github.io/beacon-APIs/#/Validator/publishAggregateAndProofs) |
|
||||
| block-data | [produceBlockV2()](https://ethereum.github.io/beacon-APIs/#/Validator/produceBlockV2) | |
|
||||
| block-publish | [publishBlock()](https://ethereum.github.io/beacon-APIs/#/Beacon/publishBlock) |
|
||||
| sync-data | [getBlockRoot()](https://ethereum.github.io/beacon-APIs/#/Beacon/getBlockRoot)</br>[produceSyncCommitteeContribution()](https://ethereum.github.io/beacon-APIs/#/Validator/produceSyncCommitteeContribution) | |
|
||||
| sync-publish | [publishContributionAndProofs()](https://ethereum.github.io/beacon-APIs/#/Validator/publishContributionAndProofs) <br/> [submitPoolSyncCommitteeSignatures()](https://ethereum.github.io/beacon-APIs/#/Beacon/submitPoolSyncCommitteeSignatures) |
|
||||
| duties | [getGenesis()](https://ethereum.github.io/beacon-APIs/#/Beacon/getGenesis)<br/>[getSpec()](https://ethereum.github.io/beacon-APIs/#/Config/getSpec)<br/> [getSyncingStatus()](https://ethereum.github.io/beacon-APIs/#/Node/getSyncingStatus)<br/>getValidatorsActivity()<br/>[getForkSchedule()](https://ethereum.github.io/beacon-APIs/#/Config/getForkSchedule)<br/>[getAttesterDuties()](https://ethereum.github.io/beacon-APIs/#/Validator/getAttesterDuties)<br/>[getProposerDuties()](https://ethereum.github.io/beacon-APIs/#/Validator/getProposerDuties)<br/>[getSyncCommitteeDuties()](https://ethereum.github.io/beacon-APIs/#/Validator/getSyncCommitteeDuties)<br/> [getStateValidators()](https://ethereum.github.io/beacon-APIs/#/Beacon/getStateValidators)<br/>[prepareSyncCommitteeSubnets()](https://ethereum.github.io/beacon-APIs/#/Validator/prepareSyncCommitteeSubnets)<br/>[prepareBeaconCommitteeSubnet()](https://ethereum.github.io/beacon-APIs/#/Validator/prepareBeaconCommitteeSubnet) |
|
||||
|
||||
Also there could be combinations
|
||||
|
||||
| Name | Roles |
|
||||
| ----------- |:-------------------------------------------------------------------- |
|
||||
| attestation | attestation-data, attestation-publish |
|
||||
| aggregated | aggregated-data, aggregated-publish |
|
||||
| block | block-data, block-publish |
|
||||
| sync | sync-data, sync-publish |
|
||||
| publish | attestation-publish, aggregated-publish, block-publish, sync-publish |
|
||||
| data | attestation-data, aggregated-data, block-data, sync-data |
|
||||
| all | attestation, aggregated, block, sync, duty |
|
||||
|
||||
### Configuration
|
||||
|
||||
Roles are configured using the `#roles=` URL anchor - the default is `all`:
|
||||
|
||||
Examples:
|
||||
`http://127.0.0.1:5052/#roles=attestation-data,attestation-publish`
|
||||
`http://127.0.0.1:5053/#roles=block-proposal-data,block-proposal-publish`
|
||||
`http://127.0.0.1:5054/#roles=all`
|
||||
`http://127.0.0.1:5055/` also means `all` roles.
|
||||
|
||||
Before usage all the roles are got stripped from BN URLs.
|
||||
|
||||
## Advanced topologies
|
||||
|
||||
### Fully redundant nodes
|
||||
|
||||
Using multiple beacon nodes with the same role allows fully redundant setups.
|
||||
|
||||
These setups are resilient against any single beacon node getting disconnected and provide additional "entry points" for the data that the validator client produces should any node experience poor connectivity.
|
||||
|
||||
### Sentry node setup
|
||||
|
||||
In the Ethereum network, the block proposer is known up to 12 minutes before they propose the block. Because each validator sends attestations every 6 minutes, it is also possible to map the validator key to the beacon node IP address that serves it.
|
||||
|
||||
Sentry nodes setups allow separating block production traffic from attestations and sync committee messages, making sure that a separate public IP address is used when proposing blocks. In this setup, there are two beacon nodes:
|
||||
|
||||
* One beacon node has all roles except `block`
|
||||
* The other beacon node has the `block` role
|
||||
|
||||
Separating block production makes it harder for an attacker to target the specific IP address that the validator would otherwise use for block production.
|
||||
@ -3,28 +3,13 @@
|
||||
!!! warning
|
||||
This feature is currently in BETA - we are still testing it and implementation details may change in response to community feedback. **We strongly advise against using it on mainnet** - your validators may get slashed
|
||||
|
||||
By default, Nimbus loads validator keys into the main beacon node process, which is a simple, safe and efficient way to run a validator.
|
||||
By default, Nimbus integrates the validator client into the main beacon node process - this is a simple, safe and efficient way to run a validator.
|
||||
|
||||
Advanced users may wish to run validators in a separate process, allowing more flexible deployment strategies. The Nimbus beacon node supports both its own and third-party validator clients via the built-in [REST API](./rest-api.md).
|
||||
|
||||
!!! warning
|
||||
So far, all slashings with known causes have been linked to overly complex setups involving separation between beacon node and validator client! Only use this setup if you've taken steps to mitigate the increased risk.
|
||||
|
||||
## Build
|
||||
|
||||
The validator client is currently only available when built from source. To build the validator client, [build the beacon node](./build.md), then issue:
|
||||
|
||||
```sh
|
||||
make -j4 nimbus_validator_client
|
||||
```
|
||||
|
||||
When upgrading, follow the [upgrade guide](./keep-updated.md) but use the following command to update both beacon node and validator client at the same time:
|
||||
|
||||
```sh
|
||||
# after "git pull && make update":
|
||||
make -j4 nimbus_beacon_node nimbus_validator_client
|
||||
```
|
||||
|
||||
## Setup
|
||||
|
||||
To run a separate validator client, you must first make sure that your beacon node has its REST API enabled - start it with the `--rest` option.
|
||||
@ -49,21 +34,6 @@ build/nimbus_validator_client \
|
||||
--data-dir:build/data/vc_shared_prater_0
|
||||
```
|
||||
|
||||
## Options
|
||||
# Options
|
||||
|
||||
The validator client shares many of its options with the beacon node. To see the available command line options, run:
|
||||
|
||||
```sh
|
||||
# See help
|
||||
build/nimbus_validator_client --help
|
||||
```
|
||||
|
||||
### `--beacon-node`
|
||||
|
||||
The client will by defualt connect to a beacon node on the same machine as the validator client. Pick a different node with `--beacon-node`:
|
||||
|
||||
```sh
|
||||
build/nimbus_validator_client \
|
||||
--data-dir:build/data/vc_shared_prater_0 \
|
||||
--beacon-node:http://host:port/
|
||||
```
|
||||
See the [validator client options](./validator-client-options.md) page for more information about beacon node roles, redundant setups and sentry nodes!
|
||||
|
||||
@ -9,6 +9,6 @@ Each beacon node requires at least one dedicated web3 provider.
|
||||
|
||||
```sh
|
||||
./run-mainnet-beacon-node.sh \
|
||||
--web3-url="ws://127.0.0.1:8546" \
|
||||
--web3-url="http://backup:4444"
|
||||
--web3-url="http://127.0.0.1:8551" \
|
||||
--web3-url="ws://backup:4444"
|
||||
```
|
||||
|
||||
@ -31,7 +31,7 @@ Environment=NETWORK=mainnet
|
||||
# a compatible execution client is running on the same machine on the default
|
||||
# websocket port. Make sure to supply the right path to the JWT secret.
|
||||
|
||||
Environment=WEB3_URL=ws://127.0.0.1:8551
|
||||
Environment=WEB3_URL=http://127.0.0.1:8551
|
||||
Environment=JWT_SECRET=/tmp/jwtsecret
|
||||
|
||||
# Where to store chain data
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user