joshua/dash-docs
1
0
Fork 0
mirror of https://github.com/seigler/dash-docs synced 2025-07-27 09:46:12 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge pull #1030: Polish and expand Bitcoin Core RPC interface intro

Browse source
This commit is contained in:
David A. Harding 2015-09-04 09:16:19 -04:00
commit e4b8f0c7dd
No known key found for this signature in database
GPG key ID: 4B29C30FF29EC4B7
2 changed files with 144 additions and 97 deletions
Download patch file Download diff file Expand all files Collapse all files

236
_includes/ref/bitcoin-core/rpcs/intro.md
View file

@ -9,153 +9,197 @@ http://opensource.org/licenses/MIT.
{% autocrossref %} {% autocrossref %}
Bitcoin Core provides a large number of Remote Procedure Calls (RPCs) Bitcoin Core provides a remote procedure call (RPC) interface for various
using a [HTTP JSON-RPC version 1.0][] interface. Any program can access administrative tasks, wallet operations, and queries about network and block
the RPCs using JSON-RPC, but Bitcoin Core also provides the chain data.
`bitcoin-cli` command to wrap the JSON-RPC access for Command Line
Interface (CLI) users. Most of the RPC examples in this documentation
use `bitcoin-cli` for simplicity, so this subsection describes raw
JSON-RPC interface and how the command-line interface translates it.
In order to start `bitcoind`, you will need to set a password for If you start Bitcoin Core using `bitcoin-qt`, the RPC interface is disabled by
JSON-RPC in the `bitcoin.conf` file. See the [Examples default. To enable it, set `server=1` in `bitcoin.conf` or supply the `-server`
Page][devexamples] for details. JSON-RPC starts on port 8332 for mainnet argument when invoking the program. If you start Bitcoin Core using `bitcoind`,
and 18332 for testnet and regtest. By default, `bitcoind` doesn't use a the RPC interface is enabled by default.
JSON-RPC user, but you can set one (see `bitcoind --help`).
The interface is not intended for public access and is only accessible The interface requires the user to provide a password for authenticating RPC
from localhost by default. 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.
RPCs are made using the standard JSON-RPC 1.0 syntax, which sends several Open-source client libraries for the RPC interface are readily available in most
standard arguments: 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 | Name | Type | Presence | Description
|----------------------|-----------------|-----------------------------|---------------- |----------------------|-----------------|-----------------------------|----------------
| RPC | object | Required<br>(exactly 1) | An object containing the standard RPC arguments | Request | object | Required<br>(exactly 1) | The JSON-RPC<!--noref--> request object
| → <br>`jsonrpc` | number (real) | Optional<br>(0 or 1) | The version of JSON-RPC used. Bitcoin Core currently ignores this, as it only supports version 1.0. Default is `1.0` | → <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 | Required<br>(exactly 1) | An arbitrary string that will be returned when the response is sent. May be set to an empty string ("") | → <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, such as `getbestblockhash`. See the RPC section for a list of available commands | → <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 | Required<br>(exactly 1) | An array containing parameters for the RPC. May be an empty array if allowed by the particular RPC | → <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 | → → <br>Parameter | *any* | Optional<br>(0 or more) | A parameter. May be any JSON type allowed by the particular RPC method
{:.ntpd} {:.ntpd}
In table above and in other tables describing JSON-RPC input<!--noref--> In the table above and in other tables describing RPC input<!--noref--> and
and output<!--noref-->, we use the following formatting output<!--noref-->, we use the following conventions
* "→" to indicate an argument that is the child of a JSON array or * "→" indicates an argument that is the child of a JSON array or JSON object.
JSON object. For example, "→ → Parameter" above means Parameter For example, "→ → Parameter" above means Parameter is the child of the
is the child of the `params` array which itself is a child of the `params` array which itself is a child of the Request object.
RPC array.
* "Plain Text" names (like "RPC" above) are unnamed in the actual * Plain-text names like "Request" are unnamed in the actual JSON object
JSON-RPC
* `literal` names (like `id` above) are the strings that appear in the * Code-style names like `params` are literal strings that appear in the JSON
actual JSON-RPC object.
* Type (specifics) are the general JSON-RPC type and the specific * "Type" is the JSON data type and the specific Bitcoin Core type.
Bitcoin Core type
* Required/Optional describe whether a field must be returned within its * "Presence" indicates whether or not a field must be present within its
containing array or object. (So an optional object may still have containing array or object. Note that an optional object may still have
required children.) required children.
For example, here is the JSON-RPC requesting the hash of the latest
block on the local best block chain: 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 %} {% highlight json %}
{ {
"jsonrpc": "1.0", "method": "getblockhash",
"id": "bitcoin.org developer documentation", "params": [0],
"method": "getbestblockhash", "id": "foo"
"params": []
} }
{% endhighlight %} {% endhighlight %}
We can send that to a local Bitcoin Core running on testnet using cURL The command to send this request using `bitcoin-cli` is:
with the following command:
{% highlight bash %} {% highlight bash %}
curl --user ':your_password' --data-binary ''' bitcoin-cli getblockhash 0
{
"jsonrpc": "1.0",
"id":"bitcoin.org developer documentation",
"method": "getbestblockhash",
"params": []
}''' \
-H 'content-type: text/plain;' http://127.0.0.1:18332/
{% endhighlight %} {% endhighlight %}
The output<!--noref--> will be sent using the standard JSON-RPC 1.0 Alternatively, we could `POST` this request using the cURL command-line program
format. For example (whitespace added): 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 %} {% highlight json %}
{ {
"result": "00000000bd68bfdf381efd5fff17c723d2bb645bcbb215a6e333d4204888e951", "result": "000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f",
"error": null, "error": null,
"id": "bitcoin.org developer documentation" "id": "foo"
} }
{% endhighlight %} {% endhighlight %}
The standard JSON-RPC 1.0 result format is described below: 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:
| Name | Type | Presence | Description - Adds whitespace indentation to JSON objects
|----------------------|-----------------|-----------------------------|---------------- - Expands escaped newline characters ("\n") into actual newlines
| Result | object | Required<br>(exactly 1) | An object describing the results - Returns only the value of the `result` field if there's no error
| → <br>`result` | *any* | Required<br>(exactly 1) | The results as any JSON data type. If an error occured, set to `null` - Strips the outer double-quotes around `result`s of type string
| → <br>`error` | null/object | Required<br>(exactly 1) | If no error occurred, set to `null`. If an error occured, an object describing the error - Returns only the `error` field if there's an error
| → → <br>`code` | number (int) | Required<br>(exactly 1) | The error code as set by the returning function and defined in Bitcoin Core's [rpcprotocol.h][]
| → → <br>`message` | string | Required<br>(exactly 1) | An attempt to describe the problem in human-readable text. May be an empty string (""). Bitcoin Core often returns help text with embedded newline strings ("\n"); `bitcoin-cli` can expand these to actual newlines
| → <br>`id` | string | Required<br>(exactly 1) | The arbitrary string passed in when the RPC was called
{:.ntpd}
For an example of the error output<!--noref-->, here's the result Continuing with the example above, the output<!--noref--> from the `bitcoin-cli`
after passing an invalid address to the `sendtoaddress` RPC command would be simply:
(whitespace added):
{% 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 %} {% highlight json %}
{ {
"result": null, "result": null,
"error": { "error": {
"code": -5, "code": -8,
"message": "Invalid Bitcoin address" "message": "Block height out of range"
}, },
"id": "bitcoin.org developer documentation" "id": "foo"
} }
{% endhighlight %} {% endhighlight %}
The `bitcoin-cli` command can save command line users a lot of typing If `bitcoin-cli` encounters an error, it exits with a non-zero status code and
compared to using cURL or another HTTP-sending command. For example, to outputs<!--noref--> the `error` field as text to the process's standard error
get the block hash we got before, we would use the following command: stream:
{% highlight bash %}
bitcoin-cli getbestblockhash
{% endhighlight %}
For non-error output<!--noref-->, `bitcoin-cli` will only display the
value of the `result` field, and if it's a string, `bitcoin-cli` will
remove its JSON quotation marks. For example, the result for the
command above:
{% highlight text %} {% highlight text %}
00000000bd68bfdf381efd5fff17c723d2bb645bcbb215a6e333d4204888e951 error: {"code": -8, "message": "Block height out of range"}
{% endhighlight %} {% endhighlight %}
For errors, `bitcoin-cli` will display only the `error` object. For Starting in Bitcoin Core version 0.7.0, the RPC interface supports request
example, the result of the invalid address command above as formatted by batching as described in [version 2.0 of the JSON-RPC
`bitcoin-cli`: 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 %} {% highlight json %}
error: {"code":-5,"message":"Invalid Bitcoin address"} {
"method": "<method name>",
"params": [ "<param1>", "<param2>", "..." ],
"id": "foo"
}
{% endhighlight %} {% endhighlight %}
Because `bitcoin-cli` abstracts away the parts of JSON-RPC we would need
to repeatedly describe in each RPC description below, we describe the
Bitcoin Core RPCs using `bitcoin-cli`. However, using an actual
programming interface to the full JSON-RPC will serve you much better
for automated tasks.
[{{WARNING}}][proper money handling]{:#term-proper-money-handling}{:.term} if you write [{{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 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] real numbers correctly. See the [Proper Money Handling][wiki proper money handling]

5
_includes/references.md
View file

@ -294,12 +294,15 @@ http://opensource.org/licenses/MIT.
[forum tech support]: https://bitcointalk.org/index.php?board=4.0 [forum tech support]: https://bitcointalk.org/index.php?board=4.0
[high-speed block relay network]: https://www.mail-archive.com/bitcoin-development@lists.sourceforge.net/msg03189.html [high-speed block relay network]: https://www.mail-archive.com/bitcoin-development@lists.sourceforge.net/msg03189.html
[HMAC-SHA512]: https://en.wikipedia.org/wiki/HMAC [HMAC-SHA512]: https://en.wikipedia.org/wiki/HMAC
[HTTP JSON-RPC version 1.0]: https://en.wikipedia.org/wiki/JSON-RPC [HTTP basic authentication]: https://en.wikipedia.org/wiki/Basic_access_authentication
[HTTP longpoll]: https://en.wikipedia.org/wiki/Push_technology#Long_polling [HTTP longpoll]: https://en.wikipedia.org/wiki/Push_technology#Long_polling
[IP-to-IP payment protocol]: https://en.bitcoin.it/wiki/IP_Transactions [IP-to-IP payment protocol]: https://en.bitcoin.it/wiki/IP_Transactions
[IPv4-mapped IPv6 addresses]: http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses [IPv4-mapped IPv6 addresses]: http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses
[irc channels]: https://en.bitcoin.it/wiki/IRC_channels [irc channels]: https://en.bitcoin.it/wiki/IRC_channels
[JSON-RPC version 1.0]: http://json-rpc.org/wiki/specification
[JSON-RPC request batching]: http://www.jsonrpc.org/specification#batch
[libblkmaker]: https://github.com/bitcoin/libblkmaker [libblkmaker]: https://github.com/bitcoin/libblkmaker
[localhost]: https://en.wikipedia.org/wiki/Localhost
[makeseeds script]: https://github.com/bitcoin/bitcoin/tree/master/contrib/seeds [makeseeds script]: https://github.com/bitcoin/bitcoin/tree/master/contrib/seeds
[murmur3]: https://en.wikipedia.org/wiki/MurmurHash [murmur3]: https://en.wikipedia.org/wiki/MurmurHash
[man-in-the-middle]: https://en.wikipedia.org/wiki/Man-in-the-middle_attack [man-in-the-middle]: https://en.wikipedia.org/wiki/Man-in-the-middle_attack