Skip to content

Mediation

Jump to bottom
Ngan Pham edited this page Jan 31, 2018 · 3 revisions

The Ink Protocol supports mediation directly within the smart contract. Each marketplace/app can establish their own rules and implement dispute resolution as they see fit, and users who use Ink Protocol for transactions on unmanaged marketplaces, like Craigslist and Facebook Marketplace, are free to choose their own third-party mediator, or none at all.

Mediators must interact with transactions on the Ink Protocol through a smart contract of their own. The mediator's smart contract address is recorded within the transaction's data and is queried along the lifecycle of an Ink Protocol transaction. To become a mediator, your smart contract must implement the InkMediator Interface. The interface provides several hooks for the mediator to charge their mediation/transaction fees.

Some things to note when implementing your mediator contract:

  • Make sure that all the functions defined in the InkMediator interface verify that the msg.sender is indeed the Ink Protocol contract.
  • All XNK values are represented in 1x1018. So, if your value is 1.0 XNK, it is represented as 1000000000000000000 XNK (1 followed by 18 zeros).
function requestMediator(uint256 _transactionId, uint256 _transactionAmount, address _transactionOwner) external returns (bool)

This function is called by Ink Protocol when the transaction is created by the buyer. The mediator contract must return two (ordered) values:

  • bool - To indicate whether or not the mediator accepts the mediation. Returning false will throw an error for the entire Ethereum transaction. The Ink Protocol Transaction will not be created.
function mediationExpiry() external returns (uint32)

This function returns the mediation expiry which is the duration of time (in seconds) you promise to complete your mediation work. After this period of time, the buyer or seller is able to confirm, refund, or settle the transaction. When this happens, the mediator will not receive any mediation fee.

  • uint32 - A mediation expiry, represented in seconds. This is the minimum amount of time the mediator requires to mediate a transaction once mediation has started.
function confirmTransactionFee(uint256 _transactionAmount) external returns (uint256)

This function is called by Ink Protocol when the transaction is completed through a confirmation by the buyer. The mediator contract is expected to return:

  • uint256 - The amount of XNK to take from the transaction as a transaction fee.
function confirmTransactionAfterExpiryFee(uint256 _transactionAmount) external returns (uint256)

This function is called by Ink Protocol when the transaction is completed through a confirmation by the seller after expiry. In this scenario, the buyer has failed to confirm the transaction in the allotted amount of time. The seller is now able to (and has) confirm the transaction. The mediator contract is expected to return:

  • uint256 - The amount of XNK to take from the transaction as a transaction fee.
function confirmTransactionAfterDisputeFee(uint256 _transactionAmount) external returns (uint256)

This function is called by Ink Protocol when the transaction is completed through a confirmation by the buyer, even after a dispute was initiated. In this scenario, the buyer initiated a dispute but later confirmed the transaction anyways. This is likely due to the buyer and seller coming an agreement without needing to escalate the dispute to the mediator. The mediator contract is expected to return:

  • uint256 - The amount of XNK to take from the transaction as a transaction fee.
function confirmTransactionByMediatorFee(uint256 _transactionAmount) external returns (uint256)

This function is called by Ink Protocol when the transaction is completed by the mediator. In this scenario, you, the mediator, have already decided that the transaction should be confirmed. The Ink Protocol contract will call back out to your contract to get the mediation fee. The mediator contract is expected to return:

  • uint256 - The amount of XNK to take from the transaction as a mediation fee.
function refundTransactionFee(uint256 _transactionAmount) external returns (uint256)

This function is called by Ink Protocol when the transaction is completed through a refund by the seller. The mediator contract is expected to return:

  • uint256 - The amount of XNK to take from the transaction as a transaction fee.
function refundTransactionAfterExpiryFee(uint256 _transactionAmount) external returns (uint256)

This function is called by Ink Protocol when the transaction is completed through a refund by the buyer after expiry. In this scenario, the seller has failed respond to the buyer's dispute. The buyer is now able to (and has) refund the transaction. The mediator contract is expected to return:

  • uint256 - The amount of XNK to take from the transaction as a transaction fee.
function refundTransactionAfterDisputeFee(uint256 _transactionAmount) external returns (uint256)

This function is called by Ink Protocol when the transaction is completed through a refund by the seller after a dispute was initiated. In this scenario, the seller has agreed to refund the transaction to the buyer after the buyer has initiated a dispute. The mediator contract is expected to return:

  • uint256 - The amount of XNK to take from the transaction as a transaction fee.
function refundTransactionByMediatorFee(uint256 _transactionAmount) external returns (uint256)

This function is called by Ink Protocol when the transaction is completed by the mediator. In this scenario, you, the mediator, have already decided that the transaction should be refunded. The Ink Protocol contract will call back out to your contract to get the mediation fee. The mediator contract is expected to return:

  • uint256 - The amount of XNK to take from the transaction as a mediation fee.
function settleTransactionByMediatorFee(uint256 _buyerAmount, uint256 _sellerAmount) external returns (uint256, uint256)

This function is called by Ink Protocol when the transaction is completed by the mediator. In this scenario, you, the mediator, have already decided that the transaction should be settled. Settling a transaction means that the mediator has complete control of how much of the funds should go to the buyer and seller. Please note that unlike the other functions, the two arguments here are:

  • uint256 _buyerAmount - This is the amount of XNK that you, the mediator, decided to send to the buyer.
  • uint256 _sellerAmount - This is the amount of XNK that you, the mediator, decided to send to the seller.

Keep in mind that the sum of _buyerAmount and _sellerAmount equals the total amount of the transaction. This information is passed to the function so that you have full control on how to take mediation fee. The mediator contract is expected to return two (ordered) values:

  • uint256 - The amount of XNK to take from the buyer as a mediation fee (referred as the buyerFee).
  • uint256 - The amount of XNK to take from the seller as a mediation fee (referred as the sellerFee).

The total value of XNK sent to the mediator contract will equal the sum of the two uint256 values above. By the end of the Ethereum transaction, the following parties will receive the following values:

  • Buyer will receive _buyerAmount - buyerFee.
  • Seller will receive _sellerAmount - sellerFee.
  • Mediator will receive buyerFee + sellerFee.
Clone this wiki locally