rlp: add support for optional struct fields (#22832)

This adds support for a new struct tag "optional". Using this tag, structs used
for RLP encoding/decoding can be extended in a backwards-compatible way,
by adding new fields at the end.

rlp/doc.go

@@ -102,29 +102,60 @@ Signed integers, floating point numbers, maps, channels and functions cannot be
 
 Struct Tags
 
-Package rlp honours certain struct tags: "-", "tail", "nil", "nilList" and "nilString".
+As with other encoding packages, the "-" tag ignores fields.
 
-The "-" tag ignores fields.
-
-The "tail" tag, which may only be used on the last exported struct field, allows slurping
-up any excess list elements into a slice. See examples for more details.
-
-The "nil" tag applies to pointer-typed fields and changes the decoding rules for the field
-such that input values of size zero decode as a nil pointer. This tag can be useful when
-decoding recursive types.
-
-    type StructWithOptionalFoo struct {
-        Foo *[20]byte `rlp:"nil"`
+    type StructWithIgnoredField struct{
+        Ignored uint `rlp:"-"`
+        Field   uint
     }
 
+Go struct values encode/decode as RLP lists. There are two ways of influencing the mapping
+of fields to list elements. The "tail" tag, which may only be used on the last exported
+struct field, allows slurping up any excess list elements into a slice.
+
+    type StructWithTail struct{
+        Field   uint
+        Tail    []string `rlp:"tail"`
+    }
+
+The "optional" tag says that the field may be omitted if it is zero-valued. If this tag is
+used on a struct field, all subsequent public fields must also be declared optional.
+
+When encoding a struct with optional fields, the output RLP list contains all values up to
+the last non-zero optional field.
+
+When decoding into a struct, optional fields may be omitted from the end of the input
+list. For the example below, this means input lists of one, two, or three elements are
+accepted.
+
+   type StructWithOptionalFields struct{
+        Required  uint
+        Optional1 uint `rlp:"optional"`
+        Optional2 uint `rlp:"optional"`
+   }
+
+The "nil", "nilList" and "nilString" tags apply to pointer-typed fields only, and change
+the decoding rules for the field type. For regular pointer fields without the "nil" tag,
+input values must always match the required input length exactly and the decoder does not
+produce nil values. When the "nil" tag is set, input values of size zero decode as a nil
+pointer. This is especially useful for recursive types.
+
+    type StructWithNilField struct {
+        Field *[3]byte `rlp:"nil"`
+    }
+
+In the example above, Field allows two possible input sizes. For input 0xC180 (a list
+containing an empty string) Field is set to nil after decoding. For input 0xC483000000 (a
+list containing a 3-byte string), Field is set to a non-nil array pointer.
+
 RLP supports two kinds of empty values: empty lists and empty strings. When using the
-"nil" tag, the kind of empty value allowed for a type is chosen automatically. A struct
-field whose Go type is a pointer to an unsigned integer, string, boolean or byte
-array/slice expects an empty RLP string. Any other pointer field type encodes/decodes as
-an empty RLP list.
+"nil" tag, the kind of empty value allowed for a type is chosen automatically. A field
+whose Go type is a pointer to an unsigned integer, string, boolean or byte array/slice
+expects an empty RLP string. Any other pointer field type encodes/decodes as an empty RLP
+list.
 
 The choice of null value can be made explicit with the "nilList" and "nilString" struct
-tags. Using these tags encodes/decodes a Go nil pointer value as the kind of empty
-RLP value defined by the tag.
+tags. Using these tags encodes/decodes a Go nil pointer value as the empty RLP value kind
+defined by the tag.
 */
 package rlp