types

Documentation

Index

• Constants
• type Fee
• type FeeEstimator
• type ForwarderManager
• type Head
• type HeadTrackable
• type Opt
• type PriorAttempt
• type QueryerFunc
• type Receipt
• type ReceiptPlus
• type TxAttemptBuilder
• type TxAttemptState
• type TxStorageService
• type TxStrategy
• type UnstartedTxQueuePruner

Constants

const (
	TxAttemptInProgress = TxAttemptState("in_progress")
	// TODO: Make name chain-agnostic (https://smartcontract-it.atlassian.net/browse/BCI-981)
	TxAttemptInsufficientEth = TxAttemptState("insufficient_eth")
	TxAttemptBroadcast       = TxAttemptState("broadcast")
)

Types

type Fee

type Fee fmt.Stringer

type FeeEstimator

type FeeEstimator[H Head, F Fee, MAXPRICE any, HASH any] interface {
	services.ServiceCtx
	HeadTrackable[H]

	GetFee(ctx context.Context, calldata []byte, feeLimit uint32, maxFeePrice MAXPRICE, opts ...Opt) (fee F, chainSpecificFeeLimit uint32, err error)
	BumpFee(ctx context.Context, originalFee F, feeLimit uint32, maxFeePrice MAXPRICE, attempts []PriorAttempt[F, HASH]) (bumpedFee F, chainSpecificFeeLimit uint32, err error)
}

FeeEstimator provides a generic interface for fee estimation

type ForwarderManager

type ForwarderManager[ADDR any] interface {
	services.ServiceCtx
	ForwarderFor(addr ADDR) (forwarder ADDR, err error)
	// Converts payload to be forwarder-friendly
	ConvertPayload(dest ADDR, origPayload []byte) ([]byte, error)
}

type Head

type Head interface {
	// BlockNumber is the head's block number
	BlockNumber() int64

	// ChainLength returns the length of the chain followed by recursively looking up parents
	ChainLength() uint32

	// EarliestInChain traverses through parents until it finds the earliest one
	EarliestHeadInChain() Head

	// Hash is the head's block hash
	BlockHash() common.Hash

	// Parent is the head's parent block
	GetParent() Head

	// HashAtHeight returns the hash of the block at the given height, if it is in the chain.
	// If not in chain, returns the zero hash
	HashAtHeight(blockNum int64) common.Hash
}

Head provides access to a chain's head, as needed by the TxManager. This is a generic interface which ALL chains will implement.

type HeadTrackable

type HeadTrackable[H Head] interface {
	OnNewLongestChain(ctx context.Context, head H)
}

HeadTrackable is implemented by the core txm, to be able to receive head events from any chain. Chain implementations should notify head events to the core txm via this interface.

type Opt

type Opt int

Opt is an option for a gas estimator

const (
	// OptForceRefetch forces the estimator to bust a cache if necessary
	OptForceRefetch Opt = iota
)

type PriorAttempt

type PriorAttempt[F Fee, HASH any] interface {
	Fee() F
	GetChainSpecificGasLimit() uint32
	GetBroadcastBeforeBlockNum() *int64
	GetHash() HASH
	GetTxType() int
}

PriorAttempt provides a generic interface for reading tx data to be used in the fee esimators

type QueryerFunc

type QueryerFunc = func(tx pg.Queryer) error

type Receipt

type Receipt[R any, HASH any] struct {
	ID               int64
	TxHash           HASH
	BlockHash        HASH
	BlockNumber      int64
	TransactionIndex uint
	Receipt          R
	CreatedAt        time.Time
}

R is the raw unparsed transaction receipt

type ReceiptPlus

type ReceiptPlus[R any] struct {
	ID           uuid.UUID `db:"pipeline_run_id"`
	Receipt      R         `db:"receipt"`
	FailOnRevert bool      `db:"fail_on_revert"`
}

R is the raw unparsed transaction receipt

type TxAttemptBuilder

type TxAttemptBuilder[
	HEAD Head,
	FEE Fee,
	ADDR any,
	TXHASH any,
	TX any,
	TXATTEMPT any,
] interface {
	// interfaces for running the underlying estimator
	services.ServiceCtx
	HeadTrackable[HEAD]

	// NewTxAttempt builds a transaction using the configured transaction type and fee estimator (new estimation)
	NewTxAttempt(ctx context.Context, tx TX, lggr logger.Logger, opts ...Opt) (attempt TXATTEMPT, fee FEE, feeLimit uint32, retryable bool, err error)

	// NewTxAttemptWithType builds a transaction using the configured fee estimator (new estimation) + passed in tx type
	NewTxAttemptWithType(ctx context.Context, tx TX, lggr logger.Logger, txType int, opts ...Opt) (attempt TXATTEMPT, fee FEE, feeLimit uint32, retryable bool, err error)

	// NewBumpTxAttempt builds a transaction using the configured fee estimator (bumping) + tx type from previous attempt
	// this should only be used after an initial attempt has been broadcast and the underlying gas estimator only needs to bump the fee
	NewBumpTxAttempt(ctx context.Context, tx TX, previousAttempt TXATTEMPT, priorAttempts []PriorAttempt[FEE, TXHASH], lggr logger.Logger) (attempt TXATTEMPT, bumpedFee FEE, bumpedFeeLimit uint32, retryable bool, err error)

	// NewCustomTxAttempt builds a transaction using the passed in fee + tx type
	NewCustomTxAttempt(tx TX, fee FEE, gasLimit uint32, txType int, lggr logger.Logger) (attempt TXATTEMPT, retryable bool, err error)

	// NewEmptyTxAttempt is used in ForceRebroadcast to create a signed tx with zero value sent to the zero address
	NewEmptyTxAttempt(nonce uint64, feeLimit uint32, fee FEE, fromAddress ADDR) (attempt TXATTEMPT, err error)
}

TxAttemptBuilder takes the base unsigned transaction + optional parameters (tx type, gas parameters) and returns a signed TxAttempt it is able to estimate fees and sign transactions

type TxAttemptState

type TxAttemptState string

type TxStorageService

type TxStorageService[ADDR any, CHAINID any, HASH any, NEWTX any, R any, TX any, TXATTEMPT any, TXID any, TXMETA any] interface {
	UnstartedTxQueuePruner
	CheckEthTxQueueCapacity(fromAddress ADDR, maxQueuedTransactions uint64, chainID CHAINID, qopts ...pg.QOpt) (err error)
	CountUnconfirmedTransactions(fromAddress ADDR, chainID CHAINID, qopts ...pg.QOpt) (count uint32, err error)
	CountUnstartedTransactions(fromAddress ADDR, chainID CHAINID, qopts ...pg.QOpt) (count uint32, err error)
	CreateEthTransaction(newTx NEWTX, chainID CHAINID, qopts ...pg.QOpt) (tx TX, err error)
	DeleteInProgressAttempt(ctx context.Context, attempt TXATTEMPT) error
	EthTransactions(offset, limit int) ([]TX, int, error)
	EthTransactionsWithAttempts(offset, limit int) ([]TX, int, error)
	EthTxAttempts(offset, limit int) ([]TXATTEMPT, int, error)
	FindEthReceiptsPendingConfirmation(ctx context.Context, blockNum int64, chainID CHAINID) (receiptsPlus []ReceiptPlus[R], err error)
	FindEthTxAttempt(hash HASH) (*TXATTEMPT, error)
	FindEthTxAttemptConfirmedByEthTxIDs(ids []TXID) ([]TXATTEMPT, error)
	FindEthTxsRequiringGasBump(ctx context.Context, address ADDR, blockNum, gasBumpThreshold, depth int64, chainID CHAINID) (etxs []*TX, err error)
	FindEthTxsRequiringResubmissionDueToInsufficientEth(address ADDR, chainID CHAINID, qopts ...pg.QOpt) (etxs []*TX, err error)
	FindEtxAttemptsConfirmedMissingReceipt(chainID CHAINID) (attempts []TXATTEMPT, err error)
	FindEthTxAttemptsByEthTxIDs(ids []TXID) ([]TXATTEMPT, error)
	FindEthTxAttemptsRequiringReceiptFetch(chainID CHAINID) (attempts []TXATTEMPT, err error)
	FindEthTxAttemptsRequiringResend(olderThan time.Time, maxInFlightTransactions uint32, chainID CHAINID, address ADDR) (attempts []TXATTEMPT, err error)
	FindEthTxByHash(hash HASH) (*TX, error)
	FindEthTxWithAttempts(etxID TXID) (etx TX, err error)
	FindEthTxWithNonce(fromAddress ADDR, nonce TXMETA) (etx *TX, err error)
	FindNextUnstartedTransactionFromAddress(etx *TX, fromAddress ADDR, chainID CHAINID, qopts ...pg.QOpt) error
	FindTransactionsConfirmedInBlockRange(highBlockNumber, lowBlockNumber int64, chainID CHAINID) (etxs []*TX, err error)
	GetEthTxInProgress(fromAddress ADDR, qopts ...pg.QOpt) (etx *TX, err error)
	GetInProgressEthTxAttempts(ctx context.Context, address ADDR, chainID CHAINID) (attempts []TXATTEMPT, err error)
	HasInProgressTransaction(account ADDR, chainID CHAINID, qopts ...pg.QOpt) (exists bool, err error)
	// InsertEthReceipt only used in tests. Use SaveFetchedReceipts instead
	InsertEthReceipt(receipt *Receipt[R, HASH]) error
	InsertEthTx(etx *TX) error
	InsertEthTxAttempt(attempt *TXATTEMPT) error
	LoadEthTxAttempts(etx *TX, qopts ...pg.QOpt) error
	LoadEthTxesAttempts(etxs []*TX, qopts ...pg.QOpt) error
	MarkAllConfirmedMissingReceipt(chainID CHAINID) (err error)
	MarkOldTxesMissingReceiptAsErrored(blockNum int64, finalityDepth uint32, chainID CHAINID, qopts ...pg.QOpt) error
	PreloadEthTxes(attempts []TXATTEMPT) error
	SaveConfirmedMissingReceiptAttempt(ctx context.Context, timeout time.Duration, attempt *TXATTEMPT, broadcastAt time.Time) error
	SaveFetchedReceipts(receipts []R, chainID CHAINID) (err error)
	SaveInProgressAttempt(attempt *TXATTEMPT) error
	SaveInsufficientEthAttempt(timeout time.Duration, attempt *TXATTEMPT, broadcastAt time.Time) error
	SaveReplacementInProgressAttempt(oldAttempt TXATTEMPT, replacementAttempt *TXATTEMPT, qopts ...pg.QOpt) error
	SaveSentAttempt(timeout time.Duration, attempt *TXATTEMPT, broadcastAt time.Time) error
	SetBroadcastBeforeBlockNum(blockNum int64, chainID CHAINID) error
	UpdateBroadcastAts(now time.Time, etxIDs []TXID) error
	UpdateEthKeyNextNonce(newNextNonce, currentNextNonce TXMETA, address ADDR, chainID CHAINID, qopts ...pg.QOpt) error
	UpdateEthTxAttemptInProgressToBroadcast(etx *TX, attempt TXATTEMPT, NewAttemptState TxAttemptState, incrNextNonceCallback QueryerFunc, qopts ...pg.QOpt) error
	UpdateEthTxsUnconfirmed(ids []int64) error
	UpdateEthTxUnstartedToInProgress(etx *TX, attempt *TXATTEMPT, qopts ...pg.QOpt) error
	UpdateEthTxFatalError(etx *TX, qopts ...pg.QOpt) error
	UpdateEthTxForRebroadcast(etx TX, etxAttempt TXATTEMPT) error
	Close()
}

NEWTX, TX, TXATTEMPT will be converted from generic types to structs at a future date to enforce design and type checks

type TxStrategy

type TxStrategy interface {
	// Subject will be saved txes.subject if not null
	Subject() uuid.NullUUID
	// PruneQueue is called after tx insertion
	// It accepts the service responsible for deleting
	// unstarted txs and deletion options
	PruneQueue(pruneService UnstartedTxQueuePruner, qopt pg.QOpt) (n int64, err error)
}

TxStrategy controls how txes are queued and sent

type UnstartedTxQueuePruner

type UnstartedTxQueuePruner interface {
	PruneUnstartedTxQueue(queueSize uint32, subject uuid.UUID, qopts ...pg.QOpt) (n int64, err error)
}