xKlerosLiquidV2

Git Source

Inherits: Initializable, ITokenController, IArbitratorV2

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;

disputesRuling

mapping(uint256 => uint256) public disputesRuling;

Functions

onlyDuringPhase

Requires a specific phase.

modifier onlyDuringPhase(Phase _phase);

Parameters

onlyDuringPeriod

Requires a specific period in a dispute.

modifier onlyDuringPeriod(uint256 _disputeID, Period _period);

Parameters

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
) public initializer;

Parameters

executeGovernorProposal

Lets the governor call anything on behalf of the contract.

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

Parameters

changeGovernor

Changes the governor storage variable.

function changeGovernor(address _governor) external onlyByGovernor;

Parameters

changePinakion

Changes the pinakion storage variable.

function changePinakion(WrappedPinakion _pinakion) external onlyByGovernor;

Parameters

changeRNGenerator

Changes the RNGenerator storage variable.

function changeRNGenerator(IRandomAuRa _RNGenerator) external onlyByGovernor;

Parameters

changeMinStakingTime

Changes the minStakingTime storage variable.

function changeMinStakingTime(uint256 _minStakingTime) external onlyByGovernor;

Parameters

changeMaxDrawingTime

Changes the maxDrawingTime storage variable.

function changeMaxDrawingTime(uint256 _maxDrawingTime) external onlyByGovernor;

Parameters

changeForeignGateway

Changes the foreignGateway storage variable.

function changeForeignGateway(IForeignGateway _foreignGateway) external onlyByGovernor;

Parameters

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

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

changeSubcourtAlpha

Changes the alpha property value of a specified subcourt.

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

Parameters

changeSubcourtJurorFee

Changes the feeForJuror property value of a specified subcourt.

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

Parameters

changeSubcourtJurorsForJump

Changes the jurorsForCourtJump property value of a specified subcourt.

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

Parameters

changeSubcourtTimesPerPeriod

Changes the timesPerPeriod property value of a specified subcourt.

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

Parameters

setStake

Sets the caller's stake in a subcourt.

function setStake(uint96 _subcourtID, uint128 _stake) external;

Parameters

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

rule

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

function rule(uint256 _disputeID, uint256 _ruling) external;

Parameters

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

Returns

createDispute

Create a dispute and pay for the fees in the native currency, typically ETH. Must be called by the arbitrable contract. Must pay at least arbitrationCost(_extraData).

function createDispute(uint256, bytes calldata, IERC20, uint256) external override returns (uint256);

Parameters

Returns

proxyPayment

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

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

Parameters

Returns

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

Returns

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

Returns

_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

Returns

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

Returns

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

Returns

arbitrationCost

Compute the cost of arbitration denominated in the native currency, typically ETH. It is recommended not to increase it often, as it can be highly time and gas consuming for the arbitrated contracts to cope with fee augmentation.

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

Parameters

Returns

arbitrationCost

Compute the cost of arbitration denominated in the native currency, typically ETH. It is recommended not to increase it often, as it can be highly time and gas consuming for the arbitrated contracts to cope with fee augmentation.

function arbitrationCost(bytes calldata, IERC20) public pure override returns (uint256);

Parameters

Returns

currentRuling

Gets the current ruling of a specified dispute.

function currentRuling(uint256 _disputeID) public view returns (uint256 ruling, bool tied, bool);

Parameters

Returns

getSubcourt

Gets a specified subcourt's non primitive properties.

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

Parameters

Returns

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

Returns

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

Returns

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

Returns

getJuror

Gets a specified juror's non primitive properties.

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

Parameters

Returns

stakeOf

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

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

Parameters

Returns

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;
    IArbitrableV2 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
}