KyberDeveloper · Powering Liquidity for the Ecosystem

KyberDeveloper · Powering Liquidity for the Ecosystem

  • Home
  • Integrations
  • Reserves
  • KyberPRO
  • Addresses
  • API/ABI
  • Trade Debugger
  • Tracker
  • GitHub

›Core Smart Contracts

Getting Started

  • Introduction

RESTful API

  • RESTful API Overview
  • RESTful API

Widgets

  • Widgets Overview
  • KyberWidget
  • Sign In Widget

Core Smart Contracts

  • IKyberNetworkProxy
  • KyberNetworkProxy
  • IKyberNetwork
  • ISimpleKyberProxy
  • IKyberMatchingEngine
  • KyberMatchingEngine
  • IKyberHint
  • KyberHintHandler
  • IKyberFeeHandler
  • KyberFeeHandler
  • IKyberStaking
  • KyberStaking
  • IKyberDao
  • KyberDao
  • IKyberStorage
  • KyberStorage
  • IKyberHistory
  • KyberHistory
  • IKyberReserve
  • KyberReserve
  • ConversionRates
  • LiquidityConversionRates
  • IEpochUtils
  • EpochUtils

Contract ABIs

  • ABIs

Plugins

  • Plugins Overview
  • WooCommerce Plugin

Code Snippets

  • Token Quantity Conversion

Misc Contracts

  • KyberNetwork
  • ConversionRatesInterface
  • OrderbookReserveInterface
  • PermissionGroups
  • SanityRates
  • SanityRatesInterface
  • Withdrawable

ConversionRates

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

PropertyTypeDescription
xint[]Quantity for each step. Includes previous steps
yint[]Rate change per quantity step in bps


TokenData

PropertyTypeDescription
listedbooltrue if added to reserve, false otherwise
enabledbooltrue if trades are enabled, false otherwise
compactDataArrayIndexuintToken position in compact data
compactDataFieldIndexuintToken position in compact data
baseBuyRateuintBase buy rate of token
baseSellRateuintBase sell rate of token
buyRateQtyStepFunctionStepFunctionsource ERC20 token balance of user
sellRateQtyStepFunctionStepFunctiondestination ERC20 token balance of user
buyRateImbalanceStepFunctionStepFunctionsource ERC20 token balance of user
sellRateImbalanceStepFunctionStepFunctiondestination 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

ParameterTypeDescription
_adminaddressadmin'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

ParameterTypeDescription
tokenERC20ERC20 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

ParameterTypeDescription
tokenERC20ERC20 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

ParameterTypeDescription
tokenERC20ERC20 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)

ParameterTypeDescription
tokenERC20ERC20 token contract address
buybooltrue 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)

ParameterTypeDescription
tokenERC20ERC20 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)

ParameterTypeDescription
tokenERC20ERC20 token contract address
currentBlockNumberuintto see if rates' adjustments are applicable on this ETH block number
buybooltrue to get the buy rate, otherwise false to get the sell rate
qtyuinttoken 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)

ParameterTypeDescription
tokenERC20ERC20 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)

ParameterTypeDescription
tokenERC20ERC20 token contract address
commanduintnumber within 0 to 15 inclusive
paramuintindex 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)

ParameterTypeDescription
tokenERC20Token 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

ParameterTypeDescription
tokenERC20Token contract address
buyAmountintToken wei amount bought or sold
rateUpdateBlockuintblock number for which the rates are valid from
currentBlockuintblock 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

ParameterTypeDescription
tokensERC20[]array of token contract addresses to set the base rates for
baseBuyuint[]array of token buy rates in wei amount
baseSelluint[]array of token sell rates in wei amount
buybytes14[]compact data representation of basis points (bps) to adjust tokens' buy rates. 1bps = 0.01%
sellbytes14[]Compact data representation of basis points (bps) to adjust tokens' sell rates. 1bps = 0.01%
blockNumberuintETH block number for which the adjustments are valid from
indicesuint[]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

ParameterTypeDescription
buybytes14[]basis points to adjust tokens' buy rates
sellbytes14[]basis points to adjust tokens' sell rates
blockNumberuintETH block number for which the adjustment rates are valid from
indicesuint[]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

ParameterTypeDescription
tokenERC20token contract address to set the base rates for
xBuyint[]array of buy steps in wei amount
yBuyint[]impact on buy rate in basis points (bps). 1 bps = 0.01% Eg. -30 = -0.3%
xSellint[]array of sell steps in wei amount
ySellint[]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

ParameterTypeDescription
tokenERC20ERC20 token contract address
minimalRecordResolutionuintminimum denominator in token wei that can be changed
maxPerBlockImbalanceuintmaximum wei amount of net absolute (+/-) change for a token in an ethereum block
maxTotalImbalanceuintwei 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

ParameterTypeDescription
tokenERC20token contract address to set the base rates for
xBuyint[]array of buy steps in wei amount
yBuyint[]impact on buy rate in basis points (bps). 1 bps = 0.01% Eg. -30 = -0.3%
xSellint[]array of sell steps in wei amount
ySellint[]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

ParameterTypeDescription
durationuintNumber 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

ParameterTypeDescription
reserveaddressreserve 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}`);
    }
  );


← KyberReserveLiquidityConversionRates →
  • INDEX
  • REFERENCE
    • Structs
    • StepFunction
    • TokenData
    • Functions
    • ConversionRates
    • addToken
    • disableTokenTrade
    • enableTokenTrade
    • getBasicRate
    • getCompactData
    • getListedTokens
    • getRate
    • getRateUpdateBlock
    • getStepFunctionData
    • getTokenBasicData
    • recordImbalance
    • setBaseRate
    • setCompactData
    • setQtyStepFunction
    • setTokenControlInfo
    • setImbalanceStepFunction
    • setValidRateDurationInBlocks
    • setReserveAddress
KyberDeveloper · Powering Liquidity for the Ecosystem
EssentialsGetting StartedDesign PrinciplesProtocol OverviewSmart Contract Architecture
IntegrationsDAppsVendorsWalletsPlatform Fees
ReservesFed PriceAutomated Price
© 2019 Kyber Network. All rights reserved.
Follow us on Facebook
Follow us on Twitter
Follow us on Github
Follow us on Reddit
Join our Telegram group
Subscribe to our Youtube channel
Read our blog on Medium