Skip to content

Commit f4b556a

Browse files
thephezthephez
committed
docs: import v21.0.0 core docs (#417)
* docs: import v21.0.0 core docs From dashpay/docs-core@37c8850 * docs: update index to include local core docs * build: update conf Remove unnecessary core intersphinx connection Remove unnecessary core external link Add some files to ignore * docs: convert core intersphinx links to local Previously these links to labels were in a separate project and had to be referred to using intersphinx. Now that core docs are in the same repo, the links are internal to the project and don't require intersphinx mapping.
1 parent 792b966 commit f4b556a

File tree

351 files changed

+48225
-56
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

351 files changed

+48225
-56
lines changed

‎conf.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,8 @@
7373
'README.md',
7474
'.devcontainer',
7575
'transifex',
76+
'docs/core/api/ai-prompt.md',
77+
'docs/img/dev/gifs/README.md',
7678
'docs/user/wallets/electrum/dip3_p2sh_howto.md',
7779
'venv'
7880
]
@@ -116,7 +118,6 @@
116118

117119
# -- intersphinx configuration -----------------------------------------------
118120
intersphinx_mapping = {
119-
"core": ("https://docs.dash.org/projects/core/en/stable/", None),
120121
"platform": ("https://docs.dash.org/projects/platform/en/stable/", None),
121122
}
122123

@@ -139,7 +140,6 @@
139140
#
140141
html_theme_options = {
141142
"external_links": [
142-
{"name": "Core docs", "url": "https://docs.dash.org/projects/core/en/stable/docs/index.html"},
143143
{"name": "Platform docs", "url": "https://docs.dash.org/projects/platform/en/stable/docs/index.html"},
144144
{"name": "Dash.org", "url": "https://www.dash.org"},
145145
{"name": "Forum", "url": "https://www.dash.org/forum"},

‎docs/core/api/ai-prompt.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
## Check documentation against Core help output
2+
3+
Compare this documentation
4+
```
5+
INSERT MARKDOWN TABLE FROM DOCS HERE
6+
```
7+
8+
With the actual help output
9+
```
10+
INSERT "HELP <RPCNAME>" OUTPUT HERE
11+
```
12+
13+
Only list any discrepancies (including parameters and/or response fields that have changed to be deprecated) and output markdown table entries in a copyable code block for items missing from the documentation. Use field descriptions from the provided help output without modifying them.
14+
15+
## Remove the excess whitespace at the end of tables
16+
17+
Remove the whitespace padding from the last column of this markdown table. do not worry about alignment of the end of the line but do include the ending "|" with a single space before it
18+
19+
## Create documentation for a new RPC
20+
21+
Use this RPC documentation as a template to create documentation for new RPCs:
22+
23+
```## ImportMulti
24+
25+
:::{note}
26+
Requires [wallet](../resources/glossary.md#wallet) support (**unavailable on masternodes**). Wallet must be unlocked.
27+
:::
28+
29+
_Added in Dash Core 0.12.3 / Bitcoin Core 0.14.0_
30+
31+
The [`importmulti` RPC](../api/remote-procedure-calls-wallet.md#importmulti) imports addresses or scripts (with private keys, public keys, or P2SH redeem scripts) and optionally performs the minimum necessary rescan for all imports.
32+
33+
_Parameter #1---the addresses/scripts to import_
34+
35+
| Name | Type | Presence | Description|
36+
| --------------------- | --------------------- | ----------------------- | -----------|
37+
| Imports | array | Required<br>(exactly 1) | An array of JSON objects, each one being an address or script to be imported |
38+
| → Import | object | Required<br>(1 or more) | A JSON object describing a particular import |
39+
| → →<br>`scriptPubKey` | string (hex) | Optional<br>(0 or 1) | The script (string) to be imported. Must have either this field or `address` below |
40+
| → →<br>`address` | string (base58) | Optional<br>(0 or 1) | The P2PKH or P2SH address to be imported. Must have either this field or `scriptPubKey` above |
41+
| → →<br>`timestamp` | number (int) / string | Required<br>(exactly 1) | The creation time of the key in Unix epoch time or the string “now” to substitute the current synced block chain time. The timestamp of the oldest key will determine how far back block chain rescans need to begin. Specify `now` to bypass scanning for keys which are known to never have been used. Specify `0` to scan the entire block chain. Blocks up to 2 hours before the earliest key creation time will be scanned |
42+
| → →<br>`redeemscript` | string | Optional<br>(0 or 1) | A redeem script. Only allowed if either the `address` field is a P2SH address or the `scriptPubKey` field is a P2SH scriptPubKey |
43+
| → →<br>`pubkeys` | array | Optional<br>(0 or 1) | Array of strings giving pubkeys that must occur in the scriptPubKey or redeemscript |
44+
| → →<br>`keys` | array | Optional<br>(0 or 1) | Array of strings giving private keys whose corresponding public keys must occur in the scriptPubKey or redeemscript |
45+
| → →<br>`internal` | bool | Optional<br>(0 or 1) | Stating whether matching outputs should be treated as change rather than incoming payments. The default is `false` |
46+
| → →<br>`watchonly` | bool | Optional<br>(0 or 1) | Stating whether matching outputs should be considered watched even when they're not spendable. This is only allowed if keys are empty. The default is `false` |
47+
| → →<br>`label` | string | Optional<br>(0 or 1) | Label to assign to the address, only allowed with `internal` set to `false`. The default is an empty string (“”) |
48+
49+
_Parameter #2---options regarding the import_
50+
51+
| Name | Type | Presence | Description |
52+
| -------------- | ------ | -------------------- | ----------- |
53+
| Option | object | Optional<br>(0 or 1) | JSON object with options regarding the import |
54+
| → <br>`rescan` | bool | Optional<br>(0 or 1) | Set to `true` (the default) to rescan the entire local block chain for transactions affecting any imported address or script. Set to `false` to not rescan after the import. Rescanning may take a considerable amount of time and may require re-downloading blocks if using block chain pruning |
55+
56+
_Result---execution result_
57+
58+
| Name | Type | Presence | Description |
59+
| ------------------- | --------------- | ----------------------- | ----------------------------------------------------------------------------------------- |
60+
| `result` | array | Required<br>(exactly 1) | An array of JSON objects, with each object describing the execution result of each import |
61+
| → Result | object | Required<br>(1 or more) | A JSON object describing the execution result of an imported address or script |
62+
| → → <br>`success` | string | Required<br>(exactly 1) | Displays `true` if the import has been successful or `false` if it failed |
63+
| → → <br>`error` | string : object | Optional<br>(0 or 1) | A JSON object containing details about the error. Only displayed if the import fails |
64+
| → → → <br>`code` | number (int) | Optional<br>(0 or 1) | The error code |
65+
| → → → <br>`message` | string | Optional<br>(0 or 1) | The error message |
66+
67+
_Example from Dash Core 0.12.3_
68+
69+
Import the address `ycCsAUKsjdmoP4qAXiS1cjYA4ixM48zJWe` (giving it a label and scanning the entire block chain) and the scriptPubKey `76a9146cf5870411edc31ba5630d61c7cddff55b884fda88ac` (giving a specific timestamp and label):
70+
71+
```bash
72+
dash-cli importmulti '
73+
[
74+
{
75+
"scriptPubKey" : { "address": "ycCsAUKsjdmoP4qAXiS1cjYA4ixM48zJWe" },
76+
"timestamp" : 0,
77+
"label" : "Personal"
78+
},
79+
{
80+
"scriptPubKey" : "76a9146cf5870411edc31ba5630d61c7cddff55b884fda88ac",
81+
"timestamp" : 1493912405,
82+
"label" : "TestFailure"
83+
}
84+
]' '{ "rescan": true }'
85+
```
86+
87+
Result (scriptPubKey import failed because `internal` was not set to `true`):
88+
89+
```json
90+
[
91+
{
92+
"success": true
93+
},
94+
{
95+
"success": false,
96+
"error": {
97+
"code": -8,
98+
"message": "Internal must be set for hex scriptPubKey"
99+
}
100+
}
101+
]
102+
```
103+
104+
_See also_
105+
106+
* [ImportPrivKey](../api/remote-procedure-calls-wallet.md#importprivkey): adds a private key to your wallet. The key should be formatted in the wallet import format created by the [`dumpprivkey` RPC](../api/remote-procedure-calls-wallet.md#dumpprivkey).
107+
* [ImportAddress](../api/remote-procedure-calls-wallet.md#importaddress): adds an address or pubkey script to the wallet without the associated private key, allowing you to watch for transactions affecting that address or pubkey script without being able to spend any of its outputs.
108+
* [ImportWallet](../api/remote-procedure-calls-wallet.md#importwallet): imports private keys from a file in wallet dump file format (see the [`dumpwallet` RPC](../api/remote-procedure-calls-wallet.md#dumpwallet)). These keys will be added to the keys currently in the wallet. This call may need to rescan all or parts of the block chain for transactions affecting the newly-added keys, which may take several minutes.
109+
```
110+
111+
112+
Create documentation for the following new RPC using the style of previously provided RPC documentation as a template:
113+
114+
```
115+
INSERT "HELP <RPCNAME>" OUTPUT HERE
116+
```

‎docs/core/api/dash-core-apis-hash-byte-order.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
```{eval-rst}
2+
.. meta::
3+
:title: Hash Byte Order
4+
:description: Dash Core RPCs accept and return the byte-wise reverse of computed SHA-256 hash values. Dash Core's RPCs use the byte-wise reverse for hashes.
5+
```
6+
7+
# Hash Byte Order
8+
9+
Dash Core RPCs accept and return the byte-wise reverse of computed SHA-256 hash values. For example, the Unix `sha256sum` command displays the SHA256(SHA256()) hash of mainnet block 300,000's header as:
10+
11+
``` shell
12+
> /bin/echo -n '020000007ef055e1674d2e6551dba41cd214debbee34aeb544c7ec670000000000000000d3998963f80c5bab43fe8c26228e98d030edf4dcbe48a666f5c39e2d7a885c9102c86d536c890019593a470d' \
13+
| xxd -r -p \
14+
| sha256sum -b \
15+
| xxd -r -p \
16+
| sha256sum -b
17+
18+
5472ac8b1187bfcf91d6d218bbda1eb2405d7c55f1f8cc820000000000000000 (Resulting hash)
19+
```
20+
21+
The result above is also how the hash appears in the previous-header-hash part of [block](../resources/glossary.md#block) 300,001's header:
22+
23+
<pre>02000000<b>5472ac8b1187bfcf91d6d218bbda1eb2405d7c55f1f8cc82000\
24+
0000000000000</b>ab0aaa377ca3f49b1545e2ae6b0667a08f42e72d8c24ae\
25+
237140e28f14f3bb7c6bcc6d536c890019edd83ccf</pre>
26+
27+
However, Dash Core's RPCs use the byte-wise reverse for hashes, so if you want to get information about block 675,776 using the [`getblock` RPC](../api/remote-procedure-calls-blockchain.md#getblock), you need to reverse the requested hash:
28+
29+
``` shell
30+
> dash-cli getblock \
31+
000000000000327a66cd1011b2d1defd1417b7d9e39b439e8e67ba996ee92602
32+
```
33+
34+
:::{note}
35+
Hex representation uses two characters to display each byte of data, which is why the reversed string looks somewhat mangled.
36+
:::
37+
38+
The rationale for the reversal is unknown, but it likely stems from Dash Core's use of hashes (which are byte arrays in C++) as integers for the purpose of determining whether the hash is below the network target. Whatever the reason for reversing header hashes, the reversal also extends to other hashes used in RPCs, such as [TXIDs](../resources/glossary.md#transaction-identifiers) and merkle roots.
39+
40+
As header hashes and TXIDs are widely used as global identifiers in other Dash software, this reversal of hashes has become the standard way to refer to certain objects. The table below should make clear where each byte order is used.
41+
42+
| Data | Internal Byte Order | RPC Byte Order |
43+
|---------------|---------------------|-----------------|
44+
| Example: SHA256(SHA256(0x00)) | Hash: 1406...539a | Hash: 9a53...0614 |
45+
|---------------|---------------------|-----------------|
46+
| Header Hashes: SHA256(SHA256(block header)) | Used when constructing block headers | Used by RPCs such as `getblock`; widely used in block explorers |
47+
|---------------|---------------------|-----------------|
48+
| Merkle Roots: SHA256(SHA256(TXIDs and merkle rows)) | Used when constructing block headers | Returned by RPCs such as `getblock` |
49+
|---------------|---------------------|-----------------|
50+
| TXIDs: SHA256(SHA256(transaction)) | Used in transaction inputs | Used by RPCs such as `gettransaction` and transaction data parts of `getblock`; widely used in wallet programs |
51+
|---------------|---------------------|-----------------|
52+
| P2PKH Hashes: RIPEMD160(SHA256(pubkey)) | Used in both addresses and pubkey scripts | **N/A:** RPCs use addresses which use internal byte order |
53+
|---------------|---------------------|-----------------|
54+
| P2SH Hashes: RIPEMD160(SHA256(redeem script)) | Used in both addresses and pubkey scripts | **N/A:** RPCs use addresses which use internal byte order |
55+
|---------------|---------------------|-----------------|
56+
57+
:::{note}
58+
Note: RPCs which return raw results, such as `getrawtransaction` or the raw mode of `getblock`, always display hashes as they appear in blocks ([internal byte order](../resources/glossary.md#internal-byte-order)).
59+
:::
60+
61+
The code below may help you check byte order by generating hashes from raw hex.
62+
63+
``` python
64+
from sys import byteorder
65+
from hashlib import sha256
66+
import codecs
67+
68+
decode_hex = codecs.getdecoder('hex_codec')
69+
encode_hex = codecs.getencoder('hex_codec')
70+
71+
# You can put in $data an 80-byte block header to get its header hash,
72+
# or a raw transaction to get its txid
73+
data = decode_hex('00')[0]
74+
data_hash = sha256(sha256(data).digest()).digest()
75+
76+
print("Warning: this code only tested on a little-endian x86_64 arch")
77+
print()
78+
print("System byte order: ", byteorder)
79+
print("Internal-Byte-Order Hash: ", encode_hex(data_hash)[0])
80+
print("RPC-Byte-Order Hash: ", encode_hex(data_hash[::-1])[0])
81+
```

‎docs/core/api/http-rest-quick-reference.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Quick Reference
2+
3+
* [GET Block](../api/http-rest-requests.md#get-block) gets a block with a particular header hash from the local block database either as a JSON object or as a serialized block. _Updated in Bitcoin Core 0.13.0_
4+
* [GET Block/NoTxDetails](../api/http-rest-requests.md#get-blocknotxdetails) gets a block with a particular header hash from the local block database either as a JSON object or as a serialized block. The JSON object includes TXIDs for transactions within the block rather than the complete transactions [GET block](../api/http-rest-requests.md#get-block) returns. _Updated in Bitcoin Core 0.13.0_
5+
* [GET BlockHashByHeight](../api/http-rest-requests.md#get-blockhashbyheight) returns the hash of a block in best-block-chain at the height provided. The hash can be returned as a JSON object or serialized as binary or hex. _Added in Dash Core 18.0.0_
6+
* [GET ChainInfo](../api/http-rest-requests.md#get-chaininfo) returns information about the current state of the block chain. _Updated in Bitcoin Core 0.12.0_
7+
* [GET GetUtxos](../api/http-rest-requests.md#get-getutxos) returns an UTXO set given a set of outpoints. _New in Bitcoin Core 0.11.0_
8+
* [GET Headers](../api/http-rest-requests.md#get-headers) returns a specified amount of block headers in upward direction. _Updated in Bitcoin Core 0.13.0_
9+
* [GET MemPool/Contents](../api/http-rest-requests.md#get-mempoolcontents) returns all transaction in the memory pool with detailed information. _New in Bitcoin Core 0.12.0_
10+
* [GET MemPool/Info](../api/http-rest-requests.md#get-mempoolinfo) returns information about the node's current transaction memory pool. _New in Bitcoin Core 0.12.0_
11+
* [GET Tx](../api/http-rest-requests.md#get-tx) gets a hex-encoded serialized transaction or a JSON object describing the transaction. By default, Dash Core only stores complete transaction data for UTXOs and your own transactions, so this method may fail on historic transactions unless you use the non-default `txindex=1` in your Dash Core startup settings. _Updated in Bitcoin Core 0.13.0_

0 commit comments

Comments
 (0)