paralith-mcp 0.4.5 → 0.4.6

package/dist/http.mjs

@@ -305,8 +305,62 @@ import { z as z9 } from "zod";
 // src/tool.mjs
 import { z } from "zod";
 
+// package.json
+var package_default = {
+  name: "paralith-mcp",
+  version: "0.4.6",
+  description: "MCP server for Paralith on AO: an AI with one 24-word phrase plays Rune Realm, trades and bridges PUSD; plus paralith-bridge, the bridge operator CLI (TEST deployment).",
+  license: "UNLICENSED",
+  homepage: "https://docs.paralithmarkets.com/ai/mcp",
+  keywords: [
+    "mcp",
+    "model-context-protocol",
+    "ao",
+    "hyperbeam",
+    "arweave",
+    "game",
+    "agent"
+  ],
+  type: "module",
+  bin: {
+    "paralith-mcp": "dist/server.mjs",
+    "paralith-bridge": "dist/bridge.mjs"
+  },
+  files: [
+    "dist",
+    "README.md"
+  ],
+  publishConfig: {
+    access: "public"
+  },
+  scripts: {
+    build: "node scripts/build-client.mjs && node scripts/tools-doc.mjs",
+    "tools-doc": "node scripts/tools-doc.mjs",
+    start: "node src/server.mjs",
+    "start:http": "node src/http.mjs",
+    test: "node --test test/*.test.mjs"
+  },
+  engines: {
+    node: ">=20"
+  },
+  dependencies: {
+    "@modelcontextprotocol/ext-apps": "^2.0.3",
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "@mysten/sui": "^2.34.0",
+    "@scure/bip39": "^2.4.0",
+    "@solana/web3.js": "^1.99.0",
+    "arweave-mnemonic-keys": "^0.0.9",
+    lodash: "^4.18.1",
+    viem: "^2.57.3",
+    zod: "^4.6.5"
+  },
+  devDependencies: {
+    esbuild: "^0.28.2"
+  }
+};
+
 // src/update.mjs
-var VERSION = "0.4.2";
+var VERSION = package_default.version;
 var CHECK_MS = 6 * 36e5;
 var NOTE_MS = 36e5;
 var latest = null;
@@ -443,13 +497,20 @@ function side(s) {
     freeMovesUsed: Object.keys(s.freeUsed ?? {})
   };
 }
+function sideOf(b, address) {
+  if (!address) return null;
+  if ((b.accepterAddress ?? b.accepter?.address) === address) return "accepter";
+  if ((b.challengerAddress ?? b.challenger?.address) === address) return "challenger";
+  return null;
+}
 function battle(b, address) {
   if (!b || typeof b !== "object") return b;
-  const mine = b.accepterAddress === address ? "accepter" : "challenger";
+  const mine = sideOf(b, address);
   const theirs = mine === "accepter" ? "challenger" : "accepter";
+  const label = (s) => !mine ? s : s === mine ? "you" : "opponent";
   const turns = (b.turns ?? []).filter((t) => t.round === b.round - 1 || t.round === b.round).map((t) => ({
     round: t.round,
-    by: t.attacker === mine ? "you" : "opponent",
+    by: label(t.attacker),
     move: t.move,
     damage: t.healthDamage,
     shieldDamage: t.shieldDamage,
@@ -458,6 +519,7 @@ function battle(b, address) {
     superEffective: t.superEffective,
     notEffective: t.notEffective
   }));
+  const sides = mine ? { you: side(b[mine]), opponent: side(b[theirs]) } : { challenger: side(b.challenger), accepter: side(b.accepter) };
   return {
     id: b.id,
     kind: b.kind,
@@ -465,8 +527,7 @@ function battle(b, address) {
     round: b.round,
     ...b.winner ? { winner: b.winner } : {},
     ...b.waitingOn?.length ? { waitingOn: b.waitingOn } : {},
-    you: side(b[mine]),
-    opponent: side(b[theirs]),
+    ...sides,
     recentTurns: turns
   };
 }
@@ -483,22 +544,31 @@ function hunt(run) {
 // src/game.mjs
 var FACTIONS = ["Sky Nomads", "Aqua Guardians", "Inferno Blades", "Stone Titans"];
 var BERRIES = ["air_berry", "fire_berry", "rock_berry", "water_berry"];
+var SHOP_ITEMS = [...BERRIES, "scroll", "rune"];
 async function me() {
   const { api, wallets } = await runtime();
   return { api, address: wallets?.ao.address };
 }
-async function player2() {
-  const { api, address } = await me();
-  if (!address) throw new Error("This server has no wallet; pass an address or battle_id.");
-  const p = await api.readPlayer(address);
-  if (!p) throw new Error("This wallet has no Rune Realm account yet. Call game_join first.");
+async function player2(address) {
+  const { api, address: mine } = await me();
+  const who = address ?? mine;
+  if (!who) throw new Error("This server has no wallet; pass an address.");
+  const p = await api.readPlayer(who);
+  if (!p) throw new Error(address ? `${address} has no Rune Realm account.` : "This wallet has no Rune Realm account yet. Call game_join first.");
   return p;
 }
+async function findBattle(id) {
+  const fleet = await readKey("game", "battlefleet").catch(() => null);
+  const workers = (fleet?.workers ?? []).map((w) => w.workerProcessId).filter(Boolean);
+  const found = await Promise.all([readKey("game", `battle-op-${id}`), ...workers.map((w) => readKey(w, `battle-${id}`))].map((read) => read.catch(() => null)));
+  return found.find((b) => b && typeof b === "object") ?? null;
+}
+var seenBy = (b, address) => b && typeof b === "object" ? Object.defineProperty(b, "viewer", { value: address, enumerable: false, configurable: true }) : b;
 function registerGame(server) {
   tool(
     server,
     "game_player",
-    "Read a Rune Realm player record (yours by default): gold, runes, inventory, companions with energy/happiness/level/moves, pending move offers, loot boxes, and any live arena (battleFleet) or hunt route. Free, unsigned. Call this before deciding anything.",
+    "Read a Rune Realm player record (yours by default): gold, inventory, companions with energy/happiness/level/moves and pendingMoveOffer, loot boxes, arena record with arena.liveBattle, and liveHunt. Free, unsigned. Call this before deciding anything.",
     { address: z2.string().optional().describe("Another player's AO address; omit for yours.") },
     async ({ address }) => {
       const { api, address: mine } = await me();
@@ -514,7 +584,13 @@ function registerGame(server) {
     "game_catalog",
     "The game rules as data: activity costs/gains, arena terms, element effectiveness, free moves (Rally, Mend), hunt capture odds, items, level-up rules and every move pool. Free, unsigned.",
     {},
-    async () => (await me()).api.readCatalog(),
+    async () => {
+      const catalog = await (await me()).api.readCatalog();
+      if (catalog?.levelUp) {
+        catalog.levelUp = { ...catalog.levelUp, costDivisor: 32, cost: "ceil(targetLevel^2 / 32) Rune" };
+      }
+      return catalog;
+    },
     READ
   );
   tool(
@@ -536,7 +612,11 @@ function registerGame(server) {
         factions: factions?.map(({ members, ...f }) => f),
         arenaTiers: tiers,
         openChallenges: challenges,
-        leaderboard: leaderboard?.slice(0, 10)
+        leaderboard: leaderboard?.slice(0, 10).map(({ monster, ...row }) => {
+          if (!monster) return row;
+          const { exp, energy, happiness, ...companion2 } = companion(monster);
+          return { ...row, companion: companion2 };
+        })
       };
     },
     READ
@@ -553,7 +633,7 @@ function registerGame(server) {
   tool(
     server,
     "game_companion",
-    "Care for and manage companions. feed: 1 berry, +10 energy. play: 10 energy + 1 berry, +25 happiness after 15 min. quest: 25 energy + 25 happiness, 1 h, then exp and Gold. claim: collect a finished play/quest. store (1 Rune) / retrieve / set_active / transfer manage the collection. adopt: once, if you have a faction but no companion.",
+    "Care for and manage companions. feed: 1 berry, +20 energy for a berry of its own element, +10 for any other. play: 10 energy + 1 berry, +25 happiness after 15 min. quest: 25 energy + 25 happiness, 1 h, then exp and Gold. claim: collect a finished play/quest. store (1 Rune; moves a companion into the collection) / retrieve / set_active / transfer manage the collection. adopt: once, if you have a faction but no companion.",
     {
       action: z2.enum(["feed", "play", "quest", "claim", "adopt", "store", "retrieve", "set_active", "transfer"]),
       monster_id: z2.string().optional().describe("Companion id; omit for the active one."),
@@ -589,7 +669,7 @@ function registerGame(server) {
   tool(
     server,
     "game_level_up",
-    "Level up the active companion when it has enough exp. Costs Rune. Allocate exactly the points the catalog says (levelUp.points), at most levelUp.maxPerStat in any one stat.",
+    "Level up the active companion when it has enough exp. Costs ceil(L^2/32) in-game Rune for target level L (1 up to level 5, 4 at 10, 13 at 20). Allocate exactly the points the catalog says (levelUp.points), at most levelUp.maxPerStat in any one stat. A pending move offer expires at the next level-up.",
     { attack: z2.number().int().min(0), defense: z2.number().int().min(0), speed: z2.number().int().min(0), health: z2.number().int().min(0) },
     async (points) => (await me()).api.levelUp(points),
     WRITE,
@@ -598,7 +678,7 @@ function registerGame(server) {
   tool(
     server,
     "game_learn_move",
-    "Answer a pending move offer (every 5th level). Give replace to swap that move out; omit replace to decline. Final either way.",
+    "Answer a pending move offer (every 5th level). Give replace to swap that move out; omit replace to decline. Final either way. An unanswered offer expires at the next level-up.",
     { move: z2.string().describe("The offered move, exactly as in the player record."), replace: z2.string().optional() },
     async ({ move, replace }) => (await me()).api.learnMove(move, replace),
     WRITE,
@@ -622,27 +702,31 @@ function registerGame(server) {
     WRITE,
     asPlayer
   );
+  tool(
+    server,
+    "game_shop_quote",
+    "The NPC realm shop's current Gold prices (bid/ask) and stock for berries, Scrolls and Rune. Free, unsigned.",
+    {},
+    async () => (await me()).api.readEconomy(),
+    READ
+  );
   tool(
     server,
     "game_shop",
-    "Trade with the NPC realm shop for Gold. quote returns current prices and stock (free). buy/sell trades; set max_total/min_total to bound slippage.",
+    "Buy from or sell to the NPC realm shop for Gold (prices: game_shop_quote). Set max_total/min_total to bound slippage.",
     {
-      action: z2.enum(["quote", "buy", "sell"]),
-      item: z2.string().optional().describe("Item id, e.g. fire_berry or scroll."),
-      quantity: z2.number().int().positive().optional(),
+      action: z2.enum(["buy", "sell"]),
+      item: z2.enum(SHOP_ITEMS),
+      quantity: z2.number().int().positive(),
       max_total: z2.number().int().optional(),
       min_total: z2.number().int().optional()
     },
-    async ({ action, item, quantity, max_total, min_total }) => {
-      const { api } = await me();
-      if (action === "quote") return api.readEconomy();
-      return api.tradeGameShop(
-        action,
-        need(item, "item"),
-        need(quantity, "quantity"),
-        { maxTotal: max_total, minTotal: min_total }
-      );
-    },
+    async ({ action, item, quantity, max_total, min_total }) => (await me()).api.tradeGameShop(
+      action,
+      item,
+      quantity,
+      { maxTotal: max_total, minTotal: min_total }
+    ),
     WRITE,
     asPlayer
   );
@@ -688,13 +772,23 @@ function registerGame(server) {
   tool(
     server,
     "arena_battle",
-    "Read the current battle: both sides' health, moves with uses left, round number and log. Free. Defaults to your live battle.",
-    { battle_id: z2.string().optional() },
-    async ({ battle_id }) => {
-      const { api } = await me();
-      const id = battle_id ?? (await player2()).battleFleet?.battleId;
-      if (!id) return { battle: null, note: "No live battle. Use arena_fight to start one." };
-      return api.readBattle(id);
+    "Read a battle: both sides' health, moves with uses left, round number and recent turns. Free. Defaults to your live battle; address reads that player's live battle; battle_id reads one battle directly (finished fights stay readable only briefly).",
+    {
+      address: z2.string().optional().describe("Whose live battle; omit for yours."),
+      battle_id: z2.string().optional().describe("A specific battle, e.g. from game_player arena.liveBattle.")
+    },
+    async ({ address, battle_id }) => {
+      const { api, address: mine } = await me();
+      const viewer = address ?? mine;
+      if (battle_id) {
+        const b = await findBattle(battle_id);
+        return b ? seenBy(b, viewer) : { battle: null, note: `No battle ${battle_id} on the game or any battle worker.` };
+      }
+      if (!viewer) throw new Error("This server has no wallet; pass address or battle_id.");
+      const p = await player2(viewer);
+      const id = p.battleFleet?.battleId ?? p.activeBattleId;
+      if (!id) return { battle: null, note: address ? `${address} has no live battle.` : "No live battle. Use arena_fight to start one." };
+      return seenBy(p.battle?.id === id ? p.battle : await api.readBattle(id), viewer);
     },
     READ,
     battleView
@@ -732,7 +826,7 @@ function registerGame(server) {
   tool(
     server,
     "hunt_begin",
-    "Start a hunt with a companion. Escrows 2 of each berry; Rune and a Scroll are spent only if you try to capture.",
+    "Start a hunt with a companion. Entry fee: 2 of each berry, not refunded. Up to 3 Rune and 1 Scroll go with the run and come back when it ends, unless a capture spends them.",
     { monster_id: z2.string().describe("Companion to hunt with (see game_player).") },
     async ({ monster_id }) => (await me()).api.beginHunt(monster_id),
     WRITE,
@@ -741,14 +835,14 @@ function registerGame(server) {
   tool(
     server,
     "hunt_state",
-    "Read your live hunt run: encounter, wild creature, round, status. Free.",
-    {},
-    async () => {
+    "Read a live hunt run (yours by default): encounter, wild creature, round, status. Free.",
+    { address: z2.string().optional().describe("Another player's AO address; omit for yours.") },
+    async ({ address }) => {
       const { api } = await me();
-      const route = (await player2()).hunt;
-      return route ? api.readHunt(route) : { hunt: null, note: "No live hunt. Use hunt_begin." };
+      const route = (await player2(address)).hunt;
+      return route ? api.readHunt(route) : { hunt: null, note: address ? `${address} has no live hunt.` : "No live hunt. Use hunt_begin." };
     },
-    OWN,
+    READ,
     huntView
   );
   tool(
@@ -783,12 +877,24 @@ function registerGame(server) {
     WRITE,
     huntView
   );
+  tool(
+    server,
+    "companion_market_browse",
+    "The companion market (priced in in-game Rune): current listings and recent sales. Free, unsigned.",
+    {},
+    async () => {
+      const { api } = await me();
+      const [listings, history] = await Promise.all([api.readMarket(), api.readMarketHistory()]);
+      return { listings, history };
+    },
+    READ
+  );
   tool(
     server,
     "companion_market",
-    "The companion market (priced in in-game Rune). browse: listings and recent sales (free). list: sell a companion. buy / cancel: by listing_id.",
+    "Trade companions for in-game Rune (listings: companion_market_browse). list: sell a companion from your collection (never the active one; game_companion store moves it there for 1 Rune). buy / cancel: by listing_id.",
     {
-      action: z2.enum(["browse", "list", "buy", "cancel"]),
+      action: z2.enum(["list", "buy", "cancel"]),
       monster_id: z2.string().optional(),
       price: z2.number().int().min(1).max(1e6).optional(),
       listing_id: z2.string().optional()
@@ -796,8 +902,6 @@ function registerGame(server) {
     async ({ action, monster_id, price, listing_id }) => {
       const { api } = await me();
       switch (action) {
-        case "browse":
-          return { listings: await api.readMarket(), history: await api.readMarketHistory() };
         case "list":
           return api.listMonster(need(monster_id, "monster_id"), need(price, "price"));
         case "buy":
@@ -825,7 +929,7 @@ function registerGame(server) {
   tool(
     server,
     "element_claim",
-    "Claim today's free TEST element tokens. Each wallet gets one element per UTC day, chosen by the contract; this claims it.",
+    "Claim today's free TEST element tokens: 1-10 of one element (chosen by the contract) per wallet per UTC day, until that element's 2,000-token daily cap across all wallets is spent; after that, claims are refused until the next day.",
     {},
     async () => {
       const { api, address } = await me();
@@ -836,9 +940,7 @@ function registerGame(server) {
   );
 }
 var asPlayer = (r) => r?.address && r?.inventory ? player(r) : r;
-async function battleView(b) {
-  return b?.id ? battle(b, (await me()).address) : b;
-}
+var battleView = (b) => b?.id ? battle(b, b.viewer) : b;
 async function attackView(p) {
   if (!p?.address) return p;
   const { address, gold, battlesRemaining, wins, losses, arenaLast } = p;
@@ -879,10 +981,17 @@ function toWire(t, m, price, quantity) {
   const baseAtoms = parseAmount(quantity, baseDen);
   if (baseAtoms % lot !== 0n) throw new Error(`Quantity moves in steps of ${formatAtoms(lot, baseDen)} ${m.base}.`);
   const perUnit = parseAmount(price, t.den(m.quote));
-  const perLot = perUnit * lot / 10n ** BigInt(baseDen);
-  if (perLot <= 0n) throw new Error("Price is below one quote atom per lot.");
-  return { lots: (baseAtoms / lot).toString(), perLot: perLot.toString() };
+  const unit = 10n ** BigInt(baseDen);
+  const tick = BigInt(Math.max(1, Number(m.tick ?? 1)));
+  const scaled = perUnit * lot;
+  if (scaled % unit !== 0n || scaled / unit % tick !== 0n) {
+    const step = tick * unit % lot === 0n ? formatAtoms(tick * unit / lot, t.den(m.quote)) : null;
+    throw new Error(step ? `Price moves in steps of ${step} ${m.quote} per ${m.base}.` : `Price must be a whole multiple of ${tick} ${m.quote} atoms per lot of ${formatAtoms(lot, baseDen)} ${m.base}.`);
+  }
+  return { lots: (baseAtoms / lot).toString(), perLot: (scaled / unit).toString() };
 }
+var unitPrice = (t, m, perLot) => formatAtoms(BigInt(perLot) * 10n ** BigInt(t.den(m.base)) / BigInt(m.lot), t.den(m.quote));
+var units = (t, m, lots) => formatAtoms(BigInt(lots) * BigInt(m.lot), t.den(m.base));
 var human = (t, free) => Object.fromEntries(Object.entries(free ?? {}).map(([asset, atoms]) => [asset, formatAtoms(atoms, t.den(asset))]));
 function registerExchange(server) {
   tool(
@@ -907,22 +1016,21 @@ function registerExchange(server) {
       const { api } = await runtime();
       const book = (await api.readVenueBook(t.process))?.[m.id];
       if (!book) return { market: m.id, book: null };
-      const unitPrice = (perLot) => formatAtoms(BigInt(perLot) * 10n ** BigInt(t.den(m.base)) / BigInt(m.lot), t.den(m.quote));
-      const units = (lots) => formatAtoms(BigInt(lots) * BigInt(m.lot), t.den(m.base));
-      const level = (l) => ({ price: unitPrice(l.price), quantity: units(l.quantity), orders: l.orders });
+      const price = (perLot) => unitPrice(t, m, perLot);
+      const level = (l) => ({ price: price(l.price), quantity: units(t, m, l.quantity), orders: l.orders });
       return {
         market: m.id,
         units: `price in ${m.quote} per 1 ${m.base}; quantity in ${m.base}`,
-        bestBid: book.bestBid ? unitPrice(book.bestBid) : null,
-        bestAsk: book.bestAsk ? unitPrice(book.bestAsk) : null,
+        bestBid: book.bestBid ? price(book.bestBid) : null,
+        bestAsk: book.bestAsk ? price(book.bestAsk) : null,
         bids: (book.depth?.bids ?? []).slice(0, 10).map(level),
         asks: (book.depth?.asks ?? []).slice(0, 10).map(level),
-        band: book.band && { low: unitPrice(book.band.low), high: unitPrice(book.band.high) },
+        band: book.band && { low: price(book.band.low), high: price(book.band.high) },
         today: book.candles?.at(-1) && {
-          open: unitPrice(book.candles.at(-1).o),
-          high: unitPrice(book.candles.at(-1).h),
-          low: unitPrice(book.candles.at(-1).l),
-          close: unitPrice(book.candles.at(-1).c),
+          open: price(book.candles.at(-1).o),
+          high: price(book.candles.at(-1).h),
+          low: price(book.candles.at(-1).l),
+          close: price(book.candles.at(-1).c),
           trades: book.candles.at(-1).n
         }
       };
@@ -932,7 +1040,7 @@ function registerExchange(server) {
   tool(
     server,
     "exchange_position",
-    "Balances at a venue (free, in orders) with open orders and recent fills; yours unless address is given. Free.",
+    "Balances at a venue (free, and where each asset sits) with open orders and recent fills, all in human units; yours unless address is given. Free.",
     { venue: VENUE, address: z3.string().optional() },
     async ({ venue, address }) => {
       const t = await terms(venue);
@@ -940,7 +1048,33 @@ function registerExchange(server) {
       const who = address ?? wallets?.ao.address;
       if (!who) throw new Error("This server has no wallet; pass an address.");
       const p = await api.readVenuePosition(t.process, who);
-      return { ...p, freeUnits: human(t, p.free) };
+      const market = (row) => t.markets[row.market] ?? marketFor(t, row.item);
+      const order = ({ lot, ...o }) => {
+        const m = { ...market(o), ...lot ? { lot } : {} };
+        return {
+          ...o,
+          price: unitPrice(t, m, o.price),
+          quantity: units(t, m, o.quantity),
+          ...o.remaining !== void 0 ? { remaining: units(t, m, o.remaining) } : {}
+        };
+      };
+      const fill = (f) => {
+        const m = market(f);
+        return {
+          ...f,
+          price: unitPrice(t, m, f.price),
+          quantity: units(t, m, f.quantity),
+          ...f.fee !== void 0 ? { fee: formatAtoms(BigInt(f.fee), t.den(m.quote)) } : {}
+        };
+      };
+      return {
+        account: p.account ?? who,
+        units: "price in quote per 1 base unit; quantity in base units; fee in quote",
+        free: human(t, p.free),
+        ...p.locations ? { locations: Object.fromEntries(Object.entries(p.locations).map(([asset, at]) => [asset, Object.fromEntries(Object.entries(at).map(([where, atoms]) => [where, formatAtoms(atoms, t.den(asset))]))])) } : {},
+        orders: (p.orders ?? []).map(order),
+        fills: (p.fills ?? []).map(fill)
+      };
     },
     READ
   );
@@ -2005,29 +2139,33 @@ var INSTRUCTIONS = `Paralith on AO (HyperBEAM): Rune Realm (a companion game), t
 Everything is TEST-prefixed while unreleased. Reads are free; every write is a signed message (a few seconds round trip, longer under load).
 
 Start: wallet -> game_player. No account? game_join (pick a faction).
-Core loop: game_daily once a day; game_companion feed/play/quest/claim to keep energy and happiness up and earn exp and Gold;
-game_level_up when exp allows; game_learn_move when an offer is pending.
+Core loop: game_daily once a day; game_companion feed/play keep energy and happiness up, quest then claim earns exp and Gold;
+game_level_up when exp allows; game_learn_move when an offer is pending (it expires at the next level-up).
 Arena: arena_enter (25 energy + 25 happiness, 4 fights), arena_fight mode=bot, then arena_attack each round
 (read arena_battle for moves and uses left; Rally and Mend are free once each), arena_end leave when done.
-Hunt: hunt_begin -> hunt_act search -> attack until defeated -> capture (1-3 Rune + a Scroll) or end. One encounter per hunt.
+Hunt: hunt_begin (entry fee 2 of each berry, not refunded; up to 3 Rune + 1 Scroll set aside and returned unless a capture spends them)
+-> hunt_act search -> attack until defeated -> capture (1-3 Rune + a Scroll) or end. One encounter per hunt.
 Markets: exchange_markets / exchange_book / exchange_order on venue "game" (items vs Gold) or "token" (elements vs TEST-RUNE).
 Vaults (pooled liquidity, one amm/active/grid per market): vault_list, vault_position, vault_deposit, vault_shares (withdraw/lock/burn), vault_fund, vault_crank.
 Rune: rune_move withdraw (game -> token) / deposit (token -> game). Bridge: bridge_balances, bridge_faucet, bridge_deposit, bridge_redeem.
 DAO (stake TEST-RUNE; a passed proposal may send one attached message): dao_info, dao_proposals, dao_stake stake/unstake/withdraw, dao_propose, dao_vote.
 
 HOW RESOURCES FLOW. When asked for a resource, find its path here, check what you hold (progress), then say the route before acting.
-- Gold (in-game only, never leaves the game). Earn: companion play/quest/claim (capped at 60 Gold per 20 h), arena bot wins,
-  selling berries/Scrolls/Rune to the shop (game_shop sell) or on the game venue. Spend: arena stakes, shop buys, game-venue buys.
+- Gold (in-game only, never leaves the game). Earn: quest claims and arena bot wins, which share one 60 Gold allowance per 20 h
+  (play pays happiness only); selling berries/Scrolls/Rune to the shop (game_shop sell) or on the game venue.
+  Spend: arena stakes, shop buys, game-venue buys.
 - Berries and Scrolls. Get: joining, crates (game_daily, game_lootbox), buying with Gold (game_shop, or exchange_order venue "game").
-  Use: feed the companion, hunt escrow (2 of each berry), arena boosts; a Scroll plus 1-3 Rune for a hunt capture.
+  Use: feed the companion, the hunt entry fee (2 of each berry), arena boosts; a Scroll plus 1-3 Rune for a hunt capture.
 - Rune exists twice: in-game Rune and the TEST-RUNE wallet token; rune_move converts 1:1 either way.
-  Get Rune: (1) the shop, only if game_shop quote shows an ask (it often only bids); (2) sell a companion on companion_market;
-  (3) the token route, which always works: element_claim (free daily, 1-10 of one element) -> exchange_order venue "token"
-  sell that element for TEST-RUNE -> rune_move deposit. Public TEST accounts accrue no Rune from game_daily (pass holders only).
-  Spend in-game Rune: game_level_up, hunt capture, companion_market buys. TEST-RUNE: token-venue buys, vaults, dao_stake.
+  Get Rune: (1) the shop, only if game_shop_quote shows an ask (it often only bids); (2) sell a companion on companion_market;
+  (3) the token route: element_claim (free, 1-10 of one element per wallet per UTC day until that element's 2,000/day
+  global cap is spent) -> exchange_order venue "token" sell that element for TEST-RUNE -> rune_move deposit.
+  Public TEST accounts accrue no Rune from game_daily (pass holders only).
+  Spend in-game Rune: game_level_up (ceil(L^2/32) for level L), hunt capture, companion_market buys, game_companion store (1 Rune).
+  TEST-RUNE: token-venue buys, vaults, dao_stake.
 - Element tokens (TEST-EARTH/AIR/FIRE/WATER): element_claim daily; trade against TEST-RUNE on the token venue; vault liquidity.
 - PUSD: bridge in TEST-USDC from Base, Solana or Sui (needs that chain's gas, which the user funds; bridge_faucet gives TEST-USDC).
-  No PUSD market is listed yet. Redeeming back out needs a release claim this server cannot submit yet: say so rather than start it.
+  No PUSD market is listed yet. bridge_redeem waits for k attestor signatures and submits the release (needs destination-chain gas).
 - Vaults: deposit both sides of a market to earn from its strategy; withdraw with vault_shares.
 
 To report how you (or every agent set up on this machine) are doing, call progress (who: "all" for every agent); it also lists what needs doing next.
@@ -2038,14 +2176,28 @@ Show once per thing, not once per round.
 
 Rules: if a tool says a write WAS accepted but unconfirmed, never resend it; re-read state instead.
 A refusal ({"error": ...}) costs nothing. Use game_catalog for exact costs and move stats; docs at ${DOCS}/llms-full.txt.`;
-var READ_ONLY_NOTE = `This endpoint is READ-ONLY: it explains the protocol and reads live state for any address.
-To play, trade or bridge, run the local server with a wallet phrase: ${DOCS}/ai/mcp`;
+var READ_ONLY_INSTRUCTIONS = `This endpoint is READ-ONLY: it explains the protocol and reads live state for any address, free.
+To play, trade or bridge, run the local server with a wallet phrase: ${DOCS}/ai/mcp
+
+Paralith on AO (HyperBEAM): Rune Realm (a companion game), two order books, and the PUSD bridge.
+Everything is TEST-prefixed while unreleased. Pass an address wherever a tool takes one.
+
+- Game: game_player (account, companions, live battle or hunt), game_catalog (rules, costs, move stats),
+  game_world (factions, arena tiers, open challenges, leaderboard), arena_battle (address or battle_id), hunt_state (address),
+  game_shop_quote (NPC shop prices and stock), companion_market_browse (listings and recent sales).
+- Markets: exchange_markets / exchange_book / exchange_position on venue "game" (items vs Gold) or "token" (elements vs TEST-RUNE);
+  vault_list, vault_position.
+- Bridge and DAO: bridge_info, bridge_status, dao_info, dao_proposals, dao_stake_info.
+- Anything else: progress (one address across everything), read_state (any published key), protocol_docs.
+
+SHOW IT. Watching beats reading: call show for anything worth seeing (a fight as it happens, a companion, a book, a vault,
+a bridge transfer). It displays inline where the client supports it, otherwise it opens in the user's browser.
+
+Docs: ${DOCS}/llms-full.txt.`;
 function buildServer() {
   const server = new McpServer(
     { name: "paralith", version: VERSION },
-    { instructions: READ_ONLY ? `${READ_ONLY_NOTE}
-
-${INSTRUCTIONS}` : INSTRUCTIONS }
+    { instructions: READ_ONLY ? READ_ONLY_INSTRUCTIONS : INSTRUCTIONS }
   );
   tool(
     server,
@@ -2072,7 +2224,7 @@ ${INSTRUCTIONS}` : INSTRUCTIONS }
   tool(
     server,
     "read_state",
-    `Read any published key of any process, free: /<process>~process@1.0/now/<key>. process is an id or an alias (${Object.keys(PROCESS_ALIASES).join(", ")}). Returns null when absent.`,
+    `Read any published key of any process, free: /<process>~process@1.0/now/<key>. process is an id or an alias (${Object.keys(PROCESS_ALIASES).join(", ")}). Returns null when absent. Common keys: game: player-<address>, catalogref (the catalog's id, not catalog), leaderboard, factions, arenatiers, challenges, economy, economybook, market, markethistory, battlefleet, huntconfig, access. rune and *-token: balance-<address>, tokeninfo (not info), totalsupply. pusd: balance-<address>, bridgeinfo, withdrawals. dao: daoinfo, proposals. game-venue and token-venue: balance-<address>, vaultinfo, vaultpairs.`,
     { process: z9.string(), key: z9.string() },
     async ({ process: process2, key }) => readKey(process2, key),
     READ
@@ -2080,7 +2232,7 @@ ${INSTRUCTIONS}` : INSTRUCTIONS }
   tool(
     server,
     "send_message",
-    "Escape hatch: sign and send a raw message to any process and return its reply. Prefer the specific tools; use this only for an action they do not cover. Tag values must be strings; never use a tag named Target.",
+    "Escape hatch: sign and send a raw message to any process and return its reply. Prefer the specific tools; use this only for an action they do not cover. Tag values must be strings; never use a tag named Target, Signature or Epoch.",
     {
       process: z9.string(),
       tags: z9.record(z9.string(), z9.string()).describe('e.g. {"Action": "Pass.Info"}'),
@@ -2088,7 +2240,8 @@ ${INSTRUCTIONS}` : INSTRUCTIONS }
       push_outbox: z9.boolean().optional().describe("Deliver the messages this one emits to other processes (e.g. a Transfer to a process).")
     },
     async ({ process: process2, tags: tags2, data, push_outbox }) => {
-      if (Object.keys(tags2).some((k) => k.toLowerCase() === "target")) throw new Error("Target is not a usable tag name.");
+      const reserved = Object.keys(tags2).find((k) => ["target", "signature", "epoch"].includes(k.toLowerCase().replace(/[-_]/g, "")));
+      if (reserved) throw new Error(`${reserved} is not a usable tag name (Target, Signature and Epoch are reserved).`);
       const { api } = await runtime();
       return api.rawSend(
         Object.entries(tags2).map(([name, value]) => ({ name, value })),

package/dist/server.mjs

@@ -506,6 +506,65 @@ var init_runtime = __esm({
   }
 });
 
+// package.json
+var package_default;
+var init_package = __esm({
+  "package.json"() {
+    package_default = {
+      name: "paralith-mcp",
+      version: "0.4.6",
+      description: "MCP server for Paralith on AO: an AI with one 24-word phrase plays Rune Realm, trades and bridges PUSD; plus paralith-bridge, the bridge operator CLI (TEST deployment).",
+      license: "UNLICENSED",
+      homepage: "https://docs.paralithmarkets.com/ai/mcp",
+      keywords: [
+        "mcp",
+        "model-context-protocol",
+        "ao",
+        "hyperbeam",
+        "arweave",
+        "game",
+        "agent"
+      ],
+      type: "module",
+      bin: {
+        "paralith-mcp": "dist/server.mjs",
+        "paralith-bridge": "dist/bridge.mjs"
+      },
+      files: [
+        "dist",
+        "README.md"
+      ],
+      publishConfig: {
+        access: "public"
+      },
+      scripts: {
+        build: "node scripts/build-client.mjs && node scripts/tools-doc.mjs",
+        "tools-doc": "node scripts/tools-doc.mjs",
+        start: "node src/server.mjs",
+        "start:http": "node src/http.mjs",
+        test: "node --test test/*.test.mjs"
+      },
+      engines: {
+        node: ">=20"
+      },
+      dependencies: {
+        "@modelcontextprotocol/ext-apps": "^2.0.3",
+        "@modelcontextprotocol/sdk": "^1.32.1",
+        "@mysten/sui": "^2.34.0",
+        "@scure/bip39": "^2.4.0",
+        "@solana/web3.js": "^1.99.0",
+        "arweave-mnemonic-keys": "^0.0.9",
+        lodash: "^4.18.1",
+        viem: "^2.57.3",
+        zod: "^4.6.5"
+      },
+      devDependencies: {
+        esbuild: "^0.28.2"
+      }
+    };
+  }
+});
+
 // src/update.mjs
 function check(now) {
   checkedAt = now;
@@ -523,7 +582,8 @@ function updateNote(now = Date.now()) {
 var VERSION, CHECK_MS, NOTE_MS, latest, checkedAt, notedAt, newer;
 var init_update = __esm({
   "src/update.mjs"() {
-    VERSION = "0.4.2";
+    init_package();
+    VERSION = package_default.version;
     CHECK_MS = 6 * 36e5;
     NOTE_MS = 36e5;
     latest = null;
@@ -651,13 +711,20 @@ function side(s) {
     freeMovesUsed: Object.keys(s.freeUsed ?? {})
   };
 }
+function sideOf(b, address) {
+  if (!address) return null;
+  if ((b.accepterAddress ?? b.accepter?.address) === address) return "accepter";
+  if ((b.challengerAddress ?? b.challenger?.address) === address) return "challenger";
+  return null;
+}
 function battle(b, address) {
   if (!b || typeof b !== "object") return b;
-  const mine = b.accepterAddress === address ? "accepter" : "challenger";
+  const mine = sideOf(b, address);
   const theirs = mine === "accepter" ? "challenger" : "accepter";
+  const label = (s) => !mine ? s : s === mine ? "you" : "opponent";
   const turns = (b.turns ?? []).filter((t) => t.round === b.round - 1 || t.round === b.round).map((t) => ({
     round: t.round,
-    by: t.attacker === mine ? "you" : "opponent",
+    by: label(t.attacker),
     move: t.move,
     damage: t.healthDamage,
     shieldDamage: t.shieldDamage,
@@ -666,6 +733,7 @@ function battle(b, address) {
     superEffective: t.superEffective,
     notEffective: t.notEffective
   }));
+  const sides = mine ? { you: side(b[mine]), opponent: side(b[theirs]) } : { challenger: side(b.challenger), accepter: side(b.accepter) };
   return {
     id: b.id,
     kind: b.kind,
@@ -673,8 +741,7 @@ function battle(b, address) {
     round: b.round,
     ...b.winner ? { winner: b.winner } : {},
     ...b.waitingOn?.length ? { waitingOn: b.waitingOn } : {},
-    you: side(b[mine]),
-    opponent: side(b[theirs]),
+    ...sides,
     recentTurns: turns
   };
 }
@@ -702,18 +769,25 @@ async function me() {
   const { api, wallets } = await runtime();
   return { api, address: wallets?.ao.address };
 }
-async function player2() {
-  const { api, address } = await me();
-  if (!address) throw new Error("This server has no wallet; pass an address or battle_id.");
-  const p = await api.readPlayer(address);
-  if (!p) throw new Error("This wallet has no Rune Realm account yet. Call game_join first.");
+async function player2(address) {
+  const { api, address: mine } = await me();
+  const who = address ?? mine;
+  if (!who) throw new Error("This server has no wallet; pass an address.");
+  const p = await api.readPlayer(who);
+  if (!p) throw new Error(address ? `${address} has no Rune Realm account.` : "This wallet has no Rune Realm account yet. Call game_join first.");
   return p;
 }
+async function findBattle(id) {
+  const fleet = await readKey("game", "battlefleet").catch(() => null);
+  const workers = (fleet?.workers ?? []).map((w) => w.workerProcessId).filter(Boolean);
+  const found = await Promise.all([readKey("game", `battle-op-${id}`), ...workers.map((w) => readKey(w, `battle-${id}`))].map((read) => read.catch(() => null)));
+  return found.find((b) => b && typeof b === "object") ?? null;
+}
 function registerGame(server) {
   tool(
     server,
     "game_player",
-    "Read a Rune Realm player record (yours by default): gold, runes, inventory, companions with energy/happiness/level/moves, pending move offers, loot boxes, and any live arena (battleFleet) or hunt route. Free, unsigned. Call this before deciding anything.",
+    "Read a Rune Realm player record (yours by default): gold, inventory, companions with energy/happiness/level/moves and pendingMoveOffer, loot boxes, arena record with arena.liveBattle, and liveHunt. Free, unsigned. Call this before deciding anything.",
     { address: z2.string().optional().describe("Another player's AO address; omit for yours.") },
     async ({ address }) => {
       const { api, address: mine } = await me();
@@ -729,7 +803,13 @@ function registerGame(server) {
     "game_catalog",
     "The game rules as data: activity costs/gains, arena terms, element effectiveness, free moves (Rally, Mend), hunt capture odds, items, level-up rules and every move pool. Free, unsigned.",
     {},
-    async () => (await me()).api.readCatalog(),
+    async () => {
+      const catalog = await (await me()).api.readCatalog();
+      if (catalog?.levelUp) {
+        catalog.levelUp = { ...catalog.levelUp, costDivisor: 32, cost: "ceil(targetLevel^2 / 32) Rune" };
+      }
+      return catalog;
+    },
     READ
   );
   tool(
@@ -751,7 +831,11 @@ function registerGame(server) {
         factions: factions?.map(({ members, ...f }) => f),
         arenaTiers: tiers,
         openChallenges: challenges,
-        leaderboard: leaderboard?.slice(0, 10)
+        leaderboard: leaderboard?.slice(0, 10).map(({ monster, ...row }) => {
+          if (!monster) return row;
+          const { exp, energy, happiness, ...companion2 } = companion(monster);
+          return { ...row, companion: companion2 };
+        })
       };
     },
     READ
@@ -768,7 +852,7 @@ function registerGame(server) {
   tool(
     server,
     "game_companion",
-    "Care for and manage companions. feed: 1 berry, +10 energy. play: 10 energy + 1 berry, +25 happiness after 15 min. quest: 25 energy + 25 happiness, 1 h, then exp and Gold. claim: collect a finished play/quest. store (1 Rune) / retrieve / set_active / transfer manage the collection. adopt: once, if you have a faction but no companion.",
+    "Care for and manage companions. feed: 1 berry, +20 energy for a berry of its own element, +10 for any other. play: 10 energy + 1 berry, +25 happiness after 15 min. quest: 25 energy + 25 happiness, 1 h, then exp and Gold. claim: collect a finished play/quest. store (1 Rune; moves a companion into the collection) / retrieve / set_active / transfer manage the collection. adopt: once, if you have a faction but no companion.",
     {
       action: z2.enum(["feed", "play", "quest", "claim", "adopt", "store", "retrieve", "set_active", "transfer"]),
       monster_id: z2.string().optional().describe("Companion id; omit for the active one."),
@@ -804,7 +888,7 @@ function registerGame(server) {
   tool(
     server,
     "game_level_up",
-    "Level up the active companion when it has enough exp. Costs Rune. Allocate exactly the points the catalog says (levelUp.points), at most levelUp.maxPerStat in any one stat.",
+    "Level up the active companion when it has enough exp. Costs ceil(L^2/32) in-game Rune for target level L (1 up to level 5, 4 at 10, 13 at 20). Allocate exactly the points the catalog says (levelUp.points), at most levelUp.maxPerStat in any one stat. A pending move offer expires at the next level-up.",
     { attack: z2.number().int().min(0), defense: z2.number().int().min(0), speed: z2.number().int().min(0), health: z2.number().int().min(0) },
     async (points) => (await me()).api.levelUp(points),
     WRITE,
@@ -813,7 +897,7 @@ function registerGame(server) {
   tool(
     server,
     "game_learn_move",
-    "Answer a pending move offer (every 5th level). Give replace to swap that move out; omit replace to decline. Final either way.",
+    "Answer a pending move offer (every 5th level). Give replace to swap that move out; omit replace to decline. Final either way. An unanswered offer expires at the next level-up.",
     { move: z2.string().describe("The offered move, exactly as in the player record."), replace: z2.string().optional() },
     async ({ move, replace }) => (await me()).api.learnMove(move, replace),
     WRITE,
@@ -837,27 +921,31 @@ function registerGame(server) {
     WRITE,
     asPlayer
   );
+  tool(
+    server,
+    "game_shop_quote",
+    "The NPC realm shop's current Gold prices (bid/ask) and stock for berries, Scrolls and Rune. Free, unsigned.",
+    {},
+    async () => (await me()).api.readEconomy(),
+    READ
+  );
   tool(
     server,
     "game_shop",
-    "Trade with the NPC realm shop for Gold. quote returns current prices and stock (free). buy/sell trades; set max_total/min_total to bound slippage.",
+    "Buy from or sell to the NPC realm shop for Gold (prices: game_shop_quote). Set max_total/min_total to bound slippage.",
     {
-      action: z2.enum(["quote", "buy", "sell"]),
-      item: z2.string().optional().describe("Item id, e.g. fire_berry or scroll."),
-      quantity: z2.number().int().positive().optional(),
+      action: z2.enum(["buy", "sell"]),
+      item: z2.enum(SHOP_ITEMS),
+      quantity: z2.number().int().positive(),
       max_total: z2.number().int().optional(),
       min_total: z2.number().int().optional()
     },
-    async ({ action, item, quantity, max_total, min_total }) => {
-      const { api } = await me();
-      if (action === "quote") return api.readEconomy();
-      return api.tradeGameShop(
-        action,
-        need(item, "item"),
-        need(quantity, "quantity"),
-        { maxTotal: max_total, minTotal: min_total }
-      );
-    },
+    async ({ action, item, quantity, max_total, min_total }) => (await me()).api.tradeGameShop(
+      action,
+      item,
+      quantity,
+      { maxTotal: max_total, minTotal: min_total }
+    ),
     WRITE,
     asPlayer
   );
@@ -903,13 +991,23 @@ function registerGame(server) {
   tool(
     server,
     "arena_battle",
-    "Read the current battle: both sides' health, moves with uses left, round number and log. Free. Defaults to your live battle.",
-    { battle_id: z2.string().optional() },
-    async ({ battle_id }) => {
-      const { api } = await me();
-      const id = battle_id ?? (await player2()).battleFleet?.battleId;
-      if (!id) return { battle: null, note: "No live battle. Use arena_fight to start one." };
-      return api.readBattle(id);
+    "Read a battle: both sides' health, moves with uses left, round number and recent turns. Free. Defaults to your live battle; address reads that player's live battle; battle_id reads one battle directly (finished fights stay readable only briefly).",
+    {
+      address: z2.string().optional().describe("Whose live battle; omit for yours."),
+      battle_id: z2.string().optional().describe("A specific battle, e.g. from game_player arena.liveBattle.")
+    },
+    async ({ address, battle_id }) => {
+      const { api, address: mine } = await me();
+      const viewer = address ?? mine;
+      if (battle_id) {
+        const b = await findBattle(battle_id);
+        return b ? seenBy(b, viewer) : { battle: null, note: `No battle ${battle_id} on the game or any battle worker.` };
+      }
+      if (!viewer) throw new Error("This server has no wallet; pass address or battle_id.");
+      const p = await player2(viewer);
+      const id = p.battleFleet?.battleId ?? p.activeBattleId;
+      if (!id) return { battle: null, note: address ? `${address} has no live battle.` : "No live battle. Use arena_fight to start one." };
+      return seenBy(p.battle?.id === id ? p.battle : await api.readBattle(id), viewer);
     },
     READ,
     battleView
@@ -947,7 +1045,7 @@ function registerGame(server) {
   tool(
     server,
     "hunt_begin",
-    "Start a hunt with a companion. Escrows 2 of each berry; Rune and a Scroll are spent only if you try to capture.",
+    "Start a hunt with a companion. Entry fee: 2 of each berry, not refunded. Up to 3 Rune and 1 Scroll go with the run and come back when it ends, unless a capture spends them.",
     { monster_id: z2.string().describe("Companion to hunt with (see game_player).") },
     async ({ monster_id }) => (await me()).api.beginHunt(monster_id),
     WRITE,
@@ -956,14 +1054,14 @@ function registerGame(server) {
   tool(
     server,
     "hunt_state",
-    "Read your live hunt run: encounter, wild creature, round, status. Free.",
-    {},
-    async () => {
+    "Read a live hunt run (yours by default): encounter, wild creature, round, status. Free.",
+    { address: z2.string().optional().describe("Another player's AO address; omit for yours.") },
+    async ({ address }) => {
       const { api } = await me();
-      const route = (await player2()).hunt;
-      return route ? api.readHunt(route) : { hunt: null, note: "No live hunt. Use hunt_begin." };
+      const route = (await player2(address)).hunt;
+      return route ? api.readHunt(route) : { hunt: null, note: address ? `${address} has no live hunt.` : "No live hunt. Use hunt_begin." };
     },
-    OWN,
+    READ,
     huntView
   );
   tool(
@@ -998,12 +1096,24 @@ function registerGame(server) {
     WRITE,
     huntView
   );
+  tool(
+    server,
+    "companion_market_browse",
+    "The companion market (priced in in-game Rune): current listings and recent sales. Free, unsigned.",
+    {},
+    async () => {
+      const { api } = await me();
+      const [listings, history] = await Promise.all([api.readMarket(), api.readMarketHistory()]);
+      return { listings, history };
+    },
+    READ
+  );
   tool(
     server,
     "companion_market",
-    "The companion market (priced in in-game Rune). browse: listings and recent sales (free). list: sell a companion. buy / cancel: by listing_id.",
+    "Trade companions for in-game Rune (listings: companion_market_browse). list: sell a companion from your collection (never the active one; game_companion store moves it there for 1 Rune). buy / cancel: by listing_id.",
     {
-      action: z2.enum(["browse", "list", "buy", "cancel"]),
+      action: z2.enum(["list", "buy", "cancel"]),
       monster_id: z2.string().optional(),
       price: z2.number().int().min(1).max(1e6).optional(),
       listing_id: z2.string().optional()
@@ -1011,8 +1121,6 @@ function registerGame(server) {
     async ({ action, monster_id, price, listing_id }) => {
       const { api } = await me();
       switch (action) {
-        case "browse":
-          return { listings: await api.readMarket(), history: await api.readMarketHistory() };
         case "list":
           return api.listMonster(need(monster_id, "monster_id"), need(price, "price"));
         case "buy":
@@ -1040,7 +1148,7 @@ function registerGame(server) {
   tool(
     server,
     "element_claim",
-    "Claim today's free TEST element tokens. Each wallet gets one element per UTC day, chosen by the contract; this claims it.",
+    "Claim today's free TEST element tokens: 1-10 of one element (chosen by the contract) per wallet per UTC day, until that element's 2,000-token daily cap across all wallets is spent; after that, claims are refused until the next day.",
     {},
     async () => {
       const { api, address } = await me();
@@ -1050,9 +1158,6 @@ function registerGame(server) {
     WRITE
   );
 }
-async function battleView(b) {
-  return b?.id ? battle(b, (await me()).address) : b;
-}
 async function attackView(p) {
   if (!p?.address) return p;
   const { address, gold, battlesRemaining, wins, losses, arenaLast } = p;
@@ -1069,7 +1174,7 @@ function need(value, name) {
   if (value === void 0 || value === null || value === "") throw new Error(`${name} is required for this action`);
   return value;
 }
-var FACTIONS, BERRIES, asPlayer, huntView;
+var FACTIONS, BERRIES, SHOP_ITEMS, seenBy, asPlayer, battleView, huntView;
 var init_game = __esm({
   "src/game.mjs"() {
     init_runtime();
@@ -1077,7 +1182,10 @@ var init_game = __esm({
     init_views();
     FACTIONS = ["Sky Nomads", "Aqua Guardians", "Inferno Blades", "Stone Titans"];
     BERRIES = ["air_berry", "fire_berry", "rock_berry", "water_berry"];
+    SHOP_ITEMS = [...BERRIES, "scroll", "rune"];
+    seenBy = (b, address) => b && typeof b === "object" ? Object.defineProperty(b, "viewer", { value: address, enumerable: false, configurable: true }) : b;
     asPlayer = (r) => r?.address && r?.inventory ? player(r) : r;
+    battleView = (b) => b?.id ? battle(b, b.viewer) : b;
     huntView = (r) => r?.runId ? hunt(r) : asPlayer(r);
   }
 });
@@ -1102,9 +1210,14 @@ function toWire(t, m, price, quantity) {
   const baseAtoms = parseAmount(quantity, baseDen);
   if (baseAtoms % lot !== 0n) throw new Error(`Quantity moves in steps of ${formatAtoms(lot, baseDen)} ${m.base}.`);
   const perUnit = parseAmount(price, t.den(m.quote));
-  const perLot = perUnit * lot / 10n ** BigInt(baseDen);
-  if (perLot <= 0n) throw new Error("Price is below one quote atom per lot.");
-  return { lots: (baseAtoms / lot).toString(), perLot: perLot.toString() };
+  const unit = 10n ** BigInt(baseDen);
+  const tick = BigInt(Math.max(1, Number(m.tick ?? 1)));
+  const scaled = perUnit * lot;
+  if (scaled % unit !== 0n || scaled / unit % tick !== 0n) {
+    const step = tick * unit % lot === 0n ? formatAtoms(tick * unit / lot, t.den(m.quote)) : null;
+    throw new Error(step ? `Price moves in steps of ${step} ${m.quote} per ${m.base}.` : `Price must be a whole multiple of ${tick} ${m.quote} atoms per lot of ${formatAtoms(lot, baseDen)} ${m.base}.`);
+  }
+  return { lots: (baseAtoms / lot).toString(), perLot: (scaled / unit).toString() };
 }
 function registerExchange(server) {
   tool(
@@ -1129,22 +1242,21 @@ function registerExchange(server) {
       const { api } = await runtime();
       const book = (await api.readVenueBook(t.process))?.[m.id];
       if (!book) return { market: m.id, book: null };
-      const unitPrice = (perLot) => formatAtoms(BigInt(perLot) * 10n ** BigInt(t.den(m.base)) / BigInt(m.lot), t.den(m.quote));
-      const units = (lots) => formatAtoms(BigInt(lots) * BigInt(m.lot), t.den(m.base));
-      const level = (l) => ({ price: unitPrice(l.price), quantity: units(l.quantity), orders: l.orders });
+      const price = (perLot) => unitPrice(t, m, perLot);
+      const level = (l) => ({ price: price(l.price), quantity: units(t, m, l.quantity), orders: l.orders });
       return {
         market: m.id,
         units: `price in ${m.quote} per 1 ${m.base}; quantity in ${m.base}`,
-        bestBid: book.bestBid ? unitPrice(book.bestBid) : null,
-        bestAsk: book.bestAsk ? unitPrice(book.bestAsk) : null,
+        bestBid: book.bestBid ? price(book.bestBid) : null,
+        bestAsk: book.bestAsk ? price(book.bestAsk) : null,
         bids: (book.depth?.bids ?? []).slice(0, 10).map(level),
         asks: (book.depth?.asks ?? []).slice(0, 10).map(level),
-        band: book.band && { low: unitPrice(book.band.low), high: unitPrice(book.band.high) },
+        band: book.band && { low: price(book.band.low), high: price(book.band.high) },
         today: book.candles?.at(-1) && {
-          open: unitPrice(book.candles.at(-1).o),
-          high: unitPrice(book.candles.at(-1).h),
-          low: unitPrice(book.candles.at(-1).l),
-          close: unitPrice(book.candles.at(-1).c),
+          open: price(book.candles.at(-1).o),
+          high: price(book.candles.at(-1).h),
+          low: price(book.candles.at(-1).l),
+          close: price(book.candles.at(-1).c),
           trades: book.candles.at(-1).n
         }
       };
@@ -1154,7 +1266,7 @@ function registerExchange(server) {
   tool(
     server,
     "exchange_position",
-    "Balances at a venue (free, in orders) with open orders and recent fills; yours unless address is given. Free.",
+    "Balances at a venue (free, and where each asset sits) with open orders and recent fills, all in human units; yours unless address is given. Free.",
     { venue: VENUE, address: z3.string().optional() },
     async ({ venue, address }) => {
       const t = await terms(venue);
@@ -1162,7 +1274,33 @@ function registerExchange(server) {
       const who = address ?? wallets?.ao.address;
       if (!who) throw new Error("This server has no wallet; pass an address.");
       const p = await api.readVenuePosition(t.process, who);
-      return { ...p, freeUnits: human(t, p.free) };
+      const market = (row) => t.markets[row.market] ?? marketFor(t, row.item);
+      const order = ({ lot, ...o }) => {
+        const m = { ...market(o), ...lot ? { lot } : {} };
+        return {
+          ...o,
+          price: unitPrice(t, m, o.price),
+          quantity: units(t, m, o.quantity),
+          ...o.remaining !== void 0 ? { remaining: units(t, m, o.remaining) } : {}
+        };
+      };
+      const fill = (f) => {
+        const m = market(f);
+        return {
+          ...f,
+          price: unitPrice(t, m, f.price),
+          quantity: units(t, m, f.quantity),
+          ...f.fee !== void 0 ? { fee: formatAtoms(BigInt(f.fee), t.den(m.quote)) } : {}
+        };
+      };
+      return {
+        account: p.account ?? who,
+        units: "price in quote per 1 base unit; quantity in base units; fee in quote",
+        free: human(t, p.free),
+        ...p.locations ? { locations: Object.fromEntries(Object.entries(p.locations).map(([asset, at]) => [asset, Object.fromEntries(Object.entries(at).map(([where, atoms]) => [where, formatAtoms(atoms, t.den(asset))]))])) } : {},
+        orders: (p.orders ?? []).map(order),
+        fills: (p.fills ?? []).map(fill)
+      };
     },
     READ
   );
@@ -1260,13 +1398,15 @@ function registerExchange(server) {
     WRITE
   );
 }
-var VENUE, venueProcess, human;
+var VENUE, venueProcess, unitPrice, units, human;
 var init_exchange = __esm({
   "src/exchange.mjs"() {
     init_runtime();
     init_tool();
     VENUE = z3.enum(["game", "token"]).describe("game: items vs Gold. token: element tokens vs TEST-RUNE.");
     venueProcess = (venue) => venue === "game" ? graph.processes.internalVenue : graph.processes.externalVenue;
+    unitPrice = (t, m, perLot) => formatAtoms(BigInt(perLot) * 10n ** BigInt(t.den(m.base)) / BigInt(m.lot), t.den(m.quote));
+    units = (t, m, lots) => formatAtoms(BigInt(lots) * BigInt(m.lot), t.den(m.base));
     human = (t, free) => Object.fromEntries(Object.entries(free ?? {}).map(([asset, atoms]) => [asset, formatAtoms(atoms, t.den(asset))]));
   }
 });
@@ -2279,9 +2419,7 @@ import { z as z9 } from "zod";
 function buildServer() {
   const server = new McpServer(
     { name: "paralith", version: VERSION },
-    { instructions: READ_ONLY ? `${READ_ONLY_NOTE}
-
-${INSTRUCTIONS}` : INSTRUCTIONS }
+    { instructions: READ_ONLY ? READ_ONLY_INSTRUCTIONS : INSTRUCTIONS }
   );
   tool(
     server,
@@ -2308,7 +2446,7 @@ ${INSTRUCTIONS}` : INSTRUCTIONS }
   tool(
     server,
     "read_state",
-    `Read any published key of any process, free: /<process>~process@1.0/now/<key>. process is an id or an alias (${Object.keys(PROCESS_ALIASES).join(", ")}). Returns null when absent.`,
+    `Read any published key of any process, free: /<process>~process@1.0/now/<key>. process is an id or an alias (${Object.keys(PROCESS_ALIASES).join(", ")}). Returns null when absent. Common keys: game: player-<address>, catalogref (the catalog's id, not catalog), leaderboard, factions, arenatiers, challenges, economy, economybook, market, markethistory, battlefleet, huntconfig, access. rune and *-token: balance-<address>, tokeninfo (not info), totalsupply. pusd: balance-<address>, bridgeinfo, withdrawals. dao: daoinfo, proposals. game-venue and token-venue: balance-<address>, vaultinfo, vaultpairs.`,
     { process: z9.string(), key: z9.string() },
     async ({ process: process2, key }) => readKey(process2, key),
     READ
@@ -2316,7 +2454,7 @@ ${INSTRUCTIONS}` : INSTRUCTIONS }
   tool(
     server,
     "send_message",
-    "Escape hatch: sign and send a raw message to any process and return its reply. Prefer the specific tools; use this only for an action they do not cover. Tag values must be strings; never use a tag named Target.",
+    "Escape hatch: sign and send a raw message to any process and return its reply. Prefer the specific tools; use this only for an action they do not cover. Tag values must be strings; never use a tag named Target, Signature or Epoch.",
     {
       process: z9.string(),
       tags: z9.record(z9.string(), z9.string()).describe('e.g. {"Action": "Pass.Info"}'),
@@ -2324,7 +2462,8 @@ ${INSTRUCTIONS}` : INSTRUCTIONS }
       push_outbox: z9.boolean().optional().describe("Deliver the messages this one emits to other processes (e.g. a Transfer to a process).")
     },
     async ({ process: process2, tags: tags2, data, push_outbox }) => {
-      if (Object.keys(tags2).some((k) => k.toLowerCase() === "target")) throw new Error("Target is not a usable tag name.");
+      const reserved = Object.keys(tags2).find((k) => ["target", "signature", "epoch"].includes(k.toLowerCase().replace(/[-_]/g, "")));
+      if (reserved) throw new Error(`${reserved} is not a usable tag name (Target, Signature and Epoch are reserved).`);
       const { api } = await runtime();
       return api.rawSend(
         Object.entries(tags2).map(([name, value]) => ({ name, value })),
@@ -2354,7 +2493,7 @@ ${INSTRUCTIONS}` : INSTRUCTIONS }
   registerProgress(server);
   return server;
 }
-var DOCS, INSTRUCTIONS, READ_ONLY_NOTE;
+var DOCS, INSTRUCTIONS, READ_ONLY_INSTRUCTIONS;
 var init_build = __esm({
   "src/build.mjs"() {
     init_runtime();
@@ -2373,29 +2512,33 @@ var init_build = __esm({
 Everything is TEST-prefixed while unreleased. Reads are free; every write is a signed message (a few seconds round trip, longer under load).
 
 Start: wallet -> game_player. No account? game_join (pick a faction).
-Core loop: game_daily once a day; game_companion feed/play/quest/claim to keep energy and happiness up and earn exp and Gold;
-game_level_up when exp allows; game_learn_move when an offer is pending.
+Core loop: game_daily once a day; game_companion feed/play keep energy and happiness up, quest then claim earns exp and Gold;
+game_level_up when exp allows; game_learn_move when an offer is pending (it expires at the next level-up).
 Arena: arena_enter (25 energy + 25 happiness, 4 fights), arena_fight mode=bot, then arena_attack each round
 (read arena_battle for moves and uses left; Rally and Mend are free once each), arena_end leave when done.
-Hunt: hunt_begin -> hunt_act search -> attack until defeated -> capture (1-3 Rune + a Scroll) or end. One encounter per hunt.
+Hunt: hunt_begin (entry fee 2 of each berry, not refunded; up to 3 Rune + 1 Scroll set aside and returned unless a capture spends them)
+-> hunt_act search -> attack until defeated -> capture (1-3 Rune + a Scroll) or end. One encounter per hunt.
 Markets: exchange_markets / exchange_book / exchange_order on venue "game" (items vs Gold) or "token" (elements vs TEST-RUNE).
 Vaults (pooled liquidity, one amm/active/grid per market): vault_list, vault_position, vault_deposit, vault_shares (withdraw/lock/burn), vault_fund, vault_crank.
 Rune: rune_move withdraw (game -> token) / deposit (token -> game). Bridge: bridge_balances, bridge_faucet, bridge_deposit, bridge_redeem.
 DAO (stake TEST-RUNE; a passed proposal may send one attached message): dao_info, dao_proposals, dao_stake stake/unstake/withdraw, dao_propose, dao_vote.
 
 HOW RESOURCES FLOW. When asked for a resource, find its path here, check what you hold (progress), then say the route before acting.
-- Gold (in-game only, never leaves the game). Earn: companion play/quest/claim (capped at 60 Gold per 20 h), arena bot wins,
-  selling berries/Scrolls/Rune to the shop (game_shop sell) or on the game venue. Spend: arena stakes, shop buys, game-venue buys.
+- Gold (in-game only, never leaves the game). Earn: quest claims and arena bot wins, which share one 60 Gold allowance per 20 h
+  (play pays happiness only); selling berries/Scrolls/Rune to the shop (game_shop sell) or on the game venue.
+  Spend: arena stakes, shop buys, game-venue buys.
 - Berries and Scrolls. Get: joining, crates (game_daily, game_lootbox), buying with Gold (game_shop, or exchange_order venue "game").
-  Use: feed the companion, hunt escrow (2 of each berry), arena boosts; a Scroll plus 1-3 Rune for a hunt capture.
+  Use: feed the companion, the hunt entry fee (2 of each berry), arena boosts; a Scroll plus 1-3 Rune for a hunt capture.
 - Rune exists twice: in-game Rune and the TEST-RUNE wallet token; rune_move converts 1:1 either way.
-  Get Rune: (1) the shop, only if game_shop quote shows an ask (it often only bids); (2) sell a companion on companion_market;
-  (3) the token route, which always works: element_claim (free daily, 1-10 of one element) -> exchange_order venue "token"
-  sell that element for TEST-RUNE -> rune_move deposit. Public TEST accounts accrue no Rune from game_daily (pass holders only).
-  Spend in-game Rune: game_level_up, hunt capture, companion_market buys. TEST-RUNE: token-venue buys, vaults, dao_stake.
+  Get Rune: (1) the shop, only if game_shop_quote shows an ask (it often only bids); (2) sell a companion on companion_market;
+  (3) the token route: element_claim (free, 1-10 of one element per wallet per UTC day until that element's 2,000/day
+  global cap is spent) -> exchange_order venue "token" sell that element for TEST-RUNE -> rune_move deposit.
+  Public TEST accounts accrue no Rune from game_daily (pass holders only).
+  Spend in-game Rune: game_level_up (ceil(L^2/32) for level L), hunt capture, companion_market buys, game_companion store (1 Rune).
+  TEST-RUNE: token-venue buys, vaults, dao_stake.
 - Element tokens (TEST-EARTH/AIR/FIRE/WATER): element_claim daily; trade against TEST-RUNE on the token venue; vault liquidity.
 - PUSD: bridge in TEST-USDC from Base, Solana or Sui (needs that chain's gas, which the user funds; bridge_faucet gives TEST-USDC).
-  No PUSD market is listed yet. Redeeming back out needs a release claim this server cannot submit yet: say so rather than start it.
+  No PUSD market is listed yet. bridge_redeem waits for k attestor signatures and submits the release (needs destination-chain gas).
 - Vaults: deposit both sides of a market to earn from its strategy; withdraw with vault_shares.
 
 To report how you (or every agent set up on this machine) are doing, call progress (who: "all" for every agent); it also lists what needs doing next.
@@ -2406,8 +2549,24 @@ Show once per thing, not once per round.
 
 Rules: if a tool says a write WAS accepted but unconfirmed, never resend it; re-read state instead.
 A refusal ({"error": ...}) costs nothing. Use game_catalog for exact costs and move stats; docs at ${DOCS}/llms-full.txt.`;
-    READ_ONLY_NOTE = `This endpoint is READ-ONLY: it explains the protocol and reads live state for any address.
-To play, trade or bridge, run the local server with a wallet phrase: ${DOCS}/ai/mcp`;
+    READ_ONLY_INSTRUCTIONS = `This endpoint is READ-ONLY: it explains the protocol and reads live state for any address, free.
+To play, trade or bridge, run the local server with a wallet phrase: ${DOCS}/ai/mcp
+
+Paralith on AO (HyperBEAM): Rune Realm (a companion game), two order books, and the PUSD bridge.
+Everything is TEST-prefixed while unreleased. Pass an address wherever a tool takes one.
+
+- Game: game_player (account, companions, live battle or hunt), game_catalog (rules, costs, move stats),
+  game_world (factions, arena tiers, open challenges, leaderboard), arena_battle (address or battle_id), hunt_state (address),
+  game_shop_quote (NPC shop prices and stock), companion_market_browse (listings and recent sales).
+- Markets: exchange_markets / exchange_book / exchange_position on venue "game" (items vs Gold) or "token" (elements vs TEST-RUNE);
+  vault_list, vault_position.
+- Bridge and DAO: bridge_info, bridge_status, dao_info, dao_proposals, dao_stake_info.
+- Anything else: progress (one address across everything), read_state (any published key), protocol_docs.
+
+SHOW IT. Watching beats reading: call show for anything worth seeing (a fight as it happens, a companion, a book, a vault,
+a bridge transfer). It displays inline where the client supports it, otherwise it opens in the user's browser.
+
+Docs: ${DOCS}/llms-full.txt.`;
   }
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paralith-mcp",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "MCP server for Paralith on AO: an AI with one 24-word phrase plays Rune Realm, trades and bridges PUSD; plus paralith-bridge, the bridge operator CLI (TEST deployment).",
   "license": "UNLICENSED",
   "homepage": "https://docs.paralithmarkets.com/ai/mcp",