Skip to content

Commit

Permalink
init (#1)
Browse files Browse the repository at this point in the history
  • Loading branch information
jesmarsc authored Aug 4, 2022
1 parent a5ac3b4 commit 6a632dc
Show file tree
Hide file tree
Showing 145 changed files with 25,451 additions and 0 deletions.
10 changes: 10 additions & 0 deletions .eslintignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
dist
node_modules
docs
.github
build
/*.js
/*.ts
/*.d.ts
static
.docusaurus
6 changes: 6 additions & 0 deletions .eslintrc.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
module.exports = {
extends: ["@stellar/eslint-config"],
rules: {
"import/no-unresolved": 0,
},
};
32 changes: 32 additions & 0 deletions .github/workflows/main.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
name: Format MDX and Lint

on:
pull_request:
branches:
- main

workflow_dispatch:

jobs:
build:
runs-on: ubuntu-latest

steps:
- name: Checkout App Repo
uses: actions/checkout@v3

- name: Setup Node
uses: actions/setup-node@v3
with:
node-version: '16'
cache: 'yarn'
cache-dependency-path: '**/yarn.lock'

- name: Install App Dependencies
run: yarn --prefer-offline

- name: Format MDX with Prettier
run: yarn check:mdx

- name: Lint with ESLint
run: yarn lint:fix
20 changes: 20 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Dependencies
node_modules

# Production
/build

# Generated files
.docusaurus
.cache-loader

# Misc
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local

npm-debug.log*
yarn-debug.log*
yarn-error.log*
13 changes: 13 additions & 0 deletions .prettierrc.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
module.exports = {
...require("@stellar/prettier-config"),
// This is mostly content, and prose wrap has a way of exploding markdown
// diffs. Override the default for a better experience.
overrides: [
{
files: "*.mdx",
options: {
proseWrap: "never",
},
},
],
};
3 changes: 3 additions & 0 deletions babel.config.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
module.exports = {
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
};
49 changes: 49 additions & 0 deletions docs/anchoring-assets/enabling-cross-border-payments/index.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
---
title: Overview
order: 10
---

import { Alert } from "@site/src/components/Alert";

Supporting cross-border payments of an asset through the Stellar network requires cooperation between a sending anchor (**SA**) and receiving anchor (**RA**). In this section, we'll only go over the steps necessary for building a SEP-31 receiving anchor, but documentation for building a sending anchor is in development.

Specifically, we will go over the SDF's [Tools and References](./reference-implementations.mdx) as well as all three stages of the development process:

1. [Setting up a test server](./setting-up-test-server.mdx)
1. [Setting up a production server](./setting-up-production-server.mdx)
1. [Launching](./launch.mdx)

## The Basic User Experience

Unlike with SEP-24, SEP-31 involves a sending user (**SU**) and receiving user (**RU**), so both users' experience is described [here](../../anchoring-assets/enabling-cross-border-payments/setting-up-test-server/#stellar-docsearch-form).

<Alert>

Note: **SA**'s are not necessarily wallet applications. This means the **SU** may not interact with a mobile application, but could go to a website or physical remittance location instead. Obviously, this affects the **SU** experience.

</Alert>

Generally, the experience of the SU and RU would look something like this:

1. The **SU** opens an app, website, or goes to a physical remittance location
1. The **SU** specifies the asset and amount to send, and the asset that should be received
1. The **SA** finds the appropriate **RA** for the asset, authenticates with the **RA**, and parses the **RA**'s requirements for sending payments
1. The **SA** collects both the **SU** and **RU** KYC information requested by the **RA** from the **SU**, as well as the transaction information
- **RU**'s should not have to take any action to receive a cross-border payment
- However, it is possible to require action from the **RU** if absolutely necessary
1. The **SA** registers the **RU** and potentially **SU** with the **RA** via [SEP-12](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0012.md)
1. Once the **RA** is ready to receive the payment, the **SA** makes the Stellar path payment to the **RA** using the **SU** and **RU** assets
1. Once the **RA** receives the path payment, it attempts make the associated off-chain transfer (usually bank transfer) using the KYC and transaction information sent by the **SA**
1. If the transfer to the **RU** fails, the **SU** will be notified by the **SA** to update the invalid or missing fields, and the **RA** will retry once the **SA** sends the updated info.

The **RU** should then receive the funds sent by the **SA** once the **RA** has the necessary to make the final transfer.

<Alert>

Note: The final off-chain transfer by the **RA** may not be a bank transfer. For example, the destination could be a mobile money account managed by the **RA**. The methods used to transfer the payment off-chain to the **RU** is up to the **RA**, and **SA**s should be aware of the off-chain transfer methods of their partner **RA**s.

</Alert>

## Interoperability and Stellar Ecosystem Proposals

As mentioned, this section will outline how to implement a [SEP-31](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0031.md) receiver, but these servers require [SEP-1](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0001.md), [10](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0010.md), and [12](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0012.md) to be implemented as well. SEP-1 is described in [this guide](../../issuing-assets/publishing-asset-info.mdx), and SEP-10 & 12 are described [here](../../anchoring-assets/enabling-cross-border-payments/setting-up-test-server.mdx#authentication).
49 changes: 49 additions & 0 deletions docs/anchoring-assets/enabling-cross-border-payments/launch.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
---
title: Launch
order: 50
---

Once the testnet and mainnet servers are deployed, KYC collection conforms to regulations, banking rails are integrated, and the whole system is audited, it's time to prepare for launch.

## Market Making

It is critical for an anchored asset to have liquid trading markets with XLM and ideally partner **SA** assets. Without a deep orderbook, its impossible to facilitate path payments at rates competivtive with equivalent off-chain fiat assets.

The SDF maintains a trading bot called [Kelp](https://kelpbot.io/) that supports many trading and market making strategies out of the box, all of which are described in [Kelp's Github Repo](https://github.com/stellar/kelp#kelp). You can use Kelp for free and start automating the order placement process in a matter of minutes.

Once the order placement is automatic, you should track the health of your token's market with these two parameters:

- Bid/Ask Amounts: Both sides of the order book should have at least 25k USD
- Spread Size: The average price of the bids and asks should be within 4% of each other.

The 25k USD value is relative to a new anchor that is still developing its business. Once the volume of traded assets (and the total supply) grows, this value should be increased.

## Creating an Anchor Website

A website allows wallets and consumers to find information about your team and your business, get in contact with questions and feedback, and understand how your service works. Your issuing account should link to that website so there's a clear connection between the Stellar asset and the URL. To do that, usee the `set options`, and choose the URL as the home domain. You can find more information about how that process works [in our guide to publishing asset information](../../issuing-assets/publishing-asset-info.mdx).

Here is a list of requirements to make sure users have a great experience navigating through your website:

### Branding Visuals

Users should feel that they are in the company's domain based on the branding of the webpage. The brand universe can include many aspects, such as: company logo or symbol, slogan, colors, fonts, icons, etc...

### Company Description

Users want to know who you are and what you do before they'll trust your service or hold your asset. Your website should describe your business, clarify your mission, and outline your vision. Giving more information about your company's executive team, or about your team in general, is a great way to increase users' confidence, and conversions.

Describing how are you integrated with the Stellar Network (and with which wallets) is also a great way to show users that the system is reliable, and that it conforms to the best protocols and practices of the financial industry.

Finally, make sure to describe what your asset represents, how it's backed (e.g. it's 1:1 with a fiat reserve), how users can redeem it, and who can use it (anyone, just for retail, etc).

### Customer Support

Your webpage is also where users will go to report problems and reach out with questions and feedback. Make sure you clearly describe the process for contacting you, and for reporting bugs, and have a plan in place to offer necessary support.Adding a FAQ section once is a great way to defray support tickets and get information to users faster.

You should also have a contact email so customers can get in touch, report inconsistencies, and open tickets. Once you get those tickets, you need to answer them in a reasonable amount of time.

## Connecting to Sending Anchors

All **RA**s must connect with **SA**s that have transaction volume to send. The SDF works with strategic partners to build and improve these relationships, and the ultimate goal is for there to be an entire ecosystem (or network) of **SA**s and **RA**s globally.

Stellar.org does not yet host any resources documenting existing SEP-31 anchors, but it is coming.
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"title": "Enable Cross-border Payments",
"order": 30
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
---
title: Tools and References
order: 20
---

These docs walk through the steps necessary to set up and launch both a test server and a production server for SEP-31 cross-border payments, but before you get any deeper, it's worth noting: you don't have to start from scratch. SDF offers some tools that make it easy to implement those servers, and test them from the sending anchor (**SA**) side.

## Anchor Server Reference Implementation

To help with server setup, SDF created [Polaris](https://github.com/stellar/django-polaris), an extendable django reusable-app that comes with fully-implemented endpoints, templates, and database models. It's built in Python using the community-supported [Stellar Python SDK](https://github.com/StellarCN/py-stellar-base), and is compliant with the Stellar Ecosystem Protocols mentioned in the previous section.

TODO: REPLACE PNG ![Screenshots of the reference implementation](../../web-assets/polaris.png)

Polaris modularizes the parts of the codebase that interface with the Stellar network, and provides clear methods for developers to integrate their own customer registrations, banking connections, and KYC and transcation processing. That means you can focus on implementing the business- and country-related aspects of your product without having to spend much time defining how to connect the server to the Stellar Network.

If you choose to use Polaris, you can jumpstart your deployment, and connect local rails to Stellar in weeks instead of months.

## Demo Client & Deployed Example

Once you have a server set up, SDF also maintains a [Demo Wallet Project](https://demo-wallet.stellar.org/) that makes it easy to test your implementation on both the testnet and the pubnet.

This allows you to run through your receiving anchor's flow by entering information to a fake wallet application like a real sending user would.

![Screenshot of the demo client](../../web-assets/demo-wallet-sep31.png)

With the demo client, you can test your payment flows, and get information about the transactions that are created during those processes. It gives a clear step-by-step visual example of how the functionalities work along with insightful information about the requests, protocols, and possible validation messages. To start testing the deploys, simply update the settings of the Demo Client (click the gear button on the bottom right) to include your project's information.

## Anchor Validation Suite

The Anchor Validation Suite is a set of tests that helps confirming if your anchor implementation is compliant with the latest specifications of the SEP-31 standard. This is a great resource for people that are getting started building an anchor and want to check what's still missing in their implementation, or for teams that have already finalized the anchor development and want an extra validation on the codebase. Also, the Anchor Validation Suite doesn't replace the necessity of having a professional security auditor reviewing the whole project.

TODO: REPLACE PNG ![Screenshot of the Anchor Validation Suite's UI](../../web-assets/anchor-validation-suite.png)

The Anchor Validation Suite codebase is available in an open-sourced [Github Repository](https://github.com/stellar/transfer-server-validator/), where you can check in details exactly how all tests work. SDF also maintains a [deployed version of the Validation Suite](http://anchor-validator.stellar.org/) with a UI for running the tests without the need to setup your own infrastructure. In order to also test the interactive parts of SEP-24, you'll need to add test values to all the required interactive flow fields. The [Github Repository Readme file](https://github.com/stellar/transfer-server-validator/#providing-field-values) has more information on how exactly those fields need to be added. Finally, you can also trigger the tests directly from a Continuous Integration tool (like CircleCI or Jenkins), in order to have continuous monitoring of your anchor infrastructure.
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
---
title: Deploy a Production Version on Mainnet
order: 40
---

import { Alert } from "@site/src/components/Alert";

Once the test server is live and you have tested the payment flow with a **SA**, it's time to deploy a productionized version of the test server on mainnet.

The **RA** server code deployed to each environment should be the same, and additional functionality offered in production should be enabled via environment variables. This is called _code parity_, which significantly reduces operational and deployment complexity. It also allows **RA**s to use the Testnet service as a staging environment for debugging or new features and allows the **SA**s to test their client code before integrating with the **RA**'s mainnet service.

## Deploying a Secure Environment

Make sure to keep the test server up, and deploy the production (mainnet) system in a separate environment. Having two deployments allows you to validate new features on the testnet before deploying to production.

To switch to Stellar's public (mainnet) network, all you have to do is change the network [passphrase](../../glossary/network-passphrase.mdx) (for authenticating requests) and the [Horizon URL](https://horizon.stellar.org/). Stellar SDKs have all the built-in logic to switch from test to public with minor changes to the codebase.

If you're issuing your own asset in addition of offering an on/off ramp, make sure you follow [best practices for asset issuance](../../issuing-assets/how-to-issue-an-asset.mdx) by creating a distribution account that is separate from the issuing account before distributing real assets on the public network. The issuing account secret key should be highly secured via means such as cold storage or multi-signature, and should only be used to send (and, consequently, issue) assets to the distribution account. The distribution account will be used by the **RA** server to receive assets from other accounts programmatically.

Since the distribution account will be managed programmatically, it should only have a balance necessary to keep operations running for a short period of time. The issuing account should send small amounts of an asset to the distribution account frequently to represent the expected deposit volume for a given period. You should set up the transfer from the issuing account to the distribution account once day (or once a week week) to make sure the distribution account only has the minimum necessary balance to keep the operation functional in that short period.

## Validating Real KYC

Most anchors need to collect [Know Your Customer](https://en.wikipedia.org/wiki/Know_your_customer) information to comply with local regulations before honoring payments. In SEP-31, the **SA** controls the UX for the **SU**. Typically, the **SA** will offer an online or in-app UX, but physical remittance locations are also acceptable. Its also important for **SA**s to be able to contact **SU**s when information must be updated or when the transaction succeeded.

How the **RA** complies with their local regulations by validating KYC information is up the **RA**: there are many services that provide KYC solutions through APIs that validate the input data against governmental databases to verify requirements. Each jurisdiction has specific KYC requirements, and they differ from jurisdiction to jurisdiction, so it's best to find a country-specific KYC provider that meets your needs. Many **RA** organizations can validiate the KYC data collected without using a third-party service.

Some countries require different KYC fields depending on the payment amount. If that's the case in an **RA**'s jurisdiction, the **RA** needs to expect and support different KYC `type` values in `GET /customer` requests. Only one `type` value can be specified in the `/info` response per-customer, so a different large-payment `type` value will have to be documented and communicated to the **RA**'s partner **SA**s outside the SEP.

KYC information should be linked to the `id` returned by the `PUT /customer` calls, so you only need to ask the **SU** for it once as long as the data provided is valid.

<Alert>

Note: The SDF encourages anchors to have the same KYC collection process on the Testnet server and Mainnet server. However, _validation_ of KYC data on Testnet is unnecessary and prevents third parties from testing your service. KYC validation should only be supported on Mainnet unless the field uses a well-known format like email addresses.

</Alert>

## Connecting to Real Banking Rails

Fiat-backed token anchors are expected to manage a full reserve. That means there's a 1:1 relationship between Stellar-network tokens and money in the bank. Since each fiat token on Stellar is backed by, and can be redeemed for, an underlying, real-world asset, anchors of fiat-backed tokens need to connect to real banking rails to make payments to receiving users (generally through bank transfers). This applies to both issuing and non-issuing anchors.

Once Stellar payment transactions have been detected and matched to an internal transaction record using the memo of the payment, **RA**s must attempt the off-chain payment (typically using a bank transfer).

Make sure to do a full security audit on your systems when banking rails connections are in place. Some banks provide a testing API that can be used for development and deployment to testnet or staging environments, which means you can test and audit the codebase before moving to a final production-ready bank integration.

## Testing

Once your application is fully functional, it's a good idea to test different scenarios and edge cases to make sure the system is behaving as expected.

The SDF offers an [anchor validation test suite](https://anchor-validator.stellar.org/) and UI for testnet and mainnet testing. SEP-24 and SEP-31 are supported, containing a growing list of tests to assess your service's compliance with the protocol. While the coverage is good, the SDF does not claim that it is complete.

Below are some tests that the suite does not and will not cover.

### General Tests

- Check that the issuing account is set up with the correct home domain, and that the website on that home domain has branding visuals, content about your company, clear language telling users how to report problems, and a method for contacting you to seek support.

### Security Tests

- Ensure distribution is done through a dedicated distribution account (not the issuing account)
- Ensure market making is done through a dedicated account (not the issuing account)
- Make sure all authenticated endpoints are not accessible without the JWT token
Loading

0 comments on commit 6a632dc

Please sign in to comment.