txsub

Documentation

Overview

Package txsub provides the machinery that horizon uses to submit transactions to the stellar network and track their progress. It also helps to hide some of the complex asynchronous nature of transaction submission, waiting to respond to submitters when no definitive state is known.

Index

• Variables
• type FailedTransactionError
  • func (err *FailedTransactionError) Error() string
  • func (fte *FailedTransactionError) OperationResultCodes() (result []string, err error)
  • func (fte *FailedTransactionError) Result() (result xdr.TransactionResult, err error)
  • func (fte *FailedTransactionError) TransactionResultCodes(transactionHash string) (result ResultCodes, err error)
• type HorizonDB
• type Listener
• type OpenSubmissionList
  • func NewDefaultSubmissionList() OpenSubmissionList
• type Result
• type ResultCodes
• type SubmissionResult
  • func (s SubmissionResult) IsBadSeq() (bool, error)
• type Submitter
  • func NewDefaultSubmitter(h *http.Client, url string) Submitter
• type System
  • func (sys *System) Init()
  • func (sys *System) RegisterMetrics(registry *prometheus.Registry)
  • func (sys *System) Submit(ctx context.Context, rawTx string, envelope xdr.TransactionEnvelope, ...) (resultReadCh <-chan Result)
  • func (sys *System) Tick(ctx context.Context)

Variables

var (
	ErrNoResults = errors.New("No result found")
	ErrCanceled  = errors.New("canceled")
	ErrTimeout   = errors.New("timeout")

	// ErrBadSequence is a canned error response for transactions whose sequence
	// number is wrong.
	ErrBadSequence = &FailedTransactionError{"AAAAAAAAAAD////7AAAAAA=="}
	// ErrNoAccount is returned when the source account for the transaction
	// cannot be found in the database
	ErrNoAccount = &FailedTransactionError{"AAAAAAAAAAD////4AAAAAA=="}
)

Types

type FailedTransactionError

type FailedTransactionError struct {
	ResultXDR string
}

FailedTransactionError represent an error that occurred because stellar-core rejected the transaction. ResultXDR is a base64 encoded TransactionResult struct

func (*FailedTransactionError) Error

func (err *FailedTransactionError) Error() string

func (*FailedTransactionError) OperationResultCodes

func (fte *FailedTransactionError) OperationResultCodes() (result []string, err error)

func (*FailedTransactionError) Result

func (fte *FailedTransactionError) Result() (result xdr.TransactionResult, err error)

func (*FailedTransactionError) TransactionResultCodes

func (fte *FailedTransactionError) TransactionResultCodes(transactionHash string) (result ResultCodes, err error)

type HorizonDB

type HorizonDB interface {
	history.QTxSubmissionResult
	GetSequenceNumbers(ctx context.Context, addresses []string) (map[string]uint64, error)
	BeginTx(*sql.TxOptions) error
	Commit() error
	Rollback() error
	NoRows(error) bool
	GetLatestHistoryLedger(ctx context.Context) (uint32, error)
	TransactionsByHashesSinceLedger(ctx context.Context, hashes []string, sinceLedgerSeq uint32) ([]history.Transaction, error)
}

type Listener

type Listener chan<- Result

Listener represents some client who is interested in retrieving the result of a specific transaction.

type OpenSubmissionList

type OpenSubmissionList interface {
	// Add registers the provided listener as interested in being notified when a
	// result is available for the provided transaction hash.
	Add(context.Context, string, Listener) error

	// Finish forwards the provided result on to any listeners and cleans up any
	// resources associated with the transaction that this result is for
	Finish(context.Context, string, Result) error

	// Clean removes any open submissions over the provided age.
	Clean(context.Context, time.Duration) (int, error)

	// Pending return a list of transaction hashes that have at least one
	// listener registered to them in this list.
	Pending(context.Context) []string
}

OpenSubmissionList represents the structure that tracks pending transactions and forwards Result structs on to listeners as they become available.

NOTE: An implementation of this interface will be called from multiple go-routines concurrently.

NOTE: A Listener must be a buffered channel. A panic will trigger if you provide an unbuffered channel

func NewDefaultSubmissionList

func NewDefaultSubmissionList() OpenSubmissionList

NewDefaultSubmissionList returns a list that manages open submissions purely in memory.

type Result

type Result struct {
	// Any error that occurred during the retrieval of this result
	Err error

	// The full details of the transaction which was submitted
	// to Stellar Core
	Transaction history.Transaction
}

Result represents the response from a ResultProvider. Given no Err is set, the rest of the struct should be populated appropriately.

type ResultCodes

type ResultCodes struct {
	Code      string
	InnerCode string
}

ResultCodes represents the result codes from a request attempting to submit a fee bump transaction.

type SubmissionResult

type SubmissionResult struct {
	// Any error that occurred during the attempted submission.  A nil value
	// indicates that the submission will or already is being considered for
	// inclusion in the ledger (i.e. A successful submission).
	Err error

	// Duration records the time it took to submit a transaction
	// to stellar-core
	Duration time.Duration
}

SubmissionResult gets returned in response to a call to Submitter.Submit. It represents a single discrete submission of a transaction envelope to the stellar network.

func (SubmissionResult) IsBadSeq

func (s SubmissionResult) IsBadSeq() (bool, error)

type Submitter

type Submitter interface {
	// Submit sends the provided transaction envelope to stellar-core
	Submit(context.Context, string) SubmissionResult
}

Submitter represents the low-level "submit a transaction to stellar-core" provider.

func NewDefaultSubmitter

func NewDefaultSubmitter(h *http.Client, url string) Submitter

NewDefaultSubmitter returns a new, simple Submitter implementation that submits directly to the stellar-core at `url` using the http client `h`.

type System

type System struct {
	DB                  func(context.Context) HorizonDB
	Pending             OpenSubmissionList
	Submitter           Submitter
	SubmissionQueue     *sequence.Manager
	SubmissionTimeout   time.Duration
	SubmissionResultTTL time.Duration

	Log *log.Entry

	Metrics struct {
		// SubmissionDuration exposes timing metrics about the rate and latency of
		// submissions to stellar-core
		SubmissionDuration prometheus.Summary

		// BufferedSubmissionGauge tracks the count of submissions buffered
		// behind this system's SubmissionQueue
		BufferedSubmissionsGauge prometheus.Gauge

		// OpenSubmissionsGauge tracks the count of "open" submissions (i.e.
		// submissions whose transactions haven't been confirmed successful or failed
		OpenSubmissionsGauge prometheus.Gauge

		// FailedSubmissionsCounter tracks the rate of failed transactions that have
		// been submitted to this process
		FailedSubmissionsCounter prometheus.Counter

		// SuccessfulSubmissionsCounter tracks the rate of successful transactions that
		// have been submitted to this process
		SuccessfulSubmissionsCounter prometheus.Counter

		// V0TransactionsCounter tracks the rate of v0 transaction envelopes that
		// have been submitted to this process
		V0TransactionsCounter prometheus.Counter

		// V1TransactionsCounter tracks the rate of v1 transaction envelopes that
		// have been submitted to this process
		V1TransactionsCounter prometheus.Counter

		// FeeBumpTransactionsCounter tracks the rate of fee bump transaction envelopes that
		// have been submitted to this process
		FeeBumpTransactionsCounter prometheus.Counter
	}
	// contains filtered or unexported fields
}

System represents a completely configured transaction submission system. Its methods tie together the various pieces used to reliably submit transactions to a stellar-core instance.

func (*System) Init

func (sys *System) Init()

Init initializes `sys`

func (*System) RegisterMetrics

func (sys *System) RegisterMetrics(registry *prometheus.Registry)

RegisterMetrics registers the prometheus metrics

func (*System) Submit

func (sys *System) Submit(
	ctx context.Context,
	rawTx string,
	envelope xdr.TransactionEnvelope,
	hash string,
	innerHash string,
) (resultReadCh <-chan Result)

Submit submits the provided base64 encoded transaction envelope to the network using this submission system.

func (*System) Tick

func (sys *System) Tick(ctx context.Context)

Tick triggers the system to update itself with any new data available.