Merge pull request #168 from keep-network/implementation-details-rng

Select A Random Group

Author: pdyraga

docs/implementation-details.md

@@ -176,4 +176,92 @@ For an in-depth explanation of how this information is structured, refer to the
 Serialization](#branch-and-root-deserialization-and-serialization) section.
 
 TODO: Joining and Leaving The Pool
-TODO: Selecting A Random Group
+
+### Selecting A Random Group
+
+To select a random group of of operators from the pool size `N`, we construct
+an array of size `N` to house the result, and then populate it, one random
+operator at a time, with replacement.
+
+We start with a seed provided from the [random
+beacon](https://github.com/keep-network/keep-core/tree/main/solidity/random-beacon)
+and use that seed in combination with the total weight of the root node,
+calculatable by summing the weight of the slots: see [Branch And Root
+Deserialization And
+Serialization](#branch-and-root-deserialization-and-serialization) to generate
+a random uniform integer in `[0, root.totalWeight)`, as well as the next random
+seed for the next random operator. In order to generate this next random seed,
+we're using 
+```
+newState = keccak256(abi.encodePacked(newState, address(this)));
+```
+which, according to [A Pseudorandom Number Generator with KECCAK Hash Function
+by A. Gholipour and S. Mirzakuchak](http://www.ijcee.org/papers/439-JE503.pdf),
+has "excellent pseudo randomness".
+
+Once we have our random integer, we are able to descend down the tree according
+to the algorithm outlined in [building intuition](building-intuition.md).
+
+```
+function pickWeightedLeaf(uint256 index, uint256 _root)
+  internal
+  view
+  returns (uint256 leafPosition)
+{
+  uint256 currentIndex = index;
+  uint256 currentNode = _root;
+  uint256 currentPosition = 0;
+  uint256 currentSlot;
+
+  require(index < currentNode.sumWeight(), "Index exceeds weight");
+
+  // get root slot
+  (currentSlot, currentIndex) = currentNode.pickWeightedSlot(currentIndex);
+
+  // get slots from levels 2 to 7
+  for (uint256 level = 2; level <= LEVELS; level++) {
+    currentPosition = currentPosition.child(currentSlot);
+    currentNode = branches[level][currentPosition];
+    (currentSlot, currentIndex) = currentNode.pickWeightedSlot(currentIndex);
+  }
+
+  // get leaf position
+  leafPosition = currentPosition.child(currentSlot);
+}
+
+function pickWeightedSlot(uint256 node, uint256 index)
+  internal
+  pure
+  returns (uint256 slot, uint256 newIndex)
+{
+  unchecked {
+    newIndex = index;
+    uint256 newNode = node;
+    uint256 currentSlotWeight = newNode & SLOT_MAX;
+    while (newIndex >= currentSlotWeight) {
+      newIndex -= currentSlotWeight;
+      slot++;
+      newNode = newNode >> SLOT_WIDTH;
+      currentSlotWeight = newNode & SLOT_MAX;
+    }
+    return (slot, newIndex);
+  }
+}
+```
+
+At a particular root/branch node, we inspect the right-most 32 bits by applying
+a bitwise `&` against `2^32 - 1`, which leaves only the last 32 bits as
+potentially non-zero.
+
+If this quantity if greater than our random number, we found our path of
+descent and repeat the process at the next layer. If it isn't, then we increase
+our slot counter, decrease our random number by the quantity, and shift our
+number over 32 bits to the right and repeat.
+
+Eventually we will find a slot that exceeds our random number and be able to
+descend to the next layer where the process repeats until we get to the leaf
+layer where the task is finished.
+
+We record our chosen operator in the result list, use the fresh seed from
+`keccak256` to generate a new random number and new seed, and repeat until we
+have a full group.