This is a series of blog posts in which I’ll cover some common EOSIO smart contract vulnerabilities and then explain how we can use our EOSIO vulnerability scanner, Inspect, to perform static analysis to uncover these vulnerabilities.

This week, I look at Missing Authorisations.

The vulnerability

In EOSIO, a developer can use two functions to control authorisation of smart contract actions by checking whether the declared authorisation of the action equals the account that should be able to run the action. These are:

• require_auth(account [, permission])
• has_auth(account)

Due to missing authorisation controls, a vulnerable smart contract grants authorisation to untrusted accounts such as malicious parties, to:

• access/modify privileged smart contract resources e.g. smart contract tables,
• Call functions of other contracts on behalf of the vulnerable contract, or
• Perform mission-critical contract actions e.g. token withdrawals.

Let’s look at an example of where a smart contract is setup such that it is paying for EOSIO RAM (which is what EOSIO calls the on chain database) storage costs, in such a scenario every write to the database should be checked to ensure that the entity calling the action that contains the database write has the proper authorisation to do so. Otherwise incorrect data may be written, or a RAM filling attack (see severity below) may occur.

In the action code below, despite there being a require_auth() call prior to the emplace call (which writes data to the _users table), the user is not the RAM payer, allowing any user to write to the database using the contract account's own RAM making the contract vulnerable to a RAM filling attack.

ACTION emplaceself1(name username, const std::string &display_name) {
 // unsafe
 require_auth(username);
 // contract is paying for RAM, requires checking get_self() auth, otherwise RAM filling attack
 _users.emplace(get_self(), [&](auto &new_user) {
   new_user.username = username;
   new_user.display_name = display_name;
 });
}

Modifying the action so that the user pays for RAM, makes the action immune to a RAM filling attack (as the user is no longer using the contract’s resources for RAM):

ACTION emplaceself2(name username, const std::string &display_name) {
 require_auth(username);
 // safe
 _users.emplace(username, [&](auto &new_user) {
   new_user.username = username;
   new_user.display_name = display_name;
 });
}

Severity

The impact of this type of vulnerability is that a hacker could:

• Write/modify/delete any data stored in RAM that is not adequately guarded by an appropriate authorisation check,
• Call functionality that should ostensibly be reserved only for the smart contract’s administrators/privileged users,
• In EOSIO RAM is not free so a hacker can fill up a smart contract’s RAM with spurious data and exhaust the dAPP’s resources leading to a denial of service for legitimate users.

Finding the vulnerability with Inspect

Inspect employs a technique called Static analysis. Static analysis is performed by reasoning about a computer program’s source-code, or some intermediate representation, without actually executing it.

With Inspect we perform static analysis on the WASM binary code, this is decompiled and then lifted into a proprietary intermediate representation (IR). Inspect then takes the IR, represents it in a database which we can mine for patterns of known vulnerabilities.

Running Inspect on a smart contract containing the above smart contract actions gives the following result:

Auth Violation: ✘
Action: emplaceself1    Insn: ($fel) = db_store_i64($feb, $fec, $fef, $feh, $fej, $fek)

The first action is correctly flagged as violating the Authorisation check. As Inspect operates on the WASM byte code, it reports the violation occurring at the EOSIO intrinsic, db_store_i64(), that corresponds to the emplace() call.

The second action is not reported as it is safe.

In a real analysis scenario, the next step would be to correlate this result with the source code and confirm that this is truly a vulnerability.

What else? What vulnerabilities would you like me to cover next?

The growth of blockchain applications has resulted in increasing amounts of value being controlled by smart contracts. Making smart contracts very lucrative targets for bad actors looking to exploit any vulnerabilities for quick profit. A successful smart contract exploit can have a disastrous effect on the value of the application's token.

To help developers catch smart contract bugs early in the development cycle, we are pleased to announce the open availability of Inspect, our automated smart contract analysis tool. Inspect performs static analysis of EOSIO WASM bytecode, mining the smart contract binaries for security bugs and flagging them to the developer before they find their way into production.

If you're in charge of securing your blockchain applications security then you'll want to take a look at:

• The Inspect Getting started document with examples of usage
• The open-source database of common EOSIO vulnerabilities, many of which Inspect automatically identifies

Sign up for Inspect here.

For further details and questions about Inspect then join the discussion.

At Klevoya we already provide a free version of our Hydra EOSIO smart contract test environment. Hydra allows you to quickly run unit tests, without requiring a local development node and easily integrate your tests within a CI/CD environment. Developers using Hydra have seen a significant improvement in the time they need to develop their smart contract test suites.

Speed improvement

But what if your current Hydra test suite takes too long to execute?

To solve that we now offer a premium service; Hydra Advanced which (depending on your location) can give you a 3-5x speed-up in the time to execute your tests.

You can sign-up for Hydra Advanced here.

vRAM support

vRAM by LiquidApps is an alternative memory solution for EOSIO developers building blockchain dApps that is RAM-compatible, decentralized, and enables storing & retrieving of potentially unlimited amounts of data affordably and efficiently.

Developing and testing of vRAM enabled smart contracts is not easy as it requires setting up and running a local DSP node which is even more complicated than running a regular EOSIO node.

Today we are pleased to announce that Hydra supports vRAM, all through the same easy interface that developers are used to.

To see how you can integrate vRAM into your smart contract tests check out these examples in the Hydra documentation.

For further details and support with these features then join the discussion.

You’ve just finished the development of your EOSIO smart contract and you’re ready to release it for the whole world to use. But before you do, take a step back and make sure you have all the bases covered. Deploying your contract to production is a big step with (literally) a lot at stake and can be a scary and daunting task. Especially in the blockchain world, where one regularly reads about smart contract hacks involving millions of stolen funds.

That’s why we’ve put together a checklist on things you should do before releasing your smart-contracts.

1) Follow coding best practices

Make sure that your contract follows coding best practices. This usually leads to cleaner code which in return leads makes spotting bugs easier.

2) Compile production build

If your contract has certain code paths that are only used for testing make sure they are removed or turned off by defining C++ macros for production builds.

3) Implement a safety switch

You never know if and when something will go wrong with your contract. Therefore (depending on your project) it may make sense to add a pause button that will stop all your other actions from executing.

4) Thoroughly unit-test your contract

Code rarely works perfectly the first time. The best way to catch bugs early is by writing unit tests while developing your smart contract. For EOSIO smart contracts our tool Hydra can help you with this.

5) Beta-test on a testnet

Before deploying your smart contracts to production on a main-net, roll them out to beta testers on a test-net. You'll get valuable feedback that isolated unit tests cannot provide.

6) Run automated vulnerability scanners

Running automated vulnerability scanners on your smart contract code doesn’t require much effort and results in a fast security check that can detect common vulnerabilities.

7) Code audit

If you are building a decentralized finance application or any other application that manages a lot of user funds, receiving a security audit by a team of professional security auditors is highly recommended.

8) Check account permissions and secure private keys

EOSIO account permissions can be complex. Double-check that your desired permission structure is set up on all the accounts and that you used fresh private keys.

9) Sufficient resources?

Make sure your smart contract accounts have enough CPU/RAM available. Consider borrowing resources from EOS Rex or automated resource management like @ChintaiEOS ARM.

10) Keep track of smart contract versions

When working on a new feature or maintaining the contract, its very important to know the exact code that is currently deployed. So tag the contract version in git.

11) Be careful when you deploy

It’s advisable to deploy early in your workday so that there’s enough time to test your system on production and fix potential problems that might occur.

Final thoughts

Pushing the button to deploy your smart contracts to production doesn't have to be a scary task as long as you are sensible and follow pre-deployment best practices.

For a more in-depth look into the pre-deployment best practices download the PDF version here.

You've sat down at your terminal, opened up a terminal and are ready to start debugging your new smart contract.

You type in nodeos, hit Enter and then see those cryptic words every EOSIO smart contract developer who has ever played around regularly with nodeos dreads:

nodeos replay required

Or, my personal favourite:

nodeos database dirty flag set

What in the....? You think. Why is the database dirty?

You start Googling and going through EOSIO Dev Telegram posts for a solution, all the while wondering how it suddenly became your job to be a part-time BP!

You figure out how to clean your dirty database, which will probably require you to completely wipe your local test net and reinitialise the state of your smart contract and all your local system contracts. And eventually you get your tests running.

Until it happens again.

"This is backwards," a little voice whispers inside of you. "There's got to be a better way."

And the truth is, yes you can write a bunch of shell scripts that will setup your test environment and have it working just the way you like it. While this is very flexible and allows quick prototyping, it takes some effort to create the scripts in the first place. It's like re-inventing the wheel and missing out on all of the advances in automated testing frameworks that run a suite of tests every time you make a code change.

What’s important in a test environment?

To get the most out of automated testing, it’s important that a testing framework supports the developer in 2 ways:

Simplicity

The testing framework should make it simple to write and run tests.
Specifically when testing EOSIO smart contracts, a testing framework should eliminate a lot of the tedious and repetitive tasks encountered when testing:

1. Having to set up and maintain an EOSIO network
2. Preparing the blockchain for the tests: Creating test accounts, managing private keys, setting up account permissions, setting the smart contract code, and bringing the blockchain into a testing state, e.g., by creating and issuing tokens
3. Sending transactions and observing the outcome by checking contract tables or action traces

Repeatability / Determinism

The point of having automated tests is that they can be run anytime on code changes, for example, on the CI server whenever a team member commits new code to GitHub to ensure a change did not negatively affect existing features (regression testing). The tests need to be easily repeatable for every developer and run in the same blockchain environment every time. This usually means running the tests on a local or private EOSIO network that is fully controlled.

Public testnets can be problematic because the environment constantly changes and cannot be reset. One is at the mercy of the chain’s RAM/CPU/NET restrictions, token faucets, and might encounter unstable BPs experimenting with non-standard settings. Private testnets mean having to maintain and debug your nodeos installation and running on high-end machines.

Testing without nodeos

It is possible to run tests without directly connecting to an existing nodeos node. There are several test frameworks that do this by either running a stripped down nodeos version or not requiring running a node at all.

This removed overhead makes them great for writing unit tests and allows for more flexibility as they are not restricted by the node behaviour. On the other hand, one cannot use them for deploying and running tests on a real EOSIO network.

Hydra

Hydra is one such testing framework that allows you to quickly get started writing unit tests.

Tests are written in JavaScript or TypeScript and allows you to use familiar JavaScript testing frameworks like Jest and Mocha.  In addition, it comes with some convenience features like bootstrapping test files, loading initial table contract data from JSON files, or being able to change the block time.

The reason it can do all this is that it runs on a customized EOSIO version (run by the Klevoya team) specifically designed for unit testing. Hydra therefore does not require any additional local setup at all, albeit it does need an internet connection.

This allows tests written in Hydra to be easily integrated into CI systems and the developer workflow. Along with its simple API and good documentation it's a great choice to test EOSIO smart contracts.

Check out Hydra

We hope this helps you see that there is an alternative to debugging those cryptic nodeos errors. Check out Hydra and see how easy it is to get testing!

For more details on how Hydra compares to nodeos+cleos, EOS Native Tester, EOSIO Unit Tests & Boost, or other EOSIO test frameworks, then download our EOSIO test framework comparison guide.

EOSIO software developer Block.one announced today that it has awarded Klevoya with a $50k grant to further develop it's smart contract verification system and foster the adoption of blockchain technology.

"At Klevoya we know that building quality dApps is complicated. So we made it our mission to help EOSIO dApp developers ship bug free, secure code. With the support from the EOS.VC grants program, we will increase the number of vulnerabilities that our Inspect smart contract analysis tool can detect,"  said Moti Tabulo, Founder of Klevoya. "Developers who are using Inspect and Hydra, our smart contract execution environment, have found that checking for bugs in their smart contracts is not the painful experience it used to be," he added.

At Klevoya our goal is to help EOSIO developers ship bug free, secure software. When we started talking to potential users, a common theme we heard was that developers spent too much time on verifying their smart contracts. This led us to explore an idea – what if testing just worked? What if instead of fiddling around with nodeos installs, running your own blockchain and multiple test scripts with cleos commands you could just open your IDE and start running tests. What if developers who want to test their smart contracts didn't have to also work as block producer administrators. What if developers could just write and run their test cases without setting up a blockchain on every computer they wanted to work on. What if test teams could easily integrate tests into a CI environment. What if test teams could rapidly spin up many hundreds of test variants.

Existing test environments solve some of these problems by wrapping your local EOSIO node's chain_api in some easier to use format. However you are still restricted to all the limitations and disadvantages of running a local blockchain; making sure it is installed locally, correctly set up, and running whenever you run your tests.

Introducing Hydra

Today, we're changing this. Hydra is a simple and fast EOSIO smart contract test and execution environment that allows you  quickly create and execute test cases without needing to maintain and run a local blockchain. The approach we have taken with Hydra is fundamentally different: Whilst it has similar APIs to existing testing tools, it eliminates all of the drawbacks of running a local blockchain by running a modified EOSIO node on our back-end which is specifically designed for testing. Hydra also comes with many convenience features (e.g. CLI to bootstrap tests and loading of smart contract tables from JSON files) that allow you to very easily write tests for your smart contracts.

How to get Hydra

You can get started using Hydra here. Try it, we think you'll like it.

Smart contracts are programs that, once deployed, execute autonomously on blockchains. Depending on the blockchain being used (and the method of smart contract deployment), these smart contracts can be to a smaller or larger extent immutable. Immutable in the sense that once deployed they may not be modifiable by their creator.

If you've ever developed a significant piece of software then you know that deploying SW that is right the first time is extremely difficult as the SW you develop may contain a variety of bugs:

• Logical errors
• Business errors
• Security vulnerabilities

While logical and business errors can be mitigated to some extent, security vulnerabilities in blockchain smart contracts can be much harder to recover from. Smart contracts often control crypto tokens that are pseudonymous and easily transferrable into liquid cash. This makes smart contracts very lucrative targets for bad actors looking to exploit any errors for quick profit at relatively lower risk of detection. In fact this is so common that the blockchain space is rife with incidents of bad actors exploiting smart contracts for real world gain.

Avoidance is better than cure

To avoid these exploits software developers are adapting techniques from off-chain development ranging from:

• Following smart contract development best practices
• Auditing their contracts via a thorough review of the code
• Subjecting their deployed contracts to white hat hackers

In this piece we concentrate on the second of these; auditing your smart contracts to discover vulnerabilities before deployment. Auditing can take two forms. Firstly, what many in the space are familiar with is a manual review of the business and programming logic of your smart contract by a team of experts who are well versed in the state of the art of security vulnerabilities. These experts pore over the design and source code of your smart contracts with the aim of identifying any exploits. Depending on the size and scope of your smart contract this process may take anything from a week to a couple of months and cost anywhere from $50k to $500k. Smart contract auditing is a very specialised skill and so it is unlikely that many of the nascent projects in the space will have such an expert internally. They will typically rely on commissioning an external organisation to conduct their audits.

Even if the organisation commissioning the external security audit is well-funded, multiple iterations through such an audit are likely to be time and cost prohibitive. Organisations therefore leave such audits as the last step before deploying their smart contract to their blockchain of choice. In this world of agile development, this feels rather like going back to the old days of waterfall development. In short, manual security audits are simply not scalable.

A second approach which is now beginning to gain traction is the use of smart contract analysis tools that perform an automated review of the smart contract to identify vulnerabilities. Whilst the results from automated analysis may not catch the full breadth of issues exposed by a properly in-depth manual security audit, automated analysis does have the benefit that it is relatively lower cost and more convenient to execute than a manual audit. This allows automated analysis to be used within the development cycle to catch potential issues prior to the code being submitted for a final manual security audit. Automated analysis also enables developers to leverage the efforts of a handful of expert smart contract security researchers making automated analysis a much more scalable approach.

Automated smart contract vulnerability analysis methods

Automated vulnerability analysis of software programs is a well researched area with a rich pedigree in the off-chain world of web, desktop and enterprise software.  In designing an automated analysis approach, there are two main areas where trade-offs need to be made:

• Reproducibility: what steps need to be taken to exactly trigger a vulnerability define whether or not a vulnerability is reproducible. Some analysis approaches may not capture information on how to trigger a vulnerability and so any vulnerabilities identified may need to be manually verified.
• Semantic insight: Insight into how and why a program, or parts of it, behaves.

Typically automated analyses cannot optimise for both reproducibility and semantic insight. High reproducibility typically means low coverage as to make results reproducible an analysis needs to be able to understand how to reach the code under analysis; removing this requirement means that an analysis can achieve much higher code coverage. However the lack of reproducibility results in a high false positive rate (i.e. a false alarm for a vulnerability that does not actually exist). A high semantic understanding on the other hand may necessitate processing and storing of a large amount of data. Attempting an analysis that achieves both full semantic insight and identifies reproducible vulnerabilities may not be entirely different from executing the smart contract through all of its possible input permutations which is typically unscalable for a smart contract of sufficient complexity.

Automated vulnerability analysis can be divided into two types:

• Static vulnerability analysis: identifies defects before you run a smart contract
• Dynamic vulnerability analysis: identifies vulnerabilities after you run a smart contract

Static vulnerability analysis

Static vulnerability analysis on a smart contract is performed by reasoning about the code without actually executing it. Normally the analysis is done on some representation of the smart contract's source code, either the source code itself or some intermediate form that is above the object code. Occasionally static analysis can also be done on the object code.

Advantages of Static Analysis?

• It can achieve very good coverage of the smart contract under analysis and can often cover every possible execution path
• It can be easier to trace the vulnerability back to the exact location in the code

Static vulnerability analysis does have some drawbacks:

• Results are not reproducible: information on how to trigger the vulnerabilities identified is typically not captured and so the vulnerabilities may need to be verified to avoid false positives.
• Lack semantic insight: They operate on simpler data domains and may have reduced insight into why a part of the smart contract has a vulnerability or what parts of the input cause misbehaviour

Dynamic vulnerability analysis

Dynamic vulnerability analysis is performed by executing the smart contract on a real or virtual processor and subjecting it to test inputs to verify its behaviour under a variety of conditions. Unit testing a smart contract to find errors is one of the most common method of dynamic analysis.

Automated dynamic analysis techniques are split into two main categories: concrete and symbolic execution.

• Concrete execution involves running the smart contract as normal against carefully crafted test cases provided by the user. A common dynamic concrete execution technique is fuzzing, where malformed input is provided to a smart contract in an attempt to discover a vulnerability.
• Symbolic execution executes the smart contract in an emulated environment using symbolic variables and tracking the state of the smart contract throughout program execution. At each conditional branch the analyser follows every path and saves the path condition. The analyser can then use the accumulated path conditions to reason on how to exactly trigger an identified vulnerability.

But how does dynamic analysis fare against static analysis?

Advantages of Dynamic analysis.

• Vulnerabilities identified are highly reproducible as you have the inputs or path conditions required to trigger the vulnerability
• It allows for analysis of smart contracts in which you do not have access to the actual code.

Drawbacks of Dynamic analysis.

• Fuzzers typically require carefully crafted test cases to avoid identifying only shallow vulnerabilities.
• Similar to static analysis, fuzzers have limited semantic insight into what parts of the input caused a vulnerability to be tirggered. This makes it more difficult to trace a vulnerability back to the exact location in the code. Symbolic execution on the other hand offers high semantic insight.
• With symbolic execution the number of condition paths causes an exponential increase in the possible paths to be explored limiting the complexity of smart contracts that can be analysed.

As can be seen from above, both static and dynamic analysis techniques have different advantages and disadvantages. One technique cannot be said to be definitively better than the other. To take advantage of their different attributes we see some of the leading suppliers of smart contract analysis tools use both types of analyses in their offerings.

Top Vulnerability Analysis Tools for Ethereum and EOS

Now that we have a fundamental understanding of the different smart contract vulnerability analysis methods, what tools are available to check your Ethereum and EOS smart contracts for bugs?

1. MythX
   
   SaaS platform that combines static, fuzzing and dynamic symbolic analysis of Ethereum smart contracts. Developed by a Consensys spoke. Offers an API that tools (such as IDEs, web interfaces etc) can use to enable security scanning in their application. Pricing from 199 DAI per user. https://mythx.io/plans
2. Mythril
   
   Developed by some of the team that were behind MythX. Utilises dynamic symbolic execution. Open source and free to use.
3. Securify
   
   Online and open-source security scanner for Ethereum smart contracts that performs static analysis. Online version is free to use, but requires signing over rights to submitted source code.
4. Manticore
   
   Open source dynamic symbolic execution analysis tool. Can analyse Ethereum smart contracts and Linux ELF binaries. Appears to be actively maintained with multiple contributions to its Github repository over the last 3 months.
5. Smartcheck Online and open source static analysis tool that translates Ethereum Solidity code into an XML based representation on which it checks against security patterns. Its Github repository does not show much sign of recent activity.
6. Octopus
   
   Octopus supports basic analysis of smart contracts allowing contract disassembly, control flow analysis and conversion byte code into an Intermediate Representation. Although it is one of the few tools we found that supports both Ethereum's EVM and EOS' WASM byte code formats, it currently cannot run a vulnerability analysis. That is planned in the future through dynamic symbolic execution. Its Github repository does not show much sign of recent activity.

Conclusion

Automated vulnerability analysis is a burgeoning field that will help secure smart contracts.

There are a variety of tools available, but these primarily target the Ethereum ecosystem. We found only one tool that has minimal support for EOS.

Do you know of any tools that we should include in the list? Do you think automated analysis can be a substitute for manual review? Let us know what you think in the comments.

EOSIO programs are typically written in C++ and then compiled into a smart contract for execution on an EOSIO blockchain.

But did you know that C++ is not the only programming language that EOSIO programs can be written in? Some projects are working on Python and even Solidity based programs. These are all compiled down into platform independent code that can be run on the EOSIO WASM Virtual Machine (WAVM).

So the WAVM does not need to know anything at all about the high level programming language (C++, Python, Solidity etc). All it knows how to do is to execute its own binary instruction set called WebAssembly.

What is WebAssembly?

The project to develop a new portable, size efficient binary format for the web was driven by the major browser vendors (Mozilla, Google, Apple and Microsoft). Apart from portability, WebAssembly's other design goals were for it to be:

• Fast: Able to execute at near native speed
• Safe: code executes in a sandboxed environment and eliminating dangerous features
• Hardware independent: Implementable by web browsers and other completely different execution environments such as datacenters, IoT devices, mobile/desktops etc
• Not break the web (allow calls/bindings to JavaScript)
• A human-editable text format that is convertible to/from the binary format

These goals, as well as the large browser ecosystem working to continuously improve it, make WASM a great choice for smart contract execution platforms. Apart from EOSIO, WASM is also planned to be used by Ethereum.

The EOSIO WAVM

EOSIO's WASM Virtual Machine (WAVM) is based on Andrew Scheidecker's standalone WAVM.

Stack Machine

The WAVM is a stack machine with two main components:

1. a last-in, first-out stack is used to hold temporary values. Most of the WAVM instructions therefore assume that operands will be taken from the stack and results placed back on the stack.
2. A program counter that controls the execution of the program and is modified explicitly by control instructions and implicitly advanced when non-control instructions execute.

This is in contrast to most modern computers that implement a register machine where temporary values are held in a set of registers.Advantages of using a stack machine over a register machine are that stack machines allow for:

• Compact object code: as instructions deal with values from the stack and do not need to select which registers to use
• Simple compilers: as no register management is needed making code generation fairly trivial
• Simple interpreters: particularly for Virtual Machines interpreters for stack machines are simpler as the logic for handling memory accesses is just in one place
• Easier control flow: control flow is expressed as structured constructs like blocks, if and loops that have clear labels at their beginning and end. The WAVM has  Implementing control flow like this makes it very easy to compile and manipulate WASM and verify the correctness of control flow in a WASM program.

A simple execution example

We can now go review a simple example to illustrate the whole flow from source code to WASM to execution of that code in the WAVM.As prerequisites we assume that you have:

• Installed the EOSIO Contract Development Toolkit (CDT)
• Have access to the Web Assembly Binary Toolkit (WABT pronounced wabbit). You can do this by running the eosio-wasm2wast/eosio-wast2wasm binaries that come with CDT. Alternatively you can also download and build the generic WABT version from https://github.com/WebAssembly/wabt. (A cursory examination seems to indicate that this versions are compatible if you disable "Generate Names" and "Fold Expressions")

Compiling Hello

For this example we'll be compiling the basic Hello World program:

#include <eosiolib/eosio.hpp>
#include <eosiolib/print.hpp>


using namespace eosio;


class hello : public contract {
  public:
      using contract::contract;


      [[eosio::action]]
      void hi( name user ) {
         require_auth( user );
         print( "Hello, ", user);
      }
};


EOSIO_DISPATCH( hello, (hi))

Running the eosio C++ compiler eosio-cpp:

eosio-cpp -o hello.wasm hello.cpp

eosio-cpp -o hello.wasm hello.cpp

This takes the C++ source file and converts it into an intermediate representation (IR) using a compiler tool chain called LLVM. LLVM performs some optimisations and then a back-end converts from the LLVM IR into WASM.

We get a WASM file, hello.wasm which is in binary. To make it readable we need to convert it into a WASM text format as follows:

eosio-wasm2wast hello.wasm -o hello.wast

This WAST file is typically huge (approximately 900 lines) so we will only concentrate on the first 50 or so lines here to illustrate some important concepts.

WASM sections

The WebAssembly module is composed of several sections. Some sections are required in all WASM modules and some are optional (you may see the optional modules appearing at the end of the WAST file).Required:

1. Type. Contains the function signatures for functions defined in this module and any imported functions.
2. Function. Gives an index to each function defined in this module.
3. Code. The actual function bodies for each function in this module.

Optional:

1. Export. Makes functions, memories, tables, and globals available to other WebAssembly modules and JavaScript. This allows separately-compiled modules to be dynamically linked together. This is WebAssembly’s version of a .dll.
2. Import. Specifies functions, memories, tables, and globals to import from other WebAssembly modules or JavaScript.
3. Start. A function that will automatically run when the WebAssembly module is loaded (basically like a main function).
4. Global. Declares global variables for the module.
5. Memory. Defines the memory this module will use.
6. Table. Makes it possible to map to values outside of the WebAssembly module, such as JavaScript objects. This is especially useful for allowing indirect function calls.
7. Data. Initializes imported or local memory.
8. Element. Initializes an imported or local table.

Section examples

For our Hello.wast file this looks like so:

(module
  (type (;0;) (func (param i32 i64)))
  (type (;1;) (func (result i32)))
  (type (;2;) (func (param i32 i32) (result i32)))
  (type (;3;) (func (param i32 i32)))
  (type (;4;) (func (param i32 i32 i32) (result i32)))
  (type (;5;) (func (param i64)))
  (type (;6;) (func (param i32)))
  (type (;7;) (func))
  (type (;8;) (func (param i64 i64 i64)))
  (type (;9;) (func (param i64 i64 i32) (result i32)))
  (type (;10;) (func (param i32) (result i32)))
  (import "env" "action_data_size" (func (;0;) (type 1)))
  (import "env" "read_action_data" (func (;1;) (type 2)))
  (import "env" "eosio_assert" (func (;2;) (type 3)))
  (import "env" "memcpy" (func (;3;) (type 4)))
  (import "env" "require_auth" (func (;4;) (type 5)))
  (import "env" "prints" (func (;5;) (type 6)))
  (import "env" "printn" (func (;6;) (type 5)))
  (import "env" "set_blockchain_parameters_packed" (func (;7;) (type 3)))
  (import "env" "get_blockchain_parameters_packed" (func (;8;) (type 2)))
  (import "env" "memset" (func (;9;) (type 4)))


  (table (;0;) 2 2 anyfunc)
  (memory (;0;) 1)
  (global (;0;) (mut i32) (i32.const 8192))
  (global (;1;) i32 (i32.const 16700))
  (global (;2;) i32 (i32.const 16700))
  (export "memory" (memory 0))
  (export "__heap_base" (global 1))
  (export "__data_end" (global 2))
  (export "apply" (func 11))
  (elem (i32.const 1) 12)
  (data (i32.const 8192) "Hello, \00")
  (data (i32.const 8202) "read\00malloc_from_freed was designed to only be called after _heap was completely allocated\00"))

Here we see that there are 10 function signatures and indices for the functions in this WASM file

These signatures are similar to function prototypes and define the expected inputs and outputs for each type of function.

There are also some imported functions  such as

(import "env" "read_action_data" (func (;1;) (type 2)))  
(import "env" "require_auth" (func (;4;) (type 5)))
(import "env" "prints" (func (;5;) (type 6)))

We can also see our print statement being initialised in memory:  

(data (i32.const 8192) "Hello, \00")

The beginning of the code section contains the actual function bodies for each function in this module. Looking back at the function definitions we see that there is one function exported which has an index of function 11:

(export "apply" (func 11))

This is the apply function that is called when an action is issued to this smart contract:

  (func (;11;) (type 8) (param i64 i64 i64)
    (local i32)
    get_global 0
    i32.const 16
    i32.sub
    tee_local 3
    set_global 0
    call 10
    block  ;; label = @1
      get_local 1
      get_local 0
      i64.ne
      br_if 0 (;@1;)
      get_local 2
      i64.const 7746191359077253120
      i64.ne
      br_if 0 (;@1;)
      get_local 3
      i32.const 0
      i32.store offset=12
      get_local 3
      i32.const 1
      i32.store offset=8
      get_local 3
      get_local 3
      i64.load offset=8
      i64.store
      get_local 1
      get_local 1
      get_local 3
      call 13
      drop
    end

Deploy your smart contract!

The last thing to do after compiling your smart contract is to send it to the blockchain by issuing a set code transaction using the cleos command line tool.

cleos set contract hello $YOURDIRECTORY/hello -p hello@active

When the block producer (BP) node receives the set code action it proceeds to create an instance of the smart contract WebAssembly module in the EOSIO blockchain's RAM. Instantiating the WebAssembly module is what makes it functional and the BP node does so by resolving memory references, linking external C++ functions and giving access to the exported functions like the apply() function.

Once the BP node completes this step the smart contract WebAssembly module will be on the chain's RAM and any BP node can then access actions intended for the smart contract.

Trigger an action!

Now that the smart contract is on chain, you can trigger it by sending an action to the smart contract using cleos:

cleos push action hello hi '["bob"]' -p bob@active

The message will be sent to the BP node which will load the smart contract WebAssembly instance and call the apply() function.

If you are curious, here's how the WebAssembly virtual machine would execute the first few instructions in the function:

  (func (;11;) (type 8) (param i64 i64 i64)
    (local i32)
    get_global 0
    i32.const 16
    i32.sub

• get_global 0: gets the value of the global variable at index 0 and pushes it onto the stack
• i32.const 16: Pushes the constant value sixteen onto the stack
• i32.sub: remember we said WebAssembly was a stack machine earlier? With a stack machine all values an operand needs are pushed onto the stack before the operation is performed. The sub instruction knows that it needs two operands and will simply take the last two values from the top of the stack and return the result to the top of the stack. This means that instructions can be short (one byte for sub) as the instructions don't need to specify source or destination addresses which makes for more compact WASM files.

Finally after the whole WebAssembly module has been executed, you should then see the smart contract reply:

Hello, bob

Closing thoughts

WebAssembly allows smart contract developers to write EOSIO applications in C++ (and in future other languages such as Solidity and Python) and ensures that the resulting code can run efficiently across different BP nodes.

It is perfectly possible for a smart contract developer to deply a distributed application (dApp) without knowledge of WebAssembly or how the WAVM works. However understanding how it works may help you to tackle difficult problems from time to time and deal better with security vulnerabilities in your smart contract.

In Part 1 we covered what an EOSIO sister chain was. In this piece we look at how the two pre-eminent contenders, Telos and Worbli compare to the EOS MainNet. Let the battle commence!

EOS MainNet

More information: no single website

Network status: Launched early June 2018

Value proposition: the original EOSIO based chain.

Pros

1. The big sister of them all. As such it captures most of the mindshare from Block Producers (BPs), investors (it has the highest market cap of all EOSIO chains by a huge margin), distributed application (dApp) developers and users.
2. Only chain that can lay claim to the EOS brand.
3. Perhaps the only EOSIO chain that makes it economically viable to run a BP node on. With multiple BPs running on other sister chains, the MainNet may effectively subsidise the sister chains.

Cons

1. It's size and status means that it has limited range for innovation across the technical and governance aspects that differentiate sister chains.

Telos

More information: https://telosfoundation.io

Network launch status: Launched December 2018

Value proposition: Learnt from the mistakes that EOS MainNet made at launch, more developer friendly.

Pros

1. Economic decentralization – Telos based its genesis snapshot on that of EOS, but capped each individual account to a maximum of 40k EOS (this is a cap on the genesis accounts only, in future a single account can acccumulate more than 40k TELOS). Potentially this means that voters are incentivised to vote in the early days as their vote counts for more.
2. DApp friendly: a) Lower cost of dApp deployment: TLOS currently trades at around 20-25x lower than EOS making network (CPU, NET and RAM) resources a steal for dApp developers. b) No RAM speculation: have an elected RAM Admin Director who can suggest RAM policy to the BPs and can also purchase/sell RAM to meet their RAM goals. c) Features dedicated to developers: IPFS storage, regular user token holder snapshots (that allow developers to choose which one to base their airdrops on)
3. No zombie BPs and equitable pay: Standby BPs are rotated into the top 21 every 3-7 days so they actually need to be ready to produce blocks. On pay, the top 21 BPs get the same pay, whilst an additional 30 standby BPs get 50% of what the top 21 get.
4. Proprietary dApps are allowed: EOS MainNet requires all dApps to be open-sourced (although many do not follow this rule), TELOS allows closed source/proprietary dApps.

Cons

1. BP pay is unviable: the TLOS token price is too low to make running a BP cost-effective: some estimates that running an EOS BP has a break even token price of ~$1.75 to $2. With a token price 1/25 of that, it's hard to see how BPs operating solely on Telos can fund their operations
2. Will it overcome voter apathy: Not clear whether voters will still be incentivised to vote despite the capped voter accounts.
3. CPU issues follow from MainNet: Telos might have solved the RAM problem, but the rampant RAM speculation on MainNet has quietened down. What plagues MainNet now is a regular lack of CPU resources for their Apps to run. Telos does not look like it will offer anything novel in this regard except perhaps for the implementation of REX as and when block.one release the feature.
4. Smaller user pool, lack of brand name recognition: EOS MainNet has the majority of investor and user interest.

Worbli

More information: https://worbli.io/

Network launch status: Launched November 2018

Value proposition: On a mission to enable opportunity. Worbli wants to build the infrastructure for an honest, efficient and accessible financial system. By developing the world’s most cost-effective and developer-friendly, consumer and enterprise blockchain platform.

Pros

1. A walled garden with a user base of AML/KYCed customers: to sign up for a Worbli account requires each user to undergo Know Your Customer (KYC) and Anti-Money Laundering (AML) checks. This will reduce the friction for businesses (primarily financial ones that need AML/KYC).
2. Low friction finance setup for companies new to blockchain: Worbli initially promised they would be setting up a digital-crypto bank Gamma bank. They soon came to realise that that would be a huge undertaking which would require resolving regulatory issues across multiple jurisdictions. The ambition has now been tempered somewhat to instead introduce banking like facilities starting with a chain wide crypto-fiat exchange. In theory, once a dApp has been accepted onto Worbli then they should already be able to trade their token for fiat. For companies that have had to deal with delays in getting a bank account, or their token listed on exchanges, this could be a killer feature.
3. Proprietary dApps are allowed: EOS MainNet requires all dApps to be open-sourced (although many do not follow this rule), Worbli allows closed source/proprietary dApps.
4. Business centric approach: contrary to other EOS sister chains Worbli appears to be following a more traditional business development strategy where they seek to identify and bring value added partners to their network. This is in keeping with their strategy for a curated experience.

Cons

1. Centralised for 2 years: for the first 2 years of its operation the Worbli Foundation will exert control of the network directing everything, from which BPs can produce, through to which applications are allowed on the network (only the Worbli foundation can delegate RAM to dApps). Voting for the BPs and Foundation members is currently locked and will not be open until the 2 year period elapses.
2. BP pay might be unviable: similar to Telos, the current value of the WBI token is too low to make producing blocks solely for Worbli unviable. However, it is not clear to what extent the Worbli Foundation is offering incentives to BPs to produce on their network.
3. Opaque governance model: at the time of publishing this post Worbli had yet to issue their Governance structure and documentation. This post will be updated once they do.

And the winner is

It's still early days with the launch of EOS sister chains. New sister chains seem to crop up monthly with sometimes little to differentiate them. At the moment if your dApp needs the user base, investor community and mindshare etc then the EOS MainNet has to be your first port of call. Telos has some interesting developer centric features that may make it the preferred chain for early developers. If you are developing a finance based application in a heavily regulated industry then Worbli's model for a pre-KYCed/AMLed userbase could be very attractive. However the current lack of public clarity on its governance structure may give some room for pause.

However, with EOSIO based dApps able to run on any EOSIO chain, then dApps may see the choice of whether to run on EOS or a sister chain as closer to an internationalisation feature.

Just as savvy web Apps choose to launch first in Canada, do all their learning and iteration and then re-launch in the USA, we may see dApps apply a similar market launch strategy. Deploy on a sister chain like Telos first where resources are cheap, prove some of the business and financial model and then re-launch on MainNet to access the larger user and investor base there.

If you’re new to the EOS world you may have heard the words “sister chain” and “side chain” crop up in conversations.

First, a bit of background. Block.one develops the EOSIO open source blockchain software, but has been very clear that they will not run any EOSIO based blockchain network. Instead, they view themselves as a provider of EOSIO software that will enable a potential multitude of EOSIO based networks.

When block.one released the EOSIO software in June 2018, it was then taken by a group of candidate Block Producers who launched what has since come to be termed the EOS main network (aka MainNet) as the only network with the “EOS” token that is listed on various cryptocurrency exchanges. block.one has since then come out to say that they encourage multiple EOSIO based blockchain networks based on its reference implementation. Coming from the Ethereum world where there is - for all intents and purposes - only one public and active Ethereum network [1] this concept can be a bit counter-intuitive to understand. Having multiple EOSIO chains is not necessarily a bad thing. In fact, as we will see it enables a diversity of chains that cater to particular niches.

Which brings us to sister and side chains. Terminology for what differentiates a sister and side chain varies, but we would propose some simple definitions:

• Side chain: any chain that uses the same token and token issuance as the EOS MainNet
• Sister chain: any chain that has its own token and has a different token issuance to the EOS MainNet.

A side chain therefore can be seen as an extension of the EOS MainNet with the same governance model and the same (or a subset) Community as the MainNet but perhaps only differing by some technical parameters such as how CPU and RAM is managed and priced.

For side chains to be useful, they will need to be able to synchronise regularly with the MainNet. For this Inter Blockchain Communication (IBC) is needed. Block.one has not publicly released any roadmap for IBC. Until they do side chains are a useful theoretical concept that has yet to be seen in practice.

Why do we need sister chains again?

In a word “differentiation”. Side chains differ technically but will adopt the same governance model that the MainNet does. Launching a sister chain allows for differentiation technically AND on the more squidgy Governance side.

This means that sister chains can tweak all of the following parameters to better suit their perceived dApp and Community audience:

• Governance
• Choice of Block Producers
• Dispute Resolution model
• Token holders
• Technical: Resource management (CPU, RAM and NET) and Source licensing

The EOS Family

It feels like every month there is a new EOS sister chain being launched. In no particular order here are the ones we know of.

1. Everipedia
2. ONO
3. Telos
4. Wax
5. Worbli
6. EOS Force
7. EuropeChain
8. Enumivio
9. EvolutionOS
10. StrongBlock?
11. BOS Core

Conclusion

EOS Sister chains are positively encouraged. Will this lead to diffraction of the developer and user community? Or is it is a benefit? As a developer which one do you launch your dApp to?

In the next piece we profile 3 contenders; MainNet, Worbli and Telos. Stay tuned!

Know of a sister chain that we’ve missed? Let us know in the comments.

[Update] Part 2 of this series can be found here.

[1] Sure there’s Ethereum Classic, but the market cap of ETC is 20x smaller than that of ETH so we can disregard it.