solanapolis 1.0.0

package/src/lib/city-slots.ts

@@ -0,0 +1,35 @@
+/**
+ * City slot allocation constants.
+ *
+ * Slots are assigned in wallet-array order (ordered by placement in the DB).
+ * The first 100 wallets get a plane, the first 250 get a car, and the total
+ * city capacity is 1,000 wallets.
+ */
+
+export const MAX_WALLETS = 1000;
+export const MAX_PLANES  = 100;
+export const MAX_CARS    = 250;
+
+export interface SlotCounts {
+  totalWallets: number;
+  planesUsed: number;
+  carsUsed: number;
+  walletsRemaining: number;
+  planesRemaining: number;
+  carsRemaining: number;
+}
+
+/**
+ * Compute how many planes, cars, and wallet slots are claimed vs available.
+ */
+export function getSlotCounts(walletCount: number): SlotCounts {
+  const clamped = Math.min(walletCount, MAX_WALLETS);
+  return {
+    totalWallets: clamped,
+    planesUsed: Math.min(clamped, MAX_PLANES),
+    carsUsed: Math.min(clamped, MAX_CARS),
+    walletsRemaining: MAX_WALLETS - clamped,
+    planesRemaining: MAX_PLANES - Math.min(clamped, MAX_PLANES),
+    carsRemaining: MAX_CARS - Math.min(clamped, MAX_CARS),
+  };
+}

package/src/lib/city-zoning.ts

@@ -0,0 +1,64 @@
+/**
+ * City zoning system — assigns block types based on distance from city center.
+ *
+ * Zone layout (concentric rings):
+ *   DOWNTOWN  — center ~20% of blocks: skyscrapers (height 15–45)
+ *   MIDRISE   — next ring ~30%: mid-level buildings (height 5–15)
+ *   LOWRISE   — outer ring ~40%: low buildings (height 0.5–5)
+ *   PARK      — 10 hardcoded park blocks
+ */
+
+export type ZoneType = "downtown" | "midrise" | "lowrise" | "park";
+
+export interface BlockZone {
+  zone: ZoneType;
+  maxHeight: number;
+  minHeight: number;
+}
+
+const ZONE_CONFIGS: Record<Exclude<ZoneType, "park">, { minHeight: number; maxHeight: number }> = {
+  downtown: { minHeight: 12, maxHeight: 45 },
+  midrise:  { minHeight: 4, maxHeight: 14 },
+  lowrise:  { minHeight: 0.5, maxHeight: 5 },
+};
+
+/**
+ * Given block grid coordinates and total grid size, determine what zone the block falls in.
+ */
+export function getBlockZone(
+  blockRow: number,
+  blockCol: number,
+  blocksPerRow: number,
+): BlockZone {
+  const centerRow = (blocksPerRow - 1) / 2;
+  const centerCol = (blocksPerRow - 1) / 2;
+
+  const dr = blockRow - centerRow;
+  const dc = blockCol - centerCol;
+  const dist = Math.sqrt(dr * dr + dc * dc);
+
+  const maxDist = Math.sqrt(centerRow * centerRow + centerCol * centerCol) || 1;
+  const normDist = dist / maxDist;
+
+  if (isParkBlock(blockRow, blockCol)) {
+    return { zone: "park", minHeight: 0, maxHeight: 0 };
+  }
+
+  if (normDist <= 0.38) {
+    return { zone: "downtown", ...ZONE_CONFIGS.downtown };
+  }
+  if (normDist <= 0.76) {
+    return { zone: "midrise", ...ZONE_CONFIGS.midrise };
+  }
+  return { zone: "lowrise", ...ZONE_CONFIGS.lowrise };
+}
+
+/** Hardcoded park positions matching the DB block_spiral_order seed */
+const PARK_BLOCKS = new Set([
+  "10,13", "11,13", "13,11", "12,3", "13,3",
+  "8,18", "20,12", "4,10", "18,21", "22,6",
+]);
+
+export function isParkBlock(row: number, col: number): boolean {
+  return PARK_BLOCKS.has(`${row},${col}`);
+}

package/src/lib/collision-map.ts

@@ -0,0 +1,147 @@
+import { PlacedWallet } from "@/types/wallet";
+import {
+  getWalletWorldPosition,
+  getBuildingDimensions,
+  setMaxVolume,
+} from "./building-math";
+import { computeHouseSlots } from "@/components/InstancedHouses";
+import {
+  CELL_SIZE,
+  BLOCK_SIZE,
+  BLOCK_STRIDE,
+  BLOCKS_PER_ROW,
+  OFFSET_X,
+  OFFSET_Z,
+  SLOTS_PER_BLOCK,
+  PARK_BLOCKS,
+} from "./city-constants";
+
+export interface AABB {
+  minX: number;
+  maxX: number;
+  minZ: number;
+  maxZ: number;
+}
+
+const BUCKET_SIZE = 4; // matches CELL_SIZE
+
+function bucketKey(bx: number, bz: number): number {
+  // Pack two ints into one number (offset to avoid negatives)
+  return (bx + 500) * 10000 + (bz + 500);
+}
+
+export class CollisionMap {
+  private buckets = new Map<number, AABB[]>();
+
+  addAABB(aabb: AABB) {
+    const minBX = Math.floor(aabb.minX / BUCKET_SIZE);
+    const maxBX = Math.floor(aabb.maxX / BUCKET_SIZE);
+    const minBZ = Math.floor(aabb.minZ / BUCKET_SIZE);
+    const maxBZ = Math.floor(aabb.maxZ / BUCKET_SIZE);
+
+    for (let bx = minBX; bx <= maxBX; bx++) {
+      for (let bz = minBZ; bz <= maxBZ; bz++) {
+        const key = bucketKey(bx, bz);
+        let list = this.buckets.get(key);
+        if (!list) {
+          list = [];
+          this.buckets.set(key, list);
+        }
+        list.push(aabb);
+      }
+    }
+  }
+
+  testAABB(test: AABB): { hit: boolean; pushX: number; pushZ: number } {
+    const minBX = Math.floor(test.minX / BUCKET_SIZE);
+    const maxBX = Math.floor(test.maxX / BUCKET_SIZE);
+    const minBZ = Math.floor(test.minZ / BUCKET_SIZE);
+    const maxBZ = Math.floor(test.maxZ / BUCKET_SIZE);
+
+    let pushX = 0;
+    let pushZ = 0;
+    let hit = false;
+
+    // Collect unique AABBs from relevant buckets
+    const checked = new Set<AABB>();
+
+    for (let bx = minBX; bx <= maxBX; bx++) {
+      for (let bz = minBZ; bz <= maxBZ; bz++) {
+        const list = this.buckets.get(bucketKey(bx, bz));
+        if (!list) continue;
+        for (const aabb of list) {
+          if (checked.has(aabb)) continue;
+          checked.add(aabb);
+
+          // AABB overlap test
+          if (
+            test.maxX <= aabb.minX ||
+            test.minX >= aabb.maxX ||
+            test.maxZ <= aabb.minZ ||
+            test.minZ >= aabb.maxZ
+          ) continue;
+
+          hit = true;
+
+          // Minimum translation vector
+          const overlapLeft = test.maxX - aabb.minX;
+          const overlapRight = aabb.maxX - test.minX;
+          const overlapTop = test.maxZ - aabb.minZ;
+          const overlapBottom = aabb.maxZ - test.minZ;
+
+          const minOverlapX = overlapLeft < overlapRight ? -overlapLeft : overlapRight;
+          const minOverlapZ = overlapTop < overlapBottom ? -overlapTop : overlapBottom;
+
+          if (Math.abs(minOverlapX) < Math.abs(minOverlapZ)) {
+            pushX += minOverlapX;
+          } else {
+            pushZ += minOverlapZ;
+          }
+        }
+      }
+    }
+
+    return { hit, pushX, pushZ };
+  }
+}
+
+export function buildCollisionMap(wallets: PlacedWallet[]): CollisionMap {
+  const map = new CollisionMap();
+
+  // Ensure maxVolume is set for building dimension calculations
+  setMaxVolume(wallets);
+
+  // 1. Buildings
+  for (const w of wallets) {
+    const dims = getBuildingDimensions(w);
+    const pos = getWalletWorldPosition(w, dims);
+    const halfW = dims.width / 2;
+    const halfD = dims.depth / 2;
+    map.addAABB({
+      minX: pos[0] - halfW,
+      maxX: pos[0] + halfW,
+      minZ: pos[2] - halfD,
+      maxZ: pos[2] + halfD,
+    });
+  }
+
+  // 2. Houses
+  const occupiedSlots = new Set<string>();
+  for (const w of wallets) {
+    occupiedSlots.add(`${w.blockRow},${w.blockCol},${w.localSlot}`);
+  }
+
+  const houses = computeHouseSlots(occupiedSlots);
+  for (const h of houses) {
+    // Axis-aligned approximation of rotated footprint
+    const halfExtent = Math.max(h.w, h.d) / 2;
+    map.addAABB({
+      minX: h.x - halfExtent,
+      maxX: h.x + halfExtent,
+      minZ: h.z - halfExtent,
+      maxZ: h.z + halfExtent,
+    });
+  }
+
+  return map;
+}

package/src/lib/day-night.ts

@@ -0,0 +1,252 @@
+import * as THREE from "three";
+
+// Full cycle duration in seconds (12-min loop: ~5min day, transitions, ~5min night)
+export const CYCLE_DURATION = 720;
+
+export interface DayNightState {
+  skyColor:         THREE.Color; // horizon tint used for fog
+  fogColor:         THREE.Color;
+  fogNear:          number;
+  fogFar:           number;
+  ambientColor:     THREE.Color;
+  ambientIntensity: number;
+  sunColor:         THREE.Color;
+  sunIntensity:     number;
+  sunPosition:      THREE.Vector3;
+  hemiSkyColor:     THREE.Color;
+  hemiGroundColor:  THREE.Color;
+  hemiIntensity:    number;
+  accentColor:      THREE.Color;
+  accentIntensity:  number;
+  starsOpacity:     number;
+  // Physically-based sky shader parameters (three <Sky> component)
+  turbidity:        number; // 1–20  atmosphere density / haziness
+  rayleigh:         number; // 0–4   Rayleigh scattering (blue sky strength)
+  mieCoefficient:   number; // 0–0.1 Mie scattering (sun-disc haze radius)
+  mieDirectionalG:  number; // 0–1   Mie directional (sun-disc sharpness)
+}
+
+interface Keyframe {
+  time:     number;
+  sky:      string;
+  fog:      string;
+  fogNear:  number;
+  fogFar:   number;
+  ambCol:   string;
+  ambInt:   number;
+  sunCol:   string;
+  sunInt:   number;
+  hemiSky:  string;
+  hemiGnd:  string;
+  hemiInt:  number;
+  accCol:   string;
+  accInt:   number;
+  stars:    number;
+  turbidity:  number;
+  rayleigh:   number;
+  mie:        number;
+  mieG:       number;
+}
+
+// ─── Weather-grade photorealistic keyframes ───────────────────────────────────
+// t=0.00  sunrise  ·  t=0.08  morning  ·  t=0.25  midday
+// t=0.42  golden hour  ·  t=0.50  sunset  ·  t=0.58  blue hour
+// t=0.75  midnight  ·  t=0.92  pre-dawn
+const KF: Keyframe[] = [
+  {
+    // ── SUNRISE — molten orange-rose horizon ──────────────────────────────────
+    time:    0.0,
+    sky:     "#e8601a",
+    fog:     "#b03c10",
+    fogNear: 260, fogFar: 700,
+    ambCol:  "#ffb87a", ambInt: 0.32,
+    sunCol:  "#ff7020", sunInt: 0.65,
+    hemiSky: "#ff9055", hemiGnd: "#5a2e14", hemiInt: 0.32,
+    accCol:  "#7c3aed",  accInt: 0.08,
+    stars:   0.12,
+    turbidity: 13, rayleigh: 0.7, mie: 0.022, mieG: 0.93,
+  },
+  {
+    // ── MORNING — champagne blue, long warm shadows ───────────────────────────
+    time:    0.08,
+    sky:     "#68b8dc",
+    fog:     "#90d0ea",
+    fogNear: 420, fogFar: 1100,
+    ambCol:  "#fff5e0", ambInt: 0.54,
+    sunCol:  "#ffe8b0", sunInt: 1.0,
+    hemiSky: "#a0dcf4", hemiGnd: "#7a5a36", hemiInt: 0.42,
+    accCol:  "#6366f1",  accInt: 0.0,
+    stars:   0.0,
+    turbidity: 4, rayleigh: 1.5, mie: 0.005, mieG: 0.88,
+  },
+  {
+    // ── MIDDAY — crisp cerulean, slight atmospheric haze ──────────────────────
+    time:    0.25,
+    sky:     "#3a98cc",
+    fog:     "#a8dcf2",
+    fogNear: 520, fogFar: 1400,
+    ambCol:  "#ffffff", ambInt: 0.75,
+    sunCol:  "#fffaf0", sunInt: 1.5,
+    hemiSky: "#78c8ec", hemiGnd: "#8a6a3a", hemiInt: 0.54,
+    accCol:  "#6366f1",  accInt: 0.0,
+    stars:   0.0,
+    turbidity: 2, rayleigh: 2.2, mie: 0.003, mieG: 0.8,
+  },
+  {
+    // ── GOLDEN HOUR — warm amber, sky turning from blue to gold ──────────────
+    time:    0.42,
+    sky:     "#5898bc",
+    fog:     "#80b8d8",
+    fogNear: 360, fogFar: 1050,
+    ambCol:  "#ffeeaa", ambInt: 0.58,
+    sunCol:  "#ffd060", sunInt: 1.0,
+    hemiSky: "#68a8cc", hemiGnd: "#684c1e", hemiInt: 0.44,
+    accCol:  "#f97316",  accInt: 0.06,
+    stars:   0.0,
+    turbidity: 6, rayleigh: 1.4, mie: 0.010, mieG: 0.91,
+  },
+  {
+    // ── SUNSET — blazing fire on the horizon, dark indigo above ───────────────
+    time:    0.50,
+    sky:     "#c44010",
+    fog:     "#9a3010",
+    fogNear: 320, fogFar: 880,
+    ambCol:  "#ff9850", ambInt: 0.58,
+    sunCol:  "#ff5010", sunInt: 0.80,
+    hemiSky: "#ff6a30", hemiGnd: "#7a4020", hemiInt: 0.46,
+    accCol:  "#f97316",  accInt: 0.30,
+    stars:   0.05,
+    turbidity: 16, rayleigh: 0.5, mie: 0.030, mieG: 0.95,
+  },
+  {
+    // ── BLUE HOUR — electric indigo, city starts glowing ─────────────────────
+    time:    0.58,
+    sky:     "#0c1028",
+    fog:     "#0c1028",
+    fogNear: 500, fogFar: 1200,
+    ambCol:  "#8090cc", ambInt: 0.42,
+    sunCol:  "#5058a8", sunInt: 0.10,
+    hemiSky: "#283068", hemiGnd: "#141414", hemiInt: 0.28,
+    accCol:  "#6366f1",  accInt: 1.4,
+    stars:   0.60,
+    turbidity: 6, rayleigh: 0.25, mie: 0.004, mieG: 0.7,
+  },
+  {
+    // ── MIDNIGHT — deep space, stars blazing, city fully lit ─────────────────
+    time:    0.75,
+    sky:     "#03030c",
+    fog:     "#04040e",
+    fogNear: 640, fogFar: 1600,
+    ambCol:  "#b0b8f0", ambInt: 1.0,   // keep high so buildings stay readable at night
+    sunCol:  "#5868c0", sunInt: 0.30,
+    hemiSky: "#4858a0", hemiGnd: "#282838", hemiInt: 0.80,
+    accCol:  "#6366f1",  accInt: 2.6,
+    stars:   1.0,
+    turbidity: 1, rayleigh: 0.15, mie: 0.001, mieG: 0.5,
+  },
+  {
+    // ── PRE-DAWN — cold blue-black, stars fading ──────────────────────────────
+    time:    0.92,
+    sky:     "#06091a",
+    fog:     "#06091a",
+    fogNear: 560, fogFar: 1320,
+    ambCol:  "#8888b8", ambInt: 0.48,
+    sunCol:  "#3a3e80", sunInt: 0.07,
+    hemiSky: "#1e2248", hemiGnd: "#121212", hemiInt: 0.36,
+    accCol:  "#6366f1",  accInt: 1.5,
+    stars:   0.82,
+    turbidity: 2, rayleigh: 0.28, mie: 0.002, mieG: 0.65,
+  },
+];
+
+// Pre-bake THREE.Color for every keyframe — no allocations during animation
+const COLORS = KF.map((k) => ({
+  sky:     new THREE.Color(k.sky),
+  fog:     new THREE.Color(k.fog),
+  amb:     new THREE.Color(k.ambCol),
+  sun:     new THREE.Color(k.sunCol),
+  hemiSky: new THREE.Color(k.hemiSky),
+  hemiGnd: new THREE.Color(k.hemiGnd),
+  acc:     new THREE.Color(k.accCol),
+}));
+
+// Reusable temp objects — zero per-frame allocation
+const _sky    = new THREE.Color();
+const _fog    = new THREE.Color();
+const _amb    = new THREE.Color();
+const _sun    = new THREE.Color();
+const _hSky   = new THREE.Color();
+const _hGnd   = new THREE.Color();
+const _acc    = new THREE.Color();
+const _sunPos = new THREE.Vector3();
+
+function smoothstep(t: number): number {
+  return t * t * (3 - 2 * t);
+}
+
+function lerp(a: number, b: number, t: number): number {
+  return a + (b - a) * t;
+}
+
+/** Lamp/headlight intensity — 0 in daylight, 1 at night, smooth transitions. */
+export function lampIntensity(t: number): number {
+  if (t >= 0.58 && t <= 0.95) return 1;
+  if (t >  0.50 && t <  0.58) return (t - 0.50) / 0.08;
+  if (t >  0.95)               return 1 - (t - 0.95) / 0.05;
+  if (t <  0.02)               return 1 - t / 0.02;
+  return 0;
+}
+
+export function getDayNightState(timeOfDay: number): DayNightState {
+  const t = ((timeOfDay % 1) + 1) % 1;
+
+  let afterIdx = KF.findIndex((k) => k.time > t);
+  if (afterIdx === -1) afterIdx = 0;
+  const beforeIdx = (afterIdx - 1 + KF.length) % KF.length;
+
+  const before = KF[beforeIdx];
+  const after  = KF[afterIdx];
+  const cB     = COLORS[beforeIdx];
+  const cA     = COLORS[afterIdx];
+
+  let progress: number;
+  if (after.time > before.time) {
+    progress = (t - before.time) / (after.time - before.time);
+  } else {
+    const segLen = 1 - before.time + after.time;
+    progress = t >= before.time
+      ? (t - before.time) / segLen
+      : (1 - before.time + t) / segLen;
+  }
+  progress = smoothstep(progress);
+
+  // Sun orbits the city: rises east (t=0), overhead (t=0.25), sets west (t=0.5), below (t=0.75)
+  const sunAngle = t * Math.PI * 2;
+  _sunPos.set(
+    Math.cos(sunAngle) * 200,
+    Math.sin(sunAngle) * 200,  // allow full below-horizon travel for night
+    30,
+  );
+
+  return {
+    skyColor:         _sky.lerpColors(cB.sky, cA.sky, progress),
+    fogColor:         _fog.lerpColors(cB.fog, cA.fog, progress),
+    fogNear:          lerp(before.fogNear, after.fogNear,  progress),
+    fogFar:           lerp(before.fogFar,  after.fogFar,   progress),
+    ambientColor:     _amb.lerpColors(cB.amb, cA.amb, progress),
+    ambientIntensity: lerp(before.ambInt,  after.ambInt,   progress),
+    sunColor:         _sun.lerpColors(cB.sun, cA.sun, progress),
+    sunIntensity:     lerp(before.sunInt,  after.sunInt,   progress),
+    sunPosition:      _sunPos,
+    hemiSkyColor:     _hSky.lerpColors(cB.hemiSky, cA.hemiSky, progress),
+    hemiGroundColor:  _hGnd.lerpColors(cB.hemiGnd, cA.hemiGnd, progress),
+    hemiIntensity:    lerp(before.hemiInt, after.hemiInt,  progress),
+    accentColor:      _acc.lerpColors(cB.acc, cA.acc, progress),
+    accentIntensity:  lerp(before.accInt,  after.accInt,   progress),
+    starsOpacity:     lerp(before.stars,   after.stars,    progress),
+    turbidity:        lerp(before.turbidity, after.turbidity, progress),
+    rayleigh:         lerp(before.rayleigh,  after.rayleigh,  progress),
+    mieCoefficient:   lerp(before.mie,       after.mie,       progress),
+    mieDirectionalG:  lerp(before.mieG,      after.mieG,      progress),
+  };
+}

package/src/lib/export-card.ts

@@ -0,0 +1,28 @@
+import { toPng } from "html-to-image";
+
+export async function exportCardAsPng(element: HTMLElement): Promise<Blob> {
+  const dataUrl = await toPng(element, {
+    pixelRatio: 2,
+    width: 600,
+    height: 340,
+  });
+  const res = await fetch(dataUrl);
+  return res.blob();
+}
+
+export function downloadBlob(blob: Blob, filename: string) {
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename;
+  document.body.appendChild(a);
+  a.click();
+  document.body.removeChild(a);
+  URL.revokeObjectURL(url);
+}
+
+export async function copyBlobToClipboard(blob: Blob) {
+  await navigator.clipboard.write([
+    new ClipboardItem({ "image/png": blob }),
+  ]);
+}

package/src/lib/helius-webhook.ts

@@ -0,0 +1,90 @@
+const HELIUS_WEBHOOKS_API = "https://api.helius.xyz/v0/webhooks";
+
+function apiKey(): string {
+  return process.env.HELIUS_API_KEY!;
+}
+
+function webhookId(): string | undefined {
+  return process.env.HELIUS_WEBHOOK_ID || undefined;
+}
+
+function webhookSecret(): string | undefined {
+  return process.env.HELIUS_WEBHOOK_SECRET || undefined;
+}
+
+/** Create the swap webhook. Returns { webhookId, secret }. */
+export async function createSwapWebhook(
+  webhookUrl: string,
+  addresses: string[],
+): Promise<{ webhookId: string; secret: string }> {
+  const secret = crypto.randomUUID();
+
+  const res = await fetch(`${HELIUS_WEBHOOKS_API}?api-key=${apiKey()}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      webhookURL: webhookUrl,
+      transactionTypes: ["SWAP"],
+      accountAddresses: addresses,
+      webhookType: "enhanced",
+      authHeader: `Bearer ${secret}`,
+    }),
+  });
+
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`Failed to create webhook: ${res.status} ${body}`);
+  }
+
+  const data = await res.json();
+  return { webhookId: data.webhookID, secret };
+}
+
+/**
+ * Add a single address to the existing swap webhook.
+ * Fetches the current webhook config, appends the address (if not already present),
+ * and PUTs the full object back (Helius requires the full object on update).
+ *
+ * No-ops silently if HELIUS_WEBHOOK_ID is not configured.
+ */
+export async function addAddressToWebhook(address: string): Promise<void> {
+  const id = webhookId();
+  if (!id) return;
+
+  try {
+    // GET current webhook
+    const getRes = await fetch(
+      `${HELIUS_WEBHOOKS_API}/${id}?api-key=${apiKey()}`,
+    );
+    if (!getRes.ok) {
+      console.error(`Failed to get webhook: ${getRes.status}`);
+      return;
+    }
+    const webhook = await getRes.json();
+
+    // Skip if already tracked
+    const existing: string[] = webhook.accountAddresses ?? [];
+    if (existing.includes(address)) return;
+
+    // PUT with new address appended
+    existing.push(address);
+    const putRes = await fetch(
+      `${HELIUS_WEBHOOKS_API}/${id}?api-key=${apiKey()}`,
+      {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          ...webhook,
+          accountAddresses: existing,
+        }),
+      },
+    );
+
+    if (!putRes.ok) {
+      const body = await putRes.text();
+      console.error(`Failed to update webhook: ${putRes.status} ${body}`);
+    }
+  } catch (err) {
+    console.error("addAddressToWebhook error:", err);
+  }
+}

package/src/lib/helius.ts

@@ -0,0 +1,74 @@
+const HELIUS_WALLET_API = "https://api.helius.xyz/v1/wallet";
+
+export interface WalletIdentity {
+  name: string;
+  type: string;
+  category: string;
+}
+
+/**
+ * Call Helius Wallet API identity endpoint.
+ * Returns identity info for known wallets (exchanges, protocols, etc.) or null if unknown.
+ */
+export async function getWalletIdentity(
+  address: string,
+): Promise<WalletIdentity | null> {
+  const url = `${HELIUS_WALLET_API}/${address}/identity?api-key=${process.env.HELIUS_API_KEY}`;
+  const res = await fetch(url);
+
+  if (res.status === 404) return null;
+  if (!res.ok) return null;
+
+  const data = await res.json();
+  if (!data.name) return null;
+
+  return {
+    name: data.name,
+    type: data.type ?? "unknown",
+    category: data.category ?? "",
+  };
+}
+
+export interface WalletFunding {
+  timestamp: number;
+  funder: string;
+  funderName: string | null;
+  amount: number;
+}
+
+export interface WalletStats {
+  address: string;
+  txnCount: number;
+  walletAgeDays: number;
+  volumeTraded: number;
+  feesPaid: number;
+  firstTxTimestamp: number | null;
+  ingestionStatus?: "queued" | "processing" | "complete" | "failed";
+  uniqueTokensSwapped?: number;
+  latestBlocktime?: number | null;
+  txnsFetched?: number;
+}
+
+/**
+ * Call Helius Wallet API funded-by endpoint.
+ * Returns funding info or null if 404 (e.g., funded via program/airdrop).
+ */
+export async function getWalletFunding(
+  address: string,
+): Promise<WalletFunding | null> {
+  const url = `${HELIUS_WALLET_API}/${address}/funded-by?api-key=${process.env.HELIUS_API_KEY}`;
+  const res = await fetch(url);
+
+  if (res.status === 404) return null;
+  if (!res.ok) {
+    throw new Error(`Helius funded-by error: ${res.status} ${res.statusText}`);
+  }
+
+  const data = await res.json();
+  return {
+    timestamp: data.timestamp,
+    funder: data.funder,
+    funderName: data.funderName ?? null,
+    amount: data.amount,
+  };
+}