Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kybernetwork/workshop

Repository for KyberDeveloper workshops
https://github.com/kybernetwork/workshop

Last synced: about 2 months ago
JSON representation

Repository for KyberDeveloper workshops

Host: GitHub
URL: https://github.com/kybernetwork/workshop
Owner: KyberNetwork
License: mit
Created: 2018-09-07T10:54:32.000Z (over 6 years ago)
Default Branch: master
Last Pushed: 2022-12-10T16:26:11.000Z (about 2 years ago)
Last Synced: 2023-02-28T21:01:11.156Z (almost 2 years ago)
Language: Solidity
Size: 6.14 MB
Stars: 22
Watchers: 4
Forks: 58
Open Issues: 15
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

### ![#f03c15](https://placehold.it/15/f03c15/000000?text=+) ALL CODE EXAMPLES IN THIS WORKSHOP HAVE NOT BEEN AUDITED AND SHOULD NOT BE USED IN PRODUCTION. IF SO, IT IS DONE AT YOUR OWN RISK! ![#f03c15](https://placehold.it/15/f03c15/000000?text=+)

# Kyber Workshop

This repository is used as complement to the workshops conducted by Kyber. It can also be used to quickly test the Kyber contracts in your local machine.

## Useful Links

1. [Sourcing On-Chain Liquidity for Your DeFi App](https://docs.google.com/presentation/d/1MdkwuSMWA_GctUFYwYEGC9hSHNbOx5ejWMzUazlZSy8/)
2. [Introduction to Kyber Network](https://docs.google.com/presentation/d/1dEbLyUSd7tLoMatOw5Km0xw3XofWT0EwDNO7K6BUWRU/)
3. [Introduction to Reserves](https://docs.google.com/presentation/d/1VOcL0UEEVFUeuR9a8rYNd4N3lW1hgmbXow3WDVcTj5A/)
4. [KyberDeveloper Portal](http://developer.kyber.network/)
5. [KyberDeveloper Telegram](https://t.me/KyberDeveloper/)
6. [Workshop Repository](https://github.com/KyberNetwork/workshop/)
7. Ropsten ETH Faucets
- https://faucet.kyber.network
- https://faucet.metamask.io
- https://faucet.ropsten.be
8. [Ropsten KyberSwap](https://ropsten.kyber.network/)

## What is Kyber?

Kyber is a widely used on-chain protocol that makes accessing liquidity simple for users, DApps and financial applications. The protocol has powered decentralised token swaps on popular wallets like MyEtherWallet and imToken, decentralised token payments (users can pay in any supported ERC20 token) in popular DApps like Etheremon and Peepeth and providing an on-chain liquidity source for decentralised financial applications like MelonPort, Set Protocol, b0x and many more.

Kyber protocol brings token inventories and prices on-chain, hence allowing developers to directly embed value exchanges into their smart contracts without any technical or security overhead. This allows for:

- Instant confirmation. A transaction happens with instant confirmation if it's sent from on-chain entities like smart contracts. Otherwise, once the transaction is included on the blockchain, the execution triggered by the transaction is immediately confirmed.

- Operation certainty. There is no transactional risk. Users know the rate and how much liquidity is available before they commit their transaction. There is also no settlement uncertainty or counterparty risk.

- Global and diverse pool of different tokens. Kyber welcomes token holders to contribute their token to the liquidity pool. By having their token made available to the liquidity pool, the token will be available in all services integrated with Kyber.

## Prerequisites

1. Node and NPM latest LTS versions. Download from [nodejs.org](https://nodejs.org/en/download/)

2. Ganache

Install the Ganache AppImage by downloading here https://truffleframework.com/ganache.
To use the provided Ganache snapshot, install `ganache-cli`.

```
sudo npm install -g ganache-cli
```

3. Truffle

Install the latest Truffle v5.

```
sudo npm install -g truffle@latest
```

Truffle v5.0 is needed in order to take advantage of new features, such as using async/await in the migration scripts. You can read more about the new features in the [Truffle release page](https://github.com/trufflesuite/truffle/releases/tag/v5.0.0)

4. Install the rest of the NPM packages

```
npm install
```

## Workshop Repository

### Overview

workshop

├── config

│   ├── network.json

│   └── tokens.json

├── contracts

│   ├── ConversionRatesInterface.sol

│   ├── ConversionRates.sol

│   ├── ERC20Interface.sol

│   ├── examples

│   │   ├── SwapEtherToToken.sol

│   │   ├── SwapTokenToEther.sol

│   │   └── SwapTokenToToken.sol

│   │   └── Trade.sol

│   ├── ExpectedRateInterface.sol

│   ├── ExpectedRate.sol

│   ├── FeeBurnerInterface.sol

│   ├── FeeBurner.sol

│   ├── KyberAutomatedReserve.sol

│   ├── KyberNetworkInterface.sol

│   ├── KyberNetworkProxyInterface.sol

│   ├── KyberNetworkProxy.sol

│   ├── KyberNetwork.sol

│   ├── KyberOrderbookReserve.sol

│   ├── KyberReserveInterface.sol

│   ├── KyberReserve.sol

│   ├── LiquidityConversionRates.sol

│   ├── LiquidityFormula.sol

│   ├── Migrations.sol

│   ├── mockTokens

│   │   ├── KyberGenesisToken.sol

│   │   ├── KyberNetworkCrystal.sol

│   │   ├── Mana.sol

│   │   ├── OmiseGo.sol

│   │   ├── Polymath.sol

│   │   ├── Salt.sol

│   │   ├── Status.sol

│   │   └── Zilliqa.sol

│   ├── PermissionGroups.sol

│   ├── permissionless

│   │   ├── OrderbookReserveInterface.sol

│   │   ├── OrderbookReserve.sol

│   │   ├── OrderIdManager.sol

│   │   ├── OrderListFactoryInterface.sol

│   │   ├── OrderListFactory.sol

│   │   ├── OrderListInterface.sol

│   │   ├── OrderList.sol

│   │   └── PermissionlessOrderbookReserveLister.sol

│   ├── SanityRatesInterface.sol

│   ├── SanityRates.sol

│   ├── SimpleNetworkInterface.sol

│   ├── Utils2.sol

│   ├── Utils.sol

│   ├── VolumeImbalanceRecorder.sol

│   ├── WhiteListInterface.sol

│   ├── WhiteList.sol

│   └── Withdrawable.sol

├── db

├── examples

│   ├── solidity

│   │   ├── SwapEtherToToken.sol -> ../../contracts/examples/SwapEtherToToken.sol

│   │   ├── SwapTokenToEther.sol -> ../../contracts/examples/SwapTokenToEther.sol

│   │   └── SwapTokenToToken.sol -> ../../contracts/examples/SwapTokenToToken.sol

│   │   └── Trade.sol -> ../../contracts/examples/Trade.sol

│   ├── truffle

│   │   ├── getExpectedRate.js

│   │   ├── swapEtherToToken.js

│   │   ├── swapTokenToEther.js

│   │   ├── swapTokenToToken.js

│   │   └── trade.js

│   └── web3

│   ├── abi

│   │   ├── KyberNetworkProxy.abi

│   │   ├── KNC.abi

│   │   ├── OMG.abi

│   │   ├── MANA.abi

│   │   ├── SALT.abi

│   │   └── ZIL.abi

│   ├── getExpectedRate.js

│   ├── swapEtherToToken.js

│   ├── swapTokenToEther.js

│   └── swapTokenToToken.js

├── LICENSE

├── migrations

│   ├── 1_initial_migration.js

│   ├── 2_deploy_tokens.js

│   ├── 3_deploy_contracts.js

│   ├── 4_setup_permissions.js

│   ├── 5_setup_KyberNetworkProxy.js

│   ├── 6_setup_KyberReserve.js

│   ├── 7_setup_KyberAutomatedReserve.js

│   ├── 8_setup_KyberOrderbookReserve.js

│   ├── 9_setup_FeeBurner.js

│   ├── 10_setup_ExpectedRate.js

│   ├── 11_setup_ConversionRates.js

│   ├── 12_setup_LiquidityConversionRates.js

│   ├── 13_setup_SanityRates.js

│   ├── 14_setup_WhiteList.js

│   ├── 15_setup_KyberNetwork.js

│   ├── 16_add_PermissionlessOrderbookReserve.js

│   ├── 17_transfer_tokens.js

│   └── 18_deployment_summary.js

├── package.json

├── README.md

├── scripts

│   ├── get_liquidity_params.py

│   └── liquidity_input_params.json

└── truffle.js

### Directory Details

**config** - contains JSON files that hold configuration details of the Kyber contracts used for migrations

**contracts** - contains all the Kyber contracts, plus some mock tokens and solidity examples for testing

**examples** - contains truffle and web3 example scripts to interact with Kyber's smart contracts, and also contains solidity examples for Kyber contract interactions

**migrations** - contains the truffle migration scripts to deploy and setup the Kyber contracts in a test environment

## Interacting with the Kyber contracts locally

### 1A. Run Ganache with local snapshot

A Ganache snapshot has already been pre-made with the Kyber contracts deployed. You can immediately interact with the contracts without having to do migrations. The snapshot is stored in `db` folder.

We use the mnemonic `gesture rather obey video awake genuine patient base soon parrot upset lounge` for the accounts. The user wallet (`0x47a793D7D0AA5727095c3Fe132a6c1A46804c8D2`) already contains some ETH and test ERC20 tokens.

**NOTE:** The mnemonic provided is used only for testing. DO NOT use the accounts generated for your own personal use in mainnet, as you can potentially lose those funds.

To run the snapshot locally, run the command:

```sh
cd /workshop
ganache-cli --db db --accounts 10 --defaultBalanceEther 1000 --mnemonic 'gesture rather obey video awake genuine patient base soon parrot upset lounge' --networkId 5777 --debug
```

### 1B. Run Ganache and deploy the Kyber contracts from scratch

If you wish to deploy the Kyber contracts yourself, you can run the following commands:

Run ganache-cli in one terminal session

```
ganache-cli --accounts 10 --defaultBalanceEther 1000 --mnemonic 'gesture rather obey video awake genuine patient base soon parrot upset lounge' --networkId 5777 --debug
```

In a new terminal session, connect to the ganache network, and run the truffle migration scripts

```
truffle migrate --network development
```

### 2. Running the example scripts

You can directly interact with the Kyber contracts on the Ganache network. We have provided some example scripts in the `example` directory.

For the Truffle examples:

```
truffle exec examples/truffle/
```

e.g.

```
truffle exec examples/truffle/swapEtherToToken.js
```

For the Web3 examples:

```
cd examples/web3
node <SCRIPT>
```

e.g.

```
cd examples/web3/
node swapEtherToToken.js
```

For the Solidity examples, they are already deployed in the Ganache network using the Truffle migration scripts. You can interact with the Solidity examples using `truffle console`, or write your own Truffle/Web3 scripts to interact with the Solidity example contracts.

### Ganache network details

# Network

development

# Permissions

# Wallets

# Tokens

# Contracts

**NOTE:** The `KyberReserve` and `KyberAutomatedReserve` as well as the `KyberOrderbookReserve` and `OrderbookReserve` are the same contracts. A duplicate was made as a workaround due to a limitation of Truffle where only one instance of a contract can be migrated. Kyber has three types of reserves, the Fed Price Reserve, Automated Price Reserve, and Orderbook Reserve, which you can read more about [here](https://developer.kyber.network/docs/ReservesUseCase/).

## How to add a new ERC20 token with rates for initial migration

### Fed Price Reserve

#### 1. Create your ERC20 token contract

Create your ERC20 token contract in `contracts/mockTokens`. You can duplicate any of the existing mock tokens and modify the token name, symbol, and total supply

#### 2. Set the minimalRecordResolution, maxPerBlockImbalance, and maxTotalImbalance of each defined token in the tokens.json config file

In `config/tokens.json`, under the `FedPriceReserve` section, define the `minimalRecordResolution`, `maxPerBlockImbalance` and `maxTotalImbalance` of each defined token (replace NEW with the token symbol).

These 3 fields are explained below:

| Input Field | Explanation | Example |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `minimalRecordResolution` | Per trade imbalance values are recorded and stored in the contract. Since this storage of data is an expensive operation, the data is squeezed into one bytes32 object. To prevent overflow while squeezing data, a resolution unit exists. Recommended value is the token wei equivalent of \$0.0001. | Assume 1 OMG = $1. $0.0001 = 0.0001 OMG Now OMG has 18 decimals, so `0.0001*(10**18) = 1000000000000` |
| `maxPerBlockImbalance` | The maximum wei amount of net absolute (+/-) change for a token in an ethereum block. We recommend this value to be larger than the maximum allowed tradeable token amount for a whitelisted user. Suppose we want the maximum change in 1 block to be 439.79 OMG, then we use `439.79 * (10 ** 18) = 439790000000000000000` | Suppose we have 2 users Alice and Bob. Alice tries to buy 200 OMG and Bob tries to buy 300 OMG. Assuming both transactions are included in the same block and Alice's transaction gets processed first, Bob's transaction will **fail** because the resulting net change of -500 OMG would exceed the limit of 439.79 OMG. However, if Bob decides to sell instead of buy, then the net change becomes +100 OMG, which means an additional 539.79 OMG can be bought, or 339.79 OMG sold. |
| `maxTotalImbalance` | Has to be `>= maxPerBlockImbalance`. Represents the amount in wei for the net token change that happens between 2 price updates. This number is reset everytime `setBaseRate()` is called in `ConversionRates.sol`. This acts as a safeguard measure to prevent reserve depletion from unexpected events between price updates. | If we want the maximum total imbalance to be 922.36 OMG, we will use: `922.36 * (10 ** 18) = 922360000000000000000` |

Next, add the desired conversion rates of each defined token with respect to ETH, defined with `baseBuy` and `baseSell`. Conversion rate sets the basic rate per token, and is set separately for buy and sell values.

For `bytes14Buy` and `bytes14Sell`, for simplicity, assume that we want to modify the base buy rates. The logic for modifying base sell rates is the same.

Suppose the reserve supports 3 tokens: DAI, BAT, and DGX.
We want to make the following modifications to their base buy rates:

- +2.5% (+25 pts) to DAI_BASE_BUY_RATE
- +1% (+10 pts) to BAT_BASE_BUY_RATE
- -3% (-30 pts) to DGX_BASE_BUY_RATE

Note:

One pt here means a 0.1% change, as compared to basis points used in step functions where 1 basis point = 0.01%.
The range which compact data can handle is from -12.8% to 12.7%.
This gives us the buy array [25,10,-30]. Encoding this to hex yields [0x190ae2]. But for simplicity sake, we can set this to 0x0000000000000000000000000000.

```json
"FedPriceReserve": {
"NEW": {
"minimalRecordResolution" : "1000000000000000",
"maxPerBlockImbalance" : "9078768104330450960384",
"maxTotalImbalance" : "57896044618658097711785492504343953926634992332820282019728792003956564819968",
"baseBuy": "549000000000000000000",
"baseSell": "1813123931381047",
"bytes14Buy": "0x0000000000000000000000000000",
"bytes14Sell": "0x0000000000000000000000000000"
}
}
```

Lastly, add the sanity rate for each token you define. The sanity rates defined protect your reserve from large inconsistencies between the sanity rates and the actual rates.

You should have the final definition of a token below:

You can read more about these fields in the [Fed Price Reserve guide](https://developer.kyber.network/docs/FedPriceReservesGuide/).

#### 3. Edit `ConversionRates` in `network.json`
```
"ConversionRates": {
"validDurationBlock": 1000000000,
"indices": [0, 0, 0]
},
```
Edit the `indices` to have the same number of zeroes as the number of tokens. For instance, if the reserve will support 6 tokens, then the `ConversionRates` section should be:
```
"ConversionRates": {
"validDurationBlock": 1000000000,
"indices": [0, 0, 0, 0, 0, 0]
},
```

#### 4. Run the Truffle migration

With Ganache running, execute:

```
truffle migrate --network development --reset
```

### Automated Price Reserve

#### 1. Create your ERC20 token contract

Create your ERC20 token contract in `contracts/mockTokens`. You can duplicate any of the existing mock tokens and modify the token name, symbol, and total supply.

#### 2. Defining the liquidity parameters of the token

Modify the file `config/tokens.json` and add the new token section (replace NEW with the token symbol) for the different properties.

```json
{
"AutomatedReserve": {
"NEW": {
"_rInFp": "7696581394",
"_pMinInFp": "27487790",
"_numFpBits": "40",
"_maxCapBuyInWei": "5000000000000000000",
"_maxCapSellInWei": "5000000000000000000",
"_feeInBps": "25",
"_maxTokenToEthRateInPrecision": "100000000000000",
"_minTokenToEthRateInPrecision": "25000000000000",
"Ether": "100",
"Tokens": "2000000"
}
}
}
```

**AutomatedReserve.Token**

| Property | Explanation |
| :-----------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------: |
| `_rInFp` | r in formula precision, calculated as r \* InFp. |
| `_pMinInFp` | Minimum supported price factor in formula precision, calculated as min price factor _ initial price of your token _ InFp. |
| `_numFpBits` | The formula precision in bits, therefore for formula precision of 2^40, \_numFpBits is 40. |
| `_maxCapBuyInWei` | The allowed quantity for one BUY trade in ETH. |
| `_maxCapSellInWei` | The allowed quantity for one SELL trade in ETH. |
| `_feeInBps` | The fee amount in basis points (1 bp = 0.01%) that should be calculated in the price. |
| `_maxTokenToEthRateInPrecision` | The maximum allowed price taking into consideration the maximum supported price factor and must be in 10^18. |
| `_minTokenToEthRateInPrecision` | The minimum allowed price taking into consideration the minimum supported price factor and must be in 10^18. |
| `Ether` | The amount of initial ETH inventory to be deposited into the automated reserve. It is recommended to allocate at least 100 ETH. |
| `Tokens` | The amount of initial token inventory to be deposited into the automated reserve. It is recommended to allocate at least 100 ETH worth of tokens. |

The function that will be invoked to set liquidity parameters is:

function **setLiquidityParams**(uint \_rInFp, uint \_pMinInFp, uint \_numFpBits, uint \_maxCapBuyInWei, uint \_maxCapSellInWei, uint \_feeInBps, uint \_maxTokenToEthRateInPrecision, uint \_minTokenToEthRateInPrecision) public onlyAdmin

The reserve manager needs to only decide on the initial liquidity parameters of the automated reserve. Specifically, the following information need to be considered and to calculate the parameters above:

1. Liquidity Rate
2. Initial Token Price
3. Initial Ether Amount
4. Initial Token Amount
5. Minimum and Maximum Supported Price Factor
6. Maximum Buy and Maximum Sell Amount in a Trade
7. Fee Percentage

There are several things to take note of in the list of parameters.

First, notice that some parameters will have the **InFp** suffix. InFp refers to formula precision. While this is configurable, 2^40 is the recommended value.

Second, **r** is liquidity the rate in basis points or units of 100 which the price should move each time the ETH/token inventory changes in 1 ETH worth of quantity. For an r of 0.01, the price will move 1%. r is calculated taking into account the amount of initial ETH and tokens deposited into the contract, and the desired minimum/maximum price factor ratio. A smaller r also means more ETH and token inventory is needed to facilitate the liquidity.

For the **minimum/maximum supported price factor ratio**, it is recommended to start with a ratio of 0.5:2.0. This indicates that the inventory will suffice for up to 100% increase or 50% decrease in token price with respect to ETH.

##### Example

Now, Let's assume we want to list a token with the following considerations:

1. Liquidity Rate – 0.007 (0.7%)
2. Initial Token Price – 1 token = 0.00005 ETH
3. Initial Ether Amount – 100 ETH
4. Initial Token Amount – 2,000,000 tokens (100 ETH worth)
5. Minimum (pMin) and Maximum (pMax) Supported Price Factor – 0.5:2.0
6. Maximum Buy and Maximum Sell Amount in a Trade – 5 ETH max buy and sell cap
7. Fee Percentage – 0.25%

Below, we will calculate the different parameters.

#### Using get_liquidity_params.py Python script

A Python script, located in `scripts/get_liquidity_params.py` in the `smart-contracts` repository, will help you calculate the liquidity parameters. Edit the input file `liquidity_input_params.json`, and specify the inputs similar to the considerations in the example above.

```json
{
"liquidity_rate": 0.007,
"initial_ether_amount": 100.0,
"initial_token_amount": 2000000,
"initial_price": 0.00005,
"min_supported_price_factor": 0.5,
"max_supported_price_factor": 2.0,
"max_tx_buy_amount_eth": 5.0,
"max_tx_sell_amount_eth": 5.0,
"fee_percent": 0.25,
"formula_precision_bits": 40
}
```

Please note that the `formula_precision_bits` refers to `_numFpBits`, which the recommended value is 40.

Afterwards, just execute the Python script, using the following command:

```sh
python3 get_liquidity_params.py --input liquidity_input_params.json --get params
```

It should give the following output:

```sh
_rInFp: 7696581394
_pMinInFp: 27487790
_numFpBits: 40
_maxCapBuyInWei: 5000000000000000000
_maxCapSellInWei: 5000000000000000000
_feeInBps: 25
_maxTokenToEthRateInPrecision: 100000000000000
_minTokenToEthRateInPrecision: 25000000000000
```

#### 3. Run the Truffle migration

With Ganache running, execute:

```
truffle migrate --network development --reset
```

### Orderbook Reserve

#### 1. Create your ERC20 token contract

Create your ERC20 token contract in `contracts/mockTokens`. You can duplicate any of the existing mock tokens and modify the token name, symbol, and total supply.

#### 2. Set the price of USD per ETH

In `config/network.json`, under the `MockMedianizer` section, add the USD price per ETH.

```json
"MockMedianizer": {
"DollarPerETH": 150
}
```

#### 3. Set the minimum USD price for new orders, maximum orders to traverse per trade, and fees

In `config/tokens.json`, under the `PermissionedOrderbookReserve` section, add the new token section (replace NEW with the token symbol) for the different properties.

```json
"PermissionedOrderbookReserve": {
"NEW": {
"minNewOrderUsd": 1000,
"maxOrdersPerTrade": 5,
"burnFeeBps": 25,
(...)
}
}
```

These 3 fields are explained below:

| Property | Explanation |
| :-----------------: | :--------------------------------------------------------------------------------------: |
| `minNewOrderUsd` | The minimum limit order size in USD. Creating orders below this limit will be reverted. |
| `maxOrdersPerTrade` | The maximum number of orders to traverse (and therefore use) to fulfill 1 trade request. |
| `burnFeeBps` | The fee amount in basis points (1 bp = 0.01%) that should be calculated in the price. |

#### 3. Set the initial limit order to the Orderbook Reserve

In `config/tokens.json`, under the `PermissionedOrderbookReserve` section, modify the new token section (replace NEW with the token symbol), as specified in Step 2 above, and indicate the different properties.

```json
"PermissionedOrderbookReserve": {
"NEW": {
(...)
"KNCStake": "1000",
"ETHDeposit": "25",
"TokenDeposit": "150000",
"ETHSell": "10",
"TokenBuy": "12450",
"ETHBuy": "10",
"TokenSell": "12400"
}
}
```

These 7 fields are explained below:

#### 4. Run the Truffle migration

With Ganache running, execute:

```
truffle migrate --network development --reset
```

## Hackathon Bounties

For our hackathon bounties, please visit https://kyber.network/hack.