contract ConversionRates

is ConversionRatesInterface, VolumeImbalanceRecorder, Utils
imports ERC20Interface, VolumeImbalanceRecorder, ConversionRatesInterface, Utils

Source: ConversionRates.sol

The ConversionRates contract's role is to allow reserve operators to make simple on-chain adjustment to the prices and is an optimized cheap (w.r.t gas consumption) interface to enter rate feeds.

INDEX

StepFunction
TokenData
ConversionRates
addToken
disableTokenTrade
enableTokenTrade
getBasicRate
getCompactData
getListedTokens
getRate
getRateUpdateBlock
getStepFunctionData
getTokenBasicData
recordImbalance
setBaseRate
setCompactData
setQtyStepFunction
setTokenControlInfo
setImbalanceStepFunction
setValidRateDurationInBlocks
setReserveAddress

REFERENCE

Structs

`StepFunction`

Property	Type	Description
`x`	int[]	Quantity for each step. Includes previous steps
`y`	int[]	Rate change per quantity step in bps

`TokenData`

Property	Type	Description
`listed`	bool	`true` if added to reserve, `false` otherwise
`enabled`	bool	`true` if trades are enabled, `false` otherwise
`compactDataArrayIndex`	uint	Token position in compact data
`compactDataFieldIndex`	uint	Token position in compact data
`baseBuyRate`	uint	Base buy rate of token
`baseSellRate`	uint	Base sell rate of token
`buyRateQtyStepFunction`	StepFunction	source ERC20 token balance of user
`sellRateQtyStepFunction`	StepFunction	destination ERC20 token balance of user
`buyRateImbalanceStepFunction`	StepFunction	source ERC20 token balance of user
`sellRateImbalanceStepFunction`	StepFunction	destination ERC20 token balance of user

Functions

`ConversionRates`

Contract constructor. Note that constructor methods are called exactly once during contract instantiation and cannot be called again.

function ConversionRates(address _admin) public

Parameter	Type	Description
`_admin`	address	admin's wallet address

Web3 Example:

// DISCLAIMER: Code snippets in this guide are just examples and you
// should always do your own testing. If you have questions, visit our
// https://t.me/KyberDeveloper.

const fs = require("fs");
const solc = require("solc");
const Web3 = require("web3");

const web3 = new Web3(new Web3.providers.HttpProvider("http://localhost:8545"));
const input = fs.readFileSync("ConversionRates.sol", "utf8");
const output = await solc.compile(input, 1);
const bytecode = output.contracts["ConversionRates"].bytecode;
const abi = JSON.parse(output.contracts["ConversionRates"].interface);

const ConversionRates = new web3.eth.Contract(JSON.parse(abi));
const _admin = "<ADMIN ADDRESS>";

const deploy = ConversionRates.deploy({
  data: `0x${bytecode}`,
  arguments: [_admin]
});

broadcastTx(deploy);

Code snippet reference: broadcastTx()

`addToken`

Adding an ERC20 token which the reserve will support. Only admin can invoke.

function addToken(ERC20 token) public onlyAdmin

Parameter	Type	Description
`token`	ERC20	ERC20 token contract address

Modifiers: onlyAdmin

Web3 Example:

// DISCLAIMER: Code snippets in this guide are just examples and you
// should always do your own testing. If you have questions, visit our
// https://t.me/KyberDeveloper.

const token = "0xdd974D5C2e2928deA5F71b9825b8b646686BD200"; // KNC
transactionData = ConversionRates.methods.addToken(token).encodeABI();

txReceipt = await web3.eth.sendTransaction({
  from: ADMIN_ADDRESS,
  to: CONVERSION_RATES_ADDRESS,
  data: transactionData
});

`disableTokenTrade`

Disables the reserve token from trades. Only alerter can invoke.

function disableTokenTrade(ERC20 token) public onlyAlerter

Parameter	Type	Description
`token`	ERC20	ERC20 token contract address to be disabled

Modifiers: onlyAlerter

Web3 Example:

// DISCLAIMER: Code snippets in this guide are just examples and you
// should always do your own testing. If you have questions, visit our
// https://t.me/KyberDeveloper.

const token = "0xdd974D5C2e2928deA5F71b9825b8b646686BD200"; // KNC
transactionData = ConversionRates.methods.disableTokenTrade(token).encodeABI();

txReceipt = await web3.eth.sendTransaction({
  from: ALERTER_ADDRESS,
  to: CONVERSION_RATES_ADDRESS,
  data: transactionData
});

`enableTokenTrade`

Enables the reserve token to be traded. Only admin can invoke.

function enableTokenTrade(ERC20 token) public onlyAdmin

Parameter	Type	Description
`token`	ERC20	ERC20 token contract address to be enabled

Modifiers: onlyAdmin

Web3 Example:

// DISCLAIMER: Code snippets in this guide are just examples and you
// should always do your own testing. If you have questions, visit our
// https://t.me/KyberDeveloper.

const token = "0xdd974D5C2e2928deA5F71b9825b8b646686BD200"; // KNC
transactionData = ConversionRates.methods.enableTokenTrade(token).encodeABI();

txReceipt = await web3.eth.sendTransaction({
  from: ADMIN_ADDRESS,
  to: CONVERSION_RATES_ADDRESS,
  data: transactionData
});

`getBasicRate`

To obtain the base buy or sell rate of a token.

function getBasicRate(ERC20 token, bool buy) public view returns (uint)

Parameter	Type	Description
`token`	ERC20	ERC20 token contract address
`buy`	bool	`true` to get the buy rate, otherwise `false` to get the sell rate

Returns:
Base buy or sell rate of a token in wei amount

Web3 Example:

// DISCLAIMER: Code snippets in this guide are just examples and you
// should always do your own testing. If you have questions, visit our
// https://t.me/KyberDeveloper.

const token = "0xdd974D5C2e2928deA5F71b9825b8b646686BD200"; // KNC
const buy = true;
result = await ConversionRates.methods.getBasicRate(token, buy).call();

`getCompactData`

To obtain the basis points (bps) adjustments of a token.

function getCompactData(ERC20 token) public view returns (uint, uint, byte, byte)

Parameter	Type	Description
`token`	ERC20	ERC20 token contract address

Returns:

Array index of token
fieldOffset of token
bps adjustment to base buy rate of token
bps adjustment to base sell rate of token

Web3 Example:

// DISCLAIMER: Code snippets in this guide are just examples and you
// should always do your own testing. If you have questions, visit our
// https://t.me/KyberDeveloper.

const token = "0xdd974D5C2e2928deA5F71b9825b8b646686BD200"; // KNC
const result = await ConversionRates.methods.getCompactData(token).call();

let arrayIndex = result[0];
let fieldOffset = result[1];
let buyRateBPS = result[2];
let sellRateBPS = result[3];

`getListedTokens`

Obtain a list of supported reserve tokens.

function getListedTokens() public view returns (ERC20[])

Web3 Example:

// DISCLAIMER: Code snippets in this guide are just examples and you
// should always do your own testing. If you have questions, visit our
// https://t.me/KyberDeveloper.

result = await ConversionRates.methods.getListedTokens().call();

`getRate`

To obtain the adjusted buy or sell rate of a token.

function getRate(ERC20 token, uint currentBlockNumber, bool buy, uint qty) public view returns (uint)

Parameter	Type	Description
`token`	ERC20	ERC20 token contract address
`currentBlockNumber`	uint	to see if rates' adjustments are applicable on this ETH block number
`buy`	bool	`true` to get the buy rate, otherwise `false` to get the sell rate
`qty`	uint	token quantity

Returns:
Adjusted buy or sell rate of a token in wei amount

Web3 Example:

// DISCLAIMER: Code snippets in this guide are just examples and you
// should always do your own testing. If you have questions, visit our
// https://t.me/KyberDeveloper.

const token = "0xdd974D5C2e2928deA5F71b9825b8b646686BD200"; // KNC
const currentBlockNumber = 5878441;
const buy = true;
const qty = new web3.utils.BN("100000000000000000000");
result = await ConversionRates.methods
  .getRate(token, currentBlockNumber, buy, qty)
  .call();

`getRateUpdateBlock`

To obtain the block number for which the basis points (bps) adjustments are valid from.

function getRateUpdateBlock(ERC20 token) public view returns (uint)

Parameter	Type	Description
`token`	ERC20	ERC20 token contract address

Returns:
Block number for which the basis points (bps) adjustments are valid from

Web3 Example:

// DISCLAIMER: Code snippets in this guide are just examples and you
// should always do your own testing. If you have questions, visit our
// https://t.me/KyberDeveloper.

const token = "0xdd974D5C2e2928deA5F71b9825b8b646686BD200"; // KNC
blockNumber = await ConversionRates.methods.getRateUpdateBlock(token).call();

`getStepFunctionData`

To obtain data of the step function of a token.

function getStepFunctionData(ERC20 token, uint command, uint param) public view returns (int)

Parameter	Type	Description
`token`	ERC20	ERC20 token contract address
`command`	uint	number within `0` to `15` inclusive
`param`	uint	index of step function data to obtain

Returns:
Dependent on command

To determine what inputs to use, it is best to refer the solidity code below.

function getStepFunctionData(ERC20 token, uint command, uint param) public view returns(int) {
        if (command == 0) return int(tokenData[token].buyRateQtyStepFunction.x.length);
        if (command == 1) return tokenData[token].buyRateQtyStepFunction.x[param];
        if (command == 2) return int(tokenData[token].buyRateQtyStepFunction.y.length);
        if (command == 3) return tokenData[token].buyRateQtyStepFunction.y[param];

        if (command == 4) return int(tokenData[token].sellRateQtyStepFunction.x.length);
        if (command == 5) return tokenData[token].sellRateQtyStepFunction.x[param];
        if (command == 6) return int(tokenData[token].sellRateQtyStepFunction.y.length);
        if (command == 7) return tokenData[token].sellRateQtyStepFunction.y[param];

        if (command == 8) return int(tokenData[token].buyRateImbalanceStepFunction.x.length);
        if (command == 9) return tokenData[token].buyRateImbalanceStepFunction.x[param];
        if (command == 10) return int(tokenData[token].buyRateImbalanceStepFunction.y.length);
        if (command == 11) return tokenData[token].buyRateImbalanceStepFunction.y[param];

        if (command == 12) return int(tokenData[token].sellRateImbalanceStepFunction.x.length);
        if (command == 13) return tokenData[token].sellRateImbalanceStepFunction.x[param];
        if (command == 14) return int(tokenData[token].sellRateImbalanceStepFunction.y.length);
        if (command == 15) return tokenData[token].sellRateImbalanceStepFunction.y[param];

        revert();
    }

Web3 Example:

// DISCLAIMER: Code snippets in this guide are just examples and you
// should always do your own testing. If you have questions, visit our
// https://t.me/KyberDeveloper.

result = await ConversionRates.methods
  .getStepFunctionData(
    "0xdd974D5C2e2928deA5F71b9825b8b646686BD200", //ERC20 token: KNC
    0, //uint command
    0 //uint param
  )
  .call();

let buyRateQtyStepFunctionLength = result[0];

`getTokenBasicData`

To obtain the basic information of a token

function getTokenBasicData(ERC20 token) public view returns (bool, bool)

Parameter	Type	Description
`token`	ERC20	Token contract address

Returns:

Whether a token is listed
Whether a token is enabled

Web3 Example:

// DISCLAIMER: Code snippets in this guide are just examples and you
// should always do your own testing. If you have questions, visit our
// https://t.me/KyberDeveloper.

result = await ConversionRates.methods
  .getTokenBasicData(
    "0xdd974D5C2e2928deA5F71b9825b8b646686BD200" //ERC20 token: KNC
  )
  .call();

let tokenListed = result[0];
let tokenEnabled = result[1];

`recordImbalance`

To record the imbalance of a reserve token after a trade was executed. The reserve contract usually invokes this.

function recordImbalance(ERC20 token, int buyAmount, uint rateUpdateBlock, uint currentBlock) public

Parameter	Type	Description
`token`	ERC20	Token contract address
`buyAmount`	int	Token wei amount bought or sold
`rateUpdateBlock`	uint	block number for which the rates are valid from
`currentBlock`	uint	block number for which trade was executed

`setBaseRate`

Set tokens' base buy and sell rates, and optional adjustments to these rates. Only operator can invoke. Refer to this guide on how to use this function.

function setBaseRate(ERC20[] tokens, uint[] baseBuy, uint[] baseSell, bytes14[] buy, bytes14[] sell, uint blockNumber, uint[] indices) public onlyOperator

Parameter	Type	Description
`tokens`	ERC20[]	array of token contract addresses to set the base rates for
`baseBuy`	uint[]	array of token buy rates in wei amount
`baseSell`	uint[]	array of token sell rates in wei amount
`buy`	bytes14[]	compact data representation of basis points (bps) to adjust tokens' buy rates. `1bps = 0.01%`
`sell`	bytes14[]	Compact data representation of basis points (bps) to adjust tokens' sell rates. `1bps = 0.01%`
`blockNumber`	uint	ETH block number for which the adjustments are valid from
`indices`	uint[]	array of indexes to apply bps adjustments on

Modifiers: onlyOperator

Web3 Example:

// DISCLAIMER: Code snippets in this guide are just examples and you
// should always do your own testing. If you have questions, visit our
// https://t.me/KyberDeveloper.

const tokens = [
  "0xdd974D5C2e2928deA5F71b9825b8b646686BD200", // KNC
  "0xd26114cd6EE289AccF82350c8d8487fedB8A0C07" // OMG
];
const baseBuy = [500000000000000000000, 600000000000000000000];
const baseSell = [1820000000000000, 1920000000000000];
const buy = [0x190a];
const sell = [0x190a];
const blockNumber = 5878441;
const indices = [0];

transactionData = ConversionRates.methods
  .setBaseRate(tokens, baseBuy, baseSell, buy, sell, blockNumber, indices)
  .encodeABI();

txReceipt = await web3.eth.sendTransaction({
  from: OPERATOR_ADDRESS,
  to: CONVERSION_RATES_ADDRESS,
  data: transactionData
});

`setCompactData`

Setting minor adjustments in basis points (bps) to tokens' buy and sell rates. 1bps = 0.01%. Only operator can invoke. Refer to this guide on how to use this function.

function setCompactData(bytes14[] buy, bytes14[] sell, uint blockNumber, uint[] indices) public onlyOperator

Parameter	Type	Description
`buy`	bytes14[]	basis points to adjust tokens' buy rates
`sell`	bytes14[]	basis points to adjust tokens' sell rates
`blockNumber`	uint	ETH block number for which the adjustment rates are valid from
`indices`	uint[]	array of indexes to apply the buy / sell rate adjustments on

Modifiers: onlyOperator

Web3 Example:

// DISCLAIMER: Code snippets in this guide are just examples and you
// should always do your own testing. If you have questions, visit our
// https://t.me/KyberDeveloper.

const buy = [0x190ae2];
const sell = [0x39698e];
const blockNumber = 5878441;
const indices = [0];

transactionData = ConversionRates.methods
  .setCompactData(buy, sell, blockNumber, indices)
  .encodeABI();

txReceipt = await web3.eth.sendTransaction({
  from: OPERATOR_ADDRESS,
  to: CONVERSION_RATES_ADDRESS,
  data: transactionData
});

`setQtyStepFunction`

Set adjustments for tokens' buy and sell rates depending on the size of a buy / sell order. Only operator can invoke.

function setQtyStepFunction(ERC20 token, int[] xBuy, int[] yBuy, int[] xSell, int[] ySell) public onlyOperator

Parameter	Type	Description
`token`	ERC20	token contract address to set the base rates for
`xBuy`	int[]	array of buy steps in wei amount
`yBuy`	int[]	impact on buy rate in basis points (bps). `1 bps = 0.01%` Eg. `-30 = -0.3%`
`xSell`	int[]	array of sell steps in wei amount
`ySell`	int[]	impact on sell rate in basis points (bps). `1 bps = 0.01%` Eg. `-30 = -0.3%`

Modifiers: onlyOperator

Buy steps (xBuy) are used to change ASK prices, sell steps (xSell) are used to change BID prices
When yBuy and ySell numbers are non-positive (< 0) they will modify the rate to be lower, meaning the rate will be reduced by the Y-value set in each step. So negative steps mean worse rates for the user. Setting positive step values will give user better rates and could be considered as an advanced method to encourage users to "re balance" the inventory.

Web3 Example:

// DISCLAIMER: Code snippets in this guide are just examples and you
// should always do your own testing. If you have questions, visit our
// https://t.me/KyberDeveloper.

ConversionRates.methods
  .setQtyStepFunction(
    "0xdd974D5C2e2928deA5F71b9825b8b646686BD200", //KNC
    [100000000000000000000, 200000000000000000000, 300000000000000000000, 5000000000000000000000], //uint[] xBuy
    [0, -30, -60, -80], //uint[] yBuy
    [100000000000000000000, 200000000000000000000, 300000000000000000000, 5000000000000000000000], //uint[] xSell
    [0, -30, -60, -80] //uint[] ySell
  )
  .send(
    {
      from: fromAddress
    },
    (err, res) => {
      console.log(`Err: ${err}`);
      console.log(`Res: ${res}`);
    }
  );

`setTokenControlInfo`

Set the minimalRecordResolution, maxPerBlockImbalance and maxTotalImbalance of an ERC20 token

function setTokenControlInfo(ERC20 token, uint minimalRecordResolution, uint maxPerBlockImbalance, uint maxTotalImbalance) public onlyAdmin

Parameter	Type	Description
`token`	ERC20	ERC20 token contract address
`minimalRecordResolution`	uint	minimum denominator in token wei that can be changed
`maxPerBlockImbalance`	uint	maximum wei amount of net absolute (+/-) change for a token in an ethereum block
`maxTotalImbalance`	uint	wei amount of the maximum net token change allowable that happens between 2 price updates

Modifiers: onlyAdmin
Returns:
Data comprising minimalRecordResolution, maxPerBlockImbalance, and maxTotalImbalance

`setImbalanceStepFunction`

Set adjustments for tokens' buy and sell rates depending on the net traded amounts. Only operator can invoke.

function setImbalanceStepFunction(ERC20 token, int[] xBuy, int[] yBuy, int[] xSell, int[] ySell) public onlyOperator

Parameter	Type	Description
`token`	ERC20	token contract address to set the base rates for
`xBuy`	int[]	array of buy steps in wei amount
`yBuy`	int[]	impact on buy rate in basis points (bps). `1 bps = 0.01%` Eg. `-30 = -0.3%`
`xSell`	int[]	array of sell steps in wei amount
`ySell`	int[]	impact on sell rate in basis points (bps). `1 bps = 0.01%` Eg. `-30 = -0.3%`

Modifiers: onlyOperator

Buy steps (xBuy) are used to change ASK prices, sell steps (xSell) are used to change BID prices
yBuy and ySell numbers should always be non-positive (<=0) because the smart contract reduces the output amount by the Y-value set in each step.

Web3 Example:

// DISCLAIMER: Code snippets in this guide are just examples and you
// should always do your own testing. If you have questions, visit our
// https://t.me/KyberDeveloper.

ConversionRates.methods
  .setImbalanceStepFunction(
    "0xdd974D5C2e2928deA5F71b9825b8b646686BD200", //ERC20 token: KNC
    [100000000000000000000, 200000000000000000000, 300000000000000000000, 5000000000000000000000], //uint[] xBuy
    [0, -30, -60, -80], //uint[] yBuy
    [-300000000000000000000, -200000000000000000000, -100000000000000000000, 0], //uint[] xSell
    [-70, -50, -25, 0] //uint[] ySell
  )
  .send(
    {
      from: fromAddress
    },
    (err, res) => {
      console.log(`Err: ${err}`);
      console.log(`Res: ${res}`);
    }
  );

`setValidRateDurationInBlocks`

Set the duration (in blocks) for which the rates will be valid for. Only admin can invoke.

function setValidRateDurationInBlocks(uint duration) public onlyAdmin

Parameter	Type	Description
`duration`	uint	Number of blocks for which the rates will be valid

Modifiers: onlyAdmin

Web3 Example:

// DISCLAIMER: Code snippets in this guide are just examples and you
// should always do your own testing. If you have questions, visit our
// https://t.me/KyberDeveloper.

ConversionRates.methods
  .setValidRateDurationInBlocks(
    24 //uint duration
  )
  .send(
    {
      from: fromAddress
    },
    (err, res) => {
      console.log(`Err: ${err}`);
      console.log(`Res: ${res}`);
    }
  );

`setReserveAddress`

Set / change the reserve contract address. Only admin can invoke.

function setReserveAddress(address reserve) public onlyAdmin

Parameter	Type	Description
`reserve`	address	reserve contract address

Modifiers: onlyAdmin

Web3 Example:

// DISCLAIMER: Code snippets in this guide are just examples and you
// should always do your own testing. If you have questions, visit our
// https://t.me/KyberDeveloper.

ConversionRates.methods
  .setReserveAddress(
    "0x63825c174ab367968EC60f061753D3bbD36A0D8F" //Eg. KyberReserve contract address
  )
  .send(
    {
      from: fromAddress
    },
    (err, res) => {
      console.log(`Err: ${err}`);
      console.log(`Res: ${res}`);
    }
  );