-
Notifications
You must be signed in to change notification settings - Fork 25
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Callbacks spec update #222
Changes from 4 commits
43b0a6a
5e01916
902626c
47c360b
67622a9
de30ac4
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
|
@@ -18,6 +18,7 @@ Version: Draft | |||||
- [Pagination](#pagination) | ||||||
- [Example](#example-1) | ||||||
- [Idempotency](#idempotency) | ||||||
- [Callbacks](#callbacks) | ||||||
- [Offerings](#offerings) | ||||||
- [List Offerings](#list-offerings) | ||||||
- [Description](#description) | ||||||
|
@@ -27,7 +28,7 @@ Version: Draft | |||||
- [Query Params](#query-params-1) | ||||||
- [Response](#response) | ||||||
- [Exchanges](#exchanges) | ||||||
- [Submit RFQ](#submit-rfq) | ||||||
- [Create Exchange](#create-exchange) | ||||||
- [Endpoint](#endpoint-1) | ||||||
- [Authentication](#authentication-1) | ||||||
- [Authorization](#authorization-1) | ||||||
|
@@ -156,6 +157,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. | ||||||
|
||||||
--- | ||||||
|
||||||
# Offerings | ||||||
|
||||||
The [`Offering`](../README.md#offering) resource is used to convey the currency pairs a PFI is _offering_. It includes information about payment methods and associated fees. | ||||||
|
@@ -196,34 +208,65 @@ No authorization required. Offerings are publicly accessible | |||||
# 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. | ||||||
|
||||||
## Submit RFQ | ||||||
## Create Exchange | ||||||
|
||||||
### Endpoint | ||||||
`POST /exchanges/:exchange_id/rfq` | ||||||
`POST /exchanges/:exchange_id` | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. We could take it a step further.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. +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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I'm a fan of removing it, @mistermoe any opposition? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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 submit an RFQ | ||||||
No Authorization required to create an exchange | ||||||
|
||||||
### Request Body | ||||||
|
||||||
#### `CreateExchangeRequest` | ||||||
| field | data type | required | description | | ||||||
| ---------------- | --------- | -------- | ------------------------------------------------------------------------------------------------- | | ||||||
| `rfq` | object | Y | The request for quote | | ||||||
| `replyTo` | object | N | A string containing a valid URI where new messages from the PFI will be sent | | ||||||
phoebe-lew marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
||||||
> [!IMPORTANT] | ||||||
> See RFQ structure [here](../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 | | ||||||
| 404 | Exchange not found | | ||||||
| 409 | RFQ already exists | | ||||||
| 409 | Exchange already exists | | ||||||
| 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 | ||||||
### Endpoint | ||||||
|
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.