diff --git a/_includes/ref/bitcoin-core/rpcs/intro.md b/_includes/ref/bitcoin-core/rpcs/intro.md
index 4b891761..813904b8 100644
--- a/_includes/ref/bitcoin-core/rpcs/intro.md
+++ b/_includes/ref/bitcoin-core/rpcs/intro.md
@@ -9,153 +9,197 @@ http://opensource.org/licenses/MIT.
{% autocrossref %}
-Bitcoin Core provides a large number of Remote Procedure Calls (RPCs)
-using a [HTTP JSON-RPC version 1.0][] interface. Any program can access
-the RPCs using JSON-RPC, but Bitcoin Core also provides the
-`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.
+Bitcoin Core provides a remote procedure call (RPC) interface for various
+administrative tasks, wallet operations, and queries about network and block
+chain data.
-In order to start `bitcoind`, you will need to set a password for
-JSON-RPC in the `bitcoin.conf` file. See the [Examples
-Page][devexamples] for details. JSON-RPC starts on port 8332 for mainnet
-and 18332 for testnet and regtest. By default, `bitcoind` doesn't use a
-JSON-RPC user, but you can set one (see `bitcoind --help`).
+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 is not intended for public access and is only accessible
-from localhost 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.
-RPCs are made using the standard JSON-RPC 1.0 syntax, which sends several
-standard arguments:
+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 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
|----------------------|-----------------|-----------------------------|----------------
-| RPC | object | Required
(exactly 1) | An object containing the standard RPC arguments
-| →
`jsonrpc` | number (real) | Optional
(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`
-| →
`id` | string | Required
(exactly 1) | An arbitrary string that will be returned when the response is sent. May be set to an empty string ("")
-| →
`method` | string | Required
(exactly 1) | The RPC, such as `getbestblockhash`. See the RPC section for a list of available commands
-| →
`params` | array | Required
(exactly 1) | An array containing parameters for the RPC. May be an empty array if allowed by the particular RPC
-| → →
Parameter | *any* | Optional
(0 or more) | A parameter. May be any JSON type allowed by the particular RPC
+| Request | object | Required
(exactly 1) | The JSON-RPC request object
+| →
`jsonrpc` | number (real) | Optional
(0 or 1) | Version indicator for the JSON-RPC request. Currently ignored by Bitcoin Core.
+| →
`id` | string | Optional
(0 or 1) | An arbitrary string that will be returned with the response. May be omitted or set to an empty string ("")
+| →
`method` | string | Required
(exactly 1) | The RPC method name (e.g. `getblock`). See the RPC section for a list of available methods.
+| →
`params` | array | Optional
(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.
+| → →
Parameter | *any* | Optional
(0 or more) | A parameter. May be any JSON type allowed by the particular RPC method
{:.ntpd}
-In table above and in other tables describing JSON-RPC input
-and output, we use the following formatting
+In the table above and in other tables describing RPC input and
+output, we use the following conventions
-* "→" to indicate 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
- RPC array.
+* "→" 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 "RPC" above) are unnamed in the actual
- JSON-RPC
+* Plain-text names like "Request" are unnamed in the actual JSON object
-* `literal` names (like `id` above) are the strings that appear in the
- actual JSON-RPC
+* Code-style names like `params` are literal strings that appear in the JSON
+ object.
-* Type (specifics) are the general JSON-RPC type and the specific
- Bitcoin Core type
+* "Type" is the JSON data type and the specific Bitcoin Core type.
-* Required/Optional describe whether a field must be returned within its
- containing array or object. (So an optional object may still have
- required children.)
+* "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.
-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
(exactly 1) | The JSON-RPC response object.
+| →
`result` | *any* | Required
(exactly 1) | The RPC output whose type varies by call. Has value `null` if an error occurred.
+| →
`error` | null/object | Required
(exactly 1) | An object describing the error if one occurred, otherwise `null`.
+| → →
`code` | number (int) | Required
(exactly 1) | The error code returned by the RPC function call. See [rpcprotocol.h][] for a full list of error codes and their meanings.
+| → →
`message` | string | Required
(exactly 1) | A text description of the error. May be an empty string ("").
+| →
`id` | string | Required
(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 request object for the hash of
+the genesis block:
{% highlight json %}
{
- "jsonrpc": "1.0",
- "id": "bitcoin.org developer documentation",
- "method": "getbestblockhash",
- "params": []
+ "method": "getblockhash",
+ "params": [0],
+ "id": "foo"
}
{% endhighlight %}
-We can send that to a local Bitcoin Core running on testnet using cURL
-with the following command:
+The command to send this request using `bitcoin-cli` is:
{% highlight bash %}
-curl --user ':your_password' --data-binary '''
- {
- "jsonrpc": "1.0",
- "id":"bitcoin.org developer documentation",
- "method": "getbestblockhash",
- "params": []
- }''' \
- -H 'content-type: text/plain;' http://127.0.0.1:18332/
+bitcoin-cli getblockhash 0
{% endhighlight %}
-The output will be sent using the standard JSON-RPC 1.0
-format. For example (whitespace added):
+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": "00000000bd68bfdf381efd5fff17c723d2bb645bcbb215a6e333d4204888e951",
+ "result": "000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f",
"error": null,
- "id": "bitcoin.org developer documentation"
+ "id": "foo"
}
{% 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
-|----------------------|-----------------|-----------------------------|----------------
-| Result | object | Required
(exactly 1) | An object describing the results
-| →
`result` | *any* | Required
(exactly 1) | The results as any JSON data type. If an error occured, set to `null`
-| →
`error` | null/object | Required
(exactly 1) | If no error occurred, set to `null`. If an error occured, an object describing the error
-| → →
`code` | number (int) | Required
(exactly 1) | The error code as set by the returning function and defined in Bitcoin Core's [rpcprotocol.h][]
-| → →
`message` | string | Required
(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
-| →
`id` | string | Required
(exactly 1) | The arbitrary string passed in when the RPC was called
-{:.ntpd}
+- 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
-For an example of the error output, here's the result
-after passing an invalid address to the `sendtoaddress` RPC
-(whitespace added):
+Continuing with the example above, the output 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": -5,
- "message": "Invalid Bitcoin address"
+ "code": -8,
+ "message": "Block height out of range"
},
- "id": "bitcoin.org developer documentation"
+ "id": "foo"
}
{% endhighlight %}
-The `bitcoin-cli` command can save command line users a lot of typing
-compared to using cURL or another HTTP-sending command. For example, to
-get the block hash we got before, we would use the following command:
-
-{% highlight bash %}
-bitcoin-cli getbestblockhash
-{% endhighlight %}
-
-For non-error output, `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:
+If `bitcoin-cli` encounters an error, it exits with a non-zero status code and
+outputs the `error` field as text to the process's standard error
+stream:
{% highlight text %}
-00000000bd68bfdf381efd5fff17c723d2bb645bcbb215a6e333d4204888e951
+error: {"code": -8, "message": "Block height out of range"}
{% endhighlight %}
-For errors, `bitcoin-cli` will display only the `error` object. For
-example, the result of the invalid address command above as formatted by
-`bitcoin-cli`:
+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] ...
+{% endhighlight %}
+
+This translates into an JSON-RPC Request object of the form:
{% highlight json %}
-error: {"code":-5,"message":"Invalid Bitcoin address"}
+{
+ "method": "",
+ "params": [ "", "", "..." ],
+ "id": "foo"
+}
{% 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
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]
diff --git a/_includes/references.md b/_includes/references.md
index ff53d2cb..6f6ca89a 100644
--- a/_includes/references.md
+++ b/_includes/references.md
@@ -294,12 +294,15 @@ http://opensource.org/licenses/MIT.
[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
[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
[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
[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
+[localhost]: https://en.wikipedia.org/wiki/Localhost
[makeseeds script]: https://github.com/bitcoin/bitcoin/tree/master/contrib/seeds
[murmur3]: https://en.wikipedia.org/wiki/MurmurHash
[man-in-the-middle]: https://en.wikipedia.org/wiki/Man-in-the-middle_attack