Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.

Hedera Stable Coin Demo


In order to run the stable coin demo, you will need a Hedera account for the network you want to deploy against (Mainnet or Testnet).

Testnet accounts can easily be created via

In addition to an account, you will need the following software components.

Docker setup prerequisites

  • Docker version 19.03.13

  • Docker-compose version 1.27.4,

Manual setup prerequisites

see install prerequisites at the end of this document for assistance if needed

Clone from GitHub

_Note: Assumes git is installed

# Clone repository
git clone
cd hedera-stable-coin-demo
git submodule sync
git submodule update --init

Docker setup

Running the demo through docker containers is the easiest way to get started.

Setup environment file for docker images

Copy the sample environment file

cd Docker

Set the environment variables

  • HSC_OPERATOR_ID=0.0.xxxx
  • HSC_OPERATOR_KEY=302e02xxx

Note: _If you are deploying to cloud infrastructure to be accessed by remote clients, edit the two lines below and replace localhost with the public IP address of your server such that it can be resolved by remote clients.

  • VUE_APP_HSC_PLATFORM="http://localhost:8083"
  • VUE_APP_APP_NET_NODES=[{"name": "Node 1", "address": "localhost:8082","left": "230px", "top": "150px"}]

Note: no other changes are necessary at this stage, all other variables are set to default values

Step 1 - build the images

The first step consists in building the images. You have two options here: either let the build pull the source code from github, or build from your local version of the repository.

Note: The build scripts were prepared for MacOS, it's possible the scripts will need adaptation for alternative unix/linux distributions.

  • Pull from github repository during build (this creates two additional staging images for the build)

Note: You can specify a branch to build from, be sure to include -b at the beginning of the environment variable.

export BRANCH=""
#export BRANCH="-b branch_name"
  • Build from local source

Note: These errors are perfectly normal during the build.

Removing images
Error: No such image: stable-coin/buildjava:latest
Error: No such image: stable-coin/buildjs:latest
Error: No such image: stable-coin/client-ui:latest
Error: No such image: stable-coin/admin-ui:latest
Error: No such image: stable-coin/platform:latest
Error: No such image: stable-coin/token-node:latest

Note: Running this build script will always clean up the environment before starting the build, for example, the volume created to persist the Postgres TimescaleDB files is deleted, the existing containers and images are also deleted

Step 2 - start the containers

Once build is complete, you may start the containers with docker-compose up.

Watch the console output, there will be some errors which are normal at this stage.

Creating network "docker_default" with the default driver
stable-coin-token-node | no Topic ID found, creating a new topic ...
stable-coin-token-platform | SEVERE: missing environment variable HSC_TOPIC_ID
stable-coin-token-platform exited with code 0
stable-coin-token-node | created topic 0.0.107057
stable-coin-token-node | creating contract for token
stable-coin-token-node | pausing 10s
stable-coin-token-node | ..........
stable-coin-token-node | starting listener on mirror for topic 0.0.107058 ...
stable-coin-token-node | listening on topic 0.0.107058 from 1970-01-01T00:00:00Z
stable-coin-token-node | Listening on port : 8082
stable-coin-token-node | Nov 16, 2020 1:59:36 PM info

CTRL+C as soon as stable-coin-token-node | Listening on port : 8082 appears on the console.

Step 3 - Update with Topic ID

edit the file with the Topic Id


locate the line that starts with #HSC_TOPIC_ID=.

Uncomment the line and input the Topic ID created in the previous step (For example: HSC_TOPIC_ID=0.0.107057) and save the changes.

Step 4 - Run the containers again

docker-compose up

or if you wish to leave the containers running in the background:

docker-compose start

Note: You may stop and re-run the containers as often as you wish

Step 5 - Test the UIs

The client user interface should now be available at http://serverip:8080 and the admin user interface at http://serverip:8081.

Try to register a new user in two separate browser windows.

Note: cookies are used so two browsers such as chrome and safari may need to be started in parallel for this

Note: if you have reset the environment resulting in a new Topic Id, it will be necessary to clear cookies in your browsers so they don't assume a prior "identity"

You should then be able to "buy" stable coin and transfer between users.

To use the compliance features of the admin interface (freeze and clawback), you will need this admin key (which is specified in the file): HSC_COMPLIANCE_MANAGER_KEY=302e020100300506032b65700422042079f3d3cbc2106d5a83193c2fca68730b4ba413de0b534b990365423f2c05f3fd

Manual setup

The sections below detail how to setup the stable coin demo.

  • The stable-coin-java-hcs (the contract) implements the logic necessary to maintain state for a stable coin across multiple stable coin nodes.

  • The stable-coin-platform is used by clients to sign transactions on behalf of the Hedera Network account (if clients had their own Hedera account, they could sign transactions themselves).

  • The stable-coin-proto-js is a set of protobuf messages that define the operations that are available to the stable coin network.

  • The stable-coin-sdk-js is an SDK used by the clients.

  • The stable-coin-client is an example wallet application for end users.

  • The stable-coin-admin is an example administration UI for compliance and other functions.

Contract — stable-coin-java-hcs

Reference implementation in Java of a Hedera Stable Coin.

refer to Hedera Stable Coin for deployment details.

Platform — stable-coin-platform

Sample implementation of a larger platform around a Stable Coin network.

Build stable-coin-platform

cd hedera-stable-coin-demo/stable-coin-platform
# Create the database
sudo su -l postgres
createdb -h localhost -U postgres stable_coin_platform
# CTRL+D to exit postgres user shell

./gradlew build

Setup environment for stable-coin-platform

Copy .env.sample to .env and edit

cp .env.sample .env
nano .env

Operator on Hedera to use to execute any needed transactions. This is the account that will get charged.

  • HSC_OPERATOR_ID=0.0.___
  • HSC_OPERATOR_KEY=302e___


  • HSC_HTTP_PORT=9005

Node Id to use when creating transactions


Topic on Hedera to use (copy from stable-coin-java-hcs .env)

  • HSC_TOPIC_ID=0.0.____

Database information for transaction and event logging

  • PLATFORM_DATABASE_URL=postgresql://localhost:5432/
  • PLATFORM_DATABASE_DB=stable_coin_platform

Private keys Used for marking an account as passing KYC

HSC = Hedera Stable Coin, ESC = Ethereum Stable Coin

  • HSC_COMPLIANCE_MANAGER_KEY=302e02__ (you may use your operator private key for initial testing)

Used for minting money to accounts

HSC = Hedera Stable Coin, ESC = Ethereum Stable Coin

  • HSC_SUPPLY_MANAGER_KEY=302e02__ (you may use your operator private key for initial testing)

URL to a remote node for interacting with the ethereum network

Note: Leave empty/commented if you don't want to use the bridge feature


Address of the Stable Coin contract on Ethereum


Run stable-coin-platform

java -jar build/libs/stable-coin-platform-1.0.0.jar

should output

Platform listening on port: 9005

Protobuf definitions - stable-coin-proto-js

Message definitions for use by the clients

Build stable-coin-proto-js

cd ../stable-coin-proto-js
# compile
# create a link for other projects
yarn link

JavaScript SDK - `stable-coin-sdk-js'

SDK for use by the client and admin user interfaces

Build stable-coin-sdk-js

cd ../stable-coin-sdk-js
# link to stable-coin-proto-js
yarn link "@stable-coin/proto"
# compile
# create a link for other projects
yarn link

Client — stable-coin-client

Sample implementation of a client on top of the platform and network.

Build stable-coin-client

cd ../stable-coin-client
# link to stable-coin-sdk-js
yarn link "@stable-coin/sdk"
# compile

Setup environment for stable-coin-client

_Note: These instructions are for running in development, for a production build, create a .env.production file.

# copy sample environment file
cp .env.sample .env
# edit environment file
nano .env

Operator account num (no leading 0.0.)


Address of the stable coin platform

List of appnet node end points for the clients

  • VUE_APP_APP_NET_NODES=[{"address": "localhost:8080"}]

Ethereum Contract Address

  • VUE_APP_ETH_CONTRACT_ADDRESS="0x125b7195212f40faD937444C29D99eA4990E88f1"

Run stable-coin-client

Choose the port you wish to run the client on in the command below

yarn serve --port 8082

Admin — stable-coin-admin

Sample implementation of an administration portal on top of the platform and network.

cd ../stable-coin-admin
# link to stable-coin-sdk-js
yarn link "@stable-coin/sdk"
# compile

Setup environment for stable-coin-admin

_Note: These instructions are for running in development, for a production build, create a .env.production file.

# copy sample environment file
cp .env.sample .env
# edit environment file
nano .env

Operator account num (no leading 0.0.)


Address of the stable coin platform

appnet Nodes

Note: This is for rendering nodes on a map, not critical

  • VUE_APP_APP_NET_NODES=[{"name": "Node 1", "address": "localhost:8080","left": "230px", "top": "150px"}]

** Ethereum Contract Address**


Run stable-coin-admin

Choose the port you wish to run the client on in the command below

yarn serve --port 8083

Manual Install prerequisites

Note: These installation instructions are applicable to Debian 4.19, other operating systems may differ.

Java 14+

Refer to:


Refer to:

Node 10+

# Update apt
sudo apt update

# Install node
sudo apt install nodejs npm

# Check installed version
node -v
# v10.21.0


Note: Assumes curl is installed

# configure the repository
curl -sS | sudo apt-key add -
echo "deb stable main" | sudo tee /etc/apt/sources.list.d/yarn.list

# install yarn
sudo apt update
sudo apt install yarn

Developing further

If you make changes to the database schema, you'll need to rebuild the automatically generated code.

# Set environment variables
export HSC_DATABASE_URL="postgresql://localhost:5432/"
export HSC_POSTGRES_DB="stable_coin"
export HSC_DATABASE_USERNAME="postgres"
export HSC_DATABASE_PASSWORD="password"

# Create / update entities in the database
./gradlew flywayMigrate

# Build java artifacts
./gradlew jooqGenerate


Licensed under Apache License, Version 2.0 – see LICENSE in this repo or