@arcnow/mcp 0.1.0

package/dist/tools/venue.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Where a token trades, and what a tool has to refuse because of it.
+ *
+ * A token's market moves exactly once, irreversibly, in the middle of its life.
+ * Before graduation it is its bonding curve. After graduation **and
+ * migration** it is a Uniswap v4 pool, reached only through arcnow.io's router.
+ * And in between there is a third state that is easy to miss and expensive to
+ * misreport: **graduated but never migrated**, where the curve has stopped for
+ * good and no pool exists, so the token trades nowhere at all until somebody
+ * runs the permissionless `migrate()`.
+ *
+ * # The venue is the SDK's answer, not this server's
+ *
+ * `client.trade(token).venue()` decides curve or pool, and every buy and sell
+ * this server sends goes through that same handle. The curve's own state is
+ * read only to tell "on the curve" apart from "stranded", which the SDK's venue
+ * cannot: a stranded token's venue is still `"curve"`, and a curve that has
+ * graduated reverts on every trade.
+ *
+ * # Parameters that do not apply are refused, never dropped
+ *
+ * The two venues take different arguments. A curve pays `msg.sender` and has
+ * no recipient; a pool swap has no referrer or developer and cannot graduate
+ * anything, so a gas limit guards nothing there. The SDK refuses each of these
+ * on the wrong venue, and so does this server — earlier, before anything is
+ * quoted or sent, and in words that say why. A parameter silently ignored is a
+ * referrer promised a share the chain never saw, or a payout sent to an address
+ * nobody named.
+ *
+ * @module
+ */
+import type { Address } from "viem";
+import type { CurveState, NetworkConfig } from "@arcnow/sdk";
+import type { CurveHandle, TradeHandle } from "../sdk-port.js";
+import type { ToolContext } from "./schema.js";
+/** Where a token can be traded right now. */
+export type MarketVenue = "curve" | "pool" | "stranded";
+export interface Market {
+    readonly curve: CurveHandle;
+    readonly state: CurveState;
+    /** True when the caller gave the token address and it was followed to the curve. */
+    readonly viaToken: boolean;
+    /** `client.trade(state.token)`: what every quote and trade goes through. */
+    readonly trade: TradeHandle;
+    readonly venue: MarketVenue;
+}
+/**
+ * Resolve a token-or-curve address to its curve, its trade handle, and where it
+ * trades now.
+ */
+export declare function resolveMarket(ctx: ToolContext, address: Address): Promise<Market>;
+/** The network's v4 router, or `undefined` — and on Arc the zero address is a real account. */
+export declare function configuredRouter(config: NetworkConfig): Address | undefined;
+export declare function routerName(config: NetworkConfig): string;
+/** The refusal for a token that graduated and never migrated. */
+export declare function strandedText(tool: string): string;
+/** Refuse `referrer`, `developer` or `gasLimit` on a token that trades in its pool. */
+export declare function refuseCurveOnly(tool: string, fields: readonly string[], nothing: "sent" | "quoted"): string;
+/** Refuse `recipient` on a token still on its curve. */
+export declare function refusePoolOnlyRecipient(tool: string): string;
+/** Refuse `approveRouter` on a curve sell, which needs no approval at all. */
+export declare function refuseCurveApproval(): string;
+/** The venue changed between the read and the quote: the token migrated mid-call. */
+export declare function venueMovedText(tool: string): string;
+/** "0x… (the signing address)", or the same address flagged as somebody else's. */
+export declare function payee(recipient: Address, signer: Address | undefined): string;
+//# sourceMappingURL=venue.d.ts.map

package/dist/tools/venue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"venue.d.ts","sourceRoot":"","sources":["../../src/tools/venue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG7D,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,6CAA6C;AAC7C,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,CAAC;AAExD,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAMvF;AAED,+FAA+F;AAC/F,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,GAAG,SAAS,CAI3E;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAGxD;AAED,iEAAiE;AACjE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAajD;AAED,uFAAuF;AACvF,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,OAAO,EAAE,MAAM,GAAG,QAAQ,GACzB,MAAM,CAiBR;AAED,wDAAwD;AACxD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAa5D;AAED,8EAA8E;AAC9E,wBAAgB,mBAAmB,IAAI,MAAM,CAU5C;AAED,qFAAqF;AACrF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOnD;AAED,mFAAmF;AACnF,wBAAgB,KAAK,CAAC,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAI7E"}

package/dist/tools/venue.js

@@ -0,0 +1,110 @@
+/**
+ * Where a token trades, and what a tool has to refuse because of it.
+ *
+ * A token's market moves exactly once, irreversibly, in the middle of its life.
+ * Before graduation it is its bonding curve. After graduation **and
+ * migration** it is a Uniswap v4 pool, reached only through arcnow.io's router.
+ * And in between there is a third state that is easy to miss and expensive to
+ * misreport: **graduated but never migrated**, where the curve has stopped for
+ * good and no pool exists, so the token trades nowhere at all until somebody
+ * runs the permissionless `migrate()`.
+ *
+ * # The venue is the SDK's answer, not this server's
+ *
+ * `client.trade(token).venue()` decides curve or pool, and every buy and sell
+ * this server sends goes through that same handle. The curve's own state is
+ * read only to tell "on the curve" apart from "stranded", which the SDK's venue
+ * cannot: a stranded token's venue is still `"curve"`, and a curve that has
+ * graduated reverts on every trade.
+ *
+ * # Parameters that do not apply are refused, never dropped
+ *
+ * The two venues take different arguments. A curve pays `msg.sender` and has
+ * no recipient; a pool swap has no referrer or developer and cannot graduate
+ * anything, so a gas limit guards nothing there. The SDK refuses each of these
+ * on the wrong venue, and so does this server — earlier, before anything is
+ * quoted or sent, and in words that say why. A parameter silently ignored is a
+ * referrer promised a share the chain never saw, or a payout sent to an address
+ * nobody named.
+ *
+ * @module
+ */
+import { addr, note, report, ZERO_ADDRESS } from "../format.js";
+import { resolveCurve } from "./resolve.js";
+/**
+ * Resolve a token-or-curve address to its curve, its trade handle, and where it
+ * trades now.
+ */
+export async function resolveMarket(ctx, address) {
+    const resolved = await resolveCurve(ctx.port, address);
+    const trade = ctx.port.trade(resolved.state.token);
+    const venue = await trade.venue();
+    if (venue === "pool")
+        return { ...resolved, trade, venue: "pool" };
+    return { ...resolved, trade, venue: resolved.state.graduated ? "stranded" : "curve" };
+}
+/** The network's v4 router, or `undefined` — and on Arc the zero address is a real account. */
+export function configuredRouter(config) {
+    const router = config.contracts.v4Router;
+    if (router === undefined || router.toLowerCase() === ZERO_ADDRESS)
+        return undefined;
+    return router;
+}
+export function routerName(config) {
+    const router = configuredRouter(config);
+    return router === undefined ? "(no v4 router configured)" : addr(router);
+}
+/** The refusal for a token that graduated and never migrated. */
+export function strandedText(tool) {
+    return report(`${tool}: this token has GRADUATED but has NOT MIGRATED, so it is not tradeable anywhere.`, note("Its bonding curve stopped trading permanently when it reached its target, and its "
+        + "Uniswap v4 pool was never created — the migration that should have run inside the "
+        + "graduating buy ran out of gas and was caught, which happens with no revert and no "
+        + "error. Until somebody calls migrate() there is no market to quote, buy or sell in. "
+        + "migrate() is permissionless and costs only gas: on this server it is arcnow_migrate, "
+        + "available when the operator has enabled writes. Once it has run, the token trades in "
+        + "its pool and this tool routes there. Nothing was quoted and nothing was sent."));
+}
+/** Refuse `referrer`, `developer` or `gasLimit` on a token that trades in its pool. */
+export function refuseCurveOnly(tool, fields, nothing) {
+    const list = fields.join(" and ");
+    const one = fields.length === 1;
+    return report(`Refused: ${list} ${one ? "is a curve-only parameter" : "are curve-only parameters"}, and `
+        + "this token has graduated — it trades in its Uniswap v4 pool, through arcnow.io's "
+        + `router. Nothing was ${nothing}.`, note("A pool swap has no argument for a referrer or a developer: arcnow.io's fee hook pays "
+        + "those two shares of its 1% to the platform recipient, deliberately, because a hook "
+        + "that took them from the trade would let any trader name themselves the referrer and "
+        + "skim the share. And gasLimit guards a bonding curve's graduation, which a pool buy "
+        + `cannot trigger. ${list} ${one ? "is" : "are"} refused rather than ignored, so that `
+        + "nobody is told a share was credited, or a limit was set, that the chain was never "
+        + `asked for. Call ${tool} again without ${one ? "it" : "them"}.`));
+}
+/** Refuse `recipient` on a token still on its curve. */
+export function refusePoolOnlyRecipient(tool) {
+    return report("Refused: recipient is a pool-only parameter, and this token is still on its bonding "
+        + "curve. Nothing was sent.", note("A bonding-curve trade always pays msg.sender — the signing address — and has no "
+        + "recipient argument anywhere in it, so there is no way to honour one. It is refused "
+        + "rather than ignored, because a trade that paid somebody other than the address named "
+        + `is the worst possible way to find that out. Call ${tool} again without recipient and `
+        + "move the proceeds afterwards; once the token graduates and migrates, its pool trades "
+        + "can pay another address."));
+}
+/** Refuse `approveRouter` on a curve sell, which needs no approval at all. */
+export function refuseCurveApproval() {
+    return report("Refused: approveRouter is a pool-only parameter, and this token is still on its bonding "
+        + "curve. Nothing was sent and nothing was approved.", note("A bonding-curve sell needs no approval, ever: the curve pulls the tokens through a "
+        + "privileged path that reads no allowance at all. This server will not grant spending "
+        + "rights that nothing is going to use. Call arcnow_sell again without approveRouter."));
+}
+/** The venue changed between the read and the quote: the token migrated mid-call. */
+export function venueMovedText(tool) {
+    return report(`${tool}: this token's venue changed while the call was running — it was on one venue `
+        + "when it was read and on the other when it was quoted. Nothing was sent.", note("A token moves from its curve to its pool once, at migration. Call again and it will "
+        + "be quoted where it trades now."));
+}
+/** "0x… (the signing address)", or the same address flagged as somebody else's. */
+export function payee(recipient, signer) {
+    return signer !== undefined && recipient.toLowerCase() === signer.toLowerCase()
+        ? `${addr(recipient)} (the signing address)`
+        : `${addr(recipient)} — NOT the signing address. Whatever reaches a wrong address is gone.`;
+}
+//# sourceMappingURL=venue.js.map

package/dist/tools/venue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"venue.js","sourceRoot":"","sources":["../../src/tools/venue.ts"],"names":[],"mappings":"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"}

package/dist/tools/write.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The write tools: everything that can cost somebody something.
+ *
+ * # What guards these, in order
+ *
+ * 1. **The operator's opt-in.** These are not published at all unless the
+ *    process was started with `--allow-writes` and a key in the environment.
+ *    A model cannot turn them on, and asking for a key will not help it: see
+ *    `config.ts`.
+ * 2. **The operator's ceilings.** One per quote token — `ARCNOW_MCP_MAX_SPEND_USDC`
+ *    for native USDC, `ARCNOW_MCP_MAX_SPEND_<SYMBOL>` for each other quote, in its
+ *    own units — bound every single call, whatever an argument says. A quote with
+ *    no cap is refused outright. See `./spend.ts`.
+ * 3. **The caller's stated ceiling.** Every spending tool requires
+ *    `maxTotalCost`, in the token's quote: the most the caller believes this call will cost. A
+ *    fresh quote is taken inside the call and compared against it, so a quote
+ *    that went stale between being shown to a person and being acted on is
+ *    caught, and so is a model that was talked into a bigger number than the
+ *    conversation agreed to.
+ * 4. **Nothing that does not apply.** A buy or sell goes wherever the token
+ *    trades — its curve or its pool, as `client.trade(token)` decides — and a
+ *    parameter the venue has no notion of is refused before anything is
+ *    quoted or sent, never silently dropped. See `./venue.ts`.
+ * 5. **The report.** Every one of these states the exact cost and the exact,
+ *    permanent effect before it sends anything, and says afterwards what
+ *    actually happened — including the two things about graduation that are
+ *    invisible from a receipt.
+ *
+ * # The one write here that grants rights rather than spending money
+ *
+ * A sell in a Uniswap v4 pool needs an ERC-20 approval to the router first: a
+ * separate transaction giving the router the right to move the seller's
+ * tokens. `arcnow_sell` never sends one unless the call says
+ * `approveRouter: true`; never for more than the amount being sold; never when
+ * the existing allowance already covers the sale; and always reports it —
+ * token, owner, spender, amount, transaction, the allowance left afterwards —
+ * including when the sell that followed it then failed.
+ *
+ * None of that makes an assistant trustworthy with money. It makes the blast
+ * radius a number somebody chose.
+ *
+ * @module
+ */
+import type { AnyTool, ToolOutput } from "./schema.js";
+export declare const WRITE_TOOLS: readonly AnyTool[];
+/**
+ * What a write tool says when the server is read-only.
+ *
+ * Deliberately a refusal by name rather than "unknown tool". A model that gets
+ * "unknown tool" concludes the server is broken or that it guessed the name
+ * wrong, and tries variations; a model that gets this stops, and can tell the
+ * user the one true thing — that this is a configuration the operator controls
+ * and the conversation cannot.
+ */
+export declare function writeRefusal(name: string): ToolOutput;
+//# sourceMappingURL=write.d.ts.map

package/dist/tools/write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/tools/write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAmDH,OAAO,KAAK,EAAE,OAAO,EAAe,UAAU,EAAE,MAAM,aAAa,CAAC;AA6jCpE,eAAO,MAAM,WAAW,EAAE,SAAS,OAAO,EAOzC,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAoBrD"}