npm - @eulerxyz/euler-v2-sdk - Versions diffs - 0.2.6-beta → 0.2.8-beta - Mend

@eulerxyz/euler-v2-sdk 0.2.6-beta → 0.2.8-beta

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (129) hide show

package/dist/src/utils/stateOverrides/approvalOverrides.js CHANGED Viewed

@@ -1,6 +1,7 @@
 import { erc20Abi, encodePacked, getAddress, hexToBigInt, keccak256, maxUint256, toHex, } from "viem";
 import { encodeFunctionData } from "viem/utils";
 import { getAccessedSlots } from "./accessList.js";
+import { computeAllowanceSlot, fetchErc20SlotHints, getCachedSlotHints, } from "./slotHints.js";
 /**
  * Compute Permit2 allowance storage slots for the given approvals.
  *
@@ -30,7 +31,7 @@ export function computePermit2StateDiff(account, approvals) {
  * Traces allowance(account, permit2) to find candidate slots, then
  * tests each by overriding and re-reading to verify.
  */
-async function discoverAllowanceSlots(client, account, assets, permit2) {
+async function discoverAllowanceSlotsViaAccessList(client, account, assets, permit2) {
     const stateOverride = [];
     const valueHex = toHex(maxUint256, { size: 32 });
     for (const asset of assets) {
@@ -77,22 +78,30 @@ async function discoverAllowanceSlots(client, account, assets, permit2) {
     }
     return stateOverride;
 }
+const allowanceKey = (asset, spender) => `${getAddress(asset)}:${getAddress(spender)}`;
 /**
  * Generate state overrides for ERC20 approvals and Permit2 allowances.
  *
- * 1. Computes Permit2 storage slots deterministically (keccak256 mapping layout)
- * 2. Traces actual ERC20 approve() calls to discover approval storage slots
- *
- * @param client - viem PublicClient (must support eth_createAccessList and eth_call with state overrides)
- * @param account - token owner address
- * @param approvals - array of [assetAddress, spenderAddress] pairs
- * @param permit2Address - Permit2 contract address
+ * Resolution order, per asset:
+ *  1. Permit2 storage slots are always derivable cryptographically — no RPC.
+ *  2. Apply caller-supplied `walletAllowances[asset:spender]` — if `maxUint256`,
+ *     skip emitting an override entirely.
+ *  3. Use caller-supplied `slotHints[asset].allowanceSlotIndex` →
+ *     cryptographic slot, no RPC.
+ *  4. Use cached probed slot index (`fetchErc20SlotHints` cache) → same.
+ *  5. Probe sequentially via `fetchErc20SlotHints`.
+ *  6. Fall back to legacy `eth_createAccessList` discovery.
  */
-export async function getApprovalOverrides(client, account, approvals, permit2Address) {
+export async function getApprovalOverrides(client, account, approvals, permit2Address, options = {}) {
     if (approvals.length === 0)
         return [];
+    const chainId = client.chain?.id;
+    if (!chainId)
+        throw new Error("Client must have a chain configured");
     const stateOverride = [];
-    // 1. Permit2 allowance overrides (deterministic slot computation)
+    const { walletAllowances, slotHints } = options;
+    const valueHex = toHex(maxUint256, { size: 32 });
+    // 1. Permit2 allowance overrides (deterministic, no RPC).
     const permit2StateDiff = computePermit2StateDiff(account, approvals);
     if (permit2StateDiff.length > 0) {
         stateOverride.push({
@@ -100,12 +109,63 @@ export async function getApprovalOverrides(client, account, approvals, permit2Ad
             stateDiff: permit2StateDiff,
         });
     }
-    // 2. ERC20 approval overrides (discovered via eth_createAccessList)
-    const uniqueAssets = [
-        ...new Set(approvals.map(([asset]) => getAddress(asset))),
-    ];
-    const allowanceOverrides = await discoverAllowanceSlots(client, account, uniqueAssets, permit2Address);
-    stateOverride.push(...allowanceOverrides);
+    // Decide which assets still need an ERC20 allowance override.
+    const uniqueAssets = [];
+    const seen = new Set();
+    for (const [asset, spender] of approvals) {
+        const a = getAddress(asset);
+        // Token already approved → skip.
+        const supplied = walletAllowances?.[allowanceKey(a, spender)];
+        if (supplied !== undefined && supplied === maxUint256)
+            continue;
+        if (!seen.has(a)) {
+            seen.add(a);
+            uniqueAssets.push(a);
+        }
+    }
+    // Partition assets by which resolution path applies.
+    const fallbackAssets = [];
+    for (const asset of uniqueAssets) {
+        const callerHintIdx = slotHints?.[asset]?.allowanceSlotIndex;
+        const cachedIdx = getCachedSlotHints(chainId, asset)?.allowanceSlotIndex;
+        const idx = callerHintIdx ?? cachedIdx;
+        if (idx !== undefined) {
+            const slot = computeAllowanceSlot(account, permit2Address, idx);
+            stateOverride.push({
+                address: asset,
+                stateDiff: [{ slot, value: valueHex }],
+            });
+            continue;
+        }
+        fallbackAssets.push(asset);
+    }
+    // Probe via sequential scan first; only fall back to access-list for the
+    // rare token where that fails.
+    const stillUnknown = [];
+    for (const asset of fallbackAssets) {
+        try {
+            const hints = await fetchErc20SlotHints(client, asset, {
+                skipBalance: true,
+                allowanceSpender: permit2Address,
+            });
+            if (hints.allowanceSlotIndex !== undefined) {
+                const slot = computeAllowanceSlot(account, permit2Address, hints.allowanceSlotIndex);
+                stateOverride.push({
+                    address: asset,
+                    stateDiff: [{ slot, value: valueHex }],
+                });
+                continue;
+            }
+        }
+        catch (e) {
+            // fall through
+        }
+        stillUnknown.push(asset);
+    }
+    if (stillUnknown.length > 0) {
+        const legacy = await discoverAllowanceSlotsViaAccessList(client, account, stillUnknown, permit2Address);
+        stateOverride.push(...legacy);
+    }
     return stateOverride;
 }
 //# sourceMappingURL=approvalOverrides.js.map

package/dist/src/utils/stateOverrides/approvalOverrides.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"approvalOverrides.js","sourceRoot":"","sources":["../../../../src/utils/stateOverrides/approvalOverrides.ts"],"names":[],"mappings":"AAAA,OAAO,EAMN,QAAQ,EACR,YAAY,EACZ,UAAU,EACV,WAAW,EACX,SAAS,EACT,UAAU,EACV,KAAK,GACL,MAAM,MAAM,CAAC;AACd,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;~~AAEnD~~;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACtC,OAAgB,EAChB,SAA+B;IAE/B,MAAM,SAAS,GAAiB,EAAE,CAAC;IACnC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAO,CAAC;IAE5B,KAAK,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,SAAS,EAAE,CAAC;QAC1C,6HAA6H;QAC7H,kCAAkC;QAClC,MAAM,QAAQ,GAAG,SAAS,CACzB,YAAY,CAAC,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,CAChE,CAAC;QACF,MAAM,SAAS,GAAG,SAAS,CAC1B,YAAY,CACX,CAAC,SAAS,EAAE,SAAS,CAAC,EACtB,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC,CAC3C,CACD,CAAC;QACF,MAAM,WAAW,GAAG,SAAS,CAC5B,YAAY,CACX,CAAC,SAAS,EAAE,SAAS,CAAC,EACtB,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC,CAC9C,CACD,CAAC;QAEF,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;YAC5B,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;YACtB,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QACjE,CAAC;IACF,CAAC;IAED,OAAO,SAAS,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,~~sBAAsB~~,~~CACpC~~,MAAoB,EACpB,OAAgB,EAChB,MAAiB,EACjB,OAAgB;IAEhB,MAAM,aAAa,GAAkB,EAAE,CAAC;IACxC,MAAM,QAAQ,GAAG,KAAK,CAAC,UAAU,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IAEjD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC5B,IAAI,CAAC;YACJ,MAAM,aAAa,GAAG,MAAM,gBAAgB,CAAC,MAAM,EAAE;gBACpD,IAAI,EAAE,kBAAkB,CAAC;oBACxB,GAAG,EAAE,QAAQ;oBACb,YAAY,EAAE,WAAW;oBACzB,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC;iBACxB,CAAC;gBACF,EAAE,EAAE,KAAK;aACT,CAAC,CAAC;YAEH,MAAM,UAAU,GAAG,aAAa,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;YACxD,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAS;YAErD,6EAA6E;YAC7E,MAAM,WAAW,GAAG,MAAM,OAAO,CAAC,GAAG,CACpC,UAAU,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CACvB,MAAM;iBACJ,YAAY,CAAC;gBACb,GAAG,EAAE,QAAQ;gBACb,OAAO,EAAE,KAAK;gBACd,YAAY,EAAE,WAAW;gBACzB,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC;gBACxB,aAAa,EAAE;oBACd;wBACC,OAAO,EAAE,KAAK;wBACd,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;qBACtC;iBACD;aACD,CAAC;iBACD,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CACjB,CACD,CAAC;YAEF,MAAM,SAAS,GAAgC,EAAE,CAAC;YAClD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC5C,IAAI,WAAW,CAAC,CAAC,CAAC,KAAK,UAAU,EAAE,CAAC;oBACnC,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;gBAC3D,CAAC;YACF,CAAC;YAED,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC1B,aAAa,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;YACnD,CAAC;QACF,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACZ,OAAO,CAAC,IAAI,CACX,iDAAiD,KAAK,GAAG,EACzD,CAAC,CACD,CAAC;QACH,CAAC;IACF,CAAC;IAED,OAAO,aAAa,CAAC;AACtB,CAAC;~~AAED;;;;;;;;;;GAUG~~;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACzC,MAAoB,EACpB,OAAgB,EAChB,SAA+B,EAC/B,cAAuB;~~IAEvB~~,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEtC,MAAM,aAAa,GAAkB,EAAE,CAAC;~~IAExC~~,~~kEAAkE~~;~~IAClE~~,MAAM,gBAAgB,GAAG,uBAAuB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACrE,IAAI,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjC,aAAa,CAAC,IAAI,CAAC;YAClB,OAAO,EAAE,cAAc;YACvB,SAAS,EAAE,gBAAgB;SAC3B,CAAC,CAAC;IACJ,CAAC;IAED,~~oEAAoE~~;~~IACpE~~,MAAM,YAAY,GAAG;~~QACpB~~,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,~~UAAU~~,CAAC,KAAK,CAAC,CAAC,CAAC;~~KACzD~~,CAAC;~~IACF~~,MAAM,kBAAkB,GAAG,MAAM,~~sBAAsB~~,~~CACtD~~,MAAM,EACN,OAAO,EACP,YAAY,EACZ,cAAc,CACd,CAAC;~~IACF~~,aAAa,CAAC,IAAI,CAAC,GAAG,~~kBAAkB~~,CAAC,CAAC;~~IAE1C~~,OAAO,aAAa,CAAC;AACtB,CAAC"}
1	+ {"version":3,"file":"approvalOverrides.js","sourceRoot":"","sources":["../../../../src/utils/stateOverrides/approvalOverrides.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/stateOverrides/balanceOverrides.d.ts CHANGED Viewed

@@ -1,14 +1,33 @@
 import { type Address, type PublicClient, type StateOverride } from "viem";
+import { type SlotHints } from "./slotHints.js";
+export type GetBalanceOverridesOptions = {
+    /**
+     * Caller-supplied on-chain balances. When a token's balance here meets the
+     * required amount, the per-call `balanceOf` RPC is skipped and no override
+     * is emitted.
+     */
+    walletBalances?: Record<Address, bigint>;
+    /**
+     * Caller-supplied slot hints. When `balanceSlotIndex` is present for a
+     * token, the slot is computed cryptographically; access-list discovery is
+     * skipped. Missing entries fall back to `fetchErc20SlotHints` (sequential
+     * probing) before finally falling back to access-list discovery.
+     */
+    slotHints?: SlotHints;
+};
 /**
  * Generate state overrides that give `account` sufficient ERC20 balances.
  *
- * For each token where the on-chain balance is below the requested amount,
- * uses eth_createAccessList to discover the balanceOf storage slot, then builds
- * a stateDiff that sets that slot to the desired value.
+ * Resolution order, per token:
+ *  1. Use caller-supplied wallet balance when sufficient → no work.
+ *  2. Read `balanceOf` on-chain; skip if sufficient.
+ *  3. Use caller-supplied `balanceSlotIndex` → compute slot cryptographically.
+ *  4. Use cached probed slot index (`fetchErc20SlotHints` cache) → same.
+ *  5. Probe sequentially via `fetchErc20SlotHints` (small N `eth_call`s).
+ *  6. Fall back to legacy `eth_createAccessList` discovery + per-slot probe.
  *
- * @param client - viem PublicClient (must support eth_createAccessList and eth_call with state overrides)
- * @param account - address whose balance to override
- * @param tokens - array of [tokenAddress, requiredAmount]
+ * Steps 3–5 are dramatically cheaper than (6) and work for the vast majority
+ * of ERC20 layouts. Step 6 remains as a safety net for exotic packed storage.
  */
-export declare function getBalanceOverrides(client: PublicClient, account: Address, tokens: [Address, bigint][]): Promise<StateOverride>;
+export declare function getBalanceOverrides(client: PublicClient, account: Address, tokens: [Address, bigint][], options?: GetBalanceOverridesOptions): Promise<StateOverride>;
 //# sourceMappingURL=balanceOverrides.d.ts.map

package/dist/src/utils/stateOverrides/balanceOverrides.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"balanceOverrides.d.ts","sourceRoot":"","sources":["../../../../src/utils/stateOverrides/balanceOverrides.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,OAAO,EAEZ,KAAK,YAAY,EACjB,KAAK,aAAa,EAIlB,MAAM,MAAM,CAAC;~~AA6Dd;;;;;;;;;;GAUG~~;AACH,wBAAsB,mBAAmB,CACxC,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,~~GACzB~~,OAAO,CAAC,aAAa,CAAC,~~CAiGxB~~"}
1	+ {"version":3,"file":"balanceOverrides.d.ts","sourceRoot":"","sources":["../../../../src/utils/stateOverrides/balanceOverrides.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,OAAO,EAEZ,KAAK,YAAY,EACjB,KAAK,aAAa,EAIlB,MAAM,MAAM,CAAC;AAGd,OAAO,EAIN,KAAK,SAAS,EACd,MAAM,gBAAgB,CAAC;AA2DxB,MAAM,MAAM,0BAA0B,GAAG;IACxC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACzC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACxC,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,EAC3B,OAAO,GAAE,0BAA+B,GACtC,OAAO,CAAC,aAAa,CAAC,CAyJxB"}

package/dist/src/utils/stateOverrides/balanceOverrides.js CHANGED Viewed

@@ -1,6 +1,7 @@
 import { erc20Abi, getAddress, numberToHex, } from "viem";
 import { encodeFunctionData } from "viem/utils";
 import { getAccessedSlots } from "./accessList.js";
+import { computeBalanceSlot, fetchErc20SlotHints, getCachedSlotHints, } from "./slotHints.js";
 const balanceSlotCache = new Map();
 // wM token requires special storage layout handling
 const WM_CONTRACT = "0x437cc33344a0B27A429f795ff6B469C72698B291";
@@ -51,23 +52,40 @@ function findIndexOfLargest(arr) {
 /**
  * Generate state overrides that give `account` sufficient ERC20 balances.
  *
- * For each token where the on-chain balance is below the requested amount,
- * uses eth_createAccessList to discover the balanceOf storage slot, then builds
- * a stateDiff that sets that slot to the desired value.
+ * Resolution order, per token:
+ *  1. Use caller-supplied wallet balance when sufficient → no work.
+ *  2. Read `balanceOf` on-chain; skip if sufficient.
+ *  3. Use caller-supplied `balanceSlotIndex` → compute slot cryptographically.
+ *  4. Use cached probed slot index (`fetchErc20SlotHints` cache) → same.
+ *  5. Probe sequentially via `fetchErc20SlotHints` (small N `eth_call`s).
+ *  6. Fall back to legacy `eth_createAccessList` discovery + per-slot probe.
  *
- * @param client - viem PublicClient (must support eth_createAccessList and eth_call with state overrides)
- * @param account - address whose balance to override
- * @param tokens - array of [tokenAddress, requiredAmount]
+ * Steps 3–5 are dramatically cheaper than (6) and work for the vast majority
+ * of ERC20 layouts. Step 6 remains as a safety net for exotic packed storage.
  */
-export async function getBalanceOverrides(client, account, tokens) {
+export async function getBalanceOverrides(client, account, tokens, options = {}) {
     if (tokens.length === 0)
         return [];
     const chainId = client.chain?.id;
     if (!chainId)
         throw new Error("Client must have a chain configured");
     const stateOverride = [];
-    // Batch-read current balances
-    const currentBalances = await Promise.all(tokens.map(([token]) => client
+    const { walletBalances, slotHints } = options;
+    // Determine which tokens still need work after applying caller-supplied
+    // balances. Tokens with `walletBalances[token] >= requiredAmount` need
+    // nothing at all.
+    const remaining = [];
+    for (const [token, requiredAmount] of tokens) {
+        const supplied = walletBalances?.[getAddress(token)];
+        if (supplied !== undefined && supplied >= requiredAmount)
+            continue;
+        remaining.push([token, requiredAmount]);
+    }
+    if (remaining.length === 0)
+        return [];
+    // Batch-read current balances for the remaining set (those without a
+    // caller-supplied sufficient balance).
+    const currentBalances = await Promise.all(remaining.map(([token]) => client
         .readContract({
         abi: erc20Abi,
         address: token,
@@ -75,13 +93,26 @@ export async function getBalanceOverrides(client, account, tokens) {
         args: [account],
     })
         .catch(() => 0n)));
-    for (const [i, [token, requiredAmount]] of tokens.entries()) {
+    for (const [i, [token, requiredAmount]] of remaining.entries()) {
         const currentBalance = currentBalances[i] ?? 0n;
         if (currentBalance >= requiredAmount)
             continue;
-        const cacheKey = `${chainId}:${account}:${token}`;
+        const tokenAddr = getAddress(token);
         const valueHex = numberToHex(requiredAmount, { size: 32 });
-        // Check cache first
+        // Fast path: caller hint → cryptographic slot computation, no RPC.
+        const callerHintIdx = slotHints?.[tokenAddr]?.balanceSlotIndex;
+        if (callerHintIdx !== undefined && !shouldSkipCaching(token)) {
+            const slot = computeBalanceSlot(account, callerHintIdx);
+            stateOverride.push({
+                address: tokenAddr,
+                stateDiff: [{ slot, value: valueHex }],
+            });
+            continue;
+        }
+        // Per-account slot cache (legacy: keyed by chainId:owner:token, useful
+        // when discovery was done via access-list against this account
+        // directly).
+        const cacheKey = `${chainId}:${account}:${token}`;
         const cached = balanceSlotCache.get(cacheKey);
         if (cached && !shouldSkipCaching(token)) {
             stateOverride.push({
@@ -90,7 +121,35 @@ export async function getBalanceOverrides(client, account, tokens) {
             });
             continue;
         }
-        // Use eth_createAccessList to find candidate storage slots
+        // Token-keyed cache from `fetchErc20SlotHints` (owner-agnostic).
+        const probed = getCachedSlotHints(chainId, tokenAddr);
+        if (probed?.balanceSlotIndex !== undefined && !shouldSkipCaching(token)) {
+            const slot = computeBalanceSlot(account, probed.balanceSlotIndex);
+            stateOverride.push({
+                address: tokenAddr,
+                stateDiff: [{ slot, value: valueHex }],
+            });
+            continue;
+        }
+        // Sequential probing via fetchErc20SlotHints (cheap, owner-agnostic).
+        try {
+            const fresh = await fetchErc20SlotHints(client, tokenAddr, {
+                skipAllowance: true,
+            });
+            if (fresh.balanceSlotIndex !== undefined && !shouldSkipCaching(token)) {
+                const slot = computeBalanceSlot(account, fresh.balanceSlotIndex);
+                stateOverride.push({
+                    address: tokenAddr,
+                    stateDiff: [{ slot, value: valueHex }],
+                });
+                continue;
+            }
+        }
+        catch (e) {
+            // fall through to legacy access-list discovery
+        }
+        // Legacy fallback: eth_createAccessList-based discovery. Only reached
+        // for exotic storage layouts where the small-integer slot probe failed.
         try {
             const accessedSlots = await getAccessedSlots(client, {
                 data: encodeFunctionData({

package/dist/src/utils/stateOverrides/balanceOverrides.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"balanceOverrides.js","sourceRoot":"","sources":["../../../../src/utils/stateOverrides/balanceOverrides.ts"],"names":[],"mappings":"AAAA,OAAO,EAKN,QAAQ,EACR,UAAU,EACV,WAAW,GACX,MAAM,MAAM,CAAC;AACd,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;~~AAKnD~~,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAA6B,CAAC;AAE9D,oDAAoD;AACpD,MAAM,WAAW,GAAG,4CAA4C,CAAC;AAEjE,SAAS,iBAAiB,CAAC,KAAc;IACxC,OAAO,UAAU,CAAC,KAAK,CAAC,KAAK,UAAU,CAAC,WAAW,CAAC,CAAC;AACtD,CAAC;AAED,SAAS,kBAAkB,CAAC,aAA4B;IACvD,MAAM,MAAM,GAAkB,EAAE,CAAC;IAEjC,KAAK,MAAM,QAAQ,IAAI,aAAa,EAAE,CAAC;QACtC,IACC,UAAU,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,UAAU,CAAC,WAAW,CAAC;YACxD,QAAQ,CAAC,SAAS,EACjB,CAAC;YACF,mEAAmE;YACnE,MAAM,YAAY,GAAG,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;gBACxD,MAAM,YAAY,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;qBAClD,QAAQ,CAAC,EAAE,CAAC;qBACZ,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,EAAS,CAAC;gBAC7B,OAAO;oBACN,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,YAAY,EAAE;oBACxC;wBACC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;6BACjC,QAAQ,CAAC,EAAE,CAAC;6BACZ,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,EAAS;wBAC5B,KAAK,EAAE,YAAY;qBACnB;iBACD,CAAC;YACH,CAAC,CAAC,CAAC;YACH,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC,CAAC;QACvD,CAAC;aAAM,CAAC;YACP,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACvB,CAAC;IACF,CAAC;IAED,OAAO,MAAM,CAAC;AACf,CAAC;AAED,SAAS,kBAAkB,CAAC,GAAa;IACxC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC,CAAC;IAChC,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,QAAQ,GAAG,GAAG,CAAC,CAAC,CAAE,CAAC;IACvB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,IAAI,GAAG,CAAC,CAAC,CAAE,GAAG,QAAQ,EAAE,CAAC;YACxB,QAAQ,GAAG,GAAG,CAAC,CAAC,CAAE,CAAC;YACnB,QAAQ,GAAG,CAAC,CAAC;QACd,CAAC;IACF,CAAC;IACD,OAAO,QAAQ,CAAC;AACjB,CAAC;~~AAED;;;;;;;;;;GAUG~~;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACxC,MAAoB,EACpB,OAAgB,EAChB,MAA2B;~~IAE3B~~,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEnC,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC;IACjC,IAAI,CAAC,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IAErE,MAAM,aAAa,GAAkB,EAAE,CAAC;~~IAExC~~,~~8BAA8B~~;~~IAC9B~~,MAAM,eAAe,GAAG,MAAM,OAAO,CAAC,GAAG,CACxC,~~MAAM~~,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE,~~CACtB~~,MAAM;SACJ,YAAY,CAAC;QACb,GAAG,EAAE,QAAQ;QACb,OAAO,EAAE,KAAK;QACd,YAAY,EAAE,WAAW;QACzB,IAAI,EAAE,CAAC,OAAO,CAAC;KACf,CAAC;SACD,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CACjB,CACD,CAAC;IAEF,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC,IAAI,~~MAAM~~,CAAC,OAAO,EAAE,EAAE,CAAC;~~QAC7D~~,MAAM,cAAc,GAAG,eAAe,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAChD,IAAI,cAAc,IAAI,cAAc;YAAE,SAAS;QAE/C,MAAM,QAAQ,GAAG,GAAG,~~OAAO~~,IAAI,~~OAAO~~,IAAI,KAAK,~~EAAkB~~,CAAC;~~QAClE~~,MAAM,~~QAAQ~~,GAAG,~~WAAW~~,CAAC,~~cAAc~~,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;~~QAE3D~~,~~oBAAoB~~;~~QACpB~~,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC9C,IAAI,MAAM,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAC;YACzC,aAAa,CAAC,IAAI,CAAC;gBAClB,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;aACnD,CAAC,CAAC;YACH,SAAS;QACV,CAAC;QAED,~~2DAA2D~~;~~QAC3D~~,IAAI,CAAC;YACJ,MAAM,aAAa,GAAG,MAAM,gBAAgB,CAAC,MAAM,EAAE;gBACpD,IAAI,EAAE,kBAAkB,CAAC;oBACxB,GAAG,EAAE,QAAQ;oBACb,YAAY,EAAE,WAAW;oBACzB,IAAI,EAAE,CAAC,OAAO,CAAC;iBACf,CAAC;gBACF,EAAE,EAAE,KAAK;aACT,CAAC,CAAC;YAEH,MAAM,UAAU,GAAG,aAAa,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;YACxD,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAS;YAErD,MAAM,cAAc,GAAkB,UAAU,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;gBAC/D,OAAO,EAAE,UAAU,CAAC,KAAK,CAAC;gBAC1B,IAAI;aACJ,CAAC,CAAC,CAAC;YAEJ,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAS;YAE1C,kEAAkE;YAClE,MAAM,YAAY,GAAG,MAAM,OAAO,CAAC,GAAG,CACrC,cAAc,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAC3B,MAAM;iBACJ,YAAY,CAAC;gBACb,GAAG,EAAE,QAAQ;gBACb,OAAO,EAAE,KAAK;gBACd,YAAY,EAAE,WAAW;gBACzB,IAAI,EAAE,CAAC,OAAO,CAAC;gBACf,aAAa,EAAE;oBACd;wBACC,OAAO,EAAE,IAAI,CAAC,OAAO;wBACrB,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;qBACjD;iBACD;aACD,CAAC;iBACD,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CACjB,CACD,CAAC;YAEF,MAAM,OAAO,GAAG,kBAAkB,CAAC,YAAY,CAAC,CAAC;YACjD,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;YACzC,IAAI,QAAQ,EAAE,CAAC;gBACd,aAAa,CAAC,IAAI,CAAC;oBAClB,OAAO,EAAE,QAAQ,CAAC,OAAO;oBACzB,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;iBACrD,CAAC,CAAC;gBACH,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAC;oBAC/B,gBAAgB,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;gBAC1C,CAAC;YACF,CAAC;QACF,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACZ,OAAO,CAAC,IAAI,CAAC,gDAAgD,KAAK,GAAG,EAAE,CAAC,CAAC,CAAC;QAC3E,CAAC;IACF,CAAC;IAED,OAAO,kBAAkB,CAAC,aAAa,CAAC,CAAC;AAC1C,CAAC"}
1	+ {"version":3,"file":"balanceOverrides.js","sourceRoot":"","sources":["../../../../src/utils/stateOverrides/balanceOverrides.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/stateOverrides/getStateOverrides.d.ts CHANGED Viewed

@@ -1,10 +1,48 @@
 import { type Address, type PublicClient, type StateOverride } from "viem";
 import type { TransactionPlan } from "../../services/executionService/executionServiceTypes.js";
+import type { SlotHints } from "./slotHints.js";
 export type DeriveStateOverridesOptions = {
     /** Override the native (ETH) balance. Defaults to 1000 ETH. Set to 0n to skip. */
     nativeBalance?: bigint;
     /** Permit2 contract address. Required for approval overrides. */
     permit2Address: Address;
+    /**
+     * Skip ERC20 balance overrides entirely. Use when the caller has already
+     * validated that the account holds sufficient funds (e.g. UI form validation).
+     * No `balanceOf` reads, no slot probing — only allowance overrides + native
+     * balance + Permit2 deterministic overrides are emitted.
+     */
+    noBalanceOverride?: boolean;
+    /**
+     * Skip ERC20 allowance overrides entirely (the Permit2 deterministic
+     * overrides are still emitted because they cost no RPC). Use when the
+     * caller knows the account has already approved the relevant spenders.
+     */
+    noAllowanceOverride?: boolean;
+    /**
+     * Caller-supplied wallet snapshot. Lets the SDK skip per-call `balanceOf`
+     * and `allowance` reads when the supplied values already cover the
+     * requirement.
+     *
+     *  - `balances[token]`: when ≥ the plan's required amount, no override
+     *    is emitted and no `balanceOf` RPC fires.
+     *  - `allowances[token:spender]`: when `maxUint256`, no override is emitted
+     *    and no `allowance` RPC fires.
+     */
+    wallet?: {
+        balances?: Record<Address, bigint>;
+        allowances?: Record<`${Address}:${Address}`, bigint>;
+    };
+    /**
+     * Caller-supplied storage slot hints. When the `balanceSlotIndex` or
+     * `allowanceSlotIndex` is present for a token, the SDK computes the slot
+     * cryptographically and bypasses access-list discovery. Missing entries
+     * fall through to the SDK's own probing + final access-list fallback.
+     *
+     * Pre-fetch with `fetchErc20SlotHints` (exported from this module) to
+     * amortise discovery across many simulate/estimate calls.
+     */
+    slotHints?: SlotHints;
 };
 /**
  * Generate all state overrides needed to simulate a TransactionPlan

package/dist/src/utils/stateOverrides/getStateOverrides.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"getStateOverrides.d.ts","sourceRoot":"","sources":["../../../../src/utils/stateOverrides/getStateOverrides.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,OAAO,EACZ,KAAK,YAAY,EACjB,KAAK,aAAa,EAGlB,MAAM,MAAM,CAAC;AACd,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0DAA0D,CAAC;~~AAKhG~~,MAAM,MAAM,2BAA2B,GAAG;IACzC,kFAAkF;IAClF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,cAAc,EAAE,OAAO,CAAC;~~CACxB~~,CAAC;AAsDF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,oBAAoB,CACzC,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,2BAA2B,GAClC,OAAO,CAAC,aAAa,CAAC,~~CAsBxB~~"}
1	+ {"version":3,"file":"getStateOverrides.d.ts","sourceRoot":"","sources":["../../../../src/utils/stateOverrides/getStateOverrides.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,OAAO,EACZ,KAAK,YAAY,EACjB,KAAK,aAAa,EAGlB,MAAM,MAAM,CAAC;AACd,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0DAA0D,CAAC;AAIhG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,MAAM,MAAM,2BAA2B,GAAG;IACzC,kFAAkF;IAClF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,cAAc,EAAE,OAAO,CAAC;IACxB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE;QACR,QAAQ,CAAC,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACnC,UAAU,CAAC,EAAE,MAAM,CAAC,GAAG,OAAO,IAAI,OAAO,EAAE,EAAE,MAAM,CAAC,CAAC;KACrD,CAAC;IACF;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;CACtB,CAAC;AAsDF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,oBAAoB,CACzC,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,2BAA2B,GAClC,OAAO,CAAC,aAAa,CAAC,CAuCxB"}

package/dist/src/utils/stateOverrides/getStateOverrides.js CHANGED Viewed

@@ -67,12 +67,22 @@ function extractApprovalRequirements(plan, account) {
  * ```
  */
 export async function deriveStateOverrides(client, plan, account, options) {
-    const { nativeBalance = parseEther("1000"), permit2Address } = options;
-    const balanceTokens = extractBalanceRequirements(plan, account);
+    const { nativeBalance = parseEther("1000"), permit2Address, noBalanceOverride = false, noAllowanceOverride = false, wallet, slotHints, } = options;
+    const balanceTokens = noBalanceOverride
+        ? []
+        : extractBalanceRequirements(plan, account);
     const approvalPairs = extractApprovalRequirements(plan, account);
     const [balanceOverrides, approvalOverrides] = await Promise.all([
-        getBalanceOverrides(client, account, balanceTokens),
-        getApprovalOverrides(client, account, approvalPairs, permit2Address),
+        getBalanceOverrides(client, account, balanceTokens, {
+            walletBalances: wallet?.balances,
+            slotHints,
+        }),
+        noAllowanceOverride
+            ? Promise.resolve([])
+            : getApprovalOverrides(client, account, approvalPairs, permit2Address, {
+                walletAllowances: wallet?.allowances,
+                slotHints,
+            }),
     ]);
     const allOverrides = [];
     // Native balance override

package/dist/src/utils/stateOverrides/getStateOverrides.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"getStateOverrides.js","sourceRoot":"","sources":["../../../../src/utils/stateOverrides/getStateOverrides.ts"],"names":[],"mappings":"AAAA,OAAO,EAIN,UAAU,EACV,UAAU,GACV,MAAM,MAAM,CAAC;AAEd,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;~~AAS~~/D;;;;GAIG;AACH,SAAS,0BAA0B,CAClC,IAAqB,EACrB,OAAgB;IAEhB,MAAM,WAAW,GAAG,IAAI,GAAG,EAAmB,CAAC;IAE/C,KAAK,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,IAAI,KAAK,kBAAkB;YAAE,SAAS;QAC/C,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,UAAU,CAAC,OAAO,CAAC;YAAE,SAAS;QAE7D,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrC,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QAC7C,IAAI,IAAI,CAAC,MAAM,GAAG,OAAO,EAAE,CAAC;YAC3B,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACrC,CAAC;IACF,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC;AAC1C,CAAC;AAED;;;GAGG;AACH,SAAS,2BAA2B,CACnC,IAAqB,EACrB,OAAgB;IAEhB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,SAAS,GAAyB,EAAE,CAAC;IAE3C,KAAK,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,IAAI,KAAK,kBAAkB;YAAE,SAAS;QAC/C,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,UAAU,CAAC,OAAO,CAAC;YAAE,SAAS;QAE7D,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrC,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACzC,MAAM,GAAG,GAAG,GAAG,KAAK,IAAI,OAAO,EAAE,CAAC;QAClC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACpB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,SAAS,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;QAClC,CAAC;IACF,CAAC;IAED,OAAO,SAAS,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACzC,MAAoB,EACpB,IAAqB,EACrB,OAAgB,EAChB,OAAoC;IAEpC,MAAM,~~EAAE~~,aAAa,GAAG,UAAU,CAAC,MAAM,CAAC,~~EAAE~~,cAAc,~~EAAE~~,GAAG,OAAO,CAAC;~~IAEvE~~,MAAM,aAAa,GAAG,0BAA0B,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;~~IAChE~~,MAAM,aAAa,GAAG,2BAA2B,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAEjE,MAAM,CAAC,gBAAgB,EAAE,iBAAiB,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC/D,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,aAAa,CAAC;~~QACnD~~,oBAAoB,CAAC,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,cAAc,CAAC;~~KACpE~~,CAAC,CAAC;IAEH,MAAM,YAAY,GAAkB,EAAE,CAAC;IAEvC,0BAA0B;IAC1B,IAAI,aAAa,GAAG,EAAE,EAAE,CAAC;QACxB,YAAY,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC,CAAC;IACjE,CAAC;IAED,YAAY,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,CAAC;IACvC,YAAY,CAAC,IAAI,CAAC,GAAG,iBAAiB,CAAC,CAAC;IAExC,OAAO,mBAAmB,CAAC,YAAY,CAAC,CAAC;AAC1C,CAAC"}
1	+ {"version":3,"file":"getStateOverrides.js","sourceRoot":"","sources":["../../../../src/utils/stateOverrides/getStateOverrides.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/stateOverrides/index.d.ts CHANGED Viewed

@@ -1,5 +1,6 @@
 export { deriveStateOverrides, type DeriveStateOverridesOptions, } from "./getStateOverrides.js";
-export { getBalanceOverrides } from "./balanceOverrides.js";
-export { getApprovalOverrides, computePermit2StateDiff, } from "./approvalOverrides.js";
+export { getBalanceOverrides, type GetBalanceOverridesOptions, } from "./balanceOverrides.js";
+export { getApprovalOverrides, computePermit2StateDiff, type GetApprovalOverridesOptions, } from "./approvalOverrides.js";
 export { mergeStateOverrides } from "./mergeStateOverrides.js";
+export { fetchErc20SlotHints, fetchErc20SlotHintsBatch, computeBalanceSlot, computeAllowanceSlot, primeSlotHintsCache, getCachedSlotHints, type Erc20SlotHints, type SlotHints, type FetchSlotHintsOptions, } from "./slotHints.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/utils/stateOverrides/index.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/utils/stateOverrides/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,oBAAoB,EACpB,KAAK,2BAA2B,GAChC,MAAM,wBAAwB,CAAC;AAChC,OAAO,~~EAAE~~,mBAAmB,~~EAAE~~,MAAM,uBAAuB,CAAC;~~AAC5D~~,OAAO,EACN,oBAAoB,EACpB,uBAAuB,~~GACvB~~,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC"}
1	+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/utils/stateOverrides/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,oBAAoB,EACpB,KAAK,2BAA2B,GAChC,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACN,mBAAmB,EACnB,KAAK,0BAA0B,GAC/B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACN,oBAAoB,EACpB,uBAAuB,EACvB,KAAK,2BAA2B,GAChC,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EACN,mBAAmB,EACnB,wBAAwB,EACxB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAClB,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,qBAAqB,GAC1B,MAAM,gBAAgB,CAAC"}

package/dist/src/utils/stateOverrides/index.js CHANGED Viewed

@@ -1,5 +1,6 @@
 export { deriveStateOverrides, } from "./getStateOverrides.js";
-export { getBalanceOverrides } from "./balanceOverrides.js";
+export { getBalanceOverrides, } from "./balanceOverrides.js";
 export { getApprovalOverrides, computePermit2StateDiff, } from "./approvalOverrides.js";
 export { mergeStateOverrides } from "./mergeStateOverrides.js";
+export { fetchErc20SlotHints, fetchErc20SlotHintsBatch, computeBalanceSlot, computeAllowanceSlot, primeSlotHintsCache, getCachedSlotHints, } from "./slotHints.js";
 //# sourceMappingURL=index.js.map

package/dist/src/utils/stateOverrides/index.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/utils/stateOverrides/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,oBAAoB,GAEpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,~~EAAE~~,mBAAmB,~~EAAE~~,MAAM,uBAAuB,CAAC;~~AAC5D~~,OAAO,EACN,oBAAoB,EACpB,uBAAuB,~~GACvB~~,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC"}
1	+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/utils/stateOverrides/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,oBAAoB,GAEpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACN,mBAAmB,GAEnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACN,oBAAoB,EACpB,uBAAuB,GAEvB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EACN,mBAAmB,EACnB,wBAAwB,EACxB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,GAIlB,MAAM,gBAAgB,CAAC"}

package/dist/src/utils/stateOverrides/slotHints.d.ts ADDED Viewed

@@ -0,0 +1,78 @@
+import { type Address, type Hex, type PublicClient, toHex } from "viem";
+/**
+ * Discovered storage-slot indices for a single ERC20 token. Slot indices are
+ * the small-integer base index used in the contract's `mapping(address =>
+ * uint256) balances` / `mapping(address => mapping(address => uint256))
+ * allowances` declaration. They are owner-/spender-agnostic — the concrete
+ * storage slot is then derived cryptographically.
+ *
+ * Cache and reuse these across calls: they don't change for a deployed token.
+ */
+export type Erc20SlotHints = {
+    /** Slot index for the `balances` mapping (base storage slot). */
+    balanceSlotIndex?: bigint;
+    /** Slot index for the `allowance` mapping (outer base storage slot). */
+    allowanceSlotIndex?: bigint;
+};
+export type SlotHints = Record<Address, Erc20SlotHints>;
+export type FetchSlotHintsOptions = {
+    /** When `true`, do not probe for the balance slot. */
+    skipBalance?: boolean;
+    /** When `true`, do not probe for the allowance slot. */
+    skipAllowance?: boolean;
+    /** Spender for allowance probing. Defaults to the Permit2 address. */
+    allowanceSpender?: Address;
+    /** Max sequential base slot to scan (0..N). Defaults to 20. */
+    maxSequentialSlot?: number;
+    /** Extra non-sequential slot indices to try (e.g. known anomalies). */
+    extraSlotCandidates?: bigint[];
+};
+/**
+ * Compute the storage slot of `balances[owner]` in a Solidity-style
+ * `mapping(address => uint256)` at base slot `slotIndex`.
+ */
+export declare function computeBalanceSlot(owner: Address, slotIndex: bigint): Hex;
+/**
+ * Compute the storage slot of `allowance[owner][spender]` in a Solidity-style
+ * `mapping(address => mapping(address => uint256))` at base slot `slotIndex`.
+ */
+export declare function computeAllowanceSlot(owner: Address, spender: Address, slotIndex: bigint): Hex;
+/**
+ * Probe a single ERC20 token to discover its `balances` and `allowance` slot
+ * indices, by overriding sequential base-slot candidates and reading the
+ * value back.
+ *
+ * Strategy is intentionally simpler than `eth_createAccessList`-based
+ * discovery: most ERC20 layouts (OpenZeppelin, Solady, custom) use a small
+ * integer base slot. Sequential probing from 0 hits the answer in 1–3 RPC
+ * calls; access-list discovery costs an `eth_createAccessList` + per-candidate
+ * probe and isn't supported by all proxies.
+ *
+ * Results are cached module-scope by `chainId:token` (slot indices are
+ * owner-/spender-agnostic and immutable for a deployed token), so subsequent
+ * calls for the same token short-circuit to a Map lookup.
+ *
+ * @example
+ * ```ts
+ * const hints = await fetchErc20SlotHints(client, token, {
+ *   allowanceSpender: permit2Address,
+ * })
+ * // → { balanceSlotIndex: 0n, allowanceSlotIndex: 1n }
+ * ```
+ */
+export declare function fetchErc20SlotHints(client: PublicClient, token: Address, options?: FetchSlotHintsOptions): Promise<Erc20SlotHints>;
+/**
+ * Convenience batch wrapper for `fetchErc20SlotHints` over many tokens.
+ * Caller-side parallelism is preserved (one `Promise.all` over the inputs);
+ * the per-token cache means repeats are free.
+ */
+export declare function fetchErc20SlotHintsBatch(client: PublicClient, tokens: Address[], options?: FetchSlotHintsOptions): Promise<SlotHints>;
+/**
+ * Helper for callers who want to pre-seed the slot-hints cache from their own
+ * persistence layer (e.g. localStorage).
+ */
+export declare function primeSlotHintsCache(chainId: number, hints: Record<Address, Erc20SlotHints>): void;
+/** Helper used by deriveStateOverrides to look up a hint without re-probing. */
+export declare function getCachedSlotHints(chainId: number, token: Address): Erc20SlotHints | undefined;
+export { toHex };
+//# sourceMappingURL=slotHints.d.ts.map

package/dist/src/utils/stateOverrides/slotHints.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"slotHints.d.ts","sourceRoot":"","sources":["../../../../src/utils/stateOverrides/slotHints.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,OAAO,EACZ,KAAK,GAAG,EACR,KAAK,YAAY,EAQjB,KAAK,EACL,MAAM,MAAM,CAAC;AAId;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG;IAC5B,iEAAiE;IACjE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,wEAAwE;IACxE,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;AAExD,MAAM,MAAM,qBAAqB,GAAG;IACnC,sDAAsD;IACtD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,wDAAwD;IACxD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,+DAA+D;IAC/D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,uEAAuE;IACvE,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC/B,CAAC;AAUF;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,GAAG,CAIzE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CACnC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,GACf,GAAG,CAUL;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,mBAAmB,CACxC,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,qBAA0B,GACjC,OAAO,CAAC,cAAc,CAAC,CAoGzB;AAED;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC7C,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,OAAO,EAAE,EACjB,OAAO,GAAE,qBAA0B,GACjC,OAAO,CAAC,SAAS,CAAC,CASpB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,CAAC,OAAO,EAAE,cAAc,CAAC,QAKtC;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,CACjC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,OAAO,GACZ,cAAc,GAAG,SAAS,CAE5B;AAED,OAAO,EAAE,KAAK,EAAE,CAAC"}