The Stellar Development Foundation recently announced the launch of Stellar Aid Assist, a new disbursement program utilizing the Stellar network and enabling aid organizations deliver cash assistance to vulnerable populations quickly and transparently. 

Stellar Aid Assist is powered by the Stellar Disbursement Platform (SDP), an application built for organizations that need to send payments to large numbers of recipients, enabling a variety of use cases such as payroll, charitable donations, & government social payments.

In this blog post, we’ll dive into the technical details of how the SDP works & how it is used today for Stellar Aid Assist.

How it works

Architecture & Deployment

‍

The Stellar Disbursement Platform is composed of four services.

• A web service hosting the API consumed by the organization (UI Server)
• A web service hosting the API consumed by wallets & custodians (Vendor Server)
• A process for ingesting payment instructions & sending payments (Payments Processor)
• A cron job for inviting new recipients to the program (SMS Processor)

The original deployment of the platform uses kubernetes, but the platform can be deployed on any infrastructure that supports docker. Each component requires a set of environment variables used to enable or disable specific features, authenticate with service providers, and secure the application. All components use a relational database to share state, such as newly registered recipients and in-progress payments.

Sending payment instructions

The organization initiates a disbursement by uploading a file containing payment instructions to an internal file server. The current iteration of the platform supports the XML file format and uses the following schema.

{% code-line %}<?xml version="1.0" encoding="utf-8"?>
<PaymentInstructions id="">
    <Payment id="">
        <ContactInfo></ContactInfo>
        <ExtraIdentityInfo></ExtraIdentityInfo>
        <Amount></Amount>
    </Payment>
</PaymentInstructions>{% code-line-end %}

Future iterations of the SDP may support different secure file formats or an API for communicating payment instructions.

The recipient's contact information (phone number) is used to identify and invite them to install Vibrant, a mobile wallet app that supports Stellar assets, if they haven’t already. Extra identity information is specified as an additional layer of security.

When these files are uploaded, the platform automatically detects the presence of a new instructions file and downloads it to begin processing. If any validation or parsing errors occur while processing the file, those errors are included in a “payment receipts” file uploaded back to the file server. The organization can pull these receipt files down at any time and upload another instructions file with corrected information.

Registering recipients

If any of the recipients have already been registered with the platform, payments are immediately disbursed to the recipient’s wallet using the organization’s custodial service. This process is detailed in the Making payments section. For first-time recipients, the platform sends an invitation to download the Vibrant app. 

Integrating with the SDP is easy, as we’ll detail below, so any wallet application that supports sending & receiving Stellar assets can quickly become compatible.

Digital wallet applications like Vibrant check if users are eligible for payments by making an authenticated request to the disbursement platform’s GET /account endpoint, including the hashes of the recipient's contact & identify info in the request body. 

It is up to the wallet provider to determine whether or not to check if a user is eligible for payments. Some examples include using the user’s location or simply enabling the user to initiate an eligibility check.

{% code-line %}{
    "hashed_contact_info": "",
    "hashed_extra_identity_info": ""
}{% code-line-end %}

If the hashes provided exist in the SDP’s database, the platform responds with a confirmation that the recipient is eligible. Note that the application does not check for eligibility or ask for the necessary identity info until it has verified the recipient’s contact information.

If eligible, the wallet application creates a non-custodial Stellar account for the recipient if one does not exist already. Non-custodial wallets are Stellar accounts that only the recipient has access to, ensuring that payments are delivered directly to recipients without having to trust another organization to manage their funds or losing value to an intermediary anywhere in the process.

Once a Stellar account has been created, the wallet application can register the account’s public key with the disbursement platform.

{% code-line %}{
    "hashed_contact_info": "",
    "hashed_extra_identity_info": "",
    "public_key": "G..."
}{% code-line-end %}

That's it! The Stellar Disbursement Platform will save the recipient's public key to the database and queue their pending payments to be made. From this point on, the wallet public key is linked to the recipient in the SDP. Subsequent payments will also be disbursed immediately after processing the payment instructions since the SDP already knows where to send the funds.

Future iterations of the platform may allow recipients to register multiple wallets with the SDP. 

Making payments

In the current iteration, the Stellar Disbursement Platform uses Circle to custody funds for aid organizations and its APIs to transfer funds to recipients. Future iterations will likely support additional custodial services & provide a self-custody alternative for organizations.

Using a custodian:

Without a custodian:

‍

‍

Regardless of the custodial service or model used, the SDP's payment processing system prioritizes throughput using a concurrent transaction submission strategy. This makes the platform ideal for sending any form of bulk payments. The underlying properties of the Stellar network make the platform easily able to scale to meet enterprise needs.

The Stellar network is capable of processing an average of 200 payments per second. A ledger is closed every 5 seconds (on average) and ledgers are currently configured to include a maximum of 1000 operations per ledger. Check out realtps.net to see TPS metrics for Stellar & other blockchains.

Custodial services may have their own additional constraints based on the architecture of their internal payment processing system. Some services submit one transaction per ledger, for example. The Stellar network prioritizes transactions based on the fee offered to include them in a ledger. As such, another constraint may be the network fee offered by the custodian for including transactions. Fortunately, Stellar’s transaction fees are extremely low, costing a fraction of a US cent. For the last 30 days (as of Dec. 2022), fees averaged out to 0.0003137 XLM per transaction, or about $0.00003.

When payments are ready to be made, either after processing a payment instructions file or after a recipient registers their public key, the SDP immediately requests the payment to be executed and begins listening for updates from the custodial service or Stellar network.

Using Circle’s APIs, payments are requested using the POST /transfers endpoint, and status updates are provided in real-time through Circle’s SNS notifications. To ensure the platform is resilient to notification delivery failure, it will also fetch updates from Circle’s GET /transfers/:id endpoint after a configured amount of time has elapsed without receiving an update.

From the recipient’s perspective, they receive their payment within seconds of signing up for Vibrant or the SDP file upload (for repeat recipients). In the case of subsequent or recurring payments, notifications will be sent to the recipient through the application’s typical channels so they know a payment has arrived.

Monitoring payment distribution

All the activity described above can be monitored by organizations using the SDP's user interface or REST API. Organization stakeholders can log in to the UI and view past and current disbursements, recipients eligible and registered, and the payments queued and already processed.

Organizations using the Stellar Disbursement Platform today have also developed internal reporting tools that leverage the platform’s API for additional monitoring & analytics. All the SDP data is available for consumption so that organizations can build reporting & analytics tools that make sense for them. The current iteration of the platform hosts the following endpoints:

Over time, the SDP will continue to improve its monitoring, reporting, and analytics capabilities!

Conclusion

The Stellar Disbursement platform is in production today, helping recipients who require cash assistance to get it quickly while providing transparency & keeping costs low for aid organizations. It is an extremely powerful platform that will only continue to improve.

The Stellar Development Foundation plans to open source a multi-use version of the platform by the end of Q2 2023.

If you or your organization are interested in utilizing this technology for your own use case, please contact [email protected].