Merge pull request #1384 from jnewbery/fee-filter

add feefilter documentation

_autocrossref.yaml

@@ -27,6 +27,8 @@ DER-formatted: der
 ECDSA:
 epoch time: unix epoch time
 '`expires`': pp expires
+'`feefilter` message': feefilter message
+'`feefilter` messages': feefilter message
 fiat:
 '`filteradd` message': filteradd message
 '`filteradd` messages': filteradd message

_config.yml

@@ -532,6 +532,7 @@ devsearches:
     - "addr":  "/en/developer-reference#addr"
     - "alert":  "/en/developer-reference#alert"
     - "block": "/en/developer-reference#block"
+    - "feefilter": "/en/developer-reference#feefilter"
     - "filteradd": "/en/developer-reference#filteradd"
     - "filterclear": "/en/developer-reference#filterclear"
     - "filterload": "/en/developer-reference#filterload"

_includes/devdoc/ref_p2p_networking.md

@@ -792,6 +792,54 @@ alert.cpp] source code for the parameters of this message.
 
 {% endautocrossref %}
 
+#### FeeFilter
+{% include helpers/subhead-links.md %}
+
+{% autocrossref %}
+
+*Added in protocol version 70013 as described by BIP133.*
+
+The `feefilter` message is a request to the receiving peer to not relay any
+transaction inv messages to the sending peer where the fee rate for the
+transaction is below the fee rate specified in the feefilter message.
+
+`feefilter` was introduced in Bitcoin Core 0.13.0 following the introduction
+of mempool limiting in Bitcoin Core 0.12.0. Mempool limiting provides protection against
+attacks and spam transactions that have low fee rates and are unlikely to be
+included in mined blocks. The `feefilter` messages allows a node to inform its
+peers that it will not accept transactions below a specified fee rate into
+its mempool, and therefore that the peers can skip relaying inv messages for
+transactions below that fee rate to that node.
+
+| Bytes | Name    | Data Type | Description
+|-------|---------|-----------|---------------
+| 8     | feerate | uint64_t  | The fee rate (in satoshis per kilobyte) below which transactions should not be relayed to this peer.
+
+The receiving peer may choose to ignore the message and not filter transaction
+inv messages.
+
+The fee filter is additive with bloom filters. If an SPV client loads a bloom
+filter and sends a feefilter message, transactions should only be relayed if
+they pass both filters.
+
+Note however that feefilter has no effect on block propagation or responses to
+getdata messages. For example, if a node requests a merkleblock from its peer
+by sending a getdata message with inv type MSG_FILTERED_BLOCK and it has
+previously sent a feefilter to that peer, the peer should respond with a
+merkleblock containing *all* the transactions matching the bloom filter, even
+if they are below the feefilter fee rate.
+
+inv messages generated from a mempool message are subject to a fee filter if it exists.
+
+The annotated hexdump below shows a `feefilter` message. (The message
+header has been omitted.)
+
+{% endautocrossref %}
+
+{% highlight text %}
+7cbd000000000000 ... satoshis per kilobyte: 48,508
+{% endhighlight %}
+
 
 #### FilterAdd
 {% include helpers/subhead-links.md %}

_includes/references.md

@@ -180,6 +180,7 @@ http://opensource.org/licenses/MIT.
 [addr message]: /en/developer-reference#addr "The P2P network message which relays IP addresses and port numbers of active nodes to other nodes and clients, allowing decentralized peer discovery."
 [alert message]: /en/developer-reference#alert "The P2P network message which sends alerts in case of major software problems."
 [block message]: /en/developer-reference#block "The P2P network message which sends a serialized block"
+[feefilter message]: /en/developer-reference#feefilter "The P2P network message which requests the receiving peer not relay any transactions below the specified fee rate"
 [filteradd message]: /en/developer-reference#filteradd "A P2P protocol message used to add a data element to an existing bloom filter."
 [filterclear message]: /en/developer-reference#filterclear "A P2P protocol message used to remove an existing bloom filter."
 [filterload message]: /en/developer-reference#filterclear "A P2P protocol message used to send a filter to a remote peer, requesting that they only send transactions which match the filter."