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

@@ -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<br>(exactly 1)     | An object containing the standard RPC arguments
+| →`jsonrpc`           | number (float)  | 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`
+| →`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 ("")
+| →`method`            | string          | Required<br>(exactly 1)     | The RPC, such as `getbestblockhash`.  See the RPC section for a list of available commands
+| →`params`            | array           | Required<br>(exactly 1)     | An array containing parameters for the RPC.  May be an empty array if allowed by the particular RPC
+| →→Parameter          | *any*           | Optional<br>(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<!--noref-->
+and output<!--noref-->, 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<!--noref--> 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<br>(exactly 1)     | An object describing the results
+| →`result`            | *any*           | Required<br>(exactly 1)     | The results as any JSON data type.  If an error occured, set to `null`
+| →`error`             | null/object     | Required<br>(exactly 1)     | If no error occurred, set to `null`.  If an error occured, an object describing the error
+| →→`code`             | number (int)    | Required<br>(exactly 1)     | The error code as set by the returning function and defined in Bitcoin Core's [rpcprotocol.h][]
+| →→`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
+| →`id`                | string          | Required<br>(exactly 1)     | The arbitrary string passed in when the RPC was called
+
+For an example of the error output<!--noref-->, 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<!--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 %}
+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 %}
 

_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