Callbacks spec update #222
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -20,6 +20,7 @@ Version: Draft | |||||
| - [Pagination](#pagination) | ||||||
| - [Example](#example-2) | ||||||
| - [Idempotency](#idempotency) | ||||||
| - [Callbacks](#callbacks) | ||||||
| - [Protected Endpoints](#protected-endpoints) | ||||||
| - [Authentication](#authentication) | ||||||
| - [Token Generation](#token-generation) | ||||||
|
|
@@ -34,7 +35,7 @@ Version: Draft | |||||
| - [Query Params](#query-params-1) | ||||||
| - [Response](#response) | ||||||
| - [Exchanges](#exchanges) | ||||||
| - [Create Exchange](#create-exchange) | ||||||
| - [Description](#description-1) | ||||||
| - [Endpoint](#endpoint-1) | ||||||
| - [Protected](#protected-1) | ||||||
|
|
@@ -168,6 +169,17 @@ The IDs of individual tbDEX messages are used as idempotency keys | |||||
|
|
||||||
| --- | ||||||
|
|
||||||
| # Callbacks | ||||||
| Callbacks are implemented via the `replyTo` property on the [request to create an exchange](#create-exchange). | ||||||
|
|
||||||
| `replyTo` is a fully qualified URI which could either be a DID or just a URL. | ||||||
|
|
||||||
| If `replyTo` is present, a PFI will send any/all new messages for a given exchange to the supplied URI. This makes the URI scoped to each exchange, allowing the caller to specify a different URI per exchange if they so wish. | ||||||
|
|
||||||
| If `replyTo` is _not_ present, the caller will have to poll the PFI for the exchange in question to receive new messages. | ||||||
|
|
||||||
| --- | ||||||
|
|
||||||
| # Protected Endpoints | ||||||
|
|
||||||
| A **_protected endpoint_** is defined as one that requires the requester to be _authenticated_. These endpoints respond with resources specific to the authenticated DID e.g. | ||||||
|
|
@@ -258,35 +270,72 @@ False | |||||
| # Exchanges | ||||||
| An exchange is a series of linked tbDEX messages between Alice and a PFI for a single exchange. An exchange can be created by submitting an RFQ. | ||||||
|
|
||||||
| ## Create Exchange | ||||||
|
|
||||||
| ### Description | ||||||
| Submits an RFQ (Request For Quote). Alice is asking the PFI to provide a Quote so she can evaluate it. | ||||||
|
|
||||||
| ### Endpoint | ||||||
| `POST /exchanges/:exchange_id` | ||||||
|
There was a problem hiding this comment. We could take it a step further.
Suggested change
There was a problem hiding this comment. +1 to this - could this actually be applied to all our POST /exchanges/xyz endpoints, since all tbdex message metadata contain exchangeId? There was a problem hiding this comment. I'm a fan of removing it, @mistermoe any opposition? There was a problem hiding this comment. Going to open a separate issue for this because it'll require refactoring httpclient/httpserver in JS/KT outside the context of implementing callbacks |
||||||
|
|
||||||
| ### Authentication | ||||||
| Refer to [Signature Verification Section]() of the tbDEX spec | ||||||
|
|
||||||
| ### Authorization | ||||||
| No Authorization required to create an exchange | ||||||
|
|
||||||
| ### Protected | ||||||
| False | ||||||
|
|
||||||
| ### Request Body | ||||||
|
|
||||||
| #### `CreateExchangeRequest` | ||||||
| | field | data type | required | description | | ||||||
| | ---------------- | --------- | -------- | ------------------------------------------------------------------------------------------------- | | ||||||
| | `rfq` | object | Y | The request for quote | | ||||||
| | `replyTo` | string | N | A string containing a valid URI where new messages from the PFI will be sent | | ||||||
|
|
||||||
| > [!IMPORTANT] | ||||||
| > See RFQ structure [here](../protocol/README.md#rfq-request-for-quote) | ||||||
|
|
||||||
| ```json | ||||||
| { | ||||||
| "rfq": { | ||||||
| { | ||||||
| "metadata": { | ||||||
| "from": "did:key:z6Mks4N5XdrE6VieJsgH8SMSRavmTox74RqoroW7bZzBLQBi", | ||||||
| "to": "did:ex:pfi", | ||||||
| "kind": "rfq", | ||||||
| "id": "rfq_01ha835rhefwmagsknrrhvaa0k", | ||||||
| "exchangeId": "rfq_01ha835rhefwmagsknrrhvaa0k", | ||||||
| "createdAt": "2023-09-13T20:19:28.430Z" | ||||||
| }, | ||||||
| "data": { | ||||||
| "offeringId": "abcd123", | ||||||
| "payinMethod": { | ||||||
| "kind": "DEBIT_CARD", | ||||||
| "paymentDetails": "<HASH_PRIVATE_PAYIN_METHOD_PAYMENT_DETAILS>" | ||||||
| }, | ||||||
| // ... | ||||||
| } | ||||||
| } | ||||||
| }, | ||||||
| "replyTo": "https://alice.wallet.com/events" | ||||||
| } | ||||||
| ``` | ||||||
|
|
||||||
| ### Response | ||||||
| | Status | Body | | ||||||
| | ------------------ | --------------------- | | ||||||
| | `202: Accepted` | N/A | | ||||||
| | `400: Bad Request` | `{ errors: Error[] }` | | ||||||
|
|
||||||
| ### Errors | ||||||
| | Status | Description | | ||||||
| | ------ | -----------------------------| | ||||||
| | 400 | Validation error(s) | | ||||||
| | 400 | Failed Signature Check | | ||||||
| | 409 | Exchange already exists | | ||||||
phoebe-lew marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
|
||||||
| ## Get Quote/Order/OrderStatus | ||||||
|
|
||||||
|
|
||||||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
just a general q about replyTo - does the URI change depending on whether Alice is talking tbdex via a self-custodial vs custodial wallet?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The URI can actually be different per exchange. In general, no difference in terms of how the callback is used if coming from a self-custodied vs custodial wallet though.