Ship: A package manager for developing smart contracts

A client framework and development environment for building, testing, and deploying distributed applications

Published in

Aergo blog

8 min readNov 5, 2018

Building large-scale distributed applications is tough. Testing them, making them work end-to-end, and deploying them is a time-consuming process. On Aergo, we plan to make things different.

Aergo is a platform that addresses the numerous unique challenges enterprises face when realizing blockchain-based systems and applications. To improve the efficiency and ease of developing, testing, and deploying smart contracts, we’ve created SHIP. SHIP is a Lua smart contract package manager. It connects local development environments with Git and the distributed ledger and so drastically reduces time spent building and managing smart contracts. It offers the following features:

Project setup: Complete the preparation for development in a simple task.
Installing packages from remote repositories: Packages on GitHub can be installed on local repositories.
Build: Combine (pre-process) the sources within a project to develop a product ready for distribution.
Unit test: Before uploading to the network, you can verify that the functionality of the new release works as desired.
Deploy to local repository: Install your developed projects in your local repository so they can be referenced by other projects.

SHIP’s most basic philosophy is conciseness; it’s lightweight, yet effective. Today, SHIP deliberately does not include a wide selection of development functions; however, importantly, SHIP is an ongoing project that will update frequently. We’ll take suggestions from our technical community and continue to add features seen as valuable.

Why did we create a package manager?

We often look to history in order to come up with our hypotheses. Earlier this month, Phil made a post explaining our approach to open-source execution based on the historical success of Linux and Red Hat. When it came to the development of distributed applications, we approached creating a package manager in the same way.

A list of major events in the history of the Web in chronological order

2009 to 2014 were the years when many technologies emerged to compete and shape what we know today as the modern Web.

Something to note is that following the creation of JavaScript, no build or package management tools were introduced between 1995 and 2010. The 15 years following JavaScript’s inception saw little progress in advancing the state of the Web. However, following the release of Node.js in 2009, package managers and bundlers became more common, enabling the creation of a new generation of dynamic webpages. The inception of npm, Node.js’ default package manager, enabled this rapid evolution of the Web.

In 2012, Trello published a post outlining the Trello Tech Stack. This post introduced a number of technologies that would make the Web work as an application rather than just as a page. It gives us today a good outline of the progress of the Web by 2012 and its rapid evolution seen in the prior few years. This rapid evolution was indeed caused by the creation of npm which reduced time spent developing webpages.

Like npm did to the Web, SHIP aims to mark a pivotal point in the the development of blockchain-based applications and smart contracts. SHIP will make the development, testing, and deployment of smart contracts seamless and efficient. Eventually, SHIP will arm Aergo with the usability required to attract the next generation of dApp and enterprise blockchain developers to create a thriving open-source ecosystem of developers.

How to use SHIP

In order to use SHIP, you must first download and install the following programs:

Git
JDK 8+
Node.js
npm

Building SHIP

SHIP is currently not officially released. If you wish to use SHIP, you will have to build it. SHIP uses the GitHub address below as a source storage.

aergoio/ship

Get the source from GitHub. (the $ at the beginning of the command displays the prompt, if prompted by system root, the prompt is #).

$ git clone https://github.com/aergoio/ship.git

Now run the build. At the first attempt to run it, the command is long.

$ cd ship$ ./build.sh clean deps npm assemble

Upon successful completion, you can see ship-$VERSION.tar file has been created in assembly/build/distributions.

Unzip this file to install SHIP.

Next, include the bin directory in the PATH path with the ship command. You can add .bash_profile to the last part. It may change, depending on your shell.

export PATH=$PATH:$SHIP_HOME/bin

SHOP_HOME refers to the unzip ship — $ {VERSION} directory. The installation has now been completed.

Building a project

We are now building a project for smart contract development. Create a directory for your project in the desired location.

$ mkdir my-first-project

In this article, I refer to this location as $ {PROJECT_HOME}.

The ship command assumes that the current working directory is the project directory. Let’s move the current directory to the project.

$ cd my-first-project

In order to make an empty directory as a project, you need a command below.

$ ship init

If it runs properly, a file named aergo.json will be created in the project directory. The aergo.json file should look like this:

{“name” : “bylee/my-first-project”,“source” : “src/main/lua/main.lua”,“target” : “app.lua”}

Change project setting

Information about the project is stored in aergo.json. You can edit this file if necessary. Let’s look at the properties of this file.

name — Project name: Use this name when importing or putting packages into the repository in the form $ {github_account} / $ {project_name}. Initially created as $ {username} / $ {project_name}, you need to modify it if your username and GitHub account are different.
source — Recognize the path of the source from which the build starts as a relative to the project folder.
target — The path to the file where you saved the build results. The built files are compiled and binaries and ABIs are generated and deployed to the Aergo server.
dependencies — The name of the package referenced. Package refers to the type of project installed in the repository.
tests — The path to the test source. As the name implies, this is an array type.
endpoint — Hostname and port information for the Aergo server to deploy and run for integration testing. $ {hostname}: Set it like $ {port}. The default value is “localhost: 7845”.

Since there is no change in the current state, we will move on to the next step.

Writing a smart contract

Now, let’s write simple code. The source is src/main/lua/main.lua.

function min(a, b)if (a < b) thenreturn aelsereturn bendend

I wrote a function that takes two numbers and returns a small number. Smart contracts currently supported by Aergo are based on the language lua. Let’s build the current source.

$ ship build

If there is no problem, app.lua file is created. If you open this file, it is exactly the same as src/main/lua/main.lua, because you have only one file to build. If you continue to modify the source and see how it changes, you can see how the build combines the files.

Previously, SHIP said it could build multiple files into one. Now, let’s refactor the main.lua file. You can use the import command to reference another source from the source. Move the min function to src/main/lua/utils.lua, replacing the existing main.lua with:

import “./utils.lua”

If you do a rebuild, you can see that the app.lua file is the same as before.

Creating unit tests

Let’s write a unit test for the min function in utils.lua we just created. We will write the test code in src/test/lua/test-utils.lua. The API for testing will be discussed in more detail in the next opportunity, and this time only an example will be shown.

import “aergoio/athena-343”local suite = TestSuite(‘test suite for utils.lua’)suite:add(TestCase(‘test min’, function()assertEquals(3, min(3, 4))end))suite:run()

Add a tests entry to aergo.json to tell SHIP that this is a file for testing.

{“name” : “bylee/my-first-project”,“source” : “src/main/lua/main.lua”,“target” : “app.lua”,“tests”: [ “src/test/lua/test-utils.lua” ]}

To run the test, run the following command:

$ ship testERROR : "Package aergoio/athena-343 not found: /Users/bylee/.aergo_modules/aergoio/athena-343/aergo.json"When you run the test, you get an error because the aergoio / athena-343 that you use as a test framework is not installed. Now, let's install the package in github.$ ship install aergoio/athena-343

Experimentals

Incremental build

SHIP has progressive building capability. This function detects changes in files in the project and automatically builds and tests them.

Additional parameters to the build command are required to run the function.

$ ship build --watch

If you have no problems running, you can see the following results. The example is the my-first-project.

If you change the source, you can see that the builds and tests are reflected in real time.

WebUI

In addition, we provide a web service that allows the browser to access the following additional port options.

$ ship build --watch --port 8080

In addition to providing more detail than the terminal provides, it also provides additional deployment capabilities. This deployment is for testing, so it goes to port 7845 on localhost. To use this feature, the server must be running and the aergoluac command must be set in the PATH.

You can also see the test results for each build, and the build keeps a record includes past five test results.

When you select the Runner menu, you are presented with a screen where you can actually run the deployed function

Conclusion

SHIP provides functions that support each stage of your development project, from set up through to deployment. It helps developers get structured programming out of existing programming methods, thereby making the process of developing smart contracts more seamless and efficient. Although SHIP does not yet have enough features and some aspects of development may be inconvenient, we plan to work with dApp developers to determine what’s of value and support them with better features in the future. We are waiting for your feedback!

In case you are unaware, we recently launched our pre-testnet and released the Alpha codebase for the Aergo platform. Feel free to spin up a local testnet, contribute to the code, or read more about the release here.

If you’re interested in learning more, feel free to join Aergo on any of our social media channels: