relay

README

relay package is a high level controller that implements whole mechanism of relaying a query

This high level logic is encapsulated in Relayer struct

Documentation

Index

• Constants
• func GetNeutronChain(logger *zap.Logger, cfg *config.NeutronChainConfig, chainID string) (*relayer.Chain, error)
• func GetTargetChain(logger *zap.Logger, cfg *config.TargetChainConfig, chainID string) (*relayer.Chain, error)
• type ChainClient
• type ErrSubmitTxProofCritical
  • func NewErrSubmitTxProofCritical(details error) ErrSubmitTxProofCritical
  • func (e ErrSubmitTxProofCritical) Error() string
• type KVProcessor
• type MessageKV
• type MessageTX
• type PendingSubmittedTxInfo
• type Relayer
  • func NewRelayer(cfg config.NeutronQueryRelayerConfig, txQuerier TXQuerier, store Storage, ...) *Relayer
  • func (r *Relayer) Run(ctx context.Context, queriesTasksQueue <-chan neutrontypes.RegisteredQuery, ...) error
• type Storage
• type SubmittedTxInfo
• type SubmittedTxStatus
• type Submitter
• type Subscriber
• type TXProcessor
• type TXQuerier
• type Transaction
• type TrustedHeaderFetcher
• type TxSubmitChecker
• type UnsuccessfulTxInfo

Constants

const TxHeight = "tx.height"

TxHeight describes tendermint filter by tx.height that we use to get only actual txs

Functions

func GetNeutronChain

func GetNeutronChain(logger *zap.Logger, cfg *config.NeutronChainConfig, chainID string) (*relayer.Chain, error)

func GetTargetChain

func GetTargetChain(logger *zap.Logger, cfg *config.TargetChainConfig, chainID string) (*relayer.Chain, error)

Types

type ChainClient

type ChainClient interface {
	BlockResults(ctx context.Context, height *int64) (*ctypes.ResultBlockResults, error)
	TxSearch(ctx context.Context, query string, prove bool, page, perPage *int, orderBy string) (*ctypes.ResultTxSearch, error)
}

ChainClient is a minimal interface for tendermint client

type ErrSubmitTxProofCritical

type ErrSubmitTxProofCritical struct {
	// contains filtered or unexported fields
}

ErrSubmitTxProofCritical is an error type that represents errors critical for the Relayer.

func NewErrSubmitTxProofCritical

func NewErrSubmitTxProofCritical(details error) ErrSubmitTxProofCritical

NewErrSubmitTxProofCritical creates a new ErrSubmitTxProofCritical.

func (ErrSubmitTxProofCritical) Error

func (e ErrSubmitTxProofCritical) Error() string

Error implements the error interface.

type KVProcessor

type KVProcessor interface {
	// ProcessAndSubmit handles an incoming KV interchain query message. It checks whether it's time
	// to execute the query (based on the relayer's settings), queries values and proofs for the query
	// keys, and submits the result to the Neutron chain.
	ProcessAndSubmit(ctx context.Context, m *MessageKV) error
}

KVProcessor processes event query KV type. Obtains the proof for a query we need to process, and sends it to the neutron

type MessageKV

type MessageKV struct {
	// QueryId is the ID of the query.
	QueryId uint64
	// KVKeys is the query parameter that describes keys list to be retrieved.
	KVKeys types.KVKeys
}

MessageKV contains params of a KV interchain query.

type MessageTX

type MessageTX struct {
	// QueryId is the ID of the query.
	QueryId uint64
	// TransactionsFilter is the query parameter that describes conditions for transactions search.
	TransactionsFilter string
}

MessageTX contains params of a TX interchain query.

type PendingSubmittedTxInfo

type PendingSubmittedTxInfo struct {
	// QueryID is the query_id transactions was submitted for
	QueryID uint64 `json:"query_id"`
	// SubmittedTxHash is the hash of a transaction we fetched from the remote chain
	SubmittedTxHash string `json:"submitted_tx_hash"`
	// NeutronHash is the hash of the *neutron chain transaction* which is responsible for delivering remote transaction to neutron
	NeutronHash string `json:"neutron_hash"`
}

PendingSubmittedTxInfo contains information about transaction which was submitted but has to be confirmed (committed or not)

type Relayer

type Relayer struct {
	// contains filtered or unexported fields
}

Relayer is controller for the whole app: 1. takes events from Neutron chain 2. dispatches each query by type to fetch proof for the right query 3. submits proof for a query back to the Neutron chain

func NewRelayer

func NewRelayer(
	cfg config.NeutronQueryRelayerConfig,
	txQuerier TXQuerier,
	store Storage,
	txProcessor TXProcessor,
	kvProcessor KVProcessor,
	targetChain *relayer.Chain,
	logger *zap.Logger,
) *Relayer

func (*Relayer) Run

func (r *Relayer) Run(
	ctx context.Context,
	queriesTasksQueue <-chan neutrontypes.RegisteredQuery,
	submittedTxsTasksQueue chan PendingSubmittedTxInfo,
) error

Run starts the relaying process: subscribes on the incoming interchain query messages from the Neutron and performs the queries by interacting with the target chain and submitting them to the Neutron chain.

type Storage

type Storage interface {
	GetAllPendingTxs() ([]*PendingSubmittedTxInfo, error)
	GetAllUnsuccessfulTxs() ([]*UnsuccessfulTxInfo, error)
	GetCachedTx(queryID uint64, hash string) (*Transaction, error)
	GetLastQueryHeight(queryID uint64) (block uint64, found bool, err error)
	SetLastQueryHeight(queryID uint64, block uint64) error
	SetTxStatus(queryID uint64, hash string, neutronHash string, status SubmittedTxInfo, processedTx *Transaction) (err error)
	TxExists(queryID uint64, hash string) (exists bool, err error)
	Close() error
}

Storage is local storage we use to store queries history: known queries, know transactions and its statuses

type SubmittedTxInfo

type SubmittedTxInfo struct {
	// SubmittedTxStatus is a status of a processing state
	Status SubmittedTxStatus `json:"status"`
	// Message is some additional information which can be useful, e.g. error message for ErrorOnSubmit and ErrorOnCommit statuses
	Message string `json:"message"`
}

SubmittedTxInfo is a struct which contains status of fetched and submitted transaction

type SubmittedTxStatus

type SubmittedTxStatus string

const (
	// Submitted describes successfully submitted tx (temporary status, should be eventually replaced with Committed or ErrorOnCommit)
	Submitted SubmittedTxStatus = "Submitted"
	// ErrorOnSubmit describes error during submit operation
	ErrorOnSubmit SubmittedTxStatus = "ErrorOnSubmit"
	// Committed describes tx successfully committed into a block
	Committed SubmittedTxStatus = "Committed"
	// ErrorOnCommit describes error during commit operation
	ErrorOnCommit SubmittedTxStatus = "ErrorOnCommit"
)

type Submitter

type Submitter interface {
	SubmitKVProof(ctx context.Context, height, revision, queryId uint64, proof []*neutrontypes.StorageValue, updateClientMsg sdk.Msg) error
	SubmitTxProof(ctx context.Context, queryId uint64, proof *neutrontypes.Block) (string, error)
}

Submitter knows how to submit proof to the chain

type Subscriber

type Subscriber interface {
	// Subscribe starts sending neutrontypes.RegisteredQuery values to the tasks channel when
	// respective queries need to be updated.
	Subscribe(ctx context.Context, tasks chan neutrontypes.RegisteredQuery) error
}

Subscriber is an interface that subscribes to Neutron and provides chain data in real time.

type TXProcessor

type TXProcessor interface {
	ProcessAndSubmit(ctx context.Context, queryID uint64, tx Transaction, submittedTxsTasksQueue chan PendingSubmittedTxInfo) error
}

TXProcessor precesses transactions from a remote chain and sends them to the neutron

type TXQuerier

type TXQuerier interface {
	// SearchTransactions searches for transactions from remote chain.
	// the returned transactions channel can be closed due to one of the following cases:
	// a) All transactions from an RPC call preprocessed successfully
	// b) error encountered during the SearchTransactions method (the error will be written into the returned errs channel)
	// After a txs channel is closed, it's necessary to check the errs channel for a possible errors in a SearchTransactions goroutine
	SearchTransactions(ctx context.Context, query string) (<-chan Transaction, <-chan error)
}

TXQuerier fetches transactions from a remote chain with specified txFilter

type Transaction

type Transaction struct {
	Tx     *neutrontypes.TxValue `json:"tx"`
	Height uint64                `json:"height"`
}

Transaction represents single searched tx with height

type TrustedHeaderFetcher

type TrustedHeaderFetcher interface {
	// Fetch returns only one trusted Header for specified height
	Fetch(ctx context.Context, height uint64) (*tmclient.Header, error)
}

TrustedHeaderFetcher able to get trusted headers for a given height

type TxSubmitChecker

type TxSubmitChecker interface {
	Run(ctx context.Context, submittedTxsTasksQueue <-chan PendingSubmittedTxInfo) error
}

TxSubmitChecker runs in background and updates submitted tx statuses

type UnsuccessfulTxInfo

type UnsuccessfulTxInfo struct {
	// QueryID is the query_id transactions was submitted for
	QueryID uint64 `json:"query_id"`
	// SubmittedTxHash is the hash of a transaction we fetched from the remote chain
	SubmittedTxHash string `json:"submitted_tx_hash"`
	// NeutronHash is the hash of the *neutron chain transaction* which is responsible for delivering remote transaction to neutron
	NeutronHash string `json:"neutron_hash"`
	// ErrorTime is the time when the error was added
	ErrorTime time.Time `json:"error_time"`
	// Status is the status of unsuccessful tx
	Status SubmittedTxStatus `json:"status"`
	// Message is the more descriptive message for the error
	Message string `json:"message"`
}