Implementing a Complex Arbitrator¶
Warning
Smart contracts in this tutorial are not intended for production but educational purposes. Beware of using them on main network.
We will refactor SimpleCentralizedArbitrator to add appeal functionality and dynamic costs.
Recall SimpleCentralizedArbitrator:
/**
* @authors: [@ferittuncer, @hbarcelos]
* @reviewers: []
* @auditors: []
* @bounties: []
* @deployments: []
* SPDX-License-Identifier: MIT
*/
pragma solidity ^0.8.9;
import "../IArbitrator.sol";
contract SimpleCentralizedArbitrator is IArbitrator {
address public owner = msg.sender;
error NotOwner();
error InsufficientPayment(uint256 _available, uint256 _required);
error InvalidRuling(uint256 _ruling, uint256 _numberOfChoices);
error InvalidStatus(DisputeStatus _current, DisputeStatus _expected);
struct Dispute {
IArbitrable arbitrated;
uint256 choices;
uint256 ruling;
DisputeStatus status;
}
Dispute[] public disputes;
function arbitrationCost(bytes memory _extraData) public pure override returns (uint256) {
return 0.1 ether;
}
function appealCost(uint256 _disputeID, bytes memory _extraData) public pure override returns (uint256) {
return 2**250; // An unaffordable amount which practically avoids appeals.
}
function createDispute(uint256 _choices, bytes memory _extraData)
public
payable
override
returns (uint256 disputeID)
{
uint256 requiredAmount = arbitrationCost(_extraData);
if (msg.value < requiredAmount) {
revert InsufficientPayment(msg.value, requiredAmount);
}
disputes.push(
Dispute({arbitrated: IArbitrable(msg.sender), choices: _choices, ruling: 0, status: DisputeStatus.Waiting})
);
disputeID = disputes.length - 1;
emit DisputeCreation(disputeID, IArbitrable(msg.sender));
}
function disputeStatus(uint256 _disputeID) public view override returns (DisputeStatus status) {
status = disputes[_disputeID].status;
}
function currentRuling(uint256 _disputeID) public view override returns (uint256 ruling) {
ruling = disputes[_disputeID].ruling;
}
function rule(uint256 _disputeID, uint256 _ruling) public {
if (msg.sender != owner) {
revert NotOwner();
}
Dispute storage dispute = disputes[_disputeID];
if (_ruling > dispute.choices) {
revert InvalidRuling(_ruling, dispute.choices);
}
if (dispute.status != DisputeStatus.Waiting) {
revert InvalidStatus(dispute.status, DisputeStatus.Waiting);
}
dispute.ruling = _ruling;
dispute.status = DisputeStatus.Solved;
payable(msg.sender).send(arbitrationCost(""));
dispute.arbitrated.rule(_disputeID, _ruling);
}
function appeal(uint256 _disputeID, bytes memory _extraData) public payable override {
uint256 requiredAmount = appealCost(_disputeID, _extraData);
if (msg.value < requiredAmount) {
revert InsufficientPayment(msg.value, requiredAmount);
}
}
function appealPeriod(uint256 _disputeID) public pure override returns (uint256 start, uint256 end) {
return (0, 0);
}
}
First, let’s implement the appeal:
pragma solidity ^0.5;
import "../Arbitrator.sol";
contract CentralizedArbitratorWithAppeal is Arbitrator {
address public owner = msg.sender;
uint constant appealWindow = 3 minutes;
struct Dispute {
IArbitrable arbitrated;
uint choices;
uint ruling;
DisputeStatus status;
uint appealPeriodStart;
uint appealPeriodEnd;
}
Dispute[] public disputes;
function arbitrationCost(bytes memory _extraData) public view returns(uint fee) {
fee = 0.1 ether;
}
function appealCost(uint _disputeID, bytes memory _extraData) public view returns(uint fee) {
fee = 2**250; // An unaffordable amount which practically avoids appeals.
}
function createDispute(uint _choices, bytes memory _extraData) public payable returns(uint disputeID) {
super.createDispute(_choices, _extraData);
disputeID = disputes.push(Dispute({
arbitrated: IArbitrable(msg.sender),
choices: _choices,
ruling: 0,
status: DisputeStatus.Waiting,
appealPeriodStart: 0,
appealPeriodEnd: 0
}));
emit DisputeCreation(disputeID, IArbitrable(msg.sender));
}
function disputeStatus(uint _disputeID) public view returns(DisputeStatus status) {
Dispute storage dispute = disputes[_disputeID];
if (disputes[_disputeID].status == DisputeStatus.Appealable && block.timestamp >= dispute.appealPeriodEnd)
return DisputeStatus.Solved;
else
return disputes[_disputeID].status;
}
function currentRuling(uint _disputeID) public view returns(uint ruling) {
ruling = disputes[_disputeID].ruling;
}
function giveRuling(uint _disputeID, uint _ruling) public {
require(msg.sender == owner, "Only the owner of this contract can execute rule function.");
Dispute storage dispute = disputes[_disputeID];
require(_ruling <= dispute.choices, "Ruling out of bounds!");
require(dispute.status != DisputeStatus.Solved, "Can't rule an already solved dispute!");
dispute.ruling = _ruling;
dispute.status = DisputeStatus.Appealable;
dispute.appealPeriodStart = block.timestamp;
dispute.appealPeriodEnd = dispute.appealPeriodStart + appealWindow;
}
function executeRuling(uint _disputeID) public {
Dispute storage dispute = disputes[_disputeID];
require(dispute.status == DisputeStatus.Appealable, "The dispute must be appealable.");
require(block.timestamp >= dispute.appealPeriodEnd, "The dispute must be executed after its appeal period has ended.");
dispute.status = DisputeStatus.Solved;
dispute.arbitrated.rule(_disputeID, dispute.ruling);
}
function appeal(uint _disputeID, bytes memory _extraData) public payable {
Dispute storage dispute = disputes[_disputeID];
super.appeal(_disputeID, _extraData);
require(dispute.status == DisputeStatus.Appealable, "The dispute must be appealable.");
require(block.timestamp < dispute.appealPeriodEnd, "The appeal must occur before the end of the appeal period.");
dispute.status = DisputeStatus.Waiting;
}
function appealPeriod(uint _disputeID) public view returns(uint start, uint end) {
Dispute storage dispute = disputes[_disputeID];
return (dispute.appealPeriodStart, dispute.appealPeriodEnd);
}
}
We first define appealWindow constant, which is the amount of time a dispute stays appealable.
To implement appealPeriod function of the ERC-792 interface, we define two additional variables in Dispute struct: appealPeriodStart and appealPeriodEnd.
DisputeStatus function is also updated to handle the case where a dispute has DisputeStatus.Appealable status, but the appeal window is closed, so actually it is DisputeStatus.Solved.
The important change is we divided proxy rule function into two parts.
giveRuling: Gives ruling, but does not enforce it.executeRulingEnforces ruling, only after the appeal window is closed.
Before, there was no appeal functionality, so we didn’t have to wait for appeal and ruling was enforced immediately after giving the ruling. Now we need to do them separately.
appeal function checks whether the dispute is eligible for appeal and performs the appeal by setting status back to the default value, DisputeStatus.Waiting.
Now let’s revisit cost functions:
/**
* @authors: [@ferittuncer, @hbarcelos]
* @reviewers: []
* @auditors: []
* @bounties: []
* @deployments: []
* SPDX-License-Identifier: MIT
*/
pragma solidity ^0.8.9;
import "../IArbitrator.sol";
contract CentralizedArbitratorWithAppeal is IArbitrator {
address public owner = msg.sender;
uint256 constant appealWindow = 3 minutes;
uint256 internal arbitrationFee = 1e15;
error NotOwner();
error InsufficientPayment(uint256 _available, uint256 _required);
error InvalidRuling(uint256 _ruling, uint256 _numberOfChoices);
error InvalidStatus(DisputeStatus _current, DisputeStatus _expected);
error BeforeAppealPeriodEnd(uint256 _currentTime, uint256 _appealPeriodEnd);
error AfterAppealPeriodEnd(uint256 _currentTime, uint256 _appealPeriodEnd);
struct Dispute {
IArbitrable arbitrated;
uint256 choices;
uint256 ruling;
DisputeStatus status;
uint256 appealPeriodStart;
uint256 appealPeriodEnd;
uint256 appealCount;
}
Dispute[] public disputes;
function arbitrationCost(bytes memory _extraData) public view override returns (uint256) {
return arbitrationFee;
}
function appealCost(uint256 _disputeID, bytes memory _extraData) public view override returns (uint256) {
return arbitrationFee * (2**(disputes[_disputeID].appealCount));
}
function setArbitrationCost(uint256 _newCost) public {
arbitrationFee = _newCost;
}
function createDispute(uint256 _choices, bytes memory _extraData)
public
payable
override
returns (uint256 disputeID)
{
uint256 requiredAmount = arbitrationCost(_extraData);
if (msg.value > requiredAmount) {
revert InsufficientPayment(msg.value, requiredAmount);
}
disputes.push(
Dispute({
arbitrated: IArbitrable(msg.sender),
choices: _choices,
ruling: 0,
status: DisputeStatus.Waiting,
appealPeriodStart: 0,
appealPeriodEnd: 0,
appealCount: 0
})
);
disputeID = disputes.length - 1;
emit DisputeCreation(disputeID, IArbitrable(msg.sender));
}
function disputeStatus(uint256 _disputeID) public view override returns (DisputeStatus status) {
Dispute storage dispute = disputes[_disputeID];
if (disputes[_disputeID].status == DisputeStatus.Appealable && block.timestamp >= dispute.appealPeriodEnd)
return DisputeStatus.Solved;
else return disputes[_disputeID].status;
}
function currentRuling(uint256 _disputeID) public view override returns (uint256 ruling) {
ruling = disputes[_disputeID].ruling;
}
function giveRuling(uint256 _disputeID, uint256 _ruling) public {
if (msg.sender != owner) {
revert NotOwner();
}
Dispute storage dispute = disputes[_disputeID];
if (_ruling > dispute.choices) {
revert InvalidRuling(_ruling, dispute.choices);
}
if (dispute.status != DisputeStatus.Waiting) {
revert InvalidStatus(dispute.status, DisputeStatus.Waiting);
}
dispute.ruling = _ruling;
dispute.status = DisputeStatus.Appealable;
dispute.appealPeriodStart = block.timestamp;
dispute.appealPeriodEnd = dispute.appealPeriodStart + appealWindow;
emit AppealPossible(_disputeID, dispute.arbitrated);
}
function executeRuling(uint256 _disputeID) public {
Dispute storage dispute = disputes[_disputeID];
if (dispute.status != DisputeStatus.Appealable) {
revert InvalidStatus(dispute.status, DisputeStatus.Appealable);
}
if (block.timestamp <= dispute.appealPeriodEnd) {
revert BeforeAppealPeriodEnd(block.timestamp, dispute.appealPeriodEnd);
}
dispute.status = DisputeStatus.Solved;
dispute.arbitrated.rule(_disputeID, dispute.ruling);
}
function appeal(uint256 _disputeID, bytes memory _extraData) public payable override {
Dispute storage dispute = disputes[_disputeID];
dispute.appealCount++;
uint256 requiredAmount = appealCost(_disputeID, _extraData);
if (msg.value < requiredAmount) {
revert InsufficientPayment(msg.value, requiredAmount);
}
if (dispute.status != DisputeStatus.Appealable) {
revert InvalidStatus(dispute.status, DisputeStatus.Appealable);
}
if (block.timestamp > dispute.appealPeriodEnd) {
revert AfterAppealPeriodEnd(block.timestamp, dispute.appealPeriodEnd);
}
dispute.status = DisputeStatus.Waiting;
emit AppealDecision(_disputeID, dispute.arbitrated);
}
function appealPeriod(uint256 _disputeID) public view override returns (uint256 start, uint256 end) {
Dispute storage dispute = disputes[_disputeID];
return (dispute.appealPeriodStart, dispute.appealPeriodEnd);
}
}
We implemented a setter for arbitration cost and we made the appeal cost as exponentially increasing.
We achieved that by counting the number of appeals with appealCount variable, which gets increased each time appeal is executed.
This concludes our implementation of a centralized arbitrator with appeal functionality.