SortitionModule

A factory of trees that keeps track of staked values for sortition.

State Variables

MAX_STAKE_PATHS

uint256 public constant MAX_STAKE_PATHS = 4;

DEFAULT_K

uint256 public constant DEFAULT_K = 6;

governor

address public governor;

core

KlerosCore public core;

phase

Phase public phase;

minStakingTime

uint256 public minStakingTime;

maxDrawingTime

uint256 public maxDrawingTime;

lastPhaseChange

uint256 public lastPhaseChange;

randomNumberRequestBlock

uint256 public randomNumberRequestBlock;

disputesWithoutJurors

uint256 public disputesWithoutJurors;

rng

RNG public rng;

randomNumber

uint256 public randomNumber;

rngLookahead

uint256 public rngLookahead;

delayedStakeWriteIndex

uint256 public delayedStakeWriteIndex;

delayedStakeReadIndex

uint256 public delayedStakeReadIndex = 1;

sortitionSumTrees

mapping(bytes32 => SortitionSumTree) sortitionSumTrees;

delayedStakes

mapping(uint256 => DelayedStake) public delayedStakes;

Functions

onlyByGovernor

modifier onlyByGovernor();

onlyByCore

modifier onlyByCore();

constructor

Constructor.

constructor(
    address _governor,
    KlerosCore _core,
    uint256 _minStakingTime,
    uint256 _maxDrawingTime,
    RNG _rng,
    uint256 _rngLookahead
);

Parameters

Name	Type	Description
`_governor`	`address`
`_core`	`KlerosCore`	The KlerosCore.
`_minStakingTime`	`uint256`	Minimal time to stake
`_maxDrawingTime`	`uint256`	Time after which the drawing phase can be switched
`_rng`	`RNG`	The random number generator.
`_rngLookahead`	`uint256`	Lookahead value for rng.

changeMinStakingTime

Changes the minStakingTime storage variable.

function changeMinStakingTime(uint256 _minStakingTime) external onlyByGovernor;

Parameters

Name	Type	Description
`_minStakingTime`	`uint256`	The new value for the `minStakingTime` storage variable.

changeMaxDrawingTime

Changes the maxDrawingTime storage variable.

function changeMaxDrawingTime(uint256 _maxDrawingTime) external onlyByGovernor;

Parameters

Name	Type	Description
`_maxDrawingTime`	`uint256`	The new value for the `maxDrawingTime` storage variable.

changeRandomNumberGenerator

Changes the _rng and _rngLookahead storage variables.

function changeRandomNumberGenerator(RNG _rng, uint256 _rngLookahead) external onlyByGovernor;

Parameters

Name	Type	Description
`_rng`	`RNG`	The new value for the `RNGenerator` storage variable.
`_rngLookahead`	`uint256`	The new value for the `rngLookahead` storage variable.

passPhase

function passPhase() external;

createTree

Create a sortition sum tree at the specified key.

function createTree(bytes32 _key, bytes memory _extraData) external override onlyByCore;

Parameters

Name	Type	Description
`_key`	`bytes32`	The key of the new tree.
`_extraData`	`bytes`	Extra data that contains the number of children each node in the tree should have.

executeDelayedStakes

Executes the next delayed stakes.

function executeDelayedStakes(uint256 _iterations) external;

Parameters

Name	Type	Description
`_iterations`	`uint256`	The number of delayed stakes to execute.

preStakeHook

function preStakeHook(address _account, uint96 _courtID, uint256 _stake, uint256 _penalty)
    external
    override
    onlyByCore
    returns (preStakeHookResult);

createDisputeHook

function createDisputeHook(uint256, uint256) external override onlyByCore;

postDrawHook

function postDrawHook(uint256, uint256) external override onlyByCore;

notifyRandomNumber

Saves the random number to use it in sortition. Not used by this contract because the storing of the number is inlined in passPhase().

function notifyRandomNumber(uint256 _randomNumber) public override;

Parameters

Name	Type	Description
`_randomNumber`	`uint256`	Random number returned by RNG contract.

setStake

Sets the value for a particular court and its parent courts.

function setStake(address _account, uint96 _courtID, uint256 _value) external override onlyByCore;

Parameters

Name	Type	Description
`_account`	`address`	Address of the juror. `O(log_k(n))` where `k` is the maximum number of children per node in the tree, and `n` is the maximum number of nodes ever appended.
`_courtID`	`uint96`	ID of the court.
`_value`	`uint256`	The new value.

Unstakes the inactive juror from all courts. O(n * (p * log_k(j)) ) where n is the number of courts the juror has staked in, p is the depth of the court tree, k is the minimum number of children per node of one of these courts' sortition sum tree, and j is the maximum number of jurors that ever staked in one of these courts simultaneously.

function setJurorInactive(address _account) external override onlyByCore;

Parameters

Name	Type	Description
`_account`	`address`	The juror to unstake.

draw

Draw an ID from a tree using a number. Note that this function reverts if the sum of all values in the tree is 0.

function draw(bytes32 _key, uint256 _coreDisputeID, uint256 _voteID)
    public
    view
    override
    returns (address drawnAddress);

Parameters

Name	Type	Description
`_key`	`bytes32`	The key of the tree.
`_coreDisputeID`	`uint256`	Index of the dispute in Kleros Core.
`_voteID`	`uint256`	ID of the voter.

Returns

Name	Type	Description
`drawnAddress`	`address`	The drawn address. `O(k * log_k(n))` where `k` is the maximum number of children per node in the tree, and `n` is the maximum number of nodes ever appended.

_updateParents

Update all the parents of a node.

function _updateParents(bytes32 _key, uint256 _treeIndex, bool _plusOrMinus, uint256 _value) private;

Parameters

Name	Type	Description
`_key`	`bytes32`	The key of the tree to update.
`_treeIndex`	`uint256`	The index of the node to start from.
`_plusOrMinus`	`bool`	Whether to add (true) or substract (false).
`_value`	`uint256`	The value to add or substract. `O(log_k(n))` where `k` is the maximum number of children per node in the tree, and `n` is the maximum number of nodes ever appended.

_stakePathIDToAccount

Retrieves a juror's address from the stake path ID.

function _stakePathIDToAccount(bytes32 _stakePathID) internal pure returns (address account);

Parameters

Name	Type	Description
`_stakePathID`	`bytes32`	The stake path ID to unpack.

Returns

Name	Type	Description
`account`	`address`	The account.

_extraDataToTreeK

function _extraDataToTreeK(bytes memory _extraData) internal pure returns (uint256 K);

_set

Set a value in a tree.

function _set(bytes32 _key, uint256 _value, bytes32 _ID) internal;

Parameters

Name	Type	Description
`_key`	`bytes32`	The key of the tree.
`_value`	`uint256`	The new value.
`_ID`	`bytes32`	The ID of the value. `O(log_k(n))` where `k` is the maximum number of children per node in the tree, and `n` is the maximum number of nodes ever appended.

_accountAndCourtIDToStakePathID

Packs an account and a court ID into a stake path ID.

function _accountAndCourtIDToStakePathID(address _account, uint96 _courtID)
    internal
    pure
    returns (bytes32 stakePathID);

Parameters

Name	Type	Description
`_account`	`address`	The address of the juror to pack.
`_courtID`	`uint96`	The court ID to pack.

Returns

Name	Type	Description
`stakePathID`	`bytes32`	The stake path ID.

Structs

SortitionSumTree

struct SortitionSumTree {
    uint256 K;
    uint256[] stack;
    uint256[] nodes;
    mapping(bytes32 => uint256) IDsToNodeIndexes;
    mapping(uint256 => bytes32) nodeIndexesToIDs;
}

DelayedStake

struct DelayedStake {
    address account;
    uint96 courtID;
    uint256 stake;
    uint256 penalty;
}