Skip to main content

Class: Colony

Properties

address

address: string


colonyNetwork

colonyNetwork: ColonyNetwork


colonyToken

Optional colonyToken: ColonyToken

An instance of the Colony's native token

Currently only Tokens deployed via Colony are supported (no external, imported tokens) in Colony SDK. All other kinds will throw an error


ext

ext: SupportedExtensions


signerOrProvider

signerOrProvider: SignerOrProvider


version

version: number


SupportedVersions

Static SupportedVersions: 10[]

The currently supported Colony version. If a Colony is not on this version it has to be upgraded. If this is not an option, Colony SDK might throw errors at certain points. Usage of ColonyJS is advised in these cases

Methods

annotateTransaction

annotateTransaction(txHash, annotationMetadata): TxCreator<ColonyClientV10, "annotateTransaction", { agent?: string ; metadata?: string ; txHash?: string }, Annotation>

Annotate a transaction with IPFS metadata to provide extra information

This will annotate a transaction with an arbitrary text message. This only really works for transactions that happened within this Colony. This will upload the text string to IPFS and connect the transaction to the IPFS hash accordingly.

Remarks

If AnnotationMetadata is provided directly (as opposed to a CID for a JSON file) this requires an IpfsAdapter that can upload and pin to IPFS. See its documentation for more information. Keep in mind that the annotation itself is a transaction.

Example

// Immediately executing async function
(async function() {

// Create a motion to pay 10 of the native token to some (maybe your own?) address
// (forced transaction example)
const [, { transactionHash }] = await colony.ext.oneTx.pay(
'0xb77D57F4959eAfA0339424b83FcFaf9c15407461',
w`10`,
).motion();
// Annotate the motion transaction with a little explanation :)
await colony.annotateTransaction(
transactionHash,
{ annotationMsg: 'I am creating this motion because I think I deserve a little bonus' },
).force();
})();

Parameters

NameTypeDescription
txHashstringTransaction hash of the transaction to annotate (within the Colony)
annotationMetadatastring | AnnotationMetadataThe annotation metadata you would like to annotate the transaction with (or an IPFS CID pointing to valid metadata)

Returns

TxCreator<ColonyClientV10, "annotateTransaction", { agent?: string ; metadata?: string ; txHash?: string }, Annotation>

A TxCreator

Event data

PropertyTypeDescription
agentstringThe address that is responsible for triggering this event
txHashBigNumberThe hash of the annotated transaction
metadataBigNumberThe IPFS hash (CID) of the metadata object

claimFunds

claimFunds(tokenAddress?): TxCreator<ColonyClientV10, "claimColonyFunds", { fee?: BigNumber ; payoutRemainder?: BigNumber ; token?: string }, MetadataType>

Claim outstanding Colony funds

Anyone can call this function. Claims funds for the Colony that have been sent to the Colony's contract address or minted funds of the Colony's native token. This function has to be called in order for the funds to appear in the Colony's treasury. You can provide a token address for the token to be claimed. Otherwise it will claim the outstanding funds of the Colony's native token

Remarks

use ethers.constants.AddressZero to claim ETH.

Parameters

NameTypeDescription
tokenAddress?stringThe address of the token to claim the funds for. Default is the Colony's native token

Returns

TxCreator<ColonyClientV10, "claimColonyFunds", { fee?: BigNumber ; payoutRemainder?: BigNumber ; token?: string }, MetadataType>

A TxCreator

Event data

PropertyTypeDescription
agentstringThe address that is responsible for triggering this event
tokenstringThe token address
feeBigNumberThe fee deducted for rewards
payoutRemainderBigNumberThe remaining funds moved to the top-level domain pot

createTeam

createTeam(): TxCreator<ColonyClientV10, "addDomain(uint256,uint256,uint256)", { domainId?: BigNumber ; fundingPotId?: BigNumber }, MetadataType>

Create a team (domain) within a Colony with no metadata attached

Remarks

Currently you can only add domains within the Root domain. This restriction will be lifted soon

Returns

TxCreator<ColonyClientV10, "addDomain(uint256,uint256,uint256)", { domainId?: BigNumber ; fundingPotId?: BigNumber }, MetadataType>

A TxCreator

Event data

PropertyTypeDescription
agentstringThe address that is responsible for triggering this event
domainIdBigNumberInteger domain id of the created team
fundingPotIdBigNumberInteger id of the corresponding funding pot

createTeamWithData

createTeamWithData(teamMetadata): TxCreator<ColonyClientV10, "addDomain(uint256,uint256,uint256,string)", { agent?: string ; domainId?: BigNumber ; fundingPotId?: BigNumber ; metadata?: string }, Domain>

Create a team (domain) within a Colony with team details as metadata

Remarks

Currently you can only add domains within the Root domain. This restriction will be lifted soon

Parameters

NameTypeDescription
teamMetadatastring | DomainMetadataAn IPFS CID for a JSON file containing the metadata described below. For now, we would like to keep it agnostic to any IPFS upload mechanism, so you have to upload the file manually and provide your own hash (by using, for example, Pinata)

Returns

TxCreator<ColonyClientV10, "addDomain(uint256,uint256,uint256,string)", { agent?: string ; domainId?: BigNumber ; fundingPotId?: BigNumber ; metadata?: string }, Domain>

A TxCreator

Event data

PropertyTypeDescription
agentstringThe address that is responsible for triggering this event
domainIdBigNumberInteger domain id of the created team
fundingPotIdBigNumberInteger id of the corresponding funding pot
metadatastringIPFS CID of metadata attached to this transaction

Metadata (can be obtained by calling and awaiting the getMetadata function)

PropertyTypeDescription
domainNamestringThe human readable name assigned to this team
domainColorstringThe color assigned to this team
domainPurposestringThe purpose for this team (a broad description)

deprecateTeam

deprecateTeam(teamId, deprecated): TxCreator<ColonyClientV10, "deprecateDomain", { agent?: string ; deprecated?: boolean ; domainId?: BigNumber }, MetadataType>

Deprecate (remove) or undeprecate a team

Teams can be deprecated which will remove them from the UI. As they can't be deleted you can always undeprecate a team by passing false as the second argument.

Parameters

NameTypeDescription
teamIdBigNumberishTeam to be (un)deprecated
deprecatedbooleantrue: Deprecate team; false: Undeprecate team

Returns

TxCreator<ColonyClientV10, "deprecateDomain", { agent?: string ; deprecated?: boolean ; domainId?: BigNumber }, MetadataType>

A TxCreator

Event data

PropertyTypeDescription
agentstringThe address that is responsible for triggering this event
domainIdBigNumberThe id of the team that was (un)deprecated
deprecatedboolWhether the team was deprecated or not

getBalance

getBalance(tokenAddress?, teamId?): Promise<BigNumber>

Get a token balance for a specific token and team. Defaults to the Colony's native token and the Root team.

Remarks

The function will automatically figure out the corresponding pot for the given domain, as this is what's usually expected.

Example

Get the xDAI balance of the team number 2

import { constants } from 'ethers';
import { toEth } from '@colony/sdk';
// The `AddressZero` means ETH on mainnet and xDAI on Gnosis chain
const balance = await colony.getBalance(constants.AddressZero, 2);
// This will format the balance as a string in eth and not wei (i.e. 1.0 vs. 1000000000000000000)
console.info(toEth(balance));

Parameters

NameTypeDescription
tokenAddress?stringThe address of the token to get the balance for. Default is the Colony's native token
teamId?BigNumberishThe teamId (domainId) of the team to get the balance for. Default is the Root team

Returns

Promise<BigNumber>

A token balance in wei


getReputation

getReputation(userAddress, teamId?): Promise<BigNumber>

Get the reputation for a user address within a team in the Colony

Parameters

NameTypeDefault valueDescription
userAddressstringundefinedThe address of the account to check the reputation for
teamIdIdId.RootDomainThe teamId (domainId) of the team to get the reputation for. Default is the Root team

Returns

Promise<BigNumber>

A number quantifying the user addresses' reputation


getReputationAcrossTeams

getReputationAcrossTeams(userAddress): Promise<{ domainId: number ; reputationAmount?: BigNumberish ; skillId: number }[]>

Get the reputation for a user address across all teams in the Colony

Parameters

NameTypeDescription
userAddressstringThe address of the account to check the reputation for

Returns

Promise<{ domainId: number ; reputationAmount?: BigNumberish ; skillId: number }[]>

An array of objects containing the following

PropertyDescription
domainIdThe domainId of the domain the user has reputation in
skillIdThe corresponding skillId
reputationAmountThe reputation amount in that domain

getTeam

getTeam(teamId): Promise<DomainStructOutput>

Gets the team for teamId

Remarks

Will throw if teamId does not exist

Parameters

NameTypeDescription
teamIdBigNumberishThe teamId to get the team information for

Returns

Promise<DomainStructOutput>

A Team object


makeArbitraryTransaction

makeArbitraryTransaction(target, action): TxCreator<ColonyClientV10, "makeArbitraryTransactions", Record<string, unknown>, MetadataType>

Execute an arbitrary transaction in the name of the Colony

This method can execute a transaction on any Ethereum Smart Contract with the Colony address as the sender. The action needs to be encoded function data (see https://docs.ethers.io/v5/api/utils/abi/interface/#Interface--encoding). We provide some common interfaces for you to make it even easier.

Example

Mint an NFT from a Colony

import { ERC721 } from '@colony/sdk';

// Mint an NFT for address 0xb794f5ea0ba39494ce839613fffba74279579268
// (forced transaction example)
const encodedAction = ERC721.encodeFunctionData(
'mintTo',
'0xb794f5ea0ba39494ce839613fffba74279579268',
);

// Immediately executing async function
(async function() {
await colony.makeArbitraryTransaction(
// NFT contract address
'0x06012c8cf97BEaD5deAe237070F9587f8E7A266d',
// encoded transaction from above
encodedAction
).force();
})();

Parameters

NameTypeDescription
targetstringAddress of the contract to execute a method on
actionBytesLikeEncoded action to execute

Returns

TxCreator<ColonyClientV10, "makeArbitraryTransactions", Record<string, unknown>, MetadataType>

A TxCreator

No event data


moveFundsToTeam

moveFundsToTeam(amount, toTeam, fromTeam?, tokenAddress?): TxCreator<ColonyClientV10, "moveFundsBetweenPots(uint256,uint256,uint256,uint256,uint256,uint256,uint256,uint256,address)", { agent?: string ; amount?: BigNumber ; fromPot?: BigNumber ; toPot?: BigNumber ; token?: string }, MetadataType>

Move funds from one team to another

After sending funds to and claiming funds for your Colony they will land in a special team, the root team. If you want to make payments from other teams (in order to award reputation in that team) you have to move the funds there first. Use this method to do so.

Remarks

Requires the Funding permission in the root team. As soon as teams can be nested, this requires the Funding permission in a team that is a parent of both teams in which funds are moved.

Example

import { Tokens, w } from '@colony/sdk';

// Immediately executing async function
(async function() {
// Move 10 of the native token from team 2 to team 3
// (forced transaction example)
await colony.moveFundsToTeam(
w`10`,
2,
3,
).force();
})();

Parameters

NameTypeDescription
amountBigNumberishAmount to transfer between the teams
toTeamBigNumberishThe team to transfer the funds to
fromTeam?BigNumberishThe team to transfer the funds from. Default is the Root team
tokenAddress?stringThe address of the token to be transferred. Default is the Colony's native token

Returns

TxCreator<ColonyClientV10, "moveFundsBetweenPots(uint256,uint256,uint256,uint256,uint256,uint256,uint256,uint256,address)", { agent?: string ; amount?: BigNumber ; fromPot?: BigNumber ; toPot?: BigNumber ; token?: string }, MetadataType>

A TxCreator

Event data

PropertyTypeDescription
agentstringThe address that is responsible for triggering this event
fromPotBigNumberThe source funding pot
toPotBigNumberThe target funding pot
amountBigNumberThe amount that was transferred
tokenstringThe token address being transferred