Skip to main content

Class: ColonyNetwork

Properties

config

config: ColonyNetworkConfig


ipfs

ipfs: IpfsMetadata


locking

locking: TokenLocking


network

network: Network


networkClient

networkClient: ColonyNetworkClient


signerOrProvider

signerOrProvider: SignerOrProvider

Methods

createColony

createColony(tokenAddress, label, metadata): MetaTxCreator<ColonyNetworkClient, "createColony(address,uint256,string,string)", { agent: string ; colonyAddress: string ; colonyId: BigNumber ; metadata: string ; token: string }, Colony>

Create a new colony with metadata

Creates a new colony with IPFS metadata. To edit metadata at a later point you can call the Colony.editColony method.

Remarks

There is more to creating a fully functional colony that can be used within the dapp than just calling this function. See the Colony Creation Guide.

Example

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

// Immediately executing async function
(async function() {
// Create a colony with some metadata details attached
// (forced transaction example)
// (also notice that this requires an upload-capable IPFS adapter)
await colonyNetwork.createColony(
// Use USDC on Gnosis chain as the native token
'0xDDAfbb505ad214D7b80b1f830fcCc89B60fb7A83', {
colonyDisplayName: 'Cool Colony',
// IPFS hash to an image file
colonyAvatarHash: 'QmS26o1Cmsrx7iw1SSFGEcy22TVDq6VmEZ4XNjpWFyaKUe',
// List of token addresses that the Colony should be initialized with (can be changed later) - excluding ETH and the native token from above
colonyTokens: [Tokens.CLNY],
}).tx();
})();

Parameters

NameTypeDescription
tokenAddressstring-
labelstring-
metadatastring | ColonyMetadataThe team metadata you would like to add (or an IPFS CID pointing to valid metadata). If ColonyMetadata is provided directly (as opposed to a CID for a JSON file) this requires an IpfsAdapter that can upload and pin to IPFS (like the PinataAdapter). See its documentation for more information.

Returns

MetaTxCreator<ColonyNetworkClient, "createColony(address,uint256,string,string)", { agent: string ; colonyAddress: string ; colonyId: BigNumber ; metadata: string ; token: string }, Colony>

A transaction creator

Event data

PropertyTypeDescription
colonyIdBigNumberAuto-incremented integer id of the colony
colonyAddressstringAddress of the newly deployed colony contract
tokenstringAddress of the token that is used as the colony's native token
metadatastringIPFS CID of metadata attached to this transaction

Metadata

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

PropertyTypeDescription
colonyDisplayNamestringThe name that should be displayed for the colony
colonyAvatarHashstringAn IPFS hash for a Colony logo (make it 200x200px)
colonyTokensstring[]A list of additional tokens that should be in the colony's "address book"

createColony(tokenAddress, label): MetaTxCreator<ColonyNetworkClient, "createColony(address,uint256,string)", { colonyAddress: string ; colonyId: BigNumber ; metadata?: undefined ; token: string }, MetadataType>

Create a new Colony without metadata

Creates a new Colony without IPFS metadata. To add metadata at a later point you can call the Colony.editColony method.

Remarks

There is more to creating a fully functional colony that can be used within the dapp than just calling this function. See the Colony Creation Guide.

Example

// Immediately executing async function
(async function() {
// Create a colony
// (forced transaction example)
await colonyNetwork
// Use USDC on Gnosis chain as the native token
.createColony('0xDDAfbb505ad214D7b80b1f830fcCc89B60fb7A83')
.tx();
})();

Parameters

NameType
tokenAddressstring
labelstring

Returns

MetaTxCreator<ColonyNetworkClient, "createColony(address,uint256,string)", { colonyAddress: string ; colonyId: BigNumber ; metadata?: undefined ; token: string }, MetadataType>

A transaction creator

Event data

PropertyTypeDescription
colonyIdBigNumberAuto-incremented integer id of the colony
colonyAddressstringAddress of the newly deployed colony contract
tokenstringAddress of the token that is used as the colony's native token

deployToken

deployToken(name, symbol, decimals?): MetaTxCreator<ColonyNetworkClient, "deployTokenViaNetwork", { tokenAddress?: string }, MetadataType>

Deploy a "special" colony ERC20 token

If there is not token yet that should be used with the Colony, this is the canonical way to create one.

This is a supercharged ERC20 token contract, that not only has a permissioned mint function (that can be used from the colony) but also supports Metatransactions. In order to fully use its permissioned system with a colony, some extra steps have to be taken. See the Colony Creation Guide.

Remarks

The token deployed with this function is locked by default. Call unlockToken() on the Colony at a later point to unlock it.

Parameters

NameTypeDefault value
namestringundefined
symbolstringundefined
decimalsnumber18

Returns

MetaTxCreator<ColonyNetworkClient, "deployTokenViaNetwork", { tokenAddress?: string }, MetadataType>

A transaction creator


getColony

getColony(address): Promise<Colony>

Get a new instance of a Colony

Use this function to instantiate a new Colony by providing the Colony's address

Remarks

Colony contracts are versioned. If the deployed Colony version does not match the supported version an error will be thrown

Parameters

NameTypeDescription
addressstringThe Colony's address

Returns

Promise<Colony>

A Colony abstaction instance


getColonyAddress

getColonyAddress(label): Promise<null | string>

Get the colony's addess by the ENS label

Returns the colony's address that belongs to the given ENS label Will return null if the given label was not assigned to a colony.

Parameters

NameType
labelstring

Returns

Promise<null | string>

The colony's address


getColonyLabel

getColonyLabel(address): Promise<null | string>

Get the colony's ENS label

Returns the colony's ENS label, just like it's shown in the browsers address bar after /colony/, when using the dApp. Will return null if the colony does not exist or if no label was assigned yet

Parameters

NameType
addressstring

Returns

Promise<null | string>

The colony's ENS label


getMetaColony

getMetaColony(): Promise<Colony>

Get a new instance of the MetaColony

Use this function to instantiate a new Colony for the deployed MetaColony

Returns

Promise<Colony>

A Colony abstaction instance of the MetaColony


getSigner

getSigner(): Signer

Returns

Signer


getUserAddress

getUserAddress(username): Promise<null | string>

Get the user's addess by the username

Returns the user's address that belongs to the given username. Username has to be provided without any suffix, just like it's shown in the dapp. Will return null if the given username was not registered.

Parameters

NameType
usernamestring

Returns

Promise<null | string>

The user's address


getUsername

getUsername(address): Promise<null | string>

Get a user's username

Returns the user's username (the ENS label, just like it's shown in the dapp, without any suffixes) Will return null if the user does not exist or if no label was assigned yet

Parameters

NameType
addressstring

Returns

Promise<null | string>

The user's username


registerUsername

registerUsername(username): MetaTxCreator<ColonyNetworkClient, "registerUserLabel", { label?: string ; user?: string }, MetadataType>

Register a Colony-internal ENS username

Registers a username for the signing address. An address can only register one username. Usernames are globally unique. This method will check whether the username was registered before.

Parameters

NameType
usernamestring

Returns

MetaTxCreator<ColonyNetworkClient, "registerUserLabel", { label?: string ; user?: string }, MetadataType>

A transaction creator


init

Static init(signerOrProvider, options?): Promise<ColonyNetwork>

Creates a new instance to connect to the ColonyNetwork

This is your main entry point to talk to the Colony Network Smart Contracts. From here you should be able to instantiate all the required instances for Colonies and their extensions.

Example

import { providers } from 'ethers';
import { ColonyNetwork, Tokens } from '@colony/sdk';

// Connect directly to the deployed Colony Network on Gnosis Chain
const provider = new providers.JsonRpcProvider('https://xdai.colony.io/rpc/');
// Immediately executing async function
(async function() {
const colonyNetwork = await ColonyNetwork.init(provider);
// Now you could call functions on the colonyNetwork, like `colonyNetwork.getMetaColony()`
})();

Parameters

NameTypeDescription
signerOrProviderSignerOrProviderAn ethers compatible Signer or Provider instance
options?ColonyNetworkOptionsOptional custom ColonyNetworkOptions

Returns

Promise<ColonyNetwork>

A ColonyNetwork abstraction instance