@zktx.io/sui-mcp 0.5.0

package/dist/core/action/humanReadableReviewEvidence.js

@@ -0,0 +1,193 @@
+import { z } from "zod";
+import { assertNoForbiddenMcpFields } from "./forbiddenFields.js";
+import { WALLET_REVIEW_REQUIRED_HUMAN_FIELDS, adapterHumanReadableReviewSchema } from "./signableAdapterContract.js";
+import { humanReadableReviewSummarySchema } from "./schemas.js";
+import { normalizedSuiAddressSchema, parseSuiAddress, suiTransactionDigestSchema } from "../suiAddress.js";
+export const HUMAN_READABLE_REVIEW_EVIDENCE_VERSION = "human-readable-review-v1";
+const isoUtcStringSchema = z.string().refine((value) => {
+    const parsed = new Date(value);
+    return Number.isFinite(parsed.getTime()) && parsed.toISOString() === value;
+}, "Expected ISO 8601 UTC timestamp");
+export const humanReadableReviewEvidenceSchema = z.object({
+    evidenceVersion: z.literal(HUMAN_READABLE_REVIEW_EVIDENCE_VERSION),
+    materialId: z.string().min(1),
+    reviewSessionId: z.string().min(1),
+    planId: z.string().min(1),
+    account: normalizedSuiAddressSchema,
+    transactionDigest: suiTransactionDigestSchema,
+    kind: z.literal("human_readable_review"),
+    adapterId: z.string().min(1).max(120),
+    protocol: z.string().min(1).max(120),
+    actionKind: z.string().min(1).max(120),
+    network: z.literal("sui:mainnet"),
+    fields: z.array(z.enum(WALLET_REVIEW_REQUIRED_HUMAN_FIELDS)).min(WALLET_REVIEW_REQUIRED_HUMAN_FIELDS.length),
+    source: z.literal("review_model_or_adapter_equivalent"),
+    purpose: z.literal("human_review_before_wallet_authorization"),
+    review: humanReadableReviewSummarySchema,
+    derivedAt: isoUtcStringSchema,
+    expiresAt: isoUtcStringSchema
+}).strict().superRefine((value, ctx) => {
+    const duplicateField = findDuplicate(value.fields);
+    if (duplicateField) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["fields"],
+            message: `Human-readable review fields contains duplicate field '${duplicateField}'`
+        });
+    }
+    if (!WALLET_REVIEW_REQUIRED_HUMAN_FIELDS.every((field) => value.fields.includes(field))) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["fields"],
+            message: "Human-readable review fields must include every required review field"
+        });
+    }
+    if (value.review.freshness.evaluatedAt !== value.derivedAt ||
+        value.review.freshness.expiresAt !== value.expiresAt) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["review", "freshness"],
+            message: "review freshness must match evidence derivedAt and expiresAt"
+        });
+    }
+    if (value.review.proposedAction.adapterId !== value.adapterId ||
+        value.review.proposedAction.protocol !== value.protocol ||
+        value.review.proposedAction.actionKind !== value.actionKind) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["review", "proposedAction"],
+            message: "review proposedAction must match the human-readable review evidence identity"
+        });
+    }
+});
+export function parseHumanReadableReviewEvidence(value) {
+    return humanReadableReviewEvidenceSchema.parse(value);
+}
+export function createHumanReadableReviewEvidence(input) {
+    return verifyHumanReadableReviewEvidence({
+        transactionMaterial: input.transactionMaterial,
+        transactionMaterialDigest: input.transactionMaterialDigest,
+        evidence: {
+            evidenceVersion: HUMAN_READABLE_REVIEW_EVIDENCE_VERSION,
+            materialId: input.transactionMaterial.materialId,
+            reviewSessionId: input.transactionMaterial.reviewSessionId,
+            planId: input.transactionMaterial.planId,
+            account: input.transactionMaterial.account,
+            transactionDigest: input.transactionMaterialDigest.transactionDigest,
+            kind: "human_readable_review",
+            adapterId: input.adapterId,
+            protocol: input.protocol,
+            actionKind: input.actionKind,
+            network: "sui:mainnet",
+            fields: [...WALLET_REVIEW_REQUIRED_HUMAN_FIELDS],
+            source: "review_model_or_adapter_equivalent",
+            purpose: "human_review_before_wallet_authorization",
+            review: input.review,
+            derivedAt: input.derivedAt.toISOString(),
+            expiresAt: input.transactionMaterial.expiresAt
+        },
+        now: input.derivedAt
+    });
+}
+export function verifyHumanReadableReviewEvidence(input) {
+    const evidence = parseHumanReadableReviewEvidence(input.evidence);
+    const now = input.now ?? new Date();
+    const nowMs = now.getTime();
+    if (!Number.isFinite(nowMs)) {
+        throw new Error("now must be a valid Date");
+    }
+    if (evidence.materialId !== input.transactionMaterial.materialId ||
+        evidence.reviewSessionId !== input.transactionMaterial.reviewSessionId ||
+        evidence.planId !== input.transactionMaterial.planId ||
+        evidence.account !== input.transactionMaterial.account ||
+        evidence.expiresAt !== input.transactionMaterial.expiresAt ||
+        evidence.transactionDigest !== input.transactionMaterialDigest.transactionDigest) {
+        throw new Error("human-readable review evidence must match material and digest identity");
+    }
+    if (input.transactionMaterialDigest.materialId !== input.transactionMaterial.materialId ||
+        input.transactionMaterialDigest.reviewSessionId !== input.transactionMaterial.reviewSessionId ||
+        input.transactionMaterialDigest.planId !== input.transactionMaterial.planId ||
+        input.transactionMaterialDigest.account !== input.transactionMaterial.account ||
+        input.transactionMaterialDigest.expiresAt !== input.transactionMaterial.expiresAt) {
+        throw new Error("transaction material digest must match material identity before human review evidence is accepted");
+    }
+    assertHumanReadableReviewConnectedAccount(evidence);
+    assertHumanReadableReviewEvidenceSources(evidence);
+    const materialCreatedAtMs = Date.parse(input.transactionMaterial.createdAt);
+    const derivedAtMs = Date.parse(evidence.derivedAt);
+    const expiresAtMs = Date.parse(evidence.expiresAt);
+    if (derivedAtMs < materialCreatedAtMs || derivedAtMs > nowMs || derivedAtMs >= expiresAtMs) {
+        throw new Error("human-readable review derivedAt must be between material creation, now, and material expiry");
+    }
+    if (expiresAtMs <= nowMs) {
+        throw new Error("human-readable review evidence must not be expired");
+    }
+    adapterHumanReadableReviewSchema.parse({
+        fields: evidence.fields,
+        transactionDigest: evidence.transactionDigest,
+        source: evidence.source,
+        purpose: evidence.purpose
+    });
+    assertNoForbiddenMcpFields(evidence.review);
+    return evidence;
+}
+export function publicHumanReadableReviewFromEvidence(evidenceInput) {
+    const evidence = parseHumanReadableReviewEvidence(evidenceInput);
+    assertNoForbiddenMcpFields(evidence.review);
+    return humanReadableReviewSummarySchema.parse(structuredClone(evidence.review));
+}
+function findDuplicate(values) {
+    const seen = new Set();
+    for (const value of values) {
+        if (seen.has(value)) {
+            return value;
+        }
+        seen.add(value);
+    }
+    return undefined;
+}
+function assertHumanReadableReviewConnectedAccount(evidence) {
+    const recipientsByRole = new Map();
+    for (const recipient of evidence.review.recipients) {
+        if (recipientsByRole.has(recipient.role)) {
+            throw new Error(`human-readable review recipients contains duplicate role '${recipient.role}'`);
+        }
+        const normalizedAddress = parseSuiAddress(recipient.address);
+        if (!normalizedAddress) {
+            throw new Error("human-readable review recipients must contain valid Sui addresses");
+        }
+        recipientsByRole.set(recipient.role, normalizedAddress);
+    }
+    if (recipientsByRole.get("connected_account") !== evidence.account) {
+        throw new Error("human-readable review connected account recipient must match the reviewed account");
+    }
+}
+export function assertPreSimulationHumanReadableReviewBoundaryClaims(evidence) {
+    requireGapId("missingEvidence", evidence.review.missingEvidence, "review_time_simulation");
+    requireGapId("requiredUserChoices", evidence.review.requiredUserChoices, "wallet_authorization_later");
+    for (const id of [
+        "no_signing_readiness",
+        "no_execution_readiness"
+    ]) {
+        requireGapId("unsupportedClaims", evidence.review.unsupportedClaims, id);
+    }
+    if (!evidence.review.blockingChecks.some((check) => check.source === "simulation" &&
+        check.status === "fail")) {
+        throw new Error("human-readable review blockingChecks must include a failed simulation check");
+    }
+}
+function assertHumanReadableReviewEvidenceSources(evidence) {
+    for (const source of ["digest_commitment"]) {
+        requireFactSource(evidence.review.evidenceUsed, source);
+    }
+}
+function requireFactSource(facts, source) {
+    if (!facts.some((fact) => fact.source === source)) {
+        throw new Error(`human-readable review evidenceUsed must include source '${source}'`);
+    }
+}
+function requireGapId(label, gaps, id) {
+    if (!gaps.some((gap) => gap.id === id)) {
+        throw new Error(`human-readable review ${label} must include '${id}'`);
+    }
+}

package/dist/core/action/humanReadableReviewProjectionVerifier.js

@@ -0,0 +1,29 @@
+import { verifyHumanReadableReviewEvidence } from "./humanReadableReviewEvidence.js";
+import { verifySwapHumanReadableReviewEvidence } from "./swapHumanReadableReviewProjection.js";
+export function verifySupportedHumanReadableReviewEvidence(input) {
+    const evidence = verifyHumanReadableReviewEvidence({
+        transactionMaterial: input.transactionMaterial,
+        transactionMaterialDigest: input.transactionMaterialDigest,
+        evidence: input.evidence,
+        now: input.now
+    });
+    switch (evidence.review.kind) {
+        case "swap_human_readable_review":
+            return verifySwapHumanReadableReviewEvidence({
+                transactionMaterial: input.transactionMaterial,
+                transactionMaterialDigest: input.transactionMaterialDigest,
+                swapQuotePolicy: requireProjectionArtifact(input.swapQuotePolicy, "swap human-readable review evidence requires swap quote policy evidence"),
+                transactionObjectOwnership: requireProjectionArtifact(input.transactionObjectOwnership, "swap human-readable review evidence requires transaction object ownership evidence"),
+                evidence,
+                now: input.now
+            });
+    }
+    const unsupportedKind = evidence.review.kind;
+    throw new Error(`unsupported human-readable review projection kind: ${String(unsupportedKind)}`);
+}
+function requireProjectionArtifact(value, message) {
+    if (value === undefined) {
+        throw new Error(message);
+    }
+    return value;
+}

package/dist/core/action/ptbVisualizationProducer.js

@@ -0,0 +1,71 @@
+import { Transaction } from "@mysten/sui/transactions";
+import { rawTransactionToIR, transactionIRToMermaid } from "@zktx.io/ptb-model";
+import { applyContractNamesToMermaid } from "./contractNameRegistry.js";
+import { PTB_VISUALIZATION_CONTRACT_VERSION, PTB_VISUALIZATION_REQUIRED_UNSUPPORTED_USES, ptbVisualizationArtifactSchema } from "./signableAdapterContract.js";
+export const PTB_VISUALIZATION_RENDERER = {
+    name: "transactionIRToMermaid",
+    packageName: "@zktx.io/ptb-model",
+    version: "0.5.0"
+};
+export async function producePtbVisualizationArtifact(input) {
+    const material = input.materialStore.getTransactionMaterial(input.transactionMaterial, input.now);
+    if (!material) {
+        return { status: "declined", reason: "transaction material is unavailable for visualization" };
+    }
+    let mermaidText;
+    try {
+        const transaction = Transaction.from(material.transactionBytes);
+        const recomputedDigest = await transaction.getDigest();
+        if (recomputedDigest !== input.transactionMaterialDigest.transactionDigest) {
+            return {
+                status: "declined",
+                reason: "stored transaction bytes do not match the bound transaction material commitment"
+            };
+        }
+        const data = transaction.getData();
+        const ir = rawTransactionToIR({ inputs: data.inputs, commands: data.commands });
+        mermaidText = transactionIRToMermaid(ir, { direction: "LR" });
+    }
+    catch (error) {
+        return {
+            status: "declined",
+            reason: `ptb renderer failed: ${error instanceof Error ? error.message : String(error)}`
+        };
+    }
+    const candidate = {
+        contractVersion: PTB_VISUALIZATION_CONTRACT_VERSION,
+        artifactKind: "ptb_visualization",
+        generatedAt: input.now.toISOString(),
+        source: {
+            adapterId: input.adapterId,
+            ...(input.planId !== undefined ? { planId: input.planId } : {}),
+            sourceKind: "review_time_generated_transaction_kind",
+            authority: "visualization_only_not_wallet_authorization",
+            renderer: PTB_VISUALIZATION_RENDERER
+        },
+        mermaid: {
+            diagramType: "flowchart",
+            // text keeps raw package addresses (truth/audit and copyable source);
+            // namedText relabels registered packages with their Move Registry name for
+            // the default graph, with a review-page toggle back to raw addresses.
+            text: mermaidText,
+            namedText: applyContractNamesToMermaid(mermaidText)
+        },
+        diagnostics: [],
+        unsupportedUse: [...PTB_VISUALIZATION_REQUIRED_UNSUPPORTED_USES],
+        executableMaterial: {
+            included: false,
+            policy: "mcp_and_review_ui_outputs_must_not_include_executable_transaction_material"
+        }
+    };
+    const parsed = ptbVisualizationArtifactSchema.safeParse(candidate);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        const path = issue?.path.join(".") ?? "";
+        return {
+            status: "declined",
+            reason: `ptb visualization artifact rejected: ${path ? `${path}: ` : ""}${issue?.message ?? "unknown issue"}`
+        };
+    }
+    return { status: "rendered", artifact: parsed.data };
+}

package/dist/core/action/receiptPtbGraph.js

@@ -0,0 +1,29 @@
+import { rawTransactionToIR, transactionIRToMermaid } from "@zktx.io/ptb-model";
+import { applyContractNamesToMermaid } from "./contractNameRegistry.js";
+// Produce a left-to-right PTB Mermaid graph for a PUBLIC receipt straight from the
+// already-fetched on-chain transaction's inputs and commands. Unlike the
+// signing-flow `producePtbVisualizationArtifact`, this needs no stored material and
+// no digest commitment — the transaction is the chain's own record, read by digest.
+// It uses the same `@zktx.io/ptb-model` pipeline (LR, matching the review page), so
+// the receipt graph and the review graph render identically.
+//
+// The same contract name registry the review graph uses is applied here, so
+// registered packages/objects show their display name (@deepbook/core, Clock, …)
+// and every other long address is shortened for the graph; the full ids stay in
+// the receipt's Inputs / Move calls / Object changes sections and Markdown.
+//
+// Returns undefined when the model cannot render the transaction (e.g. a
+// non-programmable system transaction); the page then shows a placeholder card in
+// the same slot rather than collapsing the layout.
+export function receiptPtbMermaid(transactionData) {
+    try {
+        const ir = rawTransactionToIR({ inputs: transactionData.inputs, commands: transactionData.commands });
+        // Emit both the raw-address graph and the registry-named graph so the receipt and
+        // the review render the same toggleable graph through the shared component.
+        const text = transactionIRToMermaid(ir, { direction: "LR" });
+        return text.trim().length > 0 ? { text, namedText: applyContractNamesToMermaid(text) } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/core/action/reviewCheckResults.js

@@ -0,0 +1,6 @@
+export function passReviewCheck(id, label, message, source) {
+    return { id, label, status: "pass", message, source };
+}
+export function failReviewCheck(id, label, message, source) {
+    return { id, label, status: "fail", message, source };
+}

package/dist/core/action/reviewStateValidation.js

@@ -0,0 +1,11 @@
+import { reviewStateStructuralInvariantSchema } from "./schemas.js";
+export function parseReviewStateStructuralInvariants(input) {
+    return reviewStateStructuralInvariantSchema.parse(input);
+}
+export function parseLifecycleValidatedReviewState(input, validateAdapterLifecycle) {
+    const parsed = parseReviewStateStructuralInvariants(input);
+    if (parsed.adapterLifecycle) {
+        validateAdapterLifecycle(parsed.adapterLifecycle);
+    }
+    return parsed;
+}