ConversionRates

You are referring to the Legacy version of KyberSwap docs.

For the most updated information, please refer to:

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​

<AUTOGENERATED_TABLE_OF_CONTENTS>

REFERENCE​

Structs​

StepFunction​

PropertyTypeDescription

x

int[]

Quantity for each step. Includes previous steps

y

int[]

Rate change per quantity step in bps

TokenData​

PropertyTypeDescription

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:

  1. Array index of token

  2. fieldOffset of token

  3. bps adjustment to base buy rate of token

  4. 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:

  1. Whether a token is listed

  2. 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}`);
    },
  );
PreviousKyberReserveNextLiquidityConversionRates

Last updated

#477: Elastic fee tier and token launches

Change request updated