updated deterministic hardhat tests

Author: LyonSsS

.env.example

@@ -40,6 +40,22 @@ ETHERSCAN_API_KEY=
 
 # Testing parameters.
 FORK_PROVIDER=https://base-mainnet.public.blastapi.io
+
+# Fork block numbers for consistent coverage between local and CI runs.
+# Each chain has independent block heights, so we need different blocks per chain.
+# When undefined, Hardhat forks at latest block which causes coverage variability (±0.2%).
+# These blocks were captured on 2025-12-16 and should be updated periodically.
+# Update process: Run scripts/get-blocks.mjs to fetch latest blocks, then run coverage and update baseline.
+FORK_BLOCK_NUMBER_BASE=39550474
+FORK_BLOCK_NUMBER_ETHEREUM=24024515
+FORK_BLOCK_NUMBER_ARBITRUM_ONE=411254516
+FORK_BLOCK_NUMBER_OP_MAINNET=127000000
+FORK_BLOCK_NUMBER_POLYGON_MAINNET=80390425
+FORK_BLOCK_NUMBER_AVALANCHE=73848966
+FORK_BLOCK_NUMBER_BSC=71852875
+FORK_BLOCK_NUMBER_LINEA=26756433
+FORK_BLOCK_NUMBER_UNICHAIN=1000000
+
 USDC_OWNER_ADDRESS=0x498581fF718922c3f8e6A244956aF099B2652b2b
 GHO_OWNER_ADDRESS=0x498581fF718922c3f8e6A244956aF099B2652b2b
 EURC_OWNER_ADDRESS=0x498581fF718922c3f8e6A244956aF099B2652b2b

COVERAGE.md

@@ -56,20 +56,25 @@ npm run coverage:update-baseline
 
 **Step-by-step:**
 1. Make your code changes
-2. Run coverage locally:
+2. Ensure `.env` file exists with pinned fork blocks (copy from `.env.example` if needed):
+   ```bash
+   cp .env.example .env
+   ```
+   **Important:** Using the same fork blocks as `.env.example` ensures your local coverage matches CI coverage.
+3. Run coverage locally:
    ```bash
    npm run coverage
    ```
-3. Update the baseline file:
+4. Update the baseline file:
    ```bash
    npm run coverage:update-baseline
    ```
-4. Commit the baseline file:
+5. Commit the baseline file:
    ```bash
    git add coverage-baseline.json
    git commit -m "chore: update coverage baseline"
    ```
-5. Push your PR
+6. Push your PR
 
 **What CI validates:**
 - ✅ **Check 1:** Your committed baseline matches CI coverage (proves you ran coverage)
@@ -108,6 +113,35 @@ Current baseline (as of initial setup):
 ### Environment Setup for CI
 The workflow copies `.env.example` to `.env` to enable fork tests with public RPC endpoints during coverage runs.
 
+### Fork Block Pinning for Deterministic Coverage
+
+**Why fork blocks are pinned:**
+Coverage tests fork mainnet at specific block heights. Without pinning:
+- Developer runs locally → forks at block X → gets 96.93% coverage
+- CI runs 30 mins later → forks at block Y → gets 96.82% coverage
+- Different blocks = different contract states = different test paths = different coverage
+
+**Solution:**
+Pin each chain to a specific block number in `.env.example`:
+```bash
+FORK_BLOCK_NUMBER_BASE=39550474
+FORK_BLOCK_NUMBER_ETHEREUM=24024515
+FORK_BLOCK_NUMBER_ARBITRUM_ONE=411254516
+# etc...
+```
+
+This ensures both local and CI environments fork from **identical blockchain state**, producing **identical coverage results**.
+
+**Updating fork blocks:**
+When you need to test against newer mainnet state:
+1. Run the helper script: `node scripts/get-blocks.mjs`
+2. Copy the output to `.env.example`
+3. Run coverage: `npm run coverage`
+4. If tests pass, update baseline: `npm run coverage:update-baseline`
+5. Commit both `.env.example` and `coverage-baseline.json`
+
+**Note:** Each blockchain has independent block heights, so each needs its own pinned block number.
+
 ### Branch Protection
 To enforce coverage checks, enable branch protection on main:
 1. GitHub Settings → Branches → Branch protection rules

coverage-baseline.json

@@ -1,6 +1,6 @@
 {
   "lines": "96.93",
   "functions": "98.58",
-  "branches": "87.79",
+  "branches": "87.63",
   "statements": "96.93"
 }

hardhat.config.ts

@@ -699,7 +699,14 @@ const config: HardhatUserConfig = {
         url: isSet(process.env.DRY_RUN) || isSet(process.env.FORK_TEST)
           ? process.env[`${process.env.DRY_RUN || process.env.FORK_TEST}_RPC`]!
           : (process.env.FORK_PROVIDER || process.env.BASE_RPC || "https://base-mainnet.public.blastapi.io"),
-        blockNumber: process.env.FORK_BLOCK_NUMBER ? parseInt(process.env.FORK_BLOCK_NUMBER) : undefined,
+        blockNumber: (() => {
+          // Determine which chain is being forked
+          const chain = (process.env.DRY_RUN || process.env.FORK_TEST || 'BASE').toUpperCase();
+          // Look up the per-chain fork block number
+          const blockVar = `FORK_BLOCK_NUMBER_${chain}`;
+          const blockNumber = process.env[blockVar];
+          return blockNumber ? parseInt(blockNumber) : undefined;
+        })(),
       },
       accounts: isSet(process.env.DRY_RUN)
         ? [{privateKey: process.env.PRIVATE_KEY!, balance: "1000000000000000000"}]

scripts/get-blocks.mjs

@@ -0,0 +1,35 @@
+import { ethers } from 'ethers';
+
+const chains = {
+  'BASE': process.env.BASE_RPC || 'https://base-mainnet.public.blastapi.io',
+  'ETHEREUM': process.env.ETHEREUM_RPC || 'https://eth-mainnet.public.blastapi.io',
+  'ARBITRUM_ONE': process.env.ARBITRUM_ONE_RPC || 'https://arbitrum-one.public.blastapi.io',
+  'OP_MAINNET': process.env.OP_MAINNET_RPC || 'https://public-op-mainnet.fastnode.io',
+  'POLYGON_MAINNET': process.env.POLYGON_MAINNET_RPC || 'https://polygon-bor-rpc.publicnode.com',
+  'AVALANCHE': process.env.AVALANCHE_RPC || 'https://avalanche-c-chain-rpc.publicnode.com',
+  'BSC': process.env.BSC_RPC || 'https://bsc-mainnet.public.blastapi.io',
+  'LINEA': process.env.LINEA_RPC || 'https://linea-rpc.publicnode.com',
+};
+
+async function getBlockNumber(name, url) {
+  try {
+    const provider = new ethers.JsonRpcProvider(url);
+    const blockNumber = await provider.getBlockNumber();
+    // Subtract 1000 blocks for safety margin
+    const safeBlock = blockNumber - 1000;
+    console.log(`FORK_BLOCK_NUMBER_${name}=${safeBlock}`);
+    return safeBlock;
+  } catch (error) {
+    console.error(`# Error fetching ${name}: ${error.message}`);
+    return null;
+  }
+}
+
+async function main() {
+  console.log('# Fetching current block numbers...');
+  for (const [name, url] of Object.entries(chains)) {
+    await getBlockNumber(name, url);
+  }
+}
+
+main().catch(console.error);