feat(api): §26's creator reputation figures

Launches, graduations, lifetime volume, trades, holders, and a graduation
rate. §26 calls this "a reputation layer that is market-driven without
requiring a privileged creator allocation" — so every figure is derived from
what the chain did, and there is deliberately no field here an operator
could write.

THE RATE IS PER MILLE, NOT A FLOAT
2 of 3 as a float is 0.6666666666666666, which every consumer then decides
how to round — differently, so two screens disagree about the same creator.
§424 keeps financial quantities out of JS floating point; a ratio that gets
rendered next to them belongs on the same side of that line.

Zero for a creator with no launches, not a division by zero and not "100%".
A creator who has launched nothing has not graduated nothing successfully,
and either reading is a claim about a record that does not exist.

`totalHolders` sums per-market holder counts, so a wallet holding three of a
creator's tokens counts three times. That is deliberate — it measures reach
across markets, not distinct people — and the field says holders, not people.

Author: Sent-lab

docs/API.md

@@ -228,6 +228,13 @@ money already in their wallet, and the claim would revert with `NothingToClaim`
 after they paid gas to find out. Without `claims` a creator sees "earned 4.2,
 claimable 0" and cannot tell a past withdrawal from a failure.
 
+`stats` is §26's reputation layer: launches, graduations, lifetime volume,
+trades, holders, and a graduation rate **per mille**. Every figure is derived
+from what the chain did and none of it can be granted, bought or set — which is
+the section's whole point, and also why there is no field here an operator could
+write. The rate is an integer per mille rather than a float because 2 of 3 as a
+float is `0.6666666666666666`, which every consumer then rounds differently.
+
 `feeVault` is returned so the claim a creator signs targets the same contract
 the balance came from. A client holding its own vault address could show one
 contract's balance over a button that calls another.

packages/database/src/repository.ts

@@ -2167,6 +2167,70 @@ export async function listXStockAssets(db: Db, onlyLaunchable = false): Promise<
   }));
 }
 
+export interface CreatorStats {
+  readonly launches: number;
+  readonly graduated: number;
+  /** Lifetime notional across every market they launched, normalized. */
+  readonly totalVolume: bigint;
+  readonly totalTrades: number;
+  readonly totalHolders: number;
+  /**
+   * Graduated launches per thousand launches.
+   *
+   * Per mille rather than a float: §424 keeps financial and ratio quantities
+   * out of JS floating point, and a rate that arrives as 0.6666666666666666 is
+   * a number every consumer has to decide how to round, differently.
+   */
+  readonly graduationRatePerMille: number;
+}
+
+/**
+ * §26's creator reputation figures.
+ *
+ * "Market-driven reputation without a privileged creator allocation" — every
+ * number here is derived from what the chain did, and none of it can be
+ * granted, bought or set. That is the whole point of the section: a creator's
+ * standing comes from their launches performing, not from a badge.
+ *
+ * `totalHolders` sums the per-market holder counts, so a wallet holding three
+ * of a creator's tokens counts three times. That is deliberate — it measures
+ * reach across markets rather than distinct people, and deduplicating it would
+ * need a scan of every balance row for a figure nobody would read differently.
+ * The name says holders, not people.
+ */
+export async function creatorStats(db: Db, creator: string): Promise<CreatorStats> {
+  const row = await db.queryOne<Record<string, unknown>>(
+    `SELECT
+       COUNT(*)::TEXT                                                   AS launches,
+       COUNT(*) FILTER (WHERE s.graduated_at_block IS NOT NULL)::TEXT   AS graduated,
+       COALESCE(SUM(s.holder_count), 0)::TEXT                           AS holders,
+       COALESCE(SUM(s.trade_count), 0)::TEXT                            AS trades,
+       COALESCE((
+         SELECT SUM(t.notional) FROM trades t
+         WHERE t.market IN (SELECT market FROM markets WHERE creator = $1)
+       ), 0)::TEXT                                                      AS volume
+     FROM markets m JOIN market_state s ON s.market = m.market
+     WHERE m.creator = $1`,
+    [toBytes(creator)],
+  );
+
+  const launches = Number(row?.launches ?? "0");
+  const graduated = Number(row?.graduated ?? "0");
+
+  return {
+    launches,
+    graduated,
+    totalVolume: big(row?.volume ?? "0", "volume"),
+    totalTrades: Number(row?.trades ?? "0"),
+    totalHolders: Number(row?.holders ?? "0"),
+    // Zero for a creator with no launches, not a division by zero and not
+    // "100%" — a creator who has launched nothing has not graduated nothing
+    // successfully, and either of those readings would be a claim about a
+    // record that does not exist.
+    graduationRatePerMille: launches === 0 ? 0 : Math.round((graduated * 1_000) / launches),
+  };
+}
+
 /** Addresses registered as ineligible for Stockback (§323, §324). */
 export async function getExclusions(db: Db, market: string): Promise<`0x${string}`[]> {
   const rows = await db.query<Record<string, unknown>>(

services/api/sim/handlers.ts

@@ -169,6 +169,14 @@ class FakePort implements DataPort {
         blockNumber: 870n,
       },
     ],
+    stats: {
+      launches: 3,
+      graduated: 2,
+      totalVolume: 4_200_000n,
+      totalTrades: 411,
+      totalHolders: 96,
+      graduationRatePerMille: 667,
+    },
   };
   getCreator(): CreatorRow | null {
     return this.creator;
@@ -873,6 +881,19 @@ console.log("\n--- 10. §221: the creator cockpit ------------------------------
     "amounts are serialised as strings",
     typeof result.data.claimable[0]?.amount === "string",
   );
+
+  /*
+   * §26's reputation layer: market-driven, with nothing an operator can set.
+   *
+   * The rate is per mille rather than a float. 2 of 3 as a float is
+   * 0.6666666666666666, which every consumer then decides how to round —
+   * differently — and §424 keeps ratio quantities out of JS floating point for
+   * the same reason it keeps amounts out.
+   */
+  check("launches are counted", result.data.stats.launches === 3);
+  check("graduations too", result.data.stats.graduated === 2);
+  check("and the rate is an integer per mille", result.data.stats.graduationRatePerMille === 667);
+  check("lifetime volume crosses the wire as a string", result.data.stats.totalVolume === "4200000");
 }
 
 {
@@ -886,6 +907,14 @@ console.log("\n--- 10. §221: the creator cockpit ------------------------------
   check("a creator with no launches is not an error", empty.ok);
   check("and gets an empty cockpit", empty.ok && empty.data.launches.length === 0);
 
+  // Zero, not a division by zero and not "100%". A creator who has launched
+  // nothing has not graduated nothing successfully, and either reading would be
+  // a claim about a record that does not exist.
+  check(
+    "with a graduation rate of zero rather than a divide by zero",
+    empty.ok && empty.data.stats.graduationRatePerMille === 0,
+  );
+
   const bad = handleCreator(port, "0x123");
   check("a malformed address is refused by name", !bad.ok && bad.code === "INVALID_ADDRESS");
   check("and the refusal still carries freshness", bad.freshness !== undefined);

services/api/src/handlers.ts

@@ -163,6 +163,15 @@ export interface CreatorRow {
     timestamp: number;
     blockNumber: bigint;
   }[];
+  /** §26's reputation figures. Derived from the chain; none can be granted. */
+  readonly stats: {
+    readonly launches: number;
+    readonly graduated: number;
+    readonly totalVolume: bigint;
+    readonly totalTrades: number;
+    readonly totalHolders: number;
+    readonly graduationRatePerMille: number;
+  };
 }
 
 export interface CandleBar {
@@ -700,6 +709,23 @@ export interface CreatorResponse {
     timestamp: number;
     blockNumber: string;
   }[];
+  /**
+   * §26's reputation layer.
+   *
+   * Every figure is derived from what the chain did, and none of it can be
+   * granted, bought or set. That is the section's whole point: standing comes
+   * from launches performing, not from a badge — which is also why there is no
+   * field here an operator could write.
+   */
+  readonly stats: {
+    readonly launches: number;
+    readonly graduated: number;
+    readonly totalVolume: string;
+    readonly totalTrades: number;
+    readonly totalHolders: number;
+    /** Per mille, not a float. See the repository for why. */
+    readonly graduationRatePerMille: number;
+  };
 }
 
 /**
@@ -731,6 +757,14 @@ export function handleCreator(port: DataPort, address: string): ApiResult<Creato
       claimable: [],
       accrued: [],
       claims: [],
+      stats: {
+        launches: 0,
+        graduated: 0,
+        totalVolume: "0",
+        totalTrades: 0,
+        totalHolders: 0,
+        graduationRatePerMille: 0,
+      },
     });
   }
 
@@ -772,6 +806,14 @@ export function handleCreator(port: DataPort, address: string): ApiResult<Creato
       timestamp: c.timestamp,
       blockNumber: c.blockNumber.toString(),
     })),
+    stats: {
+      launches: row.stats.launches,
+      graduated: row.stats.graduated,
+      totalVolume: row.stats.totalVolume.toString(),
+      totalTrades: row.stats.totalTrades,
+      totalHolders: row.stats.totalHolders,
+      graduationRatePerMille: row.stats.graduationRatePerMille,
+    },
   });
 }
 

services/api/src/port.ts

@@ -36,6 +36,7 @@ import {
   listMarketsByCreator,
   creatorAccruals,
   listFeeClaims,
+  creatorStats,
   countMarkets as dbCountMarkets,
   listHoldings,
   accountStockback,
@@ -558,10 +559,11 @@ export class PostgresPort implements DataPort {
    * a zero balance, so nothing is missed by asking only about the ones indexed.
    */
   async loadCreator(address: string): Promise<void> {
-    const [views, accruals, claims] = await Promise.all([
+    const [views, accruals, claims, stats] = await Promise.all([
       listMarketsByCreator(this.db, address),
       creatorAccruals(this.db, address),
       listFeeClaims(this.db, address),
+      creatorStats(this.db, address),
     ]);
 
     const vault = await this.resolveFeeVault();
@@ -623,6 +625,7 @@ export class PostgresPort implements DataPort {
         timestamp: c.timestamp,
         blockNumber: c.blockNumber,
       })),
+      stats,
     });
   }
 

tests/e2e/stack.ts

@@ -1439,6 +1439,19 @@ try {
       drift < oneRawUnit * tradeCount,
     );
 
+    /*
+     * §26's reputation figures, over the real chain.
+     *
+     * One launch, graduated, so the rate is exactly 1000 per mille — a number
+     * that can be checked rather than compared against whatever the code
+     * produced.
+     */
+    const cstats = cockpit?.stats as Record<string, unknown>;
+    check("the creator's launches are counted", cstats?.launches === 1);
+    check("and their graduation", cstats?.graduated === 1);
+    check("giving a rate of 1000 per mille", cstats?.graduationRatePerMille === 1_000);
+    check("with lifetime volume from real trades", BigInt(String(cstats?.totalVolume)) > 0n);
+
     check(
       "graduation progress is reported per launch",
       launches.every((l) => (l.graduationProgressBps as Record<string, unknown>)?.value !== undefined),