otto-intel-mcp 0.1.0

package/dist/lifi-bridge-assertions.js

@@ -0,0 +1,303 @@
+import { decodeAbiParameters, encodeAbiParameters, getAddress, parseAbiParameters, } from 'viem';
+import { attributedFeeAmount, isEnumeratedCctpBridgeRoute, LIFI_DIAMOND_ADDRESS, isReviewedLiFiFeeForwarder, reviewedLiFiFeeForwarders, unreviewedFeeForwarderMessage, LIFI_INTEGRATOR, LIFI_POLYMER_BRIDGE_TOOL, } from './execution-config.js';
+import { isExecutionRefusal, refuse } from './execution-errors.js';
+import { assertFeeDistributionBody, FORWARD_ERC20_FEES_SELECTOR, } from './lifi-fee-assertions.js';
+/** `ILiFi.BridgeData` — the universal first parameter of every LI.FI bridge function. */
+const BRIDGE_DATA_TUPLE = '(bytes32 transactionId, string bridge, string integrator, address referrer, address sendingAssetId, address receiver, uint256 minAmount, uint256 destinationChainId, bool hasSourceSwaps, bool hasDestinationCall)';
+/** `LibSwap.SwapData` — the source-swap legs LI.FI `transferFrom`s the signer for. */
+const SWAP_DATA_TUPLE = '(address callTo, address approveTo, address sendingAssetId, address receivingAssetId, uint256 fromAmount, bytes callData, bool requiresDeposit)';
+/**
+ * The live `PolymerData` tuple. Captured 2026-08-17 from li.quest and confirmed by selector
+ * derivation: keccak of
+ * `swapAndStartBridgeTokensViaPolymerCCTP(BridgeData,SwapData[],(uint256,uint256,bytes32,bytes32,uint32,address,bytes))`
+ * is exactly 0x17917a4e, the selector the live route emits.
+ *
+ * 🔴 This is a SEVEN-field tuple. The dApp's owner-op bridge validator pins the older FIVE-field
+ * shape (selector 0x780c82ab), which the live LI.FI deployment no longer emits — so the invariants
+ * below are re-specified here rather than inherited, and two fields have no counterpart there:
+ *  - `f5` (address) carries the SENDER — `action.fromAddress`, the source-chain refund role — not
+ *    the destination receiver. Established by capturing a live quote with `fromAddress != toAddress`
+ *    (2026-08-17, Base->Arbitrum): `BridgeData.receiver` moved to the declared destination while
+ *    `f5` stayed on the sender. Captures where the two roles share one address cannot tell the
+ *    fields apart, so binding `f5` to the destination recipient — as this validator first did —
+ *    refuses every valid request that bridges to any address other than the sender's own. It is
+ *    bound to the sender, which is the role the live rail actually populates.
+ *  - `f6` (bytes) is an unbounded arbitrary-payload field, bound empty fail-closed.
+ *
+ * `f2`/`f3` (bytes32) are zero on every live capture, including the differing-recipient one, so
+ * they are pinned to zero rather than being allowed to carry an address-shaped value nothing on
+ * the live rail emits.
+ */
+const POLYMER_DATA_TUPLE = '(uint256 f0, uint256 f1, bytes32 f2, bytes32 f3, uint32 f4, address f5, bytes f6)';
+const LIFI_POLYMER_PARAMS = parseAbiParameters(`${BRIDGE_DATA_TUPLE} _bridgeData, ${SWAP_DATA_TUPLE}[] _swapData, ${POLYMER_DATA_TUPLE} _polymerData`);
+/** The enumerated v1 bridge facet. Anything else — eco, stargate, a plain no-swap layout, or a
+ *  post-redeploy selector — is outside the reviewed set and refused by name. */
+export const LIFI_BRIDGE_SELECTORS = Object.freeze({
+    polymerCctp: '0x17917a4e',
+});
+/** CCTP fee/finality controls pinned to the verified permissionless route shape. */
+const POLYMER_ZERO_FIELD = 0n;
+const POLYMER_FINALITY_THRESHOLD = 2000;
+const ZERO_BYTES32 = `0x${'00'.repeat(32)}`;
+const ZERO_ADDRESS = getAddress('0x0000000000000000000000000000000000000000');
+function quoteRefuse(message) {
+    return refuse('LIFI_QUOTE_INVALID', message);
+}
+function routeRefuse(message) {
+    return refuse('UNSUPPORTED_LIFI_ROUTE', message);
+}
+function asAddress(value, field) {
+    if (typeof value !== 'string')
+        quoteRefuse(`${field} is missing`);
+    try {
+        return getAddress(value);
+    }
+    catch {
+        return quoteRefuse(`${field} is not a valid EVM address`);
+    }
+}
+function positiveBigInt(value, field) {
+    if (typeof value !== 'string' || !/^[1-9]\d*$/.test(value)) {
+        return quoteRefuse(`${field} must be a positive decimal integer`);
+    }
+    return BigInt(value);
+}
+function transactionData(value) {
+    if (typeof value !== 'string' || !/^0x(?:[0-9a-fA-F]{2}){4,}$/.test(value)) {
+        return quoteRefuse('transaction calldata is missing or malformed');
+    }
+    return value;
+}
+/**
+ * Decode the reviewed PolymerCCTP calldata. The selector is checked FIRST, so only the one exact
+ * reviewed layout is ever decoded, and the decoded arguments are re-encoded and compared so a
+ * non-canonical encoding or trailing bytes cannot smuggle a second interpretation past the asserts.
+ */
+function decodeBridge(data) {
+    const selector = data.slice(0, 10).toLowerCase();
+    if (selector !== LIFI_BRIDGE_SELECTORS.polymerCctp) {
+        return routeRefuse(`LI.FI selector ${selector} is not the reviewed PolymerCCTP facet of the v1 bridge route set`);
+    }
+    const args = `0x${data.slice(10)}`;
+    try {
+        const decoded = decodeAbiParameters(LIFI_POLYMER_PARAMS, args);
+        if (encodeAbiParameters(LIFI_POLYMER_PARAMS, decoded).toLowerCase() !== args.toLowerCase()) {
+            quoteRefuse('bridge calldata is non-canonical or carries trailing bytes');
+        }
+        const [bridgeData, legs, polymerData] = decoded;
+        return { bridgeData, legs, polymerData };
+    }
+    catch (error) {
+        if (isExecutionRefusal(error))
+            throw error;
+        return quoteRefuse('bridge calldata could not be decoded as the reviewed PolymerCCTP facet');
+    }
+}
+function assertQuoteBinding(input) {
+    const { action, estimate, transactionRequest } = input.quote;
+    if (action.fromChainId !== input.fromChainId || action.toChainId !== input.toChainId) {
+        quoteRefuse('LI.FI quote is not bound to the requested chain pair');
+    }
+    if (action.fromAmount !== input.fromAmount.toString()) {
+        quoteRefuse('LI.FI quote input amount does not match the intent');
+    }
+    if (asAddress(action.fromToken.address, 'quote input token') !== input.fromToken ||
+        asAddress(action.toToken.address, 'quote output token') !== input.toToken) {
+        quoteRefuse('LI.FI quote token pair does not match the intent');
+    }
+    if (asAddress(action.fromAddress, 'quote sender') !== getAddress(input.profile.address)) {
+        return refuse('ACCOUNT_BINDING_MISMATCH', 'LI.FI quote sender is not the bound account');
+    }
+    if (asAddress(action.toAddress, 'quote receiver') !== input.destinationRecipient) {
+        return refuse('ACCOUNT_BINDING_MISMATCH', 'LI.FI quote receiver is not the declared destination recipient');
+    }
+    if (Math.round(action.slippage * 10_000) !== input.maxSlippageBps) {
+        quoteRefuse('LI.FI quote slippage does not match the requested bound');
+    }
+    const approvalSpender = asAddress(estimate.approvalAddress, 'LI.FI approval target');
+    const transactionTarget = asAddress(transactionRequest.to, 'LI.FI transaction target');
+    if (approvalSpender !== LIFI_DIAMOND_ADDRESS || transactionTarget !== LIFI_DIAMOND_ADDRESS) {
+        quoteRefuse('LI.FI approval or transaction target is not the reviewed Diamond');
+    }
+    if (transactionRequest.from !== undefined &&
+        asAddress(transactionRequest.from, 'LI.FI transaction sender') !==
+            getAddress(input.profile.address)) {
+        return refuse('ACCOUNT_BINDING_MISMATCH', 'LI.FI transaction sender is not the bound account');
+    }
+    let transactionValue;
+    try {
+        transactionValue = BigInt(transactionRequest.value);
+    }
+    catch {
+        return quoteRefuse('LI.FI transaction value is invalid');
+    }
+    if (transactionValue !== 0n) {
+        quoteRefuse('ERC20-input LI.FI bridge unexpectedly transfers native value');
+    }
+    return { approvalSpender, transactionTarget, data: transactionData(transactionRequest.data) };
+}
+/**
+ * Decode the constructed bridge calldata and assert every fund-safety bind, fail-closed.
+ *
+ * The destination binds matter more here than on a same-chain swap: a wrong destination recipient
+ * is an irreversible cross-chain loss, and the source-chain calldata is the last place it is
+ * checkable. CCTP burns the source USDC and mints canonical USDC to `BridgeData.receiver` on the
+ * destination, so the destination asset is same-token by construction once the facet and the
+ * enumerated route are pinned — that, plus every recipient-shaped field being bound, is what makes
+ * the destination side assertable from source calldata alone.
+ */
+export function decodeAndAssertLiFiBridge(input) {
+    if (input.profile.kind !== 'eoa' && input.profile.kind !== 'safe') {
+        return refuse('UNSUPPORTED_ACCOUNT_PROFILE', 'only EOA and Safe account profiles are supported');
+    }
+    if (input.profile.chainId !== input.fromChainId) {
+        return refuse('ACCOUNT_BINDING_MISMATCH', 'account profile chain does not match the source chain');
+    }
+    if (!isEnumeratedCctpBridgeRoute(input.fromChainId, input.toChainId, input.fromToken, input.toToken)) {
+        return routeRefuse(`route ${input.fromChainId}:${input.fromToken} -> ${input.toChainId}:${input.toToken} is outside the enumerated v1 PolymerCCTP USDC route set`);
+    }
+    if (!reviewedLiFiFeeForwarders(input.fromChainId)) {
+        return routeRefuse('source chain is outside the reviewed LI.FI fee-forwarder set');
+    }
+    const boundQuote = assertQuoteBinding(input);
+    const { bridgeData, legs, polymerData } = decodeBridge(boundQuote.data);
+    // --- attribution -------------------------------------------------------------------------
+    if (bridgeData.integrator !== LIFI_INTEGRATOR) {
+        refuse('ATTRIBUTION_MISSING', 'bridge calldata does not carry the exact Otto integrator');
+    }
+    if (getAddress(bridgeData.referrer) !== ZERO_ADDRESS) {
+        refuse('ATTRIBUTION_MISSING', 'bridge calldata carries a third-party referrer');
+    }
+    if (bridgeData.bridge !== LIFI_POLYMER_BRIDGE_TOOL) {
+        routeRefuse(`bridge calldata names tool ${bridgeData.bridge}, not the reviewed PolymerCCTP tool`);
+    }
+    // --- destination binds -------------------------------------------------------------------
+    if (getAddress(bridgeData.receiver) !== input.destinationRecipient) {
+        refuse('ACCOUNT_BINDING_MISMATCH', 'bridge calldata receiver is not the declared destination recipient');
+    }
+    if (bridgeData.destinationChainId !== BigInt(input.toChainId)) {
+        quoteRefuse('bridge calldata destination chain does not match the intent');
+    }
+    if (bridgeData.hasDestinationCall) {
+        quoteRefuse('bridge calldata declares a destination call, which the v1 route set excludes');
+    }
+    if (!bridgeData.hasSourceSwaps) {
+        quoteRefuse('bridge calldata declares no source swaps, which the reviewed fee layout requires');
+    }
+    if (getAddress(bridgeData.sendingAssetId) !== input.fromToken) {
+        quoteRefuse('bridge calldata sending asset does not match the intent input token');
+    }
+    // --- over-spend / foreign-token bind -----------------------------------------------------
+    // LI.FI pulls every `requiresDeposit` leg from the signer, not `minAmount`. Binding the whole
+    // leg set (not just the first leg, and not just the summed amount) is what closes the class
+    // where an extra or split leg carries foreign calldata or masks additional spend.
+    if (legs.length !== 1) {
+        quoteRefuse('bridge calldata must carry exactly one reviewed fee-collection leg');
+    }
+    const leg = legs[0];
+    if (!leg)
+        quoteRefuse('bridge calldata has no source-swap leg');
+    // The drift alarm: an unreviewed collector is refused BY ADDRESS (see execution-config.ts).
+    if (!isReviewedLiFiFeeForwarder(input.fromChainId, leg.callTo) ||
+        !isReviewedLiFiFeeForwarder(input.fromChainId, leg.approveTo) ||
+        getAddress(leg.callTo) !== getAddress(leg.approveTo)) {
+        refuse('ATTRIBUTION_MISSING', unreviewedFeeForwarderMessage(input.fromChainId, leg.callTo, leg.approveTo));
+    }
+    if (!leg.requiresDeposit ||
+        leg.callData.slice(0, 10).toLowerCase() !== FORWARD_ERC20_FEES_SELECTOR ||
+        getAddress(leg.sendingAssetId) !== input.fromToken ||
+        getAddress(leg.receivingAssetId) !== input.fromToken ||
+        leg.fromAmount !== input.fromAmount) {
+        refuse('ATTRIBUTION_MISSING', 'bridge fee-collection leg is not bound to the reviewed forwarder, input token, and exact amount');
+    }
+    assertFeeDistributionBody({
+        callData: leg.callData,
+        expectedToken: input.fromToken,
+        grossAmount: input.fromAmount,
+        config: input.config,
+    });
+    // --- PolymerData: every recipient-shaped field bound, every control pinned ----------------
+    if (polymerData.f0 !== POLYMER_ZERO_FIELD ||
+        polymerData.f1 !== POLYMER_ZERO_FIELD ||
+        polymerData.f4 !== POLYMER_FINALITY_THRESHOLD) {
+        quoteRefuse('bridge calldata PolymerData controls are outside the reviewed pinned shape');
+    }
+    // f2/f3 are zero on every live capture of this facet, differing-recipient ones included. An
+    // address-shaped value here would be an unreviewed destination-caller / hook binding, so they
+    // are pinned to zero rather than being allowed to carry a value the live rail never emits.
+    for (const field of [polymerData.f2, polymerData.f3]) {
+        if (field.toLowerCase() !== ZERO_BYTES32) {
+            refuse('ACCOUNT_BINDING_MISMATCH', 'bridge calldata PolymerData carries a non-empty recipient-shaped control field');
+        }
+    }
+    // f5 is the SENDER / source-chain refund role, not the destination receiver — see the tuple
+    // comment above. Binding it to the sender is what the live rail actually emits; binding it to
+    // the destination recipient instead would refuse every bridge to a different address, and
+    // leaving it free would make it a refund redirect. The zero address is NOT accepted: a zero
+    // refund target burns anything the source leg returns.
+    if (getAddress(polymerData.f5) !== getAddress(input.profile.address)) {
+        refuse('ACCOUNT_BINDING_MISMATCH', 'bridge calldata PolymerData refund address is not the bound sender account');
+    }
+    // f6 is an unbounded arbitrary-payload field with no reviewed use; bound empty fail-closed.
+    if (polymerData.f6 !== '0x') {
+        quoteRefuse('bridge calldata PolymerData carries an unreviewed arbitrary payload');
+    }
+    // --- destination value floor -------------------------------------------------------------
+    const quotedOutput = positiveBigInt(input.quote.estimate.toAmount, 'LI.FI quoted output');
+    const quotedMinimum = positiveBigInt(input.quote.estimate.toAmountMin, 'LI.FI quoted minimum output');
+    if (bridgeData.minAmount !== quotedMinimum) {
+        quoteRefuse('bridge calldata minimum output does not match the quoted minimum');
+    }
+    const slippageFloor = (quotedOutput * BigInt(10_000 - input.maxSlippageBps)) / 10000n;
+    if (bridgeData.minAmount < slippageFloor) {
+        quoteRefuse('bridge calldata minimum output is inconsistent with the slippage bound');
+    }
+    // Independent of anything the quote asserts about itself: CCTP mints 1:1, so the amount reaching
+    // the destination cannot be less than the gross minus the configured aggregate fee cap. This
+    // floor is derived only from the caller's own amount and Otto's config, so a manipulated
+    // toAmount/toAmountMin pair cannot shrink what actually arrives.
+    const aggregateFeeCap = attributedFeeAmount(input.fromAmount, input.config.lifiAggregateFeeCap);
+    if (bridgeData.minAmount < input.fromAmount - aggregateFeeCap) {
+        // Same class as the fee-body cap, reached by a different route: the fee legs were inside the
+        // cap but the amount actually reaching the destination is not. A CCTP relay fee or a new
+        // finality tier lands here rather than in the fee body, so it carries the same distinguishable
+        // code — the total take exceeded the reviewed cap. It is NOT an attribution defect: Otto's fee
+        // was already asserted exact above.
+        refuse('LIFI_FEE_CAP_EXCEEDED', `bridge destination amount ${bridgeData.minAmount} is below the gross ${input.fromAmount} minus the configured aggregate fee cap ${aggregateFeeCap}`);
+    }
+    if (bridgeData.minAmount > input.fromAmount) {
+        quoteRefuse('bridge destination amount exceeds the gross input amount');
+    }
+    if (input.minAmountOut !== undefined && bridgeData.minAmount < input.minAmountOut) {
+        quoteRefuse('bridge destination amount is below the caller constraint');
+    }
+    return Object.freeze({
+        approvalSpender: boundQuote.approvalSpender,
+        transaction: Object.freeze({
+            to: boundQuote.transactionTarget,
+            value: '0',
+            data: boundQuote.data,
+        }),
+        destinationMinAmount: bridgeData.minAmount,
+        assertions: Object.freeze([
+            Object.freeze({ id: 'lifi_bridge_facet_reviewed', result: 'passed' }),
+            Object.freeze({ id: 'lifi_bridge_route_enumerated', result: 'passed' }),
+            Object.freeze({ id: 'lifi_integrator_exact', result: 'passed' }),
+            Object.freeze({ id: 'lifi_bridge_referrer_unset', result: 'passed' }),
+            Object.freeze({ id: 'lifi_fee_recipient_exact', result: 'passed' }),
+            Object.freeze({ id: 'lifi_fee_amount_exact', result: 'passed' }),
+            Object.freeze({ id: 'lifi_fee_recipient_set_versioned', result: 'passed' }),
+            Object.freeze({ id: 'lifi_fee_aggregate_cap', result: 'passed' }),
+            Object.freeze({ id: 'lifi_bridge_receiver_bound', result: 'passed' }),
+            Object.freeze({ id: 'lifi_bridge_dest_chain_exact', result: 'passed' }),
+            Object.freeze({ id: 'lifi_bridge_no_destination_call', result: 'passed' }),
+            Object.freeze({ id: 'lifi_bridge_same_token_bound', result: 'passed' }),
+            Object.freeze({ id: 'lifi_bridge_deposit_legs_exact', result: 'passed' }),
+            Object.freeze({ id: 'lifi_bridge_polymer_fields_pinned', result: 'passed' }),
+            Object.freeze({ id: 'lifi_bridge_refund_address_bound', result: 'passed' }),
+            Object.freeze({ id: 'lifi_bridge_dest_value_floor', result: 'passed' }),
+            Object.freeze({ id: 'lifi_bridge_targets_value_bound', result: 'passed' }),
+        ]),
+    });
+}
+//# sourceMappingURL=lifi-bridge-assertions.js.map

package/dist/lifi-execution-client.d.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import type { ExecutionServiceConfig } from './execution-config.js';
+export declare const LIFI_QUOTE_SCHEMA: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    tool: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodString>;
+    action: z.ZodObject<{
+        fromToken: z.ZodObject<{
+            address: z.ZodString;
+        }, z.core.$loose>;
+        fromAmount: z.ZodString;
+        toToken: z.ZodObject<{
+            address: z.ZodString;
+        }, z.core.$loose>;
+        fromChainId: z.ZodNumber;
+        toChainId: z.ZodNumber;
+        slippage: z.ZodNumber;
+        fromAddress: z.ZodString;
+        toAddress: z.ZodString;
+    }, z.core.$loose>;
+    estimate: z.ZodObject<{
+        approvalAddress: z.ZodString;
+        toAmount: z.ZodString;
+        toAmountMin: z.ZodString;
+    }, z.core.$loose>;
+    transactionRequest: z.ZodObject<{
+        to: z.ZodString;
+        data: z.ZodString;
+        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        from: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+}, z.core.$loose>;
+export type LiFiQuote = z.infer<typeof LIFI_QUOTE_SCHEMA>;
+export interface SameChainSwapQuoteRequest {
+    readonly chainId: number;
+    readonly fromToken: string;
+    readonly toToken: string;
+    readonly fromAmount: string;
+    readonly sender: string;
+    readonly receiver: string;
+    readonly maxSlippageBps: number;
+}
+export interface CrossChainBridgeQuoteRequest {
+    readonly fromChainId: number;
+    readonly toChainId: number;
+    readonly fromToken: string;
+    readonly toToken: string;
+    readonly fromAmount: string;
+    readonly sender: string;
+    readonly receiver: string;
+    readonly maxSlippageBps: number;
+}
+export interface LiFiQuoteClient {
+    getSameChainSwapQuote(request: SameChainSwapQuoteRequest, signal?: AbortSignal): Promise<LiFiQuote>;
+    getCrossChainBridgeQuote(request: CrossChainBridgeQuoteRequest, signal?: AbortSignal): Promise<LiFiQuote>;
+}
+export declare function slippageBpsToDecimal(bps: number): string;
+/** Semantic request fields first; Otto-owned attribution is appended last and has no caller seam. */
+export declare function buildLiFiQuoteUrl(request: SameChainSwapQuoteRequest, config: Pick<ExecutionServiceConfig, 'lifiBaseUrl' | 'lifiFee'>): URL;
+/**
+ * Semantic request fields first, then the bridge-tool pin, then Otto attribution appended last.
+ * `allowBridges` is pinned to the one reviewed facet so an enumerated route cannot silently come
+ * back on an unreviewed bridge (eco, stargate, across …) that this constructor would then refuse —
+ * pinning it keeps a supported route live rather than making liveness depend on LI.FI's routing.
+ */
+export declare function buildLiFiBridgeQuoteUrl(request: CrossChainBridgeQuoteRequest, config: Pick<ExecutionServiceConfig, 'lifiBaseUrl' | 'lifiFee'>): URL;
+export declare class RestLiFiQuoteClient implements LiFiQuoteClient {
+    private readonly config;
+    private readonly fetchImpl;
+    constructor(config: ExecutionServiceConfig, fetchImpl?: typeof fetch);
+    getSameChainSwapQuote(request: SameChainSwapQuoteRequest, callerSignal?: AbortSignal): Promise<LiFiQuote>;
+    getCrossChainBridgeQuote(request: CrossChainBridgeQuoteRequest, callerSignal?: AbortSignal): Promise<LiFiQuote>;
+    private fetchQuote;
+}

package/dist/lifi-execution-client.js

@@ -0,0 +1,165 @@
+import { z } from 'zod';
+import { LIFI_INTEGRATOR, LIFI_POLYMER_BRIDGE_TOOL } from './execution-config.js';
+import { isExecutionRefusal, refuse } from './execution-errors.js';
+const LIFI_TOKEN_SCHEMA = z
+    .object({
+    address: z.string(),
+})
+    .passthrough();
+const LIFI_ACTION_SCHEMA = z
+    .object({
+    fromToken: LIFI_TOKEN_SCHEMA,
+    fromAmount: z.string(),
+    toToken: LIFI_TOKEN_SCHEMA,
+    fromChainId: z.number(),
+    toChainId: z.number(),
+    slippage: z.number(),
+    fromAddress: z.string(),
+    toAddress: z.string(),
+})
+    .passthrough();
+const LIFI_ESTIMATE_SCHEMA = z
+    .object({
+    approvalAddress: z.string(),
+    toAmount: z.string(),
+    toAmountMin: z.string(),
+})
+    .passthrough();
+const LIFI_TRANSACTION_REQUEST_SCHEMA = z
+    .object({
+    to: z.string(),
+    data: z.string(),
+    value: z.union([z.string(), z.number()]),
+    from: z.string().optional(),
+})
+    .passthrough();
+export const LIFI_QUOTE_SCHEMA = z
+    .object({
+    id: z.string().optional(),
+    tool: z.string().optional(),
+    type: z.string().optional(),
+    action: LIFI_ACTION_SCHEMA,
+    estimate: LIFI_ESTIMATE_SCHEMA,
+    transactionRequest: LIFI_TRANSACTION_REQUEST_SCHEMA,
+})
+    .passthrough();
+export function slippageBpsToDecimal(bps) {
+    if (!Number.isSafeInteger(bps) || bps <= 0 || bps >= 10_000) {
+        throw new Error('slippage bps must be an integer in [1, 9999]');
+    }
+    const fractional = bps.toString().padStart(4, '0').replace(/0+$/, '');
+    return `0.${fractional}`;
+}
+/** Semantic request fields first; Otto-owned attribution is appended last and has no caller seam. */
+export function buildLiFiQuoteUrl(request, config) {
+    const url = new URL(`${config.lifiBaseUrl}/quote`);
+    const semanticFields = [
+        ['fromChain', String(request.chainId)],
+        ['toChain', String(request.chainId)],
+        ['fromToken', request.fromToken],
+        ['toToken', request.toToken],
+        ['fromAmount', request.fromAmount],
+        ['fromAddress', request.sender],
+        ['toAddress', request.receiver],
+        ['slippage', slippageBpsToDecimal(request.maxSlippageBps)],
+    ];
+    for (const [name, value] of semanticFields)
+        url.searchParams.append(name, value);
+    url.searchParams.append('integrator', LIFI_INTEGRATOR);
+    url.searchParams.append('fee', config.lifiFee.decimal);
+    return url;
+}
+/**
+ * Semantic request fields first, then the bridge-tool pin, then Otto attribution appended last.
+ * `allowBridges` is pinned to the one reviewed facet so an enumerated route cannot silently come
+ * back on an unreviewed bridge (eco, stargate, across …) that this constructor would then refuse —
+ * pinning it keeps a supported route live rather than making liveness depend on LI.FI's routing.
+ */
+export function buildLiFiBridgeQuoteUrl(request, config) {
+    const url = new URL(`${config.lifiBaseUrl}/quote`);
+    const semanticFields = [
+        ['fromChain', String(request.fromChainId)],
+        ['toChain', String(request.toChainId)],
+        ['fromToken', request.fromToken],
+        ['toToken', request.toToken],
+        ['fromAmount', request.fromAmount],
+        ['fromAddress', request.sender],
+        ['toAddress', request.receiver],
+        ['slippage', slippageBpsToDecimal(request.maxSlippageBps)],
+        ['allowBridges', LIFI_POLYMER_BRIDGE_TOOL],
+    ];
+    for (const [name, value] of semanticFields)
+        url.searchParams.append(name, value);
+    url.searchParams.append('integrator', LIFI_INTEGRATOR);
+    url.searchParams.append('fee', config.lifiFee.decimal);
+    return url;
+}
+function boundedSignal(callerSignal, timeoutMs) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(new Error('LI.FI quote timeout')), timeoutMs);
+    const onAbort = () => controller.abort(callerSignal?.reason);
+    if (callerSignal?.aborted)
+        onAbort();
+    else
+        callerSignal?.addEventListener('abort', onAbort, { once: true });
+    return {
+        signal: controller.signal,
+        cleanup: () => {
+            clearTimeout(timeout);
+            callerSignal?.removeEventListener('abort', onAbort);
+        },
+    };
+}
+export class RestLiFiQuoteClient {
+    config;
+    fetchImpl;
+    constructor(config, fetchImpl = fetch) {
+        this.config = config;
+        this.fetchImpl = fetchImpl;
+    }
+    async getSameChainSwapQuote(request, callerSignal) {
+        return this.fetchQuote(buildLiFiQuoteUrl(request, this.config), callerSignal);
+    }
+    async getCrossChainBridgeQuote(request, callerSignal) {
+        return this.fetchQuote(buildLiFiBridgeQuoteUrl(request, this.config), callerSignal);
+    }
+    async fetchQuote(requestUrl, callerSignal) {
+        const abort = boundedSignal(callerSignal, this.config.lifiTimeoutMs);
+        try {
+            const response = await this.fetchImpl(requestUrl, {
+                method: 'GET',
+                headers: {
+                    Accept: 'application/json',
+                    // Operational quote-provider authentication only. It never enters an intent schema,
+                    // execution envelope, error, caller-wallet path, or transaction-signing path.
+                    ...(this.config.lifiApiKey ? { 'x-lifi-api-key': this.config.lifiApiKey } : {}),
+                },
+                signal: abort.signal,
+            });
+            if (!response.ok) {
+                refuse('LIFI_QUOTE_FAILED', `LI.FI quote request failed with HTTP ${response.status}`);
+            }
+            let body;
+            try {
+                body = await response.json();
+            }
+            catch {
+                refuse('LIFI_QUOTE_FAILED', 'LI.FI quote response was not valid JSON');
+            }
+            const parsed = LIFI_QUOTE_SCHEMA.safeParse(body);
+            if (!parsed.success) {
+                refuse('LIFI_QUOTE_INVALID', 'LI.FI quote response is missing required fields');
+            }
+            return parsed.data;
+        }
+        catch (error) {
+            if (isExecutionRefusal(error))
+                throw error;
+            refuse('LIFI_QUOTE_FAILED', 'LI.FI quote request failed');
+        }
+        finally {
+            abort.cleanup();
+        }
+    }
+}
+//# sourceMappingURL=lifi-execution-client.js.map

package/dist/lifi-fee-assertions.d.ts

@@ -0,0 +1,32 @@
+import { type Address, type Hex } from 'viem';
+import { type ExecutionServiceConfig } from './execution-config.js';
+/** `FeeCollector.collectTokenFees(...)` — the only calldata a reviewed fee-forwarding leg may carry. */
+export declare const FORWARD_ERC20_FEES_SELECTOR: Hex;
+export interface FeeDistribution {
+    readonly recipient: Address;
+    readonly amount: bigint;
+}
+/**
+ * Decode a `collectTokenFees` body. Shared by the same-chain swap and cross-chain bridge
+ * constructors so the fund-critical attribution shape has exactly one implementation: two copies
+ * of this check would drift, and a drifted copy is an unattributed or over-charged payload.
+ */
+export declare function decodeFeeDistributions(callData: Hex): {
+    readonly token: Address;
+    readonly distributions: readonly FeeDistribution[];
+};
+export interface FeeDistributionAssertionInput {
+    /** The reviewed fee-forwarding leg's calldata, exactly as it will be submitted. */
+    readonly callData: Hex;
+    /** The token the whole payload spends; the fee body must name the same one. */
+    readonly expectedToken: Address;
+    /** The exact gross input amount the caller asked for; every rate is applied to it. */
+    readonly grossAmount: bigint;
+    readonly config: ExecutionServiceConfig;
+}
+/**
+ * Assert the decoded fee body carries exactly the versioned recipient set, the exact configured
+ * Otto amount, and an aggregate within the configured cap. Assert-what-you-built: this runs on the
+ * serialized calldata that is about to be returned, not on the values the constructor intended.
+ */
+export declare function assertFeeDistributionBody(input: FeeDistributionAssertionInput): void;