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
InkMediatorinterface verify that the
msg.senderis 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).
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.
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
TransactionEscalatedevents, 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.
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).
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:
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:
- The function returns
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).
Updated about 4 years ago