mempool

README

Mempool

Package mempool represents the chain transaction layer (not to be confused with DB transaction layer). A blockchain transaction has one of a finite number of states at any given time. Below are listed the logical states of a transaction.

States

Name	Desc		Started by	Transitions
created	tx data was built with RPC call		RPC subsystem
signed	tx data was signed with RPC call		RPC subsystem
received	tx was pushed into mempool by external subsystem (RPC, P2P node, etc)		Mempool	signed -> received
			Mempool	propagated -> received
verified	tx passed the tx verification rules		Mempool	received -> verified
propagated	tx was gossiped to the P2P network		P2P network	verified -> propagated
accepted	tx is part of a block that was accepted by the network		Mempool	propagated -> accepted
stale	tx was removed due to exceeding expiry period		Mempool	any -> stale

Mempool participates in the following transitions

• from created/signed to received
• from received to verified
• from verified to propagated
• from propagated to accepted

Mempool responsibilities:

• Store all transactions that are received from RPC call or P2P message ready to be verified
• Execute transaction verification procedure
• Store all transactions that are verified by the chain and can be included in next candidate block
• Update internal state on newly accepted block
• Monitor and report for abnormal situations

Implementation

Mempool implementation tries to avoid use of mutex to protect shared state. Instead, all input/output communication is based on channels. Similarily to Unix Select(..) sementics, mempool waits on read/write (input/output/timeout) channels to trigger an event handler

Underlying pool

In addition, mempool tries to be storage-agnostic so that a verified tx can be stored in different forms of persistent and non-persistent pools. Supported and pending ideas for pools:

• hashmap - based on golang map implements non-persistent pool. Supported
• syncpool - based sync.Pool. Pending
• distributed - distributed memory object caching system (e.g memcached). Pending
• persistent - persistent KV storage. Pending

Documentation

Index

• Variables
• type HashMap
  • func (m HashMap) Clone() []transactions.Transaction
  • func (m *HashMap) Contains(txID []byte) bool
  • func (m *HashMap) ContainsKeyImage(txInputKeyImage []byte) bool
  • func (m HashMap) FilterByType(filterType transactions.TxType) []transactions.Transaction
  • func (m *HashMap) Get(txID []byte) transactions.Transaction
  • func (m *HashMap) Len() int
  • func (m *HashMap) Put(t TxDesc) error
  • func (m *HashMap) Range(fn func(k txHash, t TxDesc) error) error
  • func (m *HashMap) RangeSort(fn func(k txHash, t TxDesc) (bool, error)) error
  • func (m *HashMap) Size() uint32
• type Mempool
  • func NewMempool(eventBus *eventbus.EventBus, rpcBus *rpcbus.RPCBus, ...) *Mempool
  • func (m *Mempool) CollectPending(msg message.Message) error
  • func (m *Mempool) Quit()
  • func (m *Mempool) Run()
• type Pool
• type TxDesc

Variables

var (
	// ErrCoinbaseTxNotAllowed coinbase tx must be built by block generator only
	ErrCoinbaseTxNotAllowed = errors.New("coinbase tx not allowed")
	// ErrAlreadyExists transaction with same txid already exists in
	ErrAlreadyExists = errors.New("already exists")
	// ErrDoubleSpending transaction uses outputs spent in other mempool txs
	ErrDoubleSpending = errors.New("double-spending in mempool")
)

Types

type HashMap

type HashMap struct {
	Capacity uint32
	// contains filtered or unexported fields
}

HashMap represents a pool implementation based on golang map. The generic solution to bench against.

func (HashMap) Clone

func (m HashMap) Clone() []transactions.Transaction

Clone the entire pool

func (*HashMap) Contains

func (m *HashMap) Contains(txID []byte) bool

Contains returns true if the given key is in the pool.

func (*HashMap) ContainsKeyImage

func (m *HashMap) ContainsKeyImage(txInputKeyImage []byte) bool

ContainsKeyImage returns true if txpool includes a input that contains this keyImage

func (HashMap) FilterByType

func (m HashMap) FilterByType(filterType transactions.TxType) []transactions.Transaction

FilterByType returns all transactions for a specific type that are currently in the HashMap.

func (*HashMap) Get

func (m *HashMap) Get(txID []byte) transactions.Transaction

Get returns a tx for a given txID if it exists.

func (*HashMap) Len

func (m *HashMap) Len() int

Len returns the number of tx entries

func (*HashMap) Put

func (m *HashMap) Put(t TxDesc) error

Put sets the value for the given key. It overwrites any previous value for that key;

func (*HashMap) Range

func (m *HashMap) Range(fn func(k txHash, t TxDesc) error) error

Range iterates through all tx entries

func (*HashMap) RangeSort

func (m *HashMap) RangeSort(fn func(k txHash, t TxDesc) (bool, error)) error

RangeSort iterates through all tx entries sorted by Fee in a descending order

func (*HashMap) Size

func (m *HashMap) Size() uint32

Size of the txs

type Mempool

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

Mempool is a storage for the chain transactions that are valid according to the current chain state and can be included in the next block.

func NewMempool

func NewMempool(eventBus *eventbus.EventBus, rpcBus *rpcbus.RPCBus, verifyTx func(tx transactions.Transaction) error) *Mempool

NewMempool instantiates and initializes node mempool

func (*Mempool) CollectPending

func (m *Mempool) CollectPending(msg message.Message) error

CollectPending process the emitted transactions. Fast-processing and simple impl to avoid locking here. NB This is always run in a different than main mempool routine

func (*Mempool) Quit

func (m *Mempool) Quit()

Quit makes mempool main loop to terminate

func (*Mempool) Run

func (m *Mempool) Run()

Run spawns the mempool lifecycle routine. The whole mempool cycle is around getting input from the outside world (from input channels) and provide the actual list of the verified txs (onto output channel).

All operations are always executed in a single go-routine so no protection-by-mutex needed

type Pool

type Pool interface {

	// Put sets the value for the given key. It overwrites any previous value
	// for that key;
	Put(t TxDesc) error
	// Get retrieves a transaction for a given txID, if it exists.
	Get(txID []byte) transactions.Transaction
	// Contains returns true if the given key is in the pool.
	Contains(key []byte) bool
	// ContainsKeyImage returns true if txpool includes a input that contains
	// this keyImage
	ContainsKeyImage(keyImage []byte) bool
	// Clone the entire pool
	Clone() []transactions.Transaction

	// FilterByType returns all verified transactions for a specific type.
	FilterByType(transactions.TxType) []transactions.Transaction

	// Size is total number of bytes of all txs marshaling size
	Size() uint32
	// Len returns the number of tx entries
	Len() int

	// Range iterates through all tx entries
	Range(fn func(k txHash, t TxDesc) error) error

	// RangeSort iterates through all tx entries sorted by Fee
	// in a descending order
	RangeSort(fn func(k txHash, t TxDesc) (bool, error)) error
}

Pool represents a transaction pool of the verified txs only.

type TxDesc

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

TxDesc encapsulates both tx raw and meta data