TokenClient

The TokenClient is a standard interface for interactions with methods and events described in Token.sol. These interactions are extended from the ERC20 and DSToken standard token interfaces and are generally concerned with managing the native token assigned to a colony. This includes operations such as minting tokens, burning tokens, and transferring tokens.

See Clients for more information about initializing TokenClient.

See ContractClient for more information about the ContractClient superclass.

Callers

getAllowance

Get the token allowance of an address. The allowance is the amount of tokens that the spender is authorized to transfer using the transferFrom function.

await tokenClient.getAllowance.call({
  sourceAddress,
  user,
});

Input

NameTypeDescription
sourceAddressaddressThe address that approved the allowance (the token owner).
useraddressThe address that was approved for the allowance (the token spender).

Response

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

NameTypeDescription
amountbig numberThe amount of tokens that were approved (the amount allowed).

Contract Information

Function: allowance

Contract: base.sol

getBalanceOf

Get the the token balance of an address.

await tokenClient.getBalanceOf.call({
  sourceAddress,
});

Input

NameTypeDescription
sourceAddressaddressThe address that will be checked.

Response

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

NameTypeDescription
amountbig numberThe balance of tokens for the address.

Contract Information

Function: balanceOf

Contract: base.sol

getTokenInfo

Get information about the token.

await tokenClient.getTokenInfo.call();

Response

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

NameTypeDescription
namestringThe name of the token.
symbolstringThe symbol of the token.
decimalsnumberThe number of decimals.

Contract Information

Contract: Token.sol

getTotalSupply

Get the total supply of the token.

await tokenClient.getTotalSupply.call();

Response

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

NameTypeDescription
amountbig numberThe total supply of the token.

Contract Information

Function: totalSupply

Contract: base.sol

isLocked

Get whether the token is locked.

await tokenClient.isLocked.call();

Response

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

NameTypeDescription
lockedbooleanWhether the token is locked.

Contract Information

Function: locked

Contract: Token.sol

Senders

approve

Approve a token allowance. This function can only be called by the token owner. The allowance is the amount of tokens that the spender is authorized to transfer using the transferFrom function.

await tokenClient.approve.send({
  user,
  amount,
}, options);

Input

NameTypeDescription
useraddressThe address that will be approved for the allowance (the token spender).
amountbig numberThe amount of tokens that will be approved (the amount allowed).

Options

See Sender for more information about options.

Response

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

NameTypeDescription
owneraddressThe address that approved the allowance (the token owner).
spenderaddressThe address that was approved for the allowance (the token spender).
valuebig numberThe amount of tokens that were approved (the amount allowed).
ApprovalobjectContains the data defined in Approval

See Sender for more information about ContractResponse.

Contract Information

Contract: base.sol

burn

Burn tokens. This is a DSToken function that can only be called by the token owner. When a colony contract address is assigned as the token owner, this function can only be called by the user assigned the FOUNDER authority role.

await tokenClient.burn.send({
  user,
  amount,
}, options);

Input

NameTypeDescription
useraddressThe address from which the tokens will be burned.
amountbig numberThe amount of tokens that will be burned.

Options

See Sender for more information about options.

Response

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

NameTypeDescription
addressaddressThe address from which the tokens were burned.
amountbig numberThe amount of tokens that were burned.
BurnobjectContains the data defined in Burn

See Sender for more information about ContractResponse.

Contract Information

Contract: Token.sol

createTokenAuthority

Deploy a TokenAuthority contract which can then be use to control the transfer of a token.

await tokenClient.createTokenAuthority.send({
  allowedToTransfer,
  colonyAddress,
  tokenAddress,
}, options);

Input

NameTypeDescription
allowedToTransferundefinedAdditional addresses which are allowed to transfer the token while locked.
colonyAddressaddressThe address of the colony which should be allowed control of the token.
tokenAddressaddressThe address of the token for which this contract will operate.

Options

See Sender for more information about options.

Response

An instance of a ContractResponse which will receive a receipt with a contractAddress property.

See Sender for more information about ContractResponse.

Contract Information

Contract: Token.sol

mint

Mint new tokens. This is a DSToken function that can only be called by the token owner. When a colony contract address is assigned as the token owner, this function can only be called by the user assigned the FOUNDER authority role.

await tokenClient.mint.send({
  user,
  amount,
}, options);

Input

NameTypeDescription
useraddressThe address that will receive the minted tokens.
amountbig numberThe amount of tokens that will be minted.

Options

See Sender for more information about options.

Response

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

NameTypeDescription
addressaddressThe address to which the minted tokens were sent.
amountbig numberThe amount of tokens that were minted.
MintobjectContains the data defined in Mint

See Sender for more information about ContractResponse.

Contract Information

Contract: Token.sol

setAuthority

Assign an account the ADMIN authority role within a colony.

await tokenClient.setAuthority.send({
  authority,
}, options);

Input

NameTypeDescription
authorityaddressThe address that will be assigned the ADMIN authority role.

Options

See Sender for more information about options.

Response

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

NameTypeDescription
authorityaddressThe address that was assigned an authority role.
LogSetAuthorityobjectContains the data defined in LogSetAuthority

See Sender for more information about ContractResponse.

Contract Information

Contract: auth.sol

setOwner

Set the owner of a token contract. This function can only be called by the current owner of the contract. In order to call token contract methods from within a colony, the token owner must be the address of the colony contract.

await tokenClient.setOwner.send({
  owner,
}, options);

Input

NameTypeDescription
owneraddressThe address that will be assigned as the new owner.

Options

See Sender for more information about options.

Response

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

NameTypeDescription
owneraddressThe address that was assigned as the new owner.
LogSetOwnerobjectContains the data defined in LogSetOwner

See Sender for more information about ContractResponse.

Contract Information

Contract: auth.sol

transfer

Transfer tokens from the address calling the function to another address. The current address must have a sufficient token balance.

await tokenClient.transfer.send({
  destinationAddress,
  amount,
}, options);

Input

NameTypeDescription
destinationAddressaddressThe address to which tokens will be transferred.
amountbig numberThe amount of tokens that will be transferred.

Options

See Sender for more information about options.

Response

An instance of a ContractResponse.

See Sender for more information about ContractResponse.

Contract Information

Contract: base.sol

transferFrom

Transfer tokens from one address to another address. The address the tokens are transferred from must have a sufficient token balance and it must have a sufficient token allowance approved by the token owner.

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

Input

NameTypeDescription
sourceAddressaddressThe address from which tokens will be transferred.
destinationAddressaddressThe address to which tokens will be transferred.
amountbig numberThe amount of tokens that will be transferred.

Options

See Sender for more information about options.

Response

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

NameTypeDescription
fromaddressThe address of the account that sent tokens.
toaddressThe address of the account that received tokens.
valuebig numberThe amount of tokens that were transferred.
TransferobjectContains the data defined in Transfer

See Sender for more information about ContractResponse.

Contract Information

Contract: base.sol

unlock

Unlock the token.

await tokenClient.unlock.send(options);

Options

See Sender for more information about options.

Response

An instance of a ContractResponse.

See Sender for more information about ContractResponse.

Contract Information

Contract: Token.sol

Events

Approval

Event Handler

const eventHandler = ({
  owner,
  spender,
  value,
}) => {
  // perform an action using the event data
};

Add Listener

tokenClient.events.Approval.addListener(eventHandler);

Remove Listener

tokenClient.events.Approval.removeListener(eventHandler);

Event Data

NameTypeDescription
owneraddressThe address that approved the allowance (the token owner).
spenderaddressThe address that was approved for the allowance (the token spender).
valuebig numberThe amount of tokens that were approved (the amount allowed).

Burn

Event Handler

const eventHandler = ({
  address,
  amount,
}) => {
  // perform an action using the event data
};

Add Listener

tokenClient.events.Burn.addListener(eventHandler);

Remove Listener

tokenClient.events.Burn.removeListener(eventHandler);

Event Data

NameTypeDescription
addressaddressThe address from which the tokens were burned.
amountbig numberThe amount of tokens that were burned.

LogSetAuthority

Event Handler

const eventHandler = ({
  authority,
}) => {
  // perform an action using the event data
};

Add Listener

tokenClient.events.LogSetAuthority.addListener(eventHandler);

Remove Listener

tokenClient.events.LogSetAuthority.removeListener(eventHandler);

Event Data

NameTypeDescription
authorityaddressThe address that was assigned an authority role.

LogSetOwner

Event Handler

const eventHandler = ({
  owner,
}) => {
  // perform an action using the event data
};

Add Listener

tokenClient.events.LogSetOwner.addListener(eventHandler);

Remove Listener

tokenClient.events.LogSetOwner.removeListener(eventHandler);

Event Data

NameTypeDescription
owneraddressThe address that was assigned as the new owner.

Mint

Event Handler

const eventHandler = ({
  address,
  amount,
}) => {
  // perform an action using the event data
};

Add Listener

tokenClient.events.Mint.addListener(eventHandler);

Remove Listener

tokenClient.events.Mint.removeListener(eventHandler);

Event Data

NameTypeDescription
addressaddressThe address to which the minted tokens were sent.
amountbig numberThe amount of tokens that were minted.

Transfer

Event Handler

const eventHandler = ({
  from,
  to,
  value,
}) => {
  // perform an action using the event data
};

Add Listener

tokenClient.events.Transfer.addListener(eventHandler);

Remove Listener

tokenClient.events.Transfer.removeListener(eventHandler);

Event Data

NameTypeDescription
fromaddressThe address of the account that sent tokens.
toaddressThe address of the account that received tokens.
valuebig numberThe amount of tokens that were transferred.

Support

Questions? Problems? Existential dilemmas? We’re here to help!

Improve this doc.

All improvements to documentation are welcome and encouraged. Submit a PR for documentation on GitHub.