indexers

package
v4.0.0-...-14ed8ac Latest Latest
Warning

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

 Go to latest Published: Feb 25, 2021 License: ISC Imports: 15 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
  • 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
  • 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
  • Committed Filter (cfindexparentbucket) Index
    • Stores all committed filters and committed filter headers for all blocks in the main chain

Installation and Updating

This package is part of the github.com/multicash/mcxd/blockchain/v3 module. Use the standard go tooling for working with modules to incorporate it.

License

Package indexers is licensed under the copyfree ISC License.

Documentation

Overview

Package indexers implements optional block chain indexes.

Index

Constants

This section is empty.

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(ctx 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 AddrIndex 

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

AddrIndex implements a transaction by address index. That is to say, it supports querying all transactions that reference a given address because they are either crediting or debiting the address. The returned transactions are ordered according to their order of appearance in the blockchain. In other words, first by block height and then by offset inside the block.

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 NewAddrIndex 

func NewAddrIndex(db database.DB, chainParams *chaincfg.Params) *AddrIndex

NewAddrIndex returns a new instance of an indexer that is used to create a mapping of all addresses in the blockchain to the respective transactions that involve them.

It implements the Indexer interface which plugs into the IndexManager that in turn is used by the blockchain package. This allows the index to be seamlessly maintained along with the chain.

func (*AddrIndex) AddUnconfirmedTx 

func (idx *AddrIndex) AddUnconfirmedTx(tx *mcxutil.Tx, prevScripts PrevScripter, isTreasuryEnabled bool)

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

NOTE: This transaction MUST have already been validated by the memory pool before calling this function with it and have all of the inputs available via the provided previous scripter interface. Failure to do so could result in some or all addresses not being indexed.

This function is safe for concurrent access.

func (*AddrIndex) ConnectBlock 

func (idx *AddrIndex) ConnectBlock(dbTx database.Tx, block, parent *mcxutil.Block, prevScripts PrevScripter, isTreasuryEnabled bool) error

ConnectBlock is invoked by the index manager when a new block has been connected to the main chain. This indexer adds a mapping for each address the transactions in the block involve.

This is part of the Indexer interface.

func (*AddrIndex) Create 

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

Create is invoked when the indexer manager determines the index needs to be created for the first time. It creates the bucket for the address index.

This is part of the Indexer interface.

func (*AddrIndex) DisconnectBlock 

func (idx *AddrIndex) DisconnectBlock(dbTx database.Tx, block, parent *mcxutil.Block, prevScripts PrevScripter, isTreasuryEnabled bool) error

DisconnectBlock is invoked by the index manager when a block has been disconnected from the main chain. This indexer removes the address mappings each transaction in the block involve.

This is part of the Indexer interface.

func (*AddrIndex) DropIndex 

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

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

func (*AddrIndex) EntriesForAddress 

func (idx *AddrIndex) EntriesForAddress(dbTx database.Tx, addr mcxutil.Address, numToSkip, numRequested uint32, reverse bool) ([]TxIndexEntry, uint32, error)

EntriesForAddress returns a slice of details which identify each transaction, including a block region, that involves the passed address according to the specified number to skip, number requested, and whether or not the results should be reversed. It also returns the number actually skipped since it could be less in the case where there are not enough entries.

NOTE: These results only include transactions confirmed in blocks. See the UnconfirmedTxnsForAddress method for obtaining unconfirmed transactions that involve a given address.

This function is safe for concurrent access.

func (*AddrIndex) Init 

func (idx *AddrIndex) Init() error

Init is only provided to satisfy the Indexer interface as there is nothing to initialize for this index.

This is part of the Indexer interface.

func (*AddrIndex) Key 

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

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

This is part of the Indexer interface.

func (*AddrIndex) Name 

func (idx *AddrIndex) Name() string

Name returns the human-readable name of the index.

This is part of the Indexer interface.

func (*AddrIndex) NeedsInputs 

func (idx *AddrIndex) NeedsInputs() bool

NeedsInputs signals that the index requires the referenced inputs in order to properly create the index.

This implements the NeedsInputser interface.

func (*AddrIndex) RemoveUnconfirmedTx 

func (idx *AddrIndex) RemoveUnconfirmedTx(hash *chainhash.Hash)

RemoveUnconfirmedTx removes the passed transaction from the unconfirmed (memory-only) address index.

This function is safe for concurrent access.

func (*AddrIndex) UnconfirmedTxnsForAddress 

func (idx *AddrIndex) UnconfirmedTxnsForAddress(addr mcxutil.Address) []*mcxutil.Tx

UnconfirmedTxnsForAddress returns all transactions currently in the unconfirmed (memory-only) address index that involve the passed address. Unsupported address types are ignored and will result in no results.

This function is safe for concurrent access.

func (*AddrIndex) Version 

func (idx *AddrIndex) Version() uint32

Version returns the current version of the index.

This is part of the Indexer interface.

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

	// BestHeight returns the height of the current best block.
	BestHeight() int64

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

	// PrevScripts returns a source of previous transaction scripts and their
	// associated versions spent by the given block.
	PrevScripts(database.Tx, *mcxutil.Block) (PrevScripter, error)

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

ChainQueryer provides a generic interface that is used to provide access to the chain details required to by the index manager to initialize and sync the various indexes.

All function MUST be safe for concurrent access.

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(db database.DB, chainParams *chaincfg.Params) *ExistsAddrIndex

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

It implements the Indexer interface which plugs into the IndexManager that in turn is used by the blockchain package. This allows the index to be seamlessly maintained along with the chain.

func (*ExistsAddrIndex) AddUnconfirmedTx 

func (idx *ExistsAddrIndex) AddUnconfirmedTx(tx *wire.MsgTx, isTreasuryEnabled bool)

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) ConnectBlock 

func (idx *ExistsAddrIndex) ConnectBlock(dbTx database.Tx, block, parent *mcxutil.Block, _ PrevScripter, isTreasuryEnabled bool) error

ConnectBlock is invoked by the index manager when a new block has been connected to the main chain. This indexer adds a key for each address the transactions in the block involve.

This is part of the Indexer interface.

func (*ExistsAddrIndex) Create 

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

Create is invoked when the indexer manager determines the index needs to be created for the first time. It creates the bucket for the address index.

This is part of the Indexer interface.

func (*ExistsAddrIndex) DisconnectBlock 

func (idx *ExistsAddrIndex) DisconnectBlock(dbTx database.Tx, block, parent *mcxutil.Block, _ PrevScripter, isTreasuryEnabled bool) error

DisconnectBlock is invoked by the index manager when a block has been disconnected from the main chain. Note that the exists address manager never removes addresses.

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 mcxutil.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 []mcxutil.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) Init 

func (idx *ExistsAddrIndex) Init() error

Init is only provided to satisfy the Indexer interface as there is nothing to initialize for this 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) Version 

func (idx *ExistsAddrIndex) Version() uint32

Version returns the current version of the index.

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 IndexManager 

type IndexManager interface {
	// Init is invoked during chain initialize in order to allow the index
	// manager to initialize itself and any indexes it is managing.  The channel
	// parameter specifies a channel the caller can close to signal that the
	// process should be interrupted.  It can be nil if that behavior is not
	// desired.
	Init(context.Context, ChainQueryer) error

	// ConnectBlock is invoked when a new block has been connected to the main
	// chain.
	ConnectBlock(database.Tx, *mcxutil.Block, *mcxutil.Block, PrevScripter, bool) error

	// DisconnectBlock is invoked when a block has been disconnected from the
	// main chain.
	DisconnectBlock(database.Tx, *mcxutil.Block, *mcxutil.Block, PrevScripter, bool) error
}

IndexManager provides a generic interface that is called when blocks are connected and disconnected to and from the tip of the main chain for the purpose of supporting optional indexes.

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

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

	// Create is invoked when the indexer manager determines the index needs
	// to be created for the first time.
	Create(dbTx database.Tx) error

	// Init is invoked when the index manager is first initializing the
	// index.  This differs from the Create method in that it is called on
	// every load, including the case the index was just created.
	Init() error

	// ConnectBlock is invoked when the index manager is notified that a new
	// block has been connected to the main chain.
	ConnectBlock(dbTx database.Tx, block, parent *mcxutil.Block, prevScripts PrevScripter, isTreasuryEnabled bool) error

	// DisconnectBlock is invoked when the index manager is notified that a
	// block has been disconnected from the main chain.
	DisconnectBlock(dbTx database.Tx, block, parent *mcxutil.Block, prevScripts PrevScripter, isTreasuryEnabled bool) error
}

Indexer provides a generic interface for an indexer that is managed by an index manager such as the Manager type provided by this package.

type Manager 

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

Manager defines an index manager that manages multiple optional indexes and implements the IndexManager interface so it can be seamlessly plugged into normal chain processing.

func NewManager 

func NewManager(db database.DB, enabledIndexes []Indexer, params *chaincfg.Params) *Manager

NewManager returns a new index manager with the provided indexes enabled.

The manager returned satisfies the IndexManager interface and thus cleanly plugs into the normal blockchain processing path.

func (*Manager) ConnectBlock 

func (m *Manager) ConnectBlock(dbTx database.Tx, block, parent *mcxutil.Block, prevScripts PrevScripter, isTreasuryEnabled bool) error

ConnectBlock must be invoked when a block is extending the main chain. It keeps track of the state of each index it is managing, performs some sanity checks, and invokes each indexer.

This is part of the IndexManager interface.

func (*Manager) DisconnectBlock 

func (m *Manager) DisconnectBlock(dbTx database.Tx, block, parent *mcxutil.Block, prevScripts PrevScripter, isTreasuryEnabled bool) error

DisconnectBlock must be invoked when a block is being disconnected from the end of the main chain. It keeps track of the state of each index it is managing, performs some sanity checks, and invokes each indexer to remove the index entries associated with the block.

This is part of the IndexManager interface.

func (*Manager) Init 

func (m *Manager) Init(ctx context.Context, chain ChainQueryer) error

Init initializes the enabled indexes. This is called during chain initialization and primarily consists of catching up all indexes to the current best chain tip. This is necessary since each index can be disabled and re-enabled at any time and attempting to catch-up indexes at the same time new blocks are being downloaded would lead to an overall longer time to catch up due to the I/O contention.

This is part of the IndexManager interface.

type NeedsInputser 

type NeedsInputser interface {
	NeedsInputs() bool
}

NeedsInputser provides a generic interface for an indexer to specify the it requires the ability to look up inputs for a transaction.

type PrevScripter 

type PrevScripter interface {
	PrevScript(*wire.OutPoint) (uint16, []byte, bool)
}

PrevScripter defines an interface that provides access to scripts and their associated version keyed by an outpoint. It is used within this package as a generic means to provide the scripts referenced by the inputs to transactions within a block that are needed to index it. The boolean return indicates whether or not the script and version for the provided outpoint was found.

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(db database.DB) *TxIndex

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.

It implements the Indexer interface which plugs into the IndexManager that in turn is used by the blockchain package. This allows the index to be seamlessly maintained along with the chain.

func (*TxIndex) ConnectBlock 

func (idx *TxIndex) ConnectBlock(dbTx database.Tx, block, parent *mcxutil.Block, _ PrevScripter, isTreasuryEnabled bool) error

ConnectBlock is invoked by the index manager when a new block has been connected to the main chain. This indexer adds a hash-to-transaction mapping for every transaction in the passed block.

This is part of the Indexer interface.

func (*TxIndex) Create 

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

Create is invoked when the indexer manager determines the index needs to be 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) DisconnectBlock 

func (idx *TxIndex) DisconnectBlock(dbTx database.Tx, block, parent *mcxutil.Block, _ PrevScripter, isTreasuryEnabled bool) error

DisconnectBlock is invoked by the index manager when a block has been disconnected from the main chain. This indexer removes the hash-to-transaction mapping for every transaction in the block.

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) Init 

func (idx *TxIndex) Init() 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) Version 

func (idx *TxIndex) Version() uint32

Version returns the current version of the index.

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.