@aibtc/mcp-server 1.69.0 → 1.70.0

package/dist/tools/competition.tools.d.ts

@@ -1,19 +1,20 @@
 /**
- * AIBTC Trading Competition Tools
+ * AIBTC Trading Competition Tools (read-only, NOT REGISTERED)
  *
- * Agents registered on aibtc.com (and indexed via ERC-8004) compete on a
- * time-bound track scored by P&L from on-chain trades. The competition service
- * monitors registered addresses passively, but agents can also submit txids
- * as a fast-path hint to skip indexer lag.
+ * The competition has concluded. Trade submission and the DEX allowlist were
+ * removed, and these two remaining read tools are no longer exposed over MCP:
+ * `registerCompetitionTools` is intentionally not called from `src/tools/index.ts`.
+ *
+ * The module is kept because the standing/history endpoints still exist and the
+ * P&L math (`computeCampaignStats`) is the reference implementation. Re-expose by
+ * restoring the import + call in `src/tools/index.ts`; the tests here exercise the
+ * module directly, so it stays compiled and verified while unwired.
  *
  * Tools:
- * - competition_submit_trade  — Submit a trade txid for verification
- * - competition_status        — Get current standing for an agent address
- * - competition_list_trades   — Paginated trade history (submitted + indexed)
+ * - competition_status        — Standing + mark-to-current P&L for an address
+ * - competition_list_trades   — Paginated trade history
  *
- * No request signing in v1: txids are self-attesting (the on-chain tx
- * already carries the agent's signature and sender), and status/list reads
- * are over public addresses. Rate-limited per IP server-side.
+ * Reads are over public addresses, no signing. Rate-limited per IP server-side.
  *
  * API spec + verifier implementation: aibtcdev/landing-page#734 (Phase 3.1).
  * Schema source of truth: docs/rfc-d1-schema.md §swaps (migration 005).

package/dist/tools/competition.tools.js

@@ -1,20 +1,9 @@
 import { z } from "zod";
 import { AIBTC_CAMPAIGN_API_URL } from "../config/competition.js";
-import { NETWORK } from "../config/networks.js";
-import { getTransactionStatus } from "../services/hiro-api.js";
 import { getTokenInfo } from "../services/tenero-api.js";
 import { getWalletManager } from "../services/wallet-manager.js";
 import { createJsonResponse } from "../utils/formatting.js";
 import { createErrorResponse } from "../utils/errors.js";
-/**
- * Stacks tx_status values from Hiro's /extended/v1/tx endpoint.
- * `pending` = in mempool, not confirmed. Everything else is terminal:
- * `success`, `abort_by_response`, `abort_by_post_condition`, and the
- * five `dropped_*` codes. The verifier records terminal failures too
- * (migration 005's CHECK allows all 8 terminal codes) so we only block
- * submission when status is `pending`.
- */
-const PENDING_TX_STATUS = "pending";
 const stacksAddressSchema = z
     .string()
     .regex(/^S[PTM][0-9A-HJKMNP-TV-Z]{38,40}$/, "Expected a Stacks address (SP… mainnet, ST… testnet, SM… contract)");
@@ -33,14 +22,6 @@ async function resolveAddress(provided) {
     }
     return meta.address;
 }
-function normalizeTxid(txid) {
-    const trimmed = txid.trim();
-    const withPrefix = trimmed.startsWith("0x") ? trimmed : `0x${trimmed}`;
-    if (!/^0x[0-9a-fA-F]{64}$/.test(withPrefix)) {
-        throw new Error(`Invalid Stacks txid: expected 64 hex chars (with optional 0x prefix), got ${JSON.stringify(txid)}`);
-    }
-    return withPrefix.toLowerCase();
-}
 const COMPETITION_FETCH_TIMEOUT_MS = 10_000;
 /**
  * Cap on `/trades` pagination when computing campaign stats. 10 pages × 200
@@ -290,66 +271,8 @@ async function resolveTokenPricesViaTenero(swaps) {
     return prices;
 }
 export function registerCompetitionTools(server) {
-    server.registerTool("competition_submit_trade", {
-        description: `Submit a trade txid to the AIBTC trading competition for verification and P&L scoring.
-
-**Two-step registration prerequisite** (both required, both one-time):
-1. Register on aibtc.com via the website's dual-sig flow (BIP-322 + SIP-018). This is not an MCP tool — agents go to https://aibtc.com to complete it.
-2. Register on the ERC-8004 identity contract via the \`identity_register\` MCP tool. This mints the on-chain agent ID that the campaign joins against.
-
-Mainnet-only in v1.
-
-The competition service fetches the tx from the Stacks chain and validates:
-- sender is registered on aibtc.com AND has an ERC-8004 agent_id
-- contract+function is on the campaign allowlist (e.g. Bitflow swap helpers, ALEX, Zest)
-- transaction status is terminal (success or any of the 7 terminal-failure codes)
-
-**No additional signed message is needed** — the txid itself is the agent's signed intent. The on-chain tx already carries their address (= identity) and the trade (= the on-chain effect). Tx history is the ledger.
-
-Submission is a fast-path hint — the backend also indexes registered agent addresses passively via a frequent catch-up cron, so a missed submission still gets picked up before final scoring. Submitting the same txid twice is idempotent (\`(txid)\` is the DB primary key; first writer wins).
-
-**Pre-flight:** This tool checks tx status on Stacks via Hiro before forwarding to the verifier. If the tx is still \`pending\` (in mempool), the call returns \`{ accepted: false, tx_status: "pending", message: "..." }\` without hitting the verifier — wait ~30s for confirmation and retry. Use \`get_transaction_status\` to poll explicitly.
-
-Response shapes:
-- \`{ accepted: false, txid, tx_status: "pending", message }\` (pre-flight gate): tx not yet confirmed. Retry after ~30s.
-- \`200 OK\` with the swap row once verified: \`{ txid, sender, contract_id, function_name, token_in, amount_in, token_out, amount_out, burn_block_time, tx_status, source, ... }\`. Field names follow on-chain vocabulary (migration 005). \`tx_status\` is one of \`success\` or 7 terminal-failure codes (verifier records terminal failures too); \`source\` is \`"agent" | "cron"\`.
-- Permanent rejection (HTTP 4xx, thrown as error): sender not registered, contract not on allowlist, or txid malformed. Do not retry — fix the inputs.
-- Transient failure (HTTP 5xx or timeout, thrown as error): retry with backoff.`,
-        inputSchema: {
-            txid: z
-                .string()
-                .min(1)
-                .describe("Stacks transaction id (with or without 0x prefix)"),
-        },
-    }, async ({ txid }) => {
-        try {
-            const normalized = normalizeTxid(txid);
-            // Pre-flight: confirm the tx is terminal on Stacks before forwarding
-            // to the verifier. Stacks blocks settle in ~30s, so a "pending" status
-            // means the agent submitted too early — we tell them to wait and
-            // resubmit rather than burning a backend round-trip.
-            const txStatus = await getTransactionStatus(normalized, NETWORK);
-            if (txStatus.status === PENDING_TX_STATUS) {
-                return createJsonResponse({
-                    accepted: false,
-                    txid: normalized,
-                    tx_status: PENDING_TX_STATUS,
-                    message: "Transaction is still pending on Stacks. Wait ~30s for confirmation and resubmit. Use get_transaction_status to poll.",
-                });
-            }
-            const parsed = await competitionFetch("/trades", {
-                method: "POST",
-                headers: { "content-type": "application/json" },
-                body: JSON.stringify({ txid: normalized }),
-            });
-            return createJsonResponse(parsed);
-        }
-        catch (error) {
-            return createErrorResponse(error);
-        }
-    });
     server.registerTool("competition_status", {
-        description: `Get the current AIBTC trading competition standing for an agent, with mark-to-current P&L computed locally.
+        description: `Get an agent's final AIBTC trading competition standing, with mark-to-current P&L computed locally. The competition has concluded; this reads the historical record.
 
 **Latency note:** by default this call also paginates the agent's trade history and parallel-fetches Tenero prices to compute live P&L. That adds a few seconds to the round-trip for agents with many trades or many distinct tokens. Pass \`include_pnl: false\` to skip that path and get only the cheap registration/count fields back.
 
@@ -399,9 +322,9 @@ To be eligible for scoring, the agent needs **both** an aibtc.com website regist
         }
     });
     server.registerTool("competition_list_trades", {
-        description: `List trades for an agent in the current AIBTC trading competition.
+        description: `List an agent's trades from the concluded AIBTC trading competition.
 
-Includes txids the agent submitted directly (via \`competition_submit_trade\`) and txids discovered via passive address monitoring (nightly cron). Each entry is a swap row from migration 005: \`{ txid, sender, contract_id, function_name, token_in, amount_in, token_out, amount_out, burn_block_time, tx_status, source, scored_value, scored_at }\`. \`source\` distinguishes \`"agent"\` (your submission) from \`"cron"\` (nightly catch-up). Response: \`{ trades, next_cursor }\` — opaque cursor for pagination. If no address is provided, uses the active wallet's Stacks address.`,
+Covers txids the agent submitted while the competition ran and txids discovered via passive address monitoring. Each entry is a swap row from migration 005: \`{ txid, sender, contract_id, function_name, token_in, amount_in, token_out, amount_out, burn_block_time, tx_status, source, scored_value, scored_at }\`. \`source\` distinguishes \`"agent"\` (your submission) from \`"cron"\` (nightly catch-up). Response: \`{ trades, next_cursor }\` — opaque cursor for pagination. If no address is provided, uses the active wallet's Stacks address.`,
         inputSchema: {
             address: stacksAddressSchema
                 .optional()
@@ -432,40 +355,5 @@ Includes txids the agent submitted directly (via \`competition_submit_trade\`) a
             return createErrorResponse(error);
         }
     });
-    server.registerTool("competition_allowlist", {
-        description: `Get the set of \`(contract_id, function_name)\` tuples the AIBTC trading-competition verifier will accept. Swaps against any contract/function not in this list are rejected with \`contract_not_allowlisted\` at \`POST /api/competition/trades\`.
-
-Use this **before submitting a txid** to confirm the swap you just made will score, or as discovery for "what protocols / pools can I trade for the competition right now?"
-
-Returns the payload from \`GET /api/competition/allowlist\` verbatim:
-
-\`\`\`
-{
-  entries: [
-    { contract_id: "SP….contract-name", functions: ["swap-x-for-y", ...] },
-    ...
-  ],
-  total_contracts: number,         // count of distinct contract_ids
-  total_functions: number,         // sum of allowed function names across entries
-  provider_address: string,        // AIBTC attribution string (audit-only)
-  protocols: { bitflow: number },  // per-protocol entry count
-}
-\`\`\`
-
-**Notes:**
-- Source of truth: \`lib/competition/allowlist.ts\` in landing-page. Reviewed per PR; no runtime mutation surface.
-- Current scope is **Bitflow only** (stableswap, XYK, DLMM router, cross-DEX routers, wrappers). ALEX direct and Zest are NOT yet in scope — \`alex_swap\` / \`zest_*\` calls land on-chain but get rejected as \`contract_not_allowlisted\`.
-- \`provider_address\` is the AIBTC attribution tag Bitflow's optional \`provider\` clarity arg can carry — it's recorded for audit but does NOT gate acceptance. Only the \`(contract, function)\` tuple match matters.
-- The list is cached server-side; tool returns whatever the live endpoint reports at call time.`,
-        inputSchema: {},
-    }, async () => {
-        try {
-            const parsed = await competitionFetch("/allowlist");
-            return createJsonResponse(parsed);
-        }
-        catch (error) {
-            return createErrorResponse(error);
-        }
-    });
 }
 //# sourceMappingURL=competition.tools.js.map

package/dist/tools/index.js

@@ -37,6 +37,8 @@ import { registerSigningTools } from "./signing.tools.js";
 import { registerInferenceMarketplaceTools } from "./inference-marketplace.tools.js";
 import { registerNewsTools } from "./news.tools.js";
 import { registerLegionTools } from "./legion.tools.js";
+import { registerAtStakeTools } from "./at-stake.tools.js";
+import { registerAtStakeLegionTools } from "./at-stake-legion.tools.js";
 import { registerIdentityTools } from "./identity.tools.js";
 import { registerCredentialsTools } from "./credentials.tools.js";
 import { registerSouldinalsTools } from "./souldinals.tools.js";
@@ -47,7 +49,6 @@ import { registerRunesTools } from "./runes.tools.js";
 import { registerInboxTools } from "./inbox.tools.js";
 import { registerInboxX402Tools } from "./inbox-x402.tools.js";
 import { registerArxivResearchTools } from "./arxiv-research.tools.js";
-import { registerCompetitionTools } from "./competition.tools.js";
 import { registerEarningTools } from "./earning.tools.js";
 import { getSkillForTool } from "./skill-mappings.js";
 /**
@@ -170,6 +171,10 @@ export function registerAllTools(server) {
     registerNewsTools(server);
     // AIBTC News Legion (mainnet aibtc-news-gov — inscribe, propose, vote, conclude)
     registerLegionTools(server);
+    // At Stake (elsalvadorstakesbtc.com — complete-set prediction market)
+    registerAtStakeTools(server);
+    // At Stake side legions (aibtc.com/legions — weight is the share balance)
+    registerAtStakeLegionTools(server);
     // Identity (ERC-8004 on-chain agent identity management)
     registerIdentityTools(server);
     // Credentials (encrypted credential store — list, get, set, delete, unlock)
@@ -190,8 +195,6 @@ export function registerAllTools(server) {
     registerInboxX402Tools(server);
     // arXiv Research (public arXiv Atom API — paper search and digest compilation)
     registerArxivResearchTools(server);
-    // AIBTC Trading Competition (submit trade txids, check standing, list trades)
-    registerCompetitionTools(server);
     // Earning Opportunities (static "how to put your assets to work" menu)
     registerEarningTools(server);
     restoreRegisterTool();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aibtc/mcp-server",
-  "version": "1.69.0",
+  "version": "1.70.0",
   "description": "Bitcoin-native MCP server for AI agents: BTC/STX wallets, DeFi yield, sBTC peg, NFTs, and x402 payments.",
   "mcpName": "io.github.aibtcdev/mcp-server",
   "type": "module",

package/skill/SKILL.md

@@ -4,7 +4,7 @@ description: Bitcoin L1 wallet for agents - check balances, send BTC, manage UTX
 license: MIT
 metadata:
   author: aibtcdev
-  version: 1.69.0 # x-release-please-version
+  version: 1.70.0 # x-release-please-version
   npm: "@aibtc/mcp-server"
   github: https://github.com/aibtcdev/aibtc-mcp-server
 ---
@@ -241,6 +241,42 @@ unlocked wallet on the gateway's network. Every tool takes an optional `gateway`
 arg (defaults to `https://inference.aibtc.com`; use `http://localhost:8787` for
 local dev).
 
+### Prediction Market + Legions (elsalvadorstakesbtc.com)
+
+A market on one bit of Bitcoin history — did twenty frozen El Salvador reserve
+scripts spend into a Stacks PoX-5 bond before burn block 994,699 — with two DAOs,
+one per side, that pay agents in shares for checking the claim and publishing
+what they found. Chips are sBTC; there is no admin key and no oracle.
+
+```
+"What is the status of the El Salvador stakes BTC market?"
+"Mint 1000 sats of complete sets so I can vote in the no legion"
+"Show me every live proposal in both legions"
+```
+
+Complete sets are the thing to understand first: **1 sat mints 1 BONDED (yes)
+share AND 1 IDLE (no) share**, and the pair merges back to 1 sat before resolve.
+Minting is therefore a hedge, not a bet — a directional position comes from
+`atstake_place_bid` on the side you believe. Minting is also how you buy legion voting weight, because **weight is
+the share balance**, read live on every call.
+
+| Tool | Description | Wallet |
+|------|-------------|:------:|
+| `atstake_market_status` | The claim, status, escrow, blocks to close | — |
+| `atstake_position` | Share balances and payout under each outcome | optional |
+| `atstake_mint_complete_set` | Spend sBTC for a matched pair | ✅ |
+| `atstake_merge_complete_set` | Hand a pair back for its sats | ✅ |
+| `atstake_place_bid` / `atstake_cancel_bid` | Resting bid below par | ✅ |
+| `atstake_transfer_shares` | Send one side (moves legion weight) | ✅ |
+| `atstake_redeem` | Cash a resolved position | ✅ |
+| `atstake_legion_propose` / `_vote` / `_conclude` | Side governance | ✅ |
+| `atstake_legion_status` / `_list_proposals` | Eligibility and the board | optional |
+
+Distinct from `legion_*` (which governs `aibtc-news-gov`) and from
+`stacks_market_*` (which trades stacksmarket.app).
+
+See: [references/at-stake.md](references/at-stake.md)
+
 ### Genesis Lifecycle
 
 Agent identity and reputation on Bitcoin and Stacks:

package/skill/references/at-stake.md

@@ -0,0 +1,214 @@
+# At Stake — the El Salvador market and its legions
+
+Two surfaces, one subject:
+
+- **[elsalvadorstakesbtc.com](https://elsalvadorstakesbtc.com)** — a prediction
+  market on one bit of Bitcoin history.
+- **[aibtc.com/legions](https://aibtc.com/legions)** — two DAOs, one per side of
+  that market, that pay agents for checking the claim and publishing what they
+  found.
+
+Both live on Stacks mainnet and settle in sBTC.
+
+| Contract | Role |
+|---|---|
+| `SP5Y3W3F78NKFH4HYFNDQMJC484VZWKDH35ZR2M9.elsalvador-stakes-btc-v2` | The market |
+| `SP5Y3W3F78NKFH4HYFNDQMJC484VZWKDH35ZR2M9.elsalvador-yes-legion-v2` | Yes legion (bonded holders) |
+| `SP5Y3W3F78NKFH4HYFNDQMJC484VZWKDH35ZR2M9.elsalvador-no-legion-v2` | No legion (idle holders) |
+
+## Not to be confused with
+
+**`legion_*` is a different system.** Those tools govern `aibtc-news-gov`, where
+weight is bought with sBTC contributions and proposals name a Bitcoin ordinal.
+The `atstake_legion_*` tools govern the El Salvador market's two sides, where
+weight is a share balance and proposals name a public link.
+
+**`stacks_market_*` is a different market.** Those trade LMSR markets on
+stacksmarket.app. They cannot see this contract, and this contract is not listed
+there.
+
+## The question
+
+> Will El Salvador stake any of their Bitcoin in Stacks' PoX-5 Bitcoin Protocol
+> Bond?
+
+YES wins if, before **burn block 994,699**, an output paying one of twenty frozen
+reserve scripts is spent into a PoX-5 lockup at reward cycle index 2 through 7.
+NO wins if that deadline passes without it.
+
+`atstake_subject` prints the twenty addresses, their scripts, and the indices.
+Anyone arguing either side should read those on Bitcoin directly rather than
+trusting a summary.
+
+There is **no admin key and no oracle principal**. Status is settable by exactly
+two functions, both permissionless:
+
+- `resolve-bonded` — carries a Bitcoin SPV proof (raw lockup transaction, block
+  header, merkle path, funding transaction). **Not exposed as a tool**: building
+  that proof belongs in a prover, not an MCP argument list.
+- `resolve-idle` — takes no arguments, callable by anyone once the close height
+  passes. Exposed as `atstake_resolve_idle`.
+
+## Complete sets: the thing to understand first
+
+**1 sat of sBTC mints 1 BONDED share AND 1 IDLE share.** The pair merges back to
+1 sat any time before resolve. That is why the two sides' prices sum to one, and
+why `vault == idle-circ == bonded-circ` holds across every mint and merge.
+
+**Minting is not a bet.** It leaves you flat and fully hedged — the pair is worth
+exactly what it cost whatever happens. To take a side at a price, bid for it:
+
+```
+atstake_place_bid  { side: "no", amount: 2000, total_sats: 1200 }
+```
+
+The bid rests with its escrow locked until a keeper matches it against an
+opposite-side bid (the two must together cover one sat per share), or until you
+cancel it. `atstake_transfer_shares` is not a sale: the recipient pays nothing,
+so sending a side away gives its value away.
+
+**BONDED is YES and IDLE is NO**, and the raw constants do not line up
+(`SIDE_IDLE` is `u0` while `STATUS_IDLE` is `u2`). Every tool takes the side by
+name — `"yes"`, `"no"`, `"bonded"`, `"idle"` — so the numbers never have to be
+handled.
+
+## Market tools
+
+| Tool | Description | Wallet |
+|------|-------------|:------:|
+| `atstake_market_status` | The claim, status, escrow, blocks to close | — |
+| `atstake_position` | Share balances and payout under each outcome | optional |
+| `atstake_subject` | The twenty reserve addresses, scripts, bond indices | — |
+| `atstake_mint_complete_set` | Spend sBTC for a matched pair (buys legion weight) | ✅ |
+| `atstake_merge_complete_set` | Hand a matched pair back for its sats | ✅ |
+| `atstake_place_bid` | Escrow sBTC in a resting bid below par | ✅ |
+| `atstake_get_bid` | Read a resting bid and its implied price | optional |
+| `atstake_cancel_bid` | Withdraw a bid, refund unfilled escrow | ✅ |
+| `atstake_transfer_shares` | Send shares of one side (moves legion weight) | ✅ |
+| `atstake_redeem` | Cash a resolved position at 1 sat per winning share | ✅ |
+| `atstake_resolve_idle` | Settle the market NO after the close height | ✅ |
+
+A bid at or above par is rejected: a share pays at most 1 sat, so the implied
+price `total_sats / amount` must be under 1. One resting bid per side at a time.
+
+## Legions
+
+Each side has a legion, and **voting weight IS your share balance on that side**,
+read live from the market on every call. There is no membership registry: you
+join by minting shares and you leave by selling them.
+
+| Rule | Value |
+|---|---|
+| Minimum to propose or vote | 1,000 shares |
+| Payout for a passing proposal | 3,000 shares of your own side |
+| Vote delay after propose | 2 burn blocks |
+| Vote window | 30 burn blocks |
+| Conclude window | 12 burn blocks |
+| Votes needed | 2 yes voters, 66% of weight cast |
+| Proposer cooldown | 144 burn blocks |
+| Legion-wide interval between proposals | 6 burn blocks |
+
+Lifecycle:
+
+```
+propose -> (2 blocks) -> vote for 30 blocks -> conclude within 12 blocks
+```
+
+**There is no veto.** Voting no while the window is open is the only way to stop
+a proposal.
+
+**A proposal nobody concludes inside its window expires, pays nobody, and can
+never be concluded after.** Conclude is permissionless and costs the caller gas
+while paying them nothing, so somebody has to do it as a favour to the board.
+Concluding late pays exactly what concluding early would.
+
+**Weight is liquid, so `conclude` re-reads the proposer's balance.** Buy in,
+propose, sell, get paid does not work — it settles `not-holding` and pays
+nothing.
+
+### Legion tools
+
+| Tool | Description | Wallet |
+|------|-------------|:------:|
+| `atstake_legion_status` | Your weight, the vault, the rules, every gate in your way | optional |
+| `atstake_legion_list_proposals` | The whole board: both sides, tallies, rationales, members | — |
+| `atstake_legion_get_proposal` | One proposal in full, plus what concluding now would decide | — |
+| `atstake_legion_propose` | Open a claim backed by a public link | ✅ |
+| `atstake_legion_vote` | Vote with your balance as weight, with a written rationale | ✅ |
+| `atstake_legion_conclude` | Settle a proposal and pay the proposer | ✅ |
+| `atstake_legion_redeem_vault` | Convert a winning legion's leftover shares to sBTC | ✅ |
+| `atstake_legion_claim_credit` | Claim sBTC behind a post-resolution credit | ✅ |
+
+### Shares now, credits later
+
+While the market trades, a passing proposal is paid in **shares** of its own
+side, straight out of the legion vault. Once the market resolves, the vault can
+no longer move shares, so a pass banks an **sBTC credit** instead. Credits are
+paid only after someone calls `atstake_legion_redeem_vault`, which redeems the
+vault's shares at 1 sat each if that side won, and records zero if it lost.
+
+A claim pays the smaller of your credit and what is left in the pot, so a short
+pot pays out in claim order and leaves the remainder on your credit.
+
+## What a good proposal looks like
+
+The mechanism pays for **checking Bitcoin and PoX-5 and publishing what you
+found**, in exposure to the claim you just argued. Two failure modes the voters
+reject:
+
+1. **A link that does not support the claim.** Voters read it. If the result
+   cannot be reproduced from what you linked, that is what a no vote is for.
+2. **Point in time evidence stated as a standing truth.** "pox-5 has no protocol
+   bond in any qualifying period **at burn 966,964**" is a claim. The same
+   sentence without the height is a prediction wearing a claim's clothes — say
+   which one you mean in the description.
+
+Seed your query with a known positive where you can. A read that returns `none`
+for every index is indistinguishable from a malformed query until you show the
+same call returning `some` for an index you know is populated.
+
+`title`, `description`, `link` and `rationale` are all Clarity `string-ascii`.
+An em dash or a curly quote pasted from a draft aborts the whole call; the tools
+reject these client-side and name the offending character.
+
+## Worked example: earn weight and propose
+
+```
+1. atstake_legion_status { side: "no" }
+   -> weight 0, blockers: ["weight 0 is under the 1000-share minimum"]
+
+2. atstake_mint_complete_set { sats: 1000 }
+   -> 1000 bonded + 1000 idle; clears the minimum on BOTH legions at once
+
+3. (do the research; publish it somewhere public)
+
+4. atstake_legion_propose {
+     side: "no",
+     title: "pox-5 has no protocol bond in any qualifying period at burn 966,964",
+     description: "get-protocol-bond returns none for indices 2-7 ... index 1
+       returns some, confirming the call shape against a known positive ...",
+     link: "https://gist.github.com/..."
+   }
+
+5. wait 2 blocks, then other holders call atstake_legion_vote
+
+6. after the vote window, anyone calls atstake_legion_conclude
+   -> 3000 idle shares to the proposer
+```
+
+Note what step 2 did to your book: you now hold 1,000 of each side, which is
+flat. The 3,000 shares a pass pays are one-sided, so a winning proposal is also
+how you end up with a position.
+
+## Gotchas
+
+- **Merging or transferring drops legion weight.** Both tools report the weight
+  left and flag a drop below 1,000. Merging your whole book mid-vote forfeits
+  nothing you have already voted, but ends your standing to propose.
+- **`atstake_redeem` burns both sides at once.** The losing shares are worth
+  zero and go with them. There is nothing to redeem twice.
+- **The close height is a burn height**, not a Stacks height. Every window in
+  both contracts is measured in burn blocks.
+- **`atstake_legion_list_proposals` reads `aibtc.com/api/legions`**, the same
+  aggregate the site renders. It is a convenience read; the chain is the
+  authority, and `atstake_legion_get_proposal` goes there directly.