A Developer Guide to Setting up Stellar Blockchain Anchor

A stellar anchor is a trusted entity on the Stellar network that can hold a user's deposits and issue credit for the deposits a user has requested to the anchor. Anchors act as a bridge between actual currencies and the Stellar network. Anchor issues credits to users equivalent to actual currency value in the form of assets.

Established currency may be of any currency i.e. Fiat or Crypto. Users can then use this credit to initiate transactions on stellar networks. Anchors tend to be organizations such as financial institutions, remittance companies, and central banks.

Before continuing with the setup guide, you should be familiar with the following:

Issuing assets, the most basic activity of an anchor
Federation, enables a single Stellar account to represent multiple users
Compliance, Compliance protocols are subject to any financial regulation

Account Structure

As an anchor, you need to maintain at least two accounts:

An issuing account - It's used for issuing and destroying assets only
A base account - A base account is used to transact with other Stellar accounts. It can hold a balance of assets issued by the issuing account of a stellar anchor.

Issuing account - An issuing account is used for issuing or destroying assets. If a new user wants to trade an asset under the control of an anchor, the anchor will simply credit the user's account, thus issuing a new asset. Similarly, if the user wants to withdraw that credit, the issued asset will subsequently be destroyed as well.

Base account - The base account is the account an anchor uses to transact with other Stellar accounts on the network. When a user wants to make a deposit with an anchor, once a deposit is received by anchor authorities in the form of Fiat or Crypto, an equivalent amount of that deposit is then credited to the user's account from the anchor's base account.

However, before an anchor issues an asset to a user, a trustline must be issued. The user must first create a trustline with the anchor. Once a user creates a trustline, the user is available to use that asset and transactions. A trustline signifies that a user trusts the asset being issued and believes it to be redeemable at a later date.

Note: For testing purposes, you can create these accounts on the test network using the laboratory or the steps from the "this" guide.

For this demonstration purpose, we'll use the following accounts:

Issuing Account ID GBK54TBCUNCHJX7PIGAEEEBB35H2TUCM6MZWNHOA4ZANNWKWXLGRRCFA

Issuing Seed

SBI54OUXGKVI3YXOXY5EL3HCMBQQQVV4JHWPHPGRD6EXT4DYGQTGIBBT

Base Account ID

GAQK3WYDV35F6P6S4JXJE5B2RQGCWLZT5OMM7TGL5KKAXYQ4CJGTN2KE

Base Seed

SCOXFQ7GHNTFFKR7V4OD3N7YQM5Z4AJNOJ43N5EJIWOY3CUJP4JGIRAT

Customer Accounts

Stellar anchor manages users' accounts at its level. There are many ways that a Stellar anchor can manage customer accounts, two of those ways are as follows:

Maintain a Stellar account for each customer
Use the federation protocol to conduct transactions

Maintain a Stellar account for each customer - By maintaining a Stellar account for each customer, deposits and withdrawals can be credited and retracted from a user's account depending on action. For example, if a user wants to make a deposit, the appropriate amount would simply be credited to their account by the anchor and vice versa if the user wants to make a withdrawal.

Use the federation protocol to conduct transactions - By using the federation protocol, a Stellar anchor can send and receive payments on behalf of their users. In this case, the anchor's base account needs to be maintained for all the transactions going through the anchor.

Note: You can follow any of the above approaches to maintain customer accounts on anchor.

Architecture

The stellar architecture comprises the following five servers:

Bridge Server
Federation Server
Compliance Server
Horizon Server
Stellar Core Server

Making Payments

When using the above services, a payment using bridge, federation, and compliance works as follows:

A customer sends a payment using the app or website of your organization.
Your anchor's internal service will send a transaction using the bridge server. Stellar provides its built-in bridge server. You can use it or set up your own. I will guide later on setting up the bridge server.
The bridge server checks if a compliance check is needed to process the transaction further. If needed, the bridge server forwards transaction data to the compliance server for further checks and verifications.
The compliance server resolves the receiving account ID by calling the federation server internally for looking up the federation address.
The compliance server calls your anchor's internal services to get information about the customer who is sending the payment. This information is used to provide it to the receiving organization's compliance system.
If the result is successful with the compliance checks, the compliance server sends it back to the bridge server for transaction signing. the bridge server then creates a transaction and signs it. Once a transaction is signed, the bridge server sends it to the Stellar network.
On the Stellar network, Once the transaction is confirmed, the bridge server returns the result to your internal services, which can be used to update your customer's account balance and transaction info.

Receiving Payments:

When someone is sending a payment to you, the flow is different slightly:

The sender needs your stellar account ID on which the sender will send the payments. This is resolved by the federation server by looking up the federated address associated with the receiver's stellar account ID.
The sender then contacts the receiver's compliance server with information about the person sending a payment.
Receiver's compliance server contacts three services you implement:
1. A sanctions callback to check whether the sender is allowed to pay your customer or not.
2. If the sender wants to check the information of your customers, a callback is used to determine whether you are willing to share your customer's information or not.
3. The same callback used when you are sending a payment (above) is used to get your customer's information.
The sender then submits a transaction to the Stellar network.
The bridge server constantly monitors the stellar network for any transaction happening for your account. Once detected, send it to your compliance server to verify whether it's the same transaction you approved. This approval is same as 3.1
The last step is to implement a notification service to inform your customer that they have received assets from a user. The bridge server sends this transaction to your service to notify you about the transaction. At the same time, you can update your customer's account balances and transactions.

In the above payments, most of the work is handled by the steller's compliance, federation, and bridge servers. You need to implement callbacks correctly. We will guide you through when setting up those servers.

Set up Servers

Now, we will see to set up the individual servers and once setup is done, we will go through the action part by interacting with each other to send a payment through.

Set Up Bridge Server

Stellar maintains its own bridge server which makes us easier to use the federation server and compliance server to send and receive payments. If you wish to use steller's bridge server, you only need to write the services that receive payment notifications and provide responses to regulatory checks.

When you process the payments via the bridge server, we need to make an HTTP request to the bridge server rather than sending requests to the horizon server directly.

Create a Database

Create a database for manipulating the bridge server data. For this guide, we are using the bridge_test database and creating a user to manage this database. The bridge server requires a postgresQL database to manage data and compliance information. Run the below commands to create a database.

Note: You must have postgresQL installed before creating a database.

$ createdb bridge_test
$ sudo -u postgres psql -d bridge_test -c "alter user $USER with password 'password';"

Download and configure database

Download the bridge server here and set it up for your platform. Download and install the executables. To set up the bridge server, create a file bridge.cfg inside the downloaded bridge server. Your bridge server will be configured based on this file. For example:

# Bridge server bridge.cfg example

port = 8006
horizon = "https://horizon-testnet.stellar.org"
network_passphrase = "Test SDF Network ; September 2015"
compliance = "http://localhost:8001"
api_key = ""
mac_key = ""

#[[assets]]
#code="USD"
#issuer="GCOGCYU77DLEVYCXDQM7F32M5PCKES6VU3Z5GURF6U6OA5LFOVTRYPOX"

#[[assets]]
#code="EUR"
#issuer="GCOGCYU77DLEVYCXDQM7F32M5PCKES6VU3Z5GURF6U6OA5LFOVTRYPOX"

[[assets]]
code="ZAR"
issuer="GBK54TBCUNCHJX7PIGAEEEBB35H2TUCM6MZWNHOA4ZANNWKWXLGRRCFA"

#Listen for XLM Payments
[[assets]]
code="XLM"

[database]
# type = "mysql"
# url = "root:@/gateway_test?parseTime=true"
type = "postgres"
url = "postgres://ubuntu:oodles123@localhost:5432/bridge_test"

[accounts]
authorizing_seed = "SDFSQ6KUWRUMMG5KXOHVADSFXLEBFBMCJYPCDCELG5DTKGT7S6M4OQ2I"
base_seed = "SCOXFQ7GHNTFFKR7V4OD3N7YQM5Z4AJNOJ43N5EJIWOY3CUJP4JGIRAT"
issuing_account_id = "GBK54TBCUNCHJX7PIGAEEEBB35H2TUCM6MZWNHOA4ZANNWKWXLGRRCFA"
receiving_account_id = "GAQK3WYDV35F6P6S4JXJE5B2RQGCWLZT5OMM7TGL5KKAXYQ4CJGTN2KE"

[callbacks]
receive = "https://api.domain.com/api/bridge/receive" # API implemented on transfer/auth server
error = "https://api.domain.com/api/bridge/error" # API implemented on transfer/auth server

Start the Bridge Server

If you are running the bridge server for the very first time, run below command:

./bridge --migrate-db

Otherwise run below command:

./bridge

Note: --migrate-db command sets up bridge server for use.

Set Up Compliance Server

Stellar maintains its own compliance server which makes it easier to use bridge server and federation server to send and receive payments. If you wish to use steller's compliance server, you only need to write the callbacks that are required for the compliance checks.

Create a Database

Create a database for manipulating the compliance server data. For this guide, we are using a compliance_test database and creating a user to manage this database. Compliance server requires a postgresQL database to manage data and compliance information. Run below commands to create a database.

Note: You must have postgresQL installed before creating a database.

$ createdb compliance_test
$ sudo -u postgres psql -d compliance_test -c "alter user $USER with password 'password';"

Download and configure database

Download the compliance server here and set up for your platform. Download and install the executables. To set up the compliance server, create a a file compliance.cfg inside the downloaded compliance server. Your compliance server will be configured based on this file. For example:

# Compliance server compliance.cfg example

external_port = 8002

internal_port = 8001

needs_auth = false

network_passphrase = "Test SDF Network ; September 2015"

[database]

# type = "mysql"

# 0url = "root:@/compliance"

type = "postgres"

url = "postgres://ubuntu:oodles123@localhost:5432/compliance_test"

[keys]

# GC7DVHGMSQYAPYXQU652VVHEMZ2OZN4VH44T67QILDHDMBOACMZHQWLW

signing_seed = "SBI54OUXGKVI3YXOXY5EL3HCMBQQQVV4JHWPHPGRD6EXT4DYGQTGIBBT"

encryption_key = ""

[callbacks]

sanctions = "https://api.domain.com/api/compliance/sanctions"

ask_user = "https://api.domain.com/api/compliance/ask_user"

fetch_info = "https://api.domain.com/api/compliance/fetch_info"

tx_status = "https://api.domain.com/api/compliance/tx_status"

[tls]

certificate_file = "server.crt"

private_key_file = "server.key"

[tx_status_auth]

username = "username"

password = "password"

Start the Compliance Server

If you are running the bridge server for the very first time, run the below command:

./compliance --migrate-db

Otherwise, run the below command:

./compliance

Note: --migrate-db command sets up bridge server for use.

Set Up Federation Server

Stellar maintains its own federation server which makes it easier to set up and run very quickly. But you can write your own if you wish to. The stellar federation address allows us to convert the human-readable format to the stellar account ID. For example, hotam_sing*api.domain.com will return my stellar account ID.

Create a Database

Create a database for manipulating user data. The federation server is designed in such a way that it can be configured with any SQL database. For this guide, we are using a federation_test database and creating a user to manage this database.

Note: You must have postgresQL/SQLite3 installed before creating a database.

$ createdb federation_test
$ sudo -u postgres psql -d federation_test -c "alter user $USER with password 'password';"

Download and configure database

Download the federation server here and set it up for your platform. Download and install the executables. To set up the federation server, create a file federation.cfg inside the downloaded federation server. Your federation server will be configured based on this file. For example:

port = 8003

[database]

type = "postgres" # Or "sqlite3"

dsn = "postgres://ubuntu:oodles123@localhost:5432/federation_test"

[queries]

# insert = "INSERT INTO users (id, first_name, last_name, mobile_number) VALUES(id = ?, first_name = ?, last_name = ?, mobile_number = ?)

reverse-federation = "SELECT username, domain FROM users WHERE account_id = ?"

federation = "SELECT id, mobile_number as memo, 'text' as memo_type FROM users WHERE mobile_number = ? AND ? = 'api.domain.com'"

# reverse-federation = "SELECT mobile_number, '' as domain FROM accounts WHERE ? = ''"

# The federation server must be available via HTTPS. Specify your SSL

# certificate and key here. If the server is behind a proxy or load balancer

# that implements HTTPS, you can omit this section.

[tls]

certificate-file = "server.crt"

private-key-file = "server.key"

Start the Bridge Serve

./federation

Steps to follow

Please follow below documentation for the steps in setting up the anchor:

https://docs.google.com/document/d/1DuJJD9qKVsKahfHY447JYZj8NAeZ-AUdBVglEDA-48c/edit#heading=h.2mrriplryk89

Conclusion

To conclude, Stellar anchors are one of the main components of the Stellar network and facilitate the user to trade on the stellar network on behalf of the user's actual currency i.e Fiat or Crypto by issuance of related assets. We need to take care of a certain level of infrastructure that is necessary before an anchor is successfully set up. Infrastructure such as: compliance protocols, payment processing capabilities and AML must also be in place in order to become an anchor on the Stellar network.

References

https://www.stellar.org/developers/guides/anchor/