@shapeshiftoss/swapper 17.8.0 → 19.0.0

package/dist/esm/utils/cosmossdk/getUnsignedCosmosSdkTransaction.js

@@ -0,0 +1,32 @@
+import { getCosmosSdkExecutionContext } from './getCosmosSdkExecutionContext.js';
+export const getUnsignedCosmosSdkTransaction = async (args) => {
+    const { from } = args;
+    const { step, adapter, transactionData, feeData } = await getCosmosSdkExecutionContext(args);
+    const { accountNumber } = step;
+    const chainSpecific = { gas: feeData.chainSpecific.gasLimit, fee: feeData.txFee };
+    if (transactionData.type === 'cosmossdk_msg_deposit') {
+        const { value, memo, coin } = transactionData;
+        if (!('buildDepositTransaction' in adapter)) {
+            throw new Error('adapter does not support deposit transactions');
+        }
+        const depositAdapter = adapter;
+        const { txToSign } = await depositAdapter.buildDepositTransaction({
+            accountNumber,
+            from,
+            value,
+            memo,
+            chainSpecific: { ...chainSpecific, coin },
+        });
+        return txToSign;
+    }
+    const { to, value, memo } = transactionData;
+    const { txToSign } = await adapter.buildSendApiTransaction({
+        accountNumber,
+        from,
+        to,
+        value,
+        memo,
+        chainSpecific,
+    });
+    return txToSign;
+};

package/dist/esm/utils/cosmossdk/index.d.ts

@@ -0,0 +1,3 @@
+export * from './getCosmosSdkExecutionContext.js';
+export * from './getCosmosSdkTransactionFees.js';
+export * from './getUnsignedCosmosSdkTransaction.js';

package/dist/esm/utils/cosmossdk/index.js

@@ -0,0 +1,3 @@
+export * from './getCosmosSdkExecutionContext.js';
+export * from './getCosmosSdkTransactionFees.js';
+export * from './getUnsignedCosmosSdkTransaction.js';

package/dist/esm/{cowswap-utils → utils/cowswap}/index.d.ts

@@ -6,7 +6,7 @@ import type { AccountMetadata, UnsignedOrderCreation } from '@shapeshiftoss/type
 import { CowNetwork } from '@shapeshiftoss/types';
 import type { TypedData } from 'eip-712';
 import type { Address } from 'viem';
-import type { AffiliateAppDataFragment } from '../swappers/CowSwapper/index.js';
+import type { AffiliateAppDataFragment } from '../../swappers/CowSwapper/index.js';
 export * from './constants.js';
 export declare const getCowNetwork: (chainId: ChainId) => CowNetwork | undefined;
 export declare const assertGetCowNetwork: (chainId: ChainId) => CowNetwork;

package/dist/esm/{cowswap-utils → utils/cowswap}/index.js

@@ -5,7 +5,7 @@ import { CowNetwork, KnownChainIds, TypedDataPrimaryType } from '@shapeshiftoss/
 import { bnOrZero, convertDecimalPercentageToBasisPoints, getNativeFeeAssetReference, } from '@shapeshiftoss/utils';
 import { ethers } from 'ethers';
 import { keccak256, stringToBytes } from 'viem';
-import { getTreasuryAddressFromChainId } from '../swappers/utils/helpers/helpers.js';
+import { getTreasuryAddressFromChainId } from '../helpers.js';
 import { CANCELLATIONS_TYPE_FIELDS, COW_SWAP_NATIVE_ASSET_MARKER_ADDRESS, COW_SWAP_SETTLEMENT_ADDRESS, ORDER_TYPE_FIELDS, } from './constants.js';
 export * from './constants.js';
 export const getCowNetwork = (chainId) => {

package/dist/esm/utils/cowswap/index.test.js

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import { getFullAppData } from './index.js';
+describe('getFullAppData', () => {
+    it('should return correct AppData for given inputs for no affiliate fee', async () => {
+        const slippageTolerancePercentage = '0.005'; // 0.5%
+        const affiliateAppDataFragment = {}; // no affiliate fee
+        const result = await getFullAppData(slippageTolerancePercentage, affiliateAppDataFragment, 'market');
+        expect(result).toEqual({
+            appDataHash: '0x41fffc0127f56060cc551652721d84c336f87649a20c51fcff5b8841dfeabe5b',
+            appData: '{"appCode":"shapeshift","metadata":{"orderClass":{"orderClass":"market"},"quote":{"slippageBips":50}},"version":"1.3.0"}',
+        });
+    });
+    it('should return correct AppData for given inputs for affiliate fee', async () => {
+        const slippageTolerancePercentage = '0.005'; // 0.5%
+        const affiliateAppDataFragment = {
+            partnerFee: {
+                bps: 48,
+                recipient: '0xb0E3175341794D1dc8E5F02a02F9D26989EbedB3',
+            },
+        };
+        const result = await getFullAppData(slippageTolerancePercentage, affiliateAppDataFragment, 'market');
+        expect(result).toEqual({
+            appDataHash: '0x6a731164dc2bb01874c1537079a3f543894da3b5803dcfed23aaf8396c919be2',
+            appData: '{"appCode":"shapeshift","metadata":{"orderClass":{"orderClass":"market"},"partnerFee":{"bps":48,"recipient":"0xb0E3175341794D1dc8E5F02a02F9D26989EbedB3"},"quote":{"slippageBips":50}},"version":"1.3.0"}',
+        });
+    });
+});

package/dist/esm/utils/evm/constants.d.ts

@@ -0,0 +1 @@
+export declare const EVM_PLACEHOLDER_ADDRESS = "0x000000000000000000000000000000000000dEaD";

package/dist/esm/utils/evm/constants.js

@@ -0,0 +1,4 @@
+// Placeholder sender for rate estimation without a connected wallet - the balance override funds
+// it as needed, and it never collides with a provider deposit address, keeping the estimated
+// transfer two-slot shaped (a self-transfer touches one balance slot and estimates low)
+export const EVM_PLACEHOLDER_ADDRESS = '0x000000000000000000000000000000000000dEaD';

package/dist/esm/utils/evm/getEvmExecutionContext.d.ts

@@ -0,0 +1,27 @@
+import { evm } from '@shapeshiftoss/chain-adapters';
+import type { GetUnsignedEvmTransactionArgs } from '../../types.js';
+export declare const getEvmExecutionContext: ({ stepIndex, tradeQuote, supportsEIP1559, assertGetEvmChainAdapter, }: GetUnsignedEvmTransactionArgs) => Promise<{
+    step: import("../../types.js").TradeQuoteStep;
+    adapter: import("@shapeshiftoss/chain-adapters").EvmChainAdapter;
+    transactionData: {
+        type: "evm";
+        chainId: number;
+        to: string;
+        data: string;
+        value: string;
+        gasLimit?: string | undefined;
+        signatureRequired?: {
+            type: "permit2";
+            eip712: {
+                domain: Record<string, unknown>;
+                types: Record<string, {
+                    name: string;
+                    type: string;
+                }[]>;
+                primaryType: string;
+                message: Record<string, unknown>;
+            };
+        } | undefined;
+    };
+    feeData: evm.Fees;
+}>;

package/dist/esm/utils/evm/getEvmExecutionContext.js

@@ -0,0 +1,25 @@
+import { evm } from '@shapeshiftoss/chain-adapters';
+import { getExecutableTradeStep, isExecutableTradeQuote } from '../../utils/index.js';
+export const getEvmExecutionContext = async ({ stepIndex, tradeQuote, supportsEIP1559, assertGetEvmChainAdapter, }) => {
+    if (!isExecutableTradeQuote(tradeQuote))
+        throw new Error('unable to execute a trade rate');
+    const step = getExecutableTradeStep(tradeQuote, stepIndex);
+    const { transactionData, sellAsset } = step;
+    if (transactionData?.type !== 'evm')
+        throw new Error('invalid evm transaction');
+    if (!transactionData.gasLimit)
+        throw new Error('missing gas limit in evm transaction');
+    const { gasLimit } = transactionData;
+    const adapter = assertGetEvmChainAdapter(sellAsset.chainId);
+    const { average } = await adapter.getGasFeeData();
+    const networkFeeCryptoBaseUnit = evm.calcNetworkFeeCryptoBaseUnit({
+        ...average,
+        supportsEIP1559,
+        gasLimit,
+    });
+    const { gasPrice, maxFeePerGas, maxPriorityFeePerGas } = average;
+    const feeData = supportsEIP1559 && maxFeePerGas && maxPriorityFeePerGas
+        ? { networkFeeCryptoBaseUnit, gasLimit, maxFeePerGas, maxPriorityFeePerGas }
+        : { networkFeeCryptoBaseUnit, gasLimit, gasPrice };
+    return { step, adapter, transactionData, feeData };
+};

package/dist/esm/utils/evm/getEvmNetworkFeeCryptoBaseUnit.d.ts

@@ -0,0 +1,22 @@
+import type { EvmChainAdapter } from '@shapeshiftoss/chain-adapters';
+import type { Asset } from '@shapeshiftoss/types';
+import type { TxBuildData } from '../../types.js';
+type GetEvmNetworkFeeCryptoBaseUnitArgs = {
+    adapter: EvmChainAdapter;
+    supportsEIP1559: boolean;
+} & ({
+    gasLimit: string;
+} | {
+    transactionData: Extract<TxBuildData, {
+        type: 'evm';
+    }>;
+    from: string;
+    gasLimitBuffer?: number;
+    stateOverride?: {
+        sellAsset: Asset;
+        sellAmountCryptoBaseUnit: string;
+        spenderAddress?: string;
+    };
+});
+export declare const getEvmNetworkFeeCryptoBaseUnit: (args: GetEvmNetworkFeeCryptoBaseUnitArgs) => Promise<string>;
+export {};

package/dist/esm/utils/evm/getEvmNetworkFeeCryptoBaseUnit.js

@@ -0,0 +1,48 @@
+import { evm } from '@shapeshiftoss/chain-adapters';
+import { bnOrZero } from '@shapeshiftoss/utils';
+import { estimateGasWithStateOverride, getMinimalStateOverride, withTimeout } from './stateOverride.js';
+export const getEvmNetworkFeeCryptoBaseUnit = async (args) => {
+    const { adapter, supportsEIP1559 } = args;
+    // Price a provider gas limit with fresh gas prices - no on chain estimation
+    const priceProviderGasLimit = async (gasLimit) => {
+        const { average: gasPrices } = await adapter.getGasFeeData();
+        return evm.calcNetworkFeeCryptoBaseUnit({ ...gasPrices, supportsEIP1559, gasLimit });
+    };
+    // Rate network fee: the caller passed a provider gas limit directly
+    if (!('transactionData' in args))
+        return priceProviderGasLimit(args.gasLimit);
+    const { transactionData, from, gasLimitBuffer = 1.2 } = args;
+    // Executable quote: the provider supplied a gas limit on the tx data, price it as-is
+    const providerGasLimit = transactionData.gasLimit;
+    if (providerGasLimit && bnOrZero(providerGasLimit).gt(0)) {
+        return priceProviderGasLimit(providerGasLimit);
+    }
+    const { to, data, value } = transactionData;
+    if (args.stateOverride) {
+        const { sellAsset, sellAmountCryptoBaseUnit, spenderAddress } = args.stateOverride;
+        // Best effort - a timeout, undiscoverable slot, or an rpc without stateOverride support falls
+        // through to plain estimation, which succeeds whenever the seller's state was sufficient anyway
+        const overriddenGasLimit = await withTimeout((async () => {
+            const overrideArgs = {
+                sellAsset,
+                sellAmountCryptoBaseUnit,
+                from,
+                spenderAddress,
+                value,
+            };
+            const stateOverride = await getMinimalStateOverride(overrideArgs);
+            if (!stateOverride)
+                return undefined;
+            return estimateGasWithStateOverride({ ...overrideArgs, to, data, stateOverride });
+        })()).catch(() => undefined);
+        if (overriddenGasLimit) {
+            transactionData.gasLimit = bnOrZero(overriddenGasLimit).times(gasLimitBuffer).toFixed(0);
+            return priceProviderGasLimit(overriddenGasLimit);
+        }
+    }
+    // Estimate on chain, then set the buffered limit on the tx data in place so the executable tx
+    // always carries a gas limit
+    const estimatedFees = await evm.getFees({ adapter, data, to, value, from, supportsEIP1559 });
+    transactionData.gasLimit = bnOrZero(estimatedFees.gasLimit).times(gasLimitBuffer).toFixed(0);
+    return estimatedFees.networkFeeCryptoBaseUnit;
+};

package/dist/esm/utils/evm/getEvmTransactionFees.d.ts

@@ -0,0 +1,2 @@
+import type { GetUnsignedEvmTransactionArgs } from '../../types.js';
+export declare const getEvmTransactionFees: (args: GetUnsignedEvmTransactionArgs) => Promise<string>;

package/dist/esm/utils/evm/getEvmTransactionFees.js

@@ -0,0 +1,5 @@
+import { getEvmExecutionContext } from './getEvmExecutionContext.js';
+export const getEvmTransactionFees = async (args) => {
+    const { feeData } = await getEvmExecutionContext(args);
+    return feeData.networkFeeCryptoBaseUnit;
+};

package/dist/esm/{thorchain-utils → utils}/evm/getUnsignedEvmTransaction.d.ts

@@ -1,4 +1,4 @@
 import type { SignTx } from '@shapeshiftoss/chain-adapters';
 import type { EvmChainId } from '@shapeshiftoss/types';
-import type { GetUnsignedEvmTransactionArgs, SwapperName } from '../../types.js';
-export declare const getUnsignedEvmTransaction: (args: GetUnsignedEvmTransactionArgs, swapperName: SwapperName) => Promise<SignTx<EvmChainId>>;
+import type { GetUnsignedEvmTransactionArgs } from '../../types.js';
+export declare const getUnsignedEvmTransaction: (args: GetUnsignedEvmTransactionArgs) => Promise<SignTx<EvmChainId>>;

package/dist/esm/utils/evm/getUnsignedEvmTransaction.js

@@ -0,0 +1,20 @@
+import { concat, numberToHex, size } from 'viem';
+import { getEvmExecutionContext } from './getEvmExecutionContext.js';
+export const getUnsignedEvmTransaction = async (args) => {
+    const { from, permit2Signature } = args;
+    const { step, adapter, transactionData, feeData } = await getEvmExecutionContext(args);
+    const { accountNumber } = step;
+    const { to, value } = transactionData;
+    const data = (() => {
+        if (!permit2Signature)
+            return transactionData.data;
+        // Append the permit2 signature to the calldata
+        // https://0x.org/docs/0x-swap-api/guides/swap-tokens-with-0x-swap-api#5-append-signature-length-and-signature-data-to-transactiondata
+        const signatureLengthInHex = numberToHex(size(permit2Signature), {
+            signed: false,
+            size: 32,
+        });
+        return concat([transactionData.data, signatureLengthInHex, permit2Signature]);
+    })();
+    return adapter.buildCustomApiTx({ accountNumber, data, from, to, value, ...feeData });
+};

package/dist/esm/utils/evm/index.d.ts

@@ -0,0 +1,7 @@
+export * from './constants.js';
+export * from './getEvmExecutionContext.js';
+export * from './getEvmNetworkFeeCryptoBaseUnit.js';
+export * from './getEvmTransactionFees.js';
+export * from './getUnsignedEvmTransaction.js';
+export * from './stateOverride.js';
+export * from './storageSlots.js';

package/dist/esm/utils/evm/index.js

@@ -0,0 +1,7 @@
+export * from './constants.js';
+export * from './getEvmExecutionContext.js';
+export * from './getEvmNetworkFeeCryptoBaseUnit.js';
+export * from './getEvmTransactionFees.js';
+export * from './getUnsignedEvmTransaction.js';
+export * from './stateOverride.js';
+export * from './storageSlots.js';

package/dist/esm/utils/evm/stateOverride.d.ts

@@ -0,0 +1,17 @@
+import type { Asset } from '@shapeshiftoss/types';
+import type { StateOverride } from 'viem';
+export declare const withTimeout: <T>(promise: Promise<T>) => Promise<T>;
+export type GetMinimalStateOverrideArgs = {
+    sellAsset: Asset;
+    sellAmountCryptoBaseUnit: string;
+    from: string;
+    spenderAddress?: string;
+    value: string;
+};
+export declare const getMinimalStateOverride: ({ sellAsset, sellAmountCryptoBaseUnit, from: _from, spenderAddress, value, }: GetMinimalStateOverrideArgs) => Promise<StateOverride | undefined>;
+export type EstimateGasWithStateOverrideArgs = GetMinimalStateOverrideArgs & {
+    to: string;
+    data: string;
+    stateOverride?: StateOverride;
+};
+export declare const estimateGasWithStateOverride: ({ to, data, stateOverride: prebuiltStateOverride, ...overrideArgs }: EstimateGasWithStateOverrideArgs) => Promise<string>;

package/dist/esm/utils/evm/stateOverride.js

@@ -0,0 +1,302 @@
+import { assertGetViemClient } from '@shapeshiftoss/contracts';
+import { assertUnreachable, contractAddressOrUndefined } from '@shapeshiftoss/utils';
+import { encodeFunctionData, erc20Abi, getAddress, maxUint256, pad, parseEther, toHex } from 'viem';
+import { isNativeEvmAsset } from '../helpers.js';
+import { getAllowanceStorageSlot, getBalanceStorageSlot, getTokenAllowanceSlot, getTokenBalanceSlot, } from './storageSlots.js';
+// Fail fast - rates run inside the UI's 10s bulk budget and anything slower is degraded service
+// where retrying beats waiting (discovered slots are cached, so retries skip discovery)
+const ESTIMATION_TIMEOUT_MS = 3_000;
+// Large native balance for gas (1B is overkill but guarantees success on all chains)
+const NATIVE_BALANCE_OVERRIDE = parseEther('1000000000');
+// Probe sentinel: distinctive enough that a real balance/allowance can't collide with it, and
+// small enough to read back intact through uint96-packed storage (UNI/COMP-style tokens)
+const PROBE_SENTINEL = (1n << 88n) - 0xdecafbadn;
+// Slot numbers seen across known token implementations, swept per layout when access-list
+// discovery isn't available (51/52 covers the L2 storage-gap pattern)
+const CANDIDATE_SLOTS = {
+    solidity: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 51, 52],
+    vyper: [0, 1, 2, 3, 4, 5, 6],
+};
+// Public rpcs on long-tail chains rate limit aggressive fan-out, so sweep probes run in small
+// batches (which also lets a hit in an early batch skip the rest)
+const SWEEP_BATCH_SIZE = 6;
+const discoveredSlots = new Map();
+// Namespaced-storage tokens (ERC-7201 style) have no recoverable slot number - the touched slot
+// itself is cached instead, keyed per owner (and spender) since it embeds them
+const rawDiscoveredSlots = new Map();
+const failedSlotDiscoveries = new Map();
+const FAILED_DISCOVERY_TTL_MS = 60_000;
+export const withTimeout = async (promise) => {
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error('State override estimation timed out')), ESTIMATION_TIMEOUT_MS);
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+// The concrete slot for an owner (and spender) at a candidate slot number/layout
+const getStorageSlotFromLocator = (args) => {
+    const { owner, slotNumber, layout } = args;
+    switch (args.kind) {
+        case 'allowance':
+            return getAllowanceStorageSlot(owner, args.spender, slotNumber, layout);
+        case 'balance':
+            return getBalanceStorageSlot(owner, slotNumber, layout);
+        default:
+            return assertUnreachable(args);
+    }
+};
+// A slot guess only counts if a read through the override reflects the written sentinel
+const probeStorageSlot = async (args) => {
+    const { client, tokenAddress, owner, storageSlot } = args;
+    const stateOverride = [
+        {
+            address: tokenAddress,
+            stateDiff: [{ slot: storageSlot, value: pad(toHex(PROBE_SENTINEL)) }],
+        },
+    ];
+    try {
+        const result = await (() => {
+            switch (args.kind) {
+                case 'allowance': {
+                    return client.readContract({
+                        address: tokenAddress,
+                        abi: erc20Abi,
+                        functionName: 'allowance',
+                        args: [owner, args.spender],
+                        stateOverride,
+                    });
+                }
+                case 'balance': {
+                    return client.readContract({
+                        address: tokenAddress,
+                        abi: erc20Abi,
+                        functionName: 'balanceOf',
+                        args: [owner],
+                        stateOverride,
+                    });
+                }
+                default:
+                    return assertUnreachable(args);
+            }
+        })();
+        return result === PROBE_SENTINEL;
+    }
+    catch {
+        return false;
+    }
+};
+// Caps request gas so nodes that charge the sender up front accept the request. The account is
+// omitted entirely - the node's default (zero address) passes funds checks on gas-charging nodes
+// where an unfunded owner wouldn't, and the sender never affects which slots the read touches
+const ACCESS_LIST_GAS = 400000n;
+// Mapping slots are recovered by hashing candidate slot numbers against the touched set - 256
+// covers storage-gap layouts (slot 51/52 style) with plenty of headroom
+const MAX_MAPPED_SLOT = 256;
+// Raw-slot fallback probes are bounded - balanceOf/allowance reads touch a handful of slots at
+// most (implementation pointer, pause flags, the mapping value)
+const MAX_RAW_SLOT_PROBES = 8;
+// Ask the node which storage slots the read touches (eth_createAccessList) - supported on 23 of
+// our 32 EVM chains, everything else falls through to the candidate sweep
+const findTouchedSlots = async (args) => {
+    const { client, tokenAddress, owner } = args;
+    try {
+        const { accessList } = await client.createAccessList({
+            to: tokenAddress,
+            data: (() => {
+                switch (args.kind) {
+                    case 'allowance':
+                        return encodeFunctionData({
+                            abi: erc20Abi,
+                            functionName: 'allowance',
+                            args: [owner, args.spender],
+                        });
+                    case 'balance':
+                        return encodeFunctionData({ abi: erc20Abi, functionName: 'balanceOf', args: [owner] });
+                    default:
+                        return assertUnreachable(args);
+                }
+            })(),
+            gas: ACCESS_LIST_GAS,
+        });
+        // Delegatecall storage reads are attributed to the proxy, so the token's own entry holds them
+        return accessList
+            .filter(entry => entry.address.toLowerCase() === tokenAddress.toLowerCase())
+            .flatMap(entry => entry.storageKeys.map(storageKey => storageKey.toLowerCase()));
+    }
+    catch {
+        // Unsupported method or node quirk - the candidate sweep covers it
+        return [];
+    }
+};
+// Recover the mapping slot number by matching the touched slots against locally computed hashes -
+// handles arbitrary slot numbers and both hash orders without any further rpc calls
+const matchTouchedSlot = (args) => {
+    const touched = new Set(args.touchedSlots);
+    for (const layout of ['solidity', 'vyper']) {
+        for (let slotNumber = 0; slotNumber < MAX_MAPPED_SLOT; slotNumber++) {
+            if (touched.has(getStorageSlotFromLocator({ ...args, slotNumber, layout }))) {
+                return { slotNumber, layout };
+            }
+        }
+    }
+    return undefined;
+};
+// Find the concrete storage slot for the owner's balance/allowance: known-table guess first,
+// then access-list assisted discovery (slot-number recovery, raw-slot fallback for namespaced
+// storage), then a batched candidate sweep across both layouts. Results are cached per
+// chain+token (raw slots per owner).
+const discoverStorageSlot = async (args) => {
+    const { chainId, tokenAddress, owner, kind } = args;
+    const cacheKey = `${chainId}:${tokenAddress.toLowerCase()}:${kind}`;
+    const rawCacheKey = `${cacheKey}:${owner.toLowerCase()}${args.kind === 'allowance' ? `:${args.spender.toLowerCase()}` : ''}`;
+    const cached = discoveredSlots.get(cacheKey);
+    if (cached !== undefined)
+        return getStorageSlotFromLocator({ ...args, ...cached });
+    const cachedRaw = rawDiscoveredSlots.get(rawCacheKey);
+    if (cachedRaw !== undefined)
+        return cachedRaw;
+    // Failures re-probe only after the ttl - covers unknown layouts and rpcs without stateOverride
+    // support, which would otherwise pay the full candidate sweep on every rate refresh
+    const failedAt = failedSlotDiscoveries.get(cacheKey);
+    if (failedAt !== undefined && Date.now() - failedAt < FAILED_DISCOVERY_TTL_MS) {
+        throw new Error(`Unable to locate ${kind} storage slot for token ${tokenAddress}`);
+    }
+    const probeLocator = (locator) => probeStorageSlot({ ...args, storageSlot: getStorageSlotFromLocator({ ...args, ...locator }) });
+    const found = await (async () => {
+        const guess = {
+            slotNumber: kind === 'balance'
+                ? getTokenBalanceSlot(tokenAddress)
+                : getTokenAllowanceSlot(tokenAddress),
+            layout: 'solidity',
+        };
+        if (await probeLocator(guess))
+            return guess;
+        const touchedSlots = await findTouchedSlots(args);
+        const matched = matchTouchedSlot({ ...args, touchedSlots });
+        if (matched && (await probeLocator(matched)))
+            return matched;
+        // No recoverable slot number (namespaced storage) - probe the touched slots directly
+        for (const rawSlot of touchedSlots.slice(0, MAX_RAW_SLOT_PROBES)) {
+            if (await probeStorageSlot({ ...args, storageSlot: rawSlot }))
+                return { rawSlot };
+        }
+        const candidates = ['solidity', 'vyper']
+            .flatMap(layout => CANDIDATE_SLOTS[layout].map(slotNumber => ({ slotNumber, layout })))
+            .filter(candidate => !(candidate.layout === guess.layout && candidate.slotNumber === guess.slotNumber));
+        for (let i = 0; i < candidates.length; i += SWEEP_BATCH_SIZE) {
+            const batch = candidates.slice(i, i + SWEEP_BATCH_SIZE);
+            const results = await Promise.all(batch.map(probeLocator));
+            const hit = batch.find((_, j) => results[j]);
+            if (hit)
+                return hit;
+        }
+        return undefined;
+    })();
+    if (found === undefined) {
+        failedSlotDiscoveries.set(cacheKey, Date.now());
+        throw new Error(`Unable to locate ${kind} storage slot for token ${tokenAddress}`);
+    }
+    if ('rawSlot' in found) {
+        rawDiscoveredSlots.set(rawCacheKey, found.rawSlot);
+        return found.rawSlot;
+    }
+    discoveredSlots.set(cacheKey, found);
+    return getStorageSlotFromLocator({ ...args, ...found });
+};
+// Read the seller's actual balance/allowance and override only what's insufficient for the trade,
+// so estimation runs against state as close to execution time as possible
+export const getMinimalStateOverride = async ({ sellAsset, sellAmountCryptoBaseUnit, from: _from, spenderAddress, value, }) => {
+    const client = assertGetViemClient(sellAsset.chainId);
+    const from = getAddress(_from);
+    const valueBigInt = BigInt(value || '0');
+    const sellAmount = BigInt(sellAmountCryptoBaseUnit);
+    const contractAddress = isNativeEvmAsset(sellAsset.assetId)
+        ? undefined
+        : contractAddressOrUndefined(sellAsset.assetId);
+    const stateOverride = [];
+    const needsNativeBalance = async () => {
+        if (valueBigInt <= 0n)
+            return false;
+        const balance = await client.getBalance({ address: from });
+        return balance < valueBigInt;
+    };
+    if (!contractAddress) {
+        if (await needsNativeBalance()) {
+            stateOverride.push({ address: from, balance: NATIVE_BALANCE_OVERRIDE });
+        }
+        return stateOverride.length ? stateOverride : undefined;
+    }
+    const tokenAddress = getAddress(contractAddress);
+    const spender = spenderAddress ? getAddress(spenderAddress) : undefined;
+    const [allowance, balance, nativeBalanceShort] = await Promise.all([
+        spender
+            ? client.readContract({
+                address: tokenAddress,
+                abi: erc20Abi,
+                functionName: 'allowance',
+                args: [from, spender],
+            })
+            : Promise.resolve(maxUint256),
+        client.readContract({
+            address: tokenAddress,
+            abi: erc20Abi,
+            functionName: 'balanceOf',
+            args: [from],
+        }),
+        needsNativeBalance(),
+    ]);
+    if (nativeBalanceShort) {
+        stateOverride.push({ address: from, balance: NATIVE_BALANCE_OVERRIDE });
+    }
+    // Override to the larger of the sell amount and the probe sentinel - covers the trade with
+    // headroom while leaving high bits clear (a full maxUint256 write would set flag bits and
+    // packed-field neighbors, e.g. USDC's slot 9 blacklist bit or UNI's uint96 balances)
+    const overrideValue = pad(toHex(sellAmount > PROBE_SENTINEL ? sellAmount : PROBE_SENTINEL));
+    const stateDiff = (await Promise.all([
+        balance < sellAmount
+            ? discoverStorageSlot({
+                client,
+                chainId: sellAsset.chainId,
+                tokenAddress,
+                kind: 'balance',
+                owner: from,
+            }).then(slot => ({ slot, value: overrideValue }))
+            : undefined,
+        spender && allowance < sellAmount
+            ? discoverStorageSlot({
+                client,
+                chainId: sellAsset.chainId,
+                tokenAddress,
+                kind: 'allowance',
+                owner: from,
+                spender,
+            }).then(slot => ({ slot, value: overrideValue }))
+            : undefined,
+    ])).filter((diff) => diff !== undefined);
+    if (stateDiff.length)
+        stateOverride.push({ address: tokenAddress, stateDiff });
+    return stateOverride.length ? stateOverride : undefined;
+};
+// Estimate gas for a transaction the seller can't yet execute (unapproved/unfunded), overriding
+// only the missing state. Estimation runs on our own RPCs - the node applies the same engine over
+// the patched pre-state, so the only systematic delta is the unrealized allowance-decrement refund
+// (a few k gas high, conservative).
+export const estimateGasWithStateOverride = ({ to, data, stateOverride: prebuiltStateOverride, ...overrideArgs }) => withTimeout((async () => {
+    const client = assertGetViemClient(overrideArgs.sellAsset.chainId);
+    const stateOverride = prebuiltStateOverride ?? (await getMinimalStateOverride(overrideArgs));
+    const gasLimit = await client.estimateGas({
+        account: getAddress(overrideArgs.from),
+        to: getAddress(to),
+        data: data,
+        value: BigInt(overrideArgs.value || '0'),
+        ...(stateOverride ? { stateOverride } : {}),
+    });
+    return gasLimit.toString();
+})());

package/dist/{cjs/utils/tenderly → esm/utils/evm}/storageSlots.d.ts

@@ -1,8 +1,8 @@
 import type { Address, Hex } from 'viem';
-export declare const getBalanceStorageSlot: (userAddress: Address, balanceSlotNumber?: number) => Hex;
-export declare const getAllowanceStorageSlot: (ownerAddress: Address, spenderAddress: Address, allowanceSlotNumber?: number) => Hex;
+export type StorageLayout = 'solidity' | 'vyper';
+export declare const getBalanceStorageSlot: (userAddress: Address, balanceSlotNumber: number, layout?: StorageLayout) => Hex;
+export declare const getAllowanceStorageSlot: (ownerAddress: Address, spenderAddress: Address, allowanceSlotNumber: number, layout?: StorageLayout) => Hex;
 export declare const KNOWN_BALANCE_SLOTS: Record<string, number>;
 export declare const KNOWN_ALLOWANCE_SLOTS: Record<string, number>;
 export declare const getTokenBalanceSlot: (tokenAddress: Address) => number;
 export declare const getTokenAllowanceSlot: (tokenAddress: Address) => number;
-export declare const getMaxBalanceValue: (tokenAddress: Address) => Hex;