txhandler

Documentation

Index

• type ManagedTxEventHandler
• type NextNonceCallback
• type RichQuery
• type SortDirection
• type Toolkit
• type TransactionHandler
• type TransactionHistoryPersistence
• type TransactionMetrics
• type TransactionPersistence

Types

type ManagedTxEventHandler

type ManagedTxEventHandler interface {
	HandleEvent(ctx context.Context, e apitypes.ManagedTransactionEvent) error
}

Handler checks received transaction process events and dispatch them to an event manager accordingly.

type NextNonceCallback

type NextNonceCallback func(ctx context.Context, signer string) (uint64, error)

type RichQuery

type RichQuery interface {
	ListStreams(ctx context.Context, filter ffapi.AndFilter) ([]*apitypes.EventStream, *ffapi.FilterResult, error)
	ListListeners(ctx context.Context, filter ffapi.AndFilter) ([]*apitypes.Listener, *ffapi.FilterResult, error)
	ListTransactions(ctx context.Context, filter ffapi.AndFilter) ([]*apitypes.ManagedTX, *ffapi.FilterResult, error)
	ListTransactionConfirmations(ctx context.Context, txID string, filter ffapi.AndFilter) ([]*apitypes.ConfirmationRecord, *ffapi.FilterResult, error)
	ListTransactionHistory(ctx context.Context, txID string, filter ffapi.AndFilter) ([]*apitypes.TXHistoryRecord, *ffapi.FilterResult, error)
	ListStreamListeners(ctx context.Context, streamID *fftypes.UUID, filter ffapi.AndFilter) ([]*apitypes.Listener, *ffapi.FilterResult, error)

	NewStreamFilter(ctx context.Context) ffapi.FilterBuilder
	NewListenerFilter(ctx context.Context) ffapi.FilterBuilder
	NewTransactionFilter(ctx context.Context) ffapi.FilterBuilder
	NewConfirmationFilter(ctx context.Context) ffapi.FilterBuilder
	NewTxHistoryFilter(ctx context.Context) ffapi.FilterBuilder
}

type SortDirection

type SortDirection int

const (
	SortDirectionAscending SortDirection = iota
	SortDirectionDescending
)

type Toolkit

type Toolkit struct {
	// Connector toolkit contains methods to interact with the plugged-in JSON-RPC endpoint of a Blockchain network
	Connector ffcapi.API

	// Transaction History toolkit contains methods to easily manage and set historical status of a Managed Transaction
	TXHistory TransactionHistoryPersistence

	// TransactionPersistence toolkit contains methods to persist Managed Transaction objects into the plugged-in persistence service
	TXPersistence TransactionPersistence

	// When a rich-query enabled Database is available (PSQL) the full rich query interface for all objects is passed to the policy engine.
	// If not available, this will be nil.
	RichQuery RichQuery

	// Metric toolkit contains methods to emit Managed Transaction specific metrics using the plugged-in metrics service
	MetricsManager TransactionMetrics

	// Event Handler toolkit contains methods to handle a defined set of events when processing managed transactions
	EventHandler ManagedTxEventHandler
}

type TransactionHandler

type TransactionHandler interface {

	// Init - setting a set of initialized toolkit plugins in the constructed transaction handler object. Safe checks & initialization
	//        can take place inside this function as well. It also enables toolkit plugins to be able to embed a reference to its parent
	//        transaction handler instance.
	Init(ctx context.Context, toolkit *Toolkit)

	// Start - starting the transaction handler to handle inbound events.
	// It takes in a context, of which upon cancellation will stop the transaction handler.
	// It returns a read-only channel. When this channel gets closed, it indicates transaction handler has been stopped gracefully.
	// It returns an error when failed to start.
	Start(ctx context.Context) (done <-chan struct{}, err error)

	// Event handling functions
	// Instructional events:
	// HandleNewTransaction - handles event of adding new transactions onto blockchain
	HandleNewTransaction(ctx context.Context, txReq *apitypes.TransactionRequest) (mtx *apitypes.ManagedTX, submissionRejected bool, err error)
	// HandleNewContractDeployment - handles event of adding new smart contract deployment onto blockchain
	HandleNewContractDeployment(ctx context.Context, txReq *apitypes.ContractDeployRequest) (mtx *apitypes.ManagedTX, submissionRejected bool, err error)
	// HandleCancelTransaction - handles event of cancelling a managed transaction
	HandleCancelTransaction(ctx context.Context, txID string) (mtx *apitypes.ManagedTX, err error)
	// HandleSuspendTransaction - handles event of suspending a managed transaction
	HandleSuspendTransaction(ctx context.Context, txID string) (mtx *apitypes.ManagedTX, err error)
	// HandleResumeTransaction - handles event of resuming a suspended managed transaction
	HandleResumeTransaction(ctx context.Context, txID string) (mtx *apitypes.ManagedTX, err error)

	// Informational events:
	// HandleTransactionConfirmations - handles confirmations of blockchain transactions for a managed transaction
	HandleTransactionConfirmations(ctx context.Context, txID string, notification *apitypes.ConfirmationsNotification) (err error)
	// HandleTransactionReceiptReceived - handles receipt of blockchain transactions for a managed transaction
	HandleTransactionReceiptReceived(ctx context.Context, txID string, receipt *ffcapi.TransactionReceiptResponse) (err error)
}

Transaction Handler owns the lifecycle of ManagedTransaction records Transaction Manager delegates all transaction specific operations to transaction apart from the triggers (REST API call for actions, Event stream for events) of those operations. This design allows the Transaction Handler to apply customized logic at different stages of transaction life cycles. The Transaction Handler interface consists of x important responsibilities: 1. Functions for handling its own lifecycle. (e.g. Init, Start)

2. Functions for handling events: When implementing functions in this category, developers need to keep concurrency in mind. Because multiple invocations of a single function can be process in parallel in any given time, it's recommended to use channels to ensure they are not blocking each other. - inbound events: these events are received by transaction handler a. instructional events: transaction handler need to implement the logic to make those event happen on blockchain. (e.g. creating a new transaction) b. informational events: transaction handler need to update its own record when an event has already happened to a related blockchain transaction of its managed transaction - outbound events: these events are emitted by transaction handler. apitypes.ManagedTransactionEventType contains a list of managed transaction events that can be emitted by transaction handler.

type TransactionHistoryPersistence

type TransactionHistoryPersistence interface {
	AddSubStatusAction(ctx context.Context, txID string, subStatus apitypes.TxSubStatus, action apitypes.TxAction, info *fftypes.JSONAny, err *fftypes.JSONAny) error
}

type TransactionMetrics

type TransactionMetrics interface {
	// functions for declaring new metrics
	InitTxHandlerCounterMetric(ctx context.Context, metricName string, helpText string, withDefaultLabels bool)
	InitTxHandlerCounterMetricWithLabels(ctx context.Context, metricName string, helpText string, labelNames []string, withDefaultLabels bool)
	InitTxHandlerGaugeMetric(ctx context.Context, metricName string, helpText string, withDefaultLabels bool)
	InitTxHandlerGaugeMetricWithLabels(ctx context.Context, metricName string, helpText string, labelNames []string, withDefaultLabels bool)
	InitTxHandlerHistogramMetric(ctx context.Context, metricName string, helpText string, buckets []float64, withDefaultLabels bool)
	InitTxHandlerHistogramMetricWithLabels(ctx context.Context, metricName string, helpText string, buckets []float64, labelNames []string, withDefaultLabels bool)
	InitTxHandlerSummaryMetric(ctx context.Context, metricName string, helpText string, withDefaultLabels bool)
	InitTxHandlerSummaryMetricWithLabels(ctx context.Context, metricName string, helpText string, labelNames []string, withDefaultLabels bool)

	// functions for use existing metrics
	SetTxHandlerGaugeMetric(ctx context.Context, metricName string, number float64, defaultLabels *metric.FireflyDefaultLabels)
	SetTxHandlerGaugeMetricWithLabels(ctx context.Context, metricName string, number float64, labels map[string]string, defaultLabels *metric.FireflyDefaultLabels)
	IncTxHandlerCounterMetric(ctx context.Context, metricName string, defaultLabels *metric.FireflyDefaultLabels)
	IncTxHandlerCounterMetricWithLabels(ctx context.Context, metricName string, labels map[string]string, defaultLabels *metric.FireflyDefaultLabels)
	ObserveTxHandlerHistogramMetric(ctx context.Context, metricName string, number float64, defaultLabels *metric.FireflyDefaultLabels)
	ObserveTxHandlerHistogramMetricWithLabels(ctx context.Context, metricName string, number float64, labels map[string]string, defaultLabels *metric.FireflyDefaultLabels)
	ObserveTxHandlerSummaryMetric(ctx context.Context, metricName string, number float64, defaultLabels *metric.FireflyDefaultLabels)
	ObserveTxHandlerSummaryMetricWithLabels(ctx context.Context, metricName string, number float64, labels map[string]string, defaultLabels *metric.FireflyDefaultLabels)
}

type TransactionPersistence

type TransactionPersistence interface {
	ListTransactionsByCreateTime(ctx context.Context, after *apitypes.ManagedTX, limit int, dir SortDirection) ([]*apitypes.ManagedTX, error)         // reverse create time order
	ListTransactionsByNonce(ctx context.Context, signer string, after *fftypes.FFBigInt, limit int, dir SortDirection) ([]*apitypes.ManagedTX, error) // reverse nonce order within signer
	ListTransactionsPending(ctx context.Context, afterSequenceID string, limit int, dir SortDirection) ([]*apitypes.ManagedTX, error)                 // reverse insertion order, only those in pending state
	GetTransactionByID(ctx context.Context, txID string) (*apitypes.ManagedTX, error)
	GetTransactionByIDWithStatus(ctx context.Context, txID string, history bool) (*apitypes.TXWithStatus, error)
	GetTransactionByNonce(ctx context.Context, signer string, nonce *fftypes.FFBigInt) (*apitypes.ManagedTX, error)
	InsertTransactionPreAssignedNonce(ctx context.Context, tx *apitypes.ManagedTX) error
	InsertTransactionWithNextNonce(ctx context.Context, tx *apitypes.ManagedTX, lookupNextNonce NextNonceCallback) error
	UpdateTransaction(ctx context.Context, txID string, updates *apitypes.TXUpdates) error
	DeleteTransaction(ctx context.Context, txID string) error

	GetTransactionReceipt(ctx context.Context, txID string) (receipt *ffcapi.TransactionReceiptResponse, err error)
	SetTransactionReceipt(ctx context.Context, txID string, receipt *ffcapi.TransactionReceiptResponse) error

	GetTransactionConfirmations(ctx context.Context, txID string) ([]*apitypes.Confirmation, error)
	AddTransactionConfirmations(ctx context.Context, txID string, clearExisting bool, confirmations ...*apitypes.Confirmation) error
}