Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

SDP: update user guide #197

Merged
merged 7 commits into from
Jul 26, 2023
Merged

SDP: update user guide #197

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
92c832e
SDP: update user guide
JakeUrban Jul 26, 2023
4706b41
use h2's
JakeUrban Jul 26, 2023
ecbadcb
use bold
JakeUrban Jul 26, 2023
c7234d6
tori's PR comments
JakeUrban Jul 26, 2023
7a203f5
remove cli example for showing sms in logs
JakeUrban Jul 26, 2023
656836a
update intro
JakeUrban Jul 26, 2023
736e028
minor corrections
JakeUrban Jul 26, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
206 changes: 128 additions & 78 deletions docs/stellar-disbursement-platform/getting-started.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,21 @@ title: Getting Started
sidebar_position: 30
---

## Set Up the Development Environment
In this guide, you will learn to:

In this guide, we'll help you set up your local workstation with a complete end-to-end development environment using docker-compose, the Stellar demo wallet, and USDC on Stellar's test network. Let’s bring up all the services.
- create and fund a distribution account for making payments
- set up an instance of the Stellar Disbursement Platform (SDP) locally
- create login credentials for users of the SDP
- 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][demo-wallet] in this guide, other Stellar assets and wallets can be used in development or production.

### 1. Create a Distribution Account
## Create and Fund a 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.

Expand Down Expand Up @@ -39,92 +47,76 @@ Your USDC should appear in your account within a few minutes, which you can chec

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

### 2. 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. This account will be used as the Distribution Account. Configure the following values in `docker-compose-sdp-anchor.yml`

**SDP**
`DISTRIBUTION_PUBLIC_KEY`
## Run the SDP Locally

**Anchor**
`ASSETS_VALUE.assets.distribution_account`
First you'll need to clone the project.

**TSS**
`DISTRIBUTION_SEED` (secret)
<CodeExample>

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`
```bash
git clone [email protected]:stellar/stellar-disbursement-platform-backend.git
```

**SDP**
`RECAPTCHA_SITE_KEY`
`RECAPTCHA_SITE_SECRET_KEY` (secret)
</CodeExample>

:::note
Before we run the SDP, lets replace the private key configured for the distribution account with the one we created with the demo wallet earlier.

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.
<CodeExample>

:::
```bash
cd stellar-disbursement-platform-backend/dev
```

### **Optional**: Configure your SMS provider
</CodeExample>

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.
Copy the secret key from the demo wallet, and replace the following value in `docker-compose-tss.yml`

TWILIO_ACCOUNT_SID
TWILIO_AUTH_TOKEN
TWILIO_SERVICE_SID
<CodeExample>

In order to use Twilio, we also have to set the following environment variable: MESSAGE_SENDER_TYPE: TWILIO_SMS
```yaml
DISTRIBUTION_SEED: # your secret key
```

### 3. Configure sdp-api and Anchor Platform hosts
</CodeExample>

Add the following two hosts to your `/etc/hosts` file:
Copy the public key from the demo wallet, and replace the following value in `docker-compose-sdp-anchor.yml`

<pre class="prettyprint">127.0.0.1 sdp-api</pre>
<CodeExample>

<pre class="prettyprint">127.0.0.1 anchor-platform</pre>
```yaml
DISTRIBUTION_PUBLIC_KEY: # your public key
```

### 4. Bring SDP services up via docker-compose
</CodeExample>

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.
Then build it using the pre-defined docker compose files.

<pre class="prettyprint">cd dev</pre>
<CodeExample>

<pre class="prettyprint">make all</pre>
```bash
make all
```

Your window will contain the logs from all services, making it easy to follow system behavior across all services.
</CodeExample>

![Window Log](/assets/SDP/SDP3.png)
You should now have the Stellar Disbursement Platform running locally on port 3000. However, you won't be able to log in until you create a user.

### 5. Create organization owner
## Create an 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.
We need to create an organization owner account with privileges (or 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#
```bash
docker exec -it sdp-api bash
./stellar-disbursement-platform auth add-user [email protected] john doe --password --owner --roles owner
```

</CodeExample>

### 6. Log in with your account
The command will ask you to define a password and then create the user.

## Log In

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.

Expand All @@ -134,39 +126,34 @@ Click the Sign in button and the SDP Dashboard will open. You will have no disbu

![Dashboard](/assets/SDP/SDP5.png)

### 7. 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.
## Create Your First Disbursement

![New Disbursement](/assets/SDP/SDP6.png)
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. You can download the template and update the values within it.

<CodeExample>
- `phone`: E164-formatted phone number of the receiver
- `id`: a unique identifier for the receiver, ensuring the receiver is only listed once per file
- `amount`: the amount to send
- `verification`: the data to verify. Currently built to verify date of birth.

```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.
![New Disbursement](/assets/SDP/SDP6.png)

Review and confirm the disbursement.

![Confirm](/assets/SDP/SDP7.png)

### 8. Verify your identity
## 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.
When a disbursement is created, the SDP attempts to send SMS messages to receivers using either Twilio or AWS SNS. 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. However, neither service is configured by default, so the SDP will not send an SMS message to the phone numbers listed in the CSV uploaded in the previous step. You can still see the message in the `sdp-api` container logs.

Check out the [Email and SMS Messages](#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.

![Verify Identity](/assets/SDP/SDP8.png)

### 9. Create a Receiver Account
## Create a Receiver Account

Clicking on the link within the SMS message will bring you back to the Stellar Demo Wallet, where you'll need to create another account to receive the USDC. Follow the same process described earlier to create the account and add a USDC trustline.

### 10. Initiate SEP-24 webflow
## 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".

Expand All @@ -186,7 +173,7 @@ The webflow provides a message indicating your successful registration, which is

![Message](/assets/SDP/SDP16.png)

### 11. Show your balance
## 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).

Expand All @@ -196,6 +183,69 @@ Keep an eye on the dashboard until the payment status reaches Success. If everyt

![Disbursement](/assets/SDP/SDP18.png)

## Next Up: Updating Application Secrets

Now that you've been able to make a disbursement, lets 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 SMS messages and emails to receivers and users, respectively. For SMS messages, the Stellar Disbursemnet Platform supports Twilio or AWS SNS. For emails, it supports AWS SES.

You'll need to chose if you want to use Twilio or AWS SNS for SMS messages. Once you create your AWS and potentially your Twilio account, you can configure the following values with your credentials.

<CodeExample>

```yaml
# Or AWS_EMAIL
MESSAGE_SENDER_TYPE: TWILIO_SMS
# AWS
AWS_ACCESS_KEY_ID:
AWS_REGION:
AWS_SECRET_ACCESS_KEY:
AWS_SES_SENDER_ID:
# Twilio
TWILIO_ACCOUNT_SID:
TWILIO_AUTH_TOKEN:
TWILIO_SERVICE_SID:
```

</CodeExample>

### 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:

<CodeExample>

```yaml
# the public key of the account used for authentication
# it should be the same public key for both attributes
SEP10_ACCOUNT:
SEP10_SIGNING_PUBLIC_KEY:
# the private key of the account used for authentication
# it should be the same secret key for both attributes
SEP10_SIGNING_PRIVATE_KEY:
SECRET_SEP10_SIGNING_SEED:
# the encryption key (any secret string) for the authentication token shared with wallets
# it should be the same key for both attributes
SEP24_JWT_SECRET:
SECRET_SEP10_JWT_SECRET:
# the encryption key for the authentication token used for internal services
# These could be different or the same value
ANCHOR_PLATFORM_OUTGOING_JWT_SECRET:
SECRET_SEP24_INTERACTIVE_URL_JWT_SECRET:
SECRET_SEP24_MORE_INFO_URL_JWT_SECRET:
# used to encrypt passwords of the SDP users
# NOTE: you'll need to recreate any existing users in the database if this is reset
EC256_PRIVATE_KEY:
```

</CodeExample>

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

[demo-wallet]: https://demo-wallet.stellar.org
[circle-sandbox]: https://login-sandbox.circle.com/
[circle-sample-app]: https://sample-sandbox.circle.com/