EOSIO Smart Contracts: Beginners Guide

EOSIO is a blockchain protocol powered by its native cryptocurrency EOS. The protocol emulates most of the attributes of a real computer including hardware (CPU(s) and GPU(s) for processing, local/ RAM memory, hard-disk storage) with the computing resources distributed equally among EOS cryptocurrency holders. EOSIO operates as a smart contract platform and decentralized operating system intended for the deployment of industrial-scale decentralized applications through a decentralized autonomous corporation model.

EOSIO is an open source blockchain protocol. So, individuals and organizations can use it to set up their own blockchain networks.

The first step is to clone eosio from https://github.com/EOSIO/eos with –recursive flag.

Now, we’ll build EOSIO. EOSIO community gives an automated build script for the following environments:

Amazon 2017.09 and higher
Centos 7
Fedora 25 and higher (Fedora 27 recommended)
Mint 18
Ubuntu 16.04 (Ubuntu 16.10 recommended)
Ubuntu 18.04
MacOS Darwin 10.12 and higher (MacOS 10.13.x recommended)

EOSIO smart contracts are, usually, coded on C++. So, you have to specify a header file with the declaration of functions (that correspond to smart contract actions) and a .cpp source file with their definitions. This leads to the creation of .abi (Application Binary Interface), which holds all the actions that the smart contract has. In addition, external systems need this file for executing the smart contract operations.

EOSIOCPP

EOSIO provides and recommends a compilation tool called eosiocpp.
for the compilation of the smart contracts.

EOSIO ships with its standard c++ libraries, i.e., when you clone the source, you will notice a folder: {$PROJECT_ROOT}/contracts/libc++ ⇒ This directory has all the standard c++ library headers and this is where eosiocpp looks for the included standard header files.

A detour to .wasm

WebAssembly (abbreviated Wasm) is a binary instruction format for a stack-based virtual machine, and has the following features:

Designed as a portable target, high-level languages like C/C++/Rust use Wasm for compilation. It enables deployment on the web for client and server applications.
Secondly, it enables executing code nearly as fast as running native machine code.
Thirdly, it speeds up the performance of critical parts of web applications by complementing JavaScript, and so, enables web development in languages other than JavaScript.
Engineers from Mozilla, Microsoft, Google, and Apple develop Wasm at the World Wide Web Consortium (W3C).

Click here to find out more about Wasm.

EOSIO smart contracts – a brief overview

If you have clicked on this article, you probably know a bit about smart contracts, but let us quickly establish a definition to proceed. Smart contracts are self-executing contracts. Here the buyer and seller ‘code’ the terms of the agreement on blockchain. The code and the agreements contained therein exist across a distributed, decentralized blockchain network. Smart contracts allow trusted transactions and agreements among disparate, anonymous parties without the need for a central authority, legal system, or external enforcement mechanism. So, they render transactions traceable, transparent, and irreversible.

There are a couple of preliminary things that need to be carried on before we jump on the deploying our escrow smart contract. The official documentation page for EOSIO has this in a very clear and precise manner.

Escrow Smart Contract

An escrow is basically a buffer where the token (currency) involved in the transaction is temporarily held. It is held till we know that the transaction can be completed without dispute. So here, the operation under focus for this article is estransfer ( i.e escrow transfer). This is the operation used to transfer the fund from the sender to the escrow. It is complemented by esrelease which releases the funds from the escrow to the recipient.

First, define the class for your smart contract in the header file.

Now, all the member functions corresponding to the actions should be made public. The .abi file of the smart contracts should have their declaration.

Since our escrow smart contracts also issues the tokens needed for transactions it needs to have a table to store the data corresponding to the issued token and the balance for any account of that token. This is done using the multi_index container provided by the EOSIO library (which is modelled after boost::multi_index_container) as follows:

Tables:

The two tables defined are accounts and stat. Firstly, different account objects make up the accounts table. Each hold the balance for a different token. Secondly, the stat table is made up of currency_stats objects (defined by struct currency_stats), that holds a supply, a max_supply, and an issuer. Before moving on further, it is important to note that this contract will hold data into two different scopes. The accounts table is scoped to an EOSIO account, and the stat table is scoped to a token symbol name.

According to the ‘eosio::multi_index’ definitions, code is the name of the account which has write permission and thescope is the account where the data gets stored.

Scope

The scope is essentially a way to compartmentalize data in a contract so that it is only accessible within a defined space. The accounts table uses EOSIO account as the scope of the token contract The accounts table is a multi-index container which holds multiple account objects. Token symbol indexes every account object which contains the token balance. When you query a users’ accounts table using their scope it returns a list of all the tokens that the user has an existing balance.

This is our smart contract’s header file.

.cpp implementation

The .cpp source file has the actions implemented. Definition of our estransfer action starts off with some assertion checks:

Firstly, we assert checks if the sender and receiver accounts are not same, then we check that the transaction has an authority of the sender, authority for a transaction can be specified by using -p flag with cleos.

Next, we fetch the table corresponding to the current token.

These lines notify the specified accounts after a successful transaction

A few more checks follow this:

Finally, we call the two most important utility functions, add_balance, and sub_balance, the former adds the tokens to a specified account and the later deducts it.

Let’s look at sub_balance in a little more detail

First, we fetch the table of accounts objects, the account being that of the sender in estransfer. A few minor checks follow this. If all checks pass, you should modify the account’s balance by subtracting the value to be transferred. Once, the number of tokens to be transferred are equal to the total available tokens in the accounts, we essentially delete the entry for the sender account from the accounts table.
Here is our escrow.cpp file in entirety.

So, this is the structure of the ABI file that documents the actions of the smart contract.

Here is the escrow.abi file:

Working with our escrow smart contract using cleos (command line utility as provided by EOSIO).

First, we need to set the contract and create a token

Now, we can check at the moment if any account has some token balance for the token we just created, and the result should not surprise you.

Post the setting of escrow smart contract and the creation of token balance, we can push the action for issuing this token to some user “ned”.

Finally, when we check the account for “ned” we can see the token balance for this account

We are in a situation to transfer funds from “ned” to “jon” (R+L=J)

Now, we have used the account “escrow” with which we had deployed the smart contract as our Escrow for this transaction.

Then, we can check the balance for “escrow”

Finally, this is the final table structure after pushing the release action.

That’s the end of this tutorial. For any doubts, please email the author at aktiwari@deqode.com. For developing an application based on EOSIO, please drop your email here.

Must read: Understanding Blockchain, Its Scalability Issues, and their Solutions