bifrost-demo

This demo application is to test creating, issuing and distributing tokens based on Stellar platform using Stellar Bifrost.

bifrost-listener - Simple web app for serving requests from bifrost sever demo-stellar - Smart contracts application.

To make the application up and running, there must be provided the Horizon server, Stellar core node and Bifrost server (if contributions in ETH/BTC are enabled). The application was tested with the components described above (built for Linux platform) and their versions are as follows:

• Stellar core v9.2.0-239-g9af27ef (built from source)
• Horizon server v0.13.0
• Bifrost v0.0.2
• PostgreSQL 10.4
• geth v1.8.11-stable-dea1ce05
• bitcoind v0.16.0.0-g4b4d7eb255

Stellar Core

Stellar core is a backbone of the Stellar platform. Stellar core is responsible for transactions on the network through the Stellar Consensus Protocol. This application is running on the top of the Stellar Core built from source for Linux platform.

Detailed instructions how to build the Stellar core can be found here. (We are not providing such instructions through the doc because information can change)

Building process is quite resource-consuming and it takes some time to finish.

Stellar core requires the PostgreSQL v9.3 or higher to store the state of the ledger. Also, there must be provided a configuration file where database url with the other parameters are specified. Configuration for the Stellar Core connected to the Testnet is here.

Before running the Stellar Core, the database must be initialized. To do so, run this command in a terminal:

$ stellar-core --newdb

Next step: to run the Stellar Core put the command below to your terminal:

$ stellar-core --conf /path/to/stellar-conf.cfg

When the Stellar Core runs for the first time, it will take some time to catch up a chain.

To check the progress, run this command in a new terminal window:

$ stellar-core -c info

and when you the status is Synced!, it means Stellar Core is ready.

Horizon Server

Horizon server is a front client for the Stellar platform. In general, Horizon server is an interface between Stellar core and application built on top of the Stellar platform. It is necessary to run your own Horizon servers when you go to production to guarantee high availability and scalability, especially if you expect high load.

Horizon is dependent upon a Stellar Core server. Horizon needs an access to both SQL database and HTTP API that is published by Stellar Core. Also, Horizon requires a PostgreSQL (verstion 9.3 or higher) server which it uses to store processed core data.

This application is running Horizon server v.0.13.0

Before running the Horizon server, additional configuration must be provided. The configuration can be provided using command-line arguments or environment variables.

cmd argument	ENV variable	value
--db-url	DATABASE_URL	postgres://postgres:postgres@localhost/horizon-testnet?sslmode=disable
--stellar-core-db-url	STELLAR_CORE_DATABASE_URL	postgres://postgres:postgres@localhost/core-testnet?sslmode=disable
--stellar-core-url	STELLAR_CORE_URL	http://localhost:11626

Extract the downloaded archive and export ENV variables. After that initialize the database schema required for the Horizon using this command:

$ horizon db init

And to start the Horizon, put this command to a terminal:

$ horizon serve

Now the Horizon is awaiting for requests.

Bifrost server

The application is running with Bifrost v0.0.2.

Bifrost server is a bridge between Stellar and Ethereum/Bitcoin networks.

Bifrost server adopts a BIP32 Hierarchical Deterministic Wallets. To proceed with Bifrost, a master public key must be specified in a bifrost.cfg configuration file along with other properties required for Bifrost to run.

This master key is a root for all wallets that Bifrost will generate. If you don't have that master public key, it can be generated by Ethereum HD Wallet util (this util works with Ethereum keys and similar util should be implemented for BTC addresses).

Before starting the Bifrost, you have to run a local rpc server and sync with Ethereum/Bitcoin network.

To provide an rpc endpoint for Ethereum network (Ropsten testnet was used during PoC development), run this command in a terminal:

$ geth --rpc --testnet --networkid 3

where 3 identifies Ropsten testnet.

To provide an rpc endpoint for Bitcoin network (Testnet3 was used during PoC development), run this command in a terminal:

$ bitcoind -testnet -rpcuser=user -rpcpassword=password

When a chain is synchronized, initialize a database schema:

$ bifrost-v0.0.2-linux-amd64 --newdb

And run Bifrost server using this command:

$ bifrost-v0.0.2-linux-amd64 server -c /path/to/bifrost.cfg

If you run Bifrost for the first time or after a while, it will take some time to synchronize all blocks.

When Bifrost finished a sync up process, it's ready for server transactions from Ethereum/Bitcoin network. But first, a contribution address must be provided.

To get this address, there must be a simple application that utilizes Bifrost JS SDK (our implementation is called bifrost-listener). The SDK generates new Ethereum/Bitcoin wallet address for each request. An investor should use this address as a receiving address for its contribution. Once ETH/BTC transaction is sent, a set of events will be handled on Bifrost server and bifrost-listener application. When a transaction is successfully completed, a new Stellar KeyPair is generated for an investor.

But we do not have private keys for all generated accounts by Bifrost on this stage. To get private keys for all Ethereum/Bitcoin accounts with successful contributions, we should make the following steps:

• Login to the Bifrost PostgreSQL server;
• Collect all receiving_address from processed_transaction table for the particular chain (ethereum or bitcoin);
• Select all address_index where address is IN (RESULT SET FROM THE PREVIOUS STEP).

When you have a list of address_index, you can derive private keys using Ethereum HD Wallet util. Use the function loadPrivateKeys(masterSeed, indexes), where masterSeed is a master seed for the root account that was previously generated and indexes is a result set from a database query. When function is finished, wallets.json is generated with walletAddress, publicKey and privateKey fields inside.

Smart contracts

Application implements a set of Stellar transactions that can be called as a Smart Contract.

These smart contracts implement new application flow:

1. Create issuer account
2. Create distribution account
3. Create custom asset (for example, QQQ)
4. Create ETH(and/or BTC) token
5. Set trust lines from distribution to issuer account for both tokens
6. Transfer tokens from issuer to distributor
7. Create ManageOfferOperation for exchanging ETH(or/and BTC) to QQQ and sign it with issuer
8. Lock issuer account

To follow this flow, please look at DemoAppApplicationTests where a full flow is implemented. The test requires a connection to the Horizon and Stellar Core servers.