From a51c4ed8799080b762a96b60fda74d61db414ab7 Mon Sep 17 00:00:00 2001 From: Jamie Li Date: Fri, 3 Jan 2025 12:52:46 +0800 Subject: [PATCH] Refactor on_chagne_callback in favor of STATUS_CALLBACK_URL --- ecosystem/sep-0001.md | 29 ++++++------ ecosystem/sep-0006.md | 106 +++++++++++++++++++++++------------------- ecosystem/sep-0024.md | 98 +++++++++----------------------------- 3 files changed, 95 insertions(+), 138 deletions(-) diff --git a/ecosystem/sep-0001.md b/ecosystem/sep-0001.md index d287bab37..158d3bd57 100644 --- a/ecosystem/sep-0001.md +++ b/ecosystem/sep-0001.md @@ -58,22 +58,23 @@ Documentation sections. These are global fields in the `stellar.toml` file. -| Field | Requirements | Description | -| ----------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -| VERSION | string | The version of SEP-1 your `stellar.toml` adheres to. This helps parsers know which fields to expect. | -| NETWORK_PASSPHRASE | string | The passphrase for the specific [Stellar network](https://www.stellar.org/developers/guides/concepts/networks.html) this infrastructure operates on | -| FEDERATION_SERVER | uses `https://` | The endpoint for clients to resolve stellar addresses for users on your domain via [SEP-2](sep-0002.md) Federation Protocol | -| AUTH_SERVER | uses `https://` | (deprecated) The endpoint used for [SEP-3](sep-0003.md) Compliance Protocol | -| TRANSFER_SERVER | uses `https://` | The server used for [SEP-6](sep-0006.md) Anchor/Client interoperability | +| Field | Requirements | Description | +|----------------| ---------------------- |-----------------------------------------------------------------------------------------------------------------------------------------------------------| +| VERSION | string | The version of SEP-1 your `stellar.toml` adheres to. This helps parsers know which fields to expect. | +| NETWORK_PASSPHRASE | string | The passphrase for the specific [Stellar network](https://www.stellar.org/developers/guides/concepts/networks.html) this infrastructure operates on | +| FEDERATION_SERVER | uses `https://` | The endpoint for clients to resolve stellar addresses for users on your domain via [SEP-2](sep-0002.md) Federation Protocol | +| AUTH_SERVER | uses `https://` | (deprecated) The endpoint used for [SEP-3](sep-0003.md) Compliance Protocol | +| TRANSFER_SERVER | uses `https://` | The server used for [SEP-6](sep-0006.md) Anchor/Client interoperability | | TRANSFER_SERVER_SEP0024 | uses `https://` | The server used for [SEP-24](sep-0024.md) Anchor/Client interoperability | -| KYC_SERVER | uses `https://` | The server used for [SEP-12](sep-0012.md) Anchor/Client customer info transfer | -| WEB_AUTH_ENDPOINT | uses `https://` | The endpoint used for [SEP-10 Web Authentication](sep-0010.md) | -| SIGNING_KEY | Stellar public key | The signing key is used for [SEP-3](sep-0003.md) Compliance Protocol (deprecated) and [SEP-10](sep-0010.md) Authentication Protocol | -| HORIZON_URL | url | Location of public-facing Horizon instance (if you offer one) | -| ACCOUNTS | list of `G...` strings | A list of Stellar accounts that are controlled by this domain | +| KYC_SERVER | uses `https://` | The server used for [SEP-12](sep-0012.md) Anchor/Client customer info transfer | +| WEB_AUTH_ENDPOINT | uses `https://` | The endpoint used for [SEP-10 Web Authentication](sep-0010.md) | +| SIGNING_KEY | Stellar public key | The signing key is used for [SEP-3](sep-0003.md) Compliance Protocol (deprecated) and [SEP-10](sep-0010.md) Authentication Protocol | +| HORIZON_URL | url | Location of public-facing Horizon instance (if you offer one) | +| ACCOUNTS | list of `G...` strings | A list of Stellar accounts that are controlled by this domain | | URI_REQUEST_SIGNING_KEY | Stellar public key | The signing key is used for [SEP-7](sep-0007.md) delegated signing | -| DIRECT_PAYMENT_SERVER | uses `https://` | The server used for receiving [SEP-31](sep-0031.md) direct fiat-to-fiat payments. Requires [SEP-12](sep-0012.md) and hence a `KYC_SERVER` TOML attribute. | -| ANCHOR_QUOTE_SERVER | uses `https://` | The server used for receiving [SEP-38](sep-0038.md) requests. | +| DIRECT_PAYMENT_SERVER | uses `https://` | The server used for receiving [SEP-31](sep-0031.md) direct fiat-to-fiat payments. Requires [SEP-12](sep-0012.md) and hence a `KYC_SERVER` TOML attribute. | +| ANCHOR_QUOTE_SERVER | uses `https://` | The server used for receiving [SEP-38](sep-0038.md) requests. | +| STATUS_CALLBACK_URL | uses `https://` | The URL used for receiving [SEP-6](sep-0006.md) and [SEP-24](sep-0024.md) transaction status change callbacks. | ### Organization Documentation diff --git a/ecosystem/sep-0006.md b/ecosystem/sep-0006.md index 12eaa464a..54d9d1dff 100644 --- a/ecosystem/sep-0006.md +++ b/ecosystem/sep-0006.md @@ -183,10 +183,21 @@ Access-Control-Allow-Origin: * This protocol involves the transfer of value, and so HTTPS is required for all endpoints for security. Wallets and anchors should refuse to interact with any insecure HTTP endpoints. -## Callback signature - +## Transaction Status Callback This protocol involves the optional use of callbacks that the Anchor can issue to update the wallet on `status` of a -transaction. In order to validate the integrity and provenance of the callback, the Anchor MUST include a signature in +transaction. + +### On Change Callback URL +The wallet server can optionally provide the Anchor with a URL to send a callback to when the status of a transaction +has changed via the `STATUS_CALLBACK_URL` field in the wallet's [`stellar.toml`](sep-0001.md). The Anchor should POST a +JSON message to when the status property of the transaction created as a result of this request changes. The JSON +message should be identical to the response format for the /transaction endpoint. The callback needs to be signed by the +anchor and the signature needs to be verified by the wallet according to the callback signature specification. + +The payload of the callback should be the same as the response of the `GET /transaction` endpoint. + +### Callback Signature +In order to validate the integrity and provenance of the callback, the Anchor MUST include a signature in the HTTP Header `Signature` or `X-Stellar-Signature` (**Deprecated**). Wallets should support both headers until the `X-Stellar-Signature` header is removed from the specification. @@ -206,7 +217,7 @@ It is the wallet's responsibility to: [`stellar.toml`](sep-0001.md). - Verify the freshness of the request by comparing the `timestamp` in the request with the current timestamp at the time of the reception and discard every request above a threshold of few seconds (1 or 2 minute(s) maximum). -- Send a working callback URL (parameter `on_change_callback`) to the anchor. +- Specify a working callback URL via `STATUS_CALLBACK_URL` field of the [`stellar.toml`](sep-0001.md) file to the anchor. ### VERIFY signature @@ -403,24 +414,24 @@ GET TRANSFER_SERVER/deposit Request Parameters: -| Name | Type | Description | -| ----------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `asset_code` | string | The code of the on-chain asset the user wants to get from the Anchor after doing an off-chain deposit. The value passed must match one of the codes listed in the [/info](#info) response's deposit object. | -| `account` | `G...` or `M...` string | The stellar or muxed account ID of the user that wants to deposit. This is where the asset token will be sent. Note that the account specified in this request could differ from the account authenticated via SEP-10. | -| `funding_method` | string | A method supported by the Anchor for transferring or settling assets. Must match one of the values specified in the corresponding `/info` response. This field is required to help the Anchor identify the necessary KYC information to collect. | -| `memo_type` | string | (optional) Type of memo that the anchor should attach to the Stellar payment transaction, one of `text`, `id` or `hash`. | -| `memo` | string | (optional) Value of memo to attach to transaction, for `hash` this should be base64-encoded. Because a memo can be specified in the SEP-10 JWT for [Shared Accounts](#shared-omnibus-or-pooled-accounts), this field as well as `memo_type` can be different than the values included in the SEP-10 JWT. For example, a client application could use the value passed for this parameter as a reference number used to match payments made to `account`. | -| `email_address` | string | (optional) Email address of depositor. If desired, an anchor can use this to send email updates to the user about the deposit. | -| `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646]. `error` fields and other human readable messages in the response should be in this language. | -| `on_change_callback` | string | (optional) A URL that the anchor should `POST` a JSON message to when the `status` property of the transaction created as a result of this request changes. The JSON message should be identical to the response format for the [/transaction](#single-historical-transaction) endpoint. The callback needs to be signed by the anchor and the signature needs to be verified by the wallet according to the [callback signature specification](#callback-signature). | -| `amount` | string | (optional) The amount of the asset the user would like to deposit with the anchor. This field may be necessary for the anchor to determine what KYC information is necessary to collect. | -| `country_code` | string | (optional) The [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code of the user's current address. This field may be necessary for the anchor to determine what KYC information is necessary to collect. | -| `claimable_balance_supported` | string | (optional) `true` if the client supports receiving deposit transactions as a claimable balance, `false` otherwise. | -| `customer_id` | string | (optional) id of an off-chain account (managed by the anchor) associated with this user's Stellar account (identified by the JWT's `sub` field). If the anchor supports [SEP-12], the `customer_id` field should match the [SEP-12] customer's id. `customer_id` should be passed only when the off-chain id is know to the client, but the relationship between this id and the user's Stellar account is not known to the Anchor. | -| `location_id` | string | (optional) optional) id of the chosen location to drop off cash | -| `type` | string | (**Deprecated** in favor of `funding_method`) Type of deposit. If the Anchor supports multiple deposit methods (e.g. `SEPA` or `SWIFT`), the wallet should specify `type`. This field may be necessary for the anchor to determine which KYC fields to collect. | -| `wallet_name` | string | (**Deprecated**, optional) In communications / pages about the deposit, anchor should display the wallet name to the user to explain where funds are going. However, anchors should use client_domain (for non-custodial) and `sub` value of JWT (for custodial) to determine wallet information. | -| `wallet_url` | string | (**Deprecated**, optional) Anchor should link to this when notifying the user that the transaction has completed. However, anchors should use client_domain (for non-custodial) and `sub` value of JWT (for custodial) to determine wallet information. | +| Name | Type | Description | +| ----------------------------- | ----------------------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `asset_code` | string | The code of the on-chain asset the user wants to get from the Anchor after doing an off-chain deposit. The value passed must match one of the codes listed in the [/info](#info) response's deposit object. | +| `account` | `G...` or `M...` string | The stellar or muxed account ID of the user that wants to deposit. This is where the asset token will be sent. Note that the account specified in this request could differ from the account authenticated via SEP-10. | +| `funding_method` | string | A method supported by the Anchor for transferring or settling assets. Must match one of the values specified in the corresponding `/info` response. This field is required to help the Anchor identify the necessary KYC information to collect. | +| `memo_type` | string | (optional) Type of memo that the anchor should attach to the Stellar payment transaction, one of `text`, `id` or `hash`. | +| `memo` | string | (optional) Value of memo to attach to transaction, for `hash` this should be base64-encoded. Because a memo can be specified in the SEP-10 JWT for [Shared Accounts](#shared-omnibus-or-pooled-accounts), this field as well as `memo_type` can be different than the values included in the SEP-10 JWT. For example, a client application could use the value passed for this parameter as a reference number used to match payments made to `account`. | +| `email_address` | string | (optional) Email address of depositor. If desired, an anchor can use this to send email updates to the user about the deposit. | +| `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646]. `error` fields and other human readable messages in the response should be in this language. | +| `on_change_callback` | string | (**deprecated** in favor of `STATUS_CALLBACK_URL` of the [SEP-1](sep0001.md)). | +| `amount` | string | (optional) The amount of the asset the user would like to deposit with the anchor. This field may be necessary for the anchor to determine what KYC information is necessary to collect. | +| `country_code` | string | (optional) The [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code of the user's current address. This field may be necessary for the anchor to determine what KYC information is necessary to collect. | +| `claimable_balance_supported` | string | (optional) `true` if the client supports receiving deposit transactions as a claimable balance, `false` otherwise. | +| `customer_id` | string | (optional) id of an off-chain account (managed by the anchor) associated with this user's Stellar account (identified by the JWT's `sub` field). If the anchor supports [SEP-12], the `customer_id` field should match the [SEP-12] customer's id. `customer_id` should be passed only when the off-chain id is know to the client, but the relationship between this id and the user's Stellar account is not known to the Anchor. | +| `location_id` | string | (optional) optional) id of the chosen location to drop off cash | +| `type` | string | (**Deprecated** in favor of `funding_method`) Type of deposit. If the Anchor supports multiple deposit methods (e.g. `SEPA` or `SWIFT`), the wallet should specify `type`. This field may be necessary for the anchor to determine which KYC fields to collect. | +| `wallet_name` | string | (**Deprecated**, optional) In communications / pages about the deposit, anchor should display the wallet name to the user to explain where funds are going. However, anchors should use client_domain (for non-custodial) and `sub` value of JWT (for custodial) to determine wallet information. | +| `wallet_url` | string | (**Deprecated**, optional) Anchor should link to this when notifying the user that the transaction has completed. However, anchors should use client_domain (for non-custodial) and `sub` value of JWT (for custodial) to determine wallet information. | The request parameters also must include the required fields from the `/info` endpoint. @@ -716,7 +727,7 @@ Request parameters: | `account` | `G...` or `M...` string | (optional) The Stellar or muxed account the client will use as the source of the withdrawal payment to the anchor. If SEP-10 authentication is not used, the anchor can use `account` to look up the user's KYC information. Note that the account specified in this request could differ from the account authenticated via SEP-10. | | `memo` | string | (optional) This field should only be used if SEP-10 authentication is not. It was originally intended to distinguish users of the same Stellar account. However if SEP-10 is supported, the anchor should use the `sub` value included in the decoded SEP-10 JWT instead. See the [Shared Account Authentication](#shared-omnibus-or-pooled-accounts) section for more information. | | `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646]. `error` fields and other human readable messages in the response should be in this language. | -| `on_change_callback` | string | (optional) A URL that the anchor should `POST` a JSON message to when the `status` property of the transaction created as a result of this request changes. The JSON message should be identical to the response format for the [/transaction](#single-historical-transaction) endpoint. The callback needs to be signed by the anchor and the signature needs to be verified by the wallet according to the [callback signature specification](#callback-signature). | +| `on_change_callback` | string | (**deprecated** in favor of `STATUS_CALLBACK_URL` of the [SEP-1](sep0001.md)). | | `amount` | string | (optional) The amount of the asset the user would like to withdraw. This field may be necessary for the anchor to determine what KYC information is necessary to collect. | | `country_code` | string | (optional) The [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code of the user's current address. This field may be necessary for the anchor to determine what KYC information is necessary to collect. | | `refund_memo` | string | (optional) The memo the anchor must use when sending refund payments back to the user. If not specified, the anchor should use the same memo used by the user to send the original payment. If specified, `refund_memo_type` must also be specified. | @@ -816,26 +827,26 @@ GET TRANSFER_SERVER/deposit-exchange Request Parameters: -| Name | Type | Description | -| ----------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `destination_asset` | string | The code of the on-chain asset the user wants to get from the Anchor after doing an off-chain deposit. The value passed must match one of the codes listed in the [/info](#info) response's `deposit-exchange` object. | -| `source_asset` | string | The off-chain asset the Anchor will receive from the user. The value must match one of the `asset` values included in a [`SEP-38 GET /prices?buy_asset=stellar::`](sep-0038.md#get-prices) response using [SEP-38 Asset Identification Format](sep-0038.md#asset-identification-format). | -| `amount` | string | The amount of the `source_asset` the user would like to deposit to the anchor's off-chain account. This field may be necessary for the anchor to determine what KYC information is necessary to collect. Should be equals to `quote.sell_amount` if a `quote_id` was used. | -| `funding_method` | string | A method supported by the Anchor for transferring or settling assets. Must match one of the values specified in the corresponding `/info` response. This field is required to help the Anchor identify the necessary KYC information to collect. | -| `account` | `G...` or `M...` string | The stellar or muxed account ID of the user that wants to deposit. This is where the asset token will be sent. Note that the account specified in this request could differ from the account authenticated via SEP-10. | -| `quote_id` | string | (optional) The `id` returned from a `SEP-38 POST /quote` response. If this parameter is provided and the user delivers the deposit funds to the Anchor before the quote expiration, the Anchor should respect the conversion rate agreed in that quote. If the values of `destination_asset`, `source_asset`, `amount` and `funding_method` conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | -| `memo_type` | string | (optional) Type of memo that the anchor should attach to the Stellar payment transaction, one of `text`, `id` or `hash`. | -| `memo` | string | (optional) Value of memo to attach to transaction, for `hash` this should be base64-encoded. Because a memo can be specified in the SEP-10 JWT for [Shared Accounts](#shared-omnibus-or-pooled-accounts), this field as well as `memo_type` can be different than the values included in the SEP-10 JWT. For example, a client application could use the value passed for this parameter as a reference number used to match payments made to `account`. | -| `email_address` | string | (optional) Email address of depositor. If desired, an anchor can use this to send email updates to the user about the deposit. | -| `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646]. `error` fields and other human readable messages in the response should be in this language. | -| `on_change_callback` | string | (optional) A URL that the anchor should `POST` a JSON message to when the `status` property of the transaction created as a result of this request changes. The JSON message should be identical to the response format for the [/transaction](#single-historical-transaction) endpoint. The callback needs to be signed by the anchor and the signature needs to be verified by the wallet according to the [callback signature specification](#callback-signature). | -| `country_code` | string | (optional) The [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code of the user's current address. This field may be necessary for the anchor to determine what KYC information is necessary to collect. | -| `claimable_balance_supported` | string | (optional) `true` if the client supports receiving deposit transactions as a claimable balance, `false` otherwise. | -| `customer_id` | string | (optional) id of an off-chain account (managed by the anchor) associated with this user's Stellar account (identified by the JWT's `sub` field). If the anchor supports [SEP-12], the `customer_id` field should match the [SEP-12] customer's id. `customer_id` should be passed only when the off-chain id is know to the client, but the relationship between this id and the user's Stellar account is not known to the Anchor. | -| `location_id` | string | (optional) optional) id of the chosen location to drop off cash | -| `type` | string | (**Deprecated** in favor of `funding_method`) Type of deposit. If the Anchor supports multiple deposit methods (e.g. `SEPA` or `SWIFT`), the wallet should specify `type`. This field may be necessary for the anchor to determine which KYC fields to collect. | -| `wallet_name` | string | (**Deprecated**, optional) In communications / pages about the deposit, anchor should display the wallet name to the user to explain where funds are going. However, anchors should use client_domain (for non-custodial) and `sub` value of JWT (for custodial) to determine wallet information. | -| `wallet_url` | string | (**Deprecated**, optional) Anchor should link to this when notifying the user that the transaction has completed. However, anchors should use client_domain (for non-custodial) and `sub` value of JWT (for custodial) to determine wallet information. | +| Name | Type | Description | +| ----------------------------- | ----------------------- |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `destination_asset` | string | The code of the on-chain asset the user wants to get from the Anchor after doing an off-chain deposit. The value passed must match one of the codes listed in the [/info](#info) response's `deposit-exchange` object. | +| `source_asset` | string | The off-chain asset the Anchor will receive from the user. The value must match one of the `asset` values included in a [`SEP-38 GET /prices?buy_asset=stellar::`](sep-0038.md#get-prices) response using [SEP-38 Asset Identification Format](sep-0038.md#asset-identification-format). | +| `amount` | string | The amount of the `source_asset` the user would like to deposit to the anchor's off-chain account. This field may be necessary for the anchor to determine what KYC information is necessary to collect. Should be equals to `quote.sell_amount` if a `quote_id` was used. | +| `funding_method` | string | A method supported by the Anchor for transferring or settling assets. Must match one of the values specified in the corresponding `/info` response. This field is required to help the Anchor identify the necessary KYC information to collect. | +| `account` | `G...` or `M...` string | The stellar or muxed account ID of the user that wants to deposit. This is where the asset token will be sent. Note that the account specified in this request could differ from the account authenticated via SEP-10. | +| `quote_id` | string | (optional) The `id` returned from a `SEP-38 POST /quote` response. If this parameter is provided and the user delivers the deposit funds to the Anchor before the quote expiration, the Anchor should respect the conversion rate agreed in that quote. If the values of `destination_asset`, `source_asset`, `amount` and `funding_method` conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | +| `memo_type` | string | (optional) Type of memo that the anchor should attach to the Stellar payment transaction, one of `text`, `id` or `hash`. | +| `memo` | string | (optional) Value of memo to attach to transaction, for `hash` this should be base64-encoded. Because a memo can be specified in the SEP-10 JWT for [Shared Accounts](#shared-omnibus-or-pooled-accounts), this field as well as `memo_type` can be different than the values included in the SEP-10 JWT. For example, a client application could use the value passed for this parameter as a reference number used to match payments made to `account`. | +| `email_address` | string | (optional) Email address of depositor. If desired, an anchor can use this to send email updates to the user about the deposit. | +| `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646]. `error` fields and other human readable messages in the response should be in this language. | +| `on_change_callback` | string | (**deprecated** in favor of `STATUS_CALLBACK_URL` of the [SEP-1](sep0001.md)). | +| `country_code` | string | (optional) The [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code of the user's current address. This field may be necessary for the anchor to determine what KYC information is necessary to collect. | +| `claimable_balance_supported` | string | (optional) `true` if the client supports receiving deposit transactions as a claimable balance, `false` otherwise. | +| `customer_id` | string | (optional) id of an off-chain account (managed by the anchor) associated with this user's Stellar account (identified by the JWT's `sub` field). If the anchor supports [SEP-12], the `customer_id` field should match the [SEP-12] customer's id. `customer_id` should be passed only when the off-chain id is know to the client, but the relationship between this id and the user's Stellar account is not known to the Anchor. | +| `location_id` | string | (optional) optional) id of the chosen location to drop off cash | +| `type` | string | (**Deprecated** in favor of `funding_method`) Type of deposit. If the Anchor supports multiple deposit methods (e.g. `SEPA` or `SWIFT`), the wallet should specify `type`. This field may be necessary for the anchor to determine which KYC fields to collect. | +| `wallet_name` | string | (**Deprecated**, optional) In communications / pages about the deposit, anchor should display the wallet name to the user to explain where funds are going. However, anchors should use client_domain (for non-custodial) and `sub` value of JWT (for custodial) to determine wallet information. | +| `wallet_url` | string | (**Deprecated**, optional) Anchor should link to this when notifying the user that the transaction has completed. However, anchors should use client_domain (for non-custodial) and `sub` value of JWT (for custodial) to determine wallet information. | Examples: @@ -880,7 +891,7 @@ Request parameters: | `account` | `G...` or `M...` string | (optional) The Stellar or muxed account of the user that wants to do the withdrawal. This is only needed if the anchor requires KYC information for withdrawal and SEP-10 authentication is not used. Instead, the anchor can use `account` to look up the user's KYC information. Note that the account specified in this request could differ from the account authenticated via SEP-10. | | `memo` | string | (optional) This field should only be used if SEP-10 authentication is not. It was originally intended to distinguish users of the same Stellar account. However if SEP-10 is supported, the anchor should use the `sub` value included in the decoded SEP-10 JWT instead. See the [Shared Account Authentication](#shared-omnibus-or-pooled-accounts) section for more information. | | `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646]. `error` fields and other human readable messages in the response should be in this language. | -| `on_change_callback` | string | (optional) A URL that the anchor should `POST` a JSON message to when the `status` property of the transaction created as a result of this request changes. The JSON message should be identical to the response format for the [/transaction](#single-historical-transaction) endpoint. The callback needs to be signed by the anchor and the signature needs to be verified by the wallet according to the [callback signature specification](#callback-signature). | +| `on_change_callback` | string | (**deprecated** in favor of `STATUS_CALLBACK_URL` of the [SEP-1](sep0001.md)). | | `country_code` | string | (optional) The [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code of the user's current address. This field may be necessary for the anchor to determine what KYC information is necessary to collect. | | `refund_memo` | string | (optional) The memo the anchor must use when sending refund payments back to the user. If not specified, the anchor should use the same memo used by the user to send the original payment. If specified, `refund_memo_type` must also be specified. | | `refund_memo_type` | string | (optional) The type of the `refund_memo`. Can be `id`, `text`, or `hash`. See the [memos](https://developers.stellar.org/docs/encyclopedia/memos) documentation for more information. If specified, `refund_memo` must also be specified. | @@ -985,9 +996,10 @@ Once the deposit or withdraw request has been made and KYC information has been [SEP-12](sep-0012.md), the wallet will need to detect that the anchor has completed flow by checking the `status` field of the transaction. -The wallet can either provide the anchor with an `on_change_callback` and check the `status` property of the transaction -object passed in the callback request, or the wallet can poll the anchor's `GET /transactions` endpoints and match the -transaction object using the `memo` and `memo_type` used in the deposit request or withdraw success response. +The wallet can either provide the anchor with the callback URL via the `STATUS_CALLBACK_URL` of the +[`stellar.toml`](sep-0001.md) and check the `status` property of the transaction object passed in the callback request, +or the wallet can poll the anchor's `GET /transactions` endpoints and match the transaction object using the `memo` and +`memo_type` used in the deposit request or withdraw success response. If transaction response object has a JSON `status` field set to `incomplete`, it means the user still needs to be KYC'ed using [SEP-12](sep-0012.md). In this case, the wallet should collect the fields with either: diff --git a/ecosystem/sep-0024.md b/ecosystem/sep-0024.md index 8e5410ed8..6367c208f 100644 --- a/ecosystem/sep-0024.md +++ b/ecosystem/sep-0024.md @@ -195,7 +195,20 @@ implemented in all the endpoints that support Cross-Origin. This protocol involves the transfer of value, and so HTTPS is required for all endpoints for security. Wallets and anchors should refuse to interact with any insecure HTTP endpoints. -## URL Callback signature +## Transaction Status Callback +This protocol involves the optional use of callbacks that the Anchor can issue to update the wallet on `status` of a +transaction. + +### On Change Callback URL +The wallet server can optionally provide the Anchor with a URL to send a callback to when the status of a transaction +has changed via the `STATUS_CALLBACK_URL` field in the wallet's [`stellar.toml`](sep-0001.md). The Anchor should POST a +JSON message to when the status property of the transaction created as a result of this request changes. The JSON +message should be identical to the response format for the /transaction endpoint. The callback needs to be signed by the +anchor and the signature needs to be verified by the wallet according to the callback signature specification. + +The payload of the callback should be the same as the response of the `GET /transaction` endpoint. + +### Callback Signature _Note that the signature discussed here is only for **URL callbacks** and does not apply to **`postMessage` callbacks**_ @@ -220,7 +233,7 @@ It is the wallet's responsibility to: [`stellar.toml`](sep-0001.md). - Verify the freshness of the request by comparing the `timestamp` in the request with the current timestamp at the time of the reception and discard every request above a threshold of few seconds (1 or 2 minute(s) maximum). -- Send a working callback URL (parameter `callback` or `on_change_callback`) to the anchor. +- Specify a working callback URL via `STATUS_CALLBACK_URL` field of the [`stellar.toml`](sep-0001.md) file to the anchor. ### VERIFY signature @@ -680,86 +693,17 @@ Example response: } ``` -#### Adding parameters to the URL +#### Adding `callback` and `on_change_callback` parameters to the URL +(**deprecated** in favor of `STATUS_CALLBACK_URL` of the [SEP-1](sep0001.md)) Before the wallet sends the user to the `url` field received from the anchor, it may add query parameters to the URL. The basic parameters are summarized in the table below. -| Name | Type | Description | -| -------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `callback` | string | (optional) [`postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) or a URL that the anchor should `POST` a JSON message to when the user successfully completes the interactive flow. If the callback is a URL (not a `postMessage`), it needs to be signed by the anchor and the signature needs to be verified by the wallet according to the [callback signature specification](#callback-signature). | -| `on_change_callback` | string | (optional) [`postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) or a URL that the anchor should `POST` a JSON message to when the `status` or `kyc_verified` properties change. If the callback is a URL (not a `postMessage`), it needs to be signed by the anchor and the signature needs to be verified by the wallet according to the [callback signature specification](#callback-signature). | - -The URL supplied by both callback parameters should receive the full transaction object. - -**`callback` details** - -If the wallet wants to be notified that the user has completed the anchor's interactive flow (either success or -failure), it can add this parameter to the URL. If the user abandons the process, the anchor does not need to report -anything to the wallet. If the `callback` value is a URL, the anchor must `POST` to it with a JSON message as the body. - -**`postMessage` details** - -Note that there are some security concerns associated with supporting `postMessage` callbacks. These conerns are -detailed in the section below. - -If provided, the anchor must post a JSON message (either as a JSON-serialized string or a plain javascript object) to -`window.opener` via the Javascript -[`Window.postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) method. If `window.opener` -is undefined, the message must be posted to `window.parent` instead. - -Because `callback` is used to notify the wallet that the interactive flow is complete, it is common for anchors to make -the `postMessage` callback as a result of the user clicking a "Close" button or similar UI element. The wallet can then -close the window displaying the anchor's interactive flow using -`[Window.close()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/close). This ensures the wallet application -receives the transaction's information and the user has a smooth experience. - -**Security Concerns (`noopener`, `postMessage`)** - -Wallet applications display content rendered by a third party anchor service. It is recommended to use the -[`rel=noopener`](https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types/noopener) attribute on links or the -`noopener` feature for -[`Window.open()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/open#window_functionality_features). - -Note that using `noopener` prohibits the use of `postMessage` callbacks. If `postMessage` callbacks are required for -your implementation, it recommended to only open URLs from anchors that you, the wallet developer, trust. - -To validate the provenance and integrity of the callback, anchors [must sign it](#callback-signature) and wallet servers -must validate the signature before taking any action. - -**Differences between `callback` and `on_change_callback`** - -Anchors may make _at most one request_ containing a `/transaction` response body to `callback` when the user is finished -with the interactive flow. - -`on_change_callback` should be called each time the `status` or `kyc_verified` properties of the transaction change. It -can be called any number of times. - -**`callback` / `on_change_callback` example** - -The JSON message should be identical to the response format for the [/transaction](#single-historical-transaction) -endpoint. - -```javascript -// Example callback at the end of an interactive withdraw, indicating that the anchor is waiting for the wallet to send a payment in the amount of 80 of the asset in question. -fetch(callback, { - method: "POST", - headers: { "Content-Type": "application/json" }, - body: JSON.stringify({ - // a plain javascript object can also be used for postMessage calls - transaction: { - id: "anchors_identifier_for_this_transaction", - status: "pending_user_transfer_start", - withdraw_anchor_account: "ANCHORS_STELLAR_ACCOUNT_ID", - withdraw_memo: "MEMO_ANCHOR_EXPECTS_TO_SEE", - withdraw_memo_type: "text|hash|id", - amount_in: "80", - // ... Any other values from the /transaction endpoint can and should be passed as well - }, - }), -}); -``` +| Name | Type | Description | +| -------------------- | ------ | ------------------------------------------------------------------------------| +| `callback` | string | (**deprecated** in favor of `STATUS_CALLBACK_URL` of the [SEP-1](sep0001.md)) | +| `on_change_callback` | string | (**deprecated** in favor of `STATUS_CALLBACK_URL` of the [SEP-1](sep0001.md)) | #### Guidance for anchors: closing the interactive popup