Two weeks ago, I attended the first global EOS Hackathon in Hong Kong. We built a peer-to-peer data marketplace distributed application (dapp) using ReactJS and EOSJS, plus a custom smart contract written in C++. While we didn’t win (the winner used retina scanning hardware and EOS’s built-in identity verification functionality), we received a lot of recognition from the EOS community for our project.

This is a step-by-step guide for anyone that would like to get started building an EOS dapp.

To Begin, I highly recommend using Docker and installing the EOSIO Dev image. Follow the official EOSIO documentation here. https://developers.eos.io/eosio-nodeos/docs/docker-quickstart

Creating a Wallet

In order to build a dapp that actually interacts with a wallet and accounts, we’ll need to set those up.

In a terminal, type cleos wallet create

This will return a password. Save this somewhere safe as you’ll need it again soon.

Note: If this doesn’t work, you didn’t alias your ‘cleos’ in step 1 above. Make sure you follow the entire docker-quickstart guide provided by EOSIO.

If you ever run into an issue where your wallet is locked, just type cleos wallet unlock

And then enter the password you saved previously.

Creating Accounts

In order to interact with dapps, you’ll need to have an account inside of your wallet. Let’s go ahead and set up an account. We begin by importing two sets of keys into our wallet. One will be the OwnerKey and one will be the ActiveKey. Make sure you save both key pairs. The OwnerKey should be kept highly secure at all times.

Create your OwnerKey

In your terminal, type cleos create key

The terminal will return a Private Key and a Public Key.

Next, type cleos wallet import [Private Key from above]

The terminal will return imported private key for [Public Key from above]

Create your ActiveKey (same steps as creating OwnerKey)

In your terminal, type cleos create key

The terminal will return a Private Key and a Public Key.

Next, type cleos wallet import [Private Key from above]

The terminal will return imported private key for [Public Key from above]

Create your first account

In your terminal, type

cleos create account eosio user1 [Owner Public Key] [Active Public Key]

Once you have finished creating your first account, you can follow the same steps to create a second account (if, for example, your application will have users send tokens to one another). I’ll assume that you created a second account called user2.

Creating a token (EOSIO makes this really easy!)

First, we’ll create a token. Unlike Ethereum, creating a token ecosystem is super simple with EOS and can be done from a terminal. We’re going to deploy the standard token that comes with EOS, but you can easily modify and customize the token contract or build your own from scratch.

Start with creating an account to which we’ll deploy the token contract. Follow the steps in Creating Accounts (above) to generate an OwnerKey and ActiveKey.

Then, in your terminal

cleos create account eosio eosio.token [New Owner public key] [New Active public key]

Next, we’ll deploy the standard token contract into this newly created account.

cleos set contract eosio.token build/contracts/eosio.token -p eosio.token

Note that in the line above the -p eosio.token indicates that the account eosio.token is giving permission to deploy the contract. It’s possible that your wallet will be locked, in which case you’ll want to unlock the wallet before doing this by following the unlock steps in Creating a Wallet (above). When you create your own custom contracts, you’ll deploy them the same way we did here, but instead of cleos set contract eosio.token , you’ll replace eosio.token with your custom contract.

Next we’ll create a token currency with your token contract. You can name the token whatever you want and set the total # of tokens issued.

cleos push action eosio.token create ‘[ “eosio”, “1000000000.0000 TOK”]’ -p eosio.token

The example above creates 1bn TOK tokens with ‘eosio’ as the issuer. The final step is to issue tokens to one of our accounts. Note that ‘memo’ is a way of attaching a string description to transactions. Also, we’re now getting permission (via -p) from eosio rather than eosio.token, since the eosio account holds all 1bn tokens.

cleos push action eosio.token issue '[ "user1", "100.0000 TOK", "memo" ]' -p eosio

That’s it, you’ve now got tokens ready to be plugged into your app ecosystem!

Using EOSJS To Connect EOS to your dapp

For an actual application, you’ll likely want to create a custom contract. But we have enough now to crank out a MVP, so I’ll next show you how to actually interact with the EOS blockchain from your application.

If you don’t already have a react application set up, type

create-react-app [name of your react app]

In that base directory, type the following into your terminal to install eosjs and add it to your package.json

npm install eosjs -s

Then in your App.js file, you’ll want to import eosjs using:

import Eos from “eosjs”;

We’ll have to initialize an instance of eosjs to use it in our application. Do so by adding the following to the global scope. Note that user1ActivePrivKey and user2ActivePrivKey are the private keys we created in Creating Accounts. Don’t use the Owner Keys here; Active Keys are safer. You should save these keys as environmental variables and import them if you’re going to make this code public at any point.

const eos = Eos({

keyProvider: [

user1ActivePrivKey,

user2ActivePrivKey

]

});

Now we can easily interact with our local EOS node. Our first step is to check the token balances of our two user accounts.

eos.getCurrencyBalance(“eosio.token”, 'user1').then(tokenBalance => {

console.log(tokenBalance)

});

Since we issued tokens to user1 in the previous section, you should see the current token balance of 100.0000 TOK. If we check on the token balance of user2, you should not see any balance.

eos.getCurrencyBalance(“eosio.token”, 'user2').then(tokenBalance => {

console.log(tokenBalance)

});

In this example dapp, we’ll have some pretty basic functionality. We’ll assume user1 is receiving some value and, in exchange, sending tokens to user2. In eosjs, the best way to do this is via a ‘transaction’. Here, we’ll send 5 TOK

eos

.transaction({

actions: [

{

account: "eosio.token",

name: "transfer",

authorization: [

{

actor: "user1",

permission: "active"

}

],

data: {

from: "user1",

to: "user2",

quantity: `5.0000 TOK`,

memo: "some description of the transaction"

}

}

]

})

.then(result => {

// Check token balances again. You'll now see 5 TOK in user2’s

// account and 95 TOK in user1’s account

});

When you build a custom contract, you’ll interact with it the same way that you interact with the token contract.

Next Steps

For additional examples from the EOSIO team and to build additional functionality for your dapp, go to the official EOS documentation.

Questions? Issues? Please leave a comment and I’ll work with you to get this going. If you found this guide helpful, clap a few times to help other aspiring EOS devs find it. Also, let me know if you’re interested in an advanced guide. We built something much more complex for the hackathon and I’m happy to share more!

If you want to read more about my experience at the hackathon, check out my other article here!