submitter

README

Submitter

Submitter is a module that submits transactions to an evm based-blockchain and bumps them/checks for completion until they are done. It is designed to abstract away gas bumping, confirmation checking, etc from the caller.

Understanding SubmitTransaction

One of the main goals of submitter is for you to be able to call SubmitTransaction once and once you're returned a nonce, be confident that the transaction will eventually get through as long as run keeps running. It's important to understand how this process works and why it exists.

Nonce Locking

The first thing you'll notice about the SubmitTransaction method is it returns a nonce rather than a transaction hash. This is because once the transaction is submitted, it will be bumped (which requires changing the transaction hash) until the transaction is confirmed. The next nonce is generated in the following manner:

graph TB
    style Locker fill:#f9f,stroke:#333,stroke-width:2px;
    style Fetch DB, RPC, Stored, Unlock, Errored, C, D, E fill:#fff,stroke:#333,stroke-width:2px;
    style A fill:#eee,stroke:#333,stroke-width:2px;

    Locker[Lock Nonce Mutex] --> Fetch
    subgraph Fetch [External Fetches ]
        direction TB
        subgraph DB
            direction TB
            B[Get last used nonce in database] --> F[Increment Database Nonce]
        end
        style DB fill:#ccf,stroke:#333,stroke-width:2px;
        style RPC fill:#cfc,stroke:#333,stroke-width:2px;
        subgraph RPC
            A[Get last nonce on-chain]
        end
    end
    style Fetch fill:#ddf,stroke:#333,stroke-width:2px;
    Fetch --> Errored
    Errored{Errored?} -- Yes -->  Unlock
    Errored{Errored?} -- No -->  C
    E --> Stored
    D --> Stored
    Stored --> Unlock
    Stored[Store Association Between Database Nonce and Transaction]
    style Stored fill:#ffc,stroke:#333,stroke-width:2px;
    Unlock[Unlock Nonce Mutex]
    style Unlock fill:#f9f,stroke:#333,stroke-width:2px;
    C{Is on-chain nonce > database nonce?} -- Yes --> D[Use on-chain nonce]
    C -- No --> E[Use database nonce]

You'll now notice that there are two failure cases for this method: if either the db or the rpc url cannot be reached you'll have to resubmit the tx. But these failures occur atomically, so you can do this in a retry loop w/ a backoff.

Grafana Dashboard

The submitter exposes a number of metrics that can be used to monitor the health of the submitter. You can find the dashboard at dashboard.json.

Documentation

Overview

Package submitter provides a simple interface for submitting txs to multiple chains and retrying.

Index

• Variables
• type ClientFetcher
• type ContractCallType
• type SubmissionState
  • func (i SubmissionState) String() string
• type SubmissionStatus
• type TransactionSubmitter
  • func NewTransactionSubmitter(metrics metrics.Handler, signer signer.Signer, fetcher ClientFetcher, ...) TransactionSubmitter

Variables

var ErrNotStarted = errors.New("submitter is not started")

ErrNotStarted is the error for when the submitter is not started.

var ErrSubmitterAlreadyStarted = errors.New("submitter already started")

ErrSubmitterAlreadyStarted is the error for when the submitter is already started.

Types

type ClientFetcher

type ClientFetcher interface {
	GetClient(ctx context.Context, chainID *big.Int) (client.EVM, error)
}

ClientFetcher is the interface for fetching a chain client.

type ContractCallType

type ContractCallType func(transactor *bind.TransactOpts) (tx *types.Transaction, err error)

ContractCallType is a contract call that can be called safely.

type SubmissionState

type SubmissionState uint8

SubmissionState is the status of a submission. This is not used internally and only serves as a way to communicate the status of a submission to the caller.

const (
	// NotFound indicates that the submission was not found.
	NotFound SubmissionState = iota
	// Pending indicates that the submission is pending.
	Pending // pending
	// Confirming indicates that the submission is confirming. The tx has completed on chain, but
	// no txhash has been associated with it yet.
	Confirming // confirming
	// Confirmed indicates that the submission is confirmed and txhash data is available.
	Confirmed // confirmed
)

func (SubmissionState) String

func (i SubmissionState) String() string

type SubmissionStatus

type SubmissionStatus interface {
	// State is the state of the submission.
	State() SubmissionState
	// HasTx indicates whether the submission has a transaction.
	HasTx() bool
	// TxHash is the hash of the transaction. This will be the zero hash if HasTx is false.
	TxHash() common.Hash
}

SubmissionStatus is the status of a submission.

type TransactionSubmitter

type TransactionSubmitter interface {
	// Start starts the transaction submitter.
	Start(ctx context.Context) error
	// SubmitTransaction submits a transaction to the chain.
	// the transaction is not guaranteed to be executed immediately, only at some point in the future.
	// the nonce is returned, and can be used to track the status of the transaction.
	SubmitTransaction(ctx context.Context, chainID *big.Int, call ContractCallType) (nonce uint64, err error)
	// GetSubmissionStatus returns the status of a transaction and any metadata associated with it if it is complete.
	GetSubmissionStatus(ctx context.Context, chainID *big.Int, nonce uint64) (status SubmissionStatus, err error)
	// Address returns the address of the signer.
	Address() common.Address
	// Started returns whether the submitter is running.
	Started() bool
}

TransactionSubmitter is the interface for submitting transactions to the chain.

func NewTransactionSubmitter

func NewTransactionSubmitter(metrics metrics.Handler, signer signer.Signer, fetcher ClientFetcher, db db.Service, config config.IConfig) TransactionSubmitter

NewTransactionSubmitter creates a new transaction submitter.