feat(meta-legion): move /meta-legion to Legion Exchange v2 (#1095)

* feat(meta-legion): move /meta-legion to Legion Exchange v2

v2 (SP3EF02CC2CGWJ327TXXW7JD4B9K9F1R0FSVY3659.legion-exchange-v2) replaces
v1's human resolvers. Every legion now asks one fixed question: will any of
these Bitcoin addresses bond in pox-5 after the legion was created and by
its deadline? YES settles by an on-chain Bitcoin proof (resolve-bonded),
accepted until 1,008 blocks after the deadline; NO by resolve-idle after
that.

- Fold the v2 prints: create-legion carries label, scripts, deadline and
  created-at; resolve-bonded and resolve-idle replace resolve and
  void-legion
- Phases follow the contract: trading, proof window, awaiting
  resolve-idle, settled
- Show every legion's addresses, decoded from the stored output scripts
  (P2PK outputs such as Satoshi's genesis key are named, since they have
  no standard address), and both countdowns: deadline and proof window
- Legion 0's label and created-at are v2's deploy values
- The exchange chainhook targets v2 as aibtc-legion-exchange-v2-mainnet

* refactor(meta-legion): trim the page copy

Drop the explanatory paragraphs (hero, scoreboard, market, footer and the
per-legion sub-line) down to one short line where one is needed, and fix
the closing call to action, which still described v1's resolvers.

Author: biwasxyz

app/api/meta-legion/route.ts

@@ -19,19 +19,19 @@ export async function GET(request: NextRequest) {
         endpoint: "/api/meta-legion",
         method: "GET",
         description:
-          "State of the Legion Exchange: every legion is a yes/no question with its own YES/NO share market paid in sBTC. Legion 0, the meta legion, asks whether at least `target` legions clear the trading bar in each of the three counted epochs before the close. The contract settles it from its own scoreboard. Folded from the exchange's print events, delivered by a Hiro chainhook; read-only.",
+          "State of the Legion Exchange v2: every legion asks whether any of a set of Bitcoin addresses bonds in pox-5 before a deadline, with its own YES/NO share market paid in sBTC. YES settles by an on-chain Bitcoin proof (resolve-bonded), NO by resolve-idle after the proof grace. Legion 0, the meta legion, asks whether at least `target` legions clear the trading bar in each of the three counted epochs before the close. The contract settles it from its own scoreboard. Folded from the exchange's print events, delivered by a Hiro chainhook; read-only.",
         contracts: { exchange: EXCHANGE_CONTRACT, collateral: SBTC_TOKEN },
         response: {
           tip: "number | null: Bitcoin burn height (epochs and resolve dates count burn blocks)",
           tipTime: "number | null: unix seconds of the tip block",
-          terms: "meta-terms: { target, closeHeight, epochs[], epochBlocks, minVolume, minTraders, feeBps, maxCollateral, feeSink }",
+          terms: "meta-terms: { target, closeHeight, epochs[], epochBlocks, minVolume, minTraders, feeBps, maxCollateral, feeSink, proofGrace, maxScripts }",
           score: "meta-count: the lowest qualified count across the counted epochs",
           currentEpoch: "floor(tip / epochBlocks)",
           epochs: "[{ epoch, start, end, state (upcoming | live | done), qualifiedCount }] for the counted epochs",
           meta: "LegionRow for legion 0",
           legions: "LegionRow[] for every other legion, newest first",
           LegionRow:
-            "{ id, subject, creator, resolver, resolveHeight, status (0 open, 1 YES, 2 NO, 3 void), collateral, supply, stats[{ epoch, volume, traders, qualified }] }",
+            "{ id, label, creator, scripts (Bitcoin output scripts, 0x hex; the question is whether any bonds in pox-5 after createdAt and by deadline), deadline, createdAt, status (0 open, 1 YES bonded, 2 NO idle), collateral, supply, stats[{ epoch, volume, traders, qualified }] }",
           orders:
             "Orders with shares left, across every legion: { id, kind (offer | bid), legion, side (1 YES, 0 NO), maker, price (ten-thousandths of a sat per share), remaining }",
           feed: "The 60 most recent exchange events, newest first: { txid, event, blockHeight, data }",

app/meta-legion/MetaLegionView.tsx

@@ -17,13 +17,12 @@ import type { MetaLegionState } from "@/lib/meta-legion/server-state";
 import {
   EXCHANGE_CONTRACT,
   EXCHANGE_SOURCE_HREF,
+  LEGION_STATUS,
   SIDE,
-  VOID_GRACE_BLOCKS,
   type Side,
 } from "@/lib/meta-legion/constants";
 import {
   bookFor,
-  costOf,
   fmtPct,
   legionPhase,
   yesQuote,
@@ -33,8 +32,8 @@ import {
   type LegionRow,
   type Order,
 } from "@/lib/meta-legion/state";
+import { describeScript } from "@/lib/meta-legion/scripts";
 import {
-  addrLink,
   contractLink,
   fmtBlocksLeft,
   fmtClock,
@@ -46,22 +45,20 @@ import {
 
 const PHASE_LABEL: Record<LegionPhase, string> = {
   trading: "Trading",
-  "awaiting-resolver": "Awaiting resolver",
-  voidable: "Voidable",
+  proving: "Proof window",
+  idle: "Awaiting resolve-idle",
   resolvable: "Resolvable",
-  yes: "Resolved YES",
-  no: "Resolved NO",
-  void: "Void",
+  yes: "Bonded, YES",
+  no: "Idle, NO",
 };
 
 const PHASE_TONE: Record<LegionPhase, string> = {
   trading: "live",
-  "awaiting-resolver": "warn",
-  voidable: "warn",
+  proving: "warn",
+  idle: "warn",
   resolvable: "warn",
   yes: "good",
   no: "bad",
-  void: "dim",
 };
 
 const SIDE_LABEL: Record<Side, string> = { [SIDE.YES]: "YES", [SIDE.NO]: "NO" };
@@ -164,17 +161,60 @@ function EpochCard({ e, target }: { e: EpochWindow; target: number }) {
   );
 }
 
+/** The addresses a legion asks about. They, not the label, decide the answer. */
+function Addresses({ scripts }: { scripts: string[] }) {
+  return (
+    <ul className="ml-addrs">
+      {scripts.map((sc) => {
+        const v = describeScript(sc);
+        return (
+          <li key={sc} title={sc}>
+            {v.address ? (
+              <a href={`https://mempool.space/address/${v.address}`} target="_blank" rel="noopener">
+                {v.address}
+              </a>
+            ) : (
+              v.label
+            )}
+          </li>
+        );
+      })}
+    </ul>
+  );
+}
+
+/** The deadline cell: trading countdown, then the proof window's. */
+function DeadlineCell({ l, state }: { l: LegionRow; state: MetaLegionState }) {
+  const { tip, terms, blockSeconds } = state;
+  const toDeadline = tip == null ? null : l.deadline - tip;
+  const proofEnd = l.deadline + terms.proofGrace;
+  const toProofEnd = tip == null ? null : proofEnd - tip;
+  return (
+    <td className="ml-mono">
+      {fmtInt(l.deadline)}
+      {toDeadline != null && toDeadline > 0 ? (
+        <span className="ml-dim"> {fmtBlocksLeft(toDeadline, blockSeconds)}</span>
+      ) : null}
+      <span className="ml-sub-line">
+        YES provable to {fmtInt(proofEnd)}
+        {toDeadline != null && toDeadline <= 0 && toProofEnd != null && toProofEnd >= 0
+          ? ` (${fmtBlocksLeft(toProofEnd, blockSeconds)})`
+          : ""}
+      </span>
+    </td>
+  );
+}
+
 function LegionTable({ state, legions }: { state: MetaLegionState; legions: LegionRow[] }) {
-  const { tip, terms, currentEpoch, blockSeconds } = state;
+  const { tip, terms, currentEpoch } = state;
   return (
     <div className="ml-table-wrap">
       <table className="ml-table">
         <thead>
           <tr>
             <th>#</th>
             <th>Question</th>
-            <th>Resolver</th>
-            <th>Resolves</th>
+            <th>Deadline</th>
             <th>Status</th>
             <th className="num">Epoch {currentEpoch ?? "-"} volume</th>
             <th className="num">Traders</th>
@@ -183,41 +223,31 @@ function LegionTable({ state, legions }: { state: MetaLegionState; legions: Legi
         </thead>
         <tbody>
           {legions.map((l) => {
-            const phase = legionPhase(l, tip);
+            const phase = legionPhase(l, tip, terms.proofGrace);
             const now = l.stats.find((s) => s.epoch === currentEpoch);
-            const left = tip == null ? null : l.resolveHeight - tip;
-            const stopsEarly = l.resolveHeight < terms.closeHeight;
+            const stopsEarly = l.deadline < terms.closeHeight;
             return (
               <tr key={l.id}>
                 <td className="ml-mono ml-dim">{l.id}</td>
                 <td className="q">
-                  {l.subject}
+                  <span className="ml-q-label">{l.label}</span>
+                  <Addresses scripts={l.scripts} />
                   {stopsEarly && phase === "trading" ? (
                     <span className="ml-flag" title={`Trading stops before burn ${fmtInt(terms.closeHeight - 1)}`}>
-                      Stops before the close
+                      Closes before the meta legion, does not count
                     </span>
                   ) : null}
                 </td>
-                <td className="ml-mono">
-                  <a href={addrLink(l.resolver)} target="_blank" rel="noopener">
-                    {shortAddr(l.resolver)}
-                  </a>
-                </td>
-                <td className="ml-mono">
-                  {fmtInt(l.resolveHeight)}
-                  {left != null && left > 0 ? (
-                    <span className="ml-dim"> {fmtBlocksLeft(left, blockSeconds)}</span>
-                  ) : null}
-                </td>
+                <DeadlineCell l={l} state={state} />
                 <td>
                   <span className={`ml-pill ${PHASE_TONE[phase]}`}>{PHASE_LABEL[phase]}</span>
                 </td>
                 <td className="ml-mono num">
-                  {now ? fmtInt(now.volume) : "-"}
+                  {fmtInt(now?.volume ?? 0)}
                   <span className="ml-dim"> / {fmtInt(terms.minVolume)}</span>
                 </td>
                 <td className="ml-mono num">
-                  {now ? fmtInt(now.traders) : "-"}
+                  {fmtInt(now?.traders ?? 0)}
                   <span className="ml-dim"> / {terms.minTraders}</span>
                 </td>
                 <td>
@@ -265,16 +295,12 @@ function MetaMarket({ state }: { state: MetaLegionState }) {
   const { meta, orders, terms, tip } = state;
   const quote = yesQuote(orders, 0);
   const room = Math.max(0, terms.maxCollateral - meta.collateral);
-  const phase = legionPhase(meta, tip);
+  const phase = legionPhase(meta, tip, terms.proofGrace);
   const sides: Side[] = [SIDE.YES, SIDE.NO];
 
   return (
     <section className="ml-section">
       <h2 className="ml-h2">The meta market</h2>
-      <p className="ml-lede">
-        Legion 0 trades like any other legion: mint a complete set, sell the side you don&apos;t believe in,
-        or buy the side you do. Its own trades never count toward the bar, so the market cannot settle itself.
-      </p>
 
       <div className="figs four">
         <div className="fig accent">
@@ -329,7 +355,6 @@ function MetaMarket({ state }: { state: MetaLegionState }) {
 
 function HowToTrade({ state }: { state: MetaLegionState }) {
   const { terms } = state;
-  const example = { shares: 10_000, price: 5_000 };
   const calls: { fn: string; args: string; what: string; pc: string }[] = [
     {
       fn: "mint-set",
@@ -373,6 +398,12 @@ function HowToTrade({ state }: { state: MetaLegionState }) {
       what: "After resolution, collect the winning side",
       pc: "Exchange sends exactly claimable(u0, you)",
     },
+    {
+      fn: "resolve-meta",
+      args: "none",
+      what: "After the close, settle legion 0 from the scoreboard (anyone)",
+      pc: "None",
+    },
   ];
   return (
     <div className="ml-howto">
@@ -383,12 +414,8 @@ function HowToTrade({ state }: { state: MetaLegionState }) {
         </a>
       </div>
       <p className="ml-howto-note">
-        Call the contract directly, e.g. with the AIBTC MCP server&apos;s <code>call_contract</code>. Always use
-        post-condition <b>deny</b> mode: shares are balances inside the contract, so only sBTC needs a
-        post-condition. <code>side</code> is <code>u1</code> YES, <code>u0</code> NO. <code>price</code> is
-        ten-thousandths of a sat per share, so <code>u5000</code> is 50%: {fmtInt(example.shares)} shares at 50%
-        cost {fmtSats(costOf(example.shares, example.price))}. Each fill pays a {terms.feeBps / 100}% fee to the
-        treasury, taken from the maker&apos;s side. Minimum trade is 1,000 sats.
+        Post-condition <b>deny</b> mode. <code>side</code> <code>u1</code> YES, <code>u0</code> NO.{" "}
+        <code>price</code> <code>u5000</code> = 50%. {terms.feeBps / 100}% fee from the maker, 1,000 sat minimum.
       </p>
       <div className="ml-table-wrap">
         <table className="ml-table ml-calls">
@@ -478,16 +505,16 @@ function wireLine(e: FeedItem): React.ReactNode {
           <b>legion #{Number(d.legion)}</b> cleared the bar in epoch {Number(d.epoch)} ({Number(d.count)} this epoch)
         </>
       );
-    case "resolve":
+    case "resolve-bonded":
       return (
         <>
-          {who("by")} resolved {legionRef(d)} {Number(d.outcome) === 1 ? "YES" : "NO"}
+          {who("by")} proved a bond: {legionRef(d)} settled <b>YES</b>
         </>
       );
-    case "void-legion":
+    case "resolve-idle":
       return (
         <>
-          {who("by")} voided {legionRef(d)}
+          {who("by")} settled {legionRef(d)} <b>NO</b>, no bond proven
         </>
       );
     case "resolve-meta":
@@ -610,13 +637,11 @@ export default function MetaLegionView({ initial }: { initial: MetaLegionState |
   const qualifiedNow = (l: LegionRow) => l.stats.some((s) => s.epoch === currentEpoch && s.qualified);
   const groups: Record<Filter, LegionRow[]> = {
     all: legions,
-    trading: legions.filter((l) => legionPhase(l, tip) === "trading"),
+    trading: legions.filter((l) => legionPhase(l, tip, terms.proofGrace) === "trading"),
     qualified: legions.filter(qualifiedNow),
-    settled: legions.filter((l) => ["yes", "no", "void"].includes(legionPhase(l, tip))),
+    settled: legions.filter((l) => l.status !== LEGION_STATUS.OPEN),
   };
   const shown = groups[filter];
-  const counting = data.epochs.some((e) => e.state !== "upcoming");
-  const firstCounted = data.epochs[0];
 
   return (
     <main className="content">
@@ -641,10 +666,8 @@ export default function MetaLegionView({ initial }: { initial: MetaLegionState |
             trade?
           </h1>
           <p className="hero-lede">
-            {meta.subject}. A legion clears the bar in an epoch with {fmtSats(terms.minVolume)} traded among{" "}
-            {terms.minTraders} distinct traders. Nobody resolves this one: after burn block{" "}
-            {fmtInt(terms.closeHeight)} anyone calls <code>resolve-meta</code> and the contract reads its own
-            scoreboard. No admin key, no upgrade path.
+            YES if {terms.target} legions each trade {fmtSats(terms.minVolume)} among {terms.minTraders} traders in
+            all three counted epochs. The contract settles it from its own scoreboard.
           </p>
           <div className="hero-cta">
             <a className="cta-btn" href={EXCHANGE_SOURCE_HREF} target="_blank" rel="noopener">
@@ -685,12 +708,6 @@ export default function MetaLegionView({ initial }: { initial: MetaLegionState |
 
       <section className="ml-section">
         <h2 className="ml-h2">Scoreboard</h2>
-        <p className="ml-lede">
-          The score is the lowest of the three counted epochs, so the bar has to be cleared in each of them.
-          {!counting && firstCounted
-            ? ` Counting starts at burn block ${fmtInt(firstCounted.start)} (epoch ${firstCounted.epoch}); until then every count is zero.`
-            : ""}
-        </p>
         <div className="ml-epochs">
           {data.epochs.map((e) => (
             <EpochCard key={e.epoch} e={e} target={terms.target} />
@@ -701,8 +718,8 @@ export default function MetaLegionView({ initial }: { initial: MetaLegionState |
       <div ref={barSentinel} className="legion-bar-sentinel" aria-hidden="true" />
       <div className={`legion-bar ${stuck ? "stuck" : ""}`}>
         <CtaBand
-          t="Anyone can create a legion. Each one that clears the bar moves the meta score."
-          d={`no signup, no admin, ${fmtSats(terms.minVolume)} among ${terms.minTraders} traders per epoch`}
+          t="Anyone can create a legion."
+          d={`${fmtSats(terms.minVolume)} among ${terms.minTraders} traders per epoch to qualify`}
         />
         {legions.length ? (
           <div className="tabs">
@@ -731,12 +748,6 @@ export default function MetaLegionView({ initial }: { initial: MetaLegionState |
       ) : (
         <LegionTable state={data} legions={shown} />
       )}
-      <p className="ml-foot">
-        Every legion is only as honest as its resolver. If the resolver misses the {fmtInt(VOID_GRACE_BLOCKS)}-block
-        grace after the resolve date, anyone can void it and every share, either side, redeems at half. Trades with
-        the treasury (<span className="ml-mono">{shortAddr(terms.feeSink)}</span>) never count toward the bar. To
-        count, a legion has to still be trading through burn block {fmtInt(terms.closeHeight - 1)}.
-      </p>
 
       <MetaMarket state={data} />
 
@@ -745,8 +756,7 @@ export default function MetaLegionView({ initial }: { initial: MetaLegionState |
       <div className="cta-close">
         <div className="t">Put a legion on the board</div>
         <p className="d">
-          Call <code>create-legion</code> with a question, a resolver and a resolve date, seed both sides, and let
-          it trade. Fifty of them clearing the bar in each counted epoch is what resolves this market YES.
+          Up to {terms.maxScripts} Bitcoin addresses and a deadline. Call <code>create-legion</code> and let it trade.
         </p>
         <a className="cta-btn" href={EXCHANGE_SOURCE_HREF} target="_blank" rel="noopener">
           Read the contract