Ethereum consensus client in Rust
Go to file
Paul Hauner fe52322088 Implement SSZ union type (#2579)
## Issue Addressed

NA

## Proposed Changes

Implements the "union" type from the SSZ spec for `ssz`, `ssz_derive`, `tree_hash` and `tree_hash_derive` so it may be derived for `enums`:

https://github.com/ethereum/consensus-specs/blob/v1.1.0-beta.3/ssz/simple-serialize.md#union

The union type is required for the merge, since the `Transaction` type is defined as a single-variant union `Union[OpaqueTransaction]`.

### Crate Updates

This PR will (hopefully) cause CI to publish new versions for the following crates:

- `eth2_ssz_derive`: `0.2.1` -> `0.3.0`
- `eth2_ssz`: `0.3.0` -> `0.4.0`
- `eth2_ssz_types`: `0.2.0` -> `0.2.1`
- `tree_hash`: `0.3.0` -> `0.4.0`
- `tree_hash_derive`: `0.3.0` -> `0.4.0`

These these crates depend on each other, I've had to add a workspace-level `[patch]` for these crates. A follow-up PR will need to remove this patch, ones the new versions are published.

### Union Behaviors

We already had SSZ `Encode` and `TreeHash` derive for enums, however it just did a "transparent" pass-through of the inner value. Since the "union" decoding from the spec is in conflict with the transparent method, I've required that all `enum` have exactly one of the following enum-level attributes:

#### SSZ

-  `#[ssz(enum_behaviour = "union")]`
    - matches the spec used for the merge
-  `#[ssz(enum_behaviour = "transparent")]`
    - maintains existing functionality
    - not supported for `Decode` (never was)
    
#### TreeHash

-  `#[tree_hash(enum_behaviour = "union")]`
    - matches the spec used for the merge
-  `#[tree_hash(enum_behaviour = "transparent")]`
    - maintains existing functionality

This means that we can maintain the existing transparent behaviour, but all existing users will get a compile-time error until they explicitly opt-in to being transparent.

### Legacy Option Encoding

Before this PR, we already had a union-esque encoding for `Option<T>`. However, this was with the *old* SSZ spec where the union selector was 4 bytes. During merge specification, the spec was changed to use 1 byte for the selector.

Whilst the 4-byte `Option` encoding was never used in the spec, we used it in our database. Writing a migrate script for all occurrences of `Option` in the database would be painful, especially since it's used in the `CommitteeCache`. To avoid the migrate script, I added a serde-esque `#[ssz(with = "module")]` field-level attribute to `ssz_derive` so that we can opt into the 4-byte encoding on a field-by-field basis.

The `ssz::legacy::four_byte_impl!` macro allows a one-liner to define the module required for the `#[ssz(with = "module")]` for some `Option<T> where T: Encode + Decode`.

Notably, **I have removed `Encode` and `Decode` impls for `Option`**. I've done this to force a break on downstream users. Like I mentioned, `Option` isn't used in the spec so I don't think it'll be *that* annoying. I think it's nicer than quietly having two different union implementations or quietly breaking the existing `Option` impl.

### Crate Publish Ordering

I've modified the order in which CI publishes crates to ensure that we don't publish a crate without ensuring we already published a crate that it depends upon.

## TODO

- [ ] Queue a follow-up `[patch]`-removing PR.
2021-09-25 05:58:36 +00:00
.github Implement SSZ union type (#2579) 2021-09-25 05:58:36 +00:00
account_manager Implement SSZ union type (#2579) 2021-09-25 05:58:36 +00:00
beacon_node Implement SSZ union type (#2579) 2021-09-25 05:58:36 +00:00
book Update spec tests to v1.1.0-beta.4 (#2548) 2021-09-25 05:58:35 +00:00
boot_node Implement SSZ union type (#2579) 2021-09-25 05:58:36 +00:00
common Implement SSZ union type (#2579) 2021-09-25 05:58:36 +00:00
consensus Implement SSZ union type (#2579) 2021-09-25 05:58:36 +00:00
crypto Implement SSZ union type (#2579) 2021-09-25 05:58:36 +00:00
lcli Implement SSZ union type (#2579) 2021-09-25 05:58:36 +00:00
lighthouse Implement checkpoint sync (#2244) 2021-09-22 00:37:28 +00:00
scripts Fix typo of vars.env (#2574) 2021-09-07 03:14:03 +00:00
slasher Implement SSZ union type (#2579) 2021-09-25 05:58:36 +00:00
testing Implement SSZ union type (#2579) 2021-09-25 05:58:36 +00:00
validator_client Implement SSZ union type (#2579) 2021-09-25 05:58:36 +00:00
.dockerignore Update spec tests to v1.1.0-beta.4 (#2548) 2021-09-25 05:58:35 +00:00
.editorconfig Add editorconfig template 2019-03-11 15:09:57 +11:00
.gitignore Delete uncompressed genesis states (#2092) 2020-12-16 03:44:05 +00:00
.gitmodules Replace EF tests submodule with a makefile 2019-09-08 04:19:54 +10:00
bors.toml Add Windows to Bors config (#2358) 2021-05-20 00:23:08 +00:00
Cargo.lock Implement SSZ union type (#2579) 2021-09-25 05:58:36 +00:00
Cargo.toml Implement SSZ union type (#2579) 2021-09-25 05:58:36 +00:00
CONTRIBUTING.md Update CONTRIBUTING.md (#751) 2020-01-03 10:45:53 +11:00
Cross.toml Ensure RUSTFLAGS is passed through on cross compile (#1529) 2020-08-17 10:06:06 +00:00
Dockerfile Update outdated dependencies (#2425) 2021-07-05 00:54:17 +00:00
Dockerfile.cross Multiarch docker GitHub actions (#2065) 2020-12-09 06:06:37 +00:00
LICENSE Update License to Apache 2.0 2019-04-15 16:47:35 +10:00
Makefile Update spec tests to v1.1.0-beta.4 (#2548) 2021-09-25 05:58:35 +00:00
README.md Fix readme typo (#2312) 2021-04-14 02:30:54 +00:00
SECURITY.md Add how users should report security vulnerabilities for this repository (#2562) 2021-09-07 01:54:05 +00:00

Lighthouse: Ethereum 2.0

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

Build Status Book Status Chat Badge

Documentation

Banner

Overview

Lighthouse is:

  • Ready for use on Eth2 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, 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.

Eth2 Deposit Contract

The Lighthouse team acknowledges 0x00000000219ab540356cBB839Cbe05303d7705Fa as the canonical Eth2 deposit contract address.

Documentation

The Lighthouse Book contains information for users and developers.

The Lighthouse team maintains a blog at lighthouse.sigmaprime.io which contains periodical progress updates, roadmap insights and interesting findings.

Branches

Lighthouse maintains two permanent branches:

  • stable: Always points to the latest stable release.
    • This is ideal for most users.
  • unstable: Used for development, contains the latest PRs.
    • Developers should base their PRs on this branch.

Contributing

Lighthouse welcomes contributors.

If you are looking to contribute, please head to the Contributing section of the Lighthouse book.

Contact

The best place for discussion is the Lighthouse Discord server. Alternatively, you may use the sigp/lighthouse gitter.

Sign up to the Lighthouse Development Updates mailing list for email notifications about releases, network status and other important information.

Encrypt sensitive messages using our PGP key.

Donations

Lighthouse is an open-source project and a public good. Funding public goods is hard and we're grateful for the donations we receive from the community via:

  • Gitcoin Grants.
  • Ethereum address: 0x25c4a76E7d118705e7Ea2e9b7d8C59930d8aCD3b (donation.sigmaprime.eth).