vendor/github.com/btcsuite/btcd/mempool/doc.go

   1 // Copyright (c) 2016 The btcsuite developers
   2 // Use of this source code is governed by an ISC
   3 // license that can be found in the LICENSE file.
   4
   5 /*
   6 Package mempool provides a policy-enforced pool of unmined bitcoin transactions.
   7
   8 A key responsbility of the bitcoin network is mining user-generated transactions
   9 into blocks.  In order to facilitate this, the mining process relies on having a
  10 readily-available source of transactions to include in a block that is being
  11 solved.
  12
  13 At a high level, this package satisfies that requirement by providing an
  14 in-memory pool of fully validated transactions that can also optionally be
  15 further filtered based upon a configurable policy.
  16
  17 One of the policy configuration options controls whether or not "standard"
  18 transactions are accepted.  In essence, a "standard" transaction is one that
  19 satisfies a fairly strict set of requirements that are largley intended to help
  20 provide fair use of the system to all users.  It is important to note that what
  21 is considered a "standard" transaction changes over time.  For some insight, at
  22 the time of this writing, an example of SOME of the criteria that are required
  23 for a transaction to be considered standard are that it is of the most-recently
  24 supported version, finalized, does not exceed a specific size, and only consists
  25 of specific script forms.
  26
  27 Since this package does not deal with other bitcoin specifics such as network
  28 communication and transaction relay, it returns a list of transactions that were
  29 accepted which gives the caller a high level of flexibility in how they want to
  30 proceed.  Typically, this will involve things such as relaying the transactions
  31 to other peers on the network and notifying the mining process that new
  32 transactions are available.
  33
  34 Feature Overview
  35
  36 The following is a quick overview of the major features.  It is not intended to
  37 be an exhaustive list.
  38
  39  - Maintain a pool of fully validated transactions
  40    - Reject non-fully-spent duplicate transactions
  41    - Reject coinbase transactions
  42    - Reject double spends (both from the chain and other transactions in pool)
  43    - Reject invalid transactions according to the network consensus rules
  44    - Full script execution and validation with signature cache support
  45    - Individual transaction query support
  46  - Orphan transaction support (transactions that spend from unknown outputs)
  47    - Configurable limits (see transaction acceptance policy)
  48    - Automatic addition of orphan transactions that are no longer orphans as new
  49      transactions are added to the pool
  50    - Individual orphan transaction query support
  51  - Configurable transaction acceptance policy
  52    - Option to accept or reject standard transactions
  53    - Option to accept or reject transactions based on priority calculations
  54    - Rate limiting of low-fee and free transactions
  55    - Non-zero fee threshold
  56    - Max signature operations per transaction
  57    - Max orphan transaction size
  58    - Max number of orphan transactions allowed
  59  - Additional metadata tracking for each transaction
  60    - Timestamp when the transaction was added to the pool
  61    - Most recent block height when the transaction was added to the pool
  62    - The fee the transaction pays
  63    - The starting priority for the transaction
  64  - Manual control of transaction removal
  65    - Recursive removal of all dependent transactions
  66
  67 Errors
  68
  69 Errors returned by this package are either the raw errors provided by underlying
  70 calls or of type mempool.RuleError.  Since there are two classes of rules
  71 (mempool acceptance rules and blockchain (consensus) acceptance rules), the
  72 mempool.RuleError type contains a single Err field which will, in turn, either
  73 be a mempool.TxRuleError or a blockchain.RuleError.  The first indicates a
  74 violation of mempool acceptance rules while the latter indicates a violation of
  75 consensus acceptance rules.  This allows the caller to easily differentiate
  76 between unexpected errors, such as database errors, versus errors due to rule
  77 violations through type assertions.  In addition, callers can programmatically
  78 determine the specific rule violation by type asserting the Err field to one of
  79 the aforementioned types and examining their underlying ErrorCode field.
  80 */
  81 package mempool