refactor: consensus constants from core, header repair in the storage layer

Closes the two layering findings left open by the cleanup review.

Consensus constants (bumps @fairco.in/core to 0.5.0):
`nLastPOWBlock` and `ProofOfWorkLimit` were the only chainparams values living
in this consumer rather than on `NetworkConfig`, and the 10000 boundary had
spread to five hardcoded places across two repos — including core's own
checkpoint and vector tests, which assumed it while being unable to import it.
The wallet now reads `network.lastPowBlock` / `network.powLimit`, and
`compactToTarget`, `isValidTargetBits`, `hashToUint256` and `meetsProofOfWork`
come from core instead of being defined here. 101 lines of duplicated
consensus math deleted; core's tests and this gate now evaluate one
implementation.

Header-store repair:
`discardCorruptHeaderStore` sat in the SPV client, hardcoding knowledge of
which upstream package versions were broken, with no version key — so it
re-hashed the tip on every launch forever with no way to retire it, and it
routed a stored record through the wire-message adapter with a fake
`txCount: 0` to do it.

It moves to the storage layer beside the blob migration, keyed on a persisted
`header_hash_version` in a new `schema_meta` table. An already-checked wallet
now costs one small SELECT at startup instead of a Quark hash, the check can
be retired by bumping the version, and the SPV client starts against a store
it can assume is coherent. A wipe also clears `rescan_state`, which describes
heights of a chain that no longer exists.

`planHeaderRepair` is pure and tested against a real mainnet header, the
regressed hash that 0.2.0–0.3.1 would have written, and the genesis-only case
that must never trigger a wipe.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: NateIsern

bun.lock

@@ -21,7 +21,7 @@
   },
   "dependencies": {
     "@expo/vector-icons": "^15.1.1",
-    "@fairco.in/core": "0.4.0",
+    "@fairco.in/core": "0.5.0",
     "@gorhom/bottom-sheet": "^5.2.9",
     "@maplibre/maplibre-react-native": "^10.4.2",
     "@noble/hashes": "1.8.0",

package.json

@@ -14,11 +14,13 @@
 
 import { describe, test, expect } from "bun:test";
 import {
-  validateHeaderChain,
-  planChainUpdate,
   compactToTarget,
   isValidTargetBits,
-  proofOfWorkLimit,
+  getNetwork,
+} from "@fairco.in/core";
+import {
+  validateHeaderChain,
+  planChainUpdate,
   HeaderValidationError,
   type HeaderChainAnchor,
 } from "./header-validation";
@@ -64,7 +66,7 @@ function buildChain(
   return headers;
 }
 
-const POW_LIMIT = proofOfWorkLimit();
+const POW_LIMIT = getNetwork("mainnet").powLimit;
 
 // ---------------------------------------------------------------------------
 // Compact ("nBits") target decoding

src/p2p/header-validation.test.ts

@@ -42,113 +42,17 @@
  * that is sound to enforce header-only.
  */
 
-import type { BlockHeader, NetworkType } from "@fairco.in/core";
-import { bytesEqual, hashBlockHeader } from "@fairco.in/core";
+import type { BlockHeader } from "@fairco.in/core";
+import {
+  bytesEqual,
+  hashBlockHeader,
+  isValidTargetBits,
+  meetsProofOfWork,
+} from "@fairco.in/core";
 import type { BlockHeaderMsg } from "./messages";
 
 // ---------------------------------------------------------------------------
 // Compact ("nBits") target encoding — Bitcoin/FairCoin `uint256::SetCompact`.
-// ---------------------------------------------------------------------------
-
-export interface CompactTarget {
-  /** The decoded 256-bit target value. */
-  readonly target: bigint;
-  /** True if the compact encoding had its sign bit set (an invalid target). */
-  readonly negative: boolean;
-  /** True if the mantissa/exponent combination overflows 256 bits. */
-  readonly overflow: boolean;
-}
-
-const U256_MASK = (1n << 256n) - 1n;
-
-/**
- * Decode a compact difficulty target ("nBits") into a 256-bit value, faithfully
- * reproducing FairCoin's `uint256::SetCompact` including its sign/overflow flags.
- */
-export function compactToTarget(bits: number): CompactTarget {
-  const nSize = (bits >>> 24) & 0xff;
-  const nWord = bits & 0x007fffff;
-
-  let target: bigint;
-  if (nSize <= 3) {
-    target = BigInt(nWord >>> (8 * (3 - nSize)));
-  } else {
-    target = (BigInt(nWord) << BigInt(8 * (nSize - 3))) & U256_MASK;
-  }
-
-  const negative = nWord !== 0 && (bits & 0x00800000) !== 0;
-  const overflow =
-    nWord !== 0 &&
-    (nSize > 34 ||
-      (nWord > 0xff && nSize > 33) ||
-      (nWord > 0xffff && nSize > 32));
-
-  return { target, negative, overflow };
-}
-
-/**
- * The proof-of-work limit (easiest allowed target) for a network, as a 256-bit
- * value. Both FairCoin mainnet and testnet use `~uint256(0) >> 20`
- * (`CTestNetParams` inherits it from `CMainParams`). Only regtest differs, and
- * this wallet never targets regtest.
- */
-export function proofOfWorkLimit(): bigint {
-  return U256_MASK >> 20n;
-}
-
-/**
- * Whether a header's `nBits` encodes a valid, in-range difficulty target.
- *
- * The range half of FairCoin's `CheckProofOfWork`: reject negative, zero,
- * overflowing, or above-limit targets.
- */
-export function isValidTargetBits(bits: number, powLimit: bigint): boolean {
-  const { target, negative, overflow } = compactToTarget(bits);
-  if (negative || overflow) return false;
-  if (target === 0n) return false;
-  if (target > powLimit) return false;
-  return true;
-}
-
-/**
- * Read a block hash as the 256-bit number FairCoin compares against the target.
- *
- * `hashBlockHeader` returns bytes in internal (`uint256` serialisation) order,
- * which is little-endian: byte 0 is the least significant.
- */
-export function hashToUint256(hash: Uint8Array): bigint {
-  let value = 0n;
-  for (let i = hash.length - 1; i >= 0; i--) {
-    value = (value << 8n) | BigInt(hash[i]);
-  }
-  return value;
-}
-
-/**
- * The work half of FairCoin's `CheckProofOfWork`: `hash > bnTarget` is a
- * failure, so equality passes.
- *
- * Only meaningful for PoW-era headers — see rule 3 in the module docblock.
- */
-export function meetsProofOfWork(hash: Uint8Array, bits: number): boolean {
-  const { target, negative, overflow } = compactToTarget(bits);
-  if (negative || overflow || target === 0n) return false;
-  return hashToUint256(hash) <= target;
-}
-
-/**
- * `Params().LAST_POW_BLOCK()` from `chainparams.cpp`. Above this height the
- * chain is proof-of-stake and header-only proof-of-work verification is not
- * applicable; at or below it, `main.cpp` rejects PoS blocks outright, so every
- * header is provably PoW.
- *
- * Kept here beside {@link proofOfWorkLimit} — the other consensus constant the
- * SPV validator needs that is not carried in `NetworkConfig`.
- */
-export function lastPowBlock(network: NetworkType): number {
-  return network === "mainnet" ? 10_000 : 200;
-}
-
 // ---------------------------------------------------------------------------
 // Header chain validation
 // ---------------------------------------------------------------------------

src/p2p/header-validation.ts

@@ -20,12 +20,9 @@
  */
 
 import { describe, test, expect } from "bun:test";
-import { hashBlockHeader } from "@fairco.in/core";
+import { getNetwork, hashBlockHeader, meetsProofOfWork } from "@fairco.in/core";
 import {
-  meetsProofOfWork,
-  lastPowBlock,
   validateHeaderChain,
-  proofOfWorkLimit,
   HeaderValidationError,
   type HeaderChainAnchor,
 } from "./header-validation";
@@ -169,13 +166,13 @@ describe("meetsProofOfWork", () => {
 
 describe("lastPowBlock", () => {
   test("mirrors chainparams.cpp nLastPOWBlock", () => {
-    expect(lastPowBlock("mainnet")).toBe(10_000);
-    expect(lastPowBlock("testnet")).toBe(200);
+    expect(getNetwork("mainnet").lastPowBlock).toBe(10_000);
+    expect(getNetwork("testnet").lastPowBlock).toBe(200);
   });
 });
 
 describe("validateHeaderChain enforces PoW only in the PoW range", () => {
-  const powLimit = proofOfWorkLimit();
+  const powLimit = getNetwork("mainnet").powLimit;
 
   test("accepts a real PoW header at height 5000", () => {
     const anchor: HeaderChainAnchor = {
@@ -186,7 +183,7 @@ describe("validateHeaderChain enforces PoW only in the PoW range", () => {
       headers: [POW_5000.header],
       anchor,
       powLimit,
-      lastPowBlockHeight: lastPowBlock("mainnet"),
+      lastPowBlockHeight: getNetwork("mainnet").lastPowBlock,
     });
     expect(result[0].height).toBe(5000);
   });
@@ -205,7 +202,7 @@ describe("validateHeaderChain enforces PoW only in the PoW range", () => {
         headers: [tampered],
         anchor,
         powLimit,
-        lastPowBlockHeight: lastPowBlock("mainnet"),
+        lastPowBlockHeight: getNetwork("mainnet").lastPowBlock,
       }),
     ).toThrow(/proof-of-work/i);
   });
@@ -219,7 +216,7 @@ describe("validateHeaderChain enforces PoW only in the PoW range", () => {
       headers: [POS_10001.header],
       anchor,
       powLimit,
-      lastPowBlockHeight: lastPowBlock("mainnet"),
+      lastPowBlockHeight: getNetwork("mainnet").lastPowBlock,
     });
     expect(result[0].height).toBe(10_001);
   });

src/p2p/proof-of-work.test.ts

@@ -13,8 +13,6 @@ import { validateMerkleProof } from "./merkle-proof";
 import {
   validateHeaderChain,
   planChainUpdate,
-  proofOfWorkLimit,
-  lastPowBlock,
   HeaderValidationError,
   type HeaderChainAnchor,
   type ValidatedHeader,
@@ -273,7 +271,7 @@ export class SPVClient {
   constructor(config: SPVClientConfig) {
     this.headerStore = config.headerStore;
     this.network = config.network;
-    this.powLimit = proofOfWorkLimit();
+    this.powLimit = config.network.powLimit;
     this.startFromCheckpoint = config.startFromCheckpoint ?? false;
 
     const peerManagerConfig: PeerManagerConfig = {
@@ -308,58 +306,16 @@ export class SPVClient {
     // `prevBlock`; without genesis in the store there is no anchor and header
     // validation rejects block 1, so sync (and therefore receiving) never
     // starts.
-    // One read of the tip serves all three startup steps: the corruption check,
-    // the genesis/anchor seed, and the initial height. Each used to issue its
-    // own `SELECT ... ORDER BY height DESC LIMIT 1` on the wallet-start path.
-    const tip = await this.discardCorruptHeaderStore();
+    // The store is repaired and migrated by the storage layer before it is
+    // handed over, so the client can assume it is coherent. One read of the tip
+    // serves both remaining startup steps.
+    const tip = await this.headerStore.getLatestHeader();
     const seeded = await this.ensureStartHeader(tip);
     this.chainHeight = seeded?.height ?? 0;
 
     await this.peerManager.start();
   }
 
-  /**
-   * Drop the whole header store if its tip does not re-hash to the id recorded
-   * alongside it.
-   *
-   * `@fairco.in/core` 0.2.0–0.3.1 shipped a regressed Quark implementation that
-   * computed the wrong id for every block. A wallet that synced against one of
-   * those builds holds headers keyed by bogus hashes: once the correct hash is
-   * restored, no incoming header's `prevBlock` can ever match the stored tip,
-   * so `processHeadersResponse` rejects every batch as unconnected and sync
-   * stalls silently and permanently.
-   *
-   * One hash of the tip is enough to detect it, and re-syncing headers is
-   * cheap next to a wallet that never confirms another payment. Wallet data
-   * (UTXOs, transactions, notes) is untouched: the rescan that follows the
-   * re-sync re-derives confirmations from the rebuilt chain.
-   */
-  private async discardCorruptHeaderStore(): Promise<
-    StoredBlockHeader | undefined
-  > {
-    const tip = await this.headerStore.getLatestHeader();
-    // Genesis is seeded from network config rather than hashed, so it proves
-    // nothing either way.
-    if (!tip || tip.height === 0) return tip;
-
-    const recomputed = hashBlockHeader({
-      version: tip.version,
-      prevBlock: tip.prevBlock,
-      merkleRoot: tip.merkleRoot,
-      timestamp: tip.timestamp,
-      bits: tip.bits,
-      nonce: tip.nonce,
-      // Not part of the hashed 80 bytes; only the `headers` wire message
-      // carries it.
-      txCount: 0,
-    });
-    if (bytesEqual(recomputed, tip.hash)) return tip;
-
-    await this.headerStore.deleteHeadersAboveHeight(-1);
-    this.chainHeight = 0;
-    return undefined;
-  }
-
   /**
    * Persist the genesis header at height 0 if the store is empty. Its hash and
    * fields come straight from the network config; the stored hash is in the
@@ -754,7 +710,7 @@ export class SPVClient {
         checkpointHashHex: (height) =>
           getCheckpointHash(height, this.network.name),
         genesisHashHex: this.network.genesisHash,
-        lastPowBlockHeight: lastPowBlock(this.network.name),
+        lastPowBlockHeight: this.network.lastPowBlock,
       });
     } catch (err) {
       if (err instanceof HeaderValidationError) {

src/p2p/spv-client.ts

@@ -14,9 +14,11 @@ import {
   hashBlockHeader,
   getCheckpointHash,
   bytesToHex,
+  getNetwork,
+  meetsProofOfWork,
 } from "@fairco.in/core";
 import { getSyncAnchor } from "./sync-anchor";
-import { lastPowBlock, meetsProofOfWork } from "./header-validation";
+
 
 /** Display order — the convention the checkpoint table uses. */
 function toDisplayHex(bytes: Uint8Array): string {
@@ -55,7 +57,7 @@ describe("mainnet sync anchor", () => {
 
   test("sits above the proof-of-work era, so it is a PoS header", () => {
     if (!anchor) throw new Error("no mainnet anchor");
-    expect(anchor.height).toBeGreaterThan(lastPowBlock("mainnet"));
+    expect(anchor.height).toBeGreaterThan(getNetwork("mainnet").lastPowBlock);
     // PoS headers carry no work and must never be PoW-checked.
     expect(anchor.nonce).toBe(0);
     expect(meetsProofOfWork(anchor.hash, anchor.bits)).toBe(false);