Secure the networkBug Bounty!November 2018

TokenClient

The TokenClient is a standard interface for interactions with functions and events described in Token.sol.

Upon creation, new colonies can either create or import existing token contracts. These contracts are expected to conform to the ERC20 or ERC20Extended token standard interface, the latter allowing for mint and burn functions. The token client is intended to help keep interactions with a colony's token straightforward.

Most functions are fairly self-explanatory and mirror their on-chain counterparts, but in some cases the function will return values passed from event data, rather than simple boolean expressions (which are returned from the contract on-chain).

Create an instance

The TokenClient is initialized for you when you ask the ColonyNetworkClient for a new instance of ColonyClient:

const tokenClient = colonyClient.token;

You could create an instance of TokenClient by providing an adapter and a query:

const tokenClient = new TokenClient({ adapter, query });

await tokenClient.init();

Callers

All callers return promises which resolve to an object containing the given return values. For a reference please check here.

getTokenInfo.call()

Get information about the ERC20 token itself

Returns

A promise which resolves to an object containing the following properties:

Return valueTypeDescription
namestringThe token's name (e.g. Cool Colony Token)
symbolstringThe token's symbol (e.g. CCT)
decimalsnumberThe token's decimals

getTotalSupply.call()

Get the total token supply.

Returns

A promise which resolves to an object containing the following properties:

Return valueTypeDescription
amountBigNumberThe total token supply.

getBalanceOf.call({ sourceAddress })

Returns the token balance of a given address.

Arguments

ArgumentTypeDescription
sourceAddressAddressThe address in question.

Returns

A promise which resolves to an object containing the following properties:

Return valueTypeDescription
amountBigNumberThe balance of tokens associated with the address.

getAllowance.call({ sourceAddress, user })

Given a token owner address and a spender, will return the amount of tokens approved by the owner that can be transferred to the spender's account.

Arguments

ArgumentTypeDescription
sourceAddressAddressAddress of the token owner.
userAddressAddress of the approved spender.

Returns

A promise which resolves to an object containing the following properties:

Return valueTypeDescription
amountBigNumberThe approved amount of tokens the spender may transfer.

Senders

All senders return an instance of a ContractResponse. Every send() method takes an options object as the second argument. For a reference please check here.

transfer.send({ destinationAddress, amount }, options)

Transfer an amount of tokens from a token owner's account to a specified destination address.

Arguments

ArgumentTypeDescription
destinationAddressAddressThe account to recieve the tokens.
amountBigNumberThe amount to transfer.

Returns

An instance of a ContractResponse

transferFrom.send({ sourceAddress, destinationAddress, amount }, options)

Transfer tokens from a specified account to a destination account. Token transfer must have a sufficient balance and allowance set by the source account for the destination address.

Arguments

ArgumentTypeDescription
sourceAddressAddress'from' address, or the token owner account.
destinationAddressAddress'to' address, or the destination with sufficient allowance` for transfer.
amountBigNumberAmount to transfer.

Returns

An instance of a ContractResponse which will eventually receive the following event data:

Event dataTypeDescription
fromAddressEvent data indicating the 'from' address.
toAddressEvent data indicating the 'to' address.
valueBigNumberEvent data indicating the amount transferred.
TransferobjectContains the data defined in Transfer

approve.send({ user, amount }, options)

The owner of a token can approve an allowance that a spender is authorized to transfer using the transferFrom function.

Arguments

ArgumentTypeDescription
userAddressThe spending account allowed to transfer tokens with transferFrom .
amountBigNumberThe maximum allowance that the spending account may transfer from the owner to the spender.

Returns

An instance of a ContractResponse which will eventually receive the following event data:

Event dataTypeDescription
ownerAddressEvent data indicating the token owner ('from' address).
spenderAddressEvent data indicating the spender (who is given the allowance ).
valueBigNumberEvent data indicating the new value of allowed transfer.
ApprovalobjectContains the data defined in Approval

mint.send({ amount }, options)

ERC20Extended functionality to mint new tokens and add to the total supply. In colony these functions are subject to authority restrictions.

Arguments

ArgumentTypeDescription
amountBigNumberThe amount of new tokens to mint.

Returns

An instance of a ContractResponse which will eventually receive the following event data:

Event dataTypeDescription
addressAddressThe address that initiated the mint event.
amountBigNumberEvent data indicating the amount of tokens minted.
MintobjectContains the data defined in Mint

burn.send({ amount }, options)

ERC20Extended functionality to burn un-owned tokens and subtract from the total token supply. In colony these functions are subject to authority restrictions.

Arguments

ArgumentTypeDescription
amountBigNumberThe amount of unspent tokens to burn.

Returns

An instance of a ContractResponse which will eventually receive the following event data:

Event dataTypeDescription
addressAddressThe address that initiated the burn event.
amountBigNumberEvent data indicating the amount burned.
BurnobjectContains the data defined in Burn

setOwner.send({ owner }, options)

Sets the owner of a given token contract. In most situations this should be the colony's own address.

Arguments

ArgumentTypeDescription
ownerAddressThe address of the new owner.

Returns

An instance of a ContractResponse which will eventually receive the following event data:

Event dataTypeDescription
ownerAddressEvent data indicating the new owner.
LogSetOwnerobjectContains the data defined in LogSetOwner

setAuthority.send({ authority }, options)

Give a particular account special authority (admin) within a colony.

Arguments

ArgumentTypeDescription
authorityAddressThe address to be given admin authority.

Returns

An instance of a ContractResponse which will eventually receive the following event data:

Event dataTypeDescription
authorityAddressEvent data indicating the address given authority.
LogSetAuthorityobjectContains the data defined in LogSetAuthority

Events

Refer to the ContractEvent class here to interact with these events.

events.Transfer.addListener(({ from, to, value }) => { /* ... */ })

Arguments

ArgumentTypeDescription
fromAddressEvent data indicating the 'from' address.
toAddressEvent data indicating the 'to' address.
valueBigNumberEvent data indicating the amount transferred.

events.Approval.addListener(({ owner, spender, value }) => { /* ... */ })

Arguments

ArgumentTypeDescription
ownerAddressEvent data indicating the token owner ('from' address).
spenderAddressEvent data indicating the spender (who is given the allowance ).
valueBigNumberEvent data indicating the new value of allowed transfer.

events.Burn.addListener(({ address, amount }) => { /* ... */ })

Arguments

ArgumentTypeDescription
addressAddressThe address that initiated the burn event.
amountBigNumberEvent data indicating the amount burned.

events.LogSetAuthority.addListener(({ authority }) => { /* ... */ })

Arguments

ArgumentTypeDescription
authorityAddressEvent data indicating the address given authority.

events.LogSetOwner.addListener(({ owner }) => { /* ... */ })

Arguments

ArgumentTypeDescription
ownerAddressEvent data indicating the new owner.

events.Mint.addListener(({ address, amount }) => { /* ... */ })

Arguments

ArgumentTypeDescription
addressAddressThe address that initiated the mint event.
amountBigNumberEvent data indicating the amount of tokens minted.