types

package
v2.1.0-beta0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 26, 2023 License: MIT Imports: 12 Imported by: 0

Documentation

Index

Constants

View Source 
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")
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Accounts added in v2.1.0 

type Accounts[ADDR types.Hashable, SEQ Sequence] interface {
	BalanceAt(ctx context.Context, accountAddress ADDR, blockNumber *big.Int) (*big.Int, error)
	TokenBalance(ctx context.Context, accountAddress ADDR, tokenAddress ADDR) (*big.Int, error)
	SequenceAt(ctx context.Context, accountAddress ADDR, blockNumber *big.Int) (SEQ, error)
}

type Blocks added in v2.1.0 

type Blocks[BLOCK any, BLOCKHASH types.Hashable] interface {
	BlockByNumber(ctx context.Context, number *big.Int) (*BLOCK, error)
	BlockByHash(ctx context.Context, hash BLOCKHASH) (*BLOCK, error)
	LatestBlockHeight(context.Context) (*big.Int, error)
}

type BroadcasterConfig added in v2.1.0 

type BroadcasterConfig[UNIT any] interface {
	TriggerFallbackDBPollInterval() time.Duration
	MaxInFlightTransactions() uint32

	// from gas.Config
	IsL2() bool
	MaxFeePrice() UNIT
	FeePriceDefault() UNIT
}

UNIT - fee unit

type Client added in v2.1.0 

type Client[
	CHAINID ID,
	SEQ Sequence,
	ADDR types.Hashable,
	BLOCK any,
	BLOCKHASH types.Hashable,
	TX any,
	TXHASH types.Hashable,
	TXRECEIPT any,
	EVENT any,
	EVENTOPS any,
] interface {
	// ChainID stored for quick access
	ConfiguredChainID() CHAINID
	// ChainID RPC call
	ChainID() (CHAINID, error)

	Accounts[ADDR, SEQ]
	Transactions[TX, TXHASH, TXRECEIPT]
	Events[EVENT, EVENTOPS]
	Blocks[BLOCK, BLOCKHASH]

	CallContext(ctx context.Context, result interface{}, method string, args ...interface{}) error
}

A generic client interface for communication with the RPC node Every native chain must implement independently

type ConfirmerConfig added in v2.1.0 

type ConfirmerConfig[UNIT any] interface {
	RPCDefaultBatchSize() uint32
	UseForwarders() bool
	FeeBumpTxDepth() uint16
	MaxInFlightTransactions() uint32
	FeeLimitDefault() uint32

	// from gas.Config
	FeeBumpThreshold() uint64
	FinalityDepth() uint32
	MaxFeePrice() UNIT
	FeeBumpPercent() uint16

	// from pg.QConfig
	DatabaseDefaultQueryTimeout() time.Duration
}

UNIT - fee unit

type Events added in v2.1.0 

type Events[EVENT any, EVENTOPS any] interface {
	FilterEvents(ctx context.Context, query EVENTOPS) ([]EVENT, error)
}

type Fee 

type Fee fmt.Stringer

type FeeEstimator 

type FeeEstimator[H Head, F Fee, MAXPRICE any, TX_HASH types.Hashable] 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, TX_HASH]) (bumpedFee F, chainSpecificFeeLimit uint32, err error)
}

FeeEstimator provides a generic interface for fee estimation

type ForwarderManager 

type ForwarderManager[ADDR types.Hashable] 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 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 ID added in v2.1.0 

type ID fmt.Stringer

ID represents the base type, for any chain's ID. It should be convertible to a string, that can uniquely identify this chain

type KeyStore added in v2.1.0 

type KeyStore[

	ADDR types.Hashable,

	CHAIN_ID ID,

	SEQ Sequence,
] interface {
	CheckEnabled(address ADDR, chainID CHAIN_ID) error
	NextSequence(address ADDR, chainID CHAIN_ID, qopts ...pg.QOpt) (SEQ, error)
	EnabledAddressesForChain(chainId CHAIN_ID) ([]ADDR, error)
	IncrementNextSequence(address ADDR, chainID CHAIN_ID, currentSequence SEQ, qopts ...pg.QOpt) error
	SubscribeToKeyChanges() (ch chan struct{}, unsub func())
}

KeyStore encompasses the subset of keystore used by txmgr

type NewTx added in v2.1.0 

type NewTx[ADDR types.Hashable, TX_HASH types.Hashable] struct {
	FromAddress      ADDR
	ToAddress        ADDR
	EncodedPayload   []byte
	FeeLimit         uint32
	Meta             *TxMeta[ADDR, TX_HASH]
	ForwarderAddress ADDR

	// Pipeline variables - if you aren't calling this from ethtx task within
	// the pipeline, you don't need these variables
	MinConfirmations  clnull.Uint32
	PipelineTaskRunID *uuid.UUID

	Strategy TxStrategy

	// Checker defines the check that should be run before a transaction is submitted on chain.
	Checker TransmitCheckerSpec[ADDR]
}

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, TX_HASH types.Hashable] interface {
	Fee() F
	GetChainSpecificGasLimit() uint32
	GetBroadcastBeforeBlockNum() *int64
	GetHash() TX_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 ReaperConfig added in v2.1.0 

type ReaperConfig interface {
	TxReaperInterval() time.Duration
	TxReaperThreshold() time.Duration

	// gas config
	FinalityDepth() uint32
}

ReaperConfig is the config subset used by the reaper

type Receipt 

type Receipt[R any, TX_HASH types.Hashable, BLOCK_HASH types.Hashable] struct {
	ID               int64
	TxHash           TX_HASH
	BlockHash        BLOCK_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 ResenderConfig added in v2.1.0 

type ResenderConfig interface {
	TxResendAfterThreshold() time.Duration
	MaxInFlightTransactions() uint32
	RPCDefaultBatchSize() uint32
}

type Sequence added in v2.1.0 

type Sequence fmt.Stringer

Sequence represents the base type, for any chain's sequence object. It should be convertible to a string

type Transaction added in v2.1.0 

type Transaction interface {
	GetID() string
}

Transaction is the type that callers get back, when they create a Transaction using the Txm. TODO: Remove this with the EthTx type, once that is extracted out to this namespace.

type Transactions added in v2.1.0 

type Transactions[TX any, TXHASH types.Hashable, TXRECEIPT any] interface {
	SendTransaction(ctx context.Context, tx *TX) error
	SimulateTransaction(ctx context.Context, tx *TX) error
	TransactionByHash(ctx context.Context, txHash TXHASH) (*TX, error)
	TransactionReceipt(ctx context.Context, txHash TXHASH) (*TXRECEIPT, error)
}

type TransmitCheckerSpec added in v2.1.0 

type TransmitCheckerSpec[ADDR types.Hashable] struct {
	// CheckerType is the type of check that should be performed. Empty indicates no check.
	CheckerType TransmitCheckerType `json:",omitempty"`

	// VRFCoordinatorAddress is the address of the VRF coordinator that should be used to perform
	// VRF transmit checks. This should be set iff CheckerType is TransmitCheckerTypeVRFV2.
	VRFCoordinatorAddress *ADDR `json:",omitempty"`

	// VRFRequestBlockNumber is the block number in which the provided VRF request has been made.
	// This should be set iff CheckerType is TransmitCheckerTypeVRFV2.
	VRFRequestBlockNumber *big.Int `json:",omitempty"`
}

TransmitCheckerSpec defines the check that should be performed before a transaction is submitted on chain.

type TransmitCheckerType added in v2.1.0 

type TransmitCheckerType string

TransmitCheckerType describes the type of check that should be performed before a transaction is executed on-chain.

type TxAttemptBuilder 

type TxAttemptBuilder[
	HEAD Head,
	FEE Fee,
	ADDR types.Hashable,
	TX_HASH types.Hashable,
	TX any,
	TXATTEMPT any,
	SEQ Sequence,
] 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, TX_HASH], 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(seq SEQ, 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 TxMeta added in v2.1.0 

type TxMeta[ADDR types.Hashable, TX_HASH types.Hashable] struct {
	JobID *int32 `json:"JobID,omitempty"`

	// Pipeline fields
	FailOnRevert null.Bool `json:"FailOnRevert,omitempty"`

	// VRF-only fields
	RequestID     *TX_HASH `json:"RequestID,omitempty"`
	RequestTxHash *TX_HASH `json:"RequestTxHash,omitempty"`
	// Batch variants of the above
	RequestIDs      []TX_HASH `json:"RequestIDs,omitempty"`
	RequestTxHashes []TX_HASH `json:"RequestTxHashes,omitempty"`
	// Used for the VRFv2 - max link this tx will bill
	// should it get bumped
	MaxLink *string `json:"MaxLink,omitempty"`
	// Used for the VRFv2 - the subscription ID of the
	// requester of the VRF.
	SubID *uint64 `json:"SubId,omitempty"`

	// Used for keepers
	UpkeepID *string `json:"UpkeepID,omitempty"`

	// Used only for forwarded txs, tracks the original destination address.
	// When this is set, it indicates tx is forwarded through To address.
	FwdrDestAddress *ADDR `json:"ForwarderDestAddress,omitempty"`

	// MessageIDs is used by CCIP for tx to executed messages correlation in logs
	MessageIDs []string `json:"MessageIDs,omitempty"`
	// SeqNumbers is used by CCIP for tx to committed sequence numbers correlation in logs
	SeqNumbers []uint64 `json:"SeqNumbers,omitempty"`
}

TxMeta contains fields of the transaction metadata Not all fields are guaranteed to be present

type TxStore added in v2.1.0 

type TxStore[

	ADDR types.Hashable,

	CHAIN_ID ID,

	TX_HASH types.Hashable,

	BLOCK_HASH types.Hashable,
	NEWTX any,

	R any,

	TX any,

	TXATTEMPT any,

	SEQ Sequence,
] interface {
	UnstartedTxQueuePruner
	CheckEthTxQueueCapacity(fromAddress ADDR, maxQueuedTransactions uint64, chainID CHAIN_ID, qopts ...pg.QOpt) (err error)
	CountUnconfirmedTransactions(fromAddress ADDR, chainID CHAIN_ID, qopts ...pg.QOpt) (count uint32, err error)
	CountUnstartedTransactions(fromAddress ADDR, chainID CHAIN_ID, qopts ...pg.QOpt) (count uint32, err error)
	CreateEthTransaction(newTx NEWTX, chainID CHAIN_ID, qopts ...pg.QOpt) (tx Transaction, 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 CHAIN_ID) (receiptsPlus []ReceiptPlus[R], err error)
	FindEthTxAttempt(hash TX_HASH) (*TXATTEMPT, error)
	FindEthTxAttemptConfirmedByEthTxIDs(ids []int64) ([]TXATTEMPT, error)
	FindEthTxsRequiringGasBump(ctx context.Context, address ADDR, blockNum, gasBumpThreshold, depth int64, chainID CHAIN_ID) (etxs []*TX, err error)
	FindEthTxsRequiringResubmissionDueToInsufficientEth(address ADDR, chainID CHAIN_ID, qopts ...pg.QOpt) (etxs []*TX, err error)
	FindEtxAttemptsConfirmedMissingReceipt(chainID CHAIN_ID) (attempts []TXATTEMPT, err error)
	FindEthTxAttemptsByEthTxIDs(ids []int64) ([]TXATTEMPT, error)
	FindEthTxAttemptsRequiringReceiptFetch(chainID CHAIN_ID) (attempts []TXATTEMPT, err error)
	FindEthTxAttemptsRequiringResend(olderThan time.Time, maxInFlightTransactions uint32, chainID CHAIN_ID, address ADDR) (attempts []TXATTEMPT, err error)
	FindEthTxByHash(hash TX_HASH) (*TX, error)
	FindEthTxWithAttempts(etxID int64) (etx TX, err error)
	FindEthTxWithNonce(fromAddress ADDR, seq SEQ) (etx *TX, err error)
	FindNextUnstartedTransactionFromAddress(etx *TX, fromAddress ADDR, chainID CHAIN_ID, qopts ...pg.QOpt) error
	FindTransactionsConfirmedInBlockRange(highBlockNumber, lowBlockNumber int64, chainID CHAIN_ID) (etxs []*TX, err error)
	GetEthTxInProgress(fromAddress ADDR, qopts ...pg.QOpt) (etx *TX, err error)
	GetInProgressEthTxAttempts(ctx context.Context, address ADDR, chainID CHAIN_ID) (attempts []TXATTEMPT, err error)
	HasInProgressTransaction(account ADDR, chainID CHAIN_ID, qopts ...pg.QOpt) (exists bool, err error)
	// InsertEthReceipt only used in tests. Use SaveFetchedReceipts instead
	InsertEthReceipt(receipt *Receipt[R, TX_HASH, BLOCK_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 CHAIN_ID) (err error)
	MarkOldTxesMissingReceiptAsErrored(blockNum int64, finalityDepth uint32, chainID CHAIN_ID, qopts ...pg.QOpt) error
	PreloadEthTxes(attempts []TXATTEMPT, qopts ...pg.QOpt) error
	SaveConfirmedMissingReceiptAttempt(ctx context.Context, timeout time.Duration, attempt *TXATTEMPT, broadcastAt time.Time) error
	SaveFetchedReceipts(receipts []R, chainID CHAIN_ID) (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 CHAIN_ID) error
	UpdateBroadcastAts(now time.Time, etxIDs []int64) error
	UpdateEthKeyNextNonce(newNextNonce, currentNextNonce SEQ, address ADDR, chainID CHAIN_ID, 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 TxmConfig added in v2.1.0 

type TxmConfig[UNIT any] interface {
	BroadcasterConfig[UNIT]
	ConfirmerConfig[UNIT]
	ResenderConfig
	ReaperConfig

	SequenceAutoSync() bool
	UseForwarders() bool
	MaxQueuedTransactions() uint64
}

UNIT - fee unit

type UnstartedTxQueuePruner 

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

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.