Secure the networkBug Bounty!November 2018

ColonyNetworkClient

The ColonyNetworkClient is a standard interface for interactions with functions and events described in IColonyNetwork.sol.

These interactions are generally concerned with the colony network as a whole, rather than at the colony level. This includes operations like getting a count of all colonies on the network, querying for information about a parent skillId, or deposits/withdrawals of staked CLNY for use in the reputation system.

You can learn more about the solidity implementation from the Colony Network Docs.

For interactions within a particular colony, see the ColonyClient API.

Create an instance

You can create an instance of ColonyNetworkClient by providing an adapter:

const networkClient = new ColonyNetworkClient({ adapter });

await networkClient.init();

Instance methods

All instance methods return promises.

getColonyClientByAddress(contractAddress)

Returns an initialized ColonyClient for the contract at address contractAddress

Arguments

ArgumentTypeDescription
contractAddressAdressAddress of a deployed Colony contract

Returns

Promise<ColonyClient>. An instance of a ColonyClient associated with the given Colony contract

getColonyClient(id)

Returns an initialized ColonyClient for the specified id of a deployed colony contract.

Arguments

ArgumentTypeDescription
keystringName of the Colony to get
idnumberInteger number of the Colony

Returns

Promise<ColonyClient>. An instance of a ColonyClient associated with the given Colony contract

getColonyAddress(id)

Get the address of a Colony for the specified id of a deployed colony contract.

Arguments

ArgumentTypeDescription
keystringName of the Colony to get
idnumberInteger number of the Colony

Returns

Promise<Address>. The address of the given Colony contract

getMetaColonyClient()

Gets the Meta Colony as an initialized ColonyClient

Returns

Promise<ColonyClient>. An instance of a ColonyClient associated with the MetaColony contract

Callers

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

getRecoveryRolesCount.call()

Returns the number of recovery roles.

Returns

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

Return valueTypeDescription
countnumberNumber of users with the recovery role (excluding owner)

isInRecoveryMode.call()

Is the colony in recovery mode?

Returns

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

Return valueTypeDescription
inRecoveryModebooleanReturn true if recovery mode is active, false otherwise

getColony.call({ id })

Returns the address of a colony when given the ID

Arguments

ArgumentTypeDescription
idnumberInteger colony ID

Returns

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

Return valueTypeDescription
addressAddressAddress of the colony contract

getMetaColonyAddress.call()

Returns the address of the Meta Colony

Returns

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

Return valueTypeDescription
addressAddressAddress of the Meta Colony contract

getColonyCount.call()

Returns the number of colonies created on the Colony Network, i.e. the colonyId of the most recently created colony.

Returns

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

Return valueTypeDescription
countnumbercolonyId of the most recently created colony

isColony.call({ colony })

Check if specific address is a Colony created on the Colony Network

Arguments

ArgumentTypeDescription
colonyAddressAddress of the colony

Returns

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

Return valueTypeDescription
isColonybooleanWhether specified address is a colony

getColonyVersionResolver.call({ version })

Given a version of the colony contract, returns the address of the corresponding Resolver contract

Arguments

ArgumentTypeDescription
versionnumberThe Colony contract version

Returns

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

Return valueTypeDescription
addressAddressAddress of the Resolver contract

getCurrentColonyVersion.call()

Returns the latest Colony contract version. This is the version used to create all new colonies.

Returns

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

Return valueTypeDescription
versionnumberThe current / latest Colony contract version

getParentSkillId.call({ skillId, parentSkillIndex })

Given the id of a particular skill, returns the skill's parent skill id

Arguments

ArgumentTypeDescription
skillIdnumberId of the skill
parentSkillIndexnumberIndex of the skill.parents array to get

Returns

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

Return valueTypeDescription
parentSkillIdnumberId of the parent skill

getChildSkillId.call({ skillId, childSkillIndex })

Given the id of a particular skill, returns the child skill at the given index

Arguments

ArgumentTypeDescription
skillIdnumberId of the skill
childSkillIndexnumberIndex of the skill.children array to get

Returns

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

Return valueTypeDescription
childSkillIdnumberId of the child skill

getSkill.call({ skillId })

Returns the number of parent and child skills associated with the provided skill

Arguments

ArgumentTypeDescription
skillIdnumberskillId to be checked

Returns

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

Return valueTypeDescription
nParentsnumberNumber of parent skills
nChildrennumberNumber of child skills
isGlobalSkillbooleanWhether the specified skill is a global skill

getSkillCount.call()

Get the total number of skills in the network (both global and local skills)

Returns

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

Return valueTypeDescription
countnumberThe number of skills on the network

getRootGlobalSkillId.call()

Get the ID of the root global skill.

Returns

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

Return valueTypeDescription
skillIdnumberThe root global skill id

getTokenLocking.call()

Get the token locking contract address.

Returns

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

Return valueTypeDescription
lockingAddressAddressToken locking contract address

getProfileDBAddress.call({ nameHash })

Returns the database address of a user when given the hashed ENS username

Arguments

ArgumentTypeDescription
nameHashHex stringThe hashed human-readable ENS name

Returns

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

Return valueTypeDescription
orbitDBAddressstringAddress of the UserProfile DDB

lookupRegisteredENSDomain.call({ ensAddress })

Given an Ethereum address, returns a user's or colony's human-readable name, or an empty string if the address has no Colony-based ENS name

Arguments

ArgumentTypeDescription
ensAddressAddressThe address we wish to find the corresponding ENS domain for (if any)

Returns

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

Return valueTypeDescription
domainstringA string containing the colony-based ENS name corresponding to ensAddress

getAddressForENSHash.call({ nameHash })

Given a hash of the ENS name, returns the Ethereum address registered with it

Arguments

ArgumentTypeDescription
nameHashHex stringThe hashed human-readable ENS name

Returns

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

Return valueTypeDescription
ensAddressAddressThe registered ENS username for a colony or a user

ensSupportsInterface.call({ interfaceId })

Given an ENS interface, returns a boolean indicating whether the interface is supported

Arguments

ArgumentTypeDescription
interfaceIdHex stringThe interface identifier, as specified in ERC-165

Returns

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

Return valueTypeDescription
isSupportedbooleanReturns true if the contract implements interfaceId

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.

approveExitRecovery.send(options)

Indicate approval to exit recovery mode. Can only be called by user with recovery role.

Returns

An instance of a ContractResponse

enterRecoveryMode.send(options)

Put the colony into recovery mode. Can only be called by user with a recovery role.

Returns

An instance of a ContractResponse

exitRecoveryMode.send({ newVersion }, options)

Exit recovery mode. Can be called by anyone if enough whitelist approvals are given.

Arguments

ArgumentTypeDescription
newVersionnumberResolver version to upgrade to (>= current version)

Returns

An instance of a ContractResponse

setRecoveryRole.send({ user }, options)

Set new colony recovery role. Can only be called by the founder role.

Arguments

ArgumentTypeDescription
userAddressThe user we want to give a recovery role to.

Returns

An instance of a ContractResponse

removeRecoveryRole.send({ user }, options)

Remove colony recovery role. Can only be called by the founder role.

Arguments

ArgumentTypeDescription
userAddressThe user we want to remove the recovery role from.

Returns

An instance of a ContractResponse

setStorageSlotRecovery.send({ slot, value }, options)

Update the value of an arbitrary storage variable. This can only be called by a user with the recovery role. Certain critical variables are protected from editing in this function.

Arguments

ArgumentTypeDescription
slotnumberAddress of storage slot to be updated.
valueHex stringWord of data to be set.

Returns

An instance of a ContractResponse

createToken.send({ name, symbol, decimals }, options)

Deploys a new ERC20 compatible token contract for you to use with your Colony. You can also use your own token when creating a Colony.

Arguments

ArgumentTypeDescription
namestringName of the token to create
symbolstringSymbol of the token (e.g. CLNY)
decimalsnumberDecimals to use for your token

Returns

An instance of a ContractResponse which will receive a receipt with a contractAddress property (the address of the newly-deployed contract)

addSkill.send({ parentSkillId, globalSkill }, options)

Adds a new skill to the global or local skills tree.

Arguments

ArgumentTypeDescription
parentSkillIdnumberThe skill under which the new skill will be added
globalSkillbooleanWhether the new skill is global

Returns

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

Event dataTypeDescription
skillIdnumber
parentSkillIdnumber
SkillAddedobjectContains the data defined in SkillAdded

setTokenLocking.send({ tokenLockingAddress }, options)

Sets the token locking address.

Arguments

ArgumentTypeDescription
tokenLockingAddressAddressAddress of the locking contract

Returns

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

Event dataTypeDescription
tokenLockingAddressAddress of the TokenLocking contract
TokenLockingAddressSetobjectContains the data defined in TokenLockingAddressSet

createMetaColony.send({ tokenAddress }, options)

Create the Meta Colony, same as a normal Colony plus the root skill.

Arguments

ArgumentTypeDescription
tokenAddressAddressToken to import. Note: the ownership of the token contract must be transferred to the newly-created Meta Colony.

Returns

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

Event dataTypeDescription
colonyAddressnumberAddress of the Meta Colony
tokenAddressAddressAddress of the associated CLNY token
rootSkillIdnumberID of the root skill of the global skills tree (normally, this is 2)
MetaColonyCreatedobjectContains the data defined in MetaColonyCreated

createColony.send({ tokenAddress }, options)

Creates a new colony on the network.

Arguments

ArgumentTypeDescription
tokenAddressAddressToken to import. Note: the ownership of the token contract must be transferred to the newly-created Colony.

Returns

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

Event dataTypeDescription
colonyIdnumberID of the newly-created colony
colonyAddressAddressAddress of the newly-created colony
tokenAddressAddressAddress of the associated colony token
ColonyAddedobjectContains the data defined in ColonyAdded

addColonyVersion.send({ version, resolver }, options)

Adds a new Colony contract version and the address of associated Resolver contract.

Arguments

ArgumentTypeDescription
versionnumberThe new Colony contract version
resolverAddressAddress of the Resolver contract

Returns

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

Event dataTypeDescription
versionnumberThe new int colony version, e.g. 2, 3, 4, etc
resolverAddressThe new colony contract resolver contract instance
ColonyVersionAddedobjectContains the data defined in ColonyVersionAdded

startTokenAuction.send({ tokenAddress }, options)

Create and start a new Dutch Auction for the entire amount of a specified token owned by the Colony Network

Arguments

ArgumentTypeDescription
tokenAddressAddressAddress of the token held by the network to be auctioned

Returns

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

Event dataTypeDescription
auctionstringThe address of the auction contract
tokenAddressThe address of the token being auctioned
quantityBigNumberThe amount of available tokens for auction
AuctionCreatedobjectContains the data defined in AuctionCreated

setupRegistrar.send({ ens, rootNode }, options)

Setup registrar with ENS and root node.

Arguments

ArgumentTypeDescription
ensAddressAddress of ENS registrar
rootNodestringNamehash of the root node for the domain

Returns

An instance of a ContractResponse

registerUserLabel.send({ username, orbitDBPath }, options)

Register a "user.joincolony.eth" label.

Arguments

ArgumentTypeDescription
usernamestringThe label to register
orbitDBPathstringThe path of the OrbitDB database associated with the user profile

Returns

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

Event dataTypeDescription
userAddressAddress of the user that registered a label
labelstringThe label registered
UserLabelRegisteredobjectContains the data defined in UserLabelRegistered

Events

Refer to the ContractEvent class here to interact with these events.

events.ColonyAdded.addListener(({ colonyId, colonyAddress, tokenAddress }) => { /* ... */ })

Arguments

ArgumentTypeDescription
colonyIdnumberID of the newly-created colony
colonyAddressAddressAddress of the newly-created colony
tokenAddressAddressAddress of the associated colony token

events.SkillAdded.addListener(({ skillId, parentSkillId }) => { /* ... */ })

Arguments

ArgumentTypeDescription
skillIdnumber
parentSkillIdnumber

events.AuctionCreated.addListener(({ auction, token, quantity }) => { /* ... */ })

Arguments

ArgumentTypeDescription
auctionstringThe address of the auction contract
tokenAddressThe address of the token being auctioned
quantityBigNumberThe amount of available tokens for auction

events.UserLabelRegistered.addListener(({ user, label }) => { /* ... */ })

Arguments

ArgumentTypeDescription
userAddressAddress of the user that registered a label
labelstringThe label registered

events.ColonyLabelRegistered.addListener(({ colony, label }) => { /* ... */ })

Arguments

ArgumentTypeDescription
colonyAddressAddress of the colony that registered a label
labelstringThe label registered

events.ReputationMiningInitialised.addListener(({ inactiveReputationMiningCycle }) => { /* ... */ })

Arguments

ArgumentTypeDescription
inactiveReputationMiningCycleAddressAddress of the newly created ReputationMiningCycle used in logging reputation changes

events.ReputationMiningCycleComplete.addListener(({ hash, nNodes }) => { /* ... */ })

Arguments

ArgumentTypeDescription
hashHex stringThe root hash of the newly accepted reputation state
nNodesnumberThe number of nodes in the reputation state

events.ReputationRootHashSet.addListener(({ newHash, newNNodes, stakers, reward }) => { /* ... */ })

Arguments

ArgumentTypeDescription
newHashHex stringThe reputation root hash
newNNodesnumberThe updated nodes count value
stakersundefinedArray of users who submitted or backed the hash accepted
rewardundefinedAmount of CLNY distributed as reward to miners

events.TokenLockingAddressSet.addListener(({ tokenLocking }) => { /* ... */ })

Arguments

ArgumentTypeDescription
tokenLockingAddressAddress of the TokenLocking contract

events.ColonyNetworkInitialised.addListener(({ resolver }) => { /* ... */ })

Arguments

ArgumentTypeDescription
resolverAddressThe Resolver contract address used by the Colony version 1

events.MiningCycleResolverSet.addListener(({ miningCycleResolver }) => { /* ... */ })

Arguments

ArgumentTypeDescription
miningCycleResolverAddressResolver address for the ReputationMiningCycle contract

events.NetworkFeeInverseSet.addListener(({ feeInverse }) => { /* ... */ })

Arguments

ArgumentTypeDescription
feeInverseBigNumberThe network fee inverse value

events.ColonyVersionAdded.addListener(({ version, resolver }) => { /* ... */ })

Arguments

ArgumentTypeDescription
versionnumberThe new int colony version, e.g. 2, 3, 4, etc
resolverAddressThe new colony contract resolver contract instance

events.MetaColonyCreated.addListener(({ colonyAddress, tokenAddress, rootSkillId }) => { /* ... */ })

Arguments

ArgumentTypeDescription
colonyAddressnumberAddress of the Meta Colony
tokenAddressAddressAddress of the associated CLNY token
rootSkillIdnumberID of the root skill of the global skills tree (normally, this is 2)