@epoch-protocol/epoch-commons-sdk 0.1.17 → 0.1.19

package/dist/utils/compact.d.ts

@@ -1,4 +1,5 @@
 import { type Hex } from "viem";
-import { CompactData } from "../types/index.js";
+import { CompactData, Mandate } from "../types/index.js";
 export declare function getCompactTypehash(witnessTypeString?: string): Hex;
+export declare function getSimpleWitnessHash(mandate: Mandate, witnessTypeString: string): Hex;
 export declare function getClaimHash(message: CompactData, witnessTypeString: string): `0x${string}`;

package/dist/utils/compact.js

@@ -1,4 +1,4 @@
-import { keccak256, toBytes, } from "viem";
+import { keccak256, toBytes } from "viem";
 import { hashStruct } from "viem/utils";
 export function getCompactTypehash(witnessTypeString) {
     if (witnessTypeString) {
@@ -8,14 +8,76 @@ export function getCompactTypehash(witnessTypeString) {
     const typestring = "Compact(address arbiter,address sponsor,uint256 nonce,uint256 expires,bytes12 lockTag,address token,uint256 amount)";
     return keccak256(toBytes(typestring));
 }
+function parseWitnessFields(witnessTypeString) {
+    return witnessTypeString.split(",").map((field) => {
+        const tokens = field.trim().split(/\s+/).filter(Boolean);
+        if (tokens.length < 2) {
+            throw new Error(`Invalid witness field "${field}" (expected "type name" in witnessTypeString)`);
+        }
+        return {
+            type: tokens[0],
+            name: tokens[tokens.length - 1],
+        };
+    });
+}
+function normalizeWitnessMandate(mandate, witnessTypeString) {
+    if (!mandate)
+        return mandate;
+    const fields = parseWitnessFields(witnessTypeString);
+    const normalized = { ...mandate };
+    for (const { type, name } of fields) {
+        const value = normalized[name];
+        if (value === undefined || value === null)
+            continue;
+        if (type === "uint256") {
+            normalized[name] = BigInt(value);
+        }
+    }
+    return normalized;
+}
+function mandateWitnessValuesInOrder(mandate, witnessTypeString) {
+    const fields = witnessTypeString
+        .split(",")
+        .map((f) => f.trim())
+        .filter(Boolean);
+    return fields.map((field) => {
+        const tokens = field.split(/\s+/).filter(Boolean);
+        if (tokens.length < 2) {
+            throw new Error(`Invalid witness field "${field}" (expected "type name" in witnessTypeString)`);
+        }
+        const name = tokens[tokens.length - 1];
+        const record = mandate;
+        if (!(name in record) ||
+            record[name] === undefined ||
+            record[name] === null) {
+            throw new Error(`Mandate missing field "${name}" required by witnessTypeString (witness hash)`);
+        }
+        return record[name];
+    });
+}
+export function getSimpleWitnessHash(mandate, witnessTypeString) {
+    const normalizedMandate = normalizeWitnessMandate(mandate, witnessTypeString);
+    const mandateTypes = parseWitnessFields(witnessTypeString);
+    const witnessData = mandateWitnessValuesInOrder(normalizedMandate, witnessTypeString).reduce((acc, value, index) => {
+        acc[mandateTypes[index].name] = value;
+        return acc;
+    }, {});
+    return hashStruct({
+        types: { Mandate: mandateTypes },
+        primaryType: "Mandate",
+        data: witnessData,
+    });
+}
 export function getClaimHash(message, witnessTypeString) {
-    // Convert lockTag bigint to bytes12 hex string and token bigint to address
+    const mandate = normalizeWitnessMandate(message.mandate, witnessTypeString);
     const messageWithFormattedData = {
         ...message,
+        amount: BigInt(message.amount),
         lockTag: `0x${message.lockTag.toString(16).padStart(24, "0")}`,
         token: typeof message.token === "bigint"
             ? `0x${message.token.toString(16).padStart(40, "0")}`
             : message.token,
+        ...(mandate ? { mandate } : {}),
     };
     return hashStruct({
         types: getTypes(messageWithFormattedData, witnessTypeString),
@@ -37,10 +99,7 @@ function getTypes(message, witnessTypeString) {
         ],
         ...(message.mandate
             ? {
-                Mandate: witnessTypeString.split(",").map((field) => {
-                    const [type, name] = field.trim().split(/\s+/);
-                    return { name, type };
-                }),
+                Mandate: parseWitnessFields(witnessTypeString),
             }
             : {}),
     };

package/dist/utils/index.d.ts

@@ -1,2 +1,4 @@
 export * from "./compact.js";
+export * from "./miden-intent.js";
 export * from "./path.js";
+export * from "./witness-typestring.js";

package/dist/utils/index.js

@@ -1,2 +1,4 @@
 export * from "./compact.js";
+export * from "./miden-intent.js";
 export * from "./path.js";
+export * from "./witness-typestring.js";

package/dist/utils/miden-intent.d.ts

@@ -0,0 +1,29 @@
+import { EVM_TO_MIDEN_EXTRA_TYPESTRING, EVM_TO_MIDEN_FIELD_NAMES, MIDEN_MARKER_FIELD_NAMES, MIDEN_TO_EVM_EXTRA_TYPESTRING, MIDEN_TO_EVM_FIELD_NAMES } from "./witness-typestring.js";
+export type MidenBridgeDirection = "miden-to-evm" | "evm-to-miden";
+export interface MidenExtraData {
+    midenSourceAccount?: string;
+    midenRecipientAccount?: string;
+    midenFaucetId?: string;
+    midenNoteType?: string;
+    midenNoteId?: string;
+}
+/** True when mandate/extra data carries any Miden bridge marker field. */
+export declare function hasMidenMarkersInData(data?: Record<string, unknown>): boolean;
+/** True when a witness/extra typestring declares any Miden bridge marker field. */
+export declare function hasMidenMarkersInTypestring(typestring: string): boolean;
+/**
+ * True iff the intent is a Miden bridge intent (markers in typestring and/or data).
+ * At least one of `typestring` or `data` must be provided.
+ */
+export declare function isMidenIntent(typestring?: string, data?: Record<string, unknown>): boolean;
+/** EVM→Miden: recipient set, source account absent. */
+export declare function isEVMToMidenIntent(data?: Record<string, unknown>): boolean;
+/** Miden→EVM: source account set. */
+export declare function isMidenToEvmIntent(data?: Record<string, unknown>): boolean;
+export declare function hasMidenToEvmTypestringMarker(typestring: string): boolean;
+export declare function hasEvmToMidenTypestringMarker(typestring: string): boolean;
+export declare function resolveMidenBridgeDirection(typestring: string, data?: Record<string, unknown>): MidenBridgeDirection | "conflict" | null;
+export declare function getMidenMetadata(data?: Record<string, unknown>, typestring?: string): MidenExtraData | null;
+/** @deprecated Use {@link isEVMToMidenIntent}. */
+export declare function isEVMToMidenMandate(mandate?: Record<string, unknown>): boolean;
+export { EVM_TO_MIDEN_EXTRA_TYPESTRING, EVM_TO_MIDEN_FIELD_NAMES, MIDEN_TO_EVM_EXTRA_TYPESTRING, MIDEN_TO_EVM_FIELD_NAMES, MIDEN_MARKER_FIELD_NAMES, };

package/dist/utils/miden-intent.js

@@ -0,0 +1,79 @@
+import { EVM_TO_MIDEN_EXTRA_TYPESTRING, EVM_TO_MIDEN_FIELD_NAMES, MIDEN_MARKER_FIELD_NAMES, MIDEN_RECIPIENT_ACCOUNT_FIELD_NAME, MIDEN_SOURCE_ACCOUNT_FIELD_NAME, MIDEN_TO_EVM_EXTRA_TYPESTRING, MIDEN_TO_EVM_FIELD_NAMES, } from "./witness-typestring.js";
+function hasTruthyField(data, fieldName) {
+    return data[fieldName] != null && data[fieldName] !== "";
+}
+/** True when mandate/extra data carries any Miden bridge marker field. */
+export function hasMidenMarkersInData(data) {
+    if (!data)
+        return false;
+    return MIDEN_MARKER_FIELD_NAMES.some((name) => hasTruthyField(data, name));
+}
+/** True when a witness/extra typestring declares any Miden bridge marker field. */
+export function hasMidenMarkersInTypestring(typestring) {
+    if (!typestring.trim())
+        return false;
+    return MIDEN_MARKER_FIELD_NAMES.some((name) => typestring.includes(name));
+}
+/**
+ * True iff the intent is a Miden bridge intent (markers in typestring and/or data).
+ * At least one of `typestring` or `data` must be provided.
+ */
+export function isMidenIntent(typestring, data) {
+    const hasTypestring = typestring !== undefined && typestring.trim() !== "";
+    const hasData = data !== undefined;
+    if (!hasTypestring && !hasData) {
+        throw new Error("isMidenIntent requires typestring and/or data");
+    }
+    return ((hasTypestring && hasMidenMarkersInTypestring(typestring)) ||
+        hasMidenMarkersInData(data));
+}
+/** EVM→Miden: recipient set, source account absent. */
+export function isEVMToMidenIntent(data) {
+    if (!data)
+        return false;
+    return (hasTruthyField(data, MIDEN_RECIPIENT_ACCOUNT_FIELD_NAME) &&
+        !hasTruthyField(data, MIDEN_SOURCE_ACCOUNT_FIELD_NAME));
+}
+/** Miden→EVM: source account set. */
+export function isMidenToEvmIntent(data) {
+    if (!data)
+        return false;
+    return hasTruthyField(data, MIDEN_SOURCE_ACCOUNT_FIELD_NAME);
+}
+export function hasMidenToEvmTypestringMarker(typestring) {
+    return typestring.includes(MIDEN_SOURCE_ACCOUNT_FIELD_NAME);
+}
+export function hasEvmToMidenTypestringMarker(typestring) {
+    return typestring.includes(MIDEN_RECIPIENT_ACCOUNT_FIELD_NAME);
+}
+export function resolveMidenBridgeDirection(typestring, data) {
+    const toEvm = isMidenToEvmIntent(data) || hasMidenToEvmTypestringMarker(typestring);
+    const fromEvm = isEVMToMidenIntent(data) || hasEvmToMidenTypestringMarker(typestring);
+    if (toEvm && fromEvm)
+        return "conflict";
+    if (toEvm)
+        return "miden-to-evm";
+    if (fromEvm)
+        return "evm-to-miden";
+    // Match server routing: other Miden markers without a recipient use collateral path.
+    if (isMidenIntent(typestring, data))
+        return "miden-to-evm";
+    return null;
+}
+export function getMidenMetadata(data, typestring) {
+    if (!data || !isMidenIntent(typestring, data))
+        return null;
+    return {
+        midenSourceAccount: data?.midenSourceAccount,
+        midenRecipientAccount: data?.midenRecipientAccount,
+        midenFaucetId: data?.midenFaucetId,
+        midenNoteType: data?.midenNoteType,
+        midenNoteId: data?.midenNoteId,
+    };
+}
+/** @deprecated Use {@link isEVMToMidenIntent}. */
+export function isEVMToMidenMandate(mandate) {
+    return isEVMToMidenIntent(mandate);
+}
+// Re-export canonical typestrings for callers that import direction helpers here.
+export { EVM_TO_MIDEN_EXTRA_TYPESTRING, EVM_TO_MIDEN_FIELD_NAMES, MIDEN_TO_EVM_EXTRA_TYPESTRING, MIDEN_TO_EVM_FIELD_NAMES, MIDEN_MARKER_FIELD_NAMES, };

package/dist/utils/witness-typestring-constants.d.ts

@@ -0,0 +1,18 @@
+/** Base Mandate fields shared by all Epoch intents (matches `getTaskData`). */
+export declare const BASE_MANDATE_TYPESTRING = "address tokenIn,uint256 tokenInAmount,address tokenOut,uint256 minTokenOut,uint256 destinationChainId,bytes4 taskType,bytes32 protocolHashIdentifier,address recipient";
+/** Miden → EVM cross-chain bridge witness suffix (canonical). */
+export declare const MIDEN_TO_EVM_EXTRA_TYPESTRING = "string midenSourceAccount,string midenFaucetId,string midenNoteType,string midenNoteId";
+/** EVM → Miden cross-chain bridge witness suffix (canonical). */
+export declare const EVM_TO_MIDEN_EXTRA_TYPESTRING = "string midenRecipientAccount,string midenFaucetId";
+export declare const MIDEN_TO_EVM_WITNESS_TYPESTRING = "address tokenIn,uint256 tokenInAmount,address tokenOut,uint256 minTokenOut,uint256 destinationChainId,bytes4 taskType,bytes32 protocolHashIdentifier,address recipient,string midenSourceAccount,string midenFaucetId,string midenNoteType,string midenNoteId";
+export declare const EVM_TO_MIDEN_WITNESS_TYPESTRING = "address tokenIn,uint256 tokenInAmount,address tokenOut,uint256 minTokenOut,uint256 destinationChainId,bytes4 taskType,bytes32 protocolHashIdentifier,address recipient,string midenRecipientAccount,string midenFaucetId";
+export declare const MIDEN_TO_EVM_FIELD_NAMES: string[];
+export declare const EVM_TO_MIDEN_FIELD_NAMES: string[];
+/** Union of all Miden bridge field names from the canonical extra typestrings. */
+export declare const MIDEN_MARKER_FIELD_NAMES: string[];
+/** Fields declared only on the Miden→EVM extra typestring. */
+export declare const MIDEN_TO_EVM_ONLY_FIELD_NAMES: string[];
+/** Fields declared only on the EVM→Miden extra typestring. */
+export declare const EVM_TO_MIDEN_ONLY_FIELD_NAMES: string[];
+export declare const MIDEN_SOURCE_ACCOUNT_FIELD_NAME: "midenSourceAccount";
+export declare const MIDEN_RECIPIENT_ACCOUNT_FIELD_NAME: "midenRecipientAccount";

package/dist/utils/witness-typestring-constants.js

@@ -0,0 +1,31 @@
+import { fieldNamesFromExtraTypestring } from "./witness-typestring-parse.js";
+function uniqueFieldNames(typestrings) {
+    return [
+        ...new Set(typestrings.flatMap((typestring) => fieldNamesFromExtraTypestring(typestring))),
+    ];
+}
+function onlyInLeft(left, right) {
+    const rightSet = new Set(right);
+    return left.filter((name) => !rightSet.has(name));
+}
+/** Base Mandate fields shared by all Epoch intents (matches `getTaskData`). */
+export const BASE_MANDATE_TYPESTRING = "address tokenIn,uint256 tokenInAmount,address tokenOut,uint256 minTokenOut,uint256 destinationChainId,bytes4 taskType,bytes32 protocolHashIdentifier,address recipient";
+/** Miden → EVM cross-chain bridge witness suffix (canonical). */
+export const MIDEN_TO_EVM_EXTRA_TYPESTRING = "string midenSourceAccount,string midenFaucetId,string midenNoteType,string midenNoteId";
+/** EVM → Miden cross-chain bridge witness suffix (canonical). */
+export const EVM_TO_MIDEN_EXTRA_TYPESTRING = "string midenRecipientAccount,string midenFaucetId";
+export const MIDEN_TO_EVM_WITNESS_TYPESTRING = `${BASE_MANDATE_TYPESTRING},${MIDEN_TO_EVM_EXTRA_TYPESTRING}`;
+export const EVM_TO_MIDEN_WITNESS_TYPESTRING = `${BASE_MANDATE_TYPESTRING},${EVM_TO_MIDEN_EXTRA_TYPESTRING}`;
+export const MIDEN_TO_EVM_FIELD_NAMES = fieldNamesFromExtraTypestring(MIDEN_TO_EVM_EXTRA_TYPESTRING);
+export const EVM_TO_MIDEN_FIELD_NAMES = fieldNamesFromExtraTypestring(EVM_TO_MIDEN_EXTRA_TYPESTRING);
+/** Union of all Miden bridge field names from the canonical extra typestrings. */
+export const MIDEN_MARKER_FIELD_NAMES = uniqueFieldNames([
+    MIDEN_TO_EVM_EXTRA_TYPESTRING,
+    EVM_TO_MIDEN_EXTRA_TYPESTRING,
+]);
+/** Fields declared only on the Miden→EVM extra typestring. */
+export const MIDEN_TO_EVM_ONLY_FIELD_NAMES = onlyInLeft(MIDEN_TO_EVM_FIELD_NAMES, EVM_TO_MIDEN_FIELD_NAMES);
+/** Fields declared only on the EVM→Miden extra typestring. */
+export const EVM_TO_MIDEN_ONLY_FIELD_NAMES = onlyInLeft(EVM_TO_MIDEN_FIELD_NAMES, MIDEN_TO_EVM_FIELD_NAMES);
+export const MIDEN_SOURCE_ACCOUNT_FIELD_NAME = MIDEN_TO_EVM_ONLY_FIELD_NAMES.find((name) => name === "midenSourceAccount");
+export const MIDEN_RECIPIENT_ACCOUNT_FIELD_NAME = EVM_TO_MIDEN_ONLY_FIELD_NAMES.find((name) => name === "midenRecipientAccount");

package/dist/utils/witness-typestring-parse.d.ts

@@ -0,0 +1,5 @@
+export declare function parseWitnessTypestringFields(witnessTypeString: string): Array<{
+    type: string;
+    name: string;
+}>;
+export declare function fieldNamesFromExtraTypestring(typestring: string): string[];

package/dist/utils/witness-typestring-parse.js

@@ -0,0 +1,18 @@
+export function parseWitnessTypestringFields(witnessTypeString) {
+    return witnessTypeString
+        .split(",")
+        .map((field) => field.trim())
+        .filter(Boolean)
+        .map((field) => {
+        const tokens = field.split(/\s+/).filter(Boolean);
+        if (tokens.length < 2) {
+            throw new Error(`Invalid witness field "${field}" (expected "type name" in witnessTypeString)`);
+        }
+        const name = tokens[tokens.length - 1];
+        const type = tokens.slice(0, -1).join(" ");
+        return { type, name };
+    });
+}
+export function fieldNamesFromExtraTypestring(typestring) {
+    return parseWitnessTypestringFields(typestring).map((field) => field.name);
+}

package/dist/utils/witness-typestring.d.ts

@@ -0,0 +1,53 @@
+export declare function parseWitnessTypestringFields(witnessTypeString: string): Array<{
+    type: string;
+    name: string;
+}>;
+export declare function fieldNamesFromExtraTypestring(typestring: string): string[];
+/** Base Mandate fields shared by all Epoch intents (matches `getTaskData`). */
+export declare const BASE_MANDATE_TYPESTRING = "address tokenIn,uint256 tokenInAmount,address tokenOut,uint256 minTokenOut,uint256 destinationChainId,bytes4 taskType,bytes32 protocolHashIdentifier,address recipient";
+/** Miden → EVM cross-chain bridge witness suffix (canonical). */
+export declare const MIDEN_TO_EVM_EXTRA_TYPESTRING = "string midenSourceAccount,string midenFaucetId,string midenNoteType,string midenNoteId";
+/** EVM → Miden cross-chain bridge witness suffix (canonical). */
+export declare const EVM_TO_MIDEN_EXTRA_TYPESTRING = "string midenRecipientAccount,string midenFaucetId";
+/** Lending DEPOSIT extraData suffix (canonical). */
+export declare const DEPOSIT_EXTRADATA_TYPESTRING = "string marketUid,string action,string payAsset,bool isAll";
+/** Lending WITHDRAW extraData suffix (canonical). */
+export declare const WITHDRAW_EXTRADATA_TYPESTRING = "string marketUid,string action,string payAsset,bool isAll";
+export declare const MIDEN_TO_EVM_FIELD_NAMES: string[];
+export declare const EVM_TO_MIDEN_FIELD_NAMES: string[];
+/** Union of all Miden bridge field names from the canonical extra typestrings. */
+export declare const MIDEN_MARKER_FIELD_NAMES: string[];
+/** Fields declared only on the Miden→EVM extra typestring. */
+export declare const MIDEN_TO_EVM_ONLY_FIELD_NAMES: string[];
+/** Fields declared only on the EVM→Miden extra typestring. */
+export declare const EVM_TO_MIDEN_ONLY_FIELD_NAMES: string[];
+export declare const MIDEN_SOURCE_ACCOUNT_FIELD_NAME: "midenSourceAccount";
+export declare const MIDEN_RECIPIENT_ACCOUNT_FIELD_NAME: "midenRecipientAccount";
+export type WitnessTypestringValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    error: string;
+};
+/**
+ * Validate Miden `extraDataTypestring` / `extraData` for task assembly.
+ * Required Miden fields must be declared and present; additional protocol fields
+ * are allowed when declared in the typestring.
+ */
+export declare function validateMidenExtraFields(extraDataTypestring: string, extraData?: Record<string, unknown>): WitnessTypestringValidationResult;
+/**
+ * When a mandate includes Miden bridge metadata, the witness typestring must
+ * declare every required Miden field for the detected direction. Additional
+ * non-Miden fields may appear before or after the Miden fields.
+ *
+ * No-op for pure EVM intents — Miden checks run only when {@link isMidenIntent}.
+ */
+export declare function assertMidenWitnessFields(witnessTypeString: string, mandate?: Record<string, unknown>): WitnessTypestringValidationResult;
+/**
+ * Validates a witness typestring against its data. Handles both the full witness
+ * (base mandate + extra suffix) and a bare extra suffix — the same rules apply to
+ * either: comma spacing, "type name" format, key alignment with the data object,
+ * and required Miden bridge fields when applicable. Pass the assembled typestring and the
+ * merged data; there is no separate extra-suffix validator.
+ */
+export declare function validateWitnessTypeString(witnessTypeString: string, mandate?: Record<string, unknown>): WitnessTypestringValidationResult;

package/dist/utils/witness-typestring.js

@@ -0,0 +1,237 @@
+import { isMidenIntent, resolveMidenBridgeDirection } from "./miden-intent.js";
+export function parseWitnessTypestringFields(witnessTypeString) {
+    return witnessTypeString
+        .split(",")
+        .map((field) => field.trim())
+        .filter(Boolean)
+        .map((field) => {
+        const tokens = field.split(/\s+/).filter(Boolean);
+        if (tokens.length < 2) {
+            throw new Error(`Invalid witness field "${field}" (expected "type name" in witnessTypeString)`);
+        }
+        const name = tokens[tokens.length - 1];
+        const type = tokens.slice(0, -1).join(" ");
+        return { type, name };
+    });
+}
+export function fieldNamesFromExtraTypestring(typestring) {
+    return parseWitnessTypestringFields(typestring).map((field) => field.name);
+}
+function uniqueFieldNames(typestrings) {
+    return [
+        ...new Set(typestrings.flatMap((typestring) => fieldNamesFromExtraTypestring(typestring))),
+    ];
+}
+function onlyInLeft(left, right) {
+    const rightSet = new Set(right);
+    return left.filter((name) => !rightSet.has(name));
+}
+/** Base Mandate fields shared by all Epoch intents (matches `getTaskData`). */
+export const BASE_MANDATE_TYPESTRING = "address tokenIn,uint256 tokenInAmount,address tokenOut,uint256 minTokenOut,uint256 destinationChainId,bytes4 taskType,bytes32 protocolHashIdentifier,address recipient";
+/** Miden → EVM cross-chain bridge witness suffix (canonical). */
+export const MIDEN_TO_EVM_EXTRA_TYPESTRING = "string midenSourceAccount,string midenFaucetId,string midenNoteType,string midenNoteId";
+/** EVM → Miden cross-chain bridge witness suffix (canonical). */
+export const EVM_TO_MIDEN_EXTRA_TYPESTRING = "string midenRecipientAccount,string midenFaucetId";
+/** Lending DEPOSIT extraData suffix (canonical). */
+export const DEPOSIT_EXTRADATA_TYPESTRING = "string marketUid,string action,string payAsset,bool isAll";
+/** Lending WITHDRAW extraData suffix (canonical). */
+export const WITHDRAW_EXTRADATA_TYPESTRING = "string marketUid,string action,string payAsset,bool isAll";
+export const MIDEN_TO_EVM_FIELD_NAMES = fieldNamesFromExtraTypestring(MIDEN_TO_EVM_EXTRA_TYPESTRING);
+export const EVM_TO_MIDEN_FIELD_NAMES = fieldNamesFromExtraTypestring(EVM_TO_MIDEN_EXTRA_TYPESTRING);
+/** Union of all Miden bridge field names from the canonical extra typestrings. */
+export const MIDEN_MARKER_FIELD_NAMES = uniqueFieldNames([
+    MIDEN_TO_EVM_EXTRA_TYPESTRING,
+    EVM_TO_MIDEN_EXTRA_TYPESTRING,
+]);
+/** Fields declared only on the Miden→EVM extra typestring. */
+export const MIDEN_TO_EVM_ONLY_FIELD_NAMES = onlyInLeft(MIDEN_TO_EVM_FIELD_NAMES, EVM_TO_MIDEN_FIELD_NAMES);
+/** Fields declared only on the EVM→Miden extra typestring. */
+export const EVM_TO_MIDEN_ONLY_FIELD_NAMES = onlyInLeft(EVM_TO_MIDEN_FIELD_NAMES, MIDEN_TO_EVM_FIELD_NAMES);
+export const MIDEN_SOURCE_ACCOUNT_FIELD_NAME = MIDEN_TO_EVM_ONLY_FIELD_NAMES.find((name) => name === "midenSourceAccount");
+export const MIDEN_RECIPIENT_ACCOUNT_FIELD_NAME = EVM_TO_MIDEN_ONLY_FIELD_NAMES.find((name) => name === "midenRecipientAccount");
+function assertNoSpacesAroundCommas(typestring) {
+    if (/,(\s)|(\s),/.test(typestring)) {
+        return {
+            valid: false,
+            error: 'Typestring must not contain spaces before or after commas (e.g. use "uint256 foo,uint256 bar", not "uint256 foo, uint256 bar")',
+        };
+    }
+    return { valid: true };
+}
+function assertKeysMatchTypestring(typestring, data, dataLabel = "extraData", typestringLabel = "extraDataTypestring") {
+    let fields;
+    try {
+        fields = parseWitnessTypestringFields(typestring);
+    }
+    catch (error) {
+        return {
+            valid: false,
+            error: error instanceof Error
+                ? error.message
+                : "Invalid witnessTypeString format",
+        };
+    }
+    const typeNames = new Set(fields.map((f) => f.name));
+    const dataKeys = new Set(Object.keys(data));
+    for (const name of typeNames) {
+        if (!dataKeys.has(name)) {
+            return {
+                valid: false,
+                error: `${dataLabel} is missing key "${name}" required by ${typestringLabel}`,
+            };
+        }
+    }
+    for (const key of dataKeys) {
+        if (!typeNames.has(key)) {
+            return {
+                valid: false,
+                error: `${dataLabel} has unexpected key "${key}" not declared in ${typestringLabel}`,
+            };
+        }
+    }
+    return { valid: true };
+}
+function requiredMidenExtraTypestring(direction) {
+    return direction === "miden-to-evm"
+        ? MIDEN_TO_EVM_EXTRA_TYPESTRING
+        : EVM_TO_MIDEN_EXTRA_TYPESTRING;
+}
+function assertMidenFieldsDeclared(typestring, requiredExtraTypestring, typestringLabel) {
+    const requiredFields = parseWitnessTypestringFields(requiredExtraTypestring);
+    let declaredFields;
+    try {
+        declaredFields = parseWitnessTypestringFields(typestring);
+    }
+    catch (error) {
+        return {
+            valid: false,
+            error: error instanceof Error
+                ? error.message
+                : "Invalid witnessTypeString format",
+        };
+    }
+    const declaredByName = new Map(declaredFields.map((field) => [field.name, field.type]));
+    for (const field of requiredFields) {
+        const declaredType = declaredByName.get(field.name);
+        if (declaredType === undefined) {
+            return {
+                valid: false,
+                error: `${typestringLabel} is missing required Miden field "${field.type} ${field.name}"`,
+            };
+        }
+        if (declaredType !== field.type) {
+            return {
+                valid: false,
+                error: `${typestringLabel} field "${field.name}" must be type "${field.type}", got "${declaredType}"`,
+            };
+        }
+    }
+    return { valid: true };
+}
+function assertMidenFieldsPresentInData(data, requiredExtraTypestring, dataLabel) {
+    const requiredNames = parseWitnessTypestringFields(requiredExtraTypestring).map((field) => field.name);
+    for (const name of requiredNames) {
+        if (!Object.prototype.hasOwnProperty.call(data, name)) {
+            return {
+                valid: false,
+                error: `${dataLabel} is missing required Miden field "${name}"`,
+            };
+        }
+    }
+    return { valid: true };
+}
+function validateRequiredMidenFields(typestring, data, typestringLabel, dataLabel) {
+    const direction = resolveMidenBridgeDirection(typestring, data);
+    if (direction === "conflict") {
+        return {
+            valid: false,
+            error: "Miden witness cannot include both midenSourceAccount and midenRecipientAccount",
+        };
+    }
+    if (!direction) {
+        return {
+            valid: false,
+            error: "Unable to determine Miden bridge direction",
+        };
+    }
+    const requiredExtraTypestring = requiredMidenExtraTypestring(direction);
+    const declarationCheck = assertMidenFieldsDeclared(typestring, requiredExtraTypestring, typestringLabel);
+    if (!declarationCheck.valid)
+        return declarationCheck;
+    if (!data) {
+        return {
+            valid: false,
+            error: `${dataLabel} is required for Miden intents`,
+        };
+    }
+    return assertMidenFieldsPresentInData(data, requiredExtraTypestring, dataLabel);
+}
+/**
+ * Validate Miden `extraDataTypestring` / `extraData` for task assembly.
+ * Required Miden fields must be declared and present; additional protocol fields
+ * are allowed when declared in the typestring.
+ */
+export function validateMidenExtraFields(extraDataTypestring, extraData) {
+    if (!extraDataTypestring.trim() && extraData === undefined) {
+        return { valid: true };
+    }
+    if (!isMidenIntent(extraDataTypestring, extraData)) {
+        return { valid: true };
+    }
+    return validateRequiredMidenFields(extraDataTypestring, extraData, "extraDataTypestring", "extraData");
+}
+/**
+ * When a mandate includes Miden bridge metadata, the witness typestring must
+ * declare every required Miden field for the detected direction. Additional
+ * non-Miden fields may appear before or after the Miden fields.
+ *
+ * No-op for pure EVM intents — Miden checks run only when {@link isMidenIntent}.
+ */
+export function assertMidenWitnessFields(witnessTypeString, mandate) {
+    if (!isMidenIntent(witnessTypeString, mandate)) {
+        return { valid: true };
+    }
+    return validateRequiredMidenFields(witnessTypeString, mandate, "witnessTypeString", "mandate");
+}
+/**
+ * Validates a witness typestring against its data. Handles both the full witness
+ * (base mandate + extra suffix) and a bare extra suffix — the same rules apply to
+ * either: comma spacing, "type name" format, key alignment with the data object,
+ * and required Miden bridge fields when applicable. Pass the assembled typestring and the
+ * merged data; there is no separate extra-suffix validator.
+ */
+export function validateWitnessTypeString(witnessTypeString, mandate) {
+    if (mandate?.midenSourceAccount != null &&
+        mandate?.midenRecipientAccount != null) {
+        return {
+            valid: false,
+            error: "Miden witness cannot include both midenSourceAccount and midenRecipientAccount",
+        };
+    }
+    if (!witnessTypeString || witnessTypeString.trim() === "") {
+        return { valid: true };
+    }
+    const commaCheck = assertNoSpacesAroundCommas(witnessTypeString);
+    if (!commaCheck.valid)
+        return commaCheck;
+    try {
+        parseWitnessTypestringFields(witnessTypeString);
+    }
+    catch (error) {
+        return {
+            valid: false,
+            error: error instanceof Error
+                ? error.message
+                : "Invalid witnessTypeString format",
+        };
+    }
+    if (mandate) {
+        const keyCheck = assertKeysMatchTypestring(witnessTypeString, mandate, "mandate", "witnessTypeString");
+        if (!keyCheck.valid)
+            return keyCheck;
+    }
+    const midenCheck = assertMidenWitnessFields(witnessTypeString, mandate);
+    if (!midenCheck.valid)
+        return midenCheck;
+    return { valid: true };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epoch-protocol/epoch-commons-sdk",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "SDK for interacting with Epoch Commons Protocol",
   "type": "module",
   "main": "dist/index.js",