From 30486baa8bcb7369e28f46bd77f14a2c9fbc391d Mon Sep 17 00:00:00 2001 From: Gleb Date: Wed, 7 Jun 2023 17:40:39 -0700 Subject: [PATCH 01/17] Add SEP-38 support to SEP-24 --- ecosystem/sep-0024.md | 84 +++++++++++++++++++++++++++++++++++++------ ecosystem/sep-0038.md | 7 ++-- 2 files changed, 77 insertions(+), 14 deletions(-) diff --git a/ecosystem/sep-0024.md b/ecosystem/sep-0024.md index 39bc4c2d7..715d9f160 100644 --- a/ecosystem/sep-0024.md +++ b/ecosystem/sep-0024.md @@ -6,8 +6,8 @@ Title: Hosted Deposit and Withdrawal Author: SDF Status: Active Created: 2019-09-18 -Updated: 2023-02-06 -Version 3.0.0 +Updated: 2023-06-07 +Version 3.1.0 ``` ## Simple Summary @@ -32,13 +32,14 @@ To support this protocol an anchor acts as a server and implements the specified * The assets issuing account should [have a home_domain set](https://www.stellar.org/developers/guides/issuing-assets.html#discoverablity-and-meta-information) so the clients can find the toml file to begin the process. * An anchor must define the location of their `TRANSFER_SERVER_SEP0024` in their [`stellar.toml`](sep-0001.md). This is how a wallet knows where to find the anchor's server. * Anchors and clients must support [SEP-10](sep-0010.md) web authentication to enable authenticated deposits, withdrawals, or transaction history lookups. +* If the Anchor supports [SEP-38], `ANCHOR_QUOTE_SERVER` must be defined in their [`stellar.toml`](sep-0001.md). ## API Endpoints * [`POST /transactions/deposit/interactive`](#deposit) * [`POST /transactions/withdraw/interactive`](#withdraw) * [`GET /info`](#info) -* [`GET /fee`](#fee): optional (only needed for complex fee structures) +* [`GET /fee`](#fee): **deprecated** optional (only needed for complex fee structures) * [`GET /transactions`](#transaction-history) * [`GET /transaction`](#single-historical-transaction) @@ -73,6 +74,54 @@ To support the exchange of non-equivalent assets using this protocol, the anchor Finally, anchors should populate the optional attributes listed in the `GET /transaction(s)` endpoints related to non-equivalent asset transactions, specifically `amount_in_asset`, `amount_fee_asset`, and `amount_out_asset`. This allows client applications can relay this information, in addition to the amounts specified in the associated attributes, back to their users. +Alternatively, the Anchor must support `quote_id` in the `POST /transactions/deposit/interactive` and `POST /transactions/withdraw/interactive`, and the [SEP-38] Anchor RFQ API that enables the Anchor to provide quotes to the Wallet. + +### Asset Conversions Using the Market Rate + +To convert at the market rate, clients get an [indicative quote](https://www.investopedia.com/terms/i/indicativequote.asp) with [SEP-38] and then proceed to calling the [`GET /deposit-exchange`](#deposit-exchange) or [`GET /withdraw-exchange`](#withdraw-exchange) endpoints. Market rate conversions executed in this way do not provide a guarantee of the final price to be paid for the asset. Here is how this kind of conversion should happen in deposits and withdrawals for an asset pair like `BRL <> USDC`: + +#### Deposit: + +Considering the user will be making a bank deposit of fiat `BRL` in exchange for `USDC` in the Stellar network: + +1. The Wallet checks the assets' market conversion rate with [`SEP-38 GET /price`](sep-0038.md#get-price) and shows the estimated price to the user. +1. The Wallet initiates a [`POST /transactions/deposit/interactive`](#deposit) using the parameter `asset_code`. +1. The user proceeds with the off-chain deposit, sending `BRL` to the Anchor's bank account. +1. Upon receiving the off-chain deposit funds, the Anchor converts it to `USDC` using the market rate and sends the resulting amount to the user's Stellar account. + +#### Withdraw: + +Considering the user will be making a Stellar payment of `USDC` in exchange for withdrawing `BRL` in the bank account: + +1. The Wallet checks the assets' market conversion rate with [`SEP-38 GET /price`](sep-0038.md#get-price) and shows the estimated price to the user. +1. The Wallet initiates a [`POST /transactions/withdraw/interactive`](#withdraw) using the parameter `asset_code`. +1. The user proceeds with the on-chain payment, sending `USDC` to the Anchor's Stellar account. +1. Upon receiving the on-chain withdraw funds, the Anchor converts it to `BRL` using the market rate and sends the resulting amount to the user's bank account. + +### Asset Conversions Using a Firm Quote + +With firm quotes, users are guaranteed an asset price they will pay if they submit the payment before the quote expiration. Here is how the conversion should happen in deposits and withdrawals for an asset pair like `USDC <> BRL`: + +#### Deposit: + +Considering the user will be making a bank deposit of fiat `BRL` in exchange for `USDC` in the Stellar network: + +1. The Wallet gets a firm conversion rate in [`SEP-38 POST /quote`](sep-0038.md#post-quote) and shows the price and expiration date to the user. +1. The Wallet initiates a [`POST /transactions/deposit/interactive`](#deposit) using the parameter `quote_id` returned from the previous step, as well as `asset_code`. +1. The user proceeds with the off-chain deposit, sending `BRL` to the Anchor's bank account before the quote expires. +1. Upon receiving the off-chain deposit funds, the Anchor converts it to `USDC` according with the agreed quote and sends the resulting amount to the user's Stellar account. +1. If the user sends the funds after the quote expiration, the Anchor can proceed according with its own policy. + +#### Withdraw: + +Considering the user will be making a Stellar payment of `USDC` in exchange for withdrawing `BRL` in her bank account: + +1. The Wallet gets a firm conversion rate in [`SEP-38 POST /quote`](sep-0038.md#post-quote) and shows the price and expiration date to the user. +1. The Wallet initiates a [`GET /withdraw-exchange`](#withdraw-exchange) using the parameter `quote_id` returned from the previous step, as well as `asset_code` and `destination_asset`. +1. The user proceeds with the on-chain payment, sending `USDC` to the Anchor's Stellar account before the quote expires. +1. Upon receiving the on-chain withdraw funds, the Anchor converts it to `BRL` according with the agreed quote and sends the resulting amount to the user's bank account. +1. If the user sends the funds after the quote expiration, the Anchor can proceed according with its own policy. + ## Cross-Origin Headers Valid CORS headers are necessary to allow web clients from other sites to use the endpoints. The following HTTP header must be set for all transfer server responses, including error responses. @@ -160,16 +209,17 @@ SEP-24 lays out many options for how deposit and withdrawal can work. These are * Identify anchors you want to support manually, and test them with your wallet to be sure they work before allowing them to be used with your wallet. We encourage you to support as many anchors as possible. * For each anchor, use information from its [`stellar.toml`](sep-0001.md) file and its [`/info`](#info) endpoint to display useful information to the user about the asset they've picked. -* Provide a UI that allows users to pick an asset, anchor, and amount to use for deposit or withdraw. The UI should display the asset's fee structure (if possible) as well as information such as the address of the anchor and description of the asset from the `stellar.toml` file. -* **Use the `/info` endpoint** - * Fetch the asset's deposit & withdawal fee structure: if `fee_fixed`, `fee_percent`, or `fee_minimum` are provided, show this to the user early in the process so they're fully informed. - * If the `/fee` endpoint is enabled, use it for computing fees when you need to show them to the user. +* Provide a UI that allows users to pick an asset, anchor, and amount to use for deposit or withdraw. The UI should display the asset's quote (if possible) as well as information such as the address of the anchor and description of the asset from the `stellar.toml` file. +* **If [SEP-38] quote API is supported by the anchor** + * Fetch the asset's exchange rate at the market price using [`SEP-38 GET /price`](sep-0038.md#get-price) API. + * For the firm quote, use [`SEP-38 POST /quote`](sep-0038.md#post-quote) API and show the quote and expiration time to the user. * **Authentication** * Perform [authentication](#authentication) via SEP-10 before hitting those endpoints * **Make a request to `/transactions/deposit/interactive` or `/transactions/withdraw/interactive`.** * This will respond with the interactive url needed to proceed with KYC and deposit/withdraw details. * **For `/transactions/deposit/interactive` and `/transactions/withdraw/interactive`** * Optionally attach any fields from [SEP-9](sep-0009.md) as POST parameters in the `/deposit` or `/withdraw` endpoints in order to let the anchor pre-fill them in the interactive flow UI. This is optional, but can create a much nicer user experience. `email_address`, `first_name` and `last_name` are good examples of fields to help pre-fill the anchors website. + * Optionally attach [SEP-38] quote id, in order to the anchor to use the quote previously shown to the user. * **For `/transactions/deposit/interactive`** * Handle the interactive flow, handle it as [described in detail](#interactive-customer-information-needed). * Handle the [special cases](#special-cases), they're relatively common. @@ -184,10 +234,11 @@ SEP-24 lays out many options for how deposit and withdrawal can work. These are ### Basic Anchor Implementation * Provide a full-featured implementation of [`/info`](#info). -* Pick your approach to [fees](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0006.md#fee). We recommend using `/info` to express fees as it provides a better user experience (the user can see the fee structure in the wallet early in the process). +* Implement [SEP-38] to offer better user experience. Wallet would be able to show rates and fees your anchor provides early in the process. (Before the user initiates a transaction via interactive UI) * **For both deposit and withdrawal**: * To start an interactive flow, provide the [Customer info needed response](#interactive-customer-information-needed). * Some wallets may include other fields indicated in [SEP-9](sep-0009.md) as POST parameters added to the `/transactions/deposit/interactive` or `/transactions/withdraw/interactive` endpoints. These can be stored and used to pre-populate fields in the interactive flow. This is optional for the wallet to provide and optional for anchors to respect, but it does create a much nicer user experience. + * Some wallets may include `quote_id` fetched from the [`SEP-38 POST /quote`](sep-0038.md#post-quote) API. If provided, your implementation must respect the agreed quote. * Include the `id` field in your response to `/transactions/deposit/interactive` and `/transactions/withdraw/interactive` so the wallet can check up on the status of the transaction if it wants. * Also include the `id` field in the popup URL you provide to the wallet. This allows you to keep track of the transaction when the user visits the URL. * We recommend you use [SEP-10](#authentication) for authentication in the interactive flow and do not separately prompt for password to achieve a good user experience (although asking for MFA when confirming a transaction or requiring email confirmation is reasonable). Putting a one time use token or quickly expiring JWT in the URL returned to the client is a good way to keep continuity between authenticated API calls and fresh interactive flow requests. @@ -207,6 +258,8 @@ SEP-24 lays out many options for how deposit and withdrawal can work. These are A deposit is when a user sends some non-stellar asset (BTC via Bitcoin network, USD via bank transfer, Cash to a teller, etc...) to an account held by an anchor. In turn, the anchor sends an equal amount of tokens on the Stellar network (minus fees) to the user's Stellar account. +If the anchor supports SEP-38 quotes, it can also provide a bridge between non-equivalent tokens. For example, the anchor can receive ARS via bank transfer and in return send the equivalent value (minus fees) as USDC on the Stellar network to the user's Stellar account. That + The deposit endpoint allows a wallet to get deposit information from an anchor, so a user has all the information needed to initiate a deposit. It also lets the anchor specify additional information that the user must submit interactively via a popup or embedded browser window to be able to deposit. After a successful deposit request has been made, a transaction record with the `id` provided in the response should be retreivable from `GET /transaction(s)`. This transaction must be in the `incomplete` status until the user has provided the anchor all information necessary for the transaction to be completed once received off-chain. @@ -227,7 +280,8 @@ Name | Type | Description -----|------|------------ `asset_code` | string | The code of the stellar asset the user wants to receive for their deposit with the anchor. The value passed must match one of the codes listed in the [/info](#info) response's deposit object. `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to receive for their deposit with the anchor. If asset_issuer is not provided, the anchor should use the asset issued by themselves as described in their TOML file. -`amount` | number | (optional) Amount of asset requested to deposit. If this is not provided it will be collected in the interactive flow. +`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 `asset` and `amount` conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. +`amount` | number | (optional) Amount of asset requested to deposit. If this is not provided it will be collected in the interactive flow. Should be equals to `quote.sell_amount` or omitted if a `quote_id` was used. `account` | `G...` or `M...` string | (optional) The Stellar or muxed account the client wants to use as the destination of the payment sent by the anchor. Defaults to the account authenticated via SEP-10 if not specified. `memo_type` | string | (optional) Type of memo that anchor should attach to the Stellar 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 can be different than the value 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`. @@ -348,6 +402,8 @@ Predicates are one of the [claimable balance parameters](https://developers.stel This operation allows a user to redeem an asset currently on the Stellar network for the real asset (BTC, USD, stock, etc...) via the anchor of the Stellar asset. +If the anchor supports SEP-38 quotes, it can provide a withdraw that makes a bridge between non-equivalent tokens by receiving, for instance USDC from the Stellar network and in return sending the equivalent value (minus fees) as NGN to the user's bank account. + The withdraw endpoint allows a wallet to get withdrawal information from an anchor, so a user has all the information needed to initiate a withdrawal. It also lets the anchor specify the url for the interactive webapp to continue with the anchor's side of the withdraw. After a successful withdraw request has been made, a transaction record with the `id` provided in the response should be retreivable from `GET /transaction(s)`. Unless the [no additional information needed](#1-success-no-additional-information-needed) response is returned, this transaction must be in the `incomplete` status until the user has provided the anchor all information necessary for the transaction to be completed once received on-chain. @@ -366,7 +422,8 @@ Name | Type | Description -----|------|------------ `asset_code` | string | Code of the asset the user wants to withdraw. The value passed must match one of the codes listed in the [/info](#info) response's withdraw object. `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to withdraw with the anchor. If asset_issuer is not provided, the anchor should use the asset issued by themselves as described in their TOML file. -`amount` | number | (optional) Amount of asset requested to withdraw. If this is not provided it will be collected in the interactive flow. +`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 `asset` and `amount` conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. +`amount` | number | (optional) Amount of asset requested to withdraw. If this is not provided it will be collected in the interactive flow. Should be equals to `quote.sell_amount` or omitted if a `quote_id` was used. `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. Defaults to the account authenticated via SEP-10 if not specified. `memo` | string | (**deprecated**, optional) This field was originally intended to differentiate users of the same Stellar account. However, the anchor should use the `sub` value included in the decoded SEP-10 JWT instead. Anchors should still support this parameter to maintain support for outdated clients. See the [Shared Account Authentication](#shared-omnibus-or-pooled-accounts) section for more information. `memo_type` | string | (**deprecated**, optional) Type of `memo`. One of `text`, `id` or `hash`. Deprecated because memos used to identify users of the same Stellar account should always be of type of `id`. @@ -651,6 +708,8 @@ The default values for the features listed above have been selected based on the ## Fee +### This endpoint is deprecated. [SEP-38] quotes API should be used to communicate fees instead. + The fee endpoint allows an anchor to report the fee that would be charged for a given deposit or withdraw operation. This is important to allow an anchor to accurately report fees to a user even when the fee schedule is complex. If a fee can be fully expressed with the `fee_fixed`, `fee_percent` or `fee_minimum` fields in the `/info` response, then an anchor should not implement this endpoint. Note that this endpoint does not support providing fees for transactions using non-equivalent on and off-chain assets, since it only accepts the on-chain `asset_code` request parameter. @@ -742,6 +801,7 @@ Name | Type | Description `amount_out_asset` | string | (optional) The asset delivered or to be delivered to the user. Must be present if the deposit/withdraw was made using non-equivalent assets. The value must be in [SEP-38 Asset Identification Format](sep-0038.md#asset-identification-format). See the [Asset Exchanges](#asset-exchanges) section for more information. `amount_fee` | string | Amount of fee charged by anchor. `amount_fee_asset` | string | (optional) The asset in which fees are calculated in. Must be present if the deposit/withdraw was made using non-equivalent assets. The value must be in [SEP-38 Asset Identification Format](sep-0038.md#asset-identification-format). See the [Asset Exchanges](#asset-exchanges) section for more information. +`quote_id` | string | (optional) The ID of the quote used to create this transaction. Should be present if a `quote_id` was included in the `POST /transactions` request. Clients should be aware though that the `quote_id` may not be present in older implementations. `started_at` | UTC ISO 8601 string | Start date and time of transaction. `completed_at` | UTC ISO 8601 string | (optional) The date and time of transaction reaching `completed` or `refunded` status. `updated_at` | UTC ISO 8601 string | (optional) The date and time of transaction reaching the current status. @@ -784,7 +844,7 @@ Name | Type | Description * `pending_user` -- the user must take additional action before the deposit / withdrawal can complete, for example an email or 2fa confirmation of a withdraw. * `completed` -- deposit/withdrawal fully completed. * `refunded` -- the deposit/withdrawal is fully refunded. -* `expired` -- funds were never received by the anchor and the transaction is considered abandoned by the user. Anchors are responsible for determining when transactions are considered expired. +* `expired` -- funds were never received by the anchor and the transaction is considered abandoned by the user. If a SEP-38 quote was specified when the transaction was initiated, the transaction should expire when the quote expires, otherwise anchors are responsible for determining when transactions are considered expired. * `no_market` -- could not complete deposit because no satisfactory asset/XLM market was available to create the account. * `too_small` -- deposit/withdrawal size less than `min_amount`. * `too_large` -- deposit/withdrawal size exceeded `max_amount`. @@ -1021,6 +1081,7 @@ There is a small set of changes when upgrading from SEP-6 to SEP-24. ## Changelog +* `v3.1.0`: Add support for [SEP-38] API. Add optional `quote_id` parameter to `post /transactions/deposit/interactive` and `POST /transactions/deposit/interactive` requests. Add `quote_id` to the transaction object schema. () * `v3.0.0`: Make the `account` parameter for `POST /transactions/deposit/interactive` request optional ([#1343](https://github.com/stellar/stellar-protocol/pull/1343)) * `v2.9.2`: Remove confusing statement on `updated_at` matching `completed_at` when `status` is `refunded` ([#1336](https://github.com/stellar/stellar-protocol/pull/1336)) * `v2.9.1`: Allow anchors to omit the deprecated `X-Stellar-Signature` header ([#1335](https://github.com/stellar/stellar-protocol/pull/1335)) @@ -1037,3 +1098,4 @@ There is a small set of changes when upgrading from SEP-6 to SEP-24. * `v2.2.0`: Deprecate refunded boolean. Add refund object to transaction records. ([#1128](https://github.com/stellar/stellar-protocol/pull/1128)) [RFC 4646]: https://www.rfc-editor.org/rfc/rfc4646 +[SEP-38]: sep-0038.md diff --git a/ecosystem/sep-0038.md b/ecosystem/sep-0038.md index 4c88df182..a47e4bb41 100644 --- a/ecosystem/sep-0038.md +++ b/ecosystem/sep-0038.md @@ -7,9 +7,9 @@ Author: Jake Urban <@jakeurban> and Leigh McCulloch <@leighmcculloch> Track: Standard Status: Draft Created: 2021-04-09 -Updated: 2022-05-23 +Updated: 2023-06-07 Discussion: https://github.com/stellar/stellar-protocol/issues/901 -Version 2.0.0 +Version 2.1.0 ``` ## Summary @@ -482,7 +482,7 @@ Name | Type | Description `sell_delivery_method` | string | (optional) One of the `name` values specified by the `sell_delivery_methods` array for the associated asset returned from [`GET /info`](#info). Must be provided if the user is delivering an off-chain asset to the anchor unless no more than one method is specified in the `GET /info` response. `buy_delivery_method` | string | (optional) One of the `name` values specified by the `buy_delivery_methods` array for the associated asset returned from [`GET /info`](#info). Must be provided if the user intends to receive an off-chain asset from the anchor unless no more than one method is specified in the `GET /info` response. `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. Should be provided if there are two or more country codes available for the desired asset in [`GET /info`](#get-info). -`context` | string | The context for what this quote will be used for. Must be one of `sep6` or `sep31`. +`context` | string | The context for what this quote will be used for. Must be one of `sep6`, `sep24` or `sep31`. #### Response @@ -574,6 +574,7 @@ GET /quote/de762cda-a193-4961-861e-57b31fed6eb3 ## Changelog +* `v2.1.0`: Add `sep24` support to the `context` of the request body of the `POST /quote` request. () * `v2.0.0`: (i) add `context` to the request body and `fee` + `total_price` to the response body of the `POST /quote` and `GET /price` requests; (ii) add `fee` to the response body of `GET /quote/:id`; and (iii) allow `sell_amount` and `buy_amount` in the responses to be different from the ones sent in the request. ([#1204](https://github.com/stellar/stellar-protocol/pull/1204)) * `v1.6.1`: Add note about `expires_at` and `expires_after` and their relationship. ([#1147](https://github.com/stellar/stellar-protocol/pull/1147)) * `v1.6.0`: Make [`SEP-10`] authentication token optional for the `GET /info`, `GET /price` and `GET /prices` endpoints. ([#1144](https://github.com/stellar/stellar-protocol/pull/1144)) From 550e46ae00211e4ce6391520b07f5312225e4d18 Mon Sep 17 00:00:00 2001 From: Gleb Date: Wed, 7 Jun 2023 17:42:06 -0700 Subject: [PATCH 02/17] Link PR to the changelog --- ecosystem/sep-0024.md | 2 +- ecosystem/sep-0038.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/ecosystem/sep-0024.md b/ecosystem/sep-0024.md index 715d9f160..46c858643 100644 --- a/ecosystem/sep-0024.md +++ b/ecosystem/sep-0024.md @@ -1081,7 +1081,7 @@ There is a small set of changes when upgrading from SEP-6 to SEP-24. ## Changelog -* `v3.1.0`: Add support for [SEP-38] API. Add optional `quote_id` parameter to `post /transactions/deposit/interactive` and `POST /transactions/deposit/interactive` requests. Add `quote_id` to the transaction object schema. () +* `v3.1.0`: Add support for [SEP-38] API. Add optional `quote_id` parameter to `post /transactions/deposit/interactive` and `POST /transactions/deposit/interactive` requests. Add `quote_id` to the transaction object schema. ([#1358](https://github.com/stellar/stellar-protocol/pull/1358)) * `v3.0.0`: Make the `account` parameter for `POST /transactions/deposit/interactive` request optional ([#1343](https://github.com/stellar/stellar-protocol/pull/1343)) * `v2.9.2`: Remove confusing statement on `updated_at` matching `completed_at` when `status` is `refunded` ([#1336](https://github.com/stellar/stellar-protocol/pull/1336)) * `v2.9.1`: Allow anchors to omit the deprecated `X-Stellar-Signature` header ([#1335](https://github.com/stellar/stellar-protocol/pull/1335)) diff --git a/ecosystem/sep-0038.md b/ecosystem/sep-0038.md index a47e4bb41..019371263 100644 --- a/ecosystem/sep-0038.md +++ b/ecosystem/sep-0038.md @@ -574,7 +574,7 @@ GET /quote/de762cda-a193-4961-861e-57b31fed6eb3 ## Changelog -* `v2.1.0`: Add `sep24` support to the `context` of the request body of the `POST /quote` request. () +* `v2.1.0`: Add `sep24` support to the `context` of the request body of the `POST /quote` request. ([#1358](https://github.com/stellar/stellar-protocol/pull/1358)) * `v2.0.0`: (i) add `context` to the request body and `fee` + `total_price` to the response body of the `POST /quote` and `GET /price` requests; (ii) add `fee` to the response body of `GET /quote/:id`; and (iii) allow `sell_amount` and `buy_amount` in the responses to be different from the ones sent in the request. ([#1204](https://github.com/stellar/stellar-protocol/pull/1204)) * `v1.6.1`: Add note about `expires_at` and `expires_after` and their relationship. ([#1147](https://github.com/stellar/stellar-protocol/pull/1147)) * `v1.6.0`: Make [`SEP-10`] authentication token optional for the `GET /info`, `GET /price` and `GET /prices` endpoints. ([#1144](https://github.com/stellar/stellar-protocol/pull/1144)) From 3a548ace5f029a7ff8be8daea9ff262e9e203149 Mon Sep 17 00:00:00 2001 From: Gleb Date: Thu, 8 Jun 2023 16:39:28 -0700 Subject: [PATCH 03/17] Add quotes support flags --- ecosystem/sep-0024.md | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/ecosystem/sep-0024.md b/ecosystem/sep-0024.md index 46c858643..5e6a800c1 100644 --- a/ecosystem/sep-0024.md +++ b/ecosystem/sep-0024.md @@ -80,6 +80,8 @@ Alternatively, the Anchor must support `quote_id` in the `POST /transactions/dep To convert at the market rate, clients get an [indicative quote](https://www.investopedia.com/terms/i/indicativequote.asp) with [SEP-38] and then proceed to calling the [`GET /deposit-exchange`](#deposit-exchange) or [`GET /withdraw-exchange`](#withdraw-exchange) endpoints. Market rate conversions executed in this way do not provide a guarantee of the final price to be paid for the asset. Here is how this kind of conversion should happen in deposits and withdrawals for an asset pair like `BRL <> USDC`: +Anchors offer indicative quote support via enabling `indicative_quotes_supported` feature flag. + #### Deposit: Considering the user will be making a bank deposit of fiat `BRL` in exchange for `USDC` in the Stellar network: @@ -102,6 +104,8 @@ Considering the user will be making a Stellar payment of `USDC` in exchange for With firm quotes, users are guaranteed an asset price they will pay if they submit the payment before the quote expiration. Here is how the conversion should happen in deposits and withdrawals for an asset pair like `USDC <> BRL`: +Anchors enable firm quotes support with `firm_quotes_supported` feature flag. + #### Deposit: Considering the user will be making a bank deposit of fiat `BRL` in exchange for `USDC` in the Stellar network: @@ -280,7 +284,7 @@ Name | Type | Description -----|------|------------ `asset_code` | string | The code of the stellar asset the user wants to receive for their deposit with the anchor. The value passed must match one of the codes listed in the [/info](#info) response's deposit object. `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to receive for their deposit with the anchor. If asset_issuer is not provided, the anchor should use the asset issued by themselves as described in their TOML file. -`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 `asset` and `amount` conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. +`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 must respect the conversion rate agreed in that quote. If the values of `asset` and `amount` conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. `amount` | number | (optional) Amount of asset requested to deposit. If this is not provided it will be collected in the interactive flow. Should be equals to `quote.sell_amount` or omitted if a `quote_id` was used. `account` | `G...` or `M...` string | (optional) The Stellar or muxed account the client wants to use as the destination of the payment sent by the anchor. Defaults to the account authenticated via SEP-10 if not specified. `memo_type` | string | (optional) Type of memo that anchor should attach to the Stellar transaction, one of `text`, `id` or `hash`. @@ -422,7 +426,7 @@ Name | Type | Description -----|------|------------ `asset_code` | string | Code of the asset the user wants to withdraw. The value passed must match one of the codes listed in the [/info](#info) response's withdraw object. `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to withdraw with the anchor. If asset_issuer is not provided, the anchor should use the asset issued by themselves as described in their TOML file. -`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 `asset` and `amount` conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. +`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 must respect the conversion rate agreed in that quote. If the values of `asset` and `amount` conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. `amount` | number | (optional) Amount of asset requested to withdraw. If this is not provided it will be collected in the interactive flow. Should be equals to `quote.sell_amount` or omitted if a `quote_id` was used. `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. Defaults to the account authenticated via SEP-10 if not specified. `memo` | string | (**deprecated**, optional) This field was originally intended to differentiate users of the same Stellar account. However, the anchor should use the `sub` value included in the decoded SEP-10 JWT instead. Anchors should still support this parameter to maintain support for outdated clients. See the [Shared Account Authentication](#shared-omnibus-or-pooled-accounts) section for more information. @@ -663,7 +667,9 @@ The response should be a JSON object like: }, "features": { "account_creation": true, - "claimable_balances": true + "claimable_balances": true, + "indicative_quotes_supported": true, + "firm_quotes_supported": true } } ``` @@ -699,10 +705,12 @@ An anchor should also indicate in the `/info` response if they support the `fee` The `features` object contains boolean values indicating whether or not specific features are supported by the anchor. If the object or specific feature is not present in the response, the default value described below may be assumed. This information enables wallets to adjust their behavior based on the feature set supported by the anchor. -Name | Default | Description ------|---------|------------ -`account_creation` | `true` | Whether or not the anchor supports creating accounts for users requesting deposits. -`claimable_balances` | `false` | Whether or not the anchor supports sending deposit funds as claimable balances. This is relevant for users of Stellar accounts without a trustline to the requested asset. +| Name | Default | Description | +|-------------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `account_creation` | `true` | Whether or not the anchor supports creating accounts for users requesting deposits. | +| `claimable_balances` | `false` | Whether or not the anchor supports sending deposit funds as claimable balances. This is relevant for users of Stellar accounts without a trustline to the requested asset. | +| `indicative_quotes_supported` | `false` | Whether or not the anchor supports indicative quotes provided by `SEP-38 GET /price` and `SEP-38 GET /prices` API. | | +| `firm_quotes_supported` | `false` | Whether or not the anchor supports indicative quotes provided by `SEP-38 POST /quote` and `SEP-38 POST /prices` API. If set to yes, anchor must support `quote_id` parameter in interactive endpoints and transaction response body. | The default values for the features listed above have been selected based on the ecosystem's current support. It is highly recommened to support all features enumerated for the best user experience. From 8019ffb6bfec8feaa75ef926165f5d4e88501ca8 Mon Sep 17 00:00:00 2001 From: Gleb Date: Fri, 9 Jun 2023 13:59:39 -0700 Subject: [PATCH 04/17] Resolve PR comments --- ecosystem/sep-0024.md | 78 +++++++++++++++++++++---------------------- 1 file changed, 39 insertions(+), 39 deletions(-) diff --git a/ecosystem/sep-0024.md b/ecosystem/sep-0024.md index 5e6a800c1..3adc9f9fc 100644 --- a/ecosystem/sep-0024.md +++ b/ecosystem/sep-0024.md @@ -39,7 +39,7 @@ To support this protocol an anchor acts as a server and implements the specified * [`POST /transactions/deposit/interactive`](#deposit) * [`POST /transactions/withdraw/interactive`](#withdraw) * [`GET /info`](#info) -* [`GET /fee`](#fee): **deprecated** optional (only needed for complex fee structures) +* [`GET /fee`](#fee): **deprecated** optional (only needed for complex fee structures). [`SEP-38 GET /price`](sep-0038.md#get-price) endpoint should be used to communicate the fees. * [`GET /transactions`](#transaction-history) * [`GET /transaction`](#single-historical-transaction) @@ -74,11 +74,11 @@ To support the exchange of non-equivalent assets using this protocol, the anchor Finally, anchors should populate the optional attributes listed in the `GET /transaction(s)` endpoints related to non-equivalent asset transactions, specifically `amount_in_asset`, `amount_fee_asset`, and `amount_out_asset`. This allows client applications can relay this information, in addition to the amounts specified in the associated attributes, back to their users. -Alternatively, the Anchor must support `quote_id` in the `POST /transactions/deposit/interactive` and `POST /transactions/withdraw/interactive`, and the [SEP-38] Anchor RFQ API that enables the Anchor to provide quotes to the Wallet. +Alternatively, the Anchor can support the [SEP-38] RFQ API and the `quote_id` attribute in `POST /transactions/deposit/interactive` and `POST /transactions/withdraw/interactive` requests. This enables wallets to check the Anchor's exchange rates prior to initiating a transaction and obtain a firm quote to use for an upcoming transaction. ### Asset Conversions Using the Market Rate -To convert at the market rate, clients get an [indicative quote](https://www.investopedia.com/terms/i/indicativequote.asp) with [SEP-38] and then proceed to calling the [`GET /deposit-exchange`](#deposit-exchange) or [`GET /withdraw-exchange`](#withdraw-exchange) endpoints. Market rate conversions executed in this way do not provide a guarantee of the final price to be paid for the asset. Here is how this kind of conversion should happen in deposits and withdrawals for an asset pair like `BRL <> USDC`: +To convert at the market rate, clients get an [indicative quote](https://www.investopedia.com/terms/i/indicativequote.asp) with [SEP-38] and then proceed to calling the [`POST /transactions/withdraw/interactive`](#withdraw) or [`POST /transactions/deposit/interactive`](#deposit) endpoints. Market rate conversions executed in this way do not provide a guarantee of the final price to be paid for the asset. Here is how this kind of conversion should happen in deposits and withdrawals for an asset pair like `BRL <> USDC`: Anchors offer indicative quote support via enabling `indicative_quotes_supported` feature flag. @@ -102,7 +102,7 @@ Considering the user will be making a Stellar payment of `USDC` in exchange for ### Asset Conversions Using a Firm Quote -With firm quotes, users are guaranteed an asset price they will pay if they submit the payment before the quote expiration. Here is how the conversion should happen in deposits and withdrawals for an asset pair like `USDC <> BRL`: +With firm quotes, users are guaranteed an asset price they will pay if they submit the payment and anchor receives the payment before the quote expiration. Here is how the conversion should happen in deposits and withdrawals for an asset pair like `USDC <> BRL`: Anchors enable firm quotes support with `firm_quotes_supported` feature flag. @@ -121,7 +121,7 @@ Considering the user will be making a bank deposit of fiat `BRL` in exchange for Considering the user will be making a Stellar payment of `USDC` in exchange for withdrawing `BRL` in her bank account: 1. The Wallet gets a firm conversion rate in [`SEP-38 POST /quote`](sep-0038.md#post-quote) and shows the price and expiration date to the user. -1. The Wallet initiates a [`GET /withdraw-exchange`](#withdraw-exchange) using the parameter `quote_id` returned from the previous step, as well as `asset_code` and `destination_asset`. +1. The Wallet initiates a [`POST /transactions/withdraw/interactive`](#withdraw) using the parameter `quote_id` returned from the previous step, as well as `asset_code`. 1. The user proceeds with the on-chain payment, sending `USDC` to the Anchor's Stellar account before the quote expires. 1. Upon receiving the on-chain withdraw funds, the Anchor converts it to `BRL` according with the agreed quote and sends the resulting amount to the user's bank account. 1. If the user sends the funds after the quote expiration, the Anchor can proceed according with its own policy. @@ -262,7 +262,7 @@ SEP-24 lays out many options for how deposit and withdrawal can work. These are A deposit is when a user sends some non-stellar asset (BTC via Bitcoin network, USD via bank transfer, Cash to a teller, etc...) to an account held by an anchor. In turn, the anchor sends an equal amount of tokens on the Stellar network (minus fees) to the user's Stellar account. -If the anchor supports SEP-38 quotes, it can also provide a bridge between non-equivalent tokens. For example, the anchor can receive ARS via bank transfer and in return send the equivalent value (minus fees) as USDC on the Stellar network to the user's Stellar account. That +If the anchor supports SEP-38 quotes, it can also provide a bridge between non-equivalent tokens. For example, the anchor can receive ARS via bank transfer and in return send the equivalent value (minus fees) as USDC on the Stellar network to the user's Stellar account. The deposit endpoint allows a wallet to get deposit information from an anchor, so a user has all the information needed to initiate a deposit. It also lets the anchor specify additional information that the user must submit interactively via a popup or embedded browser window to be able to deposit. @@ -280,23 +280,23 @@ The fields below should be placed in the request body using the `multipart/form- Request Parameters: -Name | Type | Description ------|------|------------ -`asset_code` | string | The code of the stellar asset the user wants to receive for their deposit with the anchor. The value passed must match one of the codes listed in the [/info](#info) response's deposit object. -`asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to receive for their deposit with the anchor. If asset_issuer is not provided, the anchor should use the asset issued by themselves as described in their TOML file. -`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 must respect the conversion rate agreed in that quote. If the values of `asset` and `amount` conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. -`amount` | number | (optional) Amount of asset requested to deposit. If this is not provided it will be collected in the interactive flow. Should be equals to `quote.sell_amount` or omitted if a `quote_id` was used. -`account` | `G...` or `M...` string | (optional) The Stellar or muxed account the client wants to use as the destination of the payment sent by the anchor. Defaults to the account authenticated via SEP-10 if not specified. -`memo_type` | string | (optional) Type of memo that anchor should attach to the Stellar 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 can be different than the value 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`. -`wallet_name` | string | (optional) In communications / pages about the deposit, anchor should display the wallet name to the user to explain where funds are going. -`wallet_url` | string | (optional) Anchor should link to this when notifying the user that the transaction has completed. -`lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646] which means it can also accept locale in the format `en-US`. `error` fields in the response, as well as the interactive flow UI and any other user-facing strings returned for this transaction should be in this language. -`claimable_balance_supported` | boolean | (optional) True if the client supports receiving deposit transactions as a claimable balance, false otherwise. +| Name | Type | Description | +|-------------------------------|-------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `asset_code` | string | The code of the stellar asset the user wants to receive for their deposit with the anchor. The value passed must match one of the codes listed in the [/info](#info) response's deposit object. When `quote_id` is specified, `asset_code` must match the quote's `buy_asset` asset code. | +| `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to receive for their deposit with the anchor. If asset_issuer is not provided, the anchor should use the asset issued by themselves as described in their TOML file. When `quote_id` is specified, `asset_issuer` must match the quote's `buy_asset` asset issuer. | +| `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 must respect the conversion rate agreed in that quote. If the values of `asset` and `amount` conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | +| `amount` | number | (optional) Amount of asset requested to deposit. If this is not provided it will be collected in the interactive flow. Should be equals to `quote.sell_amount` or omitted if a `quote_id` was used. | +| `account` | `G...` or `M...` string | (optional) The Stellar or muxed account the client wants to use as the destination of the payment sent by the anchor. Defaults to the account authenticated via SEP-10 if not specified. | +| `memo_type` | string | (optional) Type of memo that anchor should attach to the Stellar 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 can be different than the value 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`. | +| `wallet_name` | string | (optional) In communications / pages about the deposit, anchor should display the wallet name to the user to explain where funds are going. | +| `wallet_url` | string | (optional) Anchor should link to this when notifying the user that the transaction has completed. | +| `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646] which means it can also accept locale in the format `en-US`. `error` fields in the response, as well as the interactive flow UI and any other user-facing strings returned for this transaction should be in this language. | +| `claimable_balance_supported` | boolean | (optional) True if the client supports receiving deposit transactions as a claimable balance, false otherwise. | Additionally, any [SEP-9](sep-0009.md) parameters may be passed as well to make the onboarding experience simpler. -When uploading data for fields specificed in [SEP-9](sep-0009.md), `binary` type fields (typically files) should be submitted **after all other fields**. The reason for this is that some web servers require `binary` fields at the end so that they know when they can begin processing the request as a stream. +When uploading data for fields specified in [SEP-9](sep-0009.md), `binary` type fields (typically files) should be submitted **after all other fields**. The reason for this is that some web servers require `binary` fields at the end so that they know when they can begin processing the request as a stream. Example: @@ -422,20 +422,20 @@ The fields below should be placed in the request body using the `multipart/form- Request parameters: -Name | Type | Description ------|------|------------ -`asset_code` | string | Code of the asset the user wants to withdraw. The value passed must match one of the codes listed in the [/info](#info) response's withdraw object. -`asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to withdraw with the anchor. If asset_issuer is not provided, the anchor should use the asset issued by themselves as described in their TOML file. -`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 must respect the conversion rate agreed in that quote. If the values of `asset` and `amount` conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. -`amount` | number | (optional) Amount of asset requested to withdraw. If this is not provided it will be collected in the interactive flow. Should be equals to `quote.sell_amount` or omitted if a `quote_id` was used. -`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. Defaults to the account authenticated via SEP-10 if not specified. -`memo` | string | (**deprecated**, optional) This field was originally intended to differentiate users of the same Stellar account. However, the anchor should use the `sub` value included in the decoded SEP-10 JWT instead. Anchors should still support this parameter to maintain support for outdated clients. See the [Shared Account Authentication](#shared-omnibus-or-pooled-accounts) section for more information. -`memo_type` | string | (**deprecated**, optional) Type of `memo`. One of `text`, `id` or `hash`. Deprecated because memos used to identify users of the same Stellar account should always be of type of `id`. -`wallet_name` | string | (optional) In communications / pages about the withdrawal, anchor should display the wallet name to the user to explain where funds are coming from. -`wallet_url` | string | (optional) Anchor can show this to the user when referencing the wallet involved in the withdrawal (ex. in the anchor's transaction history). -`lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646] which means it can also accept locale in the format `en-US`. `error` fields in the response, as well as the interactive flow UI and any other user-facing strings returned for this transaction should be in this language. -`refund_memo` | (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` | (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. +| Name | Type | Description | +|--------------------|-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `asset_code` | string | Code of the asset the user wants to withdraw. The value passed must match one of the codes listed in the [/info](#info) response's withdraw object. When `quote_id` is specified, `asset_code` must match the quote's `buy_asset` asset code. | +| `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to withdraw with the anchor. If `asset_issuer` is not provided, the anchor should use the asset issued by themselves as described in their TOML file. When `quote_id` is specified, `asset_issuer` must match the quote's `buy_asset` asset issuer. | +| `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 must respect the conversion rate agreed in that quote. If the values of `asset` and `amount` conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | +| `amount` | number | (optional) Amount of asset requested to withdraw. If this is not provided it will be collected in the interactive flow. Should be equals to `quote.sell_amount` or omitted if a `quote_id` was used. | +| `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. Defaults to the account authenticated via SEP-10 if not specified. | +| `memo` | string | (**deprecated**, optional) This field was originally intended to differentiate users of the same Stellar account. However, the anchor should use the `sub` value included in the decoded SEP-10 JWT instead. Anchors should still support this parameter to maintain support for outdated clients. See the [Shared Account Authentication](#shared-omnibus-or-pooled-accounts) section for more information. | +| `memo_type` | string | (**deprecated**, optional) Type of `memo`. One of `text`, `id` or `hash`. Deprecated because memos used to identify users of the same Stellar account should always be of type of `id`. | +| `wallet_name` | string | (optional) In communications / pages about the withdrawal, anchor should display the wallet name to the user to explain where funds are coming from. | +| `wallet_url` | string | (optional) Anchor can show this to the user when referencing the wallet involved in the withdrawal (ex. in the anchor's transaction history). | +| `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646] which means it can also accept locale in the format `en-US`. `error` fields in the response, as well as the interactive flow UI and any other user-facing strings returned for this transaction should be in this language. | +| `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. | Additionally, any [SEP-9](sep-0009.md) parameters may be passed as well to make the onboarding experience simpler. @@ -448,7 +448,7 @@ Content-Type: application/x-www-form-urlencoded asset_code=USD&email_address=myaccount@gmail.com&account=GACW7NONV43MZIFHCOKCQJAKSJSISSICFVUJ2C6EZIW5773OU3HD64VI ``` -When uploading data for fields specificed in [SEP-9](sep-0009.md), `binary` type fields (typically files) should be submitted **after all other fields**. The reason for this is that some web servers require `binary` fields at the end so that they know when they can begin processing the request as a stream. +When uploading data for fields specified in [SEP-9](sep-0009.md), `binary` type fields (typically files) should be submitted **after all other fields**. The reason for this is that some web servers require `binary` fields at the end so that they know when they can begin processing the request as a stream. ### Response @@ -703,7 +703,7 @@ An anchor should also indicate in the `/info` response if they support the `fee` #### Feature Flags -The `features` object contains boolean values indicating whether or not specific features are supported by the anchor. If the object or specific feature is not present in the response, the default value described below may be assumed. This information enables wallets to adjust their behavior based on the feature set supported by the anchor. +The `features` object contains boolean values indicating whether specific features are supported by the anchor. If the object or specific feature is not present in the response, the default value described below may be assumed. This information enables wallets to adjust their behavior based on the feature set supported by the anchor. | Name | Default | Description | |-------------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -712,11 +712,11 @@ The `features` object contains boolean values indicating whether or not specific | `indicative_quotes_supported` | `false` | Whether or not the anchor supports indicative quotes provided by `SEP-38 GET /price` and `SEP-38 GET /prices` API. | | | `firm_quotes_supported` | `false` | Whether or not the anchor supports indicative quotes provided by `SEP-38 POST /quote` and `SEP-38 POST /prices` API. If set to yes, anchor must support `quote_id` parameter in interactive endpoints and transaction response body. | -The default values for the features listed above have been selected based on the ecosystem's current support. It is highly recommened to support all features enumerated for the best user experience. +The default values for the features listed above have been selected based on the ecosystem's current support. It is highly recommend to support all features enumerated for the best user experience. ## Fee -### This endpoint is deprecated. [SEP-38] quotes API should be used to communicate fees instead. +### This endpoint is deprecated. The [SEP-38] `GET /price` endpoint should be used to fetch fees instead. The fee endpoint allows an anchor to report the fee that would be charged for a given deposit or withdraw operation. This is important to allow an anchor to accurately report fees to a user even when the fee schedule is complex. If a fee can be fully expressed with the `fee_fixed`, `fee_percent` or `fee_minimum` fields in the `/info` response, then an anchor should not implement this endpoint. @@ -809,7 +809,7 @@ Name | Type | Description `amount_out_asset` | string | (optional) The asset delivered or to be delivered to the user. Must be present if the deposit/withdraw was made using non-equivalent assets. The value must be in [SEP-38 Asset Identification Format](sep-0038.md#asset-identification-format). See the [Asset Exchanges](#asset-exchanges) section for more information. `amount_fee` | string | Amount of fee charged by anchor. `amount_fee_asset` | string | (optional) The asset in which fees are calculated in. Must be present if the deposit/withdraw was made using non-equivalent assets. The value must be in [SEP-38 Asset Identification Format](sep-0038.md#asset-identification-format). See the [Asset Exchanges](#asset-exchanges) section for more information. -`quote_id` | string | (optional) The ID of the quote used to create this transaction. Should be present if a `quote_id` was included in the `POST /transactions` request. Clients should be aware though that the `quote_id` may not be present in older implementations. +`quote_id` | string | (optional) The ID of the quote used when creating this transaction. Should be present if a `quote_id` was included in the `POST /transactions/deposit/interactive` or `POST /transactions/withdraw/interactive` request. Clients should be aware that the `quote_id` may not be present in older implementations. `started_at` | UTC ISO 8601 string | Start date and time of transaction. `completed_at` | UTC ISO 8601 string | (optional) The date and time of transaction reaching `completed` or `refunded` status. `updated_at` | UTC ISO 8601 string | (optional) The date and time of transaction reaching the current status. From 8a169257870249abf2682b4b48014c24691882f8 Mon Sep 17 00:00:00 2001 From: Gleb Date: Fri, 9 Jun 2023 17:24:40 -0700 Subject: [PATCH 05/17] Add optional receiving_asset field --- ecosystem/sep-0024.md | 77 ++++++++++++++++++++++++------------------- 1 file changed, 43 insertions(+), 34 deletions(-) diff --git a/ecosystem/sep-0024.md b/ecosystem/sep-0024.md index 99e90c814..b6cdf2363 100644 --- a/ecosystem/sep-0024.md +++ b/ecosystem/sep-0024.md @@ -365,7 +365,7 @@ banking rails so counterparties can run through the flow without a need to colla amount is ready for pick-up. - Some wallets might exchange currencies only once they're ready to send the withdrawal payment, so there might be slight fluctuations of value between the informed withdrawal `amount` and the actual transferred amount. It is - recommended for anchors to accept an amount fluctuation of up to ±10%, and adjust the amount to be transferred (and + recommended for anchors to accept an amount fluctuation of up to ±10%, and adjust the amount to be transferred ( and fees) to reflect the actual value received. - **Providing transaction status** - Provide the `/transaction` endpoint. The wallet relies on it to complete interactive withdrawals. @@ -402,19 +402,20 @@ The fields below should be placed in the request body using the `multipart/form- Request Parameters: -| Name | Type | Description | -| ----------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `asset_code` | string | The code of the stellar asset the user wants to receive for their deposit with the anchor. The value passed must match one of the codes listed in the [/info](#info) response's deposit object. When `quote_id` is specified, `asset_code` must match the quote's `buy_asset` asset code. | -| `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to receive for their deposit with the anchor. If asset_issuer is not provided, the anchor should use the asset issued by themselves as described in their TOML file. When `quote_id` is specified, `asset_issuer` must match the quote's `buy_asset` asset issuer. | -| `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 must respect the conversion rate agreed in that quote. If the values of `asset` and `amount` conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | -| `amount` | number | (optional) Amount of asset requested to deposit. If this is not provided it will be collected in the interactive flow. Should be equals to `quote.sell_amount` or omitted if a `quote_id` was used. | -| `account` | `G...` or `M...` string | (optional) The Stellar or muxed account the client wants to use as the destination of the payment sent by the anchor. Defaults to the account authenticated via SEP-10 if not specified. | -| `memo_type` | string | (optional) Type of memo that anchor should attach to the Stellar 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 can be different than the value 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`. | -| `wallet_name` | string | (optional) In communications / pages about the deposit, anchor should display the wallet name to the user to explain where funds are going. | -| `wallet_url` | string | (optional) Anchor should link to this when notifying the user that the transaction has completed. | -| `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646] which means it can also accept locale in the format `en-US`. `error` fields in the response, as well as the interactive flow UI and any other user-facing strings returned for this transaction should be in this language. | -| `claimable_balance_supported` | boolean | (optional) True if the client supports receiving deposit transactions as a claimable balance, false otherwise. | +| Name | Type | Description | +|-------------------------------| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `asset_code` | string | The code of the stellar asset the user wants to receive for their deposit with the anchor. The value passed must match one of the codes listed in the [/info](#info) response's deposit object. When `quote_id` is specified, `asset_code` must match the quote's `buy_asset` asset code. | +| `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to receive for their deposit with the anchor. If asset_issuer is not provided, the anchor should use the asset issued by themselves as described in their TOML file. When `quote_id` is specified, `asset_issuer` must match the quote's `buy_asset` asset issuer. | +| `receiving_asset` | string in [Asset Identification Format] | (optional) The asset user wants to receive. When `quote_id` is specified, this parameter is mandatory and must match the quote's `setll_asset` asset code. | +| `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 must respect the conversion rate agreed in that quote. If the values of `asset` and `amount` conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | +| `amount` | number | (optional) Amount of asset requested to deposit. If this is not provided it will be collected in the interactive flow. Should be equals to `quote.sell_amount` or omitted if a `quote_id` was used. | +| `account` | `G...` or `M...` string | (optional) The Stellar or muxed account the client wants to use as the destination of the payment sent by the anchor. Defaults to the account authenticated via SEP-10 if not specified. | +| `memo_type` | string | (optional) Type of memo that anchor should attach to the Stellar 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 can be different than the value 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`. | +| `wallet_name` | string | (optional) In communications / pages about the deposit, anchor should display the wallet name to the user to explain where funds are going. | +| `wallet_url` | string | (optional) Anchor should link to this when notifying the user that the transaction has completed. | +| `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646] which means it can also accept locale in the format `en-US`. `error` fields in the response, as well as the interactive flow UI and any other user-facing strings returned for this transaction should be in this language. | +| `claimable_balance_supported` | boolean | (optional) True if the client supports receiving deposit transactions as a claimable balance, false otherwise. | Additionally, any [SEP-9](sep-0009.md) parameters may be passed as well to make the onboarding experience simpler. @@ -601,20 +602,21 @@ The fields below should be placed in the request body using the `multipart/form- Request parameters: -| Name | Type | Description | -| ------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `asset_code` | string | Code of the asset the user wants to withdraw. The value passed must match one of the codes listed in the [/info](#info) response's withdraw object. When `quote_id` is specified, `asset_code` must match the quote's `buy_asset` asset code. | -| `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to withdraw with the anchor. If `asset_issuer` is not provided, the anchor should use the asset issued by themselves as described in their TOML file. When `quote_id` is specified, `asset_issuer` must match the quote's `buy_asset` asset issuer. | -| `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 must respect the conversion rate agreed in that quote. If the values of `asset` and `amount` conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | -| `amount` | number | (optional) Amount of asset requested to withdraw. If this is not provided it will be collected in the interactive flow. Should be equals to `quote.sell_amount` or omitted if a `quote_id` was used. | -| `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. Defaults to the account authenticated via SEP-10 if not specified. | -| `memo` | string | (**deprecated**, optional) This field was originally intended to differentiate users of the same Stellar account. However, the anchor should use the `sub` value included in the decoded SEP-10 JWT instead. Anchors should still support this parameter to maintain support for outdated clients. See the [Shared Account Authentication](#shared-omnibus-or-pooled-accounts) section for more information. | -| `memo_type` | string | (**deprecated**, optional) Type of `memo`. One of `text`, `id` or `hash`. Deprecated because memos used to identify users of the same Stellar account should always be of type of `id`. | -| `wallet_name` | string | (optional) In communications / pages about the withdrawal, anchor should display the wallet name to the user to explain where funds are coming from. | -| `wallet_url` | string | (optional) Anchor can show this to the user when referencing the wallet involved in the withdrawal (ex. in the anchor's transaction history). | -| `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646] which means it can also accept locale in the format `en-US`. `error` fields in the response, as well as the interactive flow UI and any other user-facing strings returned for this transaction should be in this language. | -| `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. | +| Name | Type | Description | +| ------------------ | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `asset_code` | string | Code of the asset the user wants to withdraw. The value passed must match one of the codes listed in the [/info](#info) response's withdraw object. When `quote_id` is specified, `asset_code` must match the quote's `sell_asset` asset code. | +| `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to withdraw with the anchor. If `asset_issuer` is not provided, the anchor should use the asset issued by themselves as described in their TOML file. When `quote_id` is specified, `asset_issuer` must match the quote's `buy_asset` asset issuer. | +| `receiving_asset` | string in [Asset Identification Format] | (optional) The asset user wants to receive. When `quote_id` is specified, this parameter is mandatory and must match the quote's `buy_asset` asset code. | +| `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 must respect the conversion rate agreed in that quote. If the values of `asset` and `amount` conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | +| `amount` | number | (optional) Amount of asset requested to withdraw. If this is not provided it will be collected in the interactive flow. Should be equals to `quote.sell_amount` or omitted if a `quote_id` was used. | +| `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. Defaults to the account authenticated via SEP-10 if not specified. | +| `memo` | string | (**deprecated**, optional) This field was originally intended to differentiate users of the same Stellar account. However, the anchor should use the `sub` value included in the decoded SEP-10 JWT instead. Anchors should still support this parameter to maintain support for outdated clients. See the [Shared Account Authentication](#shared-omnibus-or-pooled-accounts) section for more information. | +| `memo_type` | string | (**deprecated**, optional) Type of `memo`. One of `text`, `id` or `hash`. Deprecated because memos used to identify users of the same Stellar account should always be of type of `id`. | +| `wallet_name` | string | (optional) In communications / pages about the withdrawal, anchor should display the wallet name to the user to explain where funds are coming from. | +| `wallet_url` | string | (optional) Anchor can show this to the user when referencing the wallet involved in the withdrawal (ex. in the anchor's transaction history). | +| `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646] which means it can also accept locale in the format `en-US`. `error` fields in the response, as well as the interactive flow UI and any other user-facing strings returned for this transaction should be in this language. | +| `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. | Additionally, any [SEP-9](sep-0009.md) parameters may be passed as well to make the onboarding experience simpler. @@ -951,12 +953,18 @@ The `features` object contains boolean values indicating whether specific featur object or specific feature is not present in the response, the default value described below may be assumed. This information enables wallets to adjust their behavior based on the feature set supported by the anchor. -| Name | Default | Description | -| ----------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --- | -| `account_creation` | `true` | Whether or not the anchor supports creating accounts for users requesting deposits. | -| `claimable_balances` | `false` | Whether or not the anchor supports sending deposit funds as claimable balances. This is relevant for users of Stellar accounts without a trustline to the requested asset. | -| `indicative_quotes_supported` | `false` | Whether or not the anchor supports indicative quotes provided by `SEP-38 GET /price` and `SEP-38 GET /prices` API. | | -| `firm_quotes_supported` | `false` | Whether or not the anchor supports indicative quotes provided by `SEP-38 POST /quote` and `SEP-38 POST /prices` API. If set to yes, anchor must support `quote_id` parameter in interactive endpoints and transaction response body. | +| Name | Default | Description | +| ---------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------- | +| `account_creation` | `true` | Whether or not the anchor supports creating accounts for users requesting | +| deposits. | +| `claimable_balances` | `false` | Whether or not the anchor supports sending deposit funds as claimable | +| balances. This is relevant for users of Stellar accounts without a trustline to the requested asset. | +| `indicative_quotes_supported` | `false` | Whether or not the anchor supports indicative quotes provided | +| by `SEP-38 GET /price` and `SEP-38 GET /prices` API. | | +| `firm_quotes_supported` | `false` | Whether or not the anchor supports indicative quotes provided | + +by `SEP-38 POST /quote` and `SEP-38 POST /prices` API. If set to yes, anchor must support `quote_id` parameter in +interactive endpoints and transaction response body. | The default values for the features listed above have been selected based on the ecosystem's current support. It is highly recommend to support all features enumerated for the best user experience. @@ -1401,3 +1409,4 @@ There is a small set of changes when upgrading from SEP-6 to SEP-24. [RFC 4646]: https://www.rfc-editor.org/rfc/rfc4646 [SEP-38]: sep-0038.md +[Asset Identification Format]: sep-0038.md#asset-identification-format. From 57d0a808b68256288f8ba675a4a5bb44fa655911 Mon Sep 17 00:00:00 2001 From: Gleb Date: Fri, 9 Jun 2023 17:26:25 -0700 Subject: [PATCH 06/17] Better description --- ecosystem/sep-0024.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ecosystem/sep-0024.md b/ecosystem/sep-0024.md index b6cdf2363..aba1544d7 100644 --- a/ecosystem/sep-0024.md +++ b/ecosystem/sep-0024.md @@ -403,10 +403,10 @@ The fields below should be placed in the request body using the `multipart/form- Request Parameters: | Name | Type | Description | -|-------------------------------| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| ----------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `asset_code` | string | The code of the stellar asset the user wants to receive for their deposit with the anchor. The value passed must match one of the codes listed in the [/info](#info) response's deposit object. When `quote_id` is specified, `asset_code` must match the quote's `buy_asset` asset code. | | `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to receive for their deposit with the anchor. If asset_issuer is not provided, the anchor should use the asset issued by themselves as described in their TOML file. When `quote_id` is specified, `asset_issuer` must match the quote's `buy_asset` asset issuer. | -| `receiving_asset` | string in [Asset Identification Format] | (optional) The asset user wants to receive. When `quote_id` is specified, this parameter is mandatory and must match the quote's `setll_asset` asset code. | +| `receiving_asset` | string in [Asset Identification Format] | (optional) The asset user wants to receive. If this is not provided, it will be collected in the interactive flow. When `quote_id` is specified, this parameter is mandatory and must match the quote's `setll_asset` asset code. | | `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 must respect the conversion rate agreed in that quote. If the values of `asset` and `amount` conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | | `amount` | number | (optional) Amount of asset requested to deposit. If this is not provided it will be collected in the interactive flow. Should be equals to `quote.sell_amount` or omitted if a `quote_id` was used. | | `account` | `G...` or `M...` string | (optional) The Stellar or muxed account the client wants to use as the destination of the payment sent by the anchor. Defaults to the account authenticated via SEP-10 if not specified. | @@ -606,7 +606,7 @@ Request parameters: | ------------------ | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `asset_code` | string | Code of the asset the user wants to withdraw. The value passed must match one of the codes listed in the [/info](#info) response's withdraw object. When `quote_id` is specified, `asset_code` must match the quote's `sell_asset` asset code. | | `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to withdraw with the anchor. If `asset_issuer` is not provided, the anchor should use the asset issued by themselves as described in their TOML file. When `quote_id` is specified, `asset_issuer` must match the quote's `buy_asset` asset issuer. | -| `receiving_asset` | string in [Asset Identification Format] | (optional) The asset user wants to receive. When `quote_id` is specified, this parameter is mandatory and must match the quote's `buy_asset` asset code. | +| `receiving_asset` | string in [Asset Identification Format] | (optional) The asset user wants to receive. If this is not provided, it will be collected in the interactive flow. When `quote_id` is specified, this parameter is mandatory and must match the quote's `buy_asset` asset code. | | `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 must respect the conversion rate agreed in that quote. If the values of `asset` and `amount` conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | | `amount` | number | (optional) Amount of asset requested to withdraw. If this is not provided it will be collected in the interactive flow. Should be equals to `quote.sell_amount` or omitted if a `quote_id` was used. | | `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. Defaults to the account authenticated via SEP-10 if not specified. | From b5a26780d677ef9ddfc64eb26c4edc7b7d71be56 Mon Sep 17 00:00:00 2001 From: Gleb Date: Mon, 12 Jun 2023 13:20:42 -0700 Subject: [PATCH 07/17] Update field name --- ecosystem/sep-0024.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/ecosystem/sep-0024.md b/ecosystem/sep-0024.md index aba1544d7..fc0a29783 100644 --- a/ecosystem/sep-0024.md +++ b/ecosystem/sep-0024.md @@ -406,7 +406,7 @@ Request Parameters: | ----------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `asset_code` | string | The code of the stellar asset the user wants to receive for their deposit with the anchor. The value passed must match one of the codes listed in the [/info](#info) response's deposit object. When `quote_id` is specified, `asset_code` must match the quote's `buy_asset` asset code. | | `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to receive for their deposit with the anchor. If asset_issuer is not provided, the anchor should use the asset issued by themselves as described in their TOML file. When `quote_id` is specified, `asset_issuer` must match the quote's `buy_asset` asset issuer. | -| `receiving_asset` | string in [Asset Identification Format] | (optional) The asset user wants to receive. If this is not provided, it will be collected in the interactive flow. When `quote_id` is specified, this parameter is mandatory and must match the quote's `setll_asset` asset code. | +| `sending_asset` | string in [Asset Identification Format] | (optional) The asset user wants to send. Note, that this is the asset user initially holds (off-chain or fiat asset).If this is not provided, it will be collected in the interactive flow. When `quote_id` is specified, this parameter is mandatory and must match the quote's `setll_asset` asset code. | | `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 must respect the conversion rate agreed in that quote. If the values of `asset` and `amount` conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | | `amount` | number | (optional) Amount of asset requested to deposit. If this is not provided it will be collected in the interactive flow. Should be equals to `quote.sell_amount` or omitted if a `quote_id` was used. | | `account` | `G...` or `M...` string | (optional) The Stellar or muxed account the client wants to use as the destination of the payment sent by the anchor. Defaults to the account authenticated via SEP-10 if not specified. | @@ -602,21 +602,21 @@ The fields below should be placed in the request body using the `multipart/form- Request parameters: -| Name | Type | Description | -| ------------------ | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `asset_code` | string | Code of the asset the user wants to withdraw. The value passed must match one of the codes listed in the [/info](#info) response's withdraw object. When `quote_id` is specified, `asset_code` must match the quote's `sell_asset` asset code. | -| `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to withdraw with the anchor. If `asset_issuer` is not provided, the anchor should use the asset issued by themselves as described in their TOML file. When `quote_id` is specified, `asset_issuer` must match the quote's `buy_asset` asset issuer. | -| `receiving_asset` | string in [Asset Identification Format] | (optional) The asset user wants to receive. If this is not provided, it will be collected in the interactive flow. When `quote_id` is specified, this parameter is mandatory and must match the quote's `buy_asset` asset code. | -| `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 must respect the conversion rate agreed in that quote. If the values of `asset` and `amount` conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | -| `amount` | number | (optional) Amount of asset requested to withdraw. If this is not provided it will be collected in the interactive flow. Should be equals to `quote.sell_amount` or omitted if a `quote_id` was used. | -| `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. Defaults to the account authenticated via SEP-10 if not specified. | -| `memo` | string | (**deprecated**, optional) This field was originally intended to differentiate users of the same Stellar account. However, the anchor should use the `sub` value included in the decoded SEP-10 JWT instead. Anchors should still support this parameter to maintain support for outdated clients. See the [Shared Account Authentication](#shared-omnibus-or-pooled-accounts) section for more information. | -| `memo_type` | string | (**deprecated**, optional) Type of `memo`. One of `text`, `id` or `hash`. Deprecated because memos used to identify users of the same Stellar account should always be of type of `id`. | -| `wallet_name` | string | (optional) In communications / pages about the withdrawal, anchor should display the wallet name to the user to explain where funds are coming from. | -| `wallet_url` | string | (optional) Anchor can show this to the user when referencing the wallet involved in the withdrawal (ex. in the anchor's transaction history). | -| `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646] which means it can also accept locale in the format `en-US`. `error` fields in the response, as well as the interactive flow UI and any other user-facing strings returned for this transaction should be in this language. | -| `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. | +| Name | Type | Description | +| ------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `asset_code` | string | Code of the asset the user wants to withdraw. The value passed must match one of the codes listed in the [/info](#info) response's withdraw object. When `quote_id` is specified, `asset_code` must match the quote's `sell_asset` asset code. | +| `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to withdraw with the anchor. If `asset_issuer` is not provided, the anchor should use the asset issued by themselves as described in their TOML file. When `quote_id` is specified, `asset_issuer` must match the quote's `buy_asset` asset issuer. | +| `destination_asset` | string in [Asset Identification Format] | (optional) The asset user wants to receive. It's an off-chain or fiat asset. If this is not provided, it will be collected in the interactive flow. When `quote_id` is specified, this parameter is mandatory and must match the quote's `buy_asset` asset code. | +| `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 must respect the conversion rate agreed in that quote. If the values of `asset` and `amount` conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | +| `amount` | number | (optional) Amount of asset requested to withdraw. If this is not provided it will be collected in the interactive flow. Should be equals to `quote.sell_amount` or omitted if a `quote_id` was used. | +| `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. Defaults to the account authenticated via SEP-10 if not specified. | +| `memo` | string | (**deprecated**, optional) This field was originally intended to differentiate users of the same Stellar account. However, the anchor should use the `sub` value included in the decoded SEP-10 JWT instead. Anchors should still support this parameter to maintain support for outdated clients. See the [Shared Account Authentication](#shared-omnibus-or-pooled-accounts) section for more information. | +| `memo_type` | string | (**deprecated**, optional) Type of `memo`. One of `text`, `id` or `hash`. Deprecated because memos used to identify users of the same Stellar account should always be of type of `id`. | +| `wallet_name` | string | (optional) In communications / pages about the withdrawal, anchor should display the wallet name to the user to explain where funds are coming from. | +| `wallet_url` | string | (optional) Anchor can show this to the user when referencing the wallet involved in the withdrawal (ex. in the anchor's transaction history). | +| `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646] which means it can also accept locale in the format `en-US`. `error` fields in the response, as well as the interactive flow UI and any other user-facing strings returned for this transaction should be in this language. | +| `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. | Additionally, any [SEP-9](sep-0009.md) parameters may be passed as well to make the onboarding experience simpler. From 715d810391fcffa9f156313db35c2bf6ebbf5bdd Mon Sep 17 00:00:00 2001 From: Gleb Date: Mon, 12 Jun 2023 13:35:04 -0700 Subject: [PATCH 08/17] Fix table --- ecosystem/sep-0024.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/ecosystem/sep-0024.md b/ecosystem/sep-0024.md index fc0a29783..e71674ffb 100644 --- a/ecosystem/sep-0024.md +++ b/ecosystem/sep-0024.md @@ -953,15 +953,12 @@ The `features` object contains boolean values indicating whether specific featur object or specific feature is not present in the response, the default value described below may be assumed. This information enables wallets to adjust their behavior based on the feature set supported by the anchor. -| Name | Default | Description | -| ---------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------- | -| `account_creation` | `true` | Whether or not the anchor supports creating accounts for users requesting | -| deposits. | -| `claimable_balances` | `false` | Whether or not the anchor supports sending deposit funds as claimable | -| balances. This is relevant for users of Stellar accounts without a trustline to the requested asset. | -| `indicative_quotes_supported` | `false` | Whether or not the anchor supports indicative quotes provided | -| by `SEP-38 GET /price` and `SEP-38 GET /prices` API. | | -| `firm_quotes_supported` | `false` | Whether or not the anchor supports indicative quotes provided | +| Name | Default | Description | +| ----------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `account_creation` | `true` | Whether or not the anchor supports creating accounts for users requesting deposits. | +| `claimable_balances` | `false` | Whether or not the anchor supports sending deposit funds as claimable balances. This is relevant for users of Stellar accounts without a trustline to the requested asset. | +| `indicative_quotes_supported` | `false` | Whether or not the anchor supports indicative quotes provided by `SEP-38 GET /price` and `SEP-38 GET /prices` API. | +| `firm_quotes_supported` | `false` | Whether or not the anchor supports indicative quotes provided | by `SEP-38 POST /quote` and `SEP-38 POST /prices` API. If set to yes, anchor must support `quote_id` parameter in interactive endpoints and transaction response body. | From d17dc5c59727f21a6a3e1bbfa40fc3381f252d97 Mon Sep 17 00:00:00 2001 From: Gleb Date: Wed, 14 Jun 2023 11:29:22 -0700 Subject: [PATCH 09/17] Fix typo --- ecosystem/sep-0024.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ecosystem/sep-0024.md b/ecosystem/sep-0024.md index e71674ffb..9b383b45d 100644 --- a/ecosystem/sep-0024.md +++ b/ecosystem/sep-0024.md @@ -406,7 +406,7 @@ Request Parameters: | ----------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `asset_code` | string | The code of the stellar asset the user wants to receive for their deposit with the anchor. The value passed must match one of the codes listed in the [/info](#info) response's deposit object. When `quote_id` is specified, `asset_code` must match the quote's `buy_asset` asset code. | | `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to receive for their deposit with the anchor. If asset_issuer is not provided, the anchor should use the asset issued by themselves as described in their TOML file. When `quote_id` is specified, `asset_issuer` must match the quote's `buy_asset` asset issuer. | -| `sending_asset` | string in [Asset Identification Format] | (optional) The asset user wants to send. Note, that this is the asset user initially holds (off-chain or fiat asset).If this is not provided, it will be collected in the interactive flow. When `quote_id` is specified, this parameter is mandatory and must match the quote's `setll_asset` asset code. | +| `sending_asset` | string in [Asset Identification Format] | (optional) The asset user wants to send. Note, that this is the asset user initially holds (off-chain or fiat asset).If this is not provided, it will be collected in the interactive flow. When `quote_id` is specified, this parameter is mandatory and must match the quote's `sell_asset` asset code. | | `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 must respect the conversion rate agreed in that quote. If the values of `asset` and `amount` conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | | `amount` | number | (optional) Amount of asset requested to deposit. If this is not provided it will be collected in the interactive flow. Should be equals to `quote.sell_amount` or omitted if a `quote_id` was used. | | `account` | `G...` or `M...` string | (optional) The Stellar or muxed account the client wants to use as the destination of the payment sent by the anchor. Defaults to the account authenticated via SEP-10 if not specified. | From 2a7b2b67b9b18380e895902fb791f801480259bd Mon Sep 17 00:00:00 2001 From: Gleb Date: Wed, 14 Jun 2023 11:34:43 -0700 Subject: [PATCH 10/17] Update quote_id description --- ecosystem/sep-0024.md | 58 +++++++++++++++++++++---------------------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/ecosystem/sep-0024.md b/ecosystem/sep-0024.md index 9b383b45d..6db78a92c 100644 --- a/ecosystem/sep-0024.md +++ b/ecosystem/sep-0024.md @@ -402,20 +402,20 @@ The fields below should be placed in the request body using the `multipart/form- Request Parameters: -| Name | Type | Description | -| ----------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `asset_code` | string | The code of the stellar asset the user wants to receive for their deposit with the anchor. The value passed must match one of the codes listed in the [/info](#info) response's deposit object. When `quote_id` is specified, `asset_code` must match the quote's `buy_asset` asset code. | -| `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to receive for their deposit with the anchor. If asset_issuer is not provided, the anchor should use the asset issued by themselves as described in their TOML file. When `quote_id` is specified, `asset_issuer` must match the quote's `buy_asset` asset issuer. | -| `sending_asset` | string in [Asset Identification Format] | (optional) The asset user wants to send. Note, that this is the asset user initially holds (off-chain or fiat asset).If this is not provided, it will be collected in the interactive flow. When `quote_id` is specified, this parameter is mandatory and must match the quote's `sell_asset` asset code. | -| `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 must respect the conversion rate agreed in that quote. If the values of `asset` and `amount` conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | -| `amount` | number | (optional) Amount of asset requested to deposit. If this is not provided it will be collected in the interactive flow. Should be equals to `quote.sell_amount` or omitted if a `quote_id` was used. | -| `account` | `G...` or `M...` string | (optional) The Stellar or muxed account the client wants to use as the destination of the payment sent by the anchor. Defaults to the account authenticated via SEP-10 if not specified. | -| `memo_type` | string | (optional) Type of memo that anchor should attach to the Stellar 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 can be different than the value 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`. | -| `wallet_name` | string | (optional) In communications / pages about the deposit, anchor should display the wallet name to the user to explain where funds are going. | -| `wallet_url` | string | (optional) Anchor should link to this when notifying the user that the transaction has completed. | -| `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646] which means it can also accept locale in the format `en-US`. `error` fields in the response, as well as the interactive flow UI and any other user-facing strings returned for this transaction should be in this language. | -| `claimable_balance_supported` | boolean | (optional) True if the client supports receiving deposit transactions as a claimable balance, false otherwise. | +| Name | Type | Description | +| ----------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `asset_code` | string | The code of the stellar asset the user wants to receive for their deposit with the anchor. The value passed must match one of the codes listed in the [/info](#info) response's deposit object. When `quote_id` is specified, `asset_code` must match the quote's `buy_asset` asset code. | +| `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to receive for their deposit with the anchor. If asset_issuer is not provided, the anchor should use the asset issued by themselves as described in their TOML file. When `quote_id` is specified, `asset_issuer` must match the quote's `buy_asset` asset issuer. | +| `sending_asset` | string in [Asset Identification Format] | (optional) The asset user wants to send. Note, that this is the asset user initially holds (off-chain or fiat asset).If this is not provided, it will be collected in the interactive flow. When `quote_id` is specified, this parameter is mandatory and must match the quote's `sell_asset` asset code. | +| `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 must respect the conversion rate agreed in that quote. When `quote_id` is set, `asset_code`, `sending_asset` and `amount` are mandatory. In case of a conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | +| `amount` | number | (optional) Amount of asset requested to deposit. If this is not provided it will be collected in the interactive flow. Should be equals to `quote.sell_amount` or omitted if a `quote_id` was used. | +| `account` | `G...` or `M...` string | (optional) The Stellar or muxed account the client wants to use as the destination of the payment sent by the anchor. Defaults to the account authenticated via SEP-10 if not specified. | +| `memo_type` | string | (optional) Type of memo that anchor should attach to the Stellar 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 can be different than the value 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`. | +| `wallet_name` | string | (optional) In communications / pages about the deposit, anchor should display the wallet name to the user to explain where funds are going. | +| `wallet_url` | string | (optional) Anchor should link to this when notifying the user that the transaction has completed. | +| `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646] which means it can also accept locale in the format `en-US`. `error` fields in the response, as well as the interactive flow UI and any other user-facing strings returned for this transaction should be in this language. | +| `claimable_balance_supported` | boolean | (optional) True if the client supports receiving deposit transactions as a claimable balance, false otherwise. | Additionally, any [SEP-9](sep-0009.md) parameters may be passed as well to make the onboarding experience simpler. @@ -602,21 +602,21 @@ The fields below should be placed in the request body using the `multipart/form- Request parameters: -| Name | Type | Description | -| ------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `asset_code` | string | Code of the asset the user wants to withdraw. The value passed must match one of the codes listed in the [/info](#info) response's withdraw object. When `quote_id` is specified, `asset_code` must match the quote's `sell_asset` asset code. | -| `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to withdraw with the anchor. If `asset_issuer` is not provided, the anchor should use the asset issued by themselves as described in their TOML file. When `quote_id` is specified, `asset_issuer` must match the quote's `buy_asset` asset issuer. | -| `destination_asset` | string in [Asset Identification Format] | (optional) The asset user wants to receive. It's an off-chain or fiat asset. If this is not provided, it will be collected in the interactive flow. When `quote_id` is specified, this parameter is mandatory and must match the quote's `buy_asset` asset code. | -| `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 must respect the conversion rate agreed in that quote. If the values of `asset` and `amount` conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | -| `amount` | number | (optional) Amount of asset requested to withdraw. If this is not provided it will be collected in the interactive flow. Should be equals to `quote.sell_amount` or omitted if a `quote_id` was used. | -| `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. Defaults to the account authenticated via SEP-10 if not specified. | -| `memo` | string | (**deprecated**, optional) This field was originally intended to differentiate users of the same Stellar account. However, the anchor should use the `sub` value included in the decoded SEP-10 JWT instead. Anchors should still support this parameter to maintain support for outdated clients. See the [Shared Account Authentication](#shared-omnibus-or-pooled-accounts) section for more information. | -| `memo_type` | string | (**deprecated**, optional) Type of `memo`. One of `text`, `id` or `hash`. Deprecated because memos used to identify users of the same Stellar account should always be of type of `id`. | -| `wallet_name` | string | (optional) In communications / pages about the withdrawal, anchor should display the wallet name to the user to explain where funds are coming from. | -| `wallet_url` | string | (optional) Anchor can show this to the user when referencing the wallet involved in the withdrawal (ex. in the anchor's transaction history). | -| `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646] which means it can also accept locale in the format `en-US`. `error` fields in the response, as well as the interactive flow UI and any other user-facing strings returned for this transaction should be in this language. | -| `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. | +| Name | Type | Description | +| ------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `asset_code` | string | Code of the asset the user wants to withdraw. The value passed must match one of the codes listed in the [/info](#info) response's withdraw object. When `quote_id` is specified, `asset_code` must match the quote's `sell_asset` asset code. | +| `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to withdraw with the anchor. If `asset_issuer` is not provided, the anchor should use the asset issued by themselves as described in their TOML file. When `quote_id` is specified, `asset_issuer` must match the quote's `buy_asset` asset issuer. | +| `destination_asset` | string in [Asset Identification Format] | (optional) The asset user wants to receive. It's an off-chain or fiat asset. If this is not provided, it will be collected in the interactive flow. When `quote_id` is specified, this parameter is mandatory and must match the quote's `buy_asset` asset code. | +| `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 must respect the conversion rate agreed in that quote. When `quote_id` is set, `asset_code`, `destination_asset` and `amount` are mandatory. In case of a conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | +| `amount` | number | (optional) Amount of asset requested to withdraw. If this is not provided it will be collected in the interactive flow. Should be equals to `quote.sell_amount` or omitted if a `quote_id` was used. | +| `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. Defaults to the account authenticated via SEP-10 if not specified. | +| `memo` | string | (**deprecated**, optional) This field was originally intended to differentiate users of the same Stellar account. However, the anchor should use the `sub` value included in the decoded SEP-10 JWT instead. Anchors should still support this parameter to maintain support for outdated clients. See the [Shared Account Authentication](#shared-omnibus-or-pooled-accounts) section for more information. | +| `memo_type` | string | (**deprecated**, optional) Type of `memo`. One of `text`, `id` or `hash`. Deprecated because memos used to identify users of the same Stellar account should always be of type of `id`. | +| `wallet_name` | string | (optional) In communications / pages about the withdrawal, anchor should display the wallet name to the user to explain where funds are coming from. | +| `wallet_url` | string | (optional) Anchor can show this to the user when referencing the wallet involved in the withdrawal (ex. in the anchor's transaction history). | +| `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646] which means it can also accept locale in the format `en-US`. `error` fields in the response, as well as the interactive flow UI and any other user-facing strings returned for this transaction should be in this language. | +| `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. | Additionally, any [SEP-9](sep-0009.md) parameters may be passed as well to make the onboarding experience simpler. From 754c6b0def1fe350c858c9ccafc65efb25ff5420 Mon Sep 17 00:00:00 2001 From: Gleb Date: Wed, 14 Jun 2023 14:02:04 -0700 Subject: [PATCH 11/17] Fix optional fields description --- ecosystem/sep-0024.md | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/ecosystem/sep-0024.md b/ecosystem/sep-0024.md index 6db78a92c..8e69be510 100644 --- a/ecosystem/sep-0024.md +++ b/ecosystem/sep-0024.md @@ -405,10 +405,10 @@ Request Parameters: | Name | Type | Description | | ----------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `asset_code` | string | The code of the stellar asset the user wants to receive for their deposit with the anchor. The value passed must match one of the codes listed in the [/info](#info) response's deposit object. When `quote_id` is specified, `asset_code` must match the quote's `buy_asset` asset code. | -| `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to receive for their deposit with the anchor. If asset_issuer is not provided, the anchor should use the asset issued by themselves as described in their TOML file. When `quote_id` is specified, `asset_issuer` must match the quote's `buy_asset` asset issuer. | -| `sending_asset` | string in [Asset Identification Format] | (optional) The asset user wants to send. Note, that this is the asset user initially holds (off-chain or fiat asset).If this is not provided, it will be collected in the interactive flow. When `quote_id` is specified, this parameter is mandatory and must match the quote's `sell_asset` asset code. | +| `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to receive for their deposit with the anchor. If asset_issuer is not provided, the anchor should use the asset issued by themselves as described in their TOML file. When `quote_id` is specified, this parameter must match the quote's `buy_asset` asset code or be omitted. | +| `sending_asset` | string in [Asset Identification Format] | (optional) The asset user wants to send. Note, that this is the asset user initially holds (off-chain or fiat asset).If this is not provided, it will be collected in the interactive flow. When `quote_id` is specified, this parameter must match the quote's `sell_asset` asset code or be omitted. | +| `amount` | number | (optional) Amount of asset requested to deposit. If this is not provided it will be collected in the interactive flow. When `qoute_id` is specified, this parameter must match the quote's `quote.sell_amount` or be omitted. | | `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 must respect the conversion rate agreed in that quote. When `quote_id` is set, `asset_code`, `sending_asset` and `amount` are mandatory. In case of a conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | -| `amount` | number | (optional) Amount of asset requested to deposit. If this is not provided it will be collected in the interactive flow. Should be equals to `quote.sell_amount` or omitted if a `quote_id` was used. | | `account` | `G...` or `M...` string | (optional) The Stellar or muxed account the client wants to use as the destination of the payment sent by the anchor. Defaults to the account authenticated via SEP-10 if not specified. | | `memo_type` | string | (optional) Type of memo that anchor should attach to the Stellar 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 can be different than the value 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`. | @@ -602,21 +602,21 @@ The fields below should be placed in the request body using the `multipart/form- Request parameters: -| Name | Type | Description | -| ------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `asset_code` | string | Code of the asset the user wants to withdraw. The value passed must match one of the codes listed in the [/info](#info) response's withdraw object. When `quote_id` is specified, `asset_code` must match the quote's `sell_asset` asset code. | -| `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to withdraw with the anchor. If `asset_issuer` is not provided, the anchor should use the asset issued by themselves as described in their TOML file. When `quote_id` is specified, `asset_issuer` must match the quote's `buy_asset` asset issuer. | -| `destination_asset` | string in [Asset Identification Format] | (optional) The asset user wants to receive. It's an off-chain or fiat asset. If this is not provided, it will be collected in the interactive flow. When `quote_id` is specified, this parameter is mandatory and must match the quote's `buy_asset` asset code. | -| `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 must respect the conversion rate agreed in that quote. When `quote_id` is set, `asset_code`, `destination_asset` and `amount` are mandatory. In case of a conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | -| `amount` | number | (optional) Amount of asset requested to withdraw. If this is not provided it will be collected in the interactive flow. Should be equals to `quote.sell_amount` or omitted if a `quote_id` was used. | -| `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. Defaults to the account authenticated via SEP-10 if not specified. | -| `memo` | string | (**deprecated**, optional) This field was originally intended to differentiate users of the same Stellar account. However, the anchor should use the `sub` value included in the decoded SEP-10 JWT instead. Anchors should still support this parameter to maintain support for outdated clients. See the [Shared Account Authentication](#shared-omnibus-or-pooled-accounts) section for more information. | -| `memo_type` | string | (**deprecated**, optional) Type of `memo`. One of `text`, `id` or `hash`. Deprecated because memos used to identify users of the same Stellar account should always be of type of `id`. | -| `wallet_name` | string | (optional) In communications / pages about the withdrawal, anchor should display the wallet name to the user to explain where funds are coming from. | -| `wallet_url` | string | (optional) Anchor can show this to the user when referencing the wallet involved in the withdrawal (ex. in the anchor's transaction history). | -| `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646] which means it can also accept locale in the format `en-US`. `error` fields in the response, as well as the interactive flow UI and any other user-facing strings returned for this transaction should be in this language. | -| `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. | +| Name | Type | Description | +| ------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `asset_code` | string | Code of the asset the user wants to withdraw. The value passed must match one of the codes listed in the [/info](#info) response's withdraw object. When `quote_id` is specified, `asset_code` must match the quote's `sell_asset` asset code. | +| `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to withdraw with the anchor. If `asset_issuer` is not provided, the anchor should use the asset issued by themselves as described in their TOML file. When `quote_id` is specified, `asset_issuer` must match the quote's `buy_asset` asset issuer or be omitted. | +| `destination_asset` | string in [Asset Identification Format] | (optional) The asset user wants to receive. It's an off-chain or fiat asset. If this is not provided, it will be collected in the interactive flow. When `quote_id` is specified, this parameter must match the quote's `buy_asset` asset code or be omitted. | +| `amount` | number | (optional) Amount of asset requested to withdraw. If this is not provided it will be collected in the interactive flow. When `qoute_id` is specified, this parameter must match the quote's `quote.sell_amount` or be omitted. | +| `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 must respect the conversion rate agreed in that quote. When `quote_id` is set, `asset_code`, `destination_asset` and `amount` must be validated by the anchor, if present. In case of a conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | +| `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. Defaults to the account authenticated via SEP-10 if not specified. | +| `memo` | string | (**deprecated**, optional) This field was originally intended to differentiate users of the same Stellar account. However, the anchor should use the `sub` value included in the decoded SEP-10 JWT instead. Anchors should still support this parameter to maintain support for outdated clients. See the [Shared Account Authentication](#shared-omnibus-or-pooled-accounts) section for more information. | +| `memo_type` | string | (**deprecated**, optional) Type of `memo`. One of `text`, `id` or `hash`. Deprecated because memos used to identify users of the same Stellar account should always be of type of `id`. | +| `wallet_name` | string | (optional) In communications / pages about the withdrawal, anchor should display the wallet name to the user to explain where funds are coming from. | +| `wallet_url` | string | (optional) Anchor can show this to the user when referencing the wallet involved in the withdrawal (ex. in the anchor's transaction history). | +| `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646] which means it can also accept locale in the format `en-US`. `error` fields in the response, as well as the interactive flow UI and any other user-facing strings returned for this transaction should be in this language. | +| `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. | Additionally, any [SEP-9](sep-0009.md) parameters may be passed as well to make the onboarding experience simpler. From c1e9b7456544a0c009843516b47c0661ae39e29e Mon Sep 17 00:00:00 2001 From: Gleb Date: Thu, 15 Jun 2023 13:39:59 -0700 Subject: [PATCH 12/17] Fix qoute_id description --- ecosystem/sep-0024.md | 266 ++++++++++++++++++++++-------------------- 1 file changed, 139 insertions(+), 127 deletions(-) diff --git a/ecosystem/sep-0024.md b/ecosystem/sep-0024.md index 8e69be510..e48168b36 100644 --- a/ecosystem/sep-0024.md +++ b/ecosystem/sep-0024.md @@ -230,33 +230,33 @@ It is the wallet's responsibility to: - Check that callback request has `Signature` or `X-Stellar-Signature` (deprecated) header - Parse the header and extract: - - Key `t`: **timestamp** - - Key `s`: **base64 signature** + - Key `t`: **timestamp** + - Key `s`: **base64 signature** - Verify the request freshness: _current timestamp_ - **timestamp** < few seconds (1-2 minute(s) max) - Extract the **body** of the request - Base64 decode the **base64 signature** to get the **signature** - Prepare the payload to verify the signature: - - The **timestamp** (as a string) - - The character `.` - - The wallet host to send the callback request to - - The character `.` - - The **body** + - The **timestamp** (as a string) + - The character `.` + - The wallet host to send the callback request to + - The character `.` + - The **body** - Verify the signature using the correct `SIGNING_KEY` ### COMPUTE signature - Prepare the callback - Prepare the payload to sign: - - Current timestamp (as a string) - - The character `.` - - The wallet host to send the callback request to - - The character `.` - - The callback request body + - Current timestamp (as a string) + - The character `.` + - The wallet host to send the callback request to + - The character `.` + - The callback request body - Sign the payload `..` using the Anchor private key - Base64 encode the signature - Build the `Signature` or `X-Stellar-Signature` (deprecated) header: - - `Signature: t=, s=` - - `X-Stellar-Signature: t=, s=` + - `Signature: t=, s=` + - `X-Stellar-Signature: t=, s=` ## Content Type @@ -291,35 +291,37 @@ banking rails so counterparties can run through the flow without a need to colla display the asset's quote (if possible) as well as information such as the address of the anchor and description of the asset from the `stellar.toml` file. - **If [SEP-38] quote API is supported by the anchor** - - Fetch the asset's exchange rate at the market price using [`SEP-38 GET /price`](sep-0038.md#get-price) API. - - For the firm quote, use [`SEP-38 POST /quote`](sep-0038.md#post-quote) API and show the quote and expiration time to - the user. + - Fetch the asset's exchange rate at the market price using [`SEP-38 GET /price`](sep-0038.md#get-price) API. + - For the firm quote, use [`SEP-38 POST /quote`](sep-0038.md#post-quote) API and show the quote and expiration time + to + the user. - **Authentication** - - Perform [authentication](#authentication) via SEP-10 before hitting those endpoints + - Perform [authentication](#authentication) via SEP-10 before hitting those endpoints - **Make a request to `/transactions/deposit/interactive` or `/transactions/withdraw/interactive`.** - - This will respond with the interactive url needed to proceed with KYC and deposit/withdraw details. + - This will respond with the interactive url needed to proceed with KYC and deposit/withdraw details. - **For `/transactions/deposit/interactive` and `/transactions/withdraw/interactive`** - - Optionally attach any fields from [SEP-9](sep-0009.md) as POST parameters in the `/deposit` or `/withdraw` endpoints - in order to let the anchor pre-fill them in the interactive flow UI. This is optional, but can create a much nicer - user experience. `email_address`, `first_name` and `last_name` are good examples of fields to help pre-fill the - anchors website. - - Optionally attach [SEP-38] quote id, in order to the anchor to use the quote previously shown to the user. + - Optionally attach any fields from [SEP-9](sep-0009.md) as POST parameters in the `/deposit` or `/withdraw` + endpoints + in order to let the anchor pre-fill them in the interactive flow UI. This is optional, but can create a much nicer + user experience. `email_address`, `first_name` and `last_name` are good examples of fields to help pre-fill the + anchors website. + - Optionally attach [SEP-38] quote id, in order to the anchor to use the quote previously shown to the user. - **For `/transactions/deposit/interactive`** - - Handle the interactive flow, handle it as [described in detail](#interactive-customer-information-needed). - - Handle the [special cases](#special-cases), they're relatively common. + - Handle the interactive flow, handle it as [described in detail](#interactive-customer-information-needed). + - Handle the [special cases](#special-cases), they're relatively common. - **For `/transactions/withdraw/interactive`** - - Handle the interactive flow, handle it as [described in detail](#interactive-customer-information-needed). - - When the transaction status becomes `pending_user_transfer_start` send the required payment as described in the - interactive webapp callback or the `/transaction` endpoint. This can be a `payment` or `path_payment` operation. - Sending payments via `account_merge` or `create_account` is not supported at this time. - - Some wallets might exchange currencies only once they're ready to send the withdrawal payment, so exchange rate - fluctuations might require withdrawal values to slightly vary from the originally provided `amount`. Anchors are - instructed to accept a variation of ±10% between the informed `amount` and the actual value sent to the anchor's - Stellar account. The withdrawn amount will be adjusted accordingly. + - Handle the interactive flow, handle it as [described in detail](#interactive-customer-information-needed). + - When the transaction status becomes `pending_user_transfer_start` send the required payment as described in the + interactive webapp callback or the `/transaction` endpoint. This can be a `payment` or `path_payment` operation. + Sending payments via `account_merge` or `create_account` is not supported at this time. + - Some wallets might exchange currencies only once they're ready to send the withdrawal payment, so exchange rate + fluctuations might require withdrawal values to slightly vary from the originally provided `amount`. Anchors are + instructed to accept a variation of ±10% between the informed `amount` and the actual value sent to the anchor's + Stellar account. The withdrawn amount will be adjusted accordingly. - **Transaction history** - - Provide a list of historical and current deposits and withdrawals at the [`/transactions`](#transactions) endpoint - for wallets to show a view of all of a single anchors transactions in a list. - - Provide status or instructions for a specific deposit or withdraw at the [`/transaction`](#transaction) endpoint + - Provide a list of historical and current deposits and withdrawals at the [`/transactions`](#transactions) endpoint + for wallets to show a view of all of a single anchors transactions in a list. + - Provide status or instructions for a specific deposit or withdraw at the [`/transaction`](#transaction) endpoint ### Basic Anchor Implementation @@ -327,49 +329,57 @@ banking rails so counterparties can run through the flow without a need to colla - Implement [SEP-38] to offer better user experience. Wallet would be able to show rates and fees your anchor provides early in the process. (Before the user initiates a transaction via interactive UI) - **For both deposit and withdrawal**: - - To start an interactive flow, provide the [Customer info needed response](#interactive-customer-information-needed). - - Some wallets may include other fields indicated in [SEP-9](sep-0009.md) as POST parameters added to the - `/transactions/deposit/interactive` or `/transactions/withdraw/interactive` endpoints. These can be stored and used - to pre-populate fields in the interactive flow. This is optional for the wallet to provide and optional for anchors - to respect, but it does create a much nicer user experience. - - Some wallets may include `quote_id` fetched from the [`SEP-38 POST /quote`](sep-0038.md#post-quote) API. If - provided, your implementation must respect the agreed quote. - - Include the `id` field in your response to `/transactions/deposit/interactive` and - `/transactions/withdraw/interactive` so the wallet can check up on the status of the transaction if it wants. - - Also include the `id` field in the popup URL you provide to the wallet. This allows you to keep track of the - transaction when the user visits the URL. - - We recommend you use [SEP-10](#authentication) for authentication in the interactive flow and do not separately - prompt for password to achieve a good user experience (although asking for MFA when confirming a transaction or - requiring email confirmation is reasonable). Putting a one time use token or quickly expiring JWT in the URL - returned to the client is a good way to keep continuity between authenticated API calls and fresh interactive flow - requests. - - Test your interactive flows on mobile. They should be easy to use on all devices: make them responsive, handle - auto-fill well, and do smart keyboard management on mobile devices. + - To start an interactive flow, provide + the [Customer info needed response](#interactive-customer-information-needed). + - Some wallets may include other fields indicated in [SEP-9](sep-0009.md) as POST parameters added to the + `/transactions/deposit/interactive` or `/transactions/withdraw/interactive` endpoints. These can be stored and + used + to pre-populate fields in the interactive flow. This is optional for the wallet to provide and optional for + anchors + to respect, but it does create a much nicer user experience. + - Some wallets may include `quote_id` fetched from the [`SEP-38 POST /quote`](sep-0038.md#post-quote) API. If + provided, your implementation must respect the agreed quote. + - Include the `id` field in your response to `/transactions/deposit/interactive` and + `/transactions/withdraw/interactive` so the wallet can check up on the status of the transaction if it wants. + - Also include the `id` field in the popup URL you provide to the wallet. This allows you to keep track of the + transaction when the user visits the URL. + - We recommend you use [SEP-10](#authentication) for authentication in the interactive flow and do not separately + prompt for password to achieve a good user experience (although asking for MFA when confirming a transaction or + requiring email confirmation is reasonable). Putting a one time use token or quickly expiring JWT in the URL + returned to the client is a good way to keep continuity between authenticated API calls and fresh interactive flow + requests. + - Test your interactive flows on mobile. They should be easy to use on all devices: make them responsive, handle + auto-fill well, and do smart keyboard management on mobile devices. - **Interactive deposit** - - Your interactive deposit popup will do everything needed to initiate the deposit without the user needing to - interact with the wallet further. It should either directly initiate the deposit, or handle displaying information - (such as reference number or bank account number) that the user will need to complete their deposit. + - Your interactive deposit popup will do everything needed to initiate the deposit without the user needing to + interact with the wallet further. It should either directly initiate the deposit, or handle displaying information + (such as reference number or bank account number) that the user will need to complete their deposit. - **Interactive withdrawal** - - Your withdrawal flow will have to pass control back to the user's wallet, so it can initiate the withdrawal with a - Stellar payment to your withdrawal address. You'll need to communicate the withdrawal address, amount and status to - the wallet using the [`callback` parameter](#adding-parameters-to-the-url), and also by making it available on your - `/transaction` endpoint. See [details](#guidance-for-wallets-completing-an-interactive-withdrawal) for polling by - the wallet. - - In order to fulfill a withdrawal, a wallet must make a payment to the Stellar address that the anchor provides. It - is the anchor's job to watch for Stellar payments to the given address and make the external transaction as soon as - they're detected. Anchors must listen for `payment` and `path_payment` - [operations](https://www.stellar.org/developers/horizon/reference/endpoints/payments-all.html). Most Stellar SDKs - already support listening to all payment forms via streaming. - - When the anchor detects the fulfilling payment from the wallet and expects the customer to pick up the withdrawn - amount of cash, the transaction status must be changed to `pending_user_transfer_complete` to indicate the withdrawn - amount is ready for pick-up. - - Some wallets might exchange currencies only once they're ready to send the withdrawal payment, so there might be - slight fluctuations of value between the informed withdrawal `amount` and the actual transferred amount. It is - recommended for anchors to accept an amount fluctuation of up to ±10%, and adjust the amount to be transferred ( and - fees) to reflect the actual value received. + - Your withdrawal flow will have to pass control back to the user's wallet, so it can initiate the withdrawal with a + Stellar payment to your withdrawal address. You'll need to communicate the withdrawal address, amount and status + to + the wallet using the [`callback` parameter](#adding-parameters-to-the-url), and also by making it available on + your + `/transaction` endpoint. See [details](#guidance-for-wallets-completing-an-interactive-withdrawal) for polling by + the wallet. + - In order to fulfill a withdrawal, a wallet must make a payment to the Stellar address that the anchor provides. It + is the anchor's job to watch for Stellar payments to the given address and make the external transaction as soon + as + they're detected. Anchors must listen for `payment` and `path_payment` + [operations](https://www.stellar.org/developers/horizon/reference/endpoints/payments-all.html). Most Stellar SDKs + already support listening to all payment forms via streaming. + - When the anchor detects the fulfilling payment from the wallet and expects the customer to pick up the withdrawn + amount of cash, the transaction status must be changed to `pending_user_transfer_complete` to indicate the + withdrawn + amount is ready for pick-up. + - Some wallets might exchange currencies only once they're ready to send the withdrawal payment, so there might be + slight fluctuations of value between the informed withdrawal `amount` and the actual transferred amount. It is + recommended for anchors to accept an amount fluctuation of up to ±10%, and adjust the amount to be transferred ( + and + fees) to reflect the actual value received. - **Providing transaction status** - - Provide the `/transaction` endpoint. The wallet relies on it to complete interactive withdrawals. - - Provide the `/transactions` endpoint. Wallets normally display transaction histories. + - Provide the `/transaction` endpoint. The wallet relies on it to complete interactive withdrawals. + - Provide the `/transactions` endpoint. Wallets normally display transaction histories. ## Deposit @@ -402,20 +412,20 @@ The fields below should be placed in the request body using the `multipart/form- Request Parameters: -| Name | Type | Description | -| ----------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `asset_code` | string | The code of the stellar asset the user wants to receive for their deposit with the anchor. The value passed must match one of the codes listed in the [/info](#info) response's deposit object. When `quote_id` is specified, `asset_code` must match the quote's `buy_asset` asset code. | -| `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to receive for their deposit with the anchor. If asset_issuer is not provided, the anchor should use the asset issued by themselves as described in their TOML file. When `quote_id` is specified, this parameter must match the quote's `buy_asset` asset code or be omitted. | -| `sending_asset` | string in [Asset Identification Format] | (optional) The asset user wants to send. Note, that this is the asset user initially holds (off-chain or fiat asset).If this is not provided, it will be collected in the interactive flow. When `quote_id` is specified, this parameter must match the quote's `sell_asset` asset code or be omitted. | -| `amount` | number | (optional) Amount of asset requested to deposit. If this is not provided it will be collected in the interactive flow. When `qoute_id` is specified, this parameter must match the quote's `quote.sell_amount` or be omitted. | -| `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 must respect the conversion rate agreed in that quote. When `quote_id` is set, `asset_code`, `sending_asset` and `amount` are mandatory. In case of a conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | -| `account` | `G...` or `M...` string | (optional) The Stellar or muxed account the client wants to use as the destination of the payment sent by the anchor. Defaults to the account authenticated via SEP-10 if not specified. | -| `memo_type` | string | (optional) Type of memo that anchor should attach to the Stellar 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 can be different than the value 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`. | -| `wallet_name` | string | (optional) In communications / pages about the deposit, anchor should display the wallet name to the user to explain where funds are going. | -| `wallet_url` | string | (optional) Anchor should link to this when notifying the user that the transaction has completed. | -| `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646] which means it can also accept locale in the format `en-US`. `error` fields in the response, as well as the interactive flow UI and any other user-facing strings returned for this transaction should be in this language. | -| `claimable_balance_supported` | boolean | (optional) True if the client supports receiving deposit transactions as a claimable balance, false otherwise. | +| Name | Type | Description | +|-------------------------------|-----------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `asset_code` | string | The code of the stellar asset the user wants to receive for their deposit with the anchor. The value passed must match one of the codes listed in the [/info](#info) response's deposit object. When `quote_id` is specified, `asset_code` must match the quote's `buy_asset` asset code. | +| `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to receive for their deposit with the anchor. If asset_issuer is not provided, the anchor should use the asset issued by themselves as described in their TOML file. When `quote_id` is specified, this parameter must match the quote's `buy_asset` asset code or be omitted. | +| `sending_asset` | string in [Asset Identification Format] | (optional) The asset user wants to send. Note, that this is the asset user initially holds (off-chain or fiat asset).If this is not provided, it will be collected in the interactive flow. When `quote_id` is specified, this parameter must match the quote's `sell_asset` asset code or be omitted. | +| `amount` | number | (optional) Amount of asset requested to deposit. If this is not provided it will be collected in the interactive flow. When `qoute_id` is specified, this parameter must match the quote's `quote.sell_amount` or be omitted. | +| `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 must respect the conversion rate agreed in that quote. When `quote_id` is set, `asset_code`, `destination_asset` and `amount` must be validated by the anchor, if present. In case of a conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | +| `account` | `G...` or `M...` string | (optional) The Stellar or muxed account the client wants to use as the destination of the payment sent by the anchor. Defaults to the account authenticated via SEP-10 if not specified. | +| `memo_type` | string | (optional) Type of memo that anchor should attach to the Stellar 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 can be different than the value 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`. | +| `wallet_name` | string | (optional) In communications / pages about the deposit, anchor should display the wallet name to the user to explain where funds are going. | +| `wallet_url` | string | (optional) Anchor should link to this when notifying the user that the transaction has completed. | +| `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646] which means it can also accept locale in the format `en-US`. `error` fields in the response, as well as the interactive flow UI and any other user-facing strings returned for this transaction should be in this language. | +| `claimable_balance_supported` | boolean | (optional) True if the client supports receiving deposit transactions as a claimable balance, false otherwise. | Additionally, any [SEP-9](sep-0009.md) parameters may be passed as well to make the onboarding experience simpler. @@ -543,12 +553,12 @@ Stellar account does not have a trustline. ```javascript const transaction = new TransactionBuilder(account, { - fee: 100, - networkPassphrase: this.network_passphrase, + fee: 100, + networkPassphrase: this.network_passphrase, }) - .addOperation(Operation.claimClaimableBalance({ balanceId })) - .setTimeout(0) - .build(); + .addOperation(Operation.claimClaimableBalance({balanceId})) + .setTimeout(0) + .build(); transaction.sign(keypair); const result = await this.server.submitTransaction(transaction); ``` @@ -603,7 +613,7 @@ The fields below should be placed in the request body using the `multipart/form- Request parameters: | Name | Type | Description | -| ------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +|---------------------|-----------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `asset_code` | string | Code of the asset the user wants to withdraw. The value passed must match one of the codes listed in the [/info](#info) response's withdraw object. When `quote_id` is specified, `asset_code` must match the quote's `sell_asset` asset code. | | `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to withdraw with the anchor. If `asset_issuer` is not provided, the anchor should use the asset issued by themselves as described in their TOML file. When `quote_id` is specified, `asset_issuer` must match the quote's `buy_asset` asset issuer or be omitted. | | `destination_asset` | string in [Asset Identification Format] | (optional) The asset user wants to receive. It's an off-chain or fiat asset. If this is not provided, it will be collected in the interactive flow. When `quote_id` is specified, this parameter must match the quote's `buy_asset` asset code or be omitted. | @@ -662,7 +672,7 @@ withdrawals, the wallet must get information on where to send the withdrawal pay The response body must be a JSON object with the following fields: | Name | Type | Description | -| ------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +|--------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `type` | string | Always set to `interactive_customer_info_needed`. | | `url` | string | URL hosted by the anchor. The wallet should show this URL to the user as a popup. | | `id` | string | The anchor's internal ID for this deposit / withdrawal request. The wallet will use this ID to query the [`/transaction`](#single-historical-transaction) endpoint to check status of the request. | @@ -684,7 +694,7 @@ Before the wallet sends the user to the `url` field received from the anchor, it 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). | @@ -741,20 +751,20 @@ 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 - }, - }), + 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 + }, + }), }); ``` @@ -866,7 +876,7 @@ GET TRANSFER_SERVER_SEP0024/info Request parameters: | Name | Type | Description | -| ------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +|--------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `lang` | string | (optional) Defaults to `en` if not specified or the if the specified language is not supported. Language code specified using [RFC 4646] which means it can also accept locale in the format `en-US`. `description` fields in the response should be in this language. | ### Response @@ -954,7 +964,7 @@ object or specific feature is not present in the response, the default value des information enables wallets to adjust their behavior based on the feature set supported by the anchor. | Name | Default | Description | -| ----------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +|-------------------------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `account_creation` | `true` | Whether or not the anchor supports creating accounts for users requesting deposits. | | `claimable_balances` | `false` | Whether or not the anchor supports sending deposit funds as claimable balances. This is relevant for users of Stellar accounts without a trustline to the requested asset. | | `indicative_quotes_supported` | `false` | Whether or not the anchor supports indicative quotes provided by `SEP-38 GET /price` and `SEP-38 GET /prices` API. | @@ -985,7 +995,7 @@ GET TRANSFER_SERVER_SEP0024/fee Request parameters: | Name | Type | Description | -| ------------ | ------ | ---------------------------------------------------------------------------------- | +|--------------|--------|------------------------------------------------------------------------------------| | `operation` | string | Kind of operation (`deposit` or `withdraw`). | | `type` | string | (optional) Type of deposit or withdrawal (`SEPA`, `bank_account`, `cash`, etc...). | | `asset_code` | string | Asset code. | @@ -1000,7 +1010,7 @@ GET https://api.example.com/fee?operation=withdraw&asset_code=ETH&amount=0.5 On success the endpoint should return `200 OK` HTTP status code and a JSON object with the following fields: | Name | Type | Description | -| ----- | ----- | -------------------------------------------------------------------------------------------------------------------------------- | +|-------|-------|----------------------------------------------------------------------------------------------------------------------------------| | `fee` | float | The total fee (in units of the asset involved) that would be charged to deposit/withdraw the specified `amount` of `asset_code`. | Example response: @@ -1038,7 +1048,7 @@ GET TRANSFER_SERVER_SEP0024/transactions Request parameters: | Name | Type | Description | -| --------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +|-----------------|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `asset_code` | string | The code of the asset of interest. E.g. BTC, ETH, USD, INR, etc. | | `no_older_than` | UTC ISO 8601 string | (optional) The response should contain transactions starting on or after this date & time. | | `limit` | int | (optional) The response should contain at most `limit` transactions. | @@ -1049,7 +1059,7 @@ Request parameters: On success the endpoint should return `200 OK` HTTP status code and a JSON object with the following fields: | Name | Type | Description | -| -------------- | ----- | --------------------------------------------------------------------------------- | +|----------------|-------|-----------------------------------------------------------------------------------| | `transactions` | array | List of transactions as requested by the client, sorted in time-descending order. | Each object in the `transactions` array should have the following fields: @@ -1057,7 +1067,7 @@ Each object in the `transactions` array should have the following fields: ### Shared fields for both deposits and withdrawals | Name | Type | Description | -| ------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +|---------------------------|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `id` | string | Unique, anchor-generated id for the deposit/withdrawal. | | `kind` | string | `deposit` or `withdrawal`. | | `status` | string | Processing status of deposit/withdrawal. | @@ -1083,7 +1093,7 @@ Each object in the `transactions` array should have the following fields: ### Fields for deposit transactions | Name | Type | Description | -| ---------------------- | ------ | ------------------------------------------------------------------------------------------- | +|------------------------|--------|---------------------------------------------------------------------------------------------| | `deposit_memo` | string | (optional) This is the memo (if any) used to transfer the asset to the `to` Stellar address | | `deposit_memo_type` | string | (optional) Type for the `deposit_memo`. | | `from` | string | Sent from address, perhaps BTC, IBAN, or bank account. | @@ -1093,7 +1103,7 @@ Each object in the `transactions` array should have the following fields: ### Fields for withdraw transactions | Name | Type | Description | -| ------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +|---------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `withdraw_anchor_account` | string | If this is a withdrawal, this is the anchor's Stellar account that the user transferred (or will transfer) their issued asset to. | | `withdraw_memo` | string | Memo used when the user transferred to `withdraw_anchor_account`. Assigned null if the withdraw is not ready to receive payment, for example if KYC is not completed. | | `withdraw_memo_type` | string | Memo type for `withdraw_memo`. | @@ -1133,7 +1143,7 @@ Each object in the `transactions` array should have the following fields: ### Refunds Object Schema | Name | Type | Description | -| ----------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +|-------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `amount_refunded` | string | The total amount refunded to the user, in units of `amount_in_asset`. If a full refund was issued, this amount should match `amount_in`. | | `amount_fee` | string | The total amount charged in fees for processing all refund payments, in units of `amount_in_asset`. The sum of all `fee` values in the `payments` object list should equal this value. | | `payments` | array | A list of objects containing information on the individual payments made back to the user as refunds. The schema for these objects is defined in the section below. | @@ -1141,7 +1151,7 @@ Each object in the `transactions` array should have the following fields: #### Refund Payment Object Schema | Name | Type | Description | -| --------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +|-----------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `id` | string | The payment ID that can be used to identify the refund payment. This is either a Stellar transaction hash or an off-chain payment identifier, such as a reference number provided to the user when the refund was initiated. This id is not guaranteed to be unique. | | `id_type` | string | `stellar` or `external`. | | `amount` | string | The amount sent back to the user for the payment identified by `id`, in units of `amount_in_asset`. | @@ -1291,7 +1301,7 @@ GET TRANSFER_SERVER_SEP0024/transaction Request parameters: | Name | Type | Description | -| ------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +|---------------------------|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `id` | string | (optional) The id of the transaction. | | `stellar_transaction_id` | (optional) string | The stellar transaction id of the transaction. | | `external_transaction_id` | (optional) string | The external transaction id of the transaction. | @@ -1302,7 +1312,7 @@ One of `id`, `stellar_transaction_id` or `external_transaction_id` is required. On success the endpoint should return `200 OK` HTTP status code and a JSON object with the following fields: | Name | Type | Description | -| ------------- | ------ | ------------------------------------------------- | +|---------------|--------|---------------------------------------------------| | `transaction` | object | The transaction that was requested by the client. | The `transaction` object should be of the same form as the objects returned by the @@ -1362,7 +1372,7 @@ There is a small set of changes when upgrading from SEP-6 to SEP-24. 1. `Transaction` properties `more_info_url, amount_in, amount_out, amount_fee, and stellar_transaction_id` are now non-optional. 1. It is now recommended to use a short-lived, one-time JWT in the context of the interactive webapp. - - Anchors should not accept JWT's that have expired or been used before. + - Anchors should not accept JWT's that have expired or been used before. 1. `/transactions` endpoint no longer accepts an `account` query. The account is pulled from the JWT. ## Implementations @@ -1405,5 +1415,7 @@ There is a small set of changes when upgrading from SEP-6 to SEP-24. ([#1128](https://github.com/stellar/stellar-protocol/pull/1128)) [RFC 4646]: https://www.rfc-editor.org/rfc/rfc4646 + [SEP-38]: sep-0038.md + [Asset Identification Format]: sep-0038.md#asset-identification-format. From f8e6dbfc4c475bcabc130fba033487bbdd012098 Mon Sep 17 00:00:00 2001 From: Gleb Date: Tue, 20 Jun 2023 17:00:30 -0700 Subject: [PATCH 13/17] Fix merge conflict --- ecosystem/sep-0024.md | 261 +++++++++++++++++++----------------------- 1 file changed, 120 insertions(+), 141 deletions(-) diff --git a/ecosystem/sep-0024.md b/ecosystem/sep-0024.md index 70b9c928e..e947da3b8 100644 --- a/ecosystem/sep-0024.md +++ b/ecosystem/sep-0024.md @@ -230,33 +230,33 @@ It is the wallet's responsibility to: - Check that callback request has `Signature` or `X-Stellar-Signature` (deprecated) header - Parse the header and extract: - - Key `t`: **timestamp** - - Key `s`: **base64 signature** + - Key `t`: **timestamp** + - Key `s`: **base64 signature** - Verify the request freshness: _current timestamp_ - **timestamp** < few seconds (1-2 minute(s) max) - Extract the **body** of the request - Base64 decode the **base64 signature** to get the **signature** - Prepare the payload to verify the signature: - - The **timestamp** (as a string) - - The character `.` - - The wallet host to send the callback request to - - The character `.` - - The **body** + - The **timestamp** (as a string) + - The character `.` + - The wallet host to send the callback request to + - The character `.` + - The **body** - Verify the signature using the correct `SIGNING_KEY` ### COMPUTE signature - Prepare the callback - Prepare the payload to sign: - - Current timestamp (as a string) - - The character `.` - - The wallet host to send the callback request to - - The character `.` - - The callback request body + - Current timestamp (as a string) + - The character `.` + - The wallet host to send the callback request to + - The character `.` + - The callback request body - Sign the payload `..` using the Anchor private key - Base64 encode the signature - Build the `Signature` or `X-Stellar-Signature` (deprecated) header: - - `Signature: t=, s=` - - `X-Stellar-Signature: t=, s=` + - `Signature: t=, s=` + - `X-Stellar-Signature: t=, s=` ## Content Type @@ -291,37 +291,35 @@ banking rails so counterparties can run through the flow without a need to colla display the asset's quote (if possible) as well as information such as the address of the anchor and description of the asset from the `stellar.toml` file. - **If [SEP-38] quote API is supported by the anchor** - - Fetch the asset's exchange rate at the market price using [`SEP-38 GET /price`](sep-0038.md#get-price) API. - - For the firm quote, use [`SEP-38 POST /quote`](sep-0038.md#post-quote) API and show the quote and expiration time - to - the user. + - Fetch the asset's exchange rate at the market price using [`SEP-38 GET /price`](sep-0038.md#get-price) API. + - For the firm quote, use [`SEP-38 POST /quote`](sep-0038.md#post-quote) API and show the quote and expiration time to + the user. - **Authentication** - - Perform [authentication](#authentication) via SEP-10 before hitting those endpoints + - Perform [authentication](#authentication) via SEP-10 before hitting those endpoints - **Make a request to `/transactions/deposit/interactive` or `/transactions/withdraw/interactive`.** - - This will respond with the interactive url needed to proceed with KYC and deposit/withdraw details. + - This will respond with the interactive url needed to proceed with KYC and deposit/withdraw details. - **For `/transactions/deposit/interactive` and `/transactions/withdraw/interactive`** - - Optionally attach any fields from [SEP-9](sep-0009.md) as POST parameters in the `/deposit` or `/withdraw` - endpoints - in order to let the anchor pre-fill them in the interactive flow UI. This is optional, but can create a much nicer - user experience. `email_address`, `first_name` and `last_name` are good examples of fields to help pre-fill the - anchors website. - - Optionally attach [SEP-38] quote id, in order to the anchor to use the quote previously shown to the user. + - Optionally attach any fields from [SEP-9](sep-0009.md) as POST parameters in the `/deposit` or `/withdraw` endpoints + in order to let the anchor pre-fill them in the interactive flow UI. This is optional, but can create a much nicer + user experience. `email_address`, `first_name` and `last_name` are good examples of fields to help pre-fill the + anchors website. + - Optionally attach [SEP-38] quote id, in order to the anchor to use the quote previously shown to the user. - **For `/transactions/deposit/interactive`** - - Handle the interactive flow, handle it as [described in detail](#interactive-customer-information-needed). - - Handle the [special cases](#special-cases), they're relatively common. + - Handle the interactive flow, handle it as [described in detail](#interactive-customer-information-needed). + - Handle the [special cases](#special-cases), they're relatively common. - **For `/transactions/withdraw/interactive`** - - Handle the interactive flow, handle it as [described in detail](#interactive-customer-information-needed). - - When the transaction status becomes `pending_user_transfer_start` send the required payment as described in the - interactive webapp callback or the `/transaction` endpoint. This can be a `payment` or `path_payment` operation. - Sending payments via `account_merge` or `create_account` is not supported at this time. - - Some wallets might exchange currencies only once they're ready to send the withdrawal payment, so exchange rate - fluctuations might require withdrawal values to slightly vary from the originally provided `amount`. Anchors are - instructed to accept a variation of ±10% between the informed `amount` and the actual value sent to the anchor's - Stellar account. The withdrawn amount will be adjusted accordingly. + - Handle the interactive flow, handle it as [described in detail](#interactive-customer-information-needed). + - When the transaction status becomes `pending_user_transfer_start` send the required payment as described in the + interactive webapp callback or the `/transaction` endpoint. This can be a `payment` or `path_payment` operation. + Sending payments via `account_merge` or `create_account` is not supported at this time. + - Some wallets might exchange currencies only once they're ready to send the withdrawal payment, so exchange rate + fluctuations might require withdrawal values to slightly vary from the originally provided `amount`. Anchors are + instructed to accept a variation of ±10% between the informed `amount` and the actual value sent to the anchor's + Stellar account. The withdrawn amount will be adjusted accordingly. - **Transaction history** - - Provide a list of historical and current deposits and withdrawals at the [`/transactions`](#transactions) endpoint - for wallets to show a view of all of a single anchors transactions in a list. - - Provide status or instructions for a specific deposit or withdraw at the [`/transaction`](#transaction) endpoint + - Provide a list of historical and current deposits and withdrawals at the [`/transactions`](#transactions) endpoint + for wallets to show a view of all of a single anchors transactions in a list. + - Provide status or instructions for a specific deposit or withdraw at the [`/transaction`](#transaction) endpoint ### Basic Anchor Implementation @@ -329,57 +327,49 @@ banking rails so counterparties can run through the flow without a need to colla - Implement [SEP-38] to offer better user experience. Wallet would be able to show rates and fees your anchor provides early in the process. (Before the user initiates a transaction via interactive UI) - **For both deposit and withdrawal**: - - To start an interactive flow, provide - the [Customer info needed response](#interactive-customer-information-needed). - - Some wallets may include other fields indicated in [SEP-9](sep-0009.md) as POST parameters added to the - `/transactions/deposit/interactive` or `/transactions/withdraw/interactive` endpoints. These can be stored and - used - to pre-populate fields in the interactive flow. This is optional for the wallet to provide and optional for - anchors - to respect, but it does create a much nicer user experience. - - Some wallets may include `quote_id` fetched from the [`SEP-38 POST /quote`](sep-0038.md#post-quote) API. If - provided, your implementation must respect the agreed quote. - - Include the `id` field in your response to `/transactions/deposit/interactive` and - `/transactions/withdraw/interactive` so the wallet can check up on the status of the transaction if it wants. - - Also include the `id` field in the popup URL you provide to the wallet. This allows you to keep track of the - transaction when the user visits the URL. - - We recommend you use [SEP-10](#authentication) for authentication in the interactive flow and do not separately - prompt for password to achieve a good user experience (although asking for MFA when confirming a transaction or - requiring email confirmation is reasonable). Putting a one time use token or quickly expiring JWT in the URL - returned to the client is a good way to keep continuity between authenticated API calls and fresh interactive flow - requests. - - Test your interactive flows on mobile. They should be easy to use on all devices: make them responsive, handle - auto-fill well, and do smart keyboard management on mobile devices. + - To start an interactive flow, provide the [Customer info needed response](#interactive-customer-information-needed). + - Some wallets may include other fields indicated in [SEP-9](sep-0009.md) as POST parameters added to the + `/transactions/deposit/interactive` or `/transactions/withdraw/interactive` endpoints. These can be stored and used + to pre-populate fields in the interactive flow. This is optional for the wallet to provide and optional for anchors + to respect, but it does create a much nicer user experience. + - Some wallets may include `quote_id` fetched from the [`SEP-38 POST /quote`](sep-0038.md#post-quote) API. If + provided, your implementation must respect the agreed quote. + - Include the `id` field in your response to `/transactions/deposit/interactive` and + `/transactions/withdraw/interactive` so the wallet can check up on the status of the transaction if it wants. + - Also include the `id` field in the popup URL you provide to the wallet. This allows you to keep track of the + transaction when the user visits the URL. + - We recommend you use [SEP-10](#authentication) for authentication in the interactive flow and do not separately + prompt for password to achieve a good user experience (although asking for MFA when confirming a transaction or + requiring email confirmation is reasonable). Putting a one time use token or quickly expiring JWT in the URL + returned to the client is a good way to keep continuity between authenticated API calls and fresh interactive flow + requests. + - Test your interactive flows on mobile. They should be easy to use on all devices: make them responsive, handle + auto-fill well, and do smart keyboard management on mobile devices. - **Interactive deposit** - - Your interactive deposit popup will do everything needed to initiate the deposit without the user needing to - interact with the wallet further. It should either directly initiate the deposit, or handle displaying information - (such as reference number or bank account number) that the user will need to complete their deposit. + - Your interactive deposit popup will do everything needed to initiate the deposit without the user needing to + interact with the wallet further. It should either directly initiate the deposit, or handle displaying information + (such as reference number or bank account number) that the user will need to complete their deposit. - **Interactive withdrawal** - - Your withdrawal flow will have to pass control back to the user's wallet, so it can initiate the withdrawal with a - Stellar payment to your withdrawal address. You'll need to communicate the withdrawal address, amount and status - to - the wallet using the [`callback` parameter](#adding-parameters-to-the-url), and also by making it available on - your - `/transaction` endpoint. See [details](#guidance-for-wallets-completing-an-interactive-withdrawal) for polling by - the wallet. - - In order to fulfill a withdrawal, a wallet must make a payment to the Stellar address that the anchor provides. It - is the anchor's job to watch for Stellar payments to the given address and make the external transaction as soon - as - they're detected. Anchors must listen for `payment` and `path_payment` - [operations](https://www.stellar.org/developers/horizon/reference/endpoints/payments-all.html). Most Stellar SDKs - already support listening to all payment forms via streaming. - - When the anchor detects the fulfilling payment from the wallet and expects the customer to pick up the withdrawn - amount of cash, the transaction status must be changed to `pending_user_transfer_complete` to indicate the - withdrawn - amount is ready for pick-up. - - Some wallets might exchange currencies only once they're ready to send the withdrawal payment, so there might be - slight fluctuations of value between the informed withdrawal `amount` and the actual transferred amount. It is - recommended for anchors to accept an amount fluctuation of up to ±10%, and adjust the amount to be transferred ( - and - fees) to reflect the actual value received. + - Your withdrawal flow will have to pass control back to the user's wallet, so it can initiate the withdrawal with a + Stellar payment to your withdrawal address. You'll need to communicate the withdrawal address, amount and status to + the wallet using the [`callback` parameter](#adding-parameters-to-the-url), and also by making it available on your + `/transaction` endpoint. See [details](#guidance-for-wallets-completing-an-interactive-withdrawal) for polling by + the wallet. + - In order to fulfill a withdrawal, a wallet must make a payment to the Stellar address that the anchor provides. It + is the anchor's job to watch for Stellar payments to the given address and make the external transaction as soon as + they're detected. Anchors must listen for `payment` and `path_payment` + [operations](https://www.stellar.org/developers/horizon/reference/endpoints/payments-all.html). Most Stellar SDKs + already support listening to all payment forms via streaming. + - When the anchor detects the fulfilling payment from the wallet and expects the customer to pick up the withdrawn + amount of cash, the transaction status must be changed to `pending_user_transfer_complete` to indicate the withdrawn + amount is ready for pick-up. + - Some wallets might exchange currencies only once they're ready to send the withdrawal payment, so there might be + slight fluctuations of value between the informed withdrawal `amount` and the actual transferred amount. It is + recommended for anchors to accept an amount fluctuation of up to ±10%, and adjust the amount to be transferred ( and + fees) to reflect the actual value received. - **Providing transaction status** - - Provide the `/transaction` endpoint. The wallet relies on it to complete interactive withdrawals. - - Provide the `/transactions` endpoint. Wallets normally display transaction histories. + - Provide the `/transaction` endpoint. The wallet relies on it to complete interactive withdrawals. + - Provide the `/transactions` endpoint. Wallets normally display transaction histories. ## Deposit @@ -413,9 +403,9 @@ The fields below should be placed in the request body using the `multipart/form- Request Parameters: | Name | Type | Description | -|-------------------------------|-----------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| ----------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `asset_code` | string | The code of the stellar asset the user wants to receive for their deposit with the anchor. The value passed must match one of the codes listed in the [/info](#info) response's deposit object. When `quote_id` is specified, `asset_code` must match the quote's `buy_asset` asset code. | -| `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to receive for their deposit with the anchor. If asset_issuer is not provided, the anchor should use the asset issued by themselves as described in their TOML file. When `quote_id` is specified, this parameter must match the quote's `buy_asset` asset code or be omitted. | +| `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to receive for their deposit with the anchor. If asset_issuer is not provided, the anchor should use the asset issued by themselves as described in their TOML file. If `native` is specified as the `asset_code`, `asset_issuer` must be not be set. When `quote_id` is specified, this parameter must match the quote's `buy_asset` asset code or be omitted. | | `sending_asset` | string in [Asset Identification Format] | (optional) The asset user wants to send. Note, that this is the asset user initially holds (off-chain or fiat asset).If this is not provided, it will be collected in the interactive flow. When `quote_id` is specified, this parameter must match the quote's `sell_asset` asset code or be omitted. | | `amount` | number | (optional) Amount of asset requested to deposit. If this is not provided it will be collected in the interactive flow. When `qoute_id` is specified, this parameter must match the quote's `quote.sell_amount` or be omitted. | | `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 must respect the conversion rate agreed in that quote. When `quote_id` is set, `asset_code`, `destination_asset` and `amount` must be validated by the anchor, if present. In case of a conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | @@ -426,18 +416,6 @@ Request Parameters: | `wallet_url` | string | (optional) Anchor should link to this when notifying the user that the transaction has completed. | | `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646] which means it can also accept locale in the format `en-US`. `error` fields in the response, as well as the interactive flow UI and any other user-facing strings returned for this transaction should be in this language. | | `claimable_balance_supported` | boolean | (optional) True if the client supports receiving deposit transactions as a claimable balance, false otherwise. | -| Name | Type | Description | -| ----------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `asset_code` | string | The code of the stellar asset the user wants to receive for their deposit with the anchor. The value passed must match one of the codes listed in the [/info](#info) response's deposit object. `native` is a special `asset_code` that represents the native XLM token. | -| `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to receive for their deposit with the anchor. If asset_issuer is not provided, the anchor should use the asset issued by themselves as described in their TOML file. If `native` is specified as the `asset_code`, `asset_issuer` must be not be set. | -| `amount` | number | (optional) Amount of asset requested to deposit. If this is not provided it will be collected in the interactive flow. | -| `account` | `G...` or `M...` string | (optional) The Stellar or muxed account the client wants to use as the destination of the payment sent by the anchor. Defaults to the account authenticated via SEP-10 if not specified. | -| `memo_type` | string | (optional) Type of memo that anchor should attach to the Stellar 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 can be different than the value 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`. | -| `wallet_name` | string | (optional) In communications / pages about the deposit, anchor should display the wallet name to the user to explain where funds are going. | -| `wallet_url` | string | (optional) Anchor should link to this when notifying the user that the transaction has completed. | -| `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646] which means it can also accept locale in the format `en-US`. `error` fields in the response, as well as the interactive flow UI and any other user-facing strings returned for this transaction should be in this language. | -| `claimable_balance_supported` | boolean | (optional) True if the client supports receiving deposit transactions as a claimable balance, false otherwise. | Additionally, any [SEP-9](sep-0009.md) parameters may be passed as well to make the onboarding experience simpler. @@ -565,12 +543,12 @@ Stellar account does not have a trustline. ```javascript const transaction = new TransactionBuilder(account, { - fee: 100, - networkPassphrase: this.network_passphrase, + fee: 100, + networkPassphrase: this.network_passphrase, }) - .addOperation(Operation.claimClaimableBalance({balanceId})) - .setTimeout(0) - .build(); + .addOperation(Operation.claimClaimableBalance({ balanceId })) + .setTimeout(0) + .build(); transaction.sign(keypair); const result = await this.server.submitTransaction(transaction); ``` @@ -625,9 +603,9 @@ The fields below should be placed in the request body using the `multipart/form- Request parameters: | Name | Type | Description | -|---------------------|-----------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| ------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `asset_code` | string | Code of the asset the user wants to withdraw. The value passed must match one of the codes listed in the [/info](#info) response's withdraw object. When `quote_id` is specified, `asset_code` must match the quote's `sell_asset` asset code. `native` is a special `asset_code` that represents the native XLM token. | -| `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to withdraw with the anchor. If `asset_issuer` is not provided, the anchor should use the asset issued by themselves as described in their TOML file. If `native` is specified as the `asset_code`, `asset_issuer` must be not be set. When `quote_id` is specified, `asset_issuer` must match the quote's `buy_asset` asset issuer or be omitted. | +| `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to withdraw with the anchor. If `asset_issuer` is not provided, the anchor should use the asset issued by themselves as described in their TOML file. If `native` is specified as the `asset_code`, `asset_issuer` must be not be set. When `quote_id` is specified, `asset_issuer` must match the quote's `buy_asset` asset issuer or be omitted. | | `destination_asset` | string in [Asset Identification Format] | (optional) The asset user wants to receive. It's an off-chain or fiat asset. If this is not provided, it will be collected in the interactive flow. When `quote_id` is specified, this parameter must match the quote's `buy_asset` asset code or be omitted. | | `amount` | number | (optional) Amount of asset requested to withdraw. If this is not provided it will be collected in the interactive flow. When `qoute_id` is specified, this parameter must match the quote's `quote.sell_amount` or be omitted. | | `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 must respect the conversion rate agreed in that quote. When `quote_id` is set, `asset_code`, `destination_asset` and `amount` must be validated by the anchor, if present. In case of a conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | @@ -684,7 +662,7 @@ withdrawals, the wallet must get information on where to send the withdrawal pay The response body must be a JSON object with the following fields: | Name | Type | Description | -|--------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| ------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | string | Always set to `interactive_customer_info_needed`. | | `url` | string | URL hosted by the anchor. The wallet should show this URL to the user as a popup. | | `id` | string | The anchor's internal ID for this deposit / withdrawal request. The wallet will use this ID to query the [`/transaction`](#single-historical-transaction) endpoint to check status of the request. | @@ -706,7 +684,7 @@ Before the wallet sends the user to the `url` field received from the anchor, it 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). | @@ -763,20 +741,20 @@ 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 - }, - }), + 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 + }, + }), }); ``` @@ -878,7 +856,8 @@ wallet. For example: ## Info Allows an anchor to communicate basic info about what their `TRANSFER_SERVER_SEP0024` supports to wallets and clients. -If an anchor supports the native asset, the `native` asset code with a `null` asset issuer should be included in the response. +If an anchor supports the native asset, the `native` asset code with a `null` asset issuer should be included in the +response. The `native` asset on the [Stellar Public Network][pubnet] is the [lumen (XLM)][lumen]. @@ -894,7 +873,7 @@ GET TRANSFER_SERVER_SEP0024/info Request parameters: | Name | Type | Description | -|--------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| ------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `lang` | string | (optional) Defaults to `en` if not specified or the if the specified language is not supported. Language code specified using [RFC 4646] which means it can also accept locale in the format `en-US`. `description` fields in the response should be in this language. | ### Response @@ -990,7 +969,7 @@ object or specific feature is not present in the response, the default value des information enables wallets to adjust their behavior based on the feature set supported by the anchor. | Name | Default | Description | -|-------------------------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| ----------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account_creation` | `true` | Whether or not the anchor supports creating accounts for users requesting deposits. | | `claimable_balances` | `false` | Whether or not the anchor supports sending deposit funds as claimable balances. This is relevant for users of Stellar accounts without a trustline to the requested asset. | | `indicative_quotes_supported` | `false` | Whether or not the anchor supports indicative quotes provided by `SEP-38 GET /price` and `SEP-38 GET /prices` API. | @@ -1021,7 +1000,7 @@ GET TRANSFER_SERVER_SEP0024/fee Request parameters: | Name | Type | Description | -|--------------|--------|------------------------------------------------------------------------------------| +| ------------ | ------ | ---------------------------------------------------------------------------------- | | `operation` | string | Kind of operation (`deposit` or `withdraw`). | | `type` | string | (optional) Type of deposit or withdrawal (`SEPA`, `bank_account`, `cash`, etc...). | | `asset_code` | string | Asset code. | @@ -1036,7 +1015,7 @@ GET https://api.example.com/fee?operation=withdraw&asset_code=ETH&amount=0.5 On success the endpoint should return `200 OK` HTTP status code and a JSON object with the following fields: | Name | Type | Description | -|-------|-------|----------------------------------------------------------------------------------------------------------------------------------| +| ----- | ----- | -------------------------------------------------------------------------------------------------------------------------------- | | `fee` | float | The total fee (in units of the asset involved) that would be charged to deposit/withdraw the specified `amount` of `asset_code`. | Example response: @@ -1074,7 +1053,7 @@ GET TRANSFER_SERVER_SEP0024/transactions Request parameters: | Name | Type | Description | -|-----------------|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| --------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `asset_code` | string | The code of the asset of interest. E.g. BTC, ETH, USD, INR, native, etc. | | `no_older_than` | UTC ISO 8601 string | (optional) The response should contain transactions starting on or after this date & time. | | `limit` | int | (optional) The response should contain at most `limit` transactions. | @@ -1085,7 +1064,7 @@ Request parameters: On success the endpoint should return `200 OK` HTTP status code and a JSON object with the following fields: | Name | Type | Description | -|----------------|-------|-----------------------------------------------------------------------------------| +| -------------- | ----- | --------------------------------------------------------------------------------- | | `transactions` | array | List of transactions as requested by the client, sorted in time-descending order. | Each object in the `transactions` array should have the following fields: @@ -1093,7 +1072,7 @@ Each object in the `transactions` array should have the following fields: ### Shared fields for both deposits and withdrawals | Name | Type | Description | -|---------------------------|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| ------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | Unique, anchor-generated id for the deposit/withdrawal. | | `kind` | string | `deposit` or `withdrawal`. | | `status` | string | Processing status of deposit/withdrawal. | @@ -1119,7 +1098,7 @@ Each object in the `transactions` array should have the following fields: ### Fields for deposit transactions | Name | Type | Description | -|------------------------|--------|---------------------------------------------------------------------------------------------| +| ---------------------- | ------ | ------------------------------------------------------------------------------------------- | | `deposit_memo` | string | (optional) This is the memo (if any) used to transfer the asset to the `to` Stellar address | | `deposit_memo_type` | string | (optional) Type for the `deposit_memo`. | | `from` | string | Sent from address, perhaps BTC, IBAN, or bank account. | @@ -1129,7 +1108,7 @@ Each object in the `transactions` array should have the following fields: ### Fields for withdraw transactions | Name | Type | Description | -|---------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| ------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `withdraw_anchor_account` | string | If this is a withdrawal, this is the anchor's Stellar account that the user transferred (or will transfer) their asset to. | | `withdraw_memo` | string | Memo used when the user transferred to `withdraw_anchor_account`. Assigned null if the withdraw is not ready to receive payment, for example if KYC is not completed. | | `withdraw_memo_type` | string | Memo type for `withdraw_memo`. | @@ -1169,7 +1148,7 @@ Each object in the `transactions` array should have the following fields: ### Refunds Object Schema | Name | Type | Description | -|-------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| ----------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `amount_refunded` | string | The total amount refunded to the user, in units of `amount_in_asset`. If a full refund was issued, this amount should match `amount_in`. | | `amount_fee` | string | The total amount charged in fees for processing all refund payments, in units of `amount_in_asset`. The sum of all `fee` values in the `payments` object list should equal this value. | | `payments` | array | A list of objects containing information on the individual payments made back to the user as refunds. The schema for these objects is defined in the section below. | @@ -1177,7 +1156,7 @@ Each object in the `transactions` array should have the following fields: #### Refund Payment Object Schema | Name | Type | Description | -|-----------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| --------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | The payment ID that can be used to identify the refund payment. This is either a Stellar transaction hash or an off-chain payment identifier, such as a reference number provided to the user when the refund was initiated. This id is not guaranteed to be unique. | | `id_type` | string | `stellar` or `external`. | | `amount` | string | The amount sent back to the user for the payment identified by `id`, in units of `amount_in_asset`. | @@ -1327,7 +1306,7 @@ GET TRANSFER_SERVER_SEP0024/transaction Request parameters: | Name | Type | Description | -|---------------------------|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| ------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | (optional) The id of the transaction. | | `stellar_transaction_id` | (optional) string | The stellar transaction id of the transaction. | | `external_transaction_id` | (optional) string | The external transaction id of the transaction. | @@ -1338,7 +1317,7 @@ One of `id`, `stellar_transaction_id` or `external_transaction_id` is required. On success the endpoint should return `200 OK` HTTP status code and a JSON object with the following fields: | Name | Type | Description | -|---------------|--------|---------------------------------------------------| +| ------------- | ------ | ------------------------------------------------- | | `transaction` | object | The transaction that was requested by the client. | The `transaction` object should be of the same form as the objects returned by the @@ -1398,7 +1377,9 @@ There is a small set of changes when upgrading from SEP-6 to SEP-24. 1. `Transaction` properties `more_info_url, amount_in, amount_out, amount_fee, and stellar_transaction_id` are now non-optional. 1. It is now recommended to use a short-lived, one-time JWT in the context of the interactive webapp. - - Anchors should not accept JWT's that have expired or been used before. + +- Anchors should not accept JWT's that have expired or been used before. + 1. `/transactions` endpoint no longer accepts an `account` query. The account is pulled from the JWT. ## Implementations @@ -1442,7 +1423,5 @@ There is a small set of changes when upgrading from SEP-6 to SEP-24. ([#1128](https://github.com/stellar/stellar-protocol/pull/1128)) [RFC 4646]: https://www.rfc-editor.org/rfc/rfc4646 - [SEP-38]: sep-0038.md - [Asset Identification Format]: sep-0038.md#asset-identification-format. From db77d80026957ea98ff67c9bf0d6911533f2bb63 Mon Sep 17 00:00:00 2001 From: Gleb Date: Mon, 17 Jul 2023 14:14:55 -0700 Subject: [PATCH 14/17] Address PR comments --- ecosystem/sep-0024.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ecosystem/sep-0024.md b/ecosystem/sep-0024.md index efaf84ebd..56b35dde6 100644 --- a/ecosystem/sep-0024.md +++ b/ecosystem/sep-0024.md @@ -403,12 +403,12 @@ The fields below should be placed in the request body using the `multipart/form- Request Parameters: | Name | Type | Description | -| ----------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +|-------------------------------| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `asset_code` | string | The code of the stellar asset the user wants to receive for their deposit with the anchor. The value passed must match one of the codes listed in the [/info](#info) response's deposit object. When `quote_id` is specified, `asset_code` must match the quote's `buy_asset` asset code. | | `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to receive for their deposit with the anchor. If asset_issuer is not provided, the anchor should use the asset issued by themselves as described in their TOML file. If `native` is specified as the `asset_code`, `asset_issuer` must be not be set. When `quote_id` is specified, this parameter must match the quote's `buy_asset` asset code or be omitted. | -| `sending_asset` | string in [Asset Identification Format] | (optional) The asset user wants to send. Note, that this is the asset user initially holds (off-chain or fiat asset).If this is not provided, it will be collected in the interactive flow. When `quote_id` is specified, this parameter must match the quote's `sell_asset` asset code or be omitted. | +| `source_asset` | string in [Asset Identification Format] | (optional) The asset user wants to send. Note, that this is the asset user initially holds (off-chain or fiat asset).If this is not provided, it will be collected in the interactive flow. When `quote_id` is specified, this parameter must match the quote's `sell_asset` asset code or be omitted. | | `amount` | number | (optional) Amount of asset requested to deposit. If this is not provided it will be collected in the interactive flow. When `qoute_id` is specified, this parameter must match the quote's `quote.sell_amount` or be omitted. | -| `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 must respect the conversion rate agreed in that quote. When `quote_id` is set, `asset_code`, `destination_asset` and `amount` must be validated by the anchor, if present. In case of a conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | +| `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 must respect the conversion rate agreed in that quote. When `quote_id` is set, `asset_code`, `source_asset` and `amount` must be validated by the anchor, if present. In case of a conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | | `account` | `G...` or `M...` string | (optional) The Stellar or muxed account the client wants to use as the destination of the payment sent by the anchor. Defaults to the account authenticated via SEP-10 if not specified. | | `memo_type` | string | (optional) Type of memo that anchor should attach to the Stellar 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 can be different than the value 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`. | From af3e9c7ab3041818e371b33cc7f488ab3ce97848 Mon Sep 17 00:00:00 2001 From: Gleb Date: Mon, 17 Jul 2023 14:22:00 -0700 Subject: [PATCH 15/17] Remove quote support flags --- ecosystem/sep-0024.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/ecosystem/sep-0024.md b/ecosystem/sep-0024.md index 56b35dde6..120698ef9 100644 --- a/ecosystem/sep-0024.md +++ b/ecosystem/sep-0024.md @@ -123,8 +123,6 @@ endpoints. Market rate conversions executed in this way do not provide a guarant asset. Here is how this kind of conversion should happen in deposits and withdrawals for an asset pair like `BRL <> USDC`: -Anchors offer indicative quote support via enabling `indicative_quotes_supported` feature flag. - #### Deposit: Considering the user will be making a bank deposit of fiat `BRL` in exchange for `USDC` in the Stellar network: @@ -153,8 +151,6 @@ With firm quotes, users are guaranteed an asset price they will pay if they subm payment before the quote expiration. Here is how the conversion should happen in deposits and withdrawals for an asset pair like `USDC <> BRL`: -Anchors enable firm quotes support with `firm_quotes_supported` feature flag. - #### Deposit: Considering the user will be making a bank deposit of fiat `BRL` in exchange for `USDC` in the Stellar network: @@ -927,8 +923,6 @@ The response should be a JSON object like: "features": { "account_creation": true, "claimable_balances": true, - "indicative_quotes_supported": true, - "firm_quotes_supported": true } } ``` @@ -977,8 +971,6 @@ information enables wallets to adjust their behavior based on the feature set su | ----------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account_creation` | `true` | Whether or not the anchor supports creating accounts for users requesting deposits. | | `claimable_balances` | `false` | Whether or not the anchor supports sending deposit funds as claimable balances. This is relevant for users of Stellar accounts without a trustline to the requested asset. | -| `indicative_quotes_supported` | `false` | Whether or not the anchor supports indicative quotes provided by `SEP-38 GET /price` and `SEP-38 GET /prices` API. | -| `firm_quotes_supported` | `false` | Whether or not the anchor supports indicative quotes provided | by `SEP-38 POST /quote` and `SEP-38 POST /prices` API. If set to yes, anchor must support `quote_id` parameter in interactive endpoints and transaction response body. | From 0dc5c27ee2c804094870a6ae4743e1d65f4f9ae1 Mon Sep 17 00:00:00 2001 From: Gleb Date: Mon, 17 Jul 2023 14:23:52 -0700 Subject: [PATCH 16/17] Fix wording --- ecosystem/sep-0024.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ecosystem/sep-0024.md b/ecosystem/sep-0024.md index 120698ef9..a46cfbd9e 100644 --- a/ecosystem/sep-0024.md +++ b/ecosystem/sep-0024.md @@ -52,7 +52,7 @@ the API endpoints according to the protocol will work with any compliant wallet. - [`POST /transactions/withdraw/interactive`](#withdraw) - [`GET /info`](#info) - [`GET /fee`](#fee): **deprecated** optional (only needed for complex fee structures). - [`SEP-38 GET /price`](sep-0038.md#get-price) endpoint should be used to communicate the fees. + [`SEP-38 GET /price`](sep-0038.md#get-price) endpoint should be used to communicate fees and exchange rates. - [`GET /transactions`](#transaction-history) - [`GET /transaction`](#single-historical-transaction) From 100821b5079ff77f14ea724b4900fe89f0b39957 Mon Sep 17 00:00:00 2001 From: Gleb Date: Mon, 17 Jul 2023 15:32:59 -0700 Subject: [PATCH 17/17] Fix merge comments + prettier --- ecosystem/sep-0024.md | 45 ++++++++++++++++++++----------------------- 1 file changed, 21 insertions(+), 24 deletions(-) diff --git a/ecosystem/sep-0024.md b/ecosystem/sep-0024.md index a46cfbd9e..f4d145235 100644 --- a/ecosystem/sep-0024.md +++ b/ecosystem/sep-0024.md @@ -398,20 +398,20 @@ The fields below should be placed in the request body using the `multipart/form- Request Parameters: -| Name | Type | Description | -|-------------------------------| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `asset_code` | string | The code of the stellar asset the user wants to receive for their deposit with the anchor. The value passed must match one of the codes listed in the [/info](#info) response's deposit object. When `quote_id` is specified, `asset_code` must match the quote's `buy_asset` asset code. | -| `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to receive for their deposit with the anchor. If asset_issuer is not provided, the anchor should use the asset issued by themselves as described in their TOML file. If `native` is specified as the `asset_code`, `asset_issuer` must be not be set. When `quote_id` is specified, this parameter must match the quote's `buy_asset` asset code or be omitted. | -| `source_asset` | string in [Asset Identification Format] | (optional) The asset user wants to send. Note, that this is the asset user initially holds (off-chain or fiat asset).If this is not provided, it will be collected in the interactive flow. When `quote_id` is specified, this parameter must match the quote's `sell_asset` asset code or be omitted. | -| `amount` | number | (optional) Amount of asset requested to deposit. If this is not provided it will be collected in the interactive flow. When `qoute_id` is specified, this parameter must match the quote's `quote.sell_amount` or be omitted. | +| Name | Type | Description | +| ----------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `asset_code` | string | The code of the stellar asset the user wants to receive for their deposit with the anchor. The value passed must match one of the codes listed in the [/info](#info) response's deposit object. When `quote_id` is specified, `asset_code` must match the quote's `buy_asset` asset code. | +| `asset_issuer` | string | (optional) The issuer of the stellar asset the user wants to receive for their deposit with the anchor. If asset_issuer is not provided, the anchor should use the asset issued by themselves as described in their TOML file. If `native` is specified as the `asset_code`, `asset_issuer` must be not be set. When `quote_id` is specified, this parameter must match the quote's `buy_asset` asset code or be omitted. | +| `source_asset` | string in [Asset Identification Format] | (optional) The asset user wants to send. Note, that this is the asset user initially holds (off-chain or fiat asset).If this is not provided, it will be collected in the interactive flow. When `quote_id` is specified, this parameter must match the quote's `sell_asset` asset code or be omitted. | +| `amount` | number | (optional) Amount of asset requested to deposit. If this is not provided it will be collected in the interactive flow. When `qoute_id` is specified, this parameter must match the quote's `quote.sell_amount` or be omitted. | | `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 must respect the conversion rate agreed in that quote. When `quote_id` is set, `asset_code`, `source_asset` and `amount` must be validated by the anchor, if present. In case of a conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`. | -| `account` | `G...` or `M...` string | (optional) The Stellar or muxed account the client wants to use as the destination of the payment sent by the anchor. Defaults to the account authenticated via SEP-10 if not specified. | -| `memo_type` | string | (optional) Type of memo that anchor should attach to the Stellar 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 can be different than the value 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`. | -| `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. | -| `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646] which means it can also accept locale in the format `en-US`. `error` fields in the response, as well as the interactive flow UI and any other user-facing strings returned for this transaction should be in this language. | -| `claimable_balance_supported` | boolean | (optional) True if the client supports receiving deposit transactions as a claimable balance, false otherwise. | +| `account` | `G...` or `M...` string | (optional) The Stellar or muxed account the client wants to use as the destination of the payment sent by the anchor. Defaults to the account authenticated via SEP-10 if not specified. | +| `memo_type` | string | (optional) Type of memo that anchor should attach to the Stellar 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 can be different than the value 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`. | +| `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. | +| `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646] which means it can also accept locale in the format `en-US`. `error` fields in the response, as well as the interactive flow UI and any other user-facing strings returned for this transaction should be in this language. | +| `claimable_balance_supported` | boolean | (optional) True if the client supports receiving deposit transactions as a claimable balance, false otherwise. | When anchor receives a request, it can determine an origin of the request. First, it should check `client_domain` value of the authentication token. If it's set, this wallet is an origin of the request. Otherwise, `sub` value of the JWT is @@ -613,8 +613,8 @@ 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. Defaults to the account authenticated via SEP-10 if not specified. | | `memo` | string | (**deprecated**, optional) This field was originally intended to differentiate users of the same Stellar account. However, the anchor should use the `sub` value included in the decoded SEP-10 JWT instead. Anchors should still support this parameter to maintain support for outdated clients. See the [Shared Account Authentication](#shared-omnibus-or-pooled-accounts) section for more information. | | `memo_type` | string | (**deprecated**, optional) Type of `memo`. One of `text`, `id` or `hash`. Deprecated because memos used to identify users of the same Stellar account should always be of type of `id`. | -| `wallet_name` | string | (**deprecated**,optional) In communications / pages about the withdrawal, anchor should display the wallet name to the user to explain where funds are coming from. 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 can show this to the user when referencing the wallet involved in the withdrawal (ex. in the anchor's transaction history). However, anchors should use client_domain (for non-custodial) and `sub` value of JWT (for custodial) to determine wallet information. | +| `wallet_name` | string | (**deprecated**,optional) In communications / pages about the withdrawal, anchor should display the wallet name to the user to explain where funds are coming from. 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 can show this to the user when referencing the wallet involved in the withdrawal (ex. in the anchor's transaction history). However, anchors should use client_domain (for non-custodial) and `sub` value of JWT (for custodial) to determine wallet information. | | `lang` | string | (optional) Defaults to `en` if not specified or if the specified language is not supported. Language code specified using [RFC 4646] which means it can also accept locale in the format `en-US`. `error` fields in the response, as well as the interactive flow UI and any other user-facing strings returned for this transaction should be in this language. | | `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. | @@ -922,7 +922,7 @@ The response should be a JSON object like: }, "features": { "account_creation": true, - "claimable_balances": true, + "claimable_balances": true } } ``` @@ -967,20 +967,17 @@ The `features` object contains boolean values indicating whether specific featur object or specific feature is not present in the response, the default value described below may be assumed. This information enables wallets to adjust their behavior based on the feature set supported by the anchor. -| Name | Default | Description | -| ----------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `account_creation` | `true` | Whether or not the anchor supports creating accounts for users requesting deposits. | -| `claimable_balances` | `false` | Whether or not the anchor supports sending deposit funds as claimable balances. This is relevant for users of Stellar accounts without a trustline to the requested asset. | - -by `SEP-38 POST /quote` and `SEP-38 POST /prices` API. If set to yes, anchor must support `quote_id` parameter in -interactive endpoints and transaction response body. | +| Name | Default | Description | +| -------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `account_creation` | `true` | Whether or not the anchor supports creating accounts for users requesting deposits. | +| `claimable_balances` | `false` | Whether or not the anchor supports sending deposit funds as claimable balances. This is relevant for users of Stellar accounts without a trustline to the requested asset. | The default values for the features listed above have been selected based on the ecosystem's current support. It is highly recommend to support all features enumerated for the best user experience. ## Fee -### This endpoint is deprecated. The [SEP-38] `GET /price` endpoint should be used to fetch fees instead. +**This endpoint is deprecated. The [SEP-38] `GET /price` endpoint should be used to fetch fees instead.** The fee endpoint allows an anchor to report the fee that would be charged for a given deposit or withdraw operation. This is important to allow an anchor to accurately report fees to a user even when the fee schedule is complex. If a fee