db

Documentation

Overview

Package db provides a database interface for the submitter.

Index

• Variables
• type Service
• type Status
  • func AllStatusTypes() []Status
  • func (s Status) GormDataType() string
  • func (s Status) Int() uint8
  • func (s *Status) Scan(src interface{}) error
  • func (i Status) String() string
  • func (s *Status) Value() (driver.Value, error)
• type SubmitterDBFactory
• type TX
  • func NewTX(tx *types.Transaction, status Status, UUID string) TX
  • func (t *TX) CreationTime() time.Time
  • func (t *TX) UnsafeSetCreationTime(creationTime time.Time)
• type TransactionFunc

Variables

var (
	// ErrNoNonceForChain is the error returned when there is no nonce for a given chain id.
	ErrNoNonceForChain = errors.New("no nonce exists for this chain")
	// ErrNonceNotExist is the error returned when a nonce does not exist.
	ErrNonceNotExist = errors.New("nonce does not exist")
)

Types

type Service

type Service interface {
	// GetNonceForChainID gets the nonce for a given chain id.
	GetNonceForChainID(ctx context.Context, fromAddress common.Address, chainID *big.Int) (nonce uint64, err error)
	// PutTXS stores a tx in the database.
	PutTXS(ctx context.Context, txs ...TX) error
	// GetTXS gets all txs for a given address and chain id. If chain id is nil, it will get all txs for the address.
	GetTXS(ctx context.Context, fromAddress common.Address, chainID *big.Int, statuses ...Status) (txs []TX, err error)
	// MarkAllBeforeNonceReplacedOrConfirmed marks all txs for a given chain id and address before a given nonce as replaced or confirmed.
	// TODO: cleaner function name
	MarkAllBeforeNonceReplacedOrConfirmed(ctx context.Context, signer common.Address, chainID *big.Int, nonce uint64) error
	// DBTransaction executes a transaction on the database.
	// the function passed in will be passed a new service that is scoped to the transaction.
	DBTransaction(ctx context.Context, f TransactionFunc) error
	// GetAllTXAttemptByStatus gets all txs for a given address and chain id with a given status.
	GetAllTXAttemptByStatus(ctx context.Context, fromAddress common.Address, chainID *big.Int, matchStatuses ...Status) (txs []TX, err error)
	// GetNonceStatus returns the nonce status for a given nonce by aggregating all attempts and finding the highest status.
	GetNonceStatus(ctx context.Context, fromAddress common.Address, chainID *big.Int, nonce uint64) (status Status, err error)
	// GetNonceAttemptsByStatus gets all txs for a given address and chain id with a given status and nonce.
	GetNonceAttemptsByStatus(ctx context.Context, fromAddress common.Address, chainID *big.Int, nonce uint64, matchStatuses ...Status) (txs []TX, err error)
	// GetChainIDsByStatus gets the distinct chain ids for a given address and status.
	GetChainIDsByStatus(ctx context.Context, fromAddress common.Address, matchStatuses ...Status) (chainIDs []*big.Int, err error)
	// DeleteTXS deletes txs that are older than a given duration.
	DeleteTXS(ctx context.Context, maxAge time.Duration, matchStatuses ...Status) error
	// GetDistinctChainIDs gets the distinct chain ids for all txs.
	GetDistinctChainIDs(ctx context.Context) ([]*big.Int, error)
}

Service is the interface for the tx queue database. note: the other files in this package (base, sqlite, mysql) provide a suggested implementation. you can implement these yourself. If you plan on importing them, you should wrap in your own service.

type Status

type Status uint8

Status is the status of a tx.

const (
	// Pending is the status of a tx that has not been processed yet.
	Pending Status = iota + 1 // Pending
	// Stored is the status of a tx that has been stored.
	Stored // Stored
	// Submitted is the status of a tx that has been submitted.
	Submitted // Submitted
	// FailedSubmit is the status of a tx that has failed to submit.
	FailedSubmit // Failed
	// ReplacedOrConfirmed is the status of a tx that has been replaced by a new tx or confirmed. The actual status will be set later.
	ReplacedOrConfirmed // ReplacedOrConfirmed
	// Replaced is the status of a tx that has been replaced by a new tx.
	Replaced // Replaced
	// Confirmed is the status of a tx that has been confirmed.
	Confirmed // Confirmed
)

Important: do not modify the order of these constants. if one needs to be removed, replace it with a no-op status. additionally, due to the GetMaxNoncestatus function, statuses are currently assumed to be in order. if you need to modify this functionality, please update that function. to reflect that the highest status isno longer the expected end status.

func AllStatusTypes

func AllStatusTypes() []Status

AllStatusTypes returns all status types. it is exported for testing purposes

These are guaranteed to be in order.

func (Status) GormDataType

func (s Status) GormDataType() string

GormDataType returns the gorm data type for the status.

func (Status) Int

func (s Status) Int() uint8

Int returns the uint8 representation of the status.

func (*Status) Scan

func (s *Status) Scan(src interface{}) error

Scan implements the gorm Scanner interface.

func (Status) String

func (i Status) String() string

func (*Status) Value

func (s *Status) Value() (driver.Value, error)

Value implements the gorm Valuer interface.

type SubmitterDBFactory

type SubmitterDBFactory interface {
	SubmitterDB() Service
}

SubmitterDBFactory is the interface for the tx queue database factory.

type TX

type TX struct {
	// UUID is a unique identifier for the transaction that should be reused
	// if the transaction is bumped.
	UUID string
	// inherited from types.Transaction
	*types.Transaction

	// Status is the status of the transaction
	Status Status
	// contains filtered or unexported fields
}

TX is a superset of transaction that includes the gas price.

func NewTX

func NewTX(tx *types.Transaction, status Status, UUID string) TX

NewTX creates a new TX for use in the db package.

func (*TX) CreationTime

func (t *TX) CreationTime() time.Time

CreationTime is the time the transaction was last updated.

func (*TX) UnsafeSetCreationTime

func (t *TX) UnsafeSetCreationTime(creationTime time.Time)

UnsafeSetCreationTime is an unsafe setter for the creation time it is called unsafe to force you to read this comment telling you this should only be called if you are creating a db implementation of this package. this should not be called in the submmiter itself or any other package.

type TransactionFunc

type TransactionFunc func(ctx context.Context, svc Service) error

TransactionFunc is a function that can be passed to DBTransaction.