Update Anchor Platform SEP-6 guide (#728)

stellar · Jun 28, 2024 · e50156b · e50156b
1 parent 05b3309
commit e50156b
Showing 1 changed file with 79 additions and 87 deletions.
diff --git a/platforms/anchor-platform/admin-guide/sep6/configuration.mdx b/platforms/anchor-platform/admin-guide/sep6/configuration.mdx
@@ -5,9 +5,32 @@ sidebar_position: 20
 
 import { CodeExample } from "@site/src/components/CodeExample";
 
-## Modify a Stellar Info File
+# Configuration
 
-Next, let's modify the `stellar.toml` file created [earlier][sep1-ap]. Wallets need to know that SEP-6 functionality is supported by your business, and they also need to know all the currencies you support.
+To enable SEP-6 deposits and withdraws, the Anchor Platform must be configured to do the following:
+
+- Provide the necessary service URLs for SEP-6, 12, & 38 endpoints in the `stellar.toml` file
+- Provide information about the on & off-chain assets, as well as the payment rails, supported by your business via SEP-6 and SEP-38 `/info` endpoints
+- Support the endpoints and callbacks required to request KYC information and provide exchange rates
+
+## Enable Programmatic Deposits & Withdrawals
+
+Add the following variables to your environment file.
+
+<CodeExample>
+
+```bash
+# dev.env
+SEP6_ENABLED=true
+SEP12_ENABLED=true
+SEP38_ENABLED=true
+```
+
+</CodeExample>
+
+### Modify a Stellar Info File
+
+Let's modify the `stellar.toml` file created [earlier][sep1-ap]. Wallets need to know that SEP-6 functionality is supported by your business, and they also need to know all the Stellar assets you support.
 
 <CodeExample>
 
@@ -19,6 +42,8 @@ NETWORK_PASSPHRASE = "Test SDF Network ; September 2015"
 
 TRANSFER_SERVER = "http://localhost:8080/sep6"
 WEB_AUTH_ENDPOINT = "http://localhost:8080/auth"
+KYC_SERVER = "http://localhost:8080/sep12"
+ANCHOR_QUOTE_SERVER = "http://localhost:8080/sep38"
 
 # Add support for USDC
 [[CURRENCIES]]
@@ -38,20 +63,15 @@ ORG_DESCRIPTION = "A description of your organization"
 
 Note that you will need to create another file for your production deployment that uses the public network's passphrase, your production service URLs, your Mainnet distribution accounts and signing key, as well as the Mainnet issuing accounts of the assets your service utilizes.
 
-## Enable Programmatic Deposits & Withdrawals
+### Modify the Assets Configuration File
 
-Add the following variable to your environment file.
+Now you're ready to specify the following in your `dev.assets.yaml` file, and change the values depending on your use case. This example asset file enables support for Circle's USDC and a fiat USD to deposit from and withdraw to. 
 
-<CodeExample>
+The methods specified in the `sep38` sections are methods that will be exposed by the SEP-38 [`GET /info`][sep38] endpoint.
 
-```bash
-# dev.env
-SEP6_ENABLED=true
-```
+The methods specified in the `deposit` and `withdraw` sections are the methods that will be exposed by the SEP-6 [`GET /info`][sep-6] endpoint. The methods listed should match the methods defined in the SEP-38 section of the file.
 
-</CodeExample>
-
-Now you're ready to enable programmatic deposits and withdrawals using the SEP-6 API. Specify the following in your `dev.assets.yaml` file, and change the values depending on your use case. This example asset file enables support for Circle's USDC and a fiat USD to deposit from and withdraw to. The methods specified in the `deposit` and `withdraw` sections are the methods that will be exposed by the [`GET /info`][sep-6] SEP-6 endpoint under the `type` field in the case of `deposit` and `types` field in the case of `withdraw`.
+Also note that fiat assets, those with the `schema: iso4217`, do not need the `sep6_enabled`, `deposit`, or `withdraw` configuration objects specified. In the same way, Stellar assets, those with `schema: stellar`, do not need the `sep38.sell_delivery_methods` or `sep38.buy_delivery_methods` configuration objects specified.
 
 <CodeExample>
 
@@ -63,122 +83,88 @@ assets:
     distribution_account: GBLSAHONJRODSFTLOV225NZR4LHICH63RIFQTQN37L5CRTR2IMQ5UEK7
     significant_decimals: 2
     sep6_enabled: true
+    sep38_enabled: true
+    sep38:
+      exchangeable_assets:
+        - iso4217:USD
     deposit:
       enabled: true
       methods:
-        - SEPA
-        - SWIFT
-        - cash
+        - ACH
     withdraw:
       enabled: true
       methods:
-        - bank_account
-        - cash
+        - ACH
   - schema: iso4217
     code: USD
     significant_decimals: 2
+    sep38_enabled: true
+    sep38:
+      exchangeable_assets:
+        - stellar:USDC:GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5
+      buy_delivery_methods:
+        - name: ACH
+          description: ACH debits for US bank accounts
+      sell_delivery_methods:
+        - name: ACH
+          description: ACH credit for US bank accounts
+
 ```
 
 </CodeExample>
 
-The information provided for the `assets` value closely maps to the information that will be exposed to the wallet application using the [`GET /info`][sep-6] SEP-6 endpoint. The Anchor Platform also uses this information to validate requests made to your service.
-
-## Enable the Customer KYC API
+### Managing Distribution Accounts
 
-Businesses need to collect and validate KYC information on the customers they're facilitating transactions for. Clients determine what KYC information needs to be collected and send that information via a SEP-12 KYC API hosted by the Anchor Platform, but the Anchor Platform never stores personally-identifiable information (PII). Instead, it forwards requests from clients to the business server, and returns the business' responses back to the client, acting as a proxy server.
+Note that the example above lists a `distribution_account` attribute for the USDC entry. If specified, this account will be provided along with a randomly generated and unique-per-transaction memo to clients as the address to send funds to for withdrawal transactions. The transaction's memo is how you or the Anchor Platform will match the funds received with a transaction record in the Anchor Platform's database.
 
-See the [Anchor Platform KYC API specification][platform-api-kyc] for details on the endpoints that must be implemented on your business' server.
+If you do not have your own Stellar account and instead use a third party that provides you a Stellar account and memo so they can receive funds on your behalf, such as an exchange or custodian, you should omit the `distribution_account` field from your assets config file. Instead, you'll need to provide the Stellar account and memo you'd like to use to receive funds through a request to the Anchor Platform's [`request_onchain_funds`][request-onchain-funds] on a per-transaction basis.
 
-To make this API available to clients, lets add the service URL to our Stellar Info File.
+To configure the Anchor Platform to expect the Stellar account and memo to be provided via API instead of configured via the assets file, specify the following environment variable.
 
 <CodeExample>
 
-```toml
-# dev.stellar.toml
-KYC_SERVER = "http://localhost:8080/sep12"
+```bash
+# dev.env
+SEP6_DEPOSIT_INFO_GENERATOR_TYPE=none
 ```
 
 </CodeExample>
 
-And enable it in our environment.
+If you use a wallet provider supported by the Anchor Platform's custody service, such as Fireblocks, you can also configure the Anchor Platform to connect directly to your wallet provider to fetch your distribution accounts and memos. If this is configured, the Anchor Platform will also use the wallet provider to send funds to customers. See the [custody services] section for more information about configuring this feature, but first you'll need to specify a different value for the above-mentioned environment variable.
 
 <CodeExample>
 
 ```bash
 # dev.env
-SEP12_ENABLED=true
+SEP6_DEPOSIT_INFO_GENERATOR_TYPE=custody
 ```
 
 </CodeExample>
 
-## Enable Asset Exchanges
-
-To enable asset exchanges using Stellar, follow the steps below to configure the relevant settings and ensure the services are properly integrated. SEP-6 facilitates deposit and withdrawal interactions, and enabling SEP-38 allows for quote-based exchange rates for these transactions.
+### Enable Callbacks to the Business Server
 
-Businesses need to provide their send-side counterparts with a [Rate][get-rates-api] API to check the exchange rates they're offering between the on-chain asset being used for settlement and the fiat asset being used to pay the recipient. If the rate is competitive, senders also need to be able to request a commitment to the rate currently being offered from business for a short period of time.
+Businesses need to collect and validate KYC information on the customers they're facilitating transactions for. Clients ask your business what KYC information needs to be collected and sends that information via the SEP-12 KYC API hosted by the Anchor Platform, but the Anchor Platform never stores personally-identifiable information (PII). Instead, it forwards requests from clients to the business server, and returns the business' responses back to the client, acting as a proxy server.
 
-The Anchor Platform provides the [SEP-38 RFQ API][sep38] to senders for this purpose
+Additionally, businesses need to provide clients with a [Rates][get-rates-api] API to check the exchange rates they're offering between the onchain and offchain assets supported by the business. If the rate is competitive, clients also need to be able to request a commitment to the rate currently being offered from business for a short period of time. Similarly to the KYC API, the Anchor Platform makes requests to your business server to fetch exchange rates and quotes and returns them to clients.
 
-Add Service URLs to the Stellar Info File
-
-<CodeExample>
-
-```toml
-# dev.stellar.toml
-ANCHOR_QUOTE_SERVER = "http://localhost:8080/sep38"
-```
-
-</CodeExample>
-
-And enable the API in your environment configuration file.
+To enable these requests to your business server, first you'll need to add your business server to the docker compose file. Then, to support requests to your business server from the Anchor Platform, you need to enable callbacks.
 
 <CodeExample>
 
 ```bash
 # dev.env
-SEP38_ENABLED=true
+CALLBACK_API_BASE_URL=http://business-server:3000/callbacks
+CALLBACK_API_AUTH_TYPE=jwt
+CALLBACK_API_AUTH_JWT_EXPIRATION_MILLISECONDS=30000
+CALLBACK_API_AUTH_JWT_HTTP_HEADER=Authorization
+SECRET_CALLBACK_API_AUTH_SECRET="a secret used to sign JWTs"
 ```
 
 </CodeExample>
 
-Finally, configure assets to include the exchangeable assets in the `sep38` section.
-
-<CodeExample>
-
-```yaml
-assets:
-  - schema: stellar
-    code: USDC
-    issuer: GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5
-    distribution_account: GBLSAHONJRODSFTLOV225NZR4LHICH63RIFQTQN37L5CRTR2IMQ5UEK7
-    significant_decimals: 2
-    sep6_enabled: true
-    deposit:
-      enabled: true
-      methods:
-        - SEPA
-        - SWIFT
-        - cash
-    withdraw:
-      enabled: true
-      methods:
-        - bank_account
-        - cash
-    sep38_enabled: true
-    sep38:
-      exchangeable_assets:
-        - iso4217:USD
-  - schema: iso4217
-    code: USD
-    significant_decimals: 2
-    sep38_enabled: true
-    sep38:
-      exchangeable_assets:
-        - stellar:USDC:GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5
-```
-
-</CodeExample>
+The above tells the Anchor Platform to include a JWT, signed with the configured secret, in the `Authorization` header of requests made to `/callbacks/<callback endpoint>` so your server can authenticate the Anchor Platform before processing requests.
 
+See the [KYC API][platform-api-kyc] and [Rates API][sep38] for details on the endpoints that must be implemented on your business' server.
 
 ## Test With the Demo Wallet
 
@@ -196,7 +182,7 @@ Wallets should now be able to discover, authenticate, and initiate transactions
 
 </CodeExample>
 
-Your environment should now look like the following.
+Your environment should now look something like the following.
 
 <CodeExample>
 
@@ -210,17 +196,22 @@ SEP1_TOML_TYPE=file
 SEP1_TOML_VALUE=/home/dev.stellar.toml
 
 SEP6_ENABLED=true
-SEP6_MORE_INFO_URL_BASE_URL=http://example.com
-SECRET_SEP6_MORE_INFO_URL_JWT_SECRET="your encryption key shared with your business server"
+SEP6_DEPOSIT_INFO_GENERATOR_TYPE=none
 
 SEP10_ENABLED=true
 SEP10_HOME_DOMAIN=localhost:8080
 SECRET_SEP10_SIGNING_SEED="a Stellar private key"
-SECRET_SEP10_JWT_SECRET="a secret encryption key"
+SECRET_SEP10_JWT_SECRET="a secret used to sign JWTs"
 
 SEP12_ENABLED=true
 
 SEP38_ENABLED=true
+
+CALLBACK_API_BASE_URL=http://business-server:3000/callbacks
+CALLBACK_API_AUTH_TYPE=jwt
+CALLBACK_API_AUTH_JWT_EXPIRATION_MILLISECONDS=30000
+CALLBACK_API_AUTH_JWT_HTTP_HEADER=Authorization
+SECRET_CALLBACK_API_AUTH_SECRET="a secret used to sign JWTs"
 ```
 
 </CodeExample>
@@ -243,3 +234,4 @@ The demo wallet should be able to find your `stellar.toml` file, authenticate us
 [get-rates-api]: ../../api-reference/callbacks/get-rates.api.mdx
 [sep38]: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0038.md
 [platform-api-kyc]: ../../api-reference/callbacks/customer/README.mdx
+[request-onchain-funds]: ../../api-reference/rpc/methods/request_onchain_funds/README.mdx