# Cosmos delegator tools, back end application structure

## Gatherer of lost blocks

The most tricky part of the validator stat is to get lost blocks information.
Watcher and Gatherer used to watch new blocks and obtain information of lost blocks.


### Watcher

Watcher task is to query current chain height and add new blocks heights to Gatherer queue. Also, watcher deletes obsolete stats, older than *maxStatsBlocks*.

### Gatherer

Gatherer task is to query Gaia daemon and write information on the lost block for a certain height.

| Method | Gaia daemon API request URL | Description |
| ------------------------ | --------------------------- | ---------------------------------------------------------------------------- |
| GetCommitInfo(height) | "/commit?height=" + height | Qeury for commit info on selected height, with list of validators signatures |
| GetValidatorsSet(height) | "/validatorsets/" + height | Qeury for validator list on selected height |

Gatherer saves info for each validator on a given height. Gatherer creates record only if the validator is in validators set, in_block is 1 when validator actually were in the block, and 0 if validator skips block validation.

INSERT INTO stats (validator_id, in_block, height) VALUES ($1, $2, $3)

## Tables and data structure

SQL tables created automaticly from structures (if not exist) by Gorm AutoMigrate feature.

type Stat struct {
	ValidatorID int `gorm:"index:idx_validator_height"`
	Height      int `gorm:"index:idx_validator_height"`
	InBlock     int `gorm:"type:smallint"`
}

type Validator struct {
	ID          int    `gorm:"AUTO_INCREMENT;primary_key"`
	ConsAddress string `gorm:"unique_index"`
	ConsPubKey  string `gorm:"unique_index"`
}

Gatherer collects validators from Cosmos network and saves validators to DB:

ConsAddress - Consensus address in Cosmos network
ConsPubKey - Consensus public key in Cosmos network

Stats used to track lost blocks by validators:

Height - block height in Cosmos network blockchain.
InBlock - is validator participated in block, on not.

## API endpoint

Backend have one endpoint:

GET /stats/:delegator

Example of usage:
https://documenter.getpostman.com/view/6638692/T1Dwcttc?version=latest

You could find other obsolete endpoints in code, they were abandoned and are subject to deletion.

## Requests to Gaia used to compose stats

Struct Client in /stats/gaia folder responsible for all communications with Gaia CLI and Daemon.

For more info on Gaia, please check Cosmos SKD docs (https://docs.cosmos.network/master/modules/) and Gaia API (https://cosmos.network/rpc/)

| Method | Gaia API request URL | Description |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| GetRewardsInfo(delegatorAddress) | "/distribution/delegators/" + address + "/rewards" | Get the sum of all the rewards earned by delegations by a single delegator |
| GetAccountInfo(delegatorAddress) | "/auth/accounts/" + address | |
| GetDelegationsInfo(delegatorAddress) | "/staking/delegators/" + address + "/delegations" | Get all delegations from a delegator |
| GetDelegatorUnbonding(delegatorAddress) | "/staking/delegators/" + delegatorAddress + "/unbonding_delegations" | Get all unbonding delegations from a delegator |
| GetValidatorInfo(validatorAddress) | "/staking/validators/" + validatorAddr | Query the information from a single validator |
| GetDelegationsInfoWithValidator(selfDelegatedAddress, validatorAddress) | "/staking/delegators/" + delegatorAddress + "/delegations/" + validatorAddress | Query a validator that a delegator is bonded to |
| GetDelegationsInfoWithValidator(delegatorAddress, validatorAddress) | "/staking/delegators/" + delegatorAddress + "/delegations/" + validatorAddress | Query the current delegation between a delegator and a validator |
| GetAnnualProvision() | "/minting/annual-provisions" | Current minting annual provisions value |

## Exchange rate

Exchange rate ATOM to USD queried from https://api.coingecko.com/api/v3/coins/cosmos/tickers. Queried data cached for *rateExpirationTime*.