@aibtc/mcp-server 1.65.0 → 1.66.0

package/dist/config/legion.d.ts

@@ -0,0 +1,58 @@
+/**
+ * AIBTC News Legion (news-gov-v5) 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.
+ *
+ * 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.
+ */
+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";
+/**
+ * Which chain a Stacks contract id lives on, from its c32 address prefix:
+ * SP/SM are mainnet, ST/SN are testnet.
+ */
+export declare function networkOfContract(contractId: string): Network;
+/** The chain the legion contracts are deployed on. */
+export declare const LEGION_NETWORK: Network;
+/**
+ * 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
+ * viewer rather than dumping raw markdown.
+ */
+export declare const ORDINALS_INSCRIPTION_BASE = "https://ordinals.com/inscription/";
+/** The raw bytes of an inscription — what a reader fetches to render the piece. */
+export declare const ORDINALS_CONTENT_BASE = "https://ordinals.com/content/";
+/** The public reader for this legion. */
+export declare const LEGION_SITE_URL = "https://legions.aibtc.news";
+/** `link` is `(string-ascii 200)`. */
+export declare const MAX_LINK_LENGTH = 200;
+/** `title` is `(string-ascii 128)`. */
+export declare const MAX_TITLE_LENGTH = 128;
+/** `description` is `(string-ascii 512)`. */
+export declare const MAX_DESCRIPTION_LENGTH = 512;
+/** `sponsor-in` `name` is `(string-ascii 40)`. */
+export declare const MAX_SPONSOR_NAME_LENGTH = 40;
+/** `sponsor-in` `link` is `(optional (string-ascii 96))`. */
+export declare const MAX_SPONSOR_LINK_LENGTH = 96;
+/** `sponsor-in` `memo` is `(string-ascii 128)`. */
+export declare const MAX_SPONSOR_MEMO_LENGTH = 128;
+/** Story status uints as stored by the gov contract. */
+export declare const STORY_STATUS: Record<number, string>;
+/**
+ * Contract error codes, so a revert reads as a sentence rather than a `u4xx`.
+ * Gov and treasury codes are disjoint, so one map covers both.
+ */
+export declare const LEGION_ERRORS: Record<number, string>;
+//# sourceMappingURL=legion.d.ts.map

package/dist/config/legion.js

@@ -0,0 +1,100 @@
+/**
+ * AIBTC News Legion (news-gov-v5) 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.
+ *
+ * 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.
+ */
+/** 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";
+/**
+ * Which chain a Stacks contract id lives on, from its c32 address prefix:
+ * SP/SM are mainnet, ST/SN are testnet.
+ */
+export function networkOfContract(contractId) {
+    const prefix = contractId.slice(0, 2).toUpperCase();
+    if (prefix === "SP" || prefix === "SM")
+        return "mainnet";
+    if (prefix === "ST" || prefix === "SN")
+        return "testnet";
+    throw new Error(`Cannot derive a network from contract id "${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);
+/**
+ * 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
+ * viewer rather than dumping raw markdown.
+ */
+export const ORDINALS_INSCRIPTION_BASE = "https://ordinals.com/inscription/";
+/** The raw bytes of an inscription — what a reader fetches to render the piece. */
+export const ORDINALS_CONTENT_BASE = "https://ordinals.com/content/";
+/** The public reader for this legion. */
+export const LEGION_SITE_URL = "https://legions.aibtc.news";
+/** `link` is `(string-ascii 200)`. */
+export const MAX_LINK_LENGTH = 200;
+/** `title` is `(string-ascii 128)`. */
+export const MAX_TITLE_LENGTH = 128;
+/** `description` is `(string-ascii 512)`. */
+export const MAX_DESCRIPTION_LENGTH = 512;
+/** `sponsor-in` `name` is `(string-ascii 40)`. */
+export const MAX_SPONSOR_NAME_LENGTH = 40;
+/** `sponsor-in` `link` is `(optional (string-ascii 96))`. */
+export const MAX_SPONSOR_LINK_LENGTH = 96;
+/** `sponsor-in` `memo` is `(string-ascii 128)`. */
+export const MAX_SPONSOR_MEMO_LENGTH = 128;
+/** Story status uints as stored by the gov contract. */
+export const STORY_STATUS = {
+    0: "OPEN",
+    1: "PASSED",
+    2: "FAILED",
+    3: "EXPIRED",
+};
+/**
+ * Contract error codes, so a revert reads as a sentence rather than a `u4xx`.
+ * 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)",
+    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",
+    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",
+    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",
+    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",
+};
+//# sourceMappingURL=legion.js.map

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

@@ -0,0 +1,188 @@
+/**
+ * AIBTC News Legion (news-gov-v5) 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.
+ */
+import { type ClarityValue } from "@stacks/transactions";
+import type { Account } from "../transactions/builder.js";
+/**
+ * Deep-unwrap a ClarityValue into plain JS. `cvToValue` only unwraps the top
+ * level — nested tuples and optionals come back as `{type, value}` envelopes —
+ * so the legion's tuple-heavy views need this instead.
+ *
+ * uints/ints become strings to stay exact; callers narrow with `num()`.
+ */
+export declare function simplifyCV(cv: ClarityValue): unknown;
+/** A uint field from a simplified tuple, as a JS number. */
+export declare function num(value: unknown): number;
+/**
+ * Call a read-only function on a legion contract and return it deep-unwrapped.
+ * 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>;
+export interface LegionParams {
+    votingQuorum: number;
+    votingThreshold: number;
+    vetoQuorum: number;
+    minParticipants: number;
+    minWeight: number;
+    minContribution: number;
+    drawBps: number;
+    votingDelay: number;
+    voteWindow: number;
+    vetoWindow: number;
+    concludeWindow: number;
+    proposeInterval: number;
+}
+/** Every governance parameter, straight from `get-params`. */
+export declare function getParams(): Promise<LegionParams>;
+/**
+ * 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>;
+/**
+ * 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<{
+    contract: string;
+    assetName: string;
+}>;
+/**
+ * The height the contract's windows are measured against, on the clock
+ * `get-timing-mode` names.
+ */
+export declare function getClockHeight(): Promise<{
+    height: number;
+    clock: "stacks" | "burn";
+    timingMode: string;
+}>;
+/**
+ * The unlocked wallet, re-derived for the legion's network.
+ *
+ * The same private key yields a different address per chain, so a mainnet
+ * session still signs legion calls from its testnet address against the testnet
+ * node. This is the guard that makes a mainnet-configured server safe here.
+ */
+export declare function getLegionAccount(): Promise<Account>;
+export interface StoryRecord {
+    proposer: string;
+    bond: number;
+    draw: number;
+    createdAt: number;
+    voteEnd: number;
+    eligibleSnapshot: number;
+    yesWeight: number;
+    noWeight: number;
+    vetoWeight: number;
+    voterCount: number;
+    status: number;
+    reason: string;
+}
+export interface StoryMeta {
+    title: string;
+    description: string;
+    link: string;
+}
+export declare function getStory(proposalId: number): Promise<StoryRecord | null>;
+export declare function getStoryMeta(proposalId: number): Promise<StoryMeta | null>;
+/**
+ * `"none" | "pending" | "voting" | "veto" | "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<{
+    support: boolean;
+    weight: number;
+} | null>;
+export declare function getVetoRecord(proposalId: number, voter: string): Promise<{
+    weight: number;
+} | null>;
+export interface ProposeStatus {
+    canPropose: boolean;
+    eligible: boolean;
+    slotOpen: boolean;
+    noLiveProposal: boolean;
+    poolOk: boolean;
+    nextProposeHeight: number;
+    lockOnPropose: number;
+    draw: number;
+    freeWeight: number;
+}
+/** Every propose precondition folded into one read, with the individual gates. */
+export declare function getProposeStatus(who: string): Promise<ProposeStatus>;
+/** Why a propose would revert right now, in the caller's words. */
+export declare function proposeBlockers(status: ProposeStatus, minWeight: number): string[];
+export interface StoryTimeline {
+    createdAt: number;
+    votingOpensAt: number;
+    voteEnd: number;
+    vetoEnd: number;
+    concludeDeadline: number;
+    currentHeight: number;
+    clock: "stacks" | "burn";
+    blocksUntilNextTransition: number | null;
+}
+/** When each window opens and closes, on the clock the contract counts. */
+export declare function buildTimeline(story: StoryRecord, params: LegionParams, height: number, clock: "stacks" | "burn"): StoryTimeline;
+export interface PredictedOutcome {
+    outcome: "passed" | "failed" | "expired";
+    reason: string;
+    /** 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;
+    thresholdMet: boolean;
+    vetoed: boolean;
+    participantsMet: boolean;
+    payout: number;
+}
+/**
+ * What `conclude` would decide if it ran at this height, following the
+ * contract's decision order exactly (integer division included, since Clarity
+ * floors every percentage).
+ *
+ * A story that is already terminal reports what the contract RECORDED, not a
+ * forecast. Forecasting a settled piece would be worse than useless: a passed
+ * proposal is necessarily past its conclude window, so the forecast branch
+ * would call every settled piece "expired".
+ */
+export declare function predictOutcome(story: StoryRecord, params: LegionParams, poolBalance: number, height: number): PredictedOutcome;
+/**
+ * Accept either a bare inscription id (`<txid>i0`) or a full URL, and return
+ * the link the contract should store.
+ *
+ * A bare id becomes the VIEWER url, not the content url: that is what every
+ * proposal already on chain uses, and it is what a voter wants from a click.
+ * The reader at legions.aibtc.news accepts either form and both bare ids.
+ */
+export declare function normalizeOrdinalsLink(input: string): string;
+/** The inscription id inside an ordinals link, when there is one. */
+export declare function inscriptionIdFromLink(link: string): string | null;
+/**
+ * The raw-bytes url for a stored link, so a voter can read the piece rather
+ * than just look at where it lives. Null when the link names no inscription.
+ */
+export declare function contentUrlFromLink(link: string): string | null;
+/**
+ * Clarity `string-ascii` holds one byte per character, so a smart quote or an
+ * em dash pasted into a headline is a revert, not a truncation. Catch it here
+ * with a message that names the character.
+ */
+export declare function assertAscii(value: string, field: string, maxLength: number): void;
+/** `(err uXXX)` from a failed read or a broadcast rejection, as a sentence. */
+export declare function explainError(error: unknown, errors: Record<number, string>): string;
+//# sourceMappingURL=legion.service.d.ts.map