Introduction to EVM packages with ZeppelinOS

Note: There is a newer version of this tutorial updated for recent breaking changes in Solidity and Truffle.

EVM package deployment with ZeppelinOS — Part I: Introduction

Intro to ZeppelinOS and Package Managers

If you are familiar with Node.js then you will be familiar with NPM, Node Package Manager. You will also know that the ability to “ npm install " existing code into your project makes your life as a programmer easier and frequently more secure.

Being able to import existing code is a hallmark of a mature developer ecosystem and one of the fundamental tools that allow a programming language to reach an ecosystem of scale. The immense success of Node.js is due in no small part to the NPM ecosystem: in the last month alone NPM saw 33,839,343,034 downloads! (at the time of writing this)

Ethereum, and the primary language for smart contracts, Solidity is by comparison in its’ infancy. Yet the Solidity ecosystem is growing rapidly, and as it grows so does the complexity of tasks programmers are trying to solve. Starting from scratch for every project can be a major impediment to progress- especially when code can potentially store (and lose!) millions of dollars worth of real money. A frugal blockchain developer will try to write as little ‘new code’ as possible, instead of importing existing audited code libraries so as to reduce introducing new and unforeseen bugs as much as possible.

To this end, Zeppelin created Open Zeppelin, an open-source framework of battle-tested reusable smart contracts for Ethereum, (as well as other EVM and eWASM blockchains). Open Zeppelin smart contracts allow you to get up and running with standard blockchain tasks with the confidence that the code you’re using has been through rigorous testing by auditors and the open source community.

ZeppelinOS takes this idea even further by offering a development platform designed specifically for smart contract projects. It allows for seamless upgrades and provides economic incentives to create a healthy ecosystem of secure applications. Most importantly, it allows you to build projects that leverage the power of code that is already deployed on-chain . Not only does this dramatically increase the transparency of your project to your potential users, but it also saves you money as you don’t need to pay the gas cost to deploy entirely new copies of the existing code to the network- you just reuse the logic from contracts that someone else has already deployed!

With ZeppelinOS, not only can you now create upgradable smart contracts (where the upgrading process can be controlled by any number of governance techniques), you can now also create EVM packages to allow others to reuse, remix, and develop upon an open ecosystem.

What we will Learn

In this tutorial we are going to go over the complete process for creating, deploying and linking, on-chain solidity source code using NPM and the ZeppelinOS system.

You will learn:

  1. What EVM packages are, and what they are good for.
  2. The complete setup process for ZeppelinOS
  3. How to create a basic EVM Package along with basic testing in Truffle Console
  4. Deploying your EVM package to test-networks as well as Ethereum main net.
  5. Creating a new project and linking to your published EVM package.
  6. Interacting with your newly deployed on-chain library.

Who this tutorial is meant for:

This tutorial will aim to be as detailed as possible to cater to Solidity developers at all levels of experience. For beginners, it’s best to follow the entire document as I will build on steps from the previous section, while for more advanced solidity developers, feel free to skip ahead.

What are EVM packages?

EVM packages are collections of deployed on-chain code that you can easily incorporate and reuse in your own project via package managers such as NPM. This makes it easy to build upon open-source libraries created and verified by others in the ecosystem. ZeppelinOS not only makes the process of creating and using EVM packages simple- but offers additional tools to support community vouching of verified code.

What can we use EVM packages to do?

EVM packages are for any project that wants to build on existing code. A good example would be the Open Zeppelin implementation of the ERC-20 standard. While there are many implementations of the ERC-20 standard, Open Zeppelin’s open-source, public and audited code example has become the commonly accepted standard of a secure implementation.

For projects looking to launch an ERC-20 token, whether to use for a crowd-sale ICO or otherwise, it is simpler and safer to launch a token based on Open Zeppelin’s public implementation. If a project needs custom features, they can start with this base, and build additional functionality on top, confident that their base implementation code has already gone through a rigorous auditing process (they will still need to check the code they add, however).

Open Zeppelin offers a wide range of code you can start building with, from tokens to cryptography to ownership and permissions, but what about code snippets you write yourself? Or specialty use cases? This is where EVM packages come in.

What are we going to build?

For this tutorial, we are going to create our own EVM package for a solidity Linked List implementation: custom code that tackles a real use case. Our linked list will give your solidity projects an easy to use data structure that we will deploy on-chain and that you can re-use over and over for any project you might like. No “Hello World” here!

What do I need to get started?

If you are an existing Solidity developer familiar with tools such as Truffle, Ganache, node.js, and remix, you are probably already set up. If not, don’t worry- we will cover the steps necessary to get started.


Code Editor: VSCode, Atom or Sublime, Node.js, Truffle, Ganache (We will be using the command line interface version), ZeppelinOS, Xcode tools (while not strictly necessary, if you run into installation problems with NPM, sometimes this can help).

While this guide will be oriented towards Unix based operating systems such as Ubuntu or OSX, as long as you can get the core requirements running, it should work.

Let’s get started by creating a Linked List contract: