Events

Ink Protocol uses Ethereum events to record most of the important data about an Ink Protocol transaction. Instead of storing the data directly on the smart contract (which is significantly more expensive), an event containing the relevant information is emitted.

Apps that wish to build on top of Ink Protocol therefore need to listen for these events as they occur, and possibly store a copy of that data in a local database for easier querying later on.

Below we walk through each of the custom events that the Ink Protocol smart contract emits. All XNK amounts in the parameters (eg, amount, mediatorFee, buyerAmount, etc) are specified in the smallest possible unit of XNK, 1e-18 XNK:

  • 1.5 XNK would be represented as 1.5e18 (1500000000000000000)
  • 1e-18 XNK would be represented as 1

TransactionInitiated

Emitted when a transaction is successfully created.

event TransactionInitiated(
  uint256 indexed id,
  address owner,
  address indexed buyer,
  address indexed seller,
  address policy,
  address mediator,
  uint256 amount,
  bytes32 metadata
);
ParameterDescription
idThe Ink Protocol transaction's id.
ownerOwner's (marketplace, payment app) contract address.
buyerBuyer Ethereum address.
sellerSeller Ethereum address.
policyEthereum address of the policy contract (0 if not set).
Learn more about policies
mediatorEthereum address of the mediator contract (0 if not set).
Learn more about mediators
amountTransaction amount.
metadataThe Keccak-256 hash of the transaction's metadata.
Learn more about metadata

TransactionAccepted

Emitted when a transaction is accepted by the seller. When a non-mediated transaction is accepted, this event is emitted along with the TransactionConfirmed event.

// Event emitted when a transaction has been accepted by the seller.
event TransactionAccepted(
  uint256 indexed id
);
ParameterDescription
idThe Ink Protocol transaction's id.

TransactionDisputed

Emitted when the buyer initiates a dispute on a transaction.

event TransactionDisputed(
  uint256 indexed id
);
ParameterDescription
idThe Ink Protocol transaction's id.

TransactionEscalated

Emitted when a transaction is escalated to the mediator by the seller

event TransactionEscalated(
  uint256 indexed id
);
ParameterDescription
idThe Ink Protocol transaction's id.

TransactionRevoked

Emitted when a transaction is revoked by the buyer, before the seller has accepted it.

event TransactionRevoked(
  uint256 indexed id
);
ParameterDescription
idThe Ink Protocol transaction's id.

TransactionRefundedByMediator

Emitted when the mediator resolves a dispute by siding with and refunding the payment to the buyer.

event TransactionRefundedByMediator(
  uint256 indexed id,
  uint256 mediatorFee
);
ParameterDescription
idThe Ink Protocol transaction's id.
mediatorFeeThe fee taken by the mediator.

TransactionSettledByMediator

Emitted when the mediator resolves a dispute by settling (siding with neither party), which splits the original amount between the two parties (exact amounts are decided at the discretion of the mediator).

// Event emitted when a transaction is settled by the mediator.
event TransactionSettledByMediator(
  uint256 indexed id,
  uint256 buyerAmount,
  uint256 sellerAmount,
  uint256 buyerMediatorFee,
  uint256 sellerMediatorFee
);
ParameterDescription
idThe Ink Protocol transaction's id.
buyerAmountThe amount going to the buyer, before deducting buyerMediatorFee below.
sellerAmountThe amount going to the seller, before deducting sellerMediatorFee below.
buyerMediatorFeeThe fee taken by the mediator from buyerAmount.
sellerMediatorFeeThe fee taken by the mediator from sellerAmount.

Note that the buyer and seller amounts are before fees, so:

  • buyerAmount + sellerAmount = amount (from the TransactionInitiated event)
  • Buyer actually receives buyerAmount - buyerMediatorFee
  • Seller actually receives sellerAmount - sellerMediatorFee

TransactionConfirmedByMediator

Emitted when the mediator resolves a dispute by siding with and transferring the payment to the seller.

event TransactionConfirmedByMediator(
  uint256 indexed id,
  uint256 mediatorFee
);
ParameterDescription
idThe Ink Protocol transaction's id.
mediatorFeeThe fee taken by the mediator.

TransactionConfirmed

Emitted when a transaction is confirmed by the buyer, prior to any dispute.

event TransactionConfirmed(
  uint256 indexed id,
  uint256 mediatorFee
);
ParameterDescription
idThe Ink Protocol transaction's id.
mediatorFeeThe fee taken by the mediator.

TransactionRefunded

Emitted when a transaction is refunded by the seller, prior to any dispute.

event TransactionRefunded(
  uint256 indexed id,
  uint256 mediatorFee
);
ParameterDescription
idThe Ink Protocol transaction's id.
mediatorFeeThe fee taken by the mediator.

TransactionConfirmedAfterExpiry

Emitted when a transaction is confirmed by the seller. This can only happen after the duration specified by the policy's transactionExpiry function has elapsed (ie, the buyer has been given sufficient time to confirm or dispute the transaction).

event TransactionConfirmedAfterExpiry(
  uint256 indexed id,
  uint256 mediatorFee
);
ParameterDescription
idThe Ink Protocol transaction's id.
mediatorFeeThe fee taken by the mediator.

TransactionConfirmedAfterDispute

Emitted when a transaction is confirmed by the buyer after it was disputed, but prior to being escalated.

event TransactionConfirmedAfterDispute(
  uint256 indexed id,
  uint256 mediatorFee
);
ParameterDescription
idThe Ink Protocol transaction's id.
mediatorFeeThe fee taken by the mediator.

TransactionRefundedAfterDispute

Emitted when a transaction is refunded by the seller after it was disputed, but prior to being escalated.

event TransactionRefundedAfterDispute(
  uint256 indexed id,
  uint256 mediatorFee
);
ParameterDescription
idThe Ink Protocol transaction's id.
mediatorFeeThe fee taken by the mediator.

TransactionRefundedAfterExpiry

Emitted when a disputed (but not yet escalated) transaction is refunded by the buyer. This can only happen if the duration specified in the policy's escalationExpiry function has elapsed (ie, the seller has been given sufficient time to refund or escalate the dispute).

event TransactionRefundedAfterExpiry(
  uint256 indexed id,
  uint256 mediatorFee
);
ParameterDescription
idThe Ink Protocol transaction's id.
mediatorFeeThe fee taken by the mediator.

TransactionConfirmedAfterEscalation

Emitted when a transaction with an escalated dispute is confirmed by the buyer. This can only happen if the duration specified in the mediator's mediationExpiry function has elapsed (ie, the mediator has been given sufficient time to resolve the dispute).

event TransactionConfirmedAfterEscalation(
  uint256 indexed id
);
ParameterDescription
idThe Ink Protocol transaction's id.

TransactionRefundedAfterEscalation

Emitted when a transaction with an escalated dispute is refunded by the seller. This can only happen if the duration specified in the mediator's mediationExpiry function has elapsed (ie, the mediator has been given sufficient time to resolve the dispute).

event TransactionRefundedAfterEscalation(
  uint256 indexed id
);
ParameterDescription
idThe Ink Protocol transaction's id.

TransactionSettled

Emitted when a transaction with an escalated dispute is settled by either the buyer or seller. This can only happen if the duration specified in the mediator's mediationExpiry function has elapsed (ie, the mediator has been given sufficient time to resolve the dispute).

event TransactionSettled(
  uint256 indexed id,
  uint256 buyerAmount,
  uint256 sellerAmount
);
ParameterDescription
idThe Ink Protocol transaction's id.
buyerAmountThe amount returned to the buyer.
sellerAmountThe amount transferred to the seller.

Note that in this situation, the mediator cannot take a fee and the original amount is split in half, such that buyerAmount + sellerAmount = amount. In the unlikely event that amount is not evenly divisible, the buyer receives the lesser amount, which would only ever result in a difference of 1e-18 XNK.

FeedbackUpdated

Emitted when feedback is left by the buyer. Note that this can happen multiple times, as buyers are able to continually update feedback. Only the latest feedback on a transaction should be considered when displaying a seller's reputation.

event FeedbackUpdated(
  uint256 indexed transactionId,
  uint8 rating,
  bytes32 comment
);
ParameterDescription
idThe Ink Protocol transaction's id.
ratingThe integer rating between 1 and 5 (inclusive).
commentThe Keccak-256 hash of the comment.
Learn more about feedback comments

AccountLinked

This event has nothing to do with an Ink Protocol transaction. It is emitted when one account has established a link to another account for the purpose of Account Linking. Note that successful account linking requires the link to be reciprocated.

event AccountLinked(
  address indexed from,
  address indexed to
);
ParameterDescription
fromThe address that would like to be associated with to
toThe address that from is wanting to link to