pandora-cli-skills 1.1.14 → 1.1.16

package/README_FOR_SHARING.md

@@ -91,7 +91,7 @@ Prerequisite: Node.js `>=18`.
   - `pandora export --wallet <0x...> --format csv --year 2026 --out ./trades-2026.csv`
   - `pandora arbitrage --venues pandora,polymarket --min-spread-pct 3`
   - `pandora autopilot run|once ...`
-  - `pandora mirror browse|plan|deploy|verify|go|sync|status|close ...`
+  - `pandora mirror browse|plan|deploy|verify|lp-explain|hedge-calc|simulate|go|sync|status|close ...`
   - `pandora webhook test ...`
   - `pandora leaderboard --metric profit|volume|win-rate`
   - `pandora analyze --market-address <0x...> --provider <name>`
@@ -118,6 +118,9 @@ Prerequisite: Node.js `>=18`.
 - `pandora mirror plan --source polymarket --polymarket-market-id <id> --with-rules --include-similarity`
 - `pandora mirror go --polymarket-slug <slug> --liquidity-usdc 10 --paper`
 - `pandora mirror verify --pandora-market-address <0x...> --polymarket-market-id <id> --include-similarity`
+- `pandora mirror lp-explain --liquidity-usdc 10000 --source-yes-pct 58`
+- `pandora mirror hedge-calc --reserve-yes-usdc 8 --reserve-no-usdc 12 --excess-no-usdc 2 --polymarket-yes-pct 60`
+- `pandora mirror simulate --liquidity-usdc 10000 --source-yes-pct 58 --target-yes-pct 58 --volume-scenarios 1000,5000,10000`
 - `pandora mirror sync once --pandora-market-address <0x...> --polymarket-market-id <id> --paper --hedge-ratio 1.0`
 - `pandora mirror status --strategy-hash <hash> --with-live`
 - `pandora mirror close --pandora-market-address <0x...> --polymarket-market-id <id> --dry-run`
@@ -198,6 +201,14 @@ Prerequisite: Node.js `>=18`.
   - envelope is `ok=true`, `command="mirror.deploy"`, with `data.planDigest`, `data.deploymentArgs`, `data.tx`, `data.preflight`, `data.pandora`, `data.postDeployChecks`, and optional `data.trustManifest`.
 - `mirror verify`:
   - envelope is `ok=true`, `command="mirror.verify"`, with `data.matchConfidence`, `data.ruleHashLeft`, `data.ruleHashRight`, `data.ruleDiffSummary`, `data.expiry`, optional `data.trustManifest`, `data.similarityChecks[]`, and `data.gateResult`.
+- `mirror lp-explain`:
+  - envelope is `ok=true`, `command="mirror.lp-explain"`, with complete-set flow fields (`mintedCompleteSets`, `seededPoolReserves`, `returnedExcessTokens`, `totalLpInventory`).
+  - this command explains the `addLiquidity` mechanics explicitly: complete sets are minted first, only a weighted slice is seeded into pool reserves, and excess YES/NO tokens are returned to LP wallet inventory.
+- `mirror hedge-calc`:
+  - envelope is `ok=true`, `command="mirror.hedge-calc"`, with `data.metrics` (`deltaPoolUsdc`, `deltaTotalUsdc`, `targetHedgeUsdcSigned`, `hedgeToken`, `hedgeSharesApprox`, `breakEvenVolumeUsdc`) and `data.scenarios[]` fee-vs-hedge estimates.
+- `mirror simulate`:
+  - envelope is `ok=true`, `command="mirror.simulate"`, with `data.initialState`, `data.targeting`, and `data.scenarios[]` for volume-based LP/hedge planning.
+  - simulation keeps the complete-set split exact (raw integer math), then models directional AMM flow with fee-in-reserve behavior for planning-grade projections.
 - `mirror go`:
   - envelope is `ok=true`, `command="mirror.go"`, with staged results for `data.plan`, `data.deploy`, `data.verify`, optional `data.sync`, and `data.suggestedSyncCommand`.
 - `mirror sync`:

package/cli/lib/mirror_econ_service.cjs

@@ -0,0 +1,556 @@
+const { computeDistributionHint, normalizeProbability } = require('./mirror_sizing_service.cjs');
+
+const MIRROR_LP_EXPLAIN_SCHEMA_VERSION = '1.0.0';
+const MIRROR_HEDGE_CALC_SCHEMA_VERSION = '1.0.0';
+const MIRROR_SIMULATE_SCHEMA_VERSION = '1.0.0';
+const USDC_DECIMALS = 6;
+const USDC_SCALE = 10 ** USDC_DECIMALS;
+
+function toNumber(value) {
+  if (value === null || value === undefined || value === '') return null;
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return null;
+  return numeric;
+}
+
+function round(value, decimals = 6) {
+  if (!Number.isFinite(value)) return null;
+  const factor = 10 ** decimals;
+  return Math.round(value * factor) / factor;
+}
+
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(max, value));
+}
+
+function toRawUsdc(usdc) {
+  const numeric = toNumber(usdc);
+  if (numeric === null) return null;
+  return BigInt(Math.round(numeric * USDC_SCALE));
+}
+
+function rawUsdcToNumber(rawValue) {
+  if (typeof rawValue !== 'bigint') return null;
+  return round(Number(rawValue) / USDC_SCALE, 6);
+}
+
+function toPercent(value) {
+  const numeric = toNumber(value);
+  if (numeric === null) return null;
+  if (numeric >= 0 && numeric <= 1) return round(numeric * 100, 6);
+  if (numeric >= 0 && numeric <= 100) return round(numeric, 6);
+  return null;
+}
+
+function yesPctToProbability(yesPct) {
+  const normalized = normalizeProbability(yesPct);
+  if (normalized === null) return null;
+  return normalized;
+}
+
+function resolveDistribution(options = {}) {
+  const diagnostics = [];
+  const sourceYesPct = toPercent(options.sourceYesPct);
+
+  const explicitYes = toNumber(options.distributionYes);
+  const explicitNo = toNumber(options.distributionNo);
+  if (explicitYes !== null || explicitNo !== null) {
+    if (!Number.isInteger(explicitYes) || !Number.isInteger(explicitNo)) {
+      throw new Error('distributionYes and distributionNo must be integers.');
+    }
+    if (explicitYes < 0 || explicitNo < 0 || explicitYes + explicitNo !== 1_000_000_000) {
+      throw new Error('distributionYes + distributionNo must equal 1000000000.');
+    }
+    return {
+      sourceYesPct,
+      sourceYesProbability: sourceYesPct === null ? null : round(sourceYesPct / 100, 6),
+      distributionYes: explicitYes,
+      distributionNo: explicitNo,
+      diagnostics,
+      mode: 'explicit',
+    };
+  }
+
+  const distribution = computeDistributionHint(sourceYesPct === null ? 50 : sourceYesPct);
+  if (sourceYesPct === null) {
+    diagnostics.push('No source YES probability supplied; defaulted to balanced 50/50 distribution hint.');
+  }
+
+  return {
+    sourceYesPct,
+    sourceYesProbability:
+      sourceYesPct === null
+        ? null
+        : round(sourceYesPct / 100, 6),
+    distributionYes: distribution.distributionYes,
+    distributionNo: distribution.distributionNo,
+    diagnostics: diagnostics.concat(distribution.diagnostics || []),
+    mode: sourceYesPct === null ? 'default' : 'derived-from-source-yes-pct',
+  };
+}
+
+function deriveYesPctFromReserves(reserveYesUsdc, reserveNoUsdc) {
+  const yesReserve = toNumber(reserveYesUsdc);
+  const noReserve = toNumber(reserveNoUsdc);
+  if (yesReserve === null || noReserve === null) return null;
+  const total = yesReserve + noReserve;
+  if (!Number.isFinite(total) || total <= 0) return null;
+  return round((noReserve / total) * 100, 6);
+}
+
+function computeCompleteSetAllocation(options = {}) {
+  const liquidityRaw = toRawUsdc(options.liquidityUsdc);
+  if (liquidityRaw === null || liquidityRaw <= 0n) {
+    throw new Error('liquidityUsdc must be a positive number.');
+  }
+
+  const distributionYes = toNumber(options.distributionYes);
+  const distributionNo = toNumber(options.distributionNo);
+  if (!Number.isInteger(distributionYes) || !Number.isInteger(distributionNo)) {
+    throw new Error('distributionYes and distributionNo must be integers.');
+  }
+  if (distributionYes < 0 || distributionNo < 0 || distributionYes + distributionNo !== 1_000_000_000) {
+    throw new Error('distributionYes + distributionNo must equal 1000000000.');
+  }
+
+  const yesWeight = BigInt(distributionYes);
+  const noWeight = BigInt(distributionNo);
+
+  const mintedYesRaw = liquidityRaw;
+  const mintedNoRaw = liquidityRaw;
+
+  let reserveYesRaw;
+  let reserveNoRaw;
+  if (noWeight >= yesWeight) {
+    reserveYesRaw = liquidityRaw;
+    reserveNoRaw = noWeight === 0n ? 0n : (liquidityRaw * yesWeight) / noWeight;
+  } else {
+    reserveNoRaw = liquidityRaw;
+    reserveYesRaw = yesWeight === 0n ? 0n : (liquidityRaw * noWeight) / yesWeight;
+  }
+
+  const excessYesRaw = mintedYesRaw - reserveYesRaw;
+  const excessNoRaw = mintedNoRaw - reserveNoRaw;
+  const totalYesRaw = reserveYesRaw + excessYesRaw;
+  const totalNoRaw = reserveNoRaw + excessNoRaw;
+
+  return {
+    liquidityRaw,
+    mintedYesRaw,
+    mintedNoRaw,
+    reserveYesRaw,
+    reserveNoRaw,
+    excessYesRaw,
+    excessNoRaw,
+    totalYesRaw,
+    totalNoRaw,
+    impliedPoolYesPct: deriveYesPctFromReserves(rawUsdcToNumber(reserveYesRaw), rawUsdcToNumber(reserveNoRaw)),
+    liquidityUsdc: rawUsdcToNumber(liquidityRaw),
+    mintedYesUsdc: rawUsdcToNumber(mintedYesRaw),
+    mintedNoUsdc: rawUsdcToNumber(mintedNoRaw),
+    reserveYesUsdc: rawUsdcToNumber(reserveYesRaw),
+    reserveNoUsdc: rawUsdcToNumber(reserveNoRaw),
+    excessYesUsdc: rawUsdcToNumber(excessYesRaw),
+    excessNoUsdc: rawUsdcToNumber(excessNoRaw),
+    totalYesUsdc: rawUsdcToNumber(totalYesRaw),
+    totalNoUsdc: rawUsdcToNumber(totalNoRaw),
+    neutralCompleteSets: totalYesRaw === totalNoRaw,
+  };
+}
+
+function simulateDirectionalSwap(options = {}) {
+  const reserveYes = Math.max(0, toNumber(options.reserveYesUsdc) || 0);
+  const reserveNo = Math.max(0, toNumber(options.reserveNoUsdc) || 0);
+  const volumeUsdc = Math.max(0, toNumber(options.volumeUsdc) || 0);
+  const feeTier = Number.isFinite(Number(options.feeTier)) ? Number(options.feeTier) : 3000;
+  const feeRate = clamp(feeTier / 1_000_000, 0, 0.1);
+  const side = String(options.side || 'none').toLowerCase();
+
+  if (side !== 'yes' && side !== 'no') {
+    return {
+      side: 'none',
+      volumeUsdc: round(volumeUsdc, 6),
+      feeTier,
+      feeRate: round(feeRate, 8),
+      feesEarnedUsdc: 0,
+      outputShares: 0,
+      reserveYesUsdc: round(reserveYes, 6),
+      reserveNoUsdc: round(reserveNo, 6),
+      postYesPct: deriveYesPctFromReserves(reserveYes, reserveNo),
+    };
+  }
+
+  const effectiveIn = volumeUsdc * (1 - feeRate);
+  const feesEarnedUsdc = volumeUsdc - effectiveIn;
+
+  if (side === 'yes') {
+    const denominator = reserveNo + effectiveIn;
+    const outputYes = denominator > 0 ? (reserveYes * effectiveIn) / denominator : 0;
+    const postReserveYes = Math.max(0, reserveYes - outputYes);
+    const postReserveNo = reserveNo + volumeUsdc;
+    return {
+      side,
+      volumeUsdc: round(volumeUsdc, 6),
+      feeTier,
+      feeRate: round(feeRate, 8),
+      feesEarnedUsdc: round(feesEarnedUsdc, 6),
+      outputShares: round(outputYes, 6),
+      reserveYesUsdc: round(postReserveYes, 6),
+      reserveNoUsdc: round(postReserveNo, 6),
+      postYesPct: deriveYesPctFromReserves(postReserveYes, postReserveNo),
+    };
+  }
+
+  const denominator = reserveYes + effectiveIn;
+  const outputNo = denominator > 0 ? (reserveNo * effectiveIn) / denominator : 0;
+  const postReserveNo = Math.max(0, reserveNo - outputNo);
+  const postReserveYes = reserveYes + volumeUsdc;
+  return {
+    side,
+    volumeUsdc: round(volumeUsdc, 6),
+    feeTier,
+    feeRate: round(feeRate, 8),
+    feesEarnedUsdc: round(feesEarnedUsdc, 6),
+    outputShares: round(outputNo, 6),
+    reserveYesUsdc: round(postReserveYes, 6),
+    reserveNoUsdc: round(postReserveNo, 6),
+    postYesPct: deriveYesPctFromReserves(postReserveYes, postReserveNo),
+  };
+}
+
+function solveVolumeForTargetYesPct(options = {}) {
+  const targetYesPct = toPercent(options.targetYesPct);
+  const reserveYesUsdc = toNumber(options.reserveYesUsdc);
+  const reserveNoUsdc = toNumber(options.reserveNoUsdc);
+  const feeTier = Number.isFinite(Number(options.feeTier)) ? Number(options.feeTier) : 3000;
+
+  if (targetYesPct === null || reserveYesUsdc === null || reserveNoUsdc === null) {
+    return null;
+  }
+
+  const initialYesPct = deriveYesPctFromReserves(reserveYesUsdc, reserveNoUsdc);
+  if (initialYesPct === null) return null;
+  if (Math.abs(initialYesPct - targetYesPct) <= 0.01) return 0;
+
+  const side = targetYesPct > initialYesPct ? 'yes' : 'no';
+  const directionCheck = (yesPct) => (side === 'yes' ? yesPct >= targetYesPct : yesPct <= targetYesPct);
+  const f = (volumeUsdc) =>
+    simulateDirectionalSwap({
+      reserveYesUsdc,
+      reserveNoUsdc,
+      side,
+      volumeUsdc,
+      feeTier,
+    }).postYesPct;
+
+  let lo = 0;
+  let hi = Math.max(1, reserveYesUsdc + reserveNoUsdc);
+  let yesAtHi = f(hi);
+  let iterations = 0;
+  while (!directionCheck(yesAtHi) && iterations < 32) {
+    hi *= 2;
+    yesAtHi = f(hi);
+    iterations += 1;
+  }
+
+  if (!directionCheck(yesAtHi)) {
+    return null;
+  }
+
+  for (let i = 0; i < 56; i += 1) {
+    const mid = (lo + hi) / 2;
+    const yesAtMid = f(mid);
+    if (directionCheck(yesAtMid)) {
+      hi = mid;
+    } else {
+      lo = mid;
+    }
+  }
+
+  return round(hi, 6);
+}
+
+function normalizeVolumeScenarios(value, liquidityUsdc) {
+  if (Array.isArray(value)) {
+    return value.map((item) => toNumber(item)).filter((item) => Number.isFinite(item) && item >= 0).map((item) => round(item, 6));
+  }
+
+  const raw = String(value || '').trim();
+  if (raw) {
+    return raw
+      .split(',')
+      .map((entry) => toNumber(entry.trim()))
+      .filter((entry) => Number.isFinite(entry) && entry >= 0)
+      .map((entry) => round(entry, 6));
+  }
+
+  const liq = Math.max(1, toNumber(liquidityUsdc) || 0);
+  return [
+    round(liq * 0.25, 6),
+    round(liq * 0.5, 6),
+    round(liq, 6),
+    round(liq * 2, 6),
+  ];
+}
+
+function computeHedgeMetrics(options = {}) {
+  const reserveYesUsdc = toNumber(options.reserveYesUsdc) || 0;
+  const reserveNoUsdc = toNumber(options.reserveNoUsdc) || 0;
+  const excessYesUsdc = toNumber(options.excessYesUsdc) || 0;
+  const excessNoUsdc = toNumber(options.excessNoUsdc) || 0;
+  const hedgeRatio = clamp(toNumber(options.hedgeRatio) || 1, 0, 5);
+  const polymarketYesPct = toPercent(options.polymarketYesPct);
+  const hedgeCostBps = Math.max(0, toNumber(options.hedgeCostBps) || 35);
+  const feeTier = Number.isFinite(Number(options.feeTier)) ? Number(options.feeTier) : 3000;
+  const feeRate = clamp(feeTier / 1_000_000, 0, 0.1);
+
+  const deltaPoolUsdc = reserveYesUsdc - reserveNoUsdc;
+  const deltaTotalUsdc = (reserveYesUsdc + excessYesUsdc) - (reserveNoUsdc + excessNoUsdc);
+  const targetHedgeUsdcSigned = -deltaTotalUsdc * hedgeRatio;
+  const targetHedgeUsdcAbs = Math.abs(targetHedgeUsdcSigned);
+  const hedgeToken = targetHedgeUsdcSigned > 0 ? 'yes' : targetHedgeUsdcSigned < 0 ? 'no' : null;
+
+  const yesPrice01 = polymarketYesPct === null ? null : clamp(polymarketYesPct / 100, 0.0001, 0.9999);
+  const noPrice01 = yesPrice01 === null ? null : 1 - yesPrice01;
+  const hedgePrice01 = hedgeToken === 'yes' ? yesPrice01 : hedgeToken === 'no' ? noPrice01 : null;
+  const hedgeSharesApprox = hedgePrice01 ? round(targetHedgeUsdcAbs / hedgePrice01, 6) : null;
+
+  const hedgeCostApproxUsdc = round(targetHedgeUsdcAbs * (hedgeCostBps / 10_000), 6) || 0;
+  const breakEvenVolumeUsdc = feeRate > 0 ? round(hedgeCostApproxUsdc / feeRate, 6) : null;
+
+  return {
+    reserveYesUsdc: round(reserveYesUsdc, 6),
+    reserveNoUsdc: round(reserveNoUsdc, 6),
+    excessYesUsdc: round(excessYesUsdc, 6),
+    excessNoUsdc: round(excessNoUsdc, 6),
+    deltaPoolUsdc: round(deltaPoolUsdc, 6),
+    deltaTotalUsdc: round(deltaTotalUsdc, 6),
+    hedgeRatio: round(hedgeRatio, 6),
+    targetHedgeUsdcSigned: round(targetHedgeUsdcSigned, 6),
+    targetHedgeUsdcAbs: round(targetHedgeUsdcAbs, 6),
+    hedgeToken,
+    polymarketYesPct,
+    polymarketNoPct: polymarketYesPct === null ? null : round(100 - polymarketYesPct, 6),
+    hedgePrice01: hedgePrice01 === null ? null : round(hedgePrice01, 8),
+    hedgeSharesApprox,
+    hedgeCostBps: round(hedgeCostBps, 6),
+    hedgeCostApproxUsdc,
+    feeTier,
+    feeRate: round(feeRate, 8),
+    breakEvenVolumeUsdc,
+  };
+}
+
+function buildMirrorLpExplain(options = {}) {
+  const distribution = resolveDistribution(options);
+  const allocation = computeCompleteSetAllocation({
+    liquidityUsdc: options.liquidityUsdc,
+    distributionYes: distribution.distributionYes,
+    distributionNo: distribution.distributionNo,
+  });
+
+  const diagnostics = [];
+  diagnostics.push(...distribution.diagnostics);
+  diagnostics.push(
+    'addLiquidity mints complete sets first, seeds reserves by distribution hint, then returns excess YES/NO tokens to the LP wallet.',
+  );
+
+  return {
+    schemaVersion: MIRROR_LP_EXPLAIN_SCHEMA_VERSION,
+    generatedAt: new Date().toISOString(),
+    inputs: {
+      liquidityUsdc: allocation.liquidityUsdc,
+      sourceYesPct: distribution.sourceYesPct,
+      distributionYes: distribution.distributionYes,
+      distributionNo: distribution.distributionNo,
+      distributionMode: distribution.mode,
+    },
+    flow: {
+      mintedCompleteSets: {
+        yesTokens: allocation.mintedYesUsdc,
+        noTokens: allocation.mintedNoUsdc,
+      },
+      seededPoolReserves: {
+        reserveYesUsdc: allocation.reserveYesUsdc,
+        reserveNoUsdc: allocation.reserveNoUsdc,
+        impliedPandoraYesPct: allocation.impliedPoolYesPct,
+      },
+      returnedExcessTokens: {
+        excessYesUsdc: allocation.excessYesUsdc,
+        excessNoUsdc: allocation.excessNoUsdc,
+      },
+      totalLpInventory: {
+        totalYesUsdc: allocation.totalYesUsdc,
+        totalNoUsdc: allocation.totalNoUsdc,
+        deltaUsdc: round((allocation.totalYesUsdc || 0) - (allocation.totalNoUsdc || 0), 6),
+        neutralCompleteSets: allocation.neutralCompleteSets,
+      },
+    },
+    raw: {
+      liquidityRaw: allocation.liquidityRaw.toString(),
+      reserveYesRaw: allocation.reserveYesRaw.toString(),
+      reserveNoRaw: allocation.reserveNoRaw.toString(),
+      excessYesRaw: allocation.excessYesRaw.toString(),
+      excessNoRaw: allocation.excessNoRaw.toString(),
+    },
+    diagnostics,
+  };
+}
+
+function buildMirrorHedgeCalc(options = {}) {
+  const scenarios = normalizeVolumeScenarios(options.volumeScenarios, options.reserveYesUsdc + options.reserveNoUsdc);
+  const metrics = computeHedgeMetrics(options);
+
+  const scenarioRows = scenarios.map((volumeUsdc) => {
+    const fees = round(volumeUsdc * (metrics.feeRate || 0), 6) || 0;
+    return {
+      volumeUsdc,
+      feeRevenueUsdc: fees,
+      hedgeCostApproxUsdc: metrics.hedgeCostApproxUsdc,
+      netPnlApproxUsdc: round(fees - (metrics.hedgeCostApproxUsdc || 0), 6),
+    };
+  });
+
+  return {
+    schemaVersion: MIRROR_HEDGE_CALC_SCHEMA_VERSION,
+    generatedAt: new Date().toISOString(),
+    metrics,
+    scenarios: scenarioRows,
+    diagnostics: [
+      'Hedge sizing is notional-based and assumes FAK fills near the provided Polymarket mark price.',
+      'P&L rows are approximation: LP fee accrual minus estimated hedge execution cost.',
+    ],
+  };
+}
+
+function buildMirrorSimulate(options = {}) {
+  const distribution = resolveDistribution(options);
+  const allocation = computeCompleteSetAllocation({
+    liquidityUsdc: options.liquidityUsdc,
+    distributionYes: distribution.distributionYes,
+    distributionNo: distribution.distributionNo,
+  });
+
+  const targetYesPct = toPercent(options.targetYesPct !== undefined ? options.targetYesPct : distribution.sourceYesPct);
+  const initialYesPct = allocation.impliedPoolYesPct;
+  const tradeSide =
+    targetYesPct === null || initialYesPct === null
+      ? 'none'
+      : targetYesPct > initialYesPct
+        ? 'yes'
+        : targetYesPct < initialYesPct
+          ? 'no'
+          : 'none';
+
+  const feeTier = Number.isFinite(Number(options.feeTier)) ? Number(options.feeTier) : 3000;
+  const hedgeRatio = clamp(toNumber(options.hedgeRatio) || 1, 0, 5);
+  const hedgeCostBps = Math.max(0, toNumber(options.hedgeCostBps) || 35);
+  const polymarketYesPct = toPercent(
+    options.polymarketYesPct !== undefined ? options.polymarketYesPct : (targetYesPct !== null ? targetYesPct : 50),
+  );
+
+  const volumeScenarios = normalizeVolumeScenarios(options.volumeScenarios, allocation.liquidityUsdc);
+  const volumeNeededToTargetUsdc =
+    targetYesPct === null
+      ? null
+      : solveVolumeForTargetYesPct({
+          targetYesPct,
+          reserveYesUsdc: allocation.reserveYesUsdc,
+          reserveNoUsdc: allocation.reserveNoUsdc,
+          feeTier,
+        });
+
+  const scenarioResults = volumeScenarios.map((volumeUsdc) => {
+    const swap = simulateDirectionalSwap({
+      reserveYesUsdc: allocation.reserveYesUsdc,
+      reserveNoUsdc: allocation.reserveNoUsdc,
+      side: tradeSide,
+      volumeUsdc,
+      feeTier,
+    });
+
+    const hedge = computeHedgeMetrics({
+      reserveYesUsdc: swap.reserveYesUsdc,
+      reserveNoUsdc: swap.reserveNoUsdc,
+      excessYesUsdc: allocation.excessYesUsdc,
+      excessNoUsdc: allocation.excessNoUsdc,
+      hedgeRatio,
+      polymarketYesPct,
+      hedgeCostBps,
+      feeTier,
+    });
+
+    const netPnlApproxUsdc = round((swap.feesEarnedUsdc || 0) - (hedge.hedgeCostApproxUsdc || 0), 6);
+
+    return {
+      volumeUsdc: round(volumeUsdc, 6),
+      tradeSide,
+      feesEarnedUsdc: swap.feesEarnedUsdc,
+      postReserveYesUsdc: swap.reserveYesUsdc,
+      postReserveNoUsdc: swap.reserveNoUsdc,
+      postYesPct: swap.postYesPct,
+      driftToTargetBps:
+        targetYesPct === null || swap.postYesPct === null
+          ? null
+          : round(Math.abs(targetYesPct - swap.postYesPct) * 100, 6),
+      hedge: {
+        targetHedgeUsdc: hedge.targetHedgeUsdcSigned,
+        hedgeToken: hedge.hedgeToken,
+        hedgeSharesApprox: hedge.hedgeSharesApprox,
+        hedgeCostApproxUsdc: hedge.hedgeCostApproxUsdc,
+      },
+      netPnlApproxUsdc,
+    };
+  });
+
+  return {
+    schemaVersion: MIRROR_SIMULATE_SCHEMA_VERSION,
+    generatedAt: new Date().toISOString(),
+    inputs: {
+      liquidityUsdc: allocation.liquidityUsdc,
+      feeTier,
+      hedgeRatio,
+      hedgeCostBps,
+      sourceYesPct: distribution.sourceYesPct,
+      targetYesPct,
+      polymarketYesPct,
+      distributionYes: distribution.distributionYes,
+      distributionNo: distribution.distributionNo,
+      distributionMode: distribution.mode,
+      tradeSide,
+      volumeScenarios,
+    },
+    initialState: {
+      reserveYesUsdc: allocation.reserveYesUsdc,
+      reserveNoUsdc: allocation.reserveNoUsdc,
+      excessYesUsdc: allocation.excessYesUsdc,
+      excessNoUsdc: allocation.excessNoUsdc,
+      initialYesPct,
+      neutralCompleteSets: allocation.neutralCompleteSets,
+    },
+    targeting: {
+      volumeNeededToTargetUsdc,
+      targetReachable: volumeNeededToTargetUsdc !== null,
+    },
+    scenarios: scenarioResults,
+    diagnostics: [
+      'Complete-set mint/split step is exact (raw integer math).',
+      'Trade path models a CPMM-style directional flow with fees retained in reserves.',
+      'Use mirror sync + live orderbooks for execution-grade sizing; this command is planning-grade simulation.',
+    ].concat(distribution.diagnostics || []),
+  };
+}
+
+module.exports = {
+  MIRROR_LP_EXPLAIN_SCHEMA_VERSION,
+  MIRROR_HEDGE_CALC_SCHEMA_VERSION,
+  MIRROR_SIMULATE_SCHEMA_VERSION,
+  resolveDistribution,
+  computeCompleteSetAllocation,
+  simulateDirectionalSwap,
+  solveVolumeForTargetYesPct,
+  computeHedgeMetrics,
+  buildMirrorLpExplain,
+  buildMirrorHedgeCalc,
+  buildMirrorSimulate,
+};

package/cli/lib/mirror_verify_service.cjs

@@ -3,8 +3,10 @@ const { createIndexerClient } = require('./indexer_client.cjs');
 const { resolvePolymarketMarket } = require('./polymarket_trade_adapter.cjs');
 
 const MIRROR_VERIFY_SCHEMA_VERSION = '1.0.0';
+const USDC_DECIMALS = 6;
 
 function toNumber(value) {
+  if (value === null || value === undefined || value === '') return null;
   const numeric = Number(value);
   if (!Number.isFinite(numeric)) return null;
   return numeric;
@@ -16,6 +18,12 @@ function round(value, decimals = 6) {
   return Math.round(value * factor) / factor;
 }
 
+function normalizeUsdcRawToUsd(value) {
+  const numeric = toNumber(value);
+  if (numeric === null) return null;
+  return round(numeric / (10 ** USDC_DECIMALS), 6);
+}
+
 function normalizeQuestion(question) {
   return String(question || '')
     .toLowerCase()
@@ -125,8 +133,8 @@ function derivePandoraYesPct(market) {
     return round(yesFromChance * 100, 6);
   }
 
-  const reserveYes = toNumber(market && market.reserveYes);
-  const reserveNo = toNumber(market && market.reserveNo);
+  const reserveYes = normalizeUsdcRawToUsd(market && market.reserveYes);
+  const reserveNo = normalizeUsdcRawToUsd(market && market.reserveNo);
   if (reserveYes === null || reserveNo === null) return null;
 
   const total = reserveYes + reserveNo;
@@ -251,8 +259,8 @@ async function fetchPandoraMarketContext(options = {}) {
     closeTimestamp: toNumber(market.marketCloseTimestamp) || toNumber(poll && poll.deadlineEpoch),
     yesPct,
     noPct,
-    reserveYes: toNumber(market.reserveYes),
-    reserveNo: toNumber(market.reserveNo),
+    reserveYes: normalizeUsdcRawToUsd(market.reserveYes),
+    reserveNo: normalizeUsdcRawToUsd(market.reserveNo),
     totalVolumeUsd: toNumber(market.totalVolume),
     tvlUsd: toNumber(market.currentTvl),
     diagnostics,

package/cli/lib/polymarket_trade_adapter.cjs

@@ -15,6 +15,7 @@ const tradingClientCache = new Map();
 const derivedCredsCache = new Map();
 
 function toNumber(value) {
+  if (value === null || value === undefined || value === '') return null;
   const numeric = Number(value);
   if (!Number.isFinite(numeric)) return null;
   return numeric;
@@ -751,7 +752,15 @@ function calculateExecutableDepthUsd(orderbook, side, slippageBps) {
 
   const limitPriceFactor = slippageBps / 10_000;
   const entries = side === 'buy' ? normalized.asks : normalized.bids;
-  const priceLimit = side === 'buy' ? mid * (1 + limitPriceFactor) : mid * (1 - limitPriceFactor);
+  const bestBid = normalized.bids.length ? normalized.bids[0].price : null;
+  const bestAsk = normalized.asks.length ? normalized.asks[0].price : null;
+  const referencePrice =
+    side === 'buy'
+      ? (bestAsk !== null ? bestAsk : mid)
+      : (bestBid !== null ? bestBid : mid);
+  const priceLimit = side === 'buy'
+    ? referencePrice * (1 + limitPriceFactor)
+    : referencePrice * (1 - limitPriceFactor);
 
   let depthUsd = 0;
   let depthShares = 0;
@@ -770,6 +779,7 @@ function calculateExecutableDepthUsd(orderbook, side, slippageBps) {
     depthShares: round(depthShares, 6) || 0,
     worstPrice: worstPrice === null ? null : round(worstPrice, 8),
     midPrice: round(mid, 8),
+    referencePrice: round(referencePrice, 8),
     diagnostics: [],
   };
 }
@@ -852,7 +862,9 @@ async function fetchDepthForMarket(market, options = {}) {
   const candidates = [yesDepth && yesDepth.depthUsd, noDepth && noDepth.depthUsd].filter((value) => Number.isFinite(value));
   const minDepthWithinSlippageUsd = candidates.length ? Math.min(...candidates) : 0;
   const bestDepthWithinSlippageUsd = candidates.length ? Math.max(...candidates) : 0;
-  const depthWithinSlippageUsd = bestDepthWithinSlippageUsd;
+  // Keep the legacy/conservative aggregate as min depth (used by sizing paths),
+  // while exposing best-depth separately for hedge-side diagnostics.
+  const depthWithinSlippageUsd = minDepthWithinSlippageUsd;
 
   if (!yesDepth) diagnostics.push('YES token orderbook unavailable.');
   if (!noDepth) diagnostics.push('NO token orderbook unavailable.');