fee

Documentation

Overview

The fee 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 GasPrice) (uint64, error)
  • func (g Gas) SubPerSecond(gasPerSecond Gas, seconds uint64) Gas
• type GasPrice
  • func (g GasPrice) MulExp(excess Gas, excessConversionConstant Gas) GasPrice
• type State
  • func (s State) AdvanceTime(maxGasCapacity Gas, maxGasPerSecond Gas, targetGasPerSecond Gas, ...) 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.
	MaxGasCapacity Gas `json:"maxGasCapacity"`
	// Maximum amount of gas the chain is allowed to consume per second.
	MaxGasPerSecond Gas `json:"maxGasPerSecond"`
	// Target amount of gas the chain should consume per second to keep the fees
	// stable.
	TargetGasPerSecond Gas `json:"targetGasPerSecond"`
	// Minimum price per unit of gas.
	MinGasPrice GasPrice `json:"minGasPrice"`
	// 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 GasPrice) (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 GasPrice

type GasPrice uint64

func (GasPrice) MulExp

func (g GasPrice) MulExp(
	excess Gas,
	excessConversionConstant Gas,
) GasPrice

MulExp returns an approximation of g * 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(
	maxGasCapacity Gas,
	maxGasPerSecond Gas,
	targetGasPerSecond Gas,
	duration uint64,
) State

AdvanceTime adds maxGasPerSecond to capacity and subtracts targetGasPerSecond from excess over the provided duration.

Capacity is capped at maxGasCapacity. 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.