host

Documentation

Index

• Constants
• type BasicErrHealthStatus
  • func (l *BasicErrHealthStatus) Message() string
  • func (l *BasicErrHealthStatus) OK() bool
• type BatchMsg
• type BlockStream
• type EnclaveService
• type HealthCheck
• type HealthStatus
• type Host
• type Identity
  • func NewIdentity(cfg *config.HostConfig) Identity
• type L1BlockHandler
• type L1BlockRepository
• type L1Publisher
• type L1RepoService
• type L2BatchHandler
• type L2BatchRepository
• type LogSubscriptionManager
• type P2P
• type P2PBatchHandler
• type P2PBatchRequestHandler
• type P2PHostService
• type P2PTxHandler
• type Service

Constants

const (
	P2PName                    = "p2p"
	L1BlockRepositoryName      = "l1-block-repo"
	L1PublisherName            = "l1-publisher"
	L2BatchRepositoryName      = "l2-batch-repo"
	EnclaveServiceName         = "enclaves"
	LogSubscriptionServiceName = "log-subs"
)

service names - these are the keys used to register known services with the host

Types

type BasicErrHealthStatus

type BasicErrHealthStatus struct {
	ErrMsg string
}

BasicErrHealthStatus is a simple health status implementation, if the ErrMsg is non-empty then OK() returns false

func (*BasicErrHealthStatus) Message

func (l *BasicErrHealthStatus) Message() string

func (*BasicErrHealthStatus) OK

func (l *BasicErrHealthStatus) OK() bool

type BatchMsg

type BatchMsg struct {
	Batches []*common.ExtBatch // The batches being sent.
	IsLive  bool               // true if these batches are being sent as new, false if in response to a p2p request
}

type BlockStream

type BlockStream struct {
	Stream <-chan *types.Block // the channel which will receive the consecutive, canonical blocks
	Stop   func()              // function to permanently stop the stream and clean up any associated processes/resources
}

type EnclaveService

type EnclaveService interface {
	// LookupBatchBySeqNo is used to fetch batch data from the enclave - it is only used as a fallback for the sequencer
	// host if it's missing a batch (other host services should use L2Repo to fetch batch data)
	LookupBatchBySeqNo(seqNo *big.Int) (*common.ExtBatch, error)

	// GetEnclaveClient returns an enclave client // todo (@matt) we probably don't want to expose this
	GetEnclaveClient() common.Enclave

	// SubmitAndBroadcastTx submits an encrypted transaction to the enclave, and broadcasts it to other hosts on the network (in particular, to the sequencer)
	SubmitAndBroadcastTx(encryptedParams common.EncryptedParamsSendRawTx) (*responses.RawTx, error)

	Subscribe(id rpc.ID, encryptedLogSubscription common.EncryptedParamsLogSubscription) error
	Unsubscribe(id rpc.ID) error
}

EnclaveService provides access to the host enclave(s), it monitors and manages the states of the enclaves, so it can help with failover, gate-keeping (throttling/load-balancing) and circuit-breaking when the enclave is not available

type HealthCheck

type HealthCheck struct {
	OverallHealth bool
	Errors        []string
}

HealthCheck is the object returned by the host API with the Health of the Node

type HealthStatus

type HealthStatus interface {
	OK() bool
	Message() string
}

HealthStatus is an interface supported by all Services on the host

type Host

type Host interface {
	Config() *config.HostConfig
	DB() *db.DB
	EnclaveClient() common.Enclave

	// Start initializes the main loop of the host.
	Start() error
	// SubmitAndBroadcastTx submits an encrypted transaction to the enclave, and broadcasts it to the other hosts on the network.
	SubmitAndBroadcastTx(encryptedParams common.EncryptedParamsSendRawTx) (*responses.RawTx, error)
	// Subscribe feeds logs matching the encrypted log subscription to the matchedLogs channel.
	Subscribe(id rpc.ID, encryptedLogSubscription common.EncryptedParamsLogSubscription, matchedLogs chan []byte) error
	// Unsubscribe terminates a log subscription between the host and the enclave.
	Unsubscribe(id rpc.ID)
	// Stop gracefully stops the host execution.
	Stop() error

	// HealthCheck returns the health status of the host + enclave + db
	HealthCheck() (*HealthCheck, error)

	// ObscuroConfig returns the info of the Obscuro network
	ObscuroConfig() (*common.ObscuroNetworkInfo, error)
}

Host is the half of the Obscuro node that lives outside the enclave.

type Identity

type Identity struct {
	ID               gethcommon.Address
	P2PPublicAddress string
	IsGenesis        bool
	IsSequencer      bool
}

func NewIdentity

func NewIdentity(cfg *config.HostConfig) Identity

type L1BlockHandler

type L1BlockHandler interface {
	// HandleBlock will be called in a new goroutine for each new block as it arrives
	HandleBlock(block *types.Block)
}

L1BlockHandler is an interface for receiving new blocks from the repository as they arrive

type L1BlockRepository

type L1BlockRepository interface {
	// Subscribe will register a block handler to receive new blocks as they arrive, returns unsubscribe func
	Subscribe(handler L1BlockHandler) func()

	FetchBlockByHeight(height *big.Int) (*types.Block, error)
	// FetchNextBlock returns the next canonical block after a given block hash
	// It returns the new block, a bool which is true if the block is the current L1 head and a bool if the block is on a different fork to prevBlock
	FetchNextBlock(prevBlock gethcommon.Hash) (*types.Block, bool, error)
	// FetchObscuroReceipts returns the receipts for a given L1 block
	FetchObscuroReceipts(block *common.L1Block) (types.Receipts, error)
}

L1BlockRepository provides an interface for the host to request L1 block data (live-streaming and historical)

type L1Publisher

type L1Publisher interface {
	// InitializeSecret will send a management contract transaction to initialize the network with the generated secret
	InitializeSecret(attestation *common.AttestationReport, encSecret common.EncryptedSharedEnclaveSecret) error
	// RequestSecret will send a management contract transaction to request a secret from the enclave, returning the L1 head at time of sending
	RequestSecret(report *common.AttestationReport) (gethcommon.Hash, error)
	// ExtractObscuroRelevantTransactions will return all Obscuro relevant tx from an L1 block
	ExtractObscuroRelevantTransactions(block *types.Block) ([]*ethadapter.L1RespondSecretTx, []*ethadapter.L1RollupTx, []*ethadapter.L1SetImportantContractsTx)
	// PublishRollup will create and publish a rollup tx to the management contract - fire and forget we don't wait for receipt
	// todo (#1624) - With a single sequencer, it is problematic if rollup publication fails; handle this case better
	PublishRollup(producedRollup *common.ExtRollup)
	// PublishSecretResponse will create and publish a secret response tx to the management contract - fire and forget we don't wait for receipt
	PublishSecretResponse(secretResponse *common.ProducedSecretResponse) error

	FetchLatestPeersList() ([]string, error)

	FetchLatestSeqNo() (*big.Int, error)

	// GetImportantContracts returns a (cached) record of addresses of the important network contracts
	GetImportantContracts() map[string]gethcommon.Address
	// ResyncImportantContracts will fetch the latest important contracts from the management contract, update the cache
	ResyncImportantContracts() error
}

L1Publisher provides an interface for the host to interact with Obscuro data (management contract etc.) on L1

type L1RepoService

type L1RepoService interface {
	Service
	L1BlockRepository
}

type L2BatchHandler

type L2BatchHandler interface {
	// HandleBatch will be called in a new goroutine for each new batch as it arrives
	HandleBatch(batch *common.ExtBatch)
}

L2BatchHandler is an interface for receiving new batches from the publisher as they arrive

type L2BatchRepository

type L2BatchRepository interface {
	// Subscribe will register a batch handler to receive new batches as they arrive
	Subscribe(handler L2BatchHandler)

	FetchBatchBySeqNo(seqNo *big.Int) (*common.ExtBatch, error)

	// AddBatch is used to notify the repository of a new batch, e.g. from the enclave when seq produces one or a rollup is consumed
	// Note: it is fine to add batches that the repo already has, it will just ignore them
	AddBatch(batch *common.ExtBatch) error
}

L2BatchRepository provides an interface for the host to request L2 batch data (live-streaming and historical)

type LogSubscriptionManager

type LogSubscriptionManager interface {
	Subscribe(id rpc.ID, encryptedLogSubscription common.EncryptedParamsLogSubscription, matchedLogsCh chan []byte) error
	Unsubscribe(id rpc.ID)
	SendLogsToSubscribers(result *common.EncryptedSubscriptionLogs)
}

LogSubscriptionManager provides an interface for the host to manage log subscriptions

type P2P

type P2P interface {
	// BroadcastBatches sends live batch(es) to every other node on the network
	BroadcastBatches(batches []*common.ExtBatch) error
	// SendTxToSequencer sends the encrypted transaction to the sequencer.
	SendTxToSequencer(tx common.EncryptedTx) error

	// RequestBatchesFromSequencer asynchronously requests batches from the sequencer, from the given sequence number
	RequestBatchesFromSequencer(fromSeqNo *big.Int) error
	// RespondToBatchRequest sends the requested batches to the requesting peer
	RespondToBatchRequest(requestID string, batches []*common.ExtBatch) error

	// SubscribeForBatches will register a handler to receive new batches from peers, returns unsubscribe func
	SubscribeForBatches(handler P2PBatchHandler) func()
	// SubscribeForTx will register a handler to receive new transactions from peers, returns unsubscribe func
	SubscribeForTx(handler P2PTxHandler) func()
	// SubscribeForBatchRequests will register a handler to receive new batch requests from peers, returns unsubscribe func
	// todo (@matt) feels a bit weird to have this in this interface since it relates to serving data rather than receiving
	SubscribeForBatchRequests(handler P2PBatchRequestHandler) func()

	// RefreshPeerList notifies the P2P service that its peer list might be out-of-date and it should resync
	RefreshPeerList()
}

P2P provides an interface for the host to interact with the P2P network

type P2PBatchHandler

type P2PBatchHandler interface {
	// HandleBatches will be called in a new goroutine for batches that arrive
	HandleBatches(batch []*common.ExtBatch, isLive bool)
}

P2PBatchHandler is an interface for receiving new batches from the P2P network as they arrive

type P2PBatchRequestHandler

type P2PBatchRequestHandler interface {
	// HandleBatchRequest will be called in a new goroutine for each new batch request as it arrives
	HandleBatchRequest(requestID string, fromSeqNo *big.Int)
}

type P2PHostService

type P2PHostService interface {
	Service
	P2P
}

type P2PTxHandler

type P2PTxHandler interface {
	// HandleTransaction will be called in a new goroutine for each new tx as it arrives
	HandleTransaction(tx common.EncryptedTx)
}

P2PTxHandler is an interface for receiving new transactions from the P2P network as they arrive

type Service

type Service interface {
	Start() error
	Stop() error
	HealthStatus() HealthStatus
}

Service interface allows the host to manage all services in a generic way Note: Services may depend on other services but they shouldn't use them during construction, only when 'Start()' is called. They should be resilient to services availability, because the construction ordering is not guaranteed.