The colonyNetwork codebase is large and complex.

Those of you interested in joining our bug bounty program might want a bit of a primer on the Colony Network contracts before diving in.

This article is meant to just provide a quick lay of the land, and to point you, dear hacker, toward where we think the bugs might be. We'll also re-cap some of the bugs that have been discovered so far.

As always, we encourage you to read the docs to get a better sense of things, and come to gitter or post in the forums if you have questions!

Onwards!

Network Interface Abstraction

Colony uses the EtherRouter pattern for upgradability. You can read more about the pattern in this post about our token sale contracts, or get the slides from Elena’s TruffleCon presentation on the same subject.

The TL;DR: the entirety of the colonyNetwork is accessed through a proxy contract called EtherRouter . EtherRouter looks up the correct version of the colonyNetwork in a resolver contract, and then passes the function on via delegatecall .

This means that contract calls for particular functions never actually are sent directly to the contract in which the logic is written.

Instead, all functions callable by external actors are exposed through an _interface_ contract.

Business logic, such as the creation and funding of a task, is split into separate contracts that are organized by the functionality they describe. The logic contracts inherit from a separate set of storage contracts, in which all storage variables are written.

The colonyNetwork hamburger model

Maintaining this ‘layered’ separation helps with developer sanity, and will allow for easier upgrades to specific components in future versions of the Colony Network.

Just for fun, here's a diagram I made of most of the contracts that comprise the Colony Network. You can see the interface, logic, and storage layers separated, as well as which interfaces call which contracts:

This image is definitely a rough cut. Let @gichiba know on Gitter if you spot any inaccuracies!

Bugs Squashed so far:

Task Workflow

The most fundamental pattern in the Colony Protocol is the task. Tasks are discrete units of all the work that is being tracked by a colony, and it's exclusively through the completion of tasks that reputation can be earned within a colony.

The task lifecycle lives in colonyTask.sol

From start to finish, the life-cycle of a task looks like this:

Create

Modify

Rate

Payout

One recent bug discovered in the task workflow during the rating period enabled an attacker to submit null ratings and trigger finalization early, potentially resulting in an un-deserved reputation bonus if exploited correctly.

The potential impact of this bug was relatively low, given that it would have to go un-noticed by both manager and evaluator for 10 full days, but it's still an excellent catch!

Thanks Jakob, to the tune of $1,200 DAI!

Token Auctions

One of the more interesting aspects of Colony's economic model is the token auctions of the Meta Colony, the colony which performs network upgrades and maintenance.

Essentially, the Meta Colony stays funded through a small network fee imposed on any colony's tasks as they are finalized. For tasks paying out in Ether, that fee goes straight to Meta Colony revenue – but tasks can payout in any ERC-20 token.

Other tokens collected through the network fee are put into a dutch auction contract to be sold for CLNY, which is burned.

User Destiner discovered that under certain conditions, a token auction would not be able close properly. This could have resulted in some* stuck tokens!

$1,500 DAI to you, good sir!

*Because token auctions happen at most once per month per colony, using just a small percentage of each colony's task value, it wouldn't represent a lot of lost tokens, but it's still a significant find.

Secure the Network (and make some $)

The Bug Bounty program is still going strong! We want YOU to come kick the tires in on our Görli deployment.

To participate, all you gotta do is submit an issue describing the vulnerability, or send us an email at security@colony.io – go on, try us.

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.