This article is written for those of you out there who are interested in participating in The Colony Hackathon, but aren’t totally confident you’re ready to build something.

We know it can seem like a lot: That whitepaper alone is pretty intimidating. Merkle Proofs? What dat?

If you’re just a little bit unsure of yourself or your skills, it can be enough to say “Oh well, I wouldn’t have been able to do much anyways.”

But that’s not the spirit of a Hackathon! You should be able to contribute and build something cool even if you’re still learning — especially if you’re still learning.

So here are a few short explanations of some key concepts you’ll need to participate, so that you can feel good enough to dive in and figure the rest out as you go.

Git and Github

It’s *possible* that M$ is going to somehow corrupt the world’s biggest open-source development platform after it makes the purchase, but unlikely.

If you’re unfamiliar with how git works, there’s no better reason than the Hackathon to learn (or re-learn) the fundamentals!

Git is a distributed version control system designed to track and manage multiple versions of the same codebase across multiple computers. Using git, many people can keep track of the changes they make to a code-base, test new features without affecting ‘production’ code, and revert back to old versions if needed.

GitHub is a platform and service that hosts projects managed with git. Using GitHub’s services, groups of people can send comments to each other about specific code changes, organize development sprints, and even perform git operations with a web interface. GitHub has quickly become the most popular software development platform in the world, and it’s in no small part due to the fact that most open-source projects (including Colony) tend to choose GitHub as their home because it makes collaboration easy.

There are some basic concepts of git you’ll likely have already heard before, but it’s always good to do a refresher. Here are some good resources for getting up to speed on git and github:

The Git Handbook is a good starting point for a complete introduction to using git in to track your project.

The GitHub flow guide is a good overview of how most open-source projects use GitHub to keep organized with multiple collaborators on a project.

“Git — the simple guide” is a good cheat-sheet if you’re familiar with git/GitHub, but could use a reference on-hand with most of the commands you might need.

For the hackathon submission process, you’ll be doing some basic steps with GitHub, similar to the “fork and pull” model for open source development:

  1. Create an issue with your project in the colonyHackathon repository
  2. Create a new repository for your project. Work on it with friends, or go solo.
  3. When you’re ready to submit, fork the colonyHackathon repository. Inside your new forked repository, create a new folder for your project inside the submissions/ folder.
  4. Put into the folder any materials or links to external materials that you want considered. Be sure that one of the files in the folder is a clearly marked that describes your project.
  5. To submit, open a pull request to the main colonyHackathon repository before the submission deadline of June 24th, 23:59 G.M.T.

colonyNetwork: Truffle and Ganache

You’re reading stuff about Colony, so chances are good that you have done some reading about smart contracts and Ethereum. Perhaps you’ve been learning how to develop your own smart contracts or build dApps. It’s not a requirement to be familiar with the process, but knowing a bit about dApp development will certainly help quite a bit.

If you signed up for the Hackathon, you’ll have received a code that grants you 3 free months with Blockgeeks! You’ll find a really great course on the site called ETH102: Intro to building dApps — it’ll provide a solid background for the stuff below. Sign up for the hackathon to get that code and visit this link to redeem it.

The colonyNetwork smart contracts make use of the truffle development framework for testing and development. Truffle provides a lot of handy tools that make developing with smart contracts easier and more streamlined.

Jumping straight into the colonyNetwork contracts after cloning the repository might be a bit confusing if you haven’t been through the process before with your own smart contracts, because we’ve made it even more streamlined by automating deployment and testing. So let’s break down some of those scripts talk about the general process of testing:

Big picture #1: A smart contract is just a computer program that runs on a blockchain. Like a normal program, a smart contract is written in solidity (for the humans), and then compiled down to bytecode (for the computers). It’s the bytecode that *actually* runs on the blockchain, not the solidity. One of the main functions that truffle performs is to take our contracts, compile them to bytecode, and deploy that code to a blockchain virtual machine.

Big picture #2: Ethereum mainnet is expensive, and even the Ethereum testnets are not good if you’re in early stages of development or testing experimental features. So we need a local blockchain simulator to deploy our contracts to. That’s what Ganache is for: It is a blockchain environment, but we can bend the rules to make development easier — speeding up block times or increasing the gasLimit would be undesirable on the ‘real’ blockchain, but when you’re testing code, the ability to change the rules a bit is a feature, not a bug.

Big picture #3: Once deployed, you can interact with smart contracts by calling their functions with transactions from a (simulated) Ethereum client. But all smart contracts have an important constraint: Nothing on the blockchain can tell you how to correctly call a function in the contract. For this, you need a separate copy of your smart contract as a reference in order to correctly form the transaction in a way the contract understands. This is sort of like the song-list that matches arbitrary numbered codes to sweet tunes in a jukebox. You’ve got to read the contract functions, encode your desired transaction into a long number, and submit it to the contract on-chain. Truffle provides these tools as well for generating transactions.

The development process for any set of smart contracts, in a nutshell is:

  • Spin up a blockchain for testing and deploy your contracts to it
  • Poke at them (a formal, exhaustive set of poke-ings is called ‘testing’)
  • Shut down the blockchain, make some modifications and re-deploy. (AKA: change some stuff and see what happens)

In the colonyNetwork repository, scripts have been written that perform this whole process automatically. After setup, when you run yarn test:contracts, the script will do the following:

  • Spin up a Ganache blockchain pre-configured with the right settings and several test accounts (ganache-cli --gasLimit 7000000 )
  • Compile and deploy all of the colonyNetwork contracts to the testing blockchain. ( truffle migrate --reset --compile-all )
  • Run a battery of pre-written checks for all colony and colonyNetwork interactions, such as creating new tasks, assigning roles, creating new colonies, etc, speeding up time as needed. ( truffle test --network development )

colonyJS and TrufflePig

Imagine you’re going to *use* the colony smart contracts for an organization. You’re probably going to want to access it with a front-end of some kind, right? You’d expect there to be a button that says ‘create a new Colony’ somewhere, and perhaps another that says ‘fund task’ and gives you a place to input a number. Well, that’s software that wouldn’t be running on the blockchain. Instead, it’d be off-chain in an application, and that’s where colonyJS comes in.

To write the program that says “When someone clicks this button, I’ll send a transaction to the blockchain that creates a new task”, you need to make use of the colonyJS library.

In getting started with colonyJS, it’s a good idea to be comfortable with the ideas presented in the last section. Namely, you should feel okay about getting a test blockchain set up and running, with the colonyNetwork contracts deployed and waiting.

To start working your colonyJS project, some familiarity with JavaScript is needed. And for testing programs on your local blockchain with colonyJS, you need a friend: The TrufflePig!

Recall from the last section (big picture #3) that your programs need a reference contract in order to send functions to the blockchain. This is the job of TrufflePig: it takes the contracts from your local project, and serves them to your local JavaScript application so that it can form its own transactions to call functions on the blockchain.

With trufflepig installed, you can set up your JavaScript application to load contracts from trufflepig and use the contract information to generate the right transactions. You’ll then spin up a local ganache instance for testing, deploy the colony contracts to it, and run your program to see if it does what you expect it to do.

Writing a program is no small task, but you can copy some example code from the Colony docs to get off on the right foot:

There, you’ll find more detailed explanations and step-by-step instructions to set up colonyJS properly and start tinkering.

That’s it! There was a bit of hand-waving and generalization, but hopefully it was just enough of an overview to help you feel more confident to dive in and start experimenting with the colonyNetwork contracts and colonyJS. Good luck, and happy hacking!

If you have any feedback or stories to share, reach out to us on Twitter.

Colony is a platform for open organizations.

Join the discussion on Discourse, follow us on Twitter, sign up for (occasional) email updates, or if you’re feeling old-skool, drop us an email.