Skip to main content

Colony Network (IColonyNetwork)

The functions for managing the Colony Network as a whole. Includes functions for creating and upgrading colonies, managing the reputation mining process, managing the skills used in colonies, and managing colony ENS names. These functions are not publically callable, but rather callable by the Meta Colony, a special colony which controls the network.

Interface Methods

addColonyVersion(uint256 _version, address _resolver)

Adds a new Colony contract version and the address of associated _resolver contract. Secured function to authorised members. Allowed to be called by the Meta Colony only.

Parameters

NameTypeDescription
_versionuint256The new Colony contract version
_resolveraddressAddress of the Resolver contract which will be used with the underlying EtherRouter contract

addExtensionToNetwork(bytes32 _extensionId, address _resolver)

Add a new extension resolver to the Extensions repository.

Note: Can only be called by the MetaColony.

Parameters

NameTypeDescription
_extensionIdbytes32keccak256 hash of the extension name, used as an indentifier
_resolveraddressThe deployed resolver containing the extension contract logic

addSkill(uint256 _parentSkillId):uint256 _skillId

Adds a new skill to the global or local skills tree, under skill _parentSkillId. Only the Meta Colony is allowed to add a global skill, called via IColony.addGlobalSkill. Any colony is allowed to add a local skill and which is associated with a new domain via IColony.addDomain.

Note: Errors if the parent skill does not exist or if this is called by an unauthorised sender.

Parameters

NameTypeDescription
_parentSkillIduint256Id of the skill under which the new skill will be added. If 0, a global skill is added with no parent.

Return Parameters

NameTypeDescription
_skillIduint256Id of the added skill

addr(bytes32 _node):address _address

Returns the address the supplied node resolves do, if we are the resolver.

Parameters

NameTypeDescription
_nodebytes32The namehash of the ENS address being requested

Return Parameters

NameTypeDescription
_addressaddressThe address the supplied node resolves to

appendReputationUpdateLog(address _user, int256 _amount, uint256 _skillId)

Adds a reputation update entry to log.

Note: Errors if it is called by anyone but a colony or if skill with id _skillId does not exist or.

Parameters

NameTypeDescription
_useraddressThe address of the user for the reputation update
_amountint256The amount of reputation change for the update, this can be a negative as well as a positive value
_skillIduint256The skill for the reputation update

burnUnneededRewards(uint256 _amount)

Used to burn tokens that are not needed to pay out rewards (because not every possible defence was made for all submissions)

Note: Only callable by the active reputation mining cycle

Parameters

NameTypeDescription
_amountuint256The amount of CLNY to burn

calculateMinerWeight(uint256 _timeStaked, uint256 _submissonIndex):uint256 _minerWeight

Calculate raw miner weight in WADs.

Parameters

NameTypeDescription
_timeStakeduint256Amount of time (in seconds) that the miner has staked their CLNY
_submissonIndexuint256Index of reputation hash submission (between 0 and 11)

Return Parameters

NameTypeDescription
_minerWeightuint256The weight of miner reward

claimMiningReward(address _recipient)

Used by a user to claim any mining rewards due to them. This will place them in their balance or pending balance, as appropriate.

Note: Can be called by anyone, not just _recipient

Parameters

NameTypeDescription
_recipientaddressThe user whose rewards to claim

createColony(address _tokenAddress):address _colonyAddress

Creates a new colony in the network, at version 3

Note: This is now deprecated and will be removed in a future version

Parameters

NameTypeDescription
_tokenAddressaddressAddress of an ERC20 token to serve as the colony token.

Return Parameters

NameTypeDescription
_colonyAddressaddressAddress of the newly created colony

createColony(address _tokenAddress, uint256 _version, string memory _colonyName):address _colonyAddress

Creates a new colony in the network, with an optional ENS name

Note: For the colony to mint tokens, token ownership must be transferred to the new colony

Parameters

NameTypeDescription
_tokenAddressaddressAddress of an ERC20 token to serve as the colony token
_versionuint256The version of colony to deploy (pass 0 for the current version)
_colonyNamestringThe label to register (if null, no label is registered)

Return Parameters

NameTypeDescription
_colonyAddressaddressAddress of the newly created colony

createColony(address _tokenAddress, uint256 _version, string memory _colonyName, string memory _metadata):address _colonyAddress

Creates a new colony in the network, with an optional ENS name

Note: For the colony to mint tokens, token ownership must be transferred to the new colony

Parameters

NameTypeDescription
_tokenAddressaddressAddress of an ERC20 token to serve as the colony token
_versionuint256The version of colony to deploy (pass 0 for the current version)
_colonyNamestringThe label to register (if null, no label is registered)
_metadatastringThe metadata associated with the new colony

Return Parameters

NameTypeDescription
_colonyAddressaddressAddress of the newly created colony

createColony(address _tokenAddress, uint256 _version, string memory _colonyName, string memory _orbitdb, bool _useExtensionManager):address _colonyAddress

Overload of the simpler createColony -- creates a new colony in the network with a variety of options, at version 4

Note: This is now deprecated and will be removed in a future version

Parameters

NameTypeDescription
_tokenAddressaddressAddress of an ERC20 token to serve as the colony token
_versionuint256The version of colony to deploy (pass 0 for the current version)
_colonyNamestringThe label to register (if null, no label is registered)
_orbitdbstringDEPRECATED Currently a no-op
_useExtensionManagerboolDEPRECATED Currently a no-op

Return Parameters

NameTypeDescription
_colonyAddressaddressAddress of the newly created colony

createColonyForFrontend(address _tokenAddress, string memory _name, string memory _symbol, uint8 _decimals, uint256 _version, string memory _colonyName, string memory _metadata):address token, address colony

Creates a new colony in the network, possibly with a token and token authority, with an optional ENS name

Note: We expect this function to only be used by the dapp

Parameters

NameTypeDescription
_tokenAddressaddressAddress of an ERC20 token to serve as the colony token (optional)
_namestringThe name of the token (optional)
_symbolstringThe short 'ticket' symbol for the token (optional)
_decimalsuint8The number of decimal places that 1 user-facing token can be divided up in to (optional) In the case of ETH, and most tokens, this is 18.
_versionuint256The version of colony to deploy (pass 0 for the current version)
_colonyNamestringThe label to register (if null, no label is registered)
_metadatastringThe metadata associated with the new colony

Return Parameters

NameTypeDescription
tokenaddressThe address of the token - this may just be the passed _tokenAddress
colonyaddress

createMetaColony(address _tokenAddress)

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

Parameters

NameTypeDescription
_tokenAddressaddressAddress of the CLNY token

deployTokenAuthority(address _token, address _colony, address[] memory _allowedToTransfer):address _tokenAuthority

Called to deploy a token authority

Note: This is more expensive than deploying a token directly, but is able to be done via a metatransaction

Parameters

NameTypeDescription
_tokenaddressThe address of the otken
_colonyaddressThe address of the colony in control of the token
_allowedToTransferaddress[]An array of addresses that are allowed to transfer the token even if it's locked

Return Parameters

NameTypeDescription
_tokenAuthorityaddressThe address of the newly deployed TokenAuthority

deployTokenViaNetwork(string memory _name, string memory _symbol, uint8 _decimals):address _token

Called to deploy a token.

Note: This is more expensive than deploying a token directly, but is able to be done via a metatransaction

Parameters

NameTypeDescription
_namestringThe name of the token
_symbolstringThe short 'ticket' symbol for the token
_decimalsuint8The number of decimal places that 1 user-facing token can be divided up in to In the case of ETH, and most tokens, this is 18.

Return Parameters

NameTypeDescription
_tokenaddressThe address of the newly deployed token

deprecateExtension(bytes32 _extensionId, bool _deprecated)

Set the deprecation of an extension in a colony. Can only be called by a Colony.

Parameters

NameTypeDescription
_extensionIdbytes32keccak256 hash of the extension name, used as an indentifier
_deprecatedboolWhether to deprecate the extension or not

deprecateSkill(uint256 _skillId)

Mark a skill as deprecated which stops new tasks and payments from using it.

Note: This function is deprecated and will be removed in a future release

Parameters

NameTypeDescription
_skillIduint256Id of the skill

deprecateSkill(uint256 _skillId, bool _deprecated):bool _changed

Set deprecation status for a skill

Parameters

NameTypeDescription
_skillIduint256Id of the skill
_deprecatedboolDeprecation status

Return Parameters

NameTypeDescription
_changedboolWhether the deprecated state was changed

getChildSkillId(uint256 _skillId, uint256 _childSkillIndex):uint256 _childSkillId

Get the id of the child skill at index _childSkillIndex for skill with Id _skillId.

Parameters

NameTypeDescription
_skillIduint256Id of the skill
_childSkillIndexuint256Index of the skill.children array to get

Return Parameters

NameTypeDescription
_childSkillIduint256Skill Id of the requested child skill

getColony(uint256 _id):address _colonyAddress

Get a colony address by its Id in the network.

Parameters

NameTypeDescription
_iduint256Id of the colony to get

Return Parameters

NameTypeDescription
_colonyAddressaddressThe colony address, if no colony was found, returns 0x0

getColonyCount():uint256 _count

Get the number of colonies in the network.

Return Parameters

NameTypeDescription
_countuint256The colony count

getColonyVersionResolver(uint256 _version):address _resolverAddress

Get the Resolver address for Colony contract version _version.

Parameters

NameTypeDescription
_versionuint256The Colony contract version

Return Parameters

NameTypeDescription
_resolverAddressaddressAddress of the Resolver contract

getCurrentColonyVersion():uint256 _version

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

Return Parameters

NameTypeDescription
_versionuint256The current / latest Colony contract version

getENSRegistrar():address _address

Returns the address of the ENSRegistrar for the Network.

Return Parameters

NameTypeDescription
_addressaddressThe address the ENSRegistrar resolves to

getExtensionInstallation(bytes32 _extensionId, address _colony):address _installation

Get an extension's installation.

Parameters

NameTypeDescription
_extensionIdbytes32keccak256 hash of the extension name, used as an indentifier
_colonyaddressAddress of the colony the extension is installed in

Return Parameters

NameTypeDescription
_installationaddressThe address of the installed extension

getExtensionResolver(bytes32 _extensionId, uint256 _version):address _resolver

Get an extension's resolver.

Parameters

NameTypeDescription
_extensionIdbytes32keccak256 hash of the extension name, used as an indentifier
_versionuint256Version of the extension

Return Parameters

NameTypeDescription
_resolveraddressThe address of the deployed resolver

getFeeInverse():uint256 _feeInverse

Return 1 / the fee to pay to the network. e.g. if the fee is 1% (or 0.01), return 100.

Return Parameters

NameTypeDescription
_feeInverseuint256The inverse of the network fee

getMetaColony():address _colonyAddress

Get the Meta Colony address.

Return Parameters

NameTypeDescription
_colonyAddressaddressThe Meta colony address, if no colony was found, returns 0x0

getMiningDelegator(address _delegate):address _delegator

Called to get the address _delegate is allowed to mine for

Parameters

NameTypeDescription
_delegateaddressThe address that wants to mine

Return Parameters

NameTypeDescription
_delegatoraddressThe address they are allowed to mine on behalf of

getMiningResolver():address miningResolverAddress

Get the resolver to be used by new instances of ReputationMiningCycle.

Return Parameters

NameTypeDescription
miningResolverAddressaddressThe address of the mining cycle resolver currently used by new instances

getMiningStake(address _user):MiningStake _info

returns how much CLNY _user has staked for the purposes of reputation mining

Parameters

NameTypeDescription
_useraddressThe user to query

Return Parameters

NameTypeDescription
_infoMiningStakeThe amount staked and the timestamp the stake was made at.

getParentSkillId(uint256 _skillId, uint256 _parentSkillIndex):uint256 _parentSkillId

Get the id of the parent skill at index _parentSkillIndex for skill with Id _skillId.

Parameters

NameTypeDescription
_skillIduint256Id of the skill
_parentSkillIndexuint256Index of the skill.parents array to get Note that not all parent skill ids are stored here. See Skill.parents member for definition on which parents are stored

Return Parameters

NameTypeDescription
_parentSkillIduint256Skill Id of the requested parent skill

getPayoutWhitelist(address _token):bool _status

Get a token's status in the payout whitelist

Parameters

NameTypeDescription
_tokenaddressThe token being queried

Return Parameters

NameTypeDescription
_statusboolWill be true if token is whitelisted

getProfileDBAddress(bytes32 _node):string _orbitdb

Retrieve the orbitdb address corresponding to a registered account.

Parameters

NameTypeDescription
_nodebytes32The Namehash of the account being queried.

Return Parameters

NameTypeDescription
_orbitdbstringA string containing the address of the orbit database

getReplacementReputationUpdateLogEntry(address _reputationMiningCycle, uint256 _id):ReputationLogEntry _reputationLogEntry

Get a replacement log entry (if set) for the log entry _id in the mining cycle that was at the address _reputationMiningCycle.

Parameters

NameTypeDescription
_reputationMiningCycleaddressThe address of the reputation mining cycle we are asking about
_iduint256The log entry number we wish to see if there is a replacement for

Return Parameters

NameTypeDescription
_reputationLogEntryReputationLogEntryReputationLogEntry instance with the details of the log entry (if it exists)

getReplacementReputationUpdateLogsExist(address _reputationMiningCycle):bool _exists

Used by the client to avoid doubling the number of RPC calls when syncing from scratch.

Parameters

NameTypeDescription
_reputationMiningCycleaddressThe reputation mining cycle address we want to know if any entries have been replaced in.

Return Parameters

NameTypeDescription
_existsboolBoolean indicating whether there is a replacement log

getReputationMiningCycle(bool _active):address _repMiningCycleAddress

Get the address of either the active or inactive reputation mining cycle, based on active. The active reputation mining cycle is the one currently under consideration by reputation miners. The inactive reputation cycle is the one with the log that is being appended to.

Parameters

NameTypeDescription
_activeboolWhether the user wants the active or inactive reputation mining cycle

Return Parameters

NameTypeDescription
_repMiningCycleAddressaddressaddress of active or inactive ReputationMiningCycle

getReputationMiningCycleReward():uint256 _amount

Called to get the total per-cycle reputation mining reward.

Return Parameters

NameTypeDescription
_amountuint256The CLNY awarded per mining cycle to the miners

getReputationMiningSkillId():uint256 _skillId

Get the skillId of the reputation mining skill. Only set once the metacolony is set up.

Return Parameters

NameTypeDescription
_skillIduint256The skillId of the reputation mining skill.

getReputationRootHash():bytes32 rootHash

Get the root hash of the current reputation state tree.

Return Parameters

NameTypeDescription
rootHashbytes32The current Reputation Root Hash

getReputationRootHashNLeaves():uint256 nLeaves

Get the number of leaves in the current reputation state tree.

Note: I cannot see a reason why a user's client would need to call this - only stored to help with some edge cases in reputation mining dispute resolution.

Return Parameters

NameTypeDescription
nLeavesuint256uint256 The number of leaves in the state tree

getReputationRootHashNNodes():uint256 nNodes

Get the number of leaves in the current reputation state tree.

Note: Deprecated, replaced by getReputationRootHashNLeaves which does the same thing but is more accurately named.

Return Parameters

NameTypeDescription
nNodesuint256uint256 The number of leaves in the state tree

getSkill(uint256 _skillId):Skill _skill

Get the nParents and nChildren of skill with id _skillId.

Parameters

NameTypeDescription
_skillIduint256Id of the skill

Return Parameters

NameTypeDescription
_skillSkillThe Skill struct

getSkillCount():uint256 _count

Get the number of skills in the network including both global and local skills.

Return Parameters

NameTypeDescription
_countuint256The skill count

getTokenLocking():address _lockingAddress

Get token locking contract address.

Return Parameters

NameTypeDescription
_lockingAddressaddressToken locking contract address

initialise(address _resolver, uint256 _version)

Initialises the colony network by setting the first Colony version resolver to _resolver address.

Note: Only allowed to be run once, by the Network owner before any Colony versions are added.

Parameters

NameTypeDescription
_resolveraddressAddress of the resolver for Colony contract
_versionuint256Version of the Colony contract the resolver represents

initialiseReputationMining()

Creates initial inactive reputation mining cycle.

initialiseRootLocalSkill():uint256 _rootLocalSkillId

Initialise the local skills tree for a colony

Return Parameters

NameTypeDescription
_rootLocalSkillIduint256The root local skill

installExtension(bytes32 _extensionId, uint256 _version)

Install an extension in a colony. Can only be called by a Colony.

Parameters

NameTypeDescription
_extensionIdbytes32keccak256 hash of the extension name, used as an indentifier
_versionuint256Version of the extension to install

isColony(address _colony):bool _addressIsColony

Check if specific address is a colony created on colony network.

Parameters

NameTypeDescription
_colonyaddressAddress of the colony

Return Parameters

NameTypeDescription
_addressIsColonybooltrue if specified address is a colony, otherwise false

lookupRegisteredENSDomain(address _addr):string _domain

Reverse lookup a username from an address.

Parameters

NameTypeDescription
_addraddressThe address we wish to find the corresponding ENS domain for (if any)

Return Parameters

NameTypeDescription
_domainstringA string containing the colony-based ENS name corresponding to addr

punishStakers(address[] memory _stakers, uint256 _amount)

Function called to punish people who staked against a new reputation root hash that turned out to be incorrect.

Note: While external, it can only be called successfully by the current ReputationMiningCycle.

Parameters

NameTypeDescription
_stakersaddress[]Array of the addresses of stakers to punish
_amountuint256Amount of stake to slash

registerColonyLabel(string memory _colonyName, string memory _orbitdb)

Register a "colony.joincolony.eth" label. Can only be called by a Colony.

Parameters

NameTypeDescription
_colonyNamestringThe label to register.
_orbitdbstringThe path of the orbitDB database associated with the colony name

registerUserLabel(string memory _username, string memory _orbitdb)

Register a "user.joincolony.eth" label.

Parameters

NameTypeDescription
_usernamestringThe label to register
_orbitdbstringThe path of the orbitDB database associated with the user profile

reward(address _recipient, uint256 _amount)

Used to track that a user is eligible to claim a reward

Note: Only callable by the active reputation mining cycle

Parameters

NameTypeDescription
_recipientaddressThe address receiving the award
_amountuint256The amount of CLNY to be awarded

setFeeInverse(uint256 _feeInverse)

Set the colony network fee to pay. e.g. if the fee is 1% (or 0.01), pass 100 as _feeInverse.

Parameters

NameTypeDescription
_feeInverseuint256The inverse of the network fee to set

setMiningDelegate(address _delegate, bool _allowed)

Called to give or remove another address's permission to mine on your behalf

Parameters

NameTypeDescription
_delegateaddressThe address you're giving or removing permission from
_allowedboolWhether they are allowed (true) or not (false) to mine on your behalf

setMiningResolver(address _miningResolverAddress)

Set the resolver to be used by new instances of ReputationMiningCycle.

Parameters

NameTypeDescription
_miningResolverAddressaddressThe address of the Resolver contract with the functions correctly wired.

setPayoutWhitelist(address _token, bool _status)

Set a token's status in the payout whitelist

Parameters

NameTypeDescription
_tokenaddressThe token being set
_statusboolThe whitelist status

setReplacementReputationUpdateLogEntry(address _reputationMiningCycle, uint256 _id, address _user, int _amount, uint256 _skillId, address _colony, uint128 _nUpdates, uint128 _nPreviousUpdates)

Set a replacement log entry if we're in recovery mode.

Note: Note that strictly, _nUpdates and _nPreviousUpdates don't need to be set - they're only used during dispute resolution, which these replacement log entries are never used for. However, for ease of resyncing the client, we have decided to include them for now.

Parameters

NameTypeDescription
_reputationMiningCycleaddressThe address of the reputation mining cycle that the log was in.
_iduint256The number of the log entry in the reputation mining cycle in question.
_useraddressThe address of the user earning / losing the reputation
_amountintThe amount of reputation being earned / lost
_skillIduint256The id of the origin skill for the reputation update
_colonyaddressThe address of the colony being updated
_nUpdatesuint128The number of updates the log entry corresponds to
_nPreviousUpdatesuint128The number of updates in the log before this entry

setReputationMiningCycleReward(uint256 _amount)

Called to set the total per-cycle reputation reward, which will be split between all miners.

Note: Can only be called by the MetaColony.

Parameters

NameTypeDescription
_amountuint256The CLNY awarded per mining cycle to the miners

setReputationRootHash(bytes32 _newHash, uint256 _newNLeaves, address[] memory _stakers)

Set a new Reputation root hash and starts a new mining cycle. Can only be called by the ReputationMiningCycle contract.

Parameters

NameTypeDescription
_newHashbytes32The reputation root hash
_newNLeavesuint256The updated leaves count value
_stakersaddress[]Array of users who submitted or backed the hash, being accepted here as the new reputation root hash

setTokenLocking(address _tokenLockingAddress)

Sets the token locking address. This is only set once, and can't be changed afterwards.

Parameters

NameTypeDescription
_tokenLockingAddressaddressAddress of the locking contract

setupRegistrar(address _ens, bytes32 _rootNode)

Setup registrar with ENS and root node.

Parameters

NameTypeDescription
_ensaddressAddress of ENS registrar
_rootNodebytes32Namehash of the root node for the domain

stakeForMining(uint256 _amount)

Stake CLNY to allow the staker to participate in reputation mining.

Parameters

NameTypeDescription
_amountuint256Amount of CLNY to stake for the purposes of mining

startNextCycle()

Starts a new Reputation Mining cycle. Explicitly called only the first time, subsequently called from within setReputationRootHash.

startTokenAuction(address _token)

Create and start a new DutchAuction for the entire amount of _token owned by the Colony Network.

Parameters

NameTypeDescription
_tokenaddressAddress of the token held by the network to be auctioned

supportsInterface(bytes4 _interfaceID):bool _status

Query if a contract implements an interface

Note: Interface identification is specified in ERC-165.

Parameters

NameTypeDescription
_interfaceIDbytes4The interface identifier, as specified in ERC-165

Return Parameters

NameTypeDescription
_statusbooltrue if the contract implements interfaceID

uninstallExtension(bytes32 _extensionId)

Uninstall an extension in a colony. Can only be called by a Colony.

Parameters

NameTypeDescription
_extensionIdbytes32keccak256 hash of the extension name, used as an indentifier

unstakeForMining(uint256 _amount)

Unstake CLNY currently staked for reputation mining.

Parameters

NameTypeDescription
_amountuint256Amount of CLNY staked for mining to unstake

updateColonyOrbitDB(string memory _orbitdb)

Update a colony's orbitdb address. Can only be called by a colony with a registered subdomain

Parameters

NameTypeDescription
_orbitdbstringThe path of the orbitDB database to be associated with the colony

updateUserOrbitDB(string memory _orbitdb)

Update a user's orbitdb address. Can only be called by a user with a registered subdomain

Parameters

NameTypeDescription
_orbitdbstringThe path of the orbitDB database to be associated with the user

upgradeExtension(bytes32 _extensionId, uint256 _newVersion)

Upgrade an extension in a colony. Can only be called by a Colony.

Parameters

NameTypeDescription
_extensionIdbytes32keccak256 hash of the extension name, used as an indentifier
_newVersionuint256Version of the extension to upgrade to (must be one greater than current)