Policies

Policies represent a set of 3 time-based parameters under which a mediated Ink Protocol transaction should operate (see Implementing a Policy below). Non-mediated transactions don't require (and don't allow) a policy, because the flow is quite simple:

1. Buyer pays
2. Seller accepts (and the payment is transferred)

Mediated transactions, however, require that a policy be set when the transaction is created.

Setting a Policy

The buyer is responsible for setting the policy when creating a mediated transaction:

// Without owner
function createTransaction(address _seller, uint256 _amount, bytes32 _metadata, address _policy, address _mediator) external returns (uint256);
// With owner
function createTransaction(address _seller, uint256 _amount, bytes32 _metadata, address _policy, address _mediator, address _owner) external returns (uint256);

When the transaction is being facilitated by a marketplace/owner, oftentimes the owner will be creating the transaction on behalf of the buyer, and setting both the _policy and _mediator addresses to contracts the marketplace provides.

For transactions occurring without an owner, it is up to the buyer to find a reasonable policy to attach to the transaction. We imagine that for payment apps that support Ink Protocol, policy contracts will be provided and recommended as options for the buyer to choose from.

After a transaction is created, it's up to the seller to review both the policy and mediator contracts, and only accept the transaction if they find the terms agreeable.

Implementing a Policy

A valid policy must implement the InkPolicy Interface. The interface is quite simple, and requires three functions to be implemented:

interface InkPolicy {
  function transactionExpiry() external pure returns (uint32);
  function fulfillmentExpiry() external pure returns (uint32);
  function escalationExpiry() external pure returns (uint32);
}

transactionExpiry

The transactionExpiry function should return an amount of time (in seconds) indicating how much time a buyer is given to either confirm or dispute the transaction before the seller can unilaterally confirm and transfer payment. The time period begins when the transaction is accepted by the seller.

The purpose of this expiry is to allow the seller to complete the transaction when the buyer is non-responsive.

🚧

Setting Reasonable Expiries

Even though all three expiries are defined in seconds, they are designed to specify durations on the order of days (to account for shipping and handling times).

fulfillmentExpiry

The fulfillmentExpiry function should return an amount of time (in seconds) indicating how much time a seller is given to deliver the good or service without the buyer disputing the transaction. The time period begins when the transaction is accepted by the seller.

This expiration period allows the seller to have an uninterrupted window to deliver, and encourages patience on the buyer's side.

escalationExpiry

The escalationExpiry function should return an amount of time (in seconds) indicating how much time a seller is given to escalate a dispute to the mediator before the buyer can unilaterally refund their payment on the transaction. The time period begins once the dispute is initiated.

The purpose of this time period is to allow the buyer to complete the transaction when the seller is non-responsive.

📘

To summarize...

Once a seller accepts a transaction:

1. The buyer has transactionExpiry() time to either confirm or dispute the transaction before the seller can conclude the transaction and receive payment.
2. The seller has fulfillmentExpiry() time to deliver the goods/service before the buyer can initiate a dispute.

Once a buyer initiates a dispute:

1. The seller has escalationExpiry() time to escalate the dispute to a mediator before the buyer can conclude the transaction and get a refund.