xKlerosLiquidV2

Inherits: Initializable, ITokenController, IArbitrator

This contract is an adaption of Mainnet's KlerosLiquid (https://github.com/kleros/kleros/blob/69cfbfb2128c29f1625b3a99a3183540772fda08/contracts/kleros/KlerosLiquid.sol) for xDai chain. Notice that variables referring to ETH values in this contract, will hold the native token values of the chain on which xKlerosLiquid is deployed. When this contract gets deployed on xDai chain, ETH variables will hold xDai values.

State Variables

MAX_STAKE_PATHS

uint256 public constant MAX_STAKE_PATHS = 4;

DEFAULT_NB_OF_JURORS

uint256 public constant DEFAULT_NB_OF_JURORS = 3;

NON_PAYABLE_AMOUNT

uint256 public constant NON_PAYABLE_AMOUNT = (2 ** 256 - 2) / 2;

ALPHA_DIVISOR

uint256 public constant ALPHA_DIVISOR = 1e4;

governor

address public governor;

pinakion

WrappedPinakion public pinakion;

RNGenerator

IRandomAuRa public RNGenerator;

phase

Phase public phase;

lastPhaseChange

uint256 public lastPhaseChange;

disputesWithoutJurors

uint256 public disputesWithoutJurors;

RNBlock

uint256 public RNBlock;

RN

uint256 public RN;

minStakingTime

uint256 public minStakingTime;

maxDrawingTime

uint256 public maxDrawingTime;

lockInsolventTransfers

bool public lockInsolventTransfers;

courts

Court[] public courts;

sortitionSumTrees

SortitionSumTreeFactory.SortitionSumTrees internal sortitionSumTrees;

delayedSetStakes

mapping(uint256 => DelayedSetStake) public delayedSetStakes;

nextDelayedSetStake

uint256 public nextDelayedSetStake;

lastDelayedSetStake

uint256 public lastDelayedSetStake;

disputes

mapping(uint256 => Dispute) public disputes;

totalDisputes

uint256 public totalDisputes;

jurors

mapping(address => Juror) public jurors;

foreignGateway

IForeignGateway public foreignGateway;

weth

IERC20 public weth;

disputesRuling

mapping(uint256 => uint256) public disputesRuling;

Functions

onlyDuringPhase

Requires a specific phase.

modifier onlyDuringPhase(Phase _phase);

Parameters

Name	Type	Description
`_phase`	`Phase`	The required phase.

onlyDuringPeriod

Requires a specific period in a dispute.

modifier onlyDuringPeriod(uint256 _disputeID, Period _period);

Parameters

Name	Type	Description
`_disputeID`	`uint256`	The ID of the dispute.
`_period`	`Period`	The required period.

onlyByGovernor

Requires that the sender is the governor. Note that the governor is expected to not be malicious.

modifier onlyByGovernor();

initialize

Constructs the KlerosLiquid contract.

function initialize(
    address _governor,
    WrappedPinakion _pinakion,
    IRandomAuRa _RNGenerator,
    uint256 _minStakingTime,
    uint256 _maxDrawingTime,
    bool _hiddenVotes,
    uint256[4] memory _courtParameters,
    uint256[4] memory _timesPerPeriod,
    uint256 _sortitionSumTreeK,
    IForeignGateway _foreignGateway,
    IERC20 _weth
) public initializer;

Parameters

Name	Type	Description
`_governor`	`address`	The governor's address.
`_pinakion`	`WrappedPinakion`	The address of the token contract.
`_RNGenerator`	`IRandomAuRa`	The address of the random number generator contract.
`_minStakingTime`	`uint256`	The minimum time that the staking phase should last.
`_maxDrawingTime`	`uint256`	The maximum time that the drawing phase should last.
`_hiddenVotes`	`bool`	The `hiddenVotes` property value of the general court.
`_courtParameters`	`uint256[4]`	MinStake, alpha, feeForJuror and jurorsForCourtJump respectively.
`_timesPerPeriod`	`uint256[4]`	The `timesPerPeriod` property value of the general court.
`_sortitionSumTreeK`	`uint256`	The number of children per node of the general court's sortition sum tree.
`_foreignGateway`	`IForeignGateway`	Foreign gateway on xDai.
`_weth`	`IERC20`	Weth contract.

executeGovernorProposal

Lets the governor call anything on behalf of the contract.

function executeGovernorProposal(address _destination, uint256 _amount, bytes memory _data) external onlyByGovernor;

Parameters

Name	Type	Description
`_destination`	`address`	The destination of the call.
`_amount`	`uint256`	The value sent with the call.
`_data`	`bytes`	The data sent with the call.

changeGovernor

Changes the governor storage variable.

function changeGovernor(address _governor) external onlyByGovernor;

Parameters

Name	Type	Description
`_governor`	`address`	The new value for the `governor` storage variable.

changePinakion

Changes the pinakion storage variable.

function changePinakion(WrappedPinakion _pinakion) external onlyByGovernor;

Parameters

Name	Type	Description
`_pinakion`	`WrappedPinakion`	The new value for the `pinakion` storage variable.

changeRNGenerator

Changes the RNGenerator storage variable.

function changeRNGenerator(IRandomAuRa _RNGenerator) external onlyByGovernor;

Parameters

Name	Type	Description
`_RNGenerator`	`IRandomAuRa`	The new value for the `RNGenerator` storage variable.

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.

changeForeignGateway

Changes the foreignGateway storage variable.

function changeForeignGateway(IForeignGateway _foreignGateway) external onlyByGovernor;

Parameters

Name	Type	Description
`_foreignGateway`	`IForeignGateway`	The new value for the `foreignGateway` storage variable.

changeWethAddress

Changes the weth storage variable.

function changeWethAddress(IERC20 _weth) external onlyByGovernor;

Parameters

Name	Type	Description
`_weth`	`IERC20`	The new value for the `weth` storage variable.

createSubcourt

Creates a subcourt under a specified parent court.

function createSubcourt(
    uint96 _parent,
    bool _hiddenVotes,
    uint256 _minStake,
    uint256 _alpha,
    uint256 _feeForJuror,
    uint256 _jurorsForCourtJump,
    uint256[4] memory _timesPerPeriod,
    uint256 _sortitionSumTreeK
) external onlyByGovernor;

Parameters

Name	Type	Description
`_parent`	`uint96`	The `parent` property value of the subcourt.
`_hiddenVotes`	`bool`	The `hiddenVotes` property value of the subcourt.
`_minStake`	`uint256`	The `minStake` property value of the subcourt.
`_alpha`	`uint256`	The `alpha` property value of the subcourt.
`_feeForJuror`	`uint256`	The `feeForJuror` property value of the subcourt.
`_jurorsForCourtJump`	`uint256`	The `jurorsForCourtJump` property value of the subcourt.
`_timesPerPeriod`	`uint256[4]`	The `timesPerPeriod` property value of the subcourt.
`_sortitionSumTreeK`	`uint256`	The number of children per node of the subcourt's sortition sum tree.

changeSubcourtMinStake

Changes the minStake property value of a specified subcourt. Don't set to a value lower than its parent's minStake property value.

function changeSubcourtMinStake(uint96 _subcourtID, uint256 _minStake) external onlyByGovernor;

Parameters

Name	Type	Description
`_subcourtID`	`uint96`	The ID of the subcourt.
`_minStake`	`uint256`	The new value for the `minStake` property value.

changeSubcourtAlpha

Changes the alpha property value of a specified subcourt.

function changeSubcourtAlpha(uint96 _subcourtID, uint256 _alpha) external onlyByGovernor;

Parameters

Name	Type	Description
`_subcourtID`	`uint96`	The ID of the subcourt.
`_alpha`	`uint256`	The new value for the `alpha` property value.

changeSubcourtJurorFee

Changes the feeForJuror property value of a specified subcourt.

function changeSubcourtJurorFee(uint96 _subcourtID, uint256 _feeForJuror) external onlyByGovernor;

Parameters

Name	Type	Description
`_subcourtID`	`uint96`	The ID of the subcourt.
`_feeForJuror`	`uint256`	The new value for the `feeForJuror` property value.

changeSubcourtJurorsForJump

Changes the jurorsForCourtJump property value of a specified subcourt.

function changeSubcourtJurorsForJump(uint96 _subcourtID, uint256 _jurorsForCourtJump) external onlyByGovernor;

Parameters

Name	Type	Description
`_subcourtID`	`uint96`	The ID of the subcourt.
`_jurorsForCourtJump`	`uint256`	The new value for the `jurorsForCourtJump` property value.

changeSubcourtTimesPerPeriod

Changes the timesPerPeriod property value of a specified subcourt.

function changeSubcourtTimesPerPeriod(uint96 _subcourtID, uint256[4] memory _timesPerPeriod) external onlyByGovernor;

Parameters

Name	Type	Description
`_subcourtID`	`uint96`	The ID of the subcourt.
`_timesPerPeriod`	`uint256[4]`	The new value for the `timesPerPeriod` property value.

setStake

Sets the caller's stake in a subcourt.

function setStake(uint96 _subcourtID, uint128 _stake) external;

Parameters

Name	Type	Description
`_subcourtID`	`uint96`	The ID of the subcourt.
`_stake`	`uint128`	The new stake.

executeDelayedSetStakes

Executes the next delayed set stakes. O(n) where n is the number of iterations to run.

function executeDelayedSetStakes(uint256 _iterations) external onlyDuringPhase(Phase.staking);

Parameters

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

rule

Receive the ruling from foreign gateway which technically is an arbitrator of this contract.

function rule(uint256 _disputeID, uint256 _ruling) external;

Parameters

Name	Type	Description
`_disputeID`	`uint256`	ID of the dispute.
`_ruling`	`uint256`	Ruling given by V2 court and relayed by foreign gateway.

createDispute

Public

Creates a dispute. Must be called by the arbitrable contract.

function createDispute(uint256 _numberOfChoices, bytes memory _extraData)
    public
    payable
    override
    returns (uint256 disputeID);

Parameters

Name	Type	Description
`_numberOfChoices`	`uint256`	Number of choices to choose from in the dispute to be created.
`_extraData`	`bytes`	Additional info about the dispute to be created. We use it to pass the ID of the subcourt to create the dispute in (first 32 bytes) and the minimum number of jurors required (next 32 bytes).

Returns

Name	Type	Description
`disputeID`	`uint256`	The ID of the created dispute.

proxyPayment

DEPRECATED. Called when _owner sends ETH to the Wrapped Token contract.

function proxyPayment(address _owner) public payable override returns (bool allowed);

Parameters

Name	Type	Description
`_owner`	`address`	The address that sent the ETH to create tokens.

Returns

Name	Type	Description
`allowed`	`bool`	Whether the operation should be allowed or not.

onTransfer

Notifies the controller about a token transfer allowing the controller to react if desired.

function onTransfer(address _from, address _to, uint256 _amount) public override returns (bool allowed);

Parameters

Name	Type	Description
`_from`	`address`	The origin of the transfer.
`_to`	`address`	The destination of the transfer.
`_amount`	`uint256`	The amount of the transfer.

Returns

Name	Type	Description
`allowed`	`bool`	Whether the operation should be allowed or not.

onApprove

Notifies the controller about an approval allowing the controller to react if desired.

function onApprove(address _owner, address _spender, uint256 _amount) public override returns (bool allowed);

Parameters

Name	Type	Description
`_owner`	`address`	The address that calls `approve()`.
`_spender`	`address`	The spender in the `approve()` call.
`_amount`	`uint256`	The amount in the `approve()` call.

Returns

Name	Type	Description
`allowed`	`bool`	Whether the operation should be allowed or not.

_setStake

Sets the specified juror's stake in a subcourt. O(n + p * log_k(j)) where n is the number of subcourts the juror has staked in, p is the depth of the subcourt tree, k is the minimum number of children per node of one of these subcourts' sortition sum tree, and j is the maximum number of jurors that ever staked in one of these subcourts simultaneously.

function _setStake(address _account, uint96 _subcourtID, uint128 _stake) internal returns (bool succeeded);

Parameters

Name	Type	Description
`_account`	`address`	The address of the juror.
`_subcourtID`	`uint96`	The ID of the subcourt.
`_stake`	`uint128`	The new stake.

Returns

Name	Type	Description
`succeeded`	`bool`	True if the call succeeded, false otherwise.

extraDataToSubcourtIDAndMinJurors

Gets a subcourt ID and the minimum number of jurors required from a specified extra data bytes array.

function extraDataToSubcourtIDAndMinJurors(bytes memory _extraData)
    internal
    view
    returns (uint96 subcourtID, uint256 minJurors);

Parameters

Name	Type	Description
`_extraData`	`bytes`	The extra data bytes array. The first 32 bytes are the subcourt ID and the next 32 bytes are the minimum number of jurors.

Returns

Name	Type	Description
`subcourtID`	`uint96`	The subcourt ID.
`minJurors`	`uint256`	The minimum number of jurors required.

accountAndSubcourtIDToStakePathID

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

function accountAndSubcourtIDToStakePathID(address _account, uint96 _subcourtID)
    internal
    pure
    returns (bytes32 stakePathID);

Parameters

Name	Type	Description
`_account`	`address`	The account to pack.
`_subcourtID`	`uint96`	The subcourt ID to pack.

Returns

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

arbitrationCost

Gets the cost of arbitration in a specified subcourt.

function arbitrationCost(bytes memory _extraData) public view override returns (uint256 cost);

Parameters

Name	Type	Description
`_extraData`	`bytes`	Additional info about the dispute. We use it to pass the ID of the subcourt to create the dispute in (first 32 bytes) and the minimum number of jurors required (next 32 bytes).

Returns

Name	Type	Description
`cost`	`uint256`	The cost.

currentRuling

Gets the current ruling of a specified dispute.

function currentRuling(uint256 _disputeID) public view returns (uint256 ruling);

Parameters

Name	Type	Description
`_disputeID`	`uint256`	The ID of the dispute.

Returns

Name	Type	Description
`ruling`	`uint256`	The current ruling.

getSubcourt

Gets a specified subcourt's non primitive properties.

function getSubcourt(uint96 _subcourtID)
    external
    view
    returns (uint256[] memory children, uint256[4] memory timesPerPeriod);

Parameters

Name	Type	Description
`_subcourtID`	`uint96`	The ID of the subcourt.

Returns

Name	Type	Description
`children`	`uint256[]`	The subcourt's child court list.
`timesPerPeriod`	`uint256[4]`	The subcourt's time per period.

getVote

Gets a specified vote for a specified appeal in a specified dispute.

function getVote(uint256 _disputeID, uint256 _appeal, uint256 _voteID)
    external
    view
    returns (address account, bytes32 commit, uint256 choice, bool voted);

Parameters

Name	Type	Description
`_disputeID`	`uint256`	The ID of the dispute.
`_appeal`	`uint256`	The appeal.
`_voteID`	`uint256`	The ID of the vote.

Returns

Name	Type	Description
`account`	`address`	The account for vote.
`commit`	`bytes32`	The commit for vote.
`choice`	`uint256`	The choice for vote.
`voted`	`bool`	True if the account voted, False otherwise.

getVoteCounter

Gets the vote counter for a specified appeal in a specified dispute. Note: This function is only to be used by the interface and it won't work if the number of choices is too high.

function getVoteCounter(uint256 _disputeID, uint256 _appeal)
    external
    view
    returns (uint256 winningChoice, uint256[] memory counts, bool tied);

Parameters

Name	Type	Description
`_disputeID`	`uint256`	The ID of the dispute.
`_appeal`	`uint256`	The appeal.

Returns

Name	Type	Description
`winningChoice`	`uint256`	The winning choice.
`counts`	`uint256[]`	The count.
`tied`	`bool`	Whether the vote tied. `O(n)` where `n` is the number of choices of the dispute.

getDispute

Gets a specified dispute's non primitive properties.

function getDispute(uint256 _disputeID)
    external
    view
    returns (
        uint256[] memory votesLengths,
        uint256[] memory tokensAtStakePerJuror,
        uint256[] memory totalFeesForJurors,
        uint256[] memory votesInEachRound,
        uint256[] memory repartitionsInEachRound,
        uint256[] memory penaltiesInEachRound
    );

Parameters

Name	Type	Description
`_disputeID`	`uint256`	The ID of the dispute.

Returns

Name	Type	Description
`votesLengths`	`uint256[]`	The dispute's vote length.
`tokensAtStakePerJuror`	`uint256[]`	The dispute's required tokens at stake per Juror.
`totalFeesForJurors`	`uint256[]`	The dispute's total fees for Jurors.
`votesInEachRound`	`uint256[]`	The dispute's counter of votes made in each round.
`repartitionsInEachRound`	`uint256[]`	The dispute's counter of vote reward repartitions made in each round.
`penaltiesInEachRound`	`uint256[]`	The dispute's amount of tokens collected from penalties in each round. `O(a)` where `a` is the number of appeals of the dispute.

getJuror

Gets a specified juror's non primitive properties.

function getJuror(address _account) external view returns (uint96[] memory subcourtIDs);

Parameters

Name	Type	Description
`_account`	`address`	The address of the juror.

Returns

Name	Type	Description
`subcourtIDs`	`uint96[]`	The juror's IDs of subcourts where the juror has stake path.

stakeOf

Gets the stake of a specified juror in a specified subcourt.

function stakeOf(address _account, uint96 _subcourtID) external view returns (uint256 stake);

Parameters

Name	Type	Description
`_account`	`address`	The address of the juror.
`_subcourtID`	`uint96`	The ID of the subcourt.

Returns

Name	Type	Description
`stake`	`uint256`	The stake.

Events

NewPhase

Emitted when we pass to a new phase.

event NewPhase(Phase _phase);

NewPeriod

Emitted when a dispute passes to a new period.

event NewPeriod(uint256 indexed _disputeID, Period _period);

StakeSet

Emitted when a juror's stake is set.

event StakeSet(address indexed _address, uint256 _subcourtID, uint128 _stake, uint256 _newTotalStake);

Draw

Emitted when a juror is drawn.

event Draw(address indexed _address, uint256 indexed _disputeID, uint256 _appeal, uint256 _voteID);

TokenAndETHShift

Emitted when a juror wins or loses tokens and ETH from a dispute.

event TokenAndETHShift(address indexed _address, uint256 indexed _disputeID, int256 _tokenAmount, int256 _ETHAmount);

Structs

Court

struct Court {
    uint96 parent;
    uint256[] children;
    bool hiddenVotes;
    uint256 minStake;
    uint256 alpha;
    uint256 feeForJuror;
    uint256 jurorsForCourtJump;
    uint256[4] timesPerPeriod;
}

DelayedSetStake

struct DelayedSetStake {
    address account;
    uint96 subcourtID;
    uint128 stake;
}

Vote

struct Vote {
    address account;
    bytes32 commit;
    uint256 choice;
    bool voted;
}

VoteCounter

struct VoteCounter {
    uint256 winningChoice;
    mapping(uint256 => uint256) counts;
    bool tied;
}

Dispute

struct Dispute {
    uint96 subcourtID;
    IArbitrable arbitrated;
    uint256 numberOfChoices;
    Period period;
    uint256 lastPeriodChange;
    Vote[][] votes;
    VoteCounter[] voteCounters;
    uint256[] tokensAtStakePerJuror;
    uint256[] totalFeesForJurors;
    uint256 drawsInRound;
    uint256 commitsInRound;
    uint256[] votesInEachRound;
    uint256[] repartitionsInEachRound;
    uint256[] penaltiesInEachRound;
    bool ruled;
}

Juror

struct Juror {
    uint96[] subcourtIDs;
    uint256 stakedTokens;
    uint256 lockedTokens;
}

Enums

Phase

enum Phase {
    staking,
    generating,
    drawing
}

Period

enum Period {
    evidence,
    commit,
    vote,
    appeal,
    execution
}