ConverterBase

ConverterBase

The converter contains the main logic for conversions between different ERC20 tokens.

It is also the upgradable part of the mechanism (note that upgrades are opt-in).

The anchor must be set on construction and cannot be changed afterwards.

Wrappers are provided for some of the anchor's functions, for easier access.

Once the converter accepts ownership of the anchor, it becomes the anchor's sole controller

and can execute any of its functions.

To upgrade the converter, anchor ownership must be transferred to a new converter, along with

any relevant data.

Note that the converter can transfer anchor ownership to a new converter that

doesn't allow upgrades anymore, for finalizing the relationship between the converter

and the anchor.

Converter types (defined as uint16 type) -

0 = liquid token converter

1 = liquidity pool v1 converter

2 = liquidity pool v2 converter

Note that converters don't currently support tokens with transfer fees.

Functions:

Events:

Function fallback()

deposits ether

can only be called if the converter has an ETH reserve

Function withdrawETH(address _to)

withdraws ether

can only be called by the owner if the converter is inactive or by upgrader contract

can only be called after the upgrader contract has accepted the ownership of this contract

can only be called if the converter has an ETH reserve

Parameters:

  • _to: address to send the ETH to

Function isV28OrHigher() → bool

checks whether or not the converter version is 28 or higher

Return Values:

  • since the converter version is 28 or higher

Function setConversionWhitelist(contract IWhitelist _whitelist)

allows the owner to update & enable the conversion whitelist contract address

when set, only addresses that are whitelisted are actually allowed to use the converter

note that the whitelist check is actually done by the BancorNetwork contract

Parameters:

  • _whitelist: address of a whitelist contract

Function isActive() → bool

returns true if the converter is active, false otherwise

Return Values:

  • true if the converter is active, false otherwise

Function transferAnchorOwnership(address _newOwner)

transfers the anchor ownership

the new owner needs to accept the transfer

can only be called by the converter upgrder while the upgrader is the owner

note that prior to version 28, you should use 'transferAnchorOwnership' instead

Parameters:

  • _newOwner: new token owner

Function acceptAnchorOwnership()

accepts ownership of the anchor after an ownership transfer

most converters are also activated as soon as they accept the anchor ownership

can only be called by the contract owner

note that prior to version 28, you should use 'acceptTokenOwnership' instead

Function withdrawFromAnchor(contract IERC20Token _token, address _to, uint256 _amount)

withdraws tokens held by the anchor and sends them to an account

can only be called by the owner

Parameters:

  • _token: ERC20 token contract address

  • _to: account to receive the new amount

  • _amount: amount to withdraw

Function setConversionFee(uint32 _conversionFee)

updates the current conversion fee

can only be called by the contract owner

Parameters:

  • _conversionFee: new conversion fee, represented in ppm

Function withdrawTokens(contract IERC20Token _token, address _to, uint256 _amount)

withdraws tokens held by the converter and sends them to an account

can only be called by the owner

note that reserve tokens can only be withdrawn by the owner while the converter is inactive

unless the owner is the converter upgrader contract

Parameters:

  • _token: ERC20 token contract address

  • _to: account to receive the new amount

  • _amount: amount to withdraw

Function upgrade()

upgrades the converter to the latest version

can only be called by the owner

note that the owner needs to call acceptOwnership on the new converter after the upgrade

Function reserveTokenCount() → uint16

returns the number of reserve tokens defined

note that prior to version 17, you should use 'connectorTokenCount' instead

Return Values:

  • number of reserve tokens

Function addReserve(contract IERC20Token _token, uint32 _weight)

defines a new reserve token for the converter

can only be called by the owner while the converter is inactive

Parameters:

  • _token: address of the reserve token

  • _weight: reserve weight, represented in ppm, 1-1000000

Function reserveWeight(contract IERC20Token _reserveToken) → uint32

returns the reserve's weight

added in version 28

Parameters:

  • _reserveToken: reserve token contract address

Return Values:

  • reserve weight

Function reserveBalance(contract IERC20Token _reserveToken) → uint256

returns the reserve's balance

note that prior to version 17, you should use 'getConnectorBalance' instead

Parameters:

  • _reserveToken: reserve token contract address

Return Values:

  • reserve balance

Function hasETHReserve() → bool

checks whether or not the converter has an ETH reserve

Return Values:

  • true if the converter has an ETH reserve, false otherwise

Function convert(contract IERC20Token _sourceToken, contract IERC20Token _targetToken, uint256 _amount, address _trader, address _beneficiary) → uint256

converts a specific amount of source tokens to target tokens

can only be called by the bancor network contract

Parameters:

  • _sourceToken: source ERC20 token

  • _targetToken: target ERC20 token

  • _amount: amount of tokens to convert (in units of the source token)

  • _trader: address of the caller who executed the conversion

  • _beneficiary: wallet to receive the conversion result

Return Values:

  • amount of tokens received (in units of the target token)

Function token() → contract IConverterAnchor

deprecated since version 28, backward compatibility - use only for earlier versions

Function transferTokenOwnership(address _newOwner)

deprecated, backward compatibility

Function acceptTokenOwnership()

deprecated, backward compatibility

Function connectors(address _address) → uint256, uint32, bool, bool, bool

deprecated, backward compatibility

Function connectorTokens(uint256 _index) → contract IERC20Token

deprecated, backward compatibility

Function connectorTokenCount() → uint16

deprecated, backward compatibility

Function getConnectorBalance(contract IERC20Token _connectorToken) → uint256

deprecated, backward compatibility

Function getReturn(contract IERC20Token _sourceToken, contract IERC20Token _targetToken, uint256 _amount) → uint256, uint256

deprecated, backward compatibility

Event Activation(uint16 _type, contract IConverterAnchor _anchor, bool _activated)

triggered when the converter is activated

Parameters:

  • _type: converter type

  • _anchor: converter anchor

  • _activated: true if the converter was activated, false if it was deactivated

Event Conversion(address _fromToken, address _toToken, address _trader, uint256 _amount, uint256 _return, int256 _conversionFee)

triggered when a conversion between two tokens occurs

Parameters:

  • _fromToken: source ERC20 token

  • _toToken: target ERC20 token

  • _trader: wallet that initiated the trade

  • _amount: amount converted, in the source token

  • _return: amount returned, minus conversion fee

  • _conversionFee: conversion fee

Event TokenRateUpdate(address _token1, address _token2, uint256 _rateN, uint256 _rateD)

triggered when the rate between two tokens in the converter changes

note that the event might be dispatched for rate updates between any two tokens in the converter

note that prior to version 28, you should use the 'PriceDataUpdate' event instead

Parameters:

  • _token1: address of the first token

  • _token2: address of the second token

  • _rateN: rate of 1 unit of _token1 in _token2 (numerator)

  • _rateD: rate of 1 unit of _token1 in _token2 (denominator)

Event ConversionFeeUpdate(uint32 _prevFee, uint32 _newFee)

triggered when the conversion fee is updated

Parameters:

  • _prevFee: previous fee percentage, represented in ppm

  • _newFee: new fee percentage, represented in ppm

Contents
Functions:
Events:
Function fallback()
Function withdrawETH(address _to)
Parameters:
Function isV28OrHigher() → bool
Return Values:
Function setConversionWhitelist(contract IWhitelist _whitelist)
Parameters:
Function isActive() → bool
Return Values:
Function transferAnchorOwnership(address _newOwner)
Parameters:
Function acceptAnchorOwnership()
Function withdrawFromAnchor(contract IERC20Token _token, address _to, uint256 _amount)
Parameters:
Function setConversionFee(uint32 _conversionFee)
Parameters:
Function withdrawTokens(contract IERC20Token _token, address _to, uint256 _amount)
Parameters:
Function upgrade()
Function reserveTokenCount() → uint16
Return Values:
Function addReserve(contract IERC20Token _token, uint32 _weight)
Parameters:
Function reserveWeight(contract IERC20Token _reserveToken) → uint32
Parameters:
Return Values:
Function reserveBalance(contract IERC20Token _reserveToken) → uint256
Parameters:
Return Values:
Function hasETHReserve() → bool
Return Values:
Function convert(contract IERC20Token _sourceToken, contract IERC20Token _targetToken, uint256 _amount, address _trader, address _beneficiary) → uint256
Parameters:
Return Values:
Function token() → contract IConverterAnchor
Function transferTokenOwnership(address _newOwner)
Function acceptTokenOwnership()
Function connectors(address _address) → uint256, uint32, bool, bool, bool
Function connectorTokens(uint256 _index) → contract IERC20Token
Function connectorTokenCount() → uint16
Function getConnectorBalance(contract IERC20Token _connectorToken) → uint256
Function getReturn(contract IERC20Token _sourceToken, contract IERC20Token _targetToken, uint256 _amount) → uint256, uint256
Event Activation(uint16 _type, contract IConverterAnchor _anchor, bool _activated)
Parameters:
Event Conversion(address _fromToken, address _toToken, address _trader, uint256 _amount, uint256 _return, int256 _conversionFee)
Parameters:
Event TokenRateUpdate(address _token1, address _token2, uint256 _rateN, uint256 _rateD)
Parameters:
Event ConversionFeeUpdate(uint32 _prevFee, uint32 _newFee)
Parameters: