@hexcrypto/hexdex-oracles v0.4.0

Uniswap Exchange Wrapper

Exchange wrapper for connecting hYhX contracts to Uniswap Exchange on-chain.

Testing

Tests fork mainnet contracts for use locally. This makes testing already deployed contracts and infrastructure against new contracts locally incredibly easy.

Setup for this is done in the test/helpers/setup.ts file.

Tests use jest and ethers along with the local blockchain setup in the setup.ts file. Typescript preprocessing for tests is done using ts-jest.

To run tests simply run yarn test

For development, yarn test:watch will watch contract and tests for changes and rerun the tests.

Test configuration files can be found at:

• jest.config.js (basic configuration for jest and typescript)
• jest.setup.js (adds a longer timeout to tests)

Linting

Relevant linting files can be found at the following locations:

• .eslintrs.js
• .pretierrc.js
• tsconfig.json

Smart Contracts

Linting is done using ethlint.

Run yarn lint:sol to lint the contracts.

Typescript

Linting is performed through eslint along with prettier. Typescript is linted though plugins for eslint. See package.json for more info on plugins.

Building the Contracts

Contract compilation is done using waffle. Waffle is not used for tests.

To compile, simply run yarn compile:sol.

For a nice development flow, yarn compile:sol:watch can be used for automatic recompiling.

Deploying Contracts

Ensure that the correct .env variables are set before deploying. See .env.example for details.

Deployed contracts are saved to deployments.json at the root of the repo. This is committed to source.

The GAS_PRICE_GWEI .env variable is optional. If it is not supplied, an estimate will be fetched from the network. This is NOT recommended when deploying to mainnet.

For a list of already deployed contracts, see deployments.json at the root of the repo.

Private Network (dev AKA ganache)

For testing migrations locally, a local blockchain forked off of mainnet can be used:

yarn start:devchain

Deployment can then be run using:

yarn deploy:contracts

Public Networks (mainnet, kovan, etc.)

Simply run:

yarn deploy:contracts

Everything should work fine as long as .env vars were set correctly.

Contract Layout

Contract directory is as follows:

contracts
├── IncentivizedOracle.sol
├── interfaces
│   ├── IIncentivizedOracle.sol
│   ├── IMakerOracle.sol
│   ├── IMintableToken.sol
│   └── IPriceOracle.sol
├── lib
│   └── Monetary.sol
├── MintableToken.sol
└── UniswapV2OracleAdapter.sol

base

This repo and it's contracts have two purposes; to provide an on chain oracle for hexEth/ethHex prices and to provide an adapter contract for use with the dydx protocol.

The main contract is IncentivizedOracle.sol. This contract mints tokens to the updating user in return for updating the oracle. It is a hybrid of the two example oracle implementations provided by uniswap. It is hoped that this will be a long running oracle which can be used for other purposes in the community.

UniswapV2OracleAdapter.sol is an oracle adapter for UniswapV2 prices. This contract formats prices from IncentivizedOracle.sol to a format which the dydx protocol can use.

lib

The Monetary.sol lib is used for bridging UniswapV2OracleAdapter.sol to the dydx protocol which uses special monetary units.

interfaces

These are various interfacing contracts which help facilitate communication to/between contracts in/relating to this repo.

Related Oracles in the dydx Protocol Ecosystem

In order to understand how the IncentivizedOracle and UniswapV2OracleAdapter contracts work, one should have at least a brief understanding on how other related oracles work. Some of these are not directly used in this repo, but exist in the dydx protocol repo.

Medianizer

This contract/concept is from makerdao, it takes price from 14 difference anonymous sources and picks the median. The median is chosen so that price manipulation or flash crashes of single sources will not affect the price. Because, once again, the median is being taken from the reported prices. For more information, see here.

dYdX Related

These contracts may not be in this repo, but they are related in a way... will move later...

DaiPriceOracle

This uses a similar median like the Medianizer contract uses. However, it uses only 3 sources (expected, oasis dex, uniswapv1) in that order... This means it will take whichever price is closer to 1 dollar.

The price of eth for dai is gotten from the Medianizer contract in order to get prices of dai for eth from uniswap and oasis.

There is a permissioned poker which can poke the oracle into updating the price stored on the contract. The methods for getting this are public so prices seem to be possible to get without updating storage. However bounded prices would not work in this case.

UsdcPriceOracle

This just returns 1 dollar in dydx Monetary.Price format (as u256). Don't know the way usdc works, it supposedly has no fluctation. read up on it later...

WethPriceOracle

This contract simply takes the price returned from medianizer maker dao oracle and converts the amount to the dydx Monetary.Price format for 1 dollar (as u256).

Useful Information on Cross Rates

Cross rates are needed in order to calculate the dydxDollar/heart price needed by dydx protocol. Below are a few articles and a quick introduction to how this is calculated.

• cross rates
• cross rates (mid-point & bid/ask)

Example for getting cross rates hex/eth eth/hex

prices gotten from coingecko & coinbase for example purposes prices do not line up exactly due to getting eth/usd prices from coinbase

usd/eth 263.43
eth/usd 0.0037960748585962115

hex/eth 62267.27993295558
eth/hex 0.000016133507

usd/hex 0.00425
hex/usd 235.2941176470588

usd   eth   usd
--- x --- = ---
eth   hex   hex

// eth cancels out above
263.43 x 0.000016133507 = 0.00425004974901

eth   hex   hex
--- x --- = ---
usd   eth   usd

// eth cancels out above
0.0037960748585962115 x 0.000016133507 = 236.37125586666505

Legal

All Rights Reserved