docs: clarify observed block time

[thepastaclaw]

Issue being fixed or feature implemented

Clarifies that Dash Core's nPowTargetSpacing is the nominal consensus target
spacing, not an exact wall-clock estimate for user-facing ETAs. Mainnet's
observed spacing is about 2.626 min/block because DarkGravityWave preserves a
historical off-by-one interval count.

What was done?

• Replaced the ambiguous DarkGravityWave timespan note with a short explanation
  of the preserved off-by-one behavior.
• Documented nPowTargetSpacing as a nominal consensus target, not an exact ETA
  value.
• Tightened a masternode sync comment so it refers to nominal target spacing
  instead of saying blocks are exactly 2.5 minutes.

No code behavior changes are included.

How Has This Been Tested?

• git diff --check upstream/develop..HEAD
• Verified the diff is comments-only by stripping comments from base and head
  for all changed files and comparing the remaining code.
• code-review dashpay/dash upstream/develop docs/clarify-observed-block-time "Pre-PR review: clarify that nPowTargetSpacing is nominal while observed mainnet block spacing is about 2.626 min/block due to DarkGravityWave historical off-by-one; comments only, no code changes" → ship

Runtime tests were not run because this is a comments-only change.

Breaking Changes

None.

Checklist:

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have added or updated relevant unit/integration/functional/e2e tests
• I have made corresponding changes to the documentation
• I have assigned this pull request to a milestone

[github-actions]

This pull request has conflicts, please rebase.

[github-actions]

✅ No Merge Conflicts Detected

This PR currently has no conflicts with other open PRs.

[thepastaclaw]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[thepastaclaw]

Note on check_merge: GitHub reports this PR as mergeable into develop, and the check log shows the head fast-forwards cleanly onto the PR base. The failure happens afterward when .github/workflows/merge-check.yml tries to fast-forward that develop base into master, which is unrelated to this comments-only diff. I am leaving the branch unchanged rather than rebasing/changing the target just to shake this auxiliary check.

[thepastaclaw]

✅ Review complete (commit 4d98bfc)

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 2cdbc07e-c8f0-48fa-96d3-969d0078e9a7

📥 Commits

Reviewing files that changed from the base of the PR and between a59ad9e and 4d98bfc.

📒 Files selected for processing (3)

• src/consensus/params.h
• src/masternode/sync.h
• src/pow.cpp

---

Walkthrough

Three comment-only edits document the DarkGravityWave off-by-one spacing behavior. src/consensus/params.h gains a multi-line comment before nPowTargetSpacing explaining that the nominal target is 2.5 minutes but observed mainnet spacing is ~2.626 minutes due to a consensus-critical DGW off-by-one in nActualTimespan. src/pow.cpp replaces a brief accuracy note inside DarkGravityWave with a clearer explanation of the nActualTimespan vs. nTargetTimespan interval difference. src/masternode/sync.h updates the MASTERNODE_SYNC_TIMEOUT_SECONDS inline comment wording from "our blocks are 2.5 minutes" to "nominal target spacing is 2.5 minutes." No logic, values, or interfaces were changed.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs: clarify observed block time' accurately summarizes the main change—documentation clarifications about block timing and spacing measurements in Dash Core.
Description check	✅ Passed	The description comprehensively explains the issue being addressed, changes made, testing performed, and breaking changes status, all directly related to the changeset of documentation updates.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[thepastaclaw]

Code Review

Comments-only documentation clarification accurately describing the consensus-critical DGW off-by-one (nActualTimespan covers nPastBlocks-1 intervals vs nTargetTimespan's nPastBlocks). Verified against pow.cpp: the loop walks pindex back 23 times for 24 sampled blocks, matching the new comment. No code behavior changes; wording correctly warns the off-by-one is consensus-critical. Ready to merge.

Note: posted as a COMMENT review because GitHub does not allow approving my own PR.