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