@rabby-wallet/rabby-bridge 0.0.13 → 0.0.14-alpha.0

package/dist/calldata/across/swapAndBridge.js

@@ -0,0 +1,70 @@
+import { BRIDGE_ERRORS, BridgeError } from '../../errors/index.js';
+import { applyAcrossMessage } from '../destination.js';
+import { asBigint, asRecord, asString, decodeCall } from '../abi.js';
+import { accountFromBytes32 } from '../hex.js';
+import { NATIVE_TOKEN } from '../protocols.js';
+const swapAndDepositData = {
+    name: 'swapAndDepositData',
+    kind: 'tuple',
+    components: [
+        {
+            name: 'submissionFees',
+            kind: 'tuple',
+            components: [
+                { name: 'amount', kind: 'uint' },
+                { name: 'recipient', kind: 'address' },
+            ],
+        },
+        {
+            name: 'depositData',
+            kind: 'tuple',
+            components: [
+                { name: 'inputToken', kind: 'address' },
+                { name: 'outputToken', kind: 'bytes', size: 32 },
+                { name: 'outputAmount', kind: 'uint' },
+                { name: 'depositor', kind: 'address' },
+                { name: 'recipient', kind: 'bytes', size: 32 },
+                { name: 'destinationChainId', kind: 'uint' },
+                { name: 'exclusiveRelayer', kind: 'bytes', size: 32 },
+                { name: 'quoteTimestamp', kind: 'uint' },
+                { name: 'fillDeadline', kind: 'uint' },
+                { name: 'exclusivityParameter', kind: 'uint' },
+                { name: 'message', kind: 'bytes' },
+            ],
+        },
+        { name: 'swapToken', kind: 'address' },
+        { name: 'exchange', kind: 'address' },
+        { name: 'transferType', kind: 'uint' },
+        { name: 'swapTokenAmount', kind: 'uint' },
+        { name: 'minExpectedInputTokenAmount', kind: 'uint' },
+        { name: 'routerCalldata', kind: 'bytes' },
+        { name: 'enableProportionalAdjustment', kind: 'bool' },
+        { name: 'spokePool', kind: 'address' },
+        { name: 'nonce', kind: 'uint' },
+    ],
+};
+export const swapAndBridge = {
+    name: 'swapAndBridge',
+    selector: '0x110560ad',
+    decode(data, value) {
+        const args = asRecord(decodeCall([swapAndDepositData], data).swapAndDepositData);
+        const depositData = asRecord(args.depositData);
+        const sourceAmount = asBigint(args.swapTokenAmount);
+        if (value > 0n && value !== sourceAmount)
+            throw new BridgeError(BRIDGE_ERRORS.ACROSS_SWAP_VALUE_MISMATCH);
+        return applyAcrossMessage({
+            aggregatorId: 'across',
+            method: 'swapAndBridge',
+            kind: 'bridge',
+            depositor: asString(depositData.depositor),
+            sourceToken: value > 0n ? NATIVE_TOKEN : asString(args.swapToken),
+            sourceAmount,
+            destinationChainId: asBigint(depositData.destinationChainId),
+            receiver: accountFromBytes32(asString(depositData.recipient)),
+            outputToken: accountFromBytes32(asString(depositData.outputToken)),
+            minOutputAmount: asBigint(depositData.outputAmount),
+            spokePool: asString(args.spokePool),
+            innerTarget: asString(args.exchange),
+        }, asString(depositData.message));
+    },
+};

package/dist/calldata/across/validate.d.ts

@@ -0,0 +1,3 @@
+import type { BridgeErrorDefinition } from '../../errors/index.js';
+import type { ParsedBridgeCall } from '../types.js';
+export declare const acrossFailure: (parsed: ParsedBridgeCall, chainId: string, expectedDepositor?: string) => BridgeErrorDefinition | undefined;

package/dist/calldata/across/validate.js

@@ -0,0 +1,34 @@
+import { BRIDGE_ERRORS } from '../../errors/index.js';
+import { getBridgeRouter } from '../../list.js';
+import { evmChainId } from '../chains.js';
+import { isZeroWord } from '../hex.js';
+// These chains use a Periphery as the outer router, separate from their canonical SpokePool.
+const SPOKE_POOLS = {
+    56: '0x4e8e101924ede233c13e2d8622dc8aed2872d505',
+    324: '0xe0b015e54d54fc84a6cb9b666099c46ade9335ff',
+    57073: '0xef684c38f94f48775959ecf2012d7e864ffb9dd4',
+};
+export const acrossFailure = (parsed, chainId, expectedDepositor) => {
+    if (expectedDepositor && parsed.depositor?.toLowerCase() !== expectedDepositor.toLowerCase()) {
+        return BRIDGE_ERRORS.DEPOSITOR_MISMATCH;
+    }
+    if (parsed.destinationChainId === undefined || parsed.destinationChainId <= 0n) {
+        return BRIDGE_ERRORS.MISSING_DESTINATION_CHAIN;
+    }
+    if (isZeroWord(parsed.receiver ?? parsed.bridgeReceiver)) {
+        return BRIDGE_ERRORS.MISSING_RECEIVER;
+    }
+    if ((parsed.sourceAmount ?? 0n) <= 0n) {
+        return BRIDGE_ERRORS.MISSING_SOURCE_AMOUNT;
+    }
+    if (!parsed.spokePool) {
+        return undefined;
+    }
+    const spoke = parsed.spokePool.toLowerCase();
+    const expectedSpoke = SPOKE_POOLS[evmChainId(chainId)?.toString() ?? ''] ??
+        getBridgeRouter('across', chainId)?.toLowerCase();
+    if (expectedSpoke !== spoke) {
+        return BRIDGE_ERRORS.SPOKE_POOL_IS_NOT_IN_THE_ALLOWLIST;
+    }
+    return undefined;
+};

package/dist/calldata/chains.d.ts

@@ -0,0 +1,2 @@
+export declare const evmChainId: (chain: string) => bigint | undefined;
+export declare const sourceChainMismatch: (expected: string, actual?: string | number | bigint) => boolean;

package/dist/calldata/chains.js

@@ -0,0 +1,36 @@
+import { CHAIN_ENUM_TO_SERVER_ID, normalizeChainEnum } from '../chains.js';
+const CHAIN_IDS = {
+    eth: 1n, op: 10n, flr: 14n, cro: 25n, rsk: 30n, xdc: 50n, bsc: 56n,
+    xdai: 100n, fuse: 122n, uni: 130n, matic: 137n, monad: 143n, sonic: 146n,
+    manta: 169n, xlayer: 196n, opbnb: 204n, lens: 232n, frax: 252n, era: 324n,
+    stable: 988n, hyper: 999n, metis: 1088n, lisk: 1135n, sei: 1329n, story: 1514n,
+    gravity: 1625n, soneium: 1868n, swell: 1923n, ron: 2020n, abs: 2741n,
+    morph: 2818n, tempo: 4217n, megaeth: 4326n, hood: 4663n, world: 480n,
+    mnt: 5000n, arc: 5042n, cyber: 7560n, klay: 8217n, base: 8453n, plasma: 9745n,
+    ape: 33139n, mode: 34443n, arb: 42161n, celo: 42220n, hemi: 43111n, avax: 43114n,
+    zircuit: 48900n, sophon: 50104n, ink: 57073n, linea: 59144n, bob: 60808n,
+    bera: 80094n, blast: 81457n, plume: 98866n, taiko: 167000n, scrl: 534352n,
+    katana: 747474n, zora: 7777777n,
+    ethereum: 1n, optimism: 10n, gnosis: 100n, polygon: 137n, mantle: 5000n,
+    arbitrum: 42161n, avalanche: 43114n, fraxtal: 252n,
+};
+export const evmChainId = (chain) => {
+    if (/^\d+$/.test(chain)) {
+        const id = BigInt(chain);
+        return id > 0n ? id : undefined;
+    }
+    const chainEnum = normalizeChainEnum(chain);
+    return CHAIN_IDS[chainEnum ? CHAIN_ENUM_TO_SERVER_ID[chainEnum] : chain.toLowerCase()];
+};
+export const sourceChainMismatch = (expected, actual) => {
+    const expectedId = evmChainId(expected);
+    if (actual === undefined || expectedId === undefined)
+        return false;
+    try {
+        return (typeof actual === 'number' && !Number.isSafeInteger(actual)) ||
+            BigInt(actual) !== expectedId;
+    }
+    catch {
+        return true;
+    }
+};

package/dist/calldata/destination.d.ts

@@ -0,0 +1,6 @@
+import { type AbiParam, type AbiValue } from './abi.js';
+import type { ParsedBridgeCall } from './types.js';
+export declare const destinationCall: AbiParam;
+export declare const readTransfer: (target: string, data: string, value: bigint) => Partial<ParsedBridgeCall> | undefined;
+export declare const readDestinationTransfers: (calls: AbiValue[]) => Partial<ParsedBridgeCall>;
+export declare const applyAcrossMessage: (parsed: ParsedBridgeCall, message: string) => ParsedBridgeCall;

package/dist/calldata/destination.js

@@ -0,0 +1,227 @@
+import { BRIDGE_ERRORS, BridgeError, asBridgeError } from '../errors/index.js';
+import { asArray, asBigint, asRecord, asString, decodeCall, decodeParameters } from './abi.js';
+import { isZeroWord, readSelector } from './hex.js';
+import { NATIVE_TOKEN, WRAPPED_NATIVE_TOKENS, subtractFees } from './protocols.js';
+import { calldataDiagnostics } from './diagnostics.js';
+import { ALLOWANCE_HOLDER, HYPEREVM_LIFI_ROUTER, readLifiSwap, readSettlerSwap } from './destinationSwap.js';
+import { AVALANCHE_UNIVERSAL_ROUTER, readUniversalRouterSwap } from './destinationUniswap.js';
+export const destinationCall = {
+    name: 'call', kind: 'tuple', components: [
+        { name: 'target', kind: 'address' }, { name: 'data', kind: 'bytes' }, { name: 'value', kind: 'uint' },
+    ],
+};
+export const readTransfer = (target, data, value) => {
+    if (data === '0x' && value > 0n)
+        return { receiver: target, outputToken: NATIVE_TOKEN, minOutputAmount: value };
+    if (value !== 0n || readSelector(data) !== '0xa9059cbb')
+        return undefined;
+    const args = decodeCall([{ name: 'to', kind: 'address' }, { name: 'amount', kind: 'uint' }], data);
+    return { receiver: asString(args.to), outputToken: target, minOutputAmount: asBigint(args.amount) };
+};
+export const readDestinationTransfers = (calls) => {
+    const diagnostics = { destinationCallCount: calls.length,
+        destinationSelectors: [...new Set(calls.map((call) => calldataDiagnostics(asRecord(call).data).selector)
+                .filter((selector) => Boolean(selector)))].slice(0, 16) };
+    const transfers = calls.map((call) => {
+        const c = asRecord(call);
+        return readTransfer(asString(c.target), asString(c.data), asBigint(c.value));
+    });
+    if (!transfers.length || transfers.some((transfer) => !transfer))
+        return { diagnostics };
+    const first = transfers[0];
+    if (!transfers.every((transfer) => transfer?.receiver === first.receiver))
+        return { diagnostics };
+    // Different assets can have one recipient without having one comparable output amount.
+    if (!transfers.every((transfer) => transfer?.outputToken === first.outputToken))
+        return { receiver: first.receiver, diagnostics };
+    return { ...first, diagnostics, minOutputAmount: transfers.reduce((sum, transfer) => sum + (transfer?.minOutputAmount ?? 0n), 0n) };
+};
+const instructions = {
+    name: 'instructions', kind: 'tuple', components: [
+        { name: 'calls', kind: 'array', item: { name: 'call', kind: 'tuple', components: [
+                    { name: 'target', kind: 'address' }, { name: 'callData', kind: 'bytes' }, { name: 'value', kind: 'uint' },
+                ] } },
+        { name: 'fallbackRecipient', kind: 'address' },
+    ],
+};
+const ACROSS_MESSAGE_HANDLERS = {
+    143: '0xec41f75c686e376ab2a4f18bde263ab5822c4511',
+    999: '0x5e7840e06faccb6d1c3b5f5e0d1d3d07f2829bba',
+    4663: '0xa8ad2e87e2043711d8bec77e8bc3e2683c0ab6bd',
+    9745: '0x5e7840e06faccb6d1c3b5f5e0d1d3d07f2829bba',
+    43114: '0x9610954acdca5ff7905f051a040ce33fe613c60e',
+};
+const readAcrossMessage = (parsed, message) => {
+    if (message === '0x') {
+        const wrapped = WRAPPED_NATIVE_TOKENS[parsed.destinationChainId?.toString() ?? ''];
+        if (parsed.outputToken !== undefined && (wrapped === undefined || parsed.outputToken === wrapped)) {
+            parsed.bridgeOutputToken = parsed.outputToken;
+            parsed.outputTokenReference = { protocol: 'across-native', token: parsed.outputToken,
+                destinationChainId: parsed.destinationChainId, destinationContract: parsed.receiver };
+            delete parsed.outputToken;
+        }
+        return parsed;
+    }
+    const handler = parsed.receiver;
+    parsed.bridgeReceiver = handler;
+    parsed.bridgeOutputToken = parsed.outputToken;
+    parsed.bridgeOutputAmount = parsed.minOutputAmount;
+    parsed.destinationCallData = message;
+    parsed.diagnostics = { hasDestinationCall: true, destinationCalldataBytes: calldataDiagnostics(message).calldataBytes };
+    delete parsed.receiver;
+    delete parsed.outputToken;
+    delete parsed.minOutputAmount;
+    // Other message handlers can implement arbitrary destination logic.
+    const expectedHandler = ACROSS_MESSAGE_HANDLERS[parsed.destinationChainId?.toString() ?? ''] ??
+        '0x0f7ae28de1c8532170ad4ee566b5801485c13a0e';
+    if (handler !== expectedHandler)
+        return parsed;
+    const emitter = parsed.destinationChainId === 43114n
+        ? '0x25b15fc38d6a2c13feddd9cb51f184f7cf0d4c11' : '0xbf75133b48b0a42ab9374027902e83c5e2949034';
+    const args = asRecord(decodeParameters([instructions], message).instructions);
+    const calls = asArray(args.calls);
+    parsed.diagnostics.destinationCallCount = calls.length;
+    parsed.diagnostics.destinationSelectors = [...new Set(calls.map((call) => calldataDiagnostics(asRecord(call).callData).selector)
+            .filter((selector) => Boolean(selector)))].slice(0, 16);
+    const balances = new Map([[parsed.bridgeOutputToken, parsed.bridgeOutputAmount]]);
+    const payouts = [];
+    const directTransfers = [];
+    const approvals = new Map();
+    const lifiRouter = parsed.destinationChainId === 999n ? HYPEREVM_LIFI_ROUTER : undefined;
+    const possibleRefundTokens = new Set();
+    const refundReceivers = [];
+    for (let index = 0; index < calls.length; index++) {
+        const call = asRecord(calls[index]);
+        const target = asString(call.target);
+        const data = asString(call.callData);
+        const value = asBigint(call.value);
+        const selector = readSelector(data);
+        // emitData is telemetry; its amounts are not an enforced receive floor.
+        if (selector === '0xd836083e' && target === emitter && value === 0n)
+            continue;
+        if (selector === '0x095ea7b3' && value === 0n && balances.has(target)) {
+            const approval = decodeCall([{ name: 'spender', kind: 'address' }, { name: 'amount', kind: 'uint' }], data);
+            const amount = asBigint(approval.amount);
+            const spender = asString(approval.spender);
+            if ((spender !== ALLOWANCE_HOLDER && spender !== lifiRouter) ||
+                (amount > (balances.get(target) ?? 0n) && amount !== (1n << 256n) - 1n))
+                return parsed;
+            approvals.set(`${target}:${spender}`, amount);
+            continue;
+        }
+        if ((target === ALLOWANCE_HOLDER || target === lifiRouter) && value === 0n) {
+            const swap = target === ALLOWANCE_HOLDER
+                ? readSettlerSwap(data, parsed.destinationChainId, handler, balances)
+                : readLifiSwap(data, parsed.destinationChainId, target, handler);
+            const approvalKey = `${swap?.inputToken}:${target}`;
+            if (!swap || (approvals.get(approvalKey) ?? 0n) < swap.inputAmount ||
+                (balances.get(swap.inputToken) ?? 0n) < swap.inputAmount)
+                return parsed;
+            approvals.set(approvalKey, (approvals.get(approvalKey) ?? 0n) - swap.inputAmount);
+            balances.set(swap.inputToken, (balances.get(swap.inputToken) ?? 0n) - swap.inputAmount);
+            balances.set(swap.outputToken, (balances.get(swap.outputToken) ?? 0n) + swap.minOutputAmount);
+            // GenericSwapFacet returns unused input to Handler; its later payout must agree too.
+            if (target === lifiRouter)
+                possibleRefundTokens.add(swap.inputToken);
+            continue;
+        }
+        if (selector === '0xc41e8295' && target === handler) {
+            if (value !== 0n)
+                return parsed;
+            const nested = decodeCall([
+                { name: 'target', kind: 'address' }, { name: 'data', kind: 'bytes' }, { name: 'value', kind: 'uint' },
+                { name: 'replacements', kind: 'array', item: { name: 'replacement', kind: 'tuple', components: [
+                            { name: 'token', kind: 'address' }, { name: 'offset', kind: 'uint' },
+                        ] } },
+            ], data);
+            const token = asString(nested.target);
+            const replacements = asArray(nested.replacements).map(asRecord);
+            const withdrawal = asString(nested.data);
+            if (readSelector(withdrawal) !== '0x2e1a7d4d' || replacements.length !== 1 ||
+                asBigint(decodeCall([{ name: 'amount', kind: 'uint' }], withdrawal).amount) !== 0n ||
+                asBigint(nested.value) !== 0n ||
+                asString(replacements[0].token) !== token || asBigint(replacements[0].offset) !== 4n || !balances.has(token) ||
+                WRAPPED_NATIVE_TOKENS[parsed.destinationChainId?.toString() ?? ''] !== token)
+                return parsed;
+            balances.set(NATIVE_TOKEN, (balances.get(NATIVE_TOKEN) ?? 0n) + (balances.get(token) ?? 0n));
+            balances.set(token, 0n);
+            continue;
+        }
+        if (selector === '0xef8738d3' && target === handler) {
+            if (value !== 0n)
+                return parsed;
+            const drain = decodeCall([{ name: 'token', kind: 'address' }, { name: 'receiver', kind: 'address' }], data);
+            const token = asString(drain.token);
+            const amount = balances.get(token) ?? 0n;
+            if (parsed.destinationChainId === 43114n && asString(drain.receiver) === AVALANCHE_UNIVERSAL_ROUTER) {
+                if (index + 1 >= calls.length)
+                    return parsed;
+                const next = asRecord(calls[index + 1]);
+                if (asString(next.target) !== AVALANCHE_UNIVERSAL_ROUTER || asBigint(next.value) !== 0n)
+                    return parsed;
+                const swap = readUniversalRouterSwap(asString(next.callData), handler);
+                if (!swap || swap.inputToken !== token || swap.inputAmount !== amount)
+                    return parsed;
+                balances.set(token, 0n);
+                balances.set(swap.outputToken, (balances.get(swap.outputToken) ?? 0n) + swap.minOutputAmount);
+                index++;
+                continue;
+            }
+            if (possibleRefundTokens.delete(token))
+                refundReceivers.push(asString(drain.receiver));
+            if (amount > 0n)
+                payouts.push({ outputToken: token, minOutputAmount: amount, receiver: asString(drain.receiver) });
+            balances.set(token, 0n);
+            continue;
+        }
+        const transfer = readTransfer(target, data, value);
+        if (!transfer || !balances.has(transfer.outputToken))
+            return parsed;
+        const token = transfer.outputToken;
+        balances.set(token, subtractFees(balances.get(token) ?? 0n, transfer.minOutputAmount ?? 0n));
+        directTransfers.push(transfer);
+    }
+    const fallback = asString(args.fallbackRecipient);
+    const hasDrain = payouts.length > 0;
+    // The Handler drains the original bridge asset to fallback even after successful calls.
+    const remaining = balances.get(parsed.bridgeOutputToken) ?? 0n;
+    if (!isZeroWord(fallback) && possibleRefundTokens.delete(parsed.bridgeOutputToken)) {
+        refundReceivers.push(fallback);
+    }
+    if (!isZeroWord(fallback) && remaining > 0n) {
+        payouts.push({ receiver: fallback, outputToken: parsed.bridgeOutputToken, minOutputAmount: remaining });
+        balances.set(parsed.bridgeOutputToken, 0n);
+    }
+    // Existing drain routes may contain explicit fee transfers; without a drain every
+    // direct transfer must agree on the recipient, and no tracked funds may be stranded.
+    const delivered = hasDrain
+        ? [...payouts, ...directTransfers.filter((transfer) => transfer.receiver === payouts[0].receiver)]
+        : [...directTransfers, ...payouts];
+    if (delivered.length && !possibleRefundTokens.size && [...balances.values()].every((amount) => amount === 0n)) {
+        const receiver = delivered[0].receiver;
+        if (!delivered.every((payout) => payout.receiver === receiver) ||
+            !refundReceivers.every((recipient) => recipient === receiver))
+            return parsed;
+        if (!isZeroWord(fallback) && fallback !== receiver) {
+            throw new BridgeError(BRIDGE_ERRORS.ACROSS_FALLBACK_RECEIVER_MISMATCH);
+        }
+        parsed.receiver = receiver;
+        const token = delivered[0].outputToken;
+        if (delivered.every((payout) => payout.outputToken === token) &&
+            (isZeroWord(fallback) || token === parsed.bridgeOutputToken)) {
+            parsed.outputToken = token;
+            parsed.minOutputAmount = delivered.reduce((sum, payout) => sum + (payout.minOutputAmount ?? 0n), 0n);
+        }
+        // Different success/fallback assets do not invalidate a shared receiver, but
+        // neither asset nor a single minimum can be claimed for both outcomes.
+    }
+    return parsed;
+};
+export const applyAcrossMessage = (parsed, message) => {
+    try {
+        return readAcrossMessage(parsed, message);
+    }
+    catch (error) {
+        throw asBridgeError(error, BRIDGE_ERRORS.CALLDATA_DECODE_FAILED, parsed.diagnostics);
+    }
+};

package/dist/calldata/destinationSwap.d.ts

@@ -0,0 +1,14 @@
+export declare const ALLOWANCE_HOLDER = "0x0000000000001ff3684f28c67538d4d072c22734";
+export declare const HYPEREVM_LIFI_ROUTER = "0x0a0758d937d1059c356d4714e57f5df0239bce1a";
+export declare const readLifiSwap: (data: string, chain: bigint | undefined, target: string, recipient: string) => {
+    inputToken: string;
+    inputAmount: bigint;
+    outputToken: string;
+    minOutputAmount: bigint;
+} | undefined;
+export declare const readSettlerSwap: (data: string, chain: bigint | undefined, recipient: string, balances?: ReadonlyMap<string, bigint>) => {
+    inputToken: string;
+    inputAmount: bigint;
+    outputToken: string;
+    minOutputAmount: bigint;
+} | undefined;

package/dist/calldata/destinationSwap.js

@@ -0,0 +1,83 @@
+import { asArray, asBigint, asRecord, asString, decodeCall } from './abi.js';
+import { readSelector } from './hex.js';
+import { isNative, NATIVE_TOKEN } from './protocols.js';
+import { methods as lifiSwaps } from './lifi/swap/index.js';
+export const ALLOWANCE_HOLDER = '0x0000000000001ff3684f28c67538d4d072c22734';
+// Reviewed deployments, not dynamic registry lookups. Evidence and renewal limits:
+// tests/fixtures/route-discovery-20261104/evidence/base-settler-verification.json
+// tests/fixtures/reported-20261111-evidence.json (Ethereum)
+const SETTLERS = {
+    1: '0xaddc26a3854feabfd20d6bf658254088d83a425a',
+    8453: '0x7d6839415693801e94cdc4a7d732c9a3fdbbd1d7',
+    999: '0xf58d4122251f2ace689f257eaf2688883e30fc6e',
+};
+export const HYPEREVM_LIFI_ROUTER = '0x0a0758d937d1059c356d4714e57f5df0239bce1a';
+export const readLifiSwap = (data, chain, target, recipient) => {
+    if (chain !== 999n || target !== HYPEREVM_LIFI_ROUTER || readSelector(data) !== '0x4666fc80')
+        return undefined;
+    const method = lifiSwaps.find((item) => item.selector === '0x4666fc80');
+    const parsed = method?.decode(data, 0n);
+    if (!parsed || parsed.receiver !== recipient)
+        return undefined;
+    const { sourceToken: inputToken, sourceAmount: inputAmount, outputToken, minOutputAmount } = parsed;
+    if (!inputToken || isNative(inputToken) || !outputToken || isNative(outputToken) ||
+        inputAmount === undefined || inputAmount <= 0n || minOutputAmount === undefined || minOutputAmount <= 0n)
+        return undefined;
+    return { inputToken, inputAmount, outputToken, minOutputAmount };
+};
+export const readSettlerSwap = (data, chain, recipient, balances) => {
+    if (readSelector(data) !== '0x2213bc0b')
+        return undefined;
+    const args = decodeCall([
+        { name: 'operator', kind: 'address' }, { name: 'token', kind: 'address' },
+        { name: 'amount', kind: 'uint' }, { name: 'target', kind: 'address' }, { name: 'data', kind: 'bytes' },
+    ], data);
+    const settler = SETTLERS[chain?.toString() ?? ''];
+    if (!settler || asString(args.target) !== settler || asString(args.operator) !== settler ||
+        isNative(asString(args.token)) || asBigint(args.amount) <= 0n)
+        return undefined;
+    const inner = asString(args.data);
+    if (readSelector(inner) !== '0x1fff991f')
+        return undefined;
+    const execution = decodeCall([
+        { name: 'slippage', kind: 'tuple', components: [
+                { name: 'recipient', kind: 'address' }, { name: 'buyToken', kind: 'address' }, { name: 'minAmountOut', kind: 'uint' },
+            ] },
+        { name: 'actions', kind: 'array', item: { name: 'action', kind: 'bytes' } },
+        { name: 'zid', kind: 'bytes', size: 32 },
+    ], inner);
+    const slippage = asRecord(execution.slippage);
+    if (asString(slippage.recipient) !== recipient || asString(slippage.buyToken) === NATIVE_TOKEN ||
+        asBigint(slippage.minAmountOut) <= 0n)
+        return undefined;
+    const actions = asArray(execution.actions).map(asString);
+    // These reviewed actions cannot mutate/zeroize slippage. CHECK_SLIPPAGE, SELECT
+    // and unreviewed actions must not bypass the final enforced transfer to Handler.
+    if (!actions.length || readSelector(actions[0]) !== '0xc1fb425e' ||
+        actions.slice(1).some((action) => !['0x38c9c147', '0x8d68a156', '0x5f80abae'].includes(readSelector(action) ?? '') &&
+            !(chain === 1n && readSelector(action) === '0xf61460f9')))
+        return undefined;
+    const funding = decodeCall([
+        { name: 'recipient', kind: 'address' }, { name: 'token', kind: 'address' },
+        { name: 'amount', kind: 'uint' }, { name: 'nonce', kind: 'uint' },
+        { name: 'deadline', kind: 'uint' }, { name: 'signature', kind: 'bytes' },
+    ], actions[0]);
+    if (asString(funding.recipient) !== settler || asString(funding.token) !== asString(args.token) ||
+        asBigint(funding.amount) !== asBigint(args.amount) || asString(funding.signature) !== '0x')
+        return undefined;
+    let inputAmount = asBigint(args.amount);
+    const maxUint256 = (1n << 256n) - 1n;
+    // shortcut: only reviewed Ethereum/HyperEVM 100%-balance encoding; review other ratios before support.
+    if ((chain === 1n || chain === 999n) && inputAmount > maxUint256 - 1000000n) {
+        if (inputAmount !== maxUint256)
+            return undefined;
+        inputAmount = balances?.get(asString(args.token)) ?? 0n;
+        if (inputAmount <= 0n)
+            return undefined;
+    }
+    return {
+        inputToken: asString(args.token), inputAmount,
+        outputToken: isNative(asString(slippage.buyToken)) ? NATIVE_TOKEN : asString(slippage.buyToken),
+        minOutputAmount: asBigint(slippage.minAmountOut),
+    };
+};

package/dist/calldata/destinationUniswap.d.ts

@@ -0,0 +1,7 @@
+export declare const AVALANCHE_UNIVERSAL_ROUTER = "0x661e93cca42afacb172121ef892830ca3b70f08d";
+export declare const readUniversalRouterSwap: (data: string, recipient: string) => {
+    inputToken: string;
+    inputAmount: bigint;
+    outputToken: string;
+    minOutputAmount: bigint;
+} | undefined;

package/dist/calldata/destinationUniswap.js

@@ -0,0 +1,57 @@
+import { asArray, asBigint, asRecord, asString, decodeCall, decodeParameters } from './abi.js';
+import { readSelector } from './hex.js';
+import { isNative, NATIVE_TOKEN } from './protocols.js';
+// Reviewed UniversalRouter v2.1.2; see reported-20261111-evidence.json.
+export const AVALANCHE_UNIVERSAL_ROUTER = '0x661e93cca42afacb172121ef892830ca3b70f08d';
+export const readUniversalRouterSwap = (data, recipient) => {
+    if (readSelector(data) !== '0x24856bc3')
+        return undefined;
+    const execution = decodeCall([
+        { name: 'commands', kind: 'bytes' },
+        { name: 'inputs', kind: 'array', item: { name: 'input', kind: 'bytes' } },
+    ], data);
+    const inputs = asArray(execution.inputs);
+    // No optional/reverting commands or unrelated transfers may bypass the payout.
+    if (asString(execution.commands) !== '0x10' || inputs.length !== 1)
+        return undefined;
+    const plan = decodeParameters([
+        { name: 'actions', kind: 'bytes' },
+        { name: 'params', kind: 'array', item: { name: 'param', kind: 'bytes' } },
+    ], asString(inputs[0]));
+    const params = asArray(plan.params).map(asString);
+    if (asString(plan.actions) !== '0x070b0e' || params.length !== 3)
+        return undefined;
+    const swap = asRecord(decodeParameters([{ name: 'swap', kind: 'tuple', components: [
+                { name: 'currencyIn', kind: 'address' },
+                { name: 'path', kind: 'array', item: { name: 'hop', kind: 'tuple', components: [
+                            { name: 'intermediateCurrency', kind: 'address' }, { name: 'fee', kind: 'uint' },
+                            { name: 'tickSpacing', kind: 'uint' }, { name: 'hooks', kind: 'address' }, { name: 'hookData', kind: 'bytes' },
+                        ] } },
+                { name: 'minHopPriceX36', kind: 'array', item: { name: 'price', kind: 'uint' } },
+                { name: 'amountIn', kind: 'uint' }, { name: 'amountOutMinimum', kind: 'uint' },
+            ] }], params[0]).swap);
+    const path = asArray(swap.path).map(asRecord);
+    const prices = asArray(swap.minHopPriceX36);
+    // shortcut: one ERC20 hop without hooks; review additional V4 plans before support.
+    if (path.length !== 1 || prices.length > 1)
+        return undefined;
+    const hop = path[0];
+    const inputToken = asString(swap.currencyIn), outputToken = asString(hop.intermediateCurrency);
+    const inputAmount = asBigint(swap.amountIn), minOutputAmount = asBigint(swap.amountOutMinimum);
+    if (isNative(inputToken) || isNative(outputToken) || inputToken === outputToken ||
+        asString(hop.hooks) !== NATIVE_TOKEN || asString(hop.hookData) !== '0x' ||
+        asBigint(hop.fee) > 1000000n || asBigint(hop.tickSpacing) <= 0n || asBigint(hop.tickSpacing) > 32767n ||
+        inputAmount <= 0n || inputAmount >= (1n << 128n) || minOutputAmount <= 0n || minOutputAmount >= (1n << 128n))
+        return undefined;
+    const settle = decodeParameters([
+        { name: 'currency', kind: 'address' }, { name: 'amount', kind: 'uint' }, { name: 'payerIsUser', kind: 'bool' },
+    ], params[1]);
+    const take = decodeParameters([
+        { name: 'currency', kind: 'address' }, { name: 'recipient', kind: 'address' }, { name: 'amount', kind: 'uint' },
+    ], params[2]);
+    // OPEN_DELTA (0) settles the swap's debt from Router and takes all output back to Handler.
+    if (asString(settle.currency) !== inputToken || asBigint(settle.amount) !== 0n || settle.payerIsUser !== false ||
+        asString(take.currency) !== outputToken || asString(take.recipient) !== recipient || asBigint(take.amount) !== 0n)
+        return undefined;
+    return { inputToken, inputAmount, outputToken, minOutputAmount };
+};

package/dist/calldata/diagnostics.d.ts

@@ -0,0 +1,4 @@
+import type { BridgeErrorContext } from '../errors/index.js';
+/** Inspect call structure only. Never retain arguments or scan arbitrary payloads for selectors. */
+export declare const calldataDiagnostics: (data: unknown) => BridgeErrorContext;
+export declare const innerCallDiagnostics: (data: string, layer: "router" | "protocol") => BridgeErrorContext;

package/dist/calldata/diagnostics.js

@@ -0,0 +1,18 @@
+/** Inspect call structure only. Never retain arguments or scan arbitrary payloads for selectors. */
+export const calldataDiagnostics = (data) => {
+    if (typeof data !== 'string')
+        return { calldataFormat: 'missing' };
+    const valid = /^0x(?:[0-9a-f]{2})*$/i.test(data);
+    const selector = /^0x[0-9a-f]{8}/i.test(data) ? data.slice(0, 10).toLowerCase() : undefined;
+    return {
+        selector,
+        calldataFormat: valid ? (data.length === 2 ? 'empty' : 'valid') : 'invalid',
+        ...(valid ? { calldataBytes: (data.length - 2) / 2 } : {}),
+    };
+};
+export const innerCallDiagnostics = (data, layer) => {
+    const { selector, calldataBytes } = calldataDiagnostics(data);
+    return layer === 'router'
+        ? { routerSelector: selector, routerCalldataBytes: calldataBytes }
+        : { protocolSelector: selector, protocolCalldataBytes: calldataBytes };
+};

package/dist/calldata/expect.d.ts

@@ -0,0 +1,29 @@
+import type { BridgeErrorDefinition } from '../errors/index.js';
+import type { BridgeCheck, ParsedBridgeCall } from './types.js';
+export type BridgeCallExpectation = {
+    userAddress: string;
+    fromTokenId: string;
+    fromTokenRawAmount: string;
+    toTokenId: string;
+    /** 目标链 id。目标币是原生币时，用它识别 `hood` 这类链 id，而不是源链 id。 */
+    toChainId?: string;
+    toTokenRawAmount?: string;
+    /** Selected backend quote key; only protocol identifiers with known semantics are compared. */
+    quoteKey?: string | Record<string, unknown>;
+    /** Relay `protocol.v2.orderData` captured with the transaction being signed. */
+    orderData?: unknown;
+    /** 小数滑点。0.01 表示 1%。 */
+    slippage?: string | number;
+};
+export type CompareMask = {
+    fromToken: boolean;
+    fromAmount: boolean;
+    toToken: boolean;
+    toAmount: boolean;
+    receiver: boolean;
+};
+export declare const knownCompare: (parsed: ParsedBridgeCall) => CompareMask;
+/** Source payment is capped at 100.1% of local intent; smaller payments are allowed. */
+export declare const sourceAmountMatches: (actual: bigint | undefined, expected: bigint) => boolean;
+export declare const expectationFailures: (parsed: ParsedBridgeCall, expectation: BridgeCallExpectation, chainId: string, mask: CompareMask) => BridgeErrorDefinition[];
+export declare const finishCheck: (aggregatorId: string, parsed: ParsedBridgeCall, structural: BridgeErrorDefinition | undefined, expectation: BridgeCallExpectation | undefined, chainId: string, mask: CompareMask) => BridgeCheck;