Anatomy of an Ink Protocol Transaction

In this post, I’d like to go through the inner workings of the Ink Protocol smart contract (that will be released on GitHub shortly before launch). When we began defining the workflow of a transaction, we reflected on our many years of experience dealing with all sorts of outcomes and edge cases on the Listia marketplace. With that knowledge, we were able to extract and finalize what we feel is the correct, and safe, way to transact. Throughout this post, I’ll be referencing our Transaction State Diagram, which is also reproduced below, so you might want to keep that open as you follow along. Let’s dive right in!

Initiating a Transaction

All transactions are created by the buyer. The buyer specifies:

• Who the seller is (represented by an Ethereum address)
• The price of the item in tokens
• Optionally, the mediator and policy addresses (we will go over these things in the next post)
• The metadata of the transaction (this is a hashed representation of the metadata)

It may seem strange at first that the buyer is the one initiating the transaction, but this is to prevent an extra call to the Ethereum blockchain. In practice, apps supporting the Ink Protocol will wrap the entire process for buyers and sellers such that either the buyer or seller can create a transaction. Additionally, even though a buyer initiates the transaction, it does not mean that the seller is automatically held accountable for the transaction. The seller must approve the transaction before it is considered legitimate. The seller can also just ignore it completely. Meanwhile, the buyer’s funds are held in escrow by the transaction.

Revoking a Transaction

If the buyer and seller do not agree on the terms of the transaction, the seller simply ignores the transaction. The buyer however, has to revoke the transaction to get her tokens back from escrow.

Accepting a Transaction

The seller specified on the transaction can accept the transaction if he/she agrees to the terms specified by the buyer. Accepting the transaction means that the seller can confidently begin to process and ship the purchased item since the payment is secured in escrow.

Transaction in Progress

Upon accepting, the transaction is now in progress, and the seller is now on a fulfillment timer to deliver the goods as promised. The length of time allowed for fulfillment (e.g. 2 weeks) is defined in the Policy specified in the transaction. At this point, one of four things can happen:

1. If the item is not delivered within the fulfillment time, the buyer has the option to dispute the transaction.
2. If the buyer receives the item and all is well, she would confirm the transaction and the payment will be moved to the seller’s address from escrow.
3. The seller can refund the transaction if something went wrong and the seller accepts fault.
4. Enough time (defined in the Policy as the “transaction time”) has gone by and the buyer has neither confirmed nor disputed the transaction. The seller is now able to confirm the transaction himself and receive payment.

Transaction is Disputed

After the buyer disputes the transaction, the seller has a chance to respond. One of four things can happen:

1. The seller can escalate the dispute to the mediator to determine the outcome of the transaction.
2. The seller can refund the transaction.
3. The buyer can confirm the transaction.
4. The buyer can force a refund on the transaction after a time (defined in the Policy as the “escalation time”) has passed.

Transaction in Mediation

After escalation, the mediator chosen by the buyer and seller should begin the process of collecting information to make an informed decision on the outcome of the transaction. The mediator is granted a period of time, defined by “mediation time” in the Policy of the transaction, to complete this work. During this period, neither buyer nor seller can act on the transaction.

In the rare case that the mediator is non-responsive or late in their response (the “mediation time” has passed), the buyer and seller each have two options available to them. The buyer can choose to confirm the transaction, thus transferring the payment to the seller. The seller on the other hand can choose to refund the transaction. Alternatively, both the buyer and seller can unilaterally settle the transaction, causing a 50/50 split in the payment going to buyer and seller. For all three of these outcomes, no mediation fee may be taken by the mediator.

After the “mediation time”, and until the buyer or seller have taken action, the mediator can still respond to the dispute.

Transaction is Mediated

The assigned mediator is responsible for making a decision after collecting enough information from both buyer and seller. The mediator can do one of the follow:

1. Refund the transaction — payment goes back to the buyer, less the mediator’s fee.
2. Confirm the transaction — payment goes to the seller, less the mediator’s fee.
3. Settle the transaction — the payment is divided between the buyer and seller at the mediator’s discretion. The mediator can also take a mediation fee at this point as well.

Leaving Feedback

After a transaction is completed, the buyer is able to leave feedback for the seller. Completed transactions include all final states except the state when the transaction is revoked. We will be talking about feedback in another post.

Thanks for following along. We will continue to publish more technical articles and details about the Ink Protocol on Medium. These posts are great if you plan on building something on top of the Ink Protocol or if you are simply interested in how it all works. Stay tuned for more!