ColonyClient

The ColonyClient class is a standard interface for interactions with the on-chain functions and events described in IColony.sol

These interactions are generally concerned with functions and events internal to a colony, such as creating a task, assigning a work rating, or moving funds between pots.

For functions and events that concern the colonyNetwork as a whole, refer to the ColonyNetworkClient API

Creating a new instance

You could create a ColonyClient by using an adapter and a query: new ColonyClient({ adapter, query }) and then .init() it but it is advised to ask the network client for a new instance:

const colonyClient = await networkClient.getColonyClient(colonyId); // This is already initialised

Instance properties

authority

The Colony's AuthorityClient instance.

token

The Colony's TokenClient instance.

Callers

All callers return promises which resolve to an object containing the given return values. For a reference please check here.

getAuthority.call()

Gets the colony's Authority contract address

Returns

A promise which resolves to an object containing the following properties:

Return valueTypeDescription
addressAddressThe colony's Authority contract address

generateSecret.call({ salt, value })

Helper function used to generate the rating secret used in task ratings. Accepts a salt value and a value to hide, and returns the keccak256 hash of both.

Arguments

ArgumentTypeDescription
saltstringSalt value.
valuenumberValue to hide (typically a rating of 1-3).

Returns

A promise which resolves to an object containing the following properties:

Return valueTypeDescription
secretHex stringkeccak256 hash of joint Salt and Value.

getDomain.call({ domainId })

Gets the selected domain's local skill ID and funding pot ID.

Arguments

ArgumentTypeDescription
domainIdnumberID of the domain.

Returns

A promise which resolves to an object containing the following properties:

Return valueTypeDescription
localSkillIdnumberThe domain's local skill ID.
potIdnumberThe domain's funding pot ID.

getDomainCount.call()

Gets the total number of domains in a Colony. This number equals the last domainId created.

Returns

A promise which resolves to an object containing the following properties:

Return valueTypeDescription
countnumberNumber of all domain in this Colony; == the last added domainId.

getGlobalRewardPayoutCount.call()

Gets the total number of reward payout cycles.

Returns

A promise which resolves to an object containing the following properties:

Return valueTypeDescription
countnumberNumber of reward payout cycles.

getUserRewardPayoutCount.call({ user })

Gets the number of claimed and waived reward payouts for a given user.

Arguments

ArgumentTypeDescription
userAddressAddress of user.

Returns

A promise which resolves to an object containing the following properties:

Return valueTypeDescription
countnumberNumber of claimed and waived reward payouts.

getTaskCount.call()

Gets the total number of tasks in a Colony. This number equals the last taskId created.

Returns

A promise which resolves to an object containing the following properties:

Return valueTypeDescription
countnumberTotal number of tasks in this Colony.

getTask.call({ taskId })

Gets a certain task defined by its integer taskId.

Arguments

ArgumentTypeDescription
taskIdnumber

Returns

A promise which resolves to an object containing the following properties:

Return valueTypeDescription
cancelledbooleanBoolean flag denoting whether the task is cancelled.
deliverableDateDate (optional)Date when the deliverable is due.
deliverableHashIPFS hash (optional)Unique hash of the deliverable content.
domainIdnumberInteger Domain ID the task belongs to.
dueDateDate (optional)When the task is due.
finalizedbooleanBoolean flag denoting whether the task is finalized.
idnumberInteger task ID.
payoutsWeCannotMakenumber (optional)Number of payouts that cannot be completed with the current task funding.
potIdnumber (optional)Integer ID of funding pot for the task.
skillIdnumberInteger Skill ID the task is assigned to.
specificationHashIPFS hashUnique hash of the specification content.

getTaskPayout.call({ taskId, role, token })

Given a specific task, a defined role for the task, and a token address, will return any payout attached to the task in the token specified.

Arguments

ArgumentTypeDescription
taskIdnumberInteger taskId.
roleRoleRole the payout is specified for: MANAGER, EVALUATOR, or WORKER.
tokenToken addressAddress of the token's contract. 0x0 value indicates Ether.

Returns

A promise which resolves to an object containing the following properties:

Return valueTypeDescription
amountBigNumberAmount of specified tokens to payout for that task and a role.

getTaskRole.call({ taskId, role })

Every task has three roles associated with it which determine permissions for editing the task, submitting work, and ratings for performance.

Arguments

ArgumentTypeDescription
taskIdnumberInteger taskId.
roleRoleMANAGER, EVALUATOR, or WORKER.

Returns

A promise which resolves to an object containing the following properties:

Return valueTypeDescription
addressAddressAddress of the user for the given role.
ratedbooleanHas the user work been rated.
ratingnumberRating the user received (1-3).

getTaskWorkRatings.call({ taskId })

For a given task, will return the number of submitted ratings and the date of their submission.

Arguments

ArgumentTypeDescription
taskIdnumberInteger taskId.

Returns

A promise which resolves to an object containing the following properties:

Return valueTypeDescription
countnumberTotal number of submitted ratings for a task.
dateDateDate of the last submitted rating.

getTaskWorkRatingSecret.call({ taskId, role })

If ratings for a task are still in the commit period, their ratings will still be hidden, but the hashed value can still be returned.

Arguments

ArgumentTypeDescription
taskIdnumberInteger taskId.
roleRoleRole that submitted the rating: MANAGER, EVALUATOR, or WORKER.

Returns

A promise which resolves to an object containing the following properties:

Return valueTypeDescription
secretHex stringthe hashed rating (equivalent to the output of keccak256(_salt, _rating) ).

getPotBalance.call({ potId, token })

Gets a balance for a certain token in a specific pot.

Arguments

ArgumentTypeDescription
potIdnumberInteger potId.
tokenToken addressAddress to get funds from, such as the token contract address, or empty address ( 0x0 for Ether)

Returns

A promise which resolves to an object containing the following properties:

Return valueTypeDescription
balanceBigNumberBalance for token token in pot potId .

getNonRewardPotsTotal.call({ token })

The nonRewardPotsTotal is a value that keeps track of the total assets a colony has to work with, which may be split among several distinct pots associated with various domains and tasks.

Arguments

ArgumentTypeDescription
tokenToken addressAddress of the token's contract. 0x0 value indicates Ether.

Returns

A promise which resolves to an object containing the following properties:

Return valueTypeDescription
totalBigNumberAll tokens that are not within the colony's rewards pot.

getRewardPayoutInfo.call({ payoutId })

Given a specific payout, returns useful information about the payout.

Arguments

ArgumentTypeDescription
payoutIdnumberId of the reward payout.

Returns

A promise which resolves to an object containing the following properties:

Return valueTypeDescription
blockNumbernumberBlock number at the time of creation.
remainingTokenAmountBigNumberRemaining (unclaimed) amount of tokens.
reputationRootHashstringReputation root hash at the time of creation.
tokenToken addressToken address ( 0x0 value indicates Ether).
totalTokenAmountForRewardPayoutBigNumberTotal amount of tokens taken aside for reward payout.
totalTokensBigNumberTotal colony tokens at the time of creation.

getToken.call()

Gets the address of the colony's official token contract.

Returns

A promise which resolves to an object containing the following properties:

Return valueTypeDescription
addressAddressThe address of the colony's official deployed token contract

getTransactionCount.call()

Returns the total number of transactions the colony has made, == the transactionId of the last added transaction to the Colony.

Returns

A promise which resolves to an object containing the following properties:

Return valueTypeDescription
countnumberNumber of all transactions in this Colony; == the last added transactionId.

Senders

All senders return an instance of a ContractResponse. Every send() method takes an options object as the second argument. For a reference please check here.

createTask.send({ specificationHash, domainId }, options)

Creates a new task by invoking makeTask on-chain.

Arguments

ArgumentTypeDescription
specificationHashIPFS hashHashed output of the task's work specification, stored so that it can later be referenced for task ratings or in the event of a dispute.
domainIdnumberDomain in which the task has been created (default value: 1 ).

Returns

An instance of a ContractResponse which will eventually receive the following event data:

Event dataTypeDescription
taskIdnumberWill return an integer taskId, from the TaskAdded event.

setTaskDomain.send({ taskId, domainId }, options)

Every task must belong to a single existing Domain. This can only be called by the manager of the task.

Arguments

ArgumentTypeDescription
taskIdnumberInteger taskId.
domainIdnumberInteger domainId.

Returns

An instance of a ContractResponse

setTaskRoleUser.send({ taskId, role, user }, options)

Set the user for role _role in task _id. Only allowed before the task is finalized, meaning that the value cannot be changed after the task is complete. This can only be called by the manager of the task.

Arguments

ArgumentTypeDescription
taskIdnumberInteger taskId.
roleRoleMANAGER, EVALUATOR, or WORKER.
userAddressaddress of the user.

Returns

An instance of a ContractResponse

setTaskSkill.send({ taskId, skillId }, options)

Sets the skill tag associated with the task. Currently there is only one skill tag available per task, but additional skills for tasks are planned in future implementations. This can only be called by the manager of the task.

Arguments

ArgumentTypeDescription
taskIdnumberInteger taskId.
skillIdnumberInteger skillId.

Returns

An instance of a ContractResponse

setTaskManagerPayout.send({ taskId, token, amount }, options)

Sets the payout given to the MANAGER role when the task is finalized. This Sender can only be called by the manager for the task in question.

Arguments

ArgumentTypeDescription
taskIdnumberInteger taskId.
tokenToken addressAddress to send funds from, e.g. the token's contract address, or empty address ( 0x0 for Ether)
amountBigNumberAmount to be paid.

Returns

An instance of a ContractResponse

submitTaskDeliverable.send({ taskId, deliverableHash }, options)

Submit the task deliverable, i.e. the output of the work performed for task _id Submission is allowed only to the assigned worker before the task due date. Submissions cannot be overwritten.

Arguments

ArgumentTypeDescription
taskIdnumberInteger taskId.
deliverableHashIPFS hashHash of the work performed.

Returns

An instance of a ContractResponse

submitTaskWorkRating.send({ taskId, role, secret }, options)

Submits a hidden work rating for a task. This is generated by generateSecret(_salt, _rating).

Arguments

ArgumentTypeDescription
taskIdnumberInteger taskId.
roleRoleThe role submitting their rating, either EVALUATOR or WORKER.
secretHex stringhidden work rating, generated as the output of generateSecret(_salt, _rating) , where _rating is a score from 1-3.

Returns

An instance of a ContractResponse

revealTaskWorkRating.send({ taskId, role, rating, salt }, options)

Reveals a previously submitted work rating, by proving that the _rating and _salt values result in the same secret submitted during the rating submission period. This is checked on-chain using the generateSecret function.

Arguments

ArgumentTypeDescription
taskIdnumberInteger taskId.
roleRoleRole revealing their rating submission, either EVALUATOR or WORKER.
ratingnumberRating scored (1-3).
saltstring_salt value to be used in generateSecret . A correct value will result in the same secret submitted during the work rating submission period.

Returns

An instance of a ContractResponse

assignWorkRating.send({ taskId }, options)

In the event of a user not committing or revealing within the 10 day rating window, their rating of their counterpart is assumed to be the highest possible and they will receive a reputation penalty.

Arguments

ArgumentTypeDescription
taskIdnumberInteger taskId.

Returns

An instance of a ContractResponse

cancelTask.send({ taskId }, options)

Cancels a task.

Arguments

ArgumentTypeDescription
taskIdnumberInteger taskId.

Returns

An instance of a ContractResponse

finalizeTask.send({ taskId }, options)

Finalizes a task, allowing roles to claim payouts and prohibiting all further changes to the task.

Arguments

ArgumentTypeDescription
taskIdnumberInteger taskId.

Returns

An instance of a ContractResponse

claimPayout.send({ taskId, role, token }, options)

Claims the payout for token denomination for work completed in task taskId by contributor with role role. Allowed only by the contributors themselves after task is finalized. Here the network receives its fee from each payout. Ether fees go straight to the Meta Colony whereas Token fees go to the Network to be auctioned off.

Arguments

ArgumentTypeDescription
taskIdnumberInteger taskId.
roleRoleRole of the contributor claiming the payout: MANAGER, EVALUATOR, or WORKER
tokenToken addressAddress to claim funds from, e.g. the token's contract address, or empty address ( 0x0 for Ether)

Returns

An instance of a ContractResponse

addDomain.send({ parentSkillId }, options)

Adds a domain to the Colony along with the new domain's respective local skill. This can only be called by owners of the colony.

Arguments

ArgumentTypeDescription
parentSkillIdnumberId of the local skill under which the new skill will be added.

Returns

An instance of a ContractResponse which will eventually receive the following event data:

Event dataTypeDescription
skillIdnumberA skillId for this domain.
parentSkillIdnumberThe parent skill id.

addGlobalSkill.send({ parentSkillId }, options)

Adds a global skill under a given parent SkillId. This can only be called from the Meta Colony, and only by the Meta Colony owners.

Arguments

ArgumentTypeDescription
parentSkillIdnumberInteger id of the parent skill.

Returns

An instance of a ContractResponse which will eventually receive the following event data:

Event dataTypeDescription
skillIdnumberInteger id of the newly created skill.
parentSkillIdnumberInteger id of the parent skill.

claimColonyFunds.send({ token }, options)

Move any funds received by the colony for token denomination to the top-levl domain pot, siphoning off a small amount to the rewards pot. No fee is taken if called against a colony's own token.

Arguments

ArgumentTypeDescription
tokenToken addressAddress to claim funds from; empty address ( 0x0 for Ether)

Returns

An instance of a ContractResponse

finalizeRewardPayout.send({ payoutId }, options)

Finalises the reward payout and allows creation of next reward payout for token that has been used in payoutId. Can only be called when reward payout cycle is finished, i.e. 60 days from its creation.

Arguments

ArgumentTypeDescription
payoutIdnumberId of the reward payout.

Returns

An instance of a ContractResponse

moveFundsBetweenPots.send({ fromPot, toPot, amount, token }, options)

Move a given amount of token funds from one pot to another.

Arguments

ArgumentTypeDescription
fromPotnumberOrigin pot Id.
toPotnumberDestination pot Id.
amountBigNumberAmount of funds to move.
tokenToken addressAddress of the token contract ( 0x0 value indicates Ether).

Returns

An instance of a ContractResponse

mintTokens.send({ amount }, options)

The owner of a Colony may mint new tokens.

Arguments

ArgumentTypeDescription
amountBigNumberAmount of new tokens to be minted.

Returns

An instance of a ContractResponse

mintTokensForColonyNetwork.send({ amount }, options)

In the case of the Colony Network, only the Meta Colony may mint new tokens.

Arguments

ArgumentTypeDescription
amountBigNumberAmount of new tokens to be minted.

Returns

An instance of a ContractResponse

startNextRewardPayout.send({ token }, options)

Start the next reward payout for token. All funds in the reward pot for token will become unavailable. All tokens will be locked, and can be unlocked by calling waiveRewardPayout or claimRewardPayout.

Arguments

ArgumentTypeDescription
tokenToken addressAddress of token used for reward payout ( 0x0 value indicates Ether).

Returns

An instance of a ContractResponse

waiveRewardPayouts.send({ numPayouts }, options)

Waive reward payout. This unlocks the sender's tokens and increments the users reward payout counter, allowing them to claim the next reward payout.

Arguments

ArgumentTypeDescription
numPayoutsnumberNumber of payouts to waive.

Returns

An instance of a ContractResponse

Task MultiSig

All MultiSig functions return an instance of a MultiSigOperation. For a reference please check here.

setTaskBrief.startOperation({ taskId, specificationHash })

The task brief, or specification, is a description of the tasks work specification. The description is hashed and stored with the task for future reference in ratings or in the event of a dispute.

Arguments

ArgumentTypeDescription
taskIdnumberInteger taskId.
specificationHashIPFS hashdigest of the task's hashed specification.

Returns

An instance of a MultiSigOperation

setTaskDueDate.startOperation({ taskId, dueDate })

The task's due date determines when a worker may submit the task's deliverable(s).

Arguments

ArgumentTypeDescription
taskIdnumberInteger taskId.
dueDateDateDue date.

Returns

An instance of a MultiSigOperation

setTaskEvaluatorPayout.startOperation({ taskId, token, amount })

Sets the payout given to the EVALUATOR role when the task is finalized.

Arguments

ArgumentTypeDescription
taskIdnumberInteger taskId.
tokenToken addressAddress to send funds from, e.g. the token's contract address, or empty address ( 0x0 for Ether)
amountBigNumberAmount to be paid.

Returns

An instance of a MultiSigOperation

setTaskWorkerPayout.startOperation({ taskId, token, amount })

Sets the payout given to the WORKER role when the task is finalized.

Arguments

ArgumentTypeDescription
taskIdnumberInteger taskId.
tokenToken addressAddress to send funds from, e.g. the token's contract address, or empty address ( 0x0 for Ether)
amountBigNumberAmount to be paid.

Returns

An instance of a MultiSigOperation