@debridge-finance/borderless-validation-sdk 0.0.5 → 0.0.7

package/dist/esm/validations/total-dst-amount.js

@@ -0,0 +1,429 @@
+import { ViolationCode, SpecialAmount, } from "../types/index.js";
+import { resolveChainId } from "../whitelists/subscription-to-chain-id.js";
+import { addressEquals, normalizeAddress } from "../helpers/address.js";
+import { parseIntegerString } from "../helpers/integer.js";
+// Asset consolidation mode: when `request.totalDstAmount` is set, the API
+// treats `srcChainTokenInAmount` of each trade as an upper bound, walks trades
+// in order, and produces a balancing trade that closes the dst total to
+// `totalDstAmount` exactly. Tail trades after the balancing trade may be
+// dropped from `response.trades[]`. With `allowPartialFill=true` the pipeline
+// may stop short and emit no balancing trade — every kept trade is then taken
+// at the full upper bound. See the `enum TradeRole` invariant for how the
+// balancing trade is identified in each pipeline branch.
+export function validateTotalDstAmount(request, response) {
+    const requestHasField = request.totalDstAmount !== undefined;
+    const responseHasField = response.estimatedTotalDstAmount !== undefined;
+    // Neither field is set — request runs in regular mode, nothing to validate.
+    if (!requestHasField && !responseHasField)
+        return [];
+    // CRITICAL: the two fields must appear together
+    if (requestHasField !== responseHasField) {
+        return [{
+                code: ViolationCode.TotalDstAmountModeMismatch,
+                message: "request.totalDstAmount and response.estimatedTotalDstAmount must appear together",
+                path: "response.estimatedTotalDstAmount",
+                expected: request.totalDstAmount,
+                actual: response.estimatedTotalDstAmount,
+            }];
+    }
+    // Both fields are defined here: the two early returns above handle the
+    // neither-set and one-sided cases.
+    const requestedTotal = request.totalDstAmount;
+    const estimatedTotal = response.estimatedTotalDstAmount;
+    const formatViolations = validateTotalAmountFormats(requestedTotal, estimatedTotal);
+    return [
+        ...validateRequestLevelConstraints(request),
+        ...formatViolations,
+        ...(formatViolations.length === 0
+            ? [
+                ...validateEstimatedTotal(request, requestedTotal, estimatedTotal),
+                ...validateEstimatedVsAccumulative(response, estimatedTotal),
+                ...validateEstimatedVsSumOfTradeDstAmounts(response, estimatedTotal),
+            ]
+            : []),
+    ];
+}
+function validateTotalAmountFormats(requestedTotal, estimatedTotal) {
+    const violations = [];
+    // CRITICAL: request.totalDstAmount must parse as a positive integer.
+    try {
+        if (parseIntegerString(requestedTotal) <= 0n) {
+            violations.push({
+                code: ViolationCode.TotalDstAmountInvalid,
+                message: "request.totalDstAmount must be a positive integer string",
+                path: "request.totalDstAmount",
+                actual: requestedTotal,
+            });
+        }
+    }
+    catch (error) {
+        violations.push({
+            code: ViolationCode.TotalDstAmountInvalid,
+            message: "request.totalDstAmount must be a positive integer string",
+            path: "request.totalDstAmount",
+            actual: requestedTotal,
+            details: error,
+        });
+    }
+    // CRITICAL: response.estimatedTotalDstAmount must parse as a positive integer.
+    try {
+        if (parseIntegerString(estimatedTotal) <= 0n) {
+            violations.push({
+                code: ViolationCode.TotalDstAmountInvalid,
+                message: "response.estimatedTotalDstAmount must be a positive integer string",
+                path: "response.estimatedTotalDstAmount",
+                actual: estimatedTotal,
+            });
+        }
+    }
+    catch (error) {
+        violations.push({
+            code: ViolationCode.TotalDstAmountInvalid,
+            message: "response.estimatedTotalDstAmount must be a positive integer string",
+            path: "response.estimatedTotalDstAmount",
+            actual: estimatedTotal,
+            details: error,
+        });
+    }
+    return violations;
+}
+function validateRequestLevelConstraints(request) {
+    return [
+        ...validateAccountAbstractionRequired(request),
+        ...validateRecipientsRequired(request),
+        ...validateSingleDestination(request),
+        ...validateDstAmountIsAuto(request),
+        ...validateAutoSrcIsLast(request),
+        ...validateNoDuplicateSpecialSrcAssets(request),
+    ];
+}
+function validateAccountAbstractionRequired(request) {
+    if (request.enableAccountAbstraction)
+        return [];
+    // CRITICAL: `enableAccountAbstraction` must be true in asset consolidation mode
+    return [{
+            code: ViolationCode.TotalDstAmountAccountAbstractionRequired,
+            message: "request.enableAccountAbstraction must be true when request.totalDstAmount is set",
+            path: "request.enableAccountAbstraction",
+            expected: true,
+            actual: request.enableAccountAbstraction,
+        }];
+}
+function validateRecipientsRequired(request) {
+    const violations = [];
+    for (let i = 0; i < request.trades.length; i++) {
+        const recipient = request.trades[i].dstChainTokenOutRecipient;
+        if (recipient === undefined) {
+            // CRITICAL: the API's totalDstAmount bundle validator requires a
+            // concrete destination recipient so it can compare destinations.
+            violations.push({
+                code: ViolationCode.TotalDstAmountRecipientRequired,
+                message: "request.trades[].dstChainTokenOutRecipient is required"
+                    + " in asset consolidation mode",
+                path: `request.trades[${i}].dstChainTokenOutRecipient`,
+                actual: recipient,
+            });
+        }
+    }
+    return violations;
+}
+function validateSingleDestination(request) {
+    if (request.trades.length === 0)
+        return [];
+    const violations = [];
+    const referenceTrade = request.trades[0];
+    const referenceRealChainId = resolveChainId(referenceTrade.dstChainId);
+    for (let i = 1; i < request.trades.length; i++) {
+        const trade = request.trades[i];
+        violations.push(...checkDestinationMatchesReference(trade, i, referenceTrade, referenceRealChainId));
+    }
+    return violations;
+}
+function checkDestinationMatchesReference(trade, tradeIndex, referenceTrade, referenceRealChainId) {
+    const violations = [];
+    const basePath = `request.trades[${tradeIndex}]`;
+    // CRITICAL: all trades must share the same destination chain
+    if (trade.dstChainId !== referenceTrade.dstChainId) {
+        violations.push({
+            code: ViolationCode.TotalDstAmountSingleDestinationMismatch,
+            message: "all request.trades[].dstChainId must be equal in asset consolidation mode",
+            path: `${basePath}.dstChainId`,
+            expected: referenceTrade.dstChainId,
+            actual: trade.dstChainId,
+        });
+    }
+    // Safe skip: when dstChainId differs from the `referenceTrade`, the address
+    // comparison below is meaningless — address formats and case sensitivity
+    // are chain-specific (EVM lowercase vs Solana/Tron case-sensitive), so
+    // comparing under the wrong chain would produce nonsense. The chainId
+    // mismatch is already reported above as its own Violation.
+    if (trade.dstChainId === referenceTrade.dstChainId && referenceRealChainId !== undefined) {
+        // CRITICAL: same dst token across trades
+        if (!addressEquals(referenceRealChainId, referenceTrade.dstChainTokenOut, trade.dstChainTokenOut)) {
+            violations.push({
+                code: ViolationCode.TotalDstAmountSingleDestinationMismatch,
+                message: "all request.trades[].dstChainTokenOut must be equal in asset consolidation mode",
+                path: `${basePath}.dstChainTokenOut`,
+                expected: referenceTrade.dstChainTokenOut,
+                actual: trade.dstChainTokenOut,
+            });
+        }
+        // CRITICAL: same recipient across trades
+        violations.push(...checkRecipientMatches(trade, tradeIndex, referenceTrade, referenceRealChainId));
+    }
+    return violations;
+}
+function checkRecipientMatches(trade, tradeIndex, referenceTrade, referenceRealChainId) {
+    const refRecipient = referenceTrade.dstChainTokenOutRecipient;
+    const tradeRecipient = trade.dstChainTokenOutRecipient;
+    // Both undefined — simple match.
+    if (refRecipient === undefined && tradeRecipient === undefined)
+        return [];
+    const path = `request.trades[${tradeIndex}].dstChainTokenOutRecipient`;
+    const code = ViolationCode.TotalDstAmountSingleDestinationMismatch;
+    // One defined, the other not — Violation regardless of address comparison
+    if (refRecipient === undefined || tradeRecipient === undefined) {
+        return [{
+                code,
+                message: "all request.trades[].dstChainTokenOutRecipient must be equal in asset consolidation mode",
+                path,
+                expected: refRecipient,
+                actual: tradeRecipient,
+            }];
+    }
+    if (!addressEquals(referenceRealChainId, refRecipient, tradeRecipient)) {
+        return [{
+                code,
+                message: "all request.trades[].dstChainTokenOutRecipient must be equal in asset consolidation mode",
+                path,
+                expected: refRecipient,
+                actual: tradeRecipient,
+            }];
+    }
+    return [];
+}
+function validateDstAmountIsAuto(request) {
+    const violations = [];
+    for (let i = 0; i < request.trades.length; i++) {
+        const amount = request.trades[i].dstChainTokenOutAmount;
+        if (amount !== undefined && amount !== SpecialAmount.Auto) {
+            // CRITICAL: all trades must have dstChainTokenOutAmount='auto' in consolidation mode
+            violations.push({
+                code: ViolationCode.TotalDstAmountDstAmountMustBeAuto,
+                message: "request.trades[].dstChainTokenOutAmount must be 'auto' in asset consolidation mode",
+                path: `request.trades[${i}].dstChainTokenOutAmount`,
+                expected: SpecialAmount.Auto,
+                actual: amount,
+            });
+        }
+    }
+    return violations;
+}
+function validateAutoSrcIsLast(request) {
+    const violations = [];
+    const lastIndex = request.trades.length - 1;
+    for (let i = 0; i < request.trades.length; i++) {
+        const isAuto = request.trades[i].srcChainTokenInAmount === SpecialAmount.Auto;
+        if (isAuto && i !== lastIndex) {
+            // CRITICAL: 'auto' src amount may appear only on the last trade.
+            // No single "expected" concrete value (any non-'auto' value would
+            // satisfy the rule); the human-readable explanation is in `message`.
+            violations.push({
+                code: ViolationCode.TotalDstAmountAutoSrcMustBeLast,
+                message: "request.trades[].srcChainTokenInAmount='auto' is only"
+                    + " allowed on the last trade in asset consolidation mode",
+                path: `request.trades[${i}].srcChainTokenInAmount`,
+                actual: SpecialAmount.Auto,
+            });
+        }
+    }
+    return violations;
+}
+function validateNoDuplicateSpecialSrcAssets(request) {
+    const violations = [];
+    const seen = new Map();
+    for (let i = 0; i < request.trades.length; i++) {
+        const trade = request.trades[i];
+        const realSrcChainId = resolveChainId(trade.srcChainId);
+        // Safe skip: an unknown `srcChainId` is already reported as
+        // UnknownSubscriptionId by `groupTrades` / `validateSingleTrade`.
+        if (realSrcChainId === undefined)
+            continue;
+        const isSpecial = trade.srcChainTokenInAmount === SpecialAmount.Max
+            || trade.srcChainTokenInAmount === SpecialAmount.Auto;
+        const key = `${trade.srcChainId}:${normalizeAddress(realSrcChainId, trade.srcChainTokenIn)}`;
+        const existing = seen.get(key);
+        if (existing !== undefined && (isSpecial || existing.isSpecial)) {
+            const existingTrade = request.trades[existing.index];
+            // CRITICAL: only one trade per (`srcChainId`, `srcChainTokenIn`)
+            // when either uses 'max' or 'auto'.
+            violations.push({
+                code: ViolationCode.TotalDstAmountDuplicateSpecialSrcAsset,
+                message: "duplicate (srcChainId, srcChainTokenIn) is only allowed"
+                    + " when both trades use a fixed amount in asset"
+                    + " consolidation mode",
+                path: "request.trades",
+                actual: {
+                    existing: {
+                        index: existing.index,
+                        srcChainId: existingTrade.srcChainId,
+                        srcChainTokenIn: existingTrade.srcChainTokenIn,
+                        srcChainTokenInAmount: existingTrade.srcChainTokenInAmount,
+                    },
+                    duplicate: {
+                        index: i,
+                        srcChainId: trade.srcChainId,
+                        srcChainTokenIn: trade.srcChainTokenIn,
+                        srcChainTokenInAmount: trade.srcChainTokenInAmount,
+                    },
+                },
+            });
+        }
+        seen.set(key, { index: i, isSpecial });
+    }
+    return violations;
+}
+function validateEstimatedTotal(request, requestedTotal, estimatedTotal) {
+    let parsedEstimated;
+    let parsedRequested;
+    try {
+        parsedEstimated = parseIntegerString(estimatedTotal);
+        parsedRequested = parseIntegerString(requestedTotal);
+    }
+    catch (error) {
+        return [{
+                code: ViolationCode.TotalDstAmountEstimatedExceedsRequested,
+                message: "failed to parse request.totalDstAmount / response.estimatedTotalDstAmount as BigInt",
+                path: "response.estimatedTotalDstAmount",
+                expected: undefined,
+                actual: {
+                    "request.totalDstAmount": requestedTotal,
+                    "response.estimatedTotalDstAmount": estimatedTotal,
+                },
+                details: error,
+            }];
+    }
+    // CRITICAL: estimated must be strictly positive
+    if (parsedEstimated <= 0n) {
+        return [{
+                code: ViolationCode.TotalDstAmountEstimatedNonPositive,
+                message: "response.estimatedTotalDstAmount must be strictly positive",
+                path: "response.estimatedTotalDstAmount",
+                actual: estimatedTotal,
+            }];
+    }
+    // CRITICAL: estimated must equal requested in strict mode (default), or
+    // be <= requested when `allowPartialFill=true`.
+    const allowPartial = request.allowPartialFill === true;
+    if (allowPartial) {
+        if (parsedEstimated > parsedRequested) {
+            return [{
+                    code: ViolationCode.TotalDstAmountEstimatedExceedsRequested,
+                    message: "response.estimatedTotalDstAmount must be <= request.totalDstAmount (allowPartialFill=true)",
+                    path: "response.estimatedTotalDstAmount",
+                    expected: { max: requestedTotal },
+                    actual: estimatedTotal,
+                }];
+        }
+        return [];
+    }
+    // CRITICAL: in strict mode (`allowPartialFill=false` / default), the API
+    // must collect exactly `totalDstAmount` — otherwise it should return an
+    // error before producing a response.
+    if (parsedEstimated !== parsedRequested) {
+        return [{
+                code: ViolationCode.TotalDstAmountEstimatedExceedsRequested,
+                message: "response.estimatedTotalDstAmount must equal request.totalDstAmount (allowPartialFill=false)",
+                path: "response.estimatedTotalDstAmount",
+                expected: requestedTotal,
+                actual: estimatedTotal,
+            }];
+    }
+    return [];
+}
+function validateEstimatedVsAccumulative(response, estimatedTotal) {
+    // Safe skip: an empty / multi-element `accumulativeTokenOutput` is already
+    // reported by `validateAccumulativeTokens` (counts and group recomputation).
+    // We only run this sanity check when there is exactly one element, which
+    // is the expected shape for asset consolidation mode (all trades share the
+    // same dst token / chain / recipient — enforced by `validateSingleDestination`
+    // above for the request side, and by the accumulative-token grouping for
+    // the response side).
+    if (response.accumulativeTokenOutput.length !== 1)
+        return [];
+    const accumulativeAmount = response.accumulativeTokenOutput[0].amount;
+    let parsedEstimated;
+    let parsedAccumulative;
+    try {
+        parsedEstimated = parseIntegerString(estimatedTotal);
+        parsedAccumulative = parseIntegerString(accumulativeAmount);
+    }
+    catch (error) {
+        return [{
+                code: ViolationCode.TotalDstAmountVsAccumulativeMismatch,
+                message: "failed to parse response.estimatedTotalDstAmount / accumulativeTokenOutput[0].amount as BigInt",
+                path: "response.estimatedTotalDstAmount",
+                expected: undefined,
+                actual: {
+                    "response.estimatedTotalDstAmount": estimatedTotal,
+                    "response.accumulativeTokenOutput[0].amount": accumulativeAmount,
+                },
+                details: error,
+            }];
+    }
+    // CRITICAL: `estimatedTotalDstAmount` must equal `accumulativeTokenOutput[0].amount`
+    if (parsedEstimated !== parsedAccumulative) {
+        return [{
+                code: ViolationCode.TotalDstAmountVsAccumulativeMismatch,
+                message: "response.estimatedTotalDstAmount must equal response.accumulativeTokenOutput[0].amount",
+                path: "response.estimatedTotalDstAmount",
+                expected: accumulativeAmount,
+                actual: estimatedTotal,
+            }];
+    }
+    return [];
+}
+// CRITICAL: direct invariant of the consolidation mode — the destination
+// total the user receives is the sum of per-trade dst amounts. Independent
+// from the `accumulativeTokenOutput` sanity above: an attacker who reconciled
+// `estimatedTotalDstAmount` with `accumulativeTokenOutput[0].amount` would
+// still need to reconcile each per-trade `dstChainTokenOut.amount` to pass
+// this check — and per-trade amounts are pinned by the API pipeline
+// (remaining `dst` needed to reach `totalDstAmount` on balancing, `dst` computed
+// from `src` on non-balancing).
+function validateEstimatedVsSumOfTradeDstAmounts(response, estimatedTotal) {
+    let sum = 0n;
+    for (let i = 0; i < response.trades.length; i++) {
+        const tradeAmount = response.trades[i].dstChainTokenOut.amount;
+        try {
+            sum += parseIntegerString(tradeAmount);
+        }
+        catch (error) {
+            // Safe skip: invalid per-trade `dst.amount` is already reported by
+            // `validateTrades` (`dst.amount` parse rules).
+            void error;
+            return [];
+        }
+    }
+    let parsedEstimated;
+    try {
+        parsedEstimated = parseIntegerString(estimatedTotal);
+    }
+    catch {
+        // Safe skip: invalid `estimatedTotalDstAmount` is reported by
+        // `validateEstimatedTotal` above.
+        return [];
+    }
+    if (parsedEstimated !== sum) {
+        return [{
+                code: ViolationCode.TotalDstAmountSumDstMismatch,
+                message: "response.estimatedTotalDstAmount must equal the sum of"
+                    + " response.trades[].dstChainTokenOut.amount",
+                path: "response.estimatedTotalDstAmount",
+                expected: sum.toString(),
+                actual: estimatedTotal,
+            }];
+    }
+    return [];
+}
+//# sourceMappingURL=total-dst-amount.js.map

package/dist/esm/validations/total-dst-amount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"total-dst-amount.js","sourceRoot":"","sources":["../../../src/validations/total-dst-amount.ts"],"names":[],"mappings":"AAAA,OAAO,EAEH,aAAa,EAIb,aAAa,GAChB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,0EAA0E;AAC1E,+EAA+E;AAC/E,wEAAwE;AACxE,yEAAyE;AACzE,8EAA8E;AAC9E,8EAA8E;AAC9E,0EAA0E;AAC1E,yDAAyD;AACzD,MAAM,UAAU,sBAAsB,CAClC,OAA8B,EAC9B,QAAgC;IAEhC,MAAM,eAAe,GAAG,OAAO,CAAC,cAAc,KAAK,SAAS,CAAC;IAC7D,MAAM,gBAAgB,GAAG,QAAQ,CAAC,uBAAuB,KAAK,SAAS,CAAC;IAExE,4EAA4E;IAC5E,IAAI,CAAC,eAAe,IAAI,CAAC,gBAAgB;QAAE,OAAO,EAAE,CAAC;IAErD,gDAAgD;IAChD,IAAI,eAAe,KAAK,gBAAgB,EAAE,CAAC;QACvC,OAAO,CAAC;gBACJ,IAAI,EAAE,aAAa,CAAC,0BAA0B;gBAC9C,OAAO,EACH,kFAAkF;gBACtF,IAAI,EAAE,kCAAkC;gBACxC,QAAQ,EAAE,OAAO,CAAC,cAAc;gBAChC,MAAM,EAAE,QAAQ,CAAC,uBAAuB;aAC3C,CAAC,CAAC;IACP,CAAC;IAED,uEAAuE;IACvE,mCAAmC;IACnC,MAAM,cAAc,GAAG,OAAO,CAAC,cAAwB,CAAC;IACxD,MAAM,cAAc,GAAG,QAAQ,CAAC,uBAAiC,CAAC;IAClE,MAAM,gBAAgB,GAAG,0BAA0B,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC;IAEpF,OAAO;QACH,GAAG,+BAA+B,CAAC,OAAO,CAAC;QAC3C,GAAG,gBAAgB;QACnB,GAAG,CAAC,gBAAgB,CAAC,MAAM,KAAK,CAAC;YAC7B,CAAC,CAAC;gBACE,GAAG,sBAAsB,CAAC,OAAO,EAAE,cAAc,EAAE,cAAc,CAAC;gBAClE,GAAG,+BAA+B,CAAC,QAAQ,EAAE,cAAc,CAAC;gBAC5D,GAAG,uCAAuC,CAAC,QAAQ,EAAE,cAAc,CAAC;aACvE;YACD,CAAC,CAAC,EAAE,CAAC;KACZ,CAAC;AACN,CAAC;AAED,SAAS,0BAA0B,CAC/B,cAAsB,EACtB,cAAsB;IAEtB,MAAM,UAAU,GAAgB,EAAE,CAAC;IAEnC,qEAAqE;IACrE,IAAI,CAAC;QACD,IAAI,kBAAkB,CAAC,cAAc,CAAC,IAAI,EAAE,EAAE,CAAC;YAC3C,UAAU,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,aAAa,CAAC,qBAAqB;gBACzC,OAAO,EAAE,0DAA0D;gBACnE,IAAI,EAAE,wBAAwB;gBAC9B,MAAM,EAAE,cAAc;aACzB,CAAC,CAAC;QACP,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,UAAU,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,aAAa,CAAC,qBAAqB;YACzC,OAAO,EAAE,0DAA0D;YACnE,IAAI,EAAE,wBAAwB;YAC9B,MAAM,EAAE,cAAc;YACtB,OAAO,EAAE,KAAK;SACjB,CAAC,CAAC;IACP,CAAC;IAED,+EAA+E;IAC/E,IAAI,CAAC;QACD,IAAI,kBAAkB,CAAC,cAAc,CAAC,IAAI,EAAE,EAAE,CAAC;YAC3C,UAAU,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,aAAa,CAAC,qBAAqB;gBACzC,OAAO,EAAE,oEAAoE;gBAC7E,IAAI,EAAE,kCAAkC;gBACxC,MAAM,EAAE,cAAc;aACzB,CAAC,CAAC;QACP,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,UAAU,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,aAAa,CAAC,qBAAqB;YACzC,OAAO,EAAE,oEAAoE;YAC7E,IAAI,EAAE,kCAAkC;YACxC,MAAM,EAAE,cAAc;YACtB,OAAO,EAAE,KAAK;SACjB,CAAC,CAAC;IACP,CAAC;IAED,OAAO,UAAU,CAAC;AACtB,CAAC;AAED,SAAS,+BAA+B,CACpC,OAA8B;IAE9B,OAAO;QACH,GAAG,kCAAkC,CAAC,OAAO,CAAC;QAC9C,GAAG,0BAA0B,CAAC,OAAO,CAAC;QACtC,GAAG,yBAAyB,CAAC,OAAO,CAAC;QACrC,GAAG,uBAAuB,CAAC,OAAO,CAAC;QACnC,GAAG,qBAAqB,CAAC,OAAO,CAAC;QACjC,GAAG,mCAAmC,CAAC,OAAO,CAAC;KAClD,CAAC;AACN,CAAC;AAED,SAAS,kCAAkC,CACvC,OAA8B;IAE9B,IAAI,OAAO,CAAC,wBAAwB;QAAE,OAAO,EAAE,CAAC;IAEhD,gFAAgF;IAChF,OAAO,CAAC;YACJ,IAAI,EAAE,aAAa,CAAC,wCAAwC;YAC5D,OAAO,EACH,kFAAkF;YACtF,IAAI,EAAE,kCAAkC;YACxC,QAAQ,EAAE,IAAI;YACd,MAAM,EAAE,OAAO,CAAC,wBAAwB;SAC3C,CAAC,CAAC;AACP,CAAC;AAED,SAAS,0BAA0B,CAC/B,OAA8B;IAE9B,MAAM,UAAU,GAAgB,EAAE,CAAC;IAEnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7C,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,yBAAyB,CAAC;QAC9D,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC1B,iEAAiE;YACjE,iEAAiE;YACjE,UAAU,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,aAAa,CAAC,+BAA+B;gBACnD,OAAO,EACH,wDAAwD;sBACtD,8BAA8B;gBACpC,IAAI,EAAE,kBAAkB,CAAC,6BAA6B;gBACtD,MAAM,EAAE,SAAS;aACpB,CAAC,CAAC;QACP,CAAC;IACL,CAAC;IAED,OAAO,UAAU,CAAC;AACtB,CAAC;AAED,SAAS,yBAAyB,CAC9B,OAA8B;IAE9B,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAE3C,MAAM,UAAU,GAAgB,EAAE,CAAC;IACnC,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACzC,MAAM,oBAAoB,GAAG,cAAc,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;IAEvE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7C,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAChC,UAAU,CAAC,IAAI,CACX,GAAG,gCAAgC,CAC/B,KAAK,EAAE,CAAC,EAAE,cAAc,EAAE,oBAAoB,CACjD,CACJ,CAAC;IACN,CAAC;IAED,OAAO,UAAU,CAAC;AACtB,CAAC;AAED,SAAS,gCAAgC,CACrC,KAAmB,EACnB,UAAkB,EAClB,cAA4B,EAC5B,oBAAwC;IAExC,MAAM,UAAU,GAAgB,EAAE,CAAC;IACnC,MAAM,QAAQ,GAAG,kBAAkB,UAAU,GAAG,CAAC;IAEjD,6DAA6D;IAC7D,IAAI,KAAK,CAAC,UAAU,KAAK,cAAc,CAAC,UAAU,EAAE,CAAC;QACjD,UAAU,CAAC,IAAI,CAAC;YACZ,IAAI,EAAE,aAAa,CAAC,uCAAuC;YAC3D,OAAO,EACH,2EAA2E;YAC/E,IAAI,EAAE,GAAG,QAAQ,aAAa;YAC9B,QAAQ,EAAE,cAAc,CAAC,UAAU;YACnC,MAAM,EAAE,KAAK,CAAC,UAAU;SAC3B,CAAC,CAAC;IACP,CAAC;IAED,4EAA4E;IAC5E,yEAAyE;IACzE,uEAAuE;IACvE,sEAAsE;IACtE,2DAA2D;IAC3D,IAAI,KAAK,CAAC,UAAU,KAAK,cAAc,CAAC,UAAU,IAAI,oBAAoB,KAAK,SAAS,EAAE,CAAC;QACvF,yCAAyC;QACzC,IAAI,CAAC,aAAa,CACd,oBAAoB,EAAE,cAAc,CAAC,gBAAgB,EAAE,KAAK,CAAC,gBAAgB,CAChF,EAAE,CAAC;YACA,UAAU,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,aAAa,CAAC,uCAAuC;gBAC3D,OAAO,EACH,iFAAiF;gBACrF,IAAI,EAAE,GAAG,QAAQ,mBAAmB;gBACpC,QAAQ,EAAE,cAAc,CAAC,gBAAgB;gBACzC,MAAM,EAAE,KAAK,CAAC,gBAAgB;aACjC,CAAC,CAAC;QACP,CAAC;QAED,yCAAyC;QACzC,UAAU,CAAC,IAAI,CAAC,GAAG,qBAAqB,CACpC,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,oBAAoB,CAC1D,CAAC,CAAC;IACP,CAAC;IAED,OAAO,UAAU,CAAC;AACtB,CAAC;AAED,SAAS,qBAAqB,CAC1B,KAAmB,EACnB,UAAkB,EAClB,cAA4B,EAC5B,oBAA4B;IAE5B,MAAM,YAAY,GAAG,cAAc,CAAC,yBAAyB,CAAC;IAC9D,MAAM,cAAc,GAAG,KAAK,CAAC,yBAAyB,CAAC;IAEvD,iCAAiC;IACjC,IAAI,YAAY,KAAK,SAAS,IAAI,cAAc,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IAE1E,MAAM,IAAI,GAAG,kBAAkB,UAAU,6BAA6B,CAAC;IACvE,MAAM,IAAI,GAAG,aAAa,CAAC,uCAAuC,CAAC;IAEnE,0EAA0E;IAC1E,IAAI,YAAY,KAAK,SAAS,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;QAC7D,OAAO,CAAC;gBACJ,IAAI;gBACJ,OAAO,EACH,0FAA0F;gBAC9F,IAAI;gBACJ,QAAQ,EAAE,YAAY;gBACtB,MAAM,EAAE,cAAc;aACzB,CAAC,CAAC;IACP,CAAC;IAED,IAAI,CAAC,aAAa,CAAC,oBAAoB,EAAE,YAAY,EAAE,cAAc,CAAC,EAAE,CAAC;QACrE,OAAO,CAAC;gBACJ,IAAI;gBACJ,OAAO,EACH,0FAA0F;gBAC9F,IAAI;gBACJ,QAAQ,EAAE,YAAY;gBACtB,MAAM,EAAE,cAAc;aACzB,CAAC,CAAC;IACP,CAAC;IAED,OAAO,EAAE,CAAC;AACd,CAAC;AAED,SAAS,uBAAuB,CAC5B,OAA8B;IAE9B,MAAM,UAAU,GAAgB,EAAE,CAAC;IAEnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,sBAAsB,CAAC;QACxD,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,aAAa,CAAC,IAAI,EAAE,CAAC;YACxD,qFAAqF;YACrF,UAAU,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,aAAa,CAAC,iCAAiC;gBACrD,OAAO,EACH,oFAAoF;gBACxF,IAAI,EAAE,kBAAkB,CAAC,0BAA0B;gBACnD,QAAQ,EAAE,aAAa,CAAC,IAAI;gBAC5B,MAAM,EAAE,MAAM;aACjB,CAAC,CAAC;QACP,CAAC;IACL,CAAC;IAED,OAAO,UAAU,CAAC;AACtB,CAAC;AAED,SAAS,qBAAqB,CAC1B,OAA8B;IAE9B,MAAM,UAAU,GAAgB,EAAE,CAAC;IACnC,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;IAE5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,qBAAqB,KAAK,aAAa,CAAC,IAAI,CAAC;QAC9E,IAAI,MAAM,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;YAC5B,iEAAiE;YACjE,kEAAkE;YAClE,qEAAqE;YACrE,UAAU,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,aAAa,CAAC,+BAA+B;gBACnD,OAAO,EACH,uDAAuD;sBACrD,wDAAwD;gBAC9D,IAAI,EAAE,kBAAkB,CAAC,yBAAyB;gBAClD,MAAM,EAAE,aAAa,CAAC,IAAI;aAC7B,CAAC,CAAC;QACP,CAAC;IACL,CAAC;IAED,OAAO,UAAU,CAAC;AACtB,CAAC;AAED,SAAS,mCAAmC,CACxC,OAA8B;IAE9B,MAAM,UAAU,GAAgB,EAAE,CAAC;IACnC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAiD,CAAC;IAEtE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7C,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAChC,MAAM,cAAc,GAAG,cAAc,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QAExD,4DAA4D;QAC5D,kEAAkE;QAClE,IAAI,cAAc,KAAK,SAAS;YAAE,SAAS;QAE3C,MAAM,SAAS,GACX,KAAK,CAAC,qBAAqB,KAAK,aAAa,CAAC,GAAG;eAC9C,KAAK,CAAC,qBAAqB,KAAK,aAAa,CAAC,IAAI,CAAC;QAE1D,MAAM,GAAG,GAAG,GAAG,KAAK,CAAC,UAAU,IAAI,gBAAgB,CAAC,cAAc,EAAE,KAAK,CAAC,eAAe,CAAC,EAAE,CAAC;QAE7F,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,QAAQ,KAAK,SAAS,IAAI,CAAC,SAAS,IAAI,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YAC9D,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YACrD,iEAAiE;YACjE,oCAAoC;YACpC,UAAU,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,aAAa,CAAC,sCAAsC;gBAC1D,OAAO,EACH,yDAAyD;sBACvD,+CAA+C;sBAC/C,qBAAqB;gBAC3B,IAAI,EAAE,gBAAgB;gBACtB,MAAM,EAAE;oBACJ,QAAQ,EAAE;wBACN,KAAK,EAAE,QAAQ,CAAC,KAAK;wBACrB,UAAU,EAAE,aAAa,CAAC,UAAU;wBACpC,eAAe,EAAE,aAAa,CAAC,eAAe;wBAC9C,qBAAqB,EAAE,aAAa,CAAC,qBAAqB;qBAC7D;oBACD,SAAS,EAAE;wBACP,KAAK,EAAE,CAAC;wBACR,UAAU,EAAE,KAAK,CAAC,UAAU;wBAC5B,eAAe,EAAE,KAAK,CAAC,eAAe;wBACtC,qBAAqB,EAAE,KAAK,CAAC,qBAAqB;qBACrD;iBACJ;aACJ,CAAC,CAAC;QACP,CAAC;QAED,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED,OAAO,UAAU,CAAC;AACtB,CAAC;AAED,SAAS,sBAAsB,CAC3B,OAA8B,EAC9B,cAAsB,EACtB,cAAsB;IAEtB,IAAI,eAAuB,CAAC;IAC5B,IAAI,eAAuB,CAAC;IAC5B,IAAI,CAAC;QACD,eAAe,GAAG,kBAAkB,CAAC,cAAc,CAAC,CAAC;QACrD,eAAe,GAAG,kBAAkB,CAAC,cAAc,CAAC,CAAC;IACzD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,OAAO,CAAC;gBACJ,IAAI,EAAE,aAAa,CAAC,uCAAuC;gBAC3D,OAAO,EACH,qFAAqF;gBACzF,IAAI,EAAE,kCAAkC;gBACxC,QAAQ,EAAE,SAAS;gBACnB,MAAM,EAAE;oBACJ,wBAAwB,EAAE,cAAc;oBACxC,kCAAkC,EAAE,cAAc;iBACrD;gBACD,OAAO,EAAE,KAAK;aACjB,CAAC,CAAC;IACP,CAAC;IAED,gDAAgD;IAChD,IAAI,eAAe,IAAI,EAAE,EAAE,CAAC;QACxB,OAAO,CAAC;gBACJ,IAAI,EAAE,aAAa,CAAC,kCAAkC;gBACtD,OAAO,EAAE,4DAA4D;gBACrE,IAAI,EAAE,kCAAkC;gBACxC,MAAM,EAAE,cAAc;aACzB,CAAC,CAAC;IACP,CAAC;IAED,wEAAwE;IACxE,gDAAgD;IAChD,MAAM,YAAY,GAAG,OAAO,CAAC,gBAAgB,KAAK,IAAI,CAAC;IACvD,IAAI,YAAY,EAAE,CAAC;QACf,IAAI,eAAe,GAAG,eAAe,EAAE,CAAC;YACpC,OAAO,CAAC;oBACJ,IAAI,EAAE,aAAa,CAAC,uCAAuC;oBAC3D,OAAO,EACH,4FAA4F;oBAChG,IAAI,EAAE,kCAAkC;oBACxC,QAAQ,EAAE,EAAE,GAAG,EAAE,cAAc,EAAE;oBACjC,MAAM,EAAE,cAAc;iBACzB,CAAC,CAAC;QACP,CAAC;QACD,OAAO,EAAE,CAAC;IACd,CAAC;IAED,yEAAyE;IACzE,wEAAwE;IACxE,qCAAqC;IACrC,IAAI,eAAe,KAAK,eAAe,EAAE,CAAC;QACtC,OAAO,CAAC;gBACJ,IAAI,EAAE,aAAa,CAAC,uCAAuC;gBAC3D,OAAO,EACH,6FAA6F;gBACjG,IAAI,EAAE,kCAAkC;gBACxC,QAAQ,EAAE,cAAc;gBACxB,MAAM,EAAE,cAAc;aACzB,CAAC,CAAC;IACP,CAAC;IAED,OAAO,EAAE,CAAC;AACd,CAAC;AAED,SAAS,+BAA+B,CACpC,QAAgC,EAChC,cAAsB;IAEtB,2EAA2E;IAC3E,6EAA6E;IAC7E,yEAAyE;IACzE,2EAA2E;IAC3E,+EAA+E;IAC/E,yEAAyE;IACzE,sBAAsB;IACtB,IAAI,QAAQ,CAAC,uBAAuB,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAE7D,MAAM,kBAAkB,GAAG,QAAQ,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAEtE,IAAI,eAAuB,CAAC;IAC5B,IAAI,kBAA0B,CAAC;IAC/B,IAAI,CAAC;QACD,eAAe,GAAG,kBAAkB,CAAC,cAAc,CAAC,CAAC;QACrD,kBAAkB,GAAG,kBAAkB,CAAC,kBAAkB,CAAC,CAAC;IAChE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,OAAO,CAAC;gBACJ,IAAI,EAAE,aAAa,CAAC,oCAAoC;gBACxD,OAAO,EACH,gGAAgG;gBACpG,IAAI,EAAE,kCAAkC;gBACxC,QAAQ,EAAE,SAAS;gBACnB,MAAM,EAAE;oBACJ,kCAAkC,EAAE,cAAc;oBAClD,4CAA4C,EAAE,kBAAkB;iBACnE;gBACD,OAAO,EAAE,KAAK;aACjB,CAAC,CAAC;IACP,CAAC;IAED,qFAAqF;IACrF,IAAI,eAAe,KAAK,kBAAkB,EAAE,CAAC;QACzC,OAAO,CAAC;gBACJ,IAAI,EAAE,aAAa,CAAC,oCAAoC;gBACxD,OAAO,EACH,wFAAwF;gBAC5F,IAAI,EAAE,kCAAkC;gBACxC,QAAQ,EAAE,kBAAkB;gBAC5B,MAAM,EAAE,cAAc;aACzB,CAAC,CAAC;IACP,CAAC;IAED,OAAO,EAAE,CAAC;AACd,CAAC;AAED,yEAAyE;AACzE,2EAA2E;AAC3E,8EAA8E;AAC9E,2EAA2E;AAC3E,2EAA2E;AAC3E,oEAAoE;AACpE,iFAAiF;AACjF,gCAAgC;AAChC,SAAS,uCAAuC,CAC5C,QAAgC,EAChC,cAAsB;IAEtB,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9C,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,MAAM,CAAC;QAC/D,IAAI,CAAC;YACD,GAAG,IAAI,kBAAkB,CAAC,WAAW,CAAC,CAAC;QAC3C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,mEAAmE;YACnE,+CAA+C;YAC/C,KAAK,KAAK,CAAC;YACX,OAAO,EAAE,CAAC;QACd,CAAC;IACL,CAAC;IAED,IAAI,eAAuB,CAAC;IAC5B,IAAI,CAAC;QACD,eAAe,GAAG,kBAAkB,CAAC,cAAc,CAAC,CAAC;IACzD,CAAC;IAAC,MAAM,CAAC;QACL,8DAA8D;QAC9D,kCAAkC;QAClC,OAAO,EAAE,CAAC;IACd,CAAC;IAED,IAAI,eAAe,KAAK,GAAG,EAAE,CAAC;QAC1B,OAAO,CAAC;gBACJ,IAAI,EAAE,aAAa,CAAC,4BAA4B;gBAChD,OAAO,EACH,wDAAwD;sBACtD,4CAA4C;gBAClD,IAAI,EAAE,kCAAkC;gBACxC,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE;gBACxB,MAAM,EAAE,cAAc;aACzB,CAAC,CAAC;IACP,CAAC;IAED,OAAO,EAAE,CAAC;AACd,CAAC"}

package/dist/esm/validations/trade-grouping.js

@@ -4,45 +4,53 @@ import { resolveChainId } from "../whitelists/subscription-to-chain-id.js";
 import { addressEquals } from "../helpers/address.js";
 import { serializeDlnHook } from "../helpers/evm-dln-hook-pack.js";
 import { hexEquals, isEmptyHex } from "../helpers/hex.js";
+import { dlnMetadataEquals, normalizeDlnMetadataKey } from "./dln-metadata.js";
+import { getResponseExternalCallHash, ResponseExternalCallHashKind } from "./external-call.js";
+import { matchTrades } from "./trade-matching.js";
 // Groups request trades to match them later with response intents.
 //
 // Quote mode: groups by srcChainId only (addresses are placeholders).
 //
 // Execution mode: groups by (srcChainId, srcChainAuthorityAddress).
 //
+// Consolidation mode: groups only the request trades that were matched to
+// response trades. Skipped request trades must not affect per-intent budgets,
+// partner costs, hooks, or metadata checks.
+//
 // NOTE: the API may further split a group into multiple intents based on
 // fields like intent.executionMetadata, intent.dlnMetadata,
 // intent.externalCallHash, etc. that are not present in the request, so one
 // group can correspond to one or more response intents.
-export function groupTrades(trades, responseTrades, quoteMode) {
+export function groupTrades(trades, responseTrades, quoteMode, consolidationMode = false, tradePairs) {
     const map = new Map();
     const violations = [];
     // Track already-reported unknown subscriptionIds to avoid duplicate violations
     const reportedUnknown = new Set();
-    for (let i = 0; i < trades.length; i++) {
-        const trade = trades[i];
-        const realChainId = resolveChainId(trade.srcChainId);
+    const entries = getGroupEntries(trades, responseTrades, quoteMode, consolidationMode, tradePairs);
+    violations.push(...entries.violations);
+    for (const entry of entries.items) {
+        const realChainId = resolveChainId(entry.trade.srcChainId);
         if (realChainId === undefined) {
-            if (!reportedUnknown.has(trade.srcChainId)) {
-                reportedUnknown.add(trade.srcChainId);
+            if (!reportedUnknown.has(entry.trade.srcChainId)) {
+                reportedUnknown.add(entry.trade.srcChainId);
                 // CRITICAL: unknown subscriptionId — cannot validate this trade
                 violations.push({
                     code: ViolationCode.UnknownSubscriptionId,
-                    message: `srcChainId=${trade.srcChainId} is not a known subscriptionId`,
-                    path: `request.trades[${i}].srcChainId`,
-                    actual: trade.srcChainId,
+                    message: `srcChainId=${entry.trade.srcChainId} is not a known subscriptionId`,
+                    path: `request.trades[${entry.requestIndex}].srcChainId`,
+                    actual: entry.trade.srcChainId,
                 });
             }
             continue;
         }
         const key = quoteMode
-            ? String(trade.srcChainId)
-            : `${trade.srcChainId}:${trade.srcChainAuthorityAddress ?? ""}`;
+            ? String(entry.trade.srcChainId)
+            : `${entry.trade.srcChainId}:${entry.trade.srcChainAuthorityAddress ?? ""}`;
         let group = map.get(key);
         if (!group) {
             group = {
-                srcChainId: trade.srcChainId,
-                srcChainAuthorityAddress: quoteMode ? undefined : trade.srcChainAuthorityAddress,
+                srcChainId: entry.trade.srcChainId,
+                srcChainAuthorityAddress: quoteMode ? undefined : entry.trade.srcChainAuthorityAddress,
                 realChainId,
                 tradeIndices: [],
                 trades: [],
@@ -50,12 +58,37 @@ export function groupTrades(trades, responseTrades, quoteMode) {
             };
             map.set(key, group);
         }
-        group.tradeIndices.push(i);
-        group.trades.push(trade);
-        group.responseTrades.push(responseTrades[i]);
+        group.tradeIndices.push(entry.requestIndex);
+        group.trades.push(entry.trade);
+        group.responseTrades.push(entry.responseTrade);
     }
     return { groups: Array.from(map.values()), violations };
 }
+function getGroupEntries(trades, responseTrades, quoteMode, consolidationMode, tradePairs) {
+    // Regular mode groups every request trade. Consolidation mode groups only
+    // matched pairs because the API may intentionally skip some request trades.
+    if (!consolidationMode) {
+        return {
+            items: trades.map((trade, requestIndex) => ({
+                requestIndex,
+                trade,
+                responseTrade: responseTrades[requestIndex],
+            })),
+            violations: [],
+        };
+    }
+    const matchResult = tradePairs === undefined
+        ? matchTrades(trades, responseTrades, quoteMode, true)
+        : { pairs: tradePairs, violations: [] };
+    return {
+        items: matchResult.pairs.map(pair => ({
+            requestIndex: pair.requestIndex,
+            trade: pair.requestTrade,
+            responseTrade: pair.responseTrade,
+        })),
+        violations: matchResult.violations,
+    };
+}
 // Matches each response intent to its trade group.
 //
 // Quote mode: matches by intentChainId == group.srcChainId.
@@ -163,7 +196,7 @@ function validateIntentDifferentiation(contexts) {
 function intentDifferentiationKey(intent) {
     return [
         intent.externalCallHash ?? "",
-        intent.dlnMetadata ?? "",
+        normalizeDlnMetadataKey(intent.dlnMetadata),
         intent.executionMetadata ?? "",
     ].join("|");
 }
@@ -175,7 +208,7 @@ function intentDifferentiationKey(intent) {
 function selectIntentTrades(group, intent) {
     // Distinct keys for trades in the group; if every trade has the same key,
     // they all belong to the single intent (no ambiguity).
-    const tradeKeys = group.trades.map(t => tradeDifferentiationKey(t));
+    const tradeKeys = group.trades.map((trade, i) => tradeDifferentiationKey(trade, group.responseTrades[i]));
     const distinct = new Set(tradeKeys);
     if (distinct.size <= 1) {
         return {
@@ -189,7 +222,7 @@ function selectIntentTrades(group, intent) {
     const responseTrades = [];
     for (let i = 0; i < group.trades.length; i++) {
         const trade = group.trades[i];
-        if (tradeMatchesIntent(trade, intent)) {
+        if (tradeMatchesIntent(trade, group.responseTrades[i], intent)) {
             indices.push(i);
             trades.push(trade);
             responseTrades.push(group.responseTrades[i]);
@@ -209,12 +242,15 @@ function selectIntentTrades(group, intent) {
     }
     return { indices, trades, responseTrades };
 }
-function tradeDifferentiationKey(trade) {
-    return [computeTradeExternalCallHash(trade) ?? "", trade.dlnMetadata ?? ""].join("|");
+function tradeDifferentiationKey(trade, responseTrade) {
+    return [
+        computeTradeExternalCallHash(trade, responseTrade) ?? "",
+        normalizeDlnMetadataKey(trade.dlnMetadata),
+    ].join("|");
 }
-function tradeMatchesIntent(trade, intent) {
-    return (hexEquals(intent.externalCallHash, computeTradeExternalCallHash(trade))
-        && hexEquals(intent.dlnMetadata, trade.dlnMetadata)
+function tradeMatchesIntent(trade, responseTrade, intent) {
+    return (hexEquals(intent.externalCallHash, computeTradeExternalCallHash(trade, responseTrade))
+        && dlnMetadataEquals(intent.dlnMetadata, trade.dlnMetadata)
         && isEmptyHex(intent.executionMetadata));
 }
 // Returns the same hash the API stores in `intent.externalCallHash` for a
@@ -222,7 +258,13 @@ function tradeMatchesIntent(trade, intent) {
 // serialization failure: `validateExternalCallHash` reports it on its own; here
 // we just treat the trade as un-matchable so the fallback in
 // `selectIntentTrades` keeps the broader group intact.
-function computeTradeExternalCallHash(trade) {
+function computeTradeExternalCallHash(trade, responseTrade) {
+    const responseHash = getResponseExternalCallHash(responseTrade);
+    if (responseHash.kind === ResponseExternalCallHashKind.Hash) {
+        return responseHash.hash;
+    }
+    // Safe skip: malformed `response.trades[].externalCallData` is reported by
+    // `validateExternalCalls`; fall back to request-side EVM serialization below.
     try {
         const packed = serializeDlnHook(trade);
         return packed === undefined ? undefined : keccak256(packed);