otto-intel-mcp 0.1.2 → 0.1.4

package/dist/execution-account-gas-quote.js

@@ -0,0 +1,443 @@
+/** Read-only user-paid gas estimates. Neither the estimate nor its buffer is a fee cap or authority to send. */
+import { createHash } from 'node:crypto';
+import { performance } from 'node:perf_hooks';
+import { encodeAbiParameters, encodeFunctionData, getAddress, parseAbi, toHex } from 'viem';
+import { z } from 'zod';
+import { NATIVE_YIELD_USEROP_BATCH_ABI, NATIVE_YIELD_USEROP_ENTRY_POINT } from './native-yield-userop-definition.js';
+const UINT256_MAX = (1n << 256n) - 1n;
+const UINT120_MAX = (1n << 120n) - 1n;
+const TTL_MS = 30_000;
+const RESERVE_BPS = 2500n;
+const MAX_RESPONSE_BYTES = 65_536;
+const amount = z.string().max(78).regex(/^(0|[1-9][0-9]*)$/)
+    .refine(value => value.length <= 78 && /^(0|[1-9][0-9]*)$/.test(value) && BigInt(value) <= UINT256_MAX);
+const positive = amount.refine(value => value.length <= 78 && /^(0|[1-9][0-9]*)$/.test(value) && BigInt(value) > 0n);
+const time = z.number().int().positive().safe();
+const address = z.string().regex(/^0x[0-9a-fA-F]{40}$/).transform((value, context) => {
+    try {
+        if (/^0x0{40}$/i.test(value))
+            throw new Error();
+        return getAddress(value).toLowerCase();
+    }
+    catch {
+        context.addIssue({ code: 'custom', message: 'Invalid gas quote address' });
+        return z.NEVER;
+    }
+});
+const chainId = z.union([z.literal(1), z.literal(8453), z.literal(42161), z.literal(10), z.literal(137)]);
+// Public output schemas must be representable as JSON Schema. Normalization is
+// confined to input bindings; prepared quote addresses are already lowercase.
+const quoteAddress = z.string().regex(/^0x[0-9a-f]{40}$/).refine(value => !/^0x0{40}$/.test(value));
+const callsSchema = z.array(z.object({
+    to: address, data: z.string().max(262_146).regex(/^0x(?:[0-9a-fA-F]{2})*$/).transform(value => value.toLowerCase()),
+    value: amount,
+}).strict()).min(1).max(8);
+const bindingSchema = z.object({ account: address, chainId, entryPoint: address, calls: callsSchema }).strict();
+const priceSchema = z.object({
+    amountAtomic: positive, decimals: z.number().int().min(0).max(77), observedAtMs: time, expiresAtMs: time,
+}).strict().refine(value => value.expiresAtMs > value.observedAtMs);
+const sponsorSchema = z.object({
+    paymaster: address,
+    sponsorshipPolicyId: z.string().regex(/^[a-zA-Z0-9_-]{1,128}$/),
+}).strict();
+const sponsoredEstimateSchema = z.object({
+    kind: z.literal('estimate'), simulation: z.literal('paymaster-stub'), entryPointVersion: z.literal('0.6'),
+    paymaster: quoteAddress, sponsorshipPolicyId: z.string().regex(/^[a-zA-Z0-9_-]{1,128}$/),
+    paymasterAndDataCommitment: z.string().regex(/^[0-9a-f]{64}$/),
+    providerEstimate: z.object({
+        blockAnchor: z.literal('unanchored'), startedAtMs: time, completedAtMs: time,
+        elapsedMs: z.number().finite().nonnegative().max(TTL_MS),
+    }).strict(),
+    gas: z.object({
+        callGasLimit: positive, verificationGasLimit: positive, preVerificationGas: positive,
+        maxFeePerGasWei: positive, maxPriorityFeePerGasWei: amount,
+        verificationGasMultiplier: z.literal('3'), estimatedPrefundWei: positive,
+        reserveWei: positive, estimatedRequiredWei: positive, reserveBps: z.literal('2500'),
+    }).strict(),
+    estimatedGasCostUsdMicros: amount.optional(),
+}).strict();
+function ceil(numerator, denominator) {
+    return numerator / denominator + (numerator % denominator === 0n ? 0n : 1n);
+}
+function max(a, b) { return a > b ? a : b; }
+function min(a, b) { return a < b ? a : b; }
+/** The block anchor covers balance, deposit and nonce only. The bundler estimate has no block parameter. */
+export const ACCOUNT_GAS_QUOTE_SCHEMA = z.object({
+    version: z.literal(1), kind: z.literal('estimate'), payer: z.literal('user'),
+    account: quoteAddress, chainId, entryPoint: quoteAddress,
+    nativeAsset: z.object({ symbol: z.enum(['ETH', 'POL']), decimals: z.literal(18) }).strict(),
+    callsCommitment: z.string().regex(/^[0-9a-f]{64}$/), nonce: amount,
+    blockNumber: amount, blockHash: z.string().regex(/^0x[0-9a-f]{64}$/), blockTimestampMs: time,
+    observedAtMs: time, expiresAtMs: time,
+    simulation: z.literal('sender-balance-override'),
+    providerEstimate: z.object({
+        blockAnchor: z.literal('unanchored'), startedAtMs: time, completedAtMs: time,
+        elapsedMs: z.number().finite().nonnegative().max(TTL_MS),
+    }).strict(),
+    gas: z.object({
+        callGasLimit: positive, verificationGasLimit: positive, preVerificationGas: positive,
+        maxFeePerGasWei: positive, maxPriorityFeePerGasWei: amount,
+        estimatedPrefundWei: positive, reserveWei: positive,
+        /** Estimate plus buffer, not a maximum or an enforceable fee bound. */
+        estimatedRequiredWei: positive, reserveBps: z.literal('2500'),
+    }).strict(),
+    balance: z.object({
+        nativeWei: amount, entryPointDepositWei: amount, callValueWei: amount,
+        depositAppliedToGasWei: amount, walletGasRequirementWei: amount, nativeAvailableForGasWei: amount,
+        gasShortfallWei: amount, requiredNativeWei: amount,
+        /** Combined native funding shortfall, including call value principal. */
+        shortfallWei: amount,
+    }).strict(),
+    usdPrice: priceSchema.optional(), estimatedGasCostUsdMicros: amount.optional(),
+    /** Separate advisory sponsored simulation; never inferred from the self-pay estimate. */
+    sponsoredEstimate: sponsoredEstimateSchema.optional(),
+}).strict().superRefine((quote, context) => {
+    const fail = () => context.addIssue({ code: 'custom', message: 'Gas quote arithmetic or observation binding is inconsistent' });
+    try {
+        const gas = quote.gas, balance = quote.balance;
+        const limits = [gas.callGasLimit, gas.verificationGasLimit, gas.preVerificationGas].map(BigInt);
+        const fee = BigInt(gas.maxFeePerGasWei), priority = BigInt(gas.maxPriorityFeePerGasWei);
+        const prefund = limits.reduce((sum, value) => sum + value, 0n) * fee;
+        const reserve = ceil(prefund * RESERVE_BPS, 10000n), buffered = prefund + reserve;
+        const deposit = min(BigInt(balance.entryPointDepositWei), buffered), walletGas = buffered - deposit;
+        const available = max(BigInt(balance.nativeWei) - BigInt(balance.callValueWei), 0n);
+        const required = BigInt(balance.callValueWei) + walletGas;
+        if ([...limits, fee, priority].some(value => value > UINT120_MAX) || priority > fee ||
+            BigInt(quote.nonce) >= (1n << 64n) || quote.nativeAsset.symbol !== (quote.chainId === 137 ? 'POL' : 'ETH') ||
+            prefund !== BigInt(gas.estimatedPrefundWei) || reserve !== BigInt(gas.reserveWei) ||
+            buffered !== BigInt(gas.estimatedRequiredWei) || deposit !== BigInt(balance.depositAppliedToGasWei) ||
+            walletGas !== BigInt(balance.walletGasRequirementWei) || available !== BigInt(balance.nativeAvailableForGasWei) ||
+            max(walletGas - available, 0n) !== BigInt(balance.gasShortfallWei) || required !== BigInt(balance.requiredNativeWei) ||
+            max(required - BigInt(balance.nativeWei), 0n) !== BigInt(balance.shortfallWei) ||
+            quote.blockTimestampMs > quote.observedAtMs || quote.expiresAtMs <= quote.observedAtMs ||
+            quote.expiresAtMs > Math.min(quote.observedAtMs + TTL_MS, quote.blockTimestampMs + TTL_MS) ||
+            quote.providerEstimate.startedAtMs < quote.observedAtMs ||
+            quote.providerEstimate.completedAtMs < quote.providerEstimate.startedAtMs ||
+            quote.providerEstimate.completedAtMs >= quote.expiresAtMs ||
+            quote.providerEstimate.startedAtMs + quote.providerEstimate.elapsedMs >= quote.expiresAtMs)
+            fail();
+        if (quote.usdPrice) {
+            const price = quote.usdPrice;
+            if (price.observedAtMs > quote.observedAtMs || quote.expiresAtMs > price.expiresAtMs ||
+                quote.estimatedGasCostUsdMicros !== ceil(buffered * BigInt(price.amountAtomic) * 1000000n, 10n ** BigInt(18 + price.decimals)).toString())
+                fail();
+        }
+        else if (quote.estimatedGasCostUsdMicros !== undefined)
+            fail();
+        if (quote.sponsoredEstimate) {
+            const sponsored = quote.sponsoredEstimate, sponsoredGas = sponsored.gas, observation = sponsored.providerEstimate;
+            const call = BigInt(sponsoredGas.callGasLimit), verification = BigInt(sponsoredGas.verificationGasLimit), pre = BigInt(sponsoredGas.preVerificationGas);
+            const sponsoredPrefund = (call + 3n * verification + pre) * fee;
+            const sponsoredReserve = ceil(sponsoredPrefund * RESERVE_BPS, 10000n), sponsoredBuffered = sponsoredPrefund + sponsoredReserve;
+            if (quote.entryPoint !== NATIVE_YIELD_USEROP_ENTRY_POINT.toLowerCase() ||
+                [call, verification, pre].some(value => value > UINT120_MAX) ||
+                sponsoredGas.maxFeePerGasWei !== gas.maxFeePerGasWei || sponsoredGas.maxPriorityFeePerGasWei !== gas.maxPriorityFeePerGasWei ||
+                sponsoredGas.estimatedPrefundWei !== sponsoredPrefund.toString() || sponsoredGas.reserveWei !== sponsoredReserve.toString() ||
+                sponsoredGas.estimatedRequiredWei !== sponsoredBuffered.toString() || observation.startedAtMs < quote.providerEstimate.completedAtMs ||
+                observation.completedAtMs < observation.startedAtMs || observation.completedAtMs >= quote.expiresAtMs ||
+                observation.startedAtMs + observation.elapsedMs >= quote.expiresAtMs)
+                fail();
+            if (quote.usdPrice) {
+                if (sponsored.estimatedGasCostUsdMicros !== ceil(sponsoredBuffered * BigInt(quote.usdPrice.amountAtomic) * 1000000n, 10n ** BigInt(18 + quote.usdPrice.decimals)).toString())
+                    fail();
+            }
+            else if (sponsored.estimatedGasCostUsdMicros !== undefined)
+                fail();
+        }
+    }
+    catch {
+        fail();
+    }
+});
+export class AccountGasQuoteError extends Error {
+    code = 'ACCOUNT_GAS_QUOTE_UNAVAILABLE';
+    constructor(message = 'A fresh gas estimate is unavailable; refresh the review before continuing') {
+        super(message);
+        this.name = 'AccountGasQuoteError';
+    }
+}
+function unavailable() { throw new AccountGasQuoteError(); }
+class AccountGasQuoteClockError extends AccountGasQuoteError {
+}
+function invalidClock() { throw new AccountGasQuoteClockError(); }
+function parse(schema, value) {
+    const result = schema.safeParse(value);
+    if (!result.success)
+        unavailable();
+    return result.data;
+}
+function uint(value, bound = UINT256_MAX) {
+    if (typeof value !== 'bigint' || value < 0n || value > bound)
+        unavailable();
+    return value;
+}
+function clockWall(value) {
+    if (!Number.isSafeInteger(value) || value <= 0)
+        invalidClock();
+    return value;
+}
+function clockMono(value) {
+    if (!Number.isFinite(value) || value < 0)
+        invalidClock();
+    return value;
+}
+export function accountGasCallsCommitment(calls) {
+    const canonical = parse(callsSchema, calls);
+    return createHash('sha256').update(JSON.stringify({ domain: 'otto-account-gas-calls-v1', calls: canonical })).digest('hex');
+}
+const ENTRY_POINT_ABI = parseAbi([
+    'function balanceOf(address account) view returns(uint256)',
+    'function getNonce(address sender,uint192 key) view returns(uint256)',
+]);
+// The sole EOA-owner wrapper has fixed ABI overhead. All 65 signature bytes are
+// nonzero, conservatively covering signature calldata cost without signing anything.
+const DUMMY_SIGNATURE = encodeAbiParameters([
+    { type: 'tuple', components: [{ name: 'ownerIndex', type: 'uint8' }, { name: 'signatureData', type: 'bytes' }] },
+], [{ ownerIndex: 0, signatureData: `0x${'11'.repeat(32)}${'22'.repeat(32)}1b` }]);
+function providerUrl(value, expectedChainId) {
+    try {
+        const url = new URL(value);
+        const keys = [...url.searchParams.keys()];
+        if (url.protocol !== 'https:' || url.hostname !== 'api.pimlico.io' || url.port || url.username || url.password || url.hash ||
+            url.pathname !== `/v2/${expectedChainId}/rpc` || keys.length !== 1 || keys[0] !== 'apikey' || !url.searchParams.get('apikey'))
+            unavailable();
+        return url.href;
+    }
+    catch {
+        unavailable();
+    }
+}
+async function readProviderResponse(response) {
+    if (!response.ok || !response.body)
+        unavailable();
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            size += chunk.value.byteLength;
+            if (size > MAX_RESPONSE_BYTES) {
+                await reader.cancel();
+                unavailable();
+            }
+            chunks.push(chunk.value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+}
+const quantity = z.string().max(32).regex(/^0x[1-9a-fA-F][0-9a-fA-F]*$/)
+    .refine(value => /^0x[1-9a-fA-F][0-9a-fA-F]*$/.test(value) && BigInt(value) <= UINT120_MAX);
+const responseSchema = z.object({ jsonrpc: z.literal('2.0'), id: z.literal(1), result: z.object({
+        callGasLimit: quantity, verificationGasLimit: quantity, preVerificationGas: quantity, verificationGas: quantity.optional(),
+    }).strict().refine(value => value.verificationGas === undefined || BigInt(value.verificationGas) === BigInt(value.verificationGasLimit)),
+}).strict();
+const stubResponseSchema = z.object({ jsonrpc: z.literal('2.0'), id: z.literal(1), result: z.object({
+        paymasterAndData: z.string().min(42).max(8_194).regex(/^0x(?:[0-9a-fA-F]{2})+$/),
+        // ERC-7677 metadata is bounded and ignored. It never turns a stub into send authority.
+        isFinal: z.boolean().optional(),
+        sponsor: z.object({ name: z.string().max(128), icon: z.string().max(8_192).optional() }).strict().optional(),
+    }).strict() }).strict();
+const clockProofs = new WeakMap();
+function freeze(value) {
+    if (typeof value === 'object' && value !== null) {
+        Object.values(value).forEach(freeze);
+        Object.freeze(value);
+    }
+    return value;
+}
+/** No signer, paymaster sponsorship, submission, account authority or account code reads. */
+export async function prepareAccountGasQuote(input) {
+    try {
+        // Snapshot all caller-controlled bindings before the first await.
+        const binding = parse(bindingSchema, { account: input.account, chainId: input.chainId, entryPoint: input.entryPoint, calls: input.calls });
+        const price = input.usdPrice === undefined ? undefined : parse(priceSchema, input.usdPrice);
+        const sponsorResult = sponsorSchema.safeParse(input.sponsor);
+        const sponsor = sponsorResult.success ? sponsorResult.data : undefined;
+        const endpoint = providerUrl(input.paymasterUrl, binding.chainId);
+        const client = input.client, fetcher = input.fetch ?? globalThis.fetch;
+        const wall = input.nowMs ?? Date.now, mono = input.monotonicNowMs ?? (() => performance.now());
+        const startMono = clockMono(mono()), observedAtMs = clockWall(wall());
+        const [observedChain, block] = await Promise.all([client.getChainId(), client.getBlock({ blockTag: 'latest' })]);
+        if (observedChain !== binding.chainId || block.number === null || block.hash === null || !/^0x[0-9a-fA-F]{64}$/.test(block.hash))
+            unavailable();
+        const blockNumber = uint(block.number), timestamp = uint(block.timestamp);
+        if (timestamp > BigInt(Math.floor(Number.MAX_SAFE_INTEGER / 1_000)))
+            unavailable();
+        const blockTimestampMs = Number(timestamp) * 1_000;
+        if (blockTimestampMs > observedAtMs || blockTimestampMs + TTL_MS <= observedAtMs)
+            unavailable();
+        if (price && (price.observedAtMs > observedAtMs || price.expiresAtMs <= observedAtMs))
+            unavailable();
+        const expiresAtMs = Math.min(observedAtMs + TTL_MS, blockTimestampMs + TTL_MS, price?.expiresAtMs ?? Number.MAX_SAFE_INTEGER);
+        const [nativeBalance, depositBalance, operationNonce, fees] = await Promise.all([
+            client.getBalance({ address: binding.account, blockNumber }),
+            client.readContract({ address: binding.entryPoint, abi: ENTRY_POINT_ABI, functionName: 'balanceOf', args: [binding.account], blockNumber }),
+            client.readContract({ address: binding.entryPoint, abi: ENTRY_POINT_ABI, functionName: 'getNonce', args: [binding.account, 0n], blockNumber }),
+            client.estimateFeesPerGas({ chain: client.chain, type: 'eip1559' }),
+        ]);
+        const native = uint(nativeBalance), deposit = uint(depositBalance), nonce = uint(operationNonce, (1n << 64n) - 1n);
+        const maxFee = uint(fees.maxFeePerGas, UINT120_MAX), priorityFee = uint(fees.maxPriorityFeePerGas, UINT120_MAX);
+        if (maxFee === 0n || priorityFee > maxFee)
+            unavailable();
+        const callValue = binding.calls.reduce((sum, call) => sum + BigInt(call.value), 0n);
+        if (callValue > UINT256_MAX)
+            unavailable();
+        const userOperation = {
+            sender: binding.account, nonce: toHex(nonce), initCode: '0x',
+            callData: encodeFunctionData({ abi: NATIVE_YIELD_USEROP_BATCH_ABI, functionName: 'executeBatch',
+                args: [binding.calls.map(call => ({ target: call.to, value: BigInt(call.value), data: call.data }))] }),
+            callGasLimit: '0x0', verificationGasLimit: '0x0', preVerificationGas: '0x0',
+            maxFeePerGas: toHex(maxFee), maxPriorityFeePerGas: toHex(priorityFee), paymasterAndData: '0x', signature: DUMMY_SIGNATURE,
+        };
+        const providerStartMono = clockMono(mono()), providerStartWall = clockWall(wall());
+        if (providerStartMono < startMono || providerStartWall < observedAtMs)
+            unavailable();
+        const providerResponse = await fetcher(endpoint, {
+            method: 'POST', headers: { 'content-type': 'application/json' }, redirect: 'error', signal: AbortSignal.timeout(10_000),
+            body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'eth_estimateUserOperationGas',
+                params: [userOperation, binding.entryPoint, { [binding.account]: { balance: toHex(UINT256_MAX) } }] }),
+        });
+        const estimate = parse(responseSchema, await readProviderResponse(providerResponse)).result;
+        const providerEndWall = clockWall(wall()), providerEndMono = clockMono(mono());
+        if (providerEndWall < providerStartWall || providerEndMono < providerStartMono)
+            unavailable();
+        let latestObservedWall = providerEndWall, latestObservedMono = providerEndMono;
+        let sponsoredEstimate;
+        if (sponsor && binding.entryPoint === NATIVE_YIELD_USEROP_ENTRY_POINT.toLowerCase()) {
+            try {
+                const sponsorStartMono = clockMono(mono()), sponsorStartWall = clockWall(wall());
+                if (sponsorStartMono < providerEndMono || sponsorStartWall < providerEndWall)
+                    invalidClock();
+                latestObservedWall = sponsorStartWall;
+                latestObservedMono = sponsorStartMono;
+                // ERC-7677 stub data is for unsigned gas estimation. Never request final
+                // paymaster data or sponsorship signatures, and never expose this stub.
+                const { signature: _signature, paymasterAndData: _paymasterAndData, ...unsignedOperation } = userOperation;
+                const stubResponse = await fetcher(endpoint, {
+                    method: 'POST', headers: { 'content-type': 'application/json' }, redirect: 'error', signal: AbortSignal.timeout(10_000),
+                    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'pm_getPaymasterStubData',
+                        params: [unsignedOperation, binding.entryPoint, toHex(binding.chainId), { sponsorshipPolicyId: sponsor.sponsorshipPolicyId }] }),
+                });
+                const stub = parse(stubResponseSchema, await readProviderResponse(stubResponse)).result.paymasterAndData.toLowerCase();
+                if (stub.slice(0, 42) !== sponsor.paymaster)
+                    unavailable();
+                const stubEndWall = clockWall(wall()), stubEndMono = clockMono(mono());
+                if (stubEndWall < sponsorStartWall || stubEndMono < sponsorStartMono)
+                    invalidClock();
+                latestObservedWall = stubEndWall;
+                latestObservedMono = stubEndMono;
+                if (Math.max(stubEndWall, observedAtMs + stubEndMono - startMono) >= expiresAtMs)
+                    unavailable();
+                const sponsoredResponse = await fetcher(endpoint, {
+                    method: 'POST', headers: { 'content-type': 'application/json' }, redirect: 'error', signal: AbortSignal.timeout(10_000),
+                    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'eth_estimateUserOperationGas',
+                        params: [{ ...userOperation, paymasterAndData: stub }, binding.entryPoint, { [binding.account]: { balance: toHex(UINT256_MAX) } }] }),
+                });
+                const sponsoredGas = parse(responseSchema, await readProviderResponse(sponsoredResponse)).result;
+                const sponsorEndWall = clockWall(wall()), sponsorEndMono = clockMono(mono());
+                if (sponsorEndWall < stubEndWall || sponsorEndMono < stubEndMono)
+                    invalidClock();
+                latestObservedWall = sponsorEndWall;
+                latestObservedMono = sponsorEndMono;
+                const call = BigInt(sponsoredGas.callGasLimit), verification = BigInt(sponsoredGas.verificationGasLimit), pre = BigInt(sponsoredGas.preVerificationGas);
+                const sponsoredPrefund = (call + 3n * verification + pre) * maxFee;
+                const sponsoredReserve = ceil(sponsoredPrefund * RESERVE_BPS, 10000n), sponsoredBuffered = sponsoredPrefund + sponsoredReserve;
+                sponsoredEstimate = {
+                    kind: 'estimate', simulation: 'paymaster-stub', entryPointVersion: '0.6',
+                    paymaster: sponsor.paymaster, sponsorshipPolicyId: sponsor.sponsorshipPolicyId,
+                    paymasterAndDataCommitment: createHash('sha256').update('otto-account-gas-paymaster-stub-v1:' + stub).digest('hex'),
+                    providerEstimate: { blockAnchor: 'unanchored', startedAtMs: sponsorStartWall, completedAtMs: sponsorEndWall,
+                        elapsedMs: sponsorEndMono - sponsorStartMono },
+                    gas: { callGasLimit: call.toString(), verificationGasLimit: verification.toString(), preVerificationGas: pre.toString(),
+                        maxFeePerGasWei: maxFee.toString(), maxPriorityFeePerGasWei: priorityFee.toString(), verificationGasMultiplier: '3',
+                        estimatedPrefundWei: sponsoredPrefund.toString(), reserveWei: sponsoredReserve.toString(), estimatedRequiredWei: sponsoredBuffered.toString(), reserveBps: '2500' },
+                    ...(price ? { estimatedGasCostUsdMicros: ceil(sponsoredBuffered * BigInt(price.amountAtomic) * 1000000n, 10n ** BigInt(18 + price.decimals)).toString() } : {}),
+                };
+            }
+            catch (error) {
+                if (error instanceof AccountGasQuoteClockError)
+                    throw error;
+                // Sponsor availability cannot remove a still-fresh account-paid estimate.
+                // The final shared clock/anchor checks below still refuse global staleness.
+                sponsoredEstimate = undefined;
+            }
+        }
+        const [anchor, head, finalChain] = await Promise.all([
+            client.getBlock({ blockNumber }), client.getBlock({ blockTag: 'latest' }), client.getChainId(),
+        ]);
+        const actualWallAfter = clockWall(wall()), endMono = clockMono(mono());
+        if (actualWallAfter < latestObservedWall || endMono < latestObservedMono)
+            unavailable();
+        const effectiveAfter = Math.max(actualWallAfter, observedAtMs + endMono - startMono);
+        if (effectiveAfter >= expiresAtMs || finalChain !== binding.chainId || anchor.number !== blockNumber ||
+            anchor.hash?.toLowerCase() !== block.hash.toLowerCase() || anchor.timestamp !== timestamp ||
+            head.number === null || head.hash === null || !/^0x[0-9a-fA-F]{64}$/.test(head.hash) ||
+            head.number < blockNumber || head.timestamp < timestamp || head.timestamp * 1000n > BigInt(Math.floor(effectiveAfter)) ||
+            BigInt(Math.floor(effectiveAfter)) - head.timestamp * 1000n >= BigInt(TTL_MS) ||
+            (head.number === blockNumber && head.hash.toLowerCase() !== block.hash.toLowerCase()))
+            unavailable();
+        const callGas = BigInt(estimate.callGasLimit), verificationGas = BigInt(estimate.verificationGasLimit), preVerificationGas = BigInt(estimate.preVerificationGas);
+        const prefund = (callGas + verificationGas + preVerificationGas) * maxFee;
+        const reserve = ceil(prefund * RESERVE_BPS, 10000n), buffered = prefund + reserve;
+        const appliedDeposit = min(deposit, buffered), walletGas = buffered - appliedDeposit;
+        const availableForGas = max(native - callValue, 0n), requiredNative = callValue + walletGas;
+        const quote = parse(ACCOUNT_GAS_QUOTE_SCHEMA, {
+            version: 1, kind: 'estimate', payer: 'user', account: binding.account, chainId: binding.chainId, entryPoint: binding.entryPoint,
+            nativeAsset: { symbol: binding.chainId === 137 ? 'POL' : 'ETH', decimals: 18 },
+            callsCommitment: accountGasCallsCommitment(binding.calls), nonce: nonce.toString(),
+            blockNumber: blockNumber.toString(), blockHash: block.hash.toLowerCase(), blockTimestampMs, observedAtMs, expiresAtMs,
+            simulation: 'sender-balance-override',
+            providerEstimate: { blockAnchor: 'unanchored', startedAtMs: providerStartWall, completedAtMs: providerEndWall,
+                elapsedMs: providerEndMono - providerStartMono },
+            gas: { callGasLimit: callGas.toString(), verificationGasLimit: verificationGas.toString(), preVerificationGas: preVerificationGas.toString(),
+                maxFeePerGasWei: maxFee.toString(), maxPriorityFeePerGasWei: priorityFee.toString(),
+                estimatedPrefundWei: prefund.toString(), reserveWei: reserve.toString(), estimatedRequiredWei: buffered.toString(), reserveBps: '2500' },
+            balance: { nativeWei: native.toString(), entryPointDepositWei: deposit.toString(), callValueWei: callValue.toString(),
+                depositAppliedToGasWei: appliedDeposit.toString(), walletGasRequirementWei: walletGas.toString(), nativeAvailableForGasWei: availableForGas.toString(),
+                gasShortfallWei: max(walletGas - availableForGas, 0n).toString(), requiredNativeWei: requiredNative.toString(), shortfallWei: max(requiredNative - native, 0n).toString() },
+            ...(price ? { usdPrice: price, estimatedGasCostUsdMicros: ceil(buffered * BigInt(price.amountAtomic) * 1000000n, 10n ** BigInt(18 + price.decimals)).toString() } : {}),
+            ...(sponsoredEstimate ? { sponsoredEstimate } : {}),
+        });
+        freeze(quote);
+        clockProofs.set(quote, { endMono, effectiveAfter, actualWallAfter, monotonicNow: mono });
+        return quote;
+    }
+    catch (error) {
+        if (error instanceof AccountGasQuoteError)
+            throw error;
+        // Provider/config errors may include the API key, URL or request. Never propagate them.
+        unavailable();
+    }
+}
+/** Call synchronously at request start. Persisted copies retain wall-clock expiry but no process-local clock proof. */
+export function assertFreshAccountGasQuote(value, input, nowMs = Date.now()) {
+    const quote = parse(ACCOUNT_GAS_QUOTE_SCHEMA, value), binding = parse(bindingSchema, input);
+    let current = clockWall(nowMs);
+    const proof = clockProofs.get(value);
+    if (proof) {
+        const monotonicNow = clockMono(proof.monotonicNow());
+        if (current < proof.actualWallAfter || monotonicNow < proof.endMono)
+            unavailable();
+        current = Math.max(current, proof.effectiveAfter + monotonicNow - proof.endMono);
+    }
+    if (quote.account !== binding.account || quote.chainId !== binding.chainId || quote.entryPoint !== binding.entryPoint ||
+        quote.callsCommitment !== accountGasCallsCommitment(binding.calls) ||
+        quote.balance.callValueWei !== binding.calls.reduce((sum, call) => sum + BigInt(call.value), 0n).toString() ||
+        current < quote.observedAtMs || current < quote.providerEstimate.completedAtMs ||
+        current < (quote.sponsoredEstimate?.providerEstimate.completedAtMs ?? quote.providerEstimate.completedAtMs) ||
+        current >= quote.expiresAtMs)
+        unavailable();
+}
+//# sourceMappingURL=execution-account-gas-quote.js.map

package/dist/execution-account-gas-review.d.ts

@@ -0,0 +1,123 @@
+/** Review-only payer selection. Quotes are estimates; this module never authorizes a send. */
+import { z } from 'zod';
+import { type AccountGasQuote } from './execution-account-gas-quote.js';
+import { type SponsoredGasPolicyProof } from './execution-sponsored-gas-policy.js';
+export declare const ACCOUNT_GAS_REVIEW_SCHEMA: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    revision: z.ZodNumber;
+    payer: z.ZodEnum<{
+        account: "account";
+        sponsor: "sponsor";
+    }>;
+    sponsorStatus: z.ZodEnum<{
+        unavailable: "unavailable";
+        eligible: "eligible";
+        "above-limit": "above-limit";
+        "price-unavailable": "price-unavailable";
+    }>;
+    subsidyCapUsdMicros: z.ZodLiteral<"100000">;
+    quote: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        kind: z.ZodLiteral<"estimate">;
+        payer: z.ZodLiteral<"user">;
+        account: z.ZodString;
+        chainId: z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<8453>, z.ZodLiteral<42161>, z.ZodLiteral<10>, z.ZodLiteral<137>]>;
+        entryPoint: z.ZodString;
+        nativeAsset: z.ZodObject<{
+            symbol: z.ZodEnum<{
+                ETH: "ETH";
+                POL: "POL";
+            }>;
+            decimals: z.ZodLiteral<18>;
+        }, z.core.$strict>;
+        callsCommitment: z.ZodString;
+        nonce: z.ZodString;
+        blockNumber: z.ZodString;
+        blockHash: z.ZodString;
+        blockTimestampMs: z.ZodNumber;
+        observedAtMs: z.ZodNumber;
+        expiresAtMs: z.ZodNumber;
+        simulation: z.ZodLiteral<"sender-balance-override">;
+        providerEstimate: z.ZodObject<{
+            blockAnchor: z.ZodLiteral<"unanchored">;
+            startedAtMs: z.ZodNumber;
+            completedAtMs: z.ZodNumber;
+            elapsedMs: z.ZodNumber;
+        }, z.core.$strict>;
+        gas: z.ZodObject<{
+            callGasLimit: z.ZodString;
+            verificationGasLimit: z.ZodString;
+            preVerificationGas: z.ZodString;
+            maxFeePerGasWei: z.ZodString;
+            maxPriorityFeePerGasWei: z.ZodString;
+            estimatedPrefundWei: z.ZodString;
+            reserveWei: z.ZodString;
+            estimatedRequiredWei: z.ZodString;
+            reserveBps: z.ZodLiteral<"2500">;
+        }, z.core.$strict>;
+        balance: z.ZodObject<{
+            nativeWei: z.ZodString;
+            entryPointDepositWei: z.ZodString;
+            callValueWei: z.ZodString;
+            depositAppliedToGasWei: z.ZodString;
+            walletGasRequirementWei: z.ZodString;
+            nativeAvailableForGasWei: z.ZodString;
+            gasShortfallWei: z.ZodString;
+            requiredNativeWei: z.ZodString;
+            shortfallWei: z.ZodString;
+        }, z.core.$strict>;
+        usdPrice: z.ZodOptional<z.ZodObject<{
+            amountAtomic: z.ZodString;
+            decimals: z.ZodNumber;
+            observedAtMs: z.ZodNumber;
+            expiresAtMs: z.ZodNumber;
+        }, z.core.$strict>>;
+        estimatedGasCostUsdMicros: z.ZodOptional<z.ZodString>;
+        sponsoredEstimate: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodLiteral<"estimate">;
+            simulation: z.ZodLiteral<"paymaster-stub">;
+            entryPointVersion: z.ZodLiteral<"0.6">;
+            paymaster: z.ZodString;
+            sponsorshipPolicyId: z.ZodString;
+            paymasterAndDataCommitment: z.ZodString;
+            providerEstimate: z.ZodObject<{
+                blockAnchor: z.ZodLiteral<"unanchored">;
+                startedAtMs: z.ZodNumber;
+                completedAtMs: z.ZodNumber;
+                elapsedMs: z.ZodNumber;
+            }, z.core.$strict>;
+            gas: z.ZodObject<{
+                callGasLimit: z.ZodString;
+                verificationGasLimit: z.ZodString;
+                preVerificationGas: z.ZodString;
+                maxFeePerGasWei: z.ZodString;
+                maxPriorityFeePerGasWei: z.ZodString;
+                verificationGasMultiplier: z.ZodLiteral<"3">;
+                estimatedPrefundWei: z.ZodString;
+                reserveWei: z.ZodString;
+                estimatedRequiredWei: z.ZodString;
+                reserveBps: z.ZodLiteral<"2500">;
+            }, z.core.$strict>;
+            estimatedGasCostUsdMicros: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type AccountGasReview = z.infer<typeof ACCOUNT_GAS_REVIEW_SCHEMA>;
+export type AccountGasPreference = 'auto' | 'sponsor' | 'account';
+export declare class AccountGasReviewError extends Error {
+    readonly code: 'ACCOUNT_GAS_REVIEW_INVALID' | 'ACCOUNT_GAS_REVIEW_STALE' | 'ACCOUNT_GAS_SPONSOR_INELIGIBLE';
+    constructor(code: 'ACCOUNT_GAS_REVIEW_INVALID' | 'ACCOUNT_GAS_REVIEW_STALE' | 'ACCOUNT_GAS_SPONSOR_INELIGIBLE');
+}
+export declare function createAccountGasReview(input: {
+    readonly quote: AccountGasQuote;
+    readonly previousRevision?: number;
+    readonly preference: AccountGasPreference;
+    /** Already validated by the policy reader. This snapshot is eligibility evidence only. */
+    readonly sponsorPolicy?: SponsoredGasPolicyProof;
+    readonly nowMs: number;
+}): Readonly<AccountGasReview>;
+/** A fresh review is necessary, but caller-owned consent and live final checks remain required. */
+export declare function accountGasReviewCanSubmit(input: AccountGasReview, nowMs: number): boolean;
+/** Native-currency review tolerates fee movement within its displayed 25% funding cushion.
+ * This comparison is a consent threshold, not an enforceable maximum network fee. */
+export declare function accountGasReviewNeedsRenewal(previous: AccountGasReview, fresh: AccountGasReview): boolean;