From 198f85af2d8d1b10635079ef0a45aab9537475d0 Mon Sep 17 00:00:00 2001 From: hunicus <93150691+hunicus@users.noreply.github.com> Date: Mon, 13 Feb 2023 04:08:12 -0500 Subject: [PATCH] Add block audit faq --- .../src/app/docs/api-docs/api-docs-data.ts | 7 ++++ .../app/docs/api-docs/api-docs.component.html | 34 ++++++++++++--- .../app/docs/api-docs/api-docs.component.scss | 42 +++++++++++++++++++ 3 files changed, 78 insertions(+), 5 deletions(-) diff --git a/frontend/src/app/docs/api-docs/api-docs-data.ts b/frontend/src/app/docs/api-docs/api-docs-data.ts index f4b4602ad..069dabacf 100644 --- a/frontend/src/app/docs/api-docs/api-docs-data.ts +++ b/frontend/src/app/docs/api-docs/api-docs-data.ts @@ -8667,6 +8667,13 @@ export const faqData = [ fragment: "why-dont-fee-ranges-match", title: "Why doesn't the fee range shown for a block match the feerates of transactions within the block?", }, + { + type: "endpoint", + category: "advanced", + showConditions: bitcoinNetworks, + fragment: "how-do-block-audits-work", + title: "How do block audits work?", + }, { type: "endpoint", category: "advanced", diff --git a/frontend/src/app/docs/api-docs/api-docs.component.html b/frontend/src/app/docs/api-docs/api-docs.component.html index 48e9b48eb..445b2c102 100644 --- a/frontend/src/app/docs/api-docs/api-docs.component.html +++ b/frontend/src/app/docs/api-docs/api-docs.component.html @@ -218,17 +218,41 @@

For unconfirmed CPFP transactions, Mempool will show the effective feerate (along with descendent & ancestor transaction information) on the transaction page. For confirmed transactions, CPFP relationships are not stored, so this additional information is not shown.

+ +

A block audit visually compares Mempool's expected block to the actual block for a particular block height.

+

How is the expected block determined? Mempool monitors its view of the mempool and runs a re-implementation of Bitcoin Core's transaction selection algorithm to determine the transactions it expects to see in upcoming blocks (source code here). Since there is a continual flow of new transactions, this algorithm runs every 2 seconds, and as a result, you will see the transactions projected to be in upcoming blocks change in near real-time.

+

At the moment a new block is mined, Mempool saves a snapshot of its projected block template for the next block. We call this snapshot the expected block for the block height in question, and it serves as the basis for the block audit.

+

When details for an expected block and actual block are available, we can compare them. The purpose of block audits is to deduce when miners intentionally include or exclude transactions from blocks they mine. Since this information cannot be precisely known, Mempool uses a handful of heuristics to accomplish this.

+

Block audits highlight transactions in different colors to convey these heuristics:

+ +

See how results of the block audit are used to devise the block health score below.

+
+ -

Block health indicates the extent of potential censorship in a block. This is determined by counting how many expected transactions a block is missing—a block that is not missing any expected transactions will have 100% health, while a block missing 1 or more expected transactions will have sub-100% health.

-

How does this work? Let sexpected be the set of all transactions Mempool expected to be in a block and let sactual be the set of all transactions actually in a block. Let n be the number of all transactions in both sexpected and sactual.

-

Then let r be the number of removed transactions—all transactions expected to be in sactual but not actually in it (excluding those that have been recently broadcast; see below).

+

Block health is a measure of how many transactions appear to be intentionally excluded from a block—a block without any transactions that appear intentionally excluded will have 100% health, while a block with 1 or more transactions that appear intentionally excluded will have sub-100% health.

+

As a result, block health is not intended to be a measure of how closely an expected block resembles an actual block.

+

How is it calculated? Let sexpected be the set of all transactions in Mempool's expected block and let sactual be the set of all transactions in the actual block. Then let n be the number of all transactions in both sexpected and sactual.

+

Furthermore, let r be the number of transactions Mempool deduces were intentionally excluded from sactual.

Block health is calculated as n / ( n + r ).

-

Transactions appearing in both sexpected and sactual are used (instead of a block's full transaction count) in order to minimize chances that block health is impacted by missing transactions that don't imply censorship:

+

The number of transactions appearing in both sexpected and sactual is used (instead of a block's full transaction count) in order to minimize chances that block health is inadvertently impacted by transactions that were most likely not intentionally excluded:

-

Mempool uses a re-implementation of Bitcoin Core's transaction selection algorithm to determine the transactions it expects to see in the next block.

+

As a result, block health is not intended to be a measure of how closely an expected block resembles an actual block. The actual block can be vastly different from the expected block, but if no transactions appear to be intentionally excluded, it will have a high health rating (extreme example).

+

See more context in our FAQ on block audits.

diff --git a/frontend/src/app/docs/api-docs/api-docs.component.scss b/frontend/src/app/docs/api-docs/api-docs.component.scss index db6d51cf2..92e78bc55 100644 --- a/frontend/src/app/docs/api-docs/api-docs.component.scss +++ b/frontend/src/app/docs/api-docs/api-docs.component.scss @@ -42,6 +42,48 @@ li.nav-item { } } +ul.no-bull { + list-style: none; +} + +ul.no-bull.block-audit li code { + text-transform: uppercase; +} + +ul.no-bull.block-audit li span { + margin-right: 10px; +} + +ul.no-bull.block-audit li span.block-audit-highlight-color.added { + color: #0099ff; +} + +ul.no-bull.block-audit li span.block-audit-highlight-color.removed { + color: #f344df; +} + +ul.no-bull.block-audit li span.block-audit-highlight-color.recent { + color: #8a3480; +} + +ul.no-bull.block-audit li span.block-audit-highlight-color.marginal { + color: #414127; +} + +ul.no-bull.block-audit li p { + margin-left: 25px; + margin-top: 5px; +} + +ul.no-bull.block-audit li ul { + margin-left: 15px; + margin-bottom: 15px; +} + +ul.no-bull.block-audit code{ + background-color: inherit; +} + .doc-welcome-note { margin-bottom: 0; }