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

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,3 @@
 export * from "./compact.js";
 export * from "./path.js";
+export * from "./witness-typestring.js";

package/dist/utils/index.js

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

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

@@ -0,0 +1,35 @@
+/** 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 type WitnessTypestringValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    error: string;
+};
+export declare function parseWitnessTypestringFields(witnessTypeString: string): Array<{
+    type: string;
+    name: string;
+}>;
+/**
+ * When a mandate includes Miden bridge metadata, the witness typestring must end
+ * with the canonical Miden suffix. Direction (Miden→EVM vs EVM→Miden) is inferred
+ * from the mandate and from the typestring's own suffix.
+ *
+ * No-op for pure EVM intents — Miden checks run only when {@link isMidenIntent}.
+ */
+export declare function assertMidenWitnessSuffix(witnessTypeString: string, mandate?: Record<string, unknown>): WitnessTypestringValidationResult;
+export declare function isEVMToMidenMandate(mandate?: Record<string, unknown>): boolean;
+/**
+ * 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 the canonical Miden bridge suffix. 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,166 @@
+/** 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 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 };
+    });
+}
+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 isEvmToMidenMandate(mandate) {
+    return (mandate?.midenRecipientAccount != null &&
+        mandate?.midenSourceAccount == null);
+}
+function isMidenToEvmMandate(mandate) {
+    return mandate?.midenSourceAccount != null;
+}
+function hasMidenToEvmSuffix(witnessTypeString) {
+    return witnessTypeString.includes("midenSourceAccount");
+}
+function hasEvmToMidenSuffix(witnessTypeString) {
+    return (witnessTypeString.includes("midenRecipientAccount") &&
+        !witnessTypeString.includes("midenSourceAccount"));
+}
+/**
+ * True iff the intent is a Miden bridge intent — i.e. it carries Miden markers
+ * either in the mandate (midenSourceAccount / midenRecipientAccount) or in the
+ * witness typestring itself. Pure EVM intents carry none of these, so all Miden
+ * validation is skipped for them.
+ */
+function isMidenIntent(witnessTypeString, mandate) {
+    return (isMidenToEvmMandate(mandate) ||
+        isEvmToMidenMandate(mandate) ||
+        hasMidenToEvmSuffix(witnessTypeString) ||
+        hasEvmToMidenSuffix(witnessTypeString));
+}
+/**
+ * When a mandate includes Miden bridge metadata, the witness typestring must end
+ * with the canonical Miden suffix. Direction (Miden→EVM vs EVM→Miden) is inferred
+ * from the mandate and from the typestring's own suffix.
+ *
+ * No-op for pure EVM intents — Miden checks run only when {@link isMidenIntent}.
+ */
+export function assertMidenWitnessSuffix(witnessTypeString, mandate) {
+    if (!isMidenIntent(witnessTypeString, mandate)) {
+        return { valid: true };
+    }
+    const toEvm = isMidenToEvmMandate(mandate) || hasMidenToEvmSuffix(witnessTypeString);
+    const fromEvm = isEvmToMidenMandate(mandate) || hasEvmToMidenSuffix(witnessTypeString);
+    if (toEvm && fromEvm) {
+        return {
+            valid: false,
+            error: "Miden witness cannot include both midenSourceAccount and midenRecipientAccount",
+        };
+    }
+    const expectedSuffix = toEvm
+        ? MIDEN_TO_EVM_EXTRA_TYPESTRING
+        : EVM_TO_MIDEN_EXTRA_TYPESTRING;
+    if (!witnessTypeString.endsWith(expectedSuffix)) {
+        return {
+            valid: false,
+            error: `Invalid Miden witness suffix. Expected typestring to end with "${expectedSuffix}".`,
+        };
+    }
+    return { valid: true };
+}
+export function isEVMToMidenMandate(mandate) {
+    return isEvmToMidenMandate(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 the canonical Miden bridge suffix. 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 = assertMidenWitnessSuffix(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.18",
   "description": "SDK for interacting with Epoch Commons Protocol",
   "type": "module",
   "main": "dist/index.js",