Utilities for parsing, validating, manipulating, and displaying Ethereum blocks by date

🏠 Homepage

Install

Npm

npm install eth-block-datetime

Yarn

yarn add eth-block-datetime

Getting Started

import { ethers } from 'ethers'
import EthBlockDatetime from 'eth-block-datetime'

const provider = new ethers.providers.CloudflareProvider()
const ethDatetime = new EthBlockDatetime(
    provider, // [required] rpc provider
)

With block explorer for more efficient queries

const ethDatetime = new EthBlockDatetime(
    provider, // [required] rpc provider
    1, // [optional / required if using blockExplorer client] chainId
    'FREE_ETHERSCAN_APIKEY', // [optional] free or pro etherscan api key corresponding to specified chainId
)

Get block by timestamp

const latestBlock = await ethDatetime.getBlockByTimestamp({ timestamp: 'latest' })
const earliestBlock = await ethDatetime.getBlockByTimestamp({ timestamp: 'earliest' })
const blockFromDateString = await ethDatetime.getBlockByTimestamp({ timestamp: '2016-07-20T13:20:40Z' })
const blockFromDateObject = await ethDatetime.getBlockByTimestamp({ timestamp: new Date('2016-07-20T13:20:40Z') })
const blockDateFromMomentObject = await ethDatetime.getBlockByTimestamp({ timestamp: moment(new Date('2016-07-20T13:20:40Z')) })

Response

{
    datetime: '2021-10-03T16:09:28Z',
    number: 13347220,
    timestamp: 1633277292
}

Get blocks by range

let start = new Date()
start = new Date(startTime.setDate(startTime.getDate() - 7))
const block = await ethDatetime.getBlocksByRange({
    start,
    interval: 'days',
})

Response

[
  {
    datetime: '2021-09-26T16:09:28Z',
    number: 13302379,
    timestamp: 1632672551
  },
  {
    datetime: '2021-09-27T16:09:28Z',
    number: 13308801,
    timestamp: 1632758964
  },
  // ... rest of blocks
]

Usage

Providers

EthersJS

import { ethers } from 'ethers'

Public cloudflare ETH RPC

const provider = new ethers.providers.CloudflareProvider() // to use public cloudflare ETH RPC

Pass in Infura / Alchemy or other Node-as-a-service Eth RPC provider

const provider = new ethers.providers.JsonRpcProvider(process.env.ETH_RPC_URL) // to use supplied RPC url

Web3

import Web3 from 'web3'

Pass in injected browser web3 object

const provider = new Web3(window.ethereum) // to use supplied RPC url

Pass in Infura / Alchemy or other Node-as-a-service Eth RPC provider

const provider = new Web3(new Web3.providers.HttpProvider(process.env.ETH_RPC_URL)) // to use supplied RPC url

Examples

Get block by timestamp

const block = await ethDatetime.getBlockByTimestamp({
    timestamp: 'earliest', // [required] options: earliest, latest, timestamp string, momentJs date object, or javascript date object
    closest: 'after', // [optional] after (default), before [estimation method for block closest to timestamp]
    blockTime: 15, // [optional] override average blocktime for finding closest block
    useBlockExplorer: true, // [optional] true (default if chainId & api key is given)
    includeFullBlock: false, // [optiona] false (default) [specify if full block data should be returned]
})

Block

{
    datetime: '2021-10-03T16:09:28Z',
    number: 13347220,
    timestamp: 1633277292
}

Get blocks by range

let start = new Date()
let end = new Date()
start = new Date(startTime.setDate(startTime.getDate() - 7))
const block = await ethDatetime.getBlocksByRange({
    start, // [required] options: earliest, latest, timestamp string, momentJs date object, or javascript date object
    end, // [optional] latest block (default) options: earliest, latest, timestamp string, momentJs date object, or javascript date object
    interval: 'days', // [required] // seconds, minutes, hours, days, weeks, months, years
    duration: 1, // [optional] 1 (default)
    closest: 'after', // [optional] after (default), before [estimation method for block closest to timestamp] 
    includeFullBlock: false, // [optiona] false (default) [specify if full block data should be returned]
})

Blocks

[
      {
        datetime: '2021-09-26T16:09:28Z',
        number: 13302379,
        timestamp: 1632672551
      },
      {
        datetime: '2021-09-27T16:09:28Z',
        number: 13308801,
        timestamp: 1632758964
      },
      {
        datetime: '2021-09-28T16:09:28Z',
        number: 13315225,
        timestamp: 1632845341
      },
      {
        datetime: '2021-09-29T16:09:28Z',
        number: 13321658,
        timestamp: 1632931728
      },
      {
        datetime: '2021-09-30T16:09:28Z',
        number: 13328031,
        timestamp: 1633018153
      },
      {
        datetime: '2021-10-01T16:09:28Z',
        number: 13334484,
        timestamp: 1633104558
      },
      {
        datetime: '2021-10-02T16:09:28Z',
        number: 13340842,
        timestamp: 1633190949
      },
      {
        datetime: '2021-10-03T16:09:28Z',
        number: 13347220,
        timestamp: 1633277292
      }
]

Run tests

yarn test

Author

Modified and updated https://github.com/monosux/ethereum-block-by-date to add additional customization and options, dynamic blocktime calculations, and integration with public blockexplorers

👤 matmertz25

• Github: @matmertz25

🤝 Contributing

Contributions, issues and feature requests are welcome!Feel free to check issues page. You can also take a look at the contributing guide.

Show your support

Give a ⭐️ if this project helped you!

📝 License

Copyright © 2021 matmertz25. This project is MIT licensed.

This README was generated with ❤️ by readme-md-generator