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

• Constants
• 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) TransactionResultCode() (result string, err error)
• type Listener
• type MalformedTransactionError
  • func (err *MalformedTransactionError) Error() string
• type MockResultProvider
  • func (results *MockResultProvider) ResultByHash(ctx context.Context, hash string) (r Result)
• type MockSequenceProvider
  • func (results *MockSequenceProvider) Get(addresses []string) (map[string]uint64, error)
• type MockSubmitter
  • func (sub *MockSubmitter) Submit(ctx context.Context, env string) SubmissionResult
• type OpenSubmissionList
  • func NewDefaultSubmissionList() OpenSubmissionList
• type Result
• type ResultProvider
• type SequenceProvider
• 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) Submit(ctx context.Context, env string) (result <-chan Result)
  • func (sys *System) Tick(ctx context.Context)

Constants

const (
	StatusError     = "ERROR"
	StatusPending   = "PENDING"
	StatusDuplicate = "DUPLICATE"
)

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) TransactionResultCode

func (fte *FailedTransactionError) TransactionResultCode() (result string, err error)

type Listener

type Listener chan<- Result

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

type MalformedTransactionError

type MalformedTransactionError struct {
	EnvelopeXDR string
}

MalformedTransactionError represent an error that occurred because a TransactionEnvelope could not be decoded from the provided data.

func (*MalformedTransactionError) Error

func (err *MalformedTransactionError) Error() string

type MockResultProvider

type MockResultProvider struct {
	Results []Result
}

MockResultProvider is a test helper that simplements the ResultProvider interface

func (*MockResultProvider) ResultByHash

func (results *MockResultProvider) ResultByHash(ctx context.Context, hash string) (r Result)

ResultByHash implements `txsub.ResultProvider`

type MockSequenceProvider

type MockSequenceProvider struct {
	Results map[string]uint64
	Err     error
}

MockSequenceProvider is a test helper that simplements the SequenceProvider interface

func (*MockSequenceProvider) Get

func (results *MockSequenceProvider) Get(addresses []string) (map[string]uint64, error)

Get implements `txsub.SequenceProvider`

type MockSubmitter

type MockSubmitter struct {
	R              SubmissionResult
	WasSubmittedTo bool
}

MockSubmitter is a test helper that simplements the Submitter interface

func (*MockSubmitter) Submit

func (sub *MockSubmitter) Submit(ctx context.Context, env string) SubmissionResult

Submit implements `txsub.Submitter`

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, 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 transaction hash to which this result corresponds
	Hash string

	// The ledger sequence in which the transaction this result represents was
	// applied
	LedgerSequence int32

	// The base64-encoded TransactionEnvelope for the transaction this result
	// corresponds to
	EnvelopeXDR string

	// The base64-encoded TransactionResult for the transaction this result
	// corresponds to
	ResultXDR string

	// The base64-encoded TransactionMeta for the transaction this result
	// corresponds to
	ResultMetaXDR string
}

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

type ResultProvider

type ResultProvider interface {
	// Look up a result by transaction hash
	ResultByHash(context.Context, string) Result
}

ResultProvider represents an abstract store that can lookup Result objects by transaction hash or by [address,sequence] pairs. A ResultProvider is used within the transaction submission system to decide whether a submission should be submitted to the backing stellar-core process, as well as looking up the status of each transaction in the open submission list at each tick (i.e. ledger close)

type SequenceProvider

type SequenceProvider interface {
	// Look up a sequence by address
	Get(addresses []string) (map[string]uint64, error)
}

SequenceProvider represents an abstract store that can lookup the current sequence number of an account. It is used by the SequenceLock to

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 {
	Pending           OpenSubmissionList
	Results           ResultProvider
	Sequences         SequenceProvider
	Submitter         Submitter
	SubmissionQueue   *sequence.Manager
	NetworkPassphrase string
	SubmissionTimeout time.Duration

	Metrics struct {
		// SubmissionTimer exposes timing metrics about the rate and latency of
		// submissions to stellar-core
		SubmissionTimer metrics.Timer

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

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

		// FailedSubmissionsMeter tracks the rate of failed transactions that have
		// been submitted to this process
		FailedSubmissionsMeter metrics.Meter

		// SuccessfulSubmissionsMeter tracks the rate of successful transactions that
		// have been submitted to this process
		SuccessfulSubmissionsMeter metrics.Meter
	}
	// 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) Submit

func (sys *System) Submit(ctx context.Context, env string) (result <-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.