joincolony/colonynetwork

Colony Network smart contracts

The Colony Network

Contracts for running the Colony Network as defined in the Colony White Paper

Bug Bounty Program

Colony is offering substantial rewards to external developers who report bugs and flaws in the colonyNetwork contracts.

See the Bug Bounty program overview) for more information about bounties, rules, and terms.

Prerequisites

node v16.15.x (we recommend using nvm)

docker v18 or higher

Add the required solidity compiler by running:

$ docker pull ethereum/solc:0.5.8

Installation

In the working directory of your choice, clone the latest version of the colonyNetwork repository:

$ git clone https://github.com/JoinColony/colonyNetwork.git

Move into the directory and install dependencies:

$ cd colonyNetwork && npm install

Update submodule libraries:

$ git submodule update --init

Provision token contracts for testing:

$ npm run provision:token:contracts

Contracts

The contract upgradability is using the EtherRouter pattern, see the delegate proxy pattern in the documentation for implementation details.

The math, erc20, auth, roles and a significant part of the token contract have been reused from the Dappsys library.

Local Development and Testing

You can start a local test node and deploy the contracts yourself using the locally installed truffle package.

npm run start:blockchain:client

npx truffle migrate --reset --compile-all

To deploy all contracts and run all contract tests:

npm run test:contracts

To deploy all contracts and run all reputation mining tests:

npm run test:reputation

To run tests with code coverage using solidity-coverage:

npm run test:contracts:coverage

To lint contracts using Solium

npm run solium

To lint JS using eslint (this is also a pre-commit hook)

npm run eslint

Contributing

For details about how to contribute you can check the contributing page

colonynetwork's Issues

Increasing the TokenSupplyCeiling

5.1.2 Increasing the TokenSupplyCeiling

It is crucial that new tokens cannot be generated without widespread consensus — especially if
tokens have a financial value. Consequently, such decisions require a vote with high quorum and
majority requirements involving both the token holders and reputation holders.

Secure given Colony Network parameters to Meta Colony

3.2 Role of CLNY Holders and the Meta Colony

There will be permissioned functions on the Network Contract to allow fundamental parameters of the network to be set, which can only be called by the Meta Colony.
For these permissioned functions to be called by the Meta Colony, a vote open to all CLNY
and reputation holders must be conducted (see Section 11.4).

Examples of such network parameters are the Network fee, registering new Colony versions.

Note Section 3.3 Handling off decision-making power to the Meta Colony
Common Colony Token holders are responsible for Reputation Mining from the start, but decisions
about the underlying properties of the network will initially be made by a multisignature contract
controlled by the Colony team. As the network develops and is proved to be effective, control over
these decisions will cede to the Common Colony.

Reputation update log

6.4 Reputation update log

Whenever an event that causes one or more users to have their reputation updated in a colony occurs, a corresponding entry is recorded in a log in the ColonyNetwork contract. Each entry in the log contains:

• The user suffering the reputation loss or gain.
• The amount of reputation to be lost or gained.
• The colony the update has occurred in.
• How many reputation entries will need to be updated (including parent, child and colony-wide total reputations). This is the motivation for storing n_parents and n_children for each skill and domain, as described in Section 6.3.
• How many total updates to reputations have occurred before this one in this cycle, including
  decays and updates to parents and children.

If the reputation update is the result of a dispute being resolved (as outlined in Section 6.2.2), then instead of these first three properties, there is a reference to the dispute-specific record of stakes in the relevant colony. For the structure of this log, and an explanation of the way that it allows individual updates to be extracted in constant gas, see Appendix A.

This log exists to define an ordering of all reputation updates in a reputation update cycle that is accessible on-chain. In the event of a dispute during the reputation mining protocol (described in Section 7), the ColonyNetwork contract can use this record to establish whether an update has been included correctly.

Domain Creation

4.2 Domains

Of course, without structure, a large colony could quickly become difficult to navigate due to the sheer number of tasks —– domains solve this problem. A domain is like a folder in a shared filesystem, except instead of containing files and folders, it can contain sub-domains and tasks. This simple modularity enables great flexibility as to how an organisation may be structured. A
toy example is shown in in Figure 1.
This compartmentalisation of activity provides a tangible benefit to the colony as a whole. When objections are raised, they can be raised to a specific level in the colony’s domain hierarchy. This means that people with relevant contextual knowledge can be targeted for their opinion, and that when a dispute occurs, the whole colony is not required to vote in the dispute. Rather, only members with the relevant experience are asked for their opinion.
It is ultimately up to individual colonies to decide how they wish to use domains — some might only use them for coarse categorisations, whereas others may use them to precisely group only the most similar tasks together, or even multiple tasks that other colonies would consider a single task.
We aim to provide a general framework that colonies may use however they see fit, and to only be
prescriptive where necessary.
In order to create a domain, the creating user must have sufficient reputation in the domain that will become a parent, and must stake a small amount of colony tokens. These thresholds will be larger than for task creation, as the creation of a domain is more significant than the creation of a task.
The token stake for creating a domain will be able to be claimed by the creator once a task has been successfully paid out inside the domain — this indicates the domain is legitimate. In the event of a dispute being raised over the creation of the domain, if the domain is determined to be spurious, the stake is lost and the creator loses reputation.

6.2.3 Bootstrapping reputation

We note that the same is not required when a new domain is created in a colony. We do not wish to allow the creation of new reputation here, as this would devalue reputation already earned elsewhere in the colony. This bootstrapping issue is resolved by instead using reputation within the parent domain, when a child domain contains less than 10% of the reputation of its parent domain.
A domain below this threshold cannot have domains created under it.

Task completion and rating

4.1 Tasks

After the task has been assigned, the worker may make a ‘final submission’, which includes some
evidence that the work has been completed.
Once the due date has passed or the worker has made their submission, the evaluator may rate
the work. Regardless of whether the rating is positive or not, the task enters a state in which
objections to the final state of the task can be made and disputes can be initiated (see Section
9). Once three days have elapsed, no more objections or disputes can be raised. Once all pending
disputes related to the task are resolved, the parties involved get punished or rewarded based on
the final state of the task.
If the evaluator’s rating for the work is changed as a result of a dispute, they get a reduced payout
based on the discrepancy between their original score and the score that their peers determined to
be more appropriate. If an objection has determined the manager or evaluator should be punished,
they lose their stake, otherwise the stake is able to be reclaimed. The worker is paid based on the
final score awarded to their work, taking into account the result of any disputes.

Earning reputation from contributing to a task by Worker

6.2.1 Reputation change from contributing to a task

The actual number of reputation r earned by the worker for the completion of the task is then
a function of this rating s and the token payout t: r = t x ((2s - 5) / 3)

Reputation lost or gained as a function of the star rating therefore varies linearly between -(5t/3) and 5t/3 for 0 and 5 stars respectively, and a rating of 4 stars earns the user exactly t.

Action required: Greenkeeper could not be activated 🚨

🚨 You need to enable Continuous Integration on all branches of this repository. 🚨

To enable Greenkeeper, you need to make sure that a commit status is reported on all branches. This is required by Greenkeeper because we are using your CI build statuses to figure out when to notify you about breaking changes.

Since we did not receive a CI status on the greenkeeper/initial branch, we assume that you still need to configure it.

If you have already set up a CI for this repository, you might need to check your configuration. Make sure it will run on all new branches. If you don’t want it to run on every branch, you can whitelist branches starting with greenkeeper/.

We recommend using Travis CI, but Greenkeeper will work with every other CI service as well.

Once you have installed CI on this repository, you’ll need to re-trigger Greenkeeper’s initial Pull Request. To do this, please delete the greenkeeper/initial branch in this repository, and then remove and re-add this repository to the Greenkeeper integration’s white list on Github. You'll find this list on your repo or organization’s settings page, under Installed GitHub Apps.

Task schema and creation

4.1 Tasks

The smallest structural unit in a colony is the ‘task’. A task represents a unit of work requiring no
further subdivision or delegation. A task has three roles associated with it:

• A manager — someone responsible for defining and coordinating the delivery of the task.
• A worker — someone responsible for executing the task.
• An evaluator — someone responsible for assessing whether the work has been completed
  satisfactorily.
  These roles are assigned to addresses.
  The manager (usually the creator of the task) is responsible for selecting the evaluator and
  worker and setting additional metadata for the task:
• A due date.
• Bounties for each of the manager, the worker and the evaluator.
• A specification, or brief: to be used by the worker to guide the work, and by the evaluator
  for assessing the satisfactory completion of the task.

Upgrade token to implement ERC20-defined events

Upgrade TokenLibrary to include ERC20 defined events: Transfer and Approval
ethereum/EIPs#20

Reputation by Colony

6.1.3 Reputation by Colony

A user’s total reputation in a colony is the sum of their reputation in the top-level skill and the top-level domain. This is the reputation they will be voting with in any decisions that require input from everyone in the colony. Reputation in a colony has no effect outside the colony. In particular, reputations held in one colony have no bearing on reputations held by the same account in another colony.

Token Supplier

5.1.1 Token Generation and Initial Supply

When a colony is created, the TokenSupplyCeiling and the TokenIssuanceRate are set. The former is the total number of colony tokens that will be created and the latter is the rate at which they become available to the colony-wide domain to assign to tasks or subdomains. The number of tokens available to the colony-wide domain can be updated at any time by a transaction from any user.
At colony creation, some tokens must also be assigned to addresses to allow users to stake tokens to create the first tasks. A one-off lump sum may also be created and made available to the colony-wide domain.

5.1.2 Increasing the TokenSupplyCeiling

It is crucial that new tokens cannot be generated without widespread consensus — especially if
tokens have a financial value. Consequently, such decisions require a vote with high quorum and
majority requirements involving both the token holders and reputation holders.

5.1.3 Changing the TokenIssuanceRate

The TokenSupplyCeiling represents the tokens that the token holders have granted to the colony
in order to conduct business: to fund tasks and domains, and to hire workers and contributors.
This is especially important during the early life of a colony when it has little-to-no revenue in other
tokens to fall back on.
The TokenIssuanceRate controls how rapidly the colony receives the new tokens. If the rate
is ‘too high’, tokens will accumulate in the pot of the top-level colony domain (or other pots lower
in the hierarchy); usually this is not a big problem. If the rate is too low, this signals that the
colony has a healthy amount of activity and that the issuance rate has become a bottleneck. In
such situations it may be desirable to increase the rate of issuance without necessarily increasing
the maximum supply.
Increasing and decreasing the TokenIssuanceRate by up to 10% can be done by the reputation
holders alone and this action can be taken no more than once every 4 weeks. Larger changes to the
issuance rate should additionally require the agreement of existing token holders.

Tokens and Ether

8.1 Tokens and Ether

Every colony has its own native ERC20-compatible token. These tokens are under the control of the colony contract and may be used to pay for work done in the colony. Tokens only leave the control of the colony upon being paid out for completed tasks.
To pay out tasks, in addition to local tokens, a colony may also use Ether, CLNY and other ERC20 tokens that have been explicitly whitelisted by the Colony Network.

Migrate to gulp and upgrade node

In line with https://github.com/JoinColony/colonyDapp/pull/1227/files

Bootstrapping reputation (new Domains)

6.2.3 Bootstrapping reputation

We note that the same is not required when a new domain is created in a colony. We do not wish to allow the creation of new reputation here, as this would devalue reputation already earned elsewhere in the colony. This bootstrapping issue is resolved by instead using reputation within the parent domain, when a child domain contains less than 10% of the reputation of its parent domain.
A domain below this threshold cannot have domains created under it.

Earning reputation for the first time

7.6.2 Earning reputation for the first time

When a user earns reputation in a new skill, at least one new leaf is added to the tree — if they have not earned reputation before in some of the parents, then they will also cause further new leaves to be added. Additional new leaves will be added if they are the first user in a colony to earn those particular skills, making the total reputation for that skill in the colony non-zero. During a dispute, when the user proves that they have included the update in the tree, it is not possible to check (efficiently) on-chain that they should not have added it to an existing leaf instead. However, because during the resolution process we are always comparing two submissions against each other, one of two things will be true (Assuming that one of the two submissions is correct)
Both submissions added a new leaf to the tree. If there was a discrepancy, then it is in the maths conducted on this leaf, not the addition of the leaf itself. The maths can be checked on-chain to establish which result is correct.
One submission adds the new reputation to an existing leaf (the correctness of which can be checked on-chain easily). In this case, the user who added the leaf incorrectly is wrong.

Calculating the new root hash

7.3 Calculating the new root hash

To calculate the new root hash, the miners begin with the last reputation state, and decay all reputations held by all users in all colonies, in the order of the leaves in the tree. They then take the set of reputation gains or losses that were not in the last state submitted, and are to be included in the next state. They apply the reputation updates to each user in each colony, updating or adding leaves as necessary, to end up with a new list of reputations for all users and colonies.

Figure 3: The Merkle tree of users’ reputations with ReputationRootHash as the root. We use H to indicate the keccak256 hash function. Above the second row, each element is the hash of the concatenation of its two children.

These new reputations are then hashed and assembled into a new Merkle tree yielding an updated
ReputationRootHash. While the calculation is too large to be done on-chain due to technical and economic limitations (i.e. the block gas limit and the cost of gas, respectively), this calculation can easily be performed by a typical user’s computer.

Finance: Managing Funds and Bounties

This section deals with the mechanisms by which a colony allocates financial resources to domains and tasks. The norm is for resources to be allocated from the general to the particular, and that all allocations with sufficient reputational ‘backing’ may proceed without a vote. As long as there is no disagreement, everything will run smoothly and automatically.

Emergency Shutdown

7.9 Emergency Shutdown

Section 2.2 described a transaction from a whitelisted address can put a colony into ‘recovery mode’ during which the state can be edited, the effects of bugs can be corrected and upgrades can be made.
Similarly, the reputation mining process will also have an emergency stop-and-repair mechanism (to begin with). This will allow the whitelisted addresses to revert the reputation root hash to a previous version and halt all updates to the reputation state until the issues have been resolved (which will likely involve a contract upgrade). The colonies will be able to continue operations as usual using the reputations of the last valid state, which will be temporarily frozen and not decay.

Calculating reputation updates - Keeping track of reputation changes

7.6.1 Keeping track of reputation changes

Fundamentally, there are two types of reputation update that occur:

• Decay of existing reputation.
• Addition or removal of reputation as a reward or punishment.
  When a user earns reputation in a skill or domain, they also earn reputation in all parent domains, which corresponds to 2 * (n_parents + 1) reputation updates. Alternately, when a user loses reputation, they also lose reputation in all parents and all children representing a total number of updates of 2 * (n_parents + n_children + 1). The factors of two here come from also updating the relevant colony-wide totals.
  In Section 6.3, we asserted we store n_parents and n_children for all skills and domains. It is only by having access to the number of parents and children for each reputation and the reputation update log recording how many reputations have been updated already in this update cycle (via n_updates) that the resolution protocol is able to perform the binary search of the justification trees submitted by the disagreeing users. At the start of the challenge protocol, the contract can look up the last entry in the update table for the cycle under consideration, and work out how many updates have occurred in this cycle based on the number of updates prior and the number of parent and child reputations. After verifying that both submitted justification trees contain this exact number of leaves it can proceed to the binary search.
  When the discrepant state transition is found, the users supply the index of the event in the on-chain log that corresponds to that reputation update. This means that the contract does not have to iterate over the whole list expensively, but the contract can simply check the correct reputation update is being considered, and then confirm that the calculation made corresponds to the correct reputation update. To do this, we assert that children are always updated in order, then parents, and then the reputation in question itself. In addition, all colony-wide totals of reputation are always updated in this order before any user-specific reputation.
  If the discrepant transition is a decay transition they must also supply a Merkle proof that the starting value assumed for the user corresponds to the value that user had at the end of the last update cycle. A decay transition is identified by the Merkle path corresponding to an index in the justification tree smaller than the number of leaves in the reputation tree at the end of the last successful update.
  Recording the number of leaves in the reputation tree is required to accommodate the decay calculations that must be done at the start of each update. Before any new reputation is earned or lost in an update cycle, all existing reputations owned by users decay (see Section 7.6.4). There is a decay calculation for every leaf in the previously accepted reputation tree. We do the decay calculations first to give users the benefit of the doubt during reputation updates so they do not lose reputation they have only just earned to premature decay.

Reputation updates

6.2.1 Reputation change from contributing to a task

For all participants, reputation updates occur and payouts are made available only after the objection window (described in Section 4.1) has closed and all disputes (described in Section 9) have been resolved at the end of the task. The reputation updates and payouts are based on the final state of the task and the difference, if any, between the initial gradings and final state of the task.

Recovery mode for contracts

2.2 Contract security

At launch, colonies will be able to be put into a ‘recovery mode’. In this state, whitelisted
addresses are able to access functions that allow the state of the contract to be directly edited — in
practise, this will correspond to access to the functions to allow setting of variables, as well as being
able to upgrade the contract. With the agreement of multiple whitelisted addresses, the contract
will then be able to be taken out of recovery mode once the contract has been returned to a rational
state. Removal from recovery mode requires the approval of multiple whitelisted addresses.

Any approvals from whitelisted addresses to leave recovery mode must be reset whenever a
variable is edited. A whitelisted address agreeing to leave recovery mode records the timestamp at
which the agreement occurred, and any change of variables also update a timestamp indicating the
last edit. When attempting to leave recovery mode, only agreements made after the last edit are
counted towards meeting the threshold.

The first whitelisted address is added at colony creation and is the creator of the colony.
Whitelisted addresses can be added or removed by a simple majority vote of existing whitelisted
addresses.

Reputation by Skill

6.1.2 Reputation by skill

We envision domains to mostly be used as an organisational hierarchy within a colony. However, this would not necessarily capture the type of work that a user completed to earn their reputation.
If the domain were a project, with tasks corresponding to both design and development work, reputation earned by completing tasks related to these skills would not be distinguishable. To have a more granular account of the work a user completes to earn their reputation, a skill hierarchy is also maintained.

This global hierarchy of skills is available to all colonies, and is curated and maintained by the Common Colony. When a task is created, as well as being placed in a particular domain in the colony, it is also tagged with a skill from the skill hierarchy. When the worker earns reputation for successfully completing the task, they will earn reputation in the skill the task was tagged with and all parent skills. This is in addition to the reputation earned in the relevant domains. Conversely, if they are to lose reputation because their work is found inadequate, they will lose a proportional amount reputation from all child skills of the tag (if any exist), as is the case with the domain reputation. There is a top-level skill analogous to the top-level domain in a colony, of which all skills are descendants.
Even though the skill hierarchy is universal, reputation earned in the skill hierarchy is unique to each colony. Earning reputation in a skill in one colony has no effect on the user’s reputation in that skill in any other colonies.

Transfers of reputation between accounts

7.6.3 Transfers of reputation between accounts

The most important quality of reputation that distinguishes it from a token is that it is tied to an account and cannot be transferred. However, in the event of disputes (Section 9) it can happen that one party to a dispute loses reputation while the other gains. This process has to be modelled as a ‘reputation transfer’ to ensure that reputation is never created in this process (i.e. the reputation lost by the loser is at least as much as the reputation gained by the winner).
If an entry in the reputation update log indicates that a dispute has occurred and been resolved, then there will be a number of transfers of reputation between users represented by a single entry. Each such transfer will have to accommodate the updates of all the parents of the reputation being gained by one user, and updates of all the parents and children of the reputation being lost by the other. However, we have to ensure that the user who is losing reputation still has the reputation to lose if another user is gaining it.
To achieve this, all the transactions that correspond to updating the reputations of the user gaining the reputation are done first. In the event such a transaction must be proved to be correct in the resolution protocol, the users can provide a proof of the losing user’s reputation, prior to them losing it in this event in update cycle, and this can be compared to the amount of reputation intended to be gained. Whichever is smaller is used as the amount of reputation the user is gaining
during the calculations.
Then, when calculating the reputation deduction to be applied to the losing user, the reputation that was used as the voting weight should be done last i.e. all the children and parents should be considered first, as it is the amount of the reputation that was eligible to vote that will determine the fraction lost of each of the child reputations.
For further details about reputation transfers and disputes, see Appendix A.

Task cancellation

4.1 Tasks

If no worker has been assigned to a task, the manager has the ability to cancel the task entirely.

Any funds that have already been assigned to the task are assigned to the domain that the task was created in.

Dealing with false submissions - different hashes - establishing where two submissions differ

7.5 Dealing with false submissions

7.5.1 The Challenge-Response Protocol

2. Searching for the discrepancy - see whitepaper section on p24-25

Costs and rewards of Mining

7.4 Submission of a new root hash

Mining Rewards
When a state is accepted, a number of (newly minted) Common Colony Tokens are made available for the users who submitted the correct state to claim as a reward. They also receive a corresponding amount of reputation in the Common Colony (in a special mining skill, which only users in the Common Colony can earn by performing this task). This reputation update is no different from any other, aside from the limitations of who is able to earn it, and will be included in the subsequent reputation update cycle. The size of the rewards and their distribution are described in Section 7.8.

Earning reputation from contributing to a task by Evaluator

6.2.1 Reputation change from contributing to a task

Upon completion of a task, the evaluator also earns reputation based on their token reward.

For the purposes of calculating earned reputation the rating of the evaluator is assumed to be the same as the maximum of that of a manager, i.e. 5.

There is no explicit rating of the evaluator, but as with all other payments and rewards, an objection
can be raised before a payout occurs; if the evaluation is changed by such an objection, the evaluator’s reward is reduced or turns in to a loss of reputation.

On-chain representation of skills and domains

6.3 On-chain representation of skills and domains

In the context of reputation, domains and skills are the same, differing only in that domains are colony-specific categorisation and skills are universal categorisation. In this subsection, each instance of ‘skill’ should be taken to mean ‘skill or domain’.
Each skill that reputation can be earned in is assigned a skill_id that is unique across the whole network. When a skill is created, additional properties are recorded and initialised.

skill_id -> {
                n_parents (total number of parents)
                parent_n_id (the `skill_id` of the `n`th parent, where `n` is an integer power of two 
                                      larger than or equal to 1)
                children [] (array of `skill_id`s of all child skills)
                n_children (total number of child skills)
              }

Upon creation, children[] and n_children are empty. These two fields in all parents are updated
with the skill_id of the new skill on creation.*
*We acknowledge that this is fundamentally gas limited, but the only consequence of this will be the inability to create new skills once the maximum depth allowed by the block size is reached. Back-of-the-envelope calculations suggest this corresponds to a depth of around 80, which we don’t believe our users will be limited by.

Storing these pieces of data on-chain is required, as they are used by the reputation mining protocol (see next section) and the procedures for escalating disputes (see Section 9). They are stored under the control of the ColonyNetwork contract.

CurrentState of a Funding proposal

8.2.3 CurrentState

The state of a funding proposal is either inactive, active, completed or cancelled. Only an active funding proposal is in line to channel funds. A basic funding proposal begins in active state while a priority one begins inactive (i.e. it must be activated by a vote). A funding proposal is completed when its TotalPaid reaches TotalRequested. Any other state changes must be made through the dispute mechanism (see Section 9).

Task assignment

4.1 Tasks

The manager and the evaluator must also mutually agree to the assignment of the evaluator before
the evaluator is assigned to the task. The brief and due date may be changed, the assigned worker
removed, or the task cancelled, either by mutual consent, or via the dispute process.

Common Colony initialisation

3.1 Creation of CLNY Tokens

After the Colony Network Contract is deployed, the first colony created will be the Common Colony.
Tokens in the Common Colony will be known as CLNY.

The upgradable Token implementation and its setup with a MultiSig contract for upgrade-control is already complete.

Update gas costs test with usage data from Beta

Currently:

• 50 tasks created
• each of these updated twice
• each funded with ether once
• each funded with tokens once
• all of them closed

Change to

• 100 tasks created
• 20 of these updated once
• exclude ether funding from costs
• each funded with tokens once
• quarter of them closed

Detailed discussion in Slack https://joincolony.slack.com/archives/C49KPANDD/p1496651208699847

Bootstrapping reputation (new Colonies)

6.2.3 Bootstrapping reputation

Since a colony’s decision making procedure rests on reputation weighted voting, we are presented with a bootstrapping problem for new colonies. When a colony is new, no-one has yet completed any work in it and so nobody will have earned any reputation. Consequently, no objections can be raised and no disputes can be resolved as no-one is able to vote. Then, once the first task is successfully completed, that user has a ************ over decisions in the same domains or skills until another user earns similar types of reputation.
To prevent this, when a colony is created, the creator can choose addresses to have initial reputation assigned to them in the colony-wide domain to allow the colony to bootstrap itself. The reputation assigned to each a user will be equal to the number of tokens received, i.e. if a member receives ten tokens, they also receive ten reputation in the colony-wide domain. Given that reputation decays over time, this initial bootstrapping will not have an impact on the longterm operation of the colony. This is the only time that reputation can be created without an associated task being paid out. Users receiving reputation are presumably the colony creator and their colleagues, and this starting reputation should be seen as a representation of the existing trust which exists within the team.

Contract upgrade scripts don't work

The scripts in /upgrades/ do not work with the latest truffle, which we are using, and are not used in any tests, which is how they got to this point. We should change both.

Reputation Decay calculation

7.6.4 The Reputation Decay Calculation

The reputation decay process was described above as being continuous. In practise, it will decay by a small, discrete amount during each reputation update cycle following an exponential decay.
However, such a calculation is not possible to do accurately on-chain during the resolution protocol, so we must use an approximation. The details of the approximation we use, and a proof that this approximation is accurate and will not affect the running of (active) colonies can be found in Appendix B.

Dealing with false submissions - different hashes

7.5 Dealing with false submissions

7.5.1 The Challenge-Response Protocol

We now consider the more complicated case where two different hashes have been submitted.

1. The Justification Tree
   The first step is for both parties to upload a justification of their submitted hash. This justification consists of a second Merkle root and two Merkle proofs.
   The Merkle root in questions is the JustificationRootHash (JRH); it is the root of the ‘Justification Tree’ – a tree where each leaf represents a complete reputation state i.e. each leaf is a ReputationRootHash.
   The left-most leaf of the Justification Tree (RH0) is the final accepted reputation state from the last update. Both parties must submit a proof that their tree does indeed start at RH0. Note that in a Merkle proof for a left-most leaf, all siblings are hashed on the right.
   The right-most leaf of the Justification Tree (RHn) is the ReputationRootHash they originally submitted. Both parties must submit a Merkle proof that their tree does indeed end with this hash.
   Note that in a Merkle proof for a right-most leaf, all siblings are hashes on the left; furthermore, by noting the steps at which a hash is hashed with itself, we can determine the index of the last leaf.
   This index is required to be n — the number of reputation updates in the log.
   The intermediate leaves of the Justification Tree represent the evolution of the reputation state, with RHi corresponding to the reputation state after the first i reputation updates in this cycle
   have been applied.
   An example of such a tree is shown in Figure 4. Note that in the first stage of the tree, every neighbouring pair of data leaves is hashed, and so any pair has a shared Merkle proof to the root. We do this so that each element in the first row of hashes (indicated by h0;1; h0;2 : : : hn-1;n in Figure 4) represents a transition between two states. It is these transitions that are the subject of the mining dispute resolution process.
   Since any two differing submitted states agree on the first leaf RH0 (which is the ReputationRootHash accepted at the end of the previous iteration of the mining process), and disagree on the last leaf RHn (the hash they submitted), there must be a hash (hi;i+1) that represents the transition from RHi to RHi+1) where they agree on the starting state but disagree on the result. This transition is meant to be the effect of a single reputation update (the i-th - We start counting at zero, i.e. the transition from RH0 to RH1 is the ‘zeroth’.), and this is the reputation update we will calculate on-chain to establish which submission is incorrect.
   First, however, we must establish where the two submissions first differ, see #48

From, To and TokenType in a Funding proposal

8.2.2 From, To and TokenType

The purpose of a funding proposal is to move tokens of TokenType from a pot From to a pot To. The TokenType may be any ERC20 token whitelisted for use in the network, Ether, CLNY or
the Colony’s own Token. The From and To fields must be pots associated with a domain or a task in the colony. If the funds are to move ‘downstream’ from a domain to one of its children, a basic funding proposal is often sufficient.

Creating a Funding Proposal

8.2.1 Creating a Funding Proposal

Any member of the colony may create a funding proposal. The proposer must have 0.1% of the reputation of the domain that is the most recent common ancestor of the source and target pots. They must stake an equivalent fraction of the colony’s tokens. This stake is used to help discourage spamming of funding proposals and provide a mechanism whereby the creator can be punished for bad behaviour.

Denial of service attacks

7.7 Denial of service attacks

See whitepaper section for details

Upgrade solium and test linting camelCase

Solium is now at 0.4.0 and this fix should be tested end reenabled in linting rules duaraghav8/Ethlint#69

Dealing with false submissions - same hash, different number of leaves

7.4 Submission of a new root hash

Verifying a submission
If only one state is submitted by the end of the submission period, then the new state is accepted, and proposals of the next state can begin to be made. This is expected to be the most common occurrence.
If more than one state has been submitted, then either someone has made a mistake, or there is a malicious entity trying to introduce a fraudulent reputation change. In this event, the a challenge-response protocol can establish which state is incorrect (see Section 7.5)

7.5 Dealing with false submissions

7.5.1 The Challenge-Response Protocol

We assume that the correct hash is one of the submitted hashes. This is a reasonable assumption, as only one out of all the miners is required to make a correct submission, and there is an incentive for them to do so (the reward defined in Section 7.8). Thus our task is not to validate the correct hash but to invalidate the false ones.
We must prove all but one submission incorrect by having each submission navigate a series of challenges. These challenges refer to events that happened in the colony network within the last update cycle that have an effect on reputation. The responses to the challenges are Merkle proofs that the corresponding reputation update was properly handled. Anyone is able to respond to a challenge, regardless of who submitted the original hash; this should ensure that the correct state is always defended.
We begin with the scenario where only two submissions are made, and one is correct.
First we consider the case in which the same hash has been submitted twice, but with a disagreement about the number of leaves it contained. In this situation, the users are required to submit a Merkle proof for the last leaf in their tree. We are able to tell if a submitted proof corresponds to the last leaf in the tree, as all sibling hashes must be hashed on the left. Noting the positions in the Merkle proof in which a hash is hashed with itself also allows us to tell the index of this last leaf; if it corresponds to either of the submitted states, that one is correct.

The more complicated case where two different hashes have been submitted is considered in #49

Reputation by Domain

6.1.1 Reputation by Domain

The hierarchical structure of a colony was described in Section 4.2. Reputation is earned in this hierarchy, and a user has a reputation in all domains that exist — even if that reputation is zero. When a user earns or loses reputation in a domain, the reputation in all parent domains changes by the same amount. In the case of a user losing reputation, they also lose reputation in all child domains. When reputation is lost in a domain with children, all child domains lose the same fraction of reputation. If a reputation update would result in a user’s reputation being less than zero, their reputation is set to zero instead.
An example makes this clearer. Suppose a colony has a ‘development’ domain which contains a ‘backend’ domain and a ‘frontend’ domain, as in Figure 1 on page 10. Any time a member of the colony earns reputation for work completed in the backend domain, it will increase their backend reputation, their development reputation and their reputation in the all-encompassing top-level domain of the colony. Reputation earned in the development domain will only increase the development and top-level domain reputation scores of the user.
Later, the user behaves badly in the ‘development’ domain, and they lose 100 reputation out of the 2000 they have in that domain. They also lose 100 reputation in the parent domains, and 5%
(100/2000) of their reputation in each of the child domains of the ‘development’ domain (which in this example, includes all of the Frontend, Backend, Node.js and Ruby domains).

Submission of a new root hash - eligibility calculation

7.4 Submission of a new root hash

Who can submit a new root hash?
All CLNY token holders are eligible to become miners and participate in the reputation update process, but since any user can calculate the correct root hash locally, it would be possible for any
miner to submit the hash to the contract.
It is however undesirable to have too many submissions for every update. We propose a mechanism
that only allows some miners to submit results to begin with. To participate in the mining process, Common Colony Token holders must stake some of their tokens to become ‘reputation miners’. A submission will only be accepted from a miner if

keccak256(address, N, hash) < target

At the beginning of the submission window, the target is set to 0 and slowly increases to 2^256 - 1 after 150 blocks. We limit the total number of miners allowed to submit a specific hash to 12. The variable N that goes into the hash is some integer greater than 0 and less than the number
of tokens the Common Colony Token holder address has staked divided by 10^15, meaning that users with a large stake have a higher chance of qualifying to submit a hash sooner than smaller stake holders. The factor of 10^15 is introduced to ensure that all hashes a user is eligible to submit can be calculated in a few seconds by the client. It also effectively creates a minimum number of tokens that must be staked to submit a hash. This puts a tangible cost on any attacks revolving around spamming known false submissions (see Section 7.7).
Miners will also be required to have staked their tokens for a few update cycles before they are eligible to submit or support a hash.

The Reputation tree and the ReputationRootHash

7.2 The Reputation Tree and the ReputationRootHash

The data leaves in the reputation tree are the reputations all users have in all skills, as well as the
colony-wide totals. Such a leaf consists of the following data:
R = { rep_id, colony_id, user, amount }

rep_id the id of a skill or domain identifying the type of reputation;
colony_id the colony the reputation is held in;
user the address holding the skill;
amount the numerical value of the reputation

All individual reputations are assembled into the "Reputation Tree" which is a Merkle tree of all individual reputations in a colony, as well as the total reputation of each type held by the users in each colony. The leaves that represent these colony-wide totals are indicated by setting user to zero. These leaves are then put into a Merkle tree in the usual way (described in Section 7.1). The ordering of the data leaves is only determined by when these reputations were first earned.
We term the root hash of the resulting tree the ReputationRootHash, RH. The ReputationRootHash is the only data we record on the blockchain associated with users’ reputations. It summarises the state of the whole reputation system and whenever a user wishes to make use of their reputation, they can submit a Merkle proof from the reputation Ri they wish to make use of and ending at RH.

Changing the TokenIssuanceRate

5.1.3 Changing the TokenIssuanceRate

The TokenSupplyCeiling represents the tokens that the token holders have granted to the colony
in order to conduct business: to fund tasks and domains, and to hire workers and contributors.
This is especially important during the early life of a colony when it has little-to-no revenue in other
tokens to fall back on.
The TokenIssuanceRate controls how rapidly the colony receives the new tokens. If the rate
is ‘too high’, tokens will accumulate in the pot of the top-level colony domain (or other pots lower
in the hierarchy); usually this is not a big problem. If the rate is too low, this signals that the
colony has a healthy amount of activity and that the issuance rate has become a bottleneck. In
such situations it may be desirable to increase the rate of issuance without necessarily increasing
the maximum supply.
Increasing and decreasing the TokenIssuanceRate by up to 10% can be done by the reputation
holders alone and this action can be taken no more than once every 4 weeks. Larger changes to the
issuance rate should additionally require the agreement of existing token holders.

Pots and Funding Proposals

8.2 Pots and Funding Proposals

All tokens and currencies are administered by the colony contract; it is responsible for all the bookkeeping and allocations.
Each domain and each task in a colony has an associated pot. A pot can be thought of as acting like a wallet specific to a particular domain or task. To each pot, the colony contract may associate any number of unassigned tokens it holds. Depending on context, the funds in a pot may be referred to as the bounty, the budget, the salary or working capital.
Funds are transferred between pots through funding proposals.
A Funding Proposal consists of the following data

• Creator – The person that created the proposal.
• From – Pot funds are coming from.
• To – Pot funds are going to.
• TokenType – The token contract address (0x0 for ether).
• CurrentState – The state of the proposal (i.e. inactive, active, completed, cancelled).
• TotalPaid – How much has been transferred along this funding proposal so far.
• TotalRequested – The maximum amount to transfer after which this funding proposal is considered ‘completed’.
• LastUpdated – The time when the funding proposal was last updated.
• Rate – Rate of funding.
• PunishCreator – Whether the creator should be punished upon completion.
  We distinguish between two types of funding proposals: Basic Funding Proposals (BFP) intended for normal use, and Priority Funding Proposals (PFP) intended to be used when atypical circumstances present themselves. The basic funding proposal may start funding the target straight away, whereas a priority funding proposal must be explicitly voted on before it starts directing funds. Furthermore, for a basic funding proposal the target pot must be a direct descendant of the source in the hierarchy whereas a priority funding proposal has no such restrictions.
  Priority funding proposals should be used when funds need to be directed somewhere that is not a direct descendant of the source, when the funding rate needs to be very high (including immediate payment), or when the funding rate should be otherwise controlled (e.g. in the case of paying a salary).
  For either funding proposal, the assignment to pots associated with domains or tasks is purely a bookkeeping mechanism. From the perspective of the blockchain, ether and tokens are held by the colony contract until they are paid out when a task is completed.

Contract upgradability

White paper section

2.1 Contract upgradability

We want to ensure the future upgradability of the deployed system as we foresee the Colony Network being continuously developed. Providing an upgrade path is important to allow people to use Colony without preventing themselves using new features as they are added to the Network.
While we had originally decided on one approach to provide this upgradability, using a storage
contract we termed EternalStorage, the EIP150 hard fork increased the gas costs for the call
opcode which this approach relied on heavily. As a result, we are reconsidering this decision.
An explanation of the EternalStorage approach and of the alternative approach being currently
considered can be found in Appendix C.
Regardless of the implementation used, we will ensure that in the case of a colony, the choice
of upgrading the underlying Colony contract will never lie with the Colony Network. While the
network is in control of what upgrades are available, they are not able to force any colony to upgrade the underlying contracts. The colony itself must decide that it wants to upgrade to a new version.

Earning reputation from contributing to a task by Manager

6.2.1 Reputation change from contributing to a task

The manager gets an amount of reputation based on their grading by the worker, but on a scale that only varies between -tev and tev (where tev is the manager’s notional token
payout for the task). They only earn this reputation in the current (and all parent) domains, not
in the skill reputation hierarchy as they have not actually done the task. While it is likely some
knowledge is required to coordinate delivery of the task, this is not always the case; we believe that
skill reputation should exclusively demonstrate ability to perform tasks.

Submission of a new root hash

7.4 Submission of a new root hash

What is submitted?
The final ReputationRootHash is submitted to the contract by the miner along with the number of leaves in the tree. Further, the miner also submits the IPFS or Swarm hash of a document containing the entire state tree, though this is only for convenience; any user can construct this locally based on the blockchain history.

Task completion rating

6.2.1 Reputation change from contributing to a task

The performance of the user who has completed the work is established when the work is submitted and then evaluated. At this point, the evaluator grades the work submitted by the worker, and the worker rates the manager’s ability to coordinate delivery of the task out of five stars.
*These scores should be submitted using a pre-commit and reveal scheme to ensure secrecy during the rating process and avoid retaliatory grading in the event that the manager and evaluator are the same person, which we expect to be a reasonably common occurrence. In the event of a user not committing or revealing within a reasonable time, their rating of their counterpart is assumed to be the highest possible and they receive a mildly negative rating.

In the case of the evaluator, a rating of 0-2 stars counts as them rejecting the work, and a score
of 3-5 stars counts as accepting the work. Beyond that, we suggest the following guidelines for
ratings:

• 0 stars: user submitted no meaningful work
• 1 star: user showed little activity relevant to the task, and remains far from completion on due date.
• 2 stars: user was unable to complete the task, but put in a reasonable amount of effort.
• 3 stars: user completed the task following the brief but there were issues during the work.
• 4 stars: user completed the task acceptably and there were no complaints.
• 5 stars: user completed the task to a higher standard than requested.