Skip to content

Commit fb6e9d2

Browse files
sunmileesunmilee
authoredJun 25, 2021
Sender Initiated Reference ID Exchange (#186)
* Sender Initiated Reference ID Exchange * Address comments * Rename reference ID objects * More details on ref ID uniqueness * Link fixes
1 parent cc34eb5 commit fb6e9d2

File tree

1 file changed

+104
-0
lines changed

1 file changed

+104
-0
lines changed
 

‎dips/dip-183.md

+104
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
---
2+
dip: 183
3+
title: Sender Initiated Reference ID Exchange
4+
authors: Sunmi Lee (@sunmilee), David Wolinsky (@davidiw)
5+
status: Draft
6+
type: Informational
7+
created: 06/08/2021
8+
last_updated: 06/08/2021
9+
issue: https://github.com/diem/dip/issues/183
10+
---
11+
12+
import useBaseUrl from '@docusaurus/useBaseUrl';
13+
14+
# Summary
15+
16+
This DIP describes a protocol standard for sender initialized pre-flight exchange using reference IDs to form payment transactions.
17+
18+
A reference ID is used as a unique identifier for an on-chain peer-to-peer transaction between VASPs without revealing on-chain any information about the peers involved.
19+
In this protocol, the sender already knows the recipient VASP address and 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.
20+
In response, the receiver VASP shares its on-chain account as the destination for the transaction.
21+
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.
22+
23+
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`.
24+
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.
25+
26+
# Off-Chain Preflight Protocol
27+
The sender VASP initiates the off-chain preflight with the command, following the off-chain protocol conventions defined in [DIP-1](https://github.com/diem/dip/blob/main/dips/dip-1.mdx):
28+
29+
```
30+
{
31+
"_ObjectType": "CommandRequestObject",
32+
"command_type": "SenderInitiatedReferenceIDExchange",
33+
"command": {
34+
"_ObjectType": "SenderInitiatedReferenceIDExchange",
35+
"sender": "alice",
36+
"sender_address": "dm1pptdxvfjck4jyw3rkfnm2mnd2t5qqqqqqqqqqqqq305frg",
37+
"receiver": "bob",
38+
"reference_id": "5b8403c9-86f5-3fe0-7230-1fe950d030cb",
39+
},
40+
"cid": "12ce83f6-6d18-0d6e-08b6-c00fdbbf085a",
41+
}
42+
```
43+
44+
**CommandRequestObject:**
45+
46+
| Field | Type | Required? | Description |
47+
|------- |------ |----------- |------------- |
48+
| _ObjectType | str | Y | Fixed value: `CommandRequestObject`|
49+
| command_type | str | Y | Fixed value: `SenderInitiatedReferenceIDExchange`|
50+
| command | Command object | Y | The Command to request. In this DIP, refers to SenderInitiatedReferenceIDExchangeObject |
51+
| cid | str | Y | A unique identifier for the Command. Should be a UUID according to [RFC4122](https://tools.ietf.org/html/rfc4122) with "-"'s included. |
52+
53+
**SenderInitiatedReferenceIDExchangeObject:**
54+
55+
| Field | Type | Required? | Description |
56+
|------- |------ |----------- |------------- |
57+
| _ObjectType | str | Y | Fixed value: `SenderInitiatedReferenceIDExchange`|
58+
| sender | str | Y | Sender's full DiemID |
59+
| sender_address| str | Y | Sender's onchain [account identifier](https://github.com/diem/dip/blob/main/dips/dip-5.md) with subaddress set to `None` or the zero subaddress|
60+
| receiver | str | Y | Receiver's full DiemID |
61+
| reference_id | str | Y | Reference ID of this transaction to be included into payment metadata |
62+
63+
64+
The format of the success response is:
65+
```
66+
{
67+
"_ObjectType": "CommandResponseObject",
68+
"status": "success",
69+
"result": {
70+
"_ObjectType": "SenderInitiatedReferenceIDExchangeResponse",
71+
"receiver_address": "dm1p7ujcndcl7nudzwt8fglhx6wxn08kgs5tm6mz4us2vfufk",
72+
},
73+
"cid": "12ce83f6-6d18-0d6e-08b6-c00fdbbf085a",
74+
}
75+
```
76+
77+
**ReferenceIDCommandResultObject:**
78+
79+
| Field | Type | Required? | Description |
80+
|------- |------ |----------- |------------- |
81+
| _ObjectType | str | Y | Fixed value: `SenderInitiatedReferenceIDExchangeResponse`|
82+
| receiver_address | str | Y | Receiver's onchain [account identifier](https://github.com/diem/dip/blob/main/dips/dip-5.md) with subaddress set to `None` or the zero subaddress |
83+
84+
## Error Codes
85+
This protocol introduces several new error codes to the [DIP-1 set of error codes](https://github.com/diem/dip/blob/main/dips/dip-1.mdx#list-of-error-codes):
86+
87+
`duplicate_reference_id`: Duplicate reference ID was rejected by the receiving end
88+
89+
`invalid_receiver`: Receiving end could not find the user with the given user_identifier
90+
91+
`invalid_field_value`: Reference ID is in the wrong format. See more details in [DIP-1 `invalid_field_value` error code](https://github.com/diem/dip/blob/main/dips/dip-1.mdx#request-object-validation-error-codes)
92+
93+
## On-Chain Transaction Settlement
94+
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.
95+
96+
```
97+
enum PaymentMetadata {
98+
PaymentMetadataV0(ReferenceId),
99+
}
100+
type ReferenceId = [u8, 16];
101+
```
102+
103+
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.
104+
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](https://github.com/diem/dip/blob/master/dips/dip-1.md).

0 commit comments

Comments
 (0)