Adds test vectors for the Shuffling function.

Together with README and a generating script.

Author: alxmirap

shuffle/README.md

@@ -0,0 +1,32 @@
+# Fisher-Yates Shuffle function test vectors
+
+We offer test vectors for the implementation of the shuffle function as described in Appendix F of the Gray Paper.
+This section presents two definitions, a recursive one that uses an integer sequence as random seeds in Eq 329, and one (Eq 331) which takes a 32-byte hash as entropy, and is defined in terms of the previous one.
+
+The implementation of Eq 329 is not generally used in the Gray Paper, and so we present test vectors only for the version of Eq 331. However, the present script creates these test cases with recourse to the Eq 329 implementation, to reproduce exactly the definition of the Gray Paper.
+
+## Notes about test parameters
+
+In every case, the output must be a permutation of the input sequence, and this is checked by the generating script.
+In the GP, at the moment, this function is used only to shuffle sequences of validators or cores, both of which are identified by integers. For that reason, all test cases use integers as the input type. All the input elements are distinct to ensure the final positions of each element are unambiguously determined.
+
+All test cases use the same entropy, which is a 32-byte sequence with values from 0 to 31.
+
+All the inputs to each test case are integer sequences, ranging from 0 to n-1, where n is the length. The test cases are described only by the entropy and the length of the input, and so the actual input sequence has to be recreated when using these test cases.
+
+## Test vectors
+
+The following test cases are given:
+- 0
+- 8
+- 16
+- 20
+- 50
+- 100
+- 200
+- 341
+
+Each test case has this format is a Json object with 3 fields:
+* **[input]**: the length of the input sequence
+* **[entropy]**: a hex-string description of the 32 bytes used for entropy
+* **[output]**: an array containing the shuffled input sequence

shuffle/main.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+
+import hashlib
+import json
+import sys
+
+def hash(data):
+    return hashlib.blake2b(data, digest_size=32).digest()
+
+def hex(data):
+    return ''.join(f'{x:02x}' for x in data)
+
+def compute_shuffle_eq329(s, r):
+    if len(s) > 0:
+        l = len(s)
+        index = r[0] % l
+        head = s[index]
+
+        s_post = s.copy()
+        s_post[index] = s[l-1]
+
+        return [head] + compute_shuffle_eq329(s_post[:-1], r[1:])
+    else:
+        return []
+
+def number_vector(n): 
+    return [x for x in range(n)]
+
+def default_seed():
+    return [i for i in range(32)]
+
+def inputs_Eq331():
+    seed = default_seed()
+
+    yield(number_vector(0), seed)
+    yield(number_vector(8), seed)
+    yield(number_vector(16), seed)
+    yield(number_vector(20), seed)
+
+    yield(number_vector(50), seed)
+    yield(number_vector(100), seed)
+    yield(number_vector(200), seed)
+    yield(number_vector(341), seed)
+
+
+def to_le_bytes(n, k):
+    return n.to_bytes(k, 'little')
+
+def from_le_bytes(b):
+    return int.from_bytes(b, 'little')
+
+def compute_q(h, l):
+    result = []
+    for i in range(l):  
+        preimage = bytes(h.copy()) + to_le_bytes(i // 8, 4)
+        offset = 4*i % 32
+        slice = hash(preimage)[offset:offset + 4] 
+        result.append(from_le_bytes(slice))
+
+    return result
+
+def compute_shuffle_eq331(s, h):
+    l = len(s)
+    r = compute_q(h, l)
+
+    return compute_shuffle_eq329(s, r)
+
+def is_permutation(list1, list2):
+    return set(list1) == set(list2)
+
+def test_vectors_eq331():
+    for term in inputs_Eq331():
+        s, r = term
+        output = compute_shuffle_eq331(s, r)
+        assert(is_permutation(s, output))
+
+        yield {
+            'input': len(s),
+            'entropy': hex(r),
+            'output': output,
+        }
+
+def main():
+    json.dump(list(test_vectors_eq331()), sys.stdout, indent='    ')
+
+main()