feat: resolver migrated and deployed to chiado, interfaces natspec improved

Author: jaybuidl

contracts/README.md

@@ -11,6 +11,7 @@ Refresh the list of deployed contracts by running `./scripts/generateDeployments
 #### Chiado
 
 - [ArbitrableExample](https://blockscout.com/gnosis/chiado/address/0xc0fcc96BFd78e36550FCaB434A9EE1210B57225b)
+- [DisputeResolver](https://blockscout.com/gnosis/chiado/address/0x433eD78895df1df7668C40b3e82d54410331F942)
 - [ForeignGatewayOnGnosis](https://blockscout.com/gnosis/chiado/address/0x573bcD6ee4aEe152eCC9Cafd2c0820Dc548AF6cC)
 - [SortitionSumTreeFactory](https://blockscout.com/gnosis/chiado/address/0xc7e3BF90299f6BD9FA7c3703837A9CAbB5743636)
 - [TokenBridge](https://blockscout.com/gnosis/chiado/address/0xbb3c86f9918C3C1d83668fA84e79E876d147fFf2)

contracts/deploy/04-resolver-to-v2-gnosis.ts

@@ -0,0 +1,39 @@
+import { parseUnits } from "ethers/lib/utils";
+import { HardhatRuntimeEnvironment } from "hardhat/types";
+import { DeployFunction } from "hardhat-deploy/types";
+
+enum ForeignChains {
+  GNOSIS_MAINNET = 100,
+  GNOSIS_CHIADO = 10200,
+  HARDHAT = 31337,
+}
+
+const ONE_GWEI = parseUnits("1", "gwei");
+
+const deployResolver: DeployFunction = async (hre: HardhatRuntimeEnvironment) => {
+  const { deployments, getNamedAccounts, getChainId } = hre;
+  const { deploy } = deployments;
+
+  // fallback to hardhat node signers on local network
+  const deployer = (await getNamedAccounts()).deployer ?? (await hre.ethers.getSigners())[0].address;
+  const chainId = Number(await getChainId());
+  console.log("Deploying to chainId %s with deployer %s", chainId, deployer);
+
+  const foreignGateway = await deployments.get("ForeignGatewayOnGnosis");
+
+  await deploy("DisputeResolver", {
+    from: deployer,
+    args: [foreignGateway.address],
+    log: true,
+    maxFeePerGas: ONE_GWEI,
+    maxPriorityFeePerGas: ONE_GWEI,
+  });
+};
+
+deployResolver.tags = ["ResolverOnGnosis"];
+deployResolver.skip = async ({ getChainId }) => {
+  const chainId = Number(await getChainId());
+  return !ForeignChains[chainId];
+};
+
+export default deployResolver;

contracts/src/arbitration/IArbitrable.sol

@@ -12,13 +12,15 @@ import "./IArbitrator.sol";
 interface IArbitrable {
     /// @dev To be raised when a ruling is given.
     /// @param _arbitrator The arbitrator giving the ruling.
-    /// @param _disputeID ID of the dispute in the Arbitrator contract.
+    /// @param _disputeID The identifier of the dispute in the Arbitrator contract.
     /// @param _ruling The ruling which was given.
     event Ruling(IArbitrator indexed _arbitrator, uint256 indexed _disputeID, uint256 _ruling);
 
-    /// @dev Give a ruling for a dispute. Must be called by the arbitrator.
-    /// The purpose of this function is to ensure that the address calling it has the right to rule on the contract.
-    /// @param _disputeID ID of the dispute in the Arbitrator contract.
-    /// @param _ruling Ruling given by the arbitrator. Note that 0 is reserved for "Not able/wanting to make a decision".
+    /// @dev Give a ruling for a dispute.
+    ///      Must be called by the arbitrator.
+    ///      The purpose of this function is to ensure that the address calling it has the right to rule on the contract.
+    /// @param _disputeID The identifier of the dispute in the Arbitrator contract.
+    /// @param _ruling Ruling given by the arbitrator.
+    /// Note that 0 is reserved for "Not able/wanting to make a decision".
     function rule(uint256 _disputeID, uint256 _ruling) external;
 }

contracts/src/arbitration/IArbitrableV2.sol

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
 
-pragma solidity ^0.8;
+pragma solidity 0.8.18;
 
 import "./IArbitratorV2.sol";
 
@@ -11,17 +11,17 @@ import "./IArbitratorV2.sol";
 /// - Allow dispute creation. For this a function must call arbitrator.createDispute{value: _fee}(_choices,_extraData);
 interface IArbitrableV2 {
     /// @dev To be emitted when a new dispute template is created.
-    /// @param _templateId The ID of the dispute template.
+    /// @param _templateId The identifier of the dispute template.
     /// @param _templateTag An optional tag for the dispute template, such as "registration" or "removal".
     /// @param data The template data.
     event DisputeTemplate(uint256 indexed _templateId, string indexed _templateTag, string data);
 
     /// @dev To be emitted when a dispute is created to link the correct meta-evidence to the disputeID.
     /// @param _arbitrator The arbitrator of the contract.
-    /// @param _arbitrableDisputeID The ID of the dispute in the Arbitrable contract.
+    /// @param _arbitrableDisputeID The identifier of the dispute in the Arbitrable contract.
     /// @param _externalDisputeID An identifier created outside Kleros by the protocol requesting arbitration.
-    /// @param _templateId The ID of the dispute template. Should not be used with _templateUri.
-    /// @param _templateUri IPFS path to the dispute template starting with '/ipfs/'. Should not be used with _templateId.
+    /// @param _templateId The identifier of the dispute template. Should not be used with _templateUri.
+    /// @param _templateUri The URI to the dispute template. For example on IPFS: starting with '/ipfs/'. Should not be used with _templateId.
     event DisputeRequest(
         IArbitratorV2 indexed _arbitrator,
         uint256 indexed _arbitrableDisputeID,
@@ -32,11 +32,11 @@ interface IArbitrableV2 {
 
     /// @dev To be emitted when a dispute is created to link the correct meta-evidence to the disputeID.
     /// @param _arbitrator The arbitrator of the contract.
-    /// @param _arbitrableChainId The chain ID of the Arbitrable contract.
+    /// @param _arbitrableChainId The chain identifier where the Arbitrable contract is deployed.
     /// @param _arbitrable The address of the Arbitrable contract.
-    /// @param _arbitrableDisputeID The ID of the dispute in the Arbitrable contract.
+    /// @param _arbitrableDisputeID The identifier of the dispute in the Arbitrable contract.
     /// @param _externalDisputeID An identifier created outside Kleros by the protocol requesting arbitration.
-    /// @param _templateId The ID of the dispute template. Should not be used with _templateUri.
+    /// @param _templateId The identifier of the dispute template. Should not be used with _templateUri.
     /// @param _templateUri IPFS path to the dispute template starting with '/ipfs/'. Should not be used with _templateId.
     event CrossChainDisputeRequest(
         IArbitratorV2 indexed _arbitrator,
@@ -50,14 +50,14 @@ interface IArbitrableV2 {
 
     /// @dev To be raised when a ruling is given.
     /// @param _arbitrator The arbitrator giving the ruling.
-    /// @param _disputeID ID of the dispute in the Arbitrator contract.
+    /// @param _disputeID The identifier of the dispute in the Arbitrator contract.
     /// @param _ruling The ruling which was given.
     event Ruling(IArbitratorV2 indexed _arbitrator, uint256 indexed _disputeID, uint256 _ruling);
 
     /// @dev Give a ruling for a dispute.
     ///      Must be called by the arbitrator.
     ///      The purpose of this function is to ensure that the address calling it has the right to rule on the contract.
-    /// @param _disputeID ID of the dispute in the Arbitrator contract.
+    /// @param _disputeID The identifier of the dispute in the Arbitrator contract.
     /// @param _ruling Ruling given by the arbitrator.
     /// Note that 0 is reserved for "Not able/wanting to make a decision".
     function rule(uint256 _disputeID, uint256 _ruling) external;

contracts/src/arbitration/IArbitrator.sol

@@ -6,31 +6,33 @@ import "./IArbitrable.sol";
 
 /// @title Arbitrator
 /// Arbitrator interface that implements the new arbitration standard.
-/// Unlike the ERC-792 this standard doesn't have anything related to appeals, so each arbitrator can implement an appeal system that suits it the most.
+/// Unlike the ERC-792 this standard is not concerned with appeals, so each arbitrator can implement an appeal system that suits it the most.
 /// When developing arbitrator contracts we need to:
 /// - Define the functions for dispute creation (createDispute). Don't forget to store the arbitrated contract and the disputeID (which should be unique, may nbDisputes).
 /// - Define the functions for cost display (arbitrationCost).
 /// - Allow giving rulings. For this a function must call arbitrable.rule(disputeID, ruling).
 interface IArbitrator {
     /// @dev To be emitted when a dispute is created.
-    /// @param _disputeID ID of the dispute.
+    /// @param _disputeID The identifier of the dispute.
     /// @param _arbitrable The contract which created the dispute.
     event DisputeCreation(uint256 indexed _disputeID, IArbitrable indexed _arbitrable);
 
     /// @dev To be raised when a ruling is given.
     /// @param _arbitrable The arbitrable receiving the ruling.
-    /// @param _disputeID ID of the dispute in the Arbitrator contract.
+    /// @param _disputeID The identifier of the dispute in the Arbitrator contract.
     /// @param _ruling The ruling which was given.
     event Ruling(IArbitrable indexed _arbitrable, uint256 indexed _disputeID, uint256 _ruling);
 
-    /// @dev Create a dispute. Must be called by the arbitrable contract.
-    /// Must pay at least arbitrationCost(_extraData).
+    /// @dev Create a dispute.
+    ///      Must be called by the arbitrable contract.
+    ///      Must pay at least arbitrationCost(_extraData).
     /// @param _choices Amount of choices the arbitrator can make in this dispute.
     /// @param _extraData Can be used to give additional info on the dispute to be created.
-    /// @return disputeID ID of the dispute created.
+    /// @return disputeID The identifier of the dispute created.
     function createDispute(uint256 _choices, bytes calldata _extraData) external payable returns (uint256 disputeID);
 
-    /// @dev Compute the cost of arbitration. 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.
+    /// @dev Compute the cost of arbitration.
+    ///      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.
     /// @param _extraData Can be used to give additional info on the dispute to be created.
     /// @return cost Required cost of arbitration.
     function arbitrationCost(bytes calldata _extraData) external view returns (uint256 cost);

contracts/src/arbitration/IArbitratorV2.sol

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
 
-pragma solidity ^0.8;
+pragma solidity 0.8.18;
 
 import "./IArbitrableV2.sol";
 
@@ -13,13 +13,13 @@ import "./IArbitrableV2.sol";
 /// - Allow giving rulings. For this a function must call arbitrable.rule(disputeID, ruling).
 interface IArbitratorV2 {
     /// @dev To be emitted when a dispute is created.
-    /// @param _disputeID Identifier of the dispute.
+    /// @param _disputeID The identifier of the dispute in the Arbitrator contract.
     /// @param _arbitrable The contract which created the dispute.
     event DisputeCreation(uint256 indexed _disputeID, IArbitrableV2 indexed _arbitrable);
 
     /// @dev To be raised when a ruling is given.
     /// @param _arbitrable The arbitrable receiving the ruling.
-    /// @param _disputeID Identifier of the dispute in the Arbitrator contract.
+    /// @param _disputeID The identifier of the dispute in the Arbitrator contract.
     /// @param _ruling The ruling which was given.
     event Ruling(IArbitrableV2 indexed _arbitrable, uint256 indexed _disputeID, uint256 _ruling);
 
@@ -28,7 +28,7 @@ interface IArbitratorV2 {
     ///      Must pay at least arbitrationCost(_extraData).
     /// @param _choices Amount of choices the arbitrator can make in this dispute.
     /// @param _extraData Can be used to give additional info on the dispute to be created.
-    /// @return disputeID Identifier of the dispute created.
+    /// @return disputeID The identifier of the dispute created.
     function createDispute(uint256 _choices, bytes calldata _extraData) external payable returns (uint256 disputeID);
 
     /// @dev Compute the cost of arbitration.
@@ -39,7 +39,7 @@ interface IArbitratorV2 {
 
     /// @dev Return the current ruling of a dispute.
     ///      This is useful for parties to know if they should appeal.
-    /// @param _disputeID ID of the dispute.
+    /// @param _disputeID The identifer of the dispute.
     /// @return ruling The ruling which has been given or the one which will be given if there is no appeal.
     function currentRuling(uint _disputeID) external view returns (uint ruling);
 }

contracts/src/arbitration/arbitrables/DisputeResolver.sol

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
 
-/// @custom:authors: [@ferittuncer, @unknownunknown1,@jaybuidl]
+/// @custom:authors: [@ferittuncer, @unknownunknown1, @jaybuidl]
 /// @custom:reviewers: []
 /// @custom:auditors: []
 /// @custom:bounties: []
@@ -10,53 +10,85 @@ import "../IArbitrableV2.sol";
 pragma solidity 0.8.18;
 
 /// @title DisputeResolver
-/// DisputeResolver contract adapted for V2 https://github.com/kleros/arbitrable-proxy-contracts/blob/master/contracts/ArbitrableProxy.sol.
+/// DisputeResolver contract adapted for V2 from https://github.com/kleros/arbitrable-proxy-contracts/blob/master/contracts/ArbitrableProxy.sol.
 contract DisputeResolver is IArbitrableV2 {
+    // ************************************* //
+    // *         Enums / Structs           * //
+    // ************************************* //
+
     struct DisputeStruct {
         bytes arbitratorExtraData; // Extra data for the dispute.
         bool isRuled; // True if the dispute has been ruled.
         uint256 ruling; // Ruling given to the dispute.
         uint256 numberOfRulingOptions; // The number of choices the arbitrator can give.
     }
 
-    IArbitratorV2 public immutable arbitrator; // Arbitrator is set in constructor and never changed.
+    // ************************************* //
+    // *             Storage               * //
+    // ************************************* //
 
+    address public governor; // The governor.
+    IArbitratorV2 public arbitrator; // The arbitrator.
     DisputeStruct[] public disputes; // Local disputes.
-    mapping(uint256 => uint256) public arbitratorDisputeIDToLocalID; // Maps external (arbitrator side) dispute IDs to local dispute IDs.
+    mapping(uint256 => uint256) public arbitratorDisputeIDToLocalID; // Maps arbitrator-side dispute IDs to local dispute IDs.
+
+    // ************************************* //
+    // *            Constructor            * //
+    // ************************************* //
 
     /// @dev Constructor
     /// @param _arbitrator Target global arbitrator for any disputes.
     constructor(IArbitratorV2 _arbitrator) {
+        governor = msg.sender;
         arbitrator = _arbitrator;
     }
 
+    // ************************************* //
+    // *           Governance              * //
+    // ************************************* //
+
+    /// @dev Changes the governor.
+    /// @param _governor The address of the new governor.
+    function changeGovernor(address _governor) external {
+        require(governor == msg.sender, "Access not allowed: Governor only.");
+        governor = _governor;
+    }
+
+    function changeArbitrator(IArbitratorV2 _arbitrator) external {
+        require(governor == msg.sender, "Access not allowed: Governor only.");
+        arbitrator = _arbitrator;
+    }
+
+    // ************************************* //
+    // *         State Modifiers           * //
+    // ************************************* //
+
     /// @dev Calls createDispute function of the specified arbitrator to create a dispute.
     /// Note that we don’t need to check that msg.value is enough to pay arbitration fees as it’s the responsibility of the arbitrator contract.
     /// @param _arbitratorExtraData Extra data for the arbitrator of the dispute.
-    /// @param _template Dispute template.
+    /// @param _disputeTemplate Dispute template.
     /// @param _numberOfRulingOptions Number of ruling options.
     /// @return disputeID Dispute id (on arbitrator side) of the created dispute.
-    function createDispute(
+    function createDisputeForTemplate(
         bytes calldata _arbitratorExtraData,
-        string calldata _template,
+        string calldata _disputeTemplate,
         uint256 _numberOfRulingOptions
     ) external payable returns (uint256 disputeID) {
-        require(_numberOfRulingOptions > 1, "Should be at least 2 ruling options.");
-
-        disputeID = arbitrator.createDispute{value: msg.value}(_numberOfRulingOptions, _arbitratorExtraData);
-        uint256 localDisputeID = disputes.length;
-        disputes.push(
-            DisputeStruct({
-                arbitratorExtraData: _arbitratorExtraData,
-                isRuled: false,
-                ruling: 0,
-                numberOfRulingOptions: _numberOfRulingOptions
-            })
-        );
+        return _createDispute(_arbitratorExtraData, _disputeTemplate, "", _numberOfRulingOptions);
+    }
 
-        arbitratorDisputeIDToLocalID[disputeID] = localDisputeID;
-        emit DisputeTemplate(localDisputeID, "", _template);
-        emit DisputeRequest(arbitrator, disputeID, localDisputeID, localDisputeID, "");
+    /// @dev Calls createDispute function of the specified arbitrator to create a dispute.
+    /// Note that we don’t need to check that msg.value is enough to pay arbitration fees as it’s the responsibility of the arbitrator contract.
+    /// @param _arbitratorExtraData Extra data for the arbitrator of the dispute.
+    /// @param _disputeTemplateUri The URI to the dispute template. For example on IPFS: starting with '/ipfs/'.
+    /// @param _numberOfRulingOptions Number of ruling options.
+    /// @return disputeID Dispute id (on arbitrator side) of the created dispute.
+    function createDisputeForTemplateUri(
+        bytes calldata _arbitratorExtraData,
+        string calldata _disputeTemplateUri,
+        uint256 _numberOfRulingOptions
+    ) external payable returns (uint256 disputeID) {
+        return _createDispute(_arbitratorExtraData, "", _disputeTemplateUri, _numberOfRulingOptions);
     }
 
     /// @dev To be called by the arbitrator of the dispute, to declare the winning ruling.
@@ -74,4 +106,33 @@ contract DisputeResolver is IArbitrableV2 {
 
         emit Ruling(IArbitratorV2(msg.sender), _externalDisputeID, dispute.ruling);
     }
+
+    // ************************************* //
+    // *            Internal               * //
+    // ************************************* //
+
+    function _createDispute(
+        bytes calldata _arbitratorExtraData,
+        string memory _disputeTemplate,
+        string memory _disputeUri,
+        uint256 _numberOfRulingOptions
+    ) internal returns (uint256 disputeID) {
+        require(_numberOfRulingOptions > 1, "Should be at least 2 ruling options.");
+
+        disputeID = arbitrator.createDispute{value: msg.value}(_numberOfRulingOptions, _arbitratorExtraData);
+        uint256 localDisputeID = disputes.length;
+        disputes.push(
+            DisputeStruct({
+                arbitratorExtraData: _arbitratorExtraData,
+                isRuled: false,
+                ruling: 0,
+                numberOfRulingOptions: _numberOfRulingOptions
+            })
+        );
+        arbitratorDisputeIDToLocalID[disputeID] = localDisputeID;
+
+        uint256 templateId = localDisputeID;
+        emit DisputeTemplate(templateId, "", _disputeTemplate);
+        emit DisputeRequest(arbitrator, disputeID, localDisputeID, templateId, _disputeUri);
+    }
 }