Mediators and Fees

Ink Protocol supports mediation natively 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 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.

📘

When implementing a 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 1e-18. So, if your value is 1.0 XNK, it is represented as 1e18 (1 followed by 18 zeros).

Mediation Expiry

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.

Requesting a Mediator

function requestMediator(uint256 _transactionId, uint256 _transactionAmount, address _transactionOwner) external returns (bool);

This function is called by Ink Protocol when a transaction is created by the buyer with this contract set as the mediator. Inputs include the transaction amount and the app/marketplace the transaction is taking place on, if any.

This function should return true if it accepts the responsibility of mediating the transaction if a dispute is escalated. Returning false will throw an error for the entire Ethereum transaction and the Ink Protocol transaction will not be created.

🚧

It is the responsibility of the mediator to keep track of all its transactions and listen for TransactionEscalated events, which signal that the mediator's services are needed. The Ink Protocol smart contract does not directly contact the mediator contract that a dispute has been escalated.

Fees for Transactions not Requiring Mediation

Ink Protocol allows the mediator contract to take fees on a transaction even when it concludes without an escalated dispute (this means that the mediator wasn't required to decide on the outcome of a dispute). This functionality allows mediators to earn XNK for every transaction they're part of, and can be used by marketplaces that provide their own mediation services to collect a "Transaction Fee" or "Marketplace Fee."

Ink Protocol calls functions based on the state of the transaction so that the mediator contract can differentiate. However, we imagine that in all cases where no dispute was escalated, the mediator takes either no fee or something that is low and fixed (constant across all states).

// Buyer confirms the transaction without dispute
function confirmTransactionFee(uint256 _transactionAmount) external returns (uint256);
// Seller confirms the transaction after buyer's time to dispute or confirm has passed
function confirmTransactionAfterExpiryFee(uint256 _transactionAmount) external returns (uint256);
// Buyer confirms the transaction after initiating a dispute 
function confirmTransactionAfterDisputeFee(uint256 _transactionAmount) external returns (uint256);
// Seller refunds the transaction without dispute
function refundTransactionFee(uint256 _transactionAmount) external returns (uint256);
// Buyer refunds the transaction after seller's time to escalate or refund has passed
function refundTransactionAfterExpiryFee(uint256 _transactionAmount) external returns (uint256);
// Seller refunds the transaction after a dispute is initiated
function refundTransactionAfterDisputeFee(uint256 _transactionAmount) external returns (uint256);

The function should return 0 if no fee should be taken, otherwise a uint256 representing the XNK amount (in 1e-18 XNK).

Fees for Transactions Requiring Mediation

The mediator contract is responsible for contacting Ink Protocol once it has reached a decision on a dispute. As discussed earlier there are three functions the mediator contract can call:

• confirmTransactionByMediator
• refundTransactionByMediator
• settleTransactionByMediator

Depending on the decision, the Ink Protocol smart contract will call back to the mediator contract with one of the following functions to find out what the fee for mediation is:

function confirmTransactionByMediatorFee(uint256 _transactionAmount) external returns (uint256);
function refundTransactionByMediatorFee(uint256 _transactionAmount) external returns (uint256);
function settleTransactionByMediatorFee(uint256 _buyerAmount, uint256 _sellerAmount) external returns (uint256, uint256);

When the decision is to confirm (transfer to seller) or refund (refund the buyer), only one fee amount should be returned, and that fee is deducted from the _transactionAmount before transferring or refunding the remainder to the seller or buyer.

In the event of a settle, the mediator contract should return two values, the fees to be taken from the buyer (deducted from _buyerAmount) and seller (deducted from _sellerAmount), respectively. As an example, imagine a transaction whose total amount is 20 XNK. The mediator decides to settle the transaction with 15 XNK refunded to the buyer and 5 XNK transferred to the seller.

• Ink Protocol calls the mediator contract with:
  settleTransactionByMediatorFee(15e18, 5e18)
• The function returns 5e18 and 1e18 (take 5 XNK from the buyer and 1 XNK from the seller).
• The buyer ends up with 10 XNK, the seller ends up with 4 XNK, and the mediator gets a total of 6 XNK (5 XNK + 1 XNK).