search

TBD54566975 / tbdex

56 stars 26 forks source link

Consider resolving the semantic duplication of exchange finality across `OrderStatus.status` and `Close.success` #258

Closed KendallWeihe closed 8 months ago

KendallWeihe commented 8 months ago

Originally ideated upon here https://github.com/TBD54566975/tbdex/issues/255#issuecomment-1979684456

Requirement

We need a way for wallet GUI applications to map order execution states (whatever those may be) to given GUI visualizations

Problem

The problem being faced here is one of potential DX confusion cause by duplicate concepts.

The story of a PFI coming to tbdex for the first time may go as such:

  1. "Okay I'm a PFI so I need to define my own set of OrderStatus status'"
  2. "Well, logically that means one of my OrderStatus status' will be something like COMPLETED or maybe EXECUTED or SUCCESSFULLY_EXECUTED"
  3. "Oh but what's this Close thing? Oh I need to also include a Close message at the end of my order execution even though I already have defined my OrderStatus for that state"

It's entirely possible the above is acceptable in that there does not exist any undoubtedly better alternatives, but nevertheless I think it would be a benefit to explore alternatives if only to rule out the alternatives.

Proposals

Well-defined OrderStatus status enums

One such proposal is in the ticket here https://github.com/TBD54566975/tbdex/issues/256. Which is, we define a set of well-known OrderStatus status values which all PFIs must implement, with the expectation PFIs may also implement additional OrderStatus statue values (unique to their given situation). Those status' may be, for example, as simple as PENDING, SUCCESSFUL and FAILED. In this proposal, we may no longer have a need for the Close message, in which case we would remove the duplication.

Application-specific OrderStatus specifications

We may choose to rollup (so-to-speak) the responsibility of defining OrderStatus state machines into application-specific use cases. For example, one could imagine a tbdex-application specification for blockchain exchanges wherein the order execution is the identical state machine across all blockchain exchanges, and then a different specification for credit cards.

phoebe-lew commented 8 months ago

After having a read through this and the other issue, it seems that there is not an existing pain point that this will address. The DX confusion mentioned is possible even with the proposed solutions. A PFI could send a OrderStatus.SUCCESSFUL followed by an OrderStatus.FAILED, which is an application level error, not something that can be controlled by the protocol. In fact, keeping Close as well as OrderStatus at least allows us to put guard rails in by not allowing subsequent OrderStatuses after a Close has been sent.

Also echoing @mistermoe's sentiment that tbdex should not attempt to solve state machines for a bunch of different payment rails, which are PFI dependent.