docs: explain how Rootstock's secured hashrate is calculated

[nicov-iov]

Adds a concepts page, Merged Mining → Secured Hashrate, explaining how the Explorer computes bitcoinHashrate, mergeMiningPercentage and rootstockSecuredHashrate on GET /api/v3/stats, so the published numbers can be re-derived from raw chain data. Four steps: finding the RSKBLOCK: tag in a Bitcoin coinbase, counting tagged blocks over a 1,000-block window, reading Bitcoin's hashrate, and scaling one by the other. Includes a diagram of the commitment and the coinbase byte layout, plus cross-links from the Merged Mining page and the concepts index.

Merge after rsksmart/rsk-explorer-api#258 deploys. Until then the page's curl example returns the existing stats fields only.

The worked example is verified against live data: Bitcoin block 955,501 carries a coinbase OP_RETURN whose payload matches the hashForMergedMining a public Rootstock node reports for block 8,987,318, byte for byte.

The lint check fails on every pull request against main, this one included: the workflow points Vale at docs-style-guide/.vale.ini, which is not in the repository. Unrelated to this change.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
devportal-rootstock	Ready	Preview	Aug 14, 2026 12:38am

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

OpenSSF Scorecard

Package	Version	Score	Details

Scanned Files

[Copilot]

Pull request overview

Adds a new Concepts page documenting how Rootstock Explorer derives “secured hashrate” merge-mining metrics so the published /api/v3/stats values can be independently audited and reproduced.

Changes:

• Introduces a new “Merged Mining → Secured Hashrate” concepts page with a step-by-step derivation and worked example.
• Adds cross-links from the Merged Mining concept page and the Concepts overview index to the new page.

Reviewed changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated 1 comment.

File	Description
docs/01-concepts/merged-mining/secured-hashrate.md	New documentation page explaining tag detection, sampling window, Bitcoin hashrate estimation, and scaling to secured hashrate, plus a reproduction snippet and diagram.
docs/01-concepts/merged-mining/index.md	Adds a direct link to the new Secured Hashrate concepts page from the Merged Mining overview.
docs/01-concepts/index.md	Adds “Merged Mining” and “Secured Hashrate” entries to the Concepts index table for discoverability.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 4 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

docs/01-concepts/merged-mining/secured-hashrate.md:132

• The reproduction snippet only scans coinbase output scripts (vout[].scriptpubkey), but earlier this doc notes the tag may also appear in the coinbase input script; limiting to outputs will undercount in those cases. Consider printing both the coinbase input scriptSig and output scripts before grepping for the tag bytes.

Then check a single Bitcoin block for the tag. This looks up block 955,501 and prints any coinbase output script containing the tag bytes.

```bash
HASH=$(curl -s https://mempool.space/api/block-height/955501)
curl -s "https://mempool.space/api/block/$HASH/txs/0" \
  | jq -r '.[0].vout[].scriptpubkey' \
  | grep -i 52534b424c4f434b3a

</details>

[Copilot]

Pull request overview

Copilot reviewed 3 out of 4 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 4 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (5)

docs/01-concepts/merged-mining/secured-hashrate.md:195

• “merkle proof” should be capitalized as “Merkle proof”.

- **The tag is a commitment, not a full proof.** Its presence shows that a miner claimed a Rootstock block. Verifying the claim means checking the merkle proof that links the two blocks, which Rootstock nodes do during consensus. For a participation share, the tag is the correct lightweight signal.

docs/01-concepts/merged-mining/secured-hashrate.md:11

• The docs in this repo consistently use “hash power” (two words) in concepts pages (e.g., Concepts Overview / Fundamentals). This new page uses “hashpower”, which is inconsistent and makes search/translation less consistent across the docs.

Rootstock is secured by Bitcoin miners who [merge mine](/concepts/merged-mining/) both chains with the same proof of work. The share of Bitcoin's hashpower that does this is measurable. Every participating miner leaves a tag inside the Bitcoin block they mine, so you can count the tagged blocks and scale Bitcoin's total hashrate by that share.

The Rootstock Explorer publishes the result. This page explains each step of the calculation, so anyone can independently verify the published numbers or re-derive them from raw chain data. One framing matters before the math: the metric measures participation, not security directly. It says how much hashpower takes part in merge mining, not what attacking Rootstock would cost.

docs/01-concepts/merged-mining/secured-hashrate.md:91

• This section says the Explorer reads “the current network hashrate estimate that a Bitcoin data provider publishes”, but it doesn’t name the provider or the specific endpoint/metric used. Since the page’s goal is auditability/re-derivation, readers need the exact source to reproduce bitcoinHashrate precisely.

This issue also appears on line 195 of the same file.

That formula is background rather than implementation: it shows what a hashrate estimate means, but it assumes a perfect 600 second block time, which the network never delivers exactly. The Explorer intentionally reads the current network hashrate estimate that a Bitcoin data provider publishes instead, for two reasons. The provider derives its figure from the pace blocks actually arrived at, so it tracks reality more closely when blocks run fast or slow. And a published figure can be re-checked by anyone against the same public source. Read at the same moment, the formula and the provider land within a few percent of each other.

docs/01-concepts/merged-mining/index.md:36

• For consistency with the rest of the concepts docs (which use “hash power”), and to avoid the ungrammatical phrasing “hashpower merge mines”, consider rewording this sentence.

To find out how much of Bitcoin's hashpower merge mines Rootstock, and how that share is measured from Bitcoin blocks, see [Secured Hashrate](/concepts/merged-mining/secured-hashrate/).

docs/01-concepts/index.md:26

• This new row uses “hashpower” (one word), while the surrounding concepts docs consistently use “hash power” (two words). Aligning terminology improves consistency and searchability across the docs.

| [Secured Hashrate](/concepts/merged-mining/secured-hashrate/) | How much of Bitcoin's hashpower secures Rootstock, and how that share is measured from the merge-mining tag in Bitcoin coinbase transactions. |

[Copilot]

Pull request overview

Copilot reviewed 3 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (1)

docs/01-concepts/merged-mining/secured-hashrate.md:147

• The Bitcoin RPC example advertises the “standard Bitcoin JSON-RPC interface”, but the request bodies use "jsonrpc":"2.0". Bitcoin Core’s JSON-RPC is conventionally 1.0 (and some hosted providers validate this), so the current snippet may fail for readers depending on provider. Use "jsonrpc":"1.0" (or omit the field entirely) for better compatibility.

  -d '{"jsonrpc":"2.0","id":1,"method":"getblockhash","params":[955501]}' | jq -r '.result')
TXID=$(curl -s -X POST "$RPC" -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"getblock","params":["'"$HASH"'"]}' | jq -r '.result.tx[0]')
curl -s -X POST "$RPC" -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"getrawtransaction","params":["'"$TXID"'", true, "'"$HASH"'"]}' \

[Copilot]

Pull request overview

Copilot reviewed 3 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (2)

docs/01-concepts/merged-mining/secured-hashrate.md:2

• sidebar_label uses "Secure Hashrate" while the page title/links use "Secured Hashrate". This mismatch can be confusing in the sidebar navigation and makes the page harder to find by name.

sidebar_label: Secure Hashrate Calculator

docs/01-concepts/merged-mining/secured-hashrate.md:103

• This paragraph cites a 600-block sample, but elsewhere the page (and the reproducibility note) describes the metric as based on a 1,000-block window. Aligning the sample size avoids conflicting guidance for readers trying to re-derive the numbers.

The share moves in large steps rather than drifting. Merge mining is a setting that a pool enables once in its poolserver, so a participating pool tags nearly every block it finds and a non-participating pool tags none. Measured over 600 recent blocks, AntPool, F2Pool, ViaBTC, SECPOOL and Luxor tagged 100% of their blocks, while Foundry USA tagged 0% of its 161 blocks. One large pool changing its configuration moves the published metric by several percentage points.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (4)

docs/01-concepts/merged-mining/secured-hashrate.md:98

• Same as above: using "×" in the formula code block makes it less copy/pasteable into code. Prefer ASCII "*" so readers can reuse the expression directly.

rootstockSecuredHashrate = bitcoinHashrate × mergeMiningPercentage

docs/01-concepts/merged-mining/secured-hashrate.md:2

• The sidebar label calls this page a "Calculator", but the content is explanatory rather than an interactive calculator. This can be misleading in the left nav and search results; consider a label that matches the page purpose (e.g., "Secured Hashrate" or "Secured Hashrate (Calculation)").

sidebar_label: Secured Hashrate Calculator

docs/01-concepts/merged-mining/secured-hashrate.md:86

• Using Unicode math operators in code blocks ("≈", "×") makes the formula harder to copy/paste into code or search for, and can be less friendly to some tooling. Consider using ASCII operators in the code block so readers can reuse it directly.

This issue also appears on line 98 of the same file.

bitcoinHashrate ≈ difficulty × 2^32 / 600

docs/01-concepts/merged-mining/secured-hashrate.md:177

• This sentence shows the last four bytes as 0x008922b6, but the JSON-RPC call below correctly uses the minimal-hex QUANTITY form (0x8922b6). Making that relationship explicit helps readers avoid trying to pass a leading-zero quantity (which some clients reject).

The diagram in step 1 shows that the payload's last four bytes are a block number, and `0x008922b6` is 8,987,318. Ask a Rootstock node for that block.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (2)

docs/01-concepts/merged-mining/secured-hashrate.md:115

• Compound adjective should be hyphenated: “seven-day window”.

The daily cadence is deliberate. The metric summarises a seven day window, so it barely moves within a single day, and a faster refresh would recount the same thousand rows to produce the same numbers. One date-keyed row per day also builds a clean historical series for charts, and a re-run on the same day updates that row in place instead of duplicating it.

docs/01-concepts/merged-mining/secured-hashrate.md:15

• Compound adjective should be hyphenated for correct grammar and readability: “hashrate-related fields”.

This issue also appears on line 115 of the same file.

The Explorer API serves the metrics at `GET /api/v3/stats`. It exposes four hashrate related fields.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (2)

docs/01-concepts/merged-mining/secured-hashrate.md:119

• Spelling consistency: the docs elsewhere use American English (“summarize”, “reorganization”). Consider updating “summarises”/“reorganised” here to match (“summarizes”/“reorganized”).

The daily cadence is deliberate. The metric summarises a seven day window, so it barely moves within a single day, and a faster refresh would recount the same thousand rows to produce the same numbers. One date-keyed row per day also builds a clean historical series for charts, and a re-run on the same day updates that row in place instead of duplicating it.

Three behaviours follow from that design, and they matter if you consume the endpoint.

- The Bitcoin metrics trail the Bitcoin tip, by up to a day from the refresh cadence and by a further hundred blocks by design. The Explorer only indexes blocks buried deep enough that they can no longer be reorganised out, because it never revisits a height once stored. Against a seven day average that lag is not visible.

docs/01-concepts/merged-mining/secured-hashrate.md:15

• Minor wording: “hashrate related” is usually hyphenated as a compound adjective (“hashrate-related”).

This issue also appears on line 115 of the same file.

The Explorer API serves the metrics at `GET /api/v3/stats`. It exposes four hashrate related fields.