chainscan

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 16, 2024 License: MIT Imports: 17 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrUnsupportedScriptType is an error returned when we attempt to
	// parse/re-compute an output script into a PkScript struct.
	ErrUnsupportedScriptType = errors.New("unsupported script type")
)

Functions

func DisableLog

func DisableLog()

DisableLog disables all library log output. Logging output is disabled by default until UseLogger is called.

func UseLogger

func UseLogger(logger slog.Logger)

UseLogger uses a specified Logger to output package logging info. This should be used in preference to SetLogWriter if the caller is also using slog.

Types

type BlockConnectedEvent

type BlockConnectedEvent struct {
	Hash     chainhash.Hash
	Height   int32
	PrevHash chainhash.Hash
	CFKey    [16]byte
	Filter   *gcs.FilterV2
	Header   *wire.BlockHeader
}

func (BlockConnectedEvent) BlockHash

func (e BlockConnectedEvent) BlockHash() *chainhash.Hash

func (BlockConnectedEvent) BlockHeader added in v0.6.0

func (e BlockConnectedEvent) BlockHeader() *wire.BlockHeader

func (BlockConnectedEvent) BlockHeight

func (e BlockConnectedEvent) BlockHeight() int32

func (BlockConnectedEvent) PrevBlockHash

func (e BlockConnectedEvent) PrevBlockHash() *chainhash.Hash

type BlockDisconnectedEvent

type BlockDisconnectedEvent struct {
	Hash     chainhash.Hash
	Height   int32
	PrevHash chainhash.Hash
	Header   *wire.BlockHeader
}

func (BlockDisconnectedEvent) BlockHash

func (e BlockDisconnectedEvent) BlockHash() *chainhash.Hash

func (BlockDisconnectedEvent) BlockHeader added in v0.6.0

func (e BlockDisconnectedEvent) BlockHeader() *wire.BlockHeader

func (BlockDisconnectedEvent) BlockHeight

func (e BlockDisconnectedEvent) BlockHeight() int32

func (BlockDisconnectedEvent) PrevBlockHash

func (e BlockDisconnectedEvent) PrevBlockHash() *chainhash.Hash

type ChainEvent

type ChainEvent interface {
	BlockHash() *chainhash.Hash
	BlockHeight() int32
	PrevBlockHash() *chainhash.Hash
	BlockHeader() *wire.BlockHeader
	// contains filtered or unexported methods
}

type ChainSource

type ChainSource interface {
	GetBlock(context.Context, *chainhash.Hash) (*wire.MsgBlock, error)
	CurrentTip(context.Context) (*chainhash.Hash, int32, error)
}

type ErrBlockAfterTip

type ErrBlockAfterTip struct {
	Height int32
}

ErrBlockAfterTip should be returned by chains when the requested block is after the currently known tip. Scanners may choose not to fail their run if this specific error is returned.

func (ErrBlockAfterTip) Error

func (e ErrBlockAfterTip) Error() string

func (ErrBlockAfterTip) Is

func (e ErrBlockAfterTip) Is(err error) bool

type Event

type Event struct {
	BlockHeight  int32
	BlockHash    chainhash.Hash
	TxIndex      int32
	Tx           *wire.MsgTx
	Index        int32
	Tree         int8
	MatchedField MatchField
}

func (Event) String

func (e Event) String() string

type FindFunc

type FindFunc func(Target, ...Option) error

type FoundCallback

type FoundCallback func(Event, FindFunc)

type Historical

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

func NewHistorical

func NewHistorical(chain HistoricalChainSource) *Historical

func (*Historical) Find

func (h *Historical) Find(tgt Target, opts ...Option) error

func (*Historical) FindMany

func (h *Historical) FindMany(targets []TargetAndOptions) error

FindMany attempts to search for many targets at once. This is better than making individual calls to Find() when they should be searched for at the same starting height since all specified targets are guaranteed to be included in the same search batch.

This function is safe for concurrent calls in multiple goroutines, including inside functions specified with WithFoundCallback() options.

func (*Historical) Run

func (h *Historical) Run(ctx context.Context) error

type HistoricalChainSource

type HistoricalChainSource interface {
	ChainSource

	// GetCFilter MUST return the block hash, key and filter for the given
	// mainchain block height.
	//
	// If a height higher than the current mainchain tip is specified, the
	// chain source MUST return ErrBlockAfterTip so that the historical
	// scanner will correctly handle targets specified with an invalid
	// ending height.
	GetCFilter(context.Context, int32) (*chainhash.Hash, [16]byte, *gcs.FilterV2, error)
}

type MatchField

type MatchField uint8
const (
	MatchTxIn MatchField = 1 << iota
	MatchTxOut
)

func (MatchField) String

func (m MatchField) String() string

type Option

type Option func(*target)

func WithCancelChan

func WithCancelChan(c <-chan struct{}) Option

WithCancelChan allows a caller to specify a channel that, once closed, removes the provided target from being scanned for.

func WithCompleteChan

func WithCompleteChan(c chan struct{}) Option

WithCompleteChan allows a caller to specify a channel that gets closed once the endHeight was reached for the target.

func WithEndHeight

func WithEndHeight(endHeight int32) Option

WithEndHeight allows a caller to specify a block height after which scans should no longer happen.

func WithFoundCallback

func WithFoundCallback(cb FoundCallback) Option

WithFoundCallback allows a caller to specify a callback that is called synchronously in relation to a scanner when the related target is found in a block.

This callback is called in the same goroutine that performs scans, therefore it is *NOT* safe to perform any receives or sends on channels that also affect this or other target's searches (such as waiting for a StartWatchingHeight, FoundChan or other signals).

It is also generally not advised to perform lengthy operations inside this callback since it blocks all other searches from progressing.

This callback is intended to be used in situations where the caller needs to add new targets to search for as a result of having found a match within a block.

There are two ways to add addicional targets during the execution of the foundCallback:

  1. Via additional Find() calls of the scanner (which _are_ safe for direct calling by the foundCallback). This allows callers to start to search for additional targets on any block (either further along the chain or in the past).

  2. Via the second argument to the foundCallback. That function can add targets to search for, starting at the _current_ block, transaction list and transaction index. This is useful (for example) when detecting a specific script was used in an output should trigger a search for other scripts including in the same block. Note that when adding new targets using this method, they MUST include a WithStartingHeight(event.BlockHeight+1) option (even though the search will also be carried in later transactions of the current block being scanned).

The callback function may be called multiple times for a given target.

func WithFoundChan

func WithFoundChan(c chan<- Event) Option

WithFoundChan allows a caller to specify a channel that receives events when a match for a given target is found. This event is called concurrently with the rest of the search process.

Callers are responsible for draining this channel once the search completes, otherwise data may leak. They should also ensure the channel is _not_ closed until the search completes, otherwise the scanner may panic.

The channel may be sent to multiple times.

func WithStartHeight

func WithStartHeight(startHeight int32) Option

WithStartHeight allows a caller to specify a block height after which a scan should trigger events when this target is found.

func WithStartWatchHeightChan

func WithStartWatchHeightChan(c chan int32) Option

WithStartWatchHeightChan allows a caller to specify a channel that receives the block height after which events will be triggered if the target is found.

type PkScript

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

PkScript is a wrapper struct around a byte array, allowing it to be used as a map index.

func ComputePkScript

func ComputePkScript(scriptVersion uint16, sigScript []byte) (PkScript, error)

ComputePkScript computes the pkScript of an transaction output by looking at the transaction input's signature script.

NOTE: Only P2PKH and P2SH redeem scripts are supported. Only the standard secp256k1 keys are supported (alternative suites are not).

func ParsePkScript

func ParsePkScript(scriptVersion uint16, pkScript []byte) (PkScript, error)

ParsePkScript parses an output script into the PkScript struct. ErrUnsupportedScriptType is returned when attempting to parse an unsupported script type.

func (PkScript) Address

func (s PkScript) Address(chainParams *chaincfg.Params) (stdaddr.Address, error)

Address encodes the script into an address for the given chain.

func (PkScript) Class

func (s PkScript) Class() stdscript.ScriptType

Class returns the script type.

func (PkScript) Equal

func (s PkScript) Equal(o *PkScript) bool

Equal returns true if the other pkscript is equal to this one (has the same values).

func (PkScript) Script

func (s PkScript) Script() []byte

Script returns the script as a byte slice without any padding. This is a copy of the original script, therefore it's safe for modification.

func (PkScript) ScriptVersion

func (s PkScript) ScriptVersion() uint16

ScriptVersion returns the recorded script version of the pkscript.

func (PkScript) String

func (s PkScript) String() string

String returns a hex-encoded string representation of the script.

type Target

type Target interface {
	// contains filtered or unexported methods
}

Target represents the desired target (outpoint, pkscript, etc) of a search.

NOTE: targets are *not* safe for reuse for multiple searches.

func ConfirmedOutPoint

func ConfirmedOutPoint(out wire.OutPoint, version uint16, pkscript []byte) Target

ConfirmedOutPoint tries to match against a TxOut that spends the provided script but only as long as the output itself fulfills the specified outpoint (that is, the output is created in the transaction specified by out.Hash and at the out.Index position).

func ConfirmedScript

func ConfirmedScript(version uint16, pkscript []byte) Target

func ConfirmedTransaction

func ConfirmedTransaction(txh chainhash.Hash, version uint16, pkscript []byte) Target

func SpentOutPoint

func SpentOutPoint(out wire.OutPoint, version uint16, pkscript []byte) Target

SpentOutPoint tries to match against a TxIn that spends the given outpoint and pkscript combination.

NOTE: If the provided pkscript does _not_ actually correspond to the outpoint, the search may never trigger a match.

func SpentScript

func SpentScript(version uint16, pkscript []byte) Target

SpentScript tries to match against a TxIn that spends the provided script.

NOTE: only version 0 scripts are currently supported. Also, the match is a best effort one, based on the "shape" of the signature script of the txin. See ComputePkScript for details on supported script types.

type TargetAndOptions

type TargetAndOptions struct {
	Target  Target
	Options []Option
}

type TipChainSource

type TipChainSource interface {
	ChainSource

	// ChainEvents MUST return a channel that is sent ChainEvent's until
	// the passed context is canceled.
	ChainEvents(context.Context) <-chan ChainEvent
}

TipChainSource defines the required backend functions for the TipWatcher scanner to perform its duties.

type TipWatcher

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

func NewTipWatcher

func NewTipWatcher(chain TipChainSource) *TipWatcher

func (*TipWatcher) ChainEvents

func (tw *TipWatcher) ChainEvents(ctx context.Context) <-chan ChainEvent

ChainEvents follows the same semantics as the TipChainSource ChainEvents but ensures all channels are only signalled _after_ the tip watcher has processed them.

func (*TipWatcher) Find

func (tw *TipWatcher) Find(tgt Target, opts ...Option) error

func (*TipWatcher) ForceRescan

func (tw *TipWatcher) ForceRescan(ctx context.Context, e *BlockConnectedEvent) error

func (*TipWatcher) Run

func (tw *TipWatcher) Run(ctx context.Context) error

Directories

Path Synopsis
examples

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL