Quick Start
intermediate

Deploy a MachineFi dApp

Learn how to connect machine data to Dapps to build MachineFi applications.

Post Header Image

05/27/2022

Updated: 11/07/2022


SHARE

Edit on Github

Introduction

In this Quickstart, we're going to leverage W3bstream to develop a simple MachineFi application where a user is rewarded with a token by clicking a button on an IoT device:

MachineFi

MachineFi is the methodology developed by IoTeX as a way of incentivizing the deployment of machines, financializing the utility and data stream coming from machines, as well as enabling composable and transparent ways of building innovative applications.

W3bstream

W3bstream is the core component of every MachineFi application: An off-chain computing infrastructure serving as an open, chain-agnostic and decentralized protocol sitting in between blockchain and devices to convert real-world data streams from devices into verifiable, dApp-ready proofs.

Click & Earn

Just like any MachineFi application, this Click & Earn app is made out of three layers:

The Blockchain Layer

Implements a decentralized trusted logic based on blockchain, for example IoTeX, which commonly includes at least an incentivizing tokenomics

The IoT logic Layer

An off-chain node or decentralized network, that authorizes, verifies, processes, saves the IoT data, and sends the proofs of real world activities to smart contracts on the blockchain. In this tutorial we will create a single-node architecture using the W3bstream framework.

Hhe hardware Layer

This is typically a set of smart devices: combination of hardware and dedicated software (firmware) that collect sensors data and send messages to the w3bstream node.

machinefi-animation

Cloning the CLick2Earn code

Let's create a new directory called "click2earn":

mkdir click2earn && cd click2earn

Use this command to clone the MachineFi get-started repository from IoTeX:

git clone https://github.com/machinefi/get-started.git && cd get-started

This repository will have three directories, blockchain, w3bstream and firmware representing the three components of our MachineFi dApp.

The Blockchain Layer

For this application we're going to create an ERC20 mintable token with simple access levels through an operators mapping that allows the contract owner to enable certain operators to mint tokens.

If you haven't done so already, use the Utils menu item in the Developers Portal to configure the IoTeX testnet in your Metamask wallet. If you login to the portal with your GitHub account, you'll also be able to claim some test IOTX which you'll need to deploy your smart contract and test this quickstart.

Deploy the CLIK token

Let's get into the blockchain folder and create a .env file containing the private key of the wallet account you wish to use to deploy the contract.

cd blockchain
echo IOTEX_PRIVATE_KEY=<YOUR_PRIVATE_KEY> > .env
# example
# echo IOTEX_PRIVATE_KEY=cdd47d5c266...ed450624b55c4e3a > .env

We'll be using hardhat now to deploy the contract, run this command to deploy the ClickToken to the IoTeX Testnet.

make deploy

Or, if you don't have make installed:

npx hardhat run scripts/deploy.js --network testnet

You should get a log like this:

Deploying contracts with the account: 0x12345abcde.......
Address balance: 127500000 IOTX
adding owner as operator
deployer address:  0x15c....
Contract deployed to 0x8....

Import the token in Metamask

After deploying this contract, remember to import the token contract address in your Metamask wallet. If you'd like the rewards to be sent to a different account then the contract owner's, simply create a new one in Metamask and import the ClickToEarn token there:

image

Create an operator account for the W3bstream node

Since the w3bstream node will be calling this contract to mint token rewards, it's recommended to create a dedicated operator account for it, so as not to expose the contract owner account in the W3bstream configuration. Run this hardhat task in order to do so:

npx hardhat addOperator --operatoraddress  <W3BSTREAM_NODE_ADDRESS> --clicktokencontract <CLICKTOEARN_TOKEN_CONTRACT>  --network testnet

With the blockchain logic in place, it's now time to get the w3bstream node up and running.

The W3bstream IoT Layer:

Run the W3bstream node

Let's start by running the w3bstream node. Make sure Docker is installed and running on your machine, and run:

cd ../../
curl https://w3bstream.com/dc > docker-compose.yaml
export PRIVATE_KEY=<YOUR_W3BSTREAM_PRIVATE_KEY>
docker-compose up -d

You can now access the W3bstream Studio admin dashboard by pointing a browser to port 3000 for the w3bstream node server:

https://localhost:3000

And use the default password to access the dashboard.

Create a W3bstream project

For a newly installed node, you will see something like this:

create-project

Create a new project by clicking the "Create a new project now" button and call it ClicktoEarn.

Build and deploy the W3bstream logic

Once we have a w3bstream project, we are ready to deploy the Applet containing the IoT logic of our dApp.

Use your favorite editor to edit the Applet's source code in click2earn.go and replace the Mintable token contract address towards the end of the file with the ClickToEarn token address you deployed earlier.

nano w3bstream/src/click2earn.go  

click-go-file

We'll be using tinygo to compile the wasm module.

cd w3bstream/src
make 

Or, if you don't have make installed, just run:

 cd w3bstream/src
 tinygo build -o click2earn.wasm -scheduler=none --no-debug -target=wasi click2earn.go

The WASM module will be created in the w3bstream/wasm folder.

Let's go back to W3bstream Studio to add, deploy and run our Applet.

applet

Once prompted, select the click2earn.wasm file we just created, and click on the Deploy button to deploy this logic module into your w3bstream node.

deployment

If the module is correct, it will be successfully deployed, and you will be able to start/stop the module from the dashboard:

correct-deployment

You'll also notice a Strategy ID associated with your Applet. This is because, when deploying a logic module to a project, w3bstream configures a default event strategy that just routes any event to the module's start handler. The default strategy will work fine for this project. Indeed, we called our handler inside the Applet "_start", which the tinygo compiler will export as "start" in the WASM module.

Create a Publisher account

Before we can send messages to the W3bstream node, we should also make sure a Publisher Account is set.

add-publisher

Select the project, give a name to the publisher and assign it a unique key, like in the image below. Then click the Submit Button to confirm:

create-publisher

Now that the w3bstream node is up and running, it's time to configure the firmware component of our ClickToEarn application.

The Hardware Layer

Using W3bstream Studio to simulate device messages

For the purpose of this quickstart, we will simulate messages sent by a smart device from inside W3bstream Studio itself.

Before proceeding, you may want to follow the logs of the W3bstream node. In a new terminal, type the following:

docker container logs w3bstream -f

or, if you want a more readable output and you have jq installed:

# sudo apt install jq
docker container logs w3bstream -f | jq

In W3bstream Studio, select the Click2Earn project and click the Send Event button. In the Send Event dialog, select the Publisher, then edit the event payload field with:

"payload": "{\"Account\" : \"<REWARDS_RECIPIENT_ACCOUNT>}"

Just replace the REWARDS_RECIPIENT_ACCOUNT placeholder with the Metamask account address where you imported the CLIK token before (that's where rewards will be sent).

Finally click the "Submit" Button to send the message at least 5 times, then check your CLIK balance in Metamask to verify that you actually received 1 CLIK token every 5 "click" messages.

Using an Arduino board

If you are familiar with embedded development, we present a simple Arduino sketch that will work on a few ESP32 and Arduino boards. We suggest using an ESP32 with integrated user buttons like the ESP-WROOM-32. Alternatively, you will have to connect a button to one of the pins on the board.

The firmware in this project sends a message to w3bstream every time the user clicks a button connected to the board, where the payload just includes the recipient address that will receive the token rewards.

The firmware is set to send data over HTTP by default, but the MQTT option is also provided.

Make sure you have installed the Arduino IDE, and move the sketch folder included in the get-started repository to your Arduino projects directory. In MacOS it is located in your Documents folder by default:

mv firmware/click2earn ~/Documents/Arduino

Inside the IDE open click2earn.ino file within the Documents/Arduino/click2earn directory.

Let's now configure the secrets.h file:

nano firmware/click2earn/secrets.h 

Update the correct fields with their corresponding values:

  1. Set your WIFI Network name and password

ssid

  1. Set your W3bstream node ip address to SECRET_WEBSTREAM_HOST

host

  1. Set the publisher token as it appears inside W3bstream Studio:

token

publisher-info

Flash the firmware to your Arduino board:

flash-firmware

This firmware will work out of the box on an ESP32-WROOM-32 dev board: just click the "boot" button to send a click event to W3bstream. Click it at least 5 times and check your Metamask wallet to verify you got 1 CLIK token as a reward:

metamask


Docs

IoTeX Docs


IoTeX Developerslogo

devs@developers.iotex.io