Create gettxoutproof.md and verifytxoutproof.md

Closes bitcoin-dot-org#1012

Makefile

@@ -219,7 +219,7 @@ manual-update-summaries-file:
 ## future)
 	$S echo "{%comment%}AUTOMATICALLY-GENERATED FILE: DO NOT EDIT THIS FILE" > _includes/helpers/summaries.md
 	$S echo "This file is licensed under the terms of its source texts{%endcomment%}" >> _includes/helpers/summaries.md
-	$S grep -rh --exclude='*summaries.md' 'assign summary_' _includes/ | sort >> _includes/helpers/summaries.md
+	$S grep -rh --exclude='*summaries.md' 'assign summary_' _includes/ | LANG=UTF-8 sort >> _includes/helpers/summaries.md
 
 manual-check-diff-sha256sums:
 ## A manually-run command to check the locally-built

_autocrossref.yaml

@@ -265,6 +265,8 @@ CVE-2012-2459:
 '`gettransaction` RPC': rpc gettransaction
 '`gettxout`': rpc gettxout
 '`gettxout` RPC': rpc gettxout
+'`gettxoutproof`': rpc gettxoutproof
+'`gettxoutproof` RPC': rpc gettxoutproof
 '`gettxoutsetinfo`': rpc gettxoutsetinfo
 '`gettxoutsetinfo` RPC': rpc gettxoutsetinfo
 '`getunconfirmedbalance`': rpc getunconfirmedbalance
@@ -333,6 +335,8 @@ CVE-2012-2459:
 '`verifychain` RPC': rpc verifychain
 '`verifymessage`': rpc verifymessage
 '`verifymessage` RPC': rpc verifymessage
+'`verifytxoutproof`': rpc verifytxoutproof
+'`verifytxoutproof` RPC': rpc verifytxoutproof
 '`walletlock`': rpc walletlock
 '`walletlock` RPC': rpc walletlock
 '`walletpassphrase`': rpc walletpassphrase

_config.yml

@@ -264,6 +264,7 @@ devsearches:
     - 'GetReceivedByAddress': "/en/developer-reference#getreceivedbyaddress"
     - 'GetTransaction': "/en/developer-reference#gettransaction"
     - 'GetTxout': "/en/developer-reference#gettxout"
+    - 'GetTxOutProof': "/en/developer-reference#gettxoutproof"
     - 'GetTxoutSetInfo': "/en/developer-reference#gettxoutsetinfo"
     - 'GetUnconfirmedBalance': "/en/developer-reference#getunconfirmedbalance"
     - 'GetWalletInfo': "/en/developer-reference#getwalletinfo"
@@ -298,6 +299,7 @@ devsearches:
     - 'ValidateAddress': "/en/developer-reference#validateaddress"
     - 'VerifyChain': "/en/developer-reference#verifychain"
     - 'VerifyMessage': "/en/developer-reference#verifymessage"
+    - 'VerifyTxOutProof': "/en/developer-reference#verifytxoutproof"
     - 'WalletLock': "/en/developer-reference#walletlock"
     - 'WalletPassphrase': "/en/developer-reference#walletpassphrase"
     - 'WalletPassphraseChange': "/en/developer-reference#walletpassphrasechange"

_includes/helpers/summaries.md

@@ -13,15 +13,15 @@ This file is licensed under the terms of its source texts{%endcomment%}
 {% assign summary_estimateFee="estimates the transaction fee per kilobyte that needs to be paid for a transaction to be included within a certain number of blocks." %}
 {% assign summary_estimatePriority="estimates the priority that a transaction needs in order to be included within a certain number of blocks as a free high-priority transaction." %}
 {% assign summary_generate="nearly instantly generates blocks (in regtest mode only)" %}
-{% assign summary_getAccountAddress="returns the current Bitcoin address for receiving payments to this account. If the account doesn't exist, it creates both the account and a new address for receiving payment.  Once a payment has been received to an address, future calls to this RPC for the same account will return a different address." %}
 {% assign summary_getAccount="returns the name of the account associated with the given address." %}
+{% assign summary_getAccountAddress="returns the current Bitcoin address for receiving payments to this account. If the account doesn't exist, it creates both the account and a new address for receiving payment.  Once a payment has been received to an address, future calls to this RPC for the same account will return a different address." %}
 {% assign summary_getAddedNodeInfo="returns information about the given added node, or all added nodes (except onetry nodes). Only nodes which have been manually added using the `addnode` RPC will have their information displayed." %}
 {% assign summary_getAddressesByAccount="returns a list of every address assigned to a particular account." %}
 {% assign summary_getBalance="gets the balance in decimal bitcoins across all accounts or for a particular account." %}
 {% assign summary_getBestBlockHash="returns the header hash of the most recent block on the best block chain." %}
+{% assign summary_getBlock="gets a block with a particular header hash from the local block database either as a JSON object or as a serialized block." %}
 {% assign summary_getBlockChainInfo="provides information about the current state of the block chain." %}
 {% assign summary_getBlockCount="returns the number of blocks in the local best block chain." %}
-{% assign summary_getBlock="gets a block with a particular header hash from the local block database either as a JSON object or as a serialized block." %}
 {% assign summary_getBlockHash="returns the header hash of a block at the given height in the local best block chain." %}
 {% assign summary_getBlockTemplate="gets a block template or proposal for use with mining software." %}
 {% assign summary_getChainTips="returns information about the highest-height block (tip) of each local block chain." %}
@@ -44,6 +44,7 @@ This file is licensed under the terms of its source texts{%endcomment%}
 {% assign summary_getReceivedByAddress="returns the total amount received by the specified address in transactions with the specified number of confirmations. It does not count coinbase transactions." %}
 {% assign summary_getTransaction="gets detailed information about an in-wallet transaction." %}
 {% assign summary_getTxOut="returns details about a transaction output.  Only unspent transaction outputs (UTXOs) are guaranteed to be available." %}
+{% assign summary_getTxOutProof="returns a hex-encoded proof that one or more specified transactions were included in a block." %}
 {% assign summary_getTxOutSetInfo="returns statistics about the confirmed unspent transaction output (UTXO) set. Note that this call may take some time and that it only counts outputs from confirmed transactions---it does not count outputs from the memory pool." %}
 {% assign summary_getUnconfirmedBalance="returns the wallet's total unconfirmed balance." %}
 {% assign summary_getWalletInfo="provides information about the wallet." %}
@@ -65,8 +66,8 @@ This file is licensed under the terms of its source texts{%endcomment%}
 {% assign summary_move="moves a specified amount from one account in your wallet to another using an off-block-chain transaction." %}
 {% assign summary_ping-rpc="sends a P2P ping message to all connected nodes to measure ping time. Results are provided by the `getpeerinfo` RPC pingtime and pingwait fields as decimal seconds. The P2P `ping` message is handled in a queue with all other commands, so it measures processing backlog, not just network ping." %}
 {% assign summary_prioritiseTransaction="adds virtual priority or fee to a transaction, allowing it to be accepted into blocks mined by this node (or miners which use this node) with a lower priority or fee. (It can also remove virtual priority or fee, requiring the transaction have a higher priority or fee to be accepted into a locally-mined block.)" %}
-{% assign summary_restGetBlock="gets a block with a particular header hash from the local block database either as a JSON object or as a serialized block." %}
 {% assign summary_restGetBlock-noTxDetails="gets a block with a particular header hash from the local block database either as a JSON object or as a serialized block.  The JSON object includes TXIDs for transactions within the block rather than the complete transactions [GET block][rest get block] returns." %}
+{% assign summary_restGetBlock="gets a block with a particular header hash from the local block database either as a JSON object or as a serialized block." %}
 {% assign summary_restGetTx="gets a hex-encoded serialized transaction or a JSON object describing the transaction. By default, Bitcoin Core only stores complete transaction data for UTXOs and your own transactions, so this method may fail on historic transactions unless you use the non-default `txindex=1` in your Bitcoin Core startup settings." %}
 {% assign summary_sendFrom="spends an amount from a local account to a bitcoin address." %}
 {% assign summary_sendMany="creates and broadcasts a transaction which sends outputs to multiple addresses." %}
@@ -82,6 +83,7 @@ This file is licensed under the terms of its source texts{%endcomment%}
 {% assign summary_validateAddress="returns information about the given Bitcoin address." %}
 {% assign summary_verifyChain="verifies each entry in the local block chain database." %}
 {% assign summary_verifyMessage="verifies a signed message." %}
+{% assign summary_verifyTxOutProof="verifies that a proof points to one or more transactions in a block, returning the transactions the proof commits to and throwing an RPC error if the block is not in our best block chain." %}
 {% assign summary_walletLock="removes the wallet encryption key from memory, locking the wallet. After calling this method, you will need to call `walletpassphrase` again before being able to call any methods which require the wallet to be unlocked." %}
-{% assign summary_walletPassphraseChange="changes the wallet passphrase from 'old passphrase' to 'new passphrase'." %}
 {% assign summary_walletPassphrase="stores the wallet decryption key in memory for the indicated number of seconds. Issuing the `walletpassphrase` command while the wallet is already unlocked will set a new unlock time that overrides the old one." %}
+{% assign summary_walletPassphraseChange="changes the wallet passphrase from 'old passphrase' to 'new passphrase'." %}

_includes/ref/bitcoin-core/rpcs/quick-ref.md

@@ -23,6 +23,7 @@ Use v0.n.n in abbreviation title to prevent autocrossrefing.
 <!-- Bitcoin Core 0.10.0 expected January 2015 -->
 {% assign DEPRECATED='**<abbr title="Deprecated; will be removed in a future version of Bitcoin Core">Deprecated</abbr>**' %}
 {% assign NEW0_10_0='**<abbr title="New in Bitcoin Core v0.10.0">New in 0.10.0</abbr>**' %}
+{% assign NEW0_11_0='**<abbr title="New in Bitcoin Core v0.11.0">New in 0.11.0</abbr>**' %}
 {% assign UPDATED0_10_0='**<abbr title="Updated in Bitcoin Core v0.10.0">Updated in 0.10.0</abbr>**' %}
 
 <!-- Bitcoin Core 0.9.2 June 2014 -->
@@ -54,8 +55,10 @@ Use v0.n.n in abbreviation title to prevent autocrossrefing.
 * [GetMemPoolInfo][rpc getmempoolinfo]: {{summary_getMemPoolInfo}} {{NEW0_10_0}}
 * [GetRawMemPool][rpc getrawmempool]: {{summary_getRawMemPool}}
 * [GetTxOut][rpc gettxout]: {{summary_getTxOut}}
+* [GetTxOutProof][rpc gettxoutproof]: {{summary_getTxOutProof}} {{NEW0_11_0}}
 * [GetTxOutSetInfo][rpc gettxoutsetinfo]: {{summary_getTxOutSetInfo}}
 * [VerifyChain][rpc verifychain]: {{summary_verifyChain}}
+* [VerifyTxOutProof][rpc verifytxoutproof]: {{summary_verifyTxOutProof}} {{NEW0_11_0}}
 
 {% endautocrossref %}
 

_includes/ref/bitcoin-core/rpcs/rpcs/gettxoutproof.md

@@ -0,0 +1,96 @@
+{% comment %}
+This file is licensed under the MIT License (MIT) available on
+http://opensource.org/licenses/MIT.
+{% endcomment %}
+{% assign filename="_includes/ref/bitcoin-core/rpcs/rpcs/gettxoutproof.md" %}
+
+##### GetTxOutProof
+{% include helpers/subhead-links.md %}
+
+{% assign summary_getTxOutProof="returns a hex-encoded proof that one or more specified transactions were included in a block." %}
+
+{% autocrossref %}
+
+The `gettxoutproof` RPC {{summary_getTxOutProof}}
+
+NOTE: By default this function only works when there is an
+unspent output in the UTXO set for this transaction. To make it always work,
+you need to maintain a transaction index, using the `-txindex` command line option, or
+specify the block in which the transaction is included in manually (by block header hash).
+
+*Parameter #1---the transaction hashes to prove*
+
+{% itemplate ntpd1 %}
+- n: "TXIDs"
+  t: "array"
+  p: "Required<br>(exactly 1)"
+  d: "A JSON array of txids to filter"
+
+- n: "→<br>`txid`"
+  t: "string"
+  p: "Required<br>(1 or more)"
+  d: "TXIDs of the transactions to generate proof for.  All transactions must be in the same block"
+
+{% enditemplate %}
+
+*Parameter #2---the block to look for txids in*
+
+{% itemplate ntpd1 %}
+- n: "Header hash"
+  t: "string"
+  p: "Optional<br>(0 or 1)"
+  d: "If specified, looks for txid in the block with this hash"
+
+{% enditemplate %}
+
+*Result---serialized, hex-encoded data for the proof*
+
+{% itemplate ntpd1 %}
+- n: "`result`"
+  t: "string"
+  p: "Required<br>(exactly 1)"
+  d: "A string that is a serialized, hex-encoded data for the proof"
+
+{% enditemplate %}
+
+*Example from Bitcoin Core 0.11.0*
+
+Get the hex-encoded proof that "txid" was included in block 0000000000000000140e84bf183d8d5207d65fbfae596bdf48f684d13d951847:
+
+{% highlight bash %}
+bitcoin-cli gettxoutproof \
+  '''
+    [
+      "f20e44c818ec332d95119507fbe36f1b8b735e2c387db62adbe28e50f7904683"
+    ]
+  ''' \
+  '0000000000000000140e84bf183d8d5207d65fbfae596bdf48f684d13d951847'
+{% endhighlight %}
+
+Result (wrapped):
+
+{% highlight text %}
+03000000394ab3f08f712aa0f1d26c5daa4040b50e96d31d4e8e3c130000000000000000\
+ca89aaa0bbbfcd5d1210c7888501431256135736817100d8c2cf7e4ab9c02b168115d455\
+04dd1418836b20a6cb0800000d3a61beb3859abf1b773d54796c83b0b937968cc4ce3c0f\
+71f981b2407a3241cb8908f2a88ac90a2844596e6019450f507e7efb8542cbe54ea55634\
+c87bee474ee48aced68179564290d476e16cff01b483edcd2004d555c617dfc08200c083\
+08ba511250e459b49d6a465e1ab1d5d8005e0778359c2993236c85ec66bac4bfd974131a\
+dc1ee0ad8b645f459164eb38325ac88f98c9607752bc1b637e16814f0d9d8c2775ac3f20\
+f85260947929ceef16ead56fcbfd77d9dc6126cce1b5aacd9f834690f7508ee2db2ab67d\
+382c5e738b1b6fe3fb079511952d33ec18c8440ef291eb8d3546a971ee4aa5e574b7be7f\
+5aff0b1c989b2059ae5a611c8ce5c58e8e8476246c5e7c6b70e0065f2a6654e2e6cf4efb\
+6ae19bf2548a7d9febf5b0aceaff28610922e1b9e23e52f650a4a11d2986c9c2b09bb168\
+a70a7d4ac16e4d389bc2868ee91da1837d2cd79288bdc680e9c35ebb3ddfd045d69d767b\
+164ec69d5db9f995c045d10af5bd90cd9d1116c3732e14796ef9d1a57fa7bb718c07989e\
+d06ff359bf2009eaf1b9e000c054b87230567991b447757bc6ca8e1bb6e9816ad604dbd6\
+0600
+{% endhighlight %}
+
+*See also*
+
+* [VerifyTxOutProof][rpc verifytxoutproof]: {{summary_verifyTxOutProof}}
+* [`merkleblock` message][merkleblock message]: A description of the
+  format used for the proof.
+
+{% endautocrossref %}

_includes/ref/bitcoin-core/rpcs/rpcs/verifytxoutproof.md

@@ -0,0 +1,73 @@
+{% comment %}
+This file is licensed under the MIT License (MIT) available on
+http://opensource.org/licenses/MIT.
+{% endcomment %}
+{% assign filename="_includes/ref/bitcoin-core/rpcs/rpcs/verifytxoutproof.md" %}
+
+##### VerifyTxOutProof
+{% include helpers/subhead-links.md %}
+
+{% assign summary_verifyTxOutProof="verifies that a proof points to one or more transactions in a block, returning the transactions the proof commits to and throwing an RPC error if the block is not in our best block chain." %}
+
+{% autocrossref %}
+
+The `verifytxoutproof` RPC {{summary_verifyTxOutProof}}
+
+*Parameter #1---The hex-encoded proof generated by gettxoutproof*
+
+{% itemplate ntpd1 %}
+- n: "`proof`"
+  t: "string"
+  p: "Required"
+  d: "A hex-encoded proof"
+
+{% enditemplate %}
+
+*Result---txid(s) which the proof commits to*
+
+{% itemplate ntpd1 %}
+- n: "`result`"
+  t: "string"
+  p: "Required<br>(exactly 1)"
+  d: "The txid(s) which the proof commits to, or empty array if the proof is invalid"
+
+{% enditemplate %}
+
+*Example from Bitcoin Core 0.11.0*
+
+Verify a proof:
+
+{% highlight bash %}
+bitcoin-cli verifytxoutproof \
+03000000394ab3f08f712aa0f1d26c5daa4040b50e96d31d4e8e3c130000000000000000\
+ca89aaa0bbbfcd5d1210c7888501431256135736817100d8c2cf7e4ab9c02b168115d455\
+04dd1418836b20a6cb0800000d3a61beb3859abf1b773d54796c83b0b937968cc4ce3c0f\
+71f981b2407a3241cb8908f2a88ac90a2844596e6019450f507e7efb8542cbe54ea55634\
+c87bee474ee48aced68179564290d476e16cff01b483edcd2004d555c617dfc08200c083\
+08ba511250e459b49d6a465e1ab1d5d8005e0778359c2993236c85ec66bac4bfd974131a\
+dc1ee0ad8b645f459164eb38325ac88f98c9607752bc1b637e16814f0d9d8c2775ac3f20\
+f85260947929ceef16ead56fcbfd77d9dc6126cce1b5aacd9f834690f7508ee2db2ab67d\
+382c5e738b1b6fe3fb079511952d33ec18c8440ef291eb8d3546a971ee4aa5e574b7be7f\
+5aff0b1c989b2059ae5a611c8ce5c58e8e8476246c5e7c6b70e0065f2a6654e2e6cf4efb\
+6ae19bf2548a7d9febf5b0aceaff28610922e1b9e23e52f650a4a11d2986c9c2b09bb168\
+a70a7d4ac16e4d389bc2868ee91da1837d2cd79288bdc680e9c35ebb3ddfd045d69d767b\
+164ec69d5db9f995c045d10af5bd90cd9d1116c3732e14796ef9d1a57fa7bb718c07989e\
+d06ff359bf2009eaf1b9e000c054b87230567991b447757bc6ca8e1bb6e9816ad604dbd6\
+0600
+{% endhighlight %}
+
+Result:
+
+{% highlight json %}
+[
+"f20e44c818ec332d95119507fbe36f1b8b735e2c387db62adbe28e50f7904683"
+]
+{% endhighlight %}
+
+*See also*
+
+* [GetTxOutProof][rpc gettxoutproof]: {{summary_getTxOutProof}}
+* [`merkleblock` message][merkleblock message]: A description of the
+  format used for the proof.
+
+{% endautocrossref %}

_includes/references.md

@@ -110,6 +110,7 @@ http://opensource.org/licenses/MIT.
 [rpc getreceivedbyaddress]: /en/developer-reference#getreceivedbyaddress
 [rpc gettransaction]: /en/developer-reference#gettransaction
 [rpc gettxout]: /en/developer-reference#gettxout
+[rpc gettxoutproof]: /en/developer-reference#gettxoutproof
 [rpc gettxoutsetinfo]: /en/developer-reference#gettxoutsetinfo
 [rpc getunconfirmedbalance]: /en/developer-reference#getunconfirmedbalance
 [rpc getwalletinfo]: /en/developer-reference#getwalletinfo
@@ -145,6 +146,7 @@ http://opensource.org/licenses/MIT.
 [rpc validateaddress]: /en/developer-reference#validateaddress
 [rpc verifychain]: /en/developer-reference#verifychain
 [rpc verifymessage]: /en/developer-reference#verifymessage
+[rpc verifytxoutproof]: /en/developer-reference#verifytxoutproof
 [rpc walletlock]: /en/developer-reference#walletlock
 [rpc walletpassphrase]: /en/developer-reference#walletpassphrase
 [rpc walletpassphrasechange]: /en/developer-reference#walletpassphrasechange

en/developer-reference.md

@@ -151,6 +151,8 @@ untrusted source.
 
 {% include ref/bitcoin-core/rpcs/rpcs/gettxout.md %}
 
+{% include ref/bitcoin-core/rpcs/rpcs/gettxoutproof.md %}
+
 {% include ref/bitcoin-core/rpcs/rpcs/gettxoutsetinfo.md %}
 
 {% include ref/bitcoin-core/rpcs/rpcs/getunconfirmedbalance.md %}
@@ -221,6 +223,8 @@ untrusted source.
 
 {% include ref/bitcoin-core/rpcs/rpcs/verifymessage.md %}
 
+{% include ref/bitcoin-core/rpcs/rpcs/verifytxoutproof.md %}
+
 {% include ref/bitcoin-core/rpcs/rpcs/walletlock.md %}
 
 {% include ref/bitcoin-core/rpcs/rpcs/walletpassphrase.md %}