ERC20 Token Configuration
in CoreExchange

Introduction

The Ethereum ERC20 Token Standard defines the requirements that a compliant Ethereum smart contract must meet. Most important in the scope of CoreExchange are:

  • The methods
    • decimals() which returns/defines the number of fractional digits in a token amount. CoreExchange does not actively use this method, but you can - and should - use it to provide the decimals once you start to configure support for an ERC20 compliant token in CoreExchange. Note that this is defined as optional in the standard - for tokens that do not implement it you will have to retrieve the information from other sources.
    • balanceOf(address) which returns the token balance of an address. CoreExchange actively uses this method to retrieve the (spendable) token balances of addresses that belong to ERC20 token wallet accounts.
    • transfer(address, amount) which is used to transfer the given amount of tokens owned by caller to the provided address. CoreExchange uses this method for ERC20 token withdrawals (to Ethereum addresses outside of CoreExchange).
  • The event
    • Transfer(from, to, amount) which is emitted for each ERC20 token transfer - the event provides the details about the transfer (from which address the transfer has been made, which address received the transfer, and how many tokens were transferred. CoreExchange monitors the Ethereum blockchain for such events to detect ERC20 transfers and to update wallet account and internal balances if an address affected by the transfer belongs to CoreExchange (i.e. is one of a wallet account in CoreExchange)

Due to the nature of the ERC20 standard any Ethereum address (‘external account’ addresses in the Ethereum terminology, meaning addresses created from a private key - usually belonging to an individual wallet - as well as smart contract addresses, for which no private key exists) can receive ERC20 tokens, but for smart contracts it requires support in the smart contract implementation itself to be able to to ‘use’ the token (i.e. to ‘withdraw’ received tokens to another address). Due to this restriction additional standards have been proposed, such as ERC223, but they are not yet as widely adopted as ERC20.

In CoreExchange each Ethereum (and ERC20 token) wallet account is backed by a smart contract that serves as the incoming payment instrument.

This smart contract provides support for re-transferring any ERC20 token it may have received to any valid Ethereum address, by means of the method

transferERC20(contract, destination, amount) - where contract means the address of the ERC20 token contract, destination means the address where the tokens will be re-transferred, and amount means the amount of tokens to transfer. The underlying implementation will simply issue
        ERC20Interface(contract).transfer(destination, value)

for doing the transfer.

Since ERC20 tokens are free to define an optional token symbol (‘currency code’ in a wider sense) and also an optional token name it cannot be guaranteed that distinct ERC20 token deployments have distinct symbols or names, so you will have to define the currency code and (spelled out) currency name to use for the token in CoreExchange yourself.

Configuration Procedure for an ERC20 Token

Important notes

  • Order is important here if you want to avoid errors and annoyances for your users!
  • After the token is activated/enabled below, the token will be immediately visible to consumers logged in to their accounts, and users will be able to create their corresponding wallet accounts.
  • The initial limit definitions will be similar to the ones that are defined for Ethereum at the time the token is being activated/enabled, but they will all be set to disabled. You absolutely should review and adjust the individual limit definitions for the token

Configuration Procedure

  • Identify the token you want to configure, particularly its token contract address and the number of decimals it defines.
  • Define a token currency code (unique!), name, and a description that you want to use in CoreExchange for the token. The currency code may be the same as the ‘‘symbol’ the token itself defines as long as that code is not yet used in CoreExchange.
  • Define the Consumer UI translations for the token currency code.
  • Update the Consumer UI deployment to be prepared for the upcoming support for the token.
  • Define a unique currency number to use for the token in CoreExchange.
  • Create the token configuration using the CoreExchange Admin UI
            System → ERC20 Tokens → Create ERC20 token configuration



or API
see POST /v2/admin/exchange/crypto/erc20tokens
by using

  1. The token contract address
  2. The currency code
  3. The currency number
  4. The decimal digits the token uses
  5. A defaultFormatString suitable for the number of decimal digits, for example
    %s %0.018f” (without the quotes) if you want the default format to be the currency code followed by the amount as a floating point number with 18 fractional digits
  6. Any name you want to use for the token
  7. Any description you want to add
  8. Investigate and define the initial exchange rate for the token currency from/to the lead currency
  9. Activate the token using the CoreExchange Admin UI
    System → ERC20 Tokens → use the button ‘Enable/Activate’




or API
POST /v2/admin/exchange/crypto/erc20tokens/{currencyCode}:enable

  • Review & update the limit definitions created for the token, and enable those you want to be enabled (all limit definitions are initially set to ‘disabled’)
  • Define and configure any fee definitions you want to be applicable for the token in CoreExchange Admin UI or using the API.
  • Create and configure any markets for the token you want to support (usually tokens are traded against Ethereum, but you may also want to support trading them for the lead currency), including the trading maker fees and trading taker fees.