Introducing EOSFactory, an EOS smart-contract development and testing framework

EOSFactory logo.png

Since autumn 2017 Tokenika has been putting in extensive efforts towards creating a Python-based EOS smart contract development platform, allowing for easy creation, testing, and deployment of smart contracts. As EOS was evolving, we got used to sudden changes of its underlying code and practiced to curse less as we went along ;)

Today, the day has finally come and we are very excited to hand over our work to the EOS community. Our newborn baby is going under the name of EOS Factory and is intended as a full-fledged, fully documented, cross platform IDE in which, using a simple command-line interface you'll be able to:

Launch a private EOS testnet
Compile an EOS smart contract
Run it through unit-tests
Tweak it until you feel it’s ready
Deploy it on EOS

Why it’s needed?

Undoubtedly, everything that EOSFactory offers can be done with the official EOSIO toolset, i.e. cleos and eosiocpp. Does it make EOSFactory just a simple alternative to those tools? Not really.

Try to go through EOS tutorials based on cleos and you'll see how much concentration is required to follow those simple examples without making a single mistake. And now imagine doing it 10 or 100 times. Surely, it's a daunting task!

Code development and unit-testing involve tasks that need to be executed hundreds of times, and each time in exactly the same way and context. Therefore those tasks need to be fully automated, or otherwise a lot of time is being wasted and, what’s even worse, a lot of additional uncertainty is introduced. Manually performed actions are prone to errors.

This is what EOSFactory actually brings to the table: an easy & intuitive way to automate the process of dealing with smart-contracts. Write down, in the form of a Python script, what needs to be done multiple times in exactly the same way and context, and then just run the script. EOSFactory will take care of everything else: it will compile your smart-contract, create a new testnet, deploy the contract, invoke its methods and verify the response, then tear down the testnet, and finally report the results. And all of this done in a couple of seconds.

Cross-platform compatibility

One of our major goals was to make EOSFactory compatible with all major operating systems, allowing developers to run and interact with an EOS node on everything from Linux through OSX to Windows 10. We’re pleased to report that this has been successful. As far as we know, no other EOS development solution is able to offer that. EOSFactory works nicely with Visual Studio Code. This will allow you to write EOS smart-contracts, play and unit-test them, all within one robust IDE. Also, this release is compatible with the newest release of EOS Dawn 4.0.

Architecture

In EOSFactory we use Python to interact with smart-contracts. However, under the hood, our toolset is powered by C++.

Thus EOSFactory is composed of two layers:

C++ bridge called teos connected to an EOS node running a private testnet,
Python wrapper called pyteos acting as a convenient human-oriented interface.

In other words, we have Python outside, while C++ powers the insides.

Development cycle

This is what a smart-contract development cycle might look like:

Write a smart-contract (in EOS's native C++).
Write unit-tests (in Python).
Compile your smart-contract.
Start a fresh single-node testnet.
The testnet is initialized with the bios contract and a couple of test accounts to play with.
Deploy your smart-contract.
Run your unit-tests.
Tear down the testnet.
Modify your smart-contract and/or unit-tests and jump to stage 3.

In EOSFactory every step of the above process is fully automated by Python classes and methods - you, as a developer, only supply the creative part, i.e. contents of the smart-contracts and unit-tests. Unit-tests are designed to be written in Python, while of course smart-contracts are written in C++. Visual Studio Code perfectly supports both those languages.

Object-oriented vs. procedural

Thanks to Python, what you are dealing with in EOSFactory are classes and objects. For example, a smart-contract is an object, and you handle it by using its methods, e.g. contract.build(), constract.deploy(), contract.push_action(), and contract.get_table(). This is the opposite of procedural commands used in cleos, the official CLI for EOS.

Documentation

You'll find the source code of EOSFactory in this repository, and over here a list of available documentation.

Roadmap

EOSFactory is still under development, and things are getting ironed out and improved. Right now we are working on the following features:

Upgrading to a more advanced mechanism for creating and managing unit-tests. They will be stored as a hierarchy of Python files, in a similar way the process is organized in Ethereum's Truffle Framework - we just use Python instead of JavaScript. Also, we plan to add support for other IDEs, e.g. Eclipse.
Secondly, we are considering the pros and cons of connecting our Python layer directly to cleos, the official EOS CLI. When we started working on EOSFactory, cleos (at that time named eosc) was in a bad shape and thus not suitable for our needs, so we had to build our own C++ interface to an EOS node. As things get smoother, we might reconsider relying on cleos.
And finally, we are thinking about integrating Ricardian Contracts into our unit-testing. This is a very interesting (and probably not widely known at this stage) aspect of EOS smart-contracts. For more information please refer to EOSIO documentation.

We plan to have the next release of EOSFactory in a couple of weeks, ideally before EOS is launched.

We hope this is helpful, and any feedback, especially critical, is very welcome. If you find what we do useful, you can express your support by voting for Tokenika in the upcoming EOS Block Producer election - we have more exciting EOS projects in the pipeline. Stay tuned!

Thanks :)

We intend to move the C++ layer (it's called teos) into a separate repository, with EOSFactory having it as a dependency. So yes, once we do that you could use teos as a foundation for other projects.

Actually, we'd love to see it being used that way, as it was designed with this purpose in mind - that's why it's a static library, not an executable like cleos.

However, there is one important thing we need to take into account: teos is dependent on EOSIO source code, which unfortunately is incompatible with Windows - you cannot build EOS with any C++ compiler that's available on Windows. We've tried it for a long time and it looks quite hopeless. The main obstacle is that EOS is heavily dependent on an integer type that's not supported by Windows.

So I guess any .NET-based solution is out of reach, at least at this moment.