@zktx.io/sui-mcp 0.5.0

package/dist/adapters/deepbook/deepbookTransactionMaterialProducer.js

@@ -0,0 +1,254 @@
+import { SimulationError } from "@mysten/sui/client";
+import { DeepBookClient, mainnetCoins } from "@mysten/deepbook-v3";
+import { Transaction } from "@mysten/sui/transactions";
+import { parseDeepbookRawU64 } from "../../core/read/deepbookReadHelpers.js";
+import { suiTransactionDigestSchema } from "../../core/suiAddress.js";
+import { failReviewCheck, passReviewCheck } from "../../core/review/reviewComputationResult.js";
+const DEEPBOOK_SWAP_GAS_BUDGET_MIST = 50000000n;
+const SUI_COIN_TYPE = "0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI";
+export function deepbookSwapBalanceRequirements(input) {
+    if (input.sourceCoinType === SUI_COIN_TYPE) {
+        return [
+            {
+                symbol: input.sourceSymbol,
+                coinType: SUI_COIN_TYPE,
+                decimals: input.sourceDecimals,
+                requiredRaw: input.sourceAmountRaw + DEEPBOOK_SWAP_GAS_BUDGET_MIST
+            }
+        ];
+    }
+    return [
+        {
+            symbol: input.sourceSymbol,
+            coinType: input.sourceCoinType,
+            decimals: input.sourceDecimals,
+            requiredRaw: input.sourceAmountRaw
+        },
+        { symbol: "SUI", coinType: SUI_COIN_TYPE, decimals: 9, requiredRaw: DEEPBOOK_SWAP_GAS_BUDGET_MIST }
+    ];
+}
+function displayRaw(raw, decimals) {
+    const base = 10n ** BigInt(decimals);
+    const whole = raw / base;
+    const fraction = (raw % base).toString().padStart(decimals, "0").replace(/0+$/, "");
+    return fraction ? `${whole}.${fraction}` : whole.toString();
+}
+export function createDeepbookSwapTransactionMaterialProducer(options) {
+    return async (input) => {
+        if (options.network !== "mainnet" || options.chainIdentifier !== options.expectedChainIdentifier) {
+            return {
+                status: "blocked",
+                blockedReason: "network_mismatch",
+                checks: [
+                    failReviewCheck("deepbook_transaction_material_network_mismatch", "Transaction material network", "DeepBook transaction material build requires a verified Sui mainnet gRPC endpoint and matching mainnet chain identifier.", "network")
+                ]
+            };
+        }
+        if (input.poolResolution.direction !== input.quotePolicy.direction || input.quote.direction !== input.quotePolicy.direction) {
+            return {
+                status: "blocked",
+                blockedReason: "amount_mismatch",
+                checks: [
+                    failReviewCheck("deepbook_transaction_material_quote_direction_mismatch", "Transaction material quote policy", "DeepBook transaction material build requires pool direction, quote evidence, and quote policy to describe the same swap direction.", "adapter")
+                ]
+            };
+        }
+        const quoteExpiresAt = quotePolicyExpiresAt(input.quotePolicy);
+        if (quoteExpiresAt.getTime() <= input.now.getTime()) {
+            return {
+                status: "refresh_required",
+                refreshReason: "quote_stale",
+                checks: [
+                    failReviewCheck("deepbook_transaction_material_quote_expired", "Transaction material quote policy", "DeepBook transaction material was not built because the quote policy expired before build.", "quote")
+                ]
+            };
+        }
+        let sourceAmountRaw;
+        let minOutRaw;
+        let deepAmountRaw;
+        try {
+            sourceAmountRaw = parseDeepbookRawU64(input.quotePolicy.sourceAmountRaw, "sourceAmountRaw", { positive: true });
+            minOutRaw = parseDeepbookRawU64(input.quotePolicy.minOutRaw, "minOutRaw", { positive: true });
+            deepAmountRaw = parseDeepbookRawU64(input.quotePolicy.deepAmountRaw, "deepAmountRaw");
+        }
+        catch (error) {
+            return {
+                status: "blocked",
+                blockedReason: "amount_mismatch",
+                checks: [
+                    failReviewCheck("deepbook_transaction_material_raw_amount_invalid", "Transaction material quote policy", error instanceof Error ? error.message : "DeepBook transaction material requires valid raw u64 quote policy amounts.", "quote")
+                ]
+            };
+        }
+        try {
+            const sourceQuoteAmount = input.quote.rawQuote.inputAmount;
+            const requirements = deepbookSwapBalanceRequirements({
+                sourceSymbol: sourceQuoteAmount.symbol,
+                sourceCoinType: sourceQuoteAmount.coinType,
+                sourceDecimals: sourceQuoteAmount.decimals,
+                sourceAmountRaw: sourceAmountRaw
+            });
+            for (const requirement of requirements) {
+                const balance = await options.client.core.getBalance({
+                    owner: input.account,
+                    coinType: requirement.coinType
+                });
+                const heldRaw = BigInt(balance.balance.balance);
+                if (heldRaw < requirement.requiredRaw) {
+                    const isGasOnly = requirement.coinType === SUI_COIN_TYPE && sourceQuoteAmount.coinType !== SUI_COIN_TYPE;
+                    return {
+                        status: "blocked",
+                        blockedReason: "insufficient_balance",
+                        checks: [
+                            failReviewCheck("deepbook_transaction_material_build_failed", "Transaction material build", `Insufficient balance: this swap needs ${displayRaw(requirement.requiredRaw, requirement.decimals)} ${requirement.symbol}${isGasOnly ? " for gas" : requirement.coinType === SUI_COIN_TYPE ? " (amount + gas)" : ""}, but the account holds ${displayRaw(heldRaw, requirement.decimals)} ${requirement.symbol}. Nothing was signed and no funds moved.`, "adapter")
+                        ]
+                    };
+                }
+            }
+            const deepbook = new DeepBookClient({
+                client: options.client,
+                address: input.account,
+                network: options.network
+            });
+            const transaction = new Transaction();
+            transaction.setSender(input.account);
+            // The DeepBook SDK reserves a 0.25 SUI gas budget by default, which
+            // blocks small wallets whose balance is close to the swap amount. A
+            // mainnet DeepBook swap costs well under this explicit 0.05 SUI budget.
+            transaction.setGasBudget(DEEPBOOK_SWAP_GAS_BUDGET_MIST);
+            // input_coin fee mode swaps with an explicit zero DEEP coin; the Move
+            // entry point then charges the taker fee in the source coin at the
+            // protocol penalty. The explicit zero coin avoids SDK coin selection,
+            // which cannot resolve a zero balance for accounts holding no DEEP.
+            const inputFeeMode = input.quotePolicy.feeMode === "input_coin";
+            const zeroDeepCoin = inputFeeMode
+                ? transaction.moveCall({
+                    target: "0x2::coin::zero",
+                    typeArguments: [mainnetCoins.DEEP.type]
+                })
+                : undefined;
+            const swapDeepAmountRaw = inputFeeMode ? 0n : deepAmountRaw;
+            const [baseCoinResult, quoteCoinResult, deepCoinResult] = input.quotePolicy.direction === "base_to_quote"
+                ? deepbook.deepBook.swapExactBaseForQuote({
+                    poolKey: input.poolResolution.poolKey,
+                    amount: sourceAmountRaw,
+                    minOut: minOutRaw,
+                    deepAmount: swapDeepAmountRaw,
+                    ...(zeroDeepCoin ? { deepCoin: zeroDeepCoin } : {})
+                })(transaction)
+                : deepbook.deepBook.swapExactQuoteForBase({
+                    poolKey: input.poolResolution.poolKey,
+                    amount: sourceAmountRaw,
+                    minOut: minOutRaw,
+                    deepAmount: swapDeepAmountRaw,
+                    ...(zeroDeepCoin ? { deepCoin: zeroDeepCoin } : {})
+                })(transaction);
+            transaction.transferObjects([baseCoinResult, quoteCoinResult, deepCoinResult], input.account);
+            const transactionBytes = await transaction.build({ client: options.client });
+            options.materialStore.deleteReviewSessionTransactionMaterials(input.reviewSessionId);
+            const handle = options.materialStore.recordTransactionMaterial({
+                reviewSessionId: input.reviewSessionId,
+                planId: input.plan.id,
+                account: input.account,
+                kind: "deepbook_swap_transaction_data",
+                source: "sui_mcp_built",
+                transactionBytes,
+                expiresAt: quoteExpiresAt,
+                redactedDiagnostics: {
+                    protocol: input.plan.protocol,
+                    adapterId: input.plan.adapterId,
+                    actionKind: input.plan.actionKind,
+                    poolKey: input.poolResolution.poolKey,
+                    direction: input.quotePolicy.direction,
+                    quoteFetchedAt: input.quotePolicy.fetchedAt,
+                    quoteExpiresAt: quoteExpiresAt.toISOString(),
+                    sourceAmountRaw: input.quotePolicy.sourceAmountRaw,
+                    minOutRaw: input.quotePolicy.minOutRaw,
+                    deepAmountRaw: input.quotePolicy.deepAmountRaw
+                }
+            }, input.now);
+            return {
+                status: "completed",
+                evidence: handle,
+                checks: [
+                    passReviewCheck("deepbook_transaction_material_built", "Transaction material build", "Built account-bound DeepBook swap transaction material from Sui MCP quote policy and stored the unsigned transaction bytes only in the local material store until quote expiry. This is not wallet handoff, signing data, signing readiness, or execution readiness.", "adapter")
+                ]
+            };
+        }
+        catch (error) {
+            return {
+                status: "blocked",
+                blockedReason: "object_resolution_failed",
+                checks: [
+                    failReviewCheck("deepbook_transaction_material_build_failed", "Transaction material build", buildFailureMessage(error), "adapter")
+                ]
+            };
+        }
+    };
+}
+export function createDeepbookSwapTransactionMaterialDigestProducer(options) {
+    return async (input) => {
+        const material = options.materialStore.getTransactionMaterial(input.materialHandle, input.now);
+        if (!material) {
+            return {
+                status: "refresh_required",
+                refreshReason: "quote_stale",
+                checks: [
+                    failReviewCheck("deepbook_transaction_material_digest_unavailable", "Transaction material digest", "DeepBook transaction material digest was not computed because the stored local material was unavailable or expired; refresh the review evidence before continuing.", "adapter")
+                ]
+            };
+        }
+        let transactionDigest;
+        try {
+            transactionDigest = await Transaction.from(material.transactionBytes).getDigest();
+        }
+        catch {
+            return {
+                status: "blocked",
+                blockedReason: "object_resolution_failed",
+                checks: [
+                    failReviewCheck("deepbook_transaction_material_digest_failed", "Transaction material digest", "DeepBook transaction material digest could not be derived from the stored local transaction bytes.", "adapter")
+                ]
+            };
+        }
+        const parsedDigest = suiTransactionDigestSchema.safeParse(transactionDigest);
+        if (!parsedDigest.success) {
+            return {
+                status: "blocked",
+                blockedReason: "object_resolution_failed",
+                checks: [
+                    failReviewCheck("deepbook_transaction_material_digest_invalid", "Transaction material digest", "DeepBook transaction material digest did not match the pinned Sui SDK transaction digest format.", "adapter")
+                ]
+            };
+        }
+        return {
+            status: "completed",
+            evidence: {
+                materialId: material.materialId,
+                reviewSessionId: material.reviewSessionId,
+                planId: material.planId,
+                account: material.account,
+                kind: material.kind,
+                source: material.source,
+                digestKind: "sui_transaction_digest",
+                transactionDigest: parsedDigest.data,
+                computedAt: input.now.toISOString(),
+                expiresAt: material.expiresAt
+            },
+            checks: [
+                passReviewCheck("deepbook_transaction_material_digest_commitment", "Transaction material digest", "Derived a Sui transaction digest from the stored local unsigned transaction material. The digest and bytes remain internal until later review stages bind object ownership, human-readable review, and simulation evidence.", "adapter")
+            ]
+        };
+    };
+}
+function quotePolicyExpiresAt(policy) {
+    return new Date(Date.parse(policy.fetchedAt) + policy.staleAfterMs);
+}
+function buildFailureMessage(error) {
+    // The pinned SDK discards some gRPC error kinds when building a transaction.
+    // Its error text cannot establish an account-balance or gas shortfall.
+    if (error instanceof SimulationError && error.executionError) {
+        return "DeepBook transaction was rejected during build-time simulation. Refresh the review or inspect its selected constraints. Nothing was signed or submitted.";
+    }
+    return "DeepBook transaction material could not be built and verified. Nothing was signed or submitted.";
+}

package/dist/adapters/intentPlanFactories.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { createDeepbookSwapActionPlan, DEEPBOOK_SWAP_ACTION_KIND, DEEPBOOK_SWAP_ADAPTER_ID, DEEPBOOK_SWAP_PROTOCOL } from "./deepbook/deepbookSwapIntent.js";
+/**
+ * Protocol-neutral swap intent. The optional `protocol` field carries the
+ * protocol slug (same slug vocabulary as the adapter prompt surfaces). When
+ * several protocols support the same action kind, the caller must name one -
+ * the entry point never picks a venue silently.
+ */
+export const swapIntentInputSchema = z.object({
+    type: z.literal("swap"),
+    from: z.object({
+        symbol: z.string().min(1),
+        amount: z.string().min(1)
+    }),
+    to: z.object({
+        symbol: z.string().min(1)
+    }),
+    maxSlippageBps: z.number().int().min(1).max(1000),
+    protocol: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Protocol slug, required only when several protocols support the action")
+});
+export const INTENT_PLAN_FACTORIES = [
+    {
+        adapterId: DEEPBOOK_SWAP_ADAPTER_ID,
+        actionKind: DEEPBOOK_SWAP_ACTION_KIND,
+        protocolSlug: "deep",
+        protocol: DEEPBOOK_SWAP_PROTOCOL,
+        createPlan: (intent, now) => createDeepbookSwapActionPlan({ ...intent, type: "swap" }, now)
+    }
+];
+export function resolveIntentPlanFactory(factories, actionKind, protocolSlug) {
+    const group = factories.filter((factory) => factory.actionKind === actionKind);
+    if (group.length === 0) {
+        return { status: "unsupported_action", actionKind };
+    }
+    const available = group.map((factory) => factory.protocolSlug);
+    if (protocolSlug !== undefined) {
+        const factory = group.find((candidate) => candidate.protocolSlug === protocolSlug.trim());
+        if (!factory) {
+            return { status: "unknown_protocol", protocolSlug, available };
+        }
+        return { status: "resolved", factory };
+    }
+    if (group.length === 1 && group[0]) {
+        return { status: "resolved", factory: group[0] };
+    }
+    return { status: "protocol_choice_required", available };
+}

package/dist/adapters/reviewAdapters.js

@@ -0,0 +1,47 @@
+import { computeDeepbookSwapReviewEvidence } from "./deepbook/deepbookReviewEvidence.js";
+import { DEEPBOOK_SWAP_ACTION_KIND, DEEPBOOK_SWAP_ADAPTER_ID, DEEPBOOK_SWAP_PROTOCOL, isDeepbookSwapActionPlanIdentity } from "./deepbook/deepbookSwapIntent.js";
+import { DEEPBOOK_SWAP_REVIEW_LIFECYCLE_STAGE_CATALOG_ID } from "./deepbook/deepbookReviewLifecycle.js";
+import { unsupportedDeepbookSwapPlanIdentityCheck } from "../core/review/reviewChecks.js";
+import { blockedReviewResult } from "../core/review/reviewComputationResult.js";
+export function buildSupportedReviewAdapterDescriptors(wiring) {
+    const descriptors = [
+        {
+            adapterId: DEEPBOOK_SWAP_ADAPTER_ID,
+            protocol: DEEPBOOK_SWAP_PROTOCOL,
+            actionKind: DEEPBOOK_SWAP_ACTION_KIND,
+            stageCatalogId: DEEPBOOK_SWAP_REVIEW_LIFECYCLE_STAGE_CATALOG_ID,
+            computeReview: deepbookSwapEvidenceComputer(wiring.deepbook)
+        }
+    ];
+    return descriptors;
+}
+function deepbookSwapEvidenceComputer(wiring) {
+    return async (input) => {
+        if (!isDeepbookSwapActionPlanIdentity(input.plan)) {
+            return {
+                result: blockedReviewResult("unsupported_action", [unsupportedDeepbookSwapPlanIdentityCheck()])
+            };
+        }
+        return computeDeepbookSwapReviewEvidence({
+            reviewSessionId: input.reviewSessionId,
+            plan: input.plan,
+            account: input.account,
+            now: input.now,
+            quoteSource: wiring.deepbookQuoteSource,
+            deepBalanceSource: wiring.deepbookDeepBalanceSource,
+            transactionMaterialProducer: wiring.deepbookTransactionMaterialProducer,
+            transactionMaterialDigestProducer: wiring.deepbookTransactionMaterialDigestProducer,
+            transactionObjectOwnershipProducer: wiring.transactionObjectOwnershipProducer,
+            humanReadableReviewProducer: wiring.deepbookHumanReadableReviewProducer,
+            reviewTimeSimulationProducer: wiring.reviewTimeSimulationProducer,
+            ptbVisualizationProducer: wiring.ptbVisualizationProducer
+        });
+    };
+}
+export function buildSupportedReviewAdapters(wiring) {
+    const adapters = {};
+    for (const descriptor of buildSupportedReviewAdapterDescriptors(wiring)) {
+        adapters[descriptor.adapterId] = descriptor.computeReview;
+    }
+    return adapters;
+}

package/dist/core/action/adapterLifecycleValidation.js

@@ -0,0 +1,12 @@
+export function createAdapterLifecycleValidator(validatorsByStageCatalogId) {
+    return (lifecycle) => {
+        const validator = validatorsByStageCatalogId[lifecycle.stageCatalogId];
+        if (!validator) {
+            throw new Error(`Unsupported adapter lifecycle stage catalog: ${lifecycle.stageCatalogId}`);
+        }
+        validator(lifecycle);
+    };
+}
+export const rejectAdapterLifecycle = (lifecycle) => {
+    throw new Error(`Adapter lifecycle is not accepted here: ${lifecycle.stageCatalogId}`);
+};

package/dist/core/action/contractNameRegistry.js

@@ -0,0 +1,151 @@
+import { mainnetPackageIds } from "@mysten/deepbook-v3";
+import { MOVE_STDLIB_ADDRESS, normalizeSuiAddress, SUI_CLOCK_OBJECT_ID, SUI_COIN_REGISTRY_OBJECT_ID, SUI_DENY_LIST_OBJECT_ID, SUI_FRAMEWORK_ADDRESS, SUI_RANDOM_OBJECT_ID, SUI_SYSTEM_ADDRESS, SUI_SYSTEM_STATE_OBJECT_ID } from "@mysten/sui/utils";
+import { DEEPBOOK_SOURCE_FIELD_VALUES } from "../read/deepbookSourceOwners.js";
+/** Packages, relabeled only where they appear as a `<address>::...` path. */
+export const PACKAGE_NAME_REGISTRY = [
+    {
+        address: mainnetPackageIds.DEEPBOOK_PACKAGE_ID,
+        name: "@deepbook/core",
+        source: DEEPBOOK_SOURCE_FIELD_VALUES.sdkMainnetPackageId
+    },
+    {
+        address: MOVE_STDLIB_ADDRESS,
+        name: "std",
+        source: "sui_sdk_move_stdlib_address"
+    },
+    {
+        address: SUI_FRAMEWORK_ADDRESS,
+        name: "sui",
+        source: "sui_sdk_framework_address"
+    },
+    {
+        address: SUI_SYSTEM_ADDRESS,
+        name: "sui_system",
+        source: "sui_sdk_system_address"
+    }
+];
+/** Well-known shared system objects, relabeled only as a bare object id. */
+export const OBJECT_NAME_REGISTRY = [
+    {
+        address: SUI_SYSTEM_STATE_OBJECT_ID,
+        name: "SuiSystemState",
+        source: "sui_sdk_system_state_object_id"
+    },
+    {
+        address: SUI_CLOCK_OBJECT_ID,
+        name: "Clock",
+        source: "sui_sdk_clock_object_id"
+    },
+    {
+        address: SUI_RANDOM_OBJECT_ID,
+        name: "Random",
+        source: "sui_sdk_random_object_id"
+    },
+    {
+        address: SUI_DENY_LIST_OBJECT_ID,
+        name: "DenyList",
+        source: "sui_sdk_deny_list_object_id"
+    },
+    {
+        address: SUI_COIN_REGISTRY_OBJECT_ID,
+        name: "CoinRegistry",
+        source: "sui_sdk_coin_registry_object_id"
+    },
+    {
+        // Address-based balances (coin reservation / fast path) reference the
+        // accumulator root object. @mysten/sui defines this id only internally as
+        // normalizeSuiAddress("0xacc") (not an exported constant), so mirror it here.
+        address: normalizeSuiAddress("0xacc"),
+        name: "AccumulatorRoot",
+        source: "sui_accumulator_root_object_id_0xacc"
+    }
+];
+/**
+ * Normalize a Sui address or package id to `0x` + 64 lowercase hex, or return
+ * undefined when the input is not a well-formed Sui address. Short forms are
+ * left-padded with zeros so different-width forms of the same address compare
+ * equal.
+ */
+function normalizeContractAddress(value) {
+    const lower = value.trim().toLowerCase();
+    const body = lower.startsWith("0x") ? lower.slice(2) : lower;
+    if (body.length === 0 || body.length > 64 || !/^[0-9a-f]+$/.test(body)) {
+        return undefined;
+    }
+    return `0x${body.padStart(64, "0")}`;
+}
+function buildNameMap(entries) {
+    return new Map(entries.flatMap((entry) => {
+        const normalized = normalizeContractAddress(entry.address);
+        return normalized === undefined ? [] : [[normalized, entry.name]];
+    }));
+}
+const PACKAGE_NAME_BY_ADDRESS = buildNameMap(PACKAGE_NAME_REGISTRY);
+const OBJECT_NAME_BY_ADDRESS = buildNameMap(OBJECT_NAME_REGISTRY);
+/**
+ * Replace registered addresses in PTB Mermaid label text with their display
+ * names. Mermaid node ids are synthetic (`command0`, `input0`, ...), so an
+ * address only appears inside quoted label text, and matching is context-aware:
+ *
+ *  - A package is relabeled only where it is a path prefix (`<address>::`), the
+ *    form a MoveCall target or type path takes — never a bare object id.
+ *  - A well-known object is relabeled only where it is a bare id (not followed by
+ *    `::`), the form an object input takes — never a package path.
+ *
+ * Unknown addresses (no registered name) are shortened for the display graph
+ * (leading zeros collapsed, long ids middle-elided); the full address stays in
+ * the artifact's raw `text` stream for audit and copy. Matching uses the full
+ * `0x` + 64-hex address form the PTB renderer (`@zktx.io/ptb-model`) emits; the
+ * registry keys are normalized to that same form.
+ *
+ * Registered package names may be Move Registry names like `@deepbook/core`;
+ * Mermaid v11 reads a literal `@` as node/edge metadata syntax even inside a
+ * quoted label and crashes the renderer, so an inserted `@` is written as the
+ * decimal entity `#64;`, which renders as `@` without a literal `@`. The copyable
+ * Mermaid source keeps raw addresses (it is built from the unmodified text), so
+ * this only affects the rendered graph.
+ */
+export function applyContractNamesToMermaid(mermaidText) {
+    let text = mermaidText;
+    // Packages: only in path position (`<address>::...`).
+    for (const [address, name] of PACKAGE_NAME_BY_ADDRESS) {
+        text = text.split(`${address}::`).join(`${mermaidSafeName(name)}::`);
+    }
+    // Objects: only as a bare id (anything but a `::` path prefix).
+    for (const [address, name] of OBJECT_NAME_BY_ADDRESS) {
+        const safe = mermaidSafeName(name);
+        text = text.replace(new RegExp(`${address}(?!::)`, "g"), () => safe);
+    }
+    // Any address still present (no registered name) is shortened for the display
+    // graph; its `::module::name` suffix, if any, is left intact. The full address
+    // is untouched in the raw `text` stream the artifact keeps for audit and copy.
+    text = text.replace(/0x[0-9a-f]{40,64}(?![0-9a-f])/gi, (address) => shortenAddressForDisplay(address));
+    return text;
+}
+/**
+ * Escape characters that break Mermaid label parsing. A literal `@` triggers
+ * Mermaid v11 node/edge metadata syntax (even inside quotes) and throws, so it
+ * is written as the `#64;` decimal entity, which renders as `@`. The other
+ * registered label characters (letters, `/`, `-`, `_`, `.`, `:`) are valid in
+ * Mermaid label text.
+ */
+function mermaidSafeName(name) {
+    return name.replace(/@/g, "#64;");
+}
+/**
+ * Shorten an unregistered full-length address for the display graph: collapse
+ * leading zeros so low ids read compactly (`0x...0002` -> `0x2`), and middle-elide
+ * a genuinely long id (`0x123456...cdef`). Display only — the raw `text` stream
+ * keeps the full address for audit and copy. Uses ASCII `...` (a Mermaid-valid
+ * label character) rather than a unicode ellipsis.
+ */
+function shortenAddressForDisplay(address) {
+    const body = address.slice(2).replace(/^0+/, "");
+    if (body.length === 0) {
+        return "0x0";
+    }
+    if (body.length <= 12) {
+        return `0x${body}`;
+    }
+    return `0x${body.slice(0, 6)}...${body.slice(-4)}`;
+}

package/dist/core/action/forbiddenFields.js

@@ -0,0 +1,43 @@
+const FORBIDDEN_EDGE_TERMS = [
+    "bytes",
+    "signature",
+    "sessiontoken",
+    "reviewtoken",
+    "wallettoken",
+    "fragmenttoken",
+    "tokenhash",
+    "privatekey",
+    "secretkey",
+    "seed",
+    "mnemonic"
+];
+const FORBIDDEN_PREFIX_OR_SUFFIX_TERMS = ["serialized", "signable"];
+function isForbiddenFieldKey(key) {
+    const normalized = key.toLowerCase();
+    return (FORBIDDEN_EDGE_TERMS.some((term) => normalized === term || normalized.endsWith(term)) ||
+        FORBIDDEN_PREFIX_OR_SUFFIX_TERMS.some((term) => normalized === term || normalized.startsWith(term) || normalized.endsWith(term)));
+}
+export function findForbiddenMcpFields(value, path = "$") {
+    if (value === null || typeof value !== "object") {
+        return [];
+    }
+    if (Array.isArray(value)) {
+        return value.flatMap((item, index) => findForbiddenMcpFields(item, `${path}[${index}]`));
+    }
+    return Object.entries(value).flatMap(([key, nested]) => {
+        const normalized = key.toLowerCase();
+        const currentPath = `${path}.${key}`;
+        // Deliberately conservative: MCP tool output and stored evidence should not
+        // carry raw byte, signing, token, signature, seed, or key material under
+        // direct prefix/suffix key names. Generic domain keys such as tokenSymbol
+        // and bytesPerSecond remain valid.
+        const current = isForbiddenFieldKey(normalized) ? [currentPath] : [];
+        return current.concat(findForbiddenMcpFields(nested, currentPath));
+    });
+}
+export function assertNoForbiddenMcpFields(value) {
+    const forbidden = findForbiddenMcpFields(value);
+    if (forbidden.length > 0) {
+        throw new Error(`MCP payload contains forbidden field(s): ${forbidden.join(", ")}`);
+    }
+}