fix description, add comments

Author: phbnf

cmd/proofgen/main.go

@@ -387,13 +387,13 @@ func subtreeInclusionProbes(rootDir string) error {
 
 func corruptedSubtreeInclusionProbes(dir string, leafIdx, treeSize uint64, proof [][]byte, root, leafHash []byte) error {
 	happyPath := inclusionProbe{leafIdx, treeSize, root, leafHash, proof, "happy path", false}
-	if err := writeSubtreeInclusionProbePair(dir, happyPath); err != nil {
+	if err := convertToSubtreeInclusionProbesAndWrite(dir, happyPath); err != nil {
 		return err
 	}
 
 	probes := invalidInclusionProof(leafIdx, treeSize, proof, root, leafHash)
 	for _, p := range probes {
-		if err := writeSubtreeInclusionProbePair(dir, p); err != nil {
+		if err := convertToSubtreeInclusionProbesAndWrite(dir, p); err != nil {
 			return err
 		}
 	}
@@ -419,7 +419,7 @@ func singleEntrySubtreeInclusionProbes(dir string) error {
 		{emptyHash, emptyHash, "empty root and leaf", true},
 	} {
 		probe := inclusionProbe{0, 1, p.root, p.leaf, proof, p.desc, p.wantErr}
-		if err := writeSubtreeInclusionProbePair(dir, probe); err != nil {
+		if err := convertToSubtreeInclusionProbesAndWrite(dir, probe); err != nil {
 			return err
 		}
 	}
@@ -441,17 +441,17 @@ func staticSubtreeInclusionProbes(rootDir string) error {
 		}
 
 		randomLeaf := inclusionProbe{p.index, p.size, []byte{}, sha256SomeHash, proof, "random leaf", true}
-		if err := writeSubtreeInclusionProbePair(dir, randomLeaf); err != nil {
+		if err := convertToSubtreeInclusionProbesAndWrite(dir, randomLeaf); err != nil {
 			return err
 		}
 
 		emptyRoot := inclusionProbe{p.index, p.size, sha256EmptyTreeHash, []byte{}, proof, "empty root", true}
-		if err := writeSubtreeInclusionProbePair(dir, emptyRoot); err != nil {
+		if err := convertToSubtreeInclusionProbesAndWrite(dir, emptyRoot); err != nil {
 			return err
 		}
 
 		emptyRootRandomLeaf := inclusionProbe{p.index, p.size, sha256EmptyTreeHash, sha256SomeHash, proof, "empty root and random leaf", true}
-		if err := writeSubtreeInclusionProbePair(dir, emptyRootRandomLeaf); err != nil {
+		if err := convertToSubtreeInclusionProbesAndWrite(dir, emptyRootRandomLeaf); err != nil {
 			return err
 		}
 	}
@@ -467,145 +467,123 @@ func errorSubtreeInclusionProbes(rootDir string) error {
 
 	leafHash := rfc6962.DefaultHasher.HashLeaf(leaves[0])
 
-	tests := []struct {
-		filename string
-		probe    subtreeInclusionProbe
-	}{
+	tests := []subtreeInclusionProbe{
 		{
-			filename: "everything-zero.json",
-			probe: subtreeInclusionProbe{
-				LeafIdx:   0,
-				Start:     0,
-				End:       0,
-				Root:      sha256EmptyTreeHash,
-				LeafHash:  leafHash,
-				Proof:     nil,
-				Desc:      "empty root",
-				WantError: true,
-			},
+			LeafIdx:   0,
+			Start:     0,
+			End:       0,
+			Root:      sha256EmptyTreeHash,
+			LeafHash:  leafHash,
+			Proof:     nil,
+			Desc:      "everything zero",
+			WantError: true,
 		},
 		{
-			filename: "start-equals-end.json",
-			probe: subtreeInclusionProbe{
-				LeafIdx:   0,
-				Start:     1,
-				End:       1,
-				Root:      sha256EmptyTreeHash,
-				LeafHash:  leafHash,
-				Proof:     nil,
-				Desc:      "empty root",
-				WantError: true,
-			},
+			LeafIdx:   0,
+			Start:     1,
+			End:       1,
+			Root:      sha256EmptyTreeHash,
+			LeafHash:  leafHash,
+			Proof:     nil,
+			Desc:      "start equals end",
+			WantError: true,
 		},
 		{
-			filename: "invalid-subtree.json",
-			probe: subtreeInclusionProbe{
-				LeafIdx:   3,
-				Start:     3,
-				End:       5,
-				Root:      sha256EmptyTreeHash,
-				LeafHash:  leafHash,
-				Proof:     nil,
-				Desc:      "empty root",
-				WantError: true,
-			},
+			LeafIdx:   3,
+			Start:     3,
+			End:       5,
+			Root:      sha256EmptyTreeHash,
+			LeafHash:  leafHash,
+			Proof:     nil,
+			Desc:      "invalid subtree",
+			WantError: true,
 		},
 		{
-			filename: "invalid-large-subtree.json",
-			probe: subtreeInclusionProbe{
-				LeafIdx:   1,
-				Start:     1,
-				End:       9223372036854775810,
-				Root:      sha256EmptyTreeHash,
-				LeafHash:  leafHash,
-				Proof:     nil,
-				Desc:      "empty root",
-				WantError: true,
-			},
+			LeafIdx:   1,
+			Start:     1,
+			End:       9223372036854775810,
+			Root:      sha256EmptyTreeHash,
+			LeafHash:  leafHash,
+			Proof:     nil,
+			Desc:      "invalid large subtree",
+			WantError: true,
 		},
 		{
-			filename: "oob-left.json",
-			probe: subtreeInclusionProbe{
-				LeafIdx:   0,
-				Start:     1,
-				End:       2,
-				Root:      sha256EmptyTreeHash,
-				LeafHash:  leafHash,
-				Proof:     nil,
-				Desc:      "empty root",
-				WantError: true,
-			},
+			LeafIdx:   0,
+			Start:     1,
+			End:       2,
+			Root:      sha256EmptyTreeHash,
+			LeafHash:  leafHash,
+			Proof:     nil,
+			Desc:      "oob left",
+			WantError: true,
 		},
 		{
-			filename: "oob-right.json",
-			probe: subtreeInclusionProbe{
-				LeafIdx:   3,
-				Start:     0,
-				End:       2,
-				Root:      sha256EmptyTreeHash,
-				LeafHash:  leafHash,
-				Proof:     nil,
-				Desc:      "empty root",
-				WantError: true,
-			},
+			LeafIdx:   3,
+			Start:     0,
+			End:       2,
+			Root:      sha256EmptyTreeHash,
+			LeafHash:  leafHash,
+			Proof:     nil,
+			Desc:      "oob right",
+			WantError: true,
 		},
 		{
-			filename: "oob-right-2.json",
-			probe: subtreeInclusionProbe{
-				LeafIdx:   3,
-				Start:     0,
-				End:       3,
-				Root:      sha256EmptyTreeHash,
-				LeafHash:  leafHash,
-				Proof:     nil,
-				Desc:      "empty root",
-				WantError: true,
-			},
+			LeafIdx:   3,
+			Start:     0,
+			End:       3,
+			Root:      sha256EmptyTreeHash,
+			LeafHash:  leafHash,
+			Proof:     nil,
+			Desc:      "oob right 2",
+			WantError: true,
 		},
 		{
-			filename: "start-larger-than-end.json",
-			probe: subtreeInclusionProbe{
-				LeafIdx:   0,
-				Start:     2,
-				End:       1,
-				Root:      sha256EmptyTreeHash,
-				LeafHash:  leafHash,
-				Proof:     nil,
-				Desc:      "empty root",
-				WantError: true,
-			},
+			LeafIdx:   0,
+			Start:     2,
+			End:       1,
+			Root:      sha256EmptyTreeHash,
+			LeafHash:  leafHash,
+			Proof:     nil,
+			Desc:      "start larger than end",
+			WantError: true,
 		},
 	}
 
 	for _, tc := range tests {
-		if err := writeSubtreeInclusionProbeWithFilename(dir, tc.filename, tc.probe); err != nil {
+		if err := writeSubtreeInclusionProbe(dir, tc); err != nil {
 			return err
 		}
 	}
 
 	return nil
 }
 
-func writeSubtreeInclusionProbeWithFilename(dir, filename string, probe subtreeInclusionProbe) error {
+func writeSubtreeInclusionProbe(dir string, probe subtreeInclusionProbe) error {
+	fn := fileName(probe.Desc)
+
 	probeJson, err := json.MarshalIndent(probe, "", "  ")
 	if err != nil {
 		return fmt.Errorf("marshaling probe: %s", err)
 	}
 
-	fileLocation := filepath.Join(dir, filename)
+	fileLocation := filepath.Join(dir, fn)
 	if err := os.WriteFile(fileLocation, probeJson, 0644); err != nil {
-		return fmt.Errorf("writing probe: %s: %s", filename, err)
+		return fmt.Errorf("writing probe: %s: %s", fn, err)
 	}
 
 	return nil
 }
 
-func writeSubtreeInclusionProbe(dir string, probe subtreeInclusionProbe) error {
-	fn := fileName(probe.Desc)
-	return writeSubtreeInclusionProbeWithFilename(dir, fn, probe)
-}
-
-func writeSubtreeInclusionProbePair(dir string, p inclusionProbe) error {
+// convertToSubtreeInclusionProbesAndWrite generates subtree inclusion proofs
+// from inclusion proofs and writes them.
+//
+// An inclusion proof for an entry at index in a tree of a given size leads to
+// two subtree inclusion proofs:
+//   - one for for an entry at index in a subtree of the same given size.
+//   - a second one for an entry shifted by bitCeil(size) for the subtree
+//     [bitCeil(size), size+bitCeil(size)).
+func convertToSubtreeInclusionProbesAndWrite(dir string, p inclusionProbe) error {
 	sp1 := toSubtreeInclusionProbe(p)
 	if err := writeSubtreeInclusionProbe(dir, sp1); err != nil {
 		return err

testdata/subtreeinclusion/errors/everything-zero.json

@@ -5,6 +5,6 @@
   "root": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=",
   "leafHash": "bjQLnP+zepicpUTmu3gKLHiQHT+zNzh2hRGjBhevoB0=",
   "proof": null,
-  "desc": "empty root",
+  "desc": "everything zero",
   "wantErr": true
 }

testdata/subtreeinclusion/errors/invalid-large-subtree.json

@@ -5,6 +5,6 @@
   "root": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=",
   "leafHash": "bjQLnP+zepicpUTmu3gKLHiQHT+zNzh2hRGjBhevoB0=",
   "proof": null,
-  "desc": "empty root",
+  "desc": "invalid large subtree",
   "wantErr": true
 }

testdata/subtreeinclusion/errors/invalid-subtree.json

@@ -5,6 +5,6 @@
   "root": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=",
   "leafHash": "bjQLnP+zepicpUTmu3gKLHiQHT+zNzh2hRGjBhevoB0=",
   "proof": null,
-  "desc": "empty root",
+  "desc": "invalid subtree",
   "wantErr": true
 }

testdata/subtreeinclusion/errors/oob-left.json

@@ -5,6 +5,6 @@
   "root": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=",
   "leafHash": "bjQLnP+zepicpUTmu3gKLHiQHT+zNzh2hRGjBhevoB0=",
   "proof": null,
-  "desc": "empty root",
+  "desc": "oob left",
   "wantErr": true
 }

testdata/subtreeinclusion/errors/oob-right-2.json

@@ -5,6 +5,6 @@
   "root": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=",
   "leafHash": "bjQLnP+zepicpUTmu3gKLHiQHT+zNzh2hRGjBhevoB0=",
   "proof": null,
-  "desc": "empty root",
+  "desc": "oob right 2",
   "wantErr": true
 }

testdata/subtreeinclusion/errors/oob-right.json

@@ -5,6 +5,6 @@
   "root": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=",
   "leafHash": "bjQLnP+zepicpUTmu3gKLHiQHT+zNzh2hRGjBhevoB0=",
   "proof": null,
-  "desc": "empty root",
+  "desc": "oob right",
   "wantErr": true
 }

testdata/subtreeinclusion/errors/start-equals-end.json

@@ -5,6 +5,6 @@
   "root": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=",
   "leafHash": "bjQLnP+zepicpUTmu3gKLHiQHT+zNzh2hRGjBhevoB0=",
   "proof": null,
-  "desc": "empty root",
+  "desc": "start equals end",
   "wantErr": true
 }

testdata/subtreeinclusion/errors/start-larger-than-end.json

@@ -5,6 +5,6 @@
   "root": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=",
   "leafHash": "bjQLnP+zepicpUTmu3gKLHiQHT+zNzh2hRGjBhevoB0=",
   "proof": null,
-  "desc": "empty root",
+  "desc": "start larger than end",
   "wantErr": true
 }