Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

SEP-6: Add support for asynchronous deposit instructions #1379

Merged
merged 17 commits into from
Aug 30, 2023
Merged

SEP-6: Add support for asynchronous deposit instructions #1379

Changes from 15 commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
823fab8
Add support for asynchronous deposit instructions
philipliu Aug 14, 2023
9ce35ba
Deprecate `fields`
philipliu Aug 15, 2023
2647a7c
Address PR comments
philipliu Aug 16, 2023
72255fc
Missed customer_info_type
philipliu Aug 16, 2023
1392695
Fix changelog
philipliu Aug 16, 2023
79057a9
Merge branch 'master' into anchor-386-deposit
philipliu Aug 16, 2023
e30edab
Fix instructions field
philipliu Aug 16, 2023
0d08afb
Fix formatting
philipliu Aug 16, 2023
0888b04
Why did the address change
philipliu Aug 16, 2023
2157343
Address PR comments
philipliu Aug 16, 2023
1bc9c2b
Merge branch 'master' into anchor-386-deposit
philipliu Aug 16, 2023
c6b732c
Remove extra example
philipliu Aug 16, 2023
f89e9ab
Merge branch 'master' into anchor-386-deposit
philipliu Aug 16, 2023
4952172
Update ecosystem/sep-0006.md
philipliu Aug 16, 2023
539bd94
Add value to instructions schema
philipliu Aug 16, 2023
14e84b9
Fix `required_customer_info_updates` usage
philipliu Aug 17, 2023
2039b02
Merge branch 'master' into anchor-386-deposit
philipliu Aug 30, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 66 additions & 10 deletions ecosystem/sep-0006.md
View file
Open in desktop
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 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. The anchor can check which fields need to be updated by making a `GET /customer` request including the `id` or `account` & `memo` with the `required_customer_info_updates` fields associated with the transaction. 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