Documentation
¶
Overview ¶
Package txutil provides transaction lifecycle utilities for Ethereum/FEVM transactions.
Key components:
- NonceManager: cancellable serialization of nonce allocation and submission
- Gas estimation: configurable gas limits with FEVM workarounds
- Receipt polling: bounded RPC retries and block confirmation checks
Index ¶
- Variables
- func AwaitReceipt(ctx context.Context, client ReceiptClient, txHash common.Hash, ...) (*types.Receipt, error)
- func EstimateGasWithBuffer(ctx context.Context, client GasEstimator, msg ethereum.CallMsg, ...) (uint64, error)
- func HasConfirmations(blockNumber *big.Int, head, confirmations uint64) bool
- func IsGasError(err error) bool
- func IsNonceError(err error) bool
- func IsRetryableHTTPStatus(status int) bool
- func IsRetryableRPCError(err error) bool
- func PrepareTransactOpts(opts *bind.TransactOpts, from common.Address, ctx context.Context, ...) (*bind.TransactOpts, error)
- func SignAndSend(ctx context.Context, sender TransactionSender, opts *bind.TransactOpts, ...) (*types.Transaction, error)
- 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 ValidateUint256(v *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
- type NonceProvider
- type ReceiptClient
- type ReceiptWaitConfig
- type TransactionSender
Constants ¶
This section is empty.
Variables ¶
var ( // ErrReceiptTimeout is returned when waiting for a transaction receipt // or its parent context reaches its deadline. ErrReceiptTimeout = errors.New("timeout waiting for transaction receipt") // ErrReceiptRPCFailure is returned for a non-retryable RPC error or when // the consecutive RPC error budget is exhausted 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 AwaitReceipt ¶ added in v0.7.1
func AwaitReceipt(ctx context.Context, client ReceiptClient, txHash common.Hash, timeout time.Duration, confirmations uint64) (*types.Receipt, error)
AwaitReceipt waits up to timeout for the requested confirmations. A non-positive timeout selects the default. A receipt is returned only after it reaches the requested confirmations, including alongside ErrTxFailed.
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 HasConfirmations ¶ added in v0.7.0
HasConfirmations reports whether the inclusion block has the requested depth. The inclusion block counts as the first confirmation. A zero requirement does not require a block number or head.
func IsGasError ¶
IsGasError reports whether err relates to gas or fee pricing.
func IsNonceError ¶
IsNonceError reports whether err relates to nonce sequencing (too low/high/invalid).
func IsRetryableHTTPStatus ¶ added in v0.7.1
IsRetryableHTTPStatus reports whether an RPC HTTP response indicates a transient request timeout, rate limit, or gateway failure.
func IsRetryableRPCError ¶
IsRetryableRPCError reports whether err is a transient RPC condition that should be retried (connection drops, timeouts). Context errors and nil are never retryable.
func PrepareTransactOpts ¶ added in v0.7.0
func PrepareTransactOpts(opts *bind.TransactOpts, from common.Address, ctx context.Context, value *big.Int) (*bind.TransactOpts, error)
PrepareTransactOpts validates the signing identity and returns an owned copy whose context and transferred value belong to the current operation.
func SignAndSend ¶ added in v0.7.0
func SignAndSend(ctx context.Context, sender TransactionSender, opts *bind.TransactOpts, build func(*bind.TransactOpts) (*types.Transaction, error)) (*types.Transaction, error)
SignAndSend constructs a signed transaction before attempting to broadcast it. A non-nil transaction with an error means SendTransaction returned that error; the sender may already have accepted the transaction. Earlier failures return a nil transaction. The caller must hold its nonce reservation until this returns.
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 ValidateUint256 ¶ added in v0.7.0
ValidateUint256 checks that v is non-nil and within [0, 2^256-1]. It does not modify v.
func WaitForConfirmation ¶
func WaitForConfirmation(ctx context.Context, client ReceiptClient, txHash common.Hash, confirmations uint64) (*types.Receipt, error)
WaitForConfirmation waits until the transaction's inclusion block has the requested confirmations, then returns its receipt and any transaction failure.
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 after either broadcasting the transaction (so that subsequent Acquire calls observe the bumped pending count) or abandoning the attempt. release is idempotent, so callers may invoke it more than once. 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. Acquisition and submission are serialized; the node determines the pending nonce returned to each caller.
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 non-nil release function. The caller MUST call release after either broadcasting the transaction or abandoning it. release is idempotent, so callers may invoke it more than once. On error, the returned release is a no-op.
ctx governs both waiting for the manager and the PendingNonceAt RPC call.
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.
type TransactionSender ¶ added in v0.7.0
type TransactionSender interface {
SendTransaction(context.Context, *types.Transaction) error
}
TransactionSender broadcasts an already signed transaction.
Source Files