Skip to content

Commit

Permalink
SEP-6: Add support for asynchronous deposit instructions (#1379)
Browse files Browse the repository at this point in the history 
### Proposal
This adds new fields to the `transaction` object to facilitate
Anchors providing deposit instructions outside of `GET /deposit` response.

### Backwards Compatability
This change is backward compatible as it does not introduce
new required fields if Anchors can provide deposit instructions in
the `GET /deposit` response.

Resolves #1372,
#1368.
  • Loading branch information
@philipliu
philipliu authored Aug 30, 2023
1 parent 0b361cc commit d0ef9fb
Showing 1 changed file with 66 additions and 10 deletions.
76 changes: 66 additions & 10 deletions ecosystem/sep-0006.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Author: SDF
Status: Active (Interactive components are deprecated in favor of SEP-24)
Created: 2017-10-30
Updated: 2023-08-15
Version 3.19.0
Version 3.20.0
```

## Simple Summary
Expand Down Expand Up @@ -358,7 +358,8 @@ The response body should be a JSON object with the following fields:

Name | Type | Description
-----|------|------------
`how` | string | Terse but complete instructions for how to deposit the asset. In the case of most cryptocurrencies it is just an address to which the deposit should be sent.
`how` | string | (**Deprecated**, use `instructions` instead) Terse but complete instructions for how to deposit the asset. In the case of most cryptocurrencies it is just an address to which the deposit should be sent.
`instructions` | object | (optional) JSON object containing the [SEP-9 financial account fields](sep-0009.md#financial-account-fields) that describe how to complete the off-chain deposit. If the anchor cannot provide this information in the response, the wallet should query the [`/transaction`](#single-historical-transaction) endpoint to get this asynchonously.
`id` | string | (optional) The anchor's ID for this deposit. The wallet will use this ID to query the [`/transaction`](#single-historical-transaction) endpoint to check status of the request.
`eta` | int | (optional) Estimate of how long the deposit will take to credit in seconds.
`min_amount` | float | (optional) Minimum amount of an asset that a user can deposit.
Expand All @@ -367,18 +368,53 @@ Name | Type | Description
`fee_percent` | float | (optional) Percentage fee (if any). In units of percentage points.
`extra_info` | object | (optional) JSON object with additional information about the deposit process.

`instructions` fields:

An object with SEP-9 financial account fields as keys and its values are objects with the following fields:

Name | Type | Description
-----|------|------------
`value` | string | The value of the field.
`description` | string | A human-readable description of the field. This can be used to provide any additional information about fields that are not defined in the SEP-9 standard.

`extra_info` fields:

Name | Type | Description
-----|------|------------
`message` | string | (optional) Additional details about the deposit process.

##### Examples

Bank payment example:
```json
{
"id": "9421871e-0623-4356-b7b5-5996da122f3e",
"instructions": {
"organization.bank_number": {
"value": "121122676",
"description": "US bank routing number"
},
"organization.bank_account_number": {
"value": "13719713158835300",
"description": "US bank account number"
}
},
"how": "Make a payment to Bank: 121122676 Account: 13719713158835300"
}
```

Bitcoin response example:

```json
{
"how" : "1Nh7uHdvY6fNwtQtM1G5EZAFPLC33B59rB",
"id": "9421871e-0623-4356-b7b5-5996da122f3e",
"instructions": {
"organization.crypto_address": {
"value": "1Nh7uHdvY6fNwtQtM1G5EZAFPLC33B59rB",
"description": "Bitcoin address"
}
},
"how": "Make a payment to Bitcoin address 1Nh7uHdvY6fNwtQtM1G5EZAFPLC33B59rB",
"fee_fixed" : 0.0002
}
```
Expand All @@ -387,10 +423,20 @@ Ripple response example:

```json
{
"how" : "Ripple address: rNXEkKCxvfLcM1h4HJkaj2FtmYuAWrHGbf tag: 88",
"id": "9421871e-0623-4356-b7b5-5996da122f3e",
"instructions": {
"organization.crypto_address": {
"value": "rNXEkKCxvfLcM1h4HJkaj2FtmYuAWrHGbf",
"description": "Ripple address"
},
"organization.crypto_memo": {
"value": "88",
"description": "Ripple tag"
}
},
"how": "Make a payment to Ripple address rNXEkKCxvfLcM1h4HJkaj2FtmYuAWrHGbf with tag 88",
"eta": 60,
"fee_percent" : 0.1,
"fee_percent": 0.1,
"extra_info": {
"message": "You must include the tag. If the amount is more than 1000 XRP, deposit will take 24h to complete."
}
Expand All @@ -401,8 +447,14 @@ Mexican peso (MXN) response example:

```json
{
"how" : "Make a payment to Bank: STP Account: 646180111803859359",
"id": "9421871e-0623-4356-b7b5-5996da122f3e",
"instructions": {
"organization.clabe_number": {
"value": "646180111803859359",
"description": "CLABE number"
}
},
"how": "Make a payment to Bank: STP Account: 646180111803859359",
"eta": 1800
}
```
Expand Down Expand Up @@ -457,7 +509,7 @@ Using this feature, anchors will no longer have to wait until the user's Stellar

1. Make a request to `/deposit` and provide the `claimable_balance_supported=true` request parameter.
2. Register the user's KYC information with the anchor via [SEP-12](sep-0012.md) if requested and resubmit the deposit request.
3. Once a successful deposit request has been made and the transaction's status is `pending_user_transfer_start`, the user must send the required payment as described by the `how` attribute in the deposit success response, using the `amount_in` returned from the `GET [SEP-6]/transaction?id=<transaction_id>` request.
3. Once a successful deposit request has been made and the transaction's status is `pending_user_transfer_start`, the user must send the required payment as described by the `instructions` attribute in the deposit success response, using the `amount_in` returned from the `GET [SEP-6]/transaction?id=<transaction_id>` request.
4. If the anchor doesn't support claimable balances, the anchor's `/transaction(s)` endpoint will contain the `pending_trust` status. In this case, use the flow described [above](#stellar-account-doesnt-trust-asset).
5. Otherwise, detect the `claimable_balance_id` value populated in the anchor's `/transaction(s)` endpoint or poll Horizon's [/claimable_balances](https://developers.stellar.org/api/resources/claimablebalances/) endpoint for outstanding claimable balances. When a claimable balance is detected using either method, the transaction status should be `completed`.
6. Claim the balance using the value via the `ClaimClaimableBalance` operation. See the ["Claiming Claimable Balances"](#claiming-claimable-balances) section to learn more about how to claim a balance.
Expand Down Expand Up @@ -943,7 +995,7 @@ All assets listed in a `deposit` and `deposit-exchange` can contain these attrib

* `enabled`: `true` if SEP-6 deposit for this asset is supported
* `authentication_required`: Optional. `true` if client must be [authenticated](#authentication) before accessing the deposit endpoint for this asset. `false` if not specified.
* `fields` object as explained below.
* `fields` (**Deprecated**, Accepting personally identifiable information through request parameters is a security risk due to web server request logging. KYC information should be supplied to the Anchor via SEP-12) `fields` object is explained below.

Deposit assets listed in the `deposit` object can also contain the attributes:

Expand Down Expand Up @@ -1123,6 +1175,9 @@ Name | Type | Description
`refunds` | object | (optional) An object describing any on or off-chain refund associated with this transaction. The schema for this object is defined in the [Refunds Object Schema](#refunds-object-schema) section below.
`required_info_message` | string | (optional) A human-readable message indicating any errors that require updated information from the user.
`required_info_updates` | object | (optional) A set of fields that require update from the user described in the same format as [/info](#info). This field is only relevant when `status` is `pending_transaction_info_update`.
`required_customer_info_message` | string | (optional) A human-readable message indicating why the SEP-12 information provided by the user is not sufficient to complete the transaction.
`required_customer_info_updates` | string | (optional) A set of SEP-9 fields that require update from the user via SEP-12. This field is only relevant when `status` is `pending_customer_info_update`.
`instructions` | string | (optional) JSON object containing the [SEP-9 financial account fields](sep-0009.md#financial-account-fields) that describe how to complete the off-chain deposit in the same format as the [/deposit](#deposit) response. This field should be present if the `instructions` were provided in the [/deposit](#deposit) response or if it could not have been previously provided synchronously. This field should only be present once the status becomes `pending_user_transfer_start`, not while the transaction has any statuses that precede it such as `incomplete`, `pending_anchor`, or `pending_customer_info_update`.
`claimable_balance_id` | string | (optional) ID of the Claimable Balance used to send the asset initially requested. Only relevant for deposit transactions.

`status` should be one of:
Expand Down Expand Up @@ -1363,7 +1418,7 @@ Every HTTP status code other than `200 OK` will be considered an error and in th

## Pending Customer Info Update

In certain cases the anchor may need updated customer information from the user. For example, the bank could tell the anchor that the account address does not match the user's name or other identifying information. Since this information was sent via SEP-12, the transaction should go into the `pending_customer_info_update` status until the sender makes another `PUT /customer` request to update. The sending anchor can check which fields need to be updated by making a `GET /customer` request including the `id` or `account` & `memo` parameters. The anchor should respond with a `NEEDS_INFO` status and include the fields that need to be updated.
In certain cases the anchor may need updated customer information from the user. For example, the bank could tell the anchor that the account address does not match the user's name or other identifying information. Since this information was sent via SEP-12, the transaction should go into the `pending_customer_info_update` status until the sender makes another `PUT /customer` request to update by providing the fields from `required_customer_info_updates` in the transaction object. The wallet can also check which fields need to be updated by making a `GET /customer` request including the `id` or `account` & `memo`. The anchor should respond with a `NEEDS_INFO` status and include the fields that need to be updated.

## Pending Transaction Info Update

Expand Down Expand Up @@ -1422,7 +1477,8 @@ If the information was malformed, or if the sender tried to update data that isn

## Changelog

* `v3.19.0`: Deprecate `/fee` endpoint
* `v3.20.0`: Add support for asynchronous deposit instructions. ([#1379](https://github.com/stellar/stellar-protocol/pull/1379/))
* `v3.19.0`: Deprecate `/fee` endpoint.([#1381](https://github.com/stellar/stellar-protocol/pull/1381))
* `v3.18.1`: Fix the missing types of the `withdraw` request parameters and some typo. ([#1365](https://github.com/stellar/stellar-protocol/pull/1365))
* `v3.18.0`: Added `refunded` status and `updated_at` transaction fields to match other SEPs (24, 31) ([#1336](https://github.com/stellar/stellar-protocol/pull/1336))
* `v3.17.1`: Allow anchors to omit the deprecated `X-Stellar-Signature` header ([#1335](https://github.com/stellar/stellar-protocol/pull/1335))
Expand Down

0 comments on commit d0ef9fb

Please sign in to comment.