gas

README

Module: go-gas

A simple Golang client for the ETH Gas Station API.

It provides a simple set of methods for loading appropriate gas prices for submitting Ethereum transactions in base units.

Built only on the standard library, it has no external dependencies other than stretchr/testify which is used for testing.

Usage

Install

The go-gas module supports Go modules. Add to your project with the following command.

go get -u github.com/hrharder/go-gas

Usage

Package gas provides two main ways to fetch a gas price from the ETH Gas Station API.

1. Fetch the current recommended price for a given priority level with a new API call each time
   • Use gas.SuggestGasPrice for a specific priority level
   • Use gas.SuggestFastGasPrice to fetch the fast priority level (no arguments)
2. Create a new GasPriceSuggester which maintains a cache of results for a user-defined duration
   • Use gas.NewGasPriceSuggester and specify a max result age
   • Use the returned function to fetch new gas prices, or use the cache based on how old the results are

Example

package main

import (
    "fmt"
    "log"
    "time"

    "github.com/hrharder/go-gas"
)

func main() {
    // get a gas price in base units with one of the exported priorities (fast, fastest, safeLow, average)
    fastestGasPrice, err := gas.SuggestGasPrice(gas.GasPriorityFastest)
    if err != nil {
        log.Fatal(err)
    }

    // convenience wrapper for getting the fast gas price
    fastGasPrice, err := gas.SuggestFastGasPrice()
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(fastestGasPrice)
    fmt.Println(fastGasPrice)

    // alternatively, use the NewGasPriceSuggester which maintains a cache of results until they are older than max age
    suggestGasPrice, err := gas.NewGasPriceSuggester(5 * time.Minute)
    if err != nil {
        log.Fatal(err)
    }

    fastGasPriceFromCache, err := suggestGasPrice(gas.GasPriorityFast)
    if err != nil {
        return nil, err
    }

    // after 5 minutes, the cache will be invalidated and new results will be fetched
    time.Sleep(5 * time.Minute)
    fasGasPriceFromAPI, err := suggestGasPrice(gas.GasPriorityFast)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(fastGasPriceFromCache)
    fmt.Println(fasGasPriceFromAPI)
}

Documentation

Overview

Package gas provides a client for the ETH Gas Station API and convenience functions.

It includes type aliases for each priority level supported by ETH Gas Station, functions to get the lastest price from the API, and a closure that can be used to cache results for a user-defined period of time.

Index

• Constants
• func SuggestFastGasPrice() (*big.Int, error)
• func SuggestGasPrice(priority GasPriority) (*big.Int, error)
• type GasPriceSuggester
  • func NewGasPriceSuggester(maxResultAge time.Duration) (GasPriceSuggester, error)
• type GasPriority

Constants

const (
	// GasPriorityFast is the recommended gas price for a transaction to be mined in less than 2 minutes.
	GasPriorityFast = GasPriority("fast")

	// GasPriorityFastest is the recommended gas price for a transaction to be mined in less than 30 seconds.
	GasPriorityFastest = GasPriority("fastest")

	// GasPrioritySafeLow is the recommended cheapest gas price for a transaction to be mined in less than 30 minutes.
	GasPrioritySafeLow = GasPriority("safeLow")

	// GasPriorityAverage is the recommended average gas price for a transaction to be mined in less than 5 minutes.
	GasPriorityAverage = GasPriority("average")
)

const ETHGasStationURL = "https://ethgasstation.info/json/ethgasAPI.json"

ETHGasStationURL is the API URL for the ETH Gas Station API.

More information available at https://ethgasstation.info

Functions

func SuggestFastGasPrice

func SuggestFastGasPrice() (*big.Int, error)

SuggestFastGasPrice is a helper method that calls SuggestGasPrice with GasPriorityFast

It always makes a new call to the ETH Gas Station API. Use NewGasPriceSuggester to leverage cached results.

func SuggestGasPrice

func SuggestGasPrice(priority GasPriority) (*big.Int, error)

SuggestGasPrice returns a suggested gas price value in wei (base units) for timely transaction execution. It always makes a new call to the ETH Gas Station API. Use NewGasPriceSuggester to leverage cached results.

The returned price depends on the priority specified, and supports all priorities supported by the ETH Gas Station API.

Types

type GasPriceSuggester

type GasPriceSuggester func(GasPriority) (*big.Int, error)

GasPriceSuggester is type alias for a function that returns a reccomended gas price in base units for a given priority level.

func NewGasPriceSuggester

func NewGasPriceSuggester(maxResultAge time.Duration) (GasPriceSuggester, error)

NewGasPriceSuggester returns a function that can be used to either load a new gas price response, or use a cached response if it is within the age range defined by maxResultAge.

The returned function loads from the cache or pulls a new response if the stored result is older than maxResultAge.

type GasPriority

type GasPriority string

GasPriority is a type alias for a string, with supported priorities included in this package.