/cross-chain-arbitration-proxy

Smart contract infrastructure to allow arbitrable dapps on other chains to use Kleros on Ethereum as arbitrator.

Primary LanguageSolidityMIT LicenseMIT

Kleros Cross-Chain Arbitration for xDAI

Smart contract infrastructure to allow arbitrable dapps on xDAI to use Kleros on Ethereum as arbitrator.

Architectural Overview


                                              +----------------+
                       +--------------------->+  Cross  Chain  |
                       v                      |   Arbitrable   |
            +----------+----------+           +----------------+
            |   Home Arbitration  |
            |        Proxy        |
            +----------+----------+
                       ^
  xDAI                 |
+----------------------|---------------------------------------------+
                       v
           +-----------+-------------------------------+
           |  xDAI/Ethereum AMB    +----------------+  |
           |                       |     Oracle     |  |
           |                       +----------------+  |
           |  +----------------+   +----------------+  |
           |  |     Oracle     |   |     Oracle     |  |
           |  +----------------+   +----------------+  |
           +-----------+-------------------------------+
                       ^
+----------------------|---------------------------------------------+
  Ethereum             |
                       v
            +----------+----------+
            | Foreign Arbitration |
            |        Proxy        |
            +----------+----------+
                       ^                      +------------+
                       +--------------------->+   Kleros   |
                                              +------------+

Glossary

  • Home Proxy: proxy on xDAI/Sokol.
  • Foreign Proxy: proxy on Ethereum Mainnet/Goerli.
  • Plaintiff: the dispute requester, interested in changing the current arbitrable outcome.
  • Defendant: the user interested in keeping the current arbitrable outcome.

Disclaimers

  • Users willing to request a dispute SHOULD watch the arbitrable contract on the Home Network to know when requesting dispute is possible.
  • However, if there is a time limit for when the dispute can be requested, the Arbitration Proxies CANNOT guarantee the dispute request will be notified in time. This is due to the asynchronous nature of cross-chain communication.
  • Once the dispute is created, its lifecycle will happen entirely on Ethereum.

High-Level Algorithm

Handshaking

  1. Arbitrable contracts MUST register themselves in the Home Proxy before any dispute can be created.
    1. Contracts CAN register the dispute params (namely metaEvidence, and arbitratorExtraData) at a contract level or on a per-item basis or a mix of both.
  2. The Home Proxy MUST forward the params to the Foreign Proxy.

At this point users CAN request a dispute for that given arbitrable item.

Dispute Request

  1. In order to request a dispute, the plaintiff MUST pay for the current arbitration cost beforehand.
  2. The dispute request MUST be relayed to the Home Proxy.
  3. The Home Proxy MUST check if the Arbitrable contract accepts the dispute.
    1. The arbitrable contract CAN accept or reject the request according to its own rules.
    2. If the dispute request is accepted, the information MUST be relayed to the foreign proxy, which will proceed to create the dispute.
      1. The home proxy MUST inform the arbitrable contract of the dispute request.
      2. The foreign proxy MUST now wait for the defendant to pay for the arbitration cost up to feeDepositTimeout seconds.
        1. If the defendant pays the due amount in time, then the dispute SHOULD be created.
          1. If the dispute could be created
            1. Then the foreign proxy MUST relay that information to the home proxy.
            2. Once the final ruling is recived, it MUST be relayed to the home proxy.
              1. The home proxy MUST rule over the arbitrable item.
          2. Otherwise, if the dispute creation fails
            1. Then the foreign proxy MUST relay that information to the home proxy.
              1. The home proxy MUST inform the arbitrable contract that the dispute could not be created.
        2. Otherwise, the plaintiff MUST be considered the winner
          1. The foreign proxy MUST forward the ruling to the home proxy.
          2. The home proxy MUST rule over the arbitrable item.
    3. Otherwise, the rejection MUST also be relayed to the foreign proxy.
      1. The plaintiff MUST be reimbursed of any deposited fees.
      2. The arbitration request process CAN be restarted.

State Charts

Home Proxy

(I) Means the initial state.
[condition] Means a guard condition.

     Receive Request     +----------+
   +-------------------->+ Rejected |
   |   [Rejected]        +-----+----+
   |                           |
   |                           |
   |                           | Relay Rejected
+-(I)--+                       |
| None +<----------------------+
+--+---+                       |
   |                           |
   |                           | Receive Dispute Failed
   |                           |
   | Receive Request     +-----+----+                     +--(F)--+
   +-------------------->+ Accepted +-------------------->+ Ruled |
      [Accepted]         +----------+   Receive Ruling    +-------+

Foreign Proxy

(I) Means the initial state.
(F) Means a final state.
[condition] Means a guard condition.

                                                                               [Defendant did not pay]
                                                                                      |
+-(I)--+   Request Dispute   +-----------+                  +----------------+        |        +--(F)--+
| None +-------------------->+ Requested +----------------->+ DepositPending +---------------->+ Ruled |
+------+    [Registered]     +-----+-----+    [Accepted]    +-------+--------+                 +---+---+
    A                              |                                |                              ^
    |                              |                                |                              |
    |                              | [Rejected]                     | [Defendant Paid]             |
    |                              |                                |                              | Rule
    |                              |                                |                              |
    |                              |                                |          +---------+         |
    +------------------------------+--------------------------------+--------->+ Ongoing +---------+
                                                              |           |    +---------+
                                                              |           |
                                           [Create Dispute Failed]      [Create Dispute Created]

Available Proxies

Binary Arbitration

Used by arbitrable contracts which expect a binary ruling for dispute.

Deployed Addresses

Home Proxy:

  • Sokol: <none>
  • xDai: <none>

Foreign Proxy:

  • Goerli: <none>
  • Mainnet: <none>

Contributing

Install Dependencies

yarn install

Run Tests

yarn test

Compile the Contracts

yarn build

Run Linter on Files

yarn lint

Fix Linter Issues on Files

yarn fix