Note: you can find a more thorough and user-friendly documentation of this project at Stelar Docs.
The Stellar Disbursement Platform (SDP) enables organizations to disburse bulk payments to recipients using Stellar.
Throughout this documentation, we'll define "users" as members of the organization using the SDP to make payments, while defining "recipients" as those receiving payments.
Install golang and make sure $GOPATH/bin is in your $PATH. Then run the following.
git clone [email protected]:stellar/stellar-disbursement-platform-backend.git
cd stellar-disbursement-platform-backend
make go-install
stellar-disbursement-platform --helpTo quickly test the SDP using preconfigured values, see the Quick Start Guide.
The SDP Dashboard and Anchor Platform components are separate projects that must be installed and configured alongside the services included in this project.
In a future iteration of this project, the Transaction Submission Service (TSS) will also be moved to its own repository to be used as an independent service. At that point, this project will include the services contained in the Core module shown in the diagram above.
The SDP Core service include several components started using a single command.
stellar-disbursement-platform serve --helpThe Dashboard API is the component responsible for enabling clients to interact with the SDP. The primary client is the SDP Dashboard, but other clients can use the API as well.
The Dashboard API component is also responsible for exporting system and application metrics. We only have support for Prometheus at the moment, but we can add new monitors clients in the future.
The Message Service sends messages to users and recipients for the following reasons:
- Informing recipients they have an incoming disbursement and need to register
- Providing one-time passcodes (OTPs) to recipients
- Sending emails to users during account creation and account recovery flows
Note that the Message Service requires that both SMS and email services are configured. For emails, AWS SES is supported. For SMS messages to recipients, Twilio is supported. AWS SNS support is not integrated yet.
If you're using the AWS_EMAIL sender type, you'll need to verify the email address you're using to send emails in order to prevent it from being flagged by email firewalls. You can do that by following the instructions in this link.
The Wallet Registration UI is also hosted by the Core server, and enables recipients to confirm their phone number and other information used to verify their identity. Once recipients have registered through this UI, the Transaction Submission Server (TSS) immediately makes the payment to the recipients registered Stellar account.
For a full understanding on how the Core and Anchor Platform components interact, as well as the best security and configuration practices, please refer to the Anchor Platform Integration Points section of the Stellar Docs.
Refer to documentation here.
Currently, Core and Transaction Submission Service (TSS) interact at the database layer, sharing the submitter_transactions table to read and write state. The interaction is as follows:
- Core inserts rows into the
submitter_transactionstable, queuing payments - The TSS polls the
submitter_transactionstable, detecting payments - For each payment detected, the TSS creates and submits a transaction to the Stellar network, monitoring its state until it is confirmed to have been included in a ledger or failed with a nonrecoverable error
- Core's Dashboard API reads from the
submitter_transactionstable on demand to fetch the state of each payment
In future iterations of the project, the Transaction Submission Service will provide an API for clients such as the SDP to use for queuing and polling the state of transactions.
To manage the migrations of the database, use the db subcommand.
stellar-disbursement-platform db --helpNote that there is an auth subcommand that has its own migrate sub-subcommand. Operators of the SDP will need to ensure migrations for both the core and auth components are run.
stellar-disbursement-platform db migrate up
stellar-disbursement-platform db auth migrate upThe tables below are used to facilitate disbursements.
The tables below are used to manage user roles and organizational information.
The tables below are shared by the transaction submission service and core service.
Note that the submitter_transactions table is used by the TSS and will be managed by the service when moved to its own project.
Please check the Making Your Wallet SDP-Ready section of the Stellar Docs for more information on how to integrate your wallet with the SDP.
This section is a work-in-progress.
The state transitions of a disbursement, payment, message, and wallet (i.e. recipient Stellar account) are described below.
stateDiagram-v2
[*] --> Draft:Started creating the disbursement
Draft --> [*]:User deleted\nthe draft
Draft --> Draft:File Ingestion failed\n due to wrong data
Draft --> Ready:Upload
Ready --> Started:User Started Disbursement\n in the Dashboard
Started --> Paused:Paused
Paused --> Started:Unpaused
Started --> Completed:All payments\n went through
stateDiagram-v2
[*] --> Draft:Upload a disbursement CSV
Draft --> [*]:Disbursement deleted
Draft --> Ready:Disbursement started
Ready --> Paused:Paused
Paused --> Ready:Unpaused
Ready --> Pending:Payment gets submitted\nif user is ready
Pending --> Success:Payment succeeds
Pending --> Failed:Payment fails
Failed --> Pending:Retry
stateDiagram-v2
[*] --> Draft:Upload disbursement CSV
Draft --> [*]:disbursement deleted
Draft --> Ready: Disbursement started
Ready --> Registered: receiver signed up
Ready --> Flagged: flagged
Flagged --> Ready: unflagged
Registered --> Flagged: flagged
Flagged --> Registered: unflagged
stateDiagram-v2
[*] --> Pending: Message is queued
Pending --> Success:Message sender\nAPI succeeds
Pending --> Failed:Message sender\nAPI fails
Failed --> Pending:Retry