From 573fe3515a14e35c319c01cc276b0e9f723defdb Mon Sep 17 00:00:00 2001
From: hunicus <93150691+hunicus@users.noreply.github.com>
Date: Tue, 31 Jan 2023 00:27:06 -0500
Subject: [PATCH] Add block health faq

---
 frontend/src/app/docs/api-docs/api-docs-data.ts     |  7 +++++++
 .../src/app/docs/api-docs/api-docs.component.html   | 13 +++++++++++++
 .../src/app/docs/api-docs/api-docs.component.scss   |  6 ++++++
 3 files changed, 26 insertions(+)

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 8cbf03dfb..f4b4602ad 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: "what-is-block-health",
+    title: "What is block health?",
+  },
   {
     type: "category",
     category: "self-hosting",
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 c343d24c8..9f0b9fc2d 100644
--- a/frontend/src/app/docs/api-docs/api-docs.component.html
+++ b/frontend/src/app/docs/api-docs/api-docs.component.html
@@ -218,6 +218,19 @@
   <p>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.</p>
 </ng-template>
 
+<ng-template type="what-is-block-health">
+  <p>Block health indicates the extent of <i>potential</i> 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.</p>
+  <p>How does this work? Let <span class='math'>s<sub>expected</sub></span> be the set of all transactions Mempool expected to be in a block and let <span class='math'>s<sub>actual</sub></span> be the set of all transactions actually in a block. Let <span class='math'>n</span> be the number of all transactions in both <span class='math'>s<sub>expected</sub></span> and <span class='math'>s<sub>actual</sub></span>.</p>
+  <p>Then let <span class='math'>r</span> be the number of all transactions expected to be in <span class='math'>s<sub>actual</sub></span> but not actually in it (excluding those that have been recently broadcast; see below).</p>
+  <p>Block health is calculated as <span class='math'>n / ( n + r</span> ).</p>
+  <p>Transactions appearing in both <span class='math'>s<sub>expected</sub></span> and <span class='math'>s<sub>actual</sub></span> 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:</p>
+  <ul>
+    <li>recently-broadcast transactions, since the miner may simply not have received them</li>
+    <li>certain low-feerate transactions, since the miner may have opted to replace them with more profitable out-of-band transactions</li>
+  </ul>
+  <p>Mempool uses a re-implementation of Bitcoin Core's transaction selection algorithm to determine the transactions it expects to see in the next block.</p>
+</ng-template>
+
 <ng-template type="who-runs-this-website">
   The official mempool.space website is operated by The Mempool Open Source Project. See more information on our <a [routerLink]="['/about']">About page</a>. There are also many unofficial instances of this website operated by individual members of the Bitcoin community.
 </ng-template>
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 7392d1f55..db6d51cf2 100644
--- a/frontend/src/app/docs/api-docs/api-docs.component.scss
+++ b/frontend/src/app/docs/api-docs/api-docs.component.scss
@@ -21,6 +21,12 @@ code {
   font-family: Consolas,Monaco,Lucida Console,Liberation Mono,DejaVu Sans Mono,Bitstream Vera Sans Mono,Courier New;
 }
 
+.math {
+  font-family: monospace;
+  margin-left: 4px;
+  margin-right: 4px;
+}
+
 tr {
   white-space: inherit;
 }