Dipping Our Toes into ARK Core
06 July 2018
Without a doubt, the best way I've found to understand code is to write it; reading it ranks as a close second. Accordingly, the best way to understand code for those who don't code is to read code, and that's what we'll focus on in this series.
if statement and a
for loop, you'll be fine.
There are two primary goals of the Understanding Code: ARK series. The first, as you might guess, is to understand how ARK Core works. We'll be working from the outside in: beginning with how ARK Core makes its information available to external developers, we'll explore deeper levels of the codebase until we understand the core mechanisms of the blockchain itself.
The second, broader goal is to impart technology enthusiasts of all levels of programming expertise with the necessary skillsets to begin understanding code on their own terms. We'll explore how to decipher a codebase you've never worked with before — how to understand developers' goals and the strategies they implement to achieve those goals.
The purpose of virtually all code is to solve a problem. Understand problems and their solutions and you've come that much closer to understanding code.
Getting Started — Where To Look
As you probably already know if you've read this far, the best way of exploring open-source code is through exploring a project's GitHub page. You can find the code for ARK Core v2 here.
Trying to navigate at GitHub as a non-coder can be pretty intimidating. Let's break it down.
I've created a video for this column that goes through the basics of GitHub using Ark Core v2 as the base project. In another column, I'll go through GitHub in detail, including its relation to Git, the program that powers GitHub's functionality and allows developer to release code in versions. Until then, here's the video breakdown:
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/quyLwJzw8cA" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
I'll assume some basic knowledge of GitHub, either through your own experience or through watching my totally-awesome-and-not-improvised-at-all video above. With no further ado, the code!
This is what the Ark Core v2 repo looks like at first glance. Lots of files with periods in front of their names, and a couple folders.
The important thing to understand here is that the "core" repo is simply a central place to organize all of the packages that comprise Ark Core. You can find all of the individual packages within the
packages directory, and we'll dive much more into each individual package later in this column as well as later in this series. Suffice it to say for now that most of the files at this top level involve configuration options to make the process of developing all of these packages easier.
package.jsons in our quest to understand the various libraries that make up Ark Core.
Here is a screenshot of the top-level
package.json, as taken from my computer:
The two keys we're most interested in here are
devDependencies key refers to a list of packages that this library depends on, as well as what versions of those packages the library requires. For example, we know from reading this document that this library requires
lerna to function properly, and that the version of
lerna must be at least
scripts key is a list of commands that can be run on this package. In this case, there are commands like
test, which runs tests across the entire Ark Core,
commit, which commits code to GitHub using commitzen, and more.
As mentioned previously, most of the libraries we'll find in this top-level
devDependencies key, you can see that every dependency has its own version — Lerna helps keep those dependencies consistent across your project to coordinate work across all packages. You'll notice that many commands in the
scripts section refer to Lerna, such as
clean and others.
You'll notice lots of references to Eslint. This package is important for two primary reasons: maintaining a consistent coding style, and preventing some classes of bugs from making their way into code. When you have many different developers working on a single project with their own coding styles, the resulting effort can feel a bit disjointed, like a book with multiple authors who don't talk to each other before publishing. Eslint fixes those inconsistencies by applying a single coding style to every package in the repository.
Jest, and the closely-related Jest-Extended, are testing libraries. We'll cover tests in short order, but the SparkNotes is that tests are often the quickest and easiest way to understand how a library operates. That's because, when designed well, tests are describe how your code functions at the highest level possible. The how of your code is hidden, but the what of your code is easily readable and accessible.
Putting It Together
From this description, it immediately becomes clearer what some of the mysterious "dot files" are doing for this repository.
lerna.json contains customizations that ARK Core has specified for Lerna to use: where to find the packages it should bundle within the repository, for example.
.eslint specifies how eslint should lint the repository, and
.eslintignore tells eslint which files it should ignore while doing so. Similarly,
jest.config.js provides Jest with information that allows it to run tests within the specific context of ARK Core: which tests to always run, which tests should only run occasionally, where it should find tests to run, etc.
Importantly, there's nothing in the top-level folder that refers to anything blockchain-related. To keep things organized, all code that actually powers the ARK blockchain is contained within the
packages folder. The
docker folder is mostly important to developers looking to replicate the ARK toolchain on their own systems, and we'll ignore it for the purposes of this tutorial. With the
plugins folder being empty, let's inspect the packages folder and get to the meat and potatoes.
Previewing the Packages
Whoa. That's a lot of folders. And if we poke around a bit, we see that each package has a handful of their own files and folders, and even their own
package.json. What do we do now? Do we give up? Do we jump straight into the
core-blockchain folder and see if we can shortcut our way to blockchain enlightenment?
Not quite! We'll dive a little bit into our first package to start the next column in this series, but keep in mind our objective here is to work from the outside in. With that in mind, let's take another look at the ARK Core Readme to figure out what the best entry point is to experience the blockchain from a public perspective before delving into the blockchain's internals.
This is a screenshot from the relevant section in the Readme. At a glance, there are two packages that seem to fit our bill of requirements:
core-api. Both of these seem to deal with how the public interacts with the blockchain —
client is a client-side library that anybody can integrate into their own website, and
core-api describes how an ARK node should respond to requests from clients.
As mentioned before, looking at a package's tests is a good way of preview what its functionality is. With that, let's take a brief look at each packages' tests to see which might be better to start with.
Above, I've pulled out some of the first tests from each folder. We'll go more into these tests, as well as how to find them and understand them, in the next column. But at a glance we can see that the
client package tests lots of non-blockchain-related functionality: how to properly send an HTTP request, how to make sure URL typos won't break the package, etc. These are important concepts, no doubt, but understanding them won't get us much closer to understanding how ARK works. By contrast, the
core-api gets right into the details of the blockchain itself. We can see that this test expects to retrieve a list of all blocks. If we figure out what code this test is designed to cover — in other words, what code needs to be working properly for this test to pass — we'll know how the API retrieves blocks from the blockchain. From there, our journey into understanding how those blocks are created, stored and retrieved can begin in earnest.
So, we'll be looking at
core-api in the next column! If space permits, perhaps we'll cover another package as well, but let's not get too ambitious. It's more important that we get it right than get it quickly.