github.com/decred/dcrlnd@v0.7.6/watchtower/lookout/interface.go (about)

     1  package lookout
     2  
     3  import (
     4  	"github.com/decred/dcrd/chaincfg/chainhash"
     5  	"github.com/decred/dcrd/wire"
     6  	"github.com/decred/dcrlnd/chainntnfs"
     7  	"github.com/decred/dcrlnd/watchtower/blob"
     8  	"github.com/decred/dcrlnd/watchtower/wtdb"
     9  )
    10  
    11  // Service abstracts the lookout functionality, supporting the ability to start
    12  // and stop. All communication and actions are driven via the database or chain
    13  // events.
    14  type Service interface {
    15  	// Start safely starts up the Interface.
    16  	Start() error
    17  
    18  	// Stop safely stops the Interface.
    19  	Stop() error
    20  }
    21  
    22  // BlockFetcher supports the ability to fetch blocks from the backend or
    23  // network.
    24  type BlockFetcher interface {
    25  	// GetBlock fetches the block given the target block hash.
    26  	GetBlock(*chainhash.Hash) (*wire.MsgBlock, error)
    27  }
    28  
    29  // DB abstracts the required persistent calls expected by the lookout. DB
    30  // provides the ability to search for state updates that correspond to breach
    31  // transactions confirmed in a particular block.
    32  type DB interface {
    33  	// GetLookoutTip returns the last block epoch at which the tower
    34  	// performed a match. If no match has been done, a nil epoch will be
    35  	// returned.
    36  	GetLookoutTip() (*chainntnfs.BlockEpoch, error)
    37  
    38  	// QueryMatches searches its database for any state updates matching the
    39  	// provided breach hints. If any matches are found, they will be
    40  	// returned along with encrypted blobs so that justice can be exacted.
    41  	QueryMatches([]blob.BreachHint) ([]wtdb.Match, error)
    42  
    43  	// SetLookoutTip writes the best epoch for which the watchtower has
    44  	// queried for breach hints.
    45  	SetLookoutTip(*chainntnfs.BlockEpoch) error
    46  }
    47  
    48  // EpochRegistrar supports the ability to register for events corresponding to
    49  // newly created blocks.
    50  type EpochRegistrar interface {
    51  	// RegisterBlockEpochNtfn registers for a new block epoch subscription.
    52  	// The implementation must support historical dispatch, starting from
    53  	// the provided chainntnfs.BlockEpoch when it is non-nil. The
    54  	// notifications should be delivered in-order, and deliver reorged
    55  	// blocks.
    56  	RegisterBlockEpochNtfn(
    57  		*chainntnfs.BlockEpoch) (*chainntnfs.BlockEpochEvent, error)
    58  }
    59  
    60  // Punisher handles the construction and publication of justice transactions
    61  // once they have been detected by the Service.
    62  type Punisher interface {
    63  	// Punish accepts a JusticeDescriptor, constructs the justice
    64  	// transaction, and publishes the transaction to the network so it can
    65  	// be mined. The second parameter is a quit channel so that long-running
    66  	// operations required to track the confirmation of the transaction can
    67  	// be canceled on shutdown.
    68  	Punish(*JusticeDescriptor, <-chan struct{}) error
    69  }