joshua/dash-docs
1
0
Fork 0
mirror of https://github.com/seigler/dash-docs synced 2025-07-28 10:16:15 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Group _includes files in subfolders

Browse source
This commit is contained in:
Saivann 2015-09-05 20:48:01 -04:00
parent 90dc6a02b6
commit af1704002b
120 changed files with 230 additions and 230 deletions
Download patch file Download diff file Expand all files Collapse all files

98
_includes/devdoc/bitcoin-core/api-intro.md Normal file
View file

@ -0,0 +1,98 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/api-intro.md" %}
## Bitcoin Core APIs
{% include helpers/subhead-links.md %}
### Hash Byte Order
{% include helpers/subhead-links.md %}
{% autocrossref %}
Bitcoin Core RPCs accept and return hashes in the reverse of their
normal byte order. For example, the Unix `sha256sum` command would display the
SHA256(SHA256()) hash of mainnet block 300,000's header as the
following string:
5472ac8b1187bfcf91d6d218bbda1eb2405d7c55f1f8cc820000000000000000
The string above is also how the hash appears in the
previous-header-hash part of block 300,001's header:
<pre>02000000<b>5472ac8b1187bfcf91d6d218bbda1eb2405d7c55f1f8cc82000\
0000000000000</b>ab0aaa377ca3f49b1545e2ae6b0667a08f42e72d8c24ae\
237140e28f14f3bb7c6bcc6d536c890019edd83ccf</pre>
However Bitcoin RPCs use the reverse byte order for hashes, so if you
want to get information about block 300,000 using the `getblock` RPC,
you need to reverse the byte order:
> bitcoin-cli getblock \
000000000000000082ccf8f1557c5d40b21edabb18d2d691cfbf87118bac7254
(Note: hex representation uses two characters to display each byte of
data, which is why the reversed string looks somewhat mangled.)
The rational for the reversal is unknown, but it likely stems from
Bitcoin's use of hash digests (which are byte arrays in C++) as integers
for the purpose of determining whether the hash is below the network
target. Whatever the reason for reversing header hashes, the reversal
also extends to other hashes used in RPCs, such as TXIDs and merkle
roots.
Off-site documentation such as the Bitcoin Wiki tends to use the terms
big endian and little endian as shown in the table below, but they
aren't always consistent. Worse, these two different ways of
representing a hash digest can confuse anyone who looks at the Bitcoin
Core source code and finds a so-called "big endian" value being stored
in a little-endian data type.
As header hashes and TXIDs are widely used as global identifiers in
other Bitcoin software, this reversal of hashes has become the standard
way to refer to certain objects. The table below should make clear where
each byte order is used.
|---------------+---------------------|-----------------|
| Data | Internal Byte Order ("Big Endian") | RPC Byte Order ("Little Endian") |
|---------------|---------------------|-----------------|
| Example: SHA256(SHA256(0x00)) | Hash: 1406...539a | Hash: 9a53...0614 |
|---------------|---------------------|-----------------|
| Header Hashes: SHA256(SHA256(block header)) | Used when constructing block headers | Used by RPCs such as `getblock`; widely used in block explorers |
|---------------|---------------------|-----------------|
| Merkle Roots: SHA256(SHA256(TXIDs and merkle rows)) | Used when constructing block headers | Returned by RPCs such as `getblock` |
|---------------|---------------------|-----------------|
| TXIDs: SHA256(SHA256(transaction)) | Used in transaction inputs | Used by RPCs such as `gettransaction` and transaction data parts of `getblock`; widely used in wallet programs |
|---------------|---------------------|-----------------|
| P2PKH Hashes: RIPEMD160(SHA256(pubkey)) | Used in both addresses and pubkey scripts | **N/A:** RPCs use addresses which use internal byte order |
|---------------|---------------------|-----------------|
| P2SH Hashes: RIPEMD160(SHA256(redeem script)) | Used in both addresses and pubkey scripts | **N/A:** RPCs use addresses which use internal byte order |
|---------------|---------------------|-----------------|
Note: RPCs which return raw results, such as `getrawtransaction` or the
raw mode of `getblock`, always display hashes as they appear in blocks
(internal byte order).
The code below may help you check byte order by generating hashes
from raw hex.
{% endautocrossref %}
{% highlight python %}
#!/usr/bin/env python
from sys import byteorder
from hashlib import sha256
## You can put in $data an 80-byte block header to get its header hash,
## or a raw transaction to get its txid
data = "00".decode("hex")
hash = sha256(sha256(data).digest()).digest()
print "Warning: this code only tested on a little-endian x86_64 arch"
print
print "System byte order:", byteorder
print "Internal-Byte-Order Hash: ", hash.encode('hex_codec')
print "RPC-Byte-Order Hash: ", hash[::-1].encode('hex_codec')
{% endhighlight %}

32
_includes/devdoc/bitcoin-core/rest/intro.md Normal file
View file

@ -0,0 +1,32 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rest/intro.md" %}
### HTTP REST
{% include helpers/subhead-links.md %}
{% autocrossref %}
As of [version 0.10.0][bitcoin core 0.10.0], Bitcoin Core provides
an **unauthenticated** HTTP REST interface. The interface runs on the
same port as the JSON-RPC interface, by default port 8332 for mainnet and
port 18332 for testnet. It must be enabled by either starting Bitcoin
Core with the `-rest` option or by specifying `rest=1` in the
configuration file.
The interface is not intended for public access and is only accessible
from localhost by default.
{{WARNING}} A web browser can access a HTTP REST interface running on
localhost, possibly allowing third parties to use cross-site scripting
attacks to download your transaction and block data, reducing your
privacy. If you have privacy concerns, you should not run a browser on
the same computer as a REST-enabled Bicoin Core node.
The interface uses standard [HTTP status
codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) and
returns a plain-text description of errors for debugging.
{% endautocrossref %}

16
_includes/devdoc/bitcoin-core/rest/quick-reference.md Normal file
View file

@ -0,0 +1,16 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rest/quick-reference.md" %}
#### Quick Reference {#rest-quick-reference}
{% include helpers/subhead-links.md %}
{% autocrossref %}
* [GET Block][rest get block] {{summary_restGetBlock}} {{NEW0_10_0}}
* [GET Block/NoTxDetails][rest get block-notxdetails] {{summary_restGetBlock-noTxDetails}} {{NEW0_10_0}}
* [GET Tx][rest get tx] {{summary_restGetTx}} {{NEW0_10_0}}
{% endautocrossref %}

182
_includes/devdoc/bitcoin-core/rest/requests/get_block-notxdetails.md Normal file
View file

@ -0,0 +1,182 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rest/requests/get_block-notxdetails.md" %}
##### GET Block/NoTxDetails
{% include helpers/subhead-links.md %}
{% 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." %}
{% autocrossref %}
The `GET block<!--noref-->/notxdetails` operation {{summary_restGetBlock-noTxDetails}}
*Request*
{% highlight text %}
GET /block/notxdetails/<hash>.<format>
{% endhighlight %}
*Parameter #1---the header hash of the block to retrieve*
{% itemplate ntpd1 %}
- n: "Header Hash"
t: "path (hex)"
p: "Required<br>(exactly 1)"
d: "The hash of the header of the block to get, encoded as hex in RPC byte order"
{% enditemplate %}
*Parameter #2---the output format*
{% itemplate ntpd1 %}
- n: "Format"
t: "suffix"
p: "Required<br>(exactly 1)"
d: "Set to `.json` for decoded block contents in JSON, or `.bin` or `hex` for a serialized block in binary or hex"
{% enditemplate %}
*Response as JSON*
{% itemplate ntpd1 %}
- n: "Result"
t: "object"
p: "Required<br>(exactly 1)"
d: "An object containing the requested block"
- n: "→<br>`hash`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The hash of this block's block header encoded as hex in RPC byte order. This is the same as the hash provided in parameter #1"
- n: "→<br>`confirmations`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The number of confirmations the transactions in this block have, starting at 1 when this block is at the tip of the best block chain. This score will be -1 if the the block is not part of the best block chain"
- n: "→<br>`size`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The size of this block in serialized block format, counted in bytes"
- n: "→<br>`height`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The height of this block on its block chain"
- n: "→<br>`version`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "This block's version number. See [block version numbers][section block versions]"
- n: "→<br>`merkleroot`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The merkle root for this block, encoded as hex in RPC byte order"
- n: "→<br>`tx`"
t: "array"
p: "Required<br>(exactly 1)"
d: "An array containing all transactions in this block. The transactions appear in the array in the same order they appear in the serialized block"
- n: "→ →<br>TXID"
t: "string (hex)"
p: "Required<br>(1 or more)"
d: "The TXID of a transaction in this block, encoded as hex in RPC byte order"
- n: "→<br>`time`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The value of the *time* field in the block header, indicating approximately when the block was created"
- n: "→<br>`nonce`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The nonce which was successful at turning this particular block into one that could be added to the best block chain"
- n: "→<br>`bits`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The value of the *nBits* field in the block header, indicating the target threshold this block's header had to pass"
- n: "→<br>`difficulty`"
t: "number (real)"
p: "Required<br>(exactly 1)"
d: "The estimated amount of work done to find this block relative to the estimated amount of work done to find block 0"
- n: "→<br>`chainwork`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The estimated number of block header hashes miners had to check from the genesis block to this block, encoded as big-endian hex"
- n: "→<br>`previousblockhash`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The hash of the header of the previous block, encoded as hex in RPC byte order"
- n: "→<br>`nextblockhash`"
t: "string (hex)"
p: "Optional<br>(0 or 1)"
d: "The hash of the next block on the best block chain, if known, encoded as hex in RPC byte order"
{% enditemplate %}
*Examples from Bitcoin Core 0.10.0*
Request a block in hex-encoded serialized block format:
{% highlight bash %}
curl http://localhost:18332/rest/block/notxdetails/000000000fe549a89848c76070d4132872cfb6efe5315d01d7ef77e4900f2d39.hex
{% endhighlight %}
Result (wrapped):
{% highlight text %}
02000000df11c014a8d798395b5059c722ebdf3171a4217ead71bf6e0e99f4c7\
000000004a6f6a2db225c81e77773f6f0457bcb05865a94900ed11356d0b7522\
8efb38c7785d6053ffff001d005d437001010000000100000000000000000000\
00000000000000000000000000000000000000000000ffffffff0d03b4770301\
64062f503253482fffffffff0100f9029500000000232103adb7d8ef6b63de74\
313e0cd4e07670d09a169b13e4eda2d650f529332c47646dac00000000
{% endhighlight %}
Get the same block in JSON:
{% highlight bash %}
curl http://localhost:18332/rest/block/notxdetails/000000000fe549a89848c76070d4132872cfb6efe5315d01d7ef77e4900f2d39.json
{% endhighlight %}
Result (whitespaced added):
{% highlight json %}
{
"hash": "000000000fe549a89848c76070d4132872cfb6efe5315d01d7ef77e4900f2d39",
"confirmations": 91807,
"size": 189,
"height": 227252,
"version": 2,
"merkleroot": "c738fb8e22750b6d3511ed0049a96558b0bc57046f3f77771ec825b22d6a6f4a",
"tx": [
"c738fb8e22750b6d3511ed0049a96558b0bc57046f3f77771ec825b22d6a6f4a"
],
"time": 1398824312,
"nonce": 1883462912,
"bits": "1d00ffff",
"difficulty": 1.0,
"chainwork": "000000000000000000000000000000000000000000000000083ada4a4009841a",
"previousblockhash": "00000000c7f4990e6ebf71ad7e21a47131dfeb22c759505b3998d7a814c011df",
"nextblockhash": "00000000afe1928529ac766f1237657819a11cfcc8ca6d67f119e868ed5b6188"
}
{% endhighlight %}
*See also*
* [GET Block][rest get block]: {{summary_restGetBlock}}
* [GetBlock][rpc getblock] RPC: {{summary_getBlock}}
* [GetBlockHash][rpc getblockhash] RPC: {{summary_getBlockHash}}
* [GetBestBlockHash][rpc getbestblockhash] RPC: {{summary_getBestBlockHash}}
{% endautocrossref %}

211
_includes/devdoc/bitcoin-core/rest/requests/get_block.md Normal file
View file

@ -0,0 +1,211 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rest/requests/get_block.md" %}
##### GET Block
{% include helpers/subhead-links.md %}
{% 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." %}
{% autocrossref %}
The `GET block` operation {{summary_restGetBlock}}
*Request*
{% highlight text %}
GET /block/<hash>.<format>
{% endhighlight %}
*Parameter #1---the header hash of the block to retrieve*
{% itemplate ntpd1 %}
- n: "Header Hash"
t: "path (hex)"
p: "Required<br>(exactly 1)"
d: "The hash of the header of the block to get, encoded as hex in RPC byte order"
{% enditemplate %}
*Parameter #2---the output format*
{% itemplate ntpd1 %}
- n: "Format"
t: "suffix"
p: "Required<br>(exactly 1)"
d: "Set to `.json` for decoded block contents in JSON, or `.bin` or `hex` for a serialized block in binary or hex"
{% enditemplate %}
*Response as JSON*
{% assign DEPTH="→ →" %}
{% include helpers/vars.md %}
{% itemplate ntpd1 %}
- n: "Result"
t: "object"
p: "Required<br>(exactly 1)"
d: "An object containing the requested block"
- n: "→<br>`hash`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The hash of this block's block header encoded as hex in RPC byte order. This is the same as the hash provided in parameter #1"
- n: "→<br>`confirmations`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The number of confirmations the transactions in this block have, starting at 1 when this block is at the tip of the best block chain. This score will be -1 if the the block is not part of the best block chain"
- n: "→<br>`size`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The size of this block in serialized block format, counted in bytes"
- n: "→<br>`height`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The height of this block on its block chain"
- n: "→<br>`version`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "This block's version number. See [block version numbers][section block versions]"
- n: "→<br>`merkleroot`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The merkle root for this block, encoded as hex in RPC byte order"
- n: "→<br>`tx`"
t: "array"
p: "Required<br>(exactly 1)"
d: "An array containing all transactions in this block. The transactions appear in the array in the same order they appear in the serialized block"
- n: "→ →<br>Transaction"
t: "object"
p: "Required<br>(1 or more)"
d: "An object describing a particular transaction within this block"
{{INCLUDE_DECODE_RAW_TRANSACTION}}
- n: "→<br>`time`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The value of the *time* field in the block header, indicating approximately when the block was created"
- n: "→<br>`nonce`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The nonce which was successful at turning this particular block into one that could be added to the best block chain"
- n: "→<br>`bits`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The value of the *nBits* field in the block header, indicating the target threshold this block's header had to pass"
- n: "→<br>`difficulty`"
t: "number (real)"
p: "Required<br>(exactly 1)"
d: "The estimated amount of work done to find this block relative to the estimated amount of work done to find block 0"
- n: "→<br>`chainwork`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The estimated number of block header hashes miners had to check from the genesis block to this block, encoded as big-endian hex"
- n: "→<br>`previousblockhash`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The hash of the header of the previous block, encoded as hex in RPC byte order"
- n: "→<br>`nextblockhash`"
t: "string (hex)"
p: "Optional<br>(0 or 1)"
d: "The hash of the next block on the best block chain, if known, encoded as hex in RPC byte order"
{% enditemplate %}
*Examples from Bitcoin Core 0.10.0*
Request a block in hex-encoded serialized block format:
{% highlight bash %}
curl http://localhost:18332/rest/block/000000000fe549a89848c76070d4132872cfb6efe5315d01d7ef77e4900f2d39.hex
{% endhighlight %}
Result (wrapped):
{% highlight text %}
02000000df11c014a8d798395b5059c722ebdf3171a4217ead71bf6e0e99f4c7\
000000004a6f6a2db225c81e77773f6f0457bcb05865a94900ed11356d0b7522\
8efb38c7785d6053ffff001d005d437001010000000100000000000000000000\
00000000000000000000000000000000000000000000ffffffff0d03b4770301\
64062f503253482fffffffff0100f9029500000000232103adb7d8ef6b63de74\
313e0cd4e07670d09a169b13e4eda2d650f529332c47646dac00000000
{% endhighlight %}
Get the same block in JSON:
{% highlight bash %}
curl http://localhost:18332/rest/block/000000000fe549a89848c76070d4132872cfb6efe5315d01d7ef77e4900f2d39.json
{% endhighlight %}
Result (whitespaced added):
{% highlight json %}
{
"hash": "000000000fe549a89848c76070d4132872cfb6efe5315d01d7ef77e4900f2d39",
"confirmations": 91785,
"size": 189,
"height": 227252,
"version": 2,
"merkleroot": "c738fb8e22750b6d3511ed0049a96558b0bc57046f3f77771ec825b22d6a6f4a",
"tx": [
{
"txid": "c738fb8e22750b6d3511ed0049a96558b0bc57046f3f77771ec825b22d6a6f4a",
"version": 1,
"locktime": 0,
"vin": [
{
"coinbase": "03b477030164062f503253482f",
"sequence": 4294967295
}
],
"vout": [
{
"value": 25.0,
"n": 0,
"scriptPubKey": {
"asm": "03adb7d8ef6b63de74313e0cd4e07670d09a169b13e4eda2d650f529332c47646d OP_CHECKSIG",
"hex": "2103adb7d8ef6b63de74313e0cd4e07670d09a169b13e4eda2d650f529332c47646dac",
"reqSigs": 1,
"type": "pubkey",
"addresses": [
"muXeUp1QYscuPRFH3qHtSrHyG6DQpvg7xZ"
]
}
}
]
}
],
"time": 1398824312,
"nonce": 1883462912,
"bits": "1d00ffff",
"difficulty": 1.0,
"chainwork": "000000000000000000000000000000000000000000000000083ada4a4009841a",
"previousblockhash": "00000000c7f4990e6ebf71ad7e21a47131dfeb22c759505b3998d7a814c011df",
"nextblockhash": "00000000afe1928529ac766f1237657819a11cfcc8ca6d67f119e868ed5b6188"
}
{% endhighlight %}
*See also*
* [GET Block/NoTxDetails][rest get block-notxdetails] {{summary_restGetBlock-noTxDetails}}
* [GetBlock][rpc getblock] RPC: {{summary_getBlock}}
* [GetBlockHash][rpc getblockhash] RPC: {{summary_getBlockHash}}
* [GetBestBlockHash][rpc getbestblockhash] RPC: {{summary_getBestBlockHash}}
{% endautocrossref %}

177
_includes/devdoc/bitcoin-core/rest/requests/get_tx.md Normal file
View file

@ -0,0 +1,177 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rest/requests/get_tx.md" %}
##### GET Tx
{% include helpers/subhead-links.md %}
{% 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." %}
{% autocrossref %}
The `GET tx` operation {{summary_restTx}}
{{reindexNote}}
*Request*
{% highlight text %}
GET /tx/<txid>.<format>
{% endhighlight %}
*Parameter #1---the TXID of the transaction to retrieve*
{% itemplate ntpd1 %}
- n: "TXID"
t: "path (hex)"
p: "Required<br>(exactly 1)"
d: "The TXID of the transaction to get, encoded as hex in RPC byte order"
{% enditemplate %}
*Parameter #2---the output format*
{% itemplate ntpd1 %}
- n: "Format"
t: "suffix"
p: "Required<br>(exactly 1)"
d: "Set to `.json` for decoded transaction contents in JSON, or `.bin` or `hex` for a serialized transaction in binary or hex"
{% enditemplate %}
*Response as JSON*
{% assign DEPTH="" %}
{% include helpers/vars.md %}
{% itemplate ntpd1 %}
- n: "Result"
t: "object"
p: "Required<br>(exactly 1)"
d: "An object describing the request transaction"
{{INCLUDE_DECODE_RAW_TRANSACTION}}
- n: "→<br>`blockhash`"
t: "string (hex)"
p: "Optional<br>(0 or 1)"
d: "If the transaction has been included in a block on the local best block chain, this is the hash of that block encoded as hex in RPC byte order"
- n: "→<br>`confirmations`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "If the transaction has been included in a block on the local best block chain, this is how many confirmations it has. Otherwise, this is `0`"
- n: "→<br>`time`"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "If the transaction has been included in a block on the local best block chain, this is the block header time of that block (may be in the future)"
- n: "→<br>`blocktime`"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "This field is currently identical to the time field described above"
{% enditemplate %}
*Examples from Bitcoin Core 0.10.0*
Request a transaction in hex-encoded serialized transaction format:
{% highlight bash %}
curl http://localhost:18332/rest/tx/ef7c0cbf6ba5af68d2ea239bba709b26ff7b0b669839a63bb01c2cb8e8de481e.hex
{% endhighlight %}
Result (wrapped):
{% highlight text %}
0100000001268a9ad7bfb21d3c086f0ff28f73a064964aa069ebb69a9e437da8\
5c7e55c7d7000000006b483045022100ee69171016b7dd218491faf6e13f53d4\
0d64f4b40123a2de52560feb95de63b902206f23a0919471eaa1e45a0982ed28\
8d374397d30dff541b2dd45a4c3d0041acc0012103a7c1fd1fdec50e1cf3f0cc\
8cb4378cd8e9a2cee8ca9b3118f3db16cbbcf8f326ffffffff0350ac60020000\
00001976a91456847befbd2360df0e35b4e3b77bae48585ae06888ac80969800\
000000001976a9142b14950b8d31620c6cc923c5408a701b1ec0a02088ac002d\
3101000000001976a9140dfc8bafc8419853b34d5e072ad37d1a5159f58488ac\
00000000
{% endhighlight %}
Get the same transaction in JSON:
{% highlight bash %}
curl http://localhost:18332/rest/tx/ef7c0cbf6ba5af68d2ea239bba709b26ff7b0b669839a63bb01c2cb8e8de481e.json
{% endhighlight %}
Result (whitespaced added):
{% highlight json %}
{
"txid": "ef7c0cbf6ba5af68d2ea239bba709b26ff7b0b669839a63bb01c2cb8e8de481e",
"version": 1,
"locktime": 0,
"vin": [
{
"txid": "d7c7557e5ca87d439e9ab6eb69a04a9664a0738ff20f6f083c1db2bfd79a8a26",
"vout": 0,
"scriptSig": {
"asm": "3045022100ee69171016b7dd218491faf6e13f53d40d64f4b40123a2de52560feb95de63b902206f23a0919471eaa1e45a0982ed288d374397d30dff541b2dd45a4c3d0041acc001 03a7c1fd1fdec50e1cf3f0cc8cb4378cd8e9a2cee8ca9b3118f3db16cbbcf8f326",
"hex": "483045022100ee69171016b7dd218491faf6e13f53d40d64f4b40123a2de52560feb95de63b902206f23a0919471eaa1e45a0982ed288d374397d30dff541b2dd45a4c3d0041acc0012103a7c1fd1fdec50e1cf3f0cc8cb4378cd8e9a2cee8ca9b3118f3db16cbbcf8f326"
},
"sequence": 4294967295
}
],
"vout": [
{
"value": 0.39889999999999998,
"n": 0,
"scriptPubKey": {
"asm": "OP_DUP OP_HASH160 56847befbd2360df0e35b4e3b77bae48585ae068 OP_EQUALVERIFY OP_CHECKSIG",
"hex": "76a91456847befbd2360df0e35b4e3b77bae48585ae06888ac",
"reqSigs": 1,
"type": "pubkeyhash",
"addresses": [
"moQR7i8XM4rSGoNwEsw3h4YEuduuP6mxw7"
]
}
},
{
"value": 0.10000000000000001,
"n": 1,
"scriptPubKey": {
"asm": "OP_DUP OP_HASH160 2b14950b8d31620c6cc923c5408a701b1ec0a020 OP_EQUALVERIFY OP_CHECKSIG",
"hex": "76a9142b14950b8d31620c6cc923c5408a701b1ec0a02088ac",
"reqSigs": 1,
"type": "pubkeyhash",
"addresses": [
"mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN"
]
}
},
{
"value": 0.20000000000000001,
"n": 2,
"scriptPubKey": {
"asm": "OP_DUP OP_HASH160 0dfc8bafc8419853b34d5e072ad37d1a5159f584 OP_EQUALVERIFY OP_CHECKSIG",
"hex": "76a9140dfc8bafc8419853b34d5e072ad37d1a5159f58488ac",
"reqSigs": 1,
"type": "pubkeyhash",
"addresses": [
"mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe"
]
}
}
],
"blockhash": "00000000103e0091b7d27e5dc744a305108f0c752be249893c749e19c1c82317",
"confirmations": 91916,
"time": 1398734825,
"blocktime": 1398734825
}
{% endhighlight %}
*See also*
* [GetRawTransaction][rpc getrawtransaction] RPC: {{summary_getRawTransaction}}
* [GetTransaction][rpc gettransaction] RPC: {{summary_getTransaction}}
{% endautocrossref %}

208
_includes/devdoc/bitcoin-core/rpcs/intro.md Normal file
View file

@ -0,0 +1,208 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/intro.md" %}
### Remote Procedure Calls (RPCs)
{% include helpers/subhead-links.md %}
{% autocrossref %}
Bitcoin Core provides a remote procedure call (RPC) interface for various
administrative tasks, wallet operations, and queries about network and block
chain data.
If you start Bitcoin Core using `bitcoin-qt`, the RPC interface is disabled by
default. To enable it, set `server=1` in `bitcoin.conf` or supply the `-server`
argument when invoking the program. If you start Bitcoin Core using `bitcoind`,
the RPC interface is enabled by default.
The interface requires the user to provide a password for authenticating RPC
requests. This password can be set either using the `rpcpassword` property in
`bitcoin.conf` or by supplying the `-rpcpassword` program argument. Optionally a
username can be set using the `rpcuser` configuration value. See the [Examples
Page][devexamples] for more information about setting Bitcoin Core configuration
values.
Open-source client libraries for the RPC interface are readily available in most
modern programming languages, so you probably don't need to write your own from
scratch. Bitcoin Core also ships with its own compiled C++ RPC client,
`bitcoin-cli`, located in the `bin` directory alongside `bitcoind` and
`bitcoin-qt`. The `bitcoin-cli` program can be used as a command-line interface
(CLI) to Bitcoin Core or for making RPC calls from applications written in
languages lacking a suitable native client. The remainder of this section
describes the Bitcoin Core RPC protocol in detail.
The Bitcoin Core RPC service listens for HTTP `POST` requests on port 8332 in
mainnet mode or 18332 in testnet or regtest mode. The port number can be changed
by setting `rpcport` in `bitcoin.conf`. By default the RPC service binds to your
server's [localhost][Localhost] loopback
network<!--noref--> interface so it's not accessible from other servers.
Authentication is implemented using [HTTP basic
authentication][HTTP basic authentication]. RPC
HTTP requests must include a `Content-Type` header set to `text/plain` and a
`Content-Length` header set to the size of the request body.
The format of the request body and response data is based on [version 1.0 of the
JSON-RPC specification][JSON-RPC version 1.0]. Specifically,
the HTTP `POST` data of a request must be a JSON object with the following
format:
| Name | Type | Presence | Description
|----------------------|-----------------|-----------------------------|----------------
| Request | object | Required<br>(exactly 1) | The JSON-RPC<!--noref--> request object
| → <br>`jsonrpc` | number (real) | Optional<br>(0 or 1) | Version indicator for the JSON-RPC<!--noref--> request. Currently ignored by Bitcoin Core.
| → <br>`id` | string | Optional<br>(0 or 1) | An arbitrary string that will be returned with the response. May be omitted or set to an empty string ("")
| → <br>`method` | string | Required<br>(exactly 1) | The RPC method name (e.g. `getblock`). See the RPC section for a list of available methods.
| → <br>`params` | array | Optional<br>(0 or 1) | An array containing positional parameter values for the RPC. May be an empty array or omitted for RPC calls that don't have any required parameters.
| → → <br>Parameter | *any* | Optional<br>(0 or more) | A parameter. May be any JSON type allowed by the particular RPC method
{:.ntpd}
In the table above and in other tables describing RPC input<!--noref--> and
output<!--noref-->, we use the following conventions
* "→" indicates an argument that is the child of a JSON array or JSON object.
For example, "→ → Parameter" above means Parameter is the child of the
`params` array which itself is a child of the Request object.
* Plain-text names like "Request" are unnamed in the actual JSON object
* Code-style names like `params` are literal strings that appear in the JSON
object.
* "Type" is the JSON data type and the specific Bitcoin Core type.
* "Presence" indicates whether or not a field must be present within its
containing array or object. Note that an optional object may still have
required children.
The HTTP response data for a RPC request is a JSON object with the following
format:
| Name | Type | Presence | Description
|----------------------|-----------------|-----------------------------|----------------
| Response | object | Required<br>(exactly 1) | The JSON-RPC<!--noref--> response object.
| → <br>`result` | *any* | Required<br>(exactly 1) | The RPC output<!--noref--> whose type varies by call. Has value `null` if an error occurred.
| → <br>`error` | null/object | Required<br>(exactly 1) | An object describing the error if one occurred, otherwise `null`.
| → → <br>`code` | number (int) | Required<br>(exactly 1) | The error code returned by the RPC function call. See [rpcprotocol.h][] for a full list of error codes and their meanings.
| → → <br>`message` | string | Required<br>(exactly 1) | A text description of the error. May be an empty string ("").
| → <br>`id` | string | Required<br>(exactly 1) | The value of `id` provided with the request. Has value `null` if the `id` field was omitted in the request.
{:.ntpd}
As an example, here is the JSON-RPC<!--noref--> request object for the hash of
the genesis block:
{% highlight json %}
{
"method": "getblockhash",
"params": [0],
"id": "foo"
}
{% endhighlight %}
The command to send this request using `bitcoin-cli` is:
{% highlight bash %}
bitcoin-cli getblockhash 0
{% endhighlight %}
Alternatively, we could `POST` this request using the cURL command-line program
as follows:
{% highlight bash %}
curl --user ':my_secret_password' --data-binary '''
{
"method": "getblockhash",
"params": [0],
"id": "foo"
}''' \
--header 'Content-Type: text/plain;' localhost:8332
{% endhighlight %}
The HTTP response data for this request would be:
{% highlight json %}
{
"result": "000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f",
"error": null,
"id": "foo"
}
{% endhighlight %}
Note: In order to minimize its size, the raw JSON response from Bitcoin Core
doesn't include any extraneous whitespace characters. Here we've added
whitespace to make the object more readable. Speaking of which, `bitcoin-cli`
also transforms the raw response to make it more human-readable. It:
- Adds whitespace indentation to JSON objects
- Expands escaped newline characters ("\n") into actual newlines
- Returns only the value of the `result` field if there's no error
- Strips the outer double-quotes around `result`s of type string
- Returns only the `error` field if there's an error
Continuing with the example above, the output<!--noref--> from the `bitcoin-cli`
command would be simply:
{% highlight text %}
000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f
{% endhighlight %}
If there's an error processing a request, Bitcoin Core sets the `result` field
to `null` and provides information about the error in the `error` field. For
example, a request for the block hash at block height -1 would be met with the
following response (again, whitespace added for clarity):
{% highlight json %}
{
"result": null,
"error": {
"code": -8,
"message": "Block height out of range"
},
"id": "foo"
}
{% endhighlight %}
If `bitcoin-cli` encounters an error, it exits with a non-zero status code and
outputs<!--noref--> the `error` field as text to the process's standard error
stream:
{% highlight text %}
error: {"code": -8, "message": "Block height out of range"}
{% endhighlight %}
Starting in Bitcoin Core version 0.7.0, the RPC interface supports request
batching as described in [version 2.0 of the JSON-RPC
specification][JSON-RPC request batching]. To initiate multiple
RPC requests within a single HTTP request, a client can `POST` a JSON array
filled with Request objects. The HTTP response data is then a JSON array filled
with the corresponding Response objects. Depending on your usage pattern,
request batching may provide significant performance gains. The `bitcoin-cli`
RPC client does not support batch requests.
To keep this documentation compact and readable, the examples for each of the
available RPC calls will be given as `bitcoin-cli` commands:
{% highlight text %}
bitcoin-cli [options] <method name> <param1> <param2> ...
{% endhighlight %}
This translates into an JSON-RPC<!--noref--> Request object of the form:
{% highlight json %}
{
"method": "<method name>",
"params": [ "<param1>", "<param2>", "..." ],
"id": "foo"
}
{% endhighlight %}
[{{WARNING}}][proper money handling]{:#term-proper-money-handling}{:.term} if you write
programs using the JSON-RPC interface, you must ensure they handle high-precision
real numbers correctly. See the [Proper Money Handling][wiki proper money handling]
Bitcoin Wiki article for details and example code.
{% endautocrossref %}

209
_includes/devdoc/bitcoin-core/rpcs/quick-ref.md Normal file
View file

@ -0,0 +1,209 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/quick-ref.md" %}
#### Quick Reference {#rpc-quick-reference}
{% include helpers/subhead-links.md %}
{% comment %}
Styling notes: use highly-visible style for upcoming changes (not yet
released) and changes made in the last 6 months. Use less-visible
style for changes made up to two years ago. Don't point out
changes made more than two years ago.
Use v0.n.n in abbreviation title to prevent autocrossrefing.
{% endcomment %}
<!-- master -->
{% assign NEW_MASTER='**<abbr title="New in Bitcoin Core’s master branch (unreleased)">New in master</abbr>**' %}
{% assign UPDATED_MASTER='**<abbr title="Updated in Bitcoin Core’s master branch (unreleased)">Updated in master</abbr>**' %}
<!-- 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 -->
{% assign NEW0_9_2='*<abbr title="New in Bitcoin Core v0.9.2">New in 0.9.2</abbr>*' %}
<!-- Bitcoin Core 0.9.0 March 2014 -->
{% assign NEW0_9_0='*<abbr title="New in Bitcoin Core v0.9.0">New in 0.9.0</abbr>*' %}
<!-- the summaries used below are defined in the files for the
particular RPC and aggregated into this helper file by the makefile
function manual-update-summaries-file. For example, to edit the
summary for GetBestBlockHash, edit
_includes/rpc/getbestblockhash.md and run `make manual-update-summaries`. -->
{% include helpers/summaries.md %}
#### Block Chain RPCs
{:.no_toc}
<!-- no subhead-links here -->
{% autocrossref %}
* [GetBestBlockHash][rpc getbestblockhash]: {{summary_getBestBlockHash}} {{NEW0_9_0}}
* [GetBlock][rpc getblock]: {{summary_getBlock}}
* [GetBlockChainInfo][rpc getblockchaininfo]: {{summary_getBlockChainInfo}} {{NEW0_9_2}}, {{UPDATED0_10_0}}
* [GetBlockCount][rpc getblockcount]: {{summary_getBlockCount}}
* [GetBlockHash][rpc getblockhash]: {{summary_getBlockHash}}
* [GetChainTips][rpc getchaintips]: {{summary_getChainTips}} {{NEW0_10_0}}
* [GetDifficulty][rpc getdifficulty]: {{summary_getDifficultly}}
* [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 %}
#### Control RPCs
{:.no_toc}
<!-- no subhead-links here -->
{% autocrossref %}
* [GetInfo][rpc getinfo]: {{summary_getInfo}} {{UPDATED0_10_0}}, {{DEPRECATED}}
* [Help][rpc help]: {{summary_help}}
* [Stop][rpc stop]: {{summary_stop}}
{% endautocrossref %}
#### Generating RPCs
{:.no_toc}
<!-- no subhead-links here -->
{% autocrossref %}
* [Generate][rpc generate]: {{summary_generate}} {{NEW_MASTER}}
* [GetGenerate][rpc getgenerate]: {{summary_getGenerate}}
* [SetGenerate][rpc setgenerate]: {{summary_setGenerate}} {{UPDATED_MASTER}}
{% endautocrossref %}
#### Mining RPCs
{:.no_toc}
<!-- no subhead-links here -->
{% autocrossref %}
* [GetBlockTemplate][rpc getblocktemplate]: {{summary_getBlockTemplate}}
* [GetMiningInfo][rpc getmininginfo]: {{summary_getMiningInfo}} {{UPDATED_MASTER}}
* [GetNetworkHashPS][rpc getnetworkhashps]: {{summary_getNetworkHashPS}}
* [PrioritiseTransaction][rpc prioritisetransaction]: {{summary_prioritiseTransaction}} {{NEW0_10_0}}
* [SubmitBlock][rpc submitblock]: {{summary_submitBlock}}
{% endautocrossref %}
#### Network RPCs
{:.no_toc}
<!-- no subhead-links here -->
{% autocrossref %}
* [AddNode][rpc addnode]: {{summary_addNode}}
* [GetAddedNodeInfo][rpc getaddednodeinfo]: {{summary_getAddedNodeInfo}}
* [GetConnectionCount][rpc getconnectioncount]: {{summary_getConnectionCount}}
* [GetNetTotals][rpc getnettotals]: {{summary_getNetTotals}}
* [GetNetworkInfo][rpc getnetworkinfo]: {{summary_getNetworkInfo}} {{NEW0_9_2}}, {{UPDATED0_10_0}}
* [GetPeerInfo][rpc getpeerinfo]: {{summary_getPeerInfo}} {{UPDATED0_10_0}}
* [Ping][rpc ping]: {{summary_ping-rpc}}
{% endautocrossref %}
#### Raw Transaction RPCs
{:.no_toc}
<!-- no subhead-links here -->
{% autocrossref %}
* [CreateRawTransaction][rpc createrawtransaction]: {{summary_createRawTransaction}}
* [DecodeRawTransaction][rpc decoderawtransaction]: {{summary_decodeRawTransaction}}
* [DecodeScript][rpc decodescript]: {{summary_decodeScript}}
* [GetRawTransaction][rpc getrawtransaction]: {{summary_getRawTransaction}}
* [SendRawTransaction][rpc sendrawtransaction]: {{summary_sendRawTransaction}}
* [SignRawTransaction][rpc signrawtransaction]: {{summary_signRawTransaction}}
{% endautocrossref %}
#### Utility RPCs
{:.no_toc}
<!-- no subhead-links here -->
{% autocrossref %}
* [CreateMultiSig][rpc createmultisig]: {{summary_createMultiSig}}
* [EstimateFee][rpc estimatefee]: {{summary_estimateFee}} {{NEW0_10_0}}
* [EstimatePriority][rpc estimatepriority]: {{summary_estimatePriority}} {{NEW0_10_0}}
* [ValidateAddress][rpc validateaddress]: {{summary_validateAddress}}
* [VerifyMessage][rpc verifymessage]: {{summary_verifyMessage}}
{% endautocrossref %}
#### Wallet RPCs
{:.no_toc}
<!-- no subhead-links here -->
{% autocrossref %}
**Note:** the wallet RPCs are only available if Bitcoin Core was built
with [wallet support][]{:#term-wallet-support}{:.term}, which is the
default.
* [AddMultiSigAddress][rpc addmultisigaddress]: {{summary_addMultiSigAddress}}
* [BackupWallet][rpc backupwallet]: {{summary_backupWallet}}
* [DumpPrivKey][rpc dumpprivkey]: {{summary_dumpPrivKey}}
* [DumpWallet][rpc dumpwallet]: {{summary_dumpWallet}}
* [EncryptWallet][rpc encryptwallet]: {{summary_encryptWallet}}
* [GetAccountAddress][rpc getaccountaddress]: {{summary_getAccountAddress}}
* [GetAccount][rpc getaccount]: {{summary_getAccount}}
* [GetAddressesByAccount][rpc getaddressesbyaccount]: {{summary_getAddressesByAccount}}
* [GetBalance][rpc getbalance]: {{summary_getBalance}}
* [GetNewAddress][rpc getnewaddress]: {{summary_getNewAddress}}
* [GetRawChangeAddress][rpc getrawchangeaddress]: {{summary_getRawChangeAddress}}
* [GetReceivedByAccount][rpc getreceivedbyaccount]: {{summary_getReceivedByAccount}}
* [GetReceivedByAddress][rpc getreceivedbyaddress]: {{summary_getReceivedByAddress}}
* [GetTransaction][rpc gettransaction]: {{summary_getTransaction}} {{UPDATED0_10_0}}
* [GetUnconfirmedBalance][rpc getunconfirmedbalance]: {{summary_getUnconfirmedBalance}}
* [GetWalletInfo][rpc getwalletinfo]: {{summary_getWalletInfo}} {{NEW0_9_2}}
* [ImportAddress][rpc importaddress]: {{summary_importAddress}} {{NEW0_10_0}}
* [ImportPrivKey][rpc importprivkey]: {{summary_importPrivKey}}
* [ImportWallet][rpc importwallet]: {{summary_importWallet}}
* [KeyPoolRefill][rpc keypoolrefill]: {{summary_keyPoolRefill}}
* [ListAccounts][rpc listaccounts]: {{summary_listAccounts}} {{UPDATED0_10_0}}
* [ListAddressGroupings][rpc listaddressgroupings]: {{summary_listAddressGroupings}}
* [ListLockUnspent][rpc listlockunspent]: {{summary_listLockUnspent}}
* [ListReceivedByAccount][rpc listreceivedbyaccount]: {{summary_listReceivedByAccount}} {{UPDATED0_10_0}}
* [ListReceivedByAddress][rpc listreceivedbyaddress]: {{summary_listReceivedByAddress}} {{UPDATED0_10_0}}
* [ListSinceBlock][rpc listsinceblock]: {{summary_listSinceBlock}} {{UPDATED0_10_0}}
* [ListTransactions][rpc listtransactions]: {{summary_listTransactions}} {{UPDATED0_10_0}}
* [ListUnspent][rpc listunspent]: {{summary_listUnspent}} {{UPDATED0_10_0}}
* [LockUnspent][rpc lockunspent]: {{summary_lockUnspent}}
* [Move][rpc move]: {{summary_move}}
* [SendFrom][rpc sendfrom]: {{summary_sendFrom}}
* [SendMany][rpc sendmany]: {{summary_sendMany}}
* [SendToAddress][rpc sendtoaddress]: {{summary_sendToAddress}}
* [SetAccount][rpc setaccount]: {{summary_setAccount}}
* [SetTxFee][rpc settxfee]: {{summary_setTxFee}}
* [SignMessage][rpc signmessage]: {{summary_signMessage}}
* [WalletLock][rpc walletlock]: {{summary_walletLock}}
* [WalletPassphrase][rpc walletpassphrase]: {{summary_walletPassphrase}}
* [WalletPassphraseChange][rpc walletpassphrasechange]: {{summary_walletPassphraseChange}}
{% endautocrossref %}
#### Removed RPCs
{:.no_toc}
<!-- no subhead-links here -->
{% autocrossref %}
* [GetHashesPerSec][rpc gethashespersec]: {{summary_getHashesPerSec}}
* [GetWork][rpc getwork]: {{summary_getWork}}
{% endautocrossref %}

95
_includes/devdoc/bitcoin-core/rpcs/rpcs/addmultisigaddress.md Normal file
View file

@ -0,0 +1,95 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/addmultisigaddress.md" %}
##### AddMultiSigAddress
{% include helpers/subhead-links.md %}
{% assign summary_addMultiSigAddress="adds a P2SH multisig address to the wallet." %}
{% autocrossref %}
*Requires wallet support.*
The `addmultisigaddress` RPC {{summary_addMultiSigAddress}}
*Parameter #1---the number of signatures required*
{% itemplate ntpd1 %}
- n: "Required"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The minimum (*m*) number of signatures required to spend this m-of-n multisig script"
{% enditemplate %}
*Parameter #2---the full public keys, or addresses for known public keys*
{% itemplate ntpd1 %}
- n: "Keys Or Addresses"
t: "array"
p: "Required<br>(exactly 1)"
d: "An array of strings with each string being a public key or address"
- n: "→<br>Key Or Address"
t: "string"
p: "Required<br>(1 or more)"
d: "A public key against which signatures will be checked. Alternatively, this may be a P2PKH address belonging to the wallet---the corresponding public key will be substituted. There must be at least as many keys as specified by the Required parameter, and there may be more keys"
{% enditemplate %}
*Parameter #3---the account name*
{% itemplate ntpd1 %}
- n: "Account"
t: "string"
p: "Optional<br>(0 or 1)"
d: "The account name in which the address should be stored. Default is the default account, \"\" (an empty string)"
{% enditemplate %}
*Result---a P2SH address printed and stored in the wallet*
{% itemplate ntpd1 %}
- n: "`result`"
t: "string (base58)"
p: "Required<br>(exactly 1)"
d: "The P2SH multisig address. The address will also be added to the wallet, and outputs paying that address will be tracked by the wallet"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Adding a 2-of-3 P2SH multisig address to the "test account" by mixing
two P2PKH addresses and one full public key:
{% highlight bash %}
bitcoin-cli -testnet addmultisigaddress \
2 \
'''
[
"mjbLRSidW1MY8oubvs4SMEnHNFXxCcoehQ",
"02ecd2d250a76d204011de6bc365a56033b9b3a149f679bc17205555d3c2b2854f",
"mt17cV37fBqZsnMmrHnGCm9pM28R1kQdMG"
]
''' \
'test account'
{% endhighlight %}
Result:
{% highlight text %}
2MyVxxgNBk5zHRPRY2iVjGRJHYZEp1pMCSq
{% endhighlight %}
(New P2SH multisig address also stored in wallet.)
*See also*
* [CreateMultiSig][rpc createmultisig]: {{summary_createMultiSig}}
* [DecodeScript][rpc decodescript]: {{summary_decodeScript}}
* [Pay-To-Script-Hash (P2SH)][/en/glossary/p2sh-address]
{% endautocrossref %}

60
_includes/devdoc/bitcoin-core/rpcs/rpcs/addnode.md Normal file
View file

@ -0,0 +1,60 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/addnode.md" %}
##### AddNode
{% include helpers/subhead-links.md %}
{% assign summary_addNode="attempts to add or remove a node from the addnode list, or to try a connection to a node once." %}
{% autocrossref %}
The `addnode` RPC {{summary_addNode}}
*Parameter #1---hostname/IP address and port of node to add or remove*
{% itemplate ntpd1 %}
- n: "Node"
t: "string"
p: "Required<br>(exactly 1)"
d: "The node to add as a string in the form of `<IP address>:<port>`. The IP address may be a hostname resolvable through DNS, an IPv4 address, an IPv4-as-IPv6 address, or an IPv6 address"
{% enditemplate %}
*Parameter #2---whether to add or remove the node, or to try only once to connect*
{% itemplate ntpd1 %}
- n: "Command"
t: "string"
p: "Required<br>(exactly 1)"
d: "What to do with the IP address above. Options are:<br>• `add` to add a node to the addnode list. This will not connect immediately if the outgoing connection slots are full<br>• `remove` to remove a node from the list. If currently connected, this will disconnect immediately<br>• `onetry` to immediately attempt connection to the node even if the outgoing connection slots are full; this will only attempt the connection once"
{% enditemplate %}
*Result---`null` plus error on failed remove*
{% itemplate ntpd1 %}
- n: "`result`"
t: "null"
p: "Required<br>(exactly 1)"
d: "Always JSON `null` whether the node was added, removed, tried-and-connected, or tried-and-not-connected. The JSON-RPC error field will be set only if you try removing a node that is not on the addnodes list"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Try connecting to the following node.
{% highlight bash %}
bitcoin-cli -testnet addnode 192.0.2.113:18333 onetry
{% endhighlight %}
Result (no output from `bitcoin-cli` because result is set to `null`).
*See also*
* [GetAddedNodeInfo][rpc getaddednodeinfo]: {{summary_getAddedNodeInfo}}
{% endautocrossref %}

49
_includes/devdoc/bitcoin-core/rpcs/rpcs/backupwallet.md Normal file
View file

@ -0,0 +1,49 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/backupwallet.md" %}
##### BackupWallet
{% include helpers/subhead-links.md %}
{% assign summary_backupWallet="safely copies `wallet.dat`<!--noref--> to the specified file, which can be a directory or a path with filename." %}
{% autocrossref %}
*Requires wallet support.*
The `backupwallet` RPC {{summary_backupWallet}}
*Parameter #1---destination directory or filename*
{% itemplate ntpd1 %}
- n: "Destination"
t: "string"
p: "Required<br>(exactly 1)"
d: "A filename or directory name. If a filename, it will be created or overwritten. If a directory name, the file `wallet.dat`<!--noref--> will be created or overwritten within that directory"
{% enditemplate %}
*Result---`null` or error*
{% itemplate ntpd1 %}
- n: "`result`"
t: "null"
p: "Required<br>(exactly 1)"
d: "Always `null` whether success or failure. The JSON-RPC error and message fields will be set if a failure occurred"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet backupwallet /tmp/backup.dat
{% endhighlight %}
*See also*
* [DumpWallet][rpc dumpwallet]: {{summary_dumpWallet}}
* [ImportWallet][rpc importwallet]: {{summary_importWallet}}
{% endautocrossref %}

91
_includes/devdoc/bitcoin-core/rpcs/rpcs/createmultisig.md Normal file
View file

@ -0,0 +1,91 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/createmultisig.md" %}
##### CreateMultiSig
{% include helpers/subhead-links.md %}
{% assign summary_createMultiSig="creates a P2SH multi-signature address." %}
{% autocrossref %}
The `createmultisig` RPC {{summary_createMultiSig}}
*Parameter #1---the number of signatures required*
{% itemplate ntpd1 %}
- n: "Required"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The minimum (*m*) number of signatures required to spend this m-of-n multisig script"
{% enditemplate %}
*Parameter #2---the full public keys, or addresses for known public keys*
{% itemplate ntpd1 %}
- n: "Keys Or Addresses"
t: "array"
p: "Required<br>(exactly 1)"
d: "An array of strings with each string being a public key or address"
- n: "→<br>Key Or Address"
t: "string"
p: "Required<br>(1 or more)"
d: "A public key against which signatures will be checked. If wallet support is enabled, this may be a P2PKH address belonging to the wallet---the corresponding public key will be substituted. There must be at least as many keys as specified by the Required parameter, and there may be more keys"
{% enditemplate %}
*Result---P2SH address and hex-encoded redeem script*
{% itemplate ntpd1 %}
- n: "`result`"
t: "object"
p: "Required<br>(exactly 1)"
d: "An object describing the multisig address"
- n: "→<br>`address`"
t: "string (base58)"
p: "Required<br>(exactly 1)"
d: "The P2SH address for this multisig redeem script"
- n: "→<br>`redeemScript`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The multisig redeem script encoded as hex"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Creating a 2-of-3 P2SH multisig address by mixing two P2PKH addresses and
one full public key:
{% highlight bash %}
bitcoin-cli -testnet createmultisig 2 '''
[
"mjbLRSidW1MY8oubvs4SMEnHNFXxCcoehQ",
"02ecd2d250a76d204011de6bc365a56033b9b3a149f679bc17205555d3c2b2854f",
"mt17cV37fBqZsnMmrHnGCm9pM28R1kQdMG"
]
'''
{% endhighlight %}
Result:
{%highlight json %}
{
"address" : "2MyVxxgNBk5zHRPRY2iVjGRJHYZEp1pMCSq",
"redeemScript" : "522103ede722780d27b05f0b1169efc90fa15a601a32fc6c3295114500c586831b6aaf2102ecd2d250a76d204011de6bc365a56033b9b3a149f679bc17205555d3c2b2854f21022d609d2f0d359e5bc0e5d0ea20ff9f5d3396cb5b1906aa9c56a0e7b5edc0c5d553ae"
}
{% endhighlight %}
*See also*
* [AddMultiSigAddress][rpc addmultisigaddress]: {{summary_addMultiSigAddress}}
* [DecodeScript][rpc decodescript]: {{summary_decodeScript}}
* [Pay-To-Script-Hash (P2SH)][/en/glossary/p2sh-address]
{% endautocrossref %}

93
_includes/devdoc/bitcoin-core/rpcs/rpcs/createrawtransaction.md Normal file
View file

@ -0,0 +1,93 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/createrawtransaction.md" %}
##### CreateRawTransaction
{% include helpers/subhead-links.md %}
{% assign summary_createRawTransaction="creates an unsigned serialized transaction that spends a previous output to a new output with a P2PKH or P2SH address. The transaction is not stored in the wallet or transmitted to the network." %}
{% autocrossref %}
The `createrawtransaction` RPC {{summary_createRawTransaction}}
*Parameter #1---references to previous outputs*
{% itemplate ntpd1 %}
- n: "Outpoints"
t: "array"
p: "Required<br>(exactly 1)"
d: "An array of objects, each one being an unspent outpoint"
- n: "→ Outpoint"
t: "object"
p: "Required<br>(1 or more)"
d: "An object describing a particular unspent outpoint"
- n: "→ →<br>`txid`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The TXID of the outpoint encoded as hex in RPC byte order"
- n: "→ →<br>`vout`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The output index number (vout) of the outpoint; the first output in a transaction is index `0`"
{% enditemplate %}
*Parameter #2---P2PKH or P2SH addresses and amounts*
{% itemplate ntpd1 %}
- n: "Outputs"
t: "object"
p: "Required<br>(exactly 1)"
d: "The addresses and amounts to pay"
- n: "→<br>Address/Amount"
t: "string : number (bitcoins)"
p: "Required<br>(1 or more)"
d: "A key/value pair with the address to pay as a string (key) and the amount to pay that address (value) in bitcoins"
{% enditemplate %}
*Result---the unsigned raw transaction in hex*
{% itemplate ntpd1 %}
- n: "`result`"
t: "string"
p: "Required<br>(Exactly 1)"
d: "The resulting unsigned raw transaction in serialized transaction format encoded as hex. If the transaction couldn't be generated, this will be set to JSON `null` and the JSON-RPC error field may contain an error message"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet createrawtransaction '''
[
{
"txid": "1eb590cd06127f78bf38ab4140c4cdce56ad9eb8886999eb898ddf4d3b28a91d",
"vout" : 0
}
]''' '{ "mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe": 0.13 }'
{% endhighlight %}
Result (wrapped):
{% highlight text %}
01000000011da9283b4ddf8d89eb996988b89ead56cecdc44041ab38bf787f12\
06cd90b51e0000000000ffffffff01405dc600000000001976a9140dfc8bafc8\
419853b34d5e072ad37d1a5159f58488ac00000000
{% endhighlight %}
*See also*
* [DecodeRawTransaction][rpc decoderawtransaction]: {{summary_decodeRawTransaction}}
* [SignRawTransaction][rpc signrawtransaction]: {{summary_signRawTransaction}}
* [SendRawTransaction][rpc sendrawtransaction]: {{summary_sendRawTransaction}}
* [Serialized Transaction Format][raw transaction format]
{% endautocrossref %}

121
_includes/devdoc/bitcoin-core/rpcs/rpcs/decoderawtransaction.md Normal file
View file

@ -0,0 +1,121 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/decoderawtransaction.md" %}
##### DecodeRawTransaction
{% include helpers/subhead-links.md %}
{% assign summary_decodeRawTransaction="decodes a serialized transaction hex string into a JSON object describing the transaction." %}
{% autocrossref %}
The `decoderawtransaction` RPC {{summary_decodeRawTransaction}}
*Parameter #1---serialized transaction in hex*
{% itemplate ntpd1 %}
- n: "Serialized Transaction"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The transaction to decode in serialized transaction format"
{% enditemplate %}
*Result---the decoded transaction*
{% itemplate ntpd1 %}
- n: "`result`"
t: "object"
p: "Required<br>(exactly 1)"
d: "An object describing the decoded transaction, or JSON `null` if the transaction could not be decoded"
{{INCLUDE_DECODE_RAW_TRANSACTION}}
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Decode a signed one-input, three-output transaction:
{% highlight bash %}
bitcoin-cli -testnet decoderawtransaction 0100000001268a9ad7bfb2\
1d3c086f0ff28f73a064964aa069ebb69a9e437da85c7e55c7d7000000006b48\
3045022100ee69171016b7dd218491faf6e13f53d40d64f4b40123a2de52560f\
eb95de63b902206f23a0919471eaa1e45a0982ed288d374397d30dff541b2dd4\
5a4c3d0041acc0012103a7c1fd1fdec50e1cf3f0cc8cb4378cd8e9a2cee8ca9b\
3118f3db16cbbcf8f326ffffffff0350ac6002000000001976a91456847befbd\
2360df0e35b4e3b77bae48585ae06888ac80969800000000001976a9142b1495\
0b8d31620c6cc923c5408a701b1ec0a02088ac002d3101000000001976a9140d\
fc8bafc8419853b34d5e072ad37d1a5159f58488ac00000000
{% endhighlight %}
Result:
{% highlight json %}
{
"txid" : "ef7c0cbf6ba5af68d2ea239bba709b26ff7b0b669839a63bb01c2cb8e8de481e",
"version" : 1,
"locktime" : 0,
"vin" : [
{
"txid" : "d7c7557e5ca87d439e9ab6eb69a04a9664a0738ff20f6f083c1db2bfd79a8a26",
"vout" : 0,
"scriptSig" : {
"asm" : "3045022100ee69171016b7dd218491faf6e13f53d40d64f4b40123a2de52560feb95de63b902206f23a0919471eaa1e45a0982ed288d374397d30dff541b2dd45a4c3d0041acc001 03a7c1fd1fdec50e1cf3f0cc8cb4378cd8e9a2cee8ca9b3118f3db16cbbcf8f326",
"hex" : "483045022100ee69171016b7dd218491faf6e13f53d40d64f4b40123a2de52560feb95de63b902206f23a0919471eaa1e45a0982ed288d374397d30dff541b2dd45a4c3d0041acc0012103a7c1fd1fdec50e1cf3f0cc8cb4378cd8e9a2cee8ca9b3118f3db16cbbcf8f326"
},
"sequence" : 4294967295
}
],
"vout" : [
{
"value" : 0.39890000,
"n" : 0,
"scriptPubKey" : {
"asm" : "OP_DUP OP_HASH160 56847befbd2360df0e35b4e3b77bae48585ae068 OP_EQUALVERIFY OP_CHECKSIG",
"hex" : "76a91456847befbd2360df0e35b4e3b77bae48585ae06888ac",
"reqSigs" : 1,
"type" : "pubkeyhash",
"addresses" : [
"moQR7i8XM4rSGoNwEsw3h4YEuduuP6mxw7"
]
}
},
{
"value" : 0.10000000,
"n" : 1,
"scriptPubKey" : {
"asm" : "OP_DUP OP_HASH160 2b14950b8d31620c6cc923c5408a701b1ec0a020 OP_EQUALVERIFY OP_CHECKSIG",
"hex" : "76a9142b14950b8d31620c6cc923c5408a701b1ec0a02088ac",
"reqSigs" : 1,
"type" : "pubkeyhash",
"addresses" : [
"mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN"
]
}
},
{
"value" : 0.20000000,
"n" : 2,
"scriptPubKey" : {
"asm" : "OP_DUP OP_HASH160 0dfc8bafc8419853b34d5e072ad37d1a5159f584 OP_EQUALVERIFY OP_CHECKSIG",
"hex" : "76a9140dfc8bafc8419853b34d5e072ad37d1a5159f58488ac",
"reqSigs" : 1,
"type" : "pubkeyhash",
"addresses" : [
"mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe"
]
}
}
]
}
{% endhighlight %}
*See also*
* [CreateRawTransaction][rpc createrawtransaction]: {{summary_createRawTransaction}}
* [SignRawTransaction][rpc signrawtransaction]: {{summary_signRawTransaction}}
* [SendRawTransaction][rpc sendrawtransaction]: {{summary_sendRawTransaction}}
{% endautocrossref %}

98
_includes/devdoc/bitcoin-core/rpcs/rpcs/decodescript.md Normal file
View file

@ -0,0 +1,98 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/decodescript.md" %}
##### DecodeScript
{% include helpers/subhead-links.md %}
{% assign summary_decodeScript="decodes a hex-encoded P2SH redeem script." %}
{% autocrossref %}
The `decodescript` RPC {{summary_decodeScript}}
*Parameter #1---a hex-encoded redeem script*
{% itemplate ntpd1 %}
- n: "Redeem Script"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The redeem script to decode as a hex-encoded serialized script"
{% enditemplate %}
*Result---the decoded script*
{% itemplate ntpd1 %}
- n: "`result`"
t: "object"
p: "Required<br>(exactly 1)"
d: "An object describing the decoded script, or JSON `null` if the script could not be decoded"
- n: "→<br>`asm`"
t: "string"
p: "Required<br>(exactly 1)"
d: "The redeem script in decoded form with non-data-pushing op codes listed. May be empty"
- n: "→<br>`type`"
t: "string"
p: "Optional<br>(0 or 1)"
d: "The type of script. This will be one of the following:<br>• `pubkey` for a P2PK script inside P2SH<br>• `pubkeyhash` for a P2PKH script inside P2SH<br>• `multisig` for a multisig script inside P2SH<br>• `nonstandard` for unknown scripts"
- n: "→<br>`reqSigs`"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "The number of signatures required; this is always `1` for P2PK or P2PKH within P2SH. It may be greater than 1 for P2SH multisig. This value will not be returned for `nonstandard` script types (see the `type` key above)"
- n: "→<br>`addresses`"
t: "array"
p: "Optional<br>(0 or 1)"
d: "A P2PKH addresses used in this script, or the computed P2PKH addresses of any pubkeys in this script. This array will not be returned for `nonstandard` script types"
- n: "→ →<br>Address"
t: "string"
p: "Required<br>(1 or more)"
d: "A P2PKH address"
- n: "→<br>`p2sh`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The P2SH address of this redeem script"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
A 2-of-3 P2SH multisig pubkey script:
{% highlight bash %}
bitcoin-cli -testnet decodescript 522103ede722780d27b05f0b1169ef\
c90fa15a601a32fc6c3295114500c586831b6aaf2102ecd2d250a76d204011de\
6bc365a56033b9b3a149f679bc17205555d3c2b2854f21022d609d2f0d359e5b\
c0e5d0ea20ff9f5d3396cb5b1906aa9c56a0e7b5edc0c5d553ae
{% endhighlight %}
Result:
{% highlight json %}
{
"asm" : "2 03ede722780d27b05f0b1169efc90fa15a601a32fc6c3295114500c586831b6aaf 02ecd2d250a76d204011de6bc365a56033b9b3a149f679bc17205555d3c2b2854f 022d609d2f0d359e5bc0e5d0ea20ff9f5d3396cb5b1906aa9c56a0e7b5edc0c5d5 3 OP_CHECKMULTISIG",
"reqSigs" : 2,
"type" : "multisig",
"addresses" : [
"mjbLRSidW1MY8oubvs4SMEnHNFXxCcoehQ",
"mo1vzGwCzWqteip29vGWWW6MsEBREuzW94",
"mt17cV37fBqZsnMmrHnGCm9pM28R1kQdMG"
],
"p2sh" : "2MyVxxgNBk5zHRPRY2iVjGRJHYZEp1pMCSq"
}
{% endhighlight %}
*See also*
* [CreateMultiSig][rpc createmultisig]: {{summary_createMultiSig}}
* [Pay-To-Script-Hash (P2SH)][/en/glossary/p2sh-address]
{% endautocrossref %}

56
_includes/devdoc/bitcoin-core/rpcs/rpcs/dumpprivkey.md Normal file
View file

@ -0,0 +1,56 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/dumpprivkey.md" %}
##### DumpPrivKey
{% include helpers/subhead-links.md %}
{% assign summary_dumpPrivKey="returns the wallet-import-format (WIP) private key corresponding to an address. (But does not remove it from the wallet.)" %}
{% autocrossref %}
*Requires wallet support. Requires an unlocked wallet or an
unencrypted wallet.*
The `dumpprivkey` RPC {{summary_dumpPrivKey}}
*Parameter #1---the address corresponding to the private key to get*
{% itemplate ntpd1 %}
- n: "P2PKH Address"
t: "string (base58)"
p: "Required<br>(exactly 1)"
d: "The P2PKH address corresponding to the private key you want returned. Must be the address corresponding to a private key in this wallet"
{% enditemplate %}
*Result---the private key*
{% itemplate ntpd1 %}
- n: "`result`"
t: "string (base58)"
p: "Required<br>(exactly 1)"
d: "The private key encoded as base58check using wallet import format"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet dumpprivkey moQR7i8XM4rSGoNwEsw3h4YEuduuP6mxw7
{% endhighlight %}
Result:
{% highlight text %}
cTVNtBK7mBi2yc9syEnwbiUpnpGJKohDWzXMeF4tGKAQ7wvomr95
{% endhighlight %}
*See also*
* [ImportPrivKey][rpc importprivkey]: {{summary_importPrivKey}}
* [DumpWallet][rpc dumpwallet]: {{summary_dumpWallet}}
{% endautocrossref %}

68
_includes/devdoc/bitcoin-core/rpcs/rpcs/dumpwallet.md Normal file
View file

@ -0,0 +1,68 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/dumpwallet.md" %}
##### DumpWallet
{% include helpers/subhead-links.md %}
{% assign summary_dumpWallet="creates or overwrites a file with all wallet keys in a human-readable format." %}
{% autocrossref %}
*Requires wallet support. Requires an unlocked wallet or an unencrypted
wallet.*
The `dumpwallet` RPC {{summary_dumpWallet}}
*Parameter #1---a filename*
{% itemplate ntpd1 %}
- n: "Filename"
t: "string"
p: "Required<br>(exactly 1)"
d: "The file in which the wallet dump will be placed. May be prefaced by an absolute file path. An existing file with that name will be overwritten"
{% enditemplate %}
*Result---`null` or error*
{% itemplate ntpd1 %}
- n: "`result`"
t: "null"
p: "Required<br>(exactly 1)"
d: "Always `null` whether success or failure. The JSON-RPC error and message fields will be set if a failure occurred"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Create a wallet dump and then print its first 10 lines.
{% highlight bash %}
bitcoin-cli -testnet dumpwallet /tmp/dump.txt
head /tmp/dump.txt
{% endhighlight %}
Results (only showing the first 10 lines):
{% highlight bash %}
# Wallet dump created by Bitcoin v0.9.1.0-g026a939-beta (Tue, 8 Apr 2014 12:04:06 +0200)
# * Created on 2014-04-29T20:46:09Z
# * Best block at time of backup was 227221 (0000000026ede4c10594af8087748507fb06dcd30b8f4f48b9cc463cabc9d767),
# mined on 2014-04-29T21:15:07Z
cTtefiUaLfXuyBXJBBywSdg8soTEkBNh9yTi1KgoHxUYxt1xZ2aA 2014-02-05T15:44:03Z label=test1 # addr=mnUbTmdAFD5EAg3348Ejmonub7JcWtrMck
cQNY9v93Gyt8KmwygFR59bDhVs3aRDkuT8pKaCBpop82TZ8ND1tH 2014-02-05T16:58:41Z reserve=1 # addr=mp4MmhTp3au21HPRz5waf6YohGumuNnsqT
cNTEPzZH9mjquFFADXe5S3BweNiHLUKD6PvEKEsHApqjX4ZddeU6 2014-02-05T16:58:41Z reserve=1 # addr=n3pdvsxveMBkktjsGJixfSbxacRUwJ9jQW
cTVNtBK7mBi2yc9syEnwbiUpnpGJKohDWzXMeF4tGKAQ7wvomr95 2014-02-05T16:58:41Z change=1 # addr=moQR7i8XM4rSGoNwEsw3h4YEuduuP6mxw7
cNCD679B4xi17jb4XeLpbRbZCbYUugptD7dCtUTfSU4KPuK2DyKT 2014-02-05T16:58:41Z reserve=1 # addr=mq8fzjxxVbAKxUGPwaSSo3C4WaUxdzfw3C
{% endhighlight %}
*See also*
* [BackupWallet][rpc backupwallet]: {{summary_backupWallet}}
* [ImportWallet][rpc importwallet]: {{summary_importWallet}}
{% endautocrossref %}

64
_includes/devdoc/bitcoin-core/rpcs/rpcs/encryptwallet.md Normal file
View file

@ -0,0 +1,64 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/encryptwallet.md" %}
##### EncryptWallet
{% include helpers/subhead-links.md %}
{% assign summary_encryptWallet="encrypts the wallet with a passphrase. This is only to enable encryption for the first time. After encryption is enabled, you will need to enter the passphrase to use private keys." %}
{% autocrossref %}
*Requires wallet support.*
The `encryptwallet` RPC {{summary_encryptWallet}}
{{WARNING}} if using this RPC on the command line, remember
that your shell probably saves your command lines (including the value
of the passphrase parameter). In addition, there is no RPC to completely
disable encryption. If you want to return to an unencrypted wallet, you
must create a new wallet and restore your data from a backup made with
the `dumpwallet` RPC.
*Parameter #1---a passphrase*
{% itemplate ntpd1 %}
- n: "Passphrase"
t: "string"
p: "Required<br>(exactly 1)"
d: "The passphrase to use for the encrypted wallet. Must be at least one character"
{% enditemplate %}
*Result---a notice (with program shutdown)*
{% itemplate ntpd1 %}
- n: "`result`"
t: "string"
p: "Required<br>(exactly 1)"
d: "A notice that the server is stopping and that you need to make a new backup. The wallet is now encrypted"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet encryptwallet "test"
{% endhighlight %}
Result:
{% highlight text %}
wallet encrypted; Bitcoin server stopping, restart to run with encrypted
wallet. The keypool has been flushed, you need to make a new backup.
{% endhighlight %}
*See also*
* [WalletPassphrase][rpc walletpassphrase]: {{summary_walletPassphrase}}
* [WalletLock][rpc walletlock]: {{summary_walletLock}}
* [WalletPassphraseChange][rpc walletpassphrasechange]: {{summary_walletPassphraseChange}}
{% endautocrossref %}

67
_includes/devdoc/bitcoin-core/rpcs/rpcs/estimatefee.md Normal file
View file

@ -0,0 +1,67 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/estimatefee.md" %}
##### EstimateFee
{% include helpers/subhead-links.md %}
{% 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." %}
{% autocrossref %}
*Added in Bitcoin Core 0.10.0.*
The `estimatefee` RPC {{summary_estimateFee}}
*Parameter #1---how many blocks the transaction may wait before being included*
{% itemplate ntpd1 %}
- n: "Blocks"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The maximum number of blocks a transaction should have to wait before it is predicted to be included in a block"
{% enditemplate %}
*Result---the fee the transaction needs to pay per kilobyte*
{% itemplate ntpd1 %}
- n: "`result`"
t: "number (bitcoins)"
p: "Required<br>(exactly 1)"
d: "The estimated fee the transaction should pay in order to be included within the specified number of blocks. If the node doesn't have enough information to make an estimate, the value `-1` will be returned"
{% enditemplate %}
*Examples from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli estimatefee 6
{% endhighlight %}
Result:
{% highlight json %}
0.00026809
{% endhighlight %}
Requesting data the node can't calculate yet:
{% highlight bash %}
bitcoin-cli estimatefee 100
{% endhighlight %}
Result:
{% highlight json %}
-1.00000000
{% endhighlight %}
*See also*
* [EstimatePriority][rpc estimatepriority]: {{summary_estimatePriority}}
* [SetTxFee][rpc settxfee]: {{summary_setTxFee}}
{% endautocrossref %}

68
_includes/devdoc/bitcoin-core/rpcs/rpcs/estimatepriority.md Normal file
View file

@ -0,0 +1,68 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/estimatepriority.md" %}
##### EstimatePriority
{% include helpers/subhead-links.md %}
{% autocrossref %}
{% 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." %}
*Added in Bitcoin Core 0.10.0.*
The `estimatepriority` RPC {{summary_estimatePriority}}
Transaction priority is relative to a transaction's byte size.
*Parameter #1---how many blocks the transaction may wait before being included as a free high-priority transaction*
{% itemplate ntpd1 %}
- n: "Blocks"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The maximum number of blocks a transaction should have to wait before it is predicted to be included in a block based purely on its priority"
{% enditemplate %}
*Result---the priority a transaction needs*
{% itemplate ntpd1 %}
- n: "`result`"
t: "number (real)"
p: "Required<br>(exactly 1)"
d: "The estimated priority the transaction should have in order to be included within the specified number of blocks. If the node doesn't have enough information to make an estimate, the value `-1` will be returned"
{% enditemplate %}
*Examples from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli estimatepriority 6
{% endhighlight %}
Result:
{% highlight json %}
718158904.10958910
{% endhighlight %}
Requesting data the node can't calculate yet:
{% highlight bash %}
bitcoin-cli estimatepriority 100
{% endhighlight %}
Result:
{% highlight json %}
-1.00000000
{% endhighlight %}
*See also*
* [EstimateFee][rpc estimatefee]: {{summary_estimateFee}}
{% endautocrossref %}

64
_includes/devdoc/bitcoin-core/rpcs/rpcs/generate.md Normal file
View file

@ -0,0 +1,64 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/generate.md" %}
##### Generate
{% include helpers/subhead-links.md %}
{% assign summary_generate="nearly instantly generates blocks (in regtest mode only)" %}
{% autocrossref %}
*Requires wallet support.*
The `generate` RPC {{summary_generate}}
*Parameter #1---the number of blocks to generate*
{% itemplate ntpd1 %}
- n: "Blocks"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The number of blocks to generate. The RPC call will not return until all blocks have been generated"
{% enditemplate %}
*Result---the generated block header hashes*
{% itemplate ntpd1 %}
- n: "`result`"
t: "array"
p: "Required<br>(exactly 1)"
d: "An array containing the block header hashes of the generated blocks (may be empty if used with `generate 0`)"
- n: "→<br>Header Hashes"
t: "string (hex)"
p: "Required<br>(1 or more)"
d: "The hashes of the headers of the blocks generated in regtest mode, as hex in RPC byte order"
{% enditemplate %}
*Examples from Bitcoin Core master (commit c2fa0846)*
Using regtest mode, generate 2 blocks:
{% highlight bash %}
bitcoin-cli -regtest generate 2
{% endhighlight %}
Result:
{% highlight json %}
[
"36252b5852a5921bdfca8701f936b39edeb1f8c39fffe73b0d8437921401f9af",
"5f2956817db1e386759aa5794285977c70596b39ea093b9eab0aa4ba8cd50c06"
]
{% endhighlight %}
*See also*
* [SetGenerate][rpc getgenerate]: {{summary_getGenerate}}
* [GetMiningInfo][rpc getmininginfo]: {{summary_getMiningInfo}}
* [GetBlockTemplate][rpc getblocktemplate]: {{summary_getBlockTemplate}}
{% endautocrossref %}

54
_includes/devdoc/bitcoin-core/rpcs/rpcs/getaccount.md Normal file
View file

@ -0,0 +1,54 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getaccount.md" %}
##### GetAccount
{% include helpers/subhead-links.md %}
{% assign summary_getAccount="returns the name of the account associated with the given address." %}
{% autocrossref %}
*Requires wallet support.*
The `getaccount` RPC {{summary_getAccount}}
*Parameter #1---a Bitcoin address*
{% itemplate ntpd1 %}
- n: "Address"
t: "string (base58)"
p: "Required<br>(exactly 1)"
d: "A P2PKH or P2SH Bitcoin address belonging either to a specific account or the default account (\"\")"
{% enditemplate %}
*Result---an account name*
{% itemplate ntpd1 %}
- n: "`result`"
t: "string"
p: "Required<br>(exactly 1)"
d: "The name of an account, or an empty string (\"\", the default account)"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet getaccount mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN
{% endhighlight %}
Result:
{% highlight text %}
doc test
{% endhighlight %}
*See also*
* [GetAddressesByAccount][rpc getaddressesbyaccount]: {{summary_getAddressesByAccount}}
{% endautocrossref %}

58
_includes/devdoc/bitcoin-core/rpcs/rpcs/getaccountaddress.md Normal file
View file

@ -0,0 +1,58 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getaccountaddress.md" %}
##### GetAccountAddress
{% include helpers/subhead-links.md %}
{% autocrossref %}
{% 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." %}
*Requires wallet support.*
The `getaccountaddress` RPC {{summary_getAccountAddress}}
*Parameter #1---an account name*
{% itemplate ntpd1 %}
- n: "Account"
t: "string"
p: "Required<br>(exactly 1)"
d: "The name of an account. Use an empty string (\"\") for the default account. If the account doesn't exist, it will be created"
{% enditemplate %}
*Result---a bitcoin address*
{% itemplate ntpd1 %}
- n: "`result`"
t: "string (base58)"
p: "Required<br>(exactly 1)"
d: "An address, belonging to the account specified, which has not yet received any payments"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Get an address for the default account:
{% highlight bash %}
bitcoin-cli -testnet getaccountaddress ""
{% endhighlight %}
Result:
{% highlight text %}
msQyFNYHkFUo4PG3puJBbpesvRCyRQax7r
{% endhighlight %}
*See also*
* [GetNewAddress][rpc getnewaddress]: {{summary_getNewAddress}}
* [GetRawChangeAddress][rpc getrawchangeaddress]: {{summary_getRawChangeAddress}}
* [GetAddressesByAccount][rpc getaddressesbyaccount]: {{summary_getAddressesByAccount}}
{% endautocrossref %}

109
_includes/devdoc/bitcoin-core/rpcs/rpcs/getaddednodeinfo.md Normal file
View file

@ -0,0 +1,109 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getaddednodeinfo.md" %}
##### GetAddedNodeInfo
{% include helpers/subhead-links.md %}
{% 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." %}
{% autocrossref %}
The `getaddednodeinfo` RPC {{summary_getAddedNodeInfo}}
*Parameter #1---whether to display connection information*
{% itemplate ntpd1 %}
- n: "Details"
t: "bool"
p: "Required<br>(exactly 1)"
d: "Set to `true` to display detailed information about each added node; set to `false` to only display the IP address or hostname and port added"
{% enditemplate %}
*Parameter #2---what node to display information about*
{% itemplate ntpd1 %}
- n: "Node"
t: "string"
p: "Optional<br>(0 or 1)"
d: "The node to get information about in the same `<IP address>:<port>` format as the `addnode` RPC. If this parameter is not provided, information about all added nodes will be returned"
{% enditemplate %}
*Result---a list of added nodes*
{% itemplate ntpd1 %}
- n: "`result`"
t: "array"
p: "Required<br>(exactly 1)"
d: "An array containing objects describing each added node. If no added nodes are present, the array will be empty. Nodes added with `onetry` will not be returned"
- n: "→<br>Added Node"
t: "object"
p: "Optional<br>(0 or more)"
d: "An object containing details about a single added node"
- n: "→ →<br>`addednode`"
t: "string"
p: "Required<br>(exactly 1)"
d: "An added node in the same `<IP address>:<port>` format as used in the `addnode` RPC. This element is present for any added node whether or not the Details parameter was set to `true`"
- n: "→ →<br>`connected`"
t: "bool"
p: "Optional<br>(0 or 1)"
d: "If the Details parameter was set to `true`, this will be set to `true` if the node is currently connected and `false` if it is not"
- n: "→ →<br>`addresses`"
t: "array"
p: "Optional<br>(0 or 1)"
d: "If the Details parameter was set to `true`, this will be an array of addresses belonging to the added node"
- n: "→ → →<br>Address"
t: "object"
p: "Optional<br>(0 or more)"
d: "An object describing one of this node's addresses"
- n: "→ → → →<br>`address`"
t: "string"
p: "Required<br>(exactly 1)"
d: "An IP address and port number of the node. If the node was added using a DNS address, this will be the resolved IP address"
- n: "→ → → →<br>`connected`"
t: "string"
p: "Required<br>(exactly 1)"
d: "Whether or not the local node is connected to this addnode using this IP address. Valid values are:<br>• `false` for not connected<br>• `inbound` if the addnode connected to us<br>• `outbound` if we connected to the addnode"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet getaddednodeinfo true
{% endhighlight %}
Result (real hostname and IP address replaced):
{% highlight json %}
[
{
"addednode" : "bitcoind.example.com:18333",
"connected" : true,
"addresses" : [
{
"address" : "192.0.2.113:18333",
"connected" : "outbound"
}
]
}
]
{% endhighlight %}
*See also*
* [AddNode][rpc addnode]: {{summary_addNode}}
* [GetPeerInfo][rpc getpeerinfo]: {{summary_getPeerInfo}}
{% endautocrossref %}

66
_includes/devdoc/bitcoin-core/rpcs/rpcs/getaddressesbyaccount.md Normal file
View file

@ -0,0 +1,66 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getaddressesbyaccount.md" %}
##### GetAddressesByAccount
{% include helpers/subhead-links.md %}
{% assign summary_getAddressesByAccount="returns a list of every address assigned to a particular account." %}
{% autocrossref %}
*Requires wallet support.*
The `getaddressesbyaccount` RPC {{summary_getAddressesByAccount}}
*Parameter #1---the account name*
{% itemplate ntpd1 %}
- n: "Account"
t: "string"
p: "Required<br>(exactly 1)"
d: "The name of the account containing the addresses to get. To get addresses from the default account, pass an empty string (\"\")"
{% enditemplate %}
*Result---a list of addresses*
{% itemplate ntpd1 %}
- n: "`result`"
t: "array"
p: "Required<br>(exactly 1)"
d: "An array containing all addresses belonging to the specified account. If the account has no addresses, the array will be empty"
- n: "Address"
t: "string (base58)"
p: "Optional<br>(1 or more)"
d: "A P2PKH or P2SH address belonging to the account"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Get the addresses assigned to the account "doc test":
{% highlight bash %}
bitcoin-cli -testnet getaddressesbyaccount "doc test"
{% endhighlight %}
Result:
{% highlight json %}
[
"mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN",
"mft61jjkmiEJwJ7Zw3r1h344D6aL1xwhma",
"mmXgiR6KAhZCyQ8ndr2BCfEq1wNG2UnyG6"
]
{% endhighlight %}
*See also*
* [GetAccount][rpc getaccount]: {{summary_getAccount}}
* [GetBalance][rpc getbalance]: {{summary_getBalance}}
{% endautocrossref %}

68
_includes/devdoc/bitcoin-core/rpcs/rpcs/getbalance.md Normal file
View file

@ -0,0 +1,68 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getbalance.md" %}
##### GetBalance
{% include helpers/subhead-links.md %}
{% assign summary_getBalance="gets the balance in decimal bitcoins across all accounts or for a particular account." %}
{% autocrossref %}
*Requires wallet support.*
The `getbalance` RPC {{summary_getBalance}}
*Parameter #1---an account name*
{% itemplate ntpd1 %}
- n: "Account"
t: "string"
p: "Optional<br>(0 or 1)"
d: "The name of an account to get the balance for. An empty string (\"\") is the default account. The string `*` will get the balance for all accounts (this is the default behavior)"
{% enditemplate %}
*Parameter #2---the minimum number of confirmations*
{{INCLUDE_CONFIRMATIONS_PARAMETER}}
*Parameter #3---whether to include watch-only addresses*
{{INCLUDE_INCLUDE_WATCH_ONLY_PARAMETER}}
*Result---the balance in bitcoins*
{% itemplate ntpd1 %}
- n: "`result`"
t: "number (bitcoins)"
p: "Required<br>(exactly 1)"
d: "The balance of the account (or all accounts) in bitcoins"
{% enditemplate %}
*Examples from Bitcoin Core 0.10.0*
Get the balance for the "test1" account, including transactions with
at least one confirmation and those spent to watch-only addresses in
that account.
{% highlight bash %}
bitcoin-cli -testnet getbalance "test1" 1 true
{% endhighlight %}
Result:
{% highlight json %}
1.99900000
{% endhighlight %}
*See also*
* [ListAccounts][rpc listaccounts]: {{summary_listAccounts}}
* [GetReceivedByAccount][rpc getreceivedbyaccount]: {{summary_getReceivedByAccount}}
* [GetReceivedByAddress][rpc getreceivedbyaddress]: {{summary_getReceivedByAddress}}
{% endautocrossref %}

47
_includes/devdoc/bitcoin-core/rpcs/rpcs/getbestblockhash.md Normal file
View file

@ -0,0 +1,47 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getbestblockhash.md" %}
##### GetBestBlockHash
{% include helpers/subhead-links.md %}
{% assign summary_getBestBlockHash="returns the header hash of the most recent block on the best block chain." %}
{% autocrossref %}
*Added in Bitcoin Core 0.9.0*
The `getbestblockhash` RPC {{summary_getBestBlockHash}}
*Parameters: none*
*Result---hash of the tip from the best block chain*
{% itemplate ntpd1 %}
- n: "`result`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The hash of the block header from the most recent block on the best block chain, encoded as hex in RPC byte order"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet getbestblockhash
{% endhighlight %}
Result:
{% highlight text %}
0000000000075c58ed39c3e50f99b32183d090aefa0cf8c324a82eea9b01a887
{% endhighlight %}
*See also*
* [GetBlock][rpc getblock]: {{summary_getBlock}}
* [GetBlockHash][rpc getblockhash]: {{summary_getBlockHash}}
{% endautocrossref %}

188
_includes/devdoc/bitcoin-core/rpcs/rpcs/getblock.md Normal file
View file

@ -0,0 +1,188 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getblock.md" %}
##### GetBlock
{% include helpers/subhead-links.md %}
{% 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." %}
{% autocrossref %}
The `getblock` RPC {{summary_getBlock}}
*Parameter #1---header hash*
{% itemplate ntpd1 %}
- n: "Header Hash"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The hash of the header of the block to get, encoded as hex in RPC byte order"
{% enditemplate %}
*Parameter #2---JSON or hex output*
{% itemplate ntpd1 %}
- n: "Format"
t: "bool"
p: "Optional<br>(0 or 1)"
d: "Set to `false` to get the block in serialized block format; set to `true` (the default) to get the decoded block as a JSON object"
{% enditemplate %}
*Result (if format was `false`)---a serialized block*
{% itemplate ntpd1 %}
- n: "`result`"
t: "string (hex)/null"
p: "Required<br>(exactly 1)"
d: "The requested block as a serialized block, encoded as hex, or JSON `null` if an error occurred"
{% enditemplate %}
*Result (if format was `true` or omitted)---a JSON block*
{% itemplate ntpd1 %}
- n: "`result`"
t: "object/null"
p: "Required<br>(exactly 1)"
d: "An object containing the requested block, or JSON `null` if an error occurred"
- n: "→<br>`hash`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The hash of this block's block header encoded as hex in RPC byte order. This is the same as the hash provided in parameter #1"
- n: "→<br>`confirmations`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The number of confirmations the transactions in this block have, starting at 1 when this block is at the tip of the best block chain. This score will be -1 if the the block is not part of the best block chain"
- n: "→<br>`size`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The size of this block in serialized block format, counted in bytes"
- n: "→<br>`height`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The height of this block on its block chain"
- n: "→<br>`version`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "This block's version number. See [block version numbers][section block versions]"
- n: "→<br>`merkleroot`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The merkle root for this block, encoded as hex in RPC byte order"
- n: "→<br>`tx`"
t: "array"
p: "Required<br>(exactly 1)"
d: "An array containing the TXIDs of all transactions in this block. The transactions appear in the array in the same order they appear in the serialized block"
- n: "→ →<br>TXID"
t: "string (hex)"
p: "Required<br>(1 or more)"
d: "The TXID of a transaction in this block, encoded as hex in RPC byte order"
- n: "→<br>`time`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The value of the *time* field in the block header, indicating approximately when the block was created"
- n: "→<br>`nonce`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The nonce which was successful at turning this particular block into one that could be added to the best block chain"
- n: "→<br>`bits`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The value of the *nBits* field in the block header, indicating the target threshold this block's header had to pass"
- n: "→<br>`difficulty`"
t: "number (real)"
p: "Required<br>(exactly 1)"
d: "The estimated amount of work done to find this block relative to the estimated amount of work done to find block 0"
- n: "→<br>`chainwork`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The estimated number of block header hashes miners had to check from the genesis block to this block, encoded as big-endian hex"
- n: "→<br>`previousblockhash`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The hash of the header of the previous block, encoded as hex in RPC byte order"
- n: "→<br>`nextblockhash`"
t: "string (hex)"
p: "Optional<br>(0 or 1)"
d: "The hash of the next block on the best block chain, if known, encoded as hex in RPC byte order"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Get a block in raw hex:
{% highlight bash %}
bitcoin-cli -testnet getblock \
000000000fe549a89848c76070d4132872cfb6efe5315d01d7ef77e4900f2d39 \
false
{% endhighlight %}
Result (wrapped):
{% highlight text %}
02000000df11c014a8d798395b5059c722ebdf3171a4217ead71bf6e0e99f4c7\
000000004a6f6a2db225c81e77773f6f0457bcb05865a94900ed11356d0b7522\
8efb38c7785d6053ffff001d005d437001010000000100000000000000000000\
00000000000000000000000000000000000000000000ffffffff0d03b4770301\
64062f503253482fffffffff0100f9029500000000232103adb7d8ef6b63de74\
313e0cd4e07670d09a169b13e4eda2d650f529332c47646dac00000000
{% endhighlight %}
Get the same block in JSON:
{% highlight bash %}
bitcoin-cli -testnet getblock \
000000000fe549a89848c76070d4132872cfb6efe5315d01d7ef77e4900f2d39 \
true
{% endhighlight %}
Result:
{% highlight json %}
{
"hash" : "000000000fe549a89848c76070d4132872cfb6efe5315d01d7ef77e4900f2d39",
"confirmations" : 88029,
"size" : 189,
"height" : 227252,
"version" : 2,
"merkleroot" : "c738fb8e22750b6d3511ed0049a96558b0bc57046f3f77771ec825b22d6a6f4a",
"tx" : [
"c738fb8e22750b6d3511ed0049a96558b0bc57046f3f77771ec825b22d6a6f4a"
],
"time" : 1398824312,
"nonce" : 1883462912,
"bits" : "1d00ffff",
"difficulty" : 1.00000000,
"chainwork" : "000000000000000000000000000000000000000000000000083ada4a4009841a",
"previousblockhash" : "00000000c7f4990e6ebf71ad7e21a47131dfeb22c759505b3998d7a814c011df",
"nextblockhash" : "00000000afe1928529ac766f1237657819a11cfcc8ca6d67f119e868ed5b6188"
}
{% endhighlight %}
*See also*
* [GetBlockHash][rpc getblockhash]: {{summary_getBlockHash}}
* [GetBestBlockHash][rpc getbestblockhash]: {{summary_getBestBlockHash}}
{% endautocrossref %}

91
_includes/devdoc/bitcoin-core/rpcs/rpcs/getblockchaininfo.md Normal file
View file

@ -0,0 +1,91 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getblockchaininfo.md" %}
##### GetBlockChainInfo
{% include helpers/subhead-links.md %}
{% assign summary_getBlockChainInfo="provides information about the current state of the block chain." %}
{% autocrossref %}
*Added in Bitcoin Core 0.9.2*
The `getblockchaininfo` RPC {{summary_getBlockChainInfo}}
*Parameters: none*
*Result---A JSON object providing information about the block chain*
{% itemplate ntpd1 %}
- n: "`result`"
t: "object"
p: "Required<br>(exactly 1)"
d: "Information about the current state of the local block chain"
- n: "→<br>`chain`"
t: "string"
p: "Required<br>(exactly 1)"
d: "The name of the block chain. One of `main` for mainnet, `test` for testnet, or `regtest`<!--noref--> for regtest"
- n: "→<br>`blocks`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The number of validated blocks in the local best block chain. For a new node with just the hardcoded genesis block, this will be 0"
- n: "→<br>`headers`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "*Added in Bitcoin Core 0.10.0*<br><br>The number of validated headers in the local best headers chain. For a new node with just the hardcoded genesis block, this will be zero. This number may be higher than the number of *blocks*"
- n: "→<br>`bestblockhash`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The hash of the header of the highest validated block in the best block chain, encoded as hex in RPC byte order. This is identical to the string returned by the `getbestblockhash` RPC"
- n: "→<br>`difficulty`"
t: "number (real)"
p: "Required<br>(exactly 1)"
d: "The difficulty of the highest-height block in the best block chain"
- n: "→<br>`verificationprogress`"
t: "number (real)"
p: "Required (exactly 1)"
d: "Estimate of what percentage of the block chain transactions have been verified so far, starting at 0.0 and increasing to 1.0 for fully verified. May slightly exceed 1.0 when fully synced to account for transactions in the memory pool which have been verified before being included in a block"
- n: "→<br>`chainwork`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The estimated number of block header hashes checked from the genesis block to this block, encoded as big-endian hex"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet getblockchaininfo
{% endhighlight %}
Result:
{% highlight json %}
{
"chain" : "test",
"blocks" : 315280,
"headers" : 315280,
"bestblockhash" : "000000000ebb17fb455e897b8f3e343eea1b07d926476d00bc66e2c0342ed50f",
"difficulty" : 1.00000000,
"verificationprogress" : 1.00000778,
"chainwork" : "0000000000000000000000000000000000000000000000015e984b4fb9f9b350"
}
{% endhighlight %}
*See also*
* [GetMiningInfo][rpc getmininginfo]: {{summary_getMiningInfo}}
* [GetNetworkInfo][rpc getnetworkinfo]: {{summary_getNetworkInfo}}
* [GetWalletInfo][rpc getwalletinfo]: {{summary_getWalletInfo}}
{% endautocrossref %}

45
_includes/devdoc/bitcoin-core/rpcs/rpcs/getblockcount.md Normal file
View file

@ -0,0 +1,45 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getblockcount.md" %}
##### GetBlockCount
{% include helpers/subhead-links.md %}
{% assign summary_getBlockCount="returns the number of blocks in the local best block chain." %}
{% autocrossref %}
The `getblockcount` RPC {{summary_getBlockCount}}
*Parameters: none*
*Result---the number of blocks in the local best block chain*
{% itemplate ntpd1 %}
- n: "`result`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The number of blocks in the local best block chain. For a new node with only the hardcoded genesis block, this number will be 0"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet getblockcount
{% endhighlight %}
Result:
{% highlight text %}
315280
{% endhighlight %}
*See also*
* [GetBlockHash][rpc getblockhash]: {{summary_getBlockHash}}
* [GetBlock][rpc getblock]: {{summary_getBlock}}
{% endautocrossref %}

53
_includes/devdoc/bitcoin-core/rpcs/rpcs/getblockhash.md Normal file
View file

@ -0,0 +1,53 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getblockhash.md" %}
##### GetBlockHash
{% include helpers/subhead-links.md %}
{% assign summary_getBlockHash="returns the header hash of a block at the given height in the local best block chain." %}
{% autocrossref %}
The `getblockhash` RPC {{summary_getBlockHash}}
*Parameter---a block height*
{% itemplate ntpd1 %}
- n: "Block Height"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The height of the block whose header hash should be returned. The height of the hardcoded genesis block is 0"
{% enditemplate %}
*Result---the block header hash*
{% itemplate ntpd1 %}
- n: "`result`"
t: "string (hex)/null"
p: "Required<br>(exactly 1)"
d: "The hash of the block at the requested height, encoded as hex in RPC byte order, or JSON `null` if an error occurred"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet getblockhash 240886
{% endhighlight %}
Result:
{% highlight text %}
00000000a0faf83ab5799354ae9c11da2a2bd6db44058e03c528851dee0a3fff
{% endhighlight %}
*See also*
* [GetBlock][rpc getblock]: {{summary_getBlock}}
* [GetBestBlockHash][rpc getbestblockhash]: {{summary_getBestBlockHash}}
{% endautocrossref %}

28
_includes/devdoc/bitcoin-core/rpcs/rpcs/getblocktemplate.md Normal file
View file

@ -0,0 +1,28 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getblocktemplate.md" %}
##### GetBlockTemplate
{% include helpers/subhead-links.md %}
{% assign summary_getBlockTemplate="gets a block template or proposal for use with mining software." %}
{% autocrossref %}
The `getblocktemplate` RPC {{summary_getBlockTemplate}} For more
information, please see the following resources:
* [Bitcoin Wiki GetBlockTemplate][wiki getblocktemplate]
* [BIP22][]
* [BIP23][]
*See also*
* [SetGenerate][rpc setgenerate]: {{summary_setGenerate}}
* [GetMiningInfo][rpc getmininginfo]: {{summary_getMiningInfo}}
* [SubmitBlock][rpc submitblock]: {{summary_submitBlock}}
* [PrioritiseTransaction][rpc prioritisetransaction]: {{summary_prioritiseTransaction}}
{% endautocrossref %}

90
_includes/devdoc/bitcoin-core/rpcs/rpcs/getchaintips.md Normal file
View file

@ -0,0 +1,90 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getchaintips.md" %}
##### GetChainTips
{% include helpers/subhead-links.md %}
{% assign summary_getChainTips="returns information about the highest-height block (tip) of each local block chain." %}
{% autocrossref %}
*Added in Bitcoin Core 0.10.0.*
The `getchaintips` RPC {{summary_getChainTips}}
*Parameters: none*
*Result---an array of block chain tips*
{% itemplate ntpd1 %}
- n: "`result`"
t: "array"
p: "Required<br>(exactly 1)"
d: "An array of JSON objects, with each object describing a chain tip. At least one tip---the local best block chain---will always be present"
- n: "→<br>Tip"
t: "object"
p: "Required<br>(1 or more)"
d: "An object describing a particular chain tip. The first object will always describe the active chain (the local best block chain)"
- n: "→ →<br>`height`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The height of the highest block in the chain. A new node with only the genesis block will have a single tip with height of 0"
- n: "→ →<br>`hash`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The hash of the highest block in the chain, encoded as hex in RPC byte order"
- n: "→ →<br>`branchlen`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The number of blocks that are on this chain but not on the main chain. For the local best block chain, this will be `0`; for all other chains, it will be at least `1`"
- n: "→ →<br>`status`"
t: "string"
p: "Required<br>(exactly 1)"
d: "The status of this chain. Valid values are:<br>• `active` for the local best block chain<br>• `invalid` for a chain that contains one or more invalid blocks<br>• `headers-only`<!--noref--> for a chain with valid headers whose corresponding blocks both haven't been validated and aren't stored locally<br>• `valid-headers` for a chain with valid headers whose corresponding blocks are stored locally, but which haven't been fully validated<br>• `valid-fork` for a chain which is fully validated but which isn't part of the local best block chain (it was probably the local best block chain at some point)<br>• `unknown` for a chain whose reason for not being the active chain is unknown"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet getchaintips
{% endhighlight %}
{% highlight json %}
[
{
"height" : 312647,
"hash" : "000000000b1be96f87b31485f62c1361193304a5ad78acf47f9164ea4773a843",
"branchlen" : 0,
"status" : "active"
},
{
"height" : 282072,
"hash" : "00000000712340a499b185080f94b28c365d8adb9fc95bca541ea5e708f31028",
"branchlen" : 5,
"status" : "valid-fork"
},
{
"height" : 281721,
"hash" : "000000006e1f2a32199629c6c1fbd37766f5ce7e8c42bab0c6e1ae42b88ffe12",
"branchlen" : 1,
"status" : "valid-headers"
},
]
{% endhighlight %}
*See also*
* [GetBestBlockHash][rpc getbestblockhash]: {{summary_getBestBlockHash}}
* [GetBlock][rpc getblock]: {{summary_getBlock}}
* [GetBlockChainInfo][rpc getblockchaininfo]: {{summary_getBlockChainInfo}}
{% endautocrossref %}

46
_includes/devdoc/bitcoin-core/rpcs/rpcs/getconnectioncount.md Normal file
View file

@ -0,0 +1,46 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getconnectioncount.md" %}
##### GetConnectionCount
{% include helpers/subhead-links.md %}
{% assign summary_getConnectionCount="returns the number of connections to other nodes." %}
{% autocrossref %}
The `getconnectioncount` RPC {{summary_getConnectionCount}}
*Parameters: none*
*Result---the number of connections to other nodes*
{% itemplate ntpd1 %}
- n: "`result`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The total number of connections to other nodes (both inbound and outbound)"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet getconnectioncount
{% endhighlight bash %}
Result:
{% highlight json %}
14
{% endhighlight %}
*See also*
* [GetNetTotals][rpc getnettotals]: {{summary_getNetTotals}}
* [GetPeerInfo][rpc getpeerinfo]: {{summary_getPeerInfo}}
* [GetNetworkInfo][rpc getnetworkinfo]: {{summary_getNetworkInfo}}
{% endautocrossref %}

45
_includes/devdoc/bitcoin-core/rpcs/rpcs/getdifficulty.md Normal file
View file

@ -0,0 +1,45 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getdifficulty.md" %}
##### GetDifficulty
{% include helpers/subhead-links.md %}
{% assign summary_getDifficultly="returns the proof-of-work difficulty as a multiple of the minimum difficulty." %}
{% autocrossref %}
The `getdifficulty` RPC {{summary_getDifficulty}}
*Parameters: none*
*Result---the current difficulty*
{% itemplate ntpd1 %}
- n: "`result`"
t: "number (real)"
p: "Required<br>(exactly 1)"
d: "The difficulty of creating a block with the same target threshold (nBits) as the highest-height block in the local best block chain. The number is a a multiple of the minimum difficulty"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet getdifficulty
{% endhighlight %}
Result:
{% highlight text %}
1.00000000
{% endhighlight %}
*See also*
* [GetNetworkHashPS][rpc getnetworkhashps]: {{summary_getNetworkHashPS}}
* [GetMiningInfo][rpc getmininginfo]: {{summary_getMiningInfo}}
{% endautocrossref %}

48
_includes/devdoc/bitcoin-core/rpcs/rpcs/getgenerate.md Normal file
View file

@ -0,0 +1,48 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getgenerate.md" %}
##### GetGenerate
{% include helpers/subhead-links.md %}
{% assign summary_getGenerate="returns true if the node is set to generate blocks using its CPU." %}
{% autocrossref %}
*Requires wallet support.*
The `getgenerate` RPC {{summary_getGenerate}}
*Parameters: none*
*Result---whether the server is set to generate blocks*
{% itemplate ntpd1 %}
- n: "`result`"
t: "bool"
p: "Required<br>(exactly 1)"
d: "Set to `true` if the server is set to generate blocks; set to `false` if it is not"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet getgenerate
{% endhighlight %}
Result:
{% highlight json %}
false
{% endhighlight %}
*See also*
* [SetGenerate][rpc setgenerate]: {{summary_setGenerate}}
* [GetMiningInfo][rpc getmininginfo]: {{summary_getMiningInfo}}
* [GetHashesPerSec][rpc gethashespersec]: {{summary_getHashesPerSec}}
{% endautocrossref %}

47
_includes/devdoc/bitcoin-core/rpcs/rpcs/gethashespersec.md Normal file
View file

@ -0,0 +1,47 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/gethashespersec.md" %}
##### GetHashesPerSec
{% include helpers/subhead-links.md %}
{% assign summary_getHashesPerSec="was removed in Bitcoin Core master (unreleased). It returned a recent hashes per second performance measurement when the node was generating blocks." %}
{% autocrossref %}
*Requires wallet support.*
The `gethashespersec` RPC {{summary_getHashesPerSec}}
*Parameters: none*
*Result---the number of hashes your computer generated per second*
{% itemplate ntpd1 %}
- n: "`result`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "If generation is enabled, the number of hashes per second your computer most recently generated. If generation is disabled, the value `0`"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet gethashespersec
{% endhighlight %}
Result:
{% highlight json %}
1995356
{% endhighlight %}
*See also*
* [SetGenerate][rpc setgenerate]: {{summary_setGenerate}}
* [GetMiningInfo][rpc getmininginfo]: {{summary_getMiningInfo}}
{% endautocrossref %}

147
_includes/devdoc/bitcoin-core/rpcs/rpcs/getinfo.md Normal file
View file

@ -0,0 +1,147 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getinfo.md" %}
##### GetInfo
{% include helpers/subhead-links.md %}
{% assign summary_getInfo="prints various information about the node and the network." %}
{% autocrossref %}
The `getinfo` RPC {{summary_getInfo}}
{{WARNING}} `getinfo` will be removed in a later version of Bitcoin
Core. Use the RPCs listed in the See Also subsection below instead.
*Parameters: none*
*Result---information about the node and network*
{% itemplate ntpd1 %}
- n: "`result`"
t: "object"
p: "Required<br>(exactly 1)"
d: "Information about this node and the network"
- n: "→<br>`version`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "This node's version of Bitcoin Core in its internal integer format. For example, Bitcoin Core 0.9.2 has the integer version number 90200"
- n: "→<br>`protocolversion`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The protocol version number used by this node. See the [protocol versions section][section protocol versions] for more information"
- n: "→<br>`walletversion`"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "The version number of the wallet. Only returned if wallet support is enabled"
- n: "→<br>`balance`"
t: "number (bitcoins)"
p: "Optional<br>(0 or 1)"
d: "The balance of the wallet in bitcoins. Only returned if wallet support is enabled"
- n: "→<br>`blocks`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The number of blocks in the local best block chain. A new node with only the hardcoded genesis block will return `0`"
- n: "→<br>`timeoffset`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The offset of the node's clock from the computer's clock (both in UTC) in seconds. The offset may be up to 4200 seconds (70 minutes)"
- n: "→<br>`connections`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The total number of open connections (both outgoing and incoming) between this node and other nodes"
- n: "→<br>`proxy`"
t: "string"
p: "Required<br>(exactly 1)"
d: "The hostname/IP address and port number of the proxy, if set, or an empty string if unset"
- n: "→<br>`difficulty`"
t: "number (real)"
p: "Required<br>(exactly 1)"
d: "The difficulty of the highest-height block in the local best block chain"
- n: "→<br>`testnet`"
t: "bool"
p: "Required<br>(exactly 1)"
d: "*Added in Bitcoin Core 0.10.0*<br><br>Set to `true` if this node is on testnet; set to `false` if this node is on mainnet or a regtest"
- n: "→<br>`keypoololdest`"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "The date as Unix epoch time when the oldest key in the wallet key pool was created; useful for only scanning blocks created since this date for transactions. Only returned if wallet support is enabled"
- n: "→<br>`keypoolsize`"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "The number of keys in the wallet keypool. Only returned if wallet support is enabled"
- n: "→<br>`paytxfee`"
t: "number (bitcoins)"
p: "Optional<br>(0 or 1)"
d: "The minimum fee to pay per kilobyte of transaction; may be `0`. Only returned if wallet suuport is enabled"
- n: "→<br>`relayfee`"
t: "number (bitcoins)"
p: "Required<br>(exactly 1)"
d: "The minimum fee a low-priority transaction must pay in order for this node to accept it into its memory pool"
- n: "→<br>`unlocked_until`"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "The Unix epoch time when the wallet will automatically re-lock. Only displayed if wallet encryption is enabled. Set to `0` if wallet is currently locked"
- n: "→<br>`errors`"
t: "string"
p: "Required<br>(exactly 1)"
d: "A plain-text description of any errors this node has encountered or detected. If there are no errors, an empty string will be returned. This is not related to the JSON-RPC `error` field"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0 with wallet support enabled*
{% highlight bash %}
bitcoin-cli -testnet getinfo
{% endhighlight %}
Result:
{% highlight json %}
{
"version" : 100000,
"protocolversion" : 70002,
"walletversion" : 60000,
"balance" : 1.27007770,
"blocks" : 315281,
"timeoffset" : 0,
"connections" : 9,
"proxy" : "",
"difficulty" : 1.00000000,
"testnet" : true,
"keypoololdest" : 1418924649,
"keypoolsize" : 101,
"paytxfee" : 0.00000000,
"relayfee" : 0.00001000,
"errors" : ""
}
{% endhighlight %}
*See also*
* [GetBlockChainInfo][rpc getblockchaininfo]: {{summary_getBlockChainInfo}}
* [GetMemPoolInfo][rpc getmempoolinfo]: {{summary_getMemPoolInfo}}
* [GetMiningInfo][rpc getmininginfo]: {{summary_getMiningInfo}}
* [GetNetworkInfo][rpc getnetworkinfo]: {{summary_getNetworkInfo}}
* [GetWalletInfo][rpc getwalletinfo]: {{summary_getWalletInfo}}
{% endautocrossref %}

61
_includes/devdoc/bitcoin-core/rpcs/rpcs/getmempoolinfo.md Normal file
View file

@ -0,0 +1,61 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getmempoolinfo.md" %}
##### GetMemPoolInfo
{% include helpers/subhead-links.md %}
{% assign summary_getMemPoolInfo="returns information about the node's current transaction memory pool." %}
{% autocrossref %}
*Added in Bitcoin Core 0.10.0*
The `getmempoolinfo` RPC {{summary_getMemPoolInfo}}
*Parameters: none*
*Result---information about the transaction memory pool*
{% itemplate ntpd1 %}
- n: "`result`"
t: "object"
p: "Required<br>(exactly 1)"
d: "A object containing information about the memory pool"
- n: "→<br>`size`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The number of transactions currently in the memory pool"
- n: "→<br>`bytes`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The total number of bytes in the transactions in the memory pool"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet getmempoolinfo
{% endhighlight %}
Result:
{% highlight json %}
{
"size" : 37,
"bytes" : 9423
}
{% endhighlight %}
*See also*
* [GetBlockChainInfo][rpc getblockchaininfo]: {{summary_getBlockChainInfo}}
* [GetRawMemPool][rpc getrawmempool]: {{summary_getRawMemPool}}
* [GetTxOutSetInfo][rpc gettxoutsetinfo]: {{summary_getTxOutSetInfo}}
{% endautocrossref %}

120
_includes/devdoc/bitcoin-core/rpcs/rpcs/getmininginfo.md Normal file
View file

@ -0,0 +1,120 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getmininginfo.md" %}
##### GetMiningInfo
{% include helpers/subhead-links.md %}
{% assign summary_getMiningInfo="returns various mining-related information." %}
{% autocrossref %}
The `getmininginfo` RPC {{summary_getMiningInfo}}
*Parameters: none*
*Result---various mining-related information*
{% itemplate ntpd1 %}
- n: "`result`"
t: "object"
p: "Required<br>(exactly 1)"
d: "Various mining-related information"
- n: "→<br>`blocks`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The height of the highest block on the local best block chain"
- n: "→<br>`currentblocksize`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "If generation was enabled since the last time this node was restarted, this is the size in bytes of the last block built by this node for header hash checking. Otherwise, the value `0`"
- n: "→<br>`currentblocktx`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "If generation was enabled since the last time this node was restarted, this is the number of transactions in the last block built by this node for header hash checking. Otherwise, this is the value `0`"
- n: "→<br>`difficulty`"
t: "number (real)"
p: "Required<br>(exactly 1)"
d: "If generation was enabled since the last time this node was restarted, this is the difficulty of the highest-height block in the local best block chain. Otherwise, this is the value `0`"
- n: "→<br>`errors`"
t: "string"
p: "Required<br>(exactly 1)"
d: "A plain-text description of any errors this node has encountered or detected. If there are no errors, an empty string will be returned. This is not related to the JSON-RPC `error` field"
- n: "→<br>`genproclimit`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The limit on the number of processors to use for generation. If generation was enabled since the last time this node was restarted, this is the number used in the second parameter of the `setgenerate` RPC (or the default). Otherwise, it is `-1`"
- n: "→<br>`networkhashps`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "An estimate of the number of hashes per second the network is generating to maintain the current difficulty. See the `getnetworkhashps` RPC for configurable access to this data"
- n: "→<br>`pooledtx`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The number of transactions in the memory pool"
- n: "→<br>`testnet`"
t: "bool"
p: "Required<br>(exactly 1)"
d: "Set to `true` if this node is running on testnet. Set to `false` if this node is on mainnet or a regtest"
- n: "→<br>`chain`"
t: "string"
p: "Required<br>(exactly 1)"
d: "Set to `main` for mainnet, `test` for testnet, and `regtest` for regtest"
- n: "→<br>`generate`"
t: "bool"
p: "Optional<br>(0 or 1)"
d: "Set to `true` if generation is currently enabled; set to `false` if generation is currently disabled. Only returned if the node has wallet support enabled"
- n: "→<br>`hashespersec`"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "*Removed in Bitcoin Core master (unreleased)*<br><br>The approximate number of hashes per second this node is generating across all CPUs, if generation is enabled. Otherwise `0`. Only returned if the node has wallet support enabled"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet getmininginfo
{% endhighlight %}
Result:
{% highlight json %}
{
"blocks" : 313168,
"currentblocksize" : 1819,
"currentblocktx" : 3,
"difficulty" : 1.00000000,
"errors" : "",
"genproclimit" : 1,
"networkhashps" : 5699977416637,
"pooledtx" : 8,
"testnet" : true,
"chain" : "test",
"generate" : true,
"hashespersec" : 921200
}
{% endhighlight %}
*See also*
* [GetMemPoolInfo][rpc getmempoolinfo]: {{summary_getMemPoolInfo}}
* [GetRawMemPool][rpc getrawmempool]: {{summary_getRawMemPool}}
* [GetBlockTemplate][rpc getblocktemplate]: {{summary_getBlockTemplate}}
* [SetGenerate][rpc setgenerate]: {{summary_setGenerate}}
{% endautocrossref %}

64
_includes/devdoc/bitcoin-core/rpcs/rpcs/getnettotals.md Normal file
View file

@ -0,0 +1,64 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getnettotals.md" %}
##### GetNetTotals
{% include helpers/subhead-links.md %}
{% assign summary_getNetTotals="returns information about network traffic, including bytes in, bytes out, and the current time." %}
{% autocrossref %}
The `getnettotals` RPC {{summary_getNetTotals}}
*Parameters: none*
*Result---the current bytes in, bytes out, and current time*
{% itemplate ntpd1 %}
- n: "`result`"
t: "object"
p: "Required<br>(exactly 1)"
d: "An object containing information about the node's network totals"
- n: "→<br>`totalbytesrecv`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The total number of bytes received since the node was last restarted"
- n: "→<br>`totalbytessent`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The total number of bytes sent since the node was last restarted"
- n: "→<br>`timemillis`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "Unix epoch time in milliseconds according to the operating system's clock (not the node adjusted time)"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet getnettotals
{% endhighlight %}
Result:
{% highlight json %}
{
"totalbytesrecv" : 723992206,
"totalbytessent" : 16846662695,
"timemillis" : 1419268217354
}
{% endhighlight %}
*See also*
* [GetNetworkInfo][rpc getnetworkinfo]: {{summary_getNetworkInfo}}
* [GetPeerInfo][rpc getpeerinfo]: {{summary_getPeerInfo}}
{% endautocrossref %}

66
_includes/devdoc/bitcoin-core/rpcs/rpcs/getnetworkhashps.md Normal file
View file

@ -0,0 +1,66 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getnetworkhashps.md" %}
##### GetNetworkHashPS
{% include helpers/subhead-links.md %}
{% assign summary_getNetworkHashPS="returns the estimated current or historical network hashes per second based on the last *n* blocks." %}
{% autocrossref %}
The `getnetworkhashps` RPC {{summary_getNetworkHashPS}}
*Parameter #1---number of blocks to average*
{% itemplate ntpd1 %}
- n: "Blocks"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "The number of blocks to average together for calculating the estimated hashes per second. Default is `120`. Use `-1` to average all blocks produced since the last difficulty change"
{% enditemplate %}
*Parameter #2---block height*
{% itemplate ntpd1 %}
- n: "Height"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "The height of the last block to use for calculating the average. Defaults to `-1` for the highest-height block on the local best block chain. If the specified height is higher than the highest block on the local best block chain, it will be interpreted the same as `-1`"
{% enditemplate %}
*Result---estimated hashes per second*
{% itemplate ntpd1 %}
- n: "`result`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The estimated number of hashes per second based on the parameters provided. May be 0 (for Height=`0`, the genesis block) or a negative value if the highest-height block averaged has a block header time earlier than the lowest-height block averaged"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Get the average hashes per second for all the blocks since the last
difficulty change before block 227255.
{% highlight bash %}
bitcoin-cli -testnet getnetworkhashps -1 227255
{% endhighlight %}
Result:
{% highlight json %}
79510076167
{% endhighlight %}
*See also*
* [GetDifficulty][rpc getdifficulty]: {{summary_getDifficultly}}
* [GetBlock][rpc getblock]: {{summary_getBlock}}
{% endautocrossref %}

184
_includes/devdoc/bitcoin-core/rpcs/rpcs/getnetworkinfo.md Normal file
View file

@ -0,0 +1,184 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getnetworkinfo.md" %}
##### GetNetworkInfo
{% include helpers/subhead-links.md %}
{% assign summary_getNetworkInfo="returns information about the node's connection to the network." %}
{% autocrossref %}
*Added in Bitcoin Core 0.9.2.*
The `getnetworkinfo` RPC {{summary_getNetworkInfo}}
*Parameters: none*
*Result---information about the node's connection to the network*
{% itemplate ntpd1 %}
- n: "`result`"
t: "object"
p: "Required<br>(exactly 1)"
d: "Information about this node's connection to the network"
- n: "→<br>`version`"
t: "number"
p: "Required<br>(exactly 1)"
d: "This node's version of Bitcoin Core in its internal integer format. For example, Bitcoin Core 0.9.2 has the integer version number 90200"
- n: "→<br>`subversion`"
t: "string"
p: "Required<br>(exactly 1)"
d: "*Added in Bitcoin Core 0.10.0*<br><br>The user agent this node sends in its `version` message"
- n: "→<br>`protocolversion`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The protocol version number used by this node. See the [protocol versions section][section protocol versions] for more information"
- n: "→<br>`timeoffset`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The offset of the node's clock from the computer's clock (both in UTC) in seconds. The offset may be up to 4200 seconds (70 minutes)"
- n: "→<br>`connections`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The total number of open connections (both outgoing and incoming) between this node and other nodes"
- n: "→<br>`proxy`"
t: "string"
p: "Required<br>(exactly 1)"
d: "The hostname/IP address and port number of the proxy, if set, or an empty string if unset"
- n: "→<br>`relayfee`"
t: "number (bitcoins)"
p: "Required<br>(exactly 1)"
d: "The minimum fee a low-priority transaction must pay in order for this node to accept it into its memory pool"
- n: "→<br>`localservices`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "*Added in Bitcoin Core 0.10.0*<br><br>The services supported by this node as advertised in its `version` message"
- n: "→<br>`networks`"
t: "array"
p: "Required<br>(exactly 1)"
d: "*Added in Bitcoin Core 0.10.0*<br><br>An array with three objects: one describing the IPv4 connection, one describing the IPv6 connection, and one describing the Tor hidden service (onion) connection"
- n: "→ →<br>Network"
t: "object"
p: "Optional<br>(0 to 3)"
d: "An object describing a network. If the network is unroutable, it will not be returned"
- n: "→ → →<br>`name`"
t: "string"
p: "Required<br>(exactly 1)"
d: "The name of the network. Either `ipv4`, `ipv6`, or `onion`"
- n: "→ → →<br>`limited`"
t: "bool"
p: "Required<br>(exactly 1)"
d: "Set to `true` if only connections to this network are allowed according to the `-onlynet` Bitcoin Core command-line/configuration-file parameter. Otherwise set to `false`"
- n: "→ → →<br>`reachable`"
t: "bool"
p: "Required<br>(exactly 1)"
d: "Set to `true` if connections can be made to or from this network. Otherwise set to `false`"
- n: "→ → →<br>`proxy`"
t: "string"
p: "Required<br>(exactly 1)"
d: "The hostname and port of any proxy being used for this network. If a proxy is not in use, an empty string"
- n: "→ → →<br>`localaddresses`"
t: "array"
p: "Required<br>(exactly 1)"
d: "An array of objects each describing the local addresses this node believes it listens on"
- n: "→ → → →<br>Address"
t: "object"
p: "Optional<br>(0 or more)"
d: "An object describing a particular address this node believes it listens on"
- n: "→ → → → →<br>`address`"
t: "string"
p: "Required<br>(exactly 1)"
d: "An IP address or .onion address this node believes it listens on. This may be manually configured, auto detected, or based on `version` messages this node received from its peers"
- n: "→ → → → →<br>`port`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The port number this node believes it listens on for the associated `address`. This may be manually configured, auto detected, or based on `version` messages this node received from its peers"
- n: "→ → → → →<br>`score`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: >
The number of incoming connections during the uptime of this node
that have used this address in their `version` message
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet getnetworkinfo
{% endhighlight %}
Result (actual addresses have been replaced with reserved addresses):
{% highlight json %}
{
"version" : 100000,
"subversion" : "/Satoshi:0.10.0/",
"protocolversion" : 70002,
"localservices" : "0000000000000001",
"timeoffset" : 0,
"connections" : 51,
"networks" : [
{
"name" : "ipv4",
"limited" : false,
"reachable" : true,
"proxy" : ""
},
{
"name" : "ipv6",
"limited" : false,
"reachable" : true,
"proxy" : ""
},
{
"name" : "onion",
"limited" : false,
"reachable" : false,
"proxy" : ""
}
],
"relayfee" : 0.00001000,
"localaddresses" : [
{
"address" : "192.0.2.113",
"port" : 18333,
"score" : 6470
},
{
"address" : "0600:3c03::f03c:91ff:fe89:dfc4",
"port" : 18333,
"score" : 2029
}
]
}
{% endhighlight %}
*See also*
* [GetPeerInfo][rpc getpeerinfo]: {{summary_getPeerInfo}}
* [GetNetTotals][rpc getnettotals]: {{summary_getNetTotals}}
{% endautocrossref %}

58
_includes/devdoc/bitcoin-core/rpcs/rpcs/getnewaddress.md Normal file
View file

@ -0,0 +1,58 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getnewaddress.md" %}
##### GetNewAddress
{% include helpers/subhead-links.md %}
{% assign summary_getNewAddress="returns a new Bitcoin address for receiving payments. If an account is specified, payments received with the address will be credited to that account." %}
{% autocrossref %}
*Requires wallet support.*
The `getnewaddress` RPC {{summary_getNewAddress}}
*Parameter #1---an account name*
{% itemplate ntpd1 %}
- n: "Account"
t: "string"
p: "Optional<br>(0 or 1)"
d: "The name of the account to put the address in. The default is the default account, an empty string (\"\")"
{% enditemplate %}
*Result---a bitcoin address never previously returned*
{% itemplate ntpd1 %}
- n: "`result`"
t: "string (base58)"
p: "Required<br>(exactly 1)"
d: "A P2PKH address which has not previously been returned by this RPC. The address will be marked as a receiving address in the wallet. The address may already have been part of the keypool, so other RPCs such as the `dumpwallet` RPC may have disclosed it previously. If the wallet is unlocked, its keypool will also be filled to its max (by default, 100 unused keys). If the wallet is locked and its keypool is empty, this RPC will fail"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Create a new address in the "doc test" account:
{% highlight bash %}
bitcoin-cli -testnet getnewaddress "doc test"
{% endhighlight %}
Result:
{% highlight text %}
mft61jjkmiEJwJ7Zw3r1h344D6aL1xwhma
{% endhighlight %}
*See also*
* [GetAccountAddress][rpc getaccountaddress]: {{summary_getAccountAddress}}
* [GetRawChangeAddress][rpc getrawchangeaddress]: {{summary_getRawChangeAddress}}
* [GetBalance][rpc getbalance]: {{summary_getBalance}}
{% endautocrossref %}

185
_includes/devdoc/bitcoin-core/rpcs/rpcs/getpeerinfo.md Normal file
View file

@ -0,0 +1,185 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getpeerinfo.md" %}
##### GetPeerInfo
{% include helpers/subhead-links.md %}
{% assign summary_getPeerInfo="returns data about each connected network node." %}
{% autocrossref %}
The `getpeerinfo` RPC {{summary_getPeerInfo}}
*Parameters: none*
*Result---information about each currently-connected network node*
{% itemplate ntpd1 %}
- n: "`result`"
t: "array"
p: "Required<br>(exactly 1)"
d: "An array of objects each describing one connected node. If there are no connections, the array will be empty"
- n: "→<br>Node"
t: "object"
p: "Optional<br>(0 or more)"
d: "An object describing a particular connected node"
- n: "→ →<br>`id`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "*Added in Bitcoin Core 0.10.0*<br><br>The node's index number in the local node address database"
- n: "→ →<br>`addr`"
t: "string"
p: "Required<br>(exactly 1)"
d: "The IP address and port number used for the connection to the remote node"
- n: "→ →<br>`addrlocal`"
t: "string"
p: "Optional<br>(0 or 1)"
d: "Our IP address and port number according to the remote node. May be incorrect due to error or lying. Many SPV nodes set this to `127.0.0.1:8333`"
- n: "→ →<br>`services`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The services advertised by the remote node in its `version` message"
- n: "→ →<br>`lastsend`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The Unix epoch time when we last successfully sent data to the TCP socket for this node"
- n: "→ →<br>`lastrecv`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The Unix epoch time when we last received data from this node"
- n: "→ →<br>`bytessent`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The total number of bytes we've sent to this node"
- n: "→ →<br>`bytesrecv`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The total number of bytes we've received from this node"
- n: "→ →<br>`conntime`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The Unix epoch time when we connected to this node"
- n: "→ →<br>`pingtime`"
t: "number (real)"
p: "Required<br>(exactly 1)"
d: "The number of seconds this node took to respond to our last P2P `ping` message"
- n: "→ →<br>`pingwait`"
t: "number (real)"
p: "Optional<br>(0 or 1)"
d: "The number of seconds we've been waiting for this node to respond to a P2P `ping` message. Only shown if there's an outstanding `ping` message"
- n: "→ →<br>`version`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The protocol version number used by this node. See the [protocol versions section][section protocol versions] for more information"
- n: "→ →<br>`subver`"
t: "string"
p: "Required<br>(exactly 1)"
d: "The user agent this node sends in its `version` message. This string will have been sanitized to prevent corrupting the JSON results. May be an empty string"
- n: "→ →<br>`inbound`"
t: "bool"
p: "Required<br>(exactly 1)"
d: "Set to `true` if this node connected to us; set to `false` if we connected to this node"
- n: "→ →<br>`startingheight`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The height of the remote node's block chain when it connected to us as reported in its `version` message"
- n: "→ →<br>`banscore`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The ban score we've assigned the node based on any misbehavior it's made. By default, Bitcoin Core disconnects when the ban score reaches `100`"
- n: "→ →<br>`synced_headers`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "*Added in Bitcoin Core 0.10.0*<br><br>The highest-height header we have in common with this node based the last P2P `headers` message it sent us. If a `headers` message has not been received, this will be set to `-1`"
- n: "→ →<br>`synced_blocks`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "*Added in Bitcoin Core 0.10.0*<br><br>The highest-height block we have in common with this node based on P2P `inv` messages this node sent us. If no block `inv` messages have been received from this node, this will be set to `-1`"
- n: "→ →<br>`syncnode`"
t: "bool"
p: "Required<br>(exactly 1)"
d: "*Removed in Bitcoin Core 0.10.0*<br><br>Whether we're using this node as our syncnode during initial block download"
- n: "→ →<br>`inflight`"
t: "array"
p: "Required<br>(exactly 1)"
d: "*Added in Bitcoin Core 0.10.0*<br><br>An array of blocks which have been requested from this peer. May be empty"
- n: "→ → →<br>Blocks"
t: "number (int)"
p: "Optional<br>(0 or more)"
d: "The height of a block being requested from the remote peer"
- n: "→ →<br>`whitelisted`"
t: "bool"
p: "Required<br>(exactly 1)"
d: "*Added in Bitcoin Core 0.10.0*<br><br>Set to `true` if the remote peer has been whitelisted; otherwise, set to `false`. Whitelisted peers will not be banned if their ban score exceeds the maximum (100 by default). By default, peers connecting from localhost are whitelisted"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet getpeerinfo
{% endhighlight %}
Result (edited to show only a single entry, with IP addresses changed to
[RFC5737][] reserved IP addresses):
{% highlight json %}
[
{
"id" : 9,
"addr" : "192.0.2.113:18333",
"addrlocal" : "192.0.2.51:18333",
"services" : "0000000000000002",
"lastsend" : 1419277992,
"lastrecv" : 1419277992,
"bytessent" : 4968,
"bytesrecv" : 105078,
"conntime" : 1419265985,
"pingtime" : 0.05617800,
"version" : 70001,
"subver" : "/Satoshi:0.8.6/",
"inbound" : false,
"startingheight" : 315280,
"banscore" : 0,
"synced_headers" : -1,
"synced_blocks" : -1,
"inflight" : [
],
"whitelisted" : false
}
]
{% endhighlight %}
*See also*
* [GetAddedNodeInfo][rpc getaddednodeinfo]: {{summary_getAddedNodeInfo}}
* [GetNetTotals][rpc getnettotals]: {{summary_getNetTotals}}
* [GetNetworkInfo][rpc getnetworkinfo]: {{summary_getNetworkInfo}}
{% endautocrossref %}

47
_includes/devdoc/bitcoin-core/rpcs/rpcs/getrawchangeaddress.md Normal file
View file

@ -0,0 +1,47 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getrawchangeaddress.md" %}
##### GetRawChangeAddress
{% include helpers/subhead-links.md %}
{% assign summary_getRawChangeAddress="returns a new Bitcoin address for receiving change. This is for use with raw transactions, not normal use." %}
{% autocrossref %}
*Requires wallet support.*
The `getrawchangeaddress` RPC {{summary_getRawChangeAddress}}
*Parameters: none*
*Result---a P2PKH address which can be used in raw transactions*
{% itemplate ntpd1 %}
- n: "`result`"
t: "string (base58)"
p: "Required<br>(exactly 1)"
d: "A P2PKH address which has not previously been returned by this RPC. The address will be removed from the keypool but not marked as a receiving address, so RPCs such as the `dumpwallet` RPC will show it as a change address. The address may already have been part of the keypool, so other RPCs such as the `dumpwallet` RPC may have disclosed it previously. If the wallet is unlocked, its keypool will also be filled to its max (by default, 100 unused keys). If the wallet is locked and its keypool is empty, this RPC will fail"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet getrawchangeaddress
{% endhighlight %}
Result:
{% highlight text %}
mnycUc8FRjJodfKhaj9QBZs2PwxxYoWqaK
{% endhighlight %}
*See also*
* [GetNewAddress][rpc getnewaddress]: {{summary_getNewAddress}}
* [GetAccountAddress][rpc getaccountaddress]: {{summary_getAccountAddress}}
{% endautocrossref %}

141
_includes/devdoc/bitcoin-core/rpcs/rpcs/getrawmempool.md Normal file
View file

@ -0,0 +1,141 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getrawmempool.md" %}
##### GetRawMemPool
{% include helpers/subhead-links.md %}
{% assign summary_getRawMemPool="returns all transaction identifiers (TXIDs) in the memory pool as a JSON array, or detailed information about each transaction in the memory pool as a JSON object." %}
{% autocrossref %}
The `getrawmempool` RPC {{summary_getRawMemPool}}
*Parameter---desired output format*
{% itemplate ntpd1 %}
- n: "Format"
t: "bool"
p: "Optional<br>(0 or 1)"
d: "Set to `true` to get verbose output describing each transaction in the memory pool; set to `false` (the default) to only get an array of TXIDs for transactions in the memory pool"
{% enditemplate %}
*Result (format `false`)---an array of TXIDs*
{% itemplate ntpd1 %}
- n: "`result`"
t: "array"
p: "Required<br>(exactly 1)"
d: "An array of TXIDs belonging to transactions in the memory pool. The array may be empty if there are no transactions in the memory pool"
- n: "→<br>TXID"
t: "string"
p: "Optional<br>(0 or more)"
d: "The TXID of a transaction in the memory pool, encoded as hex in RPC byte order"
{% enditemplate %}
*Result (format: `true`)---a JSON object describing each transaction*
{% itemplate ntpd1 %}
- n: "`result`"
t: "object"
p: "Required<br>(exactly 1)"
d: "A object containing transactions currently in the memory pool. May be empty"
- n: "→<br>TXID"
t: "string : object"
p: "Optional<br>(0 or more)"
d: "The TXID of a transaction in the memory pool, encoded as hex in RPC byte order"
- n: "→ →<br>`size`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The size of the serialized transaction in bytes"
- n: "→ →<br>`fee`"
t: "number (bitcoins)"
p: "Required<br>(exactly 1)"
d: "The transaction fee paid by the transaction in decimal bitcoins"
- n: "→ →<br>`time`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The time the transaction entered the memory pool, Unix epoch time format"
- n: "→ →<br>`height`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The block height when the transaction entered the memory pool"
- n: "→ →<br>`startingpriority`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The priority of the transaction when it first entered the memory pool"
- n: "→ →<br>`currentpriority`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The current priority of the transaction"
- n: "→ →<br>`depends`"
t: "array"
p: "Required<br>(exactly 1)"
d: "An array holding TXIDs of unconfirmed transactions this transaction depends upon. Those transactions must be part of a block before this transaction can be added to a block, although all transactions may be included in the same block. The array may be empty"
- n: "→ → →<br>Depends TXID"
t: "string"
p: "Optional (0 or more)"
d: "The TXIDs of any unconfirmed transactions this transaction depends upon, encoded as hex in RPC byte order"
{% enditemplate %}
*Examples from Bitcoin Core 0.10.0*
The default (`false`):
{% highlight bash %}
bitcoin-cli -testnet getrawmempool
{% endhighlight %}
Result:
{% highlight json %}
[
"2b1f41d6f1837e164d6d6811d3d8dad2e66effbd1058cd9ed7bdbe1cab20ae03",
"2baa1f49ac9b951fa781c4c95814333a2f3eda71ed3d0245cd76c2829b3ce354"
]
{% endhighlight %}
Verbose output (`true`):
{% highlight bash %}
bitcoin-cli -testnet getrawmempool true
{% endhighlight %}
Result:
{% highlight json %}
{
"2baa1f49ac9b951fa781c4c95814333a2f3eda71ed3d0245cd76c2829b3ce354" : {
"size" : 191,
"fee" : 0.00020000,
"time" : 1398867772,
"height" : 227310,
"startingpriority" : 54545454.54545455,
"currentpriority" : 54545454.54545455,
"depends" : [
]
}
}
{% endhighlight %}
*See also*
* [GetMemPoolInfo][rpc getmempoolinfo]: {{summary_getMemPoolInfo}}
* [GetTxOutSetInfo][rpc gettxoutsetinfo]: {{summary_getTxOutSetInfo}}
{% endautocrossref %}

191
_includes/devdoc/bitcoin-core/rpcs/rpcs/getrawtransaction.md Normal file
View file

@ -0,0 +1,191 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getrawtransaction.md" %}
##### GetRawTransaction
{% include helpers/subhead-links.md %}
{% assign summary_getRawTransaction="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 the RPC may fail on historic transactions unless you use the non-default `txindex=1` in your Bitcoin Core startup settings." %}
{% autocrossref %}
The `getrawtransaction` RPC {{summary_getRawTransaction}}
{{reindexNote}}
*Parameter #1---the TXID of the transaction to get*
{% itemplate ntpd1 %}
- n: "TXID"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The TXID of the transaction to get, encoded as hex in RPC byte order"
{% enditemplate %}
*Parameter #2---whether to get the serialized or decoded transaction*
{% itemplate ntpd1 %}
- n: "Verbose"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "Set to `0` (the default) to return the serialized transaction as hex. Set to `1` to return a decoded transaction"
{% enditemplate %}
*Result (if transaction not found)---`null`*
{% itemplate ntpd1 %}
- n: "`result`"
t: "null"
p: "Required<br>(exactly 1)"
d: "If the transaction wasn't found, the result will be JSON `null`. This can occur because the transaction doesn't exist in the block chain or memory pool, or because it isn't part of the transaction index. See the Bitcoin Core `-help` entry for `-txindex`"
{% enditemplate %}
*Result (if verbose=`0`)---the serialized transaction*
{% itemplate ntpd1 %}
- n: "`result`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "If the transaction was found, this will be the serialized transaction encoded as hex"
{% enditemplate %}
*Result (if verbose=`1`)---the decoded transaction*
{% itemplate ntpd1 %}
- n: "`result`"
t: "object"
p: "Required<br>(exactly 1)"
d: "If the transaction was found, this will be an object describing it"
{{INCLUDE_DECODE_RAW_TRANSACTION}}
- n: "→<br>`blockhash`"
t: "string (hex)"
p: "Optional<br>(0 or 1)"
d: "If the transaction has been included in a block on the local best block chain, this is the hash of that block encoded as hex in RPC byte order"
- n: "→<br>`confirmations`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "If the transaction has been included in a block on the local best block chain, this is how many confirmations it has. Otherwise, this is `0`"
- n: "→<br>`time`"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "If the transaction has been included in a block on the local best block chain, this is the block header time of that block (may be in the future)"
- n: "→<br>`blocktime`"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "This field is currently identical to the time field described above"
{% enditemplate %}
*Examples from Bitcoin Core 0.10.0*
A transaction in serialized transaction format:
{% highlight bash %}
bitcoin-cli -testnet getrawtransaction \
ef7c0cbf6ba5af68d2ea239bba709b26ff7b0b669839a63bb01c2cb8e8de481e
{% endhighlight %}
Result (wrapped):
{% highlight text %}
0100000001268a9ad7bfb21d3c086f0ff28f73a064964aa069ebb69a9e437da8\
5c7e55c7d7000000006b483045022100ee69171016b7dd218491faf6e13f53d4\
0d64f4b40123a2de52560feb95de63b902206f23a0919471eaa1e45a0982ed28\
8d374397d30dff541b2dd45a4c3d0041acc0012103a7c1fd1fdec50e1cf3f0cc\
8cb4378cd8e9a2cee8ca9b3118f3db16cbbcf8f326ffffffff0350ac60020000\
00001976a91456847befbd2360df0e35b4e3b77bae48585ae06888ac80969800\
000000001976a9142b14950b8d31620c6cc923c5408a701b1ec0a02088ac002d\
3101000000001976a9140dfc8bafc8419853b34d5e072ad37d1a5159f58488ac\
00000000
{% endhighlight %}
Get the same transaction in JSON:
{% highlight bash %}
bitcoin-cli -testnet getrawtransaction \
ef7c0cbf6ba5af68d2ea239bba709b26ff7b0b669839a63bb01c2cb8e8de481e \
1
{% endhighlight %}
Result:
{% highlight json %}
{
"hex" : "0100000001268a9ad7bfb21d3c086f0ff28f73a064964aa069ebb69a9e437da85c7e55c7d7000000006b483045022100ee69171016b7dd218491faf6e13f53d40d64f4b40123a2de52560feb95de63b902206f23a0919471eaa1e45a0982ed288d374397d30dff541b2dd45a4c3d0041acc0012103a7c1fd1fdec50e1cf3f0cc8cb4378cd8e9a2cee8ca9b3118f3db16cbbcf8f326ffffffff0350ac6002000000001976a91456847befbd2360df0e35b4e3b77bae48585ae06888ac80969800000000001976a9142b14950b8d31620c6cc923c5408a701b1ec0a02088ac002d3101000000001976a9140dfc8bafc8419853b34d5e072ad37d1a5159f58488ac00000000",
"txid" : "ef7c0cbf6ba5af68d2ea239bba709b26ff7b0b669839a63bb01c2cb8e8de481e",
"version" : 1,
"locktime" : 0,
"vin" : [
{
"txid" : "d7c7557e5ca87d439e9ab6eb69a04a9664a0738ff20f6f083c1db2bfd79a8a26",
"vout" : 0,
"scriptSig" : {
"asm" : "3045022100ee69171016b7dd218491faf6e13f53d40d64f4b40123a2de52560feb95de63b902206f23a0919471eaa1e45a0982ed288d374397d30dff541b2dd45a4c3d0041acc001 03a7c1fd1fdec50e1cf3f0cc8cb4378cd8e9a2cee8ca9b3118f3db16cbbcf8f326",
"hex" : "483045022100ee69171016b7dd218491faf6e13f53d40d64f4b40123a2de52560feb95de63b902206f23a0919471eaa1e45a0982ed288d374397d30dff541b2dd45a4c3d0041acc0012103a7c1fd1fdec50e1cf3f0cc8cb4378cd8e9a2cee8ca9b3118f3db16cbbcf8f326"
},
"sequence" : 4294967295
}
],
"vout" : [
{
"value" : 0.39890000,
"n" : 0,
"scriptPubKey" : {
"asm" : "OP_DUP OP_HASH160 56847befbd2360df0e35b4e3b77bae48585ae068 OP_EQUALVERIFY OP_CHECKSIG",
"hex" : "76a91456847befbd2360df0e35b4e3b77bae48585ae06888ac",
"reqSigs" : 1,
"type" : "pubkeyhash",
"addresses" : [
"moQR7i8XM4rSGoNwEsw3h4YEuduuP6mxw7"
]
}
},
{
"value" : 0.10000000,
"n" : 1,
"scriptPubKey" : {
"asm" : "OP_DUP OP_HASH160 2b14950b8d31620c6cc923c5408a701b1ec0a020 OP_EQUALVERIFY OP_CHECKSIG",
"hex" : "76a9142b14950b8d31620c6cc923c5408a701b1ec0a02088ac",
"reqSigs" : 1,
"type" : "pubkeyhash",
"addresses" : [
"mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN"
]
}
},
{
"value" : 0.20000000,
"n" : 2,
"scriptPubKey" : {
"asm" : "OP_DUP OP_HASH160 0dfc8bafc8419853b34d5e072ad37d1a5159f584 OP_EQUALVERIFY OP_CHECKSIG",
"hex" : "76a9140dfc8bafc8419853b34d5e072ad37d1a5159f58488ac",
"reqSigs" : 1,
"type" : "pubkeyhash",
"addresses" : [
"mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe"
]
}
}
],
"blockhash" : "00000000103e0091b7d27e5dc744a305108f0c752be249893c749e19c1c82317",
"confirmations" : 88192,
"time" : 1398734825,
"blocktime" : 1398734825
}
{% endhighlight %}
*See also*
* [GetTransaction][rpc gettransaction]: {{summary_getTransaction}}
{% endautocrossref %}

63
_includes/devdoc/bitcoin-core/rpcs/rpcs/getreceivedbyaccount.md Normal file
View file

@ -0,0 +1,63 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getreceivedbyaccount.md" %}
##### GetReceivedByAccount
{% include helpers/subhead-links.md %}
{% assign summary_getReceivedByAccount="returns the total amount received by addresses in a particular account from transactions with the specified number of confirmations. It does not count coinbase transactions." %}
{% autocrossref %}
*Requires wallet support.*
The `getreceivedbyaccount` RPC {{summary_getReceivedByAccount}}
*Parameter #1---the account name*
{% itemplate ntpd1 %}
- n: "Account"
t: "string"
p: "Required<br>(exactly 1)"
d: "The name of the account containing the addresses to get. For the default account, use an empty string (\"\")"
{% enditemplate %}
*Parameter #2---the minimum number of confirmations*
{{INCLUDE_CONFIRMATIONS_PARAMETER}}
*Result---the number of bitcoins received*
{% itemplate ntpd1 %}
- n: "`result`"
t: "number (bitcoins)"
p: "Required<br>(exactly 1)"
d: "The number of bitcoins received by the account. May be `0`"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Get the bitcoins received by the "doc test" account with six or more
confirmations:
{% highlight bash %}
bitcoin-cli -testnet getreceivedbyaccount "doc test" 6
{% endhighlight %}
Result:
{% highlight json %}
0.30000000
{% endhighlight %}
*See also*
* [GetReceivedByAddress][rpc getreceivedbyaddress]: {{summary_getReceivedByAddress}}
* [GetAddressesByAccount][rpc getaddressesbyaccount]: {{summary_getAddressesByAccount}}
* [ListAccounts][rpc listaccounts]: {{summary_listAccounts}}
{% endautocrossref %}

63
_includes/devdoc/bitcoin-core/rpcs/rpcs/getreceivedbyaddress.md Normal file
View file

@ -0,0 +1,63 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getreceivedbyaddress.md" %}
##### GetReceivedByAddress
{% include helpers/subhead-links.md %}
{% 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." %}
{% autocrossref %}
*Requires wallet support.*
The `getreceivedbyaddress` RPC {{summary_getReceivedByAddress}}
*Parameter #1---the address*
{% itemplate ntpd1 %}
- n: "Address"
t: "string"
p: "Required<br>(exactly 1)"
d: "The address whose transactions should be tallied"
{% enditemplate %}
*Parameter #2---the minimum number of confirmations*
{{INCLUDE_CONFIRMATIONS_PARAMETER}}
*Result---the number of bitcoins received*
{% itemplate ntpd1 %}
- n: "`result`"
t: "number (bitcoins)"
p: "Required<br>(exactly 1)"
d: "The number of bitcoins received by the address, excluding coinbase transactions. May be `0`"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Get the bitcoins received for a particular address, only counting
transactions with six or more confirmations:
{% highlight bash %}
bitcoin-cli -testnet getreceivedbyaddress mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN 6
{% endhighlight %}
Result:
{% highlight json %}
0.30000000
{% endhighlight %}
*See also*
* [GetReceivedByAccount][rpc getreceivedbyaccount]: {{summary_getReceivedByAccount}}
* [GetAddressesByAccount][rpc getaddressesbyaccount]: {{summary_getAddressesByAccount}}
* [ListAccounts][rpc listaccounts]: {{summary_listAccounts}}
{% endautocrossref %}

148
_includes/devdoc/bitcoin-core/rpcs/rpcs/gettransaction.md Normal file
View file

@ -0,0 +1,148 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/gettransaction.md" %}
##### GetTransaction
{% include helpers/subhead-links.md %}
{% assign summary_getTransaction="gets detailed information about an in-wallet transaction." %}
{% autocrossref %}
*Requires wallet support.*
The `gettransaction` RPC {{summary_getTransaction}}
*Parameter #1---a transaction identifier (TXID)*
{% itemplate ntpd1 %}
- n: "TXID"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The TXID of the transaction to get details about. The TXID must be encoded as hex in RPC byte order"
{% enditemplate %}
*Parameter #2---whether to include watch-only addresses in details and calculations*
{{INCLUDE_INCLUDE_WATCH_ONLY_PARAMETER}}
*Result---a description of the transaction*
{% assign DEPTH="→ " %}
{% include helpers/vars.md %}
{% itemplate ntpd1 %}
- n: "`result`"
t: "object"
p: "Required<br>(exactly 1)"
d: "An object describing how the transaction affects the wallet"
- n: "→<br>`amount`"
t: "number (bitcoins)"
p: "Required<br>(exactly 1)"
d: "A positive number of bitcoins if this transaction increased the total wallet balance; a negative number of bitcoins if this transaction decreased the total wallet balance, or `0` if the transaction had no net effect on wallet balance"
- n: "→<br>`fee`"
t: "number (bitcoins)"
p: "Optional<br>(0 or 1)"
d: "If an outgoing transaction, this is the fee paid by the transaction reported as negative bitcoins"
{{INCLUDE_F_LIST_TRANSACTIONS_F_FULL}}
- n: "→<br>`details`"
t: "array"
p: "Required<br>(exactly 1)"
d: "An array containing one object for each input or output in the transaction which affected the wallet"
- n: "→ → <br>`involvesWatchonly`"
t: "bool"
p: "Optional<br>(0 or 1)"
d: "*Added in Bitcoin Core 0.10.0*<br><br>Set to `true` if the input or output involves a watch-only address. Otherwise not returned"
- n: "→ →<br>`account`"
t: "string"
p: "Required<br>(exactly 1)"
d: "The account which the payment was credited to or debited from. May be an empty string (\"\") for the default account"
- n: "→ →<br>`address`"
t: "string (base58)"
p: "Optional<br>(0 or 1)"
d: "If an output, the address paid (may be someone else's address not belonging to this wallet). If an input, the address paid in the previous output. May be empty if the address is unknown, such as when paying to a non-standard pubkey script"
- n: "→ →<br>`category`"
t: "string"
p: "Required<br>(exactly 1)"
d: "Set to one of the following values:<br>• `send` if sending payment<br>• `receive` if this wallet received payment in a regular transaction<br>• `generate` if a matured and spendable coinbase<br>• `immature` if a coinbase that is not spendable yet<br>• `orphan` if a coinbase from a block that's not in the local best block chain"
- n: "→ →<br>`amount`"
t: "number (bitcoins)"
p: "Required<br>(exactly 1)"
d: "A negative bitcoin amount if sending payment; a positive bitcoin amount if receiving payment (including coinbases)"
- n: "→ →<br>`vout`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "*Added in Bitcoin Core 0.10.0*<br><br>For an output, the output index (vout) for this output in this transaction. For an input, the output index for the output being spent in its transaction. Because inputs list the output indexes from previous transactions, more than one entry in the details array may have the same output index"
- n: "→ →<br>`fee`"
t: "number (bitcoins)"
p: "Optional<br>(0 or 1)"
d: "If sending payment, the fee paid as a negative bitcoins value. May be `0`. Not returned if receiving payment"
- n: "→<br>`hex`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The transaction in serialized transaction format"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet gettransaction \
5a7d24cd665108c66b2d56146f244932edae4e2376b561b3d396d5ae017b9589
{% endhighlight %}
Result:
{% highlight json %}
{
"amount" : 0.00000000,
"fee" : 0.00000000,
"confirmations" : 106670,
"blockhash" : "000000008b630b3aae99b6fe215548168bed92167c47a2f7ad4df41e571bcb51",
"blockindex" : 1,
"blocktime" : 1396321351,
"txid" : "5a7d24cd665108c66b2d56146f244932edae4e2376b561b3d396d5ae017b9589",
"walletconflicts" : [
],
"time" : 1396321351,
"timereceived" : 1418924711,
"details" : [
{
"account" : "",
"address" : "mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN",
"category" : "send",
"amount" : -0.10000000,
"vout" : 0,
"fee" : 0.00000000
},
{
"account" : "doc test",
"address" : "mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN",
"category" : "receive",
"amount" : 0.10000000,
"vout" : 0
}
],
"hex" : "0100000001cde58f2e37d000eabbb60d9cf0b79ddf67cede6dba58732539983fa341dd5e6c010000006a47304402201feaf12908260f666ab369bb8753cdc12f78d0c8bdfdef997da17acff502d321022049ba0b80945a7192e631c03bafd5c6dc3c7cb35ac5c1c0ffb9e22fec86dd311c01210321eeeb46fd878ce8e62d5e0f408a0eab41d7c3a7872dc836ce360439536e423dffffffff0180969800000000001976a9142b14950b8d31620c6cc923c5408a701b1ec0a02088ac00000000"
}
{% endhighlight %}
*See also*
* [GetRawTransaction][rpc getrawtransaction]: {{summary_getRawTransaction}}
{% endautocrossref %}

155
_includes/devdoc/bitcoin-core/rpcs/rpcs/gettxout.md Normal file
View file

@ -0,0 +1,155 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/gettxout.md" %}
##### GetTxOut
{% include helpers/subhead-links.md %}
{% assign summary_getTxOut="returns details about a transaction output. Only unspent transaction outputs (UTXOs) are guaranteed to be available." %}
{% autocrossref %}
The `gettxout` RPC {{summary_getTxOut}}
*Parameter #1---the TXID of the output to get*
{% itemplate ntpd1 %}
- n: "TXID"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The TXID of the transaction containing the output to get, encoded as hex in RPC byte order"
{% enditemplate %}
*Parameter #2---the output index number (vout) of the output to get*
{% itemplate ntpd1 %}
- n: "Vout"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The output index number (vout) of the output within the transaction; the first output in a transaction is vout 0"
{% enditemplate %}
*Parameter #3---whether to display unconfirmed outputs from the memory pool*
{% itemplate ntpd1 %}
- n: "Unconfirmed"
t: "bool"
p: "Optional<br>(0 or 1)"
d: "Set to `true` to display unconfirmed outputs from the memory pool; set to `false` (the default) to only display outputs from confirmed transactions"
{% enditemplate %}
*Result---a description of the output*
{% itemplate ntpd1 %}
- n: "`result`"
t: "object/null"
p: "Required<br>(exactly 1)"
d: "Information about the output. If output wasn't found or if an error occurred, this will be JSON `null`"
- n: "→<br>`bestblock`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The hash of the header of the block on the local best block chain which includes this transaction. The hash will encoded as hex in RPC byte order. If the transaction is not part of a block, the string will be empty"
- n: "→<br>`confirmations`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The number of confirmations received for the transaction containing this output or `0` if the transaction hasn't been confirmed yet"
- n: "→<br>`value`"
t: "number (bitcoins)"
p: "Required<br>(exactly 1)"
d: "The amount of bitcoins spent to this output. May be `0`"
- n: "→<br>`scriptPubKey`"
t: "string : object"
p: "Optional<br>(0 or 1)"
d: "An object with information about the pubkey script. This may be `null` if there was no pubkey script"
- n: "→ →<br>`asm`"
t: "string"
p: "Required<br>(exactly 1)"
d: "The pubkey script in decoded form with non-data-pushing op codes listed"
- n: "→ →<br>`hex`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The pubkey script encoded as hex"
- n: "→ →<br>`reqSigs`"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "The number of signatures required; this is always `1` for P2PK, P2PKH, and P2SH (including P2SH multisig because the redeem script is not available in the pubkey script). It may be greater than 1 for bare multisig. This value will not be returned for `nulldata` or `nonstandard` script types (see the `type` key below)"
- n: "→ →<br>`type`"
t: "string"
p: "Optional<br>(0 or 1)"
d: "The type of script. This will be one of the following:<br>• `pubkey` for a P2PK script<br>• `pubkeyhash` for a P2PKH script<br>• `scripthash` for a P2SH script<br>• `multisig` for a bare multisig script<br>• `nulldata` for nulldata scripts<br>• `nonstandard` for unknown scripts"
- n: "→ →<br>`addresses`"
t: "string : array"
p: "Optional<br>(0 or 1)"
d: "The P2PKH or P2SH addresses used in this transaction, or the computed P2PKH address of any pubkeys in this transaction. This array will not be returned for `nulldata` or `nonstandard` script types"
- n: "→ → →<br>Address"
t: "string"
p: "Required<br>(1 or more)"
d: "A P2PKH or P2SH address"
- n: "→<br>`version`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The transaction version number of the transaction containing the pubkey script"
- n: "→<br>`coinbase`"
t: "bool"
p: "Required<br>(exactly 1)"
d: "Set to `true` if the transaction output belonged to a coinbase transaction; set to `false` for all other transactions. Coinbase transactions need to have 101 confirmations before their outputs can be spent"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Get the UTXO from the following transaction from the first output index ("0"),
searching the memory pool if necessary.
{% highlight bash %}
bitcoin-cli -testnet gettxout \
d77aee99e8bdc11f40b8a9354956f0346fec5535b82c77c8b5c06047e3bca86a \
0 true
{% endhighlight %}
Result:
{% highlight json %}
{
"bestblock" : "00000000c92356f7030b1deeab54b3b02885711320b4c48523be9daa3e0ace5d",
"confirmations" : 0,
"value" : 0.00100000,
"scriptPubKey" : {
"asm" : "OP_DUP OP_HASH160 a11418d3c144876258ba02909514d90e71ad8443 OP_EQUALVERIFY OP_CHECKSIG",
"hex" : "76a914a11418d3c144876258ba02909514d90e71ad844388ac",
"reqSigs" : 1,
"type" : "pubkeyhash",
"addresses" : [
"mvCfAJSKaoFXoJEvv8ssW7wxaqRPphQuSv"
]
},
"version" : 1,
"coinbase" : false
}
{% endhighlight %}
*See also*
* [GetRawTransaction][rpc getrawtransaction]: {{summary_getRawTransaction}}
* [GetTransaction][rpc gettransaction]: {{summary_getTransaction}}
{% endautocrossref %}

96
_includes/devdoc/bitcoin-core/rpcs/rpcs/gettxoutproof.md Normal file
View file

@ -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/devdoc/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 %}

88
_includes/devdoc/bitcoin-core/rpcs/rpcs/gettxoutsetinfo.md Normal file
View file

@ -0,0 +1,88 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/gettxoutsetinfo.md" %}
##### GetTxOutSetInfo
{% include helpers/subhead-links.md %}
{% 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." %}
{% autocrossref %}
The `gettxoutsetinfo` RPC {{summary_getTxOutSetInfo}}
*Parameters: none*
*Result---statistics about the UTXO set*
{% itemplate ntpd1 %}
- n: "`result`"
t: "object"
p: "Required<br>(exactly 1)"
d: "Information about the UTXO set"
- n: "→<br>`height`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The height of the local best block chain. A new node with only the hardcoded genesis block will have a height of 0"
- n: "→<br>`bestblock`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The hash of the header of the highest block on the local best block chain, encoded as hex in RPC byte order"
- n: "→<br>`transactions`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The number of transactions with unspent outputs"
- n: "→<br>`txouts`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The number of unspent transaction outputs"
- n: "→<br>`bytes_serialized`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The size of the serialized UTXO set in bytes; not counting overhead, this is the size of the `chainstate` directory in the Bitcoin Core configuration directory"
- n: "→<br>`hash_serialized`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "A SHA256(SHA256()) hash of the serialized UTXO set; useful for comparing two nodes to see if they have the same set (they should, if they always used the same serialization format and currently have the same best block). The hash is encoded as hex in RPC byte order"
- n: "→<br>`total_amount`"
t: "number (bitcoins)"
p: "Required<br>(exactly 1)"
d: "The total number of bitcoins in the UTXO set"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet gettxoutsetinfo
{% endhighlight %}
Result:
{% highlight json %}
{
"height" : 315293,
"bestblock" : "00000000c92356f7030b1deeab54b3b02885711320b4c48523be9daa3e0ace5d",
"transactions" : 771920,
"txouts" : 2734587,
"bytes_serialized" : 102629817,
"hash_serialized" : "4753470fda0145760109e79b8c218a1331e84bb4269d116857b8a4597f109905",
"total_amount" : 13131746.33839451
}
{% endhighlight %}
*See also*
* [GetBlockChainInfo][rpc getblockchaininfo]: {{summary_getBlockChainInfo}}
* [GetMemPoolInfo][rpc getmempoolinfo]: {{summary_getMemPoolInfo}}
{% endautocrossref %}

46
_includes/devdoc/bitcoin-core/rpcs/rpcs/getunconfirmedbalance.md Normal file
View file

@ -0,0 +1,46 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getunconfirmedbalance.md" %}
##### GetUnconfirmedBalance
{% include helpers/subhead-links.md %}
{% assign summary_getUnconfirmedBalance="returns the wallet's total unconfirmed balance." %}
{% autocrossref %}
*Requires wallet support.*
The `getunconfirmedbalance` RPC {{summary_getUnconfirmedBalance}}
*Parameters: none*
*Result---the balance of unconfirmed transactions paying this wallet*
{% itemplate ntpd1 %}
- n: "`result`"
t: "number (bitcoins)"
p: "Required<br>(exactly 1)"
d: "The total number of bitcoins paid to this wallet in unconfirmed transactions"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet getunconfirmedbalance
{% endhighlight %}
Result (no unconfirmed incoming payments):
{% highlight json %}
0.00000000
{% endhighlight %}
*See also*
* [GetBalance][rpc getbalance]: {{summary_getBalance}}
{% endautocrossref %}

83
_includes/devdoc/bitcoin-core/rpcs/rpcs/getwalletinfo.md Normal file
View file

@ -0,0 +1,83 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getwalletinfo.md" %}
##### GetWalletInfo
{% include helpers/subhead-links.md %}
{% assign summary_getWalletInfo="provides information about the wallet." %}
{% autocrossref %}
*Requires wallet support. Added in Bitcoin Core 0.9.2.*
The `getwalletinfo` RPC {{summary_getWalletInfo}}
*Parameters: none*
*Result---information about the wallet*
{% itemplate ntpd1 %}
- n: "`result`"
t: "object"
p: "Required<br>(exactly 1)"
d: "An object describing the wallet"
- n: "→<br>`walletversion`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The version number of the wallet"
- n: "→<br>`balance`"
t: "number (bitcoins)"
p: "Required<br>(exactly 1)"
d: "The balance of the wallet. The same as returned by the `getbalance` RPC with default parameters"
- n: "→<br>`txcount`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The total number of transactions in the wallet (both spends and receives)"
- n: "→<br>`keypoololdest`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The date as Unix epoch time when the oldest key in the wallet key pool was created; useful for only scanning blocks created since this date for transactions"
- n: "→<br>`keypoolsize`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The number of keys in the wallet keypool"
- n: "→<br>`unlocked_until`"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "Only returned if the wallet was encrypted with the `encryptwallet` RPC. A Unix epoch date when the wallet will be locked, or `0` if the wallet is currently locked"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet getwalletinfo
{% endhighlight %}
Result:
{% highlight json %}
{
"walletversion" : 60000,
"balance" : 1.45060000,
"txcount" : 17,
"keypoololdest" : 1398809500,
"keypoolsize" : 196,
"unlocked_until" : 0
}
{% endhighlight %}
*See also*
* [ListTransactions][rpc listtransactions]: {{summary_listTransactions}}
{% endautocrossref %}

24
_includes/devdoc/bitcoin-core/rpcs/rpcs/getwork.md Normal file
View file

@ -0,0 +1,24 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/getwork.md" %}
##### GetWork
{% include helpers/subhead-links.md %}
{% assign summary_getWork="was removed in Bitcoin Core 0.10.0." %}
{% autocrossref %}
The `getwork` RPC {{summary_getWork}}. If you have an older
version of Bitcoin Core, use the `help` RPC to get help. For example:
`help getwork`
*See also*
* [GetBlockTemplate][rpc getblocktemplate]: {{summary_getBlockTemplate}}
* [SubmitBlock][rpc submitblock]: {{summary_submitBlock}}
* [SetGenerate][rpc setgenerate]: {{summary_setGenerate}}
{% endautocrossref %}

63
_includes/devdoc/bitcoin-core/rpcs/rpcs/help.md Normal file
View file

@ -0,0 +1,63 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/help.md" %}
##### Help
{% include helpers/subhead-links.md %}
{% assign summary_help="lists all available public RPC commands, or gets help for the specified RPC. Commands which are unavailable will not be listed, such as wallet RPCs if wallet support is disabled." %}
{% autocrossref %}
The `help` RPC {{summary_help}}
*Parameter---the name of the RPC to get help for*
{% itemplate ntpd1 %}
- n: "RPC"
t: "string"
p: "Optional<br>(0 or 1)"
d: "The name of the RPC to get help for. If omitted, Bitcoin Core 0.9x will display an alphabetical list of commands; Bitcoin Core 0.10.0 will display a categorized list of commands"
{% enditemplate %}
*Result---a list of RPCs or detailed help for a specific RPC*
{% itemplate ntpd1 %}
- n: "`result`"
t: "string"
p: "Required<br>(exactly 1)"
d: "The help text for the specified RPC or the list of commands. The `bitcoin-cli` command will parse this text and format it as human-readable text"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Command to get help about the `help` RPC:
{% highlight bash %}
bitcoin-cli -testnet help help
{% endhighlight %}
Result:
{% highlight text %}
help ( "command" )
List all commands, or get help for a specified command.
Arguments:
1. "command" (string, optional) The command to get help on
Result:
"text" (string) The help text
{% endhighlight %}
*See also*
* The [RPC Quick Reference][section RPC quick reference]
{% endautocrossref %}

89
_includes/devdoc/bitcoin-core/rpcs/rpcs/importaddress.md Normal file
View file

@ -0,0 +1,89 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/importaddress.md" %}
##### ImportAddress
{% include helpers/subhead-links.md %}
{% assign summary_importAddress="adds an address or pubkey script to the wallet without the associated private key, allowing you to watch for transactions affecting that address or pubkey script without being able to spend any of its outputs." %}
{% autocrossref %}
*Requires wallet support. Added in Bitcoin Core 0.10.0.*
The `importaddress` RPC {{summary_importAddress}}
*Parameter #1---the address or pubkey script to watch*
{% itemplate ntpd1 %}
- n: "Address or Script"
t: "string (base58 or hex)"
p: "Required<br>(exactly 1)"
d: "Either a P2PKH or P2SH address encoded in base58check, or a pubkey script encoded as hex"
{% enditemplate %}
*Parameter #2---The account into which to place the address or pubkey script*
{% itemplate ntpd1 %}
- n: "Account"
t: "string"
p: "Optional<br>(0 or 1)"
d: "An account name into which the address should be placed. Default is the default account, an empty string(\"\")"
{% enditemplate %}
*Parameter #3---whether to rescan the block chain*
{% itemplate ntpd1 %}
- n: "Rescan"
t: "bool"
p: "Optional<br>(0 or 1)"
d: "Set to `true` (the default) to rescan the entire local block database for transactions affecting any address or pubkey script in the wallet (including transaction affecting the newly-added address or pubkey script). Set to `false` to not rescan the block database (rescanning can be performed at any time by restarting Bitcoin Core with the `-rescan` command-line argument). Rescanning may take several minutes. Notes: if the address or pubkey script is already in the wallet, the block database will not be rescanned even if this parameter is set"
{% enditemplate %}
*Result---`null` on success*
{% itemplate ntpd1 %}
- n: "`result`"
t: "null"
p: "Required<br>(exactly 1)"
d: "If the address or pubkey script is added to the wallet (or is already part of the wallet), JSON `null` will be returned"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Add an address, rescanning the local block database for any transactions
matching it.
{% highlight bash %}
bitcoin-cli -testnet importaddress \
muhtvdmsnbQEPFuEmxcChX58fGvXaaUoVt "watch-only test" true
{% endhighlight %}
Result:
(No output<!--noref-->; success.)
Show that the address has been added:
{% highlight bash %}
bitcoin-cli -testnet getaccount muhtvdmsnbQEPFuEmxcChX58fGvXaaUoVt
{% endhighlight %}
Result:
{% highlight text %}
watch-only test
{% endhighlight %}
*See also*
* [ImportPrivKey][rpc importprivkey]: {{summary_importPrivKey}}
* [ListReceivedByAddress][rpc listreceivedbyaddress]: {{summary_listReceivedByAddress}}
{% endautocrossref %}

79
_includes/devdoc/bitcoin-core/rpcs/rpcs/importprivkey.md Normal file
View file

@ -0,0 +1,79 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/importprivkey.md" %}
##### ImportPrivKey
{% include helpers/subhead-links.md %}
{% assign summary_importPrivKey="adds a private key to your wallet. The key should be formatted in the wallet import format created by the `dumpprivkey` RPC." %}
{% autocrossref %}
*Requires wallet support. Wallet must be unlocked.*
The `importprivkey` RPC {{summary_importPrivKey}}
*Parameter #1---the private key to import*
{% itemplate ntpd1 %}
- n: "Private Key"
t: "string (base58)"
p: "Required<br>(exactly 1)"
d: "The private key to import into the wallet encoded in base58check using wallet import format (WIF)"
{% enditemplate %}
*Parameter #2---the account into which the key should be placed*
{% itemplate ntpd1 %}
- n: "Account"
t: "string"
p: "Optional<br>(0 or 1)"
d: "The name of an account to which transactions involving the key should be assigned. The default is the default account, an empty string (\"\")"
{% enditemplate %}
*Parameter #3---whether to rescan the block chain*
{% itemplate ntpd1 %}
- n: "Rescan"
t: "bool"
p: "Optional<br>(0 or 1)"
d: "Set to `true` (the default) to rescan the entire local block database for transactions affecting any address or pubkey script in the wallet (including transaction affecting the newly-added address for this private key). Set to `false` to not rescan the block database (rescanning can be performed at any time by restarting Bitcoin Core with the `-rescan` command-line argument). Rescanning may take several minutes. Notes: if the address for this key is already in the wallet, the block database will not be rescanned even if this parameter is set"
{% enditemplate %}
*Result---`null` on success*
{% itemplate ntpd1 %}
- n: "`result`"
t: "null"
p: "Required<br>(exactly 1)"
d: "If the private key is added to the wallet (or is already part of the wallet), JSON `null` will be returned"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Import the private key for the address
mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe, giving it a label and scanning the
entire block chain:
{% highlight bash %}
bitcoin-cli -testnet importprivkey \
cU8Q2jGeX3GNKNa5etiC8mgEgFSeVUTRQfWE2ZCzszyqYNK4Mepy \
"test label" \
true
{% endhighlight %}
(Success: no result displayed.)
*See also*
* [DumpPrivKey][rpc dumpprivkey]: {{summary_dumpPrivKey}}
* [ImportAddress][rpc importaddress]: {{summary_importAddress}}
* [ImportWallet][rpc importwallet]: {{summary_importWallet}}
{% endautocrossref %}

54
_includes/devdoc/bitcoin-core/rpcs/rpcs/importwallet.md Normal file
View file

@ -0,0 +1,54 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/importwallet.md" %}
##### ImportWallet
{% include helpers/subhead-links.md %}
{% assign summary_importWallet="imports private keys from a file in wallet dump file format (see the `dumpwallet` RPC). These keys will be added to the keys currently in the wallet. This call may need to rescan all or parts of the block chain for transactions affecting the newly-added keys, which may take several minutes." %}
{% autocrossref %}
*Requires wallet support. Requires an unlocked wallet or an
unencrypted wallet.*
The `importwallet` RPC {{summary_importWallet}}
*Parameter #1---the file to import*
{% itemplate ntpd1 %}
- n: "Filename"
t: "string"
p: "Required<br>(exactly 1)"
d: "The file to import. The path is relative to Bitcoin Core's working directory"
{% enditemplate %}
*Result---`null` on success*
{% itemplate ntpd1 %}
- n: "`result`"
t: "null"
p: "Required<br>(exactly 1)"
d: "If all the keys in the file are added to the wallet (or are already part of the wallet), JSON `null` will be returned"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Import the file shown in the example subsection of the `dumpwallet` RPC.
{% highlight bash %}
bitcoin-cli -testnet importwallet /tmp/dump.txt
{% endhighlight %}
(Success: no result displayed.)
*See also*
* [DumpWallet][rpc dumpwallet]: {{summary_dumpWallet}}
* [ImportPrivKey][rpc importprivkey]: {{summary_importPrivKey}}
{% endautocrossref %}

55
_includes/devdoc/bitcoin-core/rpcs/rpcs/keypoolrefill.md Normal file
View file

@ -0,0 +1,55 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/keypoolrefill.md" %}
##### KeyPoolRefill
{% include helpers/subhead-links.md %}
{% assign summary_keyPoolRefill="fills the cache of unused pre-generated keys (the keypool)." %}
{% autocrossref %}
*Requires wallet support. Requires an unlocked wallet or an unencrypted
wallet.*
The `keypoolrefill` RPC {{summary_keyPoolRefill}}
*Parameter #1---the new keypool size*
{% itemplate ntpd1 %}
- n: "Key Pool Size"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "The new size of the keypool; if the number of keys in the keypool is less than this number, new keys will be generated. Default is `100`. The value `0` also equals the default. The value specified is for this call only---the default keypool size is not changed"
{% enditemplate %}
*Result---`null` on success*
{% itemplate ntpd1 %}
- n: "`result`"
t: "null"
p: "Required<br>(exactly 1)"
d: "If the keypool is successfully filled, JSON `null` will be returned"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Generate one extra key than the default:
{% highlight bash %}
bitcoin-cli -testnet keypoolrefill 101
{% endhighlight %}
(No result shown: success.)
*See also*
* [GetNewAddress][rpc getnewaddress]: {{summary_getNewAddress}}
* [GetAccountAddress][rpc getaccountaddress]: {{summary_getAccountAddress}}
* [GetWalletInfo][rpc getwalletinfo]: {{summary_getWalletInfo}}
{% endautocrossref %}

73
_includes/devdoc/bitcoin-core/rpcs/rpcs/listaccounts.md Normal file
View file

@ -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/devdoc/bitcoin-core/rpcs/rpcs/listaccounts.md" %}
##### ListAccounts
{% include helpers/subhead-links.md %}
{% assign summary_listAccounts="lists accounts and their balances." %}
{% autocrossref %}
*Requires wallet support.*
The `listaccounts` RPC {{summary_listAccounts}}
*Parameter #1---the minimum number of confirmations a transaction must have*
{{INCLUDE_CONFIRMATIONS_PARAMETER}}
*Parameter #2---whether to include watch-only addresses in results*
{{INCLUDE_INCLUDE_WATCH_ONLY_PARAMETER}}
*Result---a list of accounts and their balances*
{% itemplate ntpd1 %}
- n: "`result`"
t: "object"
p: "Required<br>(exactly 1)"
d: "A JSON array containing key/value pairs with account names and values. Must include, at the very least, the default account (\"\")"
- n: "→<br>Account : Balance"
t: "string : number (bitcoins)"
p: "Required<br>(1 or more)"
d: "The name of an account as a string paired with the balance of the account as a number of bitcoins. The number of bitcoins may be negative if the account has spent more bitcoins than it received. Accounts with zero balances and zero transactions will be displayed"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Display account balances with one confirmation and watch-only addresses
included.
{% highlight bash %}
bitcoin-cli -testnet listaccounts 1 true
{% endhighlight %}
Result:
{% highlight json %}
{
"" : -2.73928803,
"Refund from example.com" : 0.00000000,
"doc test" : -498.45900000,
"someone else's address" : 0.00000000,
"someone else's address2" : 0.00050000,
"test" : 499.97975293,
"test account" : 0.00000000,
"test label" : 0.48961280,
"test1" : 1.99900000
}
{% endhighlight %}
*See also*
* [GetAccount][rpc getaccount]: {{summary_getAccount}}
* [GetAddressesByAccount][rpc getaddressesbyaccount]: {{summary_getAddressesByAccount}}
* [ListReceivedByAccount][rpc listreceivedbyaccount]: {{summary_listReceivedByAccount}}
{% endautocrossref %}

84
_includes/devdoc/bitcoin-core/rpcs/rpcs/listaddressgroupings.md Normal file
View file

@ -0,0 +1,84 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/listaddressgroupings.md" %}
##### ListAddressGroupings
{% include helpers/subhead-links.md %}
{% assign summary_listAddressGroupings="lists groups of addresses that may have had their common ownership made public by common use as inputs in the same transaction or from being used as change from a previous transaction." %}
{% autocrossref %}
*Requires wallet support.*
The `listaddressgroupings` RPC {{summary_listAddressGroupings}}
*Parameters: none*
*Result---an array of arrays describing the groupings*
{% itemplate ntpd1 %}
- n: "`result`"
t: "array"
p: "Required<br>(exactly 1)"
d: "An array containing the groupings. May be empty"
- n: "→<br>Groupings"
t: "array"
p: "Optional<br>(0 or more)"
d: "An array containing arrays of addresses which can be associated with each other"
- n: "→ →<br>Address Details"
t: "array"
p: "Required<br>(1 or more)"
d: "An array containing information about a particular address"
- n: "→ → →<br>Address"
t: "string (base58)"
p: "Required<br>(exactly 1)"
d: "The address in base58check format"
- n: "→ → →<br>Balance"
t: "number (bitcoins)"
p: "Required<br>(exactly 1)"
d: "The current spendable balance of the address, not counting unconfirmed transactions"
- n: "→ → →<br>Account"
t: "string"
p: "Optional<br>(0 or 1)"
d: "The account the address belongs to, if any. This field will not be returned for change addresses. The default account is an empty string (\"\")"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet listaddressgroupings
{% endhighlight %}
Result (edited to only the first two results):
{% highlight json %}
[
[
[
"mgKgzJ7HR64CrB3zm1B4FUUCLtaSqUKfDb",
0.00000000
],
[
"mnUbTmdAFD5EAg3348Ejmonub7JcWtrMck",
0.00000000,
"test1"
]
]
]
{% endhighlight %}
*See also*
* [GetAddressesByAccount][rpc getaddressesbyaccount]: {{summary_getAddressesByAccount}}
* [GetTransaction][rpc gettransaction]: {{summary_getTransaction}}
{% endautocrossref %}

66
_includes/devdoc/bitcoin-core/rpcs/rpcs/listlockunspent.md Normal file
View file

@ -0,0 +1,66 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/listlockunspent.md" %}
##### ListLockUnspent
{% include helpers/subhead-links.md %}
{% assign summary_listLockUnspent="returns a list of temporarily unspendable (locked) outputs." %}
{% autocrossref %}
*Requires wallet support.*
The `listlockunspent` RPC {{summary_listLockUnspent}}
*Parameters: none*
*Result---an array of locked outputs*
{% itemplate ntpd1 %}
- n: "`result`"
t: "array"
p: "Required<br>(exactly 1)"
d: "An array containing all locked outputs. May be empty"
- n: "→<br>Output"
t: "object"
p: "Optional<br>(1 or more)"
d: "An object describing a particular locked output"
- n: "→ →<br>`txid`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The TXID of the transaction containing the locked output, encoded as hex in RPC byte order"
- n: "→ →<br>`vout`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The output index number (vout) of the locked output within the transaction. Output index `0` is the first output within the transaction"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet listlockunspent
{% endhighlight %}
Result:
{% highlight json %}
[
{
"txid" : "ca7cb6a5ffcc2f21036879493db4530c0ce9b5bff9648f9a3be46e2dfc8e0166",
"vout" : 0
}
]
{% endhighlight %}
*See also*
* [LockUnspent][rpc lockunspent]: {{summary_lockUnspent}}
{% endautocrossref %}

104
_includes/devdoc/bitcoin-core/rpcs/rpcs/listreceivedbyaccount.md Normal file
View file

@ -0,0 +1,104 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/listreceivedbyaccount.md" %}
##### ListReceivedByAccount
{% include helpers/subhead-links.md %}
{% assign summary_listReceivedByAccount="lists the total number of bitcoins received by each account." %}
{% autocrossref %}
*Requires wallet support.*
The `listreceivedbyaccount` RPC {{summary_listReceivedByAccount}}
*Parameter #1---the minimum number of confirmations a transaction must have to be counted*
{{INCLUDE_CONFIRMATIONS_PARAMETER}}
*Parameter #2---whether to include empty accounts*
{% itemplate ntpd1 %}
- n: "Include Empty"
t: "bool"
p: "Optional<br>(0 or 1)"
d: "Set to `true` to display accounts which have never received a payment. Set to `false` (the default) to only include accounts which have received a payment. Any account which has received a payment will be displayed even if its current balance is `0`"
{% enditemplate %}
*Parameter #3---whether to include watch-only addresses in results*
{{INCLUDE_INCLUDE_WATCH_ONLY_PARAMETER}}
*Result---account names, balances, and minimum confirmations*
{% itemplate ntpd1 %}
- n: "`result`"
t: "array"
p: "Required<br>(exactly 1)"
d: "An array containing objects each describing an account. At the very least, the default account (\"\") will be included"
- n: "→<br>Account"
t: "object"
p: "Required<br>(1 or more)"
d: "An object describing an account"
- n: "→ →<br>`involvesWatchonly`"
t: "bool"
p: "Optional<br>(0 or 1)"
d: "*Added in Bitcoin Core 0.10.0*<br><br>Set to `true` if the balance of this account includes a watch-only address which has received a spendable payment (that is, a payment with at least the specified number of confirmations and which is not an immature coinbase). Otherwise not returned"
- n: "→ →<br>`account`"
t: "string"
p: "Required<br>(exactly 1)"
d: "The name of the account"
- n: "→ →<br>`amount`<!--noref-->"
t: "number (bitcoins)"
p: "Required<br>(exactly 1)"
d: "The total amount received by this account in bitcoins"
- n: "→ →<br>`confirmations`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The number of confirmations received by the last transaction received by this account. May be `0`"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Get the balances for all non-empty accounts, including only transactions
which have been confirmed at least six times:
{% highlight bash %}
bitcoin-cli -testnet listreceivedbyaccount 6 false
{% endhighlight %}
Result (edited to only show the first two results):
{% highlight json %}
[
{
"account" : "",
"amount" : 0.19960000,
"confirmations" : 53601
},
{
"account" : "doc test",
"amount" : 0.30000000,
"confirmations" : 8991
}
]
{% endhighlight %}
*See also*
* [ListReceivedByAddress][rpc listreceivedbyaddress]: {{summary_listReceivedByAddress}}
* [GetReceivedByAccount][rpc getreceivedbyaccount]: {{summary_getReceivedByAccount}}
* [GetReceivedByAddress][rpc getreceivedbyaddress]: {{summary_getReceivedByAddress}}
{% endautocrossref %}

129
_includes/devdoc/bitcoin-core/rpcs/rpcs/listreceivedbyaddress.md Normal file
View file

@ -0,0 +1,129 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/listreceivedbyaddress.md" %}
##### ListReceivedByAddress
{% include helpers/subhead-links.md %}
{% assign summary_listReceivedByAddress="lists the total number of bitcoins received by each address." %}
{% autocrossref %}
*Requires wallet support.*
The `listreceivedbyaddress` RPC {{summary_listReceivedByAddress}}
*Parameter #1---the minimum number of confirmations a transaction must have to be counted*
{{INCLUDE_CONFIRMATIONS_PARAMETER}}
*Parameter #2---whether to include empty accounts*
{% itemplate ntpd1 %}
- n: "Include Empty"
t: "bool"
p: "Optional<br>(0 or 1)"
d: "Set to `true` to display accounts which have never received a payment. Set to `false` (the default) to only include accounts which have received a payment. Any account which has received a payment will be displayed even if its current balance is `0`"
{% enditemplate %}
*Parameter #3---whether to include watch-only addresses in results*
{{INCLUDE_INCLUDE_WATCH_ONLY_PARAMETER}}
*Result---addresses, account names, balances, and minimum confirmations*
{% itemplate ntpd1 %}
- n: "`result`"
t: "array"
p: "Required<br>(exactly 1)"
d: "An array containing objects each describing a particular address"
- n: "→<br>Address"
t: "object"
p: "Optional<br>(0 or more)"
d: "An object describing an address"
- n: "→ →<br>`involvesWatchonly`"
t: "bool"
p: "Optional<br>(0 or 1)"
d: "*Added in Bitcoin Core 0.10.0*<br><br>Set to `true` if this address is a watch-only address which has received a spendable payment (that is, a payment with at least the specified number of confirmations and which is not an immature coinbase). Otherwise not returned"
- n: "→ →<br>`address`"
t: "string (base58)"
p: "Required<br>(exactly 1)"
d: "The address being described encoded in base58check"
- n: "→ →<br>`account`"
t: "string"
p: "Required<br>(exactly 1)"
d: "The account the address belongs to; may be the default account, an empty string (\"\")"
- n: "→ →<br>`amount`"
t: "number (bitcoins)"
p: "Required<br>(exactly 1)"
d: "The total amount the address has received in bitcoins"
- n: "→ →<br>`confirmations`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The number of confirmations of the latest transaction to the address. May be `0` for unconfirmed"
- n: "→ →<br>TXIDs"
t: "array"
p: "Required<br>(exactly 1)"
d: "An array of TXIDs belonging to transactions that pay the address"
- n: "→ → →<br>TXID"
t: "string"
p: "Optional<br>(0 or more)"
d: "The TXID of a transaction paying the address, encoded as hex in RPC byte order"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
List addresses with balances confirmed by at least six blocks, including
watch-only addresses:
{% highlight bash %}
bitcoin-cli -testnet listreceivedbyaddress 6 false true
{% endhighlight %}
Result (edit to show only two entries):
{% highlight json %}
[
{
"address" : "mnUbTmdAFD5EAg3348Ejmonub7JcWtrMck",
"account" : "test1",
"amount" : 1.99900000,
"confirmations" : 55680,
"txids" : [
"4d71a6127796766c39270881c779b6e05183f2bf35589261e9572436356f287f",
"997115d0cf7b83ed332e6c1f2e8c44f803c95ea43490c84ce3e9ede4b2e1605f"
]
},
{
"involvesWatchonly" : true,
"address" : "n3GNqMveyvaPvUbH469vDRadqpJMPc84JA",
"account" : "someone else's address2",
"amount" : 0.00050000,
"confirmations" : 34714,
"txids" : [
"99845fd840ad2cc4d6f93fafb8b072d188821f55d9298772415175c456f3077d"
]
}
]
{% endhighlight %}
*See also*
* [ListReceivedByAccount][rpc listreceivedbyaccount]: {{summary_listReceivedByAccount}}
* [GetReceivedByAddress][rpc getreceivedbyaddress]: {{summary_getReceivedByAddress}}
* [GetReceivedByAccount][rpc getreceivedbyaccount]: {{summary_getReceivedByAccount}}
{% endautocrossref %}

132
_includes/devdoc/bitcoin-core/rpcs/rpcs/listsinceblock.md Normal file
View file

@ -0,0 +1,132 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/listsinceblock.md" %}
##### ListSinceBlock
{% include helpers/subhead-links.md %}
{% assign summary_listSinceBlock="gets all transactions affecting the wallet which have occurred since a particular block, plus the header hash of a block at a particular depth." %}
{% autocrossref %}
*Requires wallet support.*
The `listsinceblock` RPC {{summary_listSinceBlock}}
*Parameter #1---a block header hash*
{% itemplate ntpd1 %}
- n: "Header Hash"
t: "string (hex)"
p: "Optional<br>(0 or 1)"
d: "The hash of a block header encoded as hex in RPC byte order. All transactions affecting the wallet which are not in that block or any earlier block will be returned, including unconfirmed transactions. Default is the hash of the genesis block, so all transactions affecting the wallet are returned by default"
{% enditemplate %}
*Parameter #2---the target confirmations for the lastblock field*
{% itemplate ntpd1 %}
- n: "Target Confirmations"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "Sets the lastblock field of the results to the header hash of a block with this many confirmations. This does not affect which transactions are returned. Default is `1`, so the hash of the most recent block on the local best block chain is returned"
{% enditemplate %}
*Parameter #3---whether to include watch-only addresses in details and calculations*
{{INCLUDE_INCLUDE_WATCH_ONLY_PARAMETER}}
**Result**
{% assign DEPTH="→ → → " %}
{% include helpers/vars.md %}
{% itemplate ntpd1 %}
- n: "`result`"
t: "object"
p: "Required<br>(exactly 1)"
d: "An object containing an array of transactions and the lastblock field"
- n: "→<br>`transactions`"
t: "array"
p: "Required<br>(exactly 1)"
d: "An array of objects each describing a particular **payment** to or from this wallet. The objects in this array do not describe an actual transactions, so more than one object in this array may come from the same transaction. This array may be empty"
- n: "→ →<br>Payment"
t: "object"
p: "Optional<br>(0 or more)"
d: "An payment which did not appear in the specified block or an earlier block"
{{INCLUDE_F_LIST_TRANSACTIONS}}
{{INCLUDE_F_LIST_TRANSACTIONS_F_FULL}}
- n: "→<br>`lastblock`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The header hash of the block with the number of confirmations specified in the *target confirmations* parameter, encoded as hex in RPC byte order"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Get all transactions since a particular block (including watch-only
transactions) and the header hash of the sixth most recent block.
{% highlight bash %}
bitcoin-cli -testnet listsinceblock \
00000000688633a503f69818a70eac281302e9189b1bb57a76a05c329fcda718 \
6 true
{% endhighlight %}
Result (edited to show only two payments):
{% highlight json %}
{
"transactions" : [
{
"account" : "doc test",
"address" : "mmXgiR6KAhZCyQ8ndr2BCfEq1wNG2UnyG6",
"category" : "receive",
"amount" : 0.10000000,
"vout" : 0,
"confirmations" : 76478,
"blockhash" : "000000000017c84015f254498c62a7c884a51ccd75d4dd6dbdcb6434aa3bd44d",
"blockindex" : 1,
"blocktime" : 1399294967,
"txid" : "85a98fdf1529f7d5156483ad020a51b7f3340e47448cf932f470b72ff01a6821",
"walletconflicts" : [
],
"time" : 1399294967,
"timereceived" : 1418924714
},
{
"involvesWatchonly" : true,
"account" : "someone else's address2",
"address" : "n3GNqMveyvaPvUbH469vDRadqpJMPc84JA",
"category" : "receive",
"amount" : 0.00050000,
"vout" : 0,
"confirmations" : 34714,
"blockhash" : "00000000bd0ed80435fc9fe3269da69bb0730ebb454d0a29128a870ea1a37929",
"blockindex" : 11,
"blocktime" : 1411051649,
"txid" : "99845fd840ad2cc4d6f93fafb8b072d188821f55d9298772415175c456f3077d",
"walletconflicts" : [
],
"time" : 1418695703,
"timereceived" : 1418925580
}
],
"lastblock" : "0000000000984add1a686d513e66d25686572c7276ec3e358a7e3e9f7eb88619"
}
{% endhighlight %}
*See also*
* [ListReceivedByAccount][rpc listreceivedbyaccount]: {{summary_listReceivedByAccount}}
* [ListReceivedByAddress][rpc listreceivedbyaddress]: {{summary_listReceivedByAddress}}
{% endautocrossref %}

201
_includes/devdoc/bitcoin-core/rpcs/rpcs/listtransactions.md Normal file
View file

@ -0,0 +1,201 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/listtransactions.md" %}
##### ListTransactions
{% include helpers/subhead-links.md %}
{% assign summary_listTransactions="returns the most recent transactions that affect the wallet." %}
{% autocrossref %}
*Requires wallet support.*
The `listtransactions` RPC {{summary_listTransactions}}
*Parameter #1---an account name to get transactions from*
{% itemplate ntpd1 %}
- n: "Account"
t: "string"
p: "Optional<br>(0 or 1)"
d: "The name of an account to get transactinos from. Use an empty string (\"\") to get transactions for the default account. Default is `*` to get transactions for all accounts"
{% enditemplate %}
*Parameter #2---the number of transactions to get*
{% itemplate ntpd1 %}
- n: "Count"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "The number of the most recent transactions to list. Default is `10`"
{% enditemplate %}
*Parameter #3---the number of transactions to skip*
{% itemplate ntpd1 %}
- n: "Skip"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "The number of the most recent transactions which should not be returned. Allows for pagination of results. Default is `0`"
{% enditemplate %}
*Parameter #4---whether to include watch-only addresses in details and calculations*
{{INCLUDE_INCLUDE_WATCH_ONLY_PARAMETER}}
*Result---payment details*
{% itemplate ntpd1 %}
- n: "`result`"
t: "array"
p: "Required<br>(exactly 1)"
d: "An array containing objects, with each object describing a **payment** or internal accounting entry (not a transaction). More than one object in this array may come from a single transaction. Array may be empty"
- n: "→<br>Payment"
t: "object"
p: "Optional<br>(0 or more)"
d: "A payment or internal accounting entry"
- n: "→ →<br>`account`"
t: "string"
p: "Required<br>(exactly 1)"
d: "The account which the payment was credited to or debited from. May be an empty string (\"\") for the default account"
- n: "→ →<br>`address`"
t: "string (base58)"
p: "Optional<br>(0 or 1)"
d: "The address paid in this payment, which may be someone else's address not belonging to this wallet. May be empty if the address is unknown, such as when paying to a non-standard pubkey script or if this is in the *move* category"
- n: "→ →<br>`category`"
t: "string"
p: "Required<br>(exactly 1)"
d: "Set to one of the following values:<br>• `send` if sending payment<br>• `receive` if this wallet received payment in a regular transaction<br>• `generate` if a matured and spendable coinbase<br>• `immature` if a coinbase that is not spendable yet<br>• `orphan` if a coinbase from a block that's not in the local best block chain<br>• `move` if an off-block-chain move made with the `move` RPC"
- n: "→ →<br>`amount`"
t: "number (bitcoins)"
p: "Required<br>(exactly 1)"
d: "A negative bitcoin amount if sending payment; a positive bitcoin amount if receiving payment (including coinbases)"
- n: "→ →<br>`vout`"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "*Added in Bitcoin Core 0.10.0*<br><br>For an output, the output index (vout) for this output in this transaction. For an input, the output index for the output being spent in its transaction. Because inputs list the output indexes from previous transactions, more than one entry in the details array may have the same output index. Not returned for *move* category payments"
- n: "→ →<br>`fee`"
t: "number (bitcoins)"
p: "Optional<br>(0 or 1)"
d: "If sending payment, the fee paid as a negative bitcoins value. May be `0`. Not returned if receiving payment or for *move* category payments"
- n: "→ →<br>`confirmations`"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "The number of confirmations the transaction has received. Will be `0` for unconfirmed and `-1` for conflicted. Not returned for *move* category payments"
- n: "→ →<br>`generated`"
t: "bool"
p: "Optional<br>(0 or 1)"
d: "Set to `true` if the transaction is a coinbase. Not returned for regular transactions or *move* category payments"
- n: "→ →<br>`blockhash`"
t: "string (hex)"
p: "Optional<br>(0 or 1)"
d: "Only returned for confirmed transactions. The hash of the block on the local best block chain which includes this transaction, encoded as hex in RPC byte order"
- n: "→ →<br>`blockindex`"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "Only returned for confirmed transactions. The block height of the block on the local best block chain which includes this transaction"
- n: "→ →<br>`blocktime`"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "Only returned for confirmed transactions. The block header time (Unix epoch time) of the block on the local best block chain which includes this transaction"
- n: "→ →<br>`txid`"
t: "string (hex)"
p: "Optional<br>(0 or 1)"
d: "The TXID of the transaction, encoded as hex in RPC byte order. Not returned for *move* category payments"
- n: "→ →<br>`walletconflicts`"
t: "array"
p: "Optional<br>(0 or 1)"
d: "An array containing the TXIDs of other transactions that spend the same inputs (UTXOs) as this transaction. Array may be empty. Not returned for *move* category payments"
- n: "→ → →<br>TXID"
t: "string (hex)"
p: "Optional<br>(0 or more)"
d: "The TXID of a conflicting transaction, encoded as hex in RPC byte order"
- n: "→ →<br>`time`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "A Unix epoch time when the transaction was added to the wallet"
- n: "→ →<br>`timereceived`"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "A Unix epoch time when the transaction was detected by the local node, or the time of the block on the local best block chain that included the transaction. Not returned for *move* category payments"
- n: "→ →<br>`comment`"
t: "string"
p: "Optional<br>(0 or 1)"
d: "For transaction originating with this wallet, a locally-stored comment added to the transaction. Only returned in regular payments if a comment was added. Always returned in *move* category payments. May be an empty string"
- n: "→ →<br>`to`"
t: "string"
p: "Optional<br>(0 or 1)"
d: "For transaction originating with this wallet, a locally-stored comment added to the transaction identifying who the transaction was sent to. Only returned if a comment-to was added. Never returned by *move* category payments. May be an empty string"
- n: "→ →<br>`otheraccount`"
t: "string"
p: "Optional<br>(0 or 1)"
d: "Only returned by *move* category payments. This is the account the bitcoins were moved from or moved to, as indicated by a negative or positive *amount* field in this payment"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
List the most recent transaction from the account "someone else's
address2" including watch-only addresses.
{% highlight bash %}
bitcoin-cli -testnet listtransactions \
"someone else's address2" 1 0 true
{% endhighlight %}
Result:
{% highlight json %}
[
{
"involvesWatchonly" : true,
"account" : "someone else's address2",
"address" : "n3GNqMveyvaPvUbH469vDRadqpJMPc84JA",
"category" : "receive",
"amount" : 0.00050000,
"vout" : 0,
"confirmations" : 34714,
"blockhash" : "00000000bd0ed80435fc9fe3269da69bb0730ebb454d0a29128a870ea1a37929",
"blockindex" : 11,
"blocktime" : 1411051649,
"txid" : "99845fd840ad2cc4d6f93fafb8b072d188821f55d9298772415175c456f3077d",
"walletconflicts" : [
],
"time" : 1418695703,
"timereceived" : 1418925580
}
]
{% endhighlight %}
*See also*
* [GetTransaction][rpc gettransaction]: {{summary_getTransaction}}
* [ListSinceBlock][rpc listsinceblock]: {{summary_listSinceBlock}}
{% endautocrossref %}

150
_includes/devdoc/bitcoin-core/rpcs/rpcs/listunspent.md Normal file
View file

@ -0,0 +1,150 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/listunspent.md" %}
##### ListUnspent
{% include helpers/subhead-links.md %}
{% assign summary_listUnspent="returns an array of unspent transaction outputs belonging to this wallet." %}
{% autocrossref %}
*Requires wallet support.*
The `listunspent` RPC {{summary_listUnspent}} **Note:** as of Bitcoin
Core 0.10.0, outputs affecting watch-only addresses will be returned; see
the *spendable* field in the results described below.
*Parameter #1---the minimum number of confirmations an output must have*
{% itemplate ntpd1 %}
- n: "Minimum Confirmations"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "The minimum number of confirmations the transaction containing an output must have in order to be returned. Use `0` to return outputs from unconfirmed transactions. Default is `1`"
{% enditemplate %}
*Parameter #2---the maximum number of confirmations an output may have*
{% itemplate ntpd1 %}
- n: "Maximum Confirmations"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "The maximum number of confirmations the transaction containing an output may have in order to be returned. Default is `9999999` (~10 million)"
{% enditemplate %}
*Parameter #3---the addresses an output must pay*
{% itemplate ntpd1 %}
- n: "Addresses"
t: "array"
p: "Optional<br>(0 or 1)"
d: "If present, only outputs which pay an address in this array will be returned"
- n: "→<br>Address"
t: "string (base58)"
p: "Required<br>(1 or more)"
d: "A P2PKH or P2SH address"
{% enditemplate %}
*Result---the list of unspent outputs*
{% itemplate ntpd1 %}
- n: "`result`"
t: "array"
p: "Required<br>(exactly 1)"
d: "An array of objects each describing an unspent output. May be empty"
- n: "→<br>Unspent Output"
t: "object"
p: "Optional<br>(0 or more)"
d: "An object describing a particular unspent output belonging to this wallet"
- n: "→ →<br>`txid`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The TXID of the transaction containing the output, encoded as hex in RPC byte order"
- n: "→ →<br>`vout`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The output index number (vout) of the output within its containing transaction"
- n: "→ →<br>`address`"
t: "string (base58)"
p: "Optional<br>(0 or 1)"
d: "The P2PKH or P2SH address the output paid. Only returned for P2PKH or P2SH output scripts"
- n: "→ →<br>`account`"
t: "string"
p: "Optional<br>(0 or 1)"
d: "If the address returned belongs to an account, this is the account. Otherwise not returned"
- n: "→ →<br>`scriptPubKey`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The output script paid, encoded as hex"
- n: "→ →<br>`redeemScript`"
t: "string (hex)"
p: "Optional<br>(0 or 1)"
d: "If the output is a P2SH whose script belongs to this wallet, this is the redeem script"
- n: "→ →<br>`amount`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The amount paid to the output in bitcoins"
- n: "→ →<br>`confirmations`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The number of confirmations received for the transaction containing this output"
- n: "→ →<br>`spendable`"
t: "bool"
p: "Required<br>(exactly 1)"
d: "*Added in Bitcoin Core 0.10.0*<br><br>Set to `true` if the private key or keys needed to spend this output are part of the wallet. Set to `false` if not (such as for watch-only addresses)"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Get all outputs confirmed at least 6 times for a particular
address:
{% highlight bash %}
bitcoin-cli -testnet listunspent 6 99999999 '''
[
"mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe"
]
'''
{% endhighlight %}
Result:
{% highlight json %}
[
{
"txid" : "d54994ece1d11b19785c7248868696250ab195605b469632b7bd68130e880c9a",
"vout" : 1,
"address" : "mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe",
"account" : "test label",
"scriptPubKey" : "76a9140dfc8bafc8419853b34d5e072ad37d1a5159f58488ac",
"amount" : 0.00010000,
"confirmations" : 6210,
"spendable" : true
}
]
{% endhighlight %}
*See also*
* [ListTransactions][rpc listtransactions]: {{summary_listTransactions}}
* [LockUnspent][rpc lockunspent]: {{summary_lockUnspent}}
{% endautocrossref %}

150
_includes/devdoc/bitcoin-core/rpcs/rpcs/lockunspent.md Normal file
View file

@ -0,0 +1,150 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/lockunspent.md" %}
##### LockUnspent
{% include helpers/subhead-links.md %}
{% assign summary_lockUnspent="temporarily locks or unlocks specified transaction outputs. A locked transaction output will not be chosen by automatic coin selection when spending bitcoins. Locks are stored in memory only, so nodes start with zero locked outputs and the locked output list is always cleared when a node stops or fails." %}
{% autocrossref %}
*Requires wallet support.*
The `lockunspent` RPC {{summary_lockUnspent}}
*Parameter #1---whether to lock or unlock the outputs*
{% itemplate ntpd1 %}
- n: "Unlock"
t: "bool"
p: "Required<br>(exactly 1)"
d: "Set to `false` to lock the outputs specified in the following parameter. Set to `true` to unlock the outputs specified. If this is the only argument specified and it is set to `true`, all outputs will be unlocked; if it is the only argument and is set to `false`, there will be no change"
{% enditemplate %}
*Parameter #2---the outputs to lock or unlock*
{% itemplate ntpd1 %}
- n: "Outputs"
t: "array"
p: "Optional<br>(0 or 1)"
d: "An array of outputs to lock or unlock"
- n: "→<br>Output"
t: "object"
p: "Required<br>(1 or more)"
d: "An object describing a particular output"
- n: "→ →<br>`txid`"
t: "string"
p: "Required<br>(exactly 1)"
d: "The TXID of the transaction containing the output to lock or unlock, encoded as hex in internal byte order"
- n: "→ →<br>`vout`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The output index number (vout) of the output to lock or unlock. The first output in a transaction has an index of `0`"
{% enditemplate %}
*Result---`true` if successful*
{% itemplate ntpd1 %}
- n: "`result`"
t: "bool"
p: "Required<br>(exactly 1)"
d: "Set to `true` if the outputs were successfully locked or unlocked. If the outputs were already locked or unlocked, it will also return `true`"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Lock two outputs:
{% highlight bash %}
bitcoin-cli -testnet lockunspent false '''
[
{
"txid": "5a7d24cd665108c66b2d56146f244932edae4e2376b561b3d396d5ae017b9589",
"vout": 0
},
{
"txid": "6c5edd41a33f9839257358ba6ddece67df9db7f09c0db6bbea00d0372e8fe5cd",
"vout": 0
}
]
'''
{% endhighlight %}
Result:
{% highlight json %}
true
{% endhighlight %}
Verify the outputs have been locked:
{% highlight bash %}
bitcoin-cli -testnet listlockunspent
{% endhighlight %}
Result
{% highlight json %}
[
{
"txid": "5a7d24cd665108c66b2d56146f244932edae4e2376b561b3d396d5ae017b9589",
"vout": 0
},
{
"txid": "6c5edd41a33f9839257358ba6ddece67df9db7f09c0db6bbea00d0372e8fe5cd",
"vout": 0
}
]
{% endhighlight %}
Unlock one of the above outputs:
{% highlight bash %}
bitcoin-cli -testnet lockunspent true '''
[
{
"txid": "5a7d24cd665108c66b2d56146f244932edae4e2376b561b3d396d5ae017b9589",
"vout": 0
}
]
'''
{% endhighlight %}
Result:
{% highlight json %}
true
{% endhighlight %}
Verify the output has been unlocked:
{% highlight bash %}
bitcoin-cli -testnet listlockunspent
{% endhighlight %}
Result:
{% highlight json %}
[
{
"txid": "6c5edd41a33f9839257358ba6ddece67df9db7f09c0db6bbea00d0372e8fe5cd",
"vout": 0
}
]
{% endhighlight %}
*See also*
* [ListLockUnspent][rpc listlockunspent]: {{summary_listLockUnspent}}
* [ListUnspent][rpc listunspent]: {{summary_listUnspent}}
{% endautocrossref %}

104
_includes/devdoc/bitcoin-core/rpcs/rpcs/move.md Normal file
View file

@ -0,0 +1,104 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/move.md" %}
##### Move
{% include helpers/subhead-links.md %}
{% assign summary_move="moves a specified amount from one account in your wallet to another using an off-block-chain transaction." %}
{% autocrossref %}
*Requires wallet support.*
The `move` RPC {{summary_move}}
{{WARNING}} it's allowed to move more funds than are in an account,
giving the sending account a negative balance and giving the receiving
account a balance that may exceed the number of bitcoins in the wallet
(or the number of bitcoins in existence).
*Parameter #1---from account*
{% itemplate ntpd1 %}
- n: "From Account"
t: "string"
p: "Required<br>(exactly 1)"
d: "The name of the account to move the funds from"
{% enditemplate %}
*Parameter #2---to account*
{% itemplate ntpd1 %}
- n: "To Account"
t: "string"
p: "Required<br>(exactly 1)"
d: "The name of the account to move the funds to"
{% enditemplate %}
*Parameter #3---amount to move*
{% itemplate ntpd1 %}
- n: "Amount"
t: "number (bitcoins)"
p: "Required<br>(exactly 1)"
d: "The amount of bitcoins to move"
{% enditemplate %}
*Parameter #4---an unused parameter*
{% itemplate ntpd1 %}
- n: "*Unused*"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "This parameter is no longer used. If parameter #5 needs to be specified, this can be any integer"
{% enditemplate %}
*Parameter #5---a comment*
{% itemplate ntpd1 %}
- n: "Comment"
t: "string"
p: "Optional<br>(0 or 1)"
d: "A comment to assign to this move payment"
{% enditemplate %}
*Result---`true` on success*
{% itemplate ntpd1 %}
- n: "`result`"
t: "bool"
p: "Required<br>(exactly 1)"
d: "Set to `true` if the move was successful"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Move 0.1 bitcoins from "doc test" to "test1", giving the transaction the
comment "Example move":
{% highlight bash %}
bitcoin-cli -testnet move "doc test" "test1" 0.1 0 "Example move"
{% endhighlight %}
Result:
{% highlight json %}
true
{% endhighlight %}
*See also*
* [ListAccounts][rpc listaccounts]: {{summary_listAccounts}}
* [SendFrom][rpc sendfrom]: {{summary_sendFrom}}
* [SendToAddress][rpc sendtoaddress]: {{summary_sendToAddress}}
{% endautocrossref %}

61
_includes/devdoc/bitcoin-core/rpcs/rpcs/ping.md Normal file
View file

@ -0,0 +1,61 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/ping.md" %}
##### Ping {#ping-rpc}
{% include helpers/subhead-links.md %}
{% 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." %}
{% autocrossref %}
The `ping` RPC {{summary_ping-rpc}}
*Parameters: none*
*Result---`null`*
{% itemplate ntpd1 %}
- n: "`result`"
t: "null"
p: "Required"
d: "Always JSON `null`"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet ping
{% endhighlight %}
(Success: no result printed.)
Get the results using the `getpeerinfo` RPC:
{% highlight bash %}
bitcoin-cli -testnet getpeerinfo | grep ping
{% endhighlight %}
Results:
{% highlight json %}
"pingtime" : 0.11790800,
"pingtime" : 0.22673400,
"pingtime" : 0.16451900,
"pingtime" : 0.12465200,
"pingtime" : 0.13267900,
"pingtime" : 0.23983300,
"pingtime" : 0.16764700,
"pingtime" : 0.11337300,
{% endhighlight %}
*See also*
* [GetPeerInfo][rpc getpeerinfo]: {{summary_getPeerInfo}}
* [P2P Ping Message][ping message]
{% endautocrossref %}

77
_includes/devdoc/bitcoin-core/rpcs/rpcs/prioritisetransaction.md Normal file
View file

@ -0,0 +1,77 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/prioritisetransaction.md" %}
##### PrioritiseTransaction
{% include helpers/subhead-links.md %}
{% 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.)" %}
{% autocrossref %}
*Added in Bitcoin Core 0.10.0.*
The `prioritisetransaction` RPC {{summary_prioritiseTransaction}}
*Parameter #1---the TXID of the transaction to modify*
{% itemplate ntpd1 %}
- n: "TXID"
t: "string"
p: "Required<br>(exactly 1)"
d: "The TXID of the transaction whose virtual priority or fee you want to modify, encoded as hex in RPC byte order"
{% enditemplate %}
*Parameter #2---the change to make to the virtual priority*
{% itemplate ntpd1 %}
- n: "Priority"
t: "number (real)"
p: "Required<br>(exactly 1)"
d: "If positive, the priority to add to the transaction in addition to its computed priority; if negative, the priority to subtract from the transaction's computed priory. Computed priority is the age of each input in days since it was added to the block chain as an output (coinage) times the value of the input in satoshis (value) divided by the size of the serialized transaction (size), which is `coinage * value / size`"
{% enditemplate %}
*Parameter #3---the change to make to the virtual fee*
{% itemplate ntpd1 %}
- n: "Fee"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "**Warning:** this value is in satoshis, not bitcoins<br><br>If positive, the virtual fee to add to the actual fee paid by the transaction; if negative, the virtual fee to subtract from the actual fee paid by the transaction. No change is made to the actual fee paid by the transaction"
{% enditemplate %}
*Result---`true` if the priority is changed*
{% itemplate ntpd1 %}
- n: "`result`"
t: "bool (true only)"
p: "Required<br>(exactly 1)"
d: "Always set to `true` if all three parameters are provided. Will not return an error if the TXID is not in the memory pool. If fewer or more than three arguments are provided, or if something goes wrong, will be set to `null`"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet prioritisetransaction \
fe0165147da737e16f5096ab6c1709825217377a95a882023ed089a89af4cff9 \
1234 456789
{% endhighlight %}
Result:
{% highlight json %}
true
{% endhighlight %}
*See also*
* [GetRawMemPool][rpc getrawmempool]: {{summary_getRawMemPool}}
* [GetBlockTemplate][rpc getblocktemplate]: {{summary_getBlockTemplate}}
{% endautocrossref %}

112
_includes/devdoc/bitcoin-core/rpcs/rpcs/sendfrom.md Normal file
View file

@ -0,0 +1,112 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/sendfrom.md" %}
##### SendFrom
{% include helpers/subhead-links.md %}
{% assign summary_sendFrom="spends an amount from a local account to a bitcoin address." %}
{% autocrossref %}
*Requires wallet support. Requires an unlocked wallet or an
unencrypted wallet.*
The `sendfrom` RPC {{summary_sendFrom}}
*Parameter #1---from account*
{% itemplate ntpd1 %}
- n: "From Account"
t: "string"
p: "Required<br>(exactly 1)"
d: "The name of the account from which the bitcoins should be spent. Use an empty string (\"\") for the default account"
{% enditemplate %}
*Parameter #2---to address*
{% itemplate ntpd1 %}
- n: "To Address"
t: "string"
p: "Required<br>(exactly 1)"
d: "A P2PKH or P2SH address to which the bitcoins should be sent"
{% enditemplate %}
*Parameter #3---amount to spend*
{% itemplate ntpd1 %}
- n: "Amount"
t: "number (bitcoins)"
p: "Required<br>(exactly 1)"
d: "The amount to spend in bitcoins. Bitcoin Core will ensure the account has sufficient bitcoins to pay this amount (but the transaction fee paid is not included in the calculation, so an account can spend a total of its balance plus the transaction fee)"
{% enditemplate %}
*Parameter #4---minimum confirmations*
{{INCLUDE_SPEND_CONFIRMATIONS}}
*Parameter #5---a comment*
{% itemplate ntpd1 %}
- n: "Comment"
t: "string"
p: "Optional<br>(0 or 1)"
d: "A locally-stored (not broadcast) comment assigned to this transaction. Default is no comment"
{% enditemplate %}
*Parameter #6---a comment about who the payment was sent to*
{% itemplate ntpd1 %}
- n: "Comment To"
t: "string"
p: "Optional<br>(0 or 1)"
d: "A locally-stored (not broadcast) comment assigned to this transaction. Meant to be used for describing who the payment was sent to. Default is no comment"
{% enditemplate %}
*Result---a TXID of the sent transaction*
{% itemplate ntpd1 %}
- n: "`result`"
t: "string"
p: "Required<br>(exactly 1)"
d: "The TXID of the sent transaction, encoded as hex in RPC byte order"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Spend 0.1 bitcoins from the account "test" to the address indicated below
using only UTXOs with at least six confirmations, giving the
transaction the comment "Example spend" and labeling the spender
"Example.com":
{% highlight bash %}
bitcoin-cli -testnet sendfrom "test" \
mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe \
0.1 \
6 \
"Example spend" \
"Example.com"
{% endhighlight %}
Result:
{% highlight text %}
f14ee5368c339644d3037d929bbe1f1544a532f8826c7b7288cb994b0b0ff5d8
{% endhighlight %}
*See also*
* [SendToAddress][rpc sendtoaddress]: {{summary_sendToAddress}}
* [SendMany][rpc sendmany]: {{summary_sendMany}}
{% endautocrossref %}

97
_includes/devdoc/bitcoin-core/rpcs/rpcs/sendmany.md Normal file
View file

@ -0,0 +1,97 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/sendmany.md" %}
##### SendMany
{% include helpers/subhead-links.md %}
{% assign summary_sendMany="creates and broadcasts a transaction which sends outputs to multiple addresses." %}
{% autocrossref %}
*Requires wallet support. Requires an unlocked wallet or an
unencrypted wallet.*
The `sendmany` RPC {{summary_sendMany}}
*Parameter #1---from account*
{% itemplate ntpd1 %}
- n: "From Account"
t: "string"
p: "Required<br>(exactly 1)"
d: "The name of the account from which the bitcoins should be spent. Use an empty string (\"\") for the default account. Bitcoin Core will ensure the account has sufficient bitcoins to pay the total amount in the *outputs* field described below (but the transaction fee paid is not included in the calculation, so an account can spend a total of its balance plus the transaction fee)"
{% enditemplate %}
*Parameter #2---the addresses and amounts to pay*
{% itemplate ntpd1 %}
- n: "Outputs"
t: "object"
p: "Required<br>(exactly 1)"
d: "An object containing key/value pairs corresponding to the addresses and amounts to pay"
- n: "→<br>Address/Amount"
t: "string (base58) : number (bitcoins)"
p: "Required<br>(1 or more)"
d: "A key/value pair with a base58check-encoded string containing the P2PKH or P2SH address to pay as the key, and an amount of bitcoins to pay as the value"
{% enditemplate %}
*Parameter #3---minimum confirmations*
{{INCLUDE_SPEND_CONFIRMATIONS}}
*Parameter #4---a comment*
{% itemplate ntpd1 %}
- n: "Comment"
t: "string"
p: "Optional<br>(0 or 1)"
d: "A locally-stored (not broadcast) comment assigned to this transaction. Default is no comment"
{% enditemplate %}
*Result---a TXID of the sent transaction*
{% itemplate ntpd1 %}
- n: "`result`"
t: "string"
p: "Required<br>(exactly 1)"
d: "The TXID of the sent transaction, encoded as hex in RPC byte order"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
From the account *test1*, send 0.1 bitcoins to the first address and 0.2
bitcoins to the second address, with a comment of "Example Transaction".
{% highlight bash %}
bitcoin-cli -testnet sendmany \
"test1" \
'''
{
"mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN": 0.1,
"mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe": 0.2
} ''' \
6 \
"Example Transaction"
{% endhighlight %}
Result:
{% highlight text %}
ec259ab74ddff199e61caa67a26e29b13b5688dc60f509ce0df4d044e8f4d63d
{% endhighlight %}
*See also*
* [SendFrom][rpc sendfrom]: {{summary_sendFrom}}
* [SendToAddress][rpc sendtoaddress]: {{summary_sendToAddress}}
* [Move][rpc move]: {{summary_move}}
{% endautocrossref %}

72
_includes/devdoc/bitcoin-core/rpcs/rpcs/sendrawtransaction.md Normal file
View file

@ -0,0 +1,72 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/sendrawtransaction.md" %}
##### SendRawTransaction
{% include helpers/subhead-links.md %}
{% assign summary_sendRawTransaction="validates a transaction and broadcasts it to the peer-to-peer network." %}
{% autocrossref %}
The `sendrawtransaction` RPC {{summary_sendRawTransaction}}
*Parameter #1---a serialized transaction to broadcast*
{% itemplate ntpd1 %}
- n: "Transaction"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The serialized transaction to broadcast encoded as hex"
{% enditemplate %}
*Parameter #2--whether to allow high fees**
{% itemplate ntpd1 %}
- n: "Allow High Fees"
t: "bool"
p: "Optional<br>(0 or 1)"
d: "Set to `true` to allow the transaction to pay a high transaction fee. Set to `false` (the default) to prevent Bitcoin Core from broadcasting the transaction if it includes a high fee. Transaction fees are the sum of the inputs minus the sum of the outputs, so this high fees check helps ensures user including a change address to return most of the difference back to themselves"
{% enditemplate %}
*Result---a TXID or error message*
{% itemplate ntpd1 %}
- n: "`result`"
t: "null/string (hex)"
p: "Required<br>(exactly 1)"
d: "If the transaction was accepted by the node for broadcast, this will be the TXID of the transaction encoded as hex in RPC byte order. If the transaction was rejected by the node, this will set to `null`, the JSON-RPC error field will be set to a code, and the JSON-RPC message field may contain an informative error message"
{% enditemplate %}
*Examples from Bitcoin Core 0.10.0*
Broadcast a signed transaction:
{% highlight bash %}
bitcoin-cli -testnet sendrawtransaction 01000000011da9283b4ddf8d\
89eb996988b89ead56cecdc44041ab38bf787f1206cd90b51e000000006a4730\
4402200ebea9f630f3ee35fa467ffc234592c79538ecd6eb1c9199eb23c4a16a\
0485a20220172ecaf6975902584987d295b8dddf8f46ec32ca19122510e22405\
ba52d1f13201210256d16d76a49e6c8e2edc1c265d600ec1a64a45153d45c29a\
2fd0228c24c3a524ffffffff01405dc600000000001976a9140dfc8bafc84198\
53b34d5e072ad37d1a5159f58488ac00000000
{% endhighlight %}
Result:
{% highlight text %}
f5a5ce5988cc72b9b90e8d1d6c910cda53c88d2175177357cc2f2cf0899fbaad
{% endhighlight %}
*See also*
* [CreateRawTransaction][rpc createrawtransaction]: {{summary_createRawTransaction}}
* [DecodeRawTransaction][rpc decoderawtransaction]: {{summary_decodeRawTransaction}}
* [SignRawTransaction][rpc signrawtransaction]: {{summary_signRawTransaction}}
{% endautocrossref %}

92
_includes/devdoc/bitcoin-core/rpcs/rpcs/sendtoaddress.md Normal file
View file

@ -0,0 +1,92 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/sendtoaddress.md" %}
##### SendToAddress
{% include helpers/subhead-links.md %}
{% assign summary_sendToAddress="spends an amount to a given address." %}
{% autocrossref %}
*Requires wallet support. Requires an unlocked wallet or an
unencrypted wallet.*
The `sendtoaddress` RPC {{summary_sendToAddress}}
*Parameter #1---to address*
{% itemplate ntpd1 %}
- n: "To Address"
t: "string"
p: "Required<br>(exactly 1)"
d: "A P2PKH or P2SH address to which the bitcoins should be sent"
{% enditemplate %}
*Parameter #2---amount to spend*
{% itemplate ntpd1 %}
- n: "Amount"
t: "number (bitcoins)"
p: "Required<br>(exactly 1)"
d: "The amount to spent in bitcoins"
{% enditemplate %}
*Parameter #3---a comment*
{% itemplate ntpd1 %}
- n: "Comment"
t: "string"
p: "Optional<br>(0 or 1)"
d: "A locally-stored (not broadcast) comment assigned to this transaction. Default is no comment"
{% enditemplate %}
*Parameter #4---a comment about who the payment was sent to*
{% itemplate ntpd1 %}
- n: "Comment To"
t: "string"
p: "Optional<br>(0 or 1)"
d: "A locally-stored (not broadcast) comment assigned to this transaction. Meant to be used for describing who the payment was sent to. Default is no comment"
{% enditemplate %}
*Result---a TXID of the sent transaction*
{% itemplate ntpd1 %}
- n: "`result`"
t: "string"
p: "Required<br>(exactly 1)"
d: "The TXID of the sent transaction, encoded as hex in RPC byte order"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Spend 0.1 bitcoins to the address below with the comment "sendtoadress
example" and the comment-to "Nemo From Example.com":
{% highlight bash %}
bitcoin-cli -testnet sendtoaddress mmXgiR6KAhZCyQ8ndr2BCfEq1wNG2UnyG6 \
0.1 "sendtoaddress example" "Nemo From Example.com"
{% endhighlight %}
Result:
{% highlight text %}
a2a2eb18cb051b5fe896a32b1cb20b179d981554b6bd7c5a956e56a0eecb04f0
{% endhighlight %}
*See also*
* [SendFrom][rpc sendfrom]: {{summary_sendFrom}}
* [SendMany][rpc sendmany]: {{summary_sendMany}}
* [Move][rpc move]: {{summary_move}}
{% endautocrossref %}

65
_includes/devdoc/bitcoin-core/rpcs/rpcs/setaccount.md Normal file
View file

@ -0,0 +1,65 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/setaccount.md" %}
##### SetAccount
{% include helpers/subhead-links.md %}
{% assign summary_setAccount="puts the specified address in the given account." %}
{% autocrossref %}
*Requires wallet support.*
The `setaccount` RPC {{summary_setAccount}}
*Parameter #1---a bitcoin address*
{% itemplate ntpd1 %}
- n: "Address"
t: "string (base58)"
p: "Required<br>(exactly 1)"
d: "The P2PKH or P2SH address to put in the account. Must already belong to the wallet"
{% enditemplate %}
*Parameter #2---an account*
{% itemplate ntpd1 %}
- n: "Account"
t: "string"
p: "Required<br>(exactly 1)"
d: "The name of the account in which the address should be placed. May be the default account, an empty string (\"\")"
{% enditemplate %}
*Result---`null` if successful*
{% itemplate ntpd1 %}
- n: "`result`"
t: "null"
p: "Required<br>(exactly 1)"
d: "Set to JSON `null` if the address was successfully placed in the account"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Put the address indicated below in the "doc test" account.
{% highlight bash %}
bitcoin-cli -testnet setaccount \
mmXgiR6KAhZCyQ8ndr2BCfEq1wNG2UnyG6 "doc test"
{% endhighlight %}
(Success: no result displayed.)
*See also*
* [GetAccount][rpc getaccount]: {{summary_getAccount}}
* [ListAccounts][rpc listaccounts]: {{summary_listAccounts}}
* [GetAddressesByAccount][rpc getaddressesbyaccount]: {{summary_getAddressesByAccount}}
{% endautocrossref %}

109
_includes/devdoc/bitcoin-core/rpcs/rpcs/setgenerate.md Normal file
View file

@ -0,0 +1,109 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/setgenerate.md" %}
##### SetGenerate
{% include helpers/subhead-links.md %}
{% assign summary_setGenerate="enables or disables hashing to attempt to find the next block." %}
{% autocrossref %}
*Requires wallet support.*
The `setgenerate` RPC {{summary_setGenerate}}
*Parameter #1---whether to enable or disable generation*
{% itemplate ntpd1 %}
- n: "Enable/Disable"
t: "bool"
p: "Required<br>(exactly 1)"
d: "Set to `true` to enable generation; set to `false` to disable generation"
{% enditemplate %}
*Parameter #2 (regular)---the number of processors to use*
{% itemplate ntpd1 %}
- n: "Processors"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "The number of processors to use. Defaults to `1`. Set to `-1` to use all processors"
{% enditemplate %}
*Parameter #2 (regtest)---the number of blocks to generate*
Note: setgenerate in regtest mode has been removed in Bitcoin Core
master. See the `generate` RPC for the replacement.
{% itemplate ntpd1 %}
- n: "Blocks"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "In regtest mode, set to the number of blocks to generate. Defaults to `1`"
{% enditemplate %}
*Result (regular)---generating is enabled*
{% itemplate ntpd1 %}
- n: "`result`"
t: "null"
p: "Required<br>(exactly 1)"
d: "Always JSON `null`"
{% enditemplate %}
*Result (regtest)---the generated block header hashes*
{% itemplate ntpd1 %}
- n: "`result`"
t: "array/null"
p: "Required<br>(exactly 1)"
d: "An array containing the block header hashes of the generated blocks, or JSON `null` if no blocks were generated"
- n: "→<br>Header Hashes"
t: "string (hex)"
p: "Required<br>(1 or more)"
d: "The hashes of the headers of the blocks generated in regtest mode, as hex in RPC byte order"
{% enditemplate %}
*Examples from Bitcoin Core 0.10.0*
Enable generation using two logical processors (on this machine, two
cores of one physical processor):
{% highlight bash %}
bitcoin-cli -testnet setgenerate true 2
{% endhighlight %}
(Success: no result displayed. Process manager shows 200% CPU usage.)
Using regtest mode, generate 2 blocks:
{% highlight bash %}
bitcoin-cli -regtest setgenerate true 101
{% endhighlight %}
Result:
{% highlight json %}
[
"7e38de938d0dcbb41be63d78a8353e77e9d1b3ef82e0368eda051d4926eef915",
"61d6e5f1a64d009659f45ef1c614e57f4aa0501708641212be236dc56d726da8"
]
{% endhighlight %}
*See also*
* [GetGenerate][rpc getgenerate]: {{summary_getGenerate}}
* [GetHashesPerSec][rpc gethashespersec]: {{summary_getHashesPerSec}}
* [GetMiningInfo][rpc getmininginfo]: {{summary_getMiningInfo}}
* [GetBlockTemplate][rpc getblocktemplate]: {{summary_getBlockTemplate}}
{% endautocrossref %}

57
_includes/devdoc/bitcoin-core/rpcs/rpcs/settxfee.md Normal file
View file

@ -0,0 +1,57 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/settxfee.md" %}
##### SetTxFee
{% include helpers/subhead-links.md %}
{% assign summary_setTxFee="sets the transaction fee per kilobyte paid by transactions created by this wallet." %}
{% autocrossref %}
*Requires wallet support.*
The `settxfee` RPC {{summary_setTxFee}}
*Parameter #1---the transaction fee amount per kilobyte*
{% itemplate ntpd1 %}
- n: "Transaction Fee Per Kilobyte"
t: "number (bitcoins)"
p: "Required<br>(exactly 1)"
d: "The transaction fee to pay, in bitcoins, for each kilobyte of transaction data. Be careful setting the fee too low---your transactions may not be relayed or included in blocks"
{% enditemplate %}
*Result: `true` on success*
{% itemplate ntpd1 %}
- n: "`result`"
t: "bool (true)"
p: "Required<br>(exactly 1)"
d: "Set to `true` if the fee was successfully set"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Set the transaction fee per kilobyte to 100,000 satoshis.
{% highlight bash %}
bitcoin-cli -testnet settxfee 0.00100000
{% endhighlight %}
Result:
{% highlight json %}
true
{% endhighlight %}
*See also*
* [GetWalletInfo][rpc getwalletinfo]: {{summary_getWalletInfo}}
* [GetNetworkInfo][rpc getnetworkinfo]: {{summary_getNetworkInfo}}
{% endautocrossref %}

68
_includes/devdoc/bitcoin-core/rpcs/rpcs/signmessage.md Normal file
View file

@ -0,0 +1,68 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/signmessage.md" %}
##### SignMessage
{% include helpers/subhead-links.md %}
{% assign summary_signMessage="signs a message with the private key of an address." %}
{% autocrossref %}
*Requires wallet support. Requires an unlocked wallet or an
unencrypted wallet.*
The `signmessage` RPC {{summary_signMessage}}
*Parameter #1---the address corresponding to the private key to sign with*
{% itemplate ntpd1 %}
- n: "Address"
t: "string (base58)"
p: "Required<br>(exactly 1)"
d: "A P2PKH address whose private key belongs to this wallet"
{% enditemplate %}
*Parameter #2---the message to sign*
{% itemplate ntpd1 %}
- n: "Message"
t: "string"
p: "Required<br>(exactly 1)"
d: "The message to sign"
{% enditemplate %}
*Result---the message signature*
{% itemplate ntpd1 %}
- n: "`result`"
t: "string (base64)"
p: "Required<br>(exactly 1)"
d: "The signature of the message, encoded in base64. Note that Bitcoin Core before 0.10.0 creates signatures with random *k* values, so each time you sign the same message, it will create a different signature"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Sign a the message "Hello, World!" using the following address:
{% highlight bash %}
bitcoin-cli -testnet signmessage mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe \
'Hello, World!'
{% endhighlight %}
Result:
{% highlight text %}
IL98ziCmwYi5pL+dqKp4Ux+zCa4hP/xbjHmWh+Mk/lefV/0pWV1p/gQ94jgExSmgH2/+PDcCCrOHAady2IEySSI=
{% endhighlight %}
*See also*
* [VerifyMessage][rpc verifymessage]: {{summary_verifyMessage}}
{% endautocrossref %}

133
_includes/devdoc/bitcoin-core/rpcs/rpcs/signrawtransaction.md Normal file
View file

@ -0,0 +1,133 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/signrawtransaction.md" %}
##### SignRawTransaction
{% include helpers/subhead-links.md %}
{% assign summary_signRawTransaction="signs a transaction in the serialized transaction format using private keys stored in the wallet or provided in the call." %}
{% autocrossref %}
The `signrawtransaction` RPC {{summary_signRawTransaction}}
*Parameter #1---the transaction to sign*
{% itemplate ntpd1 %}
- n: "Transaction"
t: "string (hex"
p: "Required<br>(exactly 1)"
d: "The transaction to sign as a serialized transaction"
{% enditemplate %}
*Parameter #2---unspent transaction output details*
{% itemplate ntpd1 %}
- n: "Dependencies"
t: "array"
p: "Optional<br>(0 or 1)"
d: "The previous outputs being spent by this transaction"
- n: "→<br>Output"
t: "object"
p: "Optional<br>(0 or more)"
d: "An output being spent"
- n: "→ →<br>`txid`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The TXID of the transaction the output appeared in. The TXID must be encoded in hex in RPC byte order"
- n: "→ →<br>`vout`"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The index number of the output (vout) as it appeared in its transaction, with the first output being 0"
- n: "→ →<br>`scriptPubKey`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The output's pubkey script encoded as hex"
- n: "→ →<br>`redeemScript`"
t: "string (hex)"
p: "Optional<br>(0 or 1)"
d: "If the pubkey script was a script hash, this must be the corresponding redeem script"
{% enditemplate %}
*Parameter #3---private keys for signing*
{% itemplate ntpd1 %}
- n: "Private Keys"
t: "array"
p: "Optional<br>(0 or 1)"
d: "An array holding private keys. If any keys are provided, only they will be used to sign the transaction (even if the wallet has other matching keys). If this array is empty or not used, and wallet support is enabled, keys from the wallet will be used"
- n: "→<br>Key"
t: "string (base58)"
p: "Required<br>(1 or more)"
d: "A private key in base58check format to use to create a signature for this transaction"
{% enditemplate %}
*Parameter #4---signature hash type*
{% itemplate ntpd1 %}
- n: "SigHash"
t: "string"
p: "Optional<br>(0 or 1)"
d: "The type of signature hash to use for all of the signatures performed. (You must use separate calls to the `signrawtransaction` RPC if you want to use different signature hash types for different signatures. The allowed values are: `ALL`, `NONE`, `SINGLE`, `ALL|ANYONECANPAY`, `NONE|ANYONECANPAY`, and `SINGLE|ANYONECANPAY`"
{% enditemplate %}
*Result---the transaction with any signatures made*
{% itemplate ntpd1 %}
- n: "`result`"
t: "object"
p: "Required<br>(exactly 1)"
d: "The results of the signature"
- n: "→<br>`hex`"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The resulting serialized transaction encoded as hex with any signatures made inserted. If no signatures were made, this will be the same transaction provided in parameter #1"
- n: "→<br>`complete`"
t: "bool"
p: "Required<br>(exactly 1)"
d: "The value `true` if transaction is fully signed; the value `false` if more signatures are required"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Sign the hex generated in the example section for the `createrawtransaction`
RPC:
{% highlight bash %}
bitcoin-cli -testnet signrawtransaction 01000000011da9283b4ddf8d\
89eb996988b89ead56cecdc44041ab38bf787f1206cd90b51e0000000000ffff\
ffff01405dc600000000001976a9140dfc8bafc8419853b34d5e072ad37d1a51\
59f58488ac00000000
{% endhighlight %}
Result:
{% highlight json %}
{
"hex" : "01000000011da9283b4ddf8d89eb996988b89ead56cecdc44041ab38bf787f1206cd90b51e000000006a47304402200ebea9f630f3ee35fa467ffc234592c79538ecd6eb1c9199eb23c4a16a0485a20220172ecaf6975902584987d295b8dddf8f46ec32ca19122510e22405ba52d1f13201210256d16d76a49e6c8e2edc1c265d600ec1a64a45153d45c29a2fd0228c24c3a524ffffffff01405dc600000000001976a9140dfc8bafc8419853b34d5e072ad37d1a5159f58488ac00000000",
"complete" : true
}
{% endhighlight %}
*See also*
* [CreateRawTransaction][rpc createrawtransaction]: {{summary_createRawTransaction}}
* [DecodeRawTransaction][rpc decoderawtransaction]: {{summary_decodeRawTransaction}}
* [SendRawTransaction][rpc sendrawtransaction]: {{summary_sendRawTransaction}}
{% endautocrossref %}

42
_includes/devdoc/bitcoin-core/rpcs/rpcs/stop.md Normal file
View file

@ -0,0 +1,42 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/stop.md" %}
##### Stop
{% include helpers/subhead-links.md %}
{% assign summary_stop="safely shuts down the Bitcoin Core server." %}
{% autocrossref %}
The `stop` RPC {{summary_stop}}
*Parameters: none*
*Result---the server is safely shut down*
{% itemplate ntpd1 %}
- n: "`result`"
t: "string"
p: "Required<br>(exactly 1)"
d: "The string \"Bitcoin server stopping\""
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet stop
{% endhighlight %}
Result:
{% highlight text %}
Bitcoin server stopping
{% endhighlight %}
*See also: none*
{% endautocrossref %}

71
_includes/devdoc/bitcoin-core/rpcs/rpcs/submitblock.md Normal file
View file

@ -0,0 +1,71 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/submitblock.md" %}
##### SubmitBlock
{% include helpers/subhead-links.md %}
{% assign summary_submitBlock="accepts a block, verifies it is a valid addition to the block chain, and broadcasts it to the network. Extra parameters are ignored by Bitcoin Core but may be used by mining pools or other programs." %}
{% autocrossref %}
The `submitblock` RPC {{summary_submitBlock}}
*Parameter #1---the new block in serialized block format as hex*
{% itemplate ntpd1 %}
- n: "Block"
t: "string (hex)"
p: "Required<br>(exactly 1)"
d: "The full block to submit in serialized block format as hex"
{% enditemplate %}
*Parameter #2---additional parameters*
{% itemplate ntpd1 %}
- n: "Parameters"
t: "object"
p: "Optional<br>(0 or 1)"
d: "A JSON object containing extra parameters. Not used directly by Bitcoin Core and also not broadcast to the network. This is available for use by mining pools and other software. A common parameter is a `workid` string"
{% enditemplate %}
*Result---`null` or error string*
{% itemplate ntpd1 %}
- n: "`result`"
t: "null/string"
p: "Required<br>(exactly 1)"
d: "If the block submission succeeded, set to JSON `null`. If submission failed, set to one of the following strings: `duplicate`, `duplicate-invalid`, `inconclusive`, or `rejected`. The JSON-RPC `error` field will still be set to `null` if submission failed for one of these reasons"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Submit the following block with the workid, "test".
{% highlight bash %}
bitcoin-cli -testnet submitblock 02000000df11c014a8d798395b5059c\
722ebdf3171a4217ead71bf6e0e99f4c7000000004a6f6a2db225c81e77773f6\
f0457bcb05865a94900ed11356d0b75228efb38c7785d6053ffff001d005d437\
0010100000001000000000000000000000000000000000000000000000000000\
0000000000000ffffffff0d03b477030164062f503253482fffffffff0100f90\
29500000000232103adb7d8ef6b63de74313e0cd4e07670d09a169b13e4eda2d\
650f529332c47646dac00000000 \
'{ "workid": "test" }'
{% endhighlight %}
Result (the block above was already on a local block chain):
{% highlight text %}
duplicate
{% endhighlight %}
*See also*
* [GetBlockTemplate][rpc getblocktemplate]: {{summary_getBlockTemplate}}
{% endautocrossref %}

156
_includes/devdoc/bitcoin-core/rpcs/rpcs/validateaddress.md Normal file
View file

@ -0,0 +1,156 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/validateaddress.md" %}
##### ValidateAddress
{% include helpers/subhead-links.md %}
{% assign summary_validateAddress="returns information about the given Bitcoin address." %}
{% autocrossref %}
The `validateaddress` RPC {{summary_validateAddress}}
*Parameter #1---a P2PKH or P2SH address*
{% itemplate ntpd1 %}
- n: "Address"
t: "string (base58)"
p: "Required<br>(exactly 1)"
d: "The P2PKH or P2SH address to validate encoded in base58check format"
{% enditemplate %}
*Result---information about the address*
{% itemplate ntpd1 %}
- n: "`result`"
t: "object"
p: "Required<br>(exactly 1)"
d: "Information about the address"
- n: "→<br>`isvalid`"
t: "bool"
p: "Required<br>(exactly 1)"
d: "Set to `true` if the address is a valid P2PKH or P2SH address; set to `false` otherwise"
- n: "→<br>`address`"
t: "string (base58)"
p: "Optional<br>(0 or 1)"
d: "If the address is valid, this is the address <!--TODO: figure out in what cases this might be different from the address provided in the parameter -->"
- n: "→<br>`ismine`"
t: "bool"
p: "Optional<br>(0 or 1)"
d: "Set to `true` if the address belongs to the wallet; set to false if it does not. Only returned if wallet support enabled"
- n: "→<br>`iswatchonly`"
t: "bool"
p: "Optional<br>(0 or 1)"
d: "Set to `true` if the address is watch-only. Otherwise set to `false`. Only returned if address is in the wallet"
- n: "→<br>`isscript`"
t: "bool"
p: "Optional<br>(0 or 1)"
d: "Set to `true` if a P2SH address; otherwise set to `false`. Only returned if the address is in the wallet"
- n: "→<br>`script`"
t: "string"
p: "Optional<br>(0 or 1)"
d: "Only returned for P2SH addresses belonging to this wallet. This is the type of script:<br>• `pubkey` for a P2PK script inside P2SH<br>• `pubkeyhash` for a P2PKH script inside P2SH<br>• `multisig` for a multisig script inside P2SH<br>• `nonstandard` for unknown scripts"
- n: "→<br>`hex`"
t: "string (hex)"
p: "Optional<br>(0 or 1)"
d: "Only returned for P2SH addresses belonging to this wallet. This is the redeem script encoded as hex"
- n: "→<br>`addresses`"
t: "array"
p: "Optional<br>(0 or 1)"
d: "Only returned for P2SH addresses belonging to the wallet. A P2PKH addresses used in this script, or the computed P2PKH addresses of any pubkeys in this script. This array will be empty for `nonstandard` script types"
- n: "→ →<br>Address"
t: "string"
p: "Optional<br>(0 or more)"
d: "A P2PKH address"
- n: "→<br>`sigrequired`"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "Only returned for multisig P2SH addresses belonging to the wallet. The number of signatures required by this script"
- n: "→<br>`pubkey`"
t: "string (hex)"
p: "Optional<br>(0 or 1)"
d: "The public key corresponding to this address. Only returned if the address is a P2PKH address in the wallet"
- n: "→<br>`iscompressed`"
t: "bool"
p: "Optional<br>(0 or 1)"
d: "Set to `true` if a compressed public key or set to `false` if an uncompressed public key. Only returned if the address is a P2PKH address in the wallet"
- n: "→<br>`account`"
t: "string"
p: "Optional<br>(0 or 1)"
d: "The account this address belong to. May be an empty string for the default account. Only returned if the address belongs to the wallet"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Validate the following P2PKH address from the wallet:
{% highlight bash %}
bitcoin-cli -testnet validateaddress mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe
{% endhighlight %}
Result:
{% highlight json %}
{
"isvalid" : true,
"address" : "mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe",
"ismine" : true,
"iswatchonly" : false,
"isscript" : false,
"pubkey" : "03bacb84c6464a58b3e0a53cc0ba4cb3b82848cd7bed25a7724b3cc75d76c9c1ba",
"iscompressed" : true,
"account" : "test label"
}
{% endhighlight %}
Validate the following P2SH multisig address from the wallet:
{% highlight bash %}
bitcoin-cli -testnet validateaddress 2MyVxxgNBk5zHRPRY2iVjGRJHYZEp1pMCSq
{% endhighlight %}
Result:
{% highlight json %}
{
"isvalid" : true,
"address" : "2MyVxxgNBk5zHRPRY2iVjGRJHYZEp1pMCSq",
"ismine" : true,
"iswatchonly" : false,
"isscript" : true,
"script" : "multisig",
"hex" : "522103ede722780d27b05f0b1169efc90fa15a601a32fc6c3295114500c586831b6aaf2102ecd2d250a76d204011de6bc365a56033b9b3a149f679bc17205555d3c2b2854f21022d609d2f0d359e5bc0e5d0ea20ff9f5d3396cb5b1906aa9c56a0e7b5edc0c5d553ae",
"addresses" : [
"mjbLRSidW1MY8oubvs4SMEnHNFXxCcoehQ",
"mo1vzGwCzWqteip29vGWWW6MsEBREuzW94",
"mt17cV37fBqZsnMmrHnGCm9pM28R1kQdMG"
],
"sigsrequired" : 2,
"account" : "test account"
}
{% endhighlight %}
*See also*
* [ImportAddress][rpc importaddress]: {{summary_importAddress}}
* [GetNewAddress][rpc getnewaddress]: {{summary_getNewAddress}}
{% endautocrossref %}

66
_includes/devdoc/bitcoin-core/rpcs/rpcs/verifychain.md Normal file
View file

@ -0,0 +1,66 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/verifychain.md" %}
##### VerifyChain
{% include helpers/subhead-links.md %}
{% assign summary_verifyChain="verifies each entry in the local block chain database." %}
{% autocrossref %}
The `verifychain` RPC {{summary_verifyChain}}
*Parameter #1---how thoroughly to check each block*
{% itemplate ntpd1 %}
- n: "Check Level"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "How thoroughly to check each block, from 0 to 4. Default is the level set with the `-checklevel` command line argument; if that isn't set, the default is `3`. Each higher level includes the tests from the lower levels<br><br>Levels are:<br>**0.** Read from disk to ensure the files are accessible<br>**1.** Ensure each block is valid<br>**2.** Make sure undo files can be read from disk and are in a valid format<br>**3.** Test each block undo to ensure it results in correct state<br>**4.** After undoing blocks, reconnect them to ensure they reconnect correctly"
{% enditemplate %}
*Parameter #2---the number of blocks to check*
{% itemplate ntpd1 %}
- n: "Number Of Blocks"
t: "number (int)"
p: "Optional<br>(0 or 1)"
d: "The number of blocks to verify. Set to `0` to check all blocks. Defaults to the value of the `-checkblocks` command-line argument; if that isn't set, the default is `288`"
{% enditemplate %}
*Result---verification results*
{% itemplate ntpd1 %}
- n: "`result`"
t: "bool"
p: "Required<br>(exactly 1)"
d: "Set to `true` if verified; set to `false` if verification failed for any reason"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Verify the most recent 10,000 blocks in the most through way:
{% highlight bash %}
bitcoin-cli -testnet verifychain 4 10000
{% endhighlight %}
Result (took 4 minutes and 25 seconds on a generic PC laptop; it
would've taken much longer on mainnet):
{% highlight json %}
true
{% endhighlight %}
*See also*
* [GetBlockChainInfo][rpc getblockchaininfo]: {{summary_getBlockChainInfo}}
* [GetTxOutSetInfo][rpc gettxoutsetinfo]: {{summary_getTxOutSetInfo}}
{% endautocrossref %}

78
_includes/devdoc/bitcoin-core/rpcs/rpcs/verifymessage.md Normal file
View file

@ -0,0 +1,78 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/verifymessage.md" %}
##### VerifyMessage
{% include helpers/subhead-links.md %}
{% assign summary_verifyMessage="verifies a signed message." %}
{% autocrossref %}
The `verifymessage` RPC {{summary_verifyMessage}}
*Parameter #1---the address corresponding to the signing key*
{% itemplate ntpd1 %}
- n: "Address"
t: "string (base58)"
p: "Required<br>(exactly 1)"
d: "The P2PKH address corresponding to the private key which made the signature. A P2PKH address is a hash of the public key corresponding to the private key which made the signature. When the ECDSA signature is checked, up to four possible ECDSA public keys will be reconstructed from from the signature; each key will be hashed and compared against the P2PKH address provided to see if any of them match. If there are no matches, signature validation will fail"
{% enditemplate %}
*Parameter #2---the signature*
{% itemplate ntpd1 %}
- n: "Signature"
t: "string (base64)"
p: "Required<br>(exactly 1)"
d: "The signature created by the signer encoded as base-64 (the format output by the `signmessage` RPC)"
{% enditemplate %}
*Parameter #3---the message*
{% itemplate ntpd1 %}
- n: "Message"
t: "string"
p: "Required<br>(exactly 1)"
d: "The message exactly as it was signed (e.g. no extra whitespace)"
{% enditemplate %}
*Result: `true`, `false`, or an error*
{% itemplate ntpd1 %}
- n: "`result`"
t: "bool/null"
p: "Required<br>(exactly 1)"
d: "Set to `true` if the message was signed by a key corresponding to the provided P2PKH address; set to `false` if it was not signed by that key; set to JSON `null` if an error occurred"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Check the signature on the message created in the example for
`signmessage`:
{% highlight bash %}
bitcoin-cli -testnet verifymessage \
mgnucj8nYqdrPFh2JfZSB1NmUThUGnmsqe \
IL98ziCmwYi5pL+dqKp4Ux+zCa4hP/xbjHmWh+Mk/lefV/0pWV1p/gQ94jgExSmgH2/+PDcCCrOHAady2IEySSI= \
'Hello, World!'
{% endhighlight %}
Result:
{% highlight json %}
true
{% endhighlight %}
*See also*
* [SignMessage][rpc signmessage]: {{summary_signMessage}}
{% endautocrossref %}

73
_includes/devdoc/bitcoin-core/rpcs/rpcs/verifytxoutproof.md Normal file
View file

@ -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/devdoc/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 %}

44
_includes/devdoc/bitcoin-core/rpcs/rpcs/walletlock.md Normal file
View file

@ -0,0 +1,44 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/walletlock.md" %}
##### WalletLock
{% include helpers/subhead-links.md %}
{% 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." %}
{% autocrossref %}
*Requires wallet support. Requires an unlocked wallet.*
The `walletlock` RPC {{summary_walletLock}}
*Parameters: none*
*Result---`null` on success*
{% itemplate ntpd1 %}
- n: "`result`"
t: "null"
p: "Required<br>(exactly 1)"
d: "Always set to JSON `null`"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
{% highlight bash %}
bitcoin-cli -testnet walletlock
{% endhighlight %}
(Success: nothing printed.)
*See also*
* [EncryptWallet][rpc encryptwallet]: {{summary_encryptWallet}}
* [WalletPassphrase][rpc walletpassphrase]: {{summary_walletPassphrase}}
* [WalletPassphraseChange][rpc walletpassphrasechange]: {{summary_walletPassphraseChange}}
{% endautocrossref %}

68
_includes/devdoc/bitcoin-core/rpcs/rpcs/walletpassphrase.md Normal file
View file

@ -0,0 +1,68 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/walletpassphrase.md" %}
##### WalletPassphrase
{% include helpers/subhead-links.md %}
{% 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." %}
{% autocrossref %}
*Requires wallet support. Requires an encrypted wallet.*
The `walletpassphrase` RPC {{summary_walletPassphrase}}
{{WARNING}} if using this RPC on the command line, remember
that your shell probably saves your command lines (including the
value of the passphrase parameter).
*Parameter #1---the passphrase*
{% itemplate ntpd1 %}
- n: "Passphrase"
t: "string"
p: "Required<br>(exactly 1)"
d: "The passphrase that unlocks the wallet"
{% enditemplate %}
*Parameter #2---the number of seconds to leave the wallet unlocked*
{% itemplate ntpd1 %}
- n: "Seconds"
t: "number (int)"
p: "Required<br>(exactly 1)"
d: "The number of seconds after which the decryption key will be automatically deleted from memory"
{% enditemplate %}
*Result---`null` on success*
{% itemplate ntpd1 %}
- n: "`result`"
t: "null"
p: "Required<br>(exactly 1)"
d: "Always set to JSON `null`"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Unlock the wallet for 10 minutes (the passphrase is "test"):
{% highlight bash %}
bitcoin-cli -testnet walletpassphrase test 600
{% endhighlight %}
(Success: no result printed.)
*See also*
* [EncryptWallet][rpc encryptwallet]: {{summary_encryptWallet}}
* [WalletPassphraseChange][rpc walletpassphrasechange]: {{summary_walletPassphraseChange}}
* [WalletLock][rpc walletlock]: {{summary_walletLock}}
{% endautocrossref %}

68
_includes/devdoc/bitcoin-core/rpcs/rpcs/walletpassphrasechange.md Normal file
View file

@ -0,0 +1,68 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/bitcoin-core/rpcs/rpcs/walletpassphrasechange.md" %}
##### WalletPassphraseChange
{% include helpers/subhead-links.md %}
{% assign summary_walletPassphraseChange="changes the wallet passphrase from 'old passphrase' to 'new passphrase'." %}
{% autocrossref %}
*Requires wallet support. Requires an encrypted wallet.*
The `walletpassphrasechange` RPC {{summary_walletPassphraseChange}}
{{WARNING}} if using this RPC on the command line, remember
that your shell probably saves your command lines (including the
value of the passphrase parameter).
*Parameter #1---the current passphrase*
{% itemplate ntpd1 %}
- n: "Current Passphrase"
t: "string"
p: "Required<br>(exactly 1)"
d: "The current wallet passphrase"
{% enditemplate %}
*Parameter #2---the new passphrase*
{% itemplate ntpd1 %}
- n: "New Passphrase"
t: "string"
p: "Required<br>(exactly 1)"
d: "The new passphrase for the wallet"
{% enditemplate %}
*Result---`null` on success*
{% itemplate ntpd1 %}
- n: "`result`"
t: "null"
p: "Required<br>(exactly 1)"
d: "Always set to JSON `null`"
{% enditemplate %}
*Example from Bitcoin Core 0.10.0*
Change the wallet passphrase from "test" to "example":
{% highlight bash %}
bitcoin-cli -testnet walletpassphrasechange test example
{% endhighlight %}
(Success: no result printed.)
*See also*
* [EncryptWallet][rpc encryptwallet]: {{summary_encryptWallet}}
* [WalletPassphrase][rpc walletpassphrase]: {{summary_walletPassphrase}}
* [WalletLock][rpc walletlock]: {{summary_walletLock}}
{% endautocrossref %}

69
_includes/devdoc/example_intro.md Normal file
View file

@ -0,0 +1,69 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/example_intro.md" %}
{% autocrossref %}
The following guide aims to provide examples to help you start
building Bitcoin-based applications. To make the best use of this document,
you may want to install the current version of Bitcoin Core, either from
[source][core git] or from a [pre-compiled executable][core executable].
Once installed, you'll have access to three programs: `bitcoind`,
`bitcoin-qt`, and `bitcoin-cli`.
* `bitcoin-qt` provides a combination full Bitcoin peer and wallet
frontend. From the Help menu, you can access a console where you can
enter the RPC commands used throughout this document.
* `bitcoind` is more useful for programming: it provides a full peer
which you can interact with through RPCs to port 8332 (or 18332
for testnet).
* `bitcoin-cli` allows you to send RPC commands to `bitcoind` from the
command line. For example, `bitcoin-cli help`
All three programs get settings from `bitcoin.conf` in the `Bitcoin`
application directory:
* Windows: `%APPDATA%\Bitcoin\`
* OSX: `$HOME/Library/Application Support/Bitcoin/`
* Linux: `$HOME/.bitcoin/`
To use `bitcoind` and `bitcoin-cli`, you will need to add a RPC password
to your `bitcoin.conf` file. Both programs will read from the same file
if both run on the same system as the same user, so any long random
password will work:
~~~
rpcpassword=change_this_to_a_long_random_password
~~~~
You should also make the `bitcoin.conf` file only readable to its
owner. On Linux, Mac OSX, and other Unix-like systems, this can be
accomplished by running the following command in the Bitcoin application
directory:
~~~
chmod 0600 bitcoin.conf
~~~
For development, it's safer and cheaper to use Bitcoin's test network (testnet)
or regression test mode (regtest) described below.
Questions about Bitcoin use are best sent to the [BitcoinTalk forum][forum
tech support] and [IRC channels][]. Errors or suggestions related to
documentation on Bitcoin.org can be [submitted as an issue][docs issue]
or posted to the [bitcoin-documentation mailing list][].
In the following documentation, some strings have been shortened or wrapped: "[...]"
indicates extra data was removed, and lines ending in a single backslash "\\"
are continued below. If you hover your mouse over a paragraph, cross-reference
links will be shown in blue. If you hover over a cross-reference link, a brief
definition of the term will be displayed in a tooltip.
{% endautocrossref %}

456
_includes/devdoc/example_p2p_networking.md Normal file
View file

@ -0,0 +1,456 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/example_p2p_networking.md" %}
## P2P Network
{% include helpers/subhead-links.md %}
### Creating A Bloom Filter
{% include helpers/subhead-links.md %}
{% autocrossref %}
In this section, we'll use variable names that correspond to the field
names in the [`filterload` message documentation][filterload message].
Each code block precedes the paragraph describing it.
{% highlight python %}
#!/usr/bin/env python
BYTES_MAX = 36000
FUNCS_MAX = 50
nFlags = 0
{% endhighlight %}
We start by setting some maximum values defined in BIP37: the maximum
number of bytes allowed in a filter and the maximum number of hash
functions used to hash each piece of data. We also set nFlags to zero,
indicating we don't want the remote node to update the filter for us.
(We won't use nFlags again in the sample program, but real programs will
need to use it.)
{% highlight python %}
n = 1
p = 0.0001
{% endhighlight %}
We define the number (n) of elements we plan to insert into the filter
and the false positive rate (p) we want to help protect our privacy. For
this example, we will set *n* to one element and *p* to a rate of
1-in-10,000 to produce a small and precise filter for illustration
purposes. In actual use, your filters will probably be much larger.
{% highlight python %}
from math import log
nFilterBytes = int(min((-1 / log(2)**2 * n * log(p)) / 8, BYTES_MAX))
nHashFuncs = int(min(nFilterBytes * 8 / n * log(2), FUNCS_MAX))
from bitarray import bitarray # from pypi.python.org/pypi/bitarray
vData = nFilterBytes * 8 * bitarray('0', endian="little")
{% endhighlight %}
Using the formula described in BIP37, we calculate the ideal size of the
filter (in bytes) and the ideal number of hash functions to use. Both
are truncated down to the nearest whole number and both are also
constrained to the maximum values we defined earlier. The results of
this particular fixed computation are 2 filter bytes and 11 hash
functions. We then use *nFilterBytes* to create a little-endian bit
array of the appropriate size.
{% highlight python %}
nTweak = 0
{% endhighlight %}
We also should choose a value for *nTweak*. In this case, we'll simply
use zero.
{% highlight python %}
import pyhash # from https://github.com/flier/pyfasthash
murmur3 = pyhash.murmur3_32()
def bloom_hash(nHashNum, data):
seed = (nHashNum * 0xfba4c795 + nTweak) & 0xffffffff
return( murmur3(data, seed=seed) % (nFilterBytes * 8) )
{% endhighlight %}
We setup our hash function template using the formula and 0xfba4c795
constant set in BIP37. Note that we limit the size of the seed to four
bytes and that we're returning the result of the hash modulo the size of
the filter in bits.
{% highlight python %}
data_to_hash = "019f5b01d4195ecbc9398fbf3c3b1fa9" \
+ "bb3183301d7a1fb3bd174fcfa40a2b65"
data_to_hash = data_to_hash.decode("hex")
{% endhighlight %}
For the data to add to the filter, we're adding a TXID. Note that the
TXID is in internal byte order.
{% highlight python %}
print " Filter (As Bits)"
print "nHashNum nIndex Filter 0123456789abcdef"
print "~~~~~~~~ ~~~~~~ ~~~~~~ ~~~~~~~~~~~~~~~~"
for nHashNum in range(nHashFuncs):
nIndex = bloom_hash(nHashNum, data_to_hash)
## Set the bit at nIndex to 1
vData[nIndex] = True
## Debug: print current state
print ' {0:2} {1:2} {2} {3}'.format(
nHashNum,
hex(int(nIndex)),
vData.tobytes().encode("hex"),
vData.to01()
)
print
print "Bloom filter:", vData.tobytes().encode("hex")
{% endhighlight %}
Now we use the hash function template to run a slightly different hash
function for *nHashFuncs* times. The result of each function being run
on the transaction is used as an index number: the bit at that index is
set to 1. We can see this in the printed debugging output:
{% highlight text %}
Filter (As Bits)
nHashNum nIndex Filter 0123456789abcdef
~~~~~~~~ ~~~~~~ ~~~~~~ ~~~~~~~~~~~~~~~~
0 0x7 8000 0000000100000000
1 0x9 8002 0000000101000000
2 0xa 8006 0000000101100000
3 0x2 8406 0010000101100000
4 0xb 840e 0010000101110000
5 0x5 a40e 0010010101110000
6 0x0 a50e 1010010101110000
7 0x8 a50f 1010010111110000
8 0x5 a50f 1010010111110000
9 0x8 a50f 1010010111110000
10 0x4 b50f 1010110111110000
Bloom filter: b50f
{% endhighlight %}
Notice that in iterations 8 and 9, the filter did not change because the
corresponding bit was already set in a previous iteration (5 and 7,
respectively). This is a normal part of bloom filter operation.
We only added one element to the filter above, but we could repeat the
process with additional elements and continue to add them to the same
filter. (To maintain the same false-positive rate, you would need a
larger filter size as computed earlier.)
Note: for a more optimized Python implementation with fewer external
dependencies, see [python-bitcoinlib's][python-bitcoinlib] bloom filter
module which is based directly on Bitcoin Core's C++ implementation.
Using the `filterload` message format, the complete filter created above
would be the binary form of the annotated hexdump shown below:
{% highlight text %}
02 ......... Filter bytes: 2
b50f ....... Filter: 1010 1101 1111 0000
0b000000 ... nHashFuncs: 11
00000000 ... nTweak: 0/none
00 ......... nFlags: BLOOM_UPDATE_NONE
{% endhighlight %}
{% endautocrossref %}
### Evaluating A Bloom Filter
{% include helpers/subhead-links.md %}
{% autocrossref %}
Using a bloom filter to find matching data is nearly identical to
constructing a bloom filter---except that at each step we check to see
if the calculated index bit is set in the existing filter.
{% highlight python %}
vData = bitarray(endian='little')
vData.frombytes("b50f".decode("hex"))
nHashFuncs = 11
nTweak = 0
nFlags = 0
{% endhighlight %}
Using the bloom filter created above, we import its various parameters.
Note, as indicated in the section above, we won't actually use *nFlags*
to update the filter.
{% highlight python %}
def contains(nHashFuncs, data_to_hash):
for nHashNum in range(nHashFuncs):
## bloom_hash as defined in previous section
nIndex = bloom_hash(nHashNum, data_to_hash)
if vData[nIndex] != True:
print "MATCH FAILURE: Index {0} not set in {1}".format(
hex(int(nIndex)),
vData.to01()
)
return False
{% endhighlight %}
We define a function to check an element against the provided filter.
When checking whether the filter might contain an element, we test to
see whether a particular bit in the filter is already set to 1 (if it
isn't, the match fails).
{% highlight python %}
## Test 1: Same TXID as previously added to filter
data_to_hash = "019f5b01d4195ecbc9398fbf3c3b1fa9" \
+ "bb3183301d7a1fb3bd174fcfa40a2b65"
data_to_hash = data_to_hash.decode("hex")
contains(nHashFuncs, data_to_hash)
{% endhighlight %}
Testing the filter against the data element we previously added, we get
no output (indicating a possible match). Recall that bloom filters have
a zero false negative rate---so they should always match the inserted
elements.
{% highlight python %}
## Test 2: Arbitrary string
data_to_hash = "1/10,000 chance this ASCII string will match"
contains(nHashFuncs, data_to_hash)
{% endhighlight %}
Testing the filter against an arbitrary element, we get the failure
output below. Note: we created the filter with a 1-in-10,000 false
positive rate (which was rounded up somewhat when we truncated), so it
was possible this arbitrary string would've matched the filter anyway.
It is not possible to set a bloom filter to a false positive rate of
zero, so your program will always have to deal with false positives.
The output below shows us that one of the hash functions returned an
index number of 0x06, but that bit wasn't set in the filter, causing the
match failure:
{% highlight text %}
MATCH FAILURE: Index 0x6 not set in 1010110111110000
{% endhighlight %}
{% endautocrossref %}
### Retrieving A MerkleBlock
{% include helpers/subhead-links.md %}
{% autocrossref %}
For the `merkleblock` message documentation on the reference page, an
actual merkle block was retrieved from the network and manually
processed. This section walks through each step of the process,
demonstrating basic network communication and merkle block processing.
{% highlight python %}
#!/usr/bin/env python
from time import sleep
from hashlib import sha256
import struct
import sys
network_string = "f9beb4d9".decode("hex") # Mainnet
def send(msg,payload):
## Command is ASCII text, null padded to 12 bytes
command = msg + ( ( 12 - len(msg) ) * "\00" )
## Payload length is a uint32_t
payload_raw = payload.decode("hex")
payload_len = struct.pack("I", len(payload_raw))
## Checksum is first 4 bytes of SHA256(SHA256(<payload>))
checksum = sha256(sha256(payload_raw).digest()).digest()[:4]
sys.stdout.write(
network_string
+ command
+ payload_len
+ checksum
+ payload_raw
)
sys.stdout.flush()
{% endhighlight %}
To connect to the P2P network, the trivial Python function above was
developed to compute message headers and send payloads decoded from hex.
{% highlight python %}
## Create a version message
send("version",
"71110100" # ........................ Protocol Version: 70001
+ "0000000000000000" # ................ Services: Headers Only (SPV)
+ "c6925e5400000000" # ................ Time: 1415484102
+ "00000000000000000000000000000000"
+ "0000ffff7f000001208d" # ............ Receiver IP Address/Port
+ "00000000000000000000000000000000"
+ "0000ffff7f000001208d" # ............ Sender IP Address/Port
+ "0000000000000000" # ................ Nonce (not used here)
+ "1b" # .............................. Bytes in version string
+ "2f426974636f696e2e6f726720457861"
+ "6d706c653a302e392e332f" # .......... Version string
+ "93050500" # ........................ Starting block height: 329107
+ "00" # .............................. Relay transactions: false
)
{% endhighlight %}
Peers on the network will not accept any requests until you send them a
`version` message. The receiving node will reply with their `version`
message and a `verack` message.
{% highlight python %}
sleep(1)
send("verack", "")
{% endhighlight %}
We're not going to validate their `version` message with this simple
script, but we will sleep a short bit and send back our own `verack`
message as if we had accepted their `version` message.
{% highlight python %}
send("filterload",
"02" ........ Filter bytes: 2
"b50f" ....... Filter: 1010 1101 1111 0000
"0b000000" ... nHashFuncs: 11
"00000000" ... nTweak: 0/none
"00" ......... nFlags: BLOOM_UPDATE_NONE
)
{% endhighlight %}
We set a bloom filter with the `filterload` message. This filter is
described in the two preceeding sections.
{% highlight python %}
send("getdata",
"01" # ................................. Number of inventories: 1
+ "03000000" # ........................... Inventory type: filtered block
+ "a4deb66c0d726b0aefb03ed51be407fb"
+ "ad7331c6e8f9eef231b7000000000000" # ... Block header hash
)
{% endhighlight %}
We request a merkle block for transactions matching our filter,
completing our script.
To run the script, we simply pipe it to the Unix [`netcat`
command][netcat] or one of its many clones, one of which is available
for practically any platform. For example, with the original netcat and
using hexdump (`hd`) to display the output:
{% highlight bash %}
## Connect to the Bitcoin Core peer running on localhost
python get-merkle.py | nc localhost 8333 | hd
{% endhighlight %}
Part of the response is shown in the section below.
{% endautocrossref %}
### Parsing A MerkleBlock
{% include helpers/subhead-links.md %}
{% autocrossref %}
In the section above, we retrieved a merkle block from the network; now
we will parse it. Most of the block header has been omitted. For
a more complete hexdump, see the example in the [`merkleblock` message
section][merkleblock message].
{% highlight text %}
7f16c5962e8bd963659c793ce370d95f
093bc7e367117b3c30c1f8fdd0d97287 ... Merkle root
07000000 ........................... Transaction count: 7
04 ................................. Hash count: 4
3612262624047ee87660be1a707519a4
43b1c1ce3d248cbfc6c15870f6c5daa2 ... Hash #1
019f5b01d4195ecbc9398fbf3c3b1fa9
bb3183301d7a1fb3bd174fcfa40a2b65 ... Hash #2
41ed70551dd7e841883ab8f0b16bf041
76b7d1480e4f0af9f3d4c3595768d068 ... Hash #3
20d2a7bc994987302e5b1ac80fc425fe
25f8b63169ea78e68fbaaefa59379bbf ... Hash #4
01 ................................. Flag bytes: 1
1d ................................. Flags: 1 0 1 1 1 0 0 0
{% endhighlight %}
We parse the above `merkleblock` message using the following
instructions. Each illustration is described in the paragraph below it.
![Parsing A MerkleBlock](/img/dev/gifs/en-merkleblock-parsing/en-merkleblock-parsing-001.svg)
We start by building the structure of a merkle tree based on the number
of transactions in the block.
![Parsing A MerkleBlock](/img/dev/gifs/en-merkleblock-parsing/en-merkleblock-parsing-002.svg)
The first flag is a 1 and the merkle root is (as always) a non-TXID
node, so we will need to compute the hash later based on this node's
children. Accordingly, we descend into the merkle root's left child and
look at the next flag for instructions.
![Parsing A MerkleBlock](/img/dev/gifs/en-merkleblock-parsing/en-merkleblock-parsing-003.svg)
The next flag in the example is a 0 and this is also a non-TXID node, so
we apply the first hash from the `merkleblock` message to this node. We
also don't process any child nodes---according to the peer which created
the `merkleblock` message, none of those nodes will lead to TXIDs of
transactions that match our filter, so we don't need them. We go back up
to the merkle root and then descend into its right child and look at the
next (third) flag for instructions.
![Parsing A MerkleBlock](/img/dev/gifs/en-merkleblock-parsing/en-merkleblock-parsing-004.svg)
The third flag in the example is another 1 on another non-TXID node, so
we descend into its left child.
![Parsing A MerkleBlock](/img/dev/gifs/en-merkleblock-parsing/en-merkleblock-parsing-005.svg)
The fourth flag is also a 1 on another non-TXID node, so we descend
again---we will always continue descending until we reach a TXID node or
a non-TXID node with a 0 flag (or we finish filling out the tree).
![Parsing A MerkleBlock](/img/dev/gifs/en-merkleblock-parsing/en-merkleblock-parsing-006.svg)
Finally, on the fifth flag in the example (a 1), we reach a TXID node.
The 1 flag indicates this TXID's transaction matches our filter and
that we should take the next (second) hash and use it as this node's
TXID.
![Parsing A MerkleBlock](/img/dev/gifs/en-merkleblock-parsing/en-merkleblock-parsing-007.svg)
The sixth flag also applies to a TXID, but it's a 0 flag, so this
TXID's transaction doesn't match our filter; still, we take the next
(third) hash and use it as this node's TXID.
![Parsing A MerkleBlock](/img/dev/gifs/en-merkleblock-parsing/en-merkleblock-parsing-008.svg)
We now have enough information to compute the hash for the fourth node
we encountered---it's the hash of the concatenated hashes of the two
TXIDs we filled out.
![Parsing A MerkleBlock](/img/dev/gifs/en-merkleblock-parsing/en-merkleblock-parsing-009.svg)
Moving to the right child of the third node we encountered, we fill it
out using the seventh flag and final hash---and discover there are no
more child nodes to process.
![Parsing A MerkleBlock](/img/dev/gifs/en-merkleblock-parsing/en-merkleblock-parsing-011.svg)
We hash as appropriate to fill out the tree. Note that the eighth flag is
not used---this is acceptable as it was required to pad out a flag byte.
The final steps would be to ensure the computed computed merkle root
is identical to the merkle root in the header and check the other steps
of the parsing checklist in the `merkleblock` message section.
{% endautocrossref %}

473
_includes/devdoc/example_payment_processing.md Normal file
View file

@ -0,0 +1,473 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/example_payment_processing.md" %}
## Payment Processing
{% include helpers/subhead-links.md %}
### Payment Protocol
{% include helpers/subhead-links.md %}
{% autocrossref %}
To request payment using the payment protocol, you use an extended (but
backwards-compatible) `bitcoin:` URI. For example:
{% endautocrossref %}
~~~
bitcoin:mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN\
?amount=0.10\
&label=Example+Merchant\
&message=Order+of+flowers+%26+chocolates\
&r=https://example.com/pay.php/invoice%3Dda39a3ee
~~~
{% autocrossref %}
The browser, QR code reader, or other program processing the URI opens
the spender's Bitcoin wallet program on the URI. If the wallet program is
aware of the payment protocol, it accesses the URL specified in the `r`
parameter, which should provide it with a serialized PaymentRequest
served with the [MIME][] type `application/bitcoin-paymentrequest`<!--noref-->.
**Resource:** Gavin Andresen's [Payment Request Generator][] generates
custom example URIs and payment requests for use with testnet.
{% endautocrossref %}
#### PaymentRequest & PaymentDetails
{% include helpers/subhead-links.md %}
{% autocrossref %}
The [PaymentRequest][]{:#term-paymentrequest}{:.term} is created with data structures built using
Google's Protocol Buffers. BIP70 describes these data
structures in the non-sequential way they're defined in the payment
request protocol buffer code, but the text below will describe them in
a more linear order using a simple (but functional) Python CGI
program. (For brevity and clarity, many normal CGI best practices are
not used in this program.)
The full sequence of events is illustrated below, starting with the
spender clicking a `bitcoin:` URI or scanning a `bitcoin:` QR code.
![BIP70 Payment Protocol](/img/dev/en-payment-protocol.svg)
For the script to use the protocol buffer, you will need a copy of
Google's Protocol Buffer compiler (`protoc`), which is available in most
modern Linux package managers and [directly from Google.][protobuf] Non-Google
protocol buffer compilers are available for a variety of
programming languages. You will also need a copy of the PaymentRequest
[Protocol Buffer description][core paymentrequest.proto] from the Bitcoin Core source code.
{% endautocrossref %}
##### Initialization Code
{% include helpers/subhead-links.md %}
{% autocrossref %}
With the Python code generated by `protoc`, we can start our simple
CGI program.
{% highlight python %}
#!/usr/bin/env python
## This is the code generated by protoc --python_out=./ paymentrequest.proto
from paymentrequest_pb2 import *
## Load some functions
from time import time
from sys import stdout
from OpenSSL.crypto import FILETYPE_PEM, load_privatekey, sign
## Copy three of the classes created by protoc into objects we can use
details = PaymentDetails()
request = PaymentRequest()
x509 = X509Certificates()
{% endhighlight %}
The startup code above is quite simple, requiring nothing but the epoch
(Unix date) time function, the standard out file descriptor, a few
functions from the OpenSSL library, and the data structures and
functions created by `protoc`.
{% endautocrossref %}
##### Configuration Code
{% include helpers/subhead-links.md %}
{% autocrossref %}
Next, we'll set configuration settings which will typically only change
when the receiver wants to do something differently. The code pushes a
few settings into the `request` (PaymentRequest) and `details`
(PaymentDetails) objects. When we serialize them,
[PaymentDetails][]{:#term-paymentdetails}{:.term} will be contained
within the PaymentRequest.
{% highlight python %}
## SSL Signature method
request.pki_type = "x509+sha256" ## Default: none
## Mainnet or testnet?
details.network = "test" ## Default: main
## Postback URL
details.payment_url = "https://example.com/pay.py"
## PaymentDetails version number
request.payment_details_version = 1 ## Default: 1
## Certificate chain
x509.certificate.append(file("/etc/apache2/example.com-cert.der", "r").read())
#x509.certificate.append(file("/some/intermediate/cert.der", "r").read())
## Load private SSL key into memory for signing later
priv_key = "/etc/apache2/example.com-key.pem"
pw = "test" ## Key password
private_key = load_privatekey(FILETYPE_PEM, file(priv_key, "r").read(), pw)
{% endhighlight %}
Each line is described below.
{% highlight python %}
request.pki_type = "x509+sha256" ## Default: none
{% endhighlight %}
`pki_type`: (optional) tell the receiving wallet program what [Public-Key
Infrastructure][PKI]{:#term-pki}{:.term} (PKI) type you're using to
cryptographically sign your PaymentRequest so that it can't be modified
by a man-in-the-middle attack.
If you don't want to sign the PaymentRequest, you can choose a
[`pki_type`][pp pki type]{:#term-pp-pki-type}{:.term} of `none`
(the default).
If you do choose the sign the PaymentRequest, you currently have two
options defined by BIP70: `x509+sha1` and `x509+sha256`. Both options
use the X.509 certificate system, the same system used for HTTP Secure
(HTTPS). To use either option, you will need a certificate signed by a
certificate authority or one of their intermediaries. (A self-signed
certificate will not work.)
Each wallet program may choose which certificate authorities to trust,
but it's likely that they'll trust whatever certificate authorities their
operating system trusts. If the wallet program doesn't have a full
operating system, as might be the case for small hardware wallets, BIP70
suggests they use the [Mozilla Root Certificate Store][mozrootstore]. In
general, if a certificate works in your web browser when you connect to
your webserver, it will work for your PaymentRequests.
{% highlight python %}
details.network = "test" ## Default: main
{% endhighlight %}
`network`:<!--noref--> (optional) tell the spender's wallet program what Bitcoin network you're
using; BIP70 defines "main" for mainnet (actual payments) and "test" for
testnet (like mainnet, but fake satoshis are used). If the wallet
program doesn't run on the network you indicate, it will reject the
PaymentRequest.
{% highlight python %}
details.payment_url = "https://example.com/pay.py"
{% endhighlight %}
`payment_url`: (required) tell the spender's wallet program where to send the Payment
message (described later). This can be a static URL, as in this example,
or a variable URL such as `https://example.com/pay.py?invoice=123.`
It should usually be an HTTPS address to prevent man-in-the-middle
attacks from modifying the message.
{% highlight python %}
request.payment_details_version = 1 ## Default: 1
{% endhighlight %}
`payment_details_version`: (optional) tell the spender's wallet program what version of the
PaymentDetails you're using. As of this writing, the only version is
version 1.
{% highlight python %}
## This is the pubkey/certificate corresponding to the private SSL key
## that we'll use to sign:
x509.certificate.append(file("/etc/apache2/example.com-cert.der", "r").read())
{% endhighlight %}
`x509certificates`:<!--noref--> (required for signed PaymentRequests) you must
provide the public SSL key/certificate corresponding to the private SSL
key you'll use to sign the PaymentRequest. The certificate must be in
ASN.1/DER format.
{% highlight python %}
## If the pubkey/cert above didn't have the signature of a root
## certificate authority, we'd then append the intermediate certificate
## which signed it:
#x509.certificate.append(file("/some/intermediate/cert.der", "r").read())
{% endhighlight %}
You must also provide any intermediate certificates necessary to link
your certificate to the root certificate of a certificate authority
trusted by the spender's software, such as a certificate from the
Mozilla root store.
The certificates must be provided in a specific order---the same order
used by Apache's `SSLCertificateFile` directive and other server
software. The figure below shows the [certificate chain][]{:#term-certificate-chain}{:.term} of the
www.bitcoin.org X.509 certificate and how each certificate (except the
root certificate) would be loaded into the [X509Certificates][]{:#term-x509certificates}{:.term} protocol
buffer message.
![X509Certificates Loading Order](/img/dev/en-cert-order.svg)
To be specific, the first certificate provided must be the
X.509 certificate corresponding to the private SSL key which will make the
signature<!--noref-->, called the [leaf certificate][]{:#term-leaf-certificate}{:.term}. Any [intermediate
certificates][intermediate certificate]{:#term-intermediate-certificate}{:.term} necessary to link that signed public SSL
key to the [root
certificate][]{:#term-root-certificate}{:.term} (the certificate authority) are attached separately, with each
certificate in DER format bearing the signature<!--noref--> of the certificate that
follows it all the way to (but not including) the root certificate.
{% highlight python %}
priv_key = "/etc/apache2/example.com-key.pem"
pw = "test" ## Key password
private_key = load_privatekey(FILETYPE_PEM, file(priv_key, "r").read(), pw)
{% endhighlight %}
(Required for signed PaymentRequests) you will need a private SSL key in
a format your SSL library supports (DER format is not required). In this
program, we'll load it from a PEM file. (Embedding your passphrase in
your CGI code, as done here, is obviously a bad idea in real life.)
The private SSL key will not be transmitted with your request. We're
only loading it into memory here so we can use it to sign the request
later.
{% endautocrossref %}
##### Code Variables
{% include helpers/subhead-links.md %}
{% autocrossref %}
Now let's look at the variables your CGI program will likely set for
each payment.
{% highlight python %}
## Amount of the request
amount = 10000000 ## In satoshis
## P2PKH pubkey hash
pubkey_hash = "2b14950b8d31620c6cc923c5408a701b1ec0a020"
## P2PKH pubkey script entered as hex and converted to binary
# OP_DUP OP_HASH160 <push 20 bytes> <pubKey hash> OP_EQUALVERIFY OP_CHECKSIG
# 76 a9 14 <pubKey hash> 88 ac
hex_script = "76" + "a9" + "14" + pubkey_hash + "88" + "ac"
serialized_script = hex_script.decode("hex")
## Load amount and pubkey script into PaymentDetails
details.outputs.add(amount = amount, script = serialized_script)
## Memo to display to the spender
details.memo = "Flowers & chocolates"
## Data which should be returned to you with the payment
details.merchant_data = "Invoice #123"
{% endhighlight python %}
Each line is described below.
{% highlight python %}
amount = 10000000 ## In satoshis (=100 mBTC)
{% endhighlight %}
`amount`: (optional) the [amount][pp amount]{:#term-pp-amount}{:.term} you want the spender to pay. You'll probably get
this value from your shopping cart application or fiat-to-BTC exchange
rate conversion tool. If you leave the amount blank, the wallet
program will prompt the spender how much to pay (which can be useful
for donations).
{% highlight python %}
pubkey_hash = "2b14950b8d31620c6cc923c5408a701b1ec0a020"
# OP_DUP OP_HASH160 <push 20 bytes> <pubKey hash> OP_EQUALVERIFY OP_CHECKSIG
# 76 a9 14 <pubKey hash> 88 ac
hex_script = "76" + "a9" + "14" + pubkey_hash + "88" + "ac"
serialized_script = hex_script.decode("hex")
{% endhighlight %}
`script`: (required) You must specify the pubkey script you want the spender to
pay---any valid pubkey script is acceptable. In this example, we'll request
payment to a P2PKH pubkey script.
First we get a pubkey hash. The hash above is the hash form of the
address used in the URI examples throughout this section,
mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN.
Next, we plug that hash into the standard P2PKH pubkey script using hex,
as illustrated by the code comments.
Finally, we convert the pubkey script from hex into its serialized form.
{% highlight python %}
details.outputs.add(amount = amount, script = serialized_script)
{% endhighlight %}
`outputs`:<!--noref--> (required) add the pubkey script and (optional) amount to the
PaymentDetails outputs<!--noref--> array.
It's possible to specify multiple [`scripts`][pp
script]{:#term-pp-script}{:.term} and `amounts` as part of a merge
avoidance strategy, described later in the [Merge Avoidance
subsection][]. However, effective merge avoidance is not possible under
the base BIP70 rules in which the spender pays each `script` the exact
amount specified by its paired `amount`. If the amounts are omitted from
all `amount`/`script` pairs, the spender will be prompted to choose an
amount to pay.
{% highlight python %}
details.memo = "Flowers & chocolates"
{% endhighlight %}
`memo`: (optional) add a memo which will be displayed to the spender as
plain UTF-8 text. Embedded HTML or other markup will not be processed.
{% highlight python %}
details.merchant_data = "Invoice #123"
{% endhighlight %}
`merchant_data`: (optional) add arbitrary data which should be sent back to the
receiver when the invoice is paid. You can use this to track your
invoices, although you can more reliably track payments by generating a
unique address for each payment and then tracking when it gets paid.
The [`memo`][pp memo]{:#term-pp-memo}{:.term} field and the [`merchant_data`][pp merchant data]{:#term-pp-merchant-data}{:.term} field can be arbitrarily long,
but if you make them too long, you'll run into the 50,000 byte limit on
the entire PaymentRequest, which includes the often several kilobytes
given over to storing the certificate chain. As will be described in a
later subsection, the `memo` field can be used by the spender after
payment as part of a cryptographically-proven receipt.
{% endautocrossref %}
##### Derivable Data
{% include helpers/subhead-links.md %}
{% autocrossref %}
Next, let's look at some information your CGI program can
automatically derive.
{% highlight python %}
## Request creation time
details.time = int(time()) ## Current epoch (Unix) time
## Request expiration time
details.expires = int(time()) + 60 * 10 ## 10 minutes from now
## PaymentDetails is complete; serialize it and store it in PaymentRequest
request.serialized_payment_details = details.SerializeToString()
## Serialized certificate chain
request.pki_data = x509.SerializeToString()
## Initialize signature field so we can sign the full PaymentRequest
request.signature = ""
## Sign PaymentRequest
request.signature = sign(private_key, request.SerializeToString(), "sha256")
{% endhighlight %}
Each line is described below.
{% highlight python %}
details.time = int(time()) ## Current epoch (Unix) time
{% endhighlight %}
`time`: (required) PaymentRequests must indicate when they were created
in number of seconds elapsed since 1970-01-01T00:00 UTC (Unix
epoch time format).
{% highlight python %}
details.expires = int(time()) + 60 * 10 ## 10 minutes from now
{% endhighlight %}
`expires`: (optional) the PaymentRequest may also set an [`expires`][pp
expires]{:#term-pp-expires}{:.term} time after
which they're no longer valid. You probably want to give receivers
the ability to configure the expiration time delta; here we used the
reasonable choice of 10 minutes. If this request is tied to an order
total based on a fiat-to-satoshis exchange rate, you probably want to
base this on a delta from the time you got the exchange rate.
{% highlight python %}
request.serialized_payment_details = details.SerializeToString()
{% endhighlight %}
`serialized_payment_details`: (required) we've now set everything we need to create the
PaymentDetails, so we'll use the SerializeToString function from the
protocol buffer code to store the PaymentDetails in the appropriate
field of the PaymentRequest.
{% highlight python %}
request.pki_data = x509.SerializeToString()
{% endhighlight %}
`pki_data`: (required for signed PaymentRequests) serialize the certificate chain
[PKI data][pp PKI data]{:#term-pp-pki-data}{:.term} and store it in the
PaymentRequest
{% highlight python %}
request.signature = ""
{% endhighlight %}
We've filled out everything in the PaymentRequest except the signature,
but before we sign it, we have to initialize the signature field by
setting it to a zero-byte placeholder.
{% highlight python %}
request.signature = sign(private_key, request.SerializeToString(), "sha256")
{% endhighlight %}
`signature`:<!--noref--> (required for signed PaymentRequests) now we
make the [signature][ssl signature]{:#term-ssl-signature}{:.term} by
signing the completed and serialized PaymentRequest. We'll use the
private key we stored in memory in the configuration section and the
same hashing formula we specified in `pki_type` (sha256 in this case)
{% endautocrossref %}
##### Output Code
{% include helpers/subhead-links.md %}
{% autocrossref %}
Now that we have PaymentRequest all filled out, we can serialize it and
send it along with the HTTP headers, as shown in the code below.
{% highlight python %}
print "Content-Type: application/bitcoin-paymentrequest"
print "Content-Transfer-Encoding: binary"
print ""
{% endhighlight %}
(Required) BIP71 defines the content types for PaymentRequests,
Payments, and PaymentACKs.
{% highlight python %}
file.write(stdout, request.SerializeToString())
{% endhighlight %}
`request`: (required) now, to finish, we just dump out the serialized
PaymentRequest (which contains the serialized PaymentDetails). The
serialized data is in binary, so we can't use Python's print()
because it would add an extraneous newline.
The following screenshot shows how the authenticated PaymentDetails
created by the program above appears in the GUI from Bitcoin Core 0.9.
![Bitcoin Core Showing Validated Payment Request](/img/dev/en-btcc-payment-request.png)
{% endautocrossref %}

105
_includes/devdoc/example_testing.md Normal file
View file

@ -0,0 +1,105 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/example_testing.md" %}
## Testing Applications
{% include helpers/subhead-links.md %}
{% autocrossref %}
Bitcoin Core provides testing tools designed to let developers
test their applications with reduced risks and limitations.
{% endautocrossref %}
### Testnet
{% include helpers/subhead-links.md %}
{% autocrossref %}
When run with no arguments, all Bitcoin Core programs default to Bitcoin's main
network ([mainnet][/en/glossary/mainnet]{:#term-mainnet}{:.term}). However, for development,
it's safer and cheaper to use Bitcoin's test network (testnet)
where the satoshis spent have no real-world value. Testnet also relaxes some
restrictions (such as standard transaction checks) so you can test functions
which might currently be disabled by default on mainnet.
To use testnet, use the argument `-testnet`<!--noref--> with `bitcoin-cli`, `bitcoind` or `bitcoin-qt` or add
`testnet=1`<!--noref--> to your `bitcoin.conf` file as [described earlier][bitcoind initial setup]. To get
free satoshis for testing, use [Piotr Piasecki's testnet faucet][].
Testnet is a public resource provided for free by members of the
community, so please don't abuse it.
{% endautocrossref %}
### Regtest Mode
{% include helpers/subhead-links.md %}
{% autocrossref %}
For situations
where interaction with random peers and blocks is unnecessary or
unwanted, Bitcoin Core's regression test mode (regtest mode) lets you
instantly create a brand-new private block chain with the same basic
rules as testnet---but one major difference: you choose when to create
new blocks, so you have complete control over the environment.
Many developers consider regtest mode the preferred way to develop new
applications. The following example will let you create a regtest
environment after you first [configure bitcoind][bitcoind initial setup].
{% endautocrossref %}
{% highlight bash %}
> bitcoind -regtest -daemon
Bitcoin server starting
{% endhighlight %}
{% autocrossref %}
Start `bitcoind` in regtest mode to create a private block chain.
{% endautocrossref %}
~~~
## Bitcoin Core 0.10.1 and earlier
bitcoin-cli -regtest setgenerate true 101
## Bitcoin Core master (as of commit 48265f3)
bitcoin-cli -regtest generate 101
~~~
{% autocrossref %}
Generate 101 blocks using a special RPC
which is only available in regtest mode. This takes about 30 seconds on
a generic PC. Because this is a new block chain using Bitcoin's default
rules, the first blocks pay a block reward of 50 bitcoins. Unlike
mainnet, in regtest mode only the first 150 blocks pay a reward of 50 bitcoins.
However, a block must have 100 confirmations before that reward can be
spent, so we generate 101 blocks to get access to the coinbase
transaction from block #1.
{% endautocrossref %}
{% highlight bash %}
bitcoin-cli -regtest getbalance
50.00000000
{% endhighlight %}
{% autocrossref %}
Verify that we now have 50 bitcoins available to spend.
You can now use Bitcoin Core RPCs prefixed with `bitcoin-cli -regtest`<!--noref-->.
Regtest wallets and block chain state (chainstate) are saved in the `regtest`<!--noref-->
subdirectory of the Bitcoin Core configuration directory. You can safely
delete the `regtest`<!--noref--> subdirectory and restart Bitcoin Core to
start a new regtest. (See the [Developer Examples Introduction][devexamples] for default
configuration directory locations on various operating systems. Always back up
mainnet wallets before performing dangerous operations such as deleting.)
{% endautocrossref %}

1249
_includes/devdoc/example_transactions.md Normal file
View file

File diff suppressed because it is too large Load diff

12
_includes/devdoc/fragment_reviews_needed.md Normal file
View file

@ -0,0 +1,12 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
<!--Temporary disclaimer BEGIN-->
<div id="develdocdisclaimer" class="develdocdisclaimer"><div>
<b>BETA</b>: This documentation has not been extensively reviewed by Bitcoin experts and so likely contains numerous errors. Please use the <em>Issue</em> and <em>Edit</em> links on the bottom left menu to help us improve. <a href="#" onclick="disclaimerClose(event);">Click here</a> to close this disclaimer.
<a class="develdocdisclaimerclose" onclick="disclaimerClose(event);">X</a>
</div></div>
<script>disclaimerAutoClose();</script>
<!--Temporary disclaimer END-->

374
_includes/devdoc/guide_block_chain.md Normal file
View file

@ -0,0 +1,374 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/guide_block_chain.md" %}
## Block Chain
{% include helpers/subhead-links.md %}
{% autocrossref %}
The block chain provides Bitcoin's public ledger, an ordered and timestamped record
of transactions. This system is used to protect against double spending
and modification of previous transaction records.
Each full node in the Bitcoin network independently stores a block chain
containing only blocks validated by that node. When several nodes all
have the same blocks in their block chain, they are considered to be in
[consensus][/en/glossary/consensus]{:#term-consensus}{:.term}. The validation rules these
nodes follow to maintain consensus are called [consensus
rules][/en/glossary/consensus-rules]{:#term-consensus-rules}{:.term}. This section describes many of
the consensus rules used by Bitcoin Core.
{% endautocrossref %}
### Block Chain Overview
{% include helpers/subhead-links.md %}
{% autocrossref %}
![Block Chain Overview](/img/dev/en-blockchain-overview.svg)
The illustration above shows a simplified version of a block chain.
A [block][/en/glossary/block]{:#term-block}{:.term} of one or more new transactions
is collected into the transaction data part of a block.
Copies of each transaction are hashed, and the hashes are then paired,
hashed, paired again, and hashed again until a single hash remains, the
[merkle root][/en/glossary/merkle-root]{:#term-merkle-root}{:.term} of a merkle tree.
The merkle root is stored in the block header. Each block also
stores the hash of the previous block's header, chaining the blocks
together. This ensures a transaction cannot be modified without
modifying the block that records it and all following blocks.
Transactions are also chained together. Bitcoin wallet software gives
the impression that satoshis are sent from and to wallets, but
bitcoins really move from transaction to transaction. Each
transaction spends the satoshis previously received in one or more earlier
transactions, so the input of one transaction is the output of a
previous transaction.
![Transaction Propagation](/img/dev/en-transaction-propagation.svg)
A single transaction can create multiple outputs, as would be
the case when sending to multiple addresses, but each output of
a particular transaction can only be used as an input once in the
block chain. Any subsequent reference is a forbidden double
spend---an attempt to spend the same satoshis twice.
Outputs are tied to [transaction identifiers (TXIDs)][/en/glossary/txid]{:#term-txid}{:.term}, which are the hashes
of signed transactions.
Because each output of a particular transaction can only be spent once,
the outputs of all transactions included in the block chain can be categorized as either
[Unspent Transaction Outputs (UTXOs)][/en/glossary/unspent-transaction-output]{:#term-utxo}{:.term} or spent transaction outputs. For a
payment to be valid, it must only use UTXOs as inputs.
Ignoring coinbase transactions (described later), if the value of a
transaction's outputs exceed its inputs, the transaction will be
rejected---but if the inputs exceed the value of the outputs, any
difference in value may be claimed as a [transaction
fee][/en/glossary/transaction-fee]{:#term-transaction-fee}{:.term} by the Bitcoin
[miner][/en/glossary/mining]{:#term-miner}{:.term} who creates the block containing that
transaction.
For example, in the illustration above, each transaction spends 10,000 satoshis
fewer than it receives from its combined inputs, effectively paying a 10,000
satoshi transaction fee.
{% endautocrossref %}
### Proof Of Work
{% include helpers/subhead-links.md %}
{% autocrossref %}
The block chain is collaboratively maintained by anonymous peers on the network, so
Bitcoin requires that each block prove a significant amount of work was invested in
its creation to ensure that untrustworthy peers who want to modify past blocks have
to work harder than honest peers who only want to add new blocks to the
block chain.
Chaining blocks together makes it impossible to modify transactions included
in any block without modifying all following blocks. As a
result, the cost to modify a particular block increases with every new block
added to the block chain, magnifying the effect of the proof of work.
The [proof of work][/en/glossary/proof-of-work]{:#term-proof-of-work}{:.term} used in Bitcoin
takes advantage of the apparently random nature of cryptographic hashes.
A good cryptographic hash algorithm converts arbitrary data into a
seemingly-random number. If the data is modified in any way and
the hash re-run, a new seemingly-random number is produced, so there is
no way to modify the data to make the hash number predictable.
To prove you did some extra work to create a block, you must create a
hash of the block header which does not exceed a certain value. For
example, if the maximum possible hash value is <span
class="math">2<sup>256</sup> − 1</span>, you can prove that you
tried up to two combinations by producing a hash value less than <span
class="math">2<sup>255</sup></span>.
In the example given above, you will produce a successful hash on average every other try.
You can even estimate the probability
that a given hash attempt will generate a number below the [target][/en/glossary/nbits]{:#term-target}{:.term}
threshold.
Bitcoin assumes a linear probability that the lower it makes the target threshold, the more hash attempts (on average) will need to be tried.
New blocks will only be added to the block chain if their hash is at
least as challenging as a [difficulty][/en/glossary/difficulty]{:#term-difficulty}{:.term} value expected by the consensus protocol.
Every 2,016 blocks, the network uses timestamps stored in each
block header to calculate the number of seconds elapsed between generation
of the first and last of those last 2,016 blocks. The ideal value is
1,209,600 seconds (two weeks).
* If it took fewer than two weeks to generate the 2,016 blocks,
the expected difficulty value is increased proportionally (by as much
as 300%) so that the next 2,016 blocks should take exactly two weeks
to generate if hashes are checked at the same rate.
* If it took more than two weeks to generate the blocks, the expected
difficulty value is decreased proportionally (by as much as 75%) for
the same reason.
(Note: an off-by-one error in the Bitcoin Core implementation causes the
difficulty to be updated every 2,01*6* blocks using timestamps from only
2,01*5* blocks, creating a slight skew.)
Because each block header must hash to a value below the target
threshold, and because each block is linked to the block that
preceded it, it requires (on average) as much hashing power to
propagate a modified block as the entire Bitcoin network expended
between the time the original block was created and the present time.
Only if you acquired a majority of the network's hashing power
could you reliably execute such a [51 percent attack][/en/glossary/51-percent-attack]{:#term-51-attack}{:.term} against
transaction history (although, it should be noted, that even less than 50% of the hashing power still has a good chance of performing such attacks).
The block header provides several easy-to-modify fields, such as a
dedicated nonce field, so obtaining new hashes doesn't require waiting
for new transactions. Also, only the 80-byte block header is hashed for
proof-of-work, so including a large volume of transaction data in
a block does not slow down hashing with extra I/O, and adding additional
transaction data only requires the recalculation of the ancestor hashes in
the merkle tree.
{% endautocrossref %}
### Block Height And Forking
{% include helpers/subhead-links.md %}
{% autocrossref %}
Any Bitcoin miner who successfully hashes a block header to a value
below the target threshold can add the entire block to the block chain
(assuming the block is otherwise valid).
These blocks are commonly addressed
by their [block height][/en/glossary/block-height]{:#term-block-height}{:.term}---the number of blocks between them and the first Bitcoin
block (block 0, most commonly known as the [genesis block][/en/glossary/genesis-block]{:#term-genesis-block}{:.term}). For example,
block 2016 is where difficulty could have first been adjusted.
![Common And Uncommon Block Chain Forks](/img/dev/en-blockchain-fork.svg)
Multiple blocks can all have the same block height, as is common when
two or more miners each produce a block at roughly the same time. This
creates an apparent [fork][/en/glossary/fork]{:#term-fork}{:.term} in the block chain, as shown in the
illustration above.
When miners produce simultaneous blocks at the end of the block chain, each
node individually chooses which block to accept. In the absence of
other considerations, discussed below, nodes usually use the first
block they see.
Eventually a miner produces another block which attaches to only one of
the competing simultaneously-mined blocks. This makes that side of
the fork stronger than the other side.
Assuming a fork only contains valid
blocks, normal peers always follow the the most difficult chain
to recreate and throw away [stale blocks][/en/glossary/stale-block]{:#term-stale-block}{:.term} belonging to shorter forks.
(Stale blocks are also sometimes called orphans or orphan blocks<!--noref-->, but
those terms are also used for true orphan blocks without a known parent block.)
Long-term forks are possible if different miners work at cross-purposes,
such as some miners diligently working to extend the block chain at the
same time other miners are attempting a 51 percent attack to revise
transaction history.
Since multiple blocks can have the same height during a block chain fork, block
height should not be used as a globally unique identifier. Instead, blocks
are usually referenced by the hash of their header (often with the byte order reversed, and in hexadecimal).
{% endautocrossref %}
### Transaction Data
{% include helpers/subhead-links.md %}
{% autocrossref %}
Every block must include one or more transactions. The first one of these
transactions must be a coinbase transaction, also called a generation transaction, which should collect and
spend the block reward (comprised of a block subsidy and any transaction fees paid by transactions included in this block).
The UTXO of a coinbase transaction has the special condition that
it cannot be spent (used as an input) for at least 100 blocks. This temporarily
prevents a miner from spending the transaction fees and block reward from a
block that may later be determined to be stale (and therefore the coinbase transaction destroyed) after a block chain fork.
Blocks are not required to include any non-coinbase transactions, but
miners almost always do include additional transactions in order to
collect their transaction fees.
All transactions, including the coinbase transaction, are encoded into
blocks in binary rawtransaction format.
The rawtransaction format is hashed to create the transaction
identifier (txid). From these txids, the [merkle tree][/en/glossary/merkle-tree]{:#term-merkle-tree}{:.term} is constructed by pairing each
txid with one other txid and then hashing them together. If there are
an odd number of txids, the txid without a partner is hashed with a
copy of itself.
The resulting hashes themselves are each paired with one other hash and
hashed together. Any hash without a partner is hashed with itself. The
process repeats until only one hash remains, the merkle root.
For example, if transactions were merely joined (not hashed), a
five-transaction merkle tree would look like the following text diagram:
{% endautocrossref %}
~~~
ABCDEEEE .......Merkle root
/ \
ABCD EEEE
/ \ /
AB CD EE .......E is paired with itself
/ \ / \ /
A B C D E .........Transactions
~~~
{% autocrossref %}
As discussed in the Simplified Payment Verification (SPV) subsection,
the merkle tree allows clients to verify for
themselves that a transaction was included in a block by obtaining the
merkle root from a block header and a list of the intermediate hashes
from a full peer. The full peer does not need to be trusted: it is
expensive to fake block headers and the intermediate hashes cannot be faked or
the verification will fail.
For example, to verify transaction D was added to the
block, an SPV client only needs a copy of the C, AB, and EEEE hashes in addition to the
merkle root; the client doesn't need to know anything about any of the
other transactions. If the five transactions in this block were all at
the maximum size, downloading the entire block would require over
500,000 bytes---but downloading three hashes plus the block header
requires only 140 bytes.
Note: If identical txids are found within the same block, there is a possibility that the merkle tree may collide with a block with some or all duplicates removed due to how unbalanced merkle trees are implemented (duplicating the lone hash).
Since it is impractical to have separate transactions with identical txids, this does not impose a burden on honest software, but must be checked if the invalid status of a block is to be cached;
otherwise, a valid block with the duplicates eliminated could have the same merkle root and block hash, but be rejected by the cached invalid outcome, resulting in security bugs such as CVE-2012-2459.
{% endautocrossref %}
### Consensus Rule Changes
{% include helpers/subhead-links.md %}
{% autocrossref %}
To maintain consensus, all full nodes validate blocks using the same
consensus rules. However, sometimes the consensus rules are changed to
introduce new features or prevent network abuse. When the new rules are
implemented, there will likely be a period of time when non-upgraded
nodes follow the old rules and upgraded nodes follow the new rules,
creating two possible ways consensus can break:
1. A block following the new consensus rules is accepted by upgraded
nodes but rejected by non-upgraded nodes. For example, a new
transaction feature is used within a block: upgraded nodes understand
the feature and accept it, but non-upgraded nodes reject it because
it violates the old rules.
2. A block violating the new consensus rules is rejected by upgraded
nodes but accepted by non-upgraded nodes. For example, an abusive
transaction feature is used within a block: upgraded nodes reject it
because it violates the new rules, but non-upgraded nodes accept it
because it follows the old rules.
In the first case, rejection by non-upgraded nodes, mining software
which gets block chain data from those non-upgraded nodes refuses to
build on the same chain as mining software getting data from upgraded
nodes. This creates permanently divergent chains---one for non-upgraded
nodes and one for upgraded nodes---called a [hard
fork][/en/glossary/hard-fork]{:#term-hard-fork}{:.term}.
![Hard Fork](/img/dev/en-hard-fork.svg)
In the second case, rejection by upgraded nodes, it's possible to keep
the block chain from permanently diverging if upgraded nodes control a
majority of the hash rate. That's because, in this case, non-upgraded
nodes will accept as valid all the same blocks as upgraded nodes, so the
upgraded nodes can build a stronger chain that the non-upgraded nodes
will accept as the best valid block chain. This is called a [soft
fork][/en/glossary/soft-fork]{:#term-soft-fork}{:.term}.
![Soft Fork](/img/dev/en-soft-fork.svg)
Although a fork is an actual divergence in block chains, changes to the
consensus rules are often described by their potential to create either
a hard or soft fork. For example, "increasing the block size above 1 MB
requires a hard fork." In this example, an actual block chain fork is
not required---but it is a possible outcome.
**Resources:** [BIP16][], [BIP30][], and [BIP34][] were implemented as
changes which might have lead to soft forks. [BIP50][] describes both an
accidental hard fork, resolved by temporary downgrading the capabilities
of upgraded nodes, and an intentional hard fork when the temporary
downgrade was removed. A document from Gavin Andresen outlines [how
future rule changes may be
implemented](https://gist.github.com/gavinandresen/2355445).
{% endautocrossref %}
#### Detecting Forks
{% include helpers/subhead-links.md %}
{% autocrossref %}
Non-upgraded nodes may use and distribute incorrect information during
both types of forks, creating several situations which could lead to
financial loss. In particular, non-upgraded nodes may relay and accept
transactions that are considered invalid by upgraded nodes and so will
never become part of the universally-recognized best block chain.
Non-upgraded nodes may also refuse to relay blocks or transactions which
have already been added to the best block chain, or soon will be, and so
provide incomplete information.
<!-- paragraph below based on src/main.cpp CheckForkWarningConditions() -->
Bitcoin Core includes code that detects a hard fork by looking at block
chain proof of work. If a non-upgraded node receives block chain headers
demonstrating at least six blocks more proof of work than the best chain
it considers valid, the node reports an error in the `getinfo` RPC
results and runs the `-alertnotify` command if set. This warns the
operator that the non-upgraded node can't switch to what is likely the
best block chain.
Full nodes can also check block and transaction version numbers. If the
block or transaction version numbers seen in several recent blocks are
higher than the version numbers the node uses, it can assume it doesn't
use the current consensus rules. Bitcoin Core 0.10.0
reports this situation through the `getinfo` RPC and
`-alertnotify` command if set.
In either case, block and transaction data should not be relied upon if it comes from a node
that apparently isn't using the current consensus rules.
SPV clients which connect to full nodes can detect a likely hard fork by
connecting to several full nodes and ensuring that they're all on the
same chain with the same block height, plus or minus several blocks to
account for transmission delays and stale blocks. If there's a
divergence, the client can disconnect from nodes with weaker chains.
SPV clients should also monitor for block and transaction version number
increases to ensure they process received transactions and create new
transactions using the current consensus rules.
{% endautocrossref %}

289
_includes/devdoc/guide_contracts.md Normal file
View file

@ -0,0 +1,289 @@
{% comment %}
This file is licensed under the MIT License (MIT) available on
http://opensource.org/licenses/MIT.
{% endcomment %}
{% assign filename="_includes/devdoc/guide_contracts.md" %}
## Contracts
{% include helpers/subhead-links.md %}
{% autocrossref %}
Contracts are
transactions which use the decentralized Bitcoin system to enforce financial
agreements.
Bitcoin contracts can often be crafted to minimize dependency on outside
agents, such as the court system, which significantly decreases the risk
of dealing with unknown entities in financial transactions.
The following subsections will describe a variety of Bitcoin contracts
already in use. Because contracts deal with real people, not just
transactions, they are framed below in story format.
Besides the contract types described below, many other contract types
have been proposed. Several of them are collected on the [Contracts
page](https://en.bitcoin.it/wiki/Contracts) of the Bitcoin Wiki.
{% endautocrossref %}
### Escrow And Arbitration
{% include helpers/subhead-links.md %}
{% autocrossref %}
Charlie-the-customer wants to buy a product from Bob-the-businessman,
but neither of them trusts the other person, so they use a contract to
help ensure Charlie gets his merchandise and Bob gets his payment.
A simple contract could say that Charlie will spend satoshis to an
output which can only be spent if Charlie and Bob both sign the input
spending it. That means Bob won't get paid unless Charlie gets his
merchandise, but Charlie can't get the merchandise and keep his payment.
This simple contract isn't much help if there's a dispute, so Bob and
Charlie enlist the help of Alice-the-arbitrator to create an [escrow
contract][/en/glossary/escrow-contract]{:#term-escrow-contract}{:.term}. Charlie spends his satoshis
to an output which can only be spent if two of the three people sign the
input. Now Charlie can pay Bob if everything is ok, Bob can refund
Charlie's money if there's a problem, or Alice can arbitrate and decide
who should get the satoshis if there's a dispute.
To create a multiple-signature ([multisig][/en/glossary/multisig]{:#term-multisig}{:.term})
output, they each give the others a public key. Then Bob creates the
following [P2SH multisig][/en/glossary/p2sh-multisig]{:#term-p2sh-multisig}{:.term} redeem script:
{% endautocrossref %}
~~~
OP_2 [A's pubkey] [B's pubkey] [C's pubkey] OP_3 OP_CHECKMULTISIG
~~~
{% autocrossref %}
(Op codes to push the public keys onto the stack are not shown.)
`OP_2` and `OP_3` push the actual numbers 2 and 3 onto the
stack. `OP_2`
specifies that 2 signatures are required to sign; `OP_3` specifies that
3 public keys (unhashed) are being provided. This is a 2-of-3 multisig
pubkey script, more generically called a m-of-n pubkey script (where *m* is the
*minimum* matching signatures required and *n* in the *number* of public
keys provided).
Bob gives the redeem script to Charlie, who checks to make sure his
public key and Alice's public key are included. Then he hashes the
redeem script to create a P2SH redeem script and pays the satoshis to it. Bob
sees the payment get added to the block chain and ships the merchandise.
Unfortunately, the merchandise gets slightly damaged in transit. Charlie
wants a full refund, but Bob thinks a 10% refund is sufficient. They
turn to Alice to resolve the issue. Alice asks for photo evidence from
Charlie along with a copy of the redeem script Bob created and
Charlie checked.
After looking at the evidence, Alice thinks a 40% refund is sufficient,
so she creates and signs a transaction with two outputs, one that spends 60%
of the satoshis to Bob's public key and one that spends the remaining
40% to Charlie's public key.
In the signature script Alice puts her signature
and a copy of the unhashed serialized redeem script
that Bob created. She gives a copy of the incomplete transaction to
both Bob and Charlie. Either one of them can complete it by adding
his signature to create the following signature script:
{% endautocrossref %}
~~~
OP_0 [A's signature] [B's or C's signature] [serialized redeem script]
~~~
{% autocrossref %}
(Op codes to push the signatures and redeem script onto the stack are
not shown. `OP_0` is a workaround for an off-by-one error in the original
implementation which must be preserved for compatibility. Note that
the signature script must provide signatures in the same order as the
corresponding public keys appear in the redeem script. See the description in
[`OP_CHECKMULTISIG`][op_checkmultisig] for details.)
When the transaction is broadcast to the network, each peer checks the
signature script against the P2SH output Charlie previously paid,
ensuring that the redeem script matches the redeem script hash previously
provided. Then the redeem script is evaluated, with the two signatures
being used as input<!--noref--> data. Assuming the redeem script
validates, the two transaction outputs show up in Bob's and Charlie's
wallets as spendable balances.
However, if Alice created and signed a transaction neither of them would
agree to, such as spending all the satoshis to herself, Bob and Charlie
can find a new arbitrator and sign a transaction spending the satoshis
to another 2-of-3 multisig redeem script hash, this one including a public
key from that second arbitrator. This means that Bob and Charlie never
need to worry about their arbitrator stealing their money.
**Resource:** [BitRated](https://www.bitrated.com/) provides a multisig arbitration
service interface using HTML/JavaScript on a GNU AGPL-licensed website.
{% endautocrossref %}
### Micropayment Channel
{% include helpers/subhead-links.md %}
{% autocrossref %}
<!-- SOMEDAY: try to rewrite using a more likely real-world example without
making the text or illustration more complicated -->
Alice also works part-time moderating forum posts for Bob. Every time
someone posts to Bob's busy forum, Alice skims the post to make sure it
isn't offensive or spam. Alas, Bob often forgets to pay her, so Alice
demands to be paid immediately after each post she approves or rejects.
Bob says he can't do that because hundreds of small payments will cost
him thousands of satoshis in transaction fees, so Alice suggests they use a
[micropayment channel][]{:#term-micropayment-channel}{:.term}.
Bob asks Alice for her public key and then creates two transactions.
The first transaction pays 100 millibitcoins to a P2SH output whose
2-of-2 multisig redeem script requires signatures from both Alice and Bob.
This is the bond transaction.
Broadcasting this transaction would let Alice hold the millibitcoins
hostage, so Bob keeps this transaction private for now and creates a
second transaction.
The second transaction spends all of the first transaction's millibitcoins
(minus a transaction fee) back to Bob after a 24 hour delay enforced
by locktime. This is the refund transaction. Bob can't sign the refund transaction by himself, so he gives
it to Alice to sign, as shown in the
illustration below.
![Micropayment Channel Example](/img/dev/en-micropayment-channel.svg)
Alice checks that the refund transaction's locktime is 24 hours in the
future, signs it, and gives a copy of it back to Bob. She then asks Bob
for the bond transaction and checks that the refund transaction spends
the output of the bond transaction. She can now broadcast the bond
transaction to the network to ensure Bob has to wait for the time lock
to expire before further spending his millibitcoins. Bob hasn't actually
spent anything so far, except possibly a small transaction fee, and
he'll be able to broadcast the refund transaction in 24 hours for a
full refund.
Now, when Alice does some work worth 1 millibitcoin, she asks Bob to create
and sign a new version of the refund transaction. Version two of the
transaction spends 1 millibitcoin to Alice and the other 99 back to Bob; it does
not have a locktime, so Alice can sign it and spend it whenever she
wants. (But she doesn't do that immediately.)
Alice and Bob repeat these work-and-pay steps until Alice finishes for
the day, or until the time lock is about to expire. Alice signs the
final version of the refund transaction and broadcasts it, paying
herself and refunding any remaining balance to Bob. The next day, when
Alice starts work, they create a new micropayment channel.
If Alice fails to broadcast a version of the refund transaction before
its time lock expires, Bob can broadcast the first version and receive a
full refund. This is one reason micropayment channels are best suited to
small payments---if Alice's Internet service goes out for a few hours
near the time lock expiry, she could be cheated out of her payment.
Transaction malleability, discussed above in the Transactions section,
is another reason to limit the value of micropayment channels.
If someone uses transaction malleability to break the link between the
two transactions, Alice could hold Bob's 100 millibitcoins hostage even if she
hadn't done any work.
For larger payments, Bitcoin transaction fees are very low as a
percentage of the total transaction value, so it makes more sense to
protect payments with immediately-broadcast separate transactions.
**Resource:** The [bitcoinj][] Java library
provides a complete set of micropayment functions, an example
implementation, and [a
tutorial][bitcoinj micropayment tutorial]
all under an Apache license.
{% endautocrossref %}
### CoinJoin
{% include helpers/subhead-links.md %}
{% autocrossref %}
Alice is concerned about her privacy. She knows every transaction gets
added to the public block chain, so when Bob and Charlie pay her, they
can each easily track those satoshis to learn what Bitcoin
addresses she pays, how much she pays them, and possibly how many
satoshis she has left.
Alice isn't a criminal, she just wants plausible deniability about
where she has spent her satoshis and how many she has left, so she
starts up the Tor anonymity service on her computer and logs into an
IRC chatroom as "AnonGirl."
Also in the chatroom are "Nemo" and "Neminem." They collectively
agree to transfer satoshis between each other so no one besides them
can reliably determine who controls which satoshis. But they're faced
with a dilemma: who transfers their satoshis to one of the other two
pseudonymous persons first? The CoinJoin-style contract, shown in the
illustration below, makes this decision easy: they create a single
transaction which does all of the spending simultaneously, ensuring none
of them can steal the others' satoshis.
![Example CoinJoin Transaction](/img/dev/en-coinjoin.svg)
Each contributor looks through their collection of Unspent Transaction
Outputs (UTXOs) for 100 millibitcoins they can spend. They then each generate
a brand new public key and give UTXO details and pubkey hashes to the
facilitator. In this case, the facilitator is AnonGirl; she creates
a transaction spending each of the UTXOs to three equally-sized outputs.
One output goes to each of the contributors' pubkey hashes.
AnonGirl then signs her inputs using `SIGHASH_ALL` to ensure nobody can
change the input or output details. She gives the partially-signed
transaction to Nemo who signs his inputs the same way and passes it
to Neminem, who also signs it the same way. Neminem then broadcasts
the transaction to the peer-to-peer network, mixing all of the millibitcoins in
a single transaction.
As you can see in the illustration, there's no way for anyone besides
AnonGirl, Nemo, and Neminem to confidently determine who received
which output, so they can each spend their output with plausible
deniability.
Now when Bob or Charlie try to track Alice's transactions through the
block chain, they'll also see transactions made by Nemo and
Neminem. If Alice does a few more CoinJoins, Bob and Charlie might
have to guess which transactions made by dozens or hundreds of people
were actually made by Alice.
The complete history of Alice's satoshis is still in the block chain,
so a determined investigator could talk to the people AnonGirl
CoinJoined with to find out the ultimate origin of her satoshis and
possibly reveal AnonGirl as Alice. But against anyone casually browsing
block chain history, Alice gains plausible deniability.
The CoinJoin technique described above costs the participants a small
amount of satoshis to pay the transaction fee. An alternative
technique, purchaser CoinJoin, can actually save them satoshis and
improve their privacy at the same time.
AnonGirl waits in the IRC chatroom until she wants to make a purchase.
She announces her intention to spend satoshis and waits until someone
else wants to make a purchase, likely from a different merchant. Then
they combine their inputs the same way as before but set the outputs
to the separate merchant addresses so nobody will be able to figure
out solely from block chain history which one of them bought what from
the merchants.
Since they would've had to pay a transaction fee to make their purchases
anyway, AnonGirl and her co-spenders don't pay anything extra---but
because they reduced overhead by combining multiple transactions, saving
bytes, they may be able to pay a smaller aggregate transaction fee,
saving each one of them a tiny amount of satoshis.
**Resource:** An alpha-quality (as of this writing) implementation of decentralized
CoinJoin is [CoinMux](http://coinmux.com/), available under the Apache
license.
{% endautocrossref %}

Some files were not shown because too many files have changed in this diff Show more