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

package/dist/esm/validations/trades.js

@@ -2,31 +2,111 @@ import { ViolationCode, SpecialAmount, CostItemType, } from "../types/index.js";
 import { resolveChainId } from "../whitelists/subscription-to-chain-id.js";
 import { addressEquals } from "../helpers/address.js";
 import { validateRelatedIntentIds } from "./trade-intent-consistency.js";
-export function validateTrades(request, response, quoteMode) {
-    // CRITICAL: trade counts must match 1:1
-    if (request.trades.length !== response.trades.length) {
-        return [{
-                code: ViolationCode.TradeCountMismatch,
-                message: "response.trades.length does not match request.trades.length",
-                path: "response.trades",
-                expected: request.trades.length,
-                actual: response.trades.length,
-            }];
-    }
+import { parseIntegerString } from "../helpers/integer.js";
+import { matchTrades } from "./trade-matching.js";
+/**
+ * Per-trade role in asset-consolidation mode. Computed once for all trades at
+ * the start of validateTrades and threaded through to per-field validators.
+ *
+ * **Invariant** (enforced by `computeTradeRole`): `Regular` is emitted if and
+ * only if the request is NOT in consolidation mode (no `totalDstAmount`);
+ * `Balancing` and `NonBalancing` are emitted if and only if the request IS in
+ * consolidation mode. This means downstream validators can read consolidation-
+ * vs-regular directly from the role without taking `consolidationMode` as a
+ * separate parameter. This is made to simplify the logic in the per-field
+ * validators.
+ *
+ * - `Regular`: non-consolidation mode (no `totalDstAmount` set).
+ * - `Balancing`: in consolidation mode, the trade that closes the dst total.
+ *   Covers two API pipeline paths collapsed into one validator behavior:
+ *     1. The last response trade when the pipeline found a balancing point
+ *        (`estimatedTotalDstAmount === totalDstAmount`).
+ *     2. A non-last response trade with `mutatedWithOperatingExpense=true` —
+ *        the "previously balancing" trade from the API's opEx-overflow
+ *        recovery path. May appear at any non-last position; if overflow
+ *        recovery recursed, several such trades can coexist in the middle.
+ * - `NonBalancing`: in consolidation mode, everything else — kept trades
+ *   taken at the full upper bound, OR (when `allowPartialFill` exhausted
+ *   without reaching `totalDstAmount`) every kept trade including the last.
+ */
+var TradeRole;
+(function (TradeRole) {
+    TradeRole[TradeRole["Regular"] = 0] = "Regular";
+    TradeRole[TradeRole["Balancing"] = 1] = "Balancing";
+    TradeRole[TradeRole["NonBalancing"] = 2] = "NonBalancing";
+})(TradeRole || (TradeRole = {}));
+export function validateTrades(request, response, quoteMode, tradePairs) {
     const violations = [];
-    for (let i = 0; i < request.trades.length; i++) {
-        violations.push(...validateSingleTrade(request.trades[i], response.trades[i], i, quoteMode));
+    // CRITICAL: response cannot carry more trades than the request asked for.
+    // CRITICAL: response cannot carry fewer trades than the request, except when
+    // the request opts into asset-consolidation mode (totalDstAmount set), where
+    // the API may legitimately drop tail trades after the balancing trade.
+    const consolidationMode = request.totalDstAmount !== undefined;
+    const tooMany = response.trades.length > request.trades.length;
+    const tooFew = response.trades.length < request.trades.length && !consolidationMode;
+    if (tooMany || tooFew) {
+        violations.push({
+            code: ViolationCode.TradeCountMismatch,
+            message: "response.trades.length does not match request.trades.length",
+            path: "response.trades",
+            expected: request.trades.length,
+            actual: response.trades.length,
+        });
+    }
+    const isBalancingMode = computeIsBalancingMode(request, response);
+    const pairs = tradePairs ?? matchTrades(request.trades, response.trades, quoteMode, consolidationMode).pairs;
+    for (const pair of pairs) {
+        const isLastInResponse = pair.responseIndex === response.trades.length - 1;
+        const role = computeTradeRole(pair.responseTrade, isLastInResponse, consolidationMode, isBalancingMode);
+        violations.push(...validateSingleTrade(pair.requestTrade, pair.responseTrade, pair.requestIndex, pair.responseIndex, quoteMode, role));
     }
     // Cross-trade relatedIntentId consistency (execution mode only)
     if (!quoteMode) {
         violations.push(...validateRelatedIntentIds(response));
     }
-    violations.push(...validatePartnerCost(request, response));
+    const partnerCostTrades = consolidationMode
+        ? pairs.map(pair => pair.requestTrade)
+        : request.trades;
+    violations.push(...validatePartnerCost(response, partnerCostTrades));
     return violations;
 }
-function validateSingleTrade(reqTrade, resTrade, tradeIndex, quoteMode) {
+// True if and only if the pipeline ran the balancing-trade construction path
+// (i.e. the dst total was reached). In `allowPartialFill=true` responses where
+// the pipeline ran out of trades without reaching `totalDstAmount`, the last
+// kept trade is NOT a balancing trade — every trade is taken in full.
+function computeIsBalancingMode(request, response) {
+    if (request.totalDstAmount === undefined)
+        return false;
+    if (response.estimatedTotalDstAmount === undefined)
+        return false;
+    try {
+        return parseIntegerString(response.estimatedTotalDstAmount) === parseIntegerString(request.totalDstAmount);
+    }
+    catch {
+        // Safe skip: parse error is reported separately by `validateTotalDstAmount`;
+        // fall back to the safer assumption (non-balancing mode, strict checks).
+        return false;
+    }
+}
+function computeTradeRole(resTrade, isLastInResponse, consolidationMode, isBalancingMode) {
+    if (!consolidationMode)
+        return TradeRole.Regular;
+    if (isLastInResponse && isBalancingMode)
+        return TradeRole.Balancing;
+    // Overflow-recovery path: a non-last trade flagged with
+    // `mutatedWithOperatingExpense=true` is the previously-balancing trade
+    // that was demoted from the tail when its `srcAmount` overflowed the upper
+    // bound. Treat it like a balancing trade for validation purposes.
+    if (isBalancingMode
+        && !isLastInResponse
+        && resTrade.srcChainTokenIn.mutatedWithOperatingExpense) {
+        return TradeRole.Balancing;
+    }
+    return TradeRole.NonBalancing;
+}
+function validateSingleTrade(reqTrade, resTrade, requestIndex, responseIndex, quoteMode, role) {
     const violations = [];
-    const basePath = `response.trades[${tradeIndex}]`;
+    const basePath = `response.trades[${responseIndex}]`;
     const srcRealChainId = resolveChainId(reqTrade.srcChainId);
     const dstRealChainId = resolveChainId(reqTrade.dstChainId);
     // CRITICAL: dstChainId must be a known subscriptionId
@@ -34,12 +114,12 @@ function validateSingleTrade(reqTrade, resTrade, tradeIndex, quoteMode) {
         violations.push({
             code: ViolationCode.UnknownSubscriptionId,
             message: `dstChainId=${reqTrade.dstChainId} is not a known subscriptionId`,
-            path: `request.trades[${tradeIndex}].dstChainId`,
+            path: `request.trades[${requestIndex}].dstChainId`,
             actual: reqTrade.dstChainId,
         });
     }
     // Chain-agnostic validations (don't need resolved realChainId)
-    violations.push(...validateSrcChainTokenIn(reqTrade, resTrade, basePath), ...validateSrcChainTokenOut(reqTrade, resTrade, basePath), ...validateDstChainTokenOut(reqTrade, resTrade, basePath), ...validatePrependedOperatingExpenseCost(reqTrade, resTrade, basePath), ...validatePartnerFeeBps(reqTrade, resTrade, basePath));
+    violations.push(...validateSrcChainTokenIn(reqTrade, resTrade, basePath, role), ...validateSrcChainTokenOut(reqTrade, resTrade, basePath), ...validateDstChainTokenOut(reqTrade, resTrade, basePath, role), ...validatePrependedOperatingExpenseCost(reqTrade, resTrade, basePath, role), ...validatePartnerFeeBps(reqTrade, resTrade, basePath));
     // Safe skip: undefined srcRealChainId is already reported as UnknownSubscriptionId by groupTrades
     if (srcRealChainId !== undefined) {
         violations.push(...validateSrcTokenInAddress(reqTrade, resTrade, basePath, srcRealChainId));
@@ -59,7 +139,7 @@ function validateSingleTrade(reqTrade, resTrade, tradeIndex, quoteMode) {
 // =============================================
 // srcChainTokenIn
 // =============================================
-function validateSrcChainTokenIn(reqTrade, resTrade, basePath) {
+function validateSrcChainTokenIn(reqTrade, resTrade, basePath, role) {
     const violations = [];
     const src = resTrade.srcChainTokenIn;
     const path = `${basePath}.srcChainTokenIn`;
@@ -73,12 +153,17 @@ function validateSrcChainTokenIn(reqTrade, resTrade, basePath) {
             actual: src.chainId,
         });
     }
-    // CRITICAL: amount must match when prependOperatingExpenses is false and amount is numeric
-    violations.push(...validateSrcTokenInAmount(reqTrade, src, path));
+    // CRITICAL: amount must match when `prependOperatingExpenses` is false and
+    // amount is numeric. A balancing trade is allowed amount <= upperBound;
+    // a non-balancing trade in consolidation mode must equal upperBound
+    // regardless of `request.prependOperatingExpenses`.
+    violations.push(...validateSrcTokenInAmount(reqTrade, src, path, role));
     // CRITICAL + MEDIUM: operating expense checks
     violations.push(...validateOperatingExpense(resTrade, src, basePath));
-    // CRITICAL: mutatedWithOperatingExpense must reflect request conditions
-    violations.push(...validateMutatedWithOperatingExpense(reqTrade, src, path));
+    // CRITICAL: `mutatedWithOperatingExpense` must reflect request conditions.
+    // Skipped for the balancing trade (API freely sets it on the rebalanced
+    // trade); for non-balancing in consolidation mode forced to false.
+    violations.push(...validateMutatedWithOperatingExpense(reqTrade, src, path, role));
     // CRITICAL: USD values must be non-negative
     violations.push(...checkNonNegativeUsd(src.approximateUsdValue, `${path}.approximateUsdValue`), ...checkNonNegativeUsd(src.originApproximateUsdValue, `${path}.originApproximateUsdValue`));
     return violations;
@@ -98,18 +183,62 @@ function validateSrcTokenInAddress(reqTrade, resTrade, basePath, srcRealChainId)
     }
     return [];
 }
-function validateSrcTokenInAmount(reqTrade, src, path) {
-    // Skip when prependOperatingExpenses is true — amount includes expenses
-    if (reqTrade.prependOperatingExpenses ?? false)
-        return [];
+function validateSrcTokenInAmount(reqTrade, src, path, role) {
     // Skip for non-numeric amounts (auto, max)
     const amount = reqTrade.srcChainTokenInAmount;
     if (amount === SpecialAmount.Auto || amount === SpecialAmount.Max)
         return [];
+    // Balancing trade: API rebalances `srcAmount` down so the dst total matches
+    // exactly. It may be strictly less than the requested upper bound but
+    // never more. Covers both the last-trade case and the "previously
+    // balancing" trade from the opEx-overflow recovery path.
+    if (role === TradeRole.Balancing) {
+        return validateSrcTokenInAmountAgainstUpperBound(amount, src, path);
+    }
+    // Two roles remain (per TradeRole invariant): NonBalancing => consolidation
+    // mode, Regular => non-consolidation. In consolidation mode the API forces
+    // `prependOperatingExpenses=false` internally regardless of the request flag,
+    // so we require exact-equality even when the request had `prepend=true`. In
+    // regular mode we honor the request flag as-is.
+    const prependOperatingExpenses = role === TradeRole.NonBalancing
+        ? false
+        : (reqTrade.prependOperatingExpenses ?? false);
+    // CRITICAL: when `prependOperatingExpenses` is true the response amount
+    // must be >= request amount (operating expenses are added on top of the
+    // requested input). Exact equality is checked in the `false` branch
+    // below.
+    if (prependOperatingExpenses) {
+        try {
+            const requested = parseIntegerString(amount);
+            const actual = parseIntegerString(src.amount);
+            if (actual < requested) {
+                return [{
+                        code: ViolationCode.TradeSrcTokenInAmountBelowRequested,
+                        message: "srcChainTokenIn.amount is below requested srcChainTokenInAmount"
+                            + " (with prependOperatingExpenses=true the API must add expenses, "
+                            + "not deduct from the requested amount)",
+                        path: `${path}.amount`,
+                        expected: { min: amount },
+                        actual: src.amount,
+                    }];
+            }
+        }
+        catch (e) {
+            return [{
+                    code: ViolationCode.TradeSrcTokenInAmountBelowRequested,
+                    message: "failed to parse amounts for comparison",
+                    path: `${path}.amount`,
+                    expected: { min: amount },
+                    actual: src.amount,
+                    details: e,
+                }];
+        }
+        return [];
+    }
     // CRITICAL: srcChainTokenIn.amount must equal request srcChainTokenInAmount
     try {
-        const expected = BigInt(amount);
-        const actual = BigInt(src.amount);
+        const expected = parseIntegerString(amount);
+        const actual = parseIntegerString(src.amount);
         if (actual !== expected) {
             return [{
                     code: ViolationCode.TradeSrcTokenInAmountMismatch,
@@ -132,11 +261,39 @@ function validateSrcTokenInAmount(reqTrade, src, path) {
     }
     return [];
 }
+function validateSrcTokenInAmountAgainstUpperBound(upperBound, src, path) {
+    // CRITICAL: in asset-consolidation mode the balancing trade may be
+    // rebalanced down by the API to make the dst total match. It may be
+    // strictly less than the requested upper bound, but never more.
+    try {
+        const bound = parseIntegerString(upperBound);
+        const actual = parseIntegerString(src.amount);
+        if (actual > bound) {
+            return [{
+                    code: ViolationCode.TradeSrcTokenInAmountExceedsUpperBound,
+                    message: "srcChainTokenIn.amount exceeds requested upper bound on the balancing trade",
+                    path: `${path}.amount`,
+                    expected: { max: upperBound },
+                    actual: src.amount,
+                }];
+        }
+    }
+    catch (e) {
+        return [{
+                code: ViolationCode.TradeSrcTokenInAmountExceedsUpperBound,
+                message: "failed to parse amounts for comparison",
+                path: `${path}.amount`,
+                actual: src.amount,
+                details: e,
+            }];
+    }
+    return [];
+}
 function validateOperatingExpense(resTrade, src, basePath) {
     const expensePath = `${basePath}.srcChainTokenIn.approximateOperatingExpense`;
     let parsedExpense;
     try {
-        parsedExpense = BigInt(src.approximateOperatingExpense);
+        parsedExpense = parseIntegerString(src.approximateOperatingExpense);
     }
     catch (e) {
         return [{
@@ -184,11 +341,11 @@ function checkOperatingExpensePositive(resTrade, src, parsedExpense, basePath) {
     }
     // MEDIUM: if `prependedOperatingExpenseCost` is non-zero, expense must be > 0.
     // Skip when the field is absent — secondary trades in a group don't carry
-    // it (expenses accumulate on the primary trade); `BigInt(undefined)` would
-    // throw and produce a misleading `TradePrependedCostInvalid`.
+    // it (expenses accumulate on the primary trade); parsing an absent value
+    // would produce a misleading `TradePrependedCostInvalid`.
     if (resTrade.prependedOperatingExpenseCost !== undefined) {
         try {
-            if (BigInt(resTrade.prependedOperatingExpenseCost) !== 0n) {
+            if (parseIntegerString(resTrade.prependedOperatingExpenseCost) !== 0n) {
                 violations.push({
                     code: ViolationCode.TradeOperatingExpenseExpectedPositive,
                     message: "approximateOperatingExpense should be > 0"
@@ -210,14 +367,40 @@ function checkOperatingExpensePositive(resTrade, src, parsedExpense, basePath) {
     }
     return violations;
 }
-function validateMutatedWithOperatingExpense(reqTrade, src, path) {
+function validateMutatedWithOperatingExpense(reqTrade, src, path, role) {
     // Safe skip: in `max` mode the API forces `prependOperatingExpenses=false`
     // internally (operating expenses are already deducted from the max balance),
     // so `mutatedWithOperatingExpense` is unpredictable from the request alone.
     // Validating mutated amount is also impossible (we don't know the user's balance).
     if (reqTrade.srcChainTokenInAmount === SpecialAmount.Max)
         return [];
-    const prependExpenses = reqTrade.prependOperatingExpenses ?? false;
+    // Balancing trade: API pipeline pins the flag based on its own internal
+    // path, not the request. Two cases (both checkable):
+    //   - `request.srcChainTokenInAmount === 'auto'` → unlimited balancing →
+    //     `prependOperatingExpenses=false` → `mutatedWithOperatingExpense=false`.
+    //   - `request.srcChainTokenInAmount` is a number → scaled balancing →
+    //     `prependOperatingExpenses=true` → `mutatedWithOperatingExpense=true`.
+    if (role === TradeRole.Balancing) {
+        const expectedMutated = reqTrade.srcChainTokenInAmount !== SpecialAmount.Auto;
+        if (src.mutatedWithOperatingExpense !== expectedMutated) {
+            return [{
+                    code: ViolationCode.TradeMutatedWithOperatingExpenseMismatch,
+                    message: "srcChainTokenIn.mutatedWithOperatingExpense does not match"
+                        + " expected value for the balancing trade",
+                    path: `${path}.mutatedWithOperatingExpense`,
+                    expected: expectedMutated,
+                    actual: src.mutatedWithOperatingExpense,
+                }];
+        }
+        return [];
+    }
+    // Two roles remain (per TradeRole invariant): NonBalancing => consolidation
+    // mode, Regular => non-consolidation. In consolidation mode the API forces
+    // `prependOperatingExpenses=false` internally regardless of the request flag.
+    // In regular mode we honor the request flag as-is.
+    const prependExpenses = role === TradeRole.NonBalancing
+        ? false
+        : (reqTrade.prependOperatingExpenses ?? false);
     const isAuto = reqTrade.srcChainTokenInAmount === SpecialAmount.Auto;
     const expectedMutated = prependExpenses || isAuto;
     // CRITICAL: must reflect request conditions
@@ -251,7 +434,7 @@ function validateSrcChainTokenOut(reqTrade, resTrade, basePath) {
     }
     // CRITICAL: amount must be non-negative
     try {
-        if (BigInt(resTrade.srcChainTokenOut.amount) < 0n) {
+        if (parseIntegerString(resTrade.srcChainTokenOut.amount) < 0n) {
             return [{
                     code: ViolationCode.TradeSrcTokenOutAmountNegative,
                     message: "srcChainTokenOut.amount must be non-negative",
@@ -279,7 +462,7 @@ function validateSrcChainTokenOut(reqTrade, resTrade, basePath) {
 // =============================================
 // dstChainTokenOut
 // =============================================
-function validateDstChainTokenOut(reqTrade, resTrade, basePath) {
+function validateDstChainTokenOut(reqTrade, resTrade, basePath, role) {
     const violations = [];
     const dst = resTrade.dstChainTokenOut;
     const path = `${basePath}.dstChainTokenOut`;
@@ -294,7 +477,7 @@ function validateDstChainTokenOut(reqTrade, resTrade, basePath) {
         });
     }
     // CRITICAL: amount and withoutPartnerFee checks
-    violations.push(...validateDstTokenOutAmount(reqTrade, dst, path), ...validateWithoutPartnerFeeAmount(reqTrade, dst, path));
+    violations.push(...validateDstTokenOutAmount(reqTrade, dst, path), ...validateWithoutPartnerFeeAmount(reqTrade, resTrade, path, role));
     // CRITICAL: USD values must be non-negative
     violations.push(...checkNonNegativeUsd(dst.approximateUsdValue, `${path}.approximateUsdValue`), ...checkNonNegativeUsd(dst.recommendedApproximateUsdValue, `${path}.recommendedApproximateUsdValue`));
     // CRITICAL: maxTheoreticalApproximateUsdValue must be present — API always sets it
@@ -333,8 +516,8 @@ function validateDstTokenOutAmount(reqTrade, dst, path) {
         return [];
     // CRITICAL: amount must be >= requested dstChainTokenOutAmount
     try {
-        const requested = BigInt(reqTrade.dstChainTokenOutAmount);
-        const actual = BigInt(dst.amount);
+        const requested = parseIntegerString(reqTrade.dstChainTokenOutAmount);
+        const actual = parseIntegerString(dst.amount);
         if (actual < requested) {
             return [{
                     code: ViolationCode.TradeDstTokenOutAmountBelowRequested,
@@ -357,7 +540,8 @@ function validateDstTokenOutAmount(reqTrade, dst, path) {
     }
     return [];
 }
-function validateWithoutPartnerFeeAmount(reqTrade, dst, path) {
+function validateWithoutPartnerFeeAmount(reqTrade, resTrade, path, role) {
+    const dst = resTrade.dstChainTokenOut;
     const feePath = `${path}.withoutPartnerFeeBpsAmount`;
     // CRITICAL: field must be present — API always sets it
     if (dst.withoutPartnerFeeBpsAmount === undefined) {
@@ -370,7 +554,7 @@ function validateWithoutPartnerFeeAmount(reqTrade, dst, path) {
     }
     let withoutFee;
     try {
-        withoutFee = BigInt(dst.withoutPartnerFeeBpsAmount);
+        withoutFee = parseIntegerString(dst.withoutPartnerFeeBpsAmount);
     }
     catch (e) {
         return [{
@@ -383,7 +567,7 @@ function validateWithoutPartnerFeeAmount(reqTrade, dst, path) {
     }
     let amount;
     try {
-        amount = BigInt(dst.amount);
+        amount = parseIntegerString(dst.amount);
     }
     catch (e) {
         return [{
@@ -394,9 +578,7 @@ function validateWithoutPartnerFeeAmount(reqTrade, dst, path) {
                 details: e,
             }];
     }
-    const isExactOutputMode = reqTrade.srcChainTokenInAmount === SpecialAmount.Auto
-        || (reqTrade.dstChainTokenOutAmount !== undefined
-            && reqTrade.dstChainTokenOutAmount !== SpecialAmount.Auto);
+    const isExactOutputMode = isExactOutputTrade(reqTrade, resTrade, role);
     if (isExactOutputMode) {
         if (withoutFee < 0n) {
             return [{
@@ -432,6 +614,33 @@ function validateWithoutPartnerFeeAmount(reqTrade, dst, path) {
     }
     return [];
 }
+function isExactOutputTrade(reqTrade, resTrade, role) {
+    // Exact-output response shape means `dstChainTokenOut.amount` is pinned to a
+    // user/API target while `withoutPartnerFeeBpsAmount` can reflect the lower
+    // post-cost solver output. The API does not expose `Trade.isExactOutput`
+    // directly, so derive the shape from the request plus consolidation role.
+    return role === TradeRole.Balancing
+        || reqTrade.srcChainTokenInAmount === SpecialAmount.Auto
+        || (reqTrade.dstChainTokenOutAmount !== undefined
+            && reqTrade.dstChainTokenOutAmount !== SpecialAmount.Auto)
+        || (resTrade.srcChainTokenIn.mutatedWithOperatingExpense
+            && isMutatedWithOperatingExpenseRoleValid(reqTrade, role));
+}
+function isMutatedWithOperatingExpenseRoleValid(reqTrade, role) {
+    // Max mode is intentionally not validated because the API handles opEx
+    // against the unknown wallet balance. Do not let this unverifiable flag
+    // grant exact-output `withoutFee` semantics on its own.
+    if (reqTrade.srcChainTokenInAmount === SpecialAmount.Max)
+        return false;
+    if (role === TradeRole.Balancing) {
+        return reqTrade.srcChainTokenInAmount !== SpecialAmount.Auto;
+    }
+    const prependExpenses = role === TradeRole.NonBalancing
+        ? false
+        : (reqTrade.prependOperatingExpenses ?? false);
+    const isAuto = reqTrade.srcChainTokenInAmount === SpecialAmount.Auto;
+    return prependExpenses || isAuto;
+}
 // =============================================
 // Execution-mode address echo fields
 // =============================================
@@ -481,12 +690,35 @@ function validateAddressEcho(expected, actual, code, path, fieldName, realChainI
 // =============================================
 // prependedOperatingExpenseCost
 // =============================================
-function validatePrependedOperatingExpenseCost(reqTrade, resTrade, basePath) {
-    const prependExpenses = reqTrade.prependOperatingExpenses ?? false;
-    const isAuto = reqTrade.srcChainTokenInAmount === SpecialAmount.Auto;
+function validatePrependedOperatingExpenseCost(reqTrade, resTrade, basePath, role) {
     const isMax = reqTrade.srcChainTokenInAmount === SpecialAmount.Max;
-    // Only check: when prependOperatingExpenses is false AND not auto/max → must be zero
-    if (prependExpenses || isAuto || isMax)
+    // Skip: max mode handles operating expenses against the wallet balance,
+    // which the SDK cannot know.
+    if (isMax)
+        return [];
+    // Balancing trade: API pipeline pins the cost based on its own internal
+    // path, not the request:
+    //   - `request.srcChainTokenInAmount === 'auto'` → unlimited balancing →
+    //     `prependOperatingExpenses=false` → cost === '0' (or absent).
+    //   - `request.srcChainTokenInAmount` is a number → scaled balancing →
+    //     `prependOperatingExpenses=true` → cost > 0 (when present on primary).
+    if (role === TradeRole.Balancing) {
+        return validateBalancingTradePrependCost(reqTrade, resTrade, basePath);
+    }
+    // Two roles remain (per TradeRole invariant): NonBalancing => consolidation
+    // mode, Regular => non-consolidation. In consolidation mode the API forces
+    // `prependOperatingExpenses=false` internally regardless of the request flag.
+    // In regular mode we honor the request flag as-is.
+    const prependExpenses = role === TradeRole.NonBalancing
+        ? false
+        : (reqTrade.prependOperatingExpenses ?? false);
+    const isAuto = reqTrade.srcChainTokenInAmount === SpecialAmount.Auto;
+    // Skip when the API is allowed to mutate `prependedOperatingExpenseCost`
+    // freely:
+    //   - `prependOperatingExpenses=true` (regular mode): cost reflects the prepended amount.
+    //   - 'auto' srcChainTokenInAmount (regular mode): API forces the effective flag.
+    // In all other cases the cost must be zero — that's the only check below.
+    if (prependExpenses || isAuto)
         return [];
     // Treat absent field as "0" — the API omits it on secondary trades in a
     // group (expenses accumulate on the primary trade). For `prepend=false`
@@ -497,7 +729,7 @@ function validatePrependedOperatingExpenseCost(reqTrade, resTrade, basePath) {
     // CRITICAL: `prependedOperatingExpenseCost` must be zero
     let parsed;
     try {
-        parsed = BigInt(resTrade.prependedOperatingExpenseCost);
+        parsed = parseIntegerString(resTrade.prependedOperatingExpenseCost);
     }
     catch (error) {
         return [{
@@ -521,15 +753,85 @@ function validatePrependedOperatingExpenseCost(reqTrade, resTrade, basePath) {
     }
     return [];
 }
+function validateBalancingTradePrependCost(reqTrade, resTrade, basePath) {
+    const costPath = `${basePath}.prependedOperatingExpenseCost`;
+    const isAuto = reqTrade.srcChainTokenInAmount === SpecialAmount.Auto;
+    // Unlimited balancing (`request.srcChainTokenInAmount === 'auto'`): the API
+    // sets the Trade-level `prependOperatingExpenses=false` on the unlimited
+    // balancing trade, so the response emits `cost === '0'` (or omits the field).
+    if (isAuto) {
+        if (resTrade.prependedOperatingExpenseCost === undefined)
+            return [];
+        let parsed;
+        try {
+            parsed = parseIntegerString(resTrade.prependedOperatingExpenseCost);
+        }
+        catch (error) {
+            return [{
+                    code: ViolationCode.TradePrependedCostInvalid,
+                    message: "prependedOperatingExpenseCost is not a valid number",
+                    path: costPath,
+                    actual: resTrade.prependedOperatingExpenseCost,
+                    details: error,
+                }];
+        }
+        if (parsed !== 0n) {
+            return [{
+                    code: ViolationCode.TradePrependedCostNotZero,
+                    message: "prependedOperatingExpenseCost must be zero on the unlimited"
+                        + " balancing trade (srcChainTokenInAmount='auto')",
+                    path: costPath,
+                    expected: "0",
+                    actual: resTrade.prependedOperatingExpenseCost,
+                }];
+        }
+        return [];
+    }
+    // Scaled balancing (`request.srcChainTokenInAmount` is a number): the API
+    // sets the Trade-level `prependOperatingExpenses=true`, so the response
+    // emits `cost > 0` on the primary trade (or omits the field for secondaries
+    // in a group — we cannot distinguish here without group context, so omit
+    // means "skip"; the corresponding primary in the same group will report).
+    if (resTrade.prependedOperatingExpenseCost === undefined)
+        return [];
+    let parsed;
+    try {
+        parsed = parseIntegerString(resTrade.prependedOperatingExpenseCost);
+    }
+    catch (error) {
+        return [{
+                code: ViolationCode.TradePrependedCostInvalid,
+                message: "prependedOperatingExpenseCost is not a valid number",
+                path: costPath,
+                actual: resTrade.prependedOperatingExpenseCost,
+                details: error,
+            }];
+    }
+    if (parsed <= 0n) {
+        return [{
+                code: ViolationCode.TradePrependedCostNotZero,
+                message: "prependedOperatingExpenseCost must be > 0 on the scaled"
+                    + " balancing trade (request.srcChainTokenInAmount is a number)",
+                path: costPath,
+                actual: resTrade.prependedOperatingExpenseCost,
+            }];
+    }
+    return [];
+}
 // =============================================
 // partnerFeeBps
 // =============================================
-// API aggregates per-trade partner fees into a single bundle-wide cost item:
-// `amount` is the sum across trades, `feeBps` is taken from the first per-trade
-// entry — which is always trade index 0 since the API preserves request order.
-function validatePartnerCost(request, response) {
+// API aggregates per-trade partner fees into a single bundle-wide cost item.
+// `amount` is the sum across final response trades. `feeBps` is taken from the
+// first final per-trade entry, so consolidation mode must ignore skipped
+// request trades when choosing the expected value.
+function validatePartnerCost(response, requestTradesForCost) {
     const partnerCosts = response.bundleCosts.filter(c => c.type === CostItemType.PARTNER_COST);
+    const requestedFees = requestTradesForCost.map(t => t.partnerFeeBps ?? 0);
+    const anyNonZero = requestedFees.some(b => b > 0);
     if (partnerCosts.length === 0) {
+        if (!anyNonZero)
+            return [];
         return [{
                 code: ViolationCode.PartnerCostMissing,
                 message: "bundleCosts[PARTNER_COST] entry is missing",
@@ -541,7 +843,7 @@ function validatePartnerCost(request, response) {
     const path = `response.bundleCosts[PARTNER_COST]`;
     let amount;
     try {
-        amount = BigInt(partnerCost.amount);
+        amount = parseIntegerString(partnerCost.amount);
     }
     catch (error) {
         return [{
@@ -569,8 +871,6 @@ function validatePartnerCost(request, response) {
             actual: feeBps,
         });
     }
-    const requestedFees = request.trades.map(t => t.partnerFeeBps ?? 0);
-    const anyNonZero = requestedFees.some(b => b > 0);
     // CRITICAL: when no trade has a partner fee, the aggregated amount must be zero.
     if (!anyNonZero && amount !== 0n) {
         violations.push({
@@ -581,22 +881,16 @@ function validatePartnerCost(request, response) {
             actual: partnerCost.amount,
         });
     }
-    // CRITICAL: when at least one trade has a partner fee, the aggregated amount must be > 0.
-    if (anyNonZero && amount === 0n) {
-        violations.push({
-            code: ViolationCode.PartnerCostAmountUnexpectedlyZero,
-            message: "PARTNER_COST.amount must be > 0 when at least one trade has partnerFeeBps > 0",
-            path: `${path}.amount`,
-            actual: partnerCost.amount,
-        });
-    }
-    // CRITICAL: feeBps must echo request.trades[0].partnerFeeBps (or 0 when omitted).
-    if (feeBps !== undefined && request.trades.length > 0) {
+    // NO NEED: amount may round to zero for very small selected trades even when
+    // partnerFeeBps is non-zero, so a strict positive-amount check would create
+    // false positives. We still validate amount format and the no-fee non-zero case.
+    // CRITICAL: feeBps must echo the first selected request trade's partnerFeeBps (or 0 when omitted).
+    if (feeBps !== undefined && requestTradesForCost.length > 0) {
         const expected = requestedFees[0];
         if (feeBps !== expected) {
             violations.push({
                 code: ViolationCode.PartnerCostFeeBpsMismatch,
-                message: "PARTNER_COST.feeBps does not match request.trades[0].partnerFeeBps",
+                message: "PARTNER_COST.feeBps does not match the first selected trade partnerFeeBps",
                 path: `${path}.feeBps`,
                 expected,
                 actual: feeBps,