Skip to main content

API

Namespaces

Enumerations

Classes

Interfaces

Type Aliases

AnyCoinMachineClient

Ƭ AnyCoinMachineClient: CoinMachineClientV1 | CoinMachineClientV2 | CoinMachineClientV3 | CoinMachineClientV4 | CoinMachineClientV5 | CoinMachineClientV6 | CoinMachineClientV7


AnyColonyClient

Ƭ AnyColonyClient: ColonyClientV1 | ColonyClientV2 | ColonyClientV3 | ColonyClientV4 | ColonyClientV5 | ColonyClientV6 | ColonyClientV7 | ColonyClientV8 | ColonyClientV9 | ColonyClientV10 | ColonyClientV11 | ColonyClientV12


AnyEvaluatedExpenditureClient

Ƭ AnyEvaluatedExpenditureClient: EvaluatedExpenditureClientV1 | EvaluatedExpenditureClientV2 | EvaluatedExpenditureClientV3


AnyOneTxPaymentClient

Ƭ AnyOneTxPaymentClient: OneTxPaymentClientV1 | OneTxPaymentClientV2 | OneTxPaymentClientV3 | OneTxPaymentClientV4


AnyStakedExpenditureClient

Ƭ AnyStakedExpenditureClient: StakedExpenditureClientV1 | StakedExpenditureClientV2


AnyStreamingPaymentsClient

Ƭ AnyStreamingPaymentsClient: StreamingPaymentsClientV1 | StreamingPaymentsClientV2


AnyTokenSupplierClient

Ƭ AnyTokenSupplierClient: TokenSupplierClientV1 | TokenSupplierClientV2 | TokenSupplierClientV3 | TokenSupplierClientV4


AnyVotingReputationClient

Ƭ AnyVotingReputationClient: VotingReputationClientV1 | VotingReputationClientV2 | VotingReputationClientV3 | VotingReputationClientV4 | VotingReputationClientV5 | VotingReputationClientV6 | VotingReputationClientV7 | VotingReputationClientV8


AnyWhitelistClient

Ƭ AnyWhitelistClient: WhitelistClientV1 | WhitelistClientV2 | WhitelistClientV3


CoinMachineVersion

Ƭ CoinMachineVersion: typeof COIN_MACHINE_VERSIONS[number]


ColonyRoles

Ƭ ColonyRoles: UserRoles[]

All users that have roles in a colony


ColonyVersion

Ƭ ColonyVersion: typeof COLONY_VERSIONS[number]


ContractClient

Ƭ ContractClient: AnyColonyClient | ColonyNetworkClient | EventsClient | ExtensionClient | TokenContractClient | TokenLockingContractClient


ContractVersion

Ƭ ContractVersion: ExtensionVersion | ColonyVersion

All possible contract versions


DomainRoles

Ƭ DomainRoles: Object

All roles a user has in domainId

Type declaration

NameType
domainIdnumber
rolesColonyRole[]

EvaluatedExpenditureVersion

Ƭ EvaluatedExpenditureVersion: typeof EVALUATED_EXPENDITURE_VERSIONS[number]


EventsClient

Ƭ EventsClient: CoinMachineEvents | EvaluatedExpenditureEvents | IColonyEvents | IColonyNetworkEvents | IVotingReputationEvents | MetaTxTokenEvents | OneTxPaymentEvents | StakedExpenditureEvents | StreamingPaymentsEvents | TokenSupplierEvents | VotingReputationEvents | WhitelistEvents


ExtensionClient

Ƭ ExtensionClient: AnyCoinMachineClient | AnyEvaluatedExpenditureClient | AnyFundingQueueClient | AnyOneTxPaymentClient | AnyReputationBootstrapperClient | AnyStakedExpenditureClient | AnyStreamingPaymentsClient | AnyTokenSupplierClient | AnyVotingReputationClient | AnyWhitelistClient


ExtensionVersion

Ƭ ExtensionVersion: CoinMachineVersion | EvaluatedExpenditureVersion | FundingQueueVersion | OneTxPaymentVersion | ReputationBootstrapperVersion | StakedExpenditureVersion | StreamingPaymentsVersion | TokenSupplierVersion | VotingReputationVersion | WhitelistVersion

All possible extension versions


FundingQueueVersion

Ƭ FundingQueueVersion: typeof FUNDING_QUEUE_VERSIONS[number]


OneTxPaymentVersion

Ƭ OneTxPaymentVersion: typeof ONE_TX_PAYMENT_VERSIONS[number]


ReputationBootstrapperVersion

Ƭ ReputationBootstrapperVersion: typeof REPUTATION_BOOTSTRAPPER_VERSIONS[number]


SignerOrProvider

Ƭ SignerOrProvider: Signer | Provider


StakedExpenditureVersion

Ƭ StakedExpenditureVersion: typeof STAKED_EXPENDITURE_VERSIONS[number]


TokenSupplierVersion

Ƭ TokenSupplierVersion: typeof TOKEN_SUPPLIER_VERSIONS[number]


TxOverrides

Ƭ TxOverrides: Overrides & { from?: string }


UserRoles

Ƭ UserRoles: Object

All domains the user with address has roles in

Type declaration

NameType
addressstring
domainsDomainRoles[]

VotingReputationVersion

Ƭ VotingReputationVersion: typeof VOTING_REPUTATION_VERSIONS[number]


WhitelistVersion

Ƭ WhitelistVersion: typeof WHITELIST_VERSIONS[number]

Variables

DecisionMotionCode

Const DecisionMotionCode: "0x12345678"

Identifies a motion as a decision

Usually there's no need to use this directly.


ExtensionVersions

Const ExtensionVersions: Object

Latest versions of all extension contracts

Type declaration

NameType
CoinMachine1 | 2 | 3 | 4 | 5 | 6 | 7
EvaluatedExpenditure1 | 2 | 3
FundingQueue1 | 2 | 3 | 4
IVotingReputation1 | 2 | 3 | 4 | 5 | 6 | 7 | 8
OneTxPayment1 | 2 | 3 | 4
ReputationBootstrapper1
StakedExpenditure1 | 2
StreamingPayments1 | 2
TokenSupplier1 | 2 | 3 | 4
VotingReputation1 | 2 | 3 | 4 | 5 | 6 | 7 | 8
Whitelist1 | 2 | 3

Functions

addressesAreEqual

addressesAreEqual(a, b): boolean

Check if two addresses are equal

Addresses can be displayed using a checksum format which contains uppercase and lowercase characters. This function can compare addresses in either format

Parameters

NameTypeDescription
astringLeft hand side address
bstringRight hand side address

Returns

boolean

Whether a and b are the same address


colonyRoles2Hex

colonyRoles2Hex(roles): string

Converts Colony Roles to hex. Result is a binary number where the bits are one and the place of the role index. Then converted to hexadecimal, then padded with zeros to a lenghtof 64

Example

// Binary representation: 0b000101010
const roles = colonyRoles2Hex([ColonyRole.Root, ColonyRole.Architecture, ColonyRole.Funding]); // '0x000000000000000000000000000000000000000000000000000000000000002a'

Parameters

NameTypeDescription
rolesColonyRole[]An array of Colony roles

Returns

string

A hexadecimal string


formatColonyRoles

formatColonyRoles(roleSetEvents, recoveryRoleSetEvents): Promise<ColonyRoles>

Format role events into an Array of all roles in the colony

E.g.:

[{
address: 0x5346D0f80e2816FaD329F2c140c870ffc3c3E2Ef // user address
domains: [{ // all domains the user has a role in
domainId: 1, // domainId for the roles
roles: [1, 2, 3] // Array of `ColonyRole`
}]
}]

Parameters

NameType
roleSetEventsLogDescription[]
recoveryRoleSetEventsLogDescription[]

Returns

Promise<ColonyRoles>


getBlockTime

getBlockTime(blockHash, provider): Promise<number>

Get the JavaScript timestamp for a block

Parameters

NameTypeDescription
blockHashstringHash of block to get time for
providerProviderethers compatible Provider

Returns

Promise<number>

block timestamp in ms


getChildIndex

getChildIndex(network, colony, parentDomainId, domainId): Promise<BigNumber>

Get the child index for a domain inside its corresponding skills parent children array

E.g. (the values will differ for you!): domainId = 1 corresponding skillId = 2 parent of skillId 2:

{
// ...
children: [2]
}

childSkillIndex would be 0 in this case (0-position in children array)

Parameters

NameTypeDescription
networkCommonNetworkA ColonyNetwork contract
colonyCommonColonyA Colony contract
parentDomainIdBigNumberishid of parent domain
domainIdBigNumberishid of the domain

Returns

Promise<BigNumber>

Index in the children array (see above)


getColonyNetworkClient

getColonyNetworkClient(network, signerOrProvider, options?): ColonyNetworkClient

The main entry point for accessing the deployed colonyNetwork contracts

Specify a network and an ethers compatible singer or provider to get back an initialized and extended (ethers) contract client for the colonyNetwork. From here you can access different colonies, extensions, ENS and other features of Colony.

Example

import { getColonyNetworkClient, Network } = from '@colony/colony-js';
import { providers } from 'ethers';

// For local connections (run an Ethereum node on port 8545);
const provider = new providers.JsonRpcProvider();

// Just for reading data - to sign transactions we need to pass in a signer.
const networkClient = await getColonyNetworkClient(Network.Xdai, provider);

Parameters

NameTypeDescription
networkNetworkOne of the available options. See Network.
signerOrProviderSignerOrProviderAn ethers compatible signer or provider instance
options?NetworkClientOptionsHere you can supply options for accessing certain contracts (mostly used in local/dev environments)

Returns

ColonyNetworkClient


getColonyRoles

getColonyRoles(client, options?): Promise<ColonyRoles>

Get an array of all roles in the colony

Parameters

NameTypeDescription
clientAnyColonyClientAny ColonyClient
options?LogOptions-

Returns

Promise<ColonyRoles>

Array of user roles in a colony (see above) fetching it's own network events


getContractVersion

getContractVersion(address, signerOrProvider): Promise<ContractVersion>

Get the deployed contract's version

Only works with compatible contracts, i.e. Colony contracts or their extensions.

Parameters

NameTypeDescription
addressstringAddress of the deployed contract
signerOrProviderSignerOrProviderethers compatible Signer or Provider

Returns

Promise<ContractVersion>

The version number of the contract


getCreateMotionProofs

getCreateMotionProofs(network, colony, reputation, votingReputation, domainId, altTarget, action): Promise<{ actionCid: BigNumber ; branchMask: string ; key: string ; siblings: string[] ; value: string }>

Gets the necessary proofs for motion creation

This gets the reputation and domain proofs for motion creation

Parameters

NameTypeDescription
networkCommonNetwork-
colonyCommonColony-
reputationReputationClient-
votingReputationBaseContract-
domainIdBigNumberishDomain id the motion will be created in
altTargetstringTarget address for the motion (0x0 if Colony contract)
actionBytesLikeThe encoded action the motion will execute when finalized

Returns

Promise<{ actionCid: BigNumber ; branchMask: string ; key: string ; siblings: string[] ; value: string }>

The necessary reputation and domain proofs to create a motion


getEvents

getEvents(client, filter, options?): Promise<LogDescription[]>

Get parsed event data from filter

Example:

// Gets the logs for the `ColonyFundsClaimed` event (not filtered)
const filter = colonyClient.filters.ColonyFundsClaimed(null, null, null);
const events = await getEvents(colonyClient, filter);

Parameters

NameTypeDescription
clientContractClientAny of the intantiated contract clients
filterFilterethers compatible Filter object
options?LogOptionsConfiguration options to filter logs

Returns

Promise<LogDescription[]>

Parsed ethers LogDescription array (events)


getExtensionHash

getExtensionHash(extension): string

Hashes to identify the colony extension contracts

Parameters

NameTypeDescription
extensionExtensionA valid Extension name

Returns

string

A hash to identify the extension on the contracts


getHistoricColonyRoles

getHistoricColonyRoles(client, fromBlock?, toBlock?): Promise<ColonyRoles>

Parameters

NameType
clientAnyColonyClient
fromBlock?number
toBlock?number

Returns

Promise<ColonyRoles>


getLogs

getLogs(client, filter, options?): Promise<Log[]>

Get raw (unparsed logs) from filter

Example:

// Gets the logs for the `ColonyFundsClaimed` event (not filtered)
const filter = colonyClient.filters.ColonyFundsClaimed(null, null, null);
const logs = await getLogs(colonyClient, filter);

Parameters

NameTypeDescription
clientContractClientAny of the intantiated contract clients
filterFilterethers compatible Filter object
optionsLogOptionsConfiguration options to filter logs

Returns

Promise<Log[]>

ethers Log array


getMultipleEvents

getMultipleEvents(client, filters, options?): Promise<LogDescription[]>

Get multiple events from multiple filters

Remarks

only works when all events are emitted by the same contract!

Parameters

NameTypeDescription
clientContractClientAny of the intantiated contract clients
filtersEventFilter[]Array of ethers compatible Filter objects
options?LogOptionsConfiguration options to filter logs

Returns

Promise<LogDescription[]>

Parsed ethers LogDescription array (events)


getPermissionProofs

getPermissionProofs(network, colony, domainId, roles, customAddress?): Promise<[BigNumber, BigNumber, string]>

Get the permission proofs for a user address and a certain role

Certain methods on Colony contracts require so called "permission proofs". These are made up by the permissionDomainId and the childSkillIndex. We shall attempt an explanation here.

Domains within a colony can be nested and all the permissions in a parent domain apply for all child domains. Yet at the time of calling a domain-permissioned method the contracts are unaware of the parent domain a certain user has the required permission in. So when we these methods are called we have to supply them the id of the parent domain the user has the permission in (it could also be the very same domain id they want to act in!). Furthermore for the contracts the unidirectional chain downwards we have to supply the method wuth the index of the domains associated skill in its parents children array (childSkillIndex, see [[getChildIndex]]). The contracts are then able to verify the permissions (the role) claimed by the caller.

tl;dr:

  • permissionDomainId: id of the parent domain of the required domain the user has the required permission in
  • childSkillIndex: the child index for a domain inside its corresponding skills parent children array

Parameters

NameTypeDescription
networkCommonNetwork-
colonyCommonColony-
domainIdBigNumberishDomain id the method needs to act in
rolesColonyRole | ColonyRole[]Permissioning role(s) that the methods needs to function
customAddress?stringA custom address to get the permission proofs for (defaults to the signer's address)

Returns

Promise<[BigNumber, BigNumber, string]>

Tuple of [permissionDomainId, childSkillIndex, permissionAddress]


getPotDomain

getPotDomain(colony, potId): Promise<BigNumberish>

Get the associated domain for a pot id

Remarks

pots can be associated with different types, like domains, payments or tasks See [[FundingPotAssociatedType]] for details

Parameters

NameTypeDescription
colonyCommonColony-
potIdBigNumberishThe funding pot id

Returns

Promise<BigNumberish>

The associated domainId


hex2ColonyRoles

hex2ColonyRoles(hexStr): ColonyRole[]

Converts a role hex string (typically returned by a Colony contract) to Colony Roles.

Example

// Binary representation: 0b000101010
const roles = hex2ColonyRoles('0x2a'); // [1, 3, 5]

Parameters

NameTypeDescription
hexStrstringA (probably padded) hexadecimal string

Returns

ColonyRole[]

An array of Colony roles


isExtensionCompatible

isExtensionCompatible(extension, extensionVersion, colonyVersion): boolean

Checks the compatibility of an extension version with a colony version it requests to be installed in Returns true if an extension version is compatible with the given colony version

Parameters

NameTypeDescription
extensionExtensionA valid Extension contract name
extensionVersionExtensionVersionThe version of the extension to check against the colony
colonyVersion2 | 1 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12The version of the colony to check for

Returns

boolean

indication whether extension in given version is compatible with colony at the given version


parseLogs

parseLogs(logs, iface): LogDescription[]

Try to parse an array of logs with a given interface

Will filter out logs that can't be parsed with the given interface

Parameters

NameTypeDescription
logsLog[]Array of log entries (usually from a ContractReceipt)
ifaceInterfaceEthers compatible contract interface

Returns

LogDescription[]

A list of parsed log entries (events)


parsePermissionedAction

parsePermissionedAction(action): Object

Parameters

NameType
actionBytesLike

Returns

Object

NameType
childSkillIndexBigNumber
permissionDomainIdBigNumber
sigstring

toEth

toEth(num): string

Convert any number to ETH (remove 18 zeros)

Example

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

const oneEther = BigNumber.from("1000000000000000000");
console.log(toEth(oneEther)); // 1.0

Parameters

NameType
numBigNumberish

Returns

string


toWei

toWei(num): BigNumber

Convert any number to wei (add 18 zeros)

Example

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

const oneEther = '1.0';
console.log(toWei(oneEther)); // { BigNumber: "1000000000000000000" }

Parameters

NameType
numstring

Returns

BigNumber


w

w(str): BigNumber

Short-hand method to convert a number to wei using JS tagged template strings

See also here: http://tc39wiki.calculist.org/es6/template-strings/

Remarks

This is only useful in contexts where the number is hard-coded (e.g. examples)

Example

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

console.log(w`1.0`); // { BigNumber: "1000000000000000000" }

Parameters

NameType
strTemplateStringsArray

Returns

BigNumber