diff --git a/ecosystem/sep-0024.md b/ecosystem/sep-0024.md index 8e5410ed8..4bad1fc82 100644 --- a/ecosystem/sep-0024.md +++ b/ecosystem/sep-0024.md @@ -7,7 +7,7 @@ Author: SDF Status: Active Created: 2019-09-18 Updated: 2024-08-07 -Version 3.7.1 +Version 3.8.0 ``` ## Simple Summary @@ -42,8 +42,8 @@ the API endpoints according to the protocol will work with any compliant wallet. 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. +- Anchors and clients must support [SEP-10](sep-0010.md) or [SEP-45](sep-0045.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 @@ -58,10 +58,10 @@ the API endpoints according to the protocol will work with any compliant wallet. ## Authentication -As stated, Anchors must support [SEP-10](sep-0010.md) web authentication to enable authenticated deposits, withdrawals, -or transaction history lookups. Clients must submit the JWT previously obtained from the anchor via the -[SEP-10](sep-0010.md) authentication flow to all API endpoints that provide user data. `/info` should be -unauthenticated, but all other endpoints will require a token. +As stated, Anchors must support [SEP-10](sep-0010.md) or [SEP-45](sep-0045.md) web authentication to enable +authenticated deposits, withdrawals, or transaction history lookups. Clients must submit the JWT previously obtained +from the anchor via the [SEP-10](sep-0010.md)/[SEP-45](sep-0045.md) authentication flow to all API endpoints that +provide user data. `/info` should be unauthenticated, but all other endpoints will require a token. The JWT should be included in all requests as request header: @@ -75,22 +75,24 @@ flow. Query parameters can leak, so its important to have this JWT be one-time u ### Shared, Omnibus, or Pooled Accounts -Client applications can use a single Stellar account to hold multiple users' funds. To distinguish users that use the -same Stellar account, the decoded SEP-10 JWT's `sub` value may contain a memo value after the Stellar account -(`G...:2810101841641761712`) OR the `sub` value will be a [Muxed Account (`M...`)](../core/cap-0027.md). The anchor -should use this `sub` attribute in their data model to identify unique users. +Client applications can use a single account to hold multiple users' funds. To distinguish users that use the same +account, the decoded web auth JWT's `sub` value may contain a memo value after the Stellar account +(`G...:2810101841641761712`), OR contract account (`C...:2810101841641761712`) OR the `sub` value will be a +[Muxed Account (`M...`)](../core/cap-0027.md). The anchor should use this `sub` attribute in their data model to +identify unique users. -This document will refer to these accounts as shared accounts. See the [SEP-10 Memos](sep-0010.md#memos) and -[Muxed Accounts](sep-0010.md#muxed-accounts) sections for more information. +This document will refer to these accounts as shared accounts. See the +[SEP-10 Memos](sep-0010.md#memos)/[SEP-45 Memos](sep-0045.md#memos) and [Muxed Accounts](sep-0010.md#muxed-accounts) +sections for more information. -Note that Stellar accounts are either shared or they are not. This means anchors should ensure that a Stellar account -previously authenticated with a memo should not be authenticated later without a memo. Conversely, an account that was -previously authenticated without a memo should not be later authenticated as a shared account. +Note that accounts are either shared or they are not. This means anchors should ensure that an account previously +authenticated with a memo should not be authenticated later without a memo. Conversely, an account that was previously +authenticated without a memo should not be later authenticated as a shared account. ### Source and Destination Accounts Note that both the source account of a withdrawal payment and the destination account of a deposit can be different than -the account authenticated via SEP-10. +the account authenticated via SEP-10/SEP-45. ## Asset Exchanges @@ -291,7 +293,7 @@ banking rails so counterparties can run through the flow without a need to colla - 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/SEP-45 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`** @@ -306,8 +308,9 @@ banking rails so counterparties can run through the flow without a need to colla - **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. + interactive webapp callback or the `/transaction` endpoint. This can be a `payment` or `path_payment` operation or a + SAC `transfer` if the sending account is a contract. 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 @@ -334,11 +337,11 @@ banking rails so counterparties can run through the flow without a need to colla `/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. + - We recommend you use [SEP-10](#authentication) or SEP-45 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** @@ -353,7 +356,7 @@ banking rails so counterparties can run through the flow without a need to colla 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` + they're detected. Anchors must listen for `payment`, `path_payment` and `invoke_host_function` [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 @@ -398,21 +401,21 @@ 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. | -| `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. | -| `customer_id` | string | (optional) id of an off-chain account (managed by the anchor) associated with this user's Stellar account (identified by the JWT's `sub` field). If the anchor supports [SEP-12], the `customer_id` field should match the [SEP-12] customer's id. `customer_id` should be passed only when the off-chain id is know to the client, but the relationship between this id and the user's Stellar account is not known to the Anchor. | +| 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, muxed account or contract the client wants to use as the destination of the payment sent by the anchor. Defaults to the account authenticated via SEP-10/SEP-45 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`. A memo cannot be included if the `account` is a contract address. | +| `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. | +| `customer_id` | string | (optional) id of an off-chain account (managed by the anchor) associated with this user's Stellar account (identified by the JWT's `sub` field). If the anchor supports [SEP-12], the `customer_id` field should match the [SEP-12] customer's id. `customer_id` should be passed only when the off-chain id is know to the client, but the relationship between this id and the user's Stellar account is not known to the Anchor. | 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 @@ -611,8 +614,8 @@ Request parameters: | `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. | +| `account` | `G...` or `M...` string | (optional) The Stellar, muxed account or contract 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/SEP-45 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. | @@ -1095,23 +1098,23 @@ 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. | -| `to` | string | Stellar address the deposited assets were sent to. | -| `claimable_balance_id` | string | (optional) ID of the Claimable Balance used to send the asset initially requested. | +| Name | Type | Description | +| ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `deposit_memo` | string | (optional) This is the memo (if any) used to transfer the asset to the `to` Stellar address. This is not set when the receiving account is a contract. | +| `deposit_memo_type` | string | (optional) Type for the `deposit_memo`. | +| `from` | string | Sent from address, perhaps BTC, IBAN, or bank account. | +| `to` | string | Stellar address the deposited assets were sent to. | +| `claimable_balance_id` | string | (optional) ID of the Claimable Balance used to send the asset initially requested. | ### 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`. | -| `from` | string | Stellar address the assets were withdrawn from | -| `to` | string | Sent to address (perhaps BTC, IBAN, or bank account in the case of a withdrawal, Stellar address in the case of a deposit). | +| 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 | (optional) 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, or when the sending account is a contract | +| `withdraw_memo_type` | string | (optional) Memo type for `withdraw_memo`. | +| `from` | string | Stellar address the assets were withdrawn from | +| `to` | string | Sent to address (perhaps BTC, IBAN, or bank account in the case of a withdrawal, Stellar address in the case of a deposit). | `status` should be one of: @@ -1312,8 +1315,8 @@ body should contain error details. For example: The transaction endpoint enables clients to query/validate a specific transaction at an anchor. -Anchors must ensure that the SEP-10 JWT included in the request contains the Stellar account and optional memo value -used when making the original deposit or withdraw request that resulted in the transaction requested using this +Anchors must ensure that the SEP-10/SEP-45 JWT included in the request contains the Stellar account and optional memo +value used when making the original deposit or withdraw request that resulted in the transaction requested using this endpoint. ``` @@ -1407,6 +1410,7 @@ There is a small set of changes when upgrading from SEP-6 to SEP-24. ## Changelog +- `v3.8.0` Add support for contract addresses([#1562](https://github.com/stellar/stellar-protocol/pull/1562)) - `v3.7.1` Make `amount_out` optional in transaction responses([#1520](https://github.com/stellar/stellar-protocol/pull/1520)) - `v3.7.0` Add `user_action_required_by` field to transaction responses