Skip to content

docs(dashmate): describe how a DKG-safe stop decides - #5878

Merged
shumkov merged 2 commits into
v5.1-devfrom
shumkov/dashmate-dkg-safe-stop-docs
Nov 12, 2026
Merged

shumkov merged 2 commits into
v5.1-devfrom
shumkov/dashmate-dkg-safe-stop-docs

Conversation

@shumkov

@shumkov shumkov commented Nov 12, 2026 •

Copy link
Copy Markdown
Collaborator

Issue being fixed or feature implemented

The DKG-safe stop shipped in #5841, #5842 and #5843 has no maintainer documentation. Operators have the stop command page; what dashmate checks, why, and which Dash Core behaviour it relies on lived only in a working design doc and in review threads.

What was done?

  • New packages/dashmate/docs/specs/dkg-safe-stop.md, describing the merged behaviour:
    • why stopping during a DKG risks a PoSe penalty, and the active window (start to the end of the Commit phase);
    • the blockers (upcoming, imminent, session, new-round, unrecorded, active-count, unreadable) and the Core data each comes from;
    • what Core 23, 24.0 and 24.1+ provide, and why the version comes from getnetworkinfo;
    • consistent reads, a syncing Core, reorgs, and the 15-second confirmation on Core older than 24.1;
    • plain stop versus --safe, what --safe remembers and when it gives up, and the local-network exemption;
    • the progress estimate, known limits, and which file does what.
  • Linked from the dashmate docs index and from the stop page's "Stopping a masternode safely" section.
  • A code comment in checkMasternodeSafeToStop.js no longer says a syncing Core only connects blocks over 6 hours old: a reindexing Core stays in initial block download whatever the age of its blocks.

How Has This Been Tested?

Documentation and a comment only. Every claim on the page was checked by two independent reviews: one against dashmate's code at the merge of #5843, one against Dash Core's source (v24.0.0 and develop at 24.1.0). Their corrections are folded in. eslint passes on the changed JS file.

Breaking Changes

None.

Checklist:

  • I have performed a self-review of my own code
  • My Rust, FFI, WASM, Swift or Kotlin changes follow the coding conventions
  • I have commented my code, particularly in hard-to-understand areas
  • I have added or updated relevant unit/integration/functional/e2e tests
  • I have added "!" to the title and described breaking changes in the corresponding section if my code contains any
  • I have made corresponding changes to the documentation if needed
  • If I added or changed GroveDB structure, I described it in the area's structure.rs, regenerated grovedb-structure.json, and checked the structure viewer link posted on this pull request
  • If I added or changed a system contract's document schemas, I checked the contract viewer link posted on this pull request

For repository code-owners and collaborators only

  • I have assigned this pull request to a milestone

🤖 Generated with Claude Code

PR Hygiene · e9fbf0c

  • Bots — thepastaclaw not yet — /skip-bots proceeds without the ones not yet reported
  • Self-review — post /self-reviewed
  • Build running
  • Approvals — you own every area touched; none needed

When every merge requirement is met, the PR Hygiene check passes. Reviewer limits do not block merging; other required GitHub checks and protections still apply.

Summary by CodeRabbit

  • Documentation
    • Added a specification describing how safe-stop checks assess potential PoSe penalties, when --safe waits, and how behavior varies by Core version.
    • Documented blocker types, syncing and reorg handling, retries, wait limits, progress estimates, local-network exemptions, and known limitations.
    • Added links to the specification from the stop command documentation and the documentation contents.
    • Clarified how Core syncing and DKG state affect safe-stop checks.

shumkov and others added 2 commits November 12, 2026 09:21
Adds a reference page for maintainers: why stopping a masternode during
a DKG risks a PoSe penalty, the blockers dashmate derives from Core's
DKG data, what each Core version (23, 24.0, 24.1+) provides, how Core is
read consistently (syncing Core, reorgs), the confirmation on Core older
than 24.1, plain stop versus --safe and what --safe remembers, the
progress estimate, known limits, and which file does what. Linked from
the docs index and the stop command page.

Documentation only, no behaviour change, so no test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The comment on reading a syncing Core said Core stays in initial block
download only while connecting blocks over 6 hours old. A reindexing
Core stays in it whatever the age of its blocks, so a syncing Core is
usually, not always, catching up on DKGs the network ran long ago.

Comment only, no behaviour change, so no test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions github-actions Bot added this to the v5.1.0 milestone Nov 12, 2026
@coderabbitai

coderabbitai Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The pull request adds a DKG-safe stop specification and links to it from the stop command documentation and docs index. It also updates a code comment about Core’s initial block download and DKG catch-up behavior. No implementation changes are reported.

Changes: DKG-safe stop specification

Layer / File(s) Summary
Safe-stop rules
packages/dashmate/docs/specs/dkg-safe-stop.md, packages/dashmate/docs/commands/stop.md, packages/dashmate/docs/index.md
The specification describes the commands covered by the check, DKG active windows, blocker rules, and membership conditions. The stop command docs and contents list link to the specification.
Core data checks
packages/dashmate/docs/specs/dkg-safe-stop.md, packages/dashmate/src/core/quorum/checkMasternodeSafeToStop.js
The specification documents Core-version differences, snapshot reads, syncing and reorg handling, and delayed confirmation. The readDkgSnapshot comment updates its description of IBD and DKG catch-up.
Stop behavior and output
packages/dashmate/docs/specs/dkg-safe-stop.md
The specification describes stop retries, the --safe wait loop, progress output, known limits, and related implementation locations.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Other

Possibly related issues

Possibly related PRs

  • dashpay/platform#5843: That PR adds the safe-stop output and stop command documentation; this pull request documents that behavior and links to the specification from the same command page.
  • dashpay/platform#5841: That PR implements the checks described by this specification and introduced readDkgSnapshot, whose comment this pull request updates.

Suggested reviewers: quantumexplorer, thepastaclaw, ktechmidas

Merge Risk: Minimal · up to e9fbf

This change adds maintainer documentation for the safe-stop behavior and updates a code comment. It does not change runtime behavior, so there is no merge-blocking risk.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title follows the conventional commit format and names the main change: a new maintainer document that explains how the dashmate DKG-safe stop decides whether to stop. The changeset adds docs/spec…
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.
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Full details: Title check

Explanation

The title follows the conventional commit format and names the main change: a new maintainer document that explains how the dashmate DKG-safe stop decides whether to stop. The changeset adds docs/specs/dkg-safe-stop.md, links it from the index and stop command pages, and updates one code comment in checkMasternodeSafeToStop.js. The title is specific and matches the primary change, so it passes.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between f42c54c and e9fbf0c.

Files selected for processing: 4

  • packages/dashmate/docs/commands/stop.md
  • packages/dashmate/docs/index.md
  • packages/dashmate/docs/specs/dkg-safe-stop.md
  • packages/dashmate/src/core/quorum/checkMasternodeSafeToStop.js

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

@github-actions

github-actions Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Waiting for bot review — thepastaclaw not yet. Wait for the missing reviews, or a writer can post /skip-bots to proceed without them; blocking findings still need addressing.
Full checklist in the description.

@github-actions github-actions Bot added the waiting-bots Waiting for the review bots to report on this head label Nov 12, 2026
@thepastaclaw

Copy link
Copy Markdown
Collaborator

🕓 Review not started yet because the new head is waiting for the 30-minute push debounce.

  • Request normal review — click when the PR is ready for review.
  • Request priority review — click to move this review to the front of the queue.

Commit e9fbf0c. Normal review starts when eligible; priority review starts as soon as a slot is available.

@shumkov
shumkov merged commit 076393c into v5.1-dev Nov 12, 2026
24 of 26 checks passed
@shumkov
shumkov deleted the shumkov/dashmate-dkg-safe-stop-docs branch November 12, 2026 02:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

waiting-bots Waiting for the review bots to report on this head

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants