Dash Developer Reference

Find technical details and API documentation.

BETA: This documentation has not been extensively reviewed by Dash experts and so likely contains numerous errors. Please use the Issue and Edit links on the bottom left menu to help us improve. Click here to close this disclaimer. X

The Developer Reference aims to provide technical details and API information to help you start building Dash-based applications, but it is not a specification. To make the best use of this documentation, you may want to install the current version of Dash Core, either from source or from a pre-compiled executable.

Questions about Dash development are best asked in one of the Dash development communities. Errors or suggestions related to documentation on dash-docs.github.io can be submitted as an issue.

In the following documentation, some strings have been shortened or wrapped: “[…]” indicates extra data was removed, and lines ending in a single backslash “\” are continued below. If you hover your mouse over a paragraph, cross-reference links will be shown in blue. If you hover over a cross-reference link, a brief definition of the term will be displayed in a tooltip.

Not A Specification

The dash-docs.github.io Developer Documentation describes how Dash works to help educate new Dash developers, but it is not a specification—and it never will be.

Dash security depends on consensus. Should your program diverge from consensus, its security is weakened or destroyed. The cause of the divergence doesn’t matter: it could be a bug in your program, it could be an error in this documentation which you implemented as described, or it could be you do everything right but other software on the network behaves unexpectedly as in the case of Bitcoin’s v0.8 chain fork. The specific cause will not matter to the users of your software whose wealth is lost.

The only correct specification of consensus behavior is the actual behavior of programs on the network which maintain consensus. As that behavior is subject to arbitrary inputs in a large variety of unique environments, it cannot ever be fully documented here or anywhere else.

In addition, we also warn you that this documentation has not been extensively reviewed by Dash experts and so likely contains numerous errors. At the bottom of the menu on the left, you will find links that allow you to report an issue or to edit the documentation on GitHub. Please use those links if you find any errors or important missing information.

Block Chain

The following subsections briefly document core block details.

Block Headers

Block headers are serialized in the 80-byte format described below and then hashed as part of the proof-of-work algorithm, making the serialized header format part of the consensus rules.

Bytes Name Data Type Description
4 version int32_t The block version number indicates which set of block validation rules to follow. See the list of block versions below.
32 previous block header hash char[32] An X11() hash in internal byte order of the previous block’s header. This ensures no previous block can be changed without also changing this block’s header.
32 merkle root hash char[32] A SHA256(SHA256()) hash in internal byte order. The merkle root is derived from the hashes of all transactions included in this block, ensuring that none of those transactions can be modified without modifying the header. See the merkle trees section below.
4 time uint32_t The block time is a Unix epoch time when the miner started hashing the header (according to the miner). Must be strictly greater than the median time of the previous 11 blocks. Full nodes will not accept blocks with headers more than two hours in the future according to their clock.
4 nBits uint32_t An encoded version of the target threshold this block’s header hash must be less than or equal to. See the nBits format described below.
4 nonce uint32_t An arbitrary number miners change to modify the header hash in order to produce a hash less than or equal to the target threshold. If all 32-bit values are tested, the time can be updated or the coinbase transaction can be changed and the merkle root updated.

The hashes are in internal byte order; the other values are all in little-endian order.

An example header in hex:

02000000 ........................... Block version: 2

b6ff0b1b1680a2862a30ca44d346d9e8
910d334beb48ca0c0000000000000000 ... Hash of previous block's header
9d10aa52ee949386ca9385695f04ede2
70dda20810decd12bc9b048aaab31471 ... Merkle root

24d95a54 ........................... Unix time: 1415239972
30c31b18 ........................... Target: 0x1bc330 * 256**(0x18-3)
fe9f0864 ........................... Nonce

Block Versions

The mechanism used for the version 2, 3, and 4 upgrades is commonly called IsSuperMajority() after the function added to Dash Core to manage those soft forking changes. See BIP34 for a full description of this method.

As of this writing, a newer method called version bits is being designed to manage future soft forking changes, although it’s not known whether version 4 will be the last soft fork to use the IsSuperMajority() function. Draft BIP9 describes the version bits design as of this writing, although it is still being actively edited and may substantially change while in the draft state.

Merkle Trees

The merkle root is constructed using all the TXIDs of transactions in this block, but first the TXIDs are placed in order as required by the consensus rules:

If a block only has a coinbase transaction, the coinbase TXID is used as the merkle root hash.

If a block only has a coinbase transaction and one other transaction, the TXIDs of those two transactions are placed in order, concatenated as 64 raw bytes, and then SHA256(SHA256()) hashed together to form the merkle root.

If a block has three or more transactions, intermediate merkle tree rows are formed. The TXIDs are placed in order and paired, starting with the coinbase transaction’s TXID. Each pair is concatenated together as 64 raw bytes and SHA256(SHA256()) hashed to form a second row of hashes. If there are an odd (non-even) number of TXIDs, the last TXID is concatenated with a copy of itself and hashed. If there are more than two hashes in the second row, the process is repeated to create a third row (and, if necessary, repeated further to create additional rows). Once a row is obtained with only two hashes, those hashes are concatenated and hashed to produce the merkle root.

Example Merkle Tree Construction

TXIDs and intermediate hashes are always in internal byte order when they’re concatenated, and the resulting merkle root is also in internal byte order when it’s placed in the block header.

Target nBits

The target threshold is a 256-bit unsigned integer which a header hash must be equal to or below in order for that header to be a valid part of the block chain. However, the header field nBits provides only 32 bits of space, so the target number uses a less precise format called “compact” which works like a base-256 version of scientific notation:

Converting nBits Into A Target Threshold

As a base-256 number, nBits can be quickly parsed as bytes the same way you might parse a decimal number in base-10 scientific notation:

Quickly Converting nBits

Although the target threshold should be an unsigned integer, the original nBits implementation inherits properties from a signed data class, allowing the target threshold to be negative if the high bit of the significand is set. This is useless—the header hash is treated as an unsigned number, so it can never be equal to or lower than a negative target threshold. Dash Core deals with this in two ways:

  • When parsing nBits, Dash Core converts a negative target threshold into a target of zero, which the header hash can equal (in theory, at least).

  • When creating a value for nBits, Dash Core checks to see if it will produce an nBits which will be interpreted as negative; if so, it divides the significand by 256 and increases the exponent by 1 to produce the same number with a different encoding.

Some examples taken from the Dash Core test cases:

nBits Target Notes
0x01003456  0x00  
0x01123456  0x12  
0x02008000  0x80  
0x05009234  0x92340000  
0x04923456 -0x12345600 High bit set (0x80 in 0x92).
0x04123456  0x12345600 Inverse of above; no high bit.

Difficulty 1, the minimum allowed difficulty, is represented on mainnet and the current testnet by the nBits value 0x1e0ffff0. Regtest mode uses a different difficulty 1 value—0x207fffff, the highest possible value below uint32_max which can be encoded; this allows near-instant building of blocks in regtest mode.

Serialized Blocks

Under current consensus rules, a block is not valid unless its serialized size is less than or equal to 2 MB. All fields described below are counted towards the serialized size.

Bytes Name Data Type Description
80 block header block_header The block header in the format described in the block header section.
Varies txn_count compactSize uint The total number of transactions in this block, including the coinbase transaction.
Varies txns raw transaction Every transaction in this block, one after another, in raw transaction format. Transactions must appear in the data stream in the same order their TXIDs appeared in the first row of the merkle tree. See the merkle tree section for details.

The first transaction in a block must be a coinbase transaction which should collect and spend any transaction fees paid by transactions included in this block.

Until the coin limit (~18 million Dash) is hit, all blocks are entitled to receive a block subsidy of newly created Dash value. The newly created value should be spent in the coinbase transaction.

The block subsidy declines by ~7.1% per year until all Dash is mined. Subsidy calculations are performed by the Dash Core GetBlockSubsidy() function.

Together, the transaction fees and block subsidy are called the block reward. A coinbase transaction is invalid if it tries to spend more value than is available from the block reward.

The block reward is divided into three parts: Miners, Masternodes, and Superblocks.

Payee Subsidy Description
Miner 45% Payment for mining
Masternode 45% Payment for masternode services (PrivateSend, InstantSend, Governance, etc.)
Superblock 10% Payment for maintenance/expansion of the ecosystem (Core development, marketing, integration, etc.)

Transactions

The following subsections briefly document core transaction details.

OpCodes

The opcodes used in the pubkey scripts of standard transactions are:

  • Various data pushing opcodes from 0x00 to 0x4e (1–78). These aren’t typically shown in examples, but they must be used to push signatures and public keys onto the stack. See the link below this list for a description.

  • OP_TRUE/OP_1 (0x51) and OP_2 through OP_16 (0x52–0x60), which push the values 1 through 16 to the stack.

  • OP_CHECKSIG (0xac) consumes a signature and a full public key, and pushes true onto the stack if the transaction data specified by the SIGHASH flag was converted into the signature using the same ECDSA private key that generated the public key. Otherwise, it pushes false onto the stack.

  • OP_DUP (0x76) pushes a copy of the topmost stack item on to the stack.

  • OP_HASH160 (0xa9) consumes the topmost item on the stack, computes the RIPEMD160(SHA256()) hash of that item, and pushes that hash onto the stack.

  • OP_EQUAL (0x87) consumes the top two items on the stack, compares them, and pushes true onto the stack if they are the same, false if not.

  • OP_VERIFY (0x69) consumes the topmost item on the stack. If that item is zero (false) it terminates the script in failure.

  • OP_EQUALVERIFY (0x88) runs OP_EQUAL and then OP_VERIFY in sequence.

  • OP_CHECKMULTISIG (0xae) consumes the value (n) at the top of the stack, consumes that many of the next stack levels (public keys), consumes the value (m) now at the top of the stack, and consumes that many of the next values (signatures) plus one extra value.

    The “one extra value” it consumes is the result of an off-by-one error in the Bitcoin Core implementation. This value is not used, so signature scripts prefix the list of secp256k1 signatures with a single OP_0 (0x00).

    OP_CHECKMULTISIG compares the first signature against each public key until it finds an ECDSA match. Starting with the subsequent public key, it compares the second signature against each remaining public key until it finds an ECDSA match. The process is repeated until all signatures have been checked or not enough public keys remain to produce a successful result.

    Because public keys are not checked again if they fail any signature comparison, signatures must be placed in the signature script using the same order as their corresponding public keys were placed in the pubkey script or redeem script. See the OP_CHECKMULTISIG warning below for more details.

  • OP_RETURN (0x6a) terminates the script in failure when executed.

A complete list of opcodes can be found on the Bitcoin Wiki Script Page, with an authoritative list in the opcodetype enum of the Dash Core script header file

Warning icon Signature script modification warning: Signature scripts are not signed, so anyone can modify them. This means signature scripts should only contain data and data-pushing opcodes which can’t be modified without causing the pubkey script to fail. Placing non-data-pushing opcodes in the signature script currently makes a transaction non-standard, and future consensus rules may forbid such transactions altogether. (Non-data-pushing opcodes are already forbidden in signature scripts when spending a P2SH pubkey script.)

Warning icon OP_CHECKMULTISIG warning: The multisig verification process described above requires that signatures in the signature script be provided in the same order as their corresponding public keys in the pubkey script or redeem script. For example, the following combined signature and pubkey script will produce the stack and comparisons shown:

OP_0 <A sig> <B sig> OP_2 <A pubkey> <B pubkey> <C pubkey> OP_3

Sig Stack       Pubkey Stack  (Actually a single stack)
---------       ------------
B sig           C pubkey
A sig           B pubkey
OP_0            A pubkey

1. B sig compared to C pubkey (no match)
2. B sig compared to B pubkey (match #1)
3. A sig compared to A pubkey (match #2)

Success: two matches found

But reversing the order of the signatures with everything else the same will fail, as shown below:

OP_0 <B sig> <A sig> OP_2 <A pubkey> <B pubkey> <C pubkey> OP_3

Sig Stack       Pubkey Stack  (Actually a single stack)
---------       ------------
A sig           C pubkey
B sig           B pubkey
OP_0            A pubkey

1. A sig compared to C pubkey (no match)
2. A sig compared to B pubkey (no match)

Failure, aborted: two signature matches required but none found so
                  far, and there's only one pubkey remaining

Address Conversion

The hashes used in P2PKH and P2SH outputs are commonly encoded as Dash addresses. This is the procedure to encode those hashes and decode the addresses.

First, get your hash. For P2PKH, you RIPEMD-160(SHA256()) hash a ECDSA public key derived from your 256-bit ECDSA private key (random data). For P2SH, you RIPEMD-160(SHA256()) hash a redeem script serialized in the format used in raw transactions (described in a following sub-section). Taking the resulting hash:

  1. Add an address version byte in front of the hash. The version bytes commonly used by Dash are:

  2. Create a copy of the version and hash; then hash that twice with SHA256: SHA256(SHA256(version . hash))

  3. Extract the first four bytes from the double-hashed copy. These are used as a checksum to ensure the base hash gets transmitted correctly.

  4. Append the checksum to the version and hash, and encode it as a base58 string: BASE58(version . hash . checksum)

Dash’s base58 encoding, called Base58Check may not match other implementations. Tier Nolan provided the following example encoding algorithm to the Bitcoin Wiki Base58Check encoding page under the Creative Commons Attribution 3.0 license:

code_string = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
x = convert_bytes_to_big_integer(hash_result)

output_string = ""

while(x > 0)
   {
       (x, remainder) = divide(x, 58)
       output_string.append(code_string[remainder])
   }

repeat(number_of_leading_zero_bytes_in_hash)
   {
   output_string.append(code_string[0]);
   }

output_string.reverse();

Dash’s own code can be traced using the base58 header file.

To convert addresses back into hashes, reverse the base58 encoding, extract the checksum, repeat the steps to create the checksum and compare it against the extracted checksum, and then remove the version byte.

Raw Transaction Format

Dash transactions are broadcast between peers in a serialized byte format, called raw format. It is this form of a transaction which is SHA256(SHA256()) hashed to create the TXID and, ultimately, the merkle root of a block containing the transaction—making the transaction format part of the consensus rules.

Dash Core and many other tools print and accept raw transactions encoded as hex.

Transactions prior to protocol version 70209 defaulted to version 1. Transaction version 2 became the default in protocol version 70209. Version 2 transactions have the same format, but the lock_time parameter was redefined by BIP68 to enable relative lock-times. (Note: transactions in the block chain are allowed to list a higher version number to permit soft forks, but they are treated as version 2 transactions by current software.)

A raw transaction has the following top-level format:

Bytes Name Data Type Description
2 version uint16_t Transaction version number; currently version 3. Programs creating transactions using newer consensus rules may use higher version numbers.
2 type uint16_t Transaction type number; 0 for classical transactions; Non-zero for DIP2 special transactions.
Varies tx_in count compactSize uint Number of inputs in this transaction.
Varies tx_in txIn Transaction inputs. See description of txIn below.
Varies tx_out count compactSize uint Number of outputs in this transaction.
Varies tx_out txOut Transaction outputs. See description of txOut below.
4 lock_time uint32_t A time (Unix epoch time) or block number. See the locktime parsing rules.
Varies extra_payload size compactSize uint Added by DIP2

Variable number of bytes of extra payload for DIP2-based special transactions
Varies extra_payload blob Added by DIP2

Special transaction payload.

A transaction may have multiple inputs and outputs, so the txIn and txOut structures may recur within a transaction. CompactSize unsigned integers are a form of variable-length integers; they are described in the CompactSize section.

TxIn: A Transaction Input (Non-Coinbase)

Each non-coinbase input spends an outpoint from a previous transaction. (Coinbase inputs are described separately after the example section below.)

Bytes Name Data Type Description
36 previous_output outpoint The previous outpoint being spent. See description of outpoint below.
Varies script bytes compactSize uint The number of bytes in the signature script. Maximum is 10,000 bytes.
Varies signature script char[] A script-language script which satisfies the conditions placed in the outpoint’s pubkey script. Should only contain data pushes; see the signature script modification warning.
4 sequence uint32_t Sequence number. Default for Dash Core and almost all other programs is 0xffffffff.
Outpoint: The Specific Part Of A Specific Output

Because a single transaction can include multiple outputs, the outpoint structure includes both a TXID and an output index number to refer to specific output.

Bytes Name Data Type Description
32 hash char[32] The TXID of the transaction holding the output to spend. The TXID is a hash provided here in internal byte order.
4 index uint32_t The output index number of the specific output to spend from the transaction. The first output is 0x00000000.
TxOut: A Transaction Output

Each output spends a certain number of duffs, placing them under control of anyone who can satisfy the provided pubkey script.

Bytes Name Data Type Description
8 value int64_t Number of duffs to spend. May be zero; the sum of all outputs may not exceed the sum of duffs previously spent to the outpoints provided in the input section. (Exception: coinbase transactions spend the block subsidy and collected transaction fees.)
1+ pk_script bytes compactSize uint Number of bytes in the pubkey script. Maximum is 10,000 bytes.
Varies pk_script char[] Defines the conditions which must be satisfied to spend this output.

Example

The sample raw transaction itemized below is the one created in the Simple Raw Transaction section of the Developer Examples. It spends a previous pay-to-pubkey output by paying to a new pay-to-pubkey-hash (P2PKH) output.

01000000 ................................... Version

01 ......................................... Number of inputs
|
| 7b1eabe0209b1fe794124575ef807057
| c77ada2138ae4fa8d6c4de0398a14f3f ......... Outpoint TXID
| 00000000 ................................. Outpoint index number: 0
|
| 49 ....................................... Bytes in sig. script: 73
| | 48 ..................................... Push 72 bytes as data
| | | 30450221008949f0cb400094ad2b5eb3
| | | 99d59d01c14d73d8fe6e96df1a7150de
| | | b388ab8935022079656090d7f6bac4c9
| | | a94e0aad311a4268e082a725f8aeae05
| | | 73fb12ff866a5f01 ..................... Secp256k1 signature
|
| ffffffff ................................. Sequence number: UINT32_MAX

01 ......................................... Number of outputs
| f0ca052a01000000 ......................... Duffs (49.99990000 Dash)
|
| 19 ....................................... Bytes in pubkey script: 25
| | 76 ..................................... OP_DUP
| | a9 ..................................... OP_HASH160
| | 14 ..................................... Push 20 bytes as data
| | | cbc20a7664f2f69e5355aa427045bc15
| | | e7c6c772 ............................. PubKey hash
| | 88 ..................................... OP_EQUALVERIFY
| | ac ..................................... OP_CHECKSIG

00000000 ................................... locktime: 0 (a block height)
Coinbase Input: The Input Of The First Transaction In A Block

The first transaction in a block, called the coinbase transaction, must have exactly one input, called a coinbase. The coinbase input currently has the following format.

Bytes Name Data Type Description
32 hash (null) char[32] A 32-byte null, as a coinbase has no previous outpoint.
4 index (UINT32_MAX) uint32_t 0xffffffff, as a coinbase has no previous outpoint.
Varies script bytes compactSize uint The number of bytes in the coinbase script, up to a maximum of 100 bytes.
Varies (4) height script The block height of this block as required by BIP34. Uses script language: starts with a data-pushing opcode that indicates how many bytes to push to the stack followed by the block height as a little-endian unsigned integer. This script must be as short as possible, otherwise it may be rejected.

The data-pushing opcode will be 0x03 and the total size four bytes until block 16,777,216 about 300 years from now.
Varies coinbase script None The coinbase field: Arbitrary data not exceeding 100 bytes minus the (4) height bytes. Miners commonly place an extra nonce in this field to update the block header merkle root during hashing.
4 sequence uint32_t Sequence number.

Although the coinbase script is arbitrary data, if it includes the bytes used by any signature-checking operations such as OP_CHECKSIG, those signature checks will be counted as signature operations (sigops) towards the block’s sigop limit. To avoid this, you can prefix all data with the appropriate push operation.

An itemized coinbase transaction:

01000000 .............................. Version

01 .................................... Number of inputs
| 00000000000000000000000000000000
| 00000000000000000000000000000000 ...  Previous outpoint TXID
| ffffffff ............................ Previous outpoint index
|
| 18 .................................. Bytes in coinbase: 24
| |
| | 03 ................................ Bytes in height
| | | b8240b .......................... Height: 730296
| |
| | 03b8240b049d29aa59080400077efa95
| | 0000052f6d70682f .................. Arbitrary data
| 00000000 ............................ Sequence

02 .................................... Output count
| Transaction Output 1
| | f20cbe0a00000000 .................... Duffs (1.80227314 Dash)
| | 1976a9142cd46be3ceeacca983e0fea3
| | b88f26b08a26c29b88ac ................ P2PKH script
|
| Transaction Output 2
| | eb0cbe0a00000000 .................... Duffs (1.80227307 Dash)
| | 1976a914868180414905937a68fadeb0
| | f33e64d102c9591a88ac ................ P2PKH script
|
| 00000000 ............................ Locktime

Note: currently the normal coinbase has 2 outputs (1 for the miner and 1 for the selected masternode). Superblocks (superblock example) have multiple outputs depending on the number of proposals being funded.

Special Transactions

The Special Transaction framework established by DIP2 enabled the implementation of new on-chain features and consensus mechanisms. These transactions provide the flexibility to expand beyond the financial uses of classical transactions. DIP2 transactions modified classical transactions by:

  1. Splitting the 32 bit version field into two 16 bit fields (version and type)
  2. Adding support for a generic extra payload following the lock_time field

Classical (financial) transactions have a type of 0 while special transactions have a type defined in the DIP describing them. A list of current special transaction types is maintained in the DIP repository.

ProRegTx

Added in protocol version 70212 of Dash Core as described by DIP3

The Masternode Registration (ProRegTx) special transaction is used to join the masternode list by proving ownership of the 1000 DASH necessary to create a masternode.

A ProRegTx is created and sent using the protx RPC. The ProRegTx must either include an output with 1000 DASH (protx register) or refer to an existing unspent output holding 1000 DASH (protx fund_register). If the 1000 DASH is an output of the ProRegTx, the collateralOutpoint hash field should be null.

The special transaction type is 1 and the extra payload consists of the following data:

Bytes Name Data type Description
2 version uint_16 Provider transaction version number. Currently set to 1.
2 type uint_16 Masternode type. Default set to 0.
2 mode uint_16 Masternode mode. Default set to 0.
36 collateralOutpoint COutpoint The collateral outpoint.
Note: The hash will be null if the collateral is part of this transaction, otherwise it will reference an existing collateral.
16 ipAddress byte[] IPv6 address in network byte order. Only IPv4 mapped addresses are allowed (to be extended in the future)
2 port uint_16 Port (network byte order)
20 KeyIdOwner CKeyID The public key hash used for owner related signing (ProTx updates, governance voting)
48 PubKeyOperator CBLSPublicKey The BLS public key used for operational related signing (network messages, ProTx updates)
20 KeyIdVoting CKeyID The public key hash used for voting.
2 operatorReward uint_16 A value from 0 to 10000.
1-9 scriptPayoutSize compactSize uint Size of the Payee Script.
Variable scriptPayout Script Payee script (p2pkh/p2sh)
32 inputsHash uint256 Hash of all the outpoints of the transaction inputs
1-9 payloadSigSize compactSize uint Size of the Signature
Variable payloadSig vector Signature of the hash of the ProTx fields. Signed with the key corresponding to the collateral outpoint in case the collateral is not part of the ProRegTx itself, empty otherwise.

The following annotated hexdump shows a ProRegTx transaction referencing an existing collateral. (Parts of the classical transaction section have been omitted.)

0300 ....................................... Version (3)
0100 ....................................... Type (1 - ProRegTx)

[...] ...................................... Transaction inputs omitted
[...] ...................................... Transaction outputs omitted

00000000 ................................... locktime: 0 (a block height)

fd1201 ..................................... Extra payload size (274)

ProRegTx Payload
| 0100 ..................................... Version (1)
| 0000 ..................................... Type (0)
| 0000 ..................................... Mode (0)
|
| 4859747b0eb19bb2dae5a12ef7b6a69b
| 03712bfeded1174de0b6ab1334ab2e8b ......... Outpoint TXID
| 01000000 ................................. Outpoint index number: 1
|
| 00000000000000000000ffffc0000233 ......... IP Address: ::ffff:192.0.2.51
| 270f ..................................... Port: 9999
|
|
| 1636e84d02310b0b458f3eb51d8ea8b2e684b7ce . Owner pubkey hash (ECDSA)
| 88d719278eef605d9c19037366910b59bc28d437
| de4a8db4d76fda6d6985dbdf10404fb9bb5cd0e8
| c22f4a914a6c5566 ......................... Operator public key (BLS)
| 1636e84d02310b0b458f3eb51d8ea8b2e684b7ce . Voting pubkey hash (ECDSA)
|
| f401 ..................................... Operator reward (500 -> 5%)
|
| Payout script
| 19 ....................................... Bytes in pubkey script: 25
| | 76 ..................................... OP_DUP
| | a9 ..................................... OP_HASH160
| | 14 ..................................... Push 20 bytes as data
| | | fc136008111fcc7a05be6cec66f97568
| | | 727a9e51 ............................. PubKey hash
| | 88 ..................................... OP_EQUALVERIFY
| | ac ..................................... OP_CHECKSIG
|
| 0fcfb7d939078ba6a6b81ecf1dc2e05d
| e2776f49f7b503ac254798be6a672699 ......... Inputs hash
|
| Payload signature
| 41 ....................................... Signature Size (65)
| 200476f193b465764093014ba44bd4ff
| de2b3fc92794c4acda9cad6305ca172e
| 9e3d6b1cd6e30f86678dae8e6595e53d
| 2b30bc32141b6c0151eb58479121b3e6a4 ....... Signature

The following annotated hexdump shows a ProRegTx transaction creating a new collateral.

Note the presence of the output, a null Outpoint TXID and the absence of a signature (since it isn’t referring to an existing collateral). (Parts of the classical transaction section have been omitted.)

0300 ....................................... Version (3)
0100 ....................................... Type (1 - ProRegTx)

[...] ...................................... Transaction inputs omitted

02 ......................................... Number of outputs
| [...] .................................... 1 output omitted
|
| Masternode collateral output
| | 00e8764817000000 ....................... Duffs (1000 DASH)
| | 1976a9149e648c7e4b61482aa3
| | 9bd10e0bf0b5268768005f88ac ............. Script

00000000 ................................... locktime: 0 (a block height)

d1 ......................................... Extra payload size (209)

ProRegTx Payload
| 0100 ..................................... Version (1)
| 0000 ..................................... Type (0)
| 0000 ..................................... Mode (0)
|
| 00000000000000000000000000000000
| 00000000000000000000000000000000 ......... Outpoint TXID
| 01000000 ................................. Outpoint index number: 1
|
| 00000000000000000000ffffc0000233 ......... IP Address: ::ffff:192.0.2.51
| 270f ..................................... Port: 9999
|
| 757a2171bbf92517e358249f20c37a8ad2d7a5bc . Owner pubkey hash (ECDSA)
| 0e02146e9c34cfbcb3f3037574a1abb35525e2ca
| 0c3c6901dbf82ac591e30218d1711223b7ca956e
| df39f3d984d06d51 ......................... Operator public key (BLS)
| 757a2171bbf92517e358249f20c37a8ad2d7a5bc . Voting pubkey hash (ECDSA)
|
| f401 ..................................... Operator reward (500 -> 5%)
|
| Payout script
| 19 ....................................... Bytes in pubkey script: 25
| | 76 ..................................... OP_DUP
| | a9 ..................................... OP_HASH160
| | 14 ..................................... Push 20 bytes as data
| | | 9e648c7e4b61482aa39bd10e0bf0b526
| | | 8768005f ............................. PubKey hash
| | 88 ..................................... OP_EQUALVERIFY
| | ac ..................................... OP_CHECKSIG
|
| 57b115d681b9aff82824ff7e22af99d4
| ac4b39ad7be7cb70b662e9011827d589 ......... Inputs hash
|
| Payload signature
| 00 ....................................... Signature Size (0)
| .......................................... Signature (Empty)

ProUpServTx

Added in protocol version 70212 of Dash Core as described by DIP3

The Masternode Provider Update Service (ProUpServTx) special transaction is used to update the IP Address and port of a masternode. If a non-zero operatorReward was set in the initial ProRegTx, the operator may also set the scriptOperatorPayout field in the ProUpServTx.

A ProUpServTx is only valid for masternodes in the registered masternodes subset. When processed, it updates the metadata of the masternode entry and revives the masternode if it was previously marked as PoSe-banned.

A ProUpServTx is created and sent using the protx update_service RPC.

The special transaction type used for ProUpServTx Transactions is 2 and the extra payload consists of the following data:

Bytes Name Data type Description
2 version uint_16 ProUpServTx version number. Currently set to 1.
32 proTXHash uint256 The hash of the initial ProRegTx
16 ipAddress byte[] IPv6 address in network byte order. Only IPv4 mapped addresses are allowed (to be extended in the future)
2 port uint_16 Port (network byte order)
1-9 scriptOperator
PayoutSize
compactSize uint Size of the Operator Payee Script.
Variable scriptOperator
Payout
Script Operator Payee script (p2pkh/p2sh)
32 inputsHash uint256 Hash of all the outpoints of the transaction inputs
1-9 payloadSigSize compactSize uint Size of the Signature
Note: not present in BLS implementation
96 payloadSig vector BLS Signature of the hash of the ProUpServTx fields. Signed by the Operator.

The following annotated hexdump shows a ProUpServTx transaction. (Parts of the classical transaction section have been omitted.)

0300 ....................................... Version (3)
0200 ....................................... Type (2 - ProUpServTx)

[...] ...................................... Transaction inputs omitted
[...] ...................................... Transaction outputs omitted

00000000 ................................... locktime: 0 (a block height)

b5 ......................................... Extra payload size (181)

ProUpServTx Payload
| 0100 ..................................... Version (1)
|
| db60b8cecae691a3d078a2341d460b06
| b2914f6b092f1906b5c815589399b0ff ......... ProRegTx Hash
|
| 00000000000000000000ffffc0000233 ......... IP Address: ::ffff:192.0.2.51
| 270f ..................................... Port: 9999
|
| 00 ....................................... Operator payout script size (0)
| .......................................... Operator payout script (Empty)
|
| a9569d037b0eacc8bca05c5829c95283
| 4ac27d1c7e7df610500b7ba70fd46507 ......... Inputs hash
|
| Payload signature (BLS)
| 0267702ef85d186ef7fa32dc40c65f2f
| eca0a7465715eb7c30f81beb69e35ee4
| 1f6ff7f292b82a9caebb5aa961b0f915
| 02501becf629e93c0a01c76162d56a6c
| 65a9675c3ca9d5297f053e68f91393dd
| 789beed8ef7e8839695a334c2e1bd37c ......... BLS Signature (96 bytes)

ProUpRegTx

Added in protocol version 70212 of Dash Core as described by DIP3

The Masternode Provider Update Registrar (ProUpRegTx) special transaction is used by a masternode owner to update masternode metadata (e.g. operator/voting key details or the payout script).

A ProUpRegTx is created and sent using the protx update_registrar RPC.

The special transaction type is 3 and the extra payload consists of the following data:

Bytes Name Data type Description
2 version uint_16 Provider update registrar transaction version number. Currently set to 1.
32 proTXHash uint256 The hash of the initial ProRegTx
2 mode uint_16 Masternode mode. Default set to 0.
48 PubKeyOperator CBLSPublicKey The BLS public key used for operational related signing (network messages, ProTx updates)
20 KeyIdVoting CKeyID The public key hash used for voting.
1-9 scriptPayoutSize compactSize uint Size of the Payee Script.
Variable scriptPayout Script Payee script (p2pkh/p2sh)
32 inputsHash uint256 Hash of all the outpoints of the transaction inputs
1-9 payloadSigSize compactSize uint Size of the Signature
Variable payloadSig vector Signature of the hash of the ProTx fields. Signed with the key corresponding to the collateral outpoint in case the collateral is not part of the ProRegTx itself, empty otherwise.

The following annotated hexdump shows a ProUpRegTx transaction referencing an existing collateral. (Parts of the classical transaction section have been omitted.)

0300 ....................................... Version (3)
0300 ....................................... Type (3 - ProUpRegTx)

[...] ...................................... Transaction inputs omitted
[...] ...................................... Transaction outputs omitted

00000000 ................................... locktime: 0 (a block height)

e4 ......................................... Extra payload size (228)

ProRegTx Payload
| 0100 ..................................... Version (1)
|
| ddaf13bf1b02de39711de911e646c63e
| f089b6cee786a1b776086ae130331bba ......... ProRegTx Hash
|
| 0000 ..................................... Mode (0)
|
| 0e02146e9c34cfbcb3f3037574a1abb35525e2ca
| 0c3c6901dbf82ac591e30218d1711223b7ca956e
| df39f3d984d06d51 ......................... Operator public key (BLS)
| 757a2171bbf92517e358249f20c37a8ad2d7a5bc . Voting pubkey hash (ECDSA)
|
| Payout script
| 19 ....................................... Bytes in pubkey script: 25
| | 76 ..................................... OP_DUP
| | a9 ..................................... OP_HASH160
| | 14 ..................................... Push 20 bytes as data
| | | 9e648c7e4b61482aa39bd10e0bf0b526
| | | 8768005f ............................. PubKey hash
| | 88 ..................................... OP_EQUALVERIFY
| | ac ..................................... OP_CHECKSIG
|
| 50b50b24193b2b16f0383125c1f4426e
| 883d256eeadee96d500f8c08b0e0f9e4 ......... Inputs hash
|
| Payload signature
| 41 ....................................... Signature Size (65)
| 1ffa8a27ae0301e414176d4c876cff2e
| 20b810683a68ab7dcea95de1f8f36441
| 4c56368f189a3ef7a59b83bd77f22431
| a73d347841a58768b94c771819dc2bbce3 ....... Signature

ProUpRevTx

Added in protocol version 70212 of Dash Core as described by DIP3

The Masternode Operator Revocation (ProUpRevTx) special transaction allows an operator to revoke their key in case of compromise or if they wish to terminate service. If a masternode’s operator key is revoked, the masternode becomes ineligible for payment until the owner provides a new operator key (via a ProUpRegTx).

A ProUpRevTx is created and sent using the protx revoke RPC.

The special transaction type used for ProUpServTx Transactions is 4 and the extra payload consists of the following data:

Bytes Name Data type Description
2 version uint_16 ProUpRevTx version number. Currently set to 1.
32 proTXHash uint256 The hash of the initial ProRegTx
2 reason uint_16 The reason for revoking the key.
0 - Not specified
1 - Termination of Service
2 - Compromised Key
3 - Change of key
32 inputsHash uint256 Hash of all the outpoints of the transaction inputs
1-9 payloadSigSize compactSize uint Size of the Signature
Note: not present in BLS implementation
96 payloadSig vector BLS Signature of the hash of the ProUpServTx fields. Signed by the Operator.

The following annotated hexdump shows a ProUpRevTx transaction. (Parts of the classical transaction section have been omitted.)

0300 ....................................... Version (3)
0400 ....................................... Type (4 - ProUpRevTx)

[...] ...................................... Transaction inputs omitted
[...] ...................................... Transaction outputs omitted

00000000 ................................... locktime: 0 (a block height)

a4 ......................................... Extra payload size (164)

ProUpRevTx Payload
| 0100 ..................................... Version (1)
|
| ddaf13bf1b02de39711de911e646c63e
| f089b6cee786a1b776086ae130331bba ......... ProRegTx Hash
|
| 0000 ..................................... Reason: 0 (Not specified)
|
| cb0dfe113c87f8e9cde2c5d18aae12fc
| 8d0617c42c34ca5c2f2f6ab4b1dae164 ......... Inputs hash
|
| Payload signature (BLS)
| 0adaef4bf1a904308f1b0efbdfaffc93
| 864f9e047fd83415c831589180303711
| 0f0d8adb312ab43ddd7f8086042d3f5b
| 09029a6a16c341c9d2a62789b495fef4
| e068da711dac28106ff354db7249ae88
| 05877d82ff7d1af00ae2d303dea5eb3b ......... BLS Signature (96 bytes)

CbTx

Added in protocol version 70212 of Dash Core as described by DIP4

The Coinbase (CbTx) special transaction adds information to the block’s coinbase transaction that enables verification of the deterministic masternode list without the full chain (e.g. from SPV clients). This allows light-clients to properly verify InstantSend transactions and support additional deterministic masternode list functionality in the future.

The special transaction type used for CbTx Transactions is 5 and the extra payload consists of the following data:

Bytes Name Data type Description
2 version uint_16 CbTx version number. Currently set to 1.
4 height uint32_t Height of the block
32 merkleRootMNList uint256 Merkle root of the masternode list

The following annotated hexdump shows a CbTx transaction.

An itemized coinbase transaction:

0300 ....................................... Version (3)
0500 ....................................... Type (5 - Coinbase)

01 ......................................... Number of inputs
| 00000000000000000000000000000000
| 00000000000000000000000000000000 ......... Previous outpoint TXID
| ffffffff ................................. Previous outpoint index
|
| 05 ....................................... Bytes in coinbase: 5
| |
| | 02 ..................................... Bytes in height
| | | 0608 ................................. Height: 2054
| |
| | 0101 ................................... Arbitrary data
| ffffffff ................................. Sequence

02 ......................................... Output count
| Transaction Output 1
| | 00902f5009000000 ....................... Duffs (400 DASH)
| | 2102c633b7022b4dab169c8a8459d83b7e0
| | 6e0f8da0f89bf7e788ec98c8038107989ac .... Script
|
| Transaction Output 2
| | 00e40b5402000000 ....................... Duffs (100 DASH)
| | 1976a914ebafa153cffbb5b37c30fb93
| | 886f2fe0f1d549ed88ac ................... P2PKH script

00000000 ................................... Locktime

26 ......................................... Extra payload size (38)

Coinbase Transaction Payload
| 0100 ..................................... Version (1)
|
| 06080000 ................................. Block height: 2054
|
| 69010fa8b729b53c78a1e209946c82e2
| 3159439022ea4055aa60d4393fffba46 ......... MN List merkle root

Quorum Commitment

Quorum Commitment

SubTxRegister

Register Blockchain User

SubTxTopup

Topup Blockchain User Credit

SubTxResetKey

Change Blockchain User Public Key

SubTxCloseAccount

Close Blockchain User Account

CompactSize Unsigned Integers

The raw transaction format and several peer-to-peer network messages use a type of variable-length integer to indicate the number of bytes in a following piece of data.

Dash Core code and this document refers to these variable length integers as compactSize. Many other documents refer to them as var_int or varInt, but this risks conflation with other variable-length integer encodings—such as the CVarInt class used in Dash Core for serializing data to disk. Because it’s used in the transaction format, the format of compactSize unsigned integers is part of the consensus rules.

For numbers from 0 to 252 (0xfc), compactSize unsigned integers look like regular unsigned integers. For other numbers up to 0xffffffffffffffff, a byte is prefixed to the number to indicate its length—but otherwise the numbers look like regular unsigned integers in little-endian order.

Value Bytes Used Format
>= 0 && <= 0xfc (252) 1 uint8_t
>= 0xfd (253) && <= 0xffff 3 0xfd followed by the number as uint16_t
>= 0x10000 && <= 0xffffffff 5 0xfe followed by the number as uint32_t
>= 0x100000000 && <= 0xffffffffffffffff 9 0xff followed by the number as uint64_t

For example, the number 515 is encoded as 0xfd0302.

Wallets

Deterministic Wallet Formats

Type 1: Single Chain Wallets

Type 1 deterministic wallets are the simpler of the two, which can create a single series of keys from a single seed. A primary weakness is that if the seed is leaked, all funds are compromised, and wallet sharing is extremely limited.

Type 2: Hierarchical Deterministic (HD) Wallets

Overview Of Hierarchical Deterministic Key Derivation

For an overview of HD wallets, please see the developer guide section. For details, please see BIP32.

P2P Network

This section describes the Dash P2P network protocol (but it is not a specification). It does not describe the BIP70 payment protocol, the GetBlockTemplate mining protocol, or any network protocol never implemented in an official version of Dash Core.

All peer-to-peer communication occurs entirely over TCP.

Note: unless their description says otherwise, all multi-byte
integers mentioned in this section are transmitted in little-endian order.

Constants And Defaults

The following constants and defaults are taken from Dash Core’s chainparams.cpp source code file.

Network Default Port Magic Value Start String Max nBits
Mainnet 9999 0xBD6B0CBF 0xBF0C6BBD 0x1e0ffff0
Testnet 19999 0xFFCAE2CE 0xCEE2CAFF 0x1e0ffff0
Regtest 19994 0xDCB7C1FC 0xFCC1B7DC 0x207fffff
Devnet User-defined 0xCEFFCAE2 0xE2CAFFCE 0x207fffff

Note: the testnet start string and nBits above are for testnet3.

Command line parameters can change what port a node listens on (see -help). Start strings are hardcoded constants that appear at the start of all messages sent on the Dash network; they may also appear in data files such as Dash Core’s block database. The Magic Value and nBits displayed above are in big-endian order; they’re sent over the network in little-endian order. The Start String is simply the endian reversed Magic Value.

Dash Core’s chainparams.cpp also includes other constants useful to programs, such as the hash of the genesis blocks for the different networks.

Protocol Versions

The table below lists some notable versions of the P2P network protocol, with the most recent versions listed first. (If you know of a protocol version that implemented a major change but which is not listed here, please open an issue.)

As of Dash Core 0.13.0.0, the most recent protocol version is 70212.

Version Initial Release Major Changes
70210 Dash Core 0.12.3.x
(July 2018)
• Named Devnets
• New signature format / Spork 6 addition
• Bitcoin Core 0.13/0.14 backports
BIP90: Buried deployments
BIP147: NULLYDUMMY enforcement
BIP152 Compact Blocks
• Transaction version increased to 2
• Zero fee transactions removed
• Pruning in Lite Mode
70208 Dash Core 0.12.2.x
(Nov 2017)
DIP1 (2MB blocks)
• Fee reduction (10x)
InstantSend fix
PrivateSend improvements
Experimental HD wallet
• Local Masternode support removed
70206 Dash Core 0.12.1.x
(Mar 2017)
• Switch to Bitcoin Core 0.12.1
• BIP-0065 (CheckLockTimeVerify)
• BIP-0112 (CheckSequenceVerify)
70103 Dash Core 0.12.0.x
(Aug 2015)
• Switch to Bitcoin Core 0.10
• Decentralized budget system
• New IX implementation
70076 Dash Core 0.11.2.x
(Mar 2015)
Masternode enhancements
Mining/relay policy enhancements
• BIP-66 - strict DER encoding for signatures
70066 Dash Core 0.11.1.x
(Feb 2015)
InstantX fully implemented
Spork fully implemented
Masternode payment updates
• Rebrand to Dash (0.11.1.26)
70052 Dash Core 0.11.0.x
(Jan 2015)
• Switch from fork of Litecoin 0.8 to Bitcoin 0.9.3
• Rebrand to Darkcoin Core
70051 Dash Core 0.10.0.x
(Sep 2014)
• Release of the originally closed source implementation of DarkSend
70002 Dash Core 0.9.0.x
(Mar 2014)
Masternode implementation
• Rebrand to Darkcoin
70002 Dash Core 0.8.7
(Jan 2014)
Initial release of Dash (branded XCoin) as a fork of Litecoin 0.8

Historical Bitcoin protocol versions for reference shown below since Dash is a fork of Bitcoin Core.

Version Initial Release Major Changes
70012 Bitcoin Core 0.12.0
(Feb 2016)
BIP130:
• Added sendheaders message.
70011 Bitcoin Core 0.12.0
(Feb 2016)
BIP111:
filter* messages are disabled without NODE_BLOOM after and including this version.
70002 Bitcoin Core 0.9.0
(Mar 2014)
• Send multiple inv messages in response to a mempool message if necessary

BIP61:
• Added reject message
70001 Bitcoin Core 0.8.0
(Feb 2013)
• Added notfound message.

BIP37:
• Added filterload message.
• Added filteradd message.
• Added filterclear message.
• Added merkleblock message.
• Added relay field to version message
• Added MSG_FILTERED_BLOCK inventory type to getdata message.
60002 Bitcoin Core 0.7.0
(Sep 2012)
BIP35:
• Added mempool message.
• Extended getdata message to allow download of memory pool transactions
60001 Bitcoin Core 0.6.1
(May 2012)
BIP31:
• Added nonce field to ping message
• Added pong message
60000 Bitcoin Core 0.6.0
(Mar 2012)
BIP14:
• Separated protocol version from Bitcoin Core version
31800 Bitcoin Core 0.3.18
(Dec 2010)
• Added getheaders message and headers message.
31402 Bitcoin Core 0.3.15
(Oct 2010)
• Added time field to addr message.
311 Bitcoin Core 0.3.11
(Aug 2010)
• Added alert message.
209 Bitcoin Core 0.2.9
(May 2010)
• Added checksum field to message headers.
106 Bitcoin Core 0.1.6
(Oct 2009)
• Added receive IP address fields to version message.

Message Headers

All messages in the network protocol use the same container format, which provides a required multi-field message header and an optional payload. The message header format is:

Bytes Name Data Type Description
4 start string char[4] Magic bytes indicating the originating network; used to seek to next message when stream state is unknown.
12 command name char[12] ASCII string which identifies what message type is contained in the payload. Followed by nulls (0x00) to pad out byte count; for example: version\0\0\0\0\0.
4 payload size uint32_t Number of bytes in payload. The current maximum number of bytes (MAX_SIZE) allowed in the payload by Dash Core is 32 MiB—messages with a payload size larger than this will be dropped or rejected.
4 checksum char[4] Added in protocol version 209.

First 4 bytes of SHA256(SHA256(payload)) in internal byte order.

If payload is empty, as in verack and getaddr messages, the checksum is always 0x5df6e0e2 (SHA256(SHA256(<empty string>))).

The following example is an annotated hex dump of a mainnet message header from a verack message which has no payload.

bf0c6bbd ................... Start string: Mainnet
76657261636b000000000000 ... Command name: verack + null padding
00000000 ................... Byte count: 0
5df6e0e2 ................... Checksum: SHA256(SHA256(<empty>))

Data Messages

The following network messages all request or provide data related to transactions and blocks.

Overview Of P2P Protocol Data Request And Reply Messages

Many of the data messages use inventories as unique identifiers for transactions and blocks. Inventories have a simple 36-byte structure:

Bytes Name Data Type Description
4 type identifier uint32_t The type of object which was hashed. See list of type identifiers below.
32 hash char[32] SHA256(SHA256()) hash of the object in internal byte order.

The currently-available type identifiers are:

Type Identifier Name Description
1 MSG_TX The hash is a TXID.
2 MSG_BLOCK The hash is of a block header.
3 MSG_FILTERED_BLOCK The hash is of a block header; identical to MSG_BLOCK. When used in a getdata message, this indicates the response should be a merkleblock message rather than a block message (but this only works if a bloom filter was previously configured). Only for use in getdata messages.
4 MSG_TXLOCK_REQUEST The hash is an Instant Send transaction lock request.
5 MSG_TXLOCK_VOTE The hash is an Instant Send transaction vote.
6 MSG_SPORK The hash is Spork ID.
7 MSG_MASTERNODE_PAYMENT_VOTE The hash is a Masternode Payment Vote.
8 MSG_MASTERNODE_PAYMENT_BLOCK The hash is a Masternode Payment Block.
8 MSG_MASTERNODE_SCANNING_ERROR Replaced by MSG_MASTERNODE_PAYMENT_BLOCK
9 MSG_BUDGET_VOTE Deprecated
10 MSG_BUDGET_PROPOSAL Deprecated
11 MSG_BUDGET_FINALIZED Deprecated
12 MSG_BUDGET_FINALIZED_VOTE Deprecated
13 MSG_MASTERNODE_QUORUM Not Implemented
14 MSG_MASTERNODE_ANNOUNCE The hash is a Masternode Broadcast.
15 MSG_MASTERNODE_PING The hash is a Masternode Ping.
16 MSG_DSTX The hash is Private Send (Dark Send) Broadcast TX.
17 MSG_GOVERNANCE_OBJECT The hash is a Governance Object.
18 MSG_GOVERNANCE_OBJECT_VOTE The hash is a Governance Object Vote.
19 MSG_MASTERNODE_VERIFY The hash is a Masternode Verify.
20 MSG_CMPCT_BLOCK The hash is of a block header; identical to MSG_BLOCK. When used in a getdata message, this indicates the response should be a cmpctblock message. Only for use in getdata messages.

Type identifier zero and type identifiers greater than twenty are reserved for future implementations. Dash Core ignores all inventories with one of these unknown types.

Block

The block message transmits a single serialized block in the format described in the serialized blocks section. See that section for an example hexdump. It can be sent for two different reasons:

  1. GetData Response: Nodes will always send it in response to a getdata message that requests the block with an inventory type of MSG_BLOCK (provided the node has that block available for relay).

  2. Unsolicited: Some miners will send unsolicited block messages broadcasting their newly-mined blocks to all of their peers. Many mining pools do the same thing, although some may be misconfigured to send the block from multiple nodes, possibly sending the same block to some peers more than once.

Blocktxn

Added in protocol version 70209 of Dash Core as described by BIP152

The blocktxn message sends requested block transactions to a node which previously requested them with a getblocktxn message. It is defined as a message containing a serialized BlockTransactions message.

Upon receipt of a properly-formatted requested blocktxn message, nodes should:

  1. Attempt to reconstruct the full block by taking the prefilledtxn transactions from the original cmpctblock message and placing them in the marked positions
  2. For each short transaction ID from the original cmpctblock message, in order, find the corresponding transaction (from either the blocktxn message or from other sources)
  3. Place each short transaction ID in the first available position in the block
  4. Once the block has been reconstructed, it shall be processed as normal.

Short transaction IDs are expected to occasionally collide. Nodes must not be penalized for such collisions.

The structure of BlockTransactions is defined below.

Bytes Name Data Type Encoding Description
32 blockhash Binary blob The output from a double-SHA256 of the block header, as used elsewhere The blockhash of the block which the transactions being provided are in
1 or 3 transactions
_length
CompactSize As used to encode array lengths elsewhere The number of transactions provided
Varies transactions List of transactions As encoded in tx messages in response to getdata MSG_TX The transactions provided

The following annotated hexdump shows a blocktxn message. (The message header has been omitted.)

182327cb727da7d60541da793831fd0ab0509e79c8cd
3d654cdf3a0100000000 ....................... Block Hash

01 ......................................... Transactions Provided: 1

Transaction(s)
| Transaction 1
| | 01000000 ................................ Transaction Version: 1
| | 01 ...................................... Input count: 1
| |
| | Transaction input #1
| | |
| | | 0952617a516d956e2ecee71a6adc249f
| | | 4bb757adcc409452ab98c8e55c31e62a ..... Outpoint TXID
| | | 00000000 ............................. Outpoint index number: 0
| | |
| | | 6b ................................... Bytes in sig. script: 107
| | | 483045022100d10edf447252e1e69ff1
| | | 77330bb2c889a50be02e00cc5d79c0d0
| | | 79ae56518fc40220245d36905dc950fc
| | | d55694cfde8cde3109dc80b12aca3a6e
| | | 332033802ee36e1b01210272cc6e7660
| | | 2648831d8e80fca8eb24369cd0f23ff0
| | | 79cf20ae9d9beee05de6db ............... Secp256k1 signature
| | |
| | | ffffffff ............................. Sequence number: UINT32_MAX
| |
| | 02 ..................................... Number of outputs: 02
| |
| | Transaction output #1
| | | 0be0f50500000000 ..................... Duffs (0.99999755 Dash)
| | |
| | | 19 ................................... Bytes in pubkey script: 25
| | | | 76 ................................. OP_DUP
| | | | a9 ................................. OP_HASH160
| | | | 14 ................................. Push 20 bytes as data
| | | | | 923d91ed359f650eec6ea8b9030b340d
| | | | | ea63d590 ......................... PubKey hash
| | | | 88 ................................. OP_EQUALVERIFY
| | | | ac ................................. OP_CHECKSIG
| |
| | [...] .................................. 1 more tx output omitted
| |
| | 00000000 ............................... locktime: 0 (a block height)

CmpctBlock

Added in protocol version 70209 of Dash Core as described by BIP152

The cmpctblock message is a reply to a getdata message which requested a block using the inventory type MSG_CMPCT_BLOCK. If the requested block was recently announced and is close to the tip of the best chain of the receiver and after having sent the requesting peer a sendcmpct message, nodes respond with a cmpctblock message containing data for the block.

If the requested block is too old, the node responds with a full non-compact block

Upon receipt of a cmpctblock message, after sending a sendcmpct message, nodes should calculate the short transaction ID for each unconfirmed transaction they have available (i.e. in their mempool) and compare each to each short transaction ID in the cmpctblock message. After finding already-available transactions, nodes which do not have all transactions available to reconstruct the full block should request the missing transactions using a getblocktxn message.

A node must not send a cmpctblock message unless they are able to respond to a getblocktxn message which requests every transaction in the block. A node must not send a cmpctblock message without having validated that the header properly commits to each transaction in the block, and properly builds on top of the existing, fully-validated chain with a valid proof-of-work either as a part of the current most-work valid chain, or building directly on top of it. A node may send a cmpctblock message before validating that each transaction in the block validly spends existing UTXO set entries.

The cmpctblock message contains a vector of PrefilledTransaction whose structure is defined below. A PrefilledTransaction is used in HeaderAndShortIDs to provide a list of a few transactions explicitly.

Bytes Name Data Type Encoding Description
1 or 3 index CompactSize Compact Size, differentially encoded since the last PrefilledTransaction in a list The index into the block at which this transaction is
Varies tx Transaction As encoded in tx messages sent in response to getdata MSG_TX Transaction which is in the block at index index

The cmpctblock message is compromised of a serialized HeaderAndShortIDs structure which is defined below. A HeaderAndShortIDs structure is used to relay a block header, the short transactions IDs used for matching already-available transactions, and a select few transactions which we expect a peer may be missing.

Bytes Name Data Type Encoding Description
80 header Block header First 80 bytes of the block as defined by the encoding used by block messages The header of the block being provided
8 nonce uint64_t Little Endian A nonce for use in short transaction ID calculations
1 or 3 shortids_
length
CompactSize As used to encode array lengths elsewhere The number of short transaction IDs in shortids (i.e. block tx count - prefilledtxn
_length)
Varies shortids List of 6-byte integers Little Endian The short transaction IDs calculated from the transactions which were not provided explicitly in prefilledtxn
1 or 3 prefilledtxn
_length
CompactSize As used to encode array lengths elsewhere The number of prefilled transactions in prefilledtxn (i.e. block tx count - shortids
_length)
Varies prefilledtxn List of Prefilled
Transactions
As defined by Prefilled
Transaction definition below
Used to provide the coinbase transaction and a select few which we expect a peer may be missing

Short Transaction ID calculation

Short transaction IDs are used to represent a transaction without sending a full 256-bit hash. They are calculated as follows,

  • A single-SHA256 hashing the block header with the nonce appended (in little-endian)
  • Running SipHash-2-4 with the input being the transaction ID and the keys (k0/k1) set to the first two little-endian 64-bit integers from the above hash, respectively.
  • Dropping the 2 most significant bytes from the SipHash output to make it 6 bytes.

The following annotated hexdump shows a cmpctblock message. (The message header has been omitted.)

00000020981178a4342cec6316296b2ad84c9b7cdf9f
2688e5d0fe1a0003cd0000000000f64870f52a3d0125
1336c9464961216732b25fbf288a51f25a0e81bffb20
e9600194d85a64a50d1cc02b0181 ................ Block Header

3151b67e5b418b9d ............................ Nonce

01 .......................................... Short IDs Length: 1
483edcd3c799 ................................ Short IDs

01 .......................................... Prefilled Transaction Length: 1

Prefilled Transactions
| 00 ........................................ Index: 0
|
| Transaction 1 (Coinbase)
| | 01000000 ................................ Transaction Version: 1
| | 01 ...................................... Input count: 1
| |
| | Transaction input #1
| | |
| | | 00000000000000000000000000000000
| | | 00000000000000000000000000000000 ..... Outpoint TXID
| | | ffffffff ............................. Outpoint index number: UINT32_MAX
| | |
| | | 13 ................................... Bytes in sig. script: 19
| | | 03daaf010e2f5032506f6f6c2d74444153482f Secp256k1 signature
| | |
| | | ffffffff ............................. Sequence number: UINT32_MAX
| |
| | 04 ..................................... Number of outputs: 04
| |
| | Transaction output #1
| | | ffe5654200000000 ..................... Duffs (11.13974271 Dash)
| | |
| | | 19 ................................... Bytes in pubkey script: 25
| | | | 76 ................................. OP_DUP
| | | | a9 ................................. OP_HASH160
| | | | 14 ................................. Push 20 bytes as data
| | | | | b885cb21ad12e593c1a46d814df47ccb
| | | | | 450a7d84 ......................... PubKey hash
| | | | 88 ................................. OP_EQUALVERIFY
| | | | ac ................................. OP_CHECKSIG
| |
| | [...] .................................. 3 more tx outputs omitted
| |
| | 00000000 ............................... locktime: 0 (a block height)

GetBlocks

The getblocks message requests an inv message that provides block header hashes starting from a particular point in the block chain. It allows a peer which has been disconnected or started for the first time to get the data it needs to request the blocks it hasn’t seen.

Peers which have been disconnected may have stale blocks in their locally-stored block chain, so the getblocks message allows the requesting peer to provide the receiving peer with multiple header hashes at various heights on their local chain. This allows the receiving peer to find, within that list, the last header hash they had in common and reply with all subsequent header hashes.

Note: the receiving peer itself may respond with an inv message containing header hashes of stale blocks. It is up to the requesting peer to poll all of its peers to find the best block chain.

If the receiving peer does not find a common header hash within the list, it will assume the last common block was the genesis block (block zero), so it will reply with in inv message containing header hashes starting with block one (the first block after the genesis block).

Bytes Name Data Type Description
4 version uint32_t The protocol version number; the same as sent in the version message.
Varies hash count compactSize uint The number of header hashes provided not including the stop hash. There is no limit except that the byte size of the entire message must be below the MAX_SIZE limit; typically from 1 to 200 hashes are sent.
Varies block header hashes char[32] One or more block header hashes (32 bytes each) in internal byte order. Hashes should be provided in reverse order of block height, so highest-height hashes are listed first and lowest-height hashes are listed last.
32 stop hash char[32] The header hash of the last header hash being requested; set to all zeroes to request an inv message with all subsequent header hashes (a maximum of 500 will be sent as a reply to this message; if you need more than 500, you will need to send another getblocks message with a higher-height header hash as the first entry in block header hash field).

The following annotated hexdump shows a getblocks message. (The message header has been omitted.)

71110100 ........................... Protocol version: 70001
02 ................................. Hash count: 2

d39f608a7775b537729884d4e6633bb2
105e55a16a14d31b0000000000000000 ... Hash #1

5c3e6403d40837110a2e8afb602b1c01
714bda7ce23bea0a0000000000000000 ... Hash #2

00000000000000000000000000000000
00000000000000000000000000000000 ... Stop hash

GetBlockTxn

Added in protocol version 70209 of Dash Core as described by BIP152

The getblocktxn message requests a blocktxn message for any transactions that it has not seen after a compact block is received. It is defined as a message containing a serialized BlockTransactionsRequest message. Upon receipt of a properly-formatted getblocktxn message, nodes which recently provided the sender of such a message with a cmpctblock message for the block hash identified in this message must respond with either an appropriate blocktxn message, or a full block message.

A blocktxn message response must contain exactly and only each transaction which is present in the appropriate block at the index specified in the getblocktxn message indexes list, in the order requested.

The structure of BlockTransactionsRequest is defined below.

Bytes Name Data Type Encoding Description
32 blockhash Binary blob The output from a double-SHA256 of the block header, as used elsewhere The blockhash of the block which the transactions being requested are in
Varies indexes_length CompactSize uint As used to encode array lengths elsewhere The number of transactions requested
Varies indexes CompactSize uint[] Differentially encoded Vector of compactSize containing the indexes of the transactions being requested in the block.

The following annotated hexdump shows a getblocktxn message. (The message header has been omitted.)

182327cb727da7d60541da793831fd0a
b0509e79c8cd3d654cdf3a0100000000 ... Block Hash

01 ................................. Index length: 1
01 ................................. Index: 1

GetData

The getdata message requests one or more data objects from another node. The objects are requested by an inventory, which the requesting node typically previously received by way of an inv message.

The response to a getdata message can be a tx message, block message, merkleblock message, ix message, txlvote message, mnw message, mnb message, mnp message, dstx message, govobj message, govobjvote message, mnv message, notfound message, or cmpctblock message.

This message cannot be used to request arbitrary data, such as historic transactions no longer in the memory pool or relay set. Full nodes may not even be able to provide older blocks if they’ve pruned old transactions from their block database. For this reason, the getdata message should usually only be used to request data from a node which previously advertised it had that data by sending an inv message.

The format and maximum size limitations of the getdata message are identical to the inv message; only the message header differs.

GetHeaders

Added in protocol version 70077.

The getheaders message requests a headers message that provides block headers starting from a particular point in the block chain. It allows a peer which has been disconnected or started for the first time to get the headers it hasn’t seen yet.

The getheaders message is nearly identical to the getblocks message, with one minor difference: the inv reply to the getblocks message will include no more than 500 block header hashes; the headers reply to the getheaders message will include as many as 2,000 block headers.

GetMNListD

Added in protocol version 70212

The getmnlistd message is sent to request a full masternode list or an update to a previously requested masternode list.

Bytes Name Data type Required Description
32 baseBlockHash uint256 Required Hash of a block the requester already has a valid masternode list of.
Note: Can be all-zero to indicate that a full masternode list is requested.
32 blockHash uint256 Required Hash of the block for which the masternode list diff is requested

The following annotated hexdump shows a getmnlistd message. (The message header has been omitted.)

000001ee5108348a2c59396da29dc576
9b2a9bb303d7577aee9cd95136c49b9b ........... Base block hash

0000030f51f12e7069a7aa5f1bc9085d
db3fe368976296fd3b6d73fdaf898cc0 ........... Block hash

Headers

Added in protocol version 31800 (of Bitcoin).

The headers message sends block headers to a node which previously requested certain headers with a getheaders message. A headers message can be empty.

Bytes Name Data Type Description
Varies count compactSize uint Number of block headers up to a maximum of 2,000. Note: headers-first sync assumes the sending node will send the maximum number of headers whenever possible.
Varies headers block_header Block headers: each 80-byte block header is in the format described in the block headers section with an additional 0x00 suffixed. This 0x00 is called the transaction count, but because the headers message doesn’t include any transactions, the transaction count is always zero.

The following annotated hexdump shows a headers message. (The message header has been omitted.)

01 ................................. Header count: 1

02000000 ........................... Block version: 2
b6ff0b1b1680a2862a30ca44d346d9e8
910d334beb48ca0c0000000000000000 ... Hash of previous block's header
9d10aa52ee949386ca9385695f04ede2
70dda20810decd12bc9b048aaab31471 ... Merkle root
24d95a54 ........................... Unix time: 1415239972
30c31b18 ........................... Target (bits)
fe9f0864 ........................... Nonce

00 ................................. Transaction count (0x00)

Inv

The inv message (inventory message) transmits one or more inventories of objects known to the transmitting peer. It can be sent unsolicited to announce new transactions or blocks, or it can be sent in reply to a getblocks message or mempool message.

The receiving peer can compare the inventories from an inv message against the inventories it has already seen, and then use a follow-up message to request unseen objects.

Bytes Name Data Type Description
Varies count compactSize uint The number of inventory entries.
Varies inventory inventory One or more inventory entries up to a maximum of 50,000 entries.

The following annotated hexdump shows an inv message with two inventory entries. (The message header has been omitted.)

02 ................................. Count: 2

0f000000 ........................... Type: MSG_MASTERNODE_PING
dd6cc6c11211793b239c2e311f1496e2
2281b200b35233eaae465d2aa3c9d537 ... Hash (mnp)

05000000 ........................... Type: MSG_TXLOCK_VOTE
afc5b2f418f8c06c477a7d071240f5ee
ab17057f9ce4b50c2aef4fadf3729a2e ... Hash (txlvote)

MemPool

Added in protocol version 60002 (of Bitcoin).

The mempool message requests the TXIDs of transactions that the receiving node has verified as valid but which have not yet appeared in a block. That is, transactions which are in the receiving node’s memory pool. The response to the mempool message is one or more inv messages containing the TXIDs in the usual inventory format.

Sending the mempool message is mostly useful when a program first connects to the network. Full nodes can use it to quickly gather most or all of the unconfirmed transactions available on the network; this is especially useful for miners trying to gather transactions for their transaction fees. SPV clients can set a filter before sending a mempool to only receive transactions that match that filter; this allows a recently-started client to get most or all unconfirmed transactions related to its wallet.

The inv response to the mempool message is, at best, one node’s view of the network—not a complete list of unconfirmed transactions on the network. Here are some additional reasons the list might not be complete:

  • Before Bitcoin Core 0.9.0, the response to the mempool message was only one inv message. An inv message is limited to 50,000 inventories, so a node with a memory pool larger than 50,000 entries would not send everything. Later versions of Bitcoin Core send as many inv messages as needed to reference its complete memory pool.

  • The mempool message is not currently fully compatible with the filterload message’s BLOOM_UPDATE_ALL and BLOOM_UPDATE_P2PUBKEY_ONLY flags. Mempool transactions are not sorted like in-block transactions, so a transaction (tx2) spending an output can appear before the transaction (tx1) containing that output, which means the automatic filter update mechanism won’t operate until the second-appearing transaction (tx1) is seen—missing the first-appearing transaction (tx2). It has been proposed in Bitcoin Core issue #2381 that the transactions should be sorted before being processed by the filter.

There is no payload in a mempool message. See the message header section for an example of a message without a payload.

MerkleBlock

Added in protocol version 70001 as described by BIP37.

The merkleblock message is a reply to a getdata message which requested a block using the inventory type MSG_MERKLEBLOCK. It is only part of the reply: if any matching transactions are found, they will be sent separately as tx messages.

If a filter has been previously set with the filterload message, the merkleblock message will contain the TXIDs of any transactions in the requested block that matched the filter, as well as any parts of the block’s merkle tree necessary to connect those transactions to the block header’s merkle root. The message also contains a complete copy of the block header to allow the client to hash it and confirm its proof of work.

Bytes Name Data Type Description
80 block header block_header The block header in the format described in the block header section.
4 transaction count uint32_t The number of transactions in the block (including ones that don’t match the filter).
Varies hash count compactSize uint The number of hashes in the following field.
Varies hashes char[32] One or more hashes of both transactions and merkle nodes in internal byte order. Each hash is 32 bytes.
Varies flag byte count compactSize uint The number of flag bytes in the following field.
Varies flags byte[] A sequence of bits packed eight in a byte with the least significant bit first. May be padded to the nearest byte boundary but must not contain any more bits than that. Used to assign the hashes to particular nodes in the merkle tree as described below.

The annotated hexdump below shows a merkleblock message which corresponds to the examples below. (The message header has been omitted.)

01000000 ........................... Block version: 1
82bb869cf3a793432a66e826e05a6fc3
7469f8efb7421dc88067010000000000 ... Hash of previous block's header
7f16c5962e8bd963659c793ce370d95f
093bc7e367117b3c30c1f8fdd0d97287 ... Merkle root
76381b4d ........................... Time: 1293629558
4c86041b ........................... nBits: 0x04864c * 256**(0x1b-3)
554b8529 ........................... Nonce

07000000 ........................... Transaction count: 7
04 ................................. Hash count: 4

3612262624047ee87660be1a707519a4
43b1c1ce3d248cbfc6c15870f6c5daa2 ... Hash #1
019f5b01d4195ecbc9398fbf3c3b1fa9
bb3183301d7a1fb3bd174fcfa40a2b65 ... Hash #2
41ed70551dd7e841883ab8f0b16bf041
76b7d1480e4f0af9f3d4c3595768d068 ... Hash #3
20d2a7bc994987302e5b1ac80fc425fe
25f8b63169ea78e68fbaaefa59379bbf ... Hash #4

01 ................................. Flag bytes: 1
1d ................................. Flags: 1 0 1 1 1 0 0 0

Note: when fully decoded, the above merkleblock message provided the TXID for a single transaction that matched the filter. In the network traffic dump this output was taken from, the full transaction belonging to that TXID was sent immediately after the merkleblock message as a tx message.

Parsing A MerkleBlock Message

As seen in the annotated hexdump above, the merkleblock message provides three special data types: a transaction count, a list of hashes, and a list of one-bit flags.

You can use the transaction count to construct an empty merkle tree. We’ll call each entry in the tree a node; on the bottom are TXID nodes—the hashes for these nodes are TXIDs; the remaining nodes (including the merkle root) are non-TXID nodes—they may actually have the same hash as a TXID, but we treat them differently.

Example Of Parsing A MerkleBlock Message

Keep the hashes and flags in the order they appear in the merkleblock message. When we say “next flag” or “next hash”, we mean the next flag or hash on the list, even if it’s the first one we’ve used so far.

Start with the merkle root node and the first flag. The table below describes how to evaluate a flag based on whether the node being processed is a TXID node or a non-TXID node. Once you apply a flag to a node, never apply another flag to that same node or reuse that same flag again.

Flag TXID Node Non-TXID Node
0 Use the next hash as this node’s TXID, but this transaction didn’t match the filter. Use the next hash as this node’s hash. Don’t process any descendant nodes.
1 Use the next hash as this node’s TXID, and mark this transaction as matching the filter. The hash needs to be computed. Process the left child node to get its hash; process the right child node to get its hash; then concatenate the two hashes as 64 raw bytes and hash them to get this node’s hash.

Any time you begin processing a node for the first time, evaluate the next flag. Never use a flag at any other time.

When processing a child node, you may need to process its children (the grandchildren of the original node) or further-descended nodes before returning to the parent node. This is expected—keep processing depth first until you reach a TXID node or a non-TXID node with a flag of 0.

After you process a TXID node or a non-TXID node with a flag of 0, stop processing flags and begin to ascend the tree. As you ascend, compute the hash of any nodes for which you now have both child hashes or for which you now have the sole child hash. See the merkle tree section for hashing instructions. If you reach a node where only the left hash is known, descend into its right child (if present) and further descendants as necessary.

However, if you find a node whose left and right children both have the same hash, fail. This is related to CVE-2012-2459.

Continue descending and ascending until you have enough information to obtain the hash of the merkle root node. If you run out of flags or hashes before that condition is reached, fail. Then perform the following checks (order doesn’t matter):

For a detailed example of parsing a merkleblock message, please see the corresponding merkle block examples section.

Creating A MerkleBlock Message

It’s easier to understand how to create a merkleblock message after you understand how to parse an already-created message, so we recommend you read the parsing section above first.

Create a complete merkle tree with TXIDs on the bottom row and all the other hashes calculated up to the merkle root on the top row. For each transaction that matches the filter, track its TXID node and all of its ancestor nodes.

Example Of Creating A MerkleBlock Message

Start processing the tree with the merkle root node. The table below describes how to process both TXID nodes and non-TXID nodes based on whether the node is a match, a match ancestor, or neither a match nor a match ancestor.

  TXID Node Non-TXID Node
Neither Match Nor Match Ancestor Append a 0 to the flag list; append this node’s TXID to the hash list. Append a 0 to the flag list; append this node’s hash to the hash list. Do not descend into its child nodes.
Match Or Match Ancestor Append a 1 to the flag list; append this node’s TXID to the hash list. Append a 1 to the flag list; process the left child node. Then, if the node has a right child, process the right child. Do not append a hash to the hash list for this node.

Any time you begin processing a node for the first time, a flag should be appended to the flag list. Never put a flag on the list at any other time, except when processing is complete to pad out the flag list to a byte boundary.

When processing a child node, you may need to process its children (the grandchildren of the original node) or further-descended nodes before returning to the parent node. This is expected—keep processing depth first until you reach a TXID node or a node which is neither a TXID nor a match ancestor.

After you process a TXID node or a node which is neither a TXID nor a match ancestor, stop processing and begin to ascend the tree until you find a node with a right child you haven’t processed yet. Descend into that right child and process it.

After you fully process the merkle root node according to the instructions in the table above, processing is complete. Pad your flag list to a byte boundary and construct the merkleblock message using the template near the beginning of this subsection.

MnListDiff

Added in protocol version 70212

The mnlistdiff message is a reply to a getmnlistd message which requested either a full masternode list or a diff for a range of blocks.

Bytes Name Data type Required Description
32 baseBlockHash uint256 Required Hash of a block the requester already has a valid masternode list of. Can be all-zero to indicate that a full masternode list is requested.
32 blockHash uint256 Required Hash of the block for which the masternode list diff is requested
4 totalTransactions uint32_t Required Number of total transactions in blockHash
1-9 merkleHashesCount compactSize uint Required Number of Merkle hashes
variable merkleHashes vector Required Merkle hashes in depth-first order
1-9 merkleFlagsCount compactSize uint Required Number of Merkle flag bytes
variable merkleFlags vector Required Merkle flag bits, packed per 8 in a byte, least significant bit first
variable cbTx CTransaction Required The fully serialized coinbase transaction of blockHash
variable deletedMNs vector Required A list of ProRegTx hashes for masternode which were deleted after baseBlockHash
variable mnList vector Required The list of SML entries which were added or updated since baseBlockHash

The following annotated hexdump shows a mnlistdiff message. (The message header has been omitted.)

000001ee5108348a2c59396da29dc576
9b2a9bb303d7577aee9cd95136c49b9b ........... Base block hash

0000030f51f12e7069a7aa5f1bc9085d
db3fe368976296fd3b6d73fdaf898cc0 ........... Block hash

05000000 ................................... Transactions: 5

04 ......................................... Merkle hash count: 4

4488a599e5d61709664c32305befd58b
ef29e33bc6e718af0233f938557a57a9 ........... Merkle hash 1
5c8119b7b136d94e477a0d2917d5f724
5ff299cc6e31994f6236a8fb34fec88f ........... Merkle hash 2
905efa3e6743c889823f00147d36d12f
d12ad401c19089f0affcabd423deef67 ........... Merkle hash 3
3f3a7f84d7ad33214994b5aecf4c1e19
2cb65b86750b1377e069073d1eba477a ........... Merkle hash 4

01 ......................................... Merkle flag count: 1
0f ......................................... Flags: 0 0 0 0 1 1 1 1

[...]....................................... Coinbase Tx (Not shown)

00 ......................................... Deleted masternodes: 0

02 ......................................... Masternode list entries: 2

Masternode List
| Masternode 1
| | 01040eb32f760490054543356cff4638
| | 65633439dd073cffa570305eb086f70e ....... ProRegTx hash
| | 00000000000000000000000000000000 ....... IP Address: ::ffff:0.0.0.0
| | 0000 ................................... Port: 0
| |
| | 0000000000000000000000000000000000000000
| | 0000000000000000000000000000000000000000
| | 0000000000000000 ....................... Operator public key (BLS)
| | c2ae01fb4084cbc3bc31e7f59b36be228a320404 Voting pubkey hash (ECDSA)
|
| Masternode 2
| | f7737beb39779971e9bc59632243e13f
| | c5fc9ada93b69bf48c2d4c463296cd5a ....... ProRegTx hash
| | 000000000000000000000000cf9af40d ....... IP Address: ::ffff:207.154.244.13
| | 4e1f ................................... Port: 19999
| |
| | 88d719278eef605d9c19037366910b59bc28d437
| | de4a8db4d76fda6d6985dbdf10404fb9bb5cd0e8
| | c22f4a914a6c5566 ....................... Operator public key (BLS)
| | 43ce12751c4ba45dcdfe2c16cefd61461e17a54d Voting pubkey hash (ECDSA)

NotFound

Added in protocol version 70001.

The notfound message is a reply to a getdata message which requested an object the receiving node does not have available for relay. (Nodes are not expected to relay historic transactions which are no longer in the memory pool or relay set. Nodes may also have pruned spent transactions from older blocks, making them unable to send those blocks.)

The format and maximum size limitations of the notfound message are identical to the inv message; only the message header differs.

Tx

The tx message transmits a single transaction in the raw transaction format. It can be sent in a variety of situations;

For an example hexdump of the raw transaction format, see the raw transaction section.

Control Messages

The following network messages all help control the connection between two peers or allow them to advise each other about the rest of the network.

Overview Of P2P Protocol Control And Advisory Messages

Note that almost none of the control messages are authenticated in any way, meaning they can contain incorrect or intentionally harmful information. In addition, this section does not yet cover P2P protocol operation over the Tor network; if you would like to contribute information about Tor, please open an issue.

Addr

The addr (IP address) message relays connection information for peers on the network. Each peer which wants to accept incoming connections creates an addr message providing its connection information and then sends that message to its peers unsolicited. Some of its peers send that information to their peers (also unsolicited), some of which further distribute it, allowing decentralized peer discovery for any program already on the network.

An addr message may also be sent in response to a getaddr message.

Bytes Name Data Type Description
Varies IP address count compactSize uint The number of IP address entries up to a maximum of 1,000.
Varies IP addresses network IP address IP address entries. See the table below for the format of a Dash network IP address.

Each encapsulated network IP address currently uses the following structure:

Bytes Name Data Type Description
4 time uint32 Added in protocol version 31402.

A time in Unix epoch time format. Nodes advertising their own IP address set this to the current time. Nodes advertising IP addresses they’ve connected to set this to the last time they connected to that node. Other nodes just relaying the IP address should not change the time. Nodes can use the time field to avoid relaying old addr messages.

Malicious nodes may change times or even set them in the future.
8 services uint64_t The services the node advertised in its version message.
16 IP address char IPv6 address in big endian byte order. IPv4 addresses can be provided as IPv4-mapped IPv6 addresses
2 port uint16_t Port number in big endian byte order. Note that Dash Core will only connect to nodes with non-standard port numbers as a last resort for finding peers. This is to prevent anyone from trying to use the network to disrupt non-Dash services that run on other ports.

The following annotated hexdump shows part of an addr message. (The message header has been omitted and the actual IP address has been replaced with a RFC5737 reserved IP address.)

fde803 ............................. Address count: 1000

d91f4854 ........................... Epoch time: 1414012889
0100000000000000 ................... Service bits: 01 (network node)
00000000000000000000ffffc0000233 ... IP Address: ::ffff:192.0.2.51
208d ............................... Port: 8333

[...] .............................. (999 more addresses omitted)

Alert

Added in protocol version 311. Removed by Bitcoin in protocol version 70013, but retained by Dash.

The alert message warns nodes of problems that may affect them or the rest of the network. Each alert message is signed using a key controlled by respected community members, mostly Dash Core developers.

To ensure all nodes can validate and forward alert messages, encapsulation is used. Developers create an alert using the data structure appropriate for the versions of the software they want to notify; then they serialize that data and sign it. The serialized data and its signature make up the outer alert message—allowing nodes which don’t understand the data structure to validate the signature and relay the alert to nodes which do understand it. The nodes which actually need the message can decode the serialized data to access the inner alert message.

The outer alert message has four fields:

Bytes Name Data Type Description
Variable alert bytes compactSize uint The number of bytes in following alert field.
Variable alert uchar The serialized alert. See below for a description of the current alert format.
Variable signature bytes compactSize uint The number of bytes in the following signature field.
Variable signature uchar A DER-encoded ECDSA (secp256k1) signature of the alert signed with the developer’s alert key.

Although designed to be easily upgraded, the format of the inner serialized alert has not changed since the alert message was first introduced in protocol version 311.

Bytes Name Data Type Description
4 version int32_t Alert format version. Version 1 from protocol version 311 through at least protocol version 70002.
8 relayUntil int64_t The time beyond which nodes should stop relaying this alert. Unix epoch time format.
8 expiration int64_t The time beyond which this alert is no longer in effect and should be ignored. Unix epoch time format.
4 ID int32_t A unique ID number for this alert.
4 cancel int32_t All alerts with an ID number less than or equal to this number should be canceled: deleted and not accepted in the future.
Varies setCancel count compactSize uint The number of IDs in the following setCancel field. May be zero.
Varies setCancel int32_t Alert IDs which should be canceled. Each alert ID is a separate int32_t number.
4 minVer int32_t This alert only applies to protocol versions greater than or equal to this version. Nodes running other protocol versions should still relay it.
4 maxVer int32_t This alert only applies to protocol versions less than or equal to this version. Nodes running other protocol versions should still relay it.
Varies user_agent count compactSize uint The number of user agent strings in the following setUser_agent field. May be zero.
Varies setUser_agent compactSize uint + string If this field is empty, it has no effect on the alert. If there is at least one entry is this field, this alert only applies to programs with a user agent that exactly matches one of the strings in this field. Each entry in this field is a compactSize uint followed by a string—the uint indicates how many bytes are in the following string. This field was originally called setSubVer; since BIP14, it applies to user agent strings as defined in the version message.
4 priority int32_t Relative priority compared to other alerts.
Varies comment bytes compactSize uint The number of bytes in the following comment field. May be zero.
Varies comment string A comment on the alert that is not displayed.
Varies statusBar bytes compactSize uint The number of bytes in the following statusBar field. May be zero.
Varies statusBar string The alert message that is displayed to the user.
Varies reserved bytes compactSize uint The number of bytes in the following reserved field. May be zero.
Varies reserved string Reserved for future use. Originally called RPC Error.

The annotated hexdump below shows an alert message. (The message header has been omitted.)

73 ................................. Bytes in encapsulated alert: 115
01000000 ........................... Version: 1
3766404f00000000 ................... RelayUntil: 1329620535
b305434f00000000 ................... Expiration: 1330917376

f2030000 ........................... ID: 1010
f1030000 ........................... Cancel: 1009
00 ................................. setCancel count: 0

10270000 ........................... MinVer: 10000
48ee0000 ........................... MaxVer: 61000
00 ................................. setUser_agent bytes: 0
64000000 ........................... Priority: 100

00 ................................. Bytes In Comment String: 0
46 ................................. Bytes in StatusBar String: 70
53656520626974636f696e2e6f72672f
666562323020696620796f7520686176
652074726f75626c6520636f6e6e6563
74696e67206166746572203230204665
627275617279 ....................... Status Bar String: "See [...]"
00 ................................. Bytes In Reserved String: 0

47 ................................. Bytes in signature: 71
30450221008389df45f0703f39ec8c1c
c42c13810ffcae14995bb648340219e3
53b63b53eb022009ec65e1c1aaeec1fd
334c6b684bde2b3f573060d5b70c3a46
723326e4e8a4f1 ..................... Signature

Alert key compromise: Dash Core’s source code defines a particular set of alert parameters that can be used to notify users that the alert signing key has been compromised and that they should upgrade to get a new alert public key. Once a signed alert containing those parameters has been received, no other alerts can cancel or override it. See the ProcessAlert() function in the Dash Core alert.cpp source code for the parameters of this message.

FilterAdd

Added in protocol version 70001 as described by BIP37.

The filteradd message tells the receiving peer to add a single element to a previously-set bloom filter, such as a new public key. The element is sent directly to the receiving peer; the peer then uses the parameters set in the filterload message to add the element to the bloom filter.

Because the element is sent directly to the receiving peer, there is no obfuscation of the element and none of the plausible-deniability privacy provided by the bloom filter. Clients that want to maintain greater privacy should recalculate the bloom filter themselves and send a new filterload message with the recalculated bloom filter.

Bytes Name Data Type Description
Varies element bytes compactSize uint The number of bytes in the following element field.
Varies element uint8_t[] The element to add to the current filter. Maximum of 520 bytes, which is the maximum size of an element which can be pushed onto the stack in a pubkey or signature script. Elements must be sent in the byte order they would use when appearing in a raw transaction; for example, hashes should be sent in internal byte order.

Note: a filteradd message will not be accepted unless a filter was previously set with the filterload message.

The annotated hexdump below shows a filteradd message adding a TXID. (The message header has been omitted.) This TXID appears in the same block used for the example hexdump in the merkleblock message; if that merkleblock message is re-sent after sending this filteradd message, six hashes are returned instead of four.

20 ................................. Element bytes: 32
fdacf9b3eb077412e7a968d2e4f11b9a
9dee312d666187ed77ee7d26af16cb0b ... Element (A TXID)

FilterClear

Added in protocol version 70001 as described by BIP37.

The filterclear message tells the receiving peer to remove a previously-set bloom filter. This also undoes the effect of setting the relay field in the version message to 0, allowing unfiltered access to inv messages announcing new transactions.

Dash Core does not require a filterclear message before a replacement filter is loaded with filterload. It also doesn’t require a filterload message before a filterclear message.

There is no payload in a filterclear message. See the message header section for an example of a message without a payload.

FilterLoad

Added in protocol version 70001 as described by BIP37.

The filterload message tells the receiving peer to filter all relayed transactions and requested merkle blocks through the provided filter. This allows clients to receive transactions relevant to their wallet plus a configurable rate of false positive transactions which can provide plausible-deniability privacy.

Bytes Name Data Type Description
Varies nFilterBytes compactSize uint Number of bytes in the following filter bit field.
Varies filter uint8_t[] A bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.
4 nHashFuncs uint32_t The number of hash functions to use in this filter. The maximum value allowed in this field is 50.
4 nTweak uint32_t An arbitrary value to add to the seed value in the hash function used by the bloom filter.
1 nFlags uint8_t A set of flags that control how outpoints corresponding to a matched pubkey script are added to the filter. See the table in the Updating A Bloom Filter subsection below.

The annotated hexdump below shows a filterload message. (The message header has been omitted.) For an example of how this payload was created, see the filterload example.

02 ......... Filter bytes: 2
b50f ....... Filter: 1010 1101 1111 0000
0b000000 ... nHashFuncs: 11
00000000 ... nTweak: 0/none
00 ......... nFlags: BLOOM_UPDATE_NONE

Initializing A Bloom Filter

Filters have two core parameters: the size of the bit field and the number of hash functions to run against each data element. The following formulas from BIP37 will allow you to automatically select appropriate values based on the number of elements you plan to insert into the filter (n) and the false positive rate (p) you desire to maintain plausible deniability.

  • Size of the bit field in bytes (nFilterBytes), up to a maximum of 36,000: (-1 / log(2)**2 * n * log(p)) / 8

  • Hash functions to use (nHashFuncs), up to a maximum of 50: nFilterBytes * 8 / n * log(2)

Note that the filter matches parts of transactions (transaction elements), so the false positive rate is relative to the number of elements checked—not the number of transactions checked. Each normal transaction has a minimum of four matchable elements (described in the comparison subsection below), so a filter with a false-positive rate of 1 percent will match about 4 percent of all transactions at a minimum.

According to BIP37, the formulas and limits described above provide support for bloom filters containing 20,000 items with a false positive rate of less than 0.1 percent or 10,000 items with a false positive rate of less than 0.0001 percent.

Once the size of the bit field is known, the bit field should be initialized as all zeroes.

Populating A Bloom Filter

The bloom filter is populated using between 1 and 50 unique hash functions (the number specified per filter by the nHashFuncs field). Instead of using up to 50 different hash function implementations, a single implementation is used with a unique seed value for each function.

The seed is nHashNum * 0xfba4c795 + nTweak as a uint32_t, where the values are:

  • nHashNum is the sequence number for this hash function, starting at 0 for the first hash iteration and increasing up to the value of the nHashFuncs field (minus one) for the last hash iteration.

  • 0xfba4c795 is a constant optimized to create large differences in the seed for different values of nHashNum.

  • nTweak is a per-filter constant set by the client to require the use of an arbitrary set of hash functions.

If the seed resulting from the formula above is larger than four bytes, it must be truncated to its four most significant bytes (for example, 0x8967452301 & 0xffffffff → 0x67452301).

The actual hash function implementation used is the 32-bit Murmur3 hash function.

Warning icon Warning: the Murmur3 hash function has separate 32-bit and 64-bit versions that produce different results for the same input. Only the 32-bit Murmur3 version is used with Dash bloom filters.

The data to be hashed can be any transaction element which the bloom filter can match. See the next subsection for the list of transaction elements checked against the filter. The largest element which can be matched is a script data push of 520 bytes, so the data should never exceed 520 bytes.

The example below from Dash Core bloom.cpp combines all the steps above to create the hash function template. The seed is the first parameter; the data to be hashed is the second parameter. The result is a uint32_t modulo the size of the bit field in bits.

MurmurHash3(nHashNum * 0xFBA4C795 + nTweak, vDataToHash) % (vData.size() * 8)

Each data element to be added to the filter is hashed by nHashFuncs number of hash functions. Each time a hash function is run, the result will be the index number (nIndex) of a bit in the bit field. That bit must be set to 1. For example if the filter bit field was 00000000 and the result is 5, the revised filter bit field is 00000100 (the first bit is bit 0).

It is expected that sometimes the same index number will be returned more than once when populating the bit field; this does not affect the algorithm—after a bit is set to 1, it is never changed back to 0.

After all data elements have been added to the filter, each set of eight bits is converted into a little-endian byte. These bytes are the value of the filter field.

Comparing Transaction Elements To A Bloom Filter

To compare an arbitrary data element against the bloom filter, it is hashed using the same parameters used to create the bloom filter. Specifically, it is hashed nHashFuncs times, each time using the same nTweak provided in the filter, and the resulting output is modulo the size of the bit field provided in the filter field. After each hash is performed, the filter is checked to see if the bit at that indexed location is set. For example if the result of a hash is 5 and the filter is 01001110, the bit is considered set.

If the result of every hash points to a set bit, the filter matches. If any of the results points to an unset bit, the filter does not match.

The following transaction elements are compared against bloom filters. All elements will be hashed in the byte order used in blocks (for example, TXIDs will be in internal byte order).

  • TXIDs: the transaction’s SHA256(SHA256()) hash.

  • Outpoints: each 36-byte outpoint used this transaction’s input section is individually compared to the filter.

  • Signature Script Data: each element pushed onto the stack by a data-pushing opcode in a signature script from this transaction is individually compared to the filter. This includes data elements present in P2SH redeem scripts when they are being spent.

  • PubKey Script Data: each element pushed onto the the stack by a data-pushing opcode in any pubkey script from this transaction is individually compared to the filter. (If a pubkey script element matches the filter, the filter will be immediately updated if the BLOOM_UPDATE_ALL flag was set; if the pubkey script is in the P2PKH format and matches the filter, the filter will be immediately updated if the BLOOM_UPDATE_P2PUBKEY_ONLY flag was set. See the subsection below for details.)

The following annotated hexdump of a transaction is from the raw transaction format section; the elements which would be checked by the filter are emphasized in bold. Note that this transaction’s TXID (01000000017b1eab[...]) would also be checked, and that the outpoint TXID and index number below would be checked as a single 36-byte element.

01000000 ................................... Version

01 ......................................... Number of inputs
|
| 7b1eabe0209b1fe794124575ef807057
| c77ada2138ae4fa8d6c4de0398a14f3f ......... Outpoint TXID
| 00000000 ................................. Outpoint index number
|
| 49 ....................................... Bytes in sig. script: 73
| | 48 ..................................... Push 72 bytes as data
| | | 30450221008949f0cb400094ad2b5eb3
| | | 99d59d01c14d73d8fe6e96df1a7150de
| | | b388ab8935022079656090d7f6bac4c9
| | | a94e0aad311a4268e082a725f8aeae05
| | | 73fb12ff866a5f01 ..................... Secp256k1 signature
|
| ffffffff ................................. Sequence number: UINT32_MAX

01 ......................................... Number of outputs
| f0ca052a01000000 ......................... Satoshis (49.99990000 BTC)
|
| 19 ....................................... Bytes in pubkey script: 25
| | 76 ..................................... OP_DUP
| | a9 ..................................... OP_HASH160
| | 14 ..................................... Push 20 bytes as data
| | | cbc20a7664f2f69e5355aa427045bc15
| | | e7c6c772 ............................. PubKey hash
| | 88 ..................................... OP_EQUALVERIFY
| | ac ..................................... OP_CHECKSIG

00000000 ................................... locktime: 0 (a block height)

Updating A Bloom Filter

Clients will often want to track inputs that spend outputs (outpoints) relevant to their wallet, so the filterload field nFlags can be set to allow the filtering node to update the filter when a match is found. When the filtering node sees a pubkey script that pays a pubkey, address, or other data element matching the filter, the filtering node immediately updates the filter with the outpoint corresponding to that pubkey script.

Automatically Updating Bloom Filters

If an input later spends that outpoint, the filter will match it, allowing the filtering node to tell the client that one of its transaction outputs has been spent.

The nFlags field has three allowed values:

Value Name Description
0 BLOOM_UPDATE_NONE The filtering node should not update the filter.
1 BLOOM_UPDATE_ALL If the filter matches any data element in a pubkey script, the corresponding outpoint is added to the filter.
2 BLOOM_UPDATE_P2PUBKEY_ONLY If the filter matches any data element in a pubkey script and that script is either a P2PKH or non-P2SH pay-to-multisig script, the corresponding outpoint is added to the filter.

In addition, because the filter size stays the same even though additional elements are being added to it, the false positive rate increases. Each false positive can result in another element being added to the filter, creating a feedback loop that can (after a certain point) make the filter useless. For this reason, clients using automatic filter updates need to monitor the actual false positive rate and send a new filter when the rate gets too high.

GetAddr

The getaddr message requests an addr message from the receiving node, preferably one with lots of IP addresses of other receiving nodes. The transmitting node can use those IP addresses to quickly update its database of available nodes rather than waiting for unsolicited addr messages to arrive over time.

There is no payload in a getaddr message. See the message header section for an example of a message without a payload.

GetSporks

The getsporks message requests spork messages from the receiving node.

There is no payload in a getsporks message. See the message header section for an example of a message without a payload.

Ping

The ping message helps confirm that the receiving peer is still connected. If a TCP/IP error is encountered when sending the ping message (such as a connection timeout), the transmitting node can assume that the receiving node is disconnected. The response to a ping message is the pong message.

Before protocol version 60000, the ping message had no payload. As of protocol version 60001 and all later versions, the message includes a single field, the nonce.

Bytes Name Data Type Description
8 nonce uint64_t Added in protocol version 60001 as described by BIP31.

Random nonce assigned to this ping message. The responding pong message will include this nonce to identify the ping message to which it is replying.

The annotated hexdump below shows a ping message. (The message header has been omitted.)

0094102111e2af4d ... Nonce

Pong

Added in protocol version 60001 as described by BIP31.

The pong message replies to a ping message, proving to the pinging node that the ponging node is still alive. Dash Core will, by default, disconnect from any clients which have not responded to a ping message within 20 minutes.

To allow nodes to keep track of latency, the pong message sends back the same nonce received in the ping message it is replying to.

The format of the pong message is identical to the ping message; only the message header differs.

Reject

Added in protocol version 70002 as described by BIP61.

The reject message informs the receiving node that one of its previous messages has been rejected.

Bytes Name Data Type Description
Varies message bytes compactSize uint The number of bytes in the following message field.
Varies message string The type of message rejected as ASCII text without null padding. For example: “tx”, “block”, or “version”.
1 code char The reject message code. See the table below.
Varies reason bytes compactSize uint The number of bytes in the following reason field. May be 0x00 if a text reason isn’t provided.
Varies reason string The reason for the rejection in ASCII text. This should not be displayed to the user; it is only for debugging purposes.
Varies extra data varies Optional additional data provided with the rejection. For example, most rejections of tx messages or block messages include the hash of the rejected transaction or block header. See the code table below.

The following table lists message reject codes. Codes are tied to the type of message they reply to; for example there is a 0x10 reject code for transactions and a 0x10 reject code for blocks.

Code In Reply To Extra Bytes Extra Type Description
0x01 any message 0 N/A Message could not be decoded. Be careful of reject message feedback loops where two peers each don’t understand each other’s reject messages and so keep sending them back and forth forever.
0x10 block message 32 char[32] Block is invalid for some reason (invalid proof-of-work, invalid signature, etc). Extra data may include the rejected block’s header hash.
0x10 tx message 32 char[32] Transaction is invalid for some reason (invalid signature, output value greater than input, etc.). Extra data may include the rejected transaction’s TXID.
0x10 ix message 32 char[32] InstantSend transaction is invalid for some reason (invalid tx lock request, conflicting tx lock request, etc.). Extra data may include the rejected transaction’s TXID.
0x11 block message 32 char[32] The block uses a version that is no longer supported. Extra data may include the rejected block’s header hash.
0x11 version message 0 N/A Connecting node is using a protocol version that the rejecting node considers obsolete and unsupported.
0x11 dsa message 0 N/A Connecting node is using a PrivateSend protocol version that the rejecting node considers obsolete and unsupported.
0x11 dsi message 0 N/A Connecting node is using a PrivateSend protocol version that the rejecting node considers obsolete and unsupported.
0x11 dsc message 0 N/A Connecting node is using a PrivateSend protocol version that the rejecting node considers obsolete and unsupported.
0x11 dsf message 0 N/A Connecting node is using a PrivateSend protocol version that the rejecting node considers obsolete and unsupported.
0x11 dsq message 0 N/A Connecting node is using a PrivateSend protocol version that the rejecting node considers obsolete and unsupported.
0x11 dssu message 0 N/A Connecting node is using a PrivateSend protocol version that the rejecting node considers obsolete and unsupported.
0x11 govsync message 0 N/A Connecting node is using a governance protocol version that the rejecting node considers obsolete and unsupported.
0x11 govobj message 0 N/A Connecting node is using a governance protocol version that the rejecting node considers obsolete and unsupported.
0x11 govobjvote message 0 N/A Connecting node is using a governance protocol version that the rejecting node considers obsolete and unsupported.
0x11 mnget message 0 N/A Connecting node is using a masternode payment protocol version that the rejecting node considers obsolete and unsupported.
0x11 mnw message 0 N/A Connecting node is using a masternode payment protocol version that the rejecting node considers obsolete and unsupported.
0x11 txlvote message 0 N/A Connecting node is using an InstantSend protocol version that the rejecting node considers obsolete and unsupported.
0x12 tx message 32 char[32] Duplicate input spend (double spend): the rejected transaction spends the same input as a previously-received transaction. Extra data may include the rejected transaction’s TXID.
0x12 version message 0 N/A More than one version message received in this connection.
0x40 tx message 32 char[32] The transaction will not be mined or relayed because the rejecting node considers it non-standard—a transaction type or version unknown by the server. Extra data may include the rejected transaction’s TXID.
0x41 tx message 32 char[32] One or more output amounts are below the dust threshold. Extra data may include the rejected transaction’s TXID.
0x42 tx message   char[32] The transaction did not have a large enough fee or priority to be relayed or mined. Extra data may include the rejected transaction’s TXID.
0x43 block message 32 char[32] The block belongs to a block chain which is not the same block chain as provided by a compiled-in checkpoint. Extra data may include the rejected block’s header hash.

Reject Codes

Code Description
0x01 Malformed
0x10 Invalid
0x11 Obsolete
0x12 Duplicate
0x40 Non-standard
0x41 Dust
0x42 Insufficient fee
0x43 Checkpoint

The annotated hexdump below shows a reject message. (The message header has been omitted.)

02 ................................. Number of bytes in message: 2
7478 ............................... Type of message rejected: tx
12 ................................. Reject code: 0x12 (duplicate)
15 ................................. Number of bytes in reason: 21
6261642d74786e732d696e707574732d
7370656e74 ......................... Reason: bad-txns-inputs-spent
394715fcab51093be7bfca5a31005972
947baf86a31017939575fb2354222821 ... TXID

SendCmpct

Added in protocol version 70209 of Dash Core as described by BIP152

The sendcmpct message tells the receiving peer whether or not to announce new blocks using a cmpctblock message. It also sends the compact block protocol version it supports. The sendcmpct message is defined as a message containing a 1-byte integer followed by a 8-byte integer. The first integer is interpreted as a boolean and should have a value of either 1 or 0. The second integer is be interpreted as a little-endian version number.

Upon receipt of a sendcmpct message with the first and second integers set to 1, the node should announce new blocks by sending a cmpctblock message.

Upon receipt of a sendcmpct message with the first integer set to 0, the node shouldn’t announce new blocks by sending a cmpctblock message, but instead announce new blocks by sending invs or headers, as defined by BIP130.

Upon receipt of a sendcmpct message with the second integer set to something other than 1, nodes should treat the peer as if they had not received the message (as it indicates the peer will provide an unexpected encoding in cmpctblock messages, and/or other, messages). This allows future versions to send duplicate sendcmpct messages with different versions as a part of a version handshake.

Nodes should check for a protocol version of >= 70209 before sending sendcmpct messages. Nodes shouldn’t send a request for a MSG_CMPCT_BLOCK object to a peer before having received a sendcmpct message from that peer. Nodes shouldn’t request a MSG_CMPCT_BLOCK object before having sent all sendcmpct messages to that peer which they intend to send, as the peer cannot know what protocol version to use in the response.

The structure of a sendcmpct message is defined below.

Bytes Name Data Type Description
1 announce bool 0 - Announce blocks via headers message or inv message
1 - Announce blocks via cmpctblock message
8 version uint64_t The compact block protocol version number

The annotated hexdump below shows a sendcmpct message. (The message header has been omitted.)

01 ................................. Block announce type: Compact Blocks
0100000000000000 ................... Compact block version: 1

SendHeaders

The sendheaders message tells the receiving peer to send new block announcements using a headers message rather than an inv message.

There is no payload in a sendheaders message. See the message header section for an example of a message without a payload.

Spork

Sporks are a mechanism by which updated code is released to the network, but not immediately made active (or “enforced”). Enforcement of the updated code can be activated remotely. Should problems arise, the code can be deactivated in the same manner, without the need for a network-wide rollback or client update.

A spork message may be sent in response to a getsporks message.

The spork message tells the receiving peer the status of the spork defined by the SporkID field. Upon receiving a spork message, the client must verify the signature before accepting the spork message as valid.

Bytes Name Data type Required Description
4 nSporkID int Required ID assigned in spork.h
8 nValue int64_t Required Value assigned to spork
8 nTimeSigned int64_t Required Time the spork value was signed
66 vchSig char[] Required Length (1 byte) + Signature (65 bytes)

Sporks (per src/spork.h)

Spork ID Number Name Description
10001 2 INSTANTSEND_ENABLED Turns on and off InstantSend network wide
10002 3 INSTANTSEND_BLOCK_FILTERING Turns on and off InstantSend block filtering
10004 5 INSTANTSEND_MAX_VALUE Controls the max value for an InstantSend transaction (currently 2000 dash)
10005 6 NEW_SIGS Turns on and off new signature format for Dash-specific messages
10007 8 MASTERNODE_PAYMENT_ENFORCEMENT Requires masternodes to be paid by miners when blocks are processed
10008 9 SUPERBLOCKS_ENABLED Superblocks are enabled (10% of the block reward allocated to fund the dash treasury for funding approved proposals)
10009 10 MASTERNODE_PAY_UPDATED_NODES Only current protocol version masternode’s will be paid (not older nodes)
10011 12 RECONSIDER_BLOCKS Forces reindex of a specified number of blocks to recover from unintentional network forks
10013 14 REQUIRE_SENTINEL_FLAG Only masternode’s running sentinel will be paid
10014 15 DETERMINISTIC_MNS_ENABLED Deterministic masternode lists are enabled
10015 16 INSTANTSEND_AUTOLOCKS Automatic InstantSend for transactions with <=4 inputs (also eliminates the special InstantSend fee requirement for these transactions)
       
    Removed Sporks  
10012 13 OLD_SUPERBLOCK_FLAG Removed in Dash Core 0.12.3. No network function since block 614820

To verify vchSig, compare the hard-coded spork public key (strSporkPubKey from src/chainparams.cpp) with the public key recovered from the spork message’s hash and vchSig value (implementation details for Dash Core can be found in CPubKey::RecoverCompact). The hash is a double SHA-256 hash of:

  • The spork magic message ("DarkCoin Signed Message:\n")
  • nSporkID + nValue + nTimeSigned
Network Spork Pubkey (wrapped)
Mainnet 04549ac134f694c0243f503e8c8a9a986f5de6610049c40b07816809b0d1
d06a21b07be27b9bb555931773f62ba6cf35a25fd52f694d4e1106ccd237
a7bb899fdd
Testnet3 046f78dcf911fbd61910136f7f0f8d90578f68d0b3ac973b5040fb7afb50
1b5939f39b108b0569dca71488f5bbf498d92e4d1194f6f941307ffd95f7
5e76869f0e
RegTest Undefined
Devnets 046f78dcf911fbd61910136f7f0f8d90578f68d0b3ac973b5040fb7afb50
1b5939f39b108b0569dca71488f5bbf498d92e4d1194f6f941307ffd95f7
5e76869f0e

The following annotated hexdump shows a spork message.

11270000 .................................... Spork ID: Spork 2 InstantSend enabled (10001)
0000000000000000 ............................ Value (0)
2478da5900000000 ............................ Epoch time: 2017-10-08 19:10:28 UTC (1507489828)

41 .......................................... Signature length: 65

1b6762d3e70890b5cfaed5d1fd72121c
d32020c827a89f8128a00acd210f4ea4
1b36c26c3767f8a24f48663e189865ed
403ed1e850cdb4207cdd466419d9d183
45 .......................................... Masternode Signature

VerAck

The verack message acknowledges a previously-received version message, informing the connecting node that it can begin to send other messages. The verack message has no payload; for an example of a message with no payload, see the message headers section.

Version

The version message provides information about the transmitting node to the receiving node at the beginning of a connection. Until both peers have exchanged version messages, no other messages will be accepted.

If a version message is accepted, the receiving node should send a verack message—but no node should send a verack message before initializing its half of the connection by first sending a version message.

Bytes Name Data Type Required/Optional Description
4 version int32_t Required The highest protocol version understood by the transmitting node. See the protocol version section.
8 services uint64_t Required The services supported by the transmitting node encoded as a bitfield. See the list of service codes below.
8 timestamp int64_t Required The current Unix epoch time according to the transmitting node’s clock. Because nodes will reject blocks with timestamps more than two hours in the future, this field can help other nodes to determine that their clock is wrong.
8 addr_recv services uint64_t Required Added in protocol version 106.

The services supported by the receiving node as perceived by the transmitting node. Same format as the ‘services’ field above. Dash Core will attempt to provide accurate information.
16 addr_recv IP address char Required Added in protocol version 106.

The IPv6 address of the receiving node as perceived by the transmitting node in big endian byte order. IPv4 addresses can be provided as IPv4-mapped IPv6 addresses. Dash Core will attempt to provide accurate information.
2 addr_recv port uint16_t Required Added in protocol version 106.

The port number of the receiving node as perceived by the transmitting node in big endian byte order.
8 addr_trans services uint64_t Required The services supported by the transmitting node. Should be identical to the ‘services’ field above.
16 addr_trans IP address char Required The IPv6 address of the transmitting node in big endian byte order. IPv4 addresses can be provided as IPv4-mapped IPv6 addresses. Set to ::ffff:127.0.0.1 if unknown.
2 addr_trans port uint16_t Required The port number of the transmitting node in big endian byte order.
8 nonce uint64_t Required A random nonce which can help a node detect a connection to itself. If the nonce is 0, the nonce field is ignored. If the nonce is anything else, a node should terminate the connection on receipt of a version message with a nonce it previously sent.
Varies user_agent bytes compactSize uint Required Number of bytes in following user_agent field. If 0x00, no user agent field is sent.
Varies user_agent string Required if user_agent bytes > 0 Renamed in protocol version 60000.

User agent as defined by BIP14. Previously called subVer.

Dash Core limits the length to 256 characters.
4 start_height int32_t Required The height of the transmitting node’s best block chain or, in the case of an SPV client, best block header chain.
1 relay bool Optional Added in protocol version 70001 as described by BIP37.

Transaction relay flag. If 0x00, no inv messages or tx messages announcing new transactions should be sent to this client until it sends a filterload message or filterclear message. If the relay field is not present or is set to 0x01, this node wants inv messages and tx messages announcing new transactions.

The following service identifiers have been assigned.

Value Name Description
0x00 Unnamed This node is not a full node. It may not be able to provide any data except for the transactions it originates.
0x01 NODE_NETWORK This is a full node and can be asked for full blocks. It should implement all protocol features available in its self-reported protocol version.
0x02 NODE_GETUTXO This node is capable of responding to the getutxo protocol request. Dash Core does not support this service.
0x04 NODE_BLOOM This node is capable and willing to handle bloom-filtered connections. Dash Core nodes used to support this by default, without advertising this bit, but no longer do as of protocol version 70201 (= NO_BLOOM_VERSION)

The following annotated hexdump shows a version message. (The message header has been omitted and the actual IP addresses have been replaced with RFC5737 reserved IP addresses.)

3e120100 .................................... Protocol version: 70206
0500000000000000 ............................ Services: NODE_NETWORK (1) + NODE_BLOOM (4)
bc8f5e5400000000 ............................ Epoch time: 1415483324

0100000000000000 ............................ Receiving node's services
00000000000000000000ffffc61b6409 ............ Receiving node's IPv6 address
270f ........................................ Receiving node's port number

0500000000000000 ............................ Transmitting node's services
00000000000000000000ffffcb0071c0 ............ Transmitting node's IPv6 address
270f ........................................ Transmitting node's port number

128035cbc97953f8 ............................ Nonce

14 .......................................... Bytes in user agent string: 20
2f4461736820436f72653a302e31322e312e352f..... User agent: /Satoshi:0.9.2.1/

851f0b00 .................................... Start height: 728965
01 .......................................... Relay flag: true

InstantSend Messages

The following network messages all help control the InstantSend feature of Dash. InstantSend uses the masternode network to lock transaction inputs and enable secure, instantaneous transactions. For additional details, refer to the Developer Guide InstantSend section.

Overview Of P2P Protocol InstantSend Request And Reply Messages

ix

The ix message (transaction lock request) has the same structure as the tx message. The masternode network responds with txlvote messages if the transaction inputs can be locked.

txlvote

The txlvote message (transaction lock vote) is sent by masternodes to indicate approval of a transaction lock request ix message.

Bytes Name Data type Required Description
32 txHash uint256 Required TXID of the transaction to lock
36 outPoint outpoint Required The unspent outpoint to lock in this transaction
36 outpointMasternode outpoint Required The outpoint of the masternode which is signing the vote
66* vchMasternodeSignature char[] Required 66 bytes in most cases. Length (1 byte) + Signature (65 bytes)

The following annotated hexdump shows a txlvote message. (The message header has been omitted.)

3c121fb4a12b2f715e2f70a9fa282115
be197dde14073959fb2a2b8e95a7418f ..... TXID

Outpoint to lock
| bb607995757c6a6efd6429215dcb3688
| b252d34d835c81fed310fd905f487020 ... Outpoint TXID
| 01000000 ........................... Outpoint index number: 1

Masternode Outpoint
| de9029c7e9b7eb7cd11f27ba670b2349
| 0c3f0717b86ed949c316874589405cd2 ... Outpoint TXID
| 00000000 ........................... Outpoint index number: 0

41 ................................... Signature length: 65

1ccc39ffb9c62111a8c82823d3ce61d2
380db4e8f76ec238d568908f37558a90
4e79566a53663de12ec2be1183c87d61
250e8ebd57be171be1d4b5e89b69c263
88 ................................... Masternode Signature

PrivateSend Messages

The following network messages all help control the PrivateSend (formerly DarkSend) coin mixing features built in to Dash and facilitated by the masternode network.

Since the messages are all related to a single process, this diagram shows them sequentially numbered. The dssu message (not shown) is sent by the masternode in conjunction with some responses. For additional details, refer to the Developer Guide PrivateSend section.

Overview Of P2P Protocol PrivateSend Request And Reply Messages

dsa

The dsa message allows a node to join a mixing pool. A collateral fee is required and may be forfeited if the client acts maliciously. The message operates in two ways:

  1. When sent to a masternode without a current mixing queue, it initiates the start of a new mixing queue

  2. When sent to a masternode with a current mixing queue, it attempts to join the existing queue

Dash Core starts a new queue ~33% of the time and attempts to join an existing queue the remainder of the time.

Bytes Name Data type Required Description
4 nDenom int Required Denomination that will be exclusively used when submitting inputs into the pool
4 nInputCount int Required Added in protocol version 70209. Only present when Spork 6 is active.

Number of inputs required to join the queue
216+ txCollateral tx message Required Collateral TX that will be charged if this client acts maliciously

The following annotated hexdump shows a dsa message. (The message header has been omitted.) Note that the ‘Required inputs’ bytes will only be preset if Spork 6 is active and protocol version => 70209.

02000000 ................................... Denomination: 1 Dash (2)

03000000 ................................... Inputs required: 3

Collateral Transaction
| Previous Output
| |
| | 010000000183bd1980c71c38f035db9b
| | 14d7f934f7d595181b3436e362899026 ....... Outpoint TXID
| | 19f3f7d3 ............................... Outpoint index number: 3556242201
|
| 83 ....................................... Bytes in sig. script: 131
|
| 000000006b483045022100f4d8fa0ae4132235fe
| cd540a62715ccfb1c9a97f8698d066656e30bb1e
| 1e06b90220301b4cc93f38950a69396ed89dfcc0
| 8e72ec8e6e7169463592a0bf504946d98b812102
| fa4b9c0f9e76e06d57c75cab9c8368a62a1ce8db
| 6eb0c25c3e0719ddd9ab549cffffffff01e09304
| 00000000001976a914f895 ................... Secp256k1 signature: None
|
| 6a4eb0e5 ................................. Sequence number: 3853536874

dsc

The dsc message indicates a PrivateSend mixing session is complete.

Bytes Name Data type Required Description
4 nSessionID int Required ID of the mixing session
4 nMessageID int Required ID of the message describing the result of the mixing session

Reference the Message IDs table under the dssu message for descriptions of the Message ID values.

The following annotated hexdump shows a dsc message. (The message header has been omitted.)

d9070700 ............................. Session ID: 791686
14000000 ............................. Message ID: MSG_SUCCESS (20)

dsf

The dsf message is sent by the masternode as the final mixing transaction in a PrivateSend mixing session. The masternode expects nodes in the mixing session to respond with a dss message.

Bytes Name Data type Required Description
4 nSessionID int Required ID of the mixing session
# txFinal tx message Required Final mixing transaction with unsigned inputs

The following annotated hexdump shows a dsf message. (The message header has been omitted.) Transaction inputs/outputs are only shown for a single node (compare with the dsi message and dss message hexdumps).

86140c00 ............................. Session ID: 791686

Transaction Message
| 01000000 ................................. Version: 1
|
| 0f ......................................... Number of inputs: 15
|
| [...] ...................................... 5 transaction inputs omitted
|
| Transaction input #6
| |
| | 36bdc3796c5630225f2c86c946e2221a
| | 9958378f5d08da380895c2656730b5c0 ......... Outpoint TXID
| | 02000000 ................................. Outpoint index number: 0
| |
| | 00 ....................................... Bytes in sig. script: 0
| | .......................................... Secp256k1 signature: None
| |
| | ffffffff ................................. Sequence number: UINT32_MAX
|
| Transaction input #7
| |
| | 36bdc3796c5630225f2c86c946e2221a
| | 9958378f5d08da380895c2656730b5c0 ......... Outpoint TXID
| | 0f000000 ................................. Outpoint index number: 15
| |
| | 00 ....................................... Bytes in sig. script: 0
| | .......................................... Secp256k1 signature: None
| |
| | ffffffff ................................. Sequence number: UINT32_MAX
|
| Transaction input #8
| |
| | 36bdc3796c5630225f2c86c946e2221a
| | 9958378f5d08da380895c2656730b5c0 ......... Outpoint TXID
| | 0d000000 ................................. Outpoint index number: 13
| |
| | 00 ....................................... Bytes in sig. script: 0
| | .......................................... Secp256k1 signature: None
| |
| | ffffffff ................................. Sequence number: UINT32_MAX
|
|
| [...] ...................................... 7 more transaction inputs omitted
|
|
| 0f ......................................... Number of outputs: 15
|
| Transaction output #1
| | e8e4f50500000000 ......................... Duffs (1.00001 Dash)
| |
| | 19 ....................................... Bytes in pubkey script: 25
| | | 76 ..................................... OP_DUP
| | | a9 ..................................... OP_HASH160
| | | 14 ..................................... Push 20 bytes as data
| | | | 14826d7ba05cf76588a5503c03951dc9
| | | | 14c91b6c ............................. PubKey hash
| | | 88 ..................................... OP_EQUALVERIFY
| | | ac ..................................... OP_CHECKSIG
|
|
| [...] ...................................... 3 transaction outputs omitted
|
|
| Transaction output #5
| | e8e4f50500000000 ......................... 100,001,000 Duffs (1.0001 Dash)
| |
| | 19 ....................................... Bytes in pubkey script: 25
| | | 76 ..................................... OP_DUP
| | | a9 ..................................... OP_HASH160
| | | 14 ..................................... Push 20 bytes as data
| | | | 426614716e94812d483bca32374f6ac8
| | | | cd121b0d ............................. PubKey hash
| | | 88 ..................................... OP_EQUALVERIFY
| | | ac ..................................... OP_CHECKSIG
|
|
| [...] ...................................... 9 transaction outputs omitted
|
|
| Transaction output #15
| | e8e4f50500000000 ......................... 100,001,000 Duffs (1.0001 Dash)
| |
| | 19 ....................................... Bytes in pubkey script: 25
| | | 76 ..................................... OP_DUP
| | | a9 ..................................... OP_HASH160
| | | 14 ..................................... Push 20 bytes as data
| | | | f01197177de2358928196a543b2bbd97
| | | | 3c2ab002 ............................. PubKey hash
| | | 88 ..................................... OP_EQUALVERIFY
| | | ac ..................................... OP_CHECKSIG
|
| 00000000 ................................... locktime: 0 (a block height)

dsi

The dsi message replies to a dsq message that has the Ready field set to 0x01. The dsi message contains user inputs for mixing along with the outputs and a collateral. Once the masternode receives dsi messages from all members of the pool, it responds with a dsf message.

Bytes Name Data type Required Description
? vecTxDSIn CTxDSIn[] Required Vector of users inputs (CTxDSIn serialization is equal to CTxIn serialization)
216+ txCollateral tx message Required Collateral transaction which is used to prevent misbehavior and also to charge fees randomly
? vecTxDSOut CTxDSOut[] Required Vector of user outputs (CTxDSOut serialization is equal to CTxOut serialization)

The following annotated hexdump shows a dsi message. (The message header has been omitted.)

User inputs
| 03 ......................................... Number of inputs: 3
|
| Transaction input #1
| |
| | 36bdc3796c5630225f2c86c946e2221a
| | 9958378f5d08da380895c2656730b5c0 ......... Outpoint TXID
| | 02000000 ................................. Outpoint index number: 2
| |
| | 00 ....................................... Bytes in sig. script: 0
| | .......................................... Secp256k1 signature: None
| |
| | ffffffff ................................. Sequence number: UINT32_MAX
|
| Transaction input #2
| |
| | 36bdc3796c5630225f2c86c946e2221a
| | 9958378f5d08da380895c2656730b5c0 ......... Outpoint TXID
| | 0f000000 ................................. Outpoint index number: 15
| |
| | 00 ....................................... Bytes in sig. script: 0
| | .......................................... Secp256k1 signature: None
| |
| | ffffffff ................................. Sequence number: UINT32_MAX
|
| Transaction input #3
| |
| | 36bdc3796c5630225f2c86c946e2221a
| | 9958378f5d08da380895c2656730b5c0 ......... Outpoint TXID
| | 0d000000 ................................. Outpoint index number: 13
| |
| | 00 ....................................... Bytes in sig. script: 0
| | .......................................... Secp256k1 signature: None
| |
| | ffffffff ................................. Sequence number: UINT32_MAX

Collateral Transaction
| 01000000 ................................... Version: 1
|
| 01 ......................................... Number of inputs: 1
|
| Previous Output
| |
| | 83bd1980c71c38f035db9b14d7f934f7
| | d595181b3436e36289902619f3f7d383 ......... Outpoint TXID
| | 00000000 ................................. Outpoint index number: 0
| |
| | 6b ....................................... Bytes in sig. script: 107
| |
| | 483045022100f4d8fa0ae4132235fecd540a
| | 62715ccfb1c9a97f8698d066656e30bb1e1e
| | 06b90220301b4cc93f38950a69396ed89dfc
| | c08e72ec8e6e7169463592a0bf504946d98b
| | 812102fa4b9c0f9e76e06d57c75cab9c8368
| | a62a1ce8db6eb0c25c3e0719ddd9ab549c ....... Secp256k1 signature
| |
| | ffffffff ................................. Sequence number: UINT32_MAX
|
| 01 ......................................... Number of outputs: 1
|
| | e093040000000000 ......................... 300,000 Duffs (0.003 Dash)
| |
| | 19 ....................................... Bytes in pubkey script: 25
| | | 76 ..................................... OP_DUP
| | | a9 ..................................... OP_HASH160
| | | 14 ..................................... Push 20 bytes as data
| | | | f8956a4eb0e53b05ee6b30edfd2770b5
| | | | 26c1f1bb ............................. PubKey hash
| | | 88 ..................................... OP_EQUALVERIFY
| | | ac ..................................... OP_CHECKSIG
|
| 00000000 ................................... locktime: 0 (a block height)

User outputs
| 03 ......................................... Number of outputs: 3
|
| Transaction output #1
| | e8e4f50500000000 ......................... 100,001,000 Duffs (1.0001 Dash)
| |
| | 19 ....................................... Bytes in pubkey script: 25
| | | 76 ..................................... OP_DUP
| | | a9 ..................................... OP_HASH160
| | | 14 ..................................... Push 20 bytes as data
| | | | 14826d7ba05cf76588a5503c03951dc9
| | | | 14c91b6c ............................. PubKey hash
| | | 88 ..................................... OP_EQUALVERIFY
| | | ac ..................................... OP_CHECKSIG
|
| Transaction output #2
| | e8e4f50500000000 ......................... 100,001,000 Duffs (1.0001 Dash)
| |
| | 19 ....................................... Bytes in pubkey script: 25
| | | 76 ..................................... OP_DUP
| | | a9 ..................................... OP_HASH160
| | | 14 ..................................... Push 20 bytes as data
| | | | f01197177de2358928196a543b2bbd97
| | | | 3c2ab002 ............................. PubKey hash
| | | 88 ..................................... OP_EQUALVERIFY
| | | ac ..................................... OP_CHECKSIG
|
| Transaction output #3
| | e8e4f50500000000 ......................... 100,001,000 Duffs (1.0001 Dash)
| |
| | 19 ....................................... Bytes in pubkey script: 25
| | | 76 ..................................... OP_DUP
| | | a9 ..................................... OP_HASH160
| | | 14 ..................................... Push 20 bytes as data
| | | | 426614716e94812d483bca32374f6ac8
| | | | cd121b0d ............................. PubKey hash
| | | 88 ..................................... OP_EQUALVERIFY
| | | ac ..................................... OP_CHECKSIG

dsq

The dsq message provides nodes with mixing queue details and notifies them when to sign final mixing TX messages.

If the message indicates the queue is not ready, the node verifies the message is valid. It also verifies that the masternode is not flooding the network with dsq messages in an attempt to dominate the queuing process. It then relays the message to its connected peers.

If the message indicates the queue is ready, the node responds with a dsi message.

Bytes Name Data type Required Description
4 nDenom int Required Denomination allowed in this mixing session
4 nInputCount int Required Added in protocol version 70209. Only present when Spork 6 is active.

Number of inputs required to participate in this mixing session
36 masternodeOutPoint outPoint Required The unspent outpoint of the masternode (holding 1000 DASH) which is hosting this session
8 nTime int64_t Required Time this dsq message was created
1 fReady bool Required Indicates if the mixing pool is ready to be executed
66* vchSig char[] Required Signature of this message by masternode verifiable via pubKeyMasternode (Length (1 byte) + Signature (65 bytes))

Denominations (per src/privatesend.cpp)

Value Denomination
1 10 Dash
2 1 Dash
4 0.1 Dash
8 0.01 Dash

The following annotated hexdump shows a dsq message. (The message header has been omitted.) Note that the ‘Required inputs’ bytes will only be preset if Spork 6 is active and protocol version => 70209.

08000000 ............................. Denomination: 0.01 Dash (8)

03000000 ............................. Required input(s): 3

Masternode Outpoint
| aeed0e77c6db30a616507a37a129bc88
| 1811f08afc51dd485d5322f36c1f04c5 ... Outpoint TXID
| 01000000 ........................... Outpoint index number: 1

1318a85900000000 ..................... Create Time: 2017-08-31 14:07:15 UTC

00 ................................... Ready: 0

41 ................................... Signature length: 65

1bd74386ea4e111197f1b4b4660c1415
13486745ca10ba0632426ed3a644d941
047e43c988680904d4a4fcf551d8813c
ec12d47ae9b00e870db294cd66708ab7
dc ................................... Masternode Signature

dss

The dss message replies to a dsf message sent by the masternode managing the mixing session. The dsf message provides the unsigned transaction inputs for all members of the mixing pool. Each node verifies that the final transaction matches what is expected. They then sign any transaction inputs belonging to them and then relay them to the masternode via this dss message.

Once the masternode receives and validates all dss messages, it issues a dsc message. If a node does not respond to a dsf message with signed transaction inputs, it may forfeit the collateral it provided. This is to minimize malicious behavior.

Bytes Name Data type Required Description
# inputs txIn[] Required Signed inputs for mixing session

The following annotated hexdump shows a dss message. (The message header has been omitted.) Note that these will be the same transaction inputs that were supplied (unsiged) in the dsi message.

User inputs
| 03 ......................................... Number of inputs: 3
|
| Transaction input #1
| |
| | 36bdc3796c5630225f2c86c946e2221a
| | 9958378f5d08da380895c2656730b5c0 ......... Outpoint TXID
| | 02000000 ................................. Outpoint index number: 2
| |
| | 6b ....................................... Bytes in sig. script: 107
| | 483045022100b3a861dca83463aabf5e4a14a286
| | 1b9c2e51e0dedd8a13552e118bf74eb4a68d0220
| | 4a91c416768d27e6bdcfa45d28129841dbcc728b
| | f0bbec9701cfc4e743d23adf812102cc4876c9da
| | 84417dec37924e0479205ce02529bb0ba88631d3
| | ccc9cfcdf00173 ........................... Secp256k1 signature
| |
| | ffffffff ................................. Sequence number: UINT32_MAX
|
| Transaction input #2
| |
| | 36bdc3796c5630225f2c86c946e2221a
| | 9958378f5d08da380895c2656730b5c0 ......... Outpoint TXID
| | 0f000000 ................................. Outpoint index number: 15
| |
| | 6a ....................................... Bytes in sig. script: 106
| | 4730440220268f3b7799ca4ec132e511a4756019
| | c56016f7771561dc0597d84e9b1fa9fc08022067
| | 5199b9b3f9a7eba69b7bbb4aa2a413d955762f9d
| | 68be5a9c02c6772c8078fd812103258925f0dbbf
| | 9d5aa20a675459fa2e86c9f9061dee82a00dca73
| | 9080f051d891 ............................. Secp256k1 signature
| |
| | ffffffff ................................. Sequence number: UINT32_MAX
|
| Transaction input #3
| |
| | 36bdc3796c5630225f2c86c946e2221a
| | 9958378f5d08da380895c2656730b5c0 ......... Outpoint TXID
| | 0d000000 ................................. Outpoint index number: 13
| |
| | 6a ....................................... Bytes in sig. script: 106
| | 4730440220404bb067e0c94a2bd75c6798c1af8c
| | 95e8b92f5e437cff2bcb4660f24a34d06d02203a
| | b707bd371a84a9e7bd1fbe3b0c939fd23e0a9165
| | de78809b9310372a4b3879812103a9a6c5204811
| | a8cab04b595ed622a1fed6efd3b2d888fadd0c97
| | 3737fcdf2bc7 ............................. Secp256k1 signature
| |
| | ffffffff ................................. Sequence number: UINT32_MAX

dssu

The dssu message provides a mixing pool status update.

Bytes Name Data type Required Description
4 nMsgSessionID int Required Session ID
4 nMsgState int Required Current state of mixing process
4 nMsgEntriesCount int Required Number of entries in the mixing pool
4 nMsgStatusUpdate int Required Update state and/or signal if entry was accepted or not
4 nMsgMessageID int Required ID of the typical masternode reply message

Pool State

State Description
0 POOL_STATE_IDLE
1 POOL_STATE_QUEUE
2 POOL_STATE_ACCEPTING_ENTRIES
3 POOL_STATE_SIGNING
4 POOL_STATE_ERROR
5 POOL_STATE_SUCCESS

Pool Status Update

Status Description
0 STATUS_REJECTED
1 STATUS_ACCEPTED

Message IDs

Code Description
0x00 ERR_ALREADY_HAVE
0x01 ERR_DENOM
0x02 ERR_ENTRIES_FULL
0x03 ERR_EXISTING_TX
0x04 ERR_FEES
0x05 ERR_INVALID_COLLATERAL
0x06 ERR_INVALID_INPUT
0x07 ERR_INVALID_SCRIPT
0x08 ERR_INVALID_TX
0x09 ERR_MAXIMUM
0x0A (10) ERR_MN_LIST
0x0B (11) ERR_MODE
0x0C (12) ERR_NON_STANDARD_PUBKEY
0x0D (13) ERR_NOT_A_MN (Not used)
0x0E (14) ERR_QUEUE_FULL
0x0F (15) ERR_RECENT
0x10 (16) ERR_SESSION
0x11 (17) ERR_MISSING_TX
0x12 (18) ERR_VERSION
0x13 (19) MSG_NOERR
0x14 (20) MSG_SUCCESS
0x15 (21) MSG_ENTRIES_ADDED

The following annotated hexdump shows a dssu message. (The message header has been omitted.)

86140c00 ............................. Session ID: 791686
02000000 ............................. State: POOL_STATE_ACCEPTING_ENTRIES (2)
03000000 ............................. Entries: 3
01000000 ............................. Status Update: STATUS_ACCEPTED (1)
13000000 ............................. Message ID: MSG_NOERR (0x13)

dstx

The dstx message allows masternodes to broadcast subsidized transactions without fees (to provide security in mixing).

Bytes Name Data type Required Description
# tx tx message Required The transaction
36 masternodeOutPoint outPoint Required The unspent outpoint of the masternode (holding 1000 DASH) which is signing the message
66 vchSig char[] Required Signature of this message by masternode verifiable via pubKeyMasternode (Length (1 byte) + Signature (65 bytes))
8 sigTime int64_t Require Time this message was signed

The following annotated hexdump shows a dstx message. (The message header has been omitted.)

Transaction Message
| 01000000 ................................. Version: 1
|
| 0b ......................................... Number of inputs: 11
|
| Transaction input #1
| |
| | 0adb782b2170018eada54534be880e70
| | 74ed8307a566731119b1782362af43ad ......... Outpoint TXID
| | 05000000 ................................. Outpoint index number: 5
| |
| | 6a ....................................... Bytes in sig. script: 106
| | 47304402204ed56f525ae6df707f9cbe
| | 55c78d82bbcc02daa1fb27b0bf54588a
| | 446dcc804102200c4e03c4a2b9a90aef
| | 9f01de7c28812a0e8b280e6c153b0bd8
| | 26d2ff660102e18121028c96903b2709
| | 7b331d55abd1f42d2ff6cc7c784ab839
| | 7c232b73a34a149a348e ..................... Secp256k1 signature
| |
| | ffffffff ................................. Sequence number: UINT32_MAX
|
| [...] ...................................... 10 more transaction inputs omitted
|
|
| 0b ......................................... Number of outputs: 11
|
| Transaction output #1
| | e8e4f50500000000 ......................... Duffs (1.00001000 Dash)
| |
| | 19 ....................................... Bytes in pubkey script: 25
| | | 76 ..................................... OP_DUP
| | | a9 ..................................... OP_HASH160
| | | 14 ..................................... Push 20 bytes as data
| | | | 0febbeaa8818b2c2f80fb8c98f90bdae
| | | | 41fe5c26 ............................. PubKey hash
| | | 88 ..................................... OP_EQUALVERIFY
| | | ac ..................................... OP_CHECKSIG
|
| [...] ...................................... 10 more transaction outputs omitted
|
|
| 00000000 ................................... locktime: 0 (a block height)

Masternode Unspent Outpoint
| 387d522def2abfb9bdd15be899f074f3
| 49b414cef078ec642e1d14b42996b9fc ......... Outpoint TXID
| 00000000 ................................. Outpoint index number: 0

1b6fb8f90f0df6e502bc10aab9604e49
2d14214e05331c9761c834d55c7536e3
3369e5909479ea88116aad7ea64587d9
59364326c97d7f249f7b9293e120a5b6
1c ................................... Masternode Signature

ece5a95900000000 ..................... Signature Timestamp

Masternode Messages

The following network messages enable the masternode features built in to Dash.

Overview Of P2P Protocol Masternode Request And Reply Messages

For additional details, refer to the Developer Guide Masternode Sync and Masternode Payment sections.

dseg

Warning icon NOTE: This message will be deprecated following activation of DIP3 which implements deterministic masternode lists.

The dseg message requests either the entire masternode list or a specific entry. To request the list of all masternodes, use an empty txIn (TXID of all zeros and an index of 0xFFFFFFFF). To request information about a specific masternode, use the unspent outpoint associated with that masternode.

The response to a dseg message is an mnb message inventory and an mnp message inventory for each requested masternode. Masternodes ignore this request if they are not fully synced.

Bytes Name Data type Required Description
36 masternodeOutPoint outPoint Required Request options:
All Entries - empty txIn
Single Entry - Masternode’s unspent outpoint which is holding 1000 DASH
Note: Dash Core only allows nodes to request the entire list every 3 hours.
Additional requests sent prior to then may result in the node being banned.

The following annotated hexdump shows a dseg message requesting all masternodes. (The message header has been omitted.)

Masternode Unspent Outpoint
| 00000000000000000000000000000000
| 00000000000000000000000000000000 ......... Outpoint TXID
| ffffffff ................................. Outpoint index number: 0

The following annotated hexdump shows a dseg message requesting a specific masternode. (The message header has been omitted.)

Masternode Unspent Outpoint
| 7fe33a2901aa654598ae0af572d4fbec
| ee97af2d0276f189d177dee5848ef3da ......... Outpoint TXID
| 00000000 ................................. Outpoint index number: 0

mnb

Warning icon NOTE: This message will be deprecated following activation of DIP3 which implements deterministic masternode lists.

The mnb message is sent whenever a masternode comes online or a client is syncing. The masternode will send this message which describes the masternode entry and how to validate messages from it.

Bytes Name Data type Required Description
36 outPoint outPoint Required The unspent outpoint of the masternode (holding 1000 DASH) which is signing the message
# addr CService Required IPv4 address of the masternode
33-65 pubKeyCollateralAddress CPubKey Required CPubKey of the main 1000 DASH unspent outpoint. Length determined by if it is a compressed public key or not.
33-65 pubKeyMasternode CPubKey Required CPubKey of the secondary signing key (For all messaging other than the announce message). Length determined by if it is a compressed public key or not.
66 sig char[] Required Signature of this message verifiable via pubKeyMasternode (Length (1 byte) + Signature (65 bytes))
8 sigTime int64_t Required Time which the signature was created
4 nProtocolVersion int Required The protocol version of the masternode
# lastPing mnp message Required The last known ping of the masternode
8 nLastDsq int64_t Deprecated Removed in Dash Core 0.12.3.0

The last time the masternode sent a dsq message (for mixing) (DEPRECATED)

The following annotated hexdump shows a mnb message. (The message header has been omitted and the actual IP address has been replaced with a RFC5737 reserved IP address.)

Masternode Unspent Outpoint
| 3fbc7d4a8f68ba6ecb02a8db34d1f5b6
| 2dc105f0b5c3505243435cf815d02394 ......... Outpoint TXID
| 01000000 ................................. Outpoint index number: 1

Masternode Address
| 00000000000000000000ffffc0000233 ......... IP Address: ::ffff:192.0.2.51
| 270f ..................................... Port: 9999

Collateral Public Key
| 21 ....................................... Key Size: 33
| 02 ....................................... Key Type: 2 - Compressed (even)
| 02a47a6845936a4199e126d35399dd09
| 97c1aaf89a3fe70d474c53f29624a43a5b ....... Public Key

Masternode Public Key
| 41 ....................................... Key Size: 65
| 04 ....................................... Key Type: 4 - Uncompressed
| 04da252243305d604cab90480880af4a
| b5cea3a934c91393452e9b7b4c97a87e
| 198bc809916ac2c27436a1db9c28d0aa
| bfefec4dc3c2193835fd9a56c31150c633 ....... Public Key

Message Signature
| 41 ....................................... Bytes in signature: 65
| 1fb80f9ba8c110835e4a7dd4c8deccd7
| 89027663d00084d9a99ef579a9b5601f
| 40727b27e91aab2897a078f63976ae25
| 3ff8f01e56862e953278f432530f6ee080 ....... Signature

4728ef5800000000 ........................... Sig. Timestamp: 2017-04-13 07:27:03 UTC

3e120100 ................................... Protocol Version: 70206

Masternode Ping Message
| Masternode Unspent Outpoint
| | 3fbc7d4a8f68ba6ecb02a8db34d1f5b6
| | 2dc105f0b5c3505243435cf815d02394 ........ Outpoint TXID
| | 01000000 ................................ Outpoint index number: 1
|
| 94fc0fad18b166c2fedf1a5dc0511372
| 26c353d57e086737ff05000000000000 ......... Chaintip block hash
|
| 66c1a95900000000 ......................... Sig. Timestamp: 2017-10-01 21:21:58 UTC
|
| Masternode Signature
| | 41 ..................................... Bytes in signature: 65
| | 1b3017c49a03e2d77083f3c92a8c2e4c
| | d815d068b6256498a719e3cb6a34f774
| | ec6434cfcbb7a5a51704350a05903287
| | eecc82e6b40ac2fcfa2df29ddaa6c4fc
| | b8 ..................................... Masternode Signature

mnget

Warning icon NOTE: This message will be deprecated following activation of DIP3 which implements deterministic masternode lists.

The mnget message requests masternode payment sync. The response to an mnget message is mnw message inventories. Masternodes ignore this request if they are not fully synced.

Note: Dash Core limits how frequently a masternode payment sync can be
requested. Frequent requests will result in the node being banned.

There is no payload in a mnget message. See the message header section for an example of a message without a payload.

Warning icon The following information is provided for historical reference only.

In protocol versions <=70208, the mnget message has a payload consisting of an integer value requesting a specific number of payment votes. In protocol versions >70208, the mnget message has no payload.

Bytes Name Data type Required Description
4 nMnCount int Deprecated Deprecated in Dash Core 0.12.3

Number of masternode payment votes to request

The following annotated hexdump shows a pre-0.12.3 mnget message. (The message header has been omitted.)

a8170000 ................................... Count: 6056

mnp

Warning icon NOTE: This message will be deprecated following activation of DIP3 which implements deterministic masternode lists.

The mnp message is sent by masternodes every few minutes to ping the network with a message that propagates across the whole network. Dash Core currently uses a minimum masternode ping time of 10 minutes.

Bytes Name Data type Required Description
36 masternodeOutPoint outPoint Required The unspent outpoint of the masternode (holding 1000 DASH) which is signing the message
32 blockHash uint256 Required Block hash from 12 blocks ago (current chaintip minus 12). This offset allows nodes to be slightly out of sync.
8 sigTime int64_t Required Time which the signature was created
66* vchSig char[] Required Signature of this message by masternode - verifiable via pubKeyMasternode (66 bytes in most cases. Length (1 byte) + Signature (65 bytes))
1 fSentinelIsCurrent bool Required True if last sentinel ping was current
4 nSentinelVersion uint32_t Required The version of Sentinel running on the masternode which is signing the message
4 nDaemonVersion uint32_t Required The version of dashd on the masternode which is signing the message (i.e. CLIENT_VERSION)

The following annotated hexdump shows a mnp message. (The message header has been omitted.)

Masternode Unspent Outpoint
| ce12d7f32945c9544c5aeb0dcf131174
| a6269b64b40f9461595e26689b573c58 ......... Outpoint TXID
| 00000000 ................................. Outpoint index number: 0

6c7da9d9eae78644a3406eac8ed0be3b
f15eb4bc369acc95b106f37400000000 ........... Chaintip block hash

3c84025a00000000 ........................... Sig. Timestamp: 2017-11-08 04:12:44 UTC

Masternode Signature
| 41 ....................................... Bytes in signature: 65
| 1c7572842058a2075b8a996c3905e306
| 27a581a0b0702842ac4088e6c1a61b22
| 8e79a4d8aed0f413150f976045f256ef
| 2727e68a36622efcabfd60a554533b8c
| 6f ....................................... Masternode Signature

01 ......................................... Sentinel Current: true
02000100 ................................... Sentinel Version (1.0.2)
ecd50100 ................................... Dashd Deamon Version (12.3.0)

mnv

The mnv message is used by masternodes to verify each other. Several mnv messages are exchanged in the process. This results in the IP address of masternode 1 being validated as of the provided block height.

Bytes Name Data type Required Description
36 masternodeOutPoint1 outPoint Required The unspent outpoint which is holding 1000 DASH for masternode 1
36 masternodeOutPoint2 outPoint Required The unspent outpoint which is holding 1000 DASH for masternode 2
# addr CService Required IPv4 address and port of masternode 1
4 nonce int Required Random nonce
4 nBlockHeight int Required Block height
66 vchSig1 char[] Required*

Added in Step 2
Signature of this message by masternode 1 - verifiable via pubKeyMasternode (Length (1 byte) + Signature (65 bytes))

66 vchSig2 char[] Required*

Added in Step 3
Signature of this message by masternode 2 - verifiable via pubKeyMasternode (Length (1 byte) + Signature (65 bytes))

Initially, vin1, vin2, vchSig1 and vchSig2 are empty. They are updated as the exchange of messages between the masternodes occurs as detailed in the table below.

Masternode Verify Data Flow

Step MN 2 (Verifier) Direction MN 1 (Being verified) Description
  Verification request     mnv message with no signatures
1 mnv message   Contains addr, nonce, and nBlockHeight.
Sent by SendVerifyRequest().
2   mnv message Add vchSig1 (signature of the IP address + nonce + hash of the requested block).
Sent by SendVerifyReply().
3 mnv message   Verify vchSig1

Add masternodeOutPoint1, masternodeOutPoint2, and vchSig2 (signature of the IP address + nonce + hash of the requested block + masternodeOutPoint1 + masternodeOutPoint2) and relay message to peers if valid.
Sent by ProcessVerifyReply().

Nodes receiving a relayed mnv message (one in which masternodeOutPoint1, masternodeOutPoint2, vchSig1 and vchSig2 are already present) use it to update the PoSe ban score. If the ban score reaches MASTERNODE_POSE_BAN_MAX_SCORE (5), the masternode will be considered malicious and banned. If the received message is valid, nodes receiving it will relay it on to their connected peers.

Important Notes:
* Dash Core limits how frequently a masternode verify request can be
  requested. Frequent requests will result in the node being banned.

* Only masternodes in the top `MAX_POSE_RANK` (10) can send an `mnv` request
  (to no more than `MAX_POSE_CONNECTIONS` (10)).

The following annotated hexdump shows a mnv message. This is an example of the initial request (Step 1) so it does not contain any signatures. (The message header has been omitted.)

Masternode 1 Unspent Outpoint (empty)
| 00000000000000000000000000000000
| 00000000000000000000000000000000 ......... Outpoint TXID
| ffffffff ................................. Outpoint index number: 0

Masternode 2 Unspent Outpoint (empty)
| 00000000000000000000000000000000
| 00000000000000000000000000000000 ......... Outpoint TXID
| ffffffff ................................. Outpoint index number: 0

00000000000000000000ffff2d20ed4c ........... IP Address: ::ffff:45.32.237.76
4e1f ....................................... Port: 19999
9d090000 ................................... Nonce: 2641
ed5c0000 ................................... Block height: 23789

Masternode 1 Signature
| 00 ....................................... Bytes in signature: 0
| .......................................... Signature: Empty

Masternode 2 Signature
| 00 ....................................... Bytes in signature: 0
| .......................................... Signature: Empty

The following annotated hexdump shows a mnv message. This is an example of the initial response (Step 2) so it only contains the signature of masternode 1 (the masternode being verified). (The message header has been omitted.)

Masternode 1 Unspent Outpoint (empty)
| 00000000000000000000000000000000
| 00000000000000000000000000000000 ......... Outpoint TXID
| ffffffff ................................. Outpoint index number: 0

Masternode 2 Unspent Outpoint (empty)
| 00000000000000000000000000000000
| 00000000000000000000000000000000 ......... Outpoint TXID
| ffffffff ................................. Outpoint index number: 0

00000000000000000000ffff2d20ed4c ........... IP Address: ::ffff:45.32.237.76
4e1f ....................................... Port: 19999
9d090000 ................................... Nonce: 2641
ed5c0000 ................................... Block height: 23789

Masternode 1 Signature
| 41 ....................................... Bytes in signature: 65
| 1bf5bd6e6eda0cd32aafb826c4066fa5
| 4a53baa6f4211528e51716054b4df981
| d97a77e633947bbbfafd6882324b76a0
| 90c6e65c16ca1222db48f8558537c062
| f6 ....................................... Signature

Masternode 2 Signature
| 00 ....................................... Bytes in signature: 0
| .......................................... Signature: Empty

mnw

Warning icon NOTE: This message will be deprecated following activation of DIP3 which implements deterministic masternode lists.

The mnw message is used to pick the next winning masternode. When a new block is found on the network, a masternode quorum will be determined and those 10 selected masternodes will issue the masternode payment vote message.

Bytes Name Data type Required Description
36 masternodeOutPoint outPoint Required The unspent outpoint of the masternode (holding 1000 DASH) which is signing the message
4 nBlockHeight int Required The blockheight which the payee should be paid
? payeeAddress CScript Required The address receiving payment
66* vchSig char[] Required Signature of the masternode which is signing the message (66 bytes in most cases. Length (1 byte) + Signature (65 bytes))

The following annotated hexdump shows a mnw message. (The message header has been omitted.)

Masternode Unspent Outpoint
| 0c1b5c5846792b25b05eeea9586d8c34
| ecb996c566bedb4ecf6a68fe8ffa9582 ......... Outpoint TXID
| 00000000 ................................. Outpoint index number: 0

fb4f0a00 ................................... Block pay height: 675835

Payee Address
| 19 ....................................... Address Length: 25
| | 76 ..................................... OP_DUP
| | a9 ..................................... OP_HASH160
| | 14 ..................................... Push 20 bytes as data
| | | 1767c363646be7d8e4475c0aa85ea454
| | | 9fd102c4 ............................. Pubkey hash
| | 88 ..................................... OP_EQUALVERIFY
| | ac ..................................... OP_CHECKSIG

Masternode Signature
| 41 ....................................... Bytes in signature: 65
| 1c25da47190a83937fb5ef607235703a
| 7cdda155bf5a1ae6139929024750f899
| a90a4f57cdf9d54c9d9603c1f31009f8
| e257355b49c0484fb4c31bc412c73dd9
| 20 ....................................... Signature

mnwb

Warning icon NOTE: This message will be deprecated following activation of DIP3 which implements deterministic masternode lists.

There is no message for mnwb (inv message only).

The following annotated hexdump shows an inv message with a mnwb inventory entry. (The message header has been omitted.)

01 ................................. Count: 1

08000000 ........................... Type: MSG_MASTERNODE_PAYMENT_BLOCK (8)
dd6cc6c11211793b239c2e311f1496e2
2281b200b35233eaae465d2aa3c9d537 ... Hash: mnwb

ssc

The ssc message is used to track the sync status of masternode objects. This message is sent in response to sync requests for the list of masternodes (dseg message), masternode payments (mnget message), governance objects (govsync message), and governance object votes (govsync message).

Bytes Name Data type Required Description
4 nItemID int Required Masternode Sync Item ID
4 nCount int Required Number of items to sync

Sync Item IDs

ID Description Response To
2 MASTERNODE_SYNC_LIST dseg message
3 MASTERNODE_SYNC_MNW mnget message
10 MASTERNODE_SYNC_GOVOBJ govsync message
11 MASTERNODE_SYNC_GOVOBJ_VOTE govsync message with non-zero hash

The following annotated hexdump shows a ssc message. (The message header has been omitted.)

02000000 ................................... Item ID: MASTERNODE_SYNC_LIST (2)
bf110000 ................................... Count: 4543

Governance Messages

The following network messages enable the Governance features built in to Dash. For additional details on the governance system, see this Budget System page.

Overview Of P2P Protocol Governance Request And Reply Messages

For additional details, refer to the Developer Guide Governance section.

govobj

The govobj message contains a governance object that is generally a proposal, contract, or setting. Masternodes ignore this request if they are not fully synced.

Bytes Name Data type Required Description
32 nHashParent uint256 Required Parent object (a hash of all zeros here indicates this is the root object, not a child object).
4 nRevision int Required Object revision in the system
8 nTime int64_t Required Time which this object was created
32 nCollateralHash uint256 Required* Hash of the collateral fee transaction for proposals.

Set to all zeros for Triggers/Watchdogs.
0-16384 strData string Required Data field - can be used for anything (leading varint indicates size of data)
4 nObjectType int Required Type of governance object:
0 - Unknown
1 - Proposal
2 - Trigger
3 - Watchdog
36 masternodeOutPoint outPoint Required* The unspent outpoint of the masternode (holding 1000 DASH) which is signing this object.

Set to all zeros for proposals since they can be created by non-masternodes.
66* vchSig char[] Required* Signature of the masternode (Length (1 byte) + Signature (65 bytes))

Not required for proposals - they will have a length of 0x00 and no Signature.

Governance Object Types (defined by src/governance-object.h)

Type Name Description
0 GOVERNANCE_OBJECT_UNKNOWN  
1 GOVERNANCE_OBJECT_PROPOSAL Submitted proposal (requires collateral transaction - currently 5 Dash)
2 GOVERNANCE_OBJECT_TRIGGER Masternode generated. Removed after activation/execution. Used for superblocks.
3 GOVERNANCE_OBJECT_WATCHDOG Masternode generated. Two hour expiration time.

DEPRECATED since 12.2.

The following annotated hexdump shows a govobj message for a Proposal object. Notice the presence of a non-zero collateral hash, a masternodeOutPoint that is an empty Outpoint (hash of all zeros), and no vchSig. (The message header has been omitted.)

00000000000000000000000000000000
00000000000000000000000000000000 ..... Parent Hash (0 = root)
01000000 ............................. Revision: 1
c8dfd65900000000 ..................... Create timestamp: 2017-10-06 01:43:31 UTC
633611d2f3e7481325242f200c7f3485
e3a9b4b6301e7f7d18d87d8231f3880b ..... Collateral Hash

Data
| 3e02 ............................... Data length: 574
| 356235623232373 ... 376435643564 ... Data (truncated)

01000000 ............................. Object Type: GOVERNANCE_OBJECT_PROPOSAL (1)

Masternode Unspent Outpoint
| 00000000000000000000000000000000
| 00000000000000000000000000000000 ... Outpoint TXID
| ffffffff ........................... Outpoint index number: 0

00 ................................... Signature length: 0

| .................................... Masternode Signature (None required)

The following annotated hexdump shows a govobj message for a Trigger object. Notice the collateral hash of all zeros. (The message header has been omitted.)

00000000000000000000000000000000
00000000000000000000000000000000 ..... Parent Hash (0 = root)
01000000 ............................. Revision: 1
911ea85900000000 ..................... Create timestamp: 2017-08-31 14:34:57 UTC
00000000000000000000000000000000
00000000000000000000000000000000 ..... Collateral Hash (None required)

Data
| ae11 ............................... Data length: 4526
| fdae11356235623 ... 376435643564 ... Data (truncated)

02000000 ............................. Object Type: GOVERNANCE_OBJECT_TRIGGER (2)

Masternode Unspent Outpoint
| ffefbe4959085907bcd2ba29e357a441
| fa7b6e26e25896d8127332bba2419e97 ... Outpoint TXID
| 00000000 ........................... Outpoint index number: 0

41 ................................... Signature length: 65

1ce3b782f66be8ae9fc4158680128864
341202b6006384083ab2d9cfa73795e2
6000668e84af4ef6a284a52b53843524
72037d51bd9079ffd5c087d9632865ee
75 ................................... Masternode Signature

govobjvote

The govobjvote message is used to indicate the voting status of a governance object. Voting status is comprised of the vote outcome (how the masternode voted) and the vote signal (the network support status). A sufficient number of yes votes results in the proposed funding being payed out in the next superblock (assuming their are sufficient funds available in the budget).

The initial govobjvote message is created by a masternode to vote on a governance object (proposal, etc.). When the masternode votes, it broadcasts the govobjvote message to all its peers.

When a node receives a valid, new govobjvote message, it relays the message to all its connected peers to propagate the vote.

Additionally, nodes can request govobjvote messages for specific governance objects via a govsync message. Masternodes ignore requests for votes if they are not fully synced.

Dash Core limits how frequently a masternode can vote on a governance object.
A masternode's vote will not be processed if it has been less than 60 minutes
since its last vote on that object. Additionally, invalid votes can result in
the node being banned.
Bytes Name Data type Required Description
36 masternodeOutPoint outPoint Required The unspent outpoint of the masternode (holding 1000 DASH) which is voting
32 nParentHash uint256 Required Object (govobj) being voted on (proposal, contract, setting or final budget)
4 nVoteOutcome int Required None (0), Yes (1), No (2), Abstain (3)
4 nVoteSignal int Required None (0), Funding (1), Valid (2), Delete (3), Endorsed (4)
8 nTime int64_t Required Time the vote was created
66* vchSig char[] Required Signature of the masternode (66 bytes in most cases. Length (1 byte) + Signature (65 bytes))

Governance Object Vote Signals (defined by src/governance-object.h)

Value Name Description
1 Funding Minimum network support has been reached for this object to be funded (doesn’t mean it will for sure though)
2 Valid Minimum network support has been reached flagging this object as a valid and understood governance object (e.g, the serialized data is correct format, etc.)
3 Delete Minimum network support has been reached saying this object should be deleted from the system entirely
4 Endorsed Minimum network support has been reached flagging this object as endorsed by an elected representative body

The following annotated hexdump shows a govobjvote message. (The message header has been omitted.)

Masternode Unspent Outpoint
| 57566a0ef85e6cac3415ced67b0b07e1
| 781bafb853650d7c9d56d8bc132cc3b4 ... Outpoint TXID
| 00000000 ........................... Outpoint index number: 0

ad9579d5c181eee904156df1c88b050f
b8b4d39e5fda71f015996dbf14a51bff...... Parent Hash (0 = root)
01000000 ............................. Vote Outcome: VOTE_OUTCOME_NONE (1)
02000000 ............................. Vote Signal: VOTE_SIGNAL_VALID (2)
b517a85900000000 ..................... Vote Create Timestamp: 2017-08-31 14:05:41 UTC

41 ................................... Signature length: 65
1b049113a81fe913f061ad295561d267
00b8135a021ab0356a1e89b18d663d0b
dc45e9c09ee0427223e332b52e8d709e
6d64e86b6435d7bdf207d8f23b6ae0db
6f ................................... Masternode Signature

govsync

The govsync message is used to request syncing of governance objects (govobj message and govobjvote message) with peers. Masternodes ignore this request if they are not fully synced.

This message responds in one of two ways depending on the request:

  1. Object Sync - When a masternode receives a govsync message with a hash of all zeros, it responds with one ssc message for govobj objects and one for govobjvote objects. The masternode also sends an inv message (MSG_GOVERNANCE_OBJECT - 0x17) for all valid govobj governance objects. Governance object votes are excluded in this type of response.

  2. Vote Sync - When a masternode receives a govsync message with a specific hash, it responds with one ssc message for govobj objects and one for govobjvote objects. The masternode also sends both a govobj inventory message (MSG_GOVERNANCE_OBJECT - 0x17) and govobjvote inventory messages (MSG_GOVERNANCE_OBJECT_VOTE - 0x18) for the single governance object requested.

Bytes Name Data type Required Description
32 nHash uint256 Required Hash of governance object to request
Set to all zeros to request all objects (excludes votes)
# filter CBloomFilter Required Can be set to all zeros.
Only supported since protocol version 70206
Dash Core limits how frequently the first type of sync (object sync) can be
requested. Frequent requests will result in the node being banned.

The following annotated hexdump shows a govsync message. (The message header has been omitted.)

2e46ea5418e097a3dbcccbee3cf2a911
6fb94ba635153f276dcb2123efcb73ff ..... Hash
00000000000000000000 ................. Bloom Filter

Deprecated Messages

The following network messages have been deprecated and should no longer be used.

mnvs

Masternode Budget Sync - Deprecated since 12.1

mvote

Masternode Budget Vote - Deprecated since 12.1

mprop

Masternode Budget Proposal - Deprecated since 12.1

fbs

Masternode Budget Final - Deprecated since 12.1

fbvote

Masternode Budget Final Vote - Deprecated since 12.1

mn quorum

Not Implemented

Improvement Proposals

Dash (DIPs)

Similar to Bitcoin’s BIPs, a Dash Improvement Proposal (DIP) is a design document for providing information to the Dash community, or describing a new feature for Dash processes/environment. The DIP should provide a concise technical specification of the feature and a rationale for the feature.

DIP Summary Table

Information from Dash DIP repository.

Number Layer Title Type Status
1 Consensus Initial Scaling of the Network Standard Active
2 Consensus Special Transactions Standard Proposed
3 Consensus Deterministic Masternode Lists Standard Proposed
4 Consensus Simplified Verification of Deterministic Masternode Lists Standard Proposed
5 Consensus Blockchain Users Standard Proposed
6 Consensus Long-Living Masternode Quorums Standard Proposed
7 Consensus LLMQ Signing Requests / Sessions Standard Proposed

Bitcoin (BIPs)

A Bitcoin Improvement Proposal (BIP) is a design document providing information to the Bitcoin community, or describing a new feature for Bitcoin or its processes or environment.

Since Dash is forked from Bitcoin, some BIPs are applicable to both. The following table provides a list of the BIPs that are relevant to Dash. Some BIPs may only be partially implemented or modified to meet Dash requirements. The Dash Status column indicates if any changes were made.

BIP Summary Table

Dash-specific BIP information derived from Dash developer QuantumExplorer’s BIP repository.

Number Layer Title Type Status
9 Version bits with timeout and delay Informational Active
11 Applications M-of-N Standard Transactions Standard Active
13 Applications Address Format for pay-to-script-hash Standard Modified Active
14 Peer Services Protocol Version and User Agent Standard Active
16 Consensus (soft fork) Pay to Script Hash Standard Active
21 Applications URI Scheme Standard Modified Active
22 API/RPC getblocktemplate - Fundamentals Standard Modified Active
23 API/RPC getblocktemplate - Pooled Mining Standard Final
30 Consensus (soft fork) Duplicate transactions Standard Active
31 Peer Services Pong message Standard Active
32 Applications Hierarchical Deterministic Wallets Informational Modified Active
34 Consensus (soft fork) Block v2, Height in Coinbase Standard Active
35 Peer Services mempool message Standard Active
37 Peer Services Connection Bloom filtering Standard Active
38 Applications Passphrase-protected private key Standard Active *
39 Applications Mnemonic code for generating deterministic keys Standard Active *
43 Applications Purpose Field for Deterministic Wallets Informational Modified Active
44 Applications Multi-Account Hierarchy for Deterministic Wallets Standard Active *
45 Applications Structure for Deterministic P2SH Multisignature Wallets Standard Active *
47 Applications Reusable Payment Codes for Hierarchical Deterministic Wallets Informational Active *
61 Peer Services Reject P2P message Standard Extended Active
65 Consensus (soft fork) OP_CHECKLOCKTIMEVERIFY Standard Active
66 Consensus (soft fork) Strict DER signatures Standard Active
67 Applications Deterministic Pay-to-script-hash multi-signature addresses through public key sorting Standard Active *
68 Consensus (soft fork) Relative lock-time using consensus-enforced sequence numbers Standard Active
69 Applications Lexicographical Indexing of Transaction Inputs and Outputs Informational Modified Active
70 Applications Payment Protocol Standard Modified Active
71 Applications Payment Protocol MIME types Standard Modified Active
72 Applications bitcoin: uri extensions for Payment Protocol Standard Modified Active
73 Applications Use "Accept" header for response type negotiation with Payment Request URLs Standard Active *
74 Applications Allow zero value OP_RETURN in Payment Protocol Standard Active *
75 Applications Out of Band Address Exchange using Payment Protocol Encryption Standard Active *
83 Applications Dynamic Hierarchical Deterministic Key Trees Standard Active *
111 Peer Services NODE_BLOOM service bit Standard Active
112 Consensus (soft fork) CHECKSEQUENCEVERIFY Standard Active
113 Consensus (soft fork) Median time-past as endpoint for lock-time calculations Standard Active
120 Applications Proof of Payment Standard Active *
122 Applications URI scheme for Blockchain references / exploration Standard Active *
123 BIP Classification Process Active
124 Applications Hierarchical Deterministic Script Templates Informational Active *
125 Applications Opt-in Full Replace-by-Fee Signaling Standard Modified Partial
130 Peer Services sendheaders message Standard Active

* These BIPs are not Bitcoin or Dash specific (i.e. BIP-0044 Multi-Account Hierarchy for Deterministic Wallets). Generally relates to the Application Layer and not specifically the reference client.

Dash Core APIs

Hash Byte Order

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:

> /bin/echo -n '020000007ef055e1674d2e6551dba41cd214debbee34aeb544c7ec670000000000000000d3998963f80c5bab43fe8c26228e98d030edf4dcbe48a666f5c39e2d7a885c9102c86d536c890019593a470d' | xxd -r -p | sha256sum -b | xxd -r -p | sha256sum -b
5472ac8b1187bfcf91d6d218bbda1eb2405d7c55f1f8cc820000000000000000

The result above is also how the hash appears in the previous-header-hash part of block 300,001’s header:

020000005472ac8b1187bfcf91d6d218bbda1eb2405d7c55f1f8cc82000\
0000000000000ab0aaa377ca3f49b1545e2ae6b0667a08f42e72d8c24ae\
237140e28f14f3bb7c6bcc6d536c890019edd83ccf

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, you need to reverse the requested hash:

> dash-cli getblock \
  000000000000327a66cd1011b2d1defd1417b7d9e39b439e8e67ba996ee92602

(Note: hex representation uses two characters to display each byte of data, which is why the reversed string looks somewhat mangled.)

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 and merkle roots.

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.

Data Internal Byte Order RPC Byte Order
Example: SHA256(SHA256(0x00)) Hash: 1406…539a Hash: 9a53…0614
Header Hashes: SHA256(SHA256(block header)) Used when constructing block headers Used by RPCs such as getblock; widely used in block explorers
Merkle Roots: SHA256(SHA256(TXIDs and merkle rows)) Used when constructing block headers Returned by RPCs such as getblock
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
P2PKH Hashes: RIPEMD160(SHA256(pubkey)) Used in both addresses and pubkey scripts N/A: RPCs use addresses which use internal byte order
P2SH Hashes: RIPEMD160(SHA256(redeem script)) Used in both addresses and pubkey scripts N/A: RPCs use addresses which use internal byte order

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).

The code below may help you check byte order by generating hashes from raw hex.

#!/usr/bin/env python

from sys import byteorder
from hashlib import sha256

## You can put in $data an 80-byte block header to get its header hash,
## or a raw transaction to get its txid
data = "00".decode("hex")
hash = sha256(sha256(data).digest()).digest()

print "Warning: this code only tested on a little-endian x86_64 arch"
print
print "System byte order:", byteorder
print "Internal-Byte-Order Hash: ", hash.encode('hex_codec')
print "RPC-Byte-Order Hash:      ", hash[::-1].encode('hex_codec')

Remote Procedure Calls (RPCs)

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 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 loopback network interface so it’s not accessible from other servers. Authentication is implemented using 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. Specifically, the HTTP POST data of a request must be a JSON object with the following format:

Name Type Presence Description
Request object Required
(exactly 1)
The JSON-RPC request object

jsonrpc
number (real) Optional
(0 or 1)
Version indicator for the JSON-RPC request. Currently ignored by Dash Core.

id
string Optional
(0 or 1)
An arbitrary string that will be returned with the response. May be omitted or set to an empty string (“”)

method
string Required
(exactly 1)
The RPC method name (e.g. getblock). See the RPC section for a list of available methods.

params
array Optional
(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.

params
object Optional
(0 or 1)
Starting from Dash Core 0.12.3 / Bitcoin Core 0.14.0 (replaces the params array above) An object containing named parameter values for the RPC. May be an empty object or omitted for RPC calls that don’t have any required parameters.
→ →
Parameter
any Optional
(0 or more)
A parameter. May be any JSON type allowed by the particular RPC method

In the table above and in other tables describing RPC input and output, 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
(exactly 1)
The JSON-RPC response object.

result
any Required
(exactly 1)
The RPC output whose type varies by call. Has value null if an error occurred.

error
null/object Required
(exactly 1)
An object describing the error if one occurred, otherwise null.
→ →
code
number (int) Required
(exactly 1)
The error code returned by the RPC function call. See rpcprotocol.h for a full list of error codes and their meanings.
→ →
message
string Required
(exactly 1)
A text description of the error. May be an empty string (“”).

id
string Required
(exactly 1)
The value of id provided with the request. Has value null if the id field was omitted in the request.

As an example, here is the JSON-RPC request object for the hash of the genesis block:

{
    "method": "getblockhash",
    "params": [0],
    "id": "foo"
}

The command to send this request using dash-cli is:

dash-cli getblockhash 0

The command to send this request using dash-cli with named parameters is:

dash-cli -named getblockhash height=0

Alternatively, we could POST this request using the cURL command-line program as follows:

curl --user 'my_username:my_secret_password' --data-binary '''
  {
      "method": "getblockhash",
      "params": [0],
      "id": "foo"
  }''' \
  --header 'Content-Type: text/plain;' localhost:9998

The HTTP response data for this request would be:

{
    "result": "00000bafbc94add76cb75e2ec92894837288a481e5c005f6563d91623bf8bc2c",
    "error": null,
    "id": "foo"
}

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 results of type string
  • Returns only the error field if there’s an error

Continuing with the example above, the output from the dash-cli command would be simply:

00000bafbc94add76cb75e2ec92894837288a481e5c005f6563d91623bf8bc2c

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):

{
    "result": null,
    "error": {
        "code": -8,
        "message": "Block height out of range"
    },
    "id": "foo"
}

If dash-cli encounters an error, it exits with a non-zero status code and outputs the error field as text to the process’s standard error stream:

error code: -8
error message:
Block height out of range

The RPC interface supports request batching as described in version 2.0 of the JSON-RPC specification. 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.

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

To keep this documentation compact and readable, the examples for each of the available RPC calls will be given as dash-cli commands:

dash-cli [options] <method name> <param1> <param2> ...

This translates into an JSON-RPC Request object of the form:

{
    "method": "<method name>",
    "params": [ "<param1>", "<param2>", "..." ],
    "id": "foo"
}

Warning icon Warning: if you write programs using the JSON-RPC interface, you must ensure they handle high-precision real numbers correctly. See the Proper Money Handling Bitcoin Wiki article for details and example code.

Quick Reference

RPC Summary Table

Type part of the Name or Type of an RPC to filter the list:

Type Name Dash Support Dash Version
Addressindex GetAddressBalance Y
Addressindex GetAddressDeltas Y
Addressindex GetAddressMempool Y
Addressindex GetAddressTxids Y
Addressindex GetAddressUtxos Y
Blockchain GetBestBlockHash Y
Blockchain GetBlock Y
Blockchain GetBlockChainInfo Y Updated in 0.12.3.0
Blockchain GetBlockCount Y
Blockchain GetBlockHash Y
Blockchain GetBlockHashes Y 0.12.1
Blockchain GetBlockHeader Y
Blockchain GetBlockHeaders Y 0.12.1
Blockchain GetChainTips Y Updated in 0.12.3.0
Blockchain GetDifficulty Y
Blockchain GetMemPoolAncestors Y 0.12.3.0+
Blockchain GetMemPoolDescendants Y 0.12.3.0+
Blockchain GetMemPoolEntry Y 0.12.3.0+
Blockchain GetMemPoolInfo Y
Blockchain GetRawMemPool Y Updated in 0.12.3.0
Blockchain GetSpentInfo Y 0.12.1
Blockchain GetTxOut Y
Blockchain GetTxOutProof Y
Blockchain GetTxOutSetInfo Y
Blockchain PreciousBlock Y 0.12.3.0+
Blockchain PruneBlockChain Y 0.12.3.0+
Blockchain VerifyChain Y
Blockchain VerifyTxOutProof Y
Control Debug Y Updated in 0.12.3.0
Control GetInfo Y
Control Help Y
Control Stop Y
Dash GetGovernanceInfo Y Updated in 0.13.0.0
Dash GetPoolInfo Y
Dash GetSuperblockBudget Y
Dash GObject Y Updated in 0.12.3.0
Dash Masternode Y Updated in 0.13.0.0
Dash MasternodeBroadcast Y
Dash MasternodeList Y Updated in 0.12.3.0
Dash MnSync Y
Dash PrivateSend Y Updated in 0.12.3.0
Dash SentinelPing Y
Dash Spork Y
Dash VoteRaw Y
Evolution BLS Y Added in 0.13.0
Evolution ProTx Y Added in 0.13.0
Generating Generate Y Updated in 0.12.3.0
Generating GenerateToAddress Y 0.12.3.0+
Removed GetGenerate N Removed in 0.12.3.0
Removed SetGenerate N Removed in 0.12.3.0
Mining GetBlockTemplate Y Updated in 0.13.0.0
Mining GetMiningInfo Y
Mining GetNetworkHashPS Y
Mining PrioritiseTransaction Y
Mining SubmitBlock Y
Network AddNode Y
Network ClearBanned Y
Network DisconnectNode Y
Network GetAddedNodeInfo Y Updated in 0.12.3.0
Network GetConnectionCount Y
Network GetNetTotals Y
Network GetNetworkInfo Y Updated in 0.12.3.0
Network GetPeerInfo Y
Network ListBanned Y
Network Ping Y
Network SetBan Y
Network SetNetworkActive Y
Rawtransactions CreateRawTransaction Y Updated in 0.12.3.0
Rawtransactions DecodeRawTransaction Y Updated in 0.13.0.0
Rawtransactions DecodeScript Y
Rawtransactions FundRawTransaction Y Updated in 0.12.3.0
Rawtransactions GetRawTransaction Y Updated in 0.13.0.0
Rawtransactions SendRawTransaction Y
Rawtransactions SignRawTransaction Y
Removed GetHashesPerSec N N/A
Removed GetWork N N/A
Util CreateMultiSig Y
Util EstimateFee Y
Util EstimatePriority Y Deprecated in 0.12.3.0
Util EstimateSmartFee Y
Util EstimateSmartPriority Y Deprecated in 0.12.3.0
Util GetMemoryInfo Y 0.12.3.0+
Util SetBIP69Enabled Y 0.12.3.0+
Util ValidateAddress Y Updated in 0.12.3.0
Util VerifyMessage Y
Wallet AbandonTransaction Y
Wallet AddMultiSigAddress Y
Wallet AddWitnessAddress N N/A
Wallet BackupWallet Y
Wallet BumpFee N N/A
Wallet DumpHDInfo Y 0.12.2
Wallet DumpPrivKey Y
Wallet DumpWallet Y Updated in 0.13.0.0
Wallet EncryptWallet Y
Wallet GetAccount Y
Wallet GetAccountAddress Y
Wallet GetAddressesByAccount Y
Wallet GetBalance Y Updated in 0.13.0.0
Wallet GetNewAddress Y
Wallet GetRawChangeAddress Y
Wallet GetReceivedByAccount Y Updated in 0.13.0.0
Wallet GetReceivedByAddress Y Updated in 0.13.0.0
Wallet GetTransaction Y
Wallet GetUnconfirmedBalance Y
Wallet GetWalletInfo Y Updated in 0.12.3.0
Wallet ImportAddress Y
Wallet ImportElectrumWallet Y 0.12.1
Wallet ImportMulti Y 0.12.3.0+
Wallet ImportPrivKey Y
Wallet ImportPrunedFunds Y 0.12.3.0+
Wallet ImportPubKey Y
Wallet ImportWallet Y
Wallet InstantSendToAddress Y
Wallet KeePass Y
Wallet KeyPoolRefill Y
Wallet ListAccounts Y Updated in 0.13.0.0
Wallet ListAddressBalances Y 0.12.3.0+
Wallet ListAddressGroupings Y
Wallet ListLockUnspent Y
Wallet ListReceivedByAccount Y Updated in 0.13.0.0
Wallet ListReceivedByAddress Y Updated in 0.13.0.0
Wallet ListSinceBlock Y
Wallet ListTransactions Y
Wallet ListUnspent Y Updated in 0.12.3.0
Wallet LockUnspent Y
Wallet Move Y
Wallet RemovePrunedFunds Y 0.12.3.0+
Wallet SendFrom Y Updated in 0.13.0.0
Wallet SendMany Y Updated in 0.13.0.0
Wallet SendToAddress Y
Wallet SetAccount Y
Wallet SetPrivateSendAmount Y Added in 0.13.0.0
Wallet SetPrivateSendRounds Y Added in 0.13.0.0
Wallet SetTxFee Y
Wallet SignMessage Y
Wallet SignMessageWithPrivKey Y 0.12.3.0+
Wallet WalletLock Y
Wallet WalletPassphrase Y
Wallet WalletPassphraseChange Y

Addressindex RPCs

These RPCs are all Dash-specific and not found in Bitcoin Core

Block Chain RPCs

Control RPCs

  • Debug: changes the debug category from the console. Updated in Dash Core 0.12.3
  • GetInfo: prints various information about the node and the network. Deprecated
  • GetMemoryInfo: returns information about memory usage. New in Dash Core 0.12.3
  • Help: lists all available public RPC commands, or gets help for the specified RPC. Commands which are unavailable will not be listed, such as wallet RPCs if wallet support is disabled.
  • Stop: safely shuts down the Dash Core server.

Dash RPCs

  • GetGovernanceInfo: returns an object containing governance parameters. Updated in Dash Core 0.12.3
  • GetPoolInfo: returns an object containing mixing pool related information.
  • GetSuperblockBudget: returns the absolute maximum sum of superblock payments allowed.
  • GObject: provides a set of commands for managing governance objects and displaying information about them. Updated in Dash Core 0.12.3
  • Masternode: provides a set of commands for managing masternodes and displaying information about them. Updated in Dash Core 0.12.3
  • MasternodeBroadcast: provides a set of commands to create and relay masternode broadcast messages.
  • MasternodeList: returns a list of masternodes in different modes. Updated in Dash Core 0.12.3
  • MnSync: returns the sync status, updates to the next step or resets it entirely.
  • PrivateSend: controls the mixing process. Updated in Dash Core 0.12.3
  • SentinelPing: sends a Sentinel Ping to the network.
  • Spork: reads or updates spork settings on the network.
  • VoteRaw: compiles and relays a governance vote with provided external signature instead of signing vote internally

Evolution RPCs

  • BLS: New in Dash Core 0.13.0
  • ProTx: provides a set of commands to execute ProTx related actions. New in Dash Core 0.13.0

Generating RPCs

  • Generate: mines blocks immediately (before the RPC call returns). Updated in Dash Core 0.12.3 Updated in Bitcoin Core 0.13.0
  • GenerateToAddress: mines blocks immediately to a specified address. New in Dash Core 0.12.3 New in Bitcoin Core 0.13.0

Mining RPCs

  • GetBlockTemplate: gets a block template or proposal for use with mining software. Updated in Dash Core 0.12.3
  • GetMiningInfo: returns various mining-related information. Updated in Bitcoin Core 0.14.0
  • GetNetworkHashPS: returns the estimated network hashes per second based on the last n blocks.
  • PrioritiseTransaction: adds virtual priority or fee to a transaction, allowing it to be accepted into blocks mined by this node (or miners which use this node) with a lower priority or fee. (It can also remove virtual priority or fee, requiring the transaction have a higher priority or fee to be accepted into a locally-mined block.)
  • SubmitBlock: accepts a block, verifies it is a valid addition to the block chain, and broadcasts it to the network. Extra parameters are ignored by Dash Core but may be used by mining pools or other programs.

Network RPCs

  • AddNode: attempts to add or remove a node from the addnode list, or to try a connection to a node once. Updated in Bitcoin Core 0.14.0
  • ClearBanned: clears list of banned nodes. New in Bitcoin Core 0.12.0
  • DisconnectNode: immediately disconnects from a specified node. New in Bitcoin Core 0.12.0
  • GetAddedNodeInfo: returns information about the given added node, or all added nodes (except onetry nodes). Only nodes which have been manually added using the addnode RPC will have their information displayed. Updated in Dash Core 0.12.3 Updated in Bitcoin Core 0.14.0
  • GetConnectionCount: returns the number of connections to other nodes.
  • GetNetTotals: returns information about network traffic, including bytes in, bytes out, and the current time. Updated in Bitcoin Core 0.12.0
  • GetNetworkInfo: returns information about the node’s connection to the network. Updated in Dash Core 0.12.3 Updated in Bitcoin Core 0.13.0
  • GetPeerInfo: returns data about each connected network node. Updated in Bitcoin Core 0.13.0
  • ListBanned: lists all banned IPs/Subnets. New in Bitcoin Core 0.12.0
  • Ping: sends a P2P ping message to all connected nodes to measure ping time. Results are provided by the getpeerinfo RPC pingtime and pingwait fields as decimal seconds. The P2P ping message is handled in a queue with all other commands, so it measures processing backlog, not just network ping.
  • SetBan: attempts add or remove a IP/Subnet from the banned list. New in Bitcoin Core 0.12.0
  • SetNetworkActive: disables/enables all P2P network activity. New in Bitcoin Core 0.14.0

Raw Transaction RPCs

Utility RPCs

Wallet RPCs

Note: the wallet RPCs are only available if Dash Core was built with wallet support, which is the default.

Removed RPCs

  • GetHashesPerSec: was removed in Bitcoin Core 0.11.0 and is not part of Dash.
  • GetWork: was removed in Bitcoin Core 0.10.0. and is not part of Dash
  • GetGenerate: was removed in Dash Core 0.12.3.
  • SetGenerate: was removed in Dash Core 0.12.3.

RPCs

Warning icon Warning: the block chain and memory pool can include arbitrary data which several of the commands below will return in hex format. If you convert this data to another format in an executable context, it could be used in an exploit. For example, displaying a pubkey script as ASCII text in a webpage could add arbitrary Javascript to that page and create a cross-site scripting (XSS) exploit. To avoid problems, please treat block chain and memory pool data as an arbitrary input from an untrusted source.

AbandonTransaction

Added in Bitcoin Core 0.12.0

The abandontransaction RPC marks an in-wallet transaction and all its in-wallet descendants as abandoned. This allows their inputs to be respent.

Parameter #1—a transaction identifier (TXID)

Name Type Presence Description
TXID string (hex) Required
(exactly 1)
The TXID of the transaction that you want to abandon. The TXID must be encoded as hex in RPC byte order

Result—null on success

Name Type Presence Description
result null Required
(exactly 1)
JSON null when the transaction and all descendants were abandoned

Example from Dash Core 0.12.2

Abandons the transaction on your node.

dash-cli abandontransaction fa3970c341c9f5de6ab13f128cbfec58d732e736a505fe32137ad551c799ecc4

Result (no output from dash-cli because result is set to null).

See also

AddMultiSigAddress

Requires wallet support.

The addmultisigaddress RPC adds a P2SH multisig address to the wallet.

Parameter #1—the number of signatures required

Name Type Presence Description
Required number (int) Required
(exactly 1)
The minimum (m) number of signatures required to spend this m-of-n multisig script

Parameter #2—the full public keys, or addresses for known public keys

Name Type Presence Description
Keys Or Addresses array Required
(exactly 1)
An array of strings with each string being a public key or address

Key Or Address
string Required
(1 or more)
A public key against which signatures will be checked. Alternatively, this may be a P2PKH address belonging to the wallet—the corresponding public key will be substituted. There must be at least as many keys as specified by the Required parameter, and there may be more keys

Parameter #3—the account name

Name Type Presence Description
Account string Optional
(0 or 1)
The account name in which the address should be stored. Default is the default account, “” (an empty string)

Result—a P2SH address printed and stored in the wallet

Name Type Presence Description
result string (base58) Required
(exactly 1)
The P2SH multisig address. The address will also be added to the wallet, and outputs paying that address will be tracked by the wallet

Example from Dash Core 0.12.2

Adding a 2-of-3 P2SH multisig address to the “test account” by mixing two P2PKH addresses and one full public key:

dash-cli -testnet addmultisigaddress 2 '''
  [
    "yNpezfFDfoikDuT1f4iK75AiLp2YLPsGAb",
    "0311f97539724e0de38fb1ff79f5148e5202459d06ed07193ab18c730274fd0d88",
    "yVJj7TB3ZhMcSP2wo65ZFNqy23BQH9tT87"
  ]
''' \
 'test account'

Result:

8uJLxDxk2gEMbidF5vT8XLS2UCgQmVcroW

(New P2SH multisig address also stored in wallet.)

See also

AddNode

The addnode RPC attempts to add or remove a node from the addnode list, or to try a connection to a node once.

Parameter #1—hostname/IP address and port of node to add or remove

Name Type Presence Description
node string Required
(exactly 1)
The node to add as a string in the form of <IP address>:<port>.

Parameter #2—whether to add or remove the node, or to try only once to connect

Name Type Presence Description
command string Required
(exactly 1)
What to do with the IP address above. Options are:
add to add a node to the addnode list. Up to 8 nodes can be added additional to the default 8 nodes. Not limited by -maxconnections
remove to remove a node from the list. If currently connected, this will disconnect immediately
onetry to immediately attempt connection to the node even if the outgoing connection slots are full; this will only attempt the connection once

Result—null plus error on failed remove

Name Type Presence Description
result null Required
(exactly 1)
Always JSON null whether the node was added, removed, tried-and-connected, or tried-and-not-connected. The JSON-RPC error field will be set only if you try adding a node that was already added or removing a node that is not on the addnodes list

Example from Dash Core 0.12.2

Try connecting to the following node.

dash-cli -testnet addnode 192.0.2.113:19999 onetry

Result (no output from dash-cli because result is set to null).

See also

AddWitnessAddress

Added in Bitcoin Core 0.13.0

Warning icon Not implemented in Dash Core (as of 0.12.2)

BackupWallet

Requires wallet support.

The backupwallet RPC safely copies wallet.dat to the specified file, which can be a directory or a path with filename.

Parameter #1—destination directory or filename

Name Type Presence Description
Destination string Required
(exactly 1)
A filename or directory name. If a filename, it will be created or overwritten. If a directory name, the file wallet.dat will be created or overwritten within that directory

Result—null or error

Name Type Presence Description
result null Required
(exactly 1)
Always null whether success or failure. The JSON-RPC error and message fields will be set if a failure occurred

Example from Dash Core 0.12.2

dash-cli -testnet backupwallet /tmp/backup.dat

See also

  • DumpWallet: creates or overwrites a file with all wallet keys in a human-readable format.
  • ImportWallet: imports private keys from a file in wallet dump file format (see the dumpwallet RPC). 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.
BLS

Added in Dash Core 0.13.0

The bls RPC provides a set of commands to execute BLS-related actions.

BLS Generate

The bls generate RPC creates a new BLS secret/public key pair.

Parameters: none

Result—a secret/public key pair

Name Type Presence Description
result object Required
(exactly 1)
BLS key pair

secret
string (hex) Required
(exactly 1)
A BLS secret key

public
string (hex) Required
(exactly 1)
A BLS public key

Example from Dash Core 0.13.0

dash-cli -testnet bls generate

Result:

{
  "secret": "52f35cd3d977a505485f2474e7e71ef3f60f859603d72ad6b0fa7f7bd163e144",
  "public": "885d01d746c3e4d2093b0975de2d8c1f3e5a2c3e8fdaaed929f86fc9fbb278a095248163c101a2456650b415776b7990"
}

See also: none



BumpFee

Added in Bitcoin Core 0.14.0

Warning icon Not implemented in Dash Core (as of 0.12.2)

ClearBanned

Added in Bitcoin Core 0.12.0

The clearbanned RPC clears list of banned nodes.

Parameters: none

Result—null on success

Name Type Presence Description
result null Required
(exactly 1)
JSON null when the list was cleared

Example from Dash Core 0.12.2

Clears the ban list.

dash-cli clearbanned

Result (no output from dash-cli because result is set to null).

See also

  • ListBanned: lists all banned IPs/Subnets.
  • SetBan: attempts add or remove a IP/Subnet from the banned list.
CreateMultiSig

The createmultisig RPC creates a P2SH multi-signature address.

Parameter #1—the number of signatures required

Name Type Presence Description
Required number (int) Required
(exactly 1)
The minimum (m) number of signatures required to spend this m-of-n multisig script

Parameter #2—the full public keys, or addresses for known public keys

Name Type Presence Description
Keys Or Addresses array Required
(exactly 1)
An array of strings with each string being a public key or address

Key Or Address
string Required
(1 or more)
A public key against which signatures will be checked. If wallet support is enabled, this may be a P2PKH address belonging to the wallet—the corresponding public key will be substituted. There must be at least as many keys as specified by the Required parameter, and there may be more keys

Result—P2SH address and hex-encoded redeem script

Name Type Presence Description
result object Required
(exactly 1)
An object describing the multisig address

address
string (base58) Required
(exactly 1)
The P2SH address for this multisig redeem script

redeemScript
string (hex) Required
(exactly 1)
The multisig redeem script encoded as hex

Example from Dash Core 0.12.2

Creating a 2-of-3 P2SH multisig address by mixing two P2PKH addresses and one full public key:

dash-cli -testnet createmultisig 2 '''
  [
    "yNpezfFDfoikDuT1f4iK75AiLp2YLPsGAb",
    "0311f97539724e0de38fb1ff79f5148e5202459d06ed07193ab18c730274fd0d88",
    "yVJj7TB3ZhMcSP2wo65ZFNqy23BQH9tT87"
  ]
'''

Result:

{
  "address": "8uJLxDxk2gEMbidF5vT8XLS2UCgQmVcroW",
  "redeemScript": "522102eacba539d92eb88d4e73bb32749d79f53f6e8d7947ac40a71bd4b26c13b6ec29210311f97539724e0de38fb1ff79f5148e5202459d06ed07193ab18c730274fd0d882103251f25a5c0291446d801ba6df122f67a7dd06c60a9b332b7b29cc94f3b8f57d053ae"
}

See also

CreateRawTransaction

The createrawtransaction RPC creates an unsigned serialized transaction that spends a previous output to a new output with a P2PKH or P2SH address. The transaction is not stored in the wallet or transmitted to the network.

Parameter #1—Inputs

Name Type Presence Description
Transactions array Required
(exactly 1)
An array of objects, each one to be used as an input to the transaction
Input object Required
(1 or more)
An object describing a particular input
→ →
txid
string (hex) Required
(exactly 1)
The TXID of the outpoint to be spent encoded as hex in RPC byte order
→ →
vout
number (int) Required
(exactly 1)
The output index number (vout) of the outpoint to be spent; the first output in a transaction is index 0
→ →
Sequence
number (int) Optional
(0 or 1)
Added in Dash Core 0.12.3.0.

The sequence number to use for the input

Parameter #2—P2PKH or P2SH addresses and amounts

Name Type Presence Description
Outputs object Required
(exactly 1)
The addresses and amounts to pay

Address/Amount
string : number (Dash) Required
(1 or more)
A key/value pair with the address to pay as a string (key) and the amount to pay that address (value) in Dash

Data/Hex
data : hex Required
(1 or more)
A key/value pair where the key is ‘data’ and the value is hex encoded data

Parameter #3—locktime

Name Type Presence Description
Locktime numeric (int) Optional
(0 or 1)
Added in Bitcoin Core 0.12.0

Indicates the earliest time a transaction can be added to the block chain

Result—the unsigned raw transaction in hex

Name Type Presence Description
result string Required
(Exactly 1)
The resulting unsigned raw transaction in serialized transaction format encoded as hex. If the transaction couldn’t be generated, this will be set to JSON null and the JSON-RPC error field may contain an error message

Example from Dash Core 0.12.2

dash-cli -testnet createrawtransaction '''
  [
    {
      "txid": "061ec99eb641ffdeaa05a1a724a255103bebc445b15c6c8c028b19c08608496b",
      "vout" : 1
    }
  ]''' \
  '{"ySutkc49Khpz1HQN8AfWNitVBLwqtyaxvv": 800, "yY6AmGopsZS31wy1JLHR9P6AC6owFaXwuh":74.99}' '0'

Result (wrapped):

01000000016b490886c0198b028c6c5cb145c4eb3b1055a224a7a105aadeff41b69ec91e06\
0100000000ffffffff0200205fa0120000001976a914485485425fa99504ec1638ac4213f3\
cfc9f32ef388acc0a8f9be010000001976a914811eacc14db8ebb5b64486dc43400c0226b4\
28a488ac00000000

See also

Debug

The debug RPC changes the debug category from the console.

Parameter #1—debug category

Name Type Presence Description
Debug category string Required
(1 or more)
The debug category to activate. Use a + to specify multiple categories. Categories will be one of the following:
0 - Disables all categories
1 - Enables all categories
addrman
alert
bench
coindb
db
lock
rand
rpc
selectcoins
mempool
mempoolrej
net
proxy
prune
http
libevent
tor
zmq
dash
privatesend
instantsend
masternode
spork
keepass
mnpayments
gobject

Example from Dash Core 0.12.3

dash-cli -testnet debug "net+mempool"

Result:

Debug mode: net+mempool

See also: none

DecodeRawTransaction

The decoderawtransaction RPC decodes a serialized transaction hex string into a JSON object describing the transaction.

Parameter #1—serialized transaction in hex

Name Type Presence Description
Serialized Transaction string (hex) Required
(exactly 1)
The transaction to decode in serialized transaction format

Result—the decoded transaction

Name Type Presence Description
result object Required
(exactly 1)
An object describing the decoded transaction, or JSON null if the transaction could not be decoded

txid
string (hex) Required
(exactly 1)
The transaction’s TXID encoded as hex in RPC byte order

size
number (int) Required
(exactly 1)
Added in Bitcoin Core 0.12.0

The serialized transaction size

version
number (int) Required
(exactly 1)
The transaction format version number

type
number (int) Required
(exactly 1)
Added in Dash Core 0.13.0.0

The transaction format type

locktime
number (int) Required
(exactly 1)
The transaction’s locktime: either a Unix epoch date or block height; see the Locktime parsing rules

vin
array Required
(exactly 1)
An array of objects with each object being an input vector (vin) for this transaction. Input objects will have the same order within the array as they have in the transaction, so the first input listed will be input 0
→ →
Input
object Required
(1 or more)
An object describing one of this transaction’s inputs. May be a regular input or a coinbase
→ → →
txid
string Optional
(0 or 1)
The TXID of the outpoint being spent, encoded as hex in RPC byte order. Not present if this is a coinbase transaction
→ → →
vout
number (int) Optional
(0 or 1)
The output index number (vout) of the outpoint being spent. The first output in a transaction has an index of 0. Not present if this is a coinbase transaction
→ → →
scriptSig
object Optional
(0 or 1)
An object describing the signature script of this input. Not present if this is a coinbase transaction
→ → → →
asm
string Required
(exactly 1)
The signature script in decoded form with non-data-pushing opcodes listed
→ → → →
hex
string (hex) Required
(exactly 1)
The signature script encoded as hex
→ → →
coinbase
string (hex) Optional
(0 or 1)
The coinbase (similar to the hex field of a scriptSig) encoded as hex. Only present if this is a coinbase transaction
→ → →
value
number (Dash) Optional
(exactly 1)
The number of Dash paid to this output. May be 0.

Only present if spentindex enabled
→ → →
valueSat
number (duffs) Optional
(exactly 1)
The number of duffs paid to this output. May be 0.

Only present if spentindex enabled
→ → → →
addresses
string : array Optional
(0 or 1)
The P2PKH or P2SH addresses used in this transaction, or the computed P2PKH address of any pubkeys in this transaction. This array will not be returned for nulldata or nonstandard script types.

Only present if spentindex enabled
→ → → → →
Address
string Required
(1 or more)
A P2PKH or P2SH address
→ → →
sequence
number (int) Required
(exactly 1)
The input sequence number

vout
array Required
(exactly 1)
An array of objects each describing an output vector (vout) for this transaction. Output objects will have the same order within the array as they have in the transaction, so the first output listed will be output 0
→ →
Output
object Required
(1 or more)
An object describing one of this transaction’s outputs
→ → →
value
number (Dash) Required
(exactly 1)
The number of Dash paid to this output. May be 0
→ → →
valueSat
number (duffs) Required
(exactly 1)
The number of duffs paid to this output. May be 0
→ → →
n
number (int) Required
(exactly 1)
The output index number of this output within this transaction
→ → →
scriptPubKey
object Required
(exactly 1)
An object describing the pubkey script
→ → → →
asm
string Required
(exactly 1)
The pubkey script in decoded form with non-data-pushing opcodes listed
→ → → →
hex
string (hex) Required
(exactly 1)
The pubkey script encoded as hex
→ → → →
reqSigs
number (int) Optional
(0 or 1)
The number of signatures required; this is always 1 for P2PK, P2PKH, and P2SH (including P2SH multisig because the redeem script is not available in the pubkey script). It may be greater than 1 for bare multisig. This value will not be returned for nulldata or nonstandard script types (see the type key below)
→ → → →
type
string Optional
(0 or 1)
The type of script. This will be one of the following:
pubkey for a P2PK script
pubkeyhash for a P2PKH script
scripthash for a P2SH script
multisig for a bare multisig script
nulldata for nulldata scripts
nonstandard for unknown scripts
→ → → →
addresses
string : array Optional
(0 or 1)
The P2PKH or P2SH addresses used in this transaction, or the computed P2PKH address of any pubkeys in this transaction. This array will not be returned for nulldata or nonstandard script types
→ → → → →
Address
string Required
(1 or more)
A P2PKH or P2SH address

extraPayloadSize
number (int) Optional
(0 or 1)
Added in Dash Core 0.13.0.0

Size of the DIP2 extra payload. Only present if it’s a DIP2 special transaction

extraPayload
string (hex) Optional
(0 or 1)
Added in Dash Core 0.13.0.0

Hex encoded DIP2 extra payload data. Only present if it’s a DIP2 special transaction

Example from Dash Core 0.13.0

Decode a signed one-input, two-output transaction:

dash-cli decoderawtransaction 01000000016b490886c0198b028c6c5cb145c4eb3b10\
55a224a7a105aadeff41b69ec91e060100000069463043022033a61c56fa0867ed67b76b02\
3204a9dc0ee6b0d63305dc5f65fe94335445ff2f021f712f55399d5238fc7146497c431fc4\
182a1de0b96fc22716e0845f561d542e012102eacba539d92eb88d4e73bb32749d79f53f6e\
8d7947ac40a71bd4b26c13b6ec29ffffffff0200205fa0120000001976a914485485425fa9\
9504ec1638ac4213f3cfc9f32ef388acc0a8f9be010000001976a914811eacc14db8ebb5b6\
4486dc43400c0226b428a488ac00000000

Result:

{
  "txid": "2f124cb550d9967b81914b544dea3783de23e85d67a9816f9bada665ecfe1cd5",
  "size": 224,
  "version": 1,
  "type": 0,
  "locktime": 0,
  "vin": [
    {
      "txid": "061ec99eb641ffdeaa05a1a724a255103bebc445b15c6c8c028b19c08608496b",
      "vout": 1,
      "scriptSig": {
        "asm": "3043022033a61c56fa0867ed67b76b023204a9dc0ee6b0d63305dc5f65fe94335445ff2f021f712f55399d5238fc7146497c431fc4182a1de0b96fc22716e0845f561d542e[ALL] 02eacba539d92eb88d4e73bb32749d79f53f6e8d7947ac40a71bd4b26c13b6ec29",
        "hex": "463043022033a61c56fa0867ed67b76b023204a9dc0ee6b0d63305dc5f65fe94335445ff2f021f712f55399d5238fc7146497c431fc4182a1de0b96fc22716e0845f561d542e012102eacba539d92eb88d4e73bb32749d79f53f6e8d7947ac40a71bd4b26c13b6ec29"
      },
      "sequence": 4294967295
    }
  ],
  "vout": [
    {
      "value": 800.00000000,
      "valueSat": 80000000000,
      "n": 0,
      "scriptPubKey": {
        "asm": "OP_DUP OP_HASH160 485485425fa99504ec1638ac4213f3cfc9f32ef3 OP_EQUALVERIFY OP_CHECKSIG",
        "hex": "76a914485485425fa99504ec1638ac4213f3cfc9f32ef388ac",
        "reqSigs": 1,
        "type": "pubkeyhash",
        "addresses": [
          "ySutkc49Khpz1HQN8AfWNitVBLwqtyaxvv"
        ]
      }
    },
    {
      "value": 74.99000000,
      "valueSat": 7499000000,
      "n": 1,
      "scriptPubKey": {
        "asm": "OP_DUP OP_HASH160 811eacc14db8ebb5b64486dc43400c0226b428a4 OP_EQUALVERIFY OP_CHECKSIG",
        "hex": "76a914811eacc14db8ebb5b64486dc43400c0226b428a488ac",
        "reqSigs": 1,
        "type": "pubkeyhash",
        "addresses": [
          "yY6AmGopsZS31wy1JLHR9P6AC6owFaXwuh"
        ]
      }
    }
  ],
  "instantlock": false
}

See also

DecodeScript

The decodescript RPC decodes a hex-encoded P2SH redeem script.

Parameter #1—a hex-encoded redeem script

Name Type Presence Description
Redeem Script string (hex) Required
(exactly 1)
The redeem script to decode as a hex-encoded serialized script

Result—the decoded script

Name Type Presence Description
result object Required
(exactly 1)
An object describing the decoded script, or JSON null if the script could not be decoded

asm
string Required
(exactly 1)
The redeem script in decoded form with non-data-pushing opcodes listed. May be empty

reqSigs
number (int) Optional
(0 or 1)
The number of signatures required; this is always 1 for P2PK or P2PKH within P2SH. It may be greater than 1 for P2SH multisig. This value will not be returned for nonstandard script types (see the type key above)

type
string Optional
(0 or 1)
The type of script. This will be one of the following:
pubkey for a P2PK script inside P2SH
pubkeyhash for a P2PKH script inside P2SH
multisig for a multisig script inside P2SH
nonstandard for unknown scripts

addresses
array Optional
(0 or 1)
A P2PKH addresses used in this script, or the computed P2PKH addresses of any pubkeys in this script. This array will not be returned for nonstandard script types
→ →
Address
string Required
(1 or more)
A P2PKH address

p2sh
string (hex) Required
(exactly 1)
The P2SH address of this redeem script

Example from Dash Core 0.12.2

A 2-of-3 P2SH multisig pubkey script:

dash-cli -testnet decodescript 522102eacba539d92eb88d4e73bb32\
749d79f53f6e8d7947ac40a71bd4b26c13b6ec29210311f97539724e0de38fb1\
ff79f5148e5202459d06ed07193ab18c730274fd0d882103251f25a5c0291446\
d801ba6df122f67a7dd06c60a9b332b7b29cc94f3b8f57d053ae

Result:

{
  "asm": "2 02eacba539d92eb88d4e73bb32749d79f53f6e8d7947ac40a71bd4b26c13b6ec29 0311f97539724e0de38fb1ff79f5148e5202459d06ed07193ab18c730274fd0d88 03251f25a5c0291446d801ba6df122f67a7dd06c60a9b332b7b29cc94f3b8f57d0 3 OP_CHECKMULTISIG",
  "reqSigs": 2,
  "type": "multisig",
  "addresses": [
    "yNpezfFDfoikDuT1f4iK75AiLp2YLPsGAb",
    "yWAk1cDVvsRdPYjnzcFkySJux75yaCE7xz",
    "yVJj7TB3ZhMcSP2wo65ZFNqy23BQH9tT87"
  ],
  "p2sh": "8uJLxDxk2gEMbidF5vT8XLS2UCgQmVcroW"
}

See also

DisconnectNode

Added in Bitcoin Core 0.12.0

The disconnectnode RPC immediately disconnects from a specified node.

Parameter #1—hostname/IP address and port of node to disconnect