DIP-1 becomes purely about off-chain #148

davidiw · 2021-03-21T05:51:48Z

Move Travel rule into an independent DIP-13
Add an optional result field to responses
Improve statements around cid on responses
Use must and instead of should around UUID requirements
Removed example code -- should be in a guide not in a spec
Introduce a PingCommand, optional
Make author's list inclusive

Action items:

DIP-13 must be created, approved, and landed before landing this
I've added a list of authors, if you don't feel your name belongs there, let me know, but I'm a big fan of being inclusive
@xli, I've noticed that the wording around cid in response makes it quite clear that it is expected to be there unless the request is unparseable, but I remember a conversation where maybe that thought wasn't consistent either in DRW or SDK or both

* Move Travel rule into an independent DIP-13 * Add an optional result field to responses * Improve statements around cid on responses * Use must and instead of should around UUID requirements * Add X-DIEM-ADDRESS as required -- this seems ... how did this get added to the specification as required? * Removed example code -- should be in a guide not in a spec * Introduce a PingCommand * Make author's list inclusive

dips/dip-1.mdx

xli · 2021-03-23T16:22:07Z

dips/dip-1.mdx

-
+| error          | [OffChainErrorObject](#offchainerrorobject) | N | Details of the error when status == "failure". |
+| result         | Object | N | An optional JSON object that may be defined when status == "success". |
+| cid            | str      | N | The Command identifier to which this is a response. Must be a UUID according to [RFC4122](https://tools.ietf.org/html/rfc4122) with "-"'s included and must match the 'cid' of the CommandRequestObject. This field must be set unless the request to which this is responding is unparseable. |


Other cases:

No cid in the request

cid in the request is not a valid uuid

Blob is valid json, but there is a field type does not match (for example: command_type value is a int), causes the deserialization failure. You probably can still parse out the cid by not deserializing json blob in this case, but need call out and handle it probably.

I think all of these imply that the request is unparseable

What you mean unparsable? The request json string is parsed successfully for all above cases.

xli · 2021-03-23T16:30:43Z

dips/dip-1.mdx


-**Reference ID**: Every Object type contains a `reference_id` field which is a unique reference ID for the Object. The reference ID is always specified by the payment initiator VASP (the VASP which originally created the Object). This value should be globally unique. It is recommended to use a 128 bit long UUID according to [RFC4122](https://tools.ietf.org/html/rfc4122) with "-"'s included.
+Each VASP exposes an HTTPS POST end point at `https://&lt;hostname>:&lt;port>/&lt;protocol_version>/command`. The protocol_version is v2 for this iteration of the off-chain APIs.


Current version need bump up to "v3"

I thought the intent of some of these changes would be to make it be done in a compatible way so that you don't need to bump the version number. If we're bumping the version number then we can and should make a lot more changes. Since going from v2 -> v3 is a "breaking" change.

Why are we bumping it to v3? This doesn't contain any breaking changes with the current protocol. Which is why I'm not sure why we included new mandatory fields in the specification doc ;)

I think bump up version for the change added.
I feel confusing when doc has v3, but the protocol version is still v2.

But up to you.

strip out X-DIEM-ADDRESS and make it clear that base_url does not support multiplexing

pdhamdhere · 2021-03-24T13:46:48Z

DIP-1 is already in Final stage. Please note partners have implemented or in the process of implementing DIP-1 as it stands today. Changing the Spec which is already final can not only create confusion but may introduce compatibility issues in production. Would the right process be to start new DIP and then deprecate DIP-1?

davidiw · 2021-03-24T14:10:55Z

DIP-1 is already in Final stage. Please note partners have implemented or in the process of implementing DIP-1 as it stands today. Changing the Spec which is already final can not only create confusion but may introduce compatibility issues in production. Would the right process be to start new DIP and then deprecate DIP-1?

What makes you feel like this is an incompatible update to the dip? It's largely improving the readability and improving the organization. If it breaks anything or creates any incompatibilities, then the update has failed it's purpose.

With respect to a new dip, the intent here being a forward compatible update, we've agreed to using versioning. If we were to introduce a completely different off chain format, say ethereum whisper, it would be a different dip.

aching · 2021-03-24T16:26:47Z

While I do appreciate that incompatible updates to a protocol are not as disruptive, I think this DIP has gone substantive changes over time and we should be following the process of DIP deprecation rather than updating it. Also as this is an optional standard, it makes sense to keep it in a draft stage until we have sufficient confidence to more to Accepted/Final (this would avoid multiple DIP deprecation/updates).

From https://dip.diem.com/overview
Deprecated – The DIP Manager or Maintainers may mark a DIP Deprecated if it is superseded by a later proposal or otherwise becomes irrelevant.
Final – The Final state of a DIP means the necessary implementations of the DIP are complete and deployed to the codebase. This DIP represents the current state-of-the-art. A Final DIP should only be updated to correct errata. (edited).

bmwill · 2021-03-25T01:52:47Z

I think this highlights a few issues with the DIP process as a whole. Specifically that DIPs cannot be looked at as a cohesive Specification. In particular it might be more ideal to have a single offchain Specification (that includes everything) and instead use the DIP process as a way to propose and ratify changes to said specification.

xli · 2021-03-25T21:40:33Z

dips/dip-1.mdx

+```
+{
+    "_ObjectType": "CommandResponseObject",
+    "result": {},


We may remove result if it is empty

xli · 2021-03-25T22:00:13Z

dips/dip-1.mdx


-**Reference ID**: Every Object type contains a `reference_id` field which is a unique reference ID for the Object. The reference ID is always specified by the payment initiator VASP (the VASP which originally created the Object). This value should be globally unique. It is recommended to use a 128 bit long UUID according to [RFC4122](https://tools.ietf.org/html/rfc4122) with "-"'s included.
+Each VASP exposes an HTTPS POST end point at `https://&lt;hostname>:&lt;port>/&lt;protocol_version>/command`. The protocol_version is v2 for this iteration of the off-chain APIs.


I think bump up version for the change added.
I feel confusing when doc has v3, but the protocol version is still v2.

But up to you.

davidiw · 2021-03-28T22:51:20Z

At this point, the plan is to take this content and leverage it in a spec instead of updating the DIP. Once the spec is fully written, we should eliminate referring to DIPs from our nomenclature and instead refer to the spec.

davidiw requested review from xli, aching, kphfb, bmwill, longbowlu and sunmilee March 21, 2021 05:51

xli reviewed Mar 23, 2021

View reviewed changes

fixup! DIP-1 becomes purely about off-chain

4ad6291

strip out X-DIEM-ADDRESS and make it clear that base_url does not support multiplexing

davidiw linked an issue Mar 24, 2021 that may be closed by this pull request

Cleanup transaction on-chain / off-chain dips #152

Open

xli reviewed Mar 25, 2021

View reviewed changes

davidiw closed this Mar 28, 2021

davidiw deleted the dip-1 branch March 29, 2021 05:27

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DIP-1 becomes purely about off-chain #148

DIP-1 becomes purely about off-chain #148

davidiw commented Mar 21, 2021 •

edited

Loading

xli Mar 23, 2021

davidiw Mar 23, 2021

xli Mar 25, 2021

xli Mar 23, 2021

bmwill Mar 23, 2021 •

edited

Loading

davidiw Mar 23, 2021

xli Mar 25, 2021

pdhamdhere commented Mar 24, 2021

davidiw commented Mar 24, 2021

aching commented Mar 24, 2021

bmwill commented Mar 25, 2021

xli Mar 25, 2021

xli Mar 25, 2021

davidiw commented Mar 28, 2021


		Reference ID: Every Object type contains a `reference_id` field which is a unique reference ID for the Object. The reference ID is always specified by the payment initiator VASP (the VASP which originally created the Object). This value should be globally unique. It is recommended to use a 128 bit long UUID according to [RFC4122](https://tools.ietf.org/html/rfc4122) with "-"'s included.
		Each VASP exposes an HTTPS POST end point at `https://<hostname>:<port>/<protocol_version>/command`. The protocol_version is v2 for this iteration of the off-chain APIs.

DIP-1 becomes purely about off-chain #148

DIP-1 becomes purely about off-chain #148

Conversation

davidiw commented Mar 21, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bmwill Mar 23, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pdhamdhere commented Mar 24, 2021

davidiw commented Mar 24, 2021

aching commented Mar 24, 2021

bmwill commented Mar 25, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

davidiw commented Mar 28, 2021

davidiw commented Mar 21, 2021 •

edited

Loading

bmwill Mar 23, 2021 •

edited

Loading