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 docs.

Creating a new instance

Assuming you're inside an async function:

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.

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.

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

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

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
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

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 }) => { /* ... */ })

Arguments

ArgumentTypeDescription
colonyIdnumberID of the newly-created Colony
colonyAddressAddressAddress of the newly-created Colony

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