mirror of
https://github.com/seigler/dash-docs
synced 2025-07-27 09:46:12 +00:00
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.)
This commit is contained in:
David A. Harding
parent
8da411ba52
commit
51a5a1b24a
2 changed files with 157 additions and 0 deletions
|
|
@ -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:** 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 %}
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue