@aibtc/mcp-server 1.67.0 → 1.69.0

package/dist/config/legion.d.ts

@@ -1,24 +1,64 @@
 /**
- * AIBTC News Legion (news-gov-v5) configuration.
+ * AIBTC News Legion configuration.
  *
  * Contribution-weighted governance for aibtc.news: agents inscribe a news piece
  * to a Bitcoin ordinal, open ONE proposal naming that inscription, and the
  * contributors vote on whether the piece is worth paying for. A passing piece
  * pays its proposer a fixed slice of the sBTC pool.
  *
+ * LIVE ON STACKS MAINNET, WITH REAL sBTC. The legion ran on testnet through
+ * v5/v6; those deployments are gone from this file because a testnet chain that
+ * has already been reset once is not history worth reading, and because keeping
+ * them would mean every read path carried a per-era network. Mainnet generation
+ * 1 is the only deployment now, and its proposal ids start at 1.
+ *
+ * Everything here still moves real value: `legion_contribute` and
+ * `legion_sponsor` spend sBTC that cannot be withdrawn, so both meter against
+ * the wallet's `sats` spending rail before they sign.
+ *
  * NETWORK IS DERIVED FROM THE CONTRACT ADDRESS, NOT FROM `NETWORK`.
- * The legion is deployed on Stacks testnet. Every other tool in this server
- * follows the global `NETWORK` env var, which defaults to mainnet — routing
- * these calls through that would sign a testnet governance flow against real
- * funds. `LEGION_NETWORK` reads the address prefix instead, so the legion tools
- * sign against the chain the contracts actually live on no matter how the rest
- * of the server is configured.
+ * Every other tool in this server follows the global `NETWORK` env var. Reading
+ * that here would let a testnet-configured server sign governance calls against
+ * a testnet node while quoting mainnet balances. `LEGION_NETWORK` reads the
+ * address prefix instead, so these tools always follow the chain the contracts
+ * actually live on.
  */
 import type { Network } from "./networks.js";
-/** Governance contract: proposals, votes, vetoes, conclusion. */
-export declare const LEGION_GOV_CONTRACT = "STGX5YP51NKM69ZMP6DVB6GAJAANCG5WB3718KD9.news-gov-v5-testnet";
-/** Treasury contract: the sBTC pool. Every outflow is gov-gated. */
-export declare const LEGION_TREASURY_CONTRACT = "STGX5YP51NKM69ZMP6DVB6GAJAANCG5WB3718KD9.news-treasury-v5";
+/** One deployment of the legion: a gov contract and the treasury it pays from. */
+export interface LegionEra {
+    /** Full gov contract id. */
+    gov: string;
+    /** Full treasury id — where `sponsor-in` prints and the pool lives. */
+    treasury: string;
+    /**
+     * Generation number. The mainnet contracts carry no version in their names,
+     * so this is declared rather than parsed out of a string that no longer
+     * holds it.
+     */
+    version: number;
+    /** True for the one era still receiving events. Only it accepts writes. */
+    live: boolean;
+}
+/**
+ * Every deployment this server knows, LIVE FIRST.
+ *
+ * Adding an era is one entry here with `live` moved to it; the old one keeps
+ * answering reads. Both contracts of a pair must share a deployer — gov calls
+ * its treasury as `(contract-call? .aibtc-news-treasury …)`, which resolves
+ * against the DEPLOYER OF THE GOV CONTRACT — and that is asserted below rather
+ * than trusted.
+ */
+export declare const LEGION_ERAS: readonly LegionEra[];
+/** The era that accepts writes. */
+export declare const LIVE_ERA: LegionEra;
+/** Look up an era by generation number. */
+export declare function eraByVersion(version: number): LegionEra | undefined;
+/**
+ * Resolve a caller-supplied era version, defaulting to the live one.
+ * An unknown version is an error rather than a silent fallback — reading the
+ * wrong era would quietly answer about a different proposal with the same id.
+ */
+export declare function resolveEra(version?: number): LegionEra;
 /**
  * Which chain a Stacks contract id lives on, from its c32 address prefix:
  * SP/SM are mainnet, ST/SN are testnet.
@@ -42,6 +82,8 @@ export declare const MAX_LINK_LENGTH = 200;
 export declare const MAX_TITLE_LENGTH = 128;
 /** `description` is `(string-ascii 512)`. */
 export declare const MAX_DESCRIPTION_LENGTH = 512;
+/** `vote` `rationale` is `(string-ascii 256)` and must be non-empty. */
+export declare const MAX_RATIONALE_LENGTH = 256;
 /** `sponsor-in` `name` is `(string-ascii 40)`. */
 export declare const MAX_SPONSOR_NAME_LENGTH = 40;
 /** `sponsor-in` `link` is `(optional (string-ascii 96))`. */

package/dist/config/legion.js

@@ -1,23 +1,66 @@
 /**
- * AIBTC News Legion (news-gov-v5) configuration.
+ * AIBTC News Legion configuration.
  *
  * Contribution-weighted governance for aibtc.news: agents inscribe a news piece
  * to a Bitcoin ordinal, open ONE proposal naming that inscription, and the
  * contributors vote on whether the piece is worth paying for. A passing piece
  * pays its proposer a fixed slice of the sBTC pool.
  *
+ * LIVE ON STACKS MAINNET, WITH REAL sBTC. The legion ran on testnet through
+ * v5/v6; those deployments are gone from this file because a testnet chain that
+ * has already been reset once is not history worth reading, and because keeping
+ * them would mean every read path carried a per-era network. Mainnet generation
+ * 1 is the only deployment now, and its proposal ids start at 1.
+ *
+ * Everything here still moves real value: `legion_contribute` and
+ * `legion_sponsor` spend sBTC that cannot be withdrawn, so both meter against
+ * the wallet's `sats` spending rail before they sign.
+ *
  * NETWORK IS DERIVED FROM THE CONTRACT ADDRESS, NOT FROM `NETWORK`.
- * The legion is deployed on Stacks testnet. Every other tool in this server
- * follows the global `NETWORK` env var, which defaults to mainnet — routing
- * these calls through that would sign a testnet governance flow against real
- * funds. `LEGION_NETWORK` reads the address prefix instead, so the legion tools
- * sign against the chain the contracts actually live on no matter how the rest
- * of the server is configured.
+ * Every other tool in this server follows the global `NETWORK` env var. Reading
+ * that here would let a testnet-configured server sign governance calls against
+ * a testnet node while quoting mainnet balances. `LEGION_NETWORK` reads the
+ * address prefix instead, so these tools always follow the chain the contracts
+ * actually live on.
+ */
+/**
+ * Every deployment this server knows, LIVE FIRST.
+ *
+ * Adding an era is one entry here with `live` moved to it; the old one keeps
+ * answering reads. Both contracts of a pair must share a deployer — gov calls
+ * its treasury as `(contract-call? .aibtc-news-treasury …)`, which resolves
+ * against the DEPLOYER OF THE GOV CONTRACT — and that is asserted below rather
+ * than trusted.
  */
-/** Governance contract: proposals, votes, vetoes, conclusion. */
-export const LEGION_GOV_CONTRACT = "STGX5YP51NKM69ZMP6DVB6GAJAANCG5WB3718KD9.news-gov-v5-testnet";
-/** Treasury contract: the sBTC pool. Every outflow is gov-gated. */
-export const LEGION_TREASURY_CONTRACT = "STGX5YP51NKM69ZMP6DVB6GAJAANCG5WB3718KD9.news-treasury-v5";
+export const LEGION_ERAS = [
+    {
+        gov: "SP5Y3W3F78NKFH4HYFNDQMJC484VZWKDH35ZR2M9.aibtc-news-gov",
+        treasury: "SP5Y3W3F78NKFH4HYFNDQMJC484VZWKDH35ZR2M9.aibtc-news-treasury",
+        version: 1,
+        live: true,
+    },
+];
+/** The era that accepts writes. */
+export const LIVE_ERA = LEGION_ERAS.find((e) => e.live) ?? LEGION_ERAS[0];
+/** Look up an era by generation number. */
+export function eraByVersion(version) {
+    return LEGION_ERAS.find((e) => e.version === version);
+}
+/**
+ * Resolve a caller-supplied era version, defaulting to the live one.
+ * An unknown version is an error rather than a silent fallback — reading the
+ * wrong era would quietly answer about a different proposal with the same id.
+ */
+export function resolveEra(version) {
+    if (version === undefined)
+        return LIVE_ERA;
+    const found = eraByVersion(version);
+    if (!found) {
+        throw new Error(`No legion era v${version}. Known eras: ` +
+            LEGION_ERAS.map((e) => `v${e.version}${e.live ? " (live)" : ""}`).join(", "));
+    }
+    return found;
+}
 /**
  * Which chain a Stacks contract id lives on, from its c32 address prefix:
  * SP/SM are mainnet, ST/SN are testnet.
@@ -32,7 +75,20 @@ export function networkOfContract(contractId) {
         `expected an address starting with SP/SM (mainnet) or ST/SN (testnet).`);
 }
 /** The chain the legion contracts are deployed on. */
-export const LEGION_NETWORK = networkOfContract(LEGION_GOV_CONTRACT);
+export const LEGION_NETWORK = networkOfContract(LIVE_ERA.gov);
+// Every era must sit on one chain, and each pair must share a deployer. The
+// network guard is derived from the live era, so a stray id on another chain
+// would be signed against the wrong node; a mismatched deployer would point gov
+// at a treasury it cannot actually call.
+for (const e of LEGION_ERAS) {
+    if (networkOfContract(e.gov) !== LEGION_NETWORK) {
+        throw new Error(`Legion era v${e.version} (${e.gov}) is not on ${LEGION_NETWORK}, but the live era is.`);
+    }
+    if (e.gov.split(".")[0] !== e.treasury.split(".")[0]) {
+        throw new Error(`Legion era v${e.version} pairs ${e.gov} with ${e.treasury}, but gov resolves ` +
+            `its treasury against its own deployer — the two must share an address.`);
+    }
+}
 /**
  * The viewer page for an inscription. This is the form every proposal on chain
  * already stores, and the form a voter wants: clicking it opens the ordinals
@@ -49,6 +105,8 @@ export const MAX_LINK_LENGTH = 200;
 export const MAX_TITLE_LENGTH = 128;
 /** `description` is `(string-ascii 512)`. */
 export const MAX_DESCRIPTION_LENGTH = 512;
+/** `vote` `rationale` is `(string-ascii 256)` and must be non-empty. */
+export const MAX_RATIONALE_LENGTH = 256;
 /** `sponsor-in` `name` is `(string-ascii 40)`. */
 export const MAX_SPONSOR_NAME_LENGTH = 40;
 /** `sponsor-in` `link` is `(optional (string-ascii 96))`. */
@@ -67,32 +125,31 @@ export const STORY_STATUS = {
  * Gov and treasury codes are disjoint, so one map covers both.
  */
 export const LEGION_ERRORS = {
-    401: "ineligible — your weight is below minWeight (contribute more first)",
+    401: "ineligible — your weight is below minWeightToAct (contribute more first)",
     402: "treasury has insufficient balance",
     403: "treasury already wired to a gov contract",
     404: "no proposal with that id",
     405: "you have already voted on this proposal",
     407: "voting has closed on this proposal",
-    408: "too early to conclude — the veto window has not closed yet",
+    408: "too early to conclude — voting is still open",
     409: "amount must be greater than zero",
     410: "this proposal is already concluded",
     411: "invalid payout recipient",
-    413: "your free weight does not cover the bond",
     416: "this payout was already settled",
     417: "the treasury payout failed",
-    418: "the pool is empty — nothing to draw against",
-    419: "the draw would round to zero sats",
+    418: "the pool is empty — nothing to pay out against",
+    419: "the payout would round to zero sats",
     421: "the ordinals link must not be empty",
     423: "a proposer cannot vote on their own piece",
-    424: "outside the veto window",
-    425: "you have already vetoed this proposal",
     426: "contribution too small to mint any weight",
     432: "too soon to propose — the global propose interval has not elapsed",
     433: "the title must not be empty",
     434: "you already have a live proposal (one at a time per principal)",
     435: "the conclude window has passed — this proposal has already expired",
     436: "voting has not opened yet (still in the pending period)",
-    437: "contribution is below minContribution",
+    437: "contribution is below minJoinSats",
+    440: "the vote rationale must not be empty",
+    441: "the legion is not activated yet — it needs membersToActivate members holding minWeightToAct before any story can be proposed",
     450: "sponsorship is below the treasury's minimum sponsor amount",
     451: "the sponsor name must not be empty",
     452: "the treasury is not wired to a gov contract yet",

package/dist/services/legion.service.d.ts

@@ -1,13 +1,23 @@
 /**
- * AIBTC News Legion (news-gov-v5) chain reads.
+ * AIBTC News Legion chain reads.
  *
  * Everything here reads the deployed contracts rather than trusting constants:
- * governance parameters, the timing mode (which clock the windows count on),
- * and the sBTC token the treasury actually holds all come off chain and are
- * cached per process. A doc that drifts from the contract is a doc; a read that
- * drifts from the contract is a bug, so there is nothing to drift.
+ * governance parameters, the timing mode, and the sBTC token the treasury
+ * holds. A doc that drifts from the contract is a doc; a read that drifts from
+ * the contract is a bug, so there is nothing to drift.
+ *
+ * The mainnet legion has NO VETO and NO QUORUM. A story is paid when enough
+ * distinct voters turn out, the yes share clears the threshold, AND the yes
+ * weight covers `yesMultiple` times the payout it releases — the last of these
+ * being what stops a small clique from voting money out of a large pool.
+ * Proposals are also blocked outright until the legion activates at
+ * `membersToActivate` members.
+ *
+ * Every cache is keyed by era, so a future generation cannot be served the
+ * previous one's answers.
  */
 import { type ClarityValue } from "@stacks/transactions";
+import { type LegionEra } from "../config/legion.js";
 import type { Account } from "../transactions/builder.js";
 /**
  * Deep-unwrap a ClarityValue into plain JS. `cvToValue` only unwraps the top
@@ -24,36 +34,71 @@ export declare function num(value: unknown): number;
  * Always reads the legion's own chain, never the globally configured one.
  */
 export declare function readLegionContract(contractId: string, functionName: string, functionArgs?: ClarityValue[]): Promise<unknown>;
-export declare function readGov(functionName: string, functionArgs?: ClarityValue[]): Promise<unknown>;
-export declare function readTreasury(functionName: string, functionArgs?: ClarityValue[]): Promise<unknown>;
+/**
+ * Which required functions a published interface fails to satisfy.
+ *
+ * Pure, so the comparison is testable without a chain. Extra functions are
+ * fine — a contract may offer more than we call. Only missing names and
+ * changed arities matter.
+ */
+export declare function diffContractShape(functions: Array<{
+    name: string;
+    args: unknown[];
+}>, required: Readonly<Record<string, number>>): string[];
+export declare function readGov(functionName: string, functionArgs?: ClarityValue[], era?: LegionEra): Promise<unknown>;
+export declare function readTreasury(functionName: string, functionArgs?: ClarityValue[], era?: LegionEra): Promise<unknown>;
 export interface LegionParams {
-    votingQuorum: number;
+    /** Percent of cast weight that must be yes, e.g. 66. */
     votingThreshold: number;
-    vetoQuorum: number;
-    minParticipants: number;
-    minWeight: number;
-    minContribution: number;
-    drawBps: number;
-    votingDelay: number;
+    /** Distinct voters a story needs before it can pass at all. */
+    minVoters: number;
+    /** Members holding minWeightToAct before ANY story may be proposed. */
+    membersToActivate: number;
+    /** Yes weight must be at least this multiple of the payout it releases. */
+    yesMultiple: number;
+    /** Weight floor to vote or propose. */
+    minWeightToAct: number;
+    /** Smallest contribution the contract accepts, in sats. */
+    minJoinSats: number;
+    /** Payout as basis points of the whole pool. */
+    payoutBps: number;
+    /** Blocks between filing and voting opening. */
+    voteDelay: number;
     voteWindow: number;
-    vetoWindow: number;
     concludeWindow: number;
-    proposeInterval: number;
+    /** Contract-wide cooldown between any two proposals. */
+    globalProposeInterval: number;
 }
 /** Every governance parameter, straight from `get-params`. */
-export declare function getParams(): Promise<LegionParams>;
+export declare function getParams(era?: LegionEra): Promise<LegionParams>;
+export interface MembershipStatus {
+    /** Principals holding at least minWeightToAct. Only ever climbs. */
+    memberCount: number;
+    membersToActivate: number;
+    /** False means every `propose-story` reverts with u441, whatever else is true. */
+    activated: boolean;
+    membersNeeded: number;
+}
+/**
+ * Whether the legion has enough members to accept proposals at all.
+ *
+ * This is a gate no amount of weight can bypass: a single whale holding the
+ * entire pool still cannot propose until `membersToActivate` distinct
+ * principals have joined.
+ */
+export declare function getMembership(era?: LegionEra): Promise<MembershipStatus>;
 /**
  * Which clock the windows count on. `"TEST-STACKS-BLOCKS"` counts Stacks
  * blocks; `"PROD-BURN"` counts Bitcoin burn blocks. Never assume — a window
  * measured against the wrong tip is off by a factor of ten.
  */
-export declare function getTimingMode(): Promise<string>;
+export declare function getTimingMode(era?: LegionEra): Promise<string>;
 /**
  * The sBTC token the treasury actually moves, plus its fungible-token asset
  * name — both needed to write an exact post-condition. Read from the treasury
  * and its contract interface so a post-condition can never name the wrong asset.
  */
-export declare function getLegionToken(): Promise<{
+export declare function getLegionToken(era?: LegionEra): Promise<{
     contract: string;
     assetName: string;
 }>;
@@ -61,7 +106,7 @@ export declare function getLegionToken(): Promise<{
  * The height the contract's windows are measured against, on the clock
  * `get-timing-mode` names.
  */
-export declare function getClockHeight(): Promise<{
+export declare function getClockHeight(era?: LegionEra): Promise<{
     height: number;
     clock: "stacks" | "burn";
     timingMode: string;
@@ -76,14 +121,20 @@ export declare function getClockHeight(): Promise<{
 export declare function getLegionAccount(): Promise<Account>;
 export interface StoryRecord {
     proposer: string;
-    bond: number;
-    draw: number;
+    /** The proposer's whole weight, held until the piece resolves. Never spent. */
+    lockedWeight: number;
+    /** Sats the treasury pays the proposer on a pass, snapshotted at propose time. */
+    payout: number;
     createdAt: number;
     voteEnd: number;
-    eligibleSnapshot: number;
+    /**
+     * TotalWeight at the moment the story opened — including the proposer's own,
+     * which they cannot vote with. Recorded for context; nothing in the pass/fail
+     * decision divides by it, because this era has no quorum.
+     */
+    totalWeightAtOpen: number;
     yesWeight: number;
     noWeight: number;
-    vetoWeight: number;
     voterCount: number;
     status: number;
     reason: string;
@@ -93,20 +144,18 @@ export interface StoryMeta {
     description: string;
     link: string;
 }
-export declare function getStory(proposalId: number): Promise<StoryRecord | null>;
-export declare function getStoryMeta(proposalId: number): Promise<StoryMeta | null>;
+export declare function getStory(proposalId: number, era?: LegionEra): Promise<StoryRecord | null>;
+export declare function getStoryMeta(proposalId: number, era?: LegionEra): Promise<StoryMeta | null>;
 /**
- * `"none" | "pending" | "voting" | "veto" | "concludable" | "expired" |
- * "passed" | "failed"` — the contract's own view of where a piece stands.
+ * `"none" | "pending" | "voting" | "concludable" | "expired" | "passed" |
+ * "failed"` — the contract's own view of where a piece stands.
  */
-export declare function getPhase(proposalId: number): Promise<string>;
-export declare function getLastProposalId(): Promise<number>;
-export declare function getVoteRecord(proposalId: number, voter: string): Promise<{
+export declare function getPhase(proposalId: number, era?: LegionEra): Promise<string>;
+export declare function getLastProposalId(era?: LegionEra): Promise<number>;
+export declare function getVoteRecord(proposalId: number, voter: string, era?: LegionEra): Promise<{
     support: boolean;
     weight: number;
-} | null>;
-export declare function getVetoRecord(proposalId: number, voter: string): Promise<{
-    weight: number;
+    rationale: string;
 } | null>;
 export interface ProposeStatus {
     canPropose: boolean;
@@ -114,20 +163,24 @@ export interface ProposeStatus {
     slotOpen: boolean;
     noLiveProposal: boolean;
     poolOk: boolean;
+    membersOk: boolean;
+    memberCount: number;
+    membersToActivate: number;
     nextProposeHeight: number;
     lockOnPropose: number;
-    draw: number;
+    payout: number;
     freeWeight: number;
 }
 /** Every propose precondition folded into one read, with the individual gates. */
-export declare function getProposeStatus(who: string): Promise<ProposeStatus>;
+export declare function getProposeStatus(who: string, era?: LegionEra): Promise<ProposeStatus>;
 /** Why a propose would revert right now, in the caller's words. */
-export declare function proposeBlockers(status: ProposeStatus, minWeight: number): string[];
+export declare function proposeBlockers(status: ProposeStatus, minWeightToAct: number): string[];
 export interface StoryTimeline {
     createdAt: number;
     votingOpensAt: number;
     voteEnd: number;
-    vetoEnd: number;
+    /** Conclude opens the moment voting closes — there is no veto window. */
+    concludeOpensAt: number;
     concludeDeadline: number;
     currentHeight: number;
     clock: "stacks" | "burn";
@@ -141,13 +194,12 @@ export interface PredictedOutcome {
     /** True when the outcome is what the contract already recorded, not a forecast. */
     settled: boolean;
     cast: number;
-    quorumPct: number;
     yesPct: number;
-    vetoPct: number;
-    quorumMet: boolean;
+    /** Yes weight the story needs to release its payout: payout × yesMultiple. */
+    yesWeightRequired: number;
+    votersMet: boolean;
     thresholdMet: boolean;
-    vetoed: boolean;
-    participantsMet: boolean;
+    yesMet: boolean;
     payout: number;
 }
 /**