lbcd/mempool/README.md

mempool
=======

[![ISC License](http://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org)

Package mempool provides a policy-enforced pool of unmined bitcoin transactions.

A key responsbility of the bitcoin network is mining user-generated transactions
into blocks.  In order to facilitate this, the mining process relies on having a
readily-available source of transactions to include in a block that is being
solved.

At a high level, this package satisfies that requirement by providing an
in-memory pool of fully validated transactions that can also optionally be
further filtered based upon a configurable policy.

One of the policy configuration options controls whether or not "standard"
transactions are accepted.  In essence, a "standard" transaction is one that
satisfies a fairly strict set of requirements that are largely intended to help
provide fair use of the system to all users.  It is important to note that what
is considered a "standard" transaction changes over time.  For some insight, at
the time of this writing, an example of _some_ of the criteria that are required
for a transaction to be considered standard are that it is of the most-recently
supported version, finalized, does not exceed a specific size, and only consists
of specific script forms.

Since this package does not deal with other bitcoin specifics such as network
communication and transaction relay, it returns a list of transactions that were
accepted which gives the caller a high level of flexibility in how they want to
proceed.  Typically, this will involve things such as relaying the transactions
to other peers on the network and notifying the mining process that new
transactions are available.

## Feature Overview

The following is a quick overview of the major features.  It is not intended to
be an exhaustive list.

- Maintain a pool of fully validated transactions
  - Reject non-fully-spent duplicate transactions
  - Reject coinbase transactions
  - Reject double spends (both from the chain and other transactions in pool)
  - Reject invalid transactions according to the network consensus rules
  - Full script execution and validation with signature cache support
  - Individual transaction query support
- Orphan transaction support (transactions that spend from unknown outputs)
  - Configurable limits (see transaction acceptance policy)
  - Automatic addition of orphan transactions that are no longer orphans as new
    transactions are added to the pool
  - Individual orphan transaction query support
- Configurable transaction acceptance policy
  - Option to accept or reject standard transactions
  - Option to accept or reject transactions based on priority calculations
  - Rate limiting of low-fee and free transactions
  - Non-zero fee threshold
  - Max signature operations per transaction
  - Max orphan transaction size
  - Max number of orphan transactions allowed
- Additional metadata tracking for each transaction
  - Timestamp when the transaction was added to the pool
  - Most recent block height when the transaction was added to the pool
  - The fee the transaction pays
  - The starting priority for the transaction
- Manual control of transaction removal
  - Recursive removal of all dependent transactions
mempool: Refactor mempool code to its own package. (#737) This does the minimum work necessary to refactor the mempool code into its own package. The idea is that separating this code into its own package will greatly improve its testability, allow independent benchmarking and profiling, and open up some interesting opportunities for future development related to the memory pool. There are likely some areas related to policy that could be further refactored, however it is better to do that in future commits in order to keep the changeset as small as possible during this refactor. Overview of the major changes: - Create the new package - Move several files into the new package: - mempool.go -> mempool/mempool.go - mempoolerror.go -> mempool/error.go - policy.go -> mempool/policy.go - policy_test.go -> mempool/policy_test.go - Update mempool logging to use the new mempool package logger - Rename mempoolPolicy to Policy (so it's now mempool.Policy) - Rename mempoolConfig to Config (so it's now mempool.Config) - Rename mempoolTxDesc to TxDesc (so it's now mempool.TxDesc) - Rename txMemPool to TxPool (so it's now mempool.TxPool) - Move defaultBlockPrioritySize to the new package and export it - Export DefaultMinRelayTxFee from the mempool package - Export the CalcPriority function from the mempool package - Introduce a new RawMempoolVerbose function on the TxPool and update the RPC server to use it - Update all references to the mempool to use the package. - Add a skeleton README.md 2016-08-19 18:08:37 +02:00			`mempool`
			`=======`

multi: Update markdown files for GFM changes. The github markdown interpreter has been changed such that it no longer allows spaces in between the brackets and parenthesis of links and now requires a newline in between anchors and other formatting. This updates all of the markdown files accordingly. While here, it also corrects a couple of inconsistencies in some of the README.md files. 2017-05-25 18:29:23 +02:00			`[![ISC License](http://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org)`
mempool: Refactor mempool code to its own package. (#737) This does the minimum work necessary to refactor the mempool code into its own package. The idea is that separating this code into its own package will greatly improve its testability, allow independent benchmarking and profiling, and open up some interesting opportunities for future development related to the memory pool. There are likely some areas related to policy that could be further refactored, however it is better to do that in future commits in order to keep the changeset as small as possible during this refactor. Overview of the major changes: - Create the new package - Move several files into the new package: - mempool.go -> mempool/mempool.go - mempoolerror.go -> mempool/error.go - policy.go -> mempool/policy.go - policy_test.go -> mempool/policy_test.go - Update mempool logging to use the new mempool package logger - Rename mempoolPolicy to Policy (so it's now mempool.Policy) - Rename mempoolConfig to Config (so it's now mempool.Config) - Rename mempoolTxDesc to TxDesc (so it's now mempool.TxDesc) - Rename txMemPool to TxPool (so it's now mempool.TxPool) - Move defaultBlockPrioritySize to the new package and export it - Export DefaultMinRelayTxFee from the mempool package - Export the CalcPriority function from the mempool package - Introduce a new RawMempoolVerbose function on the TxPool and update the RPC server to use it - Update all references to the mempool to use the package. - Add a skeleton README.md 2016-08-19 18:08:37 +02:00
mempool: Add docs.go and flesh out README.md. 2016-10-24 02:39:41 +02:00			`Package mempool provides a policy-enforced pool of unmined bitcoin transactions.`
mempool: Refactor mempool code to its own package. (#737) This does the minimum work necessary to refactor the mempool code into its own package. The idea is that separating this code into its own package will greatly improve its testability, allow independent benchmarking and profiling, and open up some interesting opportunities for future development related to the memory pool. There are likely some areas related to policy that could be further refactored, however it is better to do that in future commits in order to keep the changeset as small as possible during this refactor. Overview of the major changes: - Create the new package - Move several files into the new package: - mempool.go -> mempool/mempool.go - mempoolerror.go -> mempool/error.go - policy.go -> mempool/policy.go - policy_test.go -> mempool/policy_test.go - Update mempool logging to use the new mempool package logger - Rename mempoolPolicy to Policy (so it's now mempool.Policy) - Rename mempoolConfig to Config (so it's now mempool.Config) - Rename mempoolTxDesc to TxDesc (so it's now mempool.TxDesc) - Rename txMemPool to TxPool (so it's now mempool.TxPool) - Move defaultBlockPrioritySize to the new package and export it - Export DefaultMinRelayTxFee from the mempool package - Export the CalcPriority function from the mempool package - Introduce a new RawMempoolVerbose function on the TxPool and update the RPC server to use it - Update all references to the mempool to use the package. - Add a skeleton README.md 2016-08-19 18:08:37 +02:00
mempool: Add docs.go and flesh out README.md. 2016-10-24 02:39:41 +02:00			`A key responsbility of the bitcoin network is mining user-generated transactions`
			`into blocks. In order to facilitate this, the mining process relies on having a`
			`readily-available source of transactions to include in a block that is being`
			`solved.`

			`At a high level, this package satisfies that requirement by providing an`
			`in-memory pool of fully validated transactions that can also optionally be`
			`further filtered based upon a configurable policy.`

			`One of the policy configuration options controls whether or not "standard"`
			`transactions are accepted. In essence, a "standard" transaction is one that`
btcd/multi: fix a number of typos in comments. 2017-10-29 20:56:03 +01:00			`satisfies a fairly strict set of requirements that are largely intended to help`
mempool: Add docs.go and flesh out README.md. 2016-10-24 02:39:41 +02:00			`provide fair use of the system to all users. It is important to note that what`
			`is considered a "standard" transaction changes over time. For some insight, at`
			`the time of this writing, an example of _some_ of the criteria that are required`
			`for a transaction to be considered standard are that it is of the most-recently`
			`supported version, finalized, does not exceed a specific size, and only consists`
			`of specific script forms.`

			`Since this package does not deal with other bitcoin specifics such as network`
			`communication and transaction relay, it returns a list of transactions that were`
			`accepted which gives the caller a high level of flexibility in how they want to`
			`proceed. Typically, this will involve things such as relaying the transactions`
			`to other peers on the network and notifying the mining process that new`
			`transactions are available.`

			`## Feature Overview`

			`The following is a quick overview of the major features. It is not intended to`
			`be an exhaustive list.`

			`- Maintain a pool of fully validated transactions`
			`- Reject non-fully-spent duplicate transactions`
			`- Reject coinbase transactions`
			`- Reject double spends (both from the chain and other transactions in pool)`
			`- Reject invalid transactions according to the network consensus rules`
			`- Full script execution and validation with signature cache support`
			`- Individual transaction query support`
			`- Orphan transaction support (transactions that spend from unknown outputs)`
			`- Configurable limits (see transaction acceptance policy)`
			`- Automatic addition of orphan transactions that are no longer orphans as new`
			`transactions are added to the pool`
			`- Individual orphan transaction query support`
			`- Configurable transaction acceptance policy`
			`- Option to accept or reject standard transactions`
			`- Option to accept or reject transactions based on priority calculations`
			`- Rate limiting of low-fee and free transactions`
			`- Non-zero fee threshold`
			`- Max signature operations per transaction`
			`- Max orphan transaction size`
			`- Max number of orphan transactions allowed`
			`- Additional metadata tracking for each transaction`
			`- Timestamp when the transaction was added to the pool`
			`- Most recent block height when the transaction was added to the pool`
			`- The fee the transaction pays`
			`- The starting priority for the transaction`
			`- Manual control of transaction removal`
			`- Recursive removal of all dependent transactions`