Overview

Frontend and contract for the bp heartbeat plugin

Monitor: http://heartbeat.liquideos.com/

Plugin Repository: https://github.com/bancorprotocol/eos-producer-heartbeat-plugin

Prerequisites

Make sure Docker and Node.js are installed

• Install Docker: https://docs.docker.com/docker-for-mac/install/
• Install Node.js: https://nodejs.org/en/

The DApp and eosio will occupy the ports 3000, 8888 and 9876. Make sure nothing else is already running on these ports.

Clone the repository:

git clone https://github.com/EOSIO/eosio-project-boilerplate-simple.git

The following guide assumes you are using macOS.

Quick start - Run the DApp

In this section we provide a single command script to run all the commands needed to start both the blockchain and UI. For more detail on each component see the Detailed guide below.

To start

./quick_start.sh

The above command will execute the following in sequence:

1. first_time_setup.sh
2. start_eosio_docker.sh
3. start_frontend.sh

To stop, press ctrl+c on your keyboard, and execute:

docker stop eosio_heartbeat_container

Detailed guide

Initial setup

./first_time_setup.sh

Executing the above shell script verifies that docker and node.js are installed. It then downloads the eosio/eos-dev docker image (which contains a full version of the eosio blockchain), removes any previous instances of this docker container and installs node packages for the frontend react app.

Initialise and start blockchain and DApp

After the initialisation, two terminal windows are required, both opened in the repository directory

• The first terminal window is for blockchain process.
• The second terminal window is for frontend react app.

running the blockchain

For the first (blockchain) terminal window, running

./start_eosio_docker.sh

will:

• Start the eosio blockchain
• Create smart contract owner account,
• Deploy smart contract

The log of blockchain will be displayed on your screen. eosio is now running and starts producing blocks.

running the DApp

For the second (frontend) terminal window, running

./start_frontend.sh

will open a browser session connecting to http://localhost:3000/ showing the react app.

Stopping blockchain or DApp

stopping the blockchain

In the first (blockchain) terminal window, press ctrl+c on your keyboard, the log will stop printing. And then execute:

docker stop eosio_heartbeat_container

This action will take a few seconds. The blockchain will be stopped.

stopping the DApp

In the second (frontend) terminal window, press ctrl+c on your keyboard. The frontend react app will be stopped.

Restarting blockchain or DApp

restarting the blockchain

In the first (blockchain) terminal window, execute this command:

./start_eosio_docker.sh

The blockchain will be resumed automatically and the log will be outputted to the terminal.

restarting the DApp

In the second (frontend) terminal window, you can restart the frontend react app by executing:

./start_frontend.sh

Reset blockchain data

First, you need to stop the blockchain (as above) and then execute:

./first_time_setup.sh

This removes all data on the blockchain, including accounts, deployed smart contracts, etc... The block count will be reset when you start the blockchain again.

Project structure

heartbeat // project directory
├── eosio_docker
│   ├── * contracts // this folder will be mounted into docker
│   │   └── heartbeat
│   │       └── heartbeat.cpp // the main smart contract
│   ├── * data // blockchain data, generated after first_time_setup.sh
│   │   ├── blocks
│   │   ├── state
│   │   └── initialized // to indicate whether the blockchain has been initialized or not
│   └── * scripts // scripts and utilities for docker container
│       ├── accounts.json // pre-create account names, public and private keys (for demo only)
│       ├── continue_blockchain.sh // continue the stopped blockchain
│       ├── create_accounts.sh // create account data
│       ├── deploy_contract.sh // deploy contract
│       └── init_blockchain.sh // script for creating accounts and deploying contract inside docker container
└── frontend
    ├── node_modules // generated after npm install
    ├── public
    │   └── index.html // html skeleton for create react app
    ├── src
    │   ├── pages
    │   │   └── index.jsx // an one-pager jsx, include react component and Material-UI
    │   └── index.js // for react-dom to render the app
    ├── package-lock.json // generated after npm install
    └── package.json // for npm packages

* means the directory will be mounted to the docker container. Whenever the file changes on the local machine, it will be automatically reflected in the docker environment.

DApp development

The DApp consists of two parts. eosio blockchain and frontend react app. These can be found in:

• eosio_docker
  • eosio block producing node (local node) wrapped in a docker container
    • 1 smart contract
    • auto smart contract deployment
    • auto create 7 user accounts
• frontend
  • node.js development environment
    • create-react-app: http://localhost:3000/

Users interact with the UI in client and sign the transaction in frontend. The signed transaction (which is an update action in this demo DApp) is sent to the blockchain directly. After the transaction is accepted in blockchain, the note is added into the multi index table in blockchain.

The UI, index.jsx, reads the notes data directly from nodeos using 'getTableRows()'. The smart contract, heartbeat.cpp, stores these notes in the multi index table using 'emplace()'' and 'modify()'.

Docker usage

Docker is used to wrap the eosio software inside and run a container (instance) from an image (eosio/eos-dev v1.1.0). To work with the blockchain directly, by running the scripts or using a cleos command line, you need to go into the container bash.

Go into container bash:

docker exec -it eosio_heartbeat_container bash

We have already set the container working directory to /opt/eosio/bin/, you could run cleos command in this directory directly. For documentation of cleos: https://developers.eos.io/eosio-nodeos/docs/cleos-overview

You can also look at the init_blockchain.sh or deploy_contract.sh scripts for examples of cleos command lines.

To exit from inside the container bash:

exit

Smart contract (Blockchain):

The smart contract can be found at eosio_docker/contracts/heartbeat/heartbeat.cpp, you can edit this smart contract. You will then need to compile and deploy the contract to the blockchain.

To save time, we prepared some scripts for you. Execute the scripts in the container bash (see above.)

The following script will help you to unlock the wallet, compile the modified contract and deploy to blockchain. 1st parameter is the contract name; 2nd parameter is the account name of the contract owner, 3rd and 4th parameter references wallet related information that was created during the Initial setup:

./scripts/deploy_contract.sh heartbeat heartbeatacc heartbeatwal $(cat heartbeat_wallet_password.txt)

After running this script the modified smart contract will be deployed on the blockchain.

Remember to redeploy the Heartbeat contract each time you modify it using the steps above!

Frontend:

The UI code can be found at heartbeat/frontend/src/pages/index.jsx), once you have edited this code the frontend react app compile automatically and the page on browser will be automatically refreshed. You can see the change on the browser once the browser finishes loading.

Docker commands

If you are more familiar with docker, you could use the docker commands below to have better control with the whole environment. Below are the explanations of each of the commands:

Execute below command in /eosio_docker:

Build and run container eosio-with-hbplugin image by mounting contracts / scripts to the container with running the init_blockchain.sh script as the process. The init_blockchain.sh script run the local node of the blockchain and initializes wallets / contract / data.

docker run --rm --name eosio_heartbeat_container \
-p 8888:8888 -p 9876:9876 \
--mount type=bind,src="$(pwd)"/contracts,dst=/opt/eosio/bin/contracts \
--mount type=bind,src="$(pwd)"/scripts,dst=/opt/eosio/bin/scripts \
--mount type=bind,src="$(pwd)"/data,dst=/mnt/dev/data \
-w "/opt/eosio/bin/" eosio-with-hbplugin /bin/bash -c "./scripts/init_blockchain.sh"

Output and follow docker console logs:

docker logs eosio_heartbeat_container --follow

Remove the container (will remove all wallets / contracts / data), useful if you want to re-init the whole DApp.

docker rm -f eosio_heartbeat_container

Stop the container (see below troubleshoot section to see how to pause and continue the blockchain):

docker stop eosio_heartbeat_container