Skip to content

fastnear/neardata-server

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

60 Commits
openapi
openapi
 
 
src
src
 
 
static
static
 
 
.gitignore
.gitignore
 
 
Cargo.toml
Cargo.toml
 
 
README.md
README.md
 
 

Repository files navigation

NEAR Data Server by FASTNEAR

Introduction

The server provides indexed data for NEAR Protocol blockchain.

It's a simple and free alternative to the publicly available NEAR Lake Framework by NEAR Protocol.

FASTNEAR provides servers for both mainnet and testnet:

OpenAPI Generation

The checked-in openapi/openapi.yaml file is generated from small typed DTOs plus a Rust-owned operation registry.

cargo run --features openapi --bin generate-openapi
cargo run --features openapi --bin generate-openapi -- --check

The docs pipeline is:

neardata-server generator -> checked-in openapi/openapi.yaml -> mike-docs split + sync -> builder-docs direct docs runtime

API

The server provides the following endpoints:

  • /v0/first_block - Redirects to the first block after genesis.
  • /v0/block/:block_height - Get a finalized block by the block height in a JSON format.
  • /v0/block_opt/:block_height - Get an optimistic block by the block height in a JSON format.
  • /v0/last_block/final - Redirects to the latest finalized block.
  • /v0/last_block/optimistic - Redirects to the latest optimistic block.

Recommended: Rust Crate

The best option to consume Neardata is using the Rust crate: fastnear-neardata-fetcher. Source code is available at github.com/fastnear/libs/tree/main/neardata-fetcher.

Usage

The server is free to use and doesn't require any authentication. The bandwidth is limited to 1 Gbps, so you may experience throttling if there are too many parallel requests. We use caching to reduce the load on the server and improve the response time, but it would more likely to be useful for the latest data.

Rate Limits

The current rate limit is 180 requests per minute per IP.

To increase your rate limits, get a subscription at https://fastnear.com/.

Authentication

To authenticate your requests with a FastNEAR Subscription API key, attach the following query string to the URL:

?apiKey={API_KEY}

For example:

https://mainnet.neardata.xyz/v0/block/98765432?apiKey=YOUR_API_KEY

Invalid API keys may return 401 Unauthorized before the request reaches the neardata application itself.

Note: Authentication using the Authorization: Bearer header requires you to manually handle redirects, since the redirect URL will not pass the header through and the redirected request will not be authenticated.

To index historical, you may read data in a sequential manner, starting from the block you need or from the genesis block (9820210 for mainnet) and moving forward up to the final block.

If you want to subscribe to the latest data, start from the latest finalized block and poll the server for the new blocks incrementing the block height by one, making sure you wait for the response.

/v0/first_block

Redirects to the first block after genesis.

The block is guaranteed to exist and will be returned immediately.

Example:

/v0/block/:block_height

Returns the block by block height.

  • If the block doesn't exist it returns null.
  • If the block is not produced yet, but close to the current finalized block, the server will wait for the block to be produced and return it.
  • Depending on deployment topology, this route may redirect to the host that owns the canonical archive range for the requested block.
  • The difference from NEAR Lake data is each block is served as a single JSON object, instead of the block and shards. Another benefit, is we include the tx_hash for every receipt in the receipt_execution_outcomes. The tx_hash is the hash of the transaction that produced the receipt.

Example:

v0/block/:block_height/headers

Returns a smaller part from the response including only the block object from the JSON document.

Example:

v0/block/:block_height/chunk/:shard_id

Returns a smaller part from the response including only the chunk of the requested shard_id part of the JSON object.

Example:

v0/block/:block_height/shard/:shard_id

Returns a smaller part from the response including only the shard of the requested shard_id part of the JSON object.

Example:

/v0/block_opt/:block_height

Returns the optimistic block by block height.

If the deployment cannot serve the requested optimistic block directly, it may redirect to a canonical finalized or archive URL.

/v0/last_block/final

Redirects to the latest finalized block.

The block is guaranteed to exist and will be returned immediately.

Example:

/v0/last_block/optimistic

Redirects to the latest optimistic block.

The block is guaranteed to exist and will be returned immediately.

Example:

Running locally

The server is built with Rust and uses the Actix Web framework.

To run the server locally, you need to have Rust installed. You can install Rust by running the following command:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

After installing Rust, you can clone the repository and run the server:

PORT=8080 \
CHAIN_ID=mainnet \
REDIS_URL=redis://localhost:6379 \
READ_PATH=./data \
SAVE_EVERY_N=1000 \
GENESIS_BLOCK_HEIGHT=9820210 \
cargo run

Environment variables

  • PORT - The port the server will listen on.
  • CHAIN_ID - The chain ID, either mainnet or testnet.
  • REDIS_URL - The Redis URL for caching.
  • READ_PATH - The path to the directory with the block files.
  • SAVE_EVERY_N - The number of blocks to save in the cache before saving to the disk.
  • GENESIS_BLOCK_HEIGHT - The block height of the genesis block.

About

Serves historical NEAR data with some caching

Resources

Readme
Activity
Custom properties

Stars

19 stars

Watchers

1 watching

Forks

1 fork
Report repository

Releases

Packages

Used by

Contributors

Languages