otto-intel-mcp 0.1.3 → 0.1.4

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

@@ -0,0 +1,104 @@
+/** Review-only payer selection. Quotes are estimates; this module never authorizes a send. */
+import { z } from 'zod';
+import { ACCOUNT_GAS_QUOTE_SCHEMA } from './execution-account-gas-quote.js';
+import { SPONSORED_GAS_POLICY_MAX_AGE_MS, SPONSORED_INITIAL_GAS_CAP_USD_MICROS } from './execution-sponsored-gas-policy.js';
+const CAP_MICROS = BigInt(SPONSORED_INITIAL_GAS_CAP_USD_MICROS);
+const payerSchema = z.enum(['sponsor', 'account']);
+const statusSchema = z.enum(['eligible', 'above-limit', 'unavailable', 'price-unavailable']);
+export const ACCOUNT_GAS_REVIEW_SCHEMA = z.object({
+    version: z.literal(1), revision: z.number().int().positive().safe(),
+    payer: payerSchema, sponsorStatus: statusSchema,
+    subsidyCapUsdMicros: z.literal('100000'), quote: ACCOUNT_GAS_QUOTE_SCHEMA,
+}).strict().superRefine((review, context) => {
+    const invalid = () => context.addIssue({ code: 'custom', message: 'Gas payer and sponsorship status do not match the estimate' });
+    try {
+        const cost = review.quote.sponsoredEstimate?.estimatedGasCostUsdMicros;
+        if ((review.payer === 'sponsor' && review.sponsorStatus !== 'eligible') ||
+            (review.sponsorStatus === 'eligible' && (cost === undefined || BigInt(cost) > CAP_MICROS)) ||
+            (review.sponsorStatus === 'price-unavailable' && (!review.quote.sponsoredEstimate || cost !== undefined)) ||
+            (review.sponsorStatus === 'above-limit' && cost === undefined))
+            invalid();
+    }
+    catch {
+        invalid();
+    }
+});
+export class AccountGasReviewError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = 'AccountGasReviewError';
+    }
+}
+function refuse(code) { throw new AccountGasReviewError(code); }
+function quoteIsCurrent(quote, nowMs) {
+    return Number.isSafeInteger(nowMs) && nowMs >= quote.observedAtMs &&
+        nowMs >= quote.providerEstimate.completedAtMs &&
+        nowMs >= (quote.sponsoredEstimate?.providerEstimate.completedAtMs ?? quote.providerEstimate.completedAtMs) &&
+        nowMs < quote.expiresAtMs;
+}
+function policyIsCurrent(policy, quote, nowMs) {
+    return !!policy && policy.chainId === quote.chainId && typeof policy.sponsorshipPolicyId === 'string' && /^[a-zA-Z0-9_-]{1,128}$/.test(policy.sponsorshipPolicyId) &&
+        Number.isSafeInteger(policy.maximumGasCostUsdMicros) && policy.maximumGasCostUsdMicros >= 10_000 &&
+        policy.maximumGasCostUsdMicros <= SPONSORED_INITIAL_GAS_CAP_USD_MICROS && policy.maximumGasCostUsdMicros % 10_000 === 0 &&
+        Number.isSafeInteger(policy.checkedAtMs) && Number.isSafeInteger(policy.validUntilMs) &&
+        policy.checkedAtMs >= 0 && policy.checkedAtMs <= nowMs && nowMs < policy.validUntilMs &&
+        policy.validUntilMs <= policy.checkedAtMs + SPONSORED_GAS_POLICY_MAX_AGE_MS;
+}
+export function createAccountGasReview(input) {
+    const parsed = ACCOUNT_GAS_QUOTE_SCHEMA.safeParse(input.quote), previousRevision = input.previousRevision ?? 0;
+    if (!parsed.success || !Number.isSafeInteger(previousRevision) || previousRevision < 0 || previousRevision >= Number.MAX_SAFE_INTEGER ||
+        !['auto', 'sponsor', 'account'].includes(input.preference))
+        return refuse('ACCOUNT_GAS_REVIEW_INVALID');
+    const quote = parsed.data;
+    if (!quoteIsCurrent(quote, input.nowMs))
+        return refuse('ACCOUNT_GAS_REVIEW_STALE');
+    const currentPolicy = policyIsCurrent(input.sponsorPolicy, quote, input.nowMs) ? input.sponsorPolicy : undefined;
+    const sponsored = quote.sponsoredEstimate;
+    const cost = sponsored?.estimatedGasCostUsdMicros;
+    const sponsorStatus = !currentPolicy || !sponsored || sponsored.sponsorshipPolicyId !== currentPolicy.sponsorshipPolicyId
+        ? 'unavailable' : cost === undefined ? 'price-unavailable'
+        : BigInt(cost) > CAP_MICROS || BigInt(cost) > BigInt(currentPolicy.maximumGasCostUsdMicros) ? 'above-limit' : 'eligible';
+    if (input.preference === 'sponsor' && sponsorStatus !== 'eligible')
+        return refuse('ACCOUNT_GAS_SPONSOR_INELIGIBLE');
+    const payer = input.preference === 'account' ? 'account' : sponsorStatus === 'eligible' ? 'sponsor' : 'account';
+    const review = ACCOUNT_GAS_REVIEW_SCHEMA.safeParse({ version: 1, revision: previousRevision + 1, payer, sponsorStatus,
+        subsidyCapUsdMicros: '100000', quote });
+    if (!review.success)
+        return refuse('ACCOUNT_GAS_REVIEW_INVALID');
+    return Object.freeze(review.data);
+}
+/** A fresh review is necessary, but caller-owned consent and live final checks remain required. */
+export function accountGasReviewCanSubmit(input, nowMs) {
+    const parsed = ACCOUNT_GAS_REVIEW_SCHEMA.safeParse(input);
+    return parsed.success && quoteIsCurrent(parsed.data.quote, nowMs) &&
+        (parsed.data.payer === 'sponsor' || parsed.data.quote.balance.shortfallWei === '0');
+}
+/** 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 function accountGasReviewNeedsRenewal(previous, fresh) {
+    const oldResult = ACCOUNT_GAS_REVIEW_SCHEMA.safeParse(previous), newResult = ACCOUNT_GAS_REVIEW_SCHEMA.safeParse(fresh);
+    if (!oldResult.success || !newResult.success)
+        return true;
+    const oldReview = oldResult.data, newReview = newResult.data, oldQuote = oldReview.quote, newQuote = newReview.quote;
+    if (newReview.revision < oldReview.revision || oldReview.payer !== newReview.payer ||
+        oldQuote.chainId !== newQuote.chainId || oldQuote.account.toLowerCase() !== newQuote.account.toLowerCase() ||
+        oldQuote.entryPoint.toLowerCase() !== newQuote.entryPoint.toLowerCase() || oldQuote.callsCommitment !== newQuote.callsCommitment ||
+        oldQuote.nonce !== newQuote.nonce)
+        return true;
+    // Otto remains the payer while fresh sponsorship is eligible under its policy cap.
+    if (oldReview.payer === 'sponsor')
+        return newReview.sponsorStatus !== 'eligible';
+    if (BigInt(newQuote.gas.estimatedPrefundWei) > BigInt(oldQuote.gas.estimatedRequiredWei))
+        return true;
+    const oldBufferedUsd = oldQuote.estimatedGasCostUsdMicros, newPrice = newQuote.usdPrice;
+    // USD is secondary to the native estimate, so losing its price does not invalidate native consent.
+    if (oldBufferedUsd === undefined || !newPrice)
+        return false;
+    const numerator = BigInt(newQuote.gas.estimatedPrefundWei) * BigInt(newPrice.amountAtomic) * 1000000n;
+    const denominator = 10n ** BigInt(18 + newPrice.decimals);
+    const freshPrefundUsd = numerator / denominator + (numerator % denominator === 0n ? 0n : 1n);
+    return freshPrefundUsd > BigInt(oldBufferedUsd);
+}
+//# sourceMappingURL=execution-account-gas-review.js.map

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

@@ -0,0 +1,33 @@
+import { type SponsoredGasPolicyProof } from './execution-sponsored-gas-policy.js';
+/** Read-only fee planning for the existing CDP UserOperation transport. Estimates grant no signing authority. */
+import { type PublicClient } from 'viem';
+import { prepareAccountGasQuote, type AccountGasQuote } from './execution-account-gas-quote.js';
+import { type AccountGasReview } from './execution-account-gas-review.js';
+import { type SponsoredActivation } from './execution-sponsored-definition.js';
+import type { createSponsoredCdpTransport, SponsoredCall, SponsoredChainId, SponsoredProviderConfig } from './execution-sponsored-transport.js';
+export interface AccountGasOperation {
+    readonly gasReview?: AccountGasReview;
+    readonly context: {
+        readonly account: string;
+        readonly chainId: SponsoredChainId;
+        readonly activation: SponsoredActivation;
+    };
+}
+export declare class AccountGasReviewError extends Error {
+    readonly code: 'ACCOUNT_GAS_REVIEW_UNAVAILABLE' | 'ACCOUNT_GAS_REVIEW_REQUIRED' | 'ACCOUNT_GAS_REVIEW_CHANGED' | 'ACCOUNT_GAS_FUNDING_REQUIRED';
+    constructor(code: 'ACCOUNT_GAS_REVIEW_UNAVAILABLE' | 'ACCOUNT_GAS_REVIEW_REQUIRED' | 'ACCOUNT_GAS_REVIEW_CHANGED' | 'ACCOUNT_GAS_FUNDING_REQUIRED');
+}
+export declare class AccountGasPaymentRuntime {
+    private readonly clients;
+    private readonly providers;
+    private readonly transport;
+    private readonly now;
+    private readonly quote;
+    private readonly verifiedQuotes;
+    private readonly freshQuotes;
+    constructor(clients: Readonly<Partial<Record<SponsoredChainId, PublicClient>>>, providers: readonly SponsoredProviderConfig[], transport: ReturnType<typeof createSponsoredCdpTransport>, now?: () => number, quote?: typeof prepareAccountGasQuote);
+    review(operation: AccountGasOperation, calls: readonly SponsoredCall[], preference?: 'auto' | 'sponsor' | 'account', checkSponsor?: boolean): Promise<AccountGasReview>;
+    private assertPilotExposure;
+    revalidate(operation: AccountGasOperation, calls: readonly SponsoredCall[]): Promise<AccountGasQuote | undefined>;
+    assertFresh(operation: AccountGasOperation, calls: readonly SponsoredCall[], quote?: AccountGasQuote, gasPolicy?: SponsoredGasPolicyProof): void;
+}

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

@@ -0,0 +1,131 @@
+import { assertSponsoredGasPolicyCurrent } from './execution-sponsored-gas-policy.js';
+/** Read-only fee planning for the existing CDP UserOperation transport. Estimates grant no signing authority. */
+import { getAddress, parseAbi } from 'viem';
+import { prepareAccountGasQuote, assertFreshAccountGasQuote } from './execution-account-gas-quote.js';
+import { createAccountGasReview, accountGasReviewCanSubmit, accountGasReviewNeedsRenewal } from './execution-account-gas-review.js';
+import { sponsoredChainTerms } from './execution-sponsored-definition.js';
+export class AccountGasReviewError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = 'AccountGasReviewError';
+    }
+}
+const FEED_ABI = parseAbi([
+    'function decimals() view returns (uint8)',
+    'function latestRoundData() view returns (uint80 roundId,int256 answer,uint256 startedAt,uint256 updatedAt,uint80 answeredInRound)',
+]);
+/** Source-pinned oracle data is only an advisory conversion. Pimlico independently enforces the subsidy limit. */
+async function gasUsdPrice(client, activation, chainId, now) {
+    const feed = sponsoredChainTerms(activation, chainId).nativeGasUsdFeed;
+    if (!feed)
+        return undefined;
+    try {
+        const block = await client.getBlock({ blockTag: 'latest' });
+        if (block.number === null || !block.hash)
+            return undefined;
+        const [decimals, round] = await Promise.all([
+            client.readContract({ address: getAddress(feed.address), abi: FEED_ABI, functionName: 'decimals', blockNumber: block.number }),
+            client.readContract({ address: getAddress(feed.address), abi: FEED_ABI, functionName: 'latestRoundData', blockNumber: block.number }),
+        ]);
+        const [roundId, answer, startedAt, updatedAt, answeredInRound] = round;
+        const observedAtMs = Number(updatedAt * 1000n), current = now();
+        if (decimals !== feed.decimals || answer <= 0n || roundId <= 0n || answeredInRound < roundId ||
+            startedAt <= 0n || startedAt > updatedAt || !Number.isSafeInteger(observedAtMs) || observedAtMs > current ||
+            current - observedAtMs >= feed.maxAgeSeconds * 1000 ||
+            await client.getChainId() !== chainId || (await client.getBlock({ blockNumber: block.number })).hash !== block.hash)
+            return undefined;
+        return { amountAtomic: answer.toString(), decimals, observedAtMs: current,
+            expiresAtMs: Math.min(observedAtMs + feed.maxAgeSeconds * 1000, current + 30_000) };
+    }
+    catch {
+        return undefined;
+    }
+}
+export class AccountGasPaymentRuntime {
+    clients;
+    providers;
+    transport;
+    now;
+    quote;
+    verifiedQuotes = new WeakSet();
+    freshQuotes = new WeakMap();
+    constructor(clients, providers, transport, now = Date.now, quote = prepareAccountGasQuote) {
+        this.clients = clients;
+        this.providers = providers;
+        this.transport = transport;
+        this.now = now;
+        this.quote = quote;
+    }
+    async review(operation, calls, preference = 'auto', checkSponsor = true) {
+        const { context } = operation, { chainId, account, activation } = context;
+        const client = this.clients[chainId], providers = this.providers.filter(provider => provider.chainId === chainId);
+        if (!activation.gasPaymentReviewEnabled || !client || providers.length !== 1)
+            throw new AccountGasReviewError('ACCOUNT_GAS_REVIEW_UNAVAILABLE');
+        const terms = sponsoredChainTerms(activation, chainId);
+        const usdPrice = await gasUsdPrice(client, activation, chainId, this.now);
+        const quote = await this.quote({ account, chainId, entryPoint: terms.entryPoint, calls, client,
+            paymasterUrl: providers[0].paymasterUrl, sponsor: { paymaster: terms.paymaster, sponsorshipPolicyId: terms.sponsorshipPolicyId }, nowMs: this.now, ...(usdPrice ? { usdPrice } : {}) });
+        let sponsorPolicy;
+        try {
+            if (checkSponsor)
+                sponsorPolicy = await this.transport.checkGasPolicy(chainId);
+        }
+        catch { /* Self-pay remains explicit and independent. */ }
+        const review = createAccountGasReview({ quote, previousRevision: operation.gasReview?.revision ?? 0,
+            preference, ...(sponsorPolicy ? { sponsorPolicy } : {}), nowMs: this.now() });
+        if (review.payer === 'account')
+            this.assertPilotExposure(operation, quote);
+        this.freshQuotes.set(review, quote);
+        return review;
+    }
+    assertPilotExposure(operation, quote) {
+        const { account, chainId, activation } = operation.context;
+        const pins = activation.userPaidGasPilot?.filter(pin => pin.chainId === chainId && pin.account.toLowerCase() === account.toLowerCase()) ?? [];
+        // A moment-in-time designated-pilot admission check, not a request-bound fee maximum.
+        if (pins.length !== 1 || BigInt(quote.balance.nativeWei) + BigInt(quote.balance.entryPointDepositWei) > BigInt(pins[0].maximumObservedExposureWei))
+            throw new AccountGasReviewError('ACCOUNT_GAS_REVIEW_UNAVAILABLE');
+    }
+    async revalidate(operation, calls) {
+        if (!operation.context.activation.gasPaymentReviewEnabled) {
+            if (operation.gasReview)
+                throw new AccountGasReviewError('ACCOUNT_GAS_REVIEW_UNAVAILABLE');
+            return undefined;
+        }
+        if (!operation.gasReview)
+            throw new AccountGasReviewError('ACCOUNT_GAS_REVIEW_REQUIRED');
+        const current = await this.review(operation, calls, operation.gasReview.payer, operation.gasReview.payer === 'sponsor');
+        if (accountGasReviewNeedsRenewal(operation.gasReview, current))
+            throw new AccountGasReviewError('ACCOUNT_GAS_REVIEW_CHANGED');
+        if (!accountGasReviewCanSubmit(current, this.now()))
+            throw new AccountGasReviewError('ACCOUNT_GAS_FUNDING_REQUIRED');
+        const original = this.freshQuotes.get(current);
+        if (!original)
+            throw new AccountGasReviewError('ACCOUNT_GAS_REVIEW_UNAVAILABLE');
+        this.verifiedQuotes.add(original);
+        return original;
+    }
+    assertFresh(operation, calls, quote, gasPolicy) {
+        if (!operation.context.activation.gasPaymentReviewEnabled)
+            return;
+        if (!quote)
+            throw new AccountGasReviewError('ACCOUNT_GAS_REVIEW_REQUIRED');
+        if (!this.verifiedQuotes.has(quote))
+            throw new AccountGasReviewError('ACCOUNT_GAS_REVIEW_UNAVAILABLE');
+        if (operation.gasReview?.payer === 'account')
+            this.assertPilotExposure(operation, quote);
+        else {
+            const estimate = quote.sponsoredEstimate, terms = sponsoredChainTerms(operation.context.activation, operation.context.chainId);
+            if (!gasPolicy || !estimate || estimate.estimatedGasCostUsdMicros === undefined ||
+                gasPolicy.chainId !== quote.chainId || gasPolicy.sponsorshipPolicyId !== terms.sponsorshipPolicyId ||
+                estimate.sponsorshipPolicyId !== gasPolicy.sponsorshipPolicyId || estimate.paymaster !== terms.paymaster.toLowerCase() ||
+                BigInt(estimate.estimatedGasCostUsdMicros) > BigInt(gasPolicy.maximumGasCostUsdMicros))
+                throw new AccountGasReviewError('ACCOUNT_GAS_REVIEW_CHANGED');
+            assertSponsoredGasPolicyCurrent(gasPolicy, this.now());
+        }
+        assertFreshAccountGasQuote(quote, { account: operation.context.account, chainId: operation.context.chainId,
+            entryPoint: sponsoredChainTerms(operation.context.activation, operation.context.chainId).entryPoint, calls }, this.now());
+    }
+}
+//# sourceMappingURL=execution-account-gas-runtime.js.map