Getting Started

In this guide, you will learn to:

• create and fund a host distribution account that may be used to fund tenant-level distribution accounts or directly for making payments
• set up an instance of the Stellar Disbursement Platform (SDP) locally
• provision a new tenant and create login credentials for users belonging to tenant
• set up a Stellar account to accept funds as a receiver
• make your first disbursement
• register your receiver account with the SDP
• check your account balance after receiving payment

By the end of this guide, you'll have a clear understanding of the Stellar Disbursement Platform's functionality and a working local setup ready for development or testing.

Note that while we'll be using USDC and the Demo Wallet in this guide, other Stellar assets and wallets can be used in development or production.

Create and Fund a Host Distribution Account

You'll need a minimum of two accounts when using the Stellar Disbursement Platform, a distribution and receiver account. We'll create the distribution account now and will create the receiver account while making our first disbursment.

1. Go to the Stellar Demo Wallet and select "Generate keypair for new account"
2. Select the "Create account" button next to the public key to fund your account with XLM
3. Select the "Select from preset assets" button, and select USDC
4. Finally, select "Add trustline" to enable payments of USDC

Now that we have an account that can send & receive USDC, lets fund it with enough USDC for our first disbursement. You can fund your distribution account from any liquidity source of Stellar USDC but here's how do it through the Circle Sandbox and Stellar Lab.

1. Create a Circle Sandbox account
2. Once you're at the dashboard, Select "Get API Key", and copy it to your clipboard
3. Go to the Circle Sample App and enter your API key after selecting the settings icon in the top right corner
4. Select "Charge Flow", then "Prefill Form", and select a card to use (it doesn't matter which)
5. Enter the amount you'd like to purchase, then select "Make Payment"

This will fund your Circle Sandbox Account with USDC. You can repeat the process above when you run out or the test network resets, which happens quarterly.

Your USDC should appear in your account within a few minutes, which you can check using the balances endpoint. Once funded, you can send it to your distribution account created earlier.

1. Select the icon in the top left, then "Payouts API", and finally "POST /transfers"
2. Select "Get Master Wallet ID" to load the wallet funded with USDC
3. Enter the amount you'd like to send
4. Select the "blockchain" destination type and then "XLM"
5. Paste the public key of the account you created with the demo wallet earlier
6. Select "Make API Call"

Circle will submit payment of USDC to the Stellar test network and you should receive funds in your demo wallet account almost immediately!

You can also acquire USDC through the Stellar Lab if you prefer. Before starting, make sure your demo wallet account is funded with XLM and has a trustline to USDC. Build a transaction in the Lab with your demo wallet account as the source account. Create a Path Payment Strict Send operation with the same account as the destination account. Use XLM (native) as the sending asset and USDC issued by GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5 as the destination asset. You can set your preferred minimum destination amount based on how much XLM you send but the amount isn't important in testnet. A very low minimum will ensure the trade. Sign the transaction and submit to the network.

USDC will arrive in your demo wallet account within seconds! Refresh the account on the demo wallet page to see the new balance.

Run the SDP Locally

Prerequisites

Docker

Make sure you have Docker installed on your system. If not, you can download it from here.

Stellar Accounts

We will need two Stellar accounts to set up the SDP, one of which you already created above.

1. A Host Distribution account that will be used for sending funds to receivers. You should have just created this account using the Create and Fund a Host Distribution Account process above.
2. A SEP-10 account that will be used for authentication. It can be created the same way as the distribution account, but it doesn't need to be funded. Make sure to create this account now if you haven't already done so.

The public and private key of these two accounts will be used to configure the SDP in the next step.

Run the SDP

First you'll need to clone the project.

bash

git clone [email protected]:stellar/stellar-disbursement-platform-backend.git

Before we run the SDP, we need to configure it with the accounts created in the previous step.

bash

cd stellar-disbursement-platform-backend/dev

Create a .env file in the dev directory by copying the .env.example file:

bash

cp .env.example .env

Update the .env file with the public and private keys of the two accounts created in the previous step.

Execute the following command to create all the necessary Docker containers needed to run SDP as well as provision sample tenants:

bash

./main.sh

This will bring up the following services:

• sdp_v2_database: The main SDP and TSS database.
• anchor-platform-postgres-db: Database used by the anchor platform.
• anchor-platform: A local instance of the anchor platform.
• sdp-api: SDP service running on port 8000.
• sdp-tss: Transaction Submission service.
• sdp-frontend: SDP frontend service running on port 3000.
• kafka: Kafka service running on ports 9092, 9094(external).
• kafka-init: Initial workflow to exec into the Kafka container and create topics.
• demo-wallet: The demo wallet client that will be used as a receiver wallet, running on port 4000.

New Tenant Provisioning Process

When you ran main.sh file, you've already created new tenants: tenants=("redcorp" "bluecorp"). To add more tenants, simply append them separated by spaces to that variable like so: tenants=("redcorp" "bluecorp" "greencorp") and run main.sh again.

Be sure that the added tenant hosts are included in the host configuration file. To check it, you can run the command cat /etc/hosts. To include them, you can run command sudo nano /etc/hosts and insert the lines below:

127.0.0.1       bluecorp.stellar.local
127.0.0.1       redcorp.stellar.local

Setup Owner User Password for each tenant

Go through the forgot password flow to be able to login as an owner user.

Go to Forgot Password page on http://${tenant}.stellar.local:3000/forgot-password and enter the tenant and owner email owner@${tenant}.org.

A token will be generated, and it's possible to check it on sdp-api logs. This token will be needed to Reset Password on http://${tenant}.stellar.local:3000/reset-password.

Log In

Once the password for your target org user has been reset to one of your choice, navigate to the dashboard by opening a browser to localhost:3000 and login with the user account.

Click the Sign in button and the SDP Dashboard will open. You will have no disbursements data at this point.

Create Your First Disbursement

Navigate to the frontend service by opening a browser and going to http://bluecorp.stellar.local:3000.

• Click New Disbursement+ on the Dashboard screen.
• Use Demo Wallet as your wallet and choose a verification method.
• Upload a disbursement file. A template file can be downloaded at the frontend page when creating a disbursement, and the template will change according with the options set for that disbursement. You can also find the template files at public/resources/disbursementTemplates. Make sure to update the file before using it by changing the contact info to yours and removing the comment line.
• Finally, confirm the disbursement.

You also have the option of modifying the message in the receiver invite.

Deposit Money

To deposit money into your account:

• Access demo-wallet in your browser.
• Click on Generate Keypair for new account to generate a new keypair. Make sure to save your public key & secret if you want to use this account later.
• Click Create account (in front of public key) to actually create the account on the Stellar testnet.
• Your newly created account will have 10,000 XLM.
• Add your home domain to the account by clicking on Add Home Domain and entering http://bluecorp.stellar.local:8000.
• In the Select action dropdown, select SEP-24 Deposit.
• In the new window, enter the phone number from the disbursement CSV.
• Enter the passcode. You can use 000000 passcode or find the actual passcode in the sdp-api container logs.
• Enter the birthday that matches the phone number in the CSV.
• Keep an eye on the dashboard until the payment status reaches Success. If everything was set up correctly, your money should be disbursed successfully.

Troubleshooting

Distribution account out of funds

Payments will start failing if the distribution account runs out of funds. To fix this, you can either write a script that funds the distribution account or use the tools available to add more funds to the distribution account by following these steps:

• The distribution account address can be found under Distribution Account on the frontend sidebar. Copy that address.
• Access https://horizon-testnet.stellar.org/accounts/:accountId in your browser and check the balance.
• If the balance is indeed low, you can add more funds by creating a new account and sending funds to the distribution account.
  • Access demo-wallet.stellar.org in your browser.
  • Click on Generate Keypair for new account to create a new testnet account. Your account comes with 10,000 XLM.
  • Click on Send and enter the distribution account public key and the amount you want to send.
  • Using Freighter or Stellar Lab, swap the XLM for USDC if you wish to test with USDC.

Verify Your Identity

When a disbursement is created, the SDP attempts to send a message to receivers using either Twilio/AWS for SMS or email, according to the contact type associated with the user. This message includes a link to the wallet application selected when creating the disbursement, and should direct the receiver to install the wallet app, go through the wallet's onboarding flow, and finally register with the SDP.

info

Please notice that the initial configuration has SMS_SENDER_TYPE=DRY_RUN and EMAIL_SENDER_TYPE=DRY_RUN, which means the messages will be printed in the logs (of the sdp-api container) instead of being sent.

Check out the Email and SMS Messages section to learn how to configure messaging in the SDP. When you do, and another disbursement is created, you should get a message like the following.

Create a Receiver Account

Clicking on initation message link will take the receiver to the demo-wallet, where they'll need to create an account to be used to receive the USDC payment. Follow the same process described earlier to create the account and add a USDC trustline.

Initiate SEP-24 Webflow

Now we'll need to connect the demo wallet to the SDP instance running locally. To do that, select the pencil icon next to "centre.io" below your USDC balance and enter "localhost:8080".

In the "Select Action" dropdown, select "SEP-24 Deposit" to initiate a SEP-24 webflow, which triggers the User Registration process to link the new wallet to the phone number in the SDP.

A SEP-24 interactive window will appear, where the receiver can select the contact info type (e.g. phone number or email) that is registered for them in the SDP database.

In the next SEP-24 screen the user should enter the contact info data (phone number or email) from the disbursement CSV.

Next, enter the passcode and the verification field that you used in the disbursement file. Note: use 000000 for this example (or 999999 if you want to see an error response).

The webflow provides a message indicating your successful registration, which is the trigger for the SDP to send the payment. You should receive your payment from the SDP shortly.

Check Your Balance

Refresh your account. The Demo Wallet should now show a balance of 2 USDC sent from the SDP (or however much was defined in the CSV file).

Keep an eye on the dashboard until the payment status reaches Success. If everything was set up correctly, your money should be disbursed successfully.

Next Up: Updating Application Secrets

Now that you've been able to make a disbursement, let's go back to our docker compose files and update some values. This is an important step before going to production. We'll be updating encryption keys and application secrets.

Email and SMS Messages

The Stellar Disbursement Platform sends emails to users and SMS/emails to receivers. For SMS messages, the Stellar Disbursement Platform supports Twilio, AWS SNS, and a dry run mode that just logs the messages. For emails, it supports AWS SES, Twilio SendGrid, and dry run.

These services can be selected through the SMS_SENDER_TYPE and EMAIL_SENDER_TYPE configurations. When selecting Twilio or AWS services, you'll need to fill their service-specific configuration as well. Below there are some example configurations, and you can mix and match the services as you see fit.

Dry Run Configuration

Dry run mode is useful for testing the SDP without sending real messages. It will log the messages to the console instead of sending them to the receiver. This is the default configuration and it works for both SMS and Email.

YAML

EMAIL_SENDER_TYPE: DRY_RUN
SMS_SENDER_TYPE: DRY_RUN

Twilio SMS Configuration

YAML

SMS_SENDER_TYPE: TWILIO_SMS

# Twilio specific configuration
TWILIO_ACCOUNT_SID:
TWILIO_AUTH_TOKEN:
TWILIO_SERVICE_SID:

Twilio Email (Send Grid) Configuration

YAML

SMS_SENDER_TYPE: TWILIO_EMAIL

# Twilio specific configuration
TWILIO_SENDGRID_API_KEY:
TWILIO_SENDGRID_SENDER_ADDRESS:

AWS SMS Configuration

YAML

SMS_SENDER_TYPE: AWS_SMS

# AWS specific configuration.
# This is needed for both AWS Email and SMS
AWS_ACCESS_KEY_ID:
AWS_REGION:
AWS_SECRET_ACCESS_KEY:

# AWS SNS configuration
AWS_SNS_SENDER_ID:

AWS Email Configuration

YAML

EMAIL_SENDER_TYPE: AWS_EMAIL

# AWS specific configuration.
# This is needed for both AWS Email and SMS
AWS_ACCESS_KEY_ID:
AWS_REGION:
AWS_SECRET_ACCESS_KEY:

# AWS SNS configuration
AWS_SES_SENDER_ID:

Authentication

Wallets authenticate with the Stellar Disbursement Platform using a mutual authentication protocol, where both the SDP and wallet prove they are in possession of their Stellar accounts by signing a payload exchanged between themselves. Once this process is complete, a JWT is provided to the wallet to use in future requests. Additionally, the SDP's microservices uses authentication tokens to communicate between themselves, and to encrypt user passwords. We need to provide updated values for all these use cases.

In docker-compose-sdp-anchor.yml, update the following:

YAML

# The public key of the Stellar account used for SEP-10 authentication:
SEP10_SIGNING_PUBLIC_KEY:
#
# The private key of the Stellar account used for SEP-10 authentication. It
# should be the same secret key for both attributes below, for the Stellar
# Disbursement Platform and Anchor Platform:
SEP10_SIGNING_PRIVATE_KEY:
SECRET_SEP10_SIGNING_SEED:
#
# The encryption key used to sign the resulting SEP-10 JWT token:
SECRET_SEP10_JWT_SECRET:
#
# A shared encryption key used to sign JWT tokens in the SEP-24 from the Anchor
# Platform to the Stellar Disbursement Platform. The value needs to be the same
# for all three attributes below:
SEP24_JWT_SECRET:
SECRET_SEP24_INTERACTIVE_URL_JWT_SECRET:
SECRET_SEP24_MORE_INFO_URL_JWT_SECRET:
#
# A shared encryption key used to sign JWT tokens in the PlatformAPI
# communications from the Stellar Disbursement Platform to the Anchor Platform.
# The value needs to be the same for both attributes below:
ANCHOR_PLATFORM_OUTGOING_JWT_SECRET:
SECRET_PLATFORM_API_AUTH_SECRET:
#
# The private key is used to sign JWT tokens for authenticating the requests
# incoming to the Stellar Disbursement Platform. The Public key is used to
# validate that the JWT token was signed by the SDP's private key. They can be
# generated with these commands:
# openssl ecparam -name prime256v1 -genkey -noout -out ec_private_key.pem
# openssl pkcs8 -topk8 -nocrypt -in ec_private_key.pem -out ec_private_key_pkcs8.pem
# openssl ec -in ec_private_key.pem -pubout -out ec_public_key.pem
EC256_PUBLIC_KEY:
EC256_PRIVATE_KEY:
#

There are many other configuration values to update when moving to a production environment, such as database credentials, URLs, and more.

Level Up

Custom Assets and Wallets

The SDP contains a list of assets and wallets available for disbursements out-of-the-box. You might want to customize these, either to limit/expand options or to prepare for going live in production. Now that you've made a disbursement and added application secrets, let's look at how to customize the new disbursement options.

Assets

You can add and remove assets easily in the SDP dashboard. The SDP backend handles the request seamlessly, including checking for outstanding balance and adding/removing trustlines on the Stellar network. When assets are removed, the record is still retained in the database to preserve a full history. However, the asset will no longer be available for disbursements or holding a balance in the distribution account.

Head to the Wallets page of the SDP dashboard to add and remove assets. You'll need the Stellar asset code and the public key of the asset issuer.

caution

Please make sure to update the appropriate configuration on the Anchor Platform side, according with the Anchor Platform Integration Points guide.

Wallets

For a full overview on how to add wallets and how to make a wallet SDP-compatible, check out the Making Your Wallet SDP-Ready guide.

Wallet Address Registration

Since version 3.0.0, the SDP can pay directly to Stellar wallet addresses rather than directing the receivers through the registration flow. This is useful for organizations that are paying receivers who already have Stellar wallets and don't need to create a new one.

To use this feature, follow these steps:

1. Make sure the User Managed Wallet is enabled at the Wallet Providers section (also available at GET /wallets).
2. If it's not enabled, you can update it through the UI dashboard or with PATCH /wallets/{id}.
3. Now you can create a disbursement and select from the registration Contact Type dropdown an option that contains Walet Address` in the name.
4. Prepare the CSV file according with the CSV sample associated with your disbursement configuration.
5. Upload the CSV file and confirm the disbursement as usual. The SDP will send the payment directly to the wallet addresses provided in the CSV ✅.