diff --git a/_includes/devdoc/ref_transactions.md b/_includes/devdoc/ref_transactions.md index f282b8eb..5fd4aedc 100644 --- a/_includes/devdoc/ref_transactions.md +++ b/_includes/devdoc/ref_transactions.md @@ -7,6 +7,8 @@ http://opensource.org/licenses/MIT. ## Transactions {% include helpers/subhead-links.md %} + + The following subsections briefly document core transaction details. #### OpCodes @@ -222,12 +224,15 @@ A raw transaction has the following top-level format: | Bytes | Name | Data Type | Description |----------|--------------|---------------------|------------- -| 4 | version | uint32_t | Transaction version number; currently version 2. Programs creating transactions using newer consensus rules may use higher version numbers. +| 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 @@ -398,6 +403,515 @@ have multiple outputs depending on the number of proposals being funded. {% endautocrossref %} +### Special Transactions +{% include helpers/subhead-links.md %} + +{% autocrossref %} + +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](https://github.com/dashpay/dips/blob/master/dip-0002-special-transactions.md). + +{% endautocrossref %} + +#### ProRegTx +{% include helpers/subhead-links.md %} + +{% autocrossref %} + +*Added in protocol version 70211 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.) + +{% highlight text %} +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 +{% endhighlight %} + +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.) + +{% highlight text %} +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) +{% endhighlight %} + +{% endautocrossref %} + +#### ProUpServTx +{% include helpers/subhead-links.md %} + +{% autocrossref %} + +*Added in protocol version 70211 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.) + +{% highlight text %} +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) +{% endhighlight %} + +{% endautocrossref %} + +#### ProUpRegTx +{% include helpers/subhead-links.md %} + +{% autocrossref %} + +*Added in protocol version 70211 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.) + + + +{% highlight text %} +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 +{% endhighlight %} + +{% endautocrossref %} + +#### ProUpRevTx +{% include helpers/subhead-links.md %} + +{% autocrossref %} + +*Added in protocol version 70211 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.) + +{% highlight text %} +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) +{% endhighlight %} + +{% endautocrossref %} + +#### CbTx +{% include helpers/subhead-links.md %} + +{% autocrossref %} + +*Added in protocol version 70211 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: + +{% highlight text %} +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 +{% endhighlight %} + +{% endautocrossref %} + +#### Quorum Commitment +{% include helpers/subhead-links.md %} + +{% autocrossref %} + +Quorum Commitment + +{% endautocrossref %} + +#### SubTxRegister +{% include helpers/subhead-links.md %} + +{% autocrossref %} + +Register Blockchain User + +{% endautocrossref %} + +#### SubTxTopup +{% include helpers/subhead-links.md %} + +{% autocrossref %} + +Topup Blockchain User Credit + +{% endautocrossref %} + +#### SubTxResetKey +{% include helpers/subhead-links.md %} + +{% autocrossref %} + +Change Blockchain User Public Key + +{% endautocrossref %} + +#### SubTxCloseAccount +{% include helpers/subhead-links.md %} + +{% autocrossref %} + +Close Blockchain User Account + +{% endautocrossref %} + ### CompactSize Unsigned Integers {% include helpers/subhead-links.md %}