Skip to content

Commit

Permalink
Rename Eth1/Eth2 in documents (sigp#3021)
Browse files Browse the repository at this point in the history
## Issue Addressed

Resolves sigp#3019

## Proposed Changes

- Eth2 Eth2.0 Ethereum 2.0 -> Ethereum consensus
- Eth2 network -> consensus layer
- Ethereum 2.0 specification -> Ethereum proof-of-stake consensus specification
- Eth2 deposit contract -> Staking deposit contract
- Eth1 -> execution client

## Additional Info

The description needs to be updated by someone who has permission to do. 📝 

<img width="487" alt="image" src="https://user-images.githubusercontent.com/1885716/153995211-816d9561-751e-4810-abb9-83d979379783.png">
  • Loading branch information
ackintosh committed Mar 2, 2022
1 parent e34524b commit 668115a
Show file tree
Hide file tree
Showing 25 changed files with 100 additions and 100 deletions.
14 changes: 7 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Lighthouse: Ethereum 2.0
# Lighthouse: Ethereum consensus client

An open-source Ethereum 2.0 client, written in Rust and maintained by Sigma Prime.
An open-source Ethereum consensus client, written in Rust and maintained by Sigma Prime.

[![Build Status]][Build Link] [![Book Status]][Book Link] [![Chat Badge]][Chat Link]

Expand All @@ -22,21 +22,21 @@ An open-source Ethereum 2.0 client, written in Rust and maintained by Sigma Prim

Lighthouse is:

- Ready for use on Eth2 mainnet.
- Ready for use on Ethereum consensus mainnet.
- Fully open-source, licensed under Apache 2.0.
- Security-focused. Fuzzing techniques have been continuously applied and several external security reviews have been performed.
- Built in [Rust](https://www.rust-lang.org), a modern language providing unique safety guarantees and
excellent performance (comparable to C++).
- Funded by various organisations, including Sigma Prime, the
Ethereum Foundation, ConsenSys, the Decentralization Foundation and private individuals.
- Actively involved in the specification and security analysis of the
Ethereum 2.0 specification.
Ethereum proof-of-stake consensus specification.

## Eth2 Deposit Contract
## Staking Deposit Contract

The Lighthouse team acknowledges
[`0x00000000219ab540356cBB839Cbe05303d7705Fa`](https://etherscan.io/address/0x00000000219ab540356cbb839cbe05303d7705fa)
as the canonical Eth2 deposit contract address.
as the canonical staking deposit contract address.

## Documentation

Expand Down Expand Up @@ -66,7 +66,7 @@ of the Lighthouse book.
## Contact

The best place for discussion is the [Lighthouse Discord
server](https://discord.gg/cyAszAh).
server](https://discord.gg/cyAszAh).

Sign up to the [Lighthouse Development Updates](http://eepurl.com/dh9Lvb) mailing list for email
notifications about releases, network status and other important information.
Expand Down
2 changes: 1 addition & 1 deletion book/src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
* [Create a validator](./validator-create.md)
* [Key recovery](./key-recovery.md)
* [Validator Management](./validator-management.md)
* [Importing from the Eth2 Launchpad](./validator-import-launchpad.md)
* [Importing from the Staking Launchpad](./validator-import-launchpad.md)
* [Slashing Protection](./slashing-protection.md)
* [Voluntary Exits](./voluntary-exit.md)
* [Validator Monitoring](./validator-monitoring.md)
Expand Down
4 changes: 2 additions & 2 deletions book/src/advanced_networking.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ still function if it is behind a NAT without any port mappings. Although
Lighthouse still functions, we recommend that some mechanism is used to ensure
that your Lighthouse node is publicly accessible. This will typically improve
your peer count, allow the scoring system to find the best/most favourable
peers for your node and overall improve the eth2 network.
peers for your node and overall improve the Ethereum consensus network.

Lighthouse currently supports UPnP. If UPnP is enabled on your router,
Lighthouse will automatically establish the port mappings for you (the beacon
Expand All @@ -63,7 +63,7 @@ settings allow you construct your initial ENR. Their primary intention is for
setting up boot-like nodes and having a contactable ENR on boot. On normal
operation of a Lighthouse node, none of these flags need to be set. Setting
these flags incorrectly can lead to your node being incorrectly added to the
global DHT which will degrades the discovery process for all Eth2 peers.
global DHT which will degrades the discovery process for all Ethereum consensus peers.

The ENR of a Lighthouse node is initially set to be non-contactable. The
in-built discovery mechanism can determine if you node is publicly accessible,
Expand Down
6 changes: 3 additions & 3 deletions book/src/api-bn.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Beacon Node API

Lighthouse implements the standard [Eth2 Beacon Node API
Lighthouse implements the standard [Beacon Node API
specification][OpenAPI]. Please follow that link for a full description of each API endpoint.

## Starting the server
Expand All @@ -22,7 +22,7 @@ The following CLI flags control the HTTP server:
- `--http-tls-cert`: specify the path to the certificate file for Lighthouse to use.
- `--http-tls-key`: specify the path to the private key file for Lighthouse to use.

The schema of the API aligns with the standard Eth2 Beacon Node API as defined
The schema of the API aligns with the standard Beacon Node API as defined
at [github.com/ethereum/beacon-APIs](https://github.com/ethereum/beacon-APIs).
An interactive specification is available [here][OpenAPI].

Expand Down Expand Up @@ -64,7 +64,7 @@ lighthouse bn --http
## HTTP Request/Response Examples

This section contains some simple examples of using the HTTP API via `curl`.
All endpoints are documented in the [Eth2 Beacon Node API
All endpoints are documented in the [Beacon Node API
specification][OpenAPI].

### View the head of the beacon chain
Expand Down
22 changes: 11 additions & 11 deletions book/src/api-lighthouse.md
Original file line number Diff line number Diff line change
Expand Up @@ -199,23 +199,23 @@ See [Validator Inclusion APIs](./validator-inclusion.md).

### `/lighthouse/eth1/syncing`

Returns information regarding the Eth1 network, as it is required for use in
Eth2
Returns information regarding execution layer, as it is required for use in
consensus layer

#### Fields

- `head_block_number`, `head_block_timestamp`: the block number and timestamp
from the very head of the Eth1 chain. Useful for understanding the immediate
health of the Eth1 node that the beacon node is connected to.
from the very head of the execution chain. Useful for understanding the immediate
health of the execution node that the beacon node is connected to.
- `latest_cached_block_number` & `latest_cached_block_timestamp`: the block
number and timestamp of the latest block we have in our block cache.
- For correct Eth1 voting this timestamp should be later than the
- For correct execution client voting this timestamp should be later than the
`voting_period_start_timestamp`.
- `voting_target_timestamp`: The latest timestamp allowed for an eth1 block in this voting period.
- `voting_target_timestamp`: The latest timestamp allowed for an execution layer block in this voting period.
- `eth1_node_sync_status_percentage` (float): An estimate of how far the head of the
Eth1 node is from the head of the Eth1 chain.
- `100.0` indicates a fully synced Eth1 node.
- `0.0` indicates an Eth1 node that has not verified any blocks past the
execution node is from the head of the execution chain.
- `100.0` indicates a fully synced execution node.
- `0.0` indicates an execution node that has not verified any blocks past the
genesis block.
- `lighthouse_is_cached_and_ready`: Is set to `true` if the caches in the
beacon node are ready for block production.
Expand Down Expand Up @@ -248,7 +248,7 @@ curl -X GET "http://localhost:5052/lighthouse/eth1/syncing" -H "accept: applica

### `/lighthouse/eth1/block_cache`

Returns a list of all the Eth1 blocks in the Eth1 voting cache.
Returns a list of all the execution layer blocks in the execution client voting cache.

#### Example

Expand Down Expand Up @@ -320,7 +320,7 @@ curl -X GET "http://localhost:5052/lighthouse/eth1/deposit_cache" -H "accept: a

Obtains a `BeaconState` in SSZ bytes. Useful for obtaining a genesis state.

The `state_id` parameter is identical to that used in the [Standard Eth2.0 Beacon Node API
The `state_id` parameter is identical to that used in the [Standard Beacon Node API
`beacon/state`
routes](https://ethereum.github.io/beacon-APIs/#/Beacon/getStateRoot).

Expand Down
4 changes: 2 additions & 2 deletions book/src/api-vc-endpoints.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ HTTP Path | Description |
| --- | -- |
[`GET /lighthouse/version`](#get-lighthouseversion) | Get the Lighthouse software version.
[`GET /lighthouse/health`](#get-lighthousehealth) | Get information about the host machine.
[`GET /lighthouse/spec`](#get-lighthousespec) | Get the Eth2 specification used by the validator.
[`GET /lighthouse/spec`](#get-lighthousespec) | Get the Ethereum proof-of-stake consensus specification used by the validator.
[`GET /lighthouse/auth`](#get-lighthouseauth) | Get the location of the authorization token.
[`GET /lighthouse/validators`](#get-lighthousevalidators) | List all validators.
[`GET /lighthouse/validators/:voting_pubkey`](#get-lighthousevalidatorsvoting_pubkey) | Get a specific validator.
Expand Down Expand Up @@ -79,7 +79,7 @@ Typical Responses | 200

## `GET /lighthouse/spec`

Returns the Eth2 specification loaded for this validator.
Returns the Ethereum proof-of-stake consensus specification loaded for this validator.

### HTTP Specification

Expand Down
2 changes: 1 addition & 1 deletion book/src/api.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# APIs

Lighthouse allows users to query the state of Eth2.0 using web-standard,
Lighthouse allows users to query the state of Ethereum consensus using web-standard,
RESTful HTTP/JSON APIs.

There are two APIs served by Lighthouse:
Expand Down
4 changes: 2 additions & 2 deletions book/src/cli.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Command-Line Interface (CLI)

The `lighthouse` binary provides all necessary Ethereum 2.0 functionality. It
The `lighthouse` binary provides all necessary Ethereum consensus client functionality. It
has two primary sub-commands:

- `$ lighthouse beacon_node`: the largest and most fundamental component which connects to
Expand Down Expand Up @@ -48,7 +48,7 @@ maintained by Sigma Prime.

However, for developers, testnets can be created by following the instructions
outlined in [testnets](./testnets.md). The steps listed here will create a
local database specified to a new testnet.
local database specified to a new testnet.

## Resuming from an existing database

Expand Down
6 changes: 3 additions & 3 deletions book/src/contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,10 +35,10 @@ Lighthouse maintains two permanent branches:
- [`unstable`][unstable]: Used for development, contains the latest PRs.
- Developers should base thier PRs on this branch.

## Ethereum 2.0
## Ethereum consensus client

Lighthouse is an implementation of the Ethereum 2.0 specification, as defined
in the [ethereum/eth2.0-specs](https://github.com/ethereum/eth2.0-specs)
Lighthouse is an implementation of the Ethereum proof-of-stake consensus specification, as defined
in the [ethereum/consensus-specs](https://github.com/ethereum/consensus-specs)
repository.

We recommend reading Danny Ryan's (incomplete) [Phase 0 for
Expand Down
48 changes: 24 additions & 24 deletions book/src/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,68 +12,68 @@

### Why does it take so long for a validator to be activated?

After validators create their Eth1 deposit transaction there are two waiting
After validators create their execution layer deposit transaction there are two waiting
periods before they can start producing blocks and attestations:

1. Waiting for the beacon chain to recognise the Eth1 block containing the
1. Waiting for the beacon chain to recognise the execution layer block containing the
deposit (generally 4 to 7.4 hours).
1. Waiting in the queue for validator activation (generally 6.4 minutes for
every 4 validators in the queue).

Detailed answers below:

#### 1. Waiting for the beacon chain to detect the Eth1 deposit
#### 1. Waiting for the beacon chain to detect the execution layer deposit

Since the beacon chain uses Eth1 for validator on-boarding, beacon chain
Since the beacon chain uses the execution layer for validator on-boarding, beacon chain
validators must listen to event logs from the deposit contract. Since the
latest blocks of the Eth1 chain are vulnerable to re-orgs due to minor network
partitions, beacon nodes follow the Eth1 chain at a distance of 1,024 blocks
latest blocks of the execution chain are vulnerable to re-orgs due to minor network
partitions, beacon nodes follow the execution chain at a distance of 1,024 blocks
(~4 hours) (see
[`ETH1_FOLLOW_DISTANCE`](https://github.com/ethereum/eth2.0-specs/blob/v0.12.1/specs/phase0/validator.md#misc)).
[`ETH1_FOLLOW_DISTANCE`](https://github.com/ethereum/consensus-specs/blob/v0.12.1/specs/phase0/validator.md#misc)).
This follow distance protects the beacon chain from on-boarding validators that
are likely to be removed due to an Eth1 re-org.
are likely to be removed due to an execution chain re-org.

Now we know there's a 4 hours delay before the beacon nodes even _consider_ an
Eth1 block. Once they _are_ considering these blocks, there's a voting period
where beacon validators vote on which Eth1 to include in the beacon chain. This
execution layer block. Once they _are_ considering these blocks, there's a voting period
where beacon validators vote on which execution block hash to include in the beacon chain. This
period is defined as 32 epochs (~3.4 hours, see
[`ETH1_VOTING_PERIOD`](https://github.com/ethereum/eth2.0-specs/blob/v0.12.1/specs/phase0/beacon-chain.md#time-parameters)).
[`ETH1_VOTING_PERIOD`](https://github.com/ethereum/consensus-specs/blob/v0.12.1/specs/phase0/beacon-chain.md#time-parameters)).
During this voting period, each beacon block producer includes an
[`Eth1Data`](https://github.com/ethereum/eth2.0-specs/blob/v0.12.1/specs/phase0/beacon-chain.md#eth1data)
[`Eth1Data`](https://github.com/ethereum/consensus-specs/blob/v0.12.1/specs/phase0/beacon-chain.md#eth1data)
in their block which counts as a vote towards what that validator considers to
be the head of the Eth1 chain at the start of the voting period (with respect
be the head of the execution chain at the start of the voting period (with respect
to `ETH1_FOLLOW_DISTANCE`, of course). You can see the exact voting logic
[here](https://github.com/ethereum/eth2.0-specs/blob/v0.12.1/specs/phase0/validator.md#eth1-data).
[here](https://github.com/ethereum/consensus-specs/blob/v0.12.1/specs/phase0/validator.md#eth1-data).

These two delays combined represent the time between an Eth1 deposit being
included in an Eth1 data vote and that validator appearing in the beacon chain.
These two delays combined represent the time between an execution layer deposit being
included in an execution data vote and that validator appearing in the beacon chain.
The `ETH1_FOLLOW_DISTANCE` delay causes a minimum delay of ~4 hours and
`ETH1_VOTING_PERIOD` means that if a validator deposit happens just _before_
the start of a new voting period then they might not notice this delay at all.
However, if the validator deposit happens just _after_ the start of the new
voting period the validator might have to wait ~3.4 hours for next voting
period. In times of very, very severe network issues, the network may even fail
to vote in new Eth1 blocks, stopping all new validator deposits!
to vote in new execution layer blocks, stopping all new validator deposits!

#### 2. Waiting for a validator to be activated

If a validator has provided an invalid public key or signature, they will
_never_ be activated.
They will simply be forgotten by the beacon chain! But, if those parameters were
correct, once the Eth1 delays have elapsed and the validator appears in the
correct, once the execution layer delays have elapsed and the validator appears in the
beacon chain, there's _another_ delay before the validator becomes "active"
(canonical definition
[here](https://github.com/ethereum/eth2.0-specs/blob/v0.12.1/specs/phase0/beacon-chain.md#is_active_validator)) and can start producing blocks and attestations.
[here](https://github.com/ethereum/consensus-specs/blob/v0.12.1/specs/phase0/beacon-chain.md#is_active_validator)) and can start producing blocks and attestations.

Firstly, the validator won't become active until their beacon chain balance is
equal to or greater than
[`MAX_EFFECTIVE_BALANCE`](https://github.com/ethereum/eth2.0-specs/blob/v0.12.1/specs/phase0/beacon-chain.md#gwei-values)
[`MAX_EFFECTIVE_BALANCE`](https://github.com/ethereum/consensus-specs/blob/v0.12.1/specs/phase0/beacon-chain.md#gwei-values)
(32 ETH on mainnet, usually 3.2 ETH on testnets). Once this balance is reached,
the validator must wait until the start of the next epoch (up to 6.4 minutes)
for the
[`process_registry_updates`](https://github.com/ethereum/eth2.0-specs/blob/v0.12.1/specs/phase0/beacon-chain.md#registry-updates)
[`process_registry_updates`](https://github.com/ethereum/consensus-specs/blob/v0.12.1/specs/phase0/beacon-chain.md#registry-updates)
routine to run. This routine activates validators with respect to a [churn
limit](https://github.com/ethereum/eth2.0-specs/blob/v0.12.1/specs/phase0/beacon-chain.md#get_validator_churn_limit);
limit](https://github.com/ethereum/consensus-specs/blob/v0.12.1/specs/phase0/beacon-chain.md#get_validator_churn_limit);
it will only allow the number of validators to increase (churn) by a certain
amount. Up until there are about 330,000 validators this churn limit is set to
4 and it starts to very slowly increase as the number of validators increases
Expand Down Expand Up @@ -161,7 +161,7 @@ Nov 30 21:04:28.268 WARN Syncing eth1 block cache est_blocks_remaining: initia
```

This log indicates that your beacon node is downloading blocks and deposits
from your eth1 node. When the `est_blocks_remaining` is
from your execution node. When the `est_blocks_remaining` is
`initializing_deposits`, your node is downloading deposit logs. It may stay in
this stage for several minutes. Once the deposits logs are finished
downloading, the `est_blocks_remaining` value will start decreasing.
Expand All @@ -170,7 +170,7 @@ It is perfectly normal to see this log when starting a node for the first time
or after being off for more than several minutes.

If this log continues appearing sporadically during operation, there may be an
issue with your eth1 endpoint.
issue with your execution client endpoint.

### Can I use redundancy in my staking setup?

Expand Down
2 changes: 1 addition & 1 deletion book/src/http.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ The following CLI flags control the HTTP server:
- `--http-port`: specify the listen port of the server.
- `--http-address`: specify the listen address of the server.

The schema of the API aligns with the standard Eth2 Beacon Node API as defined
The schema of the API aligns with the standard Ethereum Beacon Node API as defined
at [github.com/ethereum/beacon-APIs](https://github.com/ethereum/beacon-APIs).
It is an easy-to-use RESTful HTTP/JSON API. An interactive specification is
available [here](https://ethereum.github.io/beacon-APIs/).
Expand Down
4 changes: 2 additions & 2 deletions book/src/intro.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,11 @@ _Documentation for Lighthouse users and developers._
[Chat Badge]: https://img.shields.io/badge/chat-discord-%237289da
[Chat Link]: https://discord.gg/cyAszAh

Lighthouse is an **Ethereum 2.0 client** that connects to other Ethereum 2.0
Lighthouse is an **Ethereum consensus client** that connects to other Ethereum consensus
clients to form a resilient and decentralized proof-of-stake blockchain.

We implement the specification as defined in the
[ethereum/eth2.0-specs](https://github.com/ethereum/eth2.0-specs) repository.
[ethereum/consensus-specs](https://github.com/ethereum/consensus-specs) repository.

## Topics

Expand Down
4 changes: 2 additions & 2 deletions book/src/key-management.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
[launchpad]: https://launchpad.ethereum.org/

>
> **Note: we recommend using the [Eth2 launchpad][launchpad] to create validators.**
> **Note: we recommend using the [Staking launchpad][launchpad] to create validators.**
Lighthouse uses a _hierarchical_ key management system for producing validator
keys. It is hierarchical because each validator key can be _derived_ from a
Expand Down Expand Up @@ -92,7 +92,7 @@ leaking private key data.

### Withdrawal Keypairs

In Eth2 Phase 0, withdrawal keypairs do not serve any immediate purpose.
In Ethereum consensus Phase 0, withdrawal keypairs do not serve any immediate purpose.
However, they become very important _after_ Phase 0: they will provide the
ultimate control of the ETH of withdrawn validators.

Expand Down
2 changes: 1 addition & 1 deletion book/src/key-recovery.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ which contains all the information necessary to run a validator using the
`lighthouse vc` command. The password to this new keystore will be placed in
the `--secrets-dir` (default `~/.lighthouse/{network}/secrets`).

where `network` is the name of the Eth2 network passed in the `--network` parameter (default is `mainnet`).
where `network` is the name of the consensus layer network passed in the `--network` parameter (default is `mainnet`).

## Recover a EIP-2386 wallet

Expand Down
Loading

0 comments on commit 668115a

Please sign in to comment.