[#1304] Add TWAP minimum samples validation

docs/airdrop-contracts.md

@@ -43,3 +43,15 @@ forge script contracts/script/DeployMerkleClaim.s.sol \
   --broadcast \
   --private-key $DEPLOYER_PRIVATE_KEY
 ```
+
+## Settlement (finalize)
+
+```bash
+npx tsx scripts/airdrop-finalize.ts [--dry-run]
+```
+
+Emergency override for partial TWAP data (<5 daily price samples):
+
+```bash
+AIRDROP_FINALIZE_ALLOW_PARTIAL_TWAP=1 npx tsx scripts/airdrop-finalize.ts
+```

lib/airdrop/twap.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import { validateTwapSamples } from "./twap";
+
+describe("validateTwapSamples", () => {
+  it("rejects 0 samples", () => {
+    const result = validateTwapSamples(0, false);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error).toContain("No daily price entries");
+  });
+
+  it("rejects 1 sample without override", () => {
+    const result = validateTwapSamples(1, false);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error).toContain("requires >=5");
+  });
+
+  it("rejects 4 samples without override", () => {
+    const result = validateTwapSamples(4, false);
+    expect(result.ok).toBe(false);
+  });
+
+  it("allows 1 sample with override", () => {
+    const result = validateTwapSamples(1, true);
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.warning).toBeDefined();
+  });
+
+  it("allows 5 samples with warning", () => {
+    const result = validateTwapSamples(5, false);
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.warning).toContain("5 samples");
+  });
+
+  it("allows 6 samples with warning", () => {
+    const result = validateTwapSamples(6, false);
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.warning).toContain("6 samples");
+  });
+
+  it("allows 7 samples cleanly (no warning)", () => {
+    const result = validateTwapSamples(7, false);
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.warning).toBeUndefined();
+  });
+});

lib/airdrop/twap.ts

@@ -0,0 +1,27 @@
+export const EXPECTED_SAMPLES = 7;
+export const MINIMUM_SAMPLES = 5;
+export const OVERRIDE_ENV = "AIRDROP_FINALIZE_ALLOW_PARTIAL_TWAP";
+
+export function validateTwapSamples(
+  count: number,
+  overrideEnabled: boolean,
+): { ok: true; warning?: string } | { ok: false; error: string } {
+  if (count === 0) {
+    return { ok: false, error: "No daily price entries found for TWAP window" };
+  }
+  if (count < MINIMUM_SAMPLES && !overrideEnabled) {
+    return {
+      ok: false,
+      error:
+        `TWAP requires >=${MINIMUM_SAMPLES} daily samples, got ${count}. ` +
+        `Investigate pl_daily_prices cron coverage OR set ${OVERRIDE_ENV}=1 to proceed with partial data.`,
+    };
+  }
+  if (count < EXPECTED_SAMPLES) {
+    return {
+      ok: true,
+      warning: `TWAP using ${count} samples (expected ${EXPECTED_SAMPLES}). Verify pl_daily_prices cron coverage.`,
+    };
+  }
+  return { ok: true };
+}

package.json

@@ -1,6 +1,6 @@
 {
   "name": "plotlink",
-  "version": "1.41.0",
+  "version": "1.41.1",
   "private": true,
   "workspaces": [
     "packages/*"

scripts/airdrop-finalize.ts

@@ -20,6 +20,7 @@ import { StandardMerkleTree } from "@openzeppelin/merkle-tree";
 import { writeFileSync } from "fs";
 import { getAirdropConfig } from "../lib/airdrop/config";
 import { weightedSpendQuery } from "../lib/airdrop/sql";
+import { validateTwapSamples, OVERRIDE_ENV } from "../lib/airdrop/twap";
 
 const dryRun = process.argv.includes("--dry-run");
 
@@ -45,7 +46,13 @@ async function computeTwap(): Promise<number> {
     .lte("recorded_at", endDate.toISOString().slice(0, 10));
 
   if (error) throw new Error(`Failed to fetch daily prices: ${error.message}`);
-  if (!data || data.length === 0) throw new Error("No daily price entries found for TWAP window");
+
+  const validation = validateTwapSamples(
+    data?.length ?? 0,
+    process.env[OVERRIDE_ENV] === "1",
+  );
+  if (!validation.ok) throw new Error(validation.error);
+  if (validation.warning) console.warn(`Warning: ${validation.warning}`);
 
   const sum = data.reduce((acc, row) => acc + Number(row.mcap_usd), 0);
   const twap = sum / data.length;