Check vaulted holdings

export interface VaultHoldingsOptions {
  apiBaseUrl: string;
  chainId: number;
  vault: string;
  owner: string;
  token: string;
  signal?: AbortSignal;
}

export interface VaultHoldings {
  chainId: number;
  vault: string;
  owner: string;
  token: string;
  balance: bigint;
  blockNumber: bigint;
  blockHash: string;
  blockTimestamp: bigint;
  totalPositions: bigint;
}

const uintMax = (1n << 256n) - 1n;

function address(value: unknown): string {
  if (typeof value !== "string" || !/^0x[0-9a-f]{40}$/i.test(value) || /^0x0{40}$/i.test(value)) {
    throw new Error("Use a nonzero wallet, token and vault address.");
  }
  return value.toLowerCase();
}

function uint(value: unknown): bigint {
  if (typeof value !== "string" || !/^(0|[1-9][0-9]{0,77})$/.test(value) || BigInt(value) > uintMax) {
    throw new Error("Invalid integer in the vault holdings response.");
  }
  return BigInt(value);
}

/** Read every page or throw. Never use a partial balance for holder eligibility. */
export async function readVaultHoldings(options: VaultHoldingsOptions): Promise<VaultHoldings> {
  const base = new URL(options.apiBaseUrl);
  const local = ["localhost", "127.0.0.1", "[::1]"].includes(base.hostname);
  if (base.username || base.password || base.pathname !== "/" || base.search || base.hash
    || (base.protocol !== "https:" && !(base.protocol === "http:" && local))) {
    throw new Error("Configure a trusted HTTPS API origin; HTTP is allowed only on loopback.");
  }
  if (!Number.isSafeInteger(options.chainId) || options.chainId <= 0) throw new Error("Invalid chain ID.");
  const identity = {
    chainId: options.chainId, vault: address(options.vault), owner: address(options.owner), token: address(options.token),
  };
  const signal = options.signal ?? AbortSignal.timeout(30_000);
  let snapshot: Omit<VaultHoldings, "balance" | "chainId" | "vault" | "owner" | "token"> | undefined;
  let offset = 0n;
  let balance = 0n;
  let cursor: string | null = null;
  const cursors = new Set<string>();

  for (;;) {
    signal.throwIfAborted();
    const url = new URL("/api/vault-holdings", base);
    url.searchParams.set("chainId", String(identity.chainId));
    url.searchParams.set("owner", identity.owner);
    url.searchParams.set("token", identity.token);
    if (cursor) url.searchParams.set("cursor", cursor);
    const response = await fetch(url, { signal, cache: "no-store", credentials: "omit", redirect: "error" });
    if (!response.ok) throw new Error(`Vault holdings unavailable (HTTP ${response.status}). Retry the entire scan.`);
    const value: unknown = await response.json();
    signal.throwIfAborted();
    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Invalid vault holdings response.");
    const page = value as Record<string, unknown>;
    if (page.chainId !== identity.chainId || address(page.vault) !== identity.vault
      || address(page.owner) !== identity.owner || address(page.token) !== identity.token) {
      throw new Error("The holdings response belongs to another deployment, owner or token.");
    }
    if (typeof page.blockHash !== "string" || !/^0x[0-9a-f]{64}$/i.test(page.blockHash)) throw new Error("Invalid snapshot hash.");
    const current = {
      blockNumber: uint(page.blockNumber), blockHash: page.blockHash.toLowerCase(),
      blockTimestamp: uint(page.blockTimestamp), totalPositions: uint(page.totalPositions),
    };
    if (snapshot && (current.blockNumber !== snapshot.blockNumber || current.blockHash !== snapshot.blockHash
      || current.blockTimestamp !== snapshot.blockTimestamp || current.totalPositions !== snapshot.totalPositions)) {
      throw new Error("The holdings snapshot changed. Restart the scan.");
    }
    snapshot ??= current;
    const count = page.pagePositionCount;
    const scanned = uint(page.scannedPositions);
    const remaining = snapshot.totalPositions - offset;
    const expected = remaining > 100n ? 100n : remaining;
    if (uint(page.pageOffset) !== offset || !Number.isSafeInteger(count) || typeof count !== "number"
      || count < 0 || count > 100 || BigInt(count) !== expected || scanned !== offset + BigInt(count)
      || scanned > snapshot.totalPositions || typeof page.complete !== "boolean"
      || page.complete !== (scanned === snapshot.totalPositions)) {
      throw new Error("Incomplete or inconsistent holdings pagination. Restart the scan.");
    }
    const pageBalance = uint(page.pageBalance);
    if (count === 0 && pageBalance !== 0n) throw new Error("An empty page cannot contain a balance.");
    balance += pageBalance;
    if (balance > uintMax) throw new Error("The holdings balance exceeds the token quantity range.");
    if (page.complete) {
      if (page.nextCursor !== null) throw new Error("Unexpected continuation after a complete scan.");
      return { ...identity, ...snapshot, balance };
    }
    if (typeof page.nextCursor !== "string" || page.nextCursor.length < 1 || page.nextCursor.length > 2_048
      || cursors.has(page.nextCursor) || count === 0) throw new Error("Missing or repeated holdings continuation.");
    cursors.add(page.nextCursor);
    cursor = page.nextCursor;
    offset = scanned;
  }
}