mirror of
https://github.com/seigler/dash-docs
synced 2025-07-27 01:36:13 +00:00
Dev ref conversion (#2)
Developer reference/guide updates to this point * Update some reference documents - Adjust ref_intro to reference Dash - Start updating p2p network ref - Adjust some items in references.md to point to Dash URLs * Update P2P networking protocol versions and message headers sections Update subheading-links Update more items in references.md * Update inventories to include Dash specific items - Update references.md with them also Update disclaimer (Bitcoin -> Dash) * Remove reference to bitcoin mailing list from ref_intro * Add Spork/GetSporks message details Add placeholders for Dash specific messages - Added subsections for InstantSend, PrivateSend, Masternodes, and Governance * Some Bitcoin->Dash conversions - Update title / section name for Dev Doc/Dev Reference - Updated favicon * Updates for the Data Network section of P2P reference * Added Alert message details from Bitcoin back and removed feefilter * More updates for Control Messages section of P2P network - Bitcoin->Dash reference changes - Reject and Version message updates * InstantSend subsection of P2P reference detail - Added ix, txlvote message details and associated references * Governance subsection (P2P) - Start adding govobj, govobjvote details - Add spork references * Missed spork xref in previous * Governance (P2P) updates - Add details to govobjvote and govsync * Governance object P2P messages - Add additional description/details * PrivateSend P2P messages - Added details for dsa, dsc, dsf, dsi, dsq, dss, dssu, and dstx messages - Added references also - Hexdump examples for all but dsi and dss * PrivateSend P2P minor updates * Masternode P2P messages - Add descriptions - Add hexdump details * Masternode P2P messages (dseg, mnb, mnget, mnp, mnv, mnw, mnwb, ssc) - Add reference/crossref entries - Add message structure * P2P messages - minor formatting and corrections * Block chain reference - Version info updates * Update Block Chain reference (Headers) - Update version details - Update block reward info * Update Transactions reference - Add some Dash specific updates * Minor Transactions reference change * RPC reference updates * RPC reference updates - Added/removed commands to match available Dash commands * Core API updates * Renamed devdocs/bitcoin-core to dash-core - Updated developer-reference.md to point at new location * Update filename to use dash-core instead of bitcoin-core * Add Dash-specific GetAddressBalance RPC command and associated updates Update RPC quick reference list * Added cross reference/reference placeholders for remaining GetAddress... RPC commands Added RPC template placeholder files for remaining GetAddress... commands * Scripts for environment setup and frequently used builds * Add details for GetAddressDeltas/Mempool RPCs Update path in Makefile bitcoin-core -> dash-core * Add GetAddressTxids/Utxos details Update minor formatting, etc. for GetAddressBalance/Deltas/Mempool Changed reference to Dash Core and updated denominations for Dash * Misc minor cleanup * Work on updating existing Block Chain RPCs - GetBestBlockHash, GetBlock, GetBlockChainInfo, GetBlockCount, GetBlockHash * Continue updating existing Block Chain RPCs - GetBlockHeader, GetChainTips, GetDifficulty, GetMemPoolInfo, GetRawMemPool * Update RPCs quick-ref - Added descriptions for Dash - Updated description for Bitcoin related items for clarity * Comment out content of non-implemented Block chain RPCs (GetMemPoolAncestors, GetMemPoolDescendants, GetMemPoolEntry, PreciousBlock, PruneBlockChain) * Continue updating existing Block Chain RPCs - GetTxOut, GetTxOutProof, GetTxOutSetInfo, VerifyChain, VerifyTxOutProof Update previous block hash type to indicate X11 instead of double SHA256 * Add script to create basic RPC md file Set up empty GetBlockHashes/Headers and GetSpentInfo RPCs * Add GetBlockhashes details Minor correction in Empty RPC generation script * Add GetBlockHeaders details Minor formatting updates * Update Address Index related RPCs to indicate the necessity of enabling addressindex to use them * Actual details of GetBlockHeaders * Add details for GetSpentInfo * Update existing Control RPCs (GetInfo, Help, Stop) * Add Debug RPC * Expand empty RPC generation script to add example section and fix format * Added empty RPC files and cross-ref details for all Dash RPCs * Add details for some Dash RPCs - GetGovernanceInfo, GetPoolInfo, GetSuperblockBudget * Add details for MasternodeList RPC (Dash section) * Add details for MnSync RPC (Dash section) * Dash RPC updates - Add Result section to MasternodeList - Formatting updates to MnSync * Expand script to add placeholders for parameters/resuls/example * Add details for PrivateSend RPC (Dash section) * Update Generating RPCs - Added details back for GetGenerate/SetGenerate which were deprecated in Bitcoin * Formatting and example updates * Add result detail and example to GetBlockTemplate * Update existing Mining RPCs - GetMiningInfo, GetNetworkHashPs, PrioritiseTransaction, SubmitBlock * Minor formatting updates * Update most existing Network RPCs - AddNode, ClearBanned, DisconnectNode, GetAddedNodeInfo, GetConnectionCount, GetNetTotals,GetNetworkInfo, GetPeerInfo, ListBanned, Ping, SetBan - Added some norefs as needed (Network RPCs only) * Misc cleanup * SetNetworkActive (Network RPC) * Misc updates - Change logo - Disable some headers (alert, donation) - Disable footer * Governance updates - Add description of govsync to P2P guide - Updates to P2P reference * Governance - Add governance message SVG image - Typo fixes * Dseg updates - Added clarifying details regarding how to request single/all nodes - Ban warning * Minor governance updates * Governance updates / MN sync - Correct some reference links - Add MN sync info to guide - Update dseg, mnget, ssc, and govsync messages to include more detail * Governance updates - Guide updated to show both stages of govsync - Reference - Correcte ssc typo and add sync item detail - Update govobjvote to include detail about propagation - Update govsync details * Governance updates - More clarification on govsync (guide and reference) * Raw Transaction RPC - Previously uncommitted CreateRawTransaction update * Dash RPC (Gobject) - Add details for count and get sub-commands Also added description for govobj types * P2P messages - Spork updated to include verification details and a hexdump Minor typo / note updates * P2P Message - mnv - Draft details regarding use and operation * P2P message (mnv) - Additional detail updates based on info from Udjin Minor update to mnp * Guide - Masternode payment - Add section and start putting in details * P2P Messages - deprecated - Move deprecated messages to their own group * Misc minor non-content updates
This commit is contained in:
thephez
GitHub
parent
17c265f5fd
commit
703c54ffbc
183 changed files with 9570 additions and 1373 deletions
227
_includes/devdoc/dash-core/rpcs/intro.md
Normal file
227
_includes/devdoc/dash-core/rpcs/intro.md
Normal file
|
|
@ -0,0 +1,227 @@
|
|||
{% comment %}
|
||||
This file is licensed under the MIT License (MIT) available on
|
||||
http://opensource.org/licenses/MIT.
|
||||
{% endcomment %}
|
||||
{% assign filename="_includes/devdoc/dash-core/rpcs/intro.md" %}
|
||||
|
||||
### Remote Procedure Calls (RPCs)
|
||||
{% include helpers/subhead-links.md %}
|
||||
|
||||
{% autocrossref %}
|
||||
|
||||
Dash Core provides a remote procedure call (RPC) interface for various
|
||||
administrative tasks, wallet operations, and queries about network and block
|
||||
chain data.
|
||||
|
||||
If you start Dash Core using `dash-qt`, the RPC interface is disabled by
|
||||
default. To enable it, set `server=1` in `dash.conf` or supply the `-server`
|
||||
argument when invoking the program. If you start Dash Core using `dashd`,
|
||||
the RPC interface is enabled 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
|
||||
`dash.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 Dash Core configuration
|
||||
values.
|
||||
|
||||
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. Dash Core also ships with its own compiled C++ RPC client,
|
||||
`dash-cli`, located in the `bin` directory alongside `dashd` and
|
||||
`dash-qt`. The `dash-cli` program can be used as a command-line interface
|
||||
(CLI) to Dash Core or for making RPC calls from applications written in
|
||||
languages lacking a suitable native client. The remainder of this section
|
||||
describes the Dash Core RPC protocol in detail.
|
||||
|
||||
The Dash Core RPC service listens for HTTP `POST` requests on port 9998 in
|
||||
mainnet mode, 19998 in testnet, or 18332 in regtest mode. The port number can be changed
|
||||
by setting `rpcport` in `dash.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
|
||||
|----------------------|-----------------|-----------------------------|----------------
|
||||
| Request | object | Required<br>(exactly 1) | The JSON-RPC<!--noref--> request object
|
||||
| → <br>`jsonrpc` | number (real) | Optional<br>(0 or 1) | Version indicator for the JSON-RPC<!--noref--> request. Currently ignored by Dash Core.
|
||||
| → <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 method name (e.g. `getblock`). See the RPC section for a list of available methods.
|
||||
| → <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 method
|
||||
{:.ntpd}
|
||||
|
||||
In the table above and in other tables describing RPC input<!--noref--> and
|
||||
output<!--noref-->, we use the following conventions
|
||||
|
||||
* "→" 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 "Request" are unnamed in the actual JSON object
|
||||
|
||||
* Code-style names like `params` are literal strings that appear in the JSON
|
||||
object.
|
||||
|
||||
* "Type" is the JSON data type and the specific Dash Core type.
|
||||
|
||||
* "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.
|
||||
|
||||
|
||||
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 %}
|
||||
{
|
||||
"method": "getblockhash",
|
||||
"params": [0],
|
||||
"id": "foo"
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
The command to send this request using `dash-cli` is:
|
||||
|
||||
{% highlight bash %}
|
||||
dash-cli getblockhash 0
|
||||
{% endhighlight %}
|
||||
|
||||
Alternatively, we could `POST` this request using the cURL command-line program
|
||||
as follows:
|
||||
|
||||
{% highlight bash %}
|
||||
curl --user 'my_username:my_secret_password' --data-binary '''
|
||||
{
|
||||
"method": "getblockhash",
|
||||
"params": [0],
|
||||
"id": "foo"
|
||||
}''' \
|
||||
--header 'Content-Type: text/plain;' localhost:9998
|
||||
{% endhighlight %}
|
||||
|
||||
The HTTP response data for this request would be:
|
||||
|
||||
{% highlight json %}
|
||||
{
|
||||
"result": "00000ffd590b1485b3caadc19b22e6379c733355108f107a430458cdf3407ab6",
|
||||
"error": null,
|
||||
"id": "foo"
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
Note: In order to minimize its size, the raw JSON response from Dash Core
|
||||
doesn't include any extraneous whitespace characters. Here we've added
|
||||
whitespace to make the object more readable. Speaking of which, `dash-cli`
|
||||
also transforms the raw response to make it more human-readable. It:
|
||||
|
||||
- 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
|
||||
|
||||
Continuing with the example above, the output<!--noref--> from the `dash-cli`
|
||||
command would be simply:
|
||||
|
||||
{% highlight text %}
|
||||
00000ffd590b1485b3caadc19b22e6379c733355108f107a430458cdf3407ab6
|
||||
{% endhighlight %}
|
||||
|
||||
If there's an error processing a request, Dash 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": -8,
|
||||
"message": "Block height out of range"
|
||||
},
|
||||
"id": "foo"
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
If `dash-cli` encounters an error, it exits with a non-zero status code and
|
||||
outputs<!--noref--> the `error` field as text to the process's standard error
|
||||
stream:
|
||||
|
||||
{% highlight text %}
|
||||
error code: -8
|
||||
error message:
|
||||
Block height out of range
|
||||
{% endhighlight %}
|
||||
|
||||
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 `dash-cli`
|
||||
RPC client does not support batch requests.
|
||||
|
||||
{% highlight bash %}
|
||||
curl --user 'my_username:my_secret_password' --data-binary '''
|
||||
[
|
||||
{
|
||||
"method": "getblockhash",
|
||||
"params": [0],
|
||||
"id": "foo"
|
||||
},
|
||||
{
|
||||
"method": "getblockhash",
|
||||
"params": [1],
|
||||
"id": "foo2"
|
||||
}
|
||||
]''' \
|
||||
--header 'Content-Type: text/plain;' localhost:9998
|
||||
{% endhighlight %}
|
||||
|
||||
To keep this documentation compact and readable, the examples for each of the
|
||||
available RPC calls will be given as `dash-cli` commands:
|
||||
|
||||
{% highlight text %}
|
||||
dash-cli [options] <method name> <param1> <param2> ...
|
||||
{% endhighlight %}
|
||||
|
||||
This translates into an JSON-RPC<!--noref--> Request object of the form:
|
||||
|
||||
{% highlight json %}
|
||||
{
|
||||
"method": "<method name>",
|
||||
"params": [ "<param1>", "<param2>", "..." ],
|
||||
"id": "foo"
|
||||
}
|
||||
{% endhighlight %}
|
||||
|
||||
[{{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]
|
||||
Bitcoin Wiki article for details and example code.
|
||||
|
||||
{% endautocrossref %}
|
||||
Loading…
Add table
Add a link
Reference in a new issue