Skip to content

docs: move (platform) network information fields from DIP-00{03, 04, 28} to Appendix C of DIP-0003, minor cleanup #162

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
thephez merged 8 commits into from
May 27, 2025
Merged

docs: move (platform) network information fields from DIP-00{03, 04, 28} to Appendix C of DIP-0003, minor cleanup #162

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
e347706
docs(dip3): list "Masternode Types" as Appendix B
kwvg Jan 15, 2025
28aac0a
docs: refer to type 0 masternodes as "regular"
kwvg Jan 15, 2025
9cc8bf1
docs(dip3): move Pro*Tx network information fields to Appendix C
kwvg May 13, 2025
7f9d194
docs(dip4): use DIP3's "Appendix C" for SML network information
kwvg May 13, 2025
53815dd
docs(dip3): move platform*Port network information fields to Appendix C
kwvg May 13, 2025
e742046
docs(dip28): use DIP3's "Appendix C" for ProTx changelog
kwvg May 13, 2025
6bbdfc8
fix: drop "network byte order" from `platform{HTTP,P2P}Port` description
kwvg May 1, 2025
735f4c4
docs(dip4): consolidate SML entry structure by addition conditions col
kwvg May 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 31 additions & 29 deletions dip-0003.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@
1. [Masternode Rewards](#masternode-rewards)
1. [Selecting Quorums](#selecting-quorums)
1. [Appendix A: Reasons for Self Revocation of Operators](#appendix-a-reasons-for-self-revocation-of-operators)
1. [Appendix B: Masternode Types](#appendix-b-masternode-types)
1. [Appendix C: Network Information](#appendix-c-network-information)
1. [Copyright](#copyright)

## Special Mention
Expand Down Expand Up @@ -99,9 +101,9 @@ This signature is only required for external collaterals. If collateralOutpoint
the fact that the ProRegTx was able to move the collateral acts as an implicit proof of ownership. In this case the
payloadSig must be empty.

The ProRegTx might have the IP address and port fields set to zero. This will result in the masternode being added to the masternode list in the PoSe-banned state and require the operator to issue a ProUpServTx. This is needed in case the owner wants to delegate the operator role to a hosting service without knowing the IP Address and port in advance.
The ProRegTx might have an empty masternode addresses field. This will result in the masternode being added to the masternode list in the PoSe-banned state and require the operator to issue a ProUpServTx. This is needed in case the owner wants to delegate the operator role to a hosting service without knowing the IP Address and port in advance.

The ProRegTx also defines the masternode's type and mode. Default masternodes are of type 0, and future types will be defined in an [annex document](dip-0003/masternode-types.md). Different types would introduce additional or different consensus rules towards the masternodes based on future Dash improvement proposals. Masternode types are not updatable, however each type can have multiple operation modes. The operation modes are updatable.
The ProRegTx also defines the masternode's type and mode. Regular masternodes are of type 0, and future types will be defined in an [annex document](dip-0003/masternode-types.md). Different types would introduce additional or different consensus rules towards the masternodes based on future Dash improvement proposals. Masternode types are not updatable, however each type can have multiple operation modes. The operation modes are updatable.

The ProRegTx also specifies the reward for the operator. The percentage of the masternode reward paid to the operator is calculated by dividing the operatorReward field by 100. When the field is set to zero, the owner will get the full reward for every block. If set to a non-zero value, the masternode operator may specify his operator reward payee script in a ProUpServTx. If he does not do so, the full reward goes to the masternode owner.

Expand All @@ -117,8 +119,7 @@ The transaction consists of the following data in the payload area:
| type | uint_16 | 2 | Masternode type. Default set to 0. |
| mode | uint_16 | 2 | Masternode mode. Default set to 0. |
| collateralOutpoint | COutpoint | 36 | The collateral outpoint. |
| ipAddress | byte[] | 16 | IPv6 address in network byte order. Only IPv4 mapped addresses are allowed (to be extended in the future) |
| port | uint_16 | 2 | Port (network byte order) |
| networkInfo | byte[] | variable | Masternode addresses (see [appendix](#appendix-c-network-information)) |
| KeyIdOwner | CKeyID | 20 | The public key hash used for owner related signing (ProTx updates, governance voting) |
| PubKeyOperator | BLSPubKey | 48 | The public key used for operational related signing (network messages, ProTx updates) |
| KeyIdVoting | CKeyID | 20 | The public key hash used for voting. |
Expand All @@ -127,8 +128,7 @@ The transaction consists of the following data in the payload area:
| scriptPayout | Script | Variable | Payee script (p2pkh/p2sh) |
| inputsHash | uint256 | 32 | The SHA256 hash of all the outpoints of the transaction inputs |
| platformNodeID | byte[] | 0 or 20 | Dash Platform P2P node ID, derived from P2P public key. Only present for masternode type 1. |
| platformP2PPort | uint_16 | 0 or 2 | TCP port of Dash Platform peer-to-peer communication between nodes (network byte order). Only present for masternode type 1. |
| platformHTTPPort | uint_16 | 0 or 2 | TCP port of Platform HTTP/API interface (network byte order). Only present for masternode type 1. |
| platformNetInfo | byte[] | variable | Platform addresses (see [appendix](#appendix-c-network-information)) |
| payloadSigSize | compactSize uint | 1-9 | Size of the Signature |
| payloadSig | unsigned char[] | Variable | 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. |

Expand All @@ -145,15 +145,15 @@ There are multiple ways to update masternodes. The table below details the data

| Update Type | Transaction | Issued by | Data updated |
| ----------- | ----------- | --------- | ------------ |
| Service | ProUpServTx | Operator Only | IP Address / Port |
| Service | ProUpServTx | Operator Only | Masternode addresses |
| Registration | ProUpRegTx | Owner Only | Mode / Payout Script / Voting Key / Operator Key |
| Operator Revocation | ProUpRevTx | Operator Only | \* No data updated / * Only used to signal the owner that a new ProUpRegTx is required |

### Updating Service Features from Operator (ProUpServTx)

To service update a masternode, the masternode operator must submit another special transaction (DIP2) to the network. This special transaction is called a Provider Update Service Transaction and is abbreviated as ProUpServTx. It can only be done by the operator.

An operator can update the IP address and port fields of a masternode entry. If a non-zero operatorReward was set in the initial ProRegTx, the operator may also set the scriptOperatorPayout field in the ProUpServTx. If scriptOperatorPayout is not set and operatorReward is non-zero, the owner gets the full masternode reward.
An operator can update the masternode addresses of a masternode entry. If a non-zero operatorReward was set in the initial ProRegTx, the operator may also set the scriptOperatorPayout field in the ProUpServTx. If scriptOperatorPayout is not set and operatorReward is non-zero, the owner gets the full masternode reward.

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.

Expand All @@ -166,14 +166,12 @@ The transaction consists of the following data in the payload area:
| version | uint_16 | 2 | ProUpServTx version number. Set to 2 once v19 fork activates |
| type | uint_16 | 0 or 2 | Masternode type. Only present for version 2. |
| proTXHash | uint256 | 32 | The hash of the initial ProRegTx |
| ipAddress | byte[] | 16 | IPv6 address in network byte order. Only IPv4 mapped addresses are allowed (to be extended in the future) |
| port | uint_16 | 2 | Port (network byte order) |
| networkInfo | byte[] | variable | Masternode addresses (see [appendix](#appendix-c-network-information)) |
| scriptOperatorPayoutSize | compactSize uint | 1-9 | Size of the Payee Script. |
| scriptOperatorPayout | Script | Variable | Payee script (p2pkh/p2sh) |
| inputsHash | uint256 | 32 | The SHA256 hash of all the outpoints of the transaction inputs |
| platformNodeID | byte[] | 0 or 20 | Dash Platform P2P node ID, derived from P2P public key. Only present for masternode type 1. |
| platformP2PPort | uint_16 | 0 or 2 | TCP port of Dash Platform peer-to-peer communication between nodes (network byte order). Only present for masternode type 1. |
| platformHTTPPort | uint_16 | 0 or 2 | TCP port of Platform HTTP/API interface (network byte order). Only present for masternode type 1. |
| platformNetInfo | byte[] | variable | Platform addresses (see [appendix](#appendix-c-network-information)) |
| payloadSig | BLSSig | 96 | Signature of the hash of the ProUpServTx fields. Signed by the Operator. |

The different versions are:
Expand Down Expand Up @@ -246,7 +244,7 @@ Updating is done on the so called chain-tips list, which is the list valid at th

The chain-tips list is updated for every new block that is processed. The rules to update the list are the following:

1. If a valid ProRegTx is encountered, a masternode entry (identified by the hash of the ProRegTx) is added to the registered set. The entry also contains metadata (IP address, public keys, etc.) found in the ProTx.
1. If a valid ProRegTx is encountered, a masternode entry (identified by the hash of the ProRegTx) is added to the registered set. The entry also contains metadata (masternode addresses, public keys, etc.) found in the ProTx.
2. If any transaction in the block spends the collateral of an existing entry in the registered masternode set, the corresponding masternode is removed from the list
3. PoSe verification is performed for all masternodes in the valid subset. If the verification for a masternode fails, it is marked as PoSe-banned and thus will be excluded from the valid masternode subset. PoSe verification is defined by DIP 006 and only relies on data available on-chain up to the current chain-tip.
4. If a ProUpServTx is found in the block and the referenced masternode is not marked as PoSe-banned, its metadata is updated.
Expand Down Expand Up @@ -280,14 +278,12 @@ Applicable to any type:
2. KeyIdOwner or PubKeyOperator was already used by any entry in the registered masternodes set
3. scriptPayout is not a P2PKH or P2SH script
4. When scriptPayout is P2PKH script and the public key hash equals any of KeyIdOwner or KeyIdVoting
5. ipAddress is set and port is not set to the default mainnet port
6. ipAddress is set and not routable or not an IPv4 mapped address
7. ipAddress is set and already used in the registered masternodes set
8. operatorReward > 10000
9. The inputsHash does not match the calculated hash
10. collateralOutpoint `hash` is null and payloadSig is not empty (zero size)
11. collateralOutpoint `hash` is not null and payloadSig is not a valid signature signed with the collateral key
12. collateralOutpoint `hash` is not null and the referenced collateral is not a P2PKH output
5. networkInfo fails validation [(see rules)](dip-0003/network-info.md#mninfo_rules)
6. operatorReward > 10000
7. The inputsHash does not match the calculated hash
8. collateralOutpoint `hash` is null and payloadSig is not empty (zero size)
9. collateralOutpoint `hash` is not null and payloadSig is not a valid signature signed with the collateral key
10. collateralOutpoint `hash` is not null and the referenced collateral is not a P2PKH output

Please note that while deploying DIP3, additional and temporary validation rules will apply. The details of these temporary rules will be described in the deployment plan.

Expand All @@ -296,21 +292,19 @@ Please note that while deploying DIP3, additional and temporary validation rules
A ProUpServTx is invalid if any of these conditions are true:

1. proTxHash can not be found in the registered masternode set
2. ipAddress is set and port is not set to the default mainnet port
3. ipAddress is set and not routable or not an IPv4 mapped address
4. ipAddress is set and already used in another masternode from the registered masternodes set
5. scriptOperatorPayout is set and operatorReward of the masternode is 0
6. scriptOperatorPayout is set and not a P2PKH or P2SH script
7. The inputsHash does not match the calculated hash
8. payloadSig is invalid
2. networkInfo fails validation [(see rules)](dip-0003/network-info.md#mninfo_rules)
3. scriptOperatorPayout is set and operatorReward of the masternode is 0
4. scriptOperatorPayout is set and not a P2PKH or P2SH script
5. The inputsHash does not match the calculated hash
6. payloadSig is invalid

Please note that while deploying DIP3, additional and temporary validation rules will apply. The details of these temporary rules will be described in the deployment plan.

### ProRegTx and ProUpServTx

A ProRegTx or ProUpServTx is invalid if any of these conditions are true (applicable only when type is 1):

1. platformP2PPort, platformHTTPPort and port from ipAddress are not distinct.
1. platformNetInfo fails validation [(see rules)](dip-0003/network-info.md#plinfo_rules).
2. platformNodeID is null or is a non-hex string.
3. platformNodeID is not unique in the network.

Expand Down Expand Up @@ -365,6 +359,14 @@ The individual quorum types present in Dash are not subject to this DIP and shou
| 2 | Compromised Keys |
| 3 | Change of Keys (Not compromised) |

## Appendix B: Masternode Types

See [masternode types table](dip-0003/masternode-types.md)

## Appendix C: Network Information

Masternode and Platform network information are defined in the [appendix](dip-0003/network-info.md)

## Copyright

Copyright (c) 2018 Dash Core Group, Inc. [Licensed under the MIT License](https://opensource.org/licenses/MIT)
10 changes: 5 additions & 5 deletions dip-0003/masternode-types.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Masternode Types
# Appendix B: Masternode Types

| Masternode Type | Description |
| --- | --- |
| 0 | Default (1000 DASH collateral) |
| 1 | Evolution masternode (evonode) (4000 DASH collateral) |
| Masternode Type | Description | Collateral |
| --------------- | ------------------------------ | ---------- |
| 0 | Regular | 1000 DASH |
| 1 | Evolution masternode (evonode) | 4000 DASH |
43 changes: 43 additions & 0 deletions dip-0003/network-info.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# Appendix C: Network Information

## Masternode Information

The fields below are represented as `networkInfo` and are applicable to all masternodes types as defined in
[Appendix B](masternode-types.md)

| Field | Type | Size | Description |
| --------- | ------- | ---- | -------------------------------------------------------------------------- |
| ipAddress | byte[] | 16 | IPv6 address in network byte order. Only IPv4 mapped addresses are allowed |
| port | uint_16 | 2 | Port (network byte order) |

### <a name="mninfo_rules">Validation Rules</a>

* `ipAddress` MUST be a valid IPv4 address that is routable on the global internet
* `ipAddress` MUST NOT be already used in the registered masternodes set
* `port` MUST be within the valid port range [1, 65535]
* On mainnet, `port` MUST be set to the following value

| Field | Value |
| -------| ------ |
| port | 9999 |

## Platform Information

The fields below are represented as `platformNetInfo` and are only applicable for evonodes as defined in
[Appendix B](masternode-types.md)

| Field | Type | Size | Description |
| ---------------- | ------- | ------ | ------------------------------------------------------------------- |
| platformP2PPort | uint_16 | 0 or 2 | TCP port of Dash Platform peer-to-peer communication between nodes. |
| platformHTTPPort | uint_16 | 0 or 2 | TCP port of Platform HTTP/API interface. |

### <a name="plinfo_rules">Validation Rules</a>

* `platformP2PPort` and `platformHTTPPort` MUST be within the valid port range [1, 65535]
* `platformP2PPort`, `platformHTTPPort`, and [`port`](#masternode-information) from `networkInfo` MUST be distinct
* On mainnet, `platformP2PPort` and `platformHTTPPort` MUST be set to the following values

| Field | Value |
| ------------------ | ------ |
| platformP2PPort | 26656 |
| platformHTTPPort | 443 |
Loading