gas

Documentation

Overview

The gas package implements dynamic gas pricing specified in ACP-103: https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/103-dynamic-fees

Index

• Variables
• type Config
• type Dimension
• type Dimensions
  • func (d Dimensions) Add(os ...*Dimensions) (Dimensions, error)
  • func (d Dimensions) Sub(os ...*Dimensions) (Dimensions, error)
  • func (d Dimensions) ToGas(weights Dimensions) (Gas, error)
• type Gas
  • func (g Gas) AddPerSecond(gasPerSecond Gas, seconds uint64) Gas
  • func (g Gas) Cost(price Price) (uint64, error)
  • func (g Gas) SubPerSecond(gasPerSecond Gas, seconds uint64) Gas
• type Price
  • func CalculatePrice(minPrice Price, excess Gas, excessConversionConstant Gas) Price
• type State
  • func (s State) AdvanceTime(maxCapacity Gas, maxPerSecond Gas, targetPerSecond Gas, duration uint64) State
  • func (s State) ConsumeGas(gas Gas) (State, error)

Variables

var ErrInsufficientCapacity = errors.New("insufficient capacity")

Types

type Config

type Config struct {
	// Weights to merge fee dimensions into a single gas value.
	Weights Dimensions `json:"weights"`
	// Maximum amount of gas the chain is allowed to store for future use.
	MaxCapacity Gas `json:"maxCapacity"`
	// Maximum amount of gas the chain is allowed to consume per second.
	MaxPerSecond Gas `json:"maxPerSecond"`
	// Target amount of gas the chain should consume per second to keep the fees
	// stable.
	TargetPerSecond Gas `json:"targetPerSecond"`
	// Minimum price per unit of gas.
	MinPrice Price `json:"minPrice"`
	// Constant used to convert excess gas to a gas price.
	ExcessConversionConstant Gas `json:"excessConversionConstant"`
}

type Dimension

type Dimension uint

const (
	Bandwidth Dimension = iota
	DBRead
	DBWrite // includes deletes
	Compute

	NumDimensions = iota
)

type Dimensions

type Dimensions [NumDimensions]uint64

func (Dimensions) Add

func (d Dimensions) Add(os ...*Dimensions) (Dimensions, error)

Add returns d + sum(os...).

If overflow occurs, an error is returned.

func (Dimensions) Sub

func (d Dimensions) Sub(os ...*Dimensions) (Dimensions, error)

Sub returns d - sum(os...).

If underflow occurs, an error is returned.

func (Dimensions) ToGas

func (d Dimensions) ToGas(weights Dimensions) (Gas, error)

ToGas returns d · weights.

If overflow occurs, an error is returned.

type Gas

type Gas uint64

func (Gas) AddPerSecond

func (g Gas) AddPerSecond(gasPerSecond Gas, seconds uint64) Gas

AddPerSecond returns g + gasPerSecond * seconds.

If overflow would occur, MaxUint64 is returned.

func (Gas) Cost

func (g Gas) Cost(price Price) (uint64, error)

Cost converts the gas to nAVAX based on the price.

If overflow would occur, an error is returned.

func (Gas) SubPerSecond

func (g Gas) SubPerSecond(gasPerSecond Gas, seconds uint64) Gas

SubPerSecond returns g - gasPerSecond * seconds.

If underflow would occur, 0 is returned.

type Price

type Price uint64

func CalculatePrice

func CalculatePrice(
	minPrice Price,
	excess Gas,
	excessConversionConstant Gas,
) Price

CalculatePrice returns the gas price given the minimum gas price, the excess gas, and the excess conversion constant.

It is defined as an approximation of:

minPrice * e^(excess / excessConversionConstant)

This implements the EIP-4844 fake exponential formula:

def fake_exponential(factor: int, numerator: int, denominator: int) -> int:
	i = 1
	output = 0
	numerator_accum = factor * denominator
	while numerator_accum > 0:
		output += numerator_accum
		numerator_accum = (numerator_accum * numerator) // (denominator * i)
		i += 1
	return output // denominator

This implementation is optimized with the knowledge that any value greater than MaxUint64 gets returned as MaxUint64. This means that every intermediate value is guaranteed to be at most MaxUint193. So, we can safely use uint256.Int.

This function does not perform any memory allocations.

type State

type State struct {
	Capacity Gas `serialize:"true" json:"capacity"`
	Excess   Gas `serialize:"true" json:"excess"`
}

func (State) AdvanceTime

func (s State) AdvanceTime(
	maxCapacity Gas,
	maxPerSecond Gas,
	targetPerSecond Gas,
	duration uint64,
) State

AdvanceTime adds maxPerSecond to capacity and subtracts targetPerSecond from excess over the provided duration.

Capacity is capped at maxCapacity. Excess to be removed is capped at excess.

func (State) ConsumeGas

func (s State) ConsumeGas(gas Gas) (State, error)

ConsumeGas removes gas from capacity and adds gas to excess.

If the capacity is insufficient, an error is returned. If the excess would overflow, it is capped at MaxUint64.