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

Memo-based Pooled Account Support #1036

Merged
merged 41 commits into from
Sep 9, 2021
Merged

Memo-based Pooled Account Support #1036

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
41 commits
Select commit Hold shift + click to select a range
6e948c4
SEP-10 Pooled (shared account) Support
JakeUrban Sep 17, 2020
4c5fc86
Merge branch 'master' into sep10-pooled-accounts
JakeUrban Jun 25, 2021
acd18d7
rephrase 'Memos' section
JakeUrban Jun 25, 2021
561d23e
update meta info
JakeUrban Jun 25, 2021
36bfd02
Merge branch 'master' into sep10-pooled-accounts
JakeUrban Jun 30, 2021
ce4b5fc
SEP-24: shared account support changes
JakeUrban Jun 30, 2021
fd9d318
Merge branch 'master' into sep10-pooled-accounts
JakeUrban Aug 3, 2021
9275c8f
merge mistake
JakeUrban Aug 3, 2021
84c8f50
SEP-6: add support for memos in SEP-10 JWTs
JakeUrban Aug 3, 2021
3459b83
make account parameter for withdrawal deprecated as well
JakeUrban Aug 3, 2021
b3d268e
SEP-12: add support for pooled accounts
JakeUrban Aug 6, 2021
f2e4dca
deprecate all use of 'account' parameters in SEP-12
JakeUrban Aug 6, 2021
aebdf72
Merge branch 'master' into sep10-pooled-accounts
JakeUrban Aug 9, 2021
9a13fa5
update meta info
JakeUrban Aug 10, 2021
e8d5ec2
Merge branch 'master' into sep10-pooled-accounts
JakeUrban Aug 17, 2021
e7e1ea5
Update ecosystem/sep-0006.md
JakeUrban Aug 20, 2021
1ff0463
Update ecosystem/sep-0006.md
JakeUrban Aug 20, 2021
868243f
Update ecosystem/sep-0012.md
JakeUrban Aug 20, 2021
13c4edf
Update ecosystem/sep-0012.md
JakeUrban Aug 20, 2021
b5a783a
Update ecosystem/sep-0010.md
JakeUrban Aug 20, 2021
e2c50f9
Update ecosystem/sep-0006.md
JakeUrban Aug 20, 2021
0daea0e
Update ecosystem/sep-0010.md
JakeUrban Aug 23, 2021
a82e2a5
Update ecosystem/sep-0010.md
JakeUrban Aug 24, 2021
97cc897
update 'sub' format in JWT, remove 'memo_type' request parameters
JakeUrban Aug 24, 2021
f611f92
add section on ensuring shared accounts are not authenticated without…
JakeUrban Aug 24, 2021
9601a8c
updated downstream SEPs to expect memos of type 'id'
JakeUrban Aug 24, 2021
241b430
fix typo
JakeUrban Aug 24, 2021
c9826fc
more changes to the SEPs for memo-id only rule
JakeUrban Aug 24, 2021
02b32d3
missed changes needed for SEP-12's callback endpoint
JakeUrban Aug 24, 2021
39634f0
small grammar changes
JakeUrban Aug 24, 2021
7f93390
update section with omnibus and pooled account terms
JakeUrban Aug 24, 2021
085b7c7
Add support for muxed accounts in conjunction with memos
JakeUrban Aug 27, 2021
a1a0096
Apply suggestions from code review
JakeUrban Aug 27, 2021
3444897
reference SEP-23 and create section for muxed accounts in SEP-10
JakeUrban Aug 28, 2021
b04f03b
Merge branch 'master' into sep10-pooled-accounts
JakeUrban Aug 28, 2021
44e8f43
revert overwrite of a code review suggestion
JakeUrban Aug 28, 2021
324355f
Apply suggestions from code review
JakeUrban Sep 3, 2021
41f592a
remove mention of exclusive use of muxed accounts from SEP-10
JakeUrban Sep 3, 2021
007dbb2
Allow memos sent in SEP-12 requests to match muxed accounts authentic…
JakeUrban Sep 9, 2021
b1f892f
Update ecosystem/sep-0010.md
JakeUrban Sep 9, 2021
51e2f13
Update ecosystem/sep-0010.md
JakeUrban Sep 9, 2021
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
42 changes: 27 additions & 15 deletions ecosystem/sep-0006.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,11 +59,19 @@ The JWT should be included in all requests as request header:
Authorization: Bearer <JWT>
```

It is highly recommended to require authentication for all endpoints other than `/info` (and optionally `/fee`).
It is highly recommended to require authentication for all endpoints other than `/info` (and optionally `/fee`). Some functionality, including the [Shared Accounts](#shared-omnibus-or-pooled-accounts) functionality described in the section below, may only be possible through the use of SEP-10.

### 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 the `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.

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.
accordeiro marked this conversation as resolved.
Show resolved Hide resolved

### 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.
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.

## Cross-Origin Headers

Expand Down Expand Up @@ -194,9 +202,9 @@ Request Parameters:
Name | Type | Description
-----|------|------------
`asset_code` | string | The code of the on-chain asset the user wants to get from the Anchor after doing an off-chain deposit. The value passed must match one of the codes listed in the [/info](#info) response's deposit object.
`account` | `G...` string | The stellar account ID of the user that wants to deposit. This is where the asset token will be sent. Note that the account specified in this request could differ from the account authenticated via SEP-10.
`memo_type` | string | (optional) Type of memo that anchor should attach to the Stellar payment transaction, one of `text`, `id` or `hash`.
`memo` | string | (optional) Value of memo to attach to transaction, for `hash` this should be base64-encoded.
`account` | `G...` or `M...` string | The stellar or muxed account ID of the user that wants to deposit. This is where the asset token will be sent. Note that the account specified in this request could differ from the account authenticated via SEP-10.
`memo_type` | string | (optional) Type of memo that the anchor should attach to the Stellar payment transaction, one of `text`, `id` or `hash`.
`memo` | string | (optional) Value of memo to attach to transaction, for `hash` this should be base64-encoded. Because a memo can be specified in the SEP-10 JWT for [Shared Accounts](#shared-omnibus-or-pooled-accounts), this field as well as `memo_type` can be different than the values included in the SEP-10 JWT. For example, a client application could use the value passed for this parameter as a reference number used to match payments made to `account`.
`email_address` | string | (optional) Email address of depositor. If desired, an anchor can use this to send email updates to the user about the deposit.
`type` | string | (optional) Type of deposit. If the anchor supports multiple deposit methods (e.g. `SEPA` or `SWIFT`), the wallet should specify `type`. This field may be necessary for the anchor to determine which KYC fields to collect.
`wallet_name` | string | (optional) In communications / pages about the deposit, anchor should display the wallet name to the user to explain where funds are going.
Expand Down Expand Up @@ -388,9 +396,9 @@ Name | Type | Description
`type` | string | Type of withdrawal. Can be: `crypto`, `bank_account`, `cash`, `mobile`, `bill_payment` or other custom values. This field may be necessary for the anchor to determine what KYC information is necessary to collect.
`dest` | string | The account that the user wants to withdraw their funds to. This can be a crypto account, a bank account number, IBAN, mobile number, or email address.
`dest_extra` | string | (optional) Extra information to specify withdrawal location. For crypto it may be a memo in addition to the `dest` address. It can also be a routing number for a bank, a BIC, or the name of a partner handling the withdrawal.
`account` | `G...` string | (optional) The stellar account ID of the user that wants to do the withdrawal. This is only needed if the anchor requires KYC information for withdrawal. The anchor can use `account` to look up the user's KYC information. Note that the account specified in this request could differ from the account authenticated via SEP-10.
`memo` | string | (optional) A wallet will send this to uniquely identify a user if the wallet has multiple users sharing one Stellar account. The anchor can use this along with `account` to look up the user's KYC info.
`memo_type` | string | (optional) Type of `memo`. One of `text`, `id` or `hash`.
`account` | `G...` or `M...` string | (optional) The Stellar or muxed account the client will use as the source of the withdrawal payment to the anchor. If SEP-10 authentication is not used, the anchor can use `account` to look up the user's KYC information. Note that the account specified in this request could differ from the account authenticated via SEP-10.
`memo` | string | (optional) This field should only be used if SEP-10 authentication is not. It was originally intended to distinguish users of the same Stellar account. However if SEP-10 is supported, the anchor should use the `sub` value included in the decoded SEP-10 JWT instead. See the [Shared Account Authentication](#shared-omnibus-or-pooled-accounts) section for more information.
accordeiro marked this conversation as resolved.
Show resolved Hide resolved
`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`. Language code specified using [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1). `error` fields in the response should be in this language.
Expand Down Expand Up @@ -422,7 +430,7 @@ Name | Type | Description
-----|------|------------
`account_id` | `G...` string | The account the user should send its token back to.
`memo_type` | string | (optional) Type of memo to attach to transaction, one of `text`, `id` or `hash`.
`memo` | string | (optional) Value of memo to attach to transaction, for `hash` this should be base64-encoded.
`memo` | string | (optional) Value of memo to attach to transaction, for `hash` this should be base64-encoded. The anchor should use this memo to match the Stellar transaction with the database entry associated created to represent it.
`id` | string | (optional) The anchor's ID for this withdrawal. 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 withdrawal will take to credit in seconds.
`min_amount` | float | (optional) Minimum amount of an asset that a user can withdraw.
Expand Down Expand Up @@ -462,9 +470,9 @@ Name | Type | Description
`source_asset` | string | The off-chain asset the Anchor will receive from the user. The value must match one of the `asset` values included in a [`SEP-38 GET /prices?buy_asset=stellar:<destination_asset>:<asset_issuer>`](sep-0038.md#get-prices) response using [SEP-38 Asset Identification Format](sep-0038.md#asset-identification-format).
`quote_id` | string | (optional) The `id` returned from a `SEP-38 POST /quote` response. If this parameter is provided and the user delivers the deposit funds to the Anchor before the quote expiration, the Anchor should respect the conversion rate agreed in that quote. If the values of `destination_asset`, `source_asset` and `amount` conflict with the ones used to create the [SEP-38] quote, this request should be rejected with a `400`.
`amount` | string | The amount of the source_asset the user would like to deposit to the anchor's off-chain account. This field may be necessary for the anchor to determine what KYC information is necessary to collect.
`account` | `G...` string | The stellar account ID of the user that wants to deposit. This is where the asset token will be sent. Note that the account specified in this request could differ from the account authenticated via SEP-10.
`memo_type` | string | (optional) Type of memo that anchor should attach to the Stellar payment transaction, one of `text`, `id` or `hash`.
`memo` | string | (optional) Value of memo to attach to transaction, for `hash` this should be base64-encoded.
`account` | `G...` or `M...` string | The stellar or muxed account ID of the user that wants to deposit. This is where the asset token will be sent. Note that the account specified in this request could differ from the account authenticated via SEP-10.
`memo_type` | string | (optional) Type of memo that the anchor should attach to the Stellar payment transaction, one of `text`, `id` or `hash`.
`memo` | string | (optional) Value of memo to attach to transaction, for `hash` this should be base64-encoded. Because a memo can be specified in the SEP-10 JWT for [Shared Accounts](#shared-omnibus-or-pooled-accounts), this field as well as `memo_type` can be different than the values included in the SEP-10 JWT. For example, a client application could use the value passed for this parameter as a reference number used to match payments made to `account`.
`email_address` | string | (optional) Email address of depositor. If desired, an anchor can use this to send email updates to the user about the deposit.
`type` | string | (optional) Type of deposit. If the anchor supports multiple deposit methods (e.g. `SEPA` or `SWIFT`), the wallet should specify `type`. This field may be necessary for the anchor to determine which KYC fields to collect.
`wallet_name` | string | (optional) In communications / pages about the deposit, anchor should display the wallet name to the user to explain where funds are going.
Expand Down Expand Up @@ -512,9 +520,9 @@ Name | Type | Description
`type` | string | Type of withdrawal. Can be: `crypto`, `bank_account`, `cash`, `mobile`, `bill_payment` or other custom values. This field may be necessary for the anchor to determine what KYC information is necessary to collect.
`dest` | string | The account that the user wants to withdraw their funds to. This can be a crypto account, a bank account number, IBAN, mobile number, or email address.
`dest_extra` | string | (optional) Extra information to specify withdrawal location. For crypto it may be a memo in addition to the `dest` address. It can also be a routing number for a bank, a BIC, or the name of a partner handling the withdrawal.
`account` | `G...` string | (optional) The stellar account ID of the user that wants to do the withdrawal. This is only needed if the anchor requires KYC information for withdrawal. The anchor can use `account` to look up the user's KYC information. Note that the account specified in this request could differ from the account authenticated via SEP-10.
`memo` | string | (optional) A wallet will send this to uniquely identify a user if the wallet has multiple users sharing one Stellar account. The anchor can use this along with `account` to look up the user's KYC info.
`memo_type` | string | (optional) Type of `memo`. One of `text`, `id` or `hash`.
`account` | `G...` or `M...` string | (optional) The Stellar or muxed account of the user that wants to do the withdrawal. This is only needed if the anchor requires KYC information for withdrawal and SEP-10 authentication is not used. Instead, the anchor can use `account` to look up the user's KYC information. Note that the account specified in this request could differ from the account authenticated via SEP-10.
`memo` | string | (optional) This field should only be used if SEP-10 authentication is not. It was originally intended to distinguish users of the same Stellar account. However if SEP-10 is supported, the anchor should use the `sub` value included in the decoded SEP-10 JWT instead. See the [Shared Account Authentication](#shared-omnibus-or-pooled-accounts) section for more information.
accordeiro marked this conversation as resolved.
Show resolved Hide resolved
`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`. Language code specified using [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1). `error` fields in the response should be in this language.
Expand Down Expand Up @@ -916,6 +924,8 @@ For example:

The transaction history endpoint helps anchors enable a better experience for users using an external wallet. With it, wallets can display the status of deposits and withdrawals while they process and a history of past transactions with the anchor. It's only for transactions that are deposits to or withdrawals from the anchor.

If the decoded JWT's `sub` parameter also contains a memo, the anchor must only return transactions for the user identified by a combination of the account and memo. The anchor must not return all transactions for the Stellar account because that would include transactions for other memos.

```
GET TRANSFER_SERVER/transactions
```
Expand Down Expand Up @@ -1083,6 +1093,8 @@ 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 endpoint.

```
GET TRANSFER_SERVER/transaction
```
Expand Down
Loading