-
Notifications
You must be signed in to change notification settings - Fork 128
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* first sections * add images * finish getting started * dashboard home * add other UI pages * add links * tweaks * edit verbiage
- Loading branch information
1 parent
7d18844
commit e3890cd
Showing
36 changed files
with
397 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| { | ||
| "position": 85, | ||
| "label": "Use the Stellar Disbursement Platform", | ||
| "link": { | ||
| "type": "generated-index" | ||
| } | ||
| } |
27 changes: 27 additions & 0 deletions
27
docs/stellar-disbursement-platform/design-and-architecture.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,27 @@ | ||
| --- | ||
| title: Design and Architecture | ||
| sidebar_position: 20 | ||
| --- | ||
|
|
||
| The Stellar Disbursement Platform consists of four services deployed together: | ||
|
|
||
| - **Dashboard**: the user interface administrators use to initiate and track the progress of disbursements | ||
| - **SDP Core Service**: the core backend service that performs several functions: | ||
| - **Dashboard API**: the API used by the front-end UI for all disbursement requests | ||
| - **Messaging Service**: a recurring process that sends text messages to users prompting them to download the wallet selected for a particular disbursement and verify their phone with an OTP | ||
| - **Wallet Registration UI**: a web application that collects and verifies the recipient’s OTP code and verification information via Stellar’s [SEP-24: Hosted Deposit and Withdrawal](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0024.md) protocol | ||
| - **Anchor Platform Service**: the API server that the wallet uses to authenticate and initiate the recipient’s registration process through the SEP-24 deposit flow | ||
| - **Transaction Submission Service**: the service that submits all payment transactions to the Stellar network. This service is designed to maximize payment throughput, handle queuing, and graceful resubmission/error handling | ||
|
|
||
| ## Dependencies {#dependencies} | ||
|
|
||
| - **Container Orchestration**: the SDP is packaged as Docker containers and can be deployed to Kubernetes or AWS Fargate. SDF provides a Helm Chart for Kubernetes | ||
| - **Postgres**: the SDP uses a Postgres database server for all of its services | ||
| - **Twilio or AWS SNS and SES**: the SDP’s messaging service uses SMS messages via Twilio or AWS SNS and administrative emails for organization account setup and recovery via AWS SES | ||
| - **Stellar Accounts**: | ||
| - Distribution Account: the SDP requires access to a funded Stellar account to make payments to the recipient | ||
| - SEP-10 Auth Account: the SDP requires a Stellar account for the mutual authentication protocol [SEP-10: Stellar Web Authentication](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0010.md) used to connect to wallet applications | ||
|
|
||
| ## Architecture Diagram | ||
|
|
||
|  |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,185 @@ | ||
| --- | ||
| title: Getting Started | ||
| sidebar_position: 30 | ||
| --- | ||
|
|
||
| ## Set Up the Development Environment (BASH) | ||
|
|
||
| In this guide, we'll help you set up your local workstation with a complete end-to-end development environment using docker-compose, Stellar demo-wallet, USDC on Stellar, and Stellar Testnet. Let’s bring up all the services. | ||
|
|
||
| Disclaimer: USDC and the [Demo Wallet](https://demo-wallet.stellar.org/) are used in the following walk-through demo as an example asset and wallet, though they are not the only options. | ||
|
|
||
| ### 1. Configure SDP secrets | ||
|
|
||
| Before bringing up the services, make sure the secrets that the Stellar Disbursement Platform will use are configured. | ||
|
|
||
| 1. Create the Stellar account used for SEP-10 authentication and configure the following values in docker-compose-sdp-anchor.yml | ||
|
|
||
| **SDP** | ||
| `SEP10_ACCOUNT` | ||
| `SEP10_SIGNING_PUBLIC_KEY` | ||
| `SEP10_SIGNING_PRIVATE_KEY` (secret) | ||
|
|
||
| **Anchor** | ||
| `SECRET_SEP10_SIGNING_SEED` (secret) | ||
|
|
||
| 2. Create a Stellar account and fund it with the digital asset you will send in your disbursement (ex: USDC). This account will be used as the Distribution Account. Configure the following values in docker-compose-sdp-anchor.yml | ||
|
|
||
| **SDP** | ||
| `DISTRIBUTION_PUBLIC_KEY` | ||
|
|
||
| **Anchor** | ||
| `ASSETS_VALUE.assets.distribution_account` | ||
|
|
||
| **TSS** | ||
| `DISTRIBUTION_SEED` (secret) | ||
|
|
||
| 3. **Optional for testnet but must be done in production**: Get a Google Recaptcha site key/secret and configure the following values in docker-compose-sdp-anchor.yml | ||
|
|
||
| **SDP** | ||
| `RECAPTCHA_SITE_KEY` | ||
| `RECAPTCHA_SITE_SECRET_KEY` (secret) | ||
|
|
||
| :::note | ||
|
|
||
| Current keys configured in the docker images are [Google ReCAPTCHA v2 test keys](https://developers.google.com/recaptcha/docs/faq#id-like-to-run-automated-tests-with-recaptcha.-what-should-i-do). Feel free to use these for testnet. | ||
|
|
||
| ::: | ||
|
|
||
| ### **Optional**: Configure your SMS provider | ||
|
|
||
| Configure either your Twilio or AWS SNS SMS configuration settings to receive a SMS for registration in the file. Example for Twilio: set the following values in the docker-compose-sdp-anchor.yml file. | ||
|
|
||
| TWILIO_ACCOUNT_SID | ||
| TWILIO_AUTH_TOKEN | ||
| TWILIO_SERVICE_SID | ||
|
|
||
| In order to use Twilio, we also have to set the following environment variable: MESSAGE_SENDER_TYPE: TWILIO_SMS | ||
|
|
||
| ### 2. Configure sdp-api and Anchor Platform hosts | ||
|
|
||
| Add the following two hosts to your `/etc/hosts` file: | ||
|
|
||
| <pre class="prettyprint">127.0.0.1 sdp-api</pre> | ||
|
|
||
| <pre class="prettyprint">127.0.0.1 anchor-platform</pre> | ||
|
|
||
| ### 3. Bring SDP services up via docker-compose | ||
|
|
||
| From the stellar-disbursement-platform-backend main directory, navigate to the dev directory in the repository and bring all SDP services up and running using docker-compose. | ||
|
|
||
| <pre class="prettyprint">cd dev</pre> | ||
|
|
||
| <pre class="prettyprint">make all</pre> | ||
|
|
||
| Your window will contain the logs from all services, making it easy to follow system behavior across all services. | ||
|
|
||
|  | ||
|
|
||
| ### 4. Create organization owner | ||
|
|
||
| Next we need to create an organization owner account with privileges (role) to use the SDP. We will use the SDP CLI to add the user. Connect to the sdp-api container and create an owner account. | ||
|
|
||
| <CodeExample> | ||
|
|
||
| ```html | ||
| ❯ docker exec -it sdp-api bash` root@a7437e9ed3ca:/app#` | ||
| ./stellar-disbursement-platform auth add-user [email protected] joe yabuki | ||
| --password --owner --roles owner DEBU[2023-06-28T05:46:44.868Z] Setting log | ||
| level to: "TRACE" pid=45 INFO[2023-06-28T05:46:44.868Z] Version: 0.2.0 pid=45 | ||
| INFO[2023-06-28T05:46:44.868Z] GitCommit: pid=45 ✔ Password: ***** | ||
| INFO[2023-06-28T05:46:48.132Z] user inserted: [email protected] pid=45 | ||
| root@a7437e9ed3ca:/app# | ||
| ``` | ||
|
|
||
| </CodeExample> | ||
|
|
||
| ### 5. Log in with your account | ||
|
|
||
| Now that you have created an owner account, navigate to the dashboard by opening a browser to [localhost:3000](http://localhost:3000/) and login with the account you just created. | ||
|
|
||
|  | ||
|
|
||
| Click the Sign in button and the SDP Dashboard will open. You will have no disbursements data at this point. | ||
|
|
||
|  | ||
|
|
||
| ### 6. Create your first disbursement | ||
|
|
||
| Create your first disbursement by clicking the New Disbursement button. Use Demo Wallet as your wallet and USDC as your asset. You can choose whatever values you like for Country and Name. Then upload your disbursement file with receiver information. A sample file is available in the /dev/sample directory. Make sure to edit the file with a valid phone number that you have access to before using it. | ||
|
|
||
|  | ||
|
|
||
| <CodeExample> | ||
|
|
||
| ```html | ||
| ❯ cd stellar-disbursement-platform-backend/dev ❯ cat | ||
| sample/sample-disbursement.csv phone,id,amount,verification | ||
| +15551231234,4ba1,2,1987-12-01 | ||
| ``` | ||
|
|
||
| </CodeExample> | ||
|
|
||
| The phone number is the mobile number that the registration SMS message will be sent to. | ||
|
|
||
| Review and confirm the disbursement. | ||
|
|
||
|  | ||
|
|
||
| ### 7. Verify your identity | ||
|
|
||
| You should receive an SMS message containing the link, enabling you to verify your identity with the information from the CSV and register with the SDP. Note: If you do not have an SMS provider configured for your development environment, you can find the URL in the logs. | ||
|
|
||
|  | ||
|
|
||
| ### 8. Create a Stellar account | ||
|
|
||
| Click the link to open the Stellar Demo Wallet application in your web browser. Since the Demo Wallet functions differently than live wallet service providers, you must first create a Stellar account by clicking on Generate Keypair for new account (testnet only). This step is handled automatically by production Stellar wallets. | ||
|
|
||
|  | ||
|
|
||
| Next, click Create Account (in front of public key) | ||
|
|
||
|  | ||
|
|
||
| ### 9. Add USDC | ||
|
|
||
| Click the Add Asset button and input the following values: | ||
|
|
||
| **ASSET CODE**: USDC | ||
| **ANCHOR HOME DOMAIN**: localhost:8080 | ||
| **ISSUER PUBLIC KEY**: GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5 | ||
|
|
||
|  | ||
|
|
||
| Next, click Add Trustline for the USDC asset you added above. This will enable your account to receive USDC from the SDP. | ||
|
|
||
|  | ||
|
|
||
| ### 10. Initiate SEP-24 webflow | ||
|
|
||
| Now beside USDC, 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. This simulates the wallet application popup you would see on your mobile phone. Enter the phone number from the disbursement CSV. | ||
|
|
||
|  | ||
|
|
||
| Next, enter the passcode and birthday that you used in the payment 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. | ||
|
|
||
|  | ||
|
|
||
| ### 11. Show 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. | ||
|
|
||
|  |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| --- | ||
| title: Overview | ||
| sidebar_position: 10 | ||
| --- | ||
|
|
||
| The Stellar Disbursement Platform (SDP) is a tool built for organizations to make bulk payments to a group of recipients over the Stellar network. The full step-by-step process usually looks something like the following after the SDP is deployed and organizational users have been set up: | ||
|
|
||
| 1. The organization funds the SDP’s distribution account with a Stellar-based asset (e.g. USDC) | ||
| 2. An administrator logs in to the SDP’s dashboard and uploads a CSV file containing the payment information to initiate a new disbursement | ||
| 3. The SDP sends a text message to every first-time recipient in the CSV inviting them to download a Stellar-enabled wallet application | ||
| 4. Meanwhile, the SDP immediately begins making payments to each recipient that has already registered a wallet through a prior payment | ||
| 5. Each first-time recipient clicks a deep link to download the Stellar-enabled wallet application chosen by the organization for this disbursement, downloads the app, and goes through the wallet sign-up process | ||
| 6. Once the recipient has signed up and their Stellar account has been created, the wallet immediately authenticates with the SDP using parameters from the deep link and opens the SDP registration web view for the recipient to complete verification | ||
| 7. The user confirms their identity by providing an OTP code sent to their phone number and an additional piece of verification information for security purposes. The SDP supports three different types of verification information: Date of Birth, Personal PIN, and National ID. This information is input by the recipient in a web flow and passes directly to the SDP, meaning the wallet does not need to process or store this information. | ||
| 8. The SDP verifies the recipient’s information. If it matches the information from the CSV, the SDP automatically makes the payment to the recipient’s Stellar account | ||
|
|
||
| Graphic representation of flow of funds: | ||
|
|
||
|  |
4 changes: 4 additions & 0 deletions
4
docs/stellar-disbursement-platform/user-interface/_category_.json
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,4 @@ | ||
| { | ||
| "position": 40, | ||
| "label": "User Interface" | ||
| } |
20 changes: 20 additions & 0 deletions
20
docs/stellar-disbursement-platform/user-interface/analytics.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| --- | ||
| title: Analytics | ||
| sidebar_position: 60 | ||
| --- | ||
|
|
||
| The Analytics page provides comprehensive insights into various aspects of financial transactions, enabling the user to track and understand key payment-related metrics. As more metrics and statistics become available, additional tiles will be added to this screen. The page displays information such as the successful payment rate, the total number of successful payments, the number of failed payments, and the number of remaining payments. Additionally, it shows the total amount disbursed, the average amount per transaction, the total amount in USDC, and the number of individuals and wallets involved in the transactions. | ||
|
|
||
| In more detail: | ||
|
|
||
| - The "Successful payment rate" indicates the percentage of payments processed successfully out of total attempted payments. | ||
| - "Successful payments" shows the count of all transactions that have been completed successfully. | ||
| - "Failed payments" reveals the number of transactions that didn't go through, which can help identify issues with the payment process. | ||
| - "Remaining payments" provides the number of transactions that are yet to be processed. | ||
| - "Total disbursed" offers information on the total amount of funds that have been sent out. | ||
| - The "Average amount" offers an average value of all the transactions that have taken place in USDC. | ||
| - "USDC" reveals the total amount of funds in the system, denominated in USDC. | ||
| - "Individuals" represents the number of people involved in these transactions. | ||
| - "Wallets" indicates the number of unique digital wallets involved in the transactions. | ||
|
|
||
|  |
44 changes: 44 additions & 0 deletions
44
docs/stellar-disbursement-platform/user-interface/dashboard-home.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,44 @@ | ||
| --- | ||
| title: Dashboard Home | ||
| sidebar_position: 10 | ||
| --- | ||
|
|
||
| The main page of the dashboard contains a summary of recent disbursement activity and key performance metrics. | ||
|
|
||
| This includes: | ||
|
|
||
| - Successful payment rate: The percentage of payments completed successfully (pending payments are not counted as successful). | ||
| - Successful payments: The total number of payments that have been successfully made. | ||
| - Failed payments: The total number of payments that failed to process. | ||
| - Remaining payments: The total number of payments that are scheduled but haven't been processed yet. | ||
| - Total disbursed: The total amount of funds successfully sent to receivers by an organization over time. | ||
| - Individuals: The total number of individuals who are set to receive disbursements. | ||
| - Wallets: The total number of wallets used within the SDP. This usually equals the number of individuals but it is possible for each person to have more than one wallet. | ||
|
|
||
|  | ||
|
|
||
| On the left side of the Stellar Disbursement Platform dashboard is the organization logo and tabs to help you navigate through the platform. | ||
|
|
||
| They include: | ||
|
|
||
| - Home: This is the main dashboard that provides an overview of your organization’s activities. | ||
| - Disbursements: This section shows you the history and details of all disbursements. | ||
| - Receivers: Lists of individuals who are set to receive disbursements. | ||
| - Payments: Here you can find the history and granular details of all payments. | ||
| - Wallets: Information related to your organization’s wallet, the source of funds for your disbursements. | ||
| - Analytics: Data visualization tools to help you analyze your disbursements and payments. | ||
| - Profile: Manage your personal and organizational information. | ||
| - Settings: Adjust the settings of the SDP according to your preference. | ||
|
|
||
| The dashboard also shows a Recent Disbursements list, providing a quick snapshot of your most recent disbursements. | ||
|
|
||
| Each entry shows: | ||
|
|
||
| - Disbursement Name: The unique name given by your organization to the disbursement operation. | ||
| - Total payments: Total number of payments within the specific disbursement. | ||
| - Successful: Number of payments that have been successfully sent from the SDP Distribution Wallet to receiver wallets so far. | ||
| - Failed: Number of payments that failed to process. | ||
| - Remaining: Number of payments that are scheduled but haven't been processed yet, usually because the receiver has not yet set up a wallet. | ||
| - Created at: The time and date the disbursement was created, displayed in your local timezone. | ||
| - Total amount: The total value of the disbursement in the appropriate asset. | ||
| - Amount disbursed: The amount of the disbursement that has been successfully paid out so far. |
26 changes: 26 additions & 0 deletions
26
docs/stellar-disbursement-platform/user-interface/disbursements.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,26 @@ | ||
| --- | ||
| title: Disbursements | ||
| sidebar_position: 20 | ||
| --- | ||
|
|
||
| The Disbursements page provides a paginated list of all disbursements, detailing each disbursement's status and related payment information. | ||
|
|
||
|  | ||
|
|
||
| The page contains the following: | ||
|
|
||
| - Drafts: Click the Drafts button at the top right to go to a list of disbursements that have been created but not yet submitted. | ||
| - New disbursement: Click the New Disbursement button to start the process of creating a new disbursement. | ||
| - Search by disbursement name: Input the name of a disbursement to quickly find specific details. | ||
| - Filter: Allows you to narrow down the disbursement list based on specific criteria like status or creation date. | ||
| - Export: Use this option to download the disbursement data in CSV format. | ||
| - Disbursement detail: Each disbursement is displayed with the following details: | ||
| - Disbursement name: The unique name assigned to the disbursement by your organization. | ||
| - Total payments: The total number of payments within the disbursement. | ||
| - Successful: The number of payments within the disbursement that have been processed successfully from the distribution account to registered wallets. | ||
| - Failed: The number of payments that failed during processing. | ||
| - Remaining: The number of payments that are yet to be processed. | ||
| - Created at: The date and time when the disbursement was created. | ||
| - Total amount: The total value of the disbursement in the appropriate asset. | ||
| - Amount disbursed: The amount of the disbursement that has already been paid out. | ||
| - You can click into an individual disbursement to see its details, including a full list of receivers and payments. |
22 changes: 22 additions & 0 deletions
22
docs/stellar-disbursement-platform/user-interface/payments.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| --- | ||
| title: Payments | ||
| sidebar_position: 40 | ||
| --- | ||
|
|
||
| The Payments page provides a list of all payments, detailing each payment's status and related information. | ||
|
|
||
|  | ||
|
|
||
| The Payments page includes: | ||
|
|
||
| - Search by payment ID: Enter a payment ID to find specific payment details quickly. | ||
| - Filter: This tool allows you to narrow down the payment list based on specific criteria. | ||
| - Export: This option lets you download payments data in CSV format. | ||
| - Payment Details: Each payment is listed with the following details: | ||
| - Payment ID: A unique identifier assigned to each payment. | ||
| - Wallet address: The digital wallet address where the payment is sent. A dash ("-") signifies that the wallet address is not yet set. The payment cannot be made until the receiver wallet is created and linked in the SDP. | ||
| - Disbursement name: The name of the disbursement associated with the payment. | ||
| - Completed at: The date and time when the payment was completed. A dash ("-") signifies that the payment has not yet been completed. | ||
| - Amount: The value of the payment in the appropriate asset. | ||
| - Status: The current status of the payment. This can be "Success" if the payment has been completed, “Pending” if the payment is currently processing on the Stellar network, or "Ready" if the payment is yet to be processed. | ||
| - You can click into an individual payment to see its details, including a granular status history and Stellar blockchain details. |
Oops, something went wrong.