near-indexer

README

near-indexer

Data indexer and API service for Near protocol networks.

Requirements

• PostgreSQL 10.x+
• Go 1.14+

Installation

Please see the sections below for all available methods of installation.

Binary Releases

See Github Releases page for details.

Docker

Pull the official Docker image:

docker pull figmentnetworks/near-indexer

Golang

go get -u github.com/figment-networks/near-indexer

Usage

$ ./near-indexer --help

Usage of ./near-indexer:
  -cmd string
    	Command to run
  -config string
    	Path to config
  -v	Show application version

Executing commands:

near-indexer -c path/to/config.json -cmd=COMMAND

Available commands:

Name	Description
status	Print out current indexer and node status
migrate	Perform database migration
sync	Run a one-time indexer sync (for testing purposes)
worker	Start the indexer sync worker
server	Start the indexer API server
reset	Reset the database

Configuration

You can configure the service using a config file or environment variables.

Config File

Example:

{
  "app_env": "production",
  "rpc_endpoints": "http://YOUR_NODE_RPC_IP:PORT,http://YOUR_NODE_RPC_IP2:PORT2",
  "server_addr": "127.0.0.1",
  "server_port": 8081,
  "database_url": "postgres://user:pass@host/dbname?sslmode=mode",
  "sync_interval": "500ms",
  "cleanup_interval": "10m",
  "cleanup_threshold": 3600,
  "start_height": 0,
}

Environment Variables

Name	Description	Default Value
APP_ENV	Application environment	development
DATABASE_URL	PostgreSQL database URL	REQUIRED
NEAR_RPC_ENDPOINTS	Near RPC endpoints	REQUIRED
START_HEIGHT	Initial start height	optional, will use genesis if 0
SERVER_ADDR	Server listen addr	0.0.0.0
SERVER_PORT	Server listen port	8081
SYNC_INTERVAL	Data sync interval	500ms
CLEANUP_INTERVAL	Data cleanup interval	10m
CLEANUP_THRESHOLD	Max number of heights	3600
DEBUG	Turn on debugging mode	false
DATASTORE_GRPC_ADDR	Datastore service address	``

Running Application

Once you have created a database and specified all configuration options, you need to migrate the database. You can do that by running the command below:

near-indexer -config path/to/config.json -cmd=migrate

Perform the indexer check:

near-indexer -config path/to/config.josn -cmd=status

Perform the initial sync:

near-indexer -config path/to/config.josn -cmd=sync

If previous steps did not produce any errors you can start the indexer worker:

near-indexer -config path/to/config.json -cmd=worker

Start the API server:

near-indexer -config path/to/config.json -cmd=server

API Reference

Method	Path	Description
GET	/	See all available endpoints
GET	/health	Healthcheck endpoint
GET	/status	App version info and sync status
GET	/height	Current indexed blockchain height
GET	/block	Get latest block
GET	/blocks	Blocks search
GET	/blocks/:hash	Block details by ID or Hash
GET	/block_stats	Block times stats for a time bucket
GET	/block_times	Block average times
GET	/block_times_interval	Block creation stats
GET	/epochs	Get list of epochs
GET	/epochs/:id	Epoch details by ID
GET	/validators	List of chain validators
GET	/validators/:id/epochs	Validator Epochs performance by ID
GET	/validators/:id/events	Validator Events by ID
GET	/delegators/:id/rewards	Delegator rewards by ID
GET	/delegators	Delegator search
GET	/transactions	List of transactions
GET	/transactions/:id	Get transaction details
GET	/accounts/:id	Account details by ID or Key
GET	/delegations/:id	Account delegations by ID
GET	/events	List of Events

License

Apache License v2.0

How do we calculate rewards?

We trigger calculations when the current block is the first block of an epoch, since rewards are distributed at the end of each epoch.

The algorithm to calculate the rewards :

   if current block is first block of an epoch
        for each delegators -> dlg
            reward : staked balanced of dlg at current block - staked balanced of dlg at the first block of the previous epoch
            reward : reward + (sum of all unstake events)
            reward : reward - (sum of all stake events)

where unstake events are: unstake and unstake_all whereas stake events are stake, stake_all and deposit_and_stake