From 51a5a1b24a00145e3552ac4fbe9ef0bc5eff7a39 Mon Sep 17 00:00:00 2001 From: "David A. Harding" Date: Fri, 19 Dec 2014 16:04:14 -0500 Subject: [PATCH] Dev Docs: Briefly Describe JSON-RPC Format & bitcoin-cli Briefly describe the JSON-RPC 1.0 format as used by Bitcoin Core and how bitcoin-cli abstracts away some of the details. Also link to the Proper Money Handling wiki page. (This as a vanguard PR preparing the way for a larger overhaul of our RPC docs, including updating them for 0.10.) --- _includes/ref_core_rpc_intro.md | 154 ++++++++++++++++++++++++++++++++ _includes/references.md | 3 + 2 files changed, 157 insertions(+) diff --git a/_includes/ref_core_rpc_intro.md b/_includes/ref_core_rpc_intro.md index 3a44db07..3c7d5708 100644 --- a/_includes/ref_core_rpc_intro.md +++ b/_includes/ref_core_rpc_intro.md @@ -97,6 +97,160 @@ print "Internal-Byte-Order Hash: ", hash.encode('hex_codec') print "RPC-Byte-Order Hash: ", hash[::-1].encode('hex_codec') {% endhighlight %} +### JSON-RPC & Bitcoin-CLI +{% include helpers/subhead-links.md %} + +{% 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. + +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`). + +RPCs are made using the standard JSON-RPC 1.0 syntax, which sends several +standard arguments: + + +| Name | Type | Presence | Description +|----------------------|-----------------|-----------------------------|---------------- +| RPC | object | Required
(exactly 1) | An object containing the standard RPC arguments +| →`jsonrpc` | number (float) | 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 + +In table above and in other tables describing JSON-RPC input +and output, we use the following formatting + +* "→" 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. + +* "Plain Text" names (like "RPC" above) are unnamed in the actual + JSON-RPC + +* `literal` names (like `id` above) are the strings that appear in the + actual JSON-RPC + +* Type (specifics) are the general JSON-RPC 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.) + +For example, here is the JSON-RPC requesting the hash of the latest +block on the local best block chain: + +{% highlight json %} +{ + "jsonrpc": "1.0", + "id": "bitcoin.org developer documentation", + "method": "getbestblockhash", + "params": [] +} +{% endhighlight %} + +We can send that to a local Bitcoin Core running on testnet using cURL +with the following command: + +{% 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/ +{% endhighlight %} + +The output will be sent using the standard JSON-RPC 1.0 +format. For example (whitespace added): + +{% highlight json %} +{ + "result": "00000000bd68bfdf381efd5fff17c723d2bb645bcbb215a6e333d4204888e951", + "error": null, + "id": "bitcoin.org developer documentation" +} +{% endhighlight %} + +The standard JSON-RPC 1.0 result format is described below: + +| 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 + +For an example of the error output, here's the result +after passing an invalid address to the `sendtoaddress` RPC +(whitespace added): + +{% highlight json %} +{ + "result": null, + "error": { + "code": -5, + "message": "Invalid Bitcoin address" + }, + "id": "bitcoin.org developer documentation" +} +{% 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: + +{% highlight text %} +00000000bd68bfdf381efd5fff17c723d2bb645bcbb215a6e333d4204888e951 +{% 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`: + +{% highlight json %} +error: {"code":-5,"message":"Invalid Bitcoin address"} +{% 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 icon](/img/icons/icon_warning.svg) **Warning:** if you write +programs using the JSON-RPC interface, you must ensure they handle high-precision +floating point numbers correctly. See the [Proper Money Handling][] +Bitcoin Wiki article for details and example code. + +{% endautocrossref %} + ### Remote Procedure Calls (RPCs) {% include helpers/subhead-links.md %} diff --git a/_includes/references.md b/_includes/references.md index b16dbc3e..c362be3e 100644 --- a/_includes/references.md +++ b/_includes/references.md @@ -378,6 +378,7 @@ 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 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 @@ -392,6 +393,7 @@ http://opensource.org/licenses/MIT. [Payment Request Generator]: http://bitcoincore.org/~gavin/createpaymentrequest.php [Piotr Piasecki's testnet faucet]: https://tpfaucet.appspot.com/ [prime symbol]: https://en.wikipedia.org/wiki/Prime_%28symbol%29 +[proper money handling]: https://en.bitcoin.it/wiki/Proper_Money_Handling_%28JSON-RPC%29 [protobuf]: https://developers.google.com/protocol-buffers/ [python-bitcoinlib]: https://github.com/petertodd/python-bitcoinlib [python-blkmaker]: https://gitorious.org/bitcoin/python-blkmaker @@ -408,3 +410,4 @@ changes from moving the referenced object, but also update links periodically to point to recent code. Last update: 2014-11-12 --> [core bloom.cpp hash]: https://github.com/bitcoin/bitcoin/blob/cbf28c6619fe348a258dfd7d08bdbd2392d07511/src/bloom.cpp#L46 [MAX_SIZE]: https://github.com/bitcoin/bitcoin/blob/60abd463ac2eaa8bc1d616d8c07880dc53d97211/src/serialize.h#L23 +[rpcprotocol.h]: https://github.com/bitcoin/bitcoin/blob/f914f1a746d7f91951c1da262a4a749dd3ebfa71/src/rpcprotocol.h