Skip to main content
Version: Next

Configuration

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.

# dev.env
SEP6_ENABLED=true
SEP12_ENABLED=true
SEP38_ENABLED=true

Modify a Stellar Info File

Let's modify the stellar.toml file created earlier. 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.

# dev.stellar.toml
ACCOUNTS = ["add your public keys for your distribution accounts here"]
SIGNING_KEY = "add your signing key here"
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]]
code = "USDC"
issuer = "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5"
status = "test"
is_asset_anchored = false
desc = "USD Coin issued by Circle"

[DOCUMENTATION]
ORG_NAME = "Your organization"
ORG_URL = "Your website"
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.

Modify the Assets Configuration 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.

The methods specified in the sep38 sections are methods that will be exposed by the SEP-38 GET /info endpoint.

The methods specified in the deposit and withdraw sections are the methods that will be exposed by the SEP-6 GET /info endpoint. The methods listed should match the methods defined in the SEP-38 section of the file.

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.

assets:
- schema: stellar
code: USDC
issuer: GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5
distribution_account: GBLSAHONJRODSFTLOV225NZR4LHICH63RIFQTQN37L5CRTR2IMQ5UEK7
significant_decimals: 2
sep6_enabled: true
sep38_enabled: true
sep38:
exchangeable_assets:
- iso4217:USD
deposit:
enabled: true
methods:
- ACH
withdraw:
enabled: true
methods:
- 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

Managing Distribution Accounts

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.

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 on a per-transaction basis.

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.

# dev.env
SEP6_DEPOSIT_INFO_GENERATOR_TYPE=none

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.

# dev.env
SEP6_DEPOSIT_INFO_GENERATOR_TYPE=custody

Enable Callbacks to the Business Server

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.

Additionally, businesses need to provide clients with a Rates 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.

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.

# dev.env
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"

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 and Rates API for details on the endpoints that must be implemented on your business server.

Additional Optional Configuration

more_info_url is an optional URL provided by your business server for wallet applications to display information about previously initiated transactions. This URL is typically used by wallets in their transaction history views, and your business can specify the information to be displayed about the transaction.

# dev.env
SEP6_MORE_INFO_URL_BASE_URL=http://example.com
SECRET_SEP6_MORE_INFO_URL_JWT_SECRET="your encryption key shared with your business server"

Businesses can set a deadline for user actions on transactions using the user_action_required_by field. For examples, see JSON-RPC Methods. In addition, the initial_user_deadline_seconds parameter sets a default time (in seconds) a user has to act before the transaction moves into the EXPIRED status.

# dev.env
SEP6_INITIAL_USER_DEADLINE_SECONDS=1209600

Test With the Demo Wallet

Wallets should now be able to discover, authenticate, and initiate transactions with your service! Your project and source files should now look something like this.

├── dev.env
├── docker-compose.yaml
├── config
│ ├── dev.assets.yaml
│ ├── dev.stellar.toml

Your environment should now look something like the following.

# dev.env
ASSETS_TYPE=file
ASSETS_VALUE=/home/dev.assets.yaml

SEP1_ENABLED=true
SEP1_TOML_TYPE=file
SEP1_TOML_VALUE=/home/dev.stellar.toml

SEP6_ENABLED=true
SEP6_DEPOSIT_INFO_GENERATOR_TYPE=none
SEP6_MORE_INFO_URL_BASE_URL=http://example.com
SECRET_SEP6_MORE_INFO_URL_JWT_SECRET="your encryption key shared with your business server"

SEP10_ENABLED=true
SEP10_HOME_DOMAIN=localhost:8080
SECRET_SEP10_SIGNING_SEED="a Stellar private 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"

To test this out, go to the Stellar Demo Wallet.

Initiate a deposit transaction by doing the following:

  • Create a new keypair
  • Click the "Add Asset" button and enter
    • the code of the Stellar asset on your stellar.toml file
    • your home domain, localhost:8080
  • Select the dropdown and click "SEP-6 Deposit", then click "Start"

The demo wallet should be able to find your stellar.toml file, authenticate using the Stellar keypair you just created, and initiate a transaction.