chore: changelog, natspec decorators

Author: jaybuidl

contracts/CHANGELOG.md

@@ -16,6 +16,8 @@ The format is based on [Common Changelog](https://common-changelog.org/).
 - Make the primary VRF-based RNG fall back to `BlockhashRNG` if the VRF request is not fulfilled within a timeout ([#2054](https://github.com/kleros/kleros-v2/issues/2054))
 - Authenticate the calls to the RNGs to prevent 3rd parties from depleting the Chainlink VRF subscription funds ([#2054](https://github.com/kleros/kleros-v2/issues/2054))
 - Use `block.timestamp` rather than `block.number` for `BlockhashRNG` for better reliability on Arbitrum as block production is sporadic depending on network conditions. ([#2054](https://github.com/kleros/kleros-v2/issues/2054))
+- Replace the `bytes32 _key` parameter in `SortitionTrees.createTree()` and `SortitionTrees.draw()` by `uint96 courtID` ([#2113](https://github.com/kleros/kleros-v2/issues/2113))
+- Extract the sortition sum trees logic into a library `SortitionTrees` ([#2113](https://github.com/kleros/kleros-v2/issues/2113))
 - Set the Hardhat Solidity version to v0.8.30 and enable the IR pipeline ([#2069](https://github.com/kleros/kleros-v2/issues/2069))
 - Set the Foundry Solidity version to v0.8.30 and enable the IR pipeline ([#2073](https://github.com/kleros/kleros-v2/issues/2073))
 - Widen the allowed solc version to any v0.8.x for the interfaces only ([#2083](https://github.com/kleros/kleros-v2/issues/2083))

contracts/src/libraries/SortitionTrees.sol

@@ -5,13 +5,13 @@ pragma solidity ^0.8.24;
 type TreeKey is bytes32;
 type CourtID is uint96;
 
-using {toTreeKey} for CourtID global;
-
-function toTreeKey(CourtID _courtID) pure returns (TreeKey) {
-    return TreeKey.wrap(bytes32(uint256(CourtID.unwrap(_courtID))));
-}
+using {SortitionTrees.toTreeKey} for CourtID global;
 
 library SortitionTrees {
+    // ************************************* //
+    // *         Enums / Structs           * //
+    // ************************************* //
+
     struct Tree {
         uint256 K; // The maximum number of children per node.
         uint256[] stack; // We use this to keep track of vacant positions in the tree after removing a leaf. This is for keeping the tree as balanced as possible without spending gas on moving nodes around.
@@ -21,6 +21,14 @@ library SortitionTrees {
         mapping(uint256 nodeIndex => bytes32 stakePathID) nodeIndexesToIDs;
     }
 
+    function toTreeKey(CourtID _courtID) internal pure returns (TreeKey) {
+        return TreeKey.wrap(bytes32(uint256(CourtID.unwrap(_courtID))));
+    }
+
+    // ************************************* //
+    // *         State Modifiers           * //
+    // ************************************* //
+
     /// @dev Create a sortition sum tree at the specified key.
     /// @param _trees The mapping of sortition sum trees.
     /// @param _key The key of the new tree.
@@ -174,6 +182,10 @@ library SortitionTrees {
         }
     }
 
+    // ************************************* //
+    // *           Public Views            * //
+    // ************************************* //
+
     /// @dev Get the stake of a juror in a court.
     /// @param _tree The sortition sum tree.
     /// @param _stakePathID The stake path ID, corresponding to a juror.
@@ -247,6 +259,10 @@ library SortitionTrees {
         }
     }
 
+    // ************************************* //
+    // *              Errors               * //
+    // ************************************* //
+
     error TreeAlreadyExists();
     error KMustBeGreaterThanOne();
 }