docs: add Decentralized Masternode Shares DIP

[PastaPastaPasta]

Decentralized Masternode Shares (pre-DIP)

Adds dip-pasta-shared-masternode-collateral.md (alias naming per BIP2 conventions, pending DIP number assignment): a specification for trustless shared masternode ownership — 2 to 8 participants fund one masternode's collateral atomically in a single registration transaction, consensus splits the owner reward by recorded contribution, and the collateral can only move through a consensus-enforced dissolution transaction that pays each participant's principal to a refund script fixed at registration.

Relationship to DIP-0026 / #184

This is a strict superset of multi-party payouts: DIP-0026 gives a protocol-enforced recurring reward split but leaves the registrar in control of the payout list and the collateral spendable by whoever holds it — its Security Considerations explicitly defer immutable payout rights to a future protocol mechanism. This DIP is that mechanism. It extends the provider transaction payload version 3 (extended addresses) from #184; a version 3 payload with an empty share list behaves exactly as DIP-0026 specifies. The two deploy together in v24 (EHF).

Key design points

• Consensus covenant, not multisig / pre-signed refunds — without SegWit/Taproot, co-signer txid malleability makes pre-signed refund chains unsafe; ownership lives in the provider payload and spends are enforced in consensus (same trust model as DIP-0003).
• Tagged collateral script (04445348437551, exact match) — creation is valid only inside a shared registration, spending only via ProDisTx; the DIP states the anyone-can-spend-on-non-enforcing-chains trade-off explicitly.
• Monotone dissolution validity — minimum-based output rules with a non-increasing required penalty: a dissolution valid at height h is valid at every later height, which also makes offline "standby dissolutions" (owner-key-loss insurance) safe to sign years ahead.
• Bounded loss under key compromise — unilateral dissolutions carry a fixed consensus fee ceiling (MAX_DIS_FEE, 0.01 DASH) and a bonus ceiling at the configured earlyPenalty, so a stolen share owner key can cost its holder at most the consented early-exit penalty plus a small constant; every other duff must reach the immutable refund script.
• Immutable share owner keys, refund scripts, amounts, and penalty terms; only the reward script is participant-updatable. Rationale for each immutability choice (including why key rotation is deliberately absent) is in the Rationale section.
• Exit is always possible: unilateral dissolution (early-period penalty, redistributed pro-rata to remaining participants) or unanimous dissolution (penalty-free). Regular masternodes only in this version; Evo requires a Platform-side credit-distribution spec first.

A reference implementation exists at dashpay/dash#7437 and is kept in sync with this text.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added a complete draft specification for trustless shared masternode ownership among 2–8 participants.
  • Documented shared registration, proportional reward distribution, owner-approved updates, dissolution and refund rules, validation requirements, deployment guidance, and security and privacy considerations.
  • Added specifications for shared masternode registration, reward updates, and dissolution transactions.
• Chores
  • Expanded the accepted terminology list with technical vocabulary related to shared collateral, signatures, transaction processing, and privacy.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 8a01bc2b-6978-47f1-9f56-3fea0d7fe31a

📥 Commits

Reviewing files that changed from the base of the PR and between c19da1d and 79ed4ab.

📒 Files selected for processing (2)

• dip-pasta-shared-masternode-collateral.md
• project-words.txt

💤 Files with no reviewable changes (1)

• project-words.txt

🚧 Files skipped from review as they are similar to previous changes (1)

• dip-pasta-shared-masternode-collateral.md

Included review availability: Your plan includes up to 3 reviews per rolling hour; 2 remain after this review.

---

📝 Walkthrough

Walkthrough

This PR adds a DIP for trustless shared masternode ownership by 2–8 participants. It defines registration, rewards, dissolution, lifecycle updates, consensus enforcement, activation, tests, security considerations, and supporting vocabulary updates.

Changes

Shared Masternode Collateral DIP

Layer / File(s)	Summary
Shared registration contract dip-pasta-shared-masternode-collateral.md	Defines shared registration data, collateral templates, share fields, consent signatures, serialization, and validity rules.
Dissolution and share updates dip-pasta-shared-masternode-collateral.md	Defines ProDisTx, ProUpShareTx, and ProUpSharedRegTx, including dissolution penalties, reward updates, registrar updates, and deterministic list state.
Reward distribution dip-pasta-shared-masternode-collateral.md	Defines ordered, weighted reward allocation with floor, remainder, fallback, and zero-output rules.
Collateral enforcement and activation dip-pasta-shared-masternode-collateral.md	Defines template validation, forbidden destinations, mempool and block rules, filtering, same-block processing, and DEPLOYMENT_V24 activation.
Bounds, validation, and considerations dip-pasta-shared-masternode-collateral.md	Adds rationale, limits, tests, security considerations, privacy considerations, and licensing information.
Spell-checker vocabulary project-words.txt	Adds terms used by the DIP and retains the existing Wray entry.

Estimated code review effort: 4 (Complex) | ~60 minutes

Merge Risk: ⚪ Minimal · up to 79ed4

This documentation-only change introduces no actionable merge-blocking risk; it is merge-ready after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant ShareOwners
  participant Registration
  participant DeterministicList
  participant ConsensusValidation
  participant RewardConstruction
  ShareOwners->>Registration: submit shared registration and consent signatures
  Registration->>DeterministicList: create shared masternode state
  ShareOwners->>DeterministicList: submit lifecycle update or dissolution transaction
  DeterministicList->>ConsensusValidation: validate template, signatures, and state
  ConsensusValidation->>RewardConstruction: apply share-table reward rules
  RewardConstruction-->>ShareOwners: construct proportional reward outputs

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the documentation change and the shared masternode DIP added by the pull request.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@dip-pasta-shared-masternode-collateral.md`:
- Around line 286-291: The monotonicity note in the ProDisTx/requiredPenalty
description is too strong for the zero-penalty case; rewrite the sentence so
validity is defined by paying at least requiredPenalty, and say a unilateral
ProDisTx is invalid whenever it pays less than requiredPenalty rather than only
“until the early period ends.” Update the surrounding explanation in the section
that discusses requiredPenalty, earlyPenalty, and ProDisTx validity to preserve
the monotonicity claim without excluding earlyPenalty = 0.
- Around line 292-307: The ProDisTx validity rules in the actor/output section
currently allow the actor refund output to be optional whenever it is non-zero,
which can let a valid dissolution omit the actor’s remaining principal. Update
the wording around the `actorIndex`, `shares[a].refundScript`, and
`requiredPenalty` rules to make the actor output mandatory whenever
`shares[a].amount - P > 0`, and only omit it in the genuinely zero-value case;
keep the rest of the output-order and no-extra-outputs constraints unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 5f33eb94-07ee-4903-8e91-242fb4c1f4e8

📥 Commits

Reviewing files that changed from the base of the PR and between a4d46dd and 29810a3.

📒 Files selected for processing (2)

• dip-pasta-shared-masternode-collateral.md
• project-words.txt

[ndrezza]

<3

[hilawe]

Following up on my #186 closing comment. This is the Platform-side half I said
would come forward once it was ready. Background is in that thread (the June 28
request-for-comments post and the July 6 comparison with this draft). What follows draws on
a private prototype. Where something is a suggestion rather than a prototype result, I say
so.

What ran

I implemented most of this draft on a fork based on merged DIP-0026 (8c9f166a3):
registration, share updates, rewards, and dissolution. ProUpSharedRegTx and parts of the
destination rules stayed out of scope. The functional tests pass on regtest.

On the tested paths, the draft behaves as specified:

• A two-participant shared masternode registers with the template collateral.
• A normal transaction cannot spend the template output.
• The node earns its share-weighted owner rewards in the coinbase.
• A unilateral dissolution during the early period refunds the passive participant in
  full, to their immutable refund script, with the penalty math exact to the duff.

On that tested path, nothing is ever pre-signed against a transaction id, so the failure
mode the Motivation describes does not arise there.

Notes on the draft text from implementing it

These are the places where building it required decisions the text does not currently pin
down. I can expand any of them into separate comments or suggestions.

• The template-creation and template-spend checks need to cover the coinbase and the
  same-block create-then-spend path, not only ordinary mempool inputs. I hit both in
  testing.
• The penalty and reward split multiplies two duff-scale values (an amount times a share
  over the collateral). That overflows a 64-bit intermediate. The text could require wide
  multiplication explicitly.
• Low-S form on the joinSig and dissolution signatures is worth pinning in the text so
  implementations agree.
• The new transaction types need to join the contextual allowed-type list at the v24 gate.
  I hit this with ProDisTx and ProUpShareTx. Worth a line in the deployment section.
• Proof-of-service interacts with shared nodes (the ban and revive path). The text is
  silent on whether a shared node revives the same way. Better to state it than leave
  implementations to guess.
• The version-4 ProRegTx wire format would benefit from an explicit field-order statement.
  I had to infer it.
• Exposing the share table in the protx info output makes a shared node inspectable
  without fetching its registration transaction. I implemented this and would suggest
  speccing that surface.
• I also have a functional test with per-rule negative vectors for ProDisTx: each malformed
  dissolution is refused on its own consensus rule (redirecting a non-actor refund,
  underpaying a non-actor, wrong output count, wrong actor script, corrupted signature).
  Happy to contribute it in whatever form fits.

The Platform-side companion

This is the half I promised when closing the RFC. Everything here ran on a local Platform
devnet, so these are devnet results, not testnet or mainnet ones.

One property carries the whole design. A single asset-lock transaction can hold one credit
output per recipient, and Platform accepts identity top-ups against any credit-output index
of that one transaction. So a pool can turn a node reward into per-member Platform credits
directly, in one step. No pooled intermediary identity exists at any point, which means
there is no window where an operator holds the members' funds.

On top of that, a small document contract (pool, share, membership request, reward accrual,
vote preference, settlement) ran the member lifecycle end to end:

• Members join and leave by matched handover, strictly within the Platform-accounted group
  behind one Layer 1 (L1) slot. The L1 share table never changes, and recorded capital
  never unwinds on chain.
• Rewards distribute per epoch.
• On dissolution, the returned principal goes to the recorded members, with no operator
  cut.
• A member exits to L1 through a credit withdrawal signed by their own key.

Two design notes for anyone building this layer:

• Record the member's share (in basis points, at distribution time) inside each accrual
  document, under a uniqueness rule per pool, member, and epoch. That makes every past
  distribution checkable from the ledger alone, even after membership changes. Without it,
  deleted share records leave no trace, and old epochs stop being verifiable. One caution
  from experience is that the uniqueness key also needs a distribution-kind field, because
  a reward and a principal return can land at the same height.
• Governance is the honest trust remainder. A member-weighted tally over recorded
  preferences ran, and anyone can recompute it. But the node has one voting key, so casting
  the tally is enforced socially. Two mitigations would need no consensus change, and
  neither is built yet. The first is a published cast receipt, where the operator publishes
  the tally state and the resulting vote, so any deviation is visible and attributable. The
  second is a threshold arrangement on the voting key, for when a pool outgrows social
  enforcement.

Asks

• Tell me which of the notes above you want as separate issue comments or PR suggestions,
  and I will write them up individually.
• Say the word if the ProDisTx negative-test vectors would help the reference
  implementation, and I will share them.
• Say whether the Platform-side companion belongs in this PR's discussion or in a
  dedicated issue. I have the write-up ready either way.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

dip-pasta-shared-masternode-collateral.md (2)

172-176: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Apply the canonical low-S rule to shared registration update signatures too.

ProUpShareTx and ProUpSharedRegTx are signature-bearing payloads introduced by this DIP, but lines 172-174 only list joinSigs and ProDisTx. Since these updates are consensus-critical and affect txid stability, reword this as applying to every signature introduced by the DIP, including ProUpShareTx.payloadSig and ProUpSharedRegTx.sigs, or document an explicit exception.

Suggested wording

-All signatures introduced by this DIP (`joinSigs` and ProDisTx signatures) are
+All signatures introduced by this DIP, including `joinSigs`, ProDisTx,
+ProUpShareTx, and ProUpSharedRegTx signatures, are

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@dip-pasta-shared-masternode-collateral.md` around lines 172 - 176, Update the
low-S signature rule statement to cover every signature introduced by the DIP,
explicitly including ProUpShareTx.payloadSig and ProUpSharedRegTx.sigs alongside
joinSigs and ProDisTx signatures; do not leave these consensus-critical update
signatures as an implicit exception.

---

204-207: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Make the payee-reuse predicate explicit.

Line 204 mentions P2PK even though share scripts are described as P2PKH/P2SH and the test cases omit P2PK. Define P2PK as invalid/rejected, and define P2PKH/P2SH reuse as exact destination comparison: match P2PKH CKeyIDs as HASH160(pubkey) and match P2SH CScriptIDs to the script hash. Without that predicate, implementations can disagree on registration validity.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@dip-pasta-shared-masternode-collateral.md` around lines 204 - 207, Clarify
the payee-reuse rule in the collateral specification: explicitly reject any P2PK
refundScript or rewardScript, and define P2PKH/P2SH reuse as exact destination
comparisons, matching P2PKH CKeyIDs against HASH160(pubkey) and P2SH CScriptIDs
against the script hash. Update the relevant rule and test cases to use this
predicate consistently.

🧹 Nitpick comments (2)

dip-pasta-shared-masternode-collateral.md (2)

631-645: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Add a wire-format compatibility vector for non-shared version 3 ProRegTx.

Lines 112-115 append shared fields to every version-3 payload while claiming sharesCount = 0 remains DIP-0026-compatible. Add an exact serialization and deserialization test covering payouts, empty shares and joinSigs, and zeroed penalty fields. This protects ordinary version-3 registrations from wire-format regressions.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@dip-pasta-shared-masternode-collateral.md` around lines 631 - 645, Add a
wire-format compatibility test for a non-shared version-3 ProRegTx covering
exact serialization and deserialization with populated payouts, empty shares and
joinSigs, and zeroed penalty fields; preserve the expected DIP-0026-compatible
encoding when sharesCount is zero.

---

675-677: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Test both same-block update and dissolution orders.

Lines 472-475 allow ProUpShareTx or ProUpSharedRegTx and ProDisTx in either transaction order. Add test vectors for both (update, dissolution) and (dissolution, update) in one block. This verifies that block validation and mempool validation apply the same state transition.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@dip-pasta-shared-masternode-collateral.md` around lines 675 - 677, Expand the
reorg test vectors to cover both transaction orders within a single block:
ProUpShareTx or ProUpSharedRegTx followed by ProDisTx, and ProDisTx followed by
the update transaction. Verify each ordering through both block validation and
mempool validation, preserving the deterministic masternode snapshots before and
after shared-state changes.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@dip-pasta-shared-masternode-collateral.md`:
- Around line 172-176: Update the low-S signature rule statement to cover every
signature introduced by the DIP, explicitly including ProUpShareTx.payloadSig
and ProUpSharedRegTx.sigs alongside joinSigs and ProDisTx signatures; do not
leave these consensus-critical update signatures as an implicit exception.
- Around line 204-207: Clarify the payee-reuse rule in the collateral
specification: explicitly reject any P2PK refundScript or rewardScript, and
define P2PKH/P2SH reuse as exact destination comparisons, matching P2PKH CKeyIDs
against HASH160(pubkey) and P2SH CScriptIDs against the script hash. Update the
relevant rule and test cases to use this predicate consistently.

---

Nitpick comments:
In `@dip-pasta-shared-masternode-collateral.md`:
- Around line 631-645: Add a wire-format compatibility test for a non-shared
version-3 ProRegTx covering exact serialization and deserialization with
populated payouts, empty shares and joinSigs, and zeroed penalty fields;
preserve the expected DIP-0026-compatible encoding when sharesCount is zero.
- Around line 675-677: Expand the reorg test vectors to cover both transaction
orders within a single block: ProUpShareTx or ProUpSharedRegTx followed by
ProDisTx, and ProDisTx followed by the update transaction. Verify each ordering
through both block validation and mempool validation, preserving the
deterministic masternode snapshots before and after shared-state changes.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 5f26b49d-0a44-42b9-837c-9533c2c872c7

📥 Commits

Reviewing files that changed from the base of the PR and between e7eba87 and b360f4c.

📒 Files selected for processing (1)

• dip-pasta-shared-masternode-collateral.md

[thephez]

@coderabbitai @PastaPastaPasta please see feedback

[thephez]

Few more items to consider

[PastaPastaPasta]

Pushed 7 commits addressing an internal adversarial review plus the outstanding review feedback:

Security fix — 165b6c3 closes a real gap: the minimum-based dissolution output rules left the fee and voluntary penalty overpayment unbounded, so one stolen share owner key could sign a unilateral ProDisTx paying the victim's entire share to miners (as fee) or to a colluding participant (as "bonus"), contradicting the never-principal-theft guarantee. Unilateral dissolutions now carry two height-independent ceilings — fee <= MAX_DIS_FEE (0.01 DASH, both modes) and sum(bonus) <= earlyPenalty — bounding worst-case loss under key compromise at earlyPenalty + MAX_DIS_FEE. Monotone validity is preserved (the bonus ceiling is the configured earlyPenalty, not the height-dependent required penalty).

Interoperability pins (each of these was a place an independent implementation could diverge from the reference implementation and fork):

• 4a5e8ba — byte-exact digest conventions: domain tags are compactSize-length-prefixed strings, shares includes the count byte, and the ProUpShareTx/ProUpSharedRegTx signed hash omits the signature fields entirely (DIP-0003 convention).
• 6999fba — a non-shared v3 payload with non-zero joinSigs/earlyPeriodBlocks/earlyPenalty is now normatively invalid.
• 7762415 — the payee-reuse rule now also covers a ProUpSharedRegTx moving the voting key onto an existing share payee (the reference implementation already rejects this).
• 46c4142 — same-block ordering pinned for updates: register+update in one block is valid; reusing an owner key freed by a same-block dissolution is not.

Guidance and wording:

• 82a2c31 — time locks on dissolutions stay permitted; wallets must verify nLockTime/sequence before signing (BIP68 applies to version-3 transactions).
• 6999fba/79ed4ab — dropped the "unreleased version 3" framing that would go stale on release (thephez review).

Test Cases updated to cover each new rule. The PR description's stale "version 4" reference is also fixed. The reference implementation (dashpay/dash#7437) is being updated to match the new ceilings.

---

🤖 Posted autonomously by Claude on behalf of pasta.