Tombstones for deleted contracts

.env.example

@@ -84,3 +84,15 @@ RETENTION_DAYS=30
 
 # ─── API ─────────────────────────────────────────────────────
 PORT=3000
+
+# ─── Response cache (Redis) ──────────────────────────────────
+# Opt-in caching for the hot read endpoints (/assets/popular, /search).
+# Off by default; set CACHE_ENABLED=true to turn it on.
+# Clients can force a fresh response with the `X-No-Cache` request header.
+CACHE_ENABLED=false
+REDIS_URL="redis://localhost:6379"
+# Key namespace applied to every cached entry.
+CACHE_KEY_PREFIX="wraith:cache:"
+# Per-route TTLs in milliseconds.
+CACHE_TTL_POPULAR_MS=60000
+CACHE_TTL_SEARCH_MS=15000

package.json

@@ -68,6 +68,7 @@
     "express": "^4.18.3",
     "express-rate-limit": "^8.3.2",
     "graphql": "^16.11.0",
+    "ioredis": "^5.11.1",
     "parquetjs-lite": "^0.8.7",
     "ws": "^8.20.0",
     "zod": "^4.4.3"

prisma/migrations/20260629120000_add_contract_tombstones/migration.sql

@@ -0,0 +1,17 @@
+-- Track contract liveness: one tombstone row per contract whose persistent
+-- storage instance entry has expired (liveUntilLedger fell behind the current
+-- ledger). Downstream consumers watch this table for a "contract gone" signal.
+CREATE TABLE "wraith"."ContractTombstone" (
+    "id" SERIAL NOT NULL,
+    "contractId" TEXT NOT NULL,
+    "liveUntilLedger" INTEGER NOT NULL,
+    "detectedLedger" INTEGER NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "ContractTombstone_pkey" PRIMARY KEY ("id")
+);
+
+-- One tombstone per contract; first expiry detection wins, re-detection is a no-op.
+CREATE UNIQUE INDEX "ContractTombstone_contractId_key" ON "wraith"."ContractTombstone"("contractId");
+
+CREATE INDEX "ContractTombstone_detectedLedger_idx" ON "wraith"."ContractTombstone"("detectedLedger");

prisma/schema.prisma

@@ -214,6 +214,31 @@ model RetentionJobRun {
   @@schema("wraith")
 }
 
+// ─── Contract Tombstones ────────────────────────────────────────────────────
+// A tombstone marks a contract whose persistent storage has expired (its
+// instance entry's liveUntilLedger fell behind the current ledger). Downstream
+// consumers watch this table for a "the contract is gone" signal. One row per
+// contract — the first expiry detection wins; re-detection is idempotent.
+model ContractTombstone {
+  id              Int      @id @default(autoincrement())
+
+  // The contract whose storage expired (C...)
+  contractId      String   @unique
+
+  // The contract instance's liveUntilLedger at the moment of expiry — the last
+  // ledger for which the entry was still live.
+  liveUntilLedger Int
+
+  // The ledger at which we observed the entry had expired
+  // (detectedLedger > liveUntilLedger).
+  detectedLedger  Int
+
+  createdAt       DateTime @default(now())
+
+  @@index([detectedLedger])
+  @@schema("wraith")
+}
+
 // ─── Backfill Cursor ───────────────────────────────────────────────────────────
 // Durable cursor so the backfill job can resume mid-range after a crash.
 // Always row ID 1 — singleton, one backfill at a time.