Sender Initiated Reference ID Exchange#
| DIP | 183 |
| Title | Sender Initiated Reference ID Exchange |
| Author | Sunmi Lee (@sunmilee), David Wolinsky (@davidiw) |
| Status | Draft |
| Type | Informational |
| Created | 06/08/2021 |
Summary#
This DIP describes a protocol standard for sender initialized pre-flight exchange using reference IDs to form payment transactions.
A reference ID is used as a unique identifier for an on-chain transaction between VASPs that does not include private information of VASP users and cannot be used to link transactions by the same user. In this protocol, the sender already knows how to connect off-chain with the recipient VASP (for example, via DIP-182 and has an identifier for the recipient at their VASP. The sender VASP contacts the recipient VASP and shares the sender's identifier, a reference ID, and the recipient's identifier. In response, the receiver VASP shares its on-chain account as the destination for the transaction. Upon receiving the receiver's on-chain account, the sender VASP transmits to the blockchain a transaction with the reference ID, completing the protocol without revealing any potentially identifiable user information of either the sender or receiver on-chain.
Reference IDs are unique between a pair of VASPs, VASP A and VASP B, so if a reference ID r was used in a previous transaction between the two VASPs, regardless of which one initiated it, r cannot be reused for any future transactions between VASP A and VASP B.
However, the same r value can be used between a different VASP pair, VASP A and VASP C. VASPs may choose to keep reference IDs globally unique across all VASPs as well.
Off-Chain Preflight Protocol#
The sender VASP initiates the off-chain preflight with the command, following the off-chain protocol conventions defined in DIP-1:
CommandRequestObject:
| Field | Type | Required? | Description |
|---|---|---|---|
| _ObjectType | str | Y | Fixed value: CommandRequestObject |
| command_type | str | Y | Fixed value: SenderInitiatedReferenceIDExchange |
| command | Command object | Y | The Command to request. In this DIP, refers to SenderInitiatedReferenceIDExchangeObject |
| cid | str | Y | A unique identifier for the Command. Should be a UUID according to RFC4122 with "-"'s included. |
SenderInitiatedReferenceIDExchangeObject:
| Field | Type | Required? | Description |
|---|---|---|---|
| _ObjectType | str | Y | Fixed value: SenderInitiatedReferenceIDExchange |
| sender | str | Y | Sender's full DiemID |
| sender_address | str | Y | Sender's onchain account identifier with subaddress set to None or the zero subaddress |
| receiver | str | Y | Receiver's full DiemID |
| reference_id | str | Y | Reference ID of this transaction to be included into payment metadata |
The format of the success response is:
ReferenceIDCommandResultObject:
| Field | Type | Required? | Description |
|---|---|---|---|
| _ObjectType | str | Y | Fixed value: SenderInitiatedReferenceIDExchangeResponse |
| receiver_address | str | Y | Receiver's onchain account identifier with subaddress set to None or the zero subaddress |
Error Codes#
This protocol introduces several new error codes to the DIP-1 set of error codes:
duplicate_reference_id: Duplicate reference ID was rejected by the receiving end
invalid_receiver: Receiving end could not find the user with the given user_identifier
invalid_field_value: Reference ID is in the wrong format. See more details in DIP-1 invalid_field_value error code
On-Chain Transaction Settlement#
Transactions with PaymentMetadata require a reference ID in order to submit the transaction on-chain. PaymentMetadata reveals nothing about either the sender or receiver and do not create linkability between the sender or receiver across payments.
If the amount is below the travel rule limit, the sending VASP can send a p2p transaction with PaymentMetadata and the reference_id VASPs agreed on to settle the transaction.
If the amount is at or above the travel rule limit, VASPs must perform an off-chain identity exchange. The same reference_id must be used to perform a travel rule exchange as described in DIP-1.