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.
Documentation
¶
Overview ¶
Package submitter provides a simple interface for submitting txs to multiple chains and retrying.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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 ¶ added in v0.0.100
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 ¶ added in v0.0.100
func (i SubmissionState) String() string
type SubmissionStatus ¶ added in v0.0.100
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)
}
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.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package config provides a configuration struct and getters for the submitter.
|
Package config provides a configuration struct and getters for the submitter. |
|
Package db provides a database interface for the submitter.
|
Package db provides a database interface for the submitter. |
|
txdb
Package txdb provides a database implementation that simplements the submitter db service.
|
Package txdb provides a database implementation that simplements the submitter db service. |