@zktx.io/sui-mcp 0.5.0

package/dist/core/action/swapHumanReadableReviewProjection.js

@@ -0,0 +1,130 @@
+import { transactionFundingSummary } from "./transactionFunding.js";
+import { assertPreSimulationHumanReadableReviewBoundaryClaims, createHumanReadableReviewEvidence, verifyHumanReadableReviewEvidence } from "./humanReadableReviewEvidence.js";
+import { parseSuiAddress } from "../suiAddress.js";
+export function createSwapHumanReadableReviewEvidence(input) {
+    return verifySwapHumanReadableReviewEvidence({
+        transactionMaterial: input.transactionMaterial,
+        transactionMaterialDigest: input.transactionMaterialDigest,
+        swapQuotePolicy: input.swapQuotePolicy,
+        transactionObjectOwnership: input.transactionObjectOwnership,
+        evidence: createHumanReadableReviewEvidence({
+            transactionMaterial: input.transactionMaterial,
+            transactionMaterialDigest: input.transactionMaterialDigest,
+            adapterId: input.adapterId,
+            protocol: input.protocol,
+            actionKind: input.actionKind,
+            review: input.review,
+            derivedAt: input.derivedAt
+        }),
+        now: input.derivedAt
+    });
+}
+export function verifySwapHumanReadableReviewEvidence(input) {
+    const evidence = verifyHumanReadableReviewEvidence({
+        transactionMaterial: input.transactionMaterial,
+        transactionMaterialDigest: input.transactionMaterialDigest,
+        evidence: input.evidence,
+        now: input.now
+    });
+    if (evidence.review.kind !== "swap_human_readable_review") {
+        throw new Error("swap human-readable review evidence requires a swap_human_readable_review projection");
+    }
+    if (input.swapQuotePolicy.adapterId !== evidence.adapterId ||
+        input.swapQuotePolicy.protocol !== evidence.protocol ||
+        input.swapQuotePolicy.actionKind !== evidence.actionKind) {
+        throw new Error("swap human-readable review evidence must match swap quote policy adapter identity");
+    }
+    for (const artifact of [input.swapQuotePolicy, input.transactionObjectOwnership]) {
+        if (artifact.materialId !== input.transactionMaterial.materialId ||
+            artifact.reviewSessionId !== input.transactionMaterial.reviewSessionId ||
+            artifact.planId !== input.transactionMaterial.planId ||
+            artifact.account !== input.transactionMaterial.account ||
+            artifact.expiresAt !== input.transactionMaterial.expiresAt) {
+            throw new Error("swap human-readable review evidence requires quote policy and object ownership artifacts for the same material");
+        }
+    }
+    if (input.transactionObjectOwnership.transactionDigest !== input.transactionMaterialDigest.transactionDigest) {
+        throw new Error("swap human-readable review evidence requires object ownership bound to the same transaction digest");
+    }
+    const fundingFacts = evidence.review.evidenceUsed.filter((fact) => fact.id === "transaction_funding");
+    if (fundingFacts.length !== 1 || fundingFacts[0]?.source !== "transaction_material" ||
+        fundingFacts[0]?.summary !== transactionFundingSummary(input.transactionObjectOwnership.funding)) {
+        throw new Error("swap human-readable review must describe the verified transaction funding");
+    }
+    assertSwapHumanReadableReviewProjectsQuotePolicy(evidence, input.swapQuotePolicy);
+    assertSwapHumanReadableReviewParties(evidence);
+    assertSwapHumanReadableReviewEvidenceSources(evidence);
+    assertSwapHumanReadableReviewBoundaryClaims(evidence);
+    assertPreSimulationHumanReadableReviewBoundaryClaims(evidence);
+    return evidence;
+}
+function assertSwapHumanReadableReviewProjectsQuotePolicy(evidence, swapQuotePolicy) {
+    assertSingleAmountProjection("outgoing", evidence.review.assetFlow.outgoing, "input", swapQuotePolicy.sourceAmount);
+    assertSingleAmountProjection("expected incoming", evidence.review.assetFlow.expectedIncoming, "expected_output", swapQuotePolicy.expectedOutput);
+    assertSingleAmountProjection("minimum incoming", evidence.review.assetFlow.minimumIncoming, "minimum_output", swapQuotePolicy.minimumOutput);
+    assertSingleAmountProjection("fee", evidence.review.assetFlow.fees, "fee", swapQuotePolicy.protocolFee);
+    if (evidence.review.targets.length !== 1) {
+        throw new Error("swap human-readable review targets must contain exactly one swap output asset target");
+    }
+    const target = evidence.review.targets[0];
+    if (target.kind !== "swap_output_asset" ||
+        target.symbol !== swapQuotePolicy.expectedOutput.asset.symbol ||
+        target.coinType !== swapQuotePolicy.expectedOutput.asset.coinType ||
+        target.protocol !== swapQuotePolicy.protocol ||
+        target.poolKey !== swapQuotePolicy.quoteSource.poolKey ||
+        target.direction !== swapQuotePolicy.quoteSource.direction) {
+        throw new Error("swap human-readable review target must match swap quote policy output asset and quote source");
+    }
+}
+function assertSwapHumanReadableReviewParties(evidence) {
+    const recipientsByRole = new Map();
+    for (const recipient of evidence.review.recipients) {
+        if (recipientsByRole.has(recipient.role)) {
+            throw new Error(`swap human-readable review recipients contains duplicate role '${recipient.role}'`);
+        }
+        const normalizedAddress = parseSuiAddress(recipient.address);
+        if (!normalizedAddress) {
+            throw new Error("swap human-readable review recipients must contain valid Sui addresses");
+        }
+        recipientsByRole.set(recipient.role, normalizedAddress);
+    }
+    if (recipientsByRole.size !== 2) {
+        throw new Error("swap human-readable review recipients must contain exactly the connected account and output recipient");
+    }
+    if (recipientsByRole.get("connected_account") !== evidence.account ||
+        recipientsByRole.get("output_recipient") !== evidence.account) {
+        throw new Error("swap human-readable review recipients must match the reviewed account");
+    }
+}
+function assertSwapHumanReadableReviewEvidenceSources(evidence) {
+    for (const source of ["quote", "wallet"]) {
+        requireFactSource(evidence.review.evidenceUsed, source);
+    }
+}
+function assertSwapHumanReadableReviewBoundaryClaims(evidence) {
+    requireGapId("unsupportedClaims", evidence.review.unsupportedClaims, "no_route_recommendation");
+}
+function assertSingleAmountProjection(label, amounts, role, expected) {
+    if (amounts.length !== 1) {
+        throw new Error(`swap human-readable review ${label} must contain exactly one amount`);
+    }
+    const amount = amounts[0];
+    if (amount.role !== role ||
+        amount.rawAmount !== expected.raw ||
+        amount.rawAmountSource !== "quote_policy_evidence" ||
+        amount.symbol !== expected.asset.symbol ||
+        amount.coinType !== expected.asset.coinType ||
+        amount.decimals !== expected.asset.decimals) {
+        throw new Error(`swap human-readable review ${label} amount must match swap quote policy evidence`);
+    }
+}
+function requireFactSource(facts, source) {
+    if (!facts.some((fact) => fact.source === source)) {
+        throw new Error(`swap human-readable review evidenceUsed must include source '${source}'`);
+    }
+}
+function requireGapId(label, gaps, id) {
+    if (!gaps.some((gap) => gap.id === id)) {
+        throw new Error(`swap human-readable review ${label} must include '${id}'`);
+    }
+}

package/dist/core/action/swapQuotePolicyEvidence.js

@@ -0,0 +1,271 @@
+import { z } from "zod";
+import { adapterEvidenceClaimSchema, adapterRawQuantitySchema, adapterSourceOfTruthSchema } from "./signableAdapterContract.js";
+import { parseRawU64 } from "../numeric/rawU64.js";
+import { normalizedSuiAddressSchema } from "../suiAddress.js";
+import { DEEPBOOK_SCALAR_UNIT_SOURCE, SUI_METADATA_UNIT_SOURCE, normalizeCoinType } from "../read/coinMetadata.js";
+export const SWAP_QUOTE_POLICY_EVIDENCE_VERSION = "swap-quote-policy-v1";
+const BPS_DENOMINATOR = 10000n;
+const isoUtcStringSchema = z.string().refine((value) => {
+    const parsed = new Date(value);
+    return Number.isFinite(parsed.getTime()) && parsed.toISOString() === value;
+}, "Expected ISO 8601 UTC timestamp");
+const coinTypeSchema = z.string().min(1).max(512).refine((value) => {
+    try {
+        normalizeCoinType(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}, "Expected a Sui struct tag coin type").transform((value) => normalizeCoinType(value));
+const quotePolicyAssetSchema = z.object({
+    symbol: z.string().min(1).max(64),
+    coinType: coinTypeSchema,
+    decimals: z.number().int().min(0).max(255),
+    unitSource: z.enum([DEEPBOOK_SCALAR_UNIT_SOURCE, SUI_METADATA_UNIT_SOURCE])
+}).strict();
+const quotePolicyRawAmountSchema = z.object({
+    raw: z.string().min(1),
+    asset: quotePolicyAssetSchema
+}).strict();
+export const swapQuotePolicyEvidenceSchema = z.object({
+    evidenceVersion: z.literal(SWAP_QUOTE_POLICY_EVIDENCE_VERSION),
+    materialId: z.string().min(1),
+    reviewSessionId: z.string().min(1),
+    planId: z.string().min(1),
+    account: normalizedSuiAddressSchema,
+    kind: z.literal("swap_quote_policy"),
+    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"),
+    quoteEvidenceId: z.string().min(1).max(120),
+    quoteSource: z.object({
+        provider: z.string().min(1).max(120),
+        poolKey: z.string().min(1).max(120),
+        direction: z.enum(["base_to_quote", "quote_to_base"]),
+        fetchedAt: isoUtcStringSchema,
+        sourceMoveFunction: z.string().min(1).max(160)
+    }).strict(),
+    policySource: z.literal("adapter_policy_from_quote_evidence"),
+    maxSlippageBps: z.number().int().min(1).max(10_000),
+    staleAfterMs: z.number().int().min(1),
+    sourceAmount: quotePolicyRawAmountSchema,
+    expectedOutput: quotePolicyRawAmountSchema,
+    minimumOutput: quotePolicyRawAmountSchema,
+    protocolFee: quotePolicyRawAmountSchema,
+    derivedAt: isoUtcStringSchema,
+    expiresAt: isoUtcStringSchema
+}).strict();
+export function createSwapQuotePolicyEvidence(input) {
+    return verifySwapQuotePolicyEvidence({
+        transactionMaterial: input.materialHandle,
+        evidence: {
+            evidenceVersion: SWAP_QUOTE_POLICY_EVIDENCE_VERSION,
+            materialId: input.materialHandle.materialId,
+            reviewSessionId: input.materialHandle.reviewSessionId,
+            planId: input.materialHandle.planId,
+            account: input.materialHandle.account,
+            kind: "swap_quote_policy",
+            adapterId: input.adapterId,
+            protocol: input.protocol,
+            actionKind: input.actionKind,
+            network: "sui:mainnet",
+            quoteEvidenceId: input.quoteEvidenceId,
+            quoteSource: input.quoteSource,
+            policySource: "adapter_policy_from_quote_evidence",
+            maxSlippageBps: input.maxSlippageBps,
+            staleAfterMs: input.staleAfterMs,
+            sourceAmount: input.sourceAmount,
+            expectedOutput: input.expectedOutput,
+            minimumOutput: input.minimumOutput,
+            protocolFee: input.protocolFee,
+            derivedAt: input.derivedAt.toISOString(),
+            expiresAt: input.materialHandle.expiresAt
+        },
+        now: input.derivedAt
+    });
+}
+export function parseSwapQuotePolicyEvidence(value) {
+    return swapQuotePolicyEvidenceSchema.parse(value);
+}
+export function verifySwapQuotePolicyEvidence(input) {
+    const evidence = parseSwapQuotePolicyEvidence(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) {
+        throw new Error("swap quote policy evidence must match material identity");
+    }
+    const fetchedAtMs = Date.parse(evidence.quoteSource.fetchedAt);
+    const derivedAtMs = Date.parse(evidence.derivedAt);
+    const expiresAtMs = Date.parse(evidence.expiresAt);
+    if (fetchedAtMs > derivedAtMs) {
+        throw new Error("swap quote policy evidence fetchedAt must not be after derivedAt");
+    }
+    if (Date.parse(evidence.quoteSource.fetchedAt) + evidence.staleAfterMs !== expiresAtMs) {
+        throw new Error("swap quote policy evidence expiresAt must equal fetchedAt plus staleAfterMs");
+    }
+    if (derivedAtMs > nowMs) {
+        throw new Error("swap quote policy evidence derivedAt must not be in the future");
+    }
+    if (expiresAtMs <= derivedAtMs || expiresAtMs <= nowMs) {
+        throw new Error("swap quote policy evidence must not be expired");
+    }
+    const expectedOutput = parseRawU64(evidence.expectedOutput.raw, "expectedOutput.raw", { positive: true });
+    const minimumOutput = parseRawU64(evidence.minimumOutput.raw, "minimumOutput.raw", { positive: true });
+    parseRawU64(evidence.sourceAmount.raw, "sourceAmount.raw", { positive: true });
+    parseRawU64(evidence.protocolFee.raw, "protocolFee.raw");
+    const computedMinimum = (expectedOutput * (BPS_DENOMINATOR - BigInt(evidence.maxSlippageBps))) / BPS_DENOMINATOR;
+    if (minimumOutput !== computedMinimum) {
+        throw new Error("swap quote policy minimumOutput.raw must match expectedOutput.raw and maxSlippageBps");
+    }
+    if (!sameAsset(evidence.expectedOutput.asset, evidence.minimumOutput.asset)) {
+        throw new Error("swap quote policy minimum output asset must match expected output asset");
+    }
+    const contractMapping = mapSwapQuotePolicyEvidenceToContractDraft(evidence);
+    if (contractMapping.status === "unsupported") {
+        throw new Error(`swap quote policy evidence is not contract-mappable: ${contractMapping.reason}`);
+    }
+    return evidence;
+}
+export function mapSwapQuotePolicyEvidenceToContractDraft(evidenceInput) {
+    const evidence = parseSwapQuotePolicyEvidence(evidenceInput);
+    const outputUnitSource = mapUnitSource(evidence.expectedOutput.asset.unitSource);
+    if (!outputUnitSource) {
+        return { status: "unsupported", reason: "unsupported output unit source" };
+    }
+    const quoteSourceId = "swap_quote_policy";
+    const outputUnitSourceId = "swap_quote_output_unit";
+    const outputUnitClaimId = "swap_quote_output_unit_claim";
+    const expectedAmountClaimId = "swap_quote_expected_output_claim";
+    const minimumAmountClaimId = "swap_quote_minimum_output_claim";
+    const quoteMinOutClaimId = "swap_quote_min_out_claim";
+    const slippagePolicyClaimId = "swap_quote_slippage_policy_claim";
+    const outputAsset = {
+        symbol: evidence.expectedOutput.asset.symbol,
+        coinType: evidence.expectedOutput.asset.coinType
+    };
+    const sourceReferences = [
+        adapterSourceOfTruthSchema.parse({
+            id: quoteSourceId,
+            kind: "quote_evidence",
+            network: "sui:mainnet",
+            source: `${evidence.protocol} quote and slippage rules (adapter: ${evidence.adapterId})`,
+            verifiedAt: evidence.derivedAt,
+            fields: ["quoteEvidenceId", "rawAmount", "minOutRaw", "asset", "amountRole", "maxSlippageBps"]
+        }),
+        adapterSourceOfTruthSchema.parse({
+            id: outputUnitSourceId,
+            kind: outputUnitSource.sourceReferencesKind,
+            network: "sui:mainnet",
+            source: outputUnitSource.sourceDescription,
+            verifiedAt: evidence.derivedAt,
+            fields: ["coinType", "decimals"]
+        })
+    ];
+    const evidenceClaims = [
+        adapterEvidenceClaimSchema.parse({
+            id: expectedAmountClaimId,
+            factKind: "raw_quantity_amount",
+            sourceEvidenceId: quoteSourceId,
+            role: "expected_output",
+            asset: outputAsset,
+            rawAmount: evidence.expectedOutput.raw
+        }),
+        adapterEvidenceClaimSchema.parse({
+            id: minimumAmountClaimId,
+            factKind: "raw_quantity_amount",
+            sourceEvidenceId: quoteSourceId,
+            role: "minimum_output",
+            asset: outputAsset,
+            rawAmount: evidence.minimumOutput.raw
+        }),
+        adapterEvidenceClaimSchema.parse({
+            id: outputUnitClaimId,
+            factKind: "unit_metadata",
+            sourceEvidenceId: outputUnitSourceId,
+            source: outputUnitSource.unitClaimSource,
+            coinType: outputAsset.coinType,
+            decimals: evidence.expectedOutput.asset.decimals
+        }),
+        adapterEvidenceClaimSchema.parse({
+            id: quoteMinOutClaimId,
+            factKind: "quote_min_out",
+            sourceEvidenceId: quoteSourceId,
+            quoteEvidenceId: evidence.quoteEvidenceId,
+            minOutRaw: evidence.minimumOutput.raw
+        }),
+        adapterEvidenceClaimSchema.parse({
+            id: slippagePolicyClaimId,
+            factKind: "slippage_policy",
+            sourceEvidenceId: quoteSourceId,
+            policySource: "adapter_policy_from_quote_evidence",
+            maxSlippageBps: evidence.maxSlippageBps,
+            minOutRaw: evidence.minimumOutput.raw
+        })
+    ];
+    const rawQuantities = [
+        adapterRawQuantitySchema.parse({
+            id: "swap_quote_expected_output",
+            role: "expected_output",
+            asset: outputAsset,
+            rawAmount: evidence.expectedOutput.raw,
+            unit: {
+                decimals: evidence.expectedOutput.asset.decimals,
+                source: outputUnitSource.unitClaimSource,
+                sourceField: "expectedOutput.asset.decimals",
+                unitClaimId: outputUnitClaimId
+            },
+            amountClaimId: expectedAmountClaimId
+        }),
+        adapterRawQuantitySchema.parse({
+            id: "swap_quote_minimum_output",
+            role: "minimum_output",
+            asset: outputAsset,
+            rawAmount: evidence.minimumOutput.raw,
+            unit: {
+                decimals: evidence.expectedOutput.asset.decimals,
+                source: outputUnitSource.unitClaimSource,
+                sourceField: "minimumOutput.asset.decimals",
+                unitClaimId: outputUnitClaimId
+            },
+            amountClaimId: minimumAmountClaimId
+        })
+    ];
+    return {
+        status: "mapped",
+        sourceReferences,
+        evidenceClaims,
+        rawQuantities
+    };
+}
+function sameAsset(left, right) {
+    return (left.symbol === right.symbol &&
+        left.coinType === right.coinType &&
+        left.decimals === right.decimals &&
+        left.unitSource === right.unitSource);
+}
+function mapUnitSource(unitSource) {
+    if (unitSource === DEEPBOOK_SCALAR_UNIT_SOURCE) {
+        return {
+            sourceReferencesKind: "pinned_sdk_registry",
+            unitClaimSource: "pinned_sdk_metadata",
+            sourceDescription: "Token decimals from the pinned DeepBook mainnet metadata, used to interpret raw quote amounts"
+        };
+    }
+    if (unitSource === "sui_core_getCoinMetadata") {
+        return {
+            sourceReferencesKind: "verified_mainnet_onchain_metadata",
+            unitClaimSource: "verified_mainnet_onchain_metadata",
+            sourceDescription: "Token decimals read from Sui mainnet, used to interpret raw quote amounts"
+        };
+    }
+    return undefined;
+}

package/dist/core/action/transactionFunding.js

@@ -0,0 +1,244 @@
+import { isDeepStrictEqual } from "node:util";
+import { z } from "zod";
+import { bcs, TypeTagSerializer } from "@mysten/sui/bcs";
+import { deriveDynamicFieldID, fromBase58, fromHex, normalizeSuiAddress, toHex, SUI_TYPE_ARG } from "@mysten/sui/utils";
+import { normalizeCoinType } from "../read/coinMetadata.js";
+import { normalizedSuiAddressSchema } from "../suiAddress.js";
+import { makeCanonicalRawU64StringSchema } from "../numeric/rawU64.js";
+const raw = makeCanonicalRawU64StringSchema("funding amount");
+const address = normalizedSuiAddressSchema;
+const coinType = z.string().refine((value) => {
+    try {
+        return normalizeCoinType(value) === value;
+    }
+    catch {
+        return false;
+    }
+});
+const reference = z.object({ objectId: address, version: raw, digest: z.string() }).strict();
+const expiration = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("none") }).strict(),
+    z.object({ kind: z.literal("epoch"), epoch: raw }).strict(),
+    z.object({ kind: z.literal("valid_during"), minEpoch: raw, maxEpoch: raw,
+        chain: z.string().min(1), nonce: z.number().int().min(0).max(0xffffffff) }).strict()
+]);
+export const transactionFundingDescriptionSchema = z.object({
+    sender: address, gasOwner: address, chainIdentifier: z.string().min(1),
+    gasBudgetRaw: raw, gasPriceRaw: raw,
+    gasMode: z.enum(["coin_objects", "address_balance", "coin_reservation"]),
+    gasPayments: z.array(reference),
+    gasObjectIds: z.array(address),
+    reservations: z.array(z.object({ objectId: address, amountRaw: raw, epoch: raw }).strict()),
+    withdrawals: z.array(z.object({ inputIndex: z.number().int().min(0), owner: address,
+        coinType, maxAmountRaw: raw }).strict()),
+    expiration
+}).strict();
+const addressBalance = z.object({ owner: address, coinType,
+    // A holding can exceed the u64 limit of an individual transaction input.
+    balanceRaw: z.string().regex(/^(0|[1-9][0-9]*)$/), requiredRaw: z.string().regex(/^(0|[1-9][0-9]*)$/)
+}).strict();
+export const transactionFundingEvidenceSchema = transactionFundingDescriptionSchema.extend({
+    observedEpoch: raw.optional(), addressBalances: z.array(addressBalance)
+}).superRefine((value, ctx) => {
+    try {
+        assertFundingEvidence(value);
+    }
+    catch (error) {
+        ctx.addIssue({ code: "custom", message: error instanceof Error ? error.message : "Invalid funding evidence" });
+    }
+});
+export class TransactionFundingError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+    }
+}
+// Reservation-format portions are adapted from Mysten Labs (Apache-2.0).
+// Copyright (c) Mysten Labs, Inc. See LICENSES/@mysten-sui-2.17.0-Apache-2.0.txt.
+// Sui mainnet-v1.72.5 coin_reservation.rs and @mysten/sui 2.17.0
+// utils/coin-reservation.ts define this layout. The SDK helper is not exported.
+// Decode only: coin selection and reservation creation remain SDK/node work.
+export function readCoinReservation(digest) {
+    const bytes = fromBase58(digest);
+    if (bytes.length !== 32)
+        throw new Error("Invalid payment reference digest length");
+    if (!bytes.slice(12).every((byte) => byte === 0xac))
+        return undefined;
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    return { amountRaw: view.getBigUint64(0, true).toString(), epoch: view.getUint32(8, true).toString() };
+}
+function reservationId(owner, chain) {
+    const key = TypeTagSerializer.parseFromStr("0x2::accumulator::Key<0x2::balance::Balance<0x2::sui::SUI>>");
+    const id = deriveDynamicFieldID(normalizeSuiAddress("0xacc"), key, bcs.Address.serialize(owner).toBytes());
+    const result = fromHex(id.slice(2)), mask = fromBase58(chain);
+    if (mask.length !== 32)
+        throw new Error("Invalid funding chain identifier");
+    for (let i = 0; i < result.length; i++)
+        result[i] = result[i] ^ mask[i];
+    return normalizeSuiAddress(toHex(result));
+}
+function record(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("Missing funding transaction field");
+    return value;
+}
+export function describeTransactionFunding(data, account, chainIdentifier) {
+    if (!data.sender || !data.gasData.owner || !Array.isArray(data.gasData.payment))
+        throw new Error("Missing sender, gas owner or gas payments");
+    const sender = normalizeSuiAddress(data.sender), gasOwner = normalizeSuiAddress(data.gasData.owner);
+    if (sender !== account || gasOwner !== account)
+        throw new Error("Transaction funding must belong to the reviewed account");
+    const gasPayments = data.gasData.payment.map((item) => reference.parse(item));
+    const gasObjectIds = [], reservations = [];
+    for (const payment of gasPayments) {
+        const reserved = readCoinReservation(payment.digest);
+        if (reserved) {
+            if (payment.objectId !== reservationId(account, chainIdentifier) || reserved.amountRaw === "0")
+                throw new Error("Invalid account-bound SUI reservation");
+            reservations.push({ objectId: payment.objectId, ...reserved });
+        }
+        else
+            gasObjectIds.push(payment.objectId);
+    }
+    if (new Set(gasPayments.map((item) => item.objectId)).size !== gasPayments.length)
+        throw new Error("Duplicate gas payment reference");
+    const withdrawals = [];
+    for (const [inputIndex, input] of data.inputs.entries()) {
+        const item = record(input);
+        if (item.$kind === "FundsWithdrawal" || "FundsWithdrawal" in item) {
+            const withdrawal = record(item.FundsWithdrawal);
+            if (withdrawal.withdrawFrom?.Sender !== true || withdrawal.reservation?.MaxAmountU64 === undefined ||
+                typeof withdrawal.typeArg?.Balance !== "string")
+                throw new Error("Unsupported address-balance withdrawal");
+            const maxAmountRaw = raw.parse(withdrawal.reservation.MaxAmountU64);
+            if (maxAmountRaw === "0")
+                throw new Error("Address-balance withdrawal must be positive");
+            withdrawals.push({ inputIndex, owner: account, coinType: normalizeCoinType(withdrawal.typeArg.Balance), maxAmountRaw });
+        }
+    }
+    let expiry = { kind: "none" };
+    if (data.expiration) {
+        const value = record(data.expiration);
+        if (value.ValidDuring) {
+            const during = value.ValidDuring;
+            if (during.minTimestamp != null || during.maxTimestamp != null)
+                throw new Error("Timestamp expiration is unsupported");
+            expiry = expiration.parse({ kind: "valid_during", minEpoch: during.minEpoch, maxEpoch: during.maxEpoch, chain: during.chain, nonce: during.nonce });
+            if (expiry.kind !== "valid_during" || expiry.chain !== chainIdentifier || BigInt(expiry.maxEpoch) < BigInt(expiry.minEpoch) ||
+                BigInt(expiry.maxEpoch) > BigInt(expiry.minEpoch) + 1n)
+                throw new Error("Invalid mainnet epoch window");
+        }
+        else if (value.Epoch !== undefined) {
+            const epoch = value.Epoch;
+            // The pinned SDK's BCS Epoch decoder returns a number, unlike ValidDuring.
+            if (typeof epoch === "number" && (!Number.isSafeInteger(epoch) || epoch < 0)) {
+                throw new Error("Transaction expiration epoch must be a non-negative safe integer");
+            }
+            expiry = expiration.parse({ kind: "epoch", epoch: typeof epoch === "number" ? String(epoch) : epoch });
+        }
+        else if (!value.None)
+            throw new Error("Unsupported transaction expiration");
+    }
+    const gasMode = gasPayments.length === 0 ? "address_balance" : reservations.length ? "coin_reservation" : "coin_objects";
+    if (gasMode === "address_balance" && expiry.kind !== "valid_during")
+        throw new Error("Address-balance gas requires ValidDuring expiration");
+    const description = transactionFundingDescriptionSchema.parse({ sender, gasOwner, chainIdentifier,
+        gasBudgetRaw: data.gasData.budget, gasPriceRaw: data.gasData.price, gasMode, gasPayments, gasObjectIds, reservations, withdrawals, expiration: expiry });
+    if (BigInt(description.gasBudgetRaw) === 0n || BigInt(description.gasPriceRaw) === 0n)
+        throw new Error("Gasless transactions are unsupported");
+    return description;
+}
+export function addressFundingRequirements(funding) {
+    const amounts = new Map();
+    for (const withdrawal of funding.withdrawals)
+        amounts.set(withdrawal.coinType, (amounts.get(withdrawal.coinType) ?? 0n) + BigInt(withdrawal.maxAmountRaw));
+    const gasReservation = funding.gasMode === "address_balance" ? BigInt(funding.gasBudgetRaw)
+        : funding.reservations.reduce((sum, item) => sum + BigInt(item.amountRaw), 0n);
+    if (gasReservation > 0n)
+        amounts.set(SUI_TYPE_ARG, (amounts.get(SUI_TYPE_ARG) ?? 0n) + gasReservation);
+    return amounts;
+}
+function assertFundingEvidence(value) {
+    if (value.sender !== value.gasOwner)
+        throw new Error("Funding account mismatch");
+    const objects = [], reservations = [];
+    for (const payment of value.gasPayments) {
+        const reserved = readCoinReservation(payment.digest);
+        if (reserved) {
+            if (payment.objectId !== reservationId(value.sender, value.chainIdentifier) || reserved.amountRaw === "0")
+                throw new Error("Invalid funding reservation");
+            reservations.push({ objectId: payment.objectId, ...reserved });
+        }
+        else
+            objects.push(payment.objectId);
+    }
+    const mode = value.gasPayments.length === 0 ? "address_balance" : reservations.length ? "coin_reservation" : "coin_objects";
+    if (value.gasMode !== mode || !isDeepStrictEqual(objects, value.gasObjectIds) || !isDeepStrictEqual(reservations, value.reservations) ||
+        new Set(value.gasPayments.map((item) => item.objectId)).size !== value.gasPayments.length ||
+        new Set(value.withdrawals.map((item) => item.inputIndex)).size !== value.withdrawals.length ||
+        value.withdrawals.some((item) => item.owner !== value.sender || item.maxAmountRaw === "0") ||
+        value.gasBudgetRaw === "0" || value.gasPriceRaw === "0")
+        throw new Error("Inconsistent funding description");
+    const expected = addressFundingRequirements(value);
+    if (value.addressBalances.length !== expected.size || new Set(value.addressBalances.map((item) => item.coinType)).size !== expected.size)
+        throw new Error("Incomplete address-balance evidence");
+    for (const balance of value.addressBalances) {
+        if (balance.owner !== value.sender || expected.get(balance.coinType)?.toString() !== balance.requiredRaw || BigInt(balance.balanceRaw) < BigInt(balance.requiredRaw))
+            throw new Error("Address-balance evidence does not cover the transaction");
+    }
+    const epoch = value.observedEpoch === undefined ? undefined : BigInt(value.observedEpoch);
+    for (const reserved of value.reservations) {
+        if (epoch === undefined || (epoch !== BigInt(reserved.epoch) && epoch !== BigInt(reserved.epoch) + 1n))
+            throw new Error("Coin reservation epoch expired");
+    }
+    const expiry = value.expiration;
+    if (value.gasMode === "address_balance" && expiry.kind !== "valid_during")
+        throw new Error("Missing funding epoch window");
+    if (expiry.kind === "valid_during" && (expiry.chain !== value.chainIdentifier || BigInt(expiry.maxEpoch) < BigInt(expiry.minEpoch) ||
+        BigInt(expiry.maxEpoch) > BigInt(expiry.minEpoch) + 1n))
+        throw new Error("Invalid funding epoch window");
+    if (expiry.kind === "valid_during" && (epoch === undefined || epoch < BigInt(expiry.minEpoch) || epoch > BigInt(expiry.maxEpoch)))
+        throw new Error("Funding epoch window expired");
+    if (expiry.kind === "epoch" && (epoch === undefined || epoch > BigInt(expiry.epoch)))
+        throw new Error("Transaction epoch expired");
+}
+export async function readTransactionFunding(description, source) {
+    const addressBalances = [];
+    let observedEpoch;
+    try {
+        if (description.expiration.kind !== "none" || description.reservations.length) {
+            if (!source)
+                throw new Error("Funding source unavailable");
+            observedEpoch = raw.parse((await source.getCurrentSystemState()).systemState.epoch);
+        }
+        for (const [coinType, required] of addressFundingRequirements(description)) {
+            if (!source)
+                throw new Error("Funding source unavailable");
+            const response = (await source.getBalance({ owner: description.sender, coinType })).balance;
+            if (normalizeCoinType(response.coinType) !== coinType || !/^(0|[1-9][0-9]*)$/.test(response.addressBalance))
+                throw new Error("Invalid address-balance response");
+            if (BigInt(response.addressBalance) < required)
+                throw new TransactionFundingError(coinType === SUI_TYPE_ARG && !description.withdrawals.some((item) => item.coinType === coinType) ? "insufficient_gas" : "insufficient_balance", "The reviewed account's address balance does not cover the transaction's withdrawal and gas reservations. Nothing was submitted.");
+            addressBalances.push({ owner: description.sender, coinType, balanceRaw: response.addressBalance, requiredRaw: required.toString() });
+        }
+    }
+    catch (error) {
+        if (error instanceof TransactionFundingError)
+            throw error;
+        throw new TransactionFundingError("unavailable", "Transaction funding could not be verified from mainnet balance and epoch reads. Nothing was submitted.");
+    }
+    return transactionFundingEvidenceSchema.parse({ ...description, ...(observedEpoch === undefined ? {} : { observedEpoch }), addressBalances });
+}
+export function assertTransactionFundingMatches(description, evidence) {
+    if (!isDeepStrictEqual(description, transactionFundingDescriptionSchema.parse(Object.fromEntries(Object.keys(transactionFundingDescriptionSchema.shape).map((key) => [key, evidence[key]])))))
+        throw new Error("Transaction funding evidence does not match stored transaction material");
+}
+export function transactionFundingSummary(funding) {
+    transactionFundingEvidenceSchema.parse(funding);
+    const gas = funding.gasMode === "address_balance" ? "the reviewed account's SUI address balance"
+        : funding.gasMode === "coin_objects" ? "the reviewed account's SUI coin objects"
+            : funding.gasObjectIds.length ? "an address-balance reservation and SUI coin objects belonging to the reviewed account"
+                : "the reviewed account's SUI address-balance reservation";
+    return `Gas payment uses ${gas}. ${funding.withdrawals.length ? "Transaction inputs also reserve funds from the reviewed account's address balances." : "There are no explicit address-balance input withdrawals."} These are review-time funding facts, not guaranteed execution.`;
+}