everyblock-mcp 0.2.0

package/dist/chain.js

@@ -0,0 +1,202 @@
+// Connection, configuration and the read/write plumbing the tools share. Secrets are read from the environment,
+// never printed, logged or written anywhere.
+import { BaseError, ContractFunctionRevertedError, createPublicClient, createWalletClient, defineChain, http, parseAbi, parseEventLogs, parseUnits, } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { everyblockAbi, testUsdAbi } from "./abi.js";
+export const FEED_NAMES = {
+    "0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43": "BTC/USD",
+    "0xff61491a931112ddf1bd8147cd1b641375f79f5825126d665480874634fd0ace": "ETH/USD",
+    "0xef0d8b6fda2ceba41da15d4095d1da392a0d2f8ed0c6c7bc0f4cfac8c280b56d": "SOL/USD",
+    "0x31491744e2dbf6df7fcf4ac0820d18a609b49076d45066d3568424e62f686cd1": "MON/USD",
+};
+export const DEFAULT_FEEDS = Object.keys(FEED_NAMES);
+export const MONAD_MAINNET = 143;
+export const MONAD_TESTNET = 10143;
+/** The live Monad testnet deployment (docs/SUBMISSION.md, "Deployed contracts"). */
+export const TESTNET_RPC = "https://testnet-rpc.monad.xyz";
+export const TESTNET_EVERYBLOCK = "0x034ebcA29FcAdDF0F434Dd63C75e719b1dC62dB5";
+/** The hosted web app's proof endpoint for the testnet deployment. */
+export const TESTNET_PROOF_URL = "https://everyblock-gray.vercel.app/api/proof";
+export const ANVIL = 31337;
+/** Monad charges the gas limit, not gas used: estimate, then add 15% (as the keeper does). */
+const GAS_MARGIN_PCT = 115n;
+/** The fee function another stream adds; absent on older deployments, which then charge no fee. */
+const feeAbi = parseAbi(["function marketFeeBps(uint256 marketId) view returns (uint256)"]);
+export const isLocalRpc = (url) => /^https?:\/\/(127\.0\.0\.1|localhost)(:|\/|$)/.test(url);
+/**
+ * Environment:
+ *   RPC_URL, EVERYBLOCK            the chain and contract (default: both unset = the Monad testnet deployment)
+ *   MCP_PRIVATE_KEY                the trading wallet's key (writes); never printed
+ *   MCP_UNLOCKED_ACCOUNT           instead of a key, an unlocked node account (localhost only, e.g. anvil)
+ *   MCP_ALLOWED_CHAINS             chain ids writes may run on (default 10143,31337: Monad testnet and anvil)
+ *   MCP_MAX_ORDER_SIZE             shares per order (default 100)
+ *   MCP_MAX_SPEND_USD              collateral one write call may commit, in dollars (default 50)
+ *   FEEDS                          comma-separated Pyth feed ids (default BTC, ETH, SOL, MON)
+ *   MCP_LOG_RANGE, MCP_LOG_LOOKBACK  blocks per eth_getLogs call (100) and how far back to look (2000)
+ *   EVERYBLOCK_PROOF_URL           the web app's /api/proof, where `settle` gets signed Pyth prices without a Pyth
+ *                                  key of its own (default on Monad testnet: the hosted app; set "" to disable)
+ */
+export function configFromEnv(env = process.env) {
+    const need = (name) => {
+        const v = env[name];
+        if (!v)
+            throw new Error(`set ${name}`);
+        return v;
+    };
+    const positive = (name, fallback) => {
+        const v = env[name] ?? fallback;
+        if (!/^\d+(\.\d+)?$/.test(v) || Number(v) <= 0)
+            throw new Error(`${name} must be a positive number`);
+        return v;
+    };
+    return {
+        // With neither set, the server talks to the live Monad testnet deployment, so `npx everyblock-mcp` just works.
+        rpcUrl: env.RPC_URL || (env.EVERYBLOCK ? need("RPC_URL") : TESTNET_RPC),
+        everyblock: (env.EVERYBLOCK || (env.RPC_URL ? need("EVERYBLOCK") : TESTNET_EVERYBLOCK)),
+        feeds: (env.FEEDS ? env.FEEDS.split(",").map((s) => s.trim()) : DEFAULT_FEEDS),
+        allowedChains: (env.MCP_ALLOWED_CHAINS ?? `${MONAD_TESTNET},${ANVIL}`)
+            .split(",")
+            .filter((s) => s.trim() !== "")
+            .map((s) => Number(s.trim())),
+        maxOrderSize: BigInt(positive("MCP_MAX_ORDER_SIZE", "100").split(".")[0]),
+        maxSpendUsd: positive("MCP_MAX_SPEND_USD", "50"),
+        logRange: BigInt(positive("MCP_LOG_RANGE", "100").split(".")[0]),
+        logLookback: BigInt(positive("MCP_LOG_LOOKBACK", "2000").split(".")[0]),
+        privateKey: env.MCP_PRIVATE_KEY ? env.MCP_PRIVATE_KEY : undefined,
+        unlockedAccount: env.MCP_UNLOCKED_ACCOUNT ? env.MCP_UNLOCKED_ACCOUNT : undefined,
+        proofUrl: env.EVERYBLOCK_PROOF_URL,
+    };
+}
+export async function connect(cfg) {
+    // viem polls for receipts every 4 s by default; Monad makes a block in well under a second.
+    const pub = createPublicClient({ transport: http(cfg.rpcUrl), pollingInterval: 250 });
+    const chainId = await pub.getChainId();
+    const chain = defineChain({
+        id: chainId,
+        name: `chain-${chainId}`,
+        nativeCurrency: { name: "MON", symbol: "MON", decimals: 18 },
+        rpcUrls: { default: { http: [cfg.rpcUrl] } },
+    });
+    let account = null;
+    if (cfg.privateKey) {
+        account = privateKeyToAccount(cfg.privateKey);
+    }
+    else if (cfg.unlockedAccount) {
+        if (!isLocalRpc(cfg.rpcUrl))
+            throw new Error("MCP_UNLOCKED_ACCOUNT is only for a local node (localhost RPC_URL)");
+        account = cfg.unlockedAccount;
+    }
+    const wallet = account ? createWalletClient({ transport: http(cfg.rpcUrl) }) : null;
+    const [collateral, cent] = await Promise.all([
+        pub.readContract({ address: cfg.everyblock, abi: everyblockAbi, functionName: "collateral" }),
+        pub.readContract({ address: cfg.everyblock, abi: everyblockAbi, functionName: "CENT" }),
+    ]);
+    const share = 100n * cent;
+    const digits = String(share).length - 1;
+    const maxSpend = 10n ** BigInt(digits) === share
+        ? parseUnits(cfg.maxSpendUsd, digits)
+        : BigInt(Math.floor(Number(cfg.maxSpendUsd) * Number(share)));
+    return {
+        pub,
+        wallet,
+        account,
+        address: account === null ? null : typeof account === "string" ? account : account.address,
+        chain,
+        chainId,
+        everyblock: cfg.everyblock,
+        collateral,
+        cent,
+        feeds: cfg.feeds,
+        allowedChains: cfg.allowedChains,
+        maxOrderSize: cfg.maxOrderSize,
+        maxSpend,
+        logRange: cfg.logRange,
+        logLookback: cfg.logLookback,
+        proofUrl: cfg.proofUrl === undefined ? (chainId === MONAD_TESTNET ? TESTNET_PROOF_URL : undefined) : cfg.proofUrl || undefined,
+        queue: Promise.resolve(),
+    };
+}
+// ------------------------------------------------------------------------------------------------
+// Reads
+// ------------------------------------------------------------------------------------------------
+/** Reads Everyblock. The function name is dynamic, so the call is typed loosely; the ABI still encodes it. */
+export function read(ctx, functionName, args = []) {
+    return ctx.pub.readContract({ address: ctx.everyblock, abi: everyblockAbi, functionName, args });
+}
+export function readToken(ctx, functionName, args = []) {
+    return ctx.pub.readContract({ address: ctx.collateral, abi: testUsdAbi, functionName, args });
+}
+/** marketFeeBps(marketId) where the deployment has it, else 0. */
+export async function feeBps(ctx, marketId) {
+    try {
+        const bps = await ctx.pub.readContract({
+            address: ctx.everyblock,
+            abi: feeAbi,
+            functionName: "marketFeeBps",
+            args: [marketId],
+        });
+        return { bps: Number(bps), source: "marketFeeBps" };
+    }
+    catch {
+        return { bps: 0, source: "none (this deployment charges no fee)" };
+    }
+}
+export async function now(ctx) {
+    const b = await ctx.pub.getBlock();
+    return { timestamp: b.timestamp, number: b.number };
+}
+/** Why writes are refused on this server, or null if they are allowed. */
+export function writeBlocker(ctx) {
+    if (!ctx.wallet || !ctx.account) {
+        return "this server is read-only: set MCP_PRIVATE_KEY (or MCP_UNLOCKED_ACCOUNT on a local node) to trade";
+    }
+    if (!ctx.allowedChains.includes(ctx.chainId)) {
+        return `writes are not allowed on chain ${ctx.chainId} (MCP_ALLOWED_CHAINS=${ctx.allowedChains.join(",")})`;
+    }
+    return null;
+}
+/** Runs `fn` after every earlier write of this server has finished. */
+export function serialize(ctx, fn) {
+    const run = ctx.queue.then(fn, fn);
+    ctx.queue = run.catch(() => undefined);
+    return run;
+}
+/** Sends one transaction and waits for it: gas estimate + 15%, receipt checked, events decoded. */
+export async function send(ctx, target, functionName, args, value) {
+    const blocked = writeBlocker(ctx);
+    if (blocked)
+        throw new Error(blocked);
+    const abi = (target === "everyblock" ? everyblockAbi : testUsdAbi);
+    const address = target === "everyblock" ? ctx.everyblock : ctx.collateral;
+    const call = { address, abi, functionName, args, account: ctx.account, ...(value ? { value } : {}) };
+    let gas;
+    try {
+        gas = ((await ctx.pub.estimateContractGas(call)) * GAS_MARGIN_PCT) / 100n;
+    }
+    catch (e) {
+        throw new Error(`${functionName} would revert: ${reason(e)}`);
+    }
+    const hash = await ctx.wallet.writeContract({ ...call, chain: ctx.chain, gas });
+    const receipt = await ctx.pub.waitForTransactionReceipt({ hash });
+    if (receipt.status !== "success")
+        throw new Error(`${functionName} reverted in ${hash}`);
+    const logs = parseEventLogs({ abi: [...everyblockAbi, ...testUsdAbi], logs: receipt.logs });
+    return {
+        txHash: hash,
+        blockNumber: receipt.blockNumber.toString(),
+        gasUsed: receipt.gasUsed.toString(),
+        events: logs.map((l) => ({ name: l.eventName, args: (l.args ?? {}) })),
+    };
+}
+/** A revert's error name (e.g. MarketNotTrading) when the ABI knows it, else viem's short message. */
+export function reason(e) {
+    if (e instanceof BaseError) {
+        const revert = e.walk((x) => x instanceof ContractFunctionRevertedError);
+        if (revert instanceof ContractFunctionRevertedError && revert.data?.errorName) {
+            const args = revert.data.args?.length ? `(${revert.data.args.map(String).join(", ")})` : "";
+            return `${revert.data.errorName}${args}`;
+        }
+        return e.shortMessage.split("\n")[0];
+    }
+    return e instanceof Error ? e.message.split("\n")[0] : String(e);
+}

package/dist/main.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// Everyblock MCP server over stdio. Configuration comes from the environment (see chain.ts configFromEnv);
+// secrets are read, never printed. stdout carries the protocol, so diagnostics go to stderr.
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { configFromEnv, connect } from "./chain.js";
+import { createServer } from "./server.js";
+async function main() {
+    const ctx = await connect(configFromEnv());
+    const server = createServer(ctx);
+    await server.connect(new StdioServerTransport());
+    const mode = ctx.address ? `wallet ${ctx.address}` : "read-only";
+    const writes = ctx.allowedChains.includes(ctx.chainId) ? "writes allowed" : "writes refused on this chain";
+    console.error(`everyblock-mcp: chain ${ctx.chainId}, Everyblock ${ctx.everyblock}, ${mode}, ${writes}`);
+}
+main().catch((e) => {
+    console.error(e instanceof Error ? e.message : e);
+    process.exit(1);
+});

package/dist/orders.js

@@ -0,0 +1,178 @@
+// Order math, mirrored from Everyblock.sol. Pure functions, so they can be tested without a chain.
+import { formatUnits } from "viem";
+/** Everyblock.Kind, in the contract's order. */
+export const KINDS = ["BuyUp", "SellDown", "SellUp", "BuyDown"];
+export const BUY_UP = 0;
+export const SELL_DOWN = 1;
+export const SELL_UP = 2;
+export const BUY_DOWN = 3;
+export const OUTCOMES = ["pending", "up", "down", "void"];
+export function kindOf(side, outcome) {
+    if (side === "buy")
+        return outcome === "up" ? BUY_UP : BUY_DOWN;
+    return outcome === "up" ? SELL_UP : SELL_DOWN;
+}
+export function describeKind(kind) {
+    return [
+        { side: "buy", outcome: "up" },
+        { side: "sell", outcome: "down" },
+        { side: "sell", outcome: "up" },
+        { side: "buy", outcome: "down" },
+    ][kind];
+}
+/** Buy UP and Sell DOWN are bids in the UP book; Sell UP and Buy DOWN are asks. */
+export const isBid = (kind) => kind === BUY_UP || kind === SELL_DOWN;
+/** The UP-book tick an order rests at: its own price for UP orders, 100 - price for DOWN orders. */
+export const tickOf = (kind, price) => (kind === BUY_UP || kind === SELL_UP ? price : 100 - price);
+/** An order's own limit, back from its tick. */
+export const priceOf = (kind, tick) => tickOf(kind, tick);
+/** The price, in cents of this order's own outcome, that a clearing tick c (cents of UP) means. */
+export const ownPriceAt = (kind, c) => (kind === BUY_UP || kind === SELL_UP ? c : 100 - c);
+/** The fee on a notional at `bps` (the market's marketFeeBps), rounded down like Everyblock._fee. */
+export const feeOn = (notional, bps) => (notional * BigInt(bps)) / 10000n;
+/**
+ * What placeOrder takes from the trader: buys escrow price * size cents plus the fee on it (Everyblock._withFee;
+ * the unused part comes back on claim), sells escrow the shares.
+ */
+export function escrowOf(kind, price, size, cent, feeBps = 0) {
+    if (kind === SELL_UP)
+        return { collateral: 0n, up: size, down: 0n };
+    if (kind === SELL_DOWN)
+        return { collateral: 0n, up: 0n, down: size };
+    const notional = size * BigInt(price) * cent;
+    return { collateral: notional + feeOn(notional, feeBps), up: 0n, down: 0n };
+}
+/**
+ * The worst and best cases of a full fill at the limit, net of the fee (a fill at a better clearing price only
+ * improves them): a buy pays at most price per share plus the fee and each share pays 100 cents if its outcome
+ * wins; a sell receives at least price per share less the fee and gives up shares that would pay 100 cents if
+ * they win.
+ */
+export function scenarios(kind, price, size, cent, feeBps = 0) {
+    const share = 100n * cent;
+    const atLimit = size * BigInt(price) * cent;
+    const fee = feeOn(atLimit, feeBps);
+    if (kind === BUY_UP || kind === BUY_DOWN) {
+        const maxCost = atLimit + fee;
+        return { maxCost, payoutIfWins: size * share, maxProfit: size * share - maxCost, maxLoss: maxCost };
+    }
+    const minProceeds = atLimit - fee;
+    return { minProceeds, maxProfit: minProceeds, maxLoss: size * share - minProceeds };
+}
+/**
+ * Everyblock's clearing rule on a batch's levels, as `_clear` runs it: the tick that maximises matched volume,
+ * then minimises the surplus, then the midpoint of a zero-surplus range. Tick 0 means no trade. Used to show an
+ * indicative price for a batch that is still open.
+ */
+export function clearBatch(levels) {
+    const none = { tick: 0, volume: 0n, bidFillAtTick: 0n, askFillAtTick: 0n };
+    const bids = new Map();
+    const asks = new Map();
+    for (const l of levels) {
+        if (l.bid > 0n)
+            bids.set(l.tick, (bids.get(l.tick) ?? 0n) + l.bid);
+        if (l.ask > 0n)
+            asks.set(l.tick, (asks.get(l.tick) ?? 0n) + l.ask);
+    }
+    if (bids.size === 0 || asks.size === 0)
+        return none;
+    const lo = Math.min(...asks.keys());
+    const hi = Math.max(...bids.keys());
+    if (hi < lo)
+        return none;
+    const n = hi - lo + 1;
+    const b = [];
+    const a = [];
+    let demand = 0n;
+    for (let i = 0; i < n; i++) {
+        b.push(bids.get(lo + i) ?? 0n);
+        a.push(asks.get(lo + i) ?? 0n);
+        demand += b[i];
+    }
+    let volume = 0n;
+    let eqLo = 0;
+    let eqHi = 0;
+    let lastPos = 0;
+    let posSurplus = 0n;
+    let firstNeg = 0;
+    let negSurplus = 0n;
+    let supply = 0n;
+    for (let i = 0; i < n; i++) {
+        supply += a[i];
+        const v = demand < supply ? demand : supply;
+        if (v > volume) {
+            volume = v;
+            eqLo = eqHi = lastPos = firstNeg = 0;
+        }
+        if (v === volume) {
+            if (demand === supply) {
+                if (eqLo === 0)
+                    eqLo = lo + i;
+                eqHi = lo + i;
+            }
+            else if (demand > supply) {
+                lastPos = lo + i;
+                posSurplus = demand - supply;
+            }
+            else if (firstNeg === 0) {
+                firstNeg = lo + i;
+                negSurplus = supply - demand;
+            }
+        }
+        demand -= b[i];
+    }
+    if (eqLo !== 0) {
+        const c = Math.floor((eqLo + eqHi) / 2);
+        return { tick: c, volume, bidFillAtTick: b[c - lo], askFillAtTick: a[c - lo] };
+    }
+    if (firstNeg === 0 || (lastPos !== 0 && posSurplus <= negSurplus)) {
+        return { tick: lastPos, volume, bidFillAtTick: b[lastPos - lo] - posSurplus, askFillAtTick: a[lastPos - lo] };
+    }
+    return { tick: firstNeg, volume, bidFillAtTick: b[firstNeg - lo], askFillAtTick: a[firstNeg - lo] - negSurplus };
+}
+// ------------------------------------------------------------------------------------------------
+// Markets
+// ------------------------------------------------------------------------------------------------
+export const SAMPLES = 12;
+export const WINDOW = 60n;
+export const GRACE = 3600n;
+/** Where a market is in its life. `outcome` is Everyblock.outcome(), which reads Void after the deadline. */
+export function marketStatus(now, openTime, closeTime, outcome) {
+    if (outcome === 3)
+        return "void";
+    if (outcome !== 0)
+        return "resolved";
+    if (now < openTime)
+        return "upcoming";
+    if (now < closeTime)
+        return "trading";
+    return "closed";
+}
+/** A settlement sum of 12 prices as a mean price, e.g. 65012.5, or null if unset. */
+export function meanPrice(sum, expo, set) {
+    if (!set)
+        return null;
+    const decimals = Math.max(0, -expo);
+    const scaled = sum * 10n ** BigInt(Math.max(0, expo)); // positive exponents (never seen) scale up
+    const mean = (scaled * 1000n) / BigInt(SAMPLES); // 3 extra digits so the mean does not round away
+    return trimZeros(formatUnits(mean, decimals + 3));
+}
+/** Collateral units as dollars of shares (one share pays 100 * CENT units = $1.00). */
+export function usd(units, cent) {
+    const share = 100n * cent;
+    const digits = String(share).length - 1;
+    if (10n ** BigInt(digits) === share)
+        return trimZeros(formatUnits(units, digits), 2);
+    return (Number(units) / Number(share)).toFixed(6);
+}
+/** Cents as a dollar price, 55 -> "0.55". */
+export const centsToUsd = (cents) => (cents / 100).toFixed(2);
+function trimZeros(s, minDecimals = 0) {
+    if (!s.includes("."))
+        return minDecimals ? `${s}.${"0".repeat(minDecimals)}` : s;
+    let [i, f] = s.split(".");
+    f = f.replace(/0+$/, "");
+    if (f.length < minDecimals)
+        f = f.padEnd(minDecimals, "0");
+    return f ? `${i}.${f}` : i;
+}