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.

consensus/ssz_derive/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "eth2_ssz_derive"
-version = "0.2.1"
+version = "0.3.0"
 authors = ["Paul Hauner <paul@sigmaprime.io>"]
 edition = "2018"
 description = "Procedural derive macros to accompany the eth2_ssz crate."
@@ -12,4 +12,6 @@ proc-macro = true
 
 [dependencies]
 syn = "1.0.42"
+proc-macro2 = "1.0.23"
 quote = "1.0.7"
+darling = "0.13.0"

consensus/ssz_derive/src/lib.rs

@@ -3,93 +3,159 @@
 //!
 //! Supports field attributes, see each derive macro for more information.
 
+use darling::{FromDeriveInput, FromMeta};
 use proc_macro::TokenStream;
 use quote::quote;
-use syn::{parse_macro_input, DataEnum, DataStruct, DeriveInput};
+use std::convert::TryInto;
+use syn::{parse_macro_input, DataEnum, DataStruct, DeriveInput, Ident};
 
-/// Returns a Vec of `syn::Ident` for each named field in the struct, whilst filtering out fields
-/// that should not be serialized.
-///
-/// # Panics
-/// Any unnamed struct field (like in a tuple struct) will raise a panic at compile time.
-fn get_serializable_named_field_idents(struct_data: &syn::DataStruct) -> Vec<&syn::Ident> {
+/// The highest possible union selector value (higher values are reserved for backwards compatible
+/// extensions).
+const MAX_UNION_SELECTOR: u8 = 127;
+
+#[derive(Debug, FromDeriveInput)]
+#[darling(attributes(ssz))]
+struct StructOpts {
+    #[darling(default)]
+    enum_behaviour: Option<String>,
+}
+
+/// Field-level configuration.
+#[derive(Debug, Default, FromMeta)]
+struct FieldOpts {
+    #[darling(default)]
+    with: Option<Ident>,
+    #[darling(default)]
+    skip_serializing: bool,
+    #[darling(default)]
+    skip_deserializing: bool,
+}
+
+const ENUM_TRANSPARENT: &str = "transparent";
+const ENUM_UNION: &str = "union";
+const ENUM_VARIANTS: &[&str] = &[ENUM_TRANSPARENT, ENUM_UNION];
+const NO_ENUM_BEHAVIOUR_ERROR: &str = "enums require an \"enum_behaviour\" attribute, \
+    e.g., #[ssz(enum_behaviour = \"transparent\")]";
+
+enum EnumBehaviour {
+    Transparent,
+    Union,
+}
+
+impl EnumBehaviour {
+    pub fn new(s: Option<String>) -> Option<Self> {
+        s.map(|s| match s.as_ref() {
+            ENUM_TRANSPARENT => EnumBehaviour::Transparent,
+            ENUM_UNION => EnumBehaviour::Union,
+            other => panic!(
+                "{} is an invalid enum_behaviour, use either {:?}",
+                other, ENUM_VARIANTS
+            ),
+        })
+    }
+}
+
+fn parse_ssz_fields(struct_data: &syn::DataStruct) -> Vec<(&syn::Type, &syn::Ident, FieldOpts)> {
     struct_data
         .fields
         .iter()
-        .filter_map(|f| {
-            if should_skip_serializing(f) {
-                None
-            } else {
-                Some(match &f.ident {
-                    Some(ref ident) => ident,
-                    _ => panic!("ssz_derive only supports named struct fields."),
+        .map(|field| {
+            let ty = &field.ty;
+            let ident = match &field.ident {
+                Some(ref ident) => ident,
+                _ => panic!("ssz_derive only supports named struct fields."),
+            };
+
+            let field_opts_candidates = field
+                .attrs
+                .iter()
+                .filter(|attr| attr.path.get_ident().map_or(false, |ident| *ident == "ssz"))
+                .collect::<Vec<_>>();
+
+            if field_opts_candidates.len() > 1 {
+                panic!("more than one field-level \"ssz\" attribute provided")
+            }
+
+            let field_opts = field_opts_candidates
+                .first()
+                .map(|attr| {
+                    let meta = attr.parse_meta().unwrap();
+                    FieldOpts::from_meta(&meta).unwrap()
                 })
-            }
+                .unwrap_or_default();
+
+            (ty, ident, field_opts)
         })
         .collect()
 }
 
-/// Returns a Vec of `syn::Type` for each named field in the struct, whilst filtering out fields
-/// that should not be serialized.
-fn get_serializable_field_types(struct_data: &syn::DataStruct) -> Vec<&syn::Type> {
-    struct_data
-        .fields
-        .iter()
-        .filter_map(|f| {
-            if should_skip_serializing(f) {
-                None
-            } else {
-                Some(&f.ty)
-            }
-        })
-        .collect()
-}
-
-/// Returns true if some field has an attribute declaring it should not be serialized.
-///
-/// The field attribute is: `#[ssz(skip_serializing)]`
-fn should_skip_serializing(field: &syn::Field) -> bool {
-    field.attrs.iter().any(|attr| {
-        attr.path.is_ident("ssz")
-            && attr.tokens.to_string().replace(" ", "") == "(skip_serializing)"
-    })
-}
-
 /// Implements `ssz::Encode` for some `struct` or `enum`.
+#[proc_macro_derive(Encode, attributes(ssz))]
+pub fn ssz_encode_derive(input: TokenStream) -> TokenStream {
+    let item = parse_macro_input!(input as DeriveInput);
+    let opts = StructOpts::from_derive_input(&item).unwrap();
+    let enum_opt = EnumBehaviour::new(opts.enum_behaviour);
+
+    match &item.data {
+        syn::Data::Struct(s) => {
+            if enum_opt.is_some() {
+                panic!("enum_behaviour is invalid for structs");
+            }
+            ssz_encode_derive_struct(&item, s)
+        }
+        syn::Data::Enum(s) => match enum_opt.expect(NO_ENUM_BEHAVIOUR_ERROR) {
+            EnumBehaviour::Transparent => ssz_encode_derive_enum_transparent(&item, s),
+            EnumBehaviour::Union => ssz_encode_derive_enum_union(&item, s),
+        },
+        _ => panic!("ssz_derive only supports structs and enums"),
+    }
+}
+
+/// Derive `ssz::Encode` for a struct.
 ///
 /// Fields are encoded in the order they are defined.
 ///
 /// ## Field attributes
 ///
 /// - `#[ssz(skip_serializing)]`: the field will not be serialized.
-#[proc_macro_derive(Encode, attributes(ssz))]
-pub fn ssz_encode_derive(input: TokenStream) -> TokenStream {
-    let item = parse_macro_input!(input as DeriveInput);
-
-    match &item.data {
-        syn::Data::Struct(s) => ssz_encode_derive_struct(&item, s),
-        syn::Data::Enum(s) => ssz_encode_derive_enum(&item, s),
-        _ => panic!("ssz_derive only supports structs and enums"),
-    }
-}
-
 fn ssz_encode_derive_struct(derive_input: &DeriveInput, struct_data: &DataStruct) -> TokenStream {
     let name = &derive_input.ident;
     let (impl_generics, ty_generics, where_clause) = &derive_input.generics.split_for_impl();
 
-    let field_idents = get_serializable_named_field_idents(struct_data);
-    let field_idents_a = get_serializable_named_field_idents(struct_data);
-    let field_types_a = get_serializable_field_types(struct_data);
-    let field_types_b = field_types_a.clone();
-    let field_types_d = field_types_a.clone();
-    let field_types_e = field_types_a.clone();
-    let field_types_f = field_types_a.clone();
+    let field_is_ssz_fixed_len = &mut vec![];
+    let field_fixed_len = &mut vec![];
+    let field_ssz_bytes_len = &mut vec![];
+    let field_encoder_append = &mut vec![];
+
+    for (ty, ident, field_opts) in parse_ssz_fields(struct_data) {
+        if field_opts.skip_serializing {
+            continue;
+        }
+
+        if let Some(module) = field_opts.with {
+            let module = quote! { #module::encode };
+            field_is_ssz_fixed_len.push(quote! { #module::is_ssz_fixed_len() });
+            field_fixed_len.push(quote! { #module::ssz_fixed_len() });
+            field_ssz_bytes_len.push(quote! { #module::ssz_bytes_len(&self.#ident) });
+            field_encoder_append.push(quote! {
+                encoder.append_parameterized(
+                    #module::is_ssz_fixed_len(),
+                    |buf| #module::ssz_append(&self.#ident, buf)
+                )
+            });
+        } else {
+            field_is_ssz_fixed_len.push(quote! { <#ty as ssz::Encode>::is_ssz_fixed_len() });
+            field_fixed_len.push(quote! { <#ty as ssz::Encode>::ssz_fixed_len() });
+            field_ssz_bytes_len.push(quote! { self.#ident.ssz_bytes_len() });
+            field_encoder_append.push(quote! { encoder.append(&self.#ident) });
+        }
+    }
 
     let output = quote! {
         impl #impl_generics ssz::Encode for #name #ty_generics #where_clause {
             fn is_ssz_fixed_len() -> bool {
                 #(
-                    <#field_types_a as ssz::Encode>::is_ssz_fixed_len() &&
+                    #field_is_ssz_fixed_len &&
                 )*
                     true
             }
@@ -99,7 +165,7 @@ fn ssz_encode_derive_struct(derive_input: &DeriveInput, struct_data: &DataStruct
                     let mut len: usize = 0;
                     #(
                         len = len
-                            .checked_add(<#field_types_b as ssz::Encode>::ssz_fixed_len())
+                            .checked_add(#field_fixed_len)
                             .expect("encode ssz_fixed_len length overflow");
                     )*
                     len
@@ -114,16 +180,16 @@ fn ssz_encode_derive_struct(derive_input: &DeriveInput, struct_data: &DataStruct
                 } else {
                     let mut len: usize = 0;
                     #(
-                        if <#field_types_d as ssz::Encode>::is_ssz_fixed_len() {
+                        if #field_is_ssz_fixed_len {
                             len = len
-                                .checked_add(<#field_types_e as ssz::Encode>::ssz_fixed_len())
+                                .checked_add(#field_fixed_len)
                                 .expect("encode ssz_bytes_len length overflow");
                         } else {
                             len = len
                                 .checked_add(ssz::BYTES_PER_LENGTH_OFFSET)
                                 .expect("encode ssz_bytes_len length overflow for offset");
                             len = len
-                                .checked_add(self.#field_idents_a.ssz_bytes_len())
+                                .checked_add(#field_ssz_bytes_len)
                                 .expect("encode ssz_bytes_len length overflow for bytes");
                         }
                     )*
@@ -136,14 +202,14 @@ fn ssz_encode_derive_struct(derive_input: &DeriveInput, struct_data: &DataStruct
                 let mut offset: usize = 0;
                 #(
                     offset = offset
-                        .checked_add(<#field_types_f as ssz::Encode>::ssz_fixed_len())
+                        .checked_add(#field_fixed_len)
                         .expect("encode ssz_append offset overflow");
                 )*
 
                 let mut encoder = ssz::SszEncoder::container(buf, offset);
 
                 #(
-                    encoder.append(&self.#field_idents);
+                    #field_encoder_append;
                 )*
 
                 encoder.finalize();
@@ -153,15 +219,27 @@ fn ssz_encode_derive_struct(derive_input: &DeriveInput, struct_data: &DataStruct
     output.into()
 }
 
-/// Derive `Encode` for a restricted subset of all possible enum types.
+/// Derive `ssz::Encode` for an enum in the "transparent" method.
+///
+/// The "transparent" method is distinct from the "union" method specified in the SSZ specification.
+/// When using "transparent", the enum will be ignored and the contained field will be serialized as
+/// if the enum does not exist. Since an union variant "selector" is not serialized, it is not
+/// possible to reliably decode an enum that is serialized transparently.
+///
+/// ## Limitations
 ///
 /// Only supports:
 /// - Enums with a single field per variant, where
 ///     - All fields are variably sized from an SSZ-perspective (not fixed size).
 ///
+/// ## Panics
+///
 /// Will panic at compile-time if the single field requirement isn't met, but will panic *at run
 /// time* if the variable-size requirement isn't met.
-fn ssz_encode_derive_enum(derive_input: &DeriveInput, enum_data: &DataEnum) -> TokenStream {
+fn ssz_encode_derive_enum_transparent(
+    derive_input: &DeriveInput,
+    enum_data: &DataEnum,
+) -> TokenStream {
     let name = &derive_input.ident;
     let (impl_generics, ty_generics, where_clause) = &derive_input.generics.split_for_impl();
 
@@ -219,14 +297,95 @@ fn ssz_encode_derive_enum(derive_input: &DeriveInput, enum_data: &DataEnum) -> T
     output.into()
 }
 
-/// Returns true if some field has an attribute declaring it should not be deserialized.
+/// Derive `ssz::Encode` for an `enum` following the "union" SSZ spec.
 ///
-/// The field attribute is: `#[ssz(skip_deserializing)]`
-fn should_skip_deserializing(field: &syn::Field) -> bool {
-    field.attrs.iter().any(|attr| {
-        attr.path.is_ident("ssz")
-            && attr.tokens.to_string().replace(" ", "") == "(skip_deserializing)"
-    })
+/// The union selector will be determined based upon the order in which the enum variants are
+/// defined. E.g., the top-most variant in the enum will have a selector of `0`, the variant
+/// beneath it will have a selector of `1` and so on.
+///
+/// # Limitations
+///
+/// Only supports enums where each variant has a single field.
+fn ssz_encode_derive_enum_union(derive_input: &DeriveInput, enum_data: &DataEnum) -> TokenStream {
+    let name = &derive_input.ident;
+    let (impl_generics, ty_generics, where_clause) = &derive_input.generics.split_for_impl();
+
+    let patterns: Vec<_> = enum_data
+        .variants
+        .iter()
+        .map(|variant| {
+            let variant_name = &variant.ident;
+
+            if variant.fields.len() != 1 {
+                panic!("ssz::Encode can only be derived for enums with 1 field per variant");
+            }
+
+            let pattern = quote! {
+                #name::#variant_name(ref inner)
+            };
+            pattern
+        })
+        .collect();
+
+    let union_selectors = compute_union_selectors(patterns.len());
+
+    let output = quote! {
+        impl #impl_generics ssz::Encode for #name #ty_generics #where_clause {
+            fn is_ssz_fixed_len() -> bool {
+                false
+            }
+
+            fn ssz_bytes_len(&self) -> usize {
+                match self {
+                    #(
+                        #patterns => inner
+                            .ssz_bytes_len()
+                            .checked_add(1)
+                            .expect("encoded length must be less than usize::max_value"),
+                    )*
+                }
+            }
+
+            fn ssz_append(&self, buf: &mut Vec<u8>) {
+                match self {
+                    #(
+                        #patterns => {
+                            let union_selector: u8 = #union_selectors;
+                            debug_assert!(union_selector <= ssz::MAX_UNION_SELECTOR);
+                            buf.push(union_selector);
+                            inner.ssz_append(buf)
+                        },
+                    )*
+                }
+            }
+        }
+    };
+    output.into()
+}
+
+/// Derive `ssz::Decode` for a struct or enum.
+#[proc_macro_derive(Decode, attributes(ssz))]
+pub fn ssz_decode_derive(input: TokenStream) -> TokenStream {
+    let item = parse_macro_input!(input as DeriveInput);
+    let opts = StructOpts::from_derive_input(&item).unwrap();
+    let enum_opt = EnumBehaviour::new(opts.enum_behaviour);
+
+    match &item.data {
+        syn::Data::Struct(s) => {
+            if enum_opt.is_some() {
+                panic!("enum_behaviour is invalid for structs");
+            }
+            ssz_decode_derive_struct(&item, s)
+        }
+        syn::Data::Enum(s) => match enum_opt.expect(NO_ENUM_BEHAVIOUR_ERROR) {
+            EnumBehaviour::Transparent => panic!(
+                "Decode cannot be derived for enum_behaviour \"{}\", only \"{}\" is valid.",
+                ENUM_TRANSPARENT, ENUM_UNION
+            ),
+            EnumBehaviour::Union => ssz_decode_derive_enum_union(&item, s),
+        },
+        _ => panic!("ssz_derive only supports structs and enums"),
+    }
 }
 
 /// Implements `ssz::Decode` for some `struct`.
@@ -238,18 +397,10 @@ fn should_skip_deserializing(field: &syn::Field) -> bool {
 /// - `#[ssz(skip_deserializing)]`: during de-serialization the field will be instantiated from a
 /// `Default` implementation. The decoder will assume that the field was not serialized at all
 /// (e.g., if it has been serialized, an error will be raised instead of `Default` overriding it).
-#[proc_macro_derive(Decode)]
-pub fn ssz_decode_derive(input: TokenStream) -> TokenStream {
-    let item = parse_macro_input!(input as DeriveInput);
-
+fn ssz_decode_derive_struct(item: &DeriveInput, struct_data: &DataStruct) -> TokenStream {
     let name = &item.ident;
     let (impl_generics, ty_generics, where_clause) = &item.generics.split_for_impl();
 
-    let struct_data = match &item.data {
-        syn::Data::Struct(s) => s,
-        _ => panic!("ssz_derive only supports structs."),
-    };
-
     let mut register_types = vec![];
     let mut field_names = vec![];
     let mut fixed_decodes = vec![];
@@ -257,50 +408,71 @@ pub fn ssz_decode_derive(input: TokenStream) -> TokenStream {
     let mut is_fixed_lens = vec![];
     let mut fixed_lens = vec![];
 
-    // Build quotes for fields that should be deserialized and those that should be built from
-    // `Default`.
-    for field in &struct_data.fields {
-        match &field.ident {
-            Some(ref ident) => {
-                field_names.push(quote! {
-                    #ident
-                });
+    for (ty, ident, field_opts) in parse_ssz_fields(struct_data) {
+        field_names.push(quote! {
+            #ident
+        });
 
-                if should_skip_deserializing(field) {
-                    // Field should not be deserialized; use a `Default` impl to instantiate.
-                    decodes.push(quote! {
-                        let #ident = <_>::default();
-                    });
+        // Field should not be deserialized; use a `Default` impl to instantiate.
+        if field_opts.skip_deserializing {
+            decodes.push(quote! {
+                let #ident = <_>::default();
+            });
 
-                    fixed_decodes.push(quote! {
-                        let #ident = <_>::default();
-                    });
-                } else {
-                    let ty = &field.ty;
+            fixed_decodes.push(quote! {
+                let #ident = <_>::default();
+            });
 
-                    register_types.push(quote! {
-                        builder.register_type::<#ty>()?;
-                    });
+            continue;
+        }
 
-                    decodes.push(quote! {
-                        let #ident = decoder.decode_next()?;
-                    });
+        let is_ssz_fixed_len;
+        let ssz_fixed_len;
+        let from_ssz_bytes;
+        if let Some(module) = field_opts.with {
+            let module = quote! { #module::decode };
 
-                    fixed_decodes.push(quote! {
-                        let #ident = decode_field!(#ty);
-                    });
+            is_ssz_fixed_len = quote! { #module::is_ssz_fixed_len() };
+            ssz_fixed_len = quote! { #module::ssz_fixed_len() };
+            from_ssz_bytes = quote! { #module::from_ssz_bytes(slice) };
 
-                    is_fixed_lens.push(quote! {
-                        <#ty as ssz::Decode>::is_ssz_fixed_len()
-                    });
+            register_types.push(quote! {
+                builder.register_type_parameterized(#is_ssz_fixed_len, #ssz_fixed_len)?;
+            });
+            decodes.push(quote! {
+                let #ident = decoder.decode_next_with(|slice| #module::from_ssz_bytes(slice))?;
+            });
+        } else {
+            is_ssz_fixed_len = quote! { <#ty as ssz::Decode>::is_ssz_fixed_len() };
+            ssz_fixed_len = quote! { <#ty as ssz::Decode>::ssz_fixed_len() };
+            from_ssz_bytes = quote! { <#ty as ssz::Decode>::from_ssz_bytes(slice) };
 
-                    fixed_lens.push(quote! {
-                        <#ty as ssz::Decode>::ssz_fixed_len()
-                    });
-                }
-            }
-            _ => panic!("ssz_derive only supports named struct fields."),
-        };
+            register_types.push(quote! {
+                builder.register_type::<#ty>()?;
+            });
+            decodes.push(quote! {
+                let #ident = decoder.decode_next()?;
+            });
+        }
+
+        fixed_decodes.push(quote! {
+            let #ident = {
+                start = end;
+                end = end
+                    .checked_add(#ssz_fixed_len)
+                    .ok_or_else(|| ssz::DecodeError::OutOfBoundsByte {
+                        i: usize::max_value()
+                    })?;
+                let slice = bytes.get(start..end)
+                    .ok_or_else(|| ssz::DecodeError::InvalidByteLength {
+                        len: bytes.len(),
+                        expected: end
+                    })?;
+                #from_ssz_bytes?
+            };
+        });
+        is_fixed_lens.push(is_ssz_fixed_len);
+        fixed_lens.push(ssz_fixed_len);
     }
 
     let output = quote! {
@@ -338,23 +510,6 @@ pub fn ssz_decode_derive(input: TokenStream) -> TokenStream {
                     let mut start: usize = 0;
                     let mut end = start;
 
-                    macro_rules! decode_field {
-                        ($type: ty) => {{
-                            start = end;
-                            end = end
-                                .checked_add(<$type as ssz::Decode>::ssz_fixed_len())
-                                .ok_or_else(|| ssz::DecodeError::OutOfBoundsByte {
-                                    i: usize::max_value()
-                                })?;
-                            let slice = bytes.get(start..end)
-                                .ok_or_else(|| ssz::DecodeError::InvalidByteLength {
-                                    len: bytes.len(),
-                                    expected: end
-                                })?;
-                            <$type as ssz::Decode>::from_ssz_bytes(slice)?
-                        }};
-                    }
-
                     #(
                         #fixed_decodes
                     )*
@@ -389,3 +544,79 @@ pub fn ssz_decode_derive(input: TokenStream) -> TokenStream {
     };
     output.into()
 }
+
+/// Derive `ssz::Decode` for an `enum` following the "union" SSZ spec.
+fn ssz_decode_derive_enum_union(derive_input: &DeriveInput, enum_data: &DataEnum) -> TokenStream {
+    let name = &derive_input.ident;
+    let (impl_generics, ty_generics, where_clause) = &derive_input.generics.split_for_impl();
+
+    let (constructors, var_types): (Vec<_>, Vec<_>) = enum_data
+        .variants
+        .iter()
+        .map(|variant| {
+            let variant_name = &variant.ident;
+
+            if variant.fields.len() != 1 {
+                panic!("ssz::Encode can only be derived for enums with 1 field per variant");
+            }
+
+            let constructor = quote! {
+                #name::#variant_name
+            };
+
+            let ty = &(&variant.fields).into_iter().next().unwrap().ty;
+            (constructor, ty)
+        })
+        .unzip();
+
+    let union_selectors = compute_union_selectors(constructors.len());
+
+    let output = quote! {
+        impl #impl_generics ssz::Decode for #name #ty_generics #where_clause {
+            fn is_ssz_fixed_len() -> bool {
+                false
+            }
+
+            fn from_ssz_bytes(bytes: &[u8]) -> Result<Self, ssz::DecodeError> {
+                // Sanity check to ensure the definition here does not drift from the one defined in
+                // `ssz`.
+                debug_assert_eq!(#MAX_UNION_SELECTOR, ssz::MAX_UNION_SELECTOR);
+
+                let (selector, body) = ssz::split_union_bytes(bytes)?;
+
+                match selector.into() {
+                    #(
+                        #union_selectors => {
+                            <#var_types as ssz::Decode>::from_ssz_bytes(body).map(#constructors)
+                        },
+                    )*
+                    other => Err(ssz::DecodeError::UnionSelectorInvalid(other))
+                }
+            }
+        }
+    };
+    output.into()
+}
+
+fn compute_union_selectors(num_variants: usize) -> Vec<u8> {
+    let union_selectors = (0..num_variants)
+        .map(|i| {
+            i.try_into()
+                .expect("union selector exceeds u8::max_value, union has too many variants")
+        })
+        .collect::<Vec<u8>>();
+
+    let highest_selector = union_selectors
+        .last()
+        .copied()
+        .expect("0-variant union is not permitted");
+
+    assert!(
+        highest_selector <= MAX_UNION_SELECTOR,
+        "union selector {} exceeds limit of {}, enum has too many variants",
+        highest_selector,
+        MAX_UNION_SELECTOR
+    );
+
+    union_selectors
+}