From 72874d447ad7277c12563eabf10210801ebc84ed Mon Sep 17 00:00:00 2001 From: Sergey Timoshin Date: Tue, 2 Apr 2024 15:04:25 +0100 Subject: [PATCH] Add documentation about test-data generation. --- gnark-prover/merkle-tree/tree_test.go | 88 ++++++++++++++++++++++++++- 1 file changed, 87 insertions(+), 1 deletion(-) diff --git a/gnark-prover/merkle-tree/tree_test.go b/gnark-prover/merkle-tree/tree_test.go index 19bb18040c..0a8343feee 100644 --- a/gnark-prover/merkle-tree/tree_test.go +++ b/gnark-prover/merkle-tree/tree_test.go @@ -93,7 +93,7 @@ func TestCombined(t *testing.T) { InclusionParameters: tree1, NonInclusionParameters: tree2, } - // print the combined parameters + var json, err2 = combinedParams.MarshalJSON() if err2 != nil { t.Errorf("Error marshalling JSON: %v", err) @@ -142,6 +142,47 @@ type InclusionTreeValidPair struct { Valid bool } +// Function +// +// `MakeTestIncludedTrees` +// +// ```go +// func MakeTestIncludedTrees(depth int, numberOfUtxos int) []InclusionTreeValidPair +// ``` +// +// # Description +// +// The `MakeTestIncludedTrees` function creates an array of InclusionTreeValidPair instances for testing. +// The variation between valid and invalid trees helps simulate real-world scenarios and assists in better +// testing for robustness and error-handling. +// +// Parameters: +// +// - `depth (int)`: Defines the depth of each included tree. +// - `numberOfUtxos (int)`: Number of unspent transaction outputs (UTXOs) to include in each tree. +// +// Returns: +// - `[]InclusionTreeValidPair`: An array of `InclusionTreeValidPair` instances, each containing +// an `InclusionParameters` instance and a boolean value indicating whether the tree is valid. +// +// Pairs Explanation: +// +// - `validPair`: A valid tree constructed with input parameters. The Valid field is set to `true`. +// - `invalidRootPair`: A valid tree but the root value is invalidated by setting it to an integer 999. The Valid field is set to `false`. +// - `invalidLeafPair`: A valid tree where a leaf value is invalidated by setting it to an integer 999. The Valid field is set to `false`. +// - `invalidInPathIndicesPair`: A valid tree but the InPathIndices value is invalidated by setting it to an integer 999. The Valid field is set to `false`. +// - `invalidInPathElementsPair`: A valid tree where the InPathElements is invalidated by setting a value to an integer 999. The Valid field is set to `false`. +// +// Example usage: +// +// ```go +// trees := MakeTestIncludedTrees(4, 2) +// +// for _, tree := range trees { +// // perform operations on tree +// } +// +// ``` func MakeTestIncludedTrees(depth int, numberOfUtxos int) []InclusionTreeValidPair { var trees []InclusionTreeValidPair @@ -177,6 +218,51 @@ type NonInclusionTreeValidPair struct { Valid bool } +// Function +// +// `MakeTestNonInclusionTrees` +// +// ```go +// func MakeTestNonInclusionTrees(depth int, numberOfUtxos int) []NonInclusionTreeValidPair +// ``` +// +// # Description +// +// The `MakeTestNonInclusionTrees` function creates an array of `NonInclusionTreeValidPair` instances for testing. These instances include various valid and invalid cases to simulate diverse scenarios and strengthen code robustness and error handling. This function helps in creating a testing environment that closely mimics a variety of real-world scenarios. +// +// # Parameters +// +// - `depth (int)`: Defines the depth of each included tree. +// - `numberOfUtxos (int)`: Number of unspent transaction outputs (UTXOs) to include in each tree. +// +// # Returns +// +// - `[]NonInclusionTreeValidPair`: An array of `NonInclusionTreeValidPair` instances, each containing an `InclusionParameters` instance and a boolean value indicating whether the tree is valid. +// +// # Pairs Explanation +// +// - `validPair`: A tree constructed with input parameters. The `Valid` field is set to `true`. +// +// - `invalidRootPair`: A valid tree but the root value is invalidated by setting it to an integer 999. The `Valid` field is set to `false`. +// +// - `invalidLowValuePair`: An invalid tree with a low value. The `Valid` field is set to `false`. +// +// - `invalidHighValuePair`: An invalid tree with a high value. The `Valid` field is set to `false`. +// +// - `invalidInPathIndicesPair`: A valid tree but the `InPathIndices` value is invalidated by setting it to an integer 999. The `Valid` field is set to `false`. +// +// - `invalidInPathElementsPair`: A valid tree where the `InPathElements` are invalidated by an integer 999. The `Valid` field is set to `false`. +// +// # Example Usage +// +// ```go +// trees := MakeTestNonInclusionTrees(4, 2) +// +// for _, tree := range trees { +// // perform operations on tree +// } +// +// ``` func MakeTestNonInclusionTrees(depth int, numberOfUtxos int) []NonInclusionTreeValidPair { var trees []NonInclusionTreeValidPair