Merge pull request #17 from alxmirap/master

Adds test vectors for the Fisher-Yates Shuffling function.

Author: gavofyork

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.
+
+Note: All gray paper references in this document are to version 0.4.3, October 21st 2024.
+
+## 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 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,109 @@
+#!/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 uniform_seed(n):
+    return [n] * 32
+
+def linear_seed():
+    return [i for i in range(32)]
+
+def varied_seed(n):
+    # large 32 bit prime
+    large_prime = 2147483647 
+    result = []
+    next = n % large_prime
+
+    # next is always a 32-bit prime, so it fits in 4 bytes.
+    # this loop generates a cycle of modular exponents of a generator.
+    # if this generator is unknown, this cycle is in practice unpredictable,
+    # so this should generate a sequence that looks a bit like random
+    # and should be enough for simple tests.
+    for i in range(8):
+        result = result + list(to_le_bytes(next, 4))
+        next = next * n % large_prime
+    
+    return result
+
+def inputs_Eq331():
+    zero_seed = uniform_seed(0)
+    ff_seed = uniform_seed(255)
+    simple_seed = linear_seed()
+    irregular_seed = varied_seed(1_000_000_000_000)
+
+    yield(number_vector(0), zero_seed)
+    yield(number_vector(8), ff_seed)
+    yield(number_vector(16), simple_seed)
+    yield(number_vector(20), irregular_seed)
+
+    yield(number_vector(50), zero_seed)
+    yield(number_vector(100), ff_seed)
+    yield(number_vector(200), simple_seed)
+    yield(number_vector(341), irregular_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()