Merge pull request #33 from reclaimprotocol/feat/x402-admin-analytics

feat: surface x402 payment analytics in admin UI

Author: kryptocodes

services/control-plane/index.ts

@@ -53,6 +53,8 @@ import {
   type ActionNotice,
   type AdminRegion,
   type AnalyticsData,
+  type AnalyticsScope,
+  type X402AnalyticsData,
 } from './src/admin-ui';
 
 const app = new Hono();
@@ -722,6 +724,22 @@ function bucketsForWindow(windowHours: number): number {
 
 // Combines live Agones gauges (via pool managers) with cumulative Postgres
 // session stats into a single payload shared by the API and the admin UI.
+// USDC and the other supported x402 settlement assets use 6 decimals; the
+// client flow assumes the same. The atomic ledger stays the source of truth.
+const X402_ASSET_DECIMALS = 6;
+
+async function buildX402AnalyticsPayload(windowHours: number): Promise<X402AnalyticsData | undefined> {
+  if (!ControlPlaneConfig.x402.enabled) return undefined;
+  const analytics = await getX402Analytics(windowHours, ControlPlaneConfig.x402.blockSeconds);
+  return {
+    ...analytics,
+    assetName: ControlPlaneConfig.x402.paymentAssetName,
+    assetDecimals: X402_ASSET_DECIMALS,
+    network: ControlPlaneConfig.x402.network,
+    testnet: ControlPlaneConfig.x402.network === 'eip155:84532',
+  };
+}
+
 async function buildStatsPayload(windowHours: number): Promise<AnalyticsData> {
   const [regions, windowStats, allocationStats, activeSessions, staleActiveSessions, series, regionSessions, topClients] = await Promise.all([
     loadAdminRegions(),
@@ -1210,8 +1228,12 @@ app.get('/admin/ui/clusters', async (c) => {
 
 app.get('/admin/ui/analytics', async (c) => {
   const windowHours = normalizeWindowHours(c.req.query('windowHours') ?? undefined);
-  const data = await buildStatsPayload(windowHours);
-  return c.html(await renderAnalyticsViewHtml({ data }));
+  const scope: AnalyticsScope = c.req.query('scope') === 'x402' ? 'x402' : 'fleet';
+  const [data, x402] = await Promise.all([
+    buildStatsPayload(windowHours),
+    buildX402AnalyticsPayload(windowHours),
+  ]);
+  return c.html(await renderAnalyticsViewHtml({ data, x402, scope }));
 });
 
 app.post('/admin/ui/sessions', async (c) => {

services/control-plane/public/admin.css

@@ -459,6 +459,14 @@ small, .muted { color: var(--text-soft); }
 .an-controls { align-items: center; display: flex; gap: .55rem; }
 .an-range { min-width: 150px; width: auto; }
 .an-refresh { background: var(--surface-raised); border-color: var(--line); color: var(--text); }
+.an-scope { align-items: center; background: var(--surface); border: 1px solid var(--line); border-radius: 9px; box-shadow: inset 0 1px 2px rgba(0,0,0,.22); display: inline-flex; gap: 2px; padding: 3px; }
+.an-scope-btn { align-items: center; background: transparent; border: 0; border-radius: 6px; color: var(--text-soft); cursor: pointer; display: inline-flex; font-size: .8rem; font-weight: 600; gap: .42rem; line-height: 1.2; padding: .4rem .8rem; transition: background .14s ease, color .14s ease, box-shadow .14s ease; }
+.an-scope-btn:hover:not(.active) { background: rgba(255,255,255,.045); color: var(--text); }
+.an-scope-btn.active { background: var(--surface-raised); box-shadow: 0 1px 2px rgba(0,0,0,.3), 0 0 0 1px var(--line-strong); color: var(--text); }
+.an-scope-dot { border-radius: 50%; flex: none; height: 7px; opacity: .45; transition: opacity .14s ease; width: 7px; }
+.an-scope-btn.active .an-scope-dot { opacity: 1; }
+.an-scope-dot.fleet { background: var(--blue); }
+.an-scope-dot.x402 { background: #35c680; }
 .an-sublabel { color: var(--text-faint); font-size: .68rem; font-weight: 800; letter-spacing: .1em; margin: 1.4rem 0 .65rem; text-transform: uppercase; }
 .an-sublabel:first-of-type { margin-top: 0; }
 .an-kpis { display: grid; gap: .7rem; grid-template-columns: repeat(auto-fit, minmax(145px, 1fr)); }
@@ -617,6 +625,8 @@ small, .muted { color: var(--text-soft); }
   .inventory-count { align-items: center; display: flex; justify-content: center; }
   .pod-inventory-scroll { max-height: none; }
   .an-controls { align-items: stretch; flex-direction: column; width: 100%; }.an-range { width: 100%; }
+  .an-scope { width: 100%; }
+  .an-scope-btn { flex: 1 1 0; justify-content: center; }
   .ops-table, .ops-table tbody { display: block; min-width: 0; }
   .ops-table thead { display: none; }
   .ops-table tbody tr { background: var(--surface-soft); border: 1px solid var(--line); border-radius: var(--radius-sm); display: block; margin: .65rem; padding: .7rem .8rem; }

services/control-plane/src/admin-ui.tsx

@@ -94,6 +94,30 @@ export interface AnalyticsData {
   series: AnalyticsSeriesPoint[];
 }
 
+export type AnalyticsScope = 'fleet' | 'x402';
+
+export interface X402OperationStat {
+  operation: string;
+  payments: number;
+  revenueAtomic: string;
+  paidSeconds: number;
+}
+
+export interface X402AnalyticsData {
+  windowHours: number;
+  liveSessions: number;
+  revenueAtomic: string;
+  settledPayments: number;
+  uniquePayers: number;
+  paidSeconds: number;
+  operations: X402OperationStat[];
+  events: Record<string, number>;
+  assetName: string;
+  assetDecimals: number;
+  network: string;
+  testnet: boolean;
+}
+
 export interface ClientSecretNotice {
   clientId: string;
   clientSecret: string;
@@ -1451,26 +1475,58 @@ const ANALYTICS_STYLE = `
 .bar-fill.green { background: linear-gradient(90deg, #17915a, #35c680); }
 `;
 
-export function AnalyticsView({ data }: { data: AnalyticsData }) {
+function AnalyticsScopeToggle({ scope, windowHours }: { scope: AnalyticsScope; windowHours: number }) {
+  const options: { value: AnalyticsScope; label: string }[] = [
+    { value: 'fleet', label: 'Fleet' },
+    { value: 'x402', label: 'x402' },
+  ];
+  return (
+    <div class="an-scope" role="tablist" aria-label="Analytics scope">
+      {options.map((option) => (
+        <button
+          type="button"
+          role="tab"
+          class={`an-scope-btn${option.value === scope ? ' active' : ''}`}
+          aria-selected={option.value === scope ? 'true' : 'false'}
+          hx-get={`/admin/ui/analytics?scope=${option.value}&windowHours=${windowHours}`}
+          hx-target="#admin-content"
+          hx-swap="innerHTML"
+        >
+          <span class={`an-scope-dot ${option.value}`} aria-hidden="true"></span>
+          <span>{option.label}</span>
+        </button>
+      ))}
+    </div>
+  );
+}
+
+export function AnalyticsView({ data, x402, scope = 'fleet' }: { data: AnalyticsData; x402?: X402AnalyticsData; scope?: AnalyticsScope }) {
   const { live, window, series } = data;
   const utilization = percent(live.allocated, live.capacity);
   const free = Math.max(0, live.capacity - live.allocated - live.ready);
   const hasActivity = series.some((p) => p.ended > 0 || p.created > 0);
+  // The toggle only exists when x402 is enabled; otherwise always show fleet.
+  const activeScope: AnalyticsScope = x402 && scope === 'x402' ? 'x402' : 'fleet';
 
   return (
     <div class="workspace analytics-workspace">
       <header class="page-header an-topbar">
         <div class="an-title">
           <span class="eyebrow">Performance</span>
           <h1>Analytics</h1>
-          <p>Fleet allocation and session lifecycle across the {windowLabel(data.windowHours)}.</p>
+          <p>
+            {activeScope === 'x402'
+              ? `Paid x402 sessions across the ${windowLabel(data.windowHours)}.`
+              : `Fleet allocation and session lifecycle across the ${windowLabel(data.windowHours)}.`}
+          </p>
         </div>
         <div class="an-controls">
+          {x402 ? <AnalyticsScopeToggle scope={activeScope} windowHours={data.windowHours} /> : null}
           <select
             class="an-range"
             name="windowHours"
             aria-label="Time range"
-            hx-get="/admin/ui/analytics"
+            hx-get={`/admin/ui/analytics?scope=${activeScope}`}
             hx-target="#admin-content"
             hx-swap="innerHTML"
             hx-trigger="change"
@@ -1482,7 +1538,7 @@ export function AnalyticsView({ data }: { data: AnalyticsData }) {
           <button
             type="button"
             class="an-refresh"
-            hx-get={`/admin/ui/analytics?windowHours=${data.windowHours}`}
+            hx-get={`/admin/ui/analytics?windowHours=${data.windowHours}&scope=${activeScope}`}
             hx-target="#admin-content"
             hx-swap="innerHTML"
           >
@@ -1491,6 +1547,8 @@ export function AnalyticsView({ data }: { data: AnalyticsData }) {
         </div>
       </header>
 
+      {activeScope === 'x402' && x402 ? <X402Section x402={x402} /> : (
+      <>
       <div class="an-sublabel">Live fleet</div>
       <div class="an-kpis">
         <AnKpi label="Allocated" value={String(live.allocated)} hint={`of ${live.capacity} · ${utilization}%`} tone="accent" />
@@ -1569,10 +1627,117 @@ export function AnalyticsView({ data }: { data: AnalyticsData }) {
           </div>
         </div>
       )}
+      </>
+      )}
     </div>
   );
 }
 
+// USDC and most x402 settlement assets use 6 decimals; the client flow assumes
+// the same. Format the atomic ledger amount into a human token value.
+function formatAtomicAmount(atomic: string, decimals: number) {
+  const digits = String(atomic || '0').replace(/[^0-9]/g, '') || '0';
+  if (decimals <= 0) return digits;
+  const padded = digits.padStart(decimals + 1, '0');
+  const whole = padded.slice(0, padded.length - decimals);
+  const fraction = padded.slice(padded.length - decimals).replace(/0+$/, '');
+  return fraction ? `${whole}.${fraction}` : whole;
+}
+
+function x402EventLabel(eventType: string) {
+  return eventType
+    .replace(/^x402\./, '')
+    .replace(/_/g, ' ')
+    .replace(/^\w/, (ch) => ch.toUpperCase());
+}
+
+function X402Section({ x402 }: { x402: X402AnalyticsData }) {
+  const revenue = formatAtomicAmount(x402.revenueAtomic, x402.assetDecimals);
+  const events = Object.entries(x402.events).sort((a, b) => b[1] - a[1]);
+  const created = x402.events['x402.session_created'] || 0;
+  const challenges = x402.events['x402.challenge_issued'] || 0;
+  const conversion = challenges > 0 ? Math.round((created / challenges) * 100) : 0;
+
+  return (
+    <>
+      <div class="an-sublabel">
+        x402 paid sessions · {windowLabel(x402.windowHours)}
+        {x402.testnet ? ' · testnet' : ''} · {x402.network}
+      </div>
+      <div class="an-kpis">
+        <AnKpi
+          label="Live sessions"
+          value={String(x402.liveSessions)}
+          hint="paid access active now"
+          tone={x402.liveSessions > 0 ? 'success' : undefined}
+        />
+        <AnKpi
+          label="Revenue"
+          value={`${revenue} ${x402.assetName}`}
+          hint={`${x402.settledPayments} settled payment${x402.settledPayments === 1 ? '' : 's'}`}
+          tone="accent"
+        />
+        <AnKpi label="Unique payers" value={String(x402.uniquePayers)} hint="distinct wallets" />
+        <AnKpi label="Paid time sold" value={formatDuration(x402.paidSeconds)} />
+        <AnKpi
+          label="Challenge → session"
+          value={challenges > 0 ? `${conversion}%` : '—'}
+          hint={challenges > 0 ? `${created} of ${challenges} challenges` : 'No challenges issued'}
+          tone={challenges > 0 && conversion >= 50 ? 'success' : undefined}
+        />
+      </div>
+
+      <div class="an-charts">
+        <div class="an-card">
+          <div class="an-card-head"><h3>Revenue by operation</h3><span class="an-card-sub">create vs extend</span></div>
+          {x402.operations.length ? (
+            <div class="bar-list">
+              {x402.operations.map((op) => (
+                <div class="bar-row">
+                  <div class="bar-row-head">
+                    <span class="bar-row-label">{op.operation}</span>
+                    <span class="bar-row-value">
+                      {formatAtomicAmount(op.revenueAtomic, x402.assetDecimals)} {x402.assetName} · {op.payments} payment{op.payments === 1 ? '' : 's'} · {formatDuration(op.paidSeconds)}
+                    </span>
+                  </div>
+                  <div class="bar-track">
+                    <div
+                      class="bar-fill blue"
+                      style={`width:${percent(op.payments, x402.settledPayments)}%`}
+                    ></div>
+                  </div>
+                </div>
+              ))}
+            </div>
+          ) : (
+            <div class="viz-empty">No settled payments in this range.</div>
+          )}
+        </div>
+        <div class="an-card">
+          <div class="an-card-head"><h3>Lifecycle events</h3><span class="an-card-sub">count by type</span></div>
+          {events.length ? (
+            <div class="bar-list">
+              {events.map(([type, count]) => (
+                <div class="bar-row">
+                  <div class="bar-row-head">
+                    <span class="bar-row-label">{x402EventLabel(type)}</span>
+                    <span class="bar-row-value">{count}</span>
+                  </div>
+                  <div class="bar-track">
+                    <div class="bar-fill blue" style={`width:${percent(count, events[0][1])}%`}></div>
+                  </div>
+                </div>
+              ))}
+            </div>
+          ) : (
+            <div class="viz-empty">No x402 events in this range.</div>
+          )}
+        </div>
+      </div>
+    </>
+  );
+}
+
 function SelectedRegionCard({ region, selectedRegion, totals }: {
   region: AdminRegion | null;
   selectedRegion: string;

services/control-plane/src/x402-analytics.ts

@@ -3,7 +3,7 @@ import { db } from './db';
 
 export async function getX402Analytics(windowHours = 24, blockSeconds = 300) {
   const safeWindowHours = Math.max(1, Math.min(720, Math.floor(windowHours)));
-  const [totals, operations, events] = await Promise.all([
+  const [totals, operations, events, live] = await Promise.all([
     db.execute(sql`
       select
         count(*)::int as settled_payments,
@@ -31,10 +31,22 @@ export async function getX402Analytics(windowHours = 24, blockSeconds = 300) {
       group by event_type
       order by event_type
     `),
+    // Live now, not window-scoped: paid access still valid and the underlying
+    // browser session is still active (excludes expired and terminated ones).
+    db.execute(sql`
+      select count(*)::int as live_sessions
+      from x402_sessions x
+      join sessions s on s.session_id = x.session_id
+      where x.expires_at > now()
+        and s.status = 'active'
+        and s.ended_at is null
+    `),
   ]);
   const row = totals[0] as Record<string, unknown> | undefined;
+  const liveRow = live[0] as Record<string, unknown> | undefined;
   return {
     windowHours: safeWindowHours,
+    liveSessions: Number(liveRow?.live_sessions || 0),
     // Revenue is deliberately sourced only from status='settled' ledger rows.
     revenueAtomic: String(row?.revenue_atomic || '0'),
     settledPayments: Number(row?.settled_payments || 0),