ModeratedEvidenceModule

State Variables

AMOUNT_OF_CHOICES

uint256 public constant AMOUNT_OF_CHOICES = 2;

MULTIPLIER_DIVISOR

uint256 public constant MULTIPLIER_DIVISOR = 10000;

evidences

mapping(bytes32 => EvidenceData) evidences;

disputeIDtoEvidenceID

mapping(uint256 => bytes32) public disputeIDtoEvidenceID;

arbitratorDataList

ArbitratorData[] public arbitratorDataList;

arbitrator

IArbitratorV2 public immutable arbitrator;

governor

address public governor;

bondTimeout

uint256 public bondTimeout;

totalCostMultiplier

uint256 public totalCostMultiplier;

initialDepositMultiplier

uint256 public initialDepositMultiplier;

Functions

onlyGovernor

modifier onlyGovernor();

constructor

Constructor.

constructor(
    IArbitratorV2 _arbitrator,
    address _governor,
    uint256 _totalCostMultiplier,
    uint256 _initialDepositMultiplier,
    uint256 _bondTimeout,
    bytes memory _arbitratorExtraData,
    string memory _templateData
);

Parameters

Name	Type	Description
`_arbitrator`	`IArbitratorV2`	The trusted arbitrator to resolve potential disputes.
`_governor`	`address`	The trusted governor of the contract.
`_totalCostMultiplier`	`uint256`	Multiplier of arbitration fees that must be ultimately paid as fee stake. In basis points.
`_initialDepositMultiplier`	`uint256`	Multiplier of arbitration fees that must be paid as initial stake for submitting evidence. In basis points.
`_bondTimeout`	`uint256`	The time in seconds during which the last moderation status can be challenged.
`_arbitratorExtraData`	`bytes`	Extra data for the trusted arbitrator contract.
`_templateData`	`string`	The dispute template data.

changeGovernor

Change the governor of the contract.

function changeGovernor(address _governor) external onlyGovernor;

Parameters

Name	Type	Description
`_governor`	`address`	The address of the new governor.

changeInitialDepositMultiplier

Change the proportion of arbitration fees that must be paid as fee stake by parties when there is no winner or loser (e.g. when the arbitrator refused to rule).

function changeInitialDepositMultiplier(uint256 _initialDepositMultiplier) external onlyGovernor;

Parameters

Name	Type	Description
`_initialDepositMultiplier`	`uint256`	Multiplier of arbitration fees that must be paid as fee stake. In basis points.

changeTotalCostMultiplier

Change the proportion of arbitration fees that must be paid as fee stake by the winner of the previous round.

function changeTotalCostMultiplier(uint256 _totalCostMultiplier) external onlyGovernor;

Parameters

Name	Type	Description
`_totalCostMultiplier`	`uint256`	Multiplier of arbitration fees that must be paid as fee stake. In basis points.

changeBondTimeout

Change the the time window within which evidence submissions and removals can be contested. Ongoing moderations will start using the latest bondTimeout available after calling moderate() again.

function changeBondTimeout(uint256 _bondTimeout) external onlyGovernor;

Parameters

Name	Type	Description
`_bondTimeout`	`uint256`	Multiplier of arbitration fees that must be paid as fee stake. In basis points.

changeDisputeTemplate

Update the dispute template data.

function changeDisputeTemplate(string calldata _templateData) external onlyGovernor;

Parameters

Name	Type	Description
`_templateData`	`string`	The new dispute template data.

changeArbitratorExtraData

Change the arbitrator to be used for disputes that may be raised in the next requests. The arbitrator is trusted to support appeal period and not reenter.

function changeArbitratorExtraData(bytes calldata _arbitratorExtraData) external onlyGovernor;

Parameters

Name	Type	Description
`_arbitratorExtraData`	`bytes`	The extra data used by the new arbitrator.

submitEvidence

Submits evidence.

function submitEvidence(uint256 _evidenceGroupID, string calldata _evidence) external payable;

Parameters

Name	Type	Description
`_evidenceGroupID`	`uint256`	Unique identifier of the evidence group the evidence belongs to. It's the submitter responsability to submit the right evidence group ID.
`_evidence`	`string`	IPFS path to evidence, example: '/ipfs/Qmarwkf7C9RuzDEJNnarT3WZ7kem5bk8DZAzx78acJjMFH/evidence.json'.

Moderates an evidence submission. Requires the contester to at least double the accumulated stake of the oposing party. Optimization opportunity: use bytes calldata args and compress _evidenceID and _side (only for optimistic rollups).

function moderate(bytes32 _evidenceID, Party _side) external payable;

Parameters

Name	Type	Description
`_evidenceID`	`bytes32`	Unique identifier of the evidence submission.
`_side`	`Party`	The side to contribute to.

resolveModerationMarket

Resolves a moderation event once the timeout has passed.

function resolveModerationMarket(bytes32 _evidenceID) external;

Parameters

Name	Type	Description
`_evidenceID`	`bytes32`	Unique identifier of the evidence submission.

contribute

Make a fee contribution.

function contribute(
    Moderation storage _moderation,
    Party _side,
    address payable _contributor,
    uint256 _amount,
    uint256 _totalRequired
) internal returns (uint256);

Parameters

Name	Type	Description
`_moderation`	`Moderation`	The moderation to contribute to.
`_side`	`Party`	The side to contribute to.
`_contributor`	`address payable`	The contributor.
`_amount`	`uint256`	The amount contributed.
`_totalRequired`	`uint256`	The total amount required for this side.

Returns

Name	Type	Description
`<none>`	`uint256`	The amount of fees contributed.

calculateContribution

Returns the contribution value and remainder from available ETH and required amount.

function calculateContribution(uint256 _available, uint256 _requiredAmount)
    internal
    pure
    returns (uint256 taken, uint256 remainder);

Parameters

Name	Type	Description
`_available`	`uint256`	The amount of ETH available for the contribution.
`_requiredAmount`	`uint256`	The amount of ETH required for the contribution.

Returns

Name	Type	Description
`taken`	`uint256`	The amount of ETH taken.
`remainder`	`uint256`	The amount of ETH left from the contribution.

withdrawFeesAndRewards

Withdraws contributions of moderations. Reimburses contributions if the appeal was not fully funded. If the appeal was fully funded, sends the fee stake rewards and reimbursements proportional to the contributions made to the winner of a dispute. Optimization opportunity: use bytes calldata args and compress _evidenceID and _moderationID (only for optimistic rollups).

function withdrawFeesAndRewards(address payable _beneficiary, bytes32 _evidenceID, uint256 _moderationID)
    external
    returns (uint256 reward);

Parameters

Name	Type	Description
`_beneficiary`	`address payable`	The address that made contributions.
`_evidenceID`	`bytes32`	The ID of the associated evidence submission.
`_moderationID`	`uint256`	The ID of the moderatino occurence.

rule

Give a ruling for a dispute. Must be called by the arbitrator to enforce the final ruling. The purpose of this function is to ensure that the address calling it has the right to rule on the contract.

function rule(uint256 _disputeID, uint256 _ruling) public override;

Parameters

Name	Type	Description
`_disputeID`	`uint256`	ID of the dispute in the Arbitrator contract.
`_ruling`	`uint256`	Ruling given by the arbitrator. Note that 0 is reserved for "Not able/wanting to make a decision".

getNumberOfModerations

Gets the number of moderation events of the specific evidence submission.

function getNumberOfModerations(bytes32 _evidenceID) external view returns (uint256);

Parameters

Name	Type	Description
`_evidenceID`	`bytes32`	The ID of the evidence submission.

Returns

Name	Type	Description
`<none>`	`uint256`	The number of moderations.

getContributions

Gets the contributions made by a party for a given moderation.

function getContributions(bytes32 _evidenceID, uint256 _moderationID, address _contributor)
    external
    view
    returns (uint256[3] memory contributions);

Parameters

Name	Type	Description
`_evidenceID`	`bytes32`	The ID of the evidence submission.
`_moderationID`	`uint256`	The ID of the moderation occurence.
`_contributor`	`address`	The address of the contributor.

Returns

Name	Type	Description
`contributions`	`uint256[3]`	The contributions.

getModerationInfo

Gets the information of a moderation event.

function getModerationInfo(bytes32 _evidenceID, uint256 _moderationID)
    external
    view
    returns (uint256[3] memory paidFees, Party currentWinner, uint256 feeRewards);

Parameters

Name	Type	Description
`_evidenceID`	`bytes32`	The ID of the evidence submission.
`_moderationID`	`uint256`	The ID of the moderation occurence.

Returns

Name	Type	Description
`paidFees`	`uint256[3]`	currentWinner feeRewards The moderation information.
`currentWinner`	`Party`
`feeRewards`	`uint256`

getCurrentArbitratorIndex

Gets the last arbitrator data index, which is used for current new submissions.

function getCurrentArbitratorIndex() external view returns (uint256);

Returns

Name	Type	Description
`<none>`	`uint256`	The last arbitrator data index.

Events

ModeratedEvidence

To be raised when a moderated evidence is submitted. Should point to the resource (evidences are not to be stored on chain due to gas considerations).

event ModeratedEvidence(
    IArbitratorV2 indexed _arbitrator, uint256 indexed _externalDisputeID, address indexed _party, string _evidence
);

ModerationStatusChanged

Indicate that a party has to pay a fee or would otherwise be considered as losing.

event ModerationStatusChanged(bytes32 indexed _evidenceID, Party _currentWinner);

Structs

EvidenceData

struct EvidenceData {
    address payable submitter;
    bool disputed;
    Party ruling;
    uint256 disputeID;
    Moderation[] moderations;
}

Moderation

struct Moderation {
    uint256[3] paidFees;
    uint256 feeRewards;
    mapping(address => uint256[3]) contributions;
    bool closed;
    Party currentWinner;
    uint256 bondDeadline;
    uint256 arbitratorDataID;
}

ArbitratorData

struct ArbitratorData {
    uint256 disputeTemplateId;
    bytes arbitratorExtraData;
}

Enums

Party

enum Party {
    None,
    Submitter,
    Moderator
}