dexe-mcp 0.5.8 → 0.7.0

package/dist/governor/tools/read.js

@@ -0,0 +1,174 @@
+import { z } from "zod";
+import { isAddress } from "ethers";
+import { governorContract, votesContract, readProposal, readQuorum, readVotingPower, } from "../adapter.js";
+import { loadGovernorConfigs, resolveGovernor } from "../loader.js";
+function ok(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+function err(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+const governorIdSchema = z
+    .string()
+    .min(1)
+    .describe("Governor id (e.g. 'uniswap') or 0x-prefixed governor contract address.");
+const addressArg = (desc) => z.string().refine((s) => isAddress(s), { message: "must be a 0x-prefixed 20-byte address" }).describe(desc);
+const proposalIdArg = (desc) => z
+    .string()
+    .refine((s) => {
+    try {
+        BigInt(s);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}, { message: "must be a uint256 (decimal or 0x-hex) string" })
+    .describe(desc);
+export function registerGovernorReadTools(server, rpc) {
+    registerListGovernors(server);
+    registerGetProposal(server, rpc);
+    registerGetVotingPower(server, rpc);
+    registerGetQuorum(server, rpc);
+    registerGetProposalThreshold(server, rpc);
+}
+function registerListGovernors(server) {
+    server.registerTool("dexe_gov_list_governors", {
+        title: "List configured external Governor DAOs",
+        description: "Returns all DAOs registered under src/governor/configs/. Each entry is the static config (chainId, governor address, voting token, voting params, timelock). Read-only, no RPC.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            const all = [...loadGovernorConfigs().values()];
+            return ok(all);
+        }
+        catch (e) {
+            return err(`failed to load governor configs: ${e.message}`);
+        }
+    });
+}
+function registerGetProposal(server, rpc) {
+    server.registerTool("dexe_gov_get_proposal", {
+        title: "Read OpenZeppelin Governor proposal state + tallies",
+        description: "Returns ProposalState (string + numeric enum), proposalSnapshot block, proposalDeadline block, and proposalVotes (for/against/abstain) for the given proposalId on a configured Governor.",
+        inputSchema: {
+            governor: governorIdSchema,
+            proposalId: proposalIdArg("Proposal id as decimal string (Governor uses uint256, often the bytes32 keccak hash interpreted as uint256)."),
+        },
+    }, async ({ governor, proposalId }) => {
+        try {
+            const cfg = resolveGovernor(governor);
+            const provider = rpc.requireProvider(cfg.chainId);
+            const c = governorContract(provider, cfg);
+            const pid = BigInt(proposalId);
+            const readout = await readProposal(c, cfg, pid);
+            return ok({
+                governor: cfg.id,
+                governorAddress: cfg.governorAddress,
+                chainId: cfg.chainId,
+                governorVersion: cfg.governorVersion,
+                proposalId,
+                ...readout,
+            });
+        }
+        catch (e) {
+            return err(`dexe_gov_get_proposal failed: ${e.message}`);
+        }
+    });
+}
+function registerGetVotingPower(server, rpc) {
+    server.registerTool("dexe_gov_get_voting_power", {
+        title: "Read IVotes voting power for an account",
+        description: "Calls IVotes.getPastVotes(account, blockNumber) on the configured Governor's voting token. Falls back to IVotes.getVotes(account) when blockNumber is omitted. Decimals reported alongside raw wei value.",
+        inputSchema: {
+            governor: governorIdSchema,
+            account: addressArg("0x-prefixed account address."),
+            blockNumber: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("Snapshot block. When omitted, current voting power via getVotes(account) is returned."),
+        },
+    }, async ({ governor, account, blockNumber }) => {
+        try {
+            const cfg = resolveGovernor(governor);
+            const provider = rpc.requireProvider(cfg.chainId);
+            const c = votesContract(provider, cfg);
+            const { power, method } = await readVotingPower(c, cfg, account, blockNumber);
+            return ok({
+                governor: cfg.id,
+                account,
+                blockNumber: blockNumber ?? "latest",
+                votingToken: cfg.votingToken,
+                votingPower: { raw: power.toString(), decimals: cfg.votingToken.decimals },
+                method,
+            });
+        }
+        catch (e) {
+            return err(`dexe_gov_get_voting_power failed: ${e.message}`);
+        }
+    });
+}
+function registerGetQuorum(server, rpc) {
+    server.registerTool("dexe_gov_get_quorum", {
+        title: "Read Governor quorum threshold at a snapshot block",
+        description: "Calls Governor.quorum(blockNumber). When blockNumber is omitted, uses the latest block. Also returns the config-derived quorumNumerator/quorumDenominator for cross-check.",
+        inputSchema: {
+            governor: governorIdSchema,
+            blockNumber: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("Snapshot block; latest when omitted."),
+        },
+    }, async ({ governor, blockNumber }) => {
+        try {
+            const cfg = resolveGovernor(governor);
+            const provider = rpc.requireProvider(cfg.chainId);
+            const c = governorContract(provider, cfg);
+            const block = blockNumber ?? (await provider.getBlockNumber());
+            const { quorum, method } = await readQuorum(c, cfg, block);
+            return ok({
+                governor: cfg.id,
+                governorVersion: cfg.governorVersion,
+                blockNumber: block,
+                quorum: quorum.toString(),
+                method,
+                configured: {
+                    numerator: cfg.votingParams.quorumNumerator,
+                    denominator: cfg.votingParams.quorumDenominator,
+                },
+            });
+        }
+        catch (e) {
+            return err(`dexe_gov_get_quorum failed: ${e.message}`);
+        }
+    });
+}
+function registerGetProposalThreshold(server, rpc) {
+    server.registerTool("dexe_gov_get_proposal_threshold", {
+        title: "Read Governor proposalThreshold()",
+        description: "Calls Governor.proposalThreshold() — minimum voting power required to submit a proposal. Returns raw uint256 and config-derived value (when present) for cross-check.",
+        inputSchema: {
+            governor: governorIdSchema,
+        },
+    }, async ({ governor }) => {
+        try {
+            const cfg = resolveGovernor(governor);
+            const provider = rpc.requireProvider(cfg.chainId);
+            const c = governorContract(provider, cfg);
+            const threshold = await c.getFunction("proposalThreshold").staticCall();
+            return ok({
+                governor: cfg.id,
+                proposalThreshold: { raw: threshold.toString(), decimals: cfg.votingToken.decimals },
+                configured: cfg.votingParams.proposalThreshold ?? null,
+            });
+        }
+        catch (e) {
+            return err(`dexe_gov_get_proposal_threshold failed: ${e.message}`);
+        }
+    });
+}
+//# sourceMappingURL=read.js.map

package/dist/governor/tools/read.js.map

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

package/dist/governor/tools/simulate.d.ts

@@ -0,0 +1,6 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { RpcProvider } from "../../rpc.js";
+import { decodeGovernorWrite } from "../encoder.js";
+export declare function registerGovernorSimulateTools(server: McpServer, rpc: RpcProvider): void;
+export { decodeGovernorWrite };
+//# sourceMappingURL=simulate.d.ts.map

package/dist/governor/tools/simulate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simulate.d.ts","sourceRoot":"","sources":["../../../src/governor/tools/simulate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAG3C,OAAO,EAAgB,mBAAmB,EAAyB,MAAM,eAAe,CAAC;AAyDzF,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,GAAG,IAAI,CAGvF;AAqJD,OAAO,EAAE,mBAAmB,EAAE,CAAC"}

package/dist/governor/tools/simulate.js

@@ -0,0 +1,191 @@
+import { z } from "zod";
+import { Interface, ZeroAddress, toUtf8String } from "ethers";
+import { resolveGovernor } from "../loader.js";
+import { governorContract, isBravo, projectVoteImpact, readProposal, readQuorum, stateName } from "../adapter.js";
+import { buildExecute, decodeGovernorWrite } from "../encoder.js";
+const ERROR_STRING_SELECTOR = "0x08c379a0";
+const PANIC_SELECTOR = "0x4e487b71";
+function ok(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+function err(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+function decodeRevert(data) {
+    if (!data || data === "0x")
+        return null;
+    if (data.startsWith(ERROR_STRING_SELECTOR)) {
+        try {
+            const iface = new Interface(["function Error(string)"]);
+            const [reason] = iface.decodeFunctionData("Error", data);
+            return reason;
+        }
+        catch {
+            try {
+                return toUtf8String("0x" + data.slice(10 + 64 + 64));
+            }
+            catch {
+                return data;
+            }
+        }
+    }
+    if (data.startsWith(PANIC_SELECTOR)) {
+        try {
+            const code = BigInt("0x" + data.slice(10));
+            const known = {
+                "1": "assert(false)",
+                "17": "arithmetic overflow/underflow",
+                "18": "division or modulo by zero",
+                "33": "invalid enum conversion",
+                "34": "invalid storage byte array access",
+                "49": "pop() on empty array",
+                "50": "array index out of bounds",
+                "65": "out-of-memory allocation",
+                "81": "call to uninitialized internal function",
+            };
+            const hint = known[code.toString()];
+            return `Panic(0x${code.toString(16)})${hint ? ` — ${hint}` : ""}`;
+        }
+        catch {
+            return `Panic(${data.slice(10)})`;
+        }
+    }
+    return data;
+}
+const governorIdSchema = z
+    .string()
+    .min(1)
+    .describe("Governor id (e.g. 'uniswap', 'compound', 'optimism') or 0x-prefixed governor contract address.");
+const uintLikeSchema = z.union([z.string(), z.number()]);
+export function registerGovernorSimulateTools(server, rpc) {
+    registerSimulateProposal(server, rpc);
+    registerSimulateVoteImpact(server, rpc);
+}
+function registerSimulateProposal(server, rpc) {
+    server.registerTool("dexe_gov_simulate_proposal", {
+        title: "Dry-run Governor.execute() via eth_call",
+        description: "Encodes Governor.execute() for the given proposal (Bravo: proposalId; OZ: targets/values/calldatas + description or hash) and performs eth_call against the configured RPC. Returns {success, revertReason, decodedCall, currentState}. Note: this is a single-block dry-run, NOT a full fork-and-time-warp; proposals still in Queued state with unmet timelock ETA will return a revert with the timelock error. For full execution sim, run against a forked node with time advanced past the ETA.",
+        inputSchema: {
+            governor: governorIdSchema,
+            proposalId: z.string().optional().describe("Required on Bravo. For OZ, optional — provided for state lookup."),
+            targets: z.array(z.string()).optional().describe("OZ only."),
+            values: z.array(uintLikeSchema).optional().describe("OZ only."),
+            calldatas: z.array(z.string()).optional().describe("OZ only."),
+            description: z.string().optional().describe("OZ only. Auto-hashed."),
+            descriptionHash: z.string().optional().describe("OZ only. Use when description is unknown."),
+            from: z
+                .string()
+                .optional()
+                .describe("Caller for eth_call. Defaults to 0x0 — execute() is anyone-callable on both families."),
+            msgValue: uintLikeSchema.optional(),
+        },
+    }, async (args) => {
+        try {
+            const cfg = resolveGovernor(args.governor);
+            const provider = rpc.requireProvider(cfg.chainId);
+            const queueExec = {
+                proposalId: args.proposalId,
+                targets: args.targets,
+                values: args.values,
+                calldatas: args.calldatas,
+                description: args.description,
+                descriptionHash: args.descriptionHash,
+            };
+            const built = buildExecute(cfg, queueExec, args.msgValue);
+            const txReq = {
+                to: built.to,
+                from: args.from ?? ZeroAddress,
+                value: "0x" + BigInt(built.value).toString(16),
+                data: built.data,
+            };
+            let currentState = null;
+            if (args.proposalId) {
+                try {
+                    const c = governorContract(provider, cfg);
+                    const idx = Number(await c.getFunction("state").staticCall(BigInt(args.proposalId)));
+                    currentState = { index: idx, name: stateName(idx) };
+                }
+                catch {
+                    currentState = null;
+                }
+            }
+            try {
+                await provider.call(txReq);
+                return ok({
+                    governor: cfg.id,
+                    governorVersion: cfg.governorVersion,
+                    success: true,
+                    currentState,
+                    executeCalldata: built,
+                });
+            }
+            catch (e) {
+                const reason = decodeRevert(e?.data ?? e?.info?.error?.data ?? e?.error?.data);
+                return ok({
+                    governor: cfg.id,
+                    governorVersion: cfg.governorVersion,
+                    success: false,
+                    revertReason: reason ?? (e instanceof Error ? e.message : String(e)),
+                    currentState,
+                    executeCalldata: built,
+                });
+            }
+        }
+        catch (e) {
+            return err(`dexe_gov_simulate_proposal failed: ${e.message}`);
+        }
+    });
+}
+function registerSimulateVoteImpact(server, rpc) {
+    server.registerTool("dexe_gov_simulate_vote_impact", {
+        title: "Project proposal outcome after a hypothetical vote",
+        description: "Reads current vote tallies + quorum, then projects what the outcome would be if `weight` units of voting power were cast with `support` (0=Against, 1=For, 2=Abstain). Pure projection — no on-chain side effects. Returns currentTallies, projectedTallies, quorumMet, willPass.",
+        inputSchema: {
+            governor: governorIdSchema,
+            proposalId: z.string(),
+            support: z.number().int().min(0).max(2),
+            weight: z.string().describe("Hypothetical vote weight in wei (decimal string)."),
+        },
+    }, async ({ governor, proposalId, support, weight }) => {
+        try {
+            const cfg = resolveGovernor(governor);
+            const provider = rpc.requireProvider(cfg.chainId);
+            const c = governorContract(provider, cfg);
+            const pid = BigInt(proposalId);
+            const readout = await readProposal(c, cfg, pid);
+            const { quorum, method: quorumMethod } = await readQuorum(c, cfg, Number(readout.snapshotBlock));
+            const w = BigInt(weight);
+            const cur = {
+                against: BigInt(readout.votes.against),
+                for: BigInt(readout.votes.for),
+                abstain: BigInt(readout.votes.abstain),
+            };
+            const { projected: proj, quorumMet, willPass } = projectVoteImpact(isBravo(cfg), cur, support, w, quorum);
+            return ok({
+                governor: cfg.id,
+                governorVersion: cfg.governorVersion,
+                proposalId,
+                currentState: readout.state,
+                quorum: { required: quorum.toString(), method: quorumMethod },
+                currentTallies: {
+                    against: cur.against.toString(),
+                    for: cur.for.toString(),
+                    abstain: cur.abstain.toString(),
+                },
+                hypothetical: { support, weight },
+                projectedTallies: {
+                    against: proj.against.toString(),
+                    for: proj.for.toString(),
+                    abstain: proj.abstain.toString(),
+                },
+                projection: { quorumMet, willPass },
+            });
+        }
+        catch (e) {
+            return err(`dexe_gov_simulate_vote_impact failed: ${e.message}`);
+        }
+    });
+}
+// Re-export so build.test can verify decode integration in one place.
+export { decodeGovernorWrite };
+//# sourceMappingURL=simulate.js.map

package/dist/governor/tools/simulate.js.map

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

package/dist/lib/broadcastGuards.d.ts

@@ -0,0 +1,41 @@
+import type { DexeConfig } from "../config.js";
+/**
+ * Signer broadcast guards. A single `runBroadcastGuards` chains opt-in checks
+ * that run before every `wallet.sendTransaction()` — both the single-shot
+ * `dexe_tx_send` and the shared composite-flow loop (`sendOrCollect`). Each
+ * guard is a no-op when its env var is unset, so the default (calldata) posture
+ * is unchanged. They only bite once a `DEXE_PRIVATE_KEY` is configured and a
+ * broadcast is attempted.
+ *
+ *   B6  destination allowlist  — `DEXE_SIGNER_ALLOWLIST`
+ *   B7  value cap              — `DEXE_SIGNER_MAX_VALUE_WEI`
+ *   B9  auto-simulation        — eth_call preflight, abort on revert
+ *   B10 rate limit             — `DEXE_SIGNER_MAX_BROADCASTS_PER_MIN`
+ *
+ * B6/B7/B10 are stateless and safe on any broadcast. B9 simulates against
+ * *current* chain state, so it is unsound for dependent multi-step sequences
+ * (e.g. approve→deposit→createProposal): step N would be simmed before step
+ * N-1 is mined and falsely "revert". Composite flows therefore pass
+ * `skipSimulation: true`; the security-relevant guards still apply.
+ */
+/** Transaction about to be broadcast. `from`/`chainId` come from the resolved signer. */
+export interface BroadcastTx {
+    to: string;
+    data: string;
+    /** Wei value as decimal string. */
+    value: string;
+    chainId: number;
+    /** Signer address — used as the `from` for the B9 eth_call. */
+    from: string;
+}
+/** Thrown when a guard refuses a broadcast. `guard` is the backlog id (B6/B7/B9/B10). */
+export declare class BroadcastGuardError extends Error {
+    readonly guard: string;
+    constructor(guard: string, message: string);
+}
+/** Reset the B10 window. Test-only. */
+export declare function __resetBroadcastWindow(): void;
+export declare function runBroadcastGuards(tx: BroadcastTx, cfg: DexeConfig, opts?: {
+    skipSimulation?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=broadcastGuards.d.ts.map

package/dist/lib/broadcastGuards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"broadcastGuards.d.ts","sourceRoot":"","sources":["../../src/lib/broadcastGuards.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAI/C;;;;;;;;;;;;;;;;;;GAkBG;AAEH,yFAAyF;AACzF,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;CACd;AAED,yFAAyF;AACzF,qBAAa,mBAAoB,SAAQ,KAAK;IAE1C,QAAQ,CAAC,KAAK,EAAE,MAAM;gBAAb,KAAK,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM;CAKlB;AASD,uCAAuC;AACvC,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C;AAED,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,WAAW,EACf,GAAG,EAAE,UAAU,EACf,IAAI,CAAC,EAAE;IAAE,cAAc,CAAC,EAAE,OAAO,CAAA;CAAE,GAClC,OAAO,CAAC,IAAI,CAAC,CA6Ef"}

package/dist/lib/broadcastGuards.js

@@ -0,0 +1,85 @@
+import pLimit from "p-limit";
+import { RpcProvider } from "../rpc.js";
+import { simulateCalldata } from "../tools/simulate.js";
+/** Thrown when a guard refuses a broadcast. `guard` is the backlog id (B6/B7/B9/B10). */
+export class BroadcastGuardError extends Error {
+    guard;
+    constructor(guard, message) {
+        super(message);
+        this.guard = guard;
+        this.name = "BroadcastGuardError";
+    }
+}
+// ---- B10 sliding-window state -------------------------------------------
+// Module-scoped so the window survives across tool calls for the process
+// lifetime. Serialized through p-limit(1) so concurrent broadcasts cannot
+// race the prune/append on the timestamp array.
+const rateLimitGate = pLimit(1);
+const broadcastTimestamps = [];
+/** Reset the B10 window. Test-only. */
+export function __resetBroadcastWindow() {
+    broadcastTimestamps.length = 0;
+}
+export async function runBroadcastGuards(tx, cfg, opts) {
+    // ---- B6: destination allowlist ----------------------------------------
+    if (cfg.signerAllowlist && cfg.signerAllowlist.length > 0) {
+        const to = tx.to.toLowerCase();
+        if (!cfg.signerAllowlist.includes(to)) {
+            throw new BroadcastGuardError("B6", `Destination ${tx.to} is not in DEXE_SIGNER_ALLOWLIST (${cfg.signerAllowlist.length} allowed). ` +
+                `Refusing to broadcast.`);
+        }
+    }
+    // ---- B7: value cap ----------------------------------------------------
+    if (cfg.signerMaxValueWei !== undefined) {
+        const v = BigInt(tx.value);
+        if (v > cfg.signerMaxValueWei) {
+            throw new BroadcastGuardError("B7", `Value ${v.toString()} wei exceeds DEXE_SIGNER_MAX_VALUE_WEI cap of ${cfg.signerMaxValueWei.toString()} wei. ` +
+                `Refusing to broadcast.`);
+        }
+    }
+    // ---- B9: auto-simulation (eth_call preflight) -------------------------
+    // Reuses the shared sim core; aborts before spending gas if the call would
+    // revert. Must run against the SAME chain the broadcast targets — otherwise
+    // the preflight is meaningless (sims one chain, sends to another). The shared
+    // `simulateCalldata` resolves its provider via the config's default chain and
+    // takes no chainId, so hand it a config view whose default IS `tx.chainId`.
+    // Skipped for dependent multi-step composite flows (see header).
+    if (!opts?.skipSimulation) {
+        const simCfg = tx.chainId === cfg.defaultChainId
+            ? cfg
+            : { ...cfg, defaultChainId: tx.chainId, chainId: tx.chainId };
+        const rpc = new RpcProvider(simCfg);
+        const sim = await simulateCalldata(rpc, {
+            to: tx.to,
+            data: tx.data,
+            value: tx.value,
+            from: tx.from,
+        });
+        // Only a *genuine* revert aborts. A transport/RPC failure (sim.networkError)
+        // means the call never ran — fail open rather than wedge a valid broadcast
+        // and mislabel an infra hiccup as a revert.
+        if (!sim.success && !sim.networkError) {
+            throw new BroadcastGuardError("B9", `Pre-broadcast simulation (eth_call) reverted: ${sim.revertReason ?? "unknown"}. ` +
+                `Aborting before spending gas.`);
+        }
+    }
+    // ---- B10: rate limit (N per rolling 60s) ------------------------------
+    if (cfg.signerMaxBroadcastsPerMin !== undefined) {
+        const cap = cfg.signerMaxBroadcastsPerMin;
+        await rateLimitGate(() => {
+            const now = Date.now();
+            const cutoff = now - 60_000;
+            while (broadcastTimestamps.length > 0 && broadcastTimestamps[0] < cutoff) {
+                broadcastTimestamps.shift();
+            }
+            if (broadcastTimestamps.length >= cap) {
+                const oldest = broadcastTimestamps[0];
+                const waitS = Math.ceil((oldest + 60_000 - now) / 1000);
+                throw new BroadcastGuardError("B10", `Broadcast rate limit reached: ${cap} per minute (DEXE_SIGNER_MAX_BROADCASTS_PER_MIN). ` +
+                    `Retry in ~${waitS}s.`);
+            }
+            broadcastTimestamps.push(now);
+        });
+    }
+}
+//# sourceMappingURL=broadcastGuards.js.map

package/dist/lib/broadcastGuards.js.map

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

package/dist/lib/ethersProvider.d.ts

@@ -0,0 +1,96 @@
+import { JsonRpcProvider, type TypedDataDomain, type TypedDataField } from "ethers";
+/**
+ * Ethers layer for the Safe{Wallet} multisig integration. Houses everything
+ * the `dexe_safe_*` tools need that is *not* a tool registration:
+ *
+ *  - the Safe Smart Account read ABI + `readSafeState`
+ *  - the canonical `SafeTx` EIP-712 type set + domain + `computeSafeTxHash`
+ *  - the chainId → Safe Transaction Service endpoint resolver
+ *
+ * Kept separate from `../rpc.ts` (which is the generic gov-tool provider cache)
+ * so the Safe-specific crypto stays in one auditable place.
+ */
+export declare const SAFE_ABI: readonly ["function nonce() view returns (uint256)", "function getThreshold() view returns (uint256)", "function getOwners() view returns (address[])", "function isOwner(address owner) view returns (bool)", "function VERSION() view returns (string)"];
+export interface SafeState {
+    safe: string;
+    nonce: bigint;
+    threshold: bigint;
+    owners: string[];
+    version: string;
+}
+/**
+ * Read the live Safe state (nonce, threshold, owners, version) over a single
+ * provider. Each call is independent; `VERSION` is best-effort because some
+ * very old singletons predate it.
+ */
+export declare function readSafeState(provider: JsonRpcProvider, safeAddress: string): Promise<SafeState>;
+/** CALL = 0, DELEGATECALL = 1. Safe rejects any other value. */
+export declare const SAFE_OPERATION: {
+    readonly CALL: 0;
+    readonly DELEGATECALL: 1;
+};
+/**
+ * The `SafeTx` struct as signed by owners. Field order is consensus-critical:
+ * it must match `Safe.encodeTransactionData` exactly or the recovered signer
+ * will not be an owner and the service rejects the proposal.
+ */
+export declare const SAFE_TX_TYPES: Record<string, TypedDataField[]>;
+export interface SafeTx {
+    to: string;
+    value: string;
+    data: string;
+    operation: number;
+    safeTxGas: string;
+    baseGas: string;
+    gasPrice: string;
+    gasToken: string;
+    refundReceiver: string;
+    nonce: string;
+}
+/**
+ * EIP-712 domain for a Safe >= 1.3.0: `{ chainId, verifyingContract }`. Earlier
+ * singletons (< 1.3.0) used `{ verifyingContract }` only; those are not
+ * targeted here — `dexe_safe_*` assumes a modern (1.3.0 / 1.4.1) singleton.
+ */
+export declare function safeTxDomain(chainId: number, safeAddress: string): TypedDataDomain;
+/** Build a normalized SafeTx with the protocol defaults filled in. */
+export declare function buildSafeTx(input: {
+    to: string;
+    value?: string;
+    data?: string;
+    operation?: number;
+    safeTxGas?: string;
+    baseGas?: string;
+    gasPrice?: string;
+    gasToken?: string;
+    refundReceiver?: string;
+    nonce: string | bigint;
+}): SafeTx;
+/**
+ * Deterministic `safeTxHash` — the value owners sign and the service indexes
+ * the transaction under. Equivalent to `Safe.getTransactionHash(...)` on-chain.
+ */
+export declare function computeSafeTxHash(chainId: number, safeAddress: string, tx: SafeTx): string;
+/**
+ * chainId → Safe Transaction Service "short name" used in the unified
+ * `https://api.safe.global/tx-service/<shortname>/api/v2` base. Sourced from
+ * the public Safe API reference. BSC testnet (97) has no hosted service — it
+ * must be supplied via `DEXE_SAFE_TX_SERVICE_URL`.
+ */
+export declare const SAFE_TX_SERVICE_SHORTNAMES: Record<number, string>;
+export interface SafeServiceEndpoint {
+    /** Base URL ending in `/api/v2` (no trailing slash). */
+    base: string;
+    /** Full POST target for creating a multisig transaction. */
+    multisigTransactions: (safe: string) => string;
+    /** True when the base was derived from the hosted api.safe.global service. */
+    hosted: boolean;
+}
+/**
+ * Resolve the Safe Transaction Service base for a chain. When
+ * `override` (DEXE_SAFE_TX_SERVICE_URL) is set it wins unconditionally — that
+ * is the escape hatch for self-hosted services and unsupported chains (e.g.
+ * BSC testnet). Throws when neither an override nor a known short name exists.
+ */
+export declare function resolveSafeServiceEndpoint(chainId: number, override?: string): SafeServiceEndpoint;
+//# sourceMappingURL=ethersProvider.d.ts.map

package/dist/lib/ethersProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ethersProvider.d.ts","sourceRoot":"","sources":["../../src/lib/ethersProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,eAAe,EAKf,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,QAAQ,CAAC;AAEhB;;;;;;;;;;GAUG;AAMH,eAAO,MAAM,QAAQ,4PAMX,CAAC;AAEX,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,eAAe,EACzB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,SAAS,CAAC,CAyBpB;AAMD,gEAAgE;AAChE,eAAO,MAAM,cAAc;;;CAAwC,CAAC;AAEpE;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,EAAE,CAa1D,CAAC;AAEF,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,eAAe,CAElF;AAED,sEAAsE;AACtE,wBAAgB,WAAW,CAAC,KAAK,EAAE;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CACxB,GAAG,MAAM,CAuBT;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAE1F;AAMD;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAY7D,CAAC;AAEF,MAAM,WAAW,mBAAmB;IAClC,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,oBAAoB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/C,8EAA8E;IAC9E,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,GAChB,mBAAmB,CA0BrB"}