ASGARDEX-MIDGARD
The ASGARDEX Midgard package is a Midgard verification module used by ASGARDEX
clients. It provides an easy way to get a valid, but random base url of Midgards API by proofing active THORNodes.
It will do all the hard work behind the scenes by challenging active THORNodes. If Midgard cannot get consensus on data, it will blacklist bad nodes and try again. This is because of THORChain's trust model - it does not trust any Node, instead it verifies them by comparing against each other. It assumes that no more than 1/3rd of THORNodes are malicious and colluding.
Midgard gets the list of active nodes by querying the seed service: testnet-seed.thorchain.info
(testnet), chaosnet-seed.thorchain.info
(chaosnet) or seed.thorchain.info
(mainnet), which crawls THORChain for active node IPs.
Note: The Seed Service is now the weak link and must be semi-trusted (however it can be independently verified by auditing the nodes manually). In future the Seed Service will move to an Ethereum Smart Contract and Midgard will use Web3 to retrieve seed nodes IPs. This will allow the service to be fully trustless.
Installation
- Install
@thorchain/asgardex-midgard
from npm
yarn add @thorchain/asgardex-midgard
Usage
Basic usage
Whenever your application needs to ask Midgard API for data, call midgard()
before. It will return a valid, but random base url for Midgard API.
Please note: That's the only way to send a transaction to a proofed THORNode at any time.
import midgard from '@thorchain/asgardex-midgard'
const baseUrl = await midgard()
const baseUrl = await midgard('testnet')
const baseUrl = await midgard('chaosnet')
const baseUrl = await midgard('mainnet')
const data = await fetch(`${baseUrl}/v1/pools`)
Side note: Behind the scenes Midgard
is memorizing a proofed list of baseUrl
s to avoid increasing requests. Midgard
will recycle its cache every hour. If you want to get a "fresh", not cached baseUrl
, set the second parameter to true
.
const baseUrl = await midgard('testnet', true)
const baseUrl = await midgard('chaosnet', true)
const baseUrl = await midgard('mainnet', true)
Examples
Testnet
ts-node examples/testnet.ts
testnet: http://136.243.227.164:8080
Chaosnet
ts-node examples/chaosnet.ts
chaosnet: http://54.255.107.211:8080
Mainnet
ts-node examples/mainnet.ts
Error: Empty IP list: [object Object]
That might be helpful for error handling, see next chapter "Error handling".
Error handling
In same cases a cached baseUrl
can be invalid if a node goes offline for any reason. In this case you can force Midgard
to return a non-cached baseUrl
to retry this request, but using another baseUrl
.
const baseUrl = await midgard('testnet')
try {
const data = await fetch(`${baseUrl}/v1/pools`)
...
} catch (error) {
retry()
}
const retry = () => {
const anotherBaseUrl = await midgard('testnet', true)
const data = await fetch(`${baseUrl}/v1/pools`)
}
Please note: Use a non-cached baseUrl
as few as possible to avoid to increase requests made by Midgard
.
Development
Build
yarn build
Tests
yarn test