feat(trie): Implement parity trie crate

internal/trie/node/children.go

@@ -40,3 +40,7 @@ func (n *Node) HasChild() (has bool) {
 	}
 	return false
 }
+
+func (n *Node) ChildAt(i uint) *Node {
+	return n.Children[i]
+}

internal/trie/node/decode.go

@@ -25,6 +25,8 @@ var (
 	ErrDecodeChildHash = errors.New("cannot decode child hash")
 )
 
+var EmptyNode = &Node{}
+
 const hashLength = common.HashLength
 
 // Decode decodes a node from a reader.
@@ -34,21 +36,21 @@ const hashLength = common.HashLength
 // For branch decoding, see the comments on decodeBranch.
 // For leaf decoding, see the comments on decodeLeaf.
 func Decode(reader io.Reader) (n *Node, err error) {
-	variant, partialKeyLength, err := decodeHeader(reader)
+	variant, partialKeyLength, err := DecodeHeader(reader)
 	if err != nil {
 		return nil, fmt.Errorf("decoding header: %w", err)
 	}
 
 	switch variant {
-	case emptyVariant:
-		return nil, nil //nolint:nilnil
-	case leafVariant, leafWithHashedValueVariant:
+	case EmptyVariant:
+		return EmptyNode, nil
+	case LeafVariant, LeafWithHashedValueVariant:
 		n, err = decodeLeaf(reader, variant, partialKeyLength)
 		if err != nil {
 			return nil, fmt.Errorf("cannot decode leaf: %w", err)
 		}
 		return n, nil
-	case branchVariant, branchWithValueVariant, branchWithHashedValueVariant:
+	case BranchVariant, BranchWithValueVariant, BranchWithHashedValueVariant:
 		n, err = decodeBranch(reader, variant, partialKeyLength)
 		if err != nil {
 			return nil, fmt.Errorf("cannot decode branch: %w", err)
@@ -65,13 +67,13 @@ func Decode(reader io.Reader) (n *Node, err error) {
 // reconstructing the child nodes from the encoding. This function instead stubs where the
 // children are known to be with an empty leaf. The children nodes hashes are then used to
 // find other storage values using the persistent database.
-func decodeBranch(reader io.Reader, variant variant, partialKeyLength uint16) (
+func decodeBranch(reader io.Reader, variant Variant, partialKeyLength uint16) (
 	node *Node, err error) {
 	node = &Node{
 		Children: make([]*Node, ChildrenCapacity),
 	}
 
-	node.PartialKey, err = decodeKey(reader, partialKeyLength)
+	node.PartialKey, err = DecodeKey(reader, partialKeyLength)
 	if err != nil {
 		return nil, fmt.Errorf("cannot decode key: %w", err)
 	}
@@ -85,12 +87,12 @@ func decodeBranch(reader io.Reader, variant variant, partialKeyLength uint16) (
 	sd := scale.NewDecoder(reader)
 
 	switch variant {
-	case branchWithValueVariant:
+	case BranchWithValueVariant:
 		err := sd.Decode(&node.StorageValue)
 		if err != nil {
 			return nil, fmt.Errorf("%w: %s", ErrDecodeStorageValue, err)
 		}
-	case branchWithHashedValueVariant:
+	case BranchWithHashedValueVariant:
 		hashedValue, err := decodeHashedValue(reader)
 		if err != nil {
 			return nil, err
@@ -134,17 +136,17 @@ func decodeBranch(reader io.Reader, variant variant, partialKeyLength uint16) (
 }
 
 // decodeLeaf reads from a reader and decodes to a leaf node.
-func decodeLeaf(reader io.Reader, variant variant, partialKeyLength uint16) (node *Node, err error) {
+func decodeLeaf(reader io.Reader, variant Variant, partialKeyLength uint16) (node *Node, err error) {
 	node = &Node{}
 
-	node.PartialKey, err = decodeKey(reader, partialKeyLength)
+	node.PartialKey, err = DecodeKey(reader, partialKeyLength)
 	if err != nil {
 		return nil, fmt.Errorf("cannot decode key: %w", err)
 	}
 
 	sd := scale.NewDecoder(reader)
 
-	if variant == leafWithHashedValueVariant {
+	if variant == LeafWithHashedValueVariant {
 		hashedValue, err := decodeHashedValue(reader)
 		if err != nil {
 			return nil, err

internal/trie/node/decode_test.go

@@ -59,12 +59,12 @@ func Test_Decode(t *testing.T) {
 			errMessage: "decoding header: decoding header byte: node variant is unknown: for header byte 00001000",
 		},
 		"empty_node": {
-			reader: bytes.NewReader([]byte{emptyVariant.bits}),
-			n:      nil,
+			reader: bytes.NewReader([]byte{EmptyVariant.bits}),
+			n:      EmptyNode,
 		},
 		"leaf_decoding_error": {
 			reader: bytes.NewReader([]byte{
-				leafVariant.bits | 1, // key length 1
+				LeafVariant.bits | 1, // key length 1
 				// missing key data byte
 			}),
 			errWrapped: io.EOF,
@@ -73,7 +73,7 @@ func Test_Decode(t *testing.T) {
 		},
 		"leaf_success": {
 			reader: bytes.NewReader(concatByteSlices([][]byte{
-				{leafVariant.bits | 1}, // partial key length 1
+				{LeafVariant.bits | 1}, // partial key length 1
 				{9},                    // key data
 				scaleEncodeBytes(t, 1, 2, 3),
 			})),
@@ -84,7 +84,7 @@ func Test_Decode(t *testing.T) {
 		},
 		"branch_decoding_error": {
 			reader: bytes.NewReader([]byte{
-				branchVariant.bits | 1, // key length 1
+				BranchVariant.bits | 1, // key length 1
 				// missing key data byte
 			}),
 			errWrapped: io.EOF,
@@ -93,7 +93,7 @@ func Test_Decode(t *testing.T) {
 		},
 		"branch_success": {
 			reader: bytes.NewReader(concatByteSlices([][]byte{
-				{branchVariant.bits | 1},   // partial key length 1
+				{BranchVariant.bits | 1},   // partial key length 1
 				{9},                        // key data
 				{0b0000_0000, 0b0000_0000}, // no children bitmap
 			})),
@@ -104,7 +104,7 @@ func Test_Decode(t *testing.T) {
 		},
 		"leaf_with_hashed_value_success": {
 			reader: bytes.NewReader(concatByteSlices([][]byte{
-				{leafWithHashedValueVariant.bits | 1}, // partial key length 1
+				{LeafWithHashedValueVariant.bits | 1}, // partial key length 1
 				{9},                                   // key data
 				hashedValue.ToBytes(),
 			})),
@@ -116,7 +116,7 @@ func Test_Decode(t *testing.T) {
 		},
 		"leaf_with_hashed_value_fail_too_short": {
 			reader: bytes.NewReader(concatByteSlices([][]byte{
-				{leafWithHashedValueVariant.bits | 1}, // partial key length 1
+				{LeafWithHashedValueVariant.bits | 1}, // partial key length 1
 				{9},                                   // key data
 				{0b0000_0000},                         // less than 32bytes
 			})),
@@ -125,7 +125,7 @@ func Test_Decode(t *testing.T) {
 		},
 		"branch_with_hashed_value_success": {
 			reader: bytes.NewReader(concatByteSlices([][]byte{
-				{branchWithHashedValueVariant.bits | 1}, // partial key length 1
+				{BranchWithHashedValueVariant.bits | 1}, // partial key length 1
 				{9},                                     // key data
 				{0b0000_0000, 0b0000_0000},              // no children bitmap
 				hashedValue.ToBytes(),
@@ -139,7 +139,7 @@ func Test_Decode(t *testing.T) {
 		},
 		"branch_with_hashed_value_fail_too_short": {
 			reader: bytes.NewReader(concatByteSlices([][]byte{
-				{branchWithHashedValueVariant.bits | 1}, // partial key length 1
+				{BranchWithHashedValueVariant.bits | 1}, // partial key length 1
 				{9},                                     // key data
 				{0b0000_0000, 0b0000_0000},              // no children bitmap
 				{0b0000_0000},
@@ -177,7 +177,7 @@ func Test_decodeBranch(t *testing.T) {
 
 	testCases := map[string]struct {
 		reader           io.Reader
-		nodeVariant      variant
+		nodeVariant      Variant
 		partialKeyLength uint16
 		branch           *Node
 		errWrapped       error
@@ -187,7 +187,7 @@ func Test_decodeBranch(t *testing.T) {
 			reader: bytes.NewBuffer([]byte{
 				// missing key data byte
 			}),
-			nodeVariant:      branchVariant,
+			nodeVariant:      BranchVariant,
 			partialKeyLength: 1,
 			errWrapped:       io.EOF,
 			errMessage:       "cannot decode key: reading from reader: EOF",
@@ -197,7 +197,7 @@ func Test_decodeBranch(t *testing.T) {
 				9, // key data
 				// missing children bitmap 2 bytes
 			}),
-			nodeVariant:      branchVariant,
+			nodeVariant:      BranchVariant,
 			partialKeyLength: 1,
 			errWrapped:       ErrReadChildrenBitmap,
 			errMessage:       "cannot read children bitmap: EOF",
@@ -208,7 +208,7 @@ func Test_decodeBranch(t *testing.T) {
 				0, 4, // children bitmap
 				// missing children scale encoded data
 			}),
-			nodeVariant:      branchVariant,
+			nodeVariant:      BranchVariant,
 			partialKeyLength: 1,
 			errWrapped:       ErrDecodeChildHash,
 			errMessage:       "cannot decode child hash: at index 10: reading byte: EOF",
@@ -221,7 +221,7 @@ func Test_decodeBranch(t *testing.T) {
 					scaleEncodedChildHash,
 				}),
 			),
-			nodeVariant:      branchVariant,
+			nodeVariant:      BranchVariant,
 			partialKeyLength: 1,
 			branch: &Node{
 				PartialKey: []byte{9},
@@ -243,7 +243,7 @@ func Test_decodeBranch(t *testing.T) {
 					// missing encoded branch storage value
 				}),
 			),
-			nodeVariant:      branchWithValueVariant,
+			nodeVariant:      BranchWithValueVariant,
 			partialKeyLength: 1,
 			errWrapped:       ErrDecodeStorageValue,
 			errMessage:       "cannot decode storage value: reading byte: EOF",
@@ -255,7 +255,7 @@ func Test_decodeBranch(t *testing.T) {
 				scaleEncodeBytes(t, 7, 8, 9), // branch storage value
 				scaleEncodedChildHash,
 			})),
-			nodeVariant:      branchWithValueVariant,
+			nodeVariant:      BranchWithValueVariant,
 			partialKeyLength: 1,
 			branch: &Node{
 				PartialKey:   []byte{9},
@@ -277,7 +277,7 @@ func Test_decodeBranch(t *testing.T) {
 				scaleEncodeBytes(t, 1),     // branch storage value
 				{0},                        // garbage inlined node
 			})),
-			nodeVariant:      branchWithValueVariant,
+			nodeVariant:      BranchWithValueVariant,
 			partialKeyLength: 1,
 			errWrapped:       io.EOF,
 			errMessage: "decoding inlined child at index 0: " +
@@ -289,25 +289,25 @@ func Test_decodeBranch(t *testing.T) {
 				{0b0000_0011, 0b0000_0000}, // children bitmap
 				// top level inlined leaf less than 32 bytes
 				scaleEncodeByteSlice(t, concatByteSlices([][]byte{
-					{leafVariant.bits | 1}, // partial key length of 1
+					{LeafVariant.bits | 1}, // partial key length of 1
 					{2},                    // key data
 					scaleEncodeBytes(t, 2), // storage value data
 				})),
 				// top level inlined branch less than 32 bytes
 				scaleEncodeByteSlice(t, concatByteSlices([][]byte{
-					{branchWithValueVariant.bits | 1}, // partial key length of 1
+					{BranchWithValueVariant.bits | 1}, // partial key length of 1
 					{3},                               // key data
 					{0b0000_0001, 0b0000_0000},        // children bitmap
 					scaleEncodeBytes(t, 3),            // branch storage value
 					// bottom level leaf
 					scaleEncodeByteSlice(t, concatByteSlices([][]byte{
-						{leafVariant.bits | 1}, // partial key length of 1
+						{LeafVariant.bits | 1}, // partial key length of 1
 						{4},                    // key data
 						scaleEncodeBytes(t, 4), // storage value data
 					})),
 				})),
 			})),
-			nodeVariant:      branchVariant,
+			nodeVariant:      BranchVariant,
 			partialKeyLength: 1,
 			branch: &Node{
 				PartialKey:  []byte{1},
@@ -349,7 +349,7 @@ func Test_decodeLeaf(t *testing.T) {
 
 	testCases := map[string]struct {
 		reader           io.Reader
-		variant          variant
+		variant          Variant
 		partialKeyLength uint16
 		leaf             *Node
 		errWrapped       error
@@ -359,7 +359,7 @@ func Test_decodeLeaf(t *testing.T) {
 			reader: bytes.NewBuffer([]byte{
 				// missing key data byte
 			}),
-			variant:          leafVariant,
+			variant:          LeafVariant,
 			partialKeyLength: 1,
 			errWrapped:       io.EOF,
 			errMessage:       "cannot decode key: reading from reader: EOF",
@@ -369,7 +369,7 @@ func Test_decodeLeaf(t *testing.T) {
 				{9},        // key data
 				{255, 255}, // bad storage value data
 			})),
-			variant:          leafVariant,
+			variant:          LeafVariant,
 			partialKeyLength: 1,
 			errWrapped:       ErrDecodeStorageValue,
 			errMessage:       "cannot decode storage value: unknown prefix for compact uint: 255",
@@ -379,7 +379,7 @@ func Test_decodeLeaf(t *testing.T) {
 				9, // key data
 				// missing storage value data
 			}),
-			variant:          leafVariant,
+			variant:          LeafVariant,
 			partialKeyLength: 1,
 			errWrapped:       ErrDecodeStorageValue,
 			errMessage:       "cannot decode storage value: reading byte: EOF",
@@ -389,7 +389,7 @@ func Test_decodeLeaf(t *testing.T) {
 				{9},                               // key data
 				scaleEncodeByteSlice(t, []byte{}), // results to []byte{0}
 			})),
-			variant:          leafVariant,
+			variant:          LeafVariant,
 			partialKeyLength: 1,
 			leaf: &Node{
 				PartialKey:   []byte{9},
@@ -401,7 +401,7 @@ func Test_decodeLeaf(t *testing.T) {
 				{9},                                // key data
 				scaleEncodeBytes(t, 1, 2, 3, 4, 5), // storage value data
 			})),
-			variant:          leafVariant,
+			variant:          LeafVariant,
 			partialKeyLength: 1,
 			leaf: &Node{
 				PartialKey:   []byte{9},

internal/trie/node/encode_decode_test.go

@@ -121,7 +121,7 @@ func Test_Branch_Encode_Decode(t *testing.T) {
 			err := testCase.branchToEncode.Encode(buffer)
 			require.NoError(t, err)
 
-			nodeVariant, partialKeyLength, err := decodeHeader(buffer)
+			nodeVariant, partialKeyLength, err := DecodeHeader(buffer)
 			require.NoError(t, err)
 
 			resultBranch, err := decodeBranch(buffer, nodeVariant, partialKeyLength)