KlerosCore
Inherits: IArbitrator
State Variables
FORKING_COURT
uint96 public constant FORKING_COURT = 0;
GENERAL_COURT
uint96 public constant GENERAL_COURT = 1;
NULL_DISPUTE_KIT
uint256 public constant NULL_DISPUTE_KIT = 0;
DISPUTE_KIT_CLASSIC
uint256 public constant DISPUTE_KIT_CLASSIC = 1;
MAX_STAKE_PATHS
uint256 public constant MAX_STAKE_PATHS = 4;
MIN_JURORS
uint256 public constant MIN_JURORS = 3;
ALPHA_DIVISOR
uint256 public constant ALPHA_DIVISOR = 1e4;
NON_PAYABLE_AMOUNT
uint256 public constant NON_PAYABLE_AMOUNT = (2 ** 256 - 2) / 2;
SEARCH_ITERATIONS
uint256 public constant SEARCH_ITERATIONS = 10;
governor
address public governor;
pinakion
IERC20 public pinakion;
jurorProsecutionModule
address public jurorProsecutionModule;
phase
Phase public phase;
minStakingTime
uint256 public minStakingTime;
maxFreezingTime
uint256 public maxFreezingTime;
lastPhaseChange
uint256 public lastPhaseChange;
freezeBlock
uint256 public freezeBlock;
courts
Court[] public courts;
disputeKitNodes
DisputeKitNode[] public disputeKitNodes;
disputesKitIDsThatNeedFreezing
uint256[] public disputesKitIDsThatNeedFreezing;
disputes
Dispute[] public disputes;
jurors
mapping(address => Juror) internal jurors;
sortitionSumTrees
SortitionSumTreeFactoryV2.SortitionSumTrees internal sortitionSumTrees;
delayedStakes
mapping(uint256 => DelayedStake) public delayedStakes;
delayedStakeWriteIndex
uint256 public delayedStakeWriteIndex;
delayedStakeReadIndex
uint256 public delayedStakeReadIndex = 1;
Functions
onlyByGovernor
modifier onlyByGovernor();
constructor
Constructor.
constructor(
address _governor,
IERC20 _pinakion,
address _jurorProsecutionModule,
IDisputeKit _disputeKit,
uint256[2] memory _phaseTimeouts,
bool _hiddenVotes,
uint256[4] memory _courtParameters,
uint256[4] memory _timesPerPeriod,
uint256 _sortitionSumTreeK
);
Parameters
Name | Type | Description |
---|---|---|
_governor | address | The governor's address. |
_pinakion | IERC20 | The address of the token contract. |
_jurorProsecutionModule | address | The address of the juror prosecution module. |
_disputeKit | IDisputeKit | The address of the default dispute kit. |
_phaseTimeouts | uint256[2] | minStakingTime and maxFreezingTime respectively |
_hiddenVotes | bool | The hiddenVotes property value of the general court. |
_courtParameters | uint256[4] | Numeric parameters of General court (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. |
executeGovernorProposal
Allows the governor to 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 payable _governor) external onlyByGovernor;
Parameters
Name | Type | Description |
---|---|---|
_governor | address payable | The new value for the governor storage variable. |
changePinakion
Changes the pinakion
storage variable.
function changePinakion(IERC20 _pinakion) external onlyByGovernor;
Parameters
Name | Type | Description |
---|---|---|
_pinakion | IERC20 | The new value for the pinakion storage variable. |
changeJurorProsecutionModule
Changes the jurorProsecutionModule
storage variable.
function changeJurorProsecutionModule(address _jurorProsecutionModule) external onlyByGovernor;
Parameters
Name | Type | Description |
---|---|---|
_jurorProsecutionModule | address | The new value for the jurorProsecutionModule 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. |
changeMaxFreezingTime
Changes the maxFreezingTime
storage variable.
function changeMaxFreezingTime(uint256 _maxFreezingTime) external onlyByGovernor;
Parameters
Name | Type | Description |
---|---|---|
_maxFreezingTime | uint256 | The new value for the maxFreezingTime storage variable. |
addNewDisputeKit
Add a new supported dispute kit module to the court.
function addNewDisputeKit(IDisputeKit _disputeKitAddress, uint256 _parent) external onlyByGovernor;
Parameters
Name | Type | Description |
---|---|---|
_disputeKitAddress | IDisputeKit | The address of the dispute kit contract. |
_parent | uint256 | The ID of the parent dispute kit. It is left empty when root DK is created. Note that the root DK must be supported by the general court. |
createCourt
Creates a court under a specified parent court.
function createCourt(
uint96 _parent,
bool _hiddenVotes,
uint256 _minStake,
uint256 _alpha,
uint256 _feeForJuror,
uint256 _jurorsForCourtJump,
uint256[4] memory _timesPerPeriod,
uint256 _sortitionSumTreeK,
uint256[] memory _supportedDisputeKits
) external onlyByGovernor;
Parameters
Name | Type | Description |
---|---|---|
_parent | uint96 | The parent property value of the court. |
_hiddenVotes | bool | The hiddenVotes property value of the court. |
_minStake | uint256 | The minStake property value of the court. |
_alpha | uint256 | The alpha property value of the court. |
_feeForJuror | uint256 | The feeForJuror property value of the court. |
_jurorsForCourtJump | uint256 | The jurorsForCourtJump property value of the court. |
_timesPerPeriod | uint256[4] | The timesPerPeriod property value of the court. |
_sortitionSumTreeK | uint256 | The number of children per node of the court's sortition sum tree. |
_supportedDisputeKits | uint256[] | Indexes of dispute kits that this court will support. |
changeCourtMinStake
Changes the minStake
property value of a specified court. Don't set to a value lower than its parent's minStake
property value.
function changeCourtMinStake(uint96 _courtID, uint256 _minStake) external onlyByGovernor;
Parameters
Name | Type | Description |
---|---|---|
_courtID | uint96 | The ID of the court. |
_minStake | uint256 | The new value for the minStake property value. |
changeCourtAlpha
Changes the alpha
property value of a specified court.
function changeCourtAlpha(uint96 _courtID, uint256 _alpha) external onlyByGovernor;
Parameters
Name | Type | Description |
---|---|---|
_courtID | uint96 | The ID of the court. |
_alpha | uint256 | The new value for the alpha property value. |
changeCourtJurorFee
Changes the feeForJuror
property value of a specified court.
function changeCourtJurorFee(uint96 _courtID, uint256 _feeForJuror) external onlyByGovernor;
Parameters
Name | Type | Description |
---|---|---|
_courtID | uint96 | The ID of the court. |
_feeForJuror | uint256 | The new value for the feeForJuror property value. |
changeCourtJurorsForJump
Changes the jurorsForCourtJump
property value of a specified court.
function changeCourtJurorsForJump(uint96 _courtID, uint256 _jurorsForCourtJump) external onlyByGovernor;
Parameters
Name | Type | Description |
---|---|---|
_courtID | uint96 | The ID of the court. |
_jurorsForCourtJump | uint256 | The new value for the jurorsForCourtJump property value. |
changeCourtHiddenVotes
Changes the hiddenVotes
property value of a specified court.
function changeCourtHiddenVotes(uint96 _courtID, bool _hiddenVotes) external onlyByGovernor;
Parameters
Name | Type | Description |
---|---|---|
_courtID | uint96 | The ID of the court. |
_hiddenVotes | bool | The new value for the hiddenVotes property value. |
changeCourtTimesPerPeriod
Changes the timesPerPeriod
property value of a specified court.
function changeCourtTimesPerPeriod(uint96 _courtID, uint256[4] memory _timesPerPeriod) external onlyByGovernor;
Parameters
Name | Type | Description |
---|---|---|
_courtID | uint96 | The ID of the court. |
_timesPerPeriod | uint256[4] | The new value for the timesPerPeriod property value. |
enableDisputeKits
Adds/removes court's support for specified dispute kits.
function enableDisputeKits(uint96 _courtID, uint256[] memory _disputeKitIDs, bool _enable) external onlyByGovernor;
Parameters
Name | Type | Description |
---|---|---|
_courtID | uint96 | The ID of the court. |
_disputeKitIDs | uint256[] | The IDs of dispute kits which support should be added/removed. |
_enable | bool | Whether add or remove the dispute kits from the court. |
setStake
Sets the caller's stake in a court.
function setStake(uint96 _courtID, uint256 _stake) external;
Parameters
Name | Type | Description |
---|---|---|
_courtID | uint96 | The ID of the court. |
_stake | uint256 | The new stake. |
executeDelayedStakes
Executes the next delayed stakes.
function executeDelayedStakes(uint256 _iterations) external;
Parameters
Name | Type | Description |
---|---|---|
_iterations | uint256 | The number of delayed stakes to execute. |
createDispute
Creates a dispute. Must be called by the arbitrable contract.
function createDispute(uint256 _numberOfChoices, bytes memory _extraData)
external
payable
override
returns (uint256 disputeID);
Parameters
Name | Type | Description |
---|---|---|
_numberOfChoices | uint256 | Number of choices for the jurors to choose from. |
_extraData | bytes | Additional info about the dispute. We use it to pass the ID of the dispute's court (first 32 bytes), the minimum number of jurors required (next 32 bytes) and the ID of the specific dispute kit (last 32 bytes). |
Returns
Name | Type | Description |
---|---|---|
disputeID | uint256 | The ID of the created dispute. |
passPhase
Switches the phases between Staking and Freezing, also signal the switch to the dispute kits.
function passPhase() external;
passPeriod
Passes the period of a specified dispute.
function passPeriod(uint256 _disputeID) external;
Parameters
Name | Type | Description |
---|---|---|
_disputeID | uint256 | The ID of the dispute. |
draw
Draws jurors for the dispute. Can be called in parts.
function draw(uint256 _disputeID, uint256 _iterations) external;
Parameters
Name | Type | Description |
---|---|---|
_disputeID | uint256 | The ID of the dispute. |
_iterations | uint256 | The number of iterations to run. |
appeal
Appeals the ruling of a specified dispute.
Note: Access restricted to the Dispute Kit for this disputeID
.
function appeal(uint256 _disputeID, uint256 _numberOfChoices, bytes memory _extraData) external payable;
Parameters
Name | Type | Description |
---|---|---|
_disputeID | uint256 | The ID of the dispute. |
_numberOfChoices | uint256 | Number of choices for the dispute. Can be required during court jump. |
_extraData | bytes | Extradata for the dispute. Can be required during court jump. |
execute
Distribute tokens and ETH for the specific round of the dispute. Can be called in parts.
function execute(uint256 _disputeID, uint256 _round, uint256 _iterations) external;
Parameters
Name | Type | Description |
---|---|---|
_disputeID | uint256 | The ID of the dispute. |
_round | uint256 | The appeal round. |
_iterations | uint256 | The number of iterations to run. |
executeRuling
Executes a specified dispute's ruling. UNTRUSTED.
function executeRuling(uint256 _disputeID) external;
Parameters
Name | Type | Description |
---|---|---|
_disputeID | uint256 | The ID of the dispute. |
arbitrationCost
Gets the cost of arbitration in a specified court.
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 court 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 arbitration cost. |
appealCost
Gets the cost of appealing a specified dispute.
function appealCost(uint256 _disputeID) public view returns (uint256 cost);
Parameters
Name | Type | Description |
---|---|---|
_disputeID | uint256 | The ID of the dispute. |
Returns
Name | Type | Description |
---|---|---|
cost | uint256 | The appeal cost. |
appealPeriod
Gets the start and the end of a specified dispute's current appeal period.
function appealPeriod(uint256 _disputeID) public view returns (uint256 start, uint256 end);
Parameters
Name | Type | Description |
---|---|---|
_disputeID | uint256 | The ID of the dispute. |
Returns
Name | Type | Description |
---|---|---|
start | uint256 | The start of the appeal period. |
end | uint256 | The end of the appeal period. |
currentRuling
Gets the current ruling of a specified dispute.
function currentRuling(uint256 _disputeID) public view returns (uint256 ruling, bool tied, bool overridden);
Parameters
Name | Type | Description |
---|---|---|
_disputeID | uint256 | The ID of the dispute. |
Returns
Name | Type | Description |
---|---|---|
ruling | uint256 | The current ruling. |
tied | bool | Whether it's a tie or not. |
overridden | bool | Whether the ruling was overridden by appeal funding or not. |
getRoundInfo
function getRoundInfo(uint256 _disputeID, uint256 _round)
external
view
returns (
uint256 tokensAtStakePerJuror,
uint256 totalFeesForJurors,
uint256 repartitions,
uint256 penalties,
address[] memory drawnJurors,
uint256 disputeKitID
);
getNumberOfRounds
function getNumberOfRounds(uint256 _disputeID) external view returns (uint256);
getJurorBalance
function getJurorBalance(address _juror, uint96 _courtID) external view returns (uint256 staked, uint256 locked);
isSupported
function isSupported(uint96 _courtID, uint256 _disputeKitID) external view returns (bool);
getDisputeKitChildren
Gets non-primitive properties of a specified dispute kit node.
function getDisputeKitChildren(uint256 _disputeKitID) external view returns (uint256[] memory);
Parameters
Name | Type | Description |
---|---|---|
_disputeKitID | uint256 | The ID of the dispute kit. |
Returns
Name | Type | Description |
---|---|---|
<none> | uint256[] | children Indexes of children of this DK. |
getTimesPerPeriod
Gets the timesPerPeriod array for a given court.
function getTimesPerPeriod(uint96 _courtID) external view returns (uint256[4] memory timesPerPeriod);
Parameters
Name | Type | Description |
---|---|---|
_courtID | uint96 | The ID of the court to get the times from. |
Returns
Name | Type | Description |
---|---|---|
timesPerPeriod | uint256[4] | The timesPerPeriod array for the given court. |
getSortitionSumTreeNode
function getSortitionSumTreeNode(bytes32 _key, uint256 _index) external view returns (uint256);
getSortitionSumTree
function getSortitionSumTree(bytes32 _key, uint256 _nodeIndex)
public
view
returns (uint256 K, uint256 length, bytes32 ID);
getNumberOfVotes
function getNumberOfVotes(uint256 _disputeID) external view returns (uint256);
freezingPhaseTimeout
function freezingPhaseTimeout() external view returns (bool);
isDisputeKitJumping
Returns true if the dispute kit will be switched to a parent DK.
function isDisputeKitJumping(uint256 _disputeID) external view returns (bool);
Parameters
Name | Type | Description |
---|---|---|
_disputeID | uint256 | The ID of the dispute. |
Returns
Name | Type | Description |
---|---|---|
<none> | bool | Whether DK will be switched or not. |
getDisputesKitIDsThatNeedFreezing
function getDisputesKitIDsThatNeedFreezing() external view returns (uint256[] memory);
getJurorCourtIDs
function getJurorCourtIDs(address _juror) public view returns (uint96[] memory);
enableDisputeKit
function enableDisputeKit(uint96 _courtID, uint256 _disputeKitID, bool _enable) internal;
setStakeForAccount
Sets the specified juror's stake in a court.
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 setStakeForAccount(address _account, uint96 _courtID, uint256 _stake, uint256 _penalty)
internal
returns (bool succeeded);
Parameters
Name | Type | Description |
---|---|---|
_account | address | The address of the juror. |
_courtID | uint96 | The ID of the court. |
_stake | uint256 | The new stake. |
_penalty | uint256 | Penalized amount won't be transferred back to juror when the stake is lowered. |
Returns
Name | Type | Description |
---|---|---|
succeeded | bool | True if the call succeeded, false otherwise. |
extraDataToCourtIDMinJurorsDisputeKit
Gets a court ID, the minimum number of jurors and an ID of a dispute kit from a specified extra data bytes array. Note that if extradata contains an incorrect value then this value will be switched to default.
function extraDataToCourtIDMinJurorsDisputeKit(bytes memory _extraData)
internal
view
returns (uint96 courtID, uint256 minJurors, uint256 disputeKitID);
Parameters
Name | Type | Description |
---|---|---|
_extraData | bytes | The extra data bytes array. The first 32 bytes are the court ID, the next are the minimum number of jurors and the last are the dispute kit ID. |
Returns
Name | Type | Description |
---|---|---|
courtID | uint96 | The court ID. |
minJurors | uint256 | The minimum number of jurors required. |
disputeKitID | uint256 | The ID of the dispute kit. |
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. |
safeTransfer
Calls transfer() without reverting.
function safeTransfer(address _to, uint256 _value) internal returns (bool);
Parameters
Name | Type | Description |
---|---|---|
_to | address | Recepient address. |
_value | uint256 | Amount transferred. |
Returns
Name | Type | Description |
---|---|---|
<none> | bool | Whether transfer succeeded or not. |
safeTransferFrom
Calls transferFrom() without reverting.
function safeTransferFrom(address _from, address _to, uint256 _value) internal returns (bool);
Parameters
Name | Type | Description |
---|---|---|
_from | address | Sender address. |
_to | address | Recepient address. |
_value | uint256 | Amount transferred. |
Returns
Name | Type | Description |
---|---|---|
<none> | bool | Whether transfer succeeded or not. |
Events
NewPhase
event NewPhase(Phase _phase);
NewPeriod
event NewPeriod(uint256 indexed _disputeID, Period _period);
StakeSet
event StakeSet(address indexed _address, uint256 _courtID, uint256 _amount, uint256 _newTotalStake);
AppealPossible
event AppealPossible(uint256 indexed _disputeID, IArbitrable indexed _arbitrable);
AppealDecision
event AppealDecision(uint256 indexed _disputeID, IArbitrable indexed _arbitrable);
Draw
event Draw(address indexed _address, uint256 indexed _disputeID, uint256 _roundID, uint256 _voteID);
CourtCreated
event CourtCreated(
uint256 indexed _courtID,
uint96 indexed _parent,
bool _hiddenVotes,
uint256 _minStake,
uint256 _alpha,
uint256 _feeForJuror,
uint256 _jurorsForCourtJump,
uint256[4] _timesPerPeriod,
uint256 _sortitionSumTreeK,
uint256[] _supportedDisputeKits
);
CourtModified
event CourtModified(uint96 indexed _courtID, string _param);
DisputeKitCreated
event DisputeKitCreated(uint256 indexed _disputeKitID, IDisputeKit indexed _disputeKitAddress, uint256 indexed _parent);
DisputeKitEnabled
event DisputeKitEnabled(uint96 indexed _courtID, uint256 indexed _disputeKitID, bool indexed _enable);
CourtJump
event CourtJump(uint256 indexed _disputeID, uint256 indexed _roundID, uint96 indexed _fromCourtID, uint96 _toCourtID);
DisputeKitJump
event DisputeKitJump(
uint256 indexed _disputeID, uint256 indexed _roundID, uint256 indexed _fromDisputeKitID, uint256 _toDisputeKitID
);
TokenAndETHShift
event TokenAndETHShift(address indexed _account, uint256 indexed _disputeID, int256 _tokenAmount, int256 _ethAmount);
Structs
Court
struct Court {
uint96 parent;
bool hiddenVotes;
uint256[] children;
uint256 minStake;
uint256 alpha;
uint256 feeForJuror;
uint256 jurorsForCourtJump;
uint256[4] timesPerPeriod;
mapping(uint256 => bool) supportedDisputeKits;
}
Dispute
struct Dispute {
uint96 courtID;
IArbitrable arbitrated;
Period period;
bool ruled;
uint256 lastPeriodChange;
Round[] rounds;
}
Round
struct Round {
uint256 disputeKitID;
uint256 tokensAtStakePerJuror;
uint256 totalFeesForJurors;
uint256 nbVotes;
uint256 repartitions;
uint256 penalties;
address[] drawnJurors;
}
Juror
struct Juror {
uint96[] courtIDs;
mapping(uint96 => uint256) stakedTokens;
mapping(uint96 => uint256) lockedTokens;
}
DisputeKitNode
struct DisputeKitNode {
uint256 parent;
uint256[] children;
IDisputeKit disputeKit;
bool needsFreezing;
uint256 depthLevel;
}
DelayedStake
struct DelayedStake {
address account;
uint96 courtID;
uint256 stake;
uint256 penalty;
}
Enums
Phase
enum Phase {
staking,
freezing
}
Period
enum Period {
evidence,
commit,
vote,
appeal,
execution
}