txutil

Documentation

Overview

Package txutil provides transaction lifecycle utilities for Ethereum/FEVM transactions.

Key components:

• NonceManager: thread-safe nonce tracking with failure recovery
• Gas estimation: configurable gas limits with FEVM workarounds
• Receipt polling: exponential backoff receipt confirmation

Index

• Variables
• func EstimateGasWithBuffer(ctx context.Context, client GasEstimator, msg ethereum.CallMsg, ...) (uint64, error)
• func IsGasError(err error) bool
• func IsNonceError(err error) bool
• func IsRetryableRPCError(err error) bool
• func SuggestGasPriceWithMultiplier(ctx context.Context, client GasEstimator, multiplier float64) (*big.Int, error)
• func SuggestGasTipCapWithMultiplier(ctx context.Context, client GasEstimator, multiplier float64) (*big.Int, error)
• func WaitForConfirmation(ctx context.Context, client ReceiptClient, txHash common.Hash, ...) (*types.Receipt, error)
• func WaitForReceipt(ctx context.Context, client ReceiptClient, txHash common.Hash, ...) (*types.Receipt, error)
• func WaitForReceiptWithConfig(ctx context.Context, client ReceiptClient, txHash common.Hash, ...) (*types.Receipt, error)
• type GasEstimator
• type NonceManager
  • func NewNonceManager(client NonceProvider, address common.Address) *NonceManager
  • func (m *NonceManager) Acquire(ctx context.Context) (nonce uint64, release func(), err error)
• type NonceProvider
• type ReceiptClient
• type ReceiptWaitConfig
  • func DefaultReceiptWaitConfig() ReceiptWaitConfig

Variables

var (
	// ErrReceiptTimeout is returned when waiting for a transaction receipt
	// exceeds the configured timeout.
	ErrReceiptTimeout = errors.New("timeout waiting for transaction receipt")

	// ErrReceiptRPCFailure is returned when too many consecutive RPC errors
	// occur while polling for a receipt.
	ErrReceiptRPCFailure = errors.New("receipt fetch failed due to repeated RPC errors")

	// ErrTxFailed is returned when a transaction is mined but its receipt
	// status is not successful (reverted or out-of-gas on-chain).
	ErrTxFailed = errors.New("transaction failed on-chain")

	// ErrNonRetryable wraps errors that should not be retried by the caller.
	ErrNonRetryable = errors.New("non-retryable error")
)

Sentinel errors returned from the txutil package.

Functions

func EstimateGasWithBuffer

func EstimateGasWithBuffer(ctx context.Context, client GasEstimator, msg ethereum.CallMsg, bufferPercent int) (uint64, error)

EstimateGasWithBuffer estimates gas and adds a percentage safety buffer. Filecoin's FEVM commonly requires a buffer because estimation is not a tight upper bound.

bufferPercent must be in [0, 1000]; 0 disables the buffer.

func IsGasError

func IsGasError(err error) bool

IsGasError reports whether err relates to gas or fee pricing.

func IsNonceError

func IsNonceError(err error) bool

IsNonceError reports whether err relates to nonce sequencing (too low/high/invalid).

func IsRetryableRPCError

func IsRetryableRPCError(err error) bool

IsRetryableRPCError reports whether err is a transient RPC condition that should be retried (connection drops, timeouts). Context errors and nil are never retryable.

func SuggestGasPriceWithMultiplier

func SuggestGasPriceWithMultiplier(ctx context.Context, client GasEstimator, multiplier float64) (*big.Int, error)

SuggestGasPriceWithMultiplier returns the suggested legacy gas price multiplied by the given float. multiplier<=1 returns the unmodified price. Multiplication rounds down to the nearest wei.

func SuggestGasTipCapWithMultiplier

func SuggestGasTipCapWithMultiplier(ctx context.Context, client GasEstimator, multiplier float64) (*big.Int, error)

SuggestGasTipCapWithMultiplier returns the suggested EIP-1559 tip cap multiplied by the given float.

func WaitForConfirmation

func WaitForConfirmation(ctx context.Context, client ReceiptClient, txHash common.Hash, confirmations uint64) (*types.Receipt, error)

WaitForConfirmation waits until the transaction is mined and its inclusion block has accumulated the requested number of confirmations.

func WaitForReceipt

func WaitForReceipt(ctx context.Context, client ReceiptClient, txHash common.Hash, timeout time.Duration) (*types.Receipt, error)

WaitForReceipt polls TransactionReceipt until the transaction is mined, returning an error if the receipt indicates failure. A zero timeout uses DefaultReceiptWaitConfig.

func WaitForReceiptWithConfig

func WaitForReceiptWithConfig(ctx context.Context, client ReceiptClient, txHash common.Hash, cfg ReceiptWaitConfig, confirmations uint64) (*types.Receipt, error)

WaitForReceiptWithConfig gives full control over polling parameters and required confirmations.

Types

type GasEstimator

type GasEstimator interface {
	EstimateGas(ctx context.Context, msg ethereum.CallMsg) (uint64, error)
	SuggestGasPrice(ctx context.Context) (*big.Int, error)
	SuggestGasTipCap(ctx context.Context) (*big.Int, error)
}

GasEstimator abstracts the gas-estimation methods of an Ethereum client.

type NonceManager

type NonceManager struct {
	// contains filtered or unexported fields
}

NonceManager serializes nonce acquisition for an EOA. Each Acquire call locks the manager, fetches PendingNonceAt(pending) from the network, and returns both the nonce and a release function. The caller MUST invoke release exactly once after either broadcasting the transaction (so that subsequent Acquire calls observe the bumped pending count) or abandoning the attempt. Until release is called no other goroutine can acquire a nonce.

Each transaction round-trips to the node for its nonce, with no client-side cache. The added serialization is the cost of guaranteeing monotonically increasing nonces across concurrent goroutines.

func NewNonceManager

func NewNonceManager(client NonceProvider, address common.Address) *NonceManager

NewNonceManager constructs a NonceManager for the given address.

func (*NonceManager) Acquire

func (m *NonceManager) Acquire(ctx context.Context) (nonce uint64, release func(), err error)

Acquire locks the manager and returns the next pending nonce together with a release function. The caller MUST call release exactly once after either broadcasting the transaction or abandoning it. release is idempotent. On error, the returned release is a no-op.

Acquire blocks until it can take the manager mutex; ctx only governs the PendingNonceAt RPC call. If ctx is cancelled while another goroutine holds the lock, this call will continue to wait for the lock — this matches the semantics of stdlib sync.Mutex.

type NonceProvider

type NonceProvider interface {
	PendingNonceAt(ctx context.Context, account common.Address) (uint64, error)
}

NonceProvider abstracts the subset of an Ethereum client used by NonceManager. It is satisfied by *ethclient.Client and can be faked in tests.

type ReceiptClient

type ReceiptClient interface {
	TransactionReceipt(ctx context.Context, txHash common.Hash) (*types.Receipt, error)
	BlockNumber(ctx context.Context) (uint64, error)
}

ReceiptClient abstracts the subset of ethclient used by receipt helpers.

type ReceiptWaitConfig

type ReceiptWaitConfig struct {
	Timeout              time.Duration // total timeout for the whole wait; 0 = 5 minutes
	PollInterval         time.Duration // polling cadence; 0 = 2 seconds
	MaxConsecutiveErrors int           // RPC errors in a row before giving up; 0 = 5
}

ReceiptWaitConfig configures polling behavior.

func DefaultReceiptWaitConfig

func DefaultReceiptWaitConfig() ReceiptWaitConfig

DefaultReceiptWaitConfig returns a conservative default suitable for FEVM.