Skip to content

docs: document the extended addresses format in Appendix C of DIP-0003, add new {ProTx, SML} version to support it, add deprecation notices #164

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

Draft
kwvg wants to merge 19 commits into
base: master
Choose a base branch
from
Draft

docs: document the extended addresses format in Appendix C of DIP-0003, add new {ProTx, SML} version to support it, add deprecation notices #164

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
e8d8ab6
docs(dip3): list "Masternode Types" as Appendix B
kwvg Jan 15, 2025
c8712f2
docs: rename leftover HPMN usage to EvoNode
kwvg May 1, 2025
8e4dca9
docs: refer to type 0 masternodes as "regular"
kwvg Jan 15, 2025
ab27555
docs(dip3): move Pro*Tx network information fields to Appendix C
kwvg May 1, 2025
5af97fc
docs(dip4): use DIP3's "Appendix C" for SML network information
kwvg May 1, 2025
8e6edb2
docs(dip3): move platform*Port network information fields to Appendix C
kwvg May 1, 2025
758e0c5
docs(dip28): use DIP3's "Appendix C" for ProTx changelog
kwvg May 1, 2025
6be7048
fix: drop "network byte order" from `platform{HTTP,P2P}Port` description
kwvg May 1, 2025
2686b3f
docs(dip4): consolidate SML entry structure by addition conditions col
kwvg May 1, 2025
1357570
feat: introduce extended format for encoding network information
kwvg May 1, 2025
4ff8b3f
chore: add list of prohibited ("bad") ports in netinfo extended format
kwvg May 1, 2025
af8835d
feat: add domain names extension to network info extended format
kwvg Dec 24, 2024
5fd1958
docs: prohibit private/internal TLDs for domain registration
kwvg Jan 15, 2025
39682fd
docs: allow different ports to be specified per address entry
kwvg May 1, 2025
89357ad
feat: add purpose codes and pair address arrays to purpose code
kwvg May 1, 2025
6754a46
docs: require registering the same `address` if `p_entries[{1,2}][0]`
kwvg May 1, 2025
d6da674
docs: introduce new {ProTx, SML} version for enabling extended addresses
kwvg May 1, 2025
daff300
docs(dip28): add deprecation notices to subsumed `platformInfo` field
kwvg May 1, 2025
e983f5e
docs(dip3): point `networkInfo` to new validation rules
kwvg Jan 15, 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
89 changes: 47 additions & 42 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 network information 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 network information (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,33 +128,33 @@ 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. |
| platformInfo | byte[] | variable | Platform network information (see [appendix](#appendix-c-network-information)). Absent from version 3 onwards. |
| 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. |

The different versions are:

| Version | Version Description |
|---------|------------------------------------------------------|
| 1 | PubKeyOperator is serialised using legacy BLS scheme |
| 2 | PubKeyOperator is serialised using basic BLS scheme |
| Version | Version Description |
|---------|----------------------------------------------------------------------------------------------|
| 1 | PubKeyOperator is serialised using legacy BLS scheme |
| 2 | PubKeyOperator is serialised using basic BLS scheme |
| 3 | `networkInfo` uses the [extended addresses format](dip-0003/network-info.md#extended-format) |

## Updating Masternode Information

There are multiple ways to update masternodes. The table below details the data affected by each update and the responsible role:

| Update Type | Transaction | Issued by | Data updated |
| ----------- | ----------- | --------- | ------------ |
| Service | ProUpServTx | Operator Only | IP Address / Port |
| Service | ProUpServTx | Operator Only | Masternode Network Information |
| 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 network information 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,22 +167,21 @@ 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 network information (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. |
| platformInfo | byte[] | variable | Platform network information (see [appendix](#appendix-c-network-information)). Absent from version 3 onwards. |
| payloadSig | BLSSig | 96 | Signature of the hash of the ProUpServTx fields. Signed by the Operator. |

The different versions are:

| Version | Version Description |
|---------|------------------------------------------------------|
| 1 | payloadSig is serialised using legacy BLS scheme |
| 2 | payloadSig is serialised using basic BLS scheme and type is included in transaction |
| Version | Version Description |
|---------|----------------------------------------------------------------------------------------------|
| 1 | payloadSig is serialised using legacy BLS scheme |
| 2 | payloadSig is serialised using basic BLS scheme and type is included in transaction |
| 3 | `networkInfo` uses the [extended addresses format](dip-0003/network-info.md#extended-format) |

### Updating Registrar of Masternode (ProUpRegTx)

Expand Down Expand Up @@ -246,7 +246,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 network information, 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 All @@ -267,11 +267,11 @@ Reorganisations of the chain must also correctly undo changes to the chain-tips

A ProRegTx is invalid if any of these conditions are true:

In the case of type 0:
In the case of regular masternodes (type 0):
1. collateralOutpoint `hash` is null but an output with 1000 DASH is not present at position `n` of the ProRegTx outputs
2. collateralOutpoint `hash` is not null but an output with 1000 DASH can't be found in the UTXO specified by the `hash` and `n`

In the case of type 1:
In the case of EvoNodes (type 1):
1. collateralOutpoint `hash` is null but an output with 4000 DASH is not present at position `n` of the ProRegTx outputs
2. collateralOutpoint `hash` is not null but an output with 4000 DASH can't be found in the UTXO specified by the `hash` and `n`

Expand All @@ -280,14 +280,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#extended-format)
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 +294,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#extended-format)
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. platformInfo, if required, 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 All @@ -329,9 +325,9 @@ The new system removes the need for masternode reward payment votes and allows t
The new rules to determine the next block’s payee are:

1. Take the last block's payee. If it is a regular masternode (type 0), go to step 5.
2. If the last HPMN payee was already paid 4 blocks in a row, go to step 5.
3. If the last HPMN is not present in the current masternode list anymore, go to step 5.
4. Select last HPMN payee as the next block's payee. Return.
2. If the last EvoNode (type 1) payee was already paid 4 blocks in a row, go to step 5.
3. If the last EvoNode is not present in the current masternode list anymore, go to step 5.
4. Select last EvoNode payee as the next block's payee. Return.
5. Take the valid masternode subset of the previous block
6. Sort the set in ascending order by "testHeight" and “ProRegTx hash”. “testHeight” is determined for each individual entry and equals the “last paid height” (or “registered height” if the masternode was never paid). If the masternode was PoSe-banned before and revived later, the “revival height” of the masternode is used instead of the “registered height”. If the “testHeight” of two masternodes is identical, the ProRegTx hash acts as a deterministic tie breaker.
7. Take the first entry of the resulting list and use this as the next block’s payee.
Expand Down Expand Up @@ -365,6 +361,15 @@ 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

The extended network information format and the legacy network information fields (masternode and platform) it replaces
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 | High Performance Masternode (HPMN) (4000 DASH collateral) |
| Masternode Type | Description | Collateral |
| --------------- | ------------------------------ | ---------- |
| 0 | Regular | 1000 DASH |
| 1 | Evolution Masternode (EvoNode) | 4000 DASH |
Loading