Skip to content

Commit

Permalink
AP: Remove unique address callback (#1066)
Browse files Browse the repository at this point in the history
  • Loading branch information
@philipliu
philipliu authored Oct 29, 2024
1 parent 571016b commit 7d0f689
Show file tree
Hide file tree
Showing 19 changed files with 7,874 additions and 8,564 deletions.
79 changes: 9 additions & 70 deletions openapi/anchor-platform/bundled-callbacks.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,67 +22,6 @@ tags:
[SEP-12](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0012.md) requests made from client
applications.
paths:
/unique_address:
get:
description: |
If the platform is configured with `depositInfoGeneratorType: api`, the Platform make this request to
the Anchor backend every time a transaction is initiated by a client application.
The Anchor must guarantee that the memo returned in this request is unique, so it can be mapped 1-to-1 to a Platform
resource such as a [SEP-31](https://stellar.org/protocol/sep-31) transaction.
Here is how this flow would be used for Receiving Anchors that need to create their unique `(account, memo)` pairs
outside the platform, using Circle:
[![](https://mermaid.ink/img/pako:eNqlVctu2zAQ_JUFTy1iOwhyE9AUhuu0ORQ1YvdmIKDJVUSYIlWSihEY_veuRMuPhHaTVCc9VjPD4exyzYSVyDLm8U-NRuA3xR8dL-cG6AoqaMxgOp70r69g5rjxXARlDdxqu4KVCgXM2VpwrRdcLIeTu81lbRQhPXApHXo_ZxGp4i4ooSpuAkwDas1d4gMaqcwjDI0obOL7p3sUqJ6o5DNMNA-5deX5qlNII-WExvj-mLV_c3OR4slg8ms6g7XH6vpqcxn2XvgIYyuCJSPgnB2w4B4lkIGhQKi22CCsydVj7XiDF-GaK6WD9KXlTfkTwoGsf8JcvDYqg-_j2dkFfD1geFDyS5plb2U0mnDRIC0PgcNCW7EUBVcGtqCDPUqs79Ov_ZS8ewy1Mx4MriAKo_z5mKdOYlZiaeeM9lu5wVl9L1n2Zn6Qh5IUb5KWn9y6W2WUL5DSUSvdZrFJx7brDgyPDdd8e4emU1L6x7nfrznNPTjRLNtmzuAnX2LX2sT_XKIJ3U_xbf9Mb3WdIDGgCJ5i8gIKCl5VFCIJte8c-l8Xjvej82GnxdNaGyUHc2_81EjZbcPhRLwzuU2Q7YxKUjkrEIlkh0jyA9i8vc9pxvZaFd2COy-CbR93iDDSam93uhNPGD-cjX7AuptEbcenE1dJal-ZSqUPPNR-8JHk_25RW4KTiG-dz-3oSozny0zJxjFRoFi2VBG-s_l1yN_ZMq_kK9P80Q7zAeuxEulBSTpk1w3-nFF9iXOW0a3EnNc6NMfkhkqjy2OpgnUsy7n22GO8Dnb6bATLgquxK9oe1NuqzV8v2LI1)](https://mermaid.live/edit#pako:eNqlVctu2zAQ_JUFTy1iOwhyE9AUhuu0ORQ1YvdmIKDJVUSYIlWSihEY_veuRMuPhHaTVCc9VjPD4exyzYSVyDLm8U-NRuA3xR8dL-cG6AoqaMxgOp70r69g5rjxXARlDdxqu4KVCgXM2VpwrRdcLIeTu81lbRQhPXApHXo_ZxGp4i4ooSpuAkwDas1d4gMaqcwjDI0obOL7p3sUqJ6o5DNMNA-5deX5qlNII-WExvj-mLV_c3OR4slg8ms6g7XH6vpqcxn2XvgIYyuCJSPgnB2w4B4lkIGhQKi22CCsydVj7XiDF-GaK6WD9KXlTfkTwoGsf8JcvDYqg-_j2dkFfD1geFDyS5plb2U0mnDRIC0PgcNCW7EUBVcGtqCDPUqs79Ov_ZS8ewy1Mx4MriAKo_z5mKdOYlZiaeeM9lu5wVl9L1n2Zn6Qh5IUb5KWn9y6W2WUL5DSUSvdZrFJx7brDgyPDdd8e4emU1L6x7nfrznNPTjRLNtmzuAnX2LX2sT_XKIJ3U_xbf9Mb3WdIDGgCJ5i8gIKCl5VFCIJte8c-l8Xjvej82GnxdNaGyUHc2_81EjZbcPhRLwzuU2Q7YxKUjkrEIlkh0jyA9i8vc9pxvZaFd2COy-CbR93iDDSam93uhNPGD-cjX7AuptEbcenE1dJal-ZSqUPPNR-8JHk_25RW4KTiG-dz-3oSozny0zJxjFRoFi2VBG-s_l1yN_ZMq_kK9P80Q7zAeuxEulBSTpk1w3-nFF9iXOW0a3EnNc6NMfkhkqjy2OpgnUsy7n22GO8Dnb6bATLgquxK9oe1NuqzV8v2LI1)
summary: Generate Unique Address
operationId: genAddress
tags:
- Unique Address
x-seps:
- SEP-31
parameters:
- in: query
name: transaction_id
description: |
The platform server will save the posted transaction and pass the `transaction_id` through this endpoint.
If the anchor wishes to return transaction-dependent unique_address, the anchor may query the [`GET /transactions` endpoint of the Platform API](https://developers.stellar.org/platforms/anchor-platform/api-reference/resources/get-transaction).
schema:
type: string
required: true
responses:
'200':
description: Success.
content:
application/json:
schema:
type: object
properties:
unique_address:
description: An object containing the unique `stellar_address:memo` pair used to identify a destination.
type: object
properties:
stellar_address:
description: A `G...` stellar address or a `M...` [muxed stellar address](https://developers.stellar.org/docs/learn/encyclopedia/transactions-specialized/pooled-accounts-muxed-accounts-memos#muxed-accounts) of an **existing** account in the Stellar network.
type: string
memo:
description: The memo to attach to the Stellar payment.
type: string
memo_type:
description: The type of memo to attach to the Stellar payment (text, hash, or id).
type: string
enum:
- text
- hash
- id
required:
- stellar_address
'500':
description: Error. The Platform will respond to the client application with the same response code and body.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/rate:
get:
description: |
Expand Down Expand Up @@ -433,15 +372,6 @@ paths:
description: The event is invalid or rejected. The response body contains the error message.
components:
schemas:
Error:
type: object
properties:
error:
type: string
id:
type: string
required:
- error
RateFeeDetailResponse:
type: object
properties:
Expand Down Expand Up @@ -502,6 +432,15 @@ components:
- price
- sell_amount
- buy_amount
Error:
type: object
properties:
error:
type: string
id:
type: string
required:
- error
GetCustomerResponse:
type: object
required:
Expand Down
62 changes: 0 additions & 62 deletions openapi/anchor-platform/main-callbacks.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,68 +28,6 @@ x-tagGroups:
- Rates
- Customers
paths:
/unique_address:
get:
description: |
If the platform is configured with `depositInfoGeneratorType: api`, the Platform make this request to
the Anchor backend every time a transaction is initiated by a client application.
The Anchor must guarantee that the memo returned in this request is unique, so it can be mapped 1-to-1 to a Platform
resource such as a [SEP-31](https://stellar.org/protocol/sep-31) transaction.
Here is how this flow would be used for Receiving Anchors that need to create their unique `(account, memo)` pairs
outside the platform, using Circle:
[![](https://mermaid.ink/img/pako:eNqlVctu2zAQ_JUFTy1iOwhyE9AUhuu0ORQ1YvdmIKDJVUSYIlWSihEY_veuRMuPhHaTVCc9VjPD4exyzYSVyDLm8U-NRuA3xR8dL-cG6AoqaMxgOp70r69g5rjxXARlDdxqu4KVCgXM2VpwrRdcLIeTu81lbRQhPXApHXo_ZxGp4i4ooSpuAkwDas1d4gMaqcwjDI0obOL7p3sUqJ6o5DNMNA-5deX5qlNII-WExvj-mLV_c3OR4slg8ms6g7XH6vpqcxn2XvgIYyuCJSPgnB2w4B4lkIGhQKi22CCsydVj7XiDF-GaK6WD9KXlTfkTwoGsf8JcvDYqg-_j2dkFfD1geFDyS5plb2U0mnDRIC0PgcNCW7EUBVcGtqCDPUqs79Ov_ZS8ewy1Mx4MriAKo_z5mKdOYlZiaeeM9lu5wVl9L1n2Zn6Qh5IUb5KWn9y6W2WUL5DSUSvdZrFJx7brDgyPDdd8e4emU1L6x7nfrznNPTjRLNtmzuAnX2LX2sT_XKIJ3U_xbf9Mb3WdIDGgCJ5i8gIKCl5VFCIJte8c-l8Xjvej82GnxdNaGyUHc2_81EjZbcPhRLwzuU2Q7YxKUjkrEIlkh0jyA9i8vc9pxvZaFd2COy-CbR93iDDSam93uhNPGD-cjX7AuptEbcenE1dJal-ZSqUPPNR-8JHk_25RW4KTiG-dz-3oSozny0zJxjFRoFi2VBG-s_l1yN_ZMq_kK9P80Q7zAeuxEulBSTpk1w3-nFF9iXOW0a3EnNc6NMfkhkqjy2OpgnUsy7n22GO8Dnb6bATLgquxK9oe1NuqzV8v2LI1)](https://mermaid.live/edit#pako:eNqlVctu2zAQ_JUFTy1iOwhyE9AUhuu0ORQ1YvdmIKDJVUSYIlWSihEY_veuRMuPhHaTVCc9VjPD4exyzYSVyDLm8U-NRuA3xR8dL-cG6AoqaMxgOp70r69g5rjxXARlDdxqu4KVCgXM2VpwrRdcLIeTu81lbRQhPXApHXo_ZxGp4i4ooSpuAkwDas1d4gMaqcwjDI0obOL7p3sUqJ6o5DNMNA-5deX5qlNII-WExvj-mLV_c3OR4slg8ms6g7XH6vpqcxn2XvgIYyuCJSPgnB2w4B4lkIGhQKi22CCsydVj7XiDF-GaK6WD9KXlTfkTwoGsf8JcvDYqg-_j2dkFfD1geFDyS5plb2U0mnDRIC0PgcNCW7EUBVcGtqCDPUqs79Ov_ZS8ewy1Mx4MriAKo_z5mKdOYlZiaeeM9lu5wVl9L1n2Zn6Qh5IUb5KWn9y6W2WUL5DSUSvdZrFJx7brDgyPDdd8e4emU1L6x7nfrznNPTjRLNtmzuAnX2LX2sT_XKIJ3U_xbf9Mb3WdIDGgCJ5i8gIKCl5VFCIJte8c-l8Xjvej82GnxdNaGyUHc2_81EjZbcPhRLwzuU2Q7YxKUjkrEIlkh0jyA9i8vc9pxvZaFd2COy-CbR93iDDSam93uhNPGD-cjX7AuptEbcenE1dJal-ZSqUPPNR-8JHk_25RW4KTiG-dz-3oSozny0zJxjFRoFi2VBG-s_l1yN_ZMq_kK9P80Q7zAeuxEulBSTpk1w3-nFF9iXOW0a3EnNc6NMfkhkqjy2OpgnUsy7n22GO8Dnb6bATLgquxK9oe1NuqzV8v2LI1)
summary: Generate Unique Address
operationId: genAddress
tags:
- Unique Address
x-seps:
- SEP-31
parameters:
- in: query
name: transaction_id
description: |
The platform server will save the posted transaction and pass the `transaction_id` through this endpoint.
If the anchor wishes to return transaction-dependent unique_address, the anchor may query the [`GET /transactions` endpoint of the Platform API](https://developers.stellar.org/platforms/anchor-platform/api-reference/resources/get-transaction).
schema:
type: string
required: true
responses:
'200':
description: Success.
content:
application/json:
schema:
type: object
properties:
unique_address:
description: An object containing the unique `stellar_address:memo` pair used to identify a destination.
type: object
properties:
stellar_address:
description: A `G...` stellar address or a `M...` [muxed stellar address](https://developers.stellar.org/docs/learn/encyclopedia/transactions-specialized/pooled-accounts-muxed-accounts-memos#muxed-accounts) of an **existing** account in the Stellar network.
type: string
memo:
description: The memo to attach to the Stellar payment.
type: string
memo_type:
description: The type of memo to attach to the Stellar payment (text, hash, or id).
type: string
enum:
- text
- hash
- id
required:
- stellar_address

'500':
description: Error. The Platform will respond to the client application with the same response code and body.
content:
application/json:
schema:
$ref: './schemas.yaml#/components/schemas/Error'
/rate:
get:
description: |
Expand Down
2 changes: 1 addition & 1 deletion openrpc/src/anchor-platform/methods/request_onchain_funds.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
"summary": "Request onchain funds",
"description": "The user has to initiate transfer to the anchor",
"paramStructure": "by-name",
"tags": [{ "name": "SEP-6" }, { "name": "SEP-24" }],
"tags": [{ "name": "SEP-6" }, { "name": "SEP-24" }, { "name": "SEP-31" }],
"params": [
{ "$ref": "#/components/contentDescriptors/transaction_id" },
{ "$ref": "#/components/contentDescriptors/message" },
Expand Down
65 changes: 38 additions & 27 deletions platforms/anchor-platform/admin-guide/sep31/integration.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,6 @@ Integrating with the Anchor Platform for facilitating cross-border payments invo

The following may also be required depending on your use case:

- [`GET /unique_address`][get-unique-address] if your business uses a custody service for on-chain assets
- [`DELETE /customer`][delete-customer] if your business wants or is required to allow senders to request deletion of customer data

## Create a Business Server
Expand Down Expand Up @@ -240,9 +239,45 @@ This chapter also contains information about the format of [request][sep24-integ

### Ready to Receive Funds

SEP-31 Transactions should initially be in the `pending_sender` status. The Receiving Anchor waits to receive the payment identified by the stellar_memo included in the POST /transactions response.
SEP-31 Transactions should initially be in the `pending_receiver` status. To request funds from the Sending Anchor, the Receiving Anchor should change the transaction status to `pending_sender` by making the following RPC request:

Once your business detects that it has received an on-chain payment for a specific transaction, it has to update the transaction status.
<CodeExample>

```json
// request-onchain-funds.json
[
{
"id": 1,
"jsonrpc": "2.0",
"method": "request_onchain_funds",
"params": {
"transaction_id": "<transaction_id>",
"message": "Request onchain funds",
"destination_account": "GD...G",
"memo": "12345",
"memo_type": "id"
}
}
]
```

</CodeExample>

To execute this, you need to run:

<CodeExample>

```bash
./call-json-rpc.sh request-onchain-funds.json
```

</CodeExample>

The transaction status will be changed to `pending_sender`.

### Funds Received

If the Sending Anchor has sent the funds, the Receiving Anchor should change the transaction status to `pending_receiver` by making the following JSON-RPC request:

<CodeExample>

Expand Down Expand Up @@ -616,36 +651,12 @@ assets:
</CodeExample>
## Unique Address Callback Endpoint
Businesses must provide a unique Stellar account and memo pair for each transaction requested by sending organizations so that the Anchor Platform can identify and map the on-chain payment sent for the specific transaction. The Anchor Platform can generate these account & memo pairs itself, but most businesses use a custodial service to receive on-chain payments. In this case, the business must request the custodian to generate the Stellar account & memo. This is done by using the [`GET /unique_address` endpoint][get-unique-address].

### Configuration

To configure the Anchor Platform to make these requests, add the following to your configuration:

<CodeExample>

```bash
# dev.env
SEP31_DEPOSIT_INFO_GENERATOR_TYPE=api
```

</CodeExample>

:::caution

This endpoint may be removed during future major version updates of the Anchor Platform, when it adds support for connecting to custodial services and generating these addresses automatically.

:::

[ap-api]: ../../README.mdx
[ap-sep10]: ../sep10/README.mdx
[sep12]: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0012.md
[demo-wallet]: https://demo-wallet.stellar.org
[indicative]: https://www.investopedia.com/terms/i/indicativequote.asp
[firm]: https://www.investopedia.com/terms/f/firmquote.asp
[get-unique-address]: ../../api-reference/callbacks/gen-address.api.mdx
[get-customer]: ../../api-reference/callbacks/get-customer.api.mdx
[put-customer]: ../../api-reference/callbacks/put-customer.api.mdx
[get-rate]: ../../api-reference/callbacks/get-rates.api.mdx
Expand Down
15 changes: 7 additions & 8 deletions platforms/anchor-platform/api-reference/callbacks/README.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,12 @@ The Anchor Platform provides several callback functionalities for your business

<EndpointsTable title="Callbacks">

| | |
| ------ | ---------------------------------------- |
| GET | [/customer](./get-customer.api.mdx) |
| PUT | [/customer](./put-customer.api.mdx) |
| DELETE | [/customer/:id](./del-customer.api.mdx) |
| POST | [/event](./post-event.api.mdx) |
| GET | [/rate](./get-rates.api.mdx) |
| GET | [/unique_address](./gen-address.api.mdx) |
| | |
| ------ | --------------------------------------- |
| GET | [/customer](./get-customer.api.mdx) |
| PUT | [/customer](./put-customer.api.mdx) |
| DELETE | [/customer/:id](./del-customer.api.mdx) |
| POST | [/event](./post-event.api.mdx) |
| GET | [/rate](./get-rates.api.mdx) |

</EndpointsTable>
Loading

0 comments on commit 7d0f689

Please sign in to comment.