indexers

package
v1.9.5 Latest Latest
Warning

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

 Go to latest Published: Nov 11, 2024 License: ISC Imports: 17 Imported by: 0

README

indexers

Build Status ISC License Doc

Package indexers implements optional block chain indexes.

These indexes are typically used to enhance the amount of information available via an RPC interface.

Supported Indexers

  • Transaction-by-hash (txbyhashidx) Index
    • Creates a mapping from the hash of each transaction to the block that contains it along with its offset and length within the serialized block
  • Address-ever-seen (existsaddridx) Index
    • Stores a key with an empty value for every address that has ever existed and was seen by the client

Removed Legacy Indexers

  • Committed Filter (cfindexparentbucket) Index
    • Stores all committed filters and committed filter headers for all blocks in the main chain
  • Transaction-by-address (txbyaddridx) Index
    • Creates a mapping from every address to all transactions which either credit or debit the address
    • Requires the transaction-by-hash index

Installation and Updating

This package is internal and therefore is neither directly installed nor needs to be manually updated.

License

Package indexers is licensed under the copyfree ISC License.

Documentation

Overview

Package indexers implements optional block chain indexes.

Index

Constants

View Source 
const (
	// ErrUnsupportedAddressType indicates an unsupported address type.
	ErrUnsupportedAddressType = ErrorKind("ErrUnsupportedAddressType")

	// ErrConnectBlock indicates an error indexing a connected block.
	ErrConnectBlock = ErrorKind("ErrConnectBlock")

	// ErrDisconnectBlock indicates an error indexing a disconnected block.
	ErrDisconnectBlock = ErrorKind("ErrDisconnectBlock")

	// ErrRemoveSpendDependency indicates a spend dependency removal error.
	ErrRemoveSpendDependency = ErrorKind("ErrRemoveSpendDependency")

	// ErrInvalidNotificationType indicates an invalid indexer notification type.
	ErrInvalidNotificationType = ErrorKind("ErrInvalidNotificationType")

	// ErrInterruptRequested indicates an operation was cancelled due to
	// a user-requested interrupt.
	ErrInterruptRequested = ErrorKind("ErrInterruptRequested")

	// ErrFetchSubscription indicates an error fetching an index subscription.
	ErrFetchSubscription = ErrorKind("ErrFetchSubscription")

	// ErrFetchTip indicates an error fetching an index tip.
	ErrFetchTip = ErrorKind("ErrFetchTip")

	// ErrMissingNotification indicates a missing index notification.
	ErrMissingNotification = ErrorKind("ErrMissingNotification")

	// ErrBlockNotOnMainChain indicates the provided block is not on the
	// main chain.
	ErrBlockNotOnMainChain = ErrorKind("ErrBlockNotOnMainChain")
)

These constants are used to identify a specific IndexerError.

Variables

This section is empty.

Functions

func DropAddrIndex 

func DropAddrIndex(ctx context.Context, db database.DB) error

DropAddrIndex drops the address index from the provided database if it exists.

func DropCfIndex 

func DropCfIndex(_ context.Context, db database.DB) error

DropCfIndex drops the CF index from the provided database if it exists.

func DropExistsAddrIndex 

func DropExistsAddrIndex(ctx context.Context, db database.DB) error

DropExistsAddrIndex drops the exists address index from the provided database if it exists.

func DropTxIndex 

func DropTxIndex(ctx context.Context, db database.DB) error

DropTxIndex drops the transaction index from the provided database if it exists. Since the address index relies on it, the address index will also be dropped when it exists.

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 AssertError 

type AssertError string

AssertError identifies an error that indicates an internal code consistency issue and should be treated as a critical and unrecoverable error.

func (AssertError) Error 

func (e AssertError) Error() string

Error returns the assertion error as a huma-readable string and satisfies the error interface.

type ChainQueryer 

type ChainQueryer interface {
	// MainChainHasBlock returns whether or not the block with the given hash is
	// in the main chain.
	MainChainHasBlock(*chainhash.Hash) bool

	// ChainParams returns the network parameters of the chain.
	ChainParams() *chaincfg.Params

	// Best returns the height and hash of the current best block.
	Best() (int64, *chainhash.Hash)

	// BlockHeaderByHash returns the block header identified by the given hash.
	BlockHeaderByHash(hash *chainhash.Hash) (wire.BlockHeader, error)

	// BlockHashByHeight returns the hash of the block at the given height in
	// the main chain.
	BlockHashByHeight(int64) (*chainhash.Hash, error)

	// BlockHeightByHash returns the height of the block with the given hash
	// in the main chain.
	BlockHeightByHash(hash *chainhash.Hash) (int64, error)

	// BlockByHash returns the block of the provided hash.
	BlockByHash(*chainhash.Hash) (*dcrutil.Block, error)

	// IsTreasuryAgendaActive returns true if the treasury agenda is active at
	// the provided block.
	IsTreasuryAgendaActive(*chainhash.Hash) (bool, error)
}

ChainQueryer provides a generic interface that is used to provide access to the chain details required by indexes.

All functions MUST be safe for concurrent access.

type ErrorKind 

type ErrorKind string

ErrorKind identifies a kind of error. It has full support for errors.Is and errors.As, so the caller can directly check against an error kind when determining the reason for an error.

func (ErrorKind) Error 

func (e ErrorKind) Error() string

Error satisfies the error interface and prints human-readable errors.

type ExistsAddrIndex 

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

ExistsAddrIndex implements an "ever seen" address index. Any address that is ever seen in a block or in the mempool is stored here as a key. Values are empty. Once an address is seen, it is never removed from this store. This results in a local version of this database that is consistent only for this peer, but at minimum contains all the addresses seen on the blockchain itself.

In addition, support is provided for a memory-only index of unconfirmed transactions such as those which are kept in the memory pool before inclusion in a block.

func NewExistsAddrIndex 

func NewExistsAddrIndex(subscriber *IndexSubscriber, db database.DB, chain ChainQueryer) (*ExistsAddrIndex, error)

NewExistsAddrIndex returns a new instance of an indexer that is used to create a mapping of all addresses ever seen.

func (*ExistsAddrIndex) AddUnconfirmedTx 

func (idx *ExistsAddrIndex) AddUnconfirmedTx(tx *wire.MsgTx)

AddUnconfirmedTx adds all addresses related to the transaction to the unconfirmed (memory-only) exists address index.

This function is safe for concurrent access.

func (*ExistsAddrIndex) Create 

func (idx *ExistsAddrIndex) Create(dbTx database.Tx) error

Create is invoked when the index is created for the first time. It creates the bucket for the address index.

This is part of the Indexer interface.

func (*ExistsAddrIndex) DB 

func (idx *ExistsAddrIndex) DB() database.DB

DB returns the database of the index.

This is part of the Indexer interface.

func (*ExistsAddrIndex) DropIndex 

func (*ExistsAddrIndex) DropIndex(ctx context.Context, db database.DB) error

DropIndex drops the exists address index from the provided database if it exists.

func (*ExistsAddrIndex) ExistsAddress 

func (idx *ExistsAddrIndex) ExistsAddress(addr stdaddr.Address) (bool, error)

ExistsAddress is the concurrency safe, exported function that returns whether or not an address has been seen before.

func (*ExistsAddrIndex) ExistsAddresses 

func (idx *ExistsAddrIndex) ExistsAddresses(addrs []stdaddr.Address) ([]bool, error)

ExistsAddresses is the concurrency safe, exported function that returns whether or not each address in a slice of addresses has been seen before.

func (*ExistsAddrIndex) IndexSubscription 

func (idx *ExistsAddrIndex) IndexSubscription() *IndexSubscription

IndexSubscription returns the subscription for index updates.

This is part of the Indexer interface.

func (*ExistsAddrIndex) Init 

func (idx *ExistsAddrIndex) Init(ctx context.Context, chainParams *chaincfg.Params) error

Init initializes the exists address transaction index.

This is part of the Indexer interface.

func (*ExistsAddrIndex) Key 

func (idx *ExistsAddrIndex) Key() []byte

Key returns the database key to use for the index as a byte slice.

This is part of the Indexer interface.

func (*ExistsAddrIndex) Name 

func (idx *ExistsAddrIndex) Name() string

Name returns the human-readable name of the index.

This is part of the Indexer interface.

func (*ExistsAddrIndex) NotifySyncSubscribers 

func (idx *ExistsAddrIndex) NotifySyncSubscribers()

NotifySyncSubscribers signals subscribers of an index sync update.

This is part of the Indexer interface.

func (*ExistsAddrIndex) ProcessNotification 

func (idx *ExistsAddrIndex) ProcessNotification(dbTx database.Tx, ntfn *IndexNtfn) error

ProcessNotification indexes the provided notification based on its notification type.

This is part of the Indexer interface.

func (*ExistsAddrIndex) Queryer 

func (idx *ExistsAddrIndex) Queryer() ChainQueryer

Queryer returns the chain queryer.

This is part of the Indexer interface.

func (*ExistsAddrIndex) Tip 

func (idx *ExistsAddrIndex) Tip() (int64, *chainhash.Hash, error)

Tip returns the current tip of the index.

This is part of the Indexer interface.

func (*ExistsAddrIndex) Version 

func (idx *ExistsAddrIndex) Version() uint32

Version returns the current version of the index.

This is part of the Indexer interface.

func (*ExistsAddrIndex) WaitForSync 

func (idx *ExistsAddrIndex) WaitForSync() chan bool

WaitForSync subscribes clients for the next index sync update.

This is part of the Indexer interface.

type IndexDropper 

type IndexDropper interface {
	DropIndex(context.Context, database.DB) error
}

IndexDropper provides a method to remove an index from the database. Indexers may implement this for a more efficient way of deleting themselves from the database rather than simply dropping a bucket.

type IndexNtfn 

type IndexNtfn struct {
	NtfnType          IndexNtfnType
	Block             *dcrutil.Block
	Parent            *dcrutil.Block
	IsTreasuryEnabled bool
	Done              chan bool
}

IndexNtfn represents an index notification detailing a block connection or disconnection.

type IndexNtfnType 

type IndexNtfnType int

IndexNtfnType represents an index notification type. 

const (
	// ConnectNtfn indicates the index notification signals a block
	// connected to the main chain.
	ConnectNtfn IndexNtfnType = iota

	// DisconnectNtfn indicates the index notification signals a block
	// disconnected from the main chain.
	DisconnectNtfn
)

type IndexSubscriber 

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

IndexSubscriber subscribes clients for index updates.

func NewIndexSubscriber 

func NewIndexSubscriber(sCtx context.Context) *IndexSubscriber

NewIndexSubscriber creates a new index subscriber. It also starts the handler for incoming index update subscriptions.

func (*IndexSubscriber) CatchUp 

func (s *IndexSubscriber) CatchUp(ctx context.Context, _ database.DB, queryer ChainQueryer) error

CatchUp syncs all subscribed indexes to the main chain by connecting blocks from after the lowest index tip to the current main chain tip.

This should be called after all indexes have subscribed for updates.

func (*IndexSubscriber) Notify 

func (s *IndexSubscriber) Notify(ntfn *IndexNtfn)

Notify relays an index notification to subscribed indexes for processing.

func (*IndexSubscriber) Run 

func (s *IndexSubscriber) Run(ctx context.Context)

Run relays index notifications to subscribed indexes.

This should be run as a goroutine.

func (*IndexSubscriber) Subscribe 

func (s *IndexSubscriber) Subscribe(index Indexer, prerequisite string) (*IndexSubscription, error)

Subscribe subscribes an index for updates. The returned index subscription has functions to retrieve a channel that produces a stream of index updates and to stop the stream when the caller no longer wishes to receive updates.

type IndexSubscription 

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

IndexSubscription represents a subscription for index updates.

type Indexer 

type Indexer interface {
	// Key returns the key of the index as a byte slice.
	Key() []byte

	// Name returns the human-readable name of the index.
	Name() string

	// Version returns the current version of the index.
	Version() uint32

	// DB returns the database of the index.
	DB() database.DB

	// Queryer returns the chain queryer.
	Queryer() ChainQueryer

	// Tip returns the current index tip.
	Tip() (int64, *chainhash.Hash, error)

	// Create is invoked when the indexer is being created.
	Create(dbTx database.Tx) error

	// Init is invoked when the index is being initialized.
	// This differs from the Create method in that it is called on
	// every load, including the case the index was just created.
	Init(ctx context.Context, chainParams *chaincfg.Params) error

	// ProcessNotification indexes the provided notification based on its
	// notification type.
	ProcessNotification(dbTx database.Tx, ntfn *IndexNtfn) error

	// IndexSubscription returns the subscription for index updates.
	IndexSubscription() *IndexSubscription

	// WaitForSync subscribes clients for the next index sync update.
	WaitForSync() chan bool

	// NotifySyncSubscribers signals subscribers of an index sync update.
	// This should only be called when an index is synced.
	NotifySyncSubscribers()
}

Indexer defines a generic interface for an indexer.

type IndexerError 

type IndexerError struct {
	Description string
	Err         error
}

IndexerError identifies an indexer error. It has full support for errors.Is and errors.As, so the caller can ascertain the specific reason for the error by checking the underlying error.

func (IndexerError) Error 

func (e IndexerError) Error() string

Error satisfies the error interface and prints human-readable errors.

func (IndexerError) Unwrap 

func (e IndexerError) Unwrap() error

Unwrap returns the underlying wrapped error.

type TxIndex 

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

TxIndex implements a transaction by hash index. That is to say, it supports querying all transactions by their hash.

func NewTxIndex 

func NewTxIndex(subscriber *IndexSubscriber, db database.DB, chain ChainQueryer) (*TxIndex, error)

NewTxIndex returns a new instance of an indexer that is used to create a mapping of the hashes of all transactions in the blockchain to the respective block, location within the block, and size of the transaction.

func (*TxIndex) Create 

func (idx *TxIndex) Create(dbTx database.Tx) error

Create is invoked when the index is created for the first time. It creates the buckets for the hash-based transaction index and the internal block ID indexes.

This is part of the Indexer interface.

func (*TxIndex) DB 

func (idx *TxIndex) DB() database.DB

DB returns the database of the index.

This is part of the Indexer interface.

func (*TxIndex) DropIndex 

func (*TxIndex) DropIndex(ctx context.Context, db database.DB) error

DropIndex drops the transaction index from the provided database if it exists. Since the address index relies on it, the address index will also be dropped when it exists.

func (*TxIndex) Entry 

func (idx *TxIndex) Entry(hash *chainhash.Hash) (*TxIndexEntry, error)

Entry returns details for the provided transaction hash from the transaction index. The block region contained in the result can in turn be used to load the raw transaction bytes. When there is no entry for the provided hash, nil will be returned for the both the entry and the error.

This function is safe for concurrent access.

func (*TxIndex) IndexSubscription 

func (idx *TxIndex) IndexSubscription() *IndexSubscription

IndexSubscription returns the subscription for index updates.

This is part of the Indexer interface.

func (*TxIndex) Init 

func (idx *TxIndex) Init(ctx context.Context, chainParams *chaincfg.Params) error

Init initializes the hash-based transaction index. In particular, it finds the highest used block ID and stores it for later use when connecting or disconnecting blocks.

This is part of the Indexer interface.

func (*TxIndex) Key 

func (idx *TxIndex) Key() []byte

Key returns the database key to use for the index as a byte slice.

This is part of the Indexer interface.

func (*TxIndex) Name 

func (idx *TxIndex) Name() string

Name returns the human-readable name of the index.

This is part of the Indexer interface.

func (*TxIndex) NotifySyncSubscribers 

func (idx *TxIndex) NotifySyncSubscribers()

NotifySyncSubscribers signals subscribers of an index sync update.

This is part of the Indexer interface.

func (*TxIndex) ProcessNotification 

func (idx *TxIndex) ProcessNotification(dbTx database.Tx, ntfn *IndexNtfn) error

ProcessNotification indexes the provided notification based on its notification type.

This is part of the Indexer interface.

func (*TxIndex) Queryer 

func (idx *TxIndex) Queryer() ChainQueryer

Queryer returns the chain queryer.

This is part of the Indexer interface.

func (*TxIndex) Tip 

func (idx *TxIndex) Tip() (int64, *chainhash.Hash, error)

Tip returns the current tip of the index.

This is part of the Indexer interface.

func (*TxIndex) Version 

func (idx *TxIndex) Version() uint32

Version returns the current version of the index.

This is part of the Indexer interface.

func (*TxIndex) WaitForSync 

func (idx *TxIndex) WaitForSync() chan bool

WaitForSync subscribes clients for the next index sync update.

This is part of the Indexer interface.

type TxIndexEntry 

type TxIndexEntry struct {
	// BlockRegion specifies the location of the raw bytes of the transaction.
	BlockRegion database.BlockRegion

	// BlockIndex species the index of the transaction within the array of
	// transactions that comprise a tree of the block.
	BlockIndex uint32
}

TxIndexEntry houses information about an entry in the transaction index.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.