otto-intel-mcp 0.1.2 → 0.1.4

package/dist/execution-sponsored-mcp-definition.js

@@ -0,0 +1,94 @@
+import { ACCOUNT_GAS_PUBLIC_SCHEMA, ACCOUNT_GAS_FAILURE_CODES, accountGasViewMatches } from './execution-account-gas-view.js';
+/** Closed protected tool contract. Tokens stay in requests; raw provider responses never reach callers. */
+import { z } from 'zod';
+import { DELEGATED_TOOL_TRANSPORT_SCHEMA } from './execution-delegated-definition.js';
+import { SPONSORED_PREPARE_INPUT, SPONSORED_READ_INPUT, SPONSORED_SUBMIT_INPUT, SPONSORED_GAS_REVIEW_INPUT, SPONSORED_CHAIN_SCHEMA, SPONSORED_RECEIPT_SCHEMA, SPONSORED_SETTLEMENT_SCHEMA } from './execution-sponsored-definition.js';
+const address = z.string().regex(/^0x[0-9a-fA-F]{40}$/), hash = z.string().regex(/^0x[0-9a-fA-F]{64}$/);
+const atomic = z.string().regex(/^(0|[1-9][0-9]*)$/).refine(v => /^(0|[1-9][0-9]*)$/.test(v) && BigInt(v) < 2n ** 256n);
+const positive = atomic.refine(v => /^(0|[1-9][0-9]*)$/.test(v) && BigInt(v) > 0n);
+const operationId = z.string().regex(/^sp_[a-f0-9-]{36}$/);
+const digest = z.string().regex(/^[0-9a-f]{64}$/);
+export const SPONSORED_TOOL_NAME = 'otto_sponsored_account';
+export const SPONSORED_ACTION_INPUT = z.discriminatedUnion('action', [
+    z.object({ action: z.literal('availability') }).strict(),
+    SPONSORED_GAS_REVIEW_INPUT.extend({ action: z.literal('reviewGas') }).strict(),
+    SPONSORED_PREPARE_INPUT.extend({ action: z.literal('prepare') }).strict(),
+    SPONSORED_SUBMIT_INPUT.extend({ action: z.literal('submit') }).strict(),
+    SPONSORED_READ_INPUT.extend({ action: z.literal('read') }).strict(),
+    SPONSORED_READ_INPUT.extend({ action: z.literal('reconcile') }).strict(),
+]);
+export const SPONSORED_REFUSAL_CODES = [
+    'SPONSOR_ACTIVATION_UNCONFIGURED', 'SPONSOR_ACTIVATION_UNAVAILABLE', 'SPONSOR_RECOVERY_ONLY', 'SPONSOR_CAPABILITY_UNAVAILABLE',
+    'SPONSOR_RUNTIME_UNAVAILABLE', 'SPONSOR_JOURNAL_UNAVAILABLE', 'SPONSOR_REQUEST_INVALID',
+    'SPONSOR_REQUEST_REFUSED', 'SPONSOR_SESSION_REQUIRED', 'SPONSOR_SESSION_INVALID',
+    'SPONSOR_OWNER_MISMATCH', 'SPONSOR_EXPLICIT_WALLET_UPGRADE_REQUIRED', 'SPONSOR_CURRENT_GRANT_REQUIRED',
+    'SPONSOR_CAP_UNAVAILABLE', 'SPONSOR_POLICY_CHANGED', 'SPONSOR_CHAIN_UNAVAILABLE',
+    'SPONSOR_ACCOUNT_PROOF_UNAVAILABLE', 'SPONSOR_ACCOUNT_PROOF_MISMATCH',
+    'SPONSOR_INPUT_OUTSIDE_REVIEWED_CAP', 'SPONSOR_REVIEW_AUTHORITY_CHANGED', 'SPONSOR_REVIEW_EXPIRED',
+    'SPONSOR_STOP_OR_CAP_CHANGED', 'SPONSOR_BALANCE_INSUFFICIENT', 'SPONSOR_OUTPUT_TOKEN_UNREVIEWED',
+    'SPONSOR_BUDGET_HALTED', 'SPONSOR_NOT_SUBMITTED', 'SPONSOR_USER_OPERATION_REVERTED',
+    'SPONSOR_GAS_CAP_EXCEEDED', ...ACCOUNT_GAS_FAILURE_CODES,
+];
+/** A named enum keeps generated public declarations compact without broadening accepted codes. */
+export const SPONSORED_REFUSAL_SCHEMA = z.enum(SPONSORED_REFUSAL_CODES);
+export const SPONSORED_AVAILABILITY_RESULT = z.object({
+    schemaVersion: z.literal('1'), configured: z.boolean(), executionEnabled: z.boolean(),
+    recoveryAvailable: z.boolean(),
+    reason: SPONSORED_REFUSAL_SCHEMA.optional(),
+    requiresSeparateWalletUpgrade: z.literal(true), requiresOperationReview: z.literal(true),
+    automaticExecutionEnabled: z.literal(false),
+    supportedSameAddressChains: z.array(SPONSORED_CHAIN_SCHEMA).max(5),
+}).strict().refine(value => !value.executionEnabled || (value.configured && value.recoveryAvailable && value.reason === undefined));
+export const SPONSORED_OPERATION_RESULT = z.object({
+    schemaVersion: z.literal('1'), operationId, account: address, chainId: SPONSORED_CHAIN_SCHEMA,
+    state: z.enum(['review', 'active', 'unknown', 'submitted', 'completed', 'failed']), reviewConsumed: z.boolean(),
+    reviewCommitment: digest, validUntilMs: z.number().int().positive().safe(),
+    input: z.object({ token: address, amount: positive }).strict(),
+    output: z.object({ token: address, minimum: positive }).strict(), ottoFee: atomic,
+    gas: ACCOUNT_GAS_PUBLIC_SCHEMA,
+    walletAuthorityChangeIncluded: z.literal(false), automaticExecutionEnabled: z.literal(false),
+    userOpHash: hash.optional(), transactionHash: hash.optional(),
+    receipt: SPONSORED_RECEIPT_SCHEMA.optional(), settlement: SPONSORED_SETTLEMENT_SCHEMA.optional(),
+    failureCode: SPONSORED_REFUSAL_SCHEMA.optional(), attention: z.literal('The original provider request is unresolved. No replacement is permitted.').optional(),
+    requiresOperationReview: z.literal(true).optional(),
+    terms: z.object({ activationId: z.string().regex(/^[a-zA-Z0-9_-]{8,100}$/),
+        perSwapCapUsdc: z.number().int().min(1).max(5000), grantExpiresAt: z.string().datetime(),
+        scope: z.literal('one reviewed same-chain USDC swap into an explicitly reviewed ERC20, with allowance cleared in the same batch; native output is unsupported'),
+        walletAuthorityChangeIncluded: z.literal(false), providerPolicyId: z.string().regex(/^[a-zA-Z0-9_-]{1,128}$/),
+    }).strict().optional(),
+}).strict().refine(value => accountGasViewMatches(value) &&
+    (value.state === 'review') === !value.reviewConsumed &&
+    (value.state !== 'review' || (value.requiresOperationReview === true && !!value.terms)) &&
+    (value.state !== 'completed' || (!!value.receipt && value.receipt.status === 'success' && !!value.settlement)) &&
+    (!value.transactionHash || !!value.userOpHash) &&
+    (value.gas.payer !== 'sponsor' || !value.gas.activationChainHalted || (value.failureCode === 'SPONSOR_GAS_CAP_EXCEEDED' && value.state === 'submitted')), 'Sponsored operation state must agree with its finality and review evidence');
+export const SPONSORED_UNCERTAIN_RESULT = z.object({
+    schemaVersion: z.literal('1'), status: z.literal('outcome-unknown'), operationId,
+    requiresReconciliation: z.literal(true), replacementPermitted: z.literal(false),
+    attention: z.literal('The outcome of the original submission is unknown. Read or reconcile this operation; do not submit a replacement.'),
+}).strict();
+export const SPONSORED_TOOL_RESULT = z.union([
+    SPONSORED_AVAILABILITY_RESULT, SPONSORED_OPERATION_RESULT, SPONSORED_UNCERTAIN_RESULT,
+]);
+/** The pinned MCP SDK requires an object at the top level; strict union validation remains mandatory. */
+export const SPONSORED_TRANSPORT_RESULT = z.object({
+    ...SPONSORED_AVAILABILITY_RESULT.shape, ...SPONSORED_OPERATION_RESULT.shape, ...SPONSORED_UNCERTAIN_RESULT.shape,
+    // Public descriptor schemas contain no checksum transforms. The handler has already normalized
+    // and validated these values; the SDK must be able to emit ordinary JSON Schema for tools/list.
+    receipt: z.object({ ...SPONSORED_RECEIPT_SCHEMA.shape, account: address, paymaster: address }).strict().optional(),
+    settlement: z.object({ ...SPONSORED_SETTLEMENT_SCHEMA.shape, inputToken: address, outputToken: address }).strict().optional(),
+    attention: z.union([SPONSORED_OPERATION_RESULT.shape.attention.unwrap(), SPONSORED_UNCERTAIN_RESULT.shape.attention]).optional(),
+}).partial().extend({ schemaVersion: z.literal('1') }).strict().superRefine((value, context) => {
+    if (!SPONSORED_TOOL_RESULT.safeParse(value).success)
+        context.addIssue({
+            code: 'custom', message: 'The sponsored account result does not match a supported public outcome.',
+        });
+});
+export const SPONSORED_TOOL_DEFINITION = Object.freeze({
+    name: SPONSORED_TOOL_NAME, title: 'Review or recover an account transaction',
+    description: 'Protected account action: availability, prepare, reviewGas for current gas payer and estimate, explicit submit, owned read or reconcile. Gas refresh is read-only planning and requires new confirmation before any send. Wallet upgrade is separate. Sponsorship requires a reviewed source activation; current availability is authoritative. A missing submission response is unknown and must never cause a replacement submission.',
+    inputSchema: DELEGATED_TOOL_TRANSPORT_SCHEMA,
+    outputSchema: SPONSORED_TRANSPORT_RESULT,
+    annotations: Object.freeze({ readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }),
+});
+//# sourceMappingURL=execution-sponsored-mcp-definition.js.map

package/dist/execution-sponsored-receipt.d.ts

@@ -0,0 +1,47 @@
+/** A bundler transaction can succeed while an individual UserOperation reverts. */
+import { type Address, type Hex, type TransactionReceipt } from 'viem';
+import type { SponsoredChainId } from './execution-sponsored-transport.js';
+export interface SponsoredReceiptBinding {
+    readonly payer?: 'sponsor' | 'account';
+    readonly chainId: SponsoredChainId;
+    readonly account: Address;
+    readonly userOpHash: Hex;
+    readonly transactionHash: Hex;
+    readonly entryPoint: Address;
+    readonly paymaster: Address;
+    /** Operator-approved per-operation cap in the chain's native atomic units. No default. */
+    readonly maxGasCostWei: bigint;
+}
+export interface SponsoredReceiptClient {
+    getChainId(): Promise<number>;
+    getTransactionReceipt(args: {
+        hash: Hex;
+    }): Promise<TransactionReceipt>;
+    getBlock(args: {
+        blockNumber: bigint;
+    } | {
+        blockTag: 'finalized';
+    }): Promise<{
+        number: bigint | null;
+        hash: Hex | null;
+    }>;
+}
+export interface ConfirmedSponsoredReceipt {
+    readonly chainId: SponsoredChainId;
+    readonly account: Address;
+    readonly userOpHash: Hex;
+    readonly transactionHash: Hex;
+    readonly blockHash: Hex;
+    readonly blockNumber: string;
+    readonly nonce: string;
+    readonly paymaster: Address;
+    readonly actualGasCostWei: string;
+    readonly actualGasUsed: string;
+    readonly status: 'success' | 'reverted';
+}
+export declare class SponsoredReceiptUnconfirmedError extends Error {
+    readonly code: 'SPONSOR_RECEIPT_UNCONFIRMED' | 'SPONSOR_GAS_CAP_EXCEEDED';
+    readonly breachedReceipt?: ConfirmedSponsoredReceipt | undefined;
+    constructor(code?: 'SPONSOR_RECEIPT_UNCONFIRMED' | 'SPONSOR_GAS_CAP_EXCEEDED', breachedReceipt?: ConfirmedSponsoredReceipt | undefined);
+}
+export declare function readConfirmedSponsoredReceipt(binding: SponsoredReceiptBinding, client: SponsoredReceiptClient): Promise<ConfirmedSponsoredReceipt>;

package/dist/execution-sponsored-receipt.js

@@ -0,0 +1,74 @@
+/** A bundler transaction can succeed while an individual UserOperation reverts. */
+import { decodeEventLog, parseAbiItem } from 'viem';
+const USER_OPERATION_EVENT = parseAbiItem('event UserOperationEvent(bytes32 indexed userOpHash, address indexed sender, address indexed paymaster, uint256 nonce, bool success, uint256 actualGasCost, uint256 actualGasUsed)');
+export class SponsoredReceiptUnconfirmedError extends Error {
+    code;
+    breachedReceipt;
+    constructor(code = 'SPONSOR_RECEIPT_UNCONFIRMED', breachedReceipt) {
+        super(code === 'SPONSOR_GAS_CAP_EXCEEDED'
+            ? 'The sponsored receipt exceeded the approved gas cap; keep the operation locked for review.'
+            : 'The exact sponsored operation has no matching canonical finalized receipt yet.');
+        this.code = code;
+        this.breachedReceipt = breachedReceipt;
+        this.name = 'SponsoredReceiptUnconfirmedError';
+    }
+}
+export async function readConfirmedSponsoredReceipt(binding, client) {
+    try {
+        const isAddress = (value) => /^0x[0-9a-fA-F]{40}$/.test(value);
+        const isHash = (value) => /^0x[0-9a-fA-F]{64}$/.test(value);
+        if (![binding.account, binding.entryPoint, binding.paymaster].every(isAddress) ||
+            ![binding.userOpHash, binding.transactionHash].every(isHash) ||
+            (binding.payer !== undefined && !['sponsor', 'account'].includes(binding.payer)) ||
+            (binding.payer === 'account' ? !/^0x0{40}$/i.test(binding.paymaster) : /^0x0{40}$/i.test(binding.paymaster)) ||
+            binding.maxGasCostWei <= 0n || await client.getChainId() !== binding.chainId)
+            throw new Error();
+        // Establish finality before reading the receipt and its canonical block; a reorg during a
+        // later finalized-head read must never promote stale receipt evidence to settlement.
+        const finalized = await client.getBlock({ blockTag: 'finalized' });
+        const receipt = await client.getTransactionReceipt({ hash: binding.transactionHash });
+        if (receipt.transactionHash.toLowerCase() !== binding.transactionHash.toLowerCase() || receipt.status !== 'success' ||
+            receipt.to?.toLowerCase() !== binding.entryPoint.toLowerCase())
+            throw new Error();
+        const block = await client.getBlock({ blockNumber: receipt.blockNumber });
+        if (block.hash !== receipt.blockHash || block.number !== receipt.blockNumber ||
+            finalized.number === null || finalized.number < receipt.blockNumber)
+            throw new Error();
+        const matching = receipt.logs.flatMap(log => {
+            if (log.address.toLowerCase() !== binding.entryPoint.toLowerCase())
+                return [];
+            try {
+                const decoded = decodeEventLog({ abi: [USER_OPERATION_EVENT], data: log.data, topics: log.topics, strict: true });
+                if (decoded.args.userOpHash.toLowerCase() !== binding.userOpHash.toLowerCase())
+                    return [];
+                if (log.removed || log.transactionHash !== receipt.transactionHash || log.blockHash !== receipt.blockHash || log.blockNumber !== receipt.blockNumber)
+                    throw new SponsoredReceiptUnconfirmedError();
+                return [decoded.args];
+            }
+            catch (error) {
+                if (error instanceof SponsoredReceiptUnconfirmedError)
+                    throw error;
+                return [];
+            }
+        });
+        if (matching.length !== 1)
+            throw new Error();
+        const event = matching[0];
+        if (event.sender.toLowerCase() !== binding.account.toLowerCase() || event.paymaster.toLowerCase() !== binding.paymaster.toLowerCase() ||
+            event.actualGasCost <= 0n || event.actualGasUsed <= 0n)
+            throw new Error();
+        const confirmed = Object.freeze({ chainId: binding.chainId, account: binding.account, userOpHash: binding.userOpHash,
+            transactionHash: binding.transactionHash, blockHash: receipt.blockHash, blockNumber: receipt.blockNumber.toString(),
+            nonce: event.nonce.toString(), paymaster: event.paymaster, actualGasCostWei: event.actualGasCost.toString(),
+            actualGasUsed: event.actualGasUsed.toString(), status: event.success ? 'success' : 'reverted' });
+        if (binding.payer !== 'account' && event.actualGasCost > binding.maxGasCostWei)
+            throw new SponsoredReceiptUnconfirmedError('SPONSOR_GAS_CAP_EXCEEDED', confirmed);
+        return confirmed;
+    }
+    catch (error) {
+        if (error instanceof SponsoredReceiptUnconfirmedError)
+            throw error;
+        throw new SponsoredReceiptUnconfirmedError();
+    }
+}
+//# sourceMappingURL=execution-sponsored-receipt.js.map

package/dist/execution-sponsored-registration.d.ts

@@ -0,0 +1,14 @@
+/** Authenticate before parsing, availability or provider/journal work on every protected action. */
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { type SponsoredAvailabilityResult } from './execution-sponsored-mcp-definition.js';
+import type { ExecutionToolRuntime } from './execution-tools.js';
+export interface SponsoredAccountBinding {
+    availability(): Promise<SponsoredAvailabilityResult>;
+    reviewGas(input: unknown): Promise<unknown>;
+    prepare(input: unknown): Promise<unknown>;
+    submit(input: unknown): Promise<unknown>;
+    read(input: unknown): Promise<unknown>;
+    reconcile(input: unknown): Promise<unknown>;
+}
+export declare function unavailableSponsoredBinding(reason?: NonNullable<SponsoredAvailabilityResult['reason']>): SponsoredAccountBinding;
+export declare function callSponsoredAccount(runtime: ExecutionToolRuntime, raw: unknown, headers: Readonly<Record<string, string | string[] | undefined>> | undefined): Promise<CallToolResult>;

package/dist/execution-sponsored-registration.js

@@ -0,0 +1,77 @@
+import { accountGasFailure } from './execution-account-gas-view.js';
+import { ZodError } from 'zod';
+import { assertDelegationCaller, callerFromHeaders } from './execution-delegation.js';
+import { ExecutionRefusal, isExecutionRefusal } from './execution-errors.js';
+import { SponsoredAccountRefusal } from './execution-sponsored-runtime.js';
+import { sponsoredAccountAvailability } from './execution-sponsored-index.js';
+import { SPONSORED_ACTION_INPUT, SPONSORED_REFUSAL_CODES, SPONSORED_TOOL_RESULT, SPONSORED_AVAILABILITY_RESULT } from './execution-sponsored-mcp-definition.js';
+export function unavailableSponsoredBinding(reason = 'SPONSOR_ACTIVATION_UNCONFIGURED') {
+    const refuse = async () => { throw new SponsoredAccountRefusal(reason); };
+    return Object.freeze({
+        availability: async () => SPONSORED_AVAILABILITY_RESULT.parse({ ...sponsoredAccountAvailability(), executionEnabled: false, recoveryAvailable: false, reason }),
+        reviewGas: refuse, prepare: refuse, submit: refuse, read: refuse, reconcile: refuse,
+    });
+}
+function success(value) {
+    const output = SPONSORED_TOOL_RESULT.parse(value);
+    return { content: [{ type: 'text', text: JSON.stringify(output) }], structuredContent: output };
+}
+function unknownSubmission(operationId) {
+    return success({ schemaVersion: '1', status: 'outcome-unknown', operationId,
+        requiresReconciliation: true, replacementPermitted: false,
+        attention: 'The outcome of the original submission is unknown. Read or reconcile this operation; do not submit a replacement.' });
+}
+// These service refusals are proved before any operation claim/handoff. Everything else after invoking
+// submit is conservatively unknown, including a malformed output or journal failure after a POST.
+const BEFORE_HANDOFF_REFUSALS = new Set([
+    'SPONSOR_ACTIVATION_UNCONFIGURED', 'SPONSOR_ACTIVATION_UNAVAILABLE', 'SPONSOR_RECOVERY_ONLY', 'SPONSOR_CAPABILITY_UNAVAILABLE',
+    'SPONSOR_RUNTIME_UNAVAILABLE', 'SPONSOR_JOURNAL_UNAVAILABLE', 'SPONSOR_SESSION_REQUIRED', 'SPONSOR_SESSION_INVALID',
+    'SPONSOR_OWNER_MISMATCH', 'SPONSOR_EXPLICIT_WALLET_UPGRADE_REQUIRED', 'SPONSOR_CURRENT_GRANT_REQUIRED',
+    'SPONSOR_CAP_UNAVAILABLE', 'SPONSOR_POLICY_CHANGED', 'SPONSOR_CHAIN_UNAVAILABLE',
+]);
+export async function callSponsoredAccount(runtime, raw, headers) {
+    let submitId, invoked = false;
+    try {
+        const delegation = runtime.delegation;
+        if (!delegation)
+            throw new ExecutionRefusal('DELEGATION_UNAUTHORIZED', 'protected account caller is not authorized');
+        assertDelegationCaller(delegation, callerFromHeaders(headers));
+        const input = SPONSORED_ACTION_INPUT.parse(raw);
+        const binding = runtime.sponsoredAccount ?? unavailableSponsoredBinding();
+        if (input.action === 'availability')
+            return success(SPONSORED_AVAILABILITY_RESULT.parse(await binding.availability()));
+        const { action, ...body } = input;
+        if (action === 'submit')
+            submitId = input.operationId;
+        invoked = true;
+        const result = SPONSORED_TOOL_RESULT.parse(await binding[action](body));
+        if (!('operationId' in result) || !('state' in result))
+            throw new Error('unexpected action result');
+        if (action === 'prepare') {
+            if (result.state !== 'review' || result.account.toLowerCase() !== input.account.toLowerCase() ||
+                result.chainId !== input.chainId)
+                throw new Error('mismatched preparation result');
+        }
+        else if (result.operationId !== input.operationId)
+            throw new Error('mismatched operation result');
+        if (input.action === 'reviewGas' && (result.state !== 'review' || result.reviewConsumed || result.gas.reviewRequired !== true || !result.gas.paymentReview ||
+            result.reviewCommitment === input.reviewCommitment || (input.preference !== 'auto' && result.gas.payer !== input.preference)))
+            throw new Error('mismatched gas review');
+        if (input.action === 'submit' && (!result.reviewConsumed || result.reviewCommitment !== input.reviewCommitment))
+            throw new Error('mismatched consumed review');
+        return success(result);
+    }
+    catch (error) {
+        const code = accountGasFailure(error) ?? (error instanceof SponsoredAccountRefusal && SPONSORED_REFUSAL_CODES.includes(error.code)
+            ? error.code : error instanceof ZodError && !invoked ? 'SPONSOR_REQUEST_INVALID' : 'SPONSOR_REQUEST_REFUSED');
+        if (submitId && invoked && !BEFORE_HANDOFF_REFUSALS.has(code))
+            return unknownSubmission(submitId);
+        const refusal = isExecutionRefusal(error) && error.code === 'DELEGATION_UNAUTHORIZED' && !invoked
+            ? { code: 'DELEGATION_UNAUTHORIZED', message: 'The protected account caller is not authorized.' }
+            : { code, message: code === 'SPONSOR_REQUEST_INVALID' ? 'The sponsored account request is invalid.'
+                    : code === 'SPONSOR_EXPLICIT_WALLET_UPGRADE_REQUIRED' ? 'This account requires a separately approved wallet upgrade.'
+                        : 'The sponsored account action is unavailable or refused. Read current availability and the original operation before continuing.' };
+        return { isError: true, content: [{ type: 'text', text: JSON.stringify({ status: 'refused', ...refusal }) }] };
+    }
+}
+//# sourceMappingURL=execution-sponsored-registration.js.map

package/dist/execution-sponsored-runtime.d.ts

@@ -0,0 +1,84 @@
+import { type Address, type Hex, type PublicClient } from 'viem';
+import type { DelegationCapStore } from './execution-delegation-cap-store.js';
+import { type SponsoredCapability, type SponsoredActivation, type SponsoredAuthority, type SponsoredOperation } from './execution-sponsored-definition.js';
+import { type SponsoredChainId, type SponsoredCall, type SponsoredAcknowledgement } from './execution-sponsored-transport.js';
+interface EndUserIdentity {
+    userId: string;
+    evmAccountObjects?: readonly {
+        address: string;
+    }[];
+    evmSmartAccountObjects?: readonly {
+        address: string;
+        ownerAddresses: readonly string[];
+    }[];
+}
+export interface SponsoredAccountCdp {
+    endUser: {
+        validateAccessToken(input: {
+            accessToken: string;
+        }): Promise<EndUserIdentity>;
+        getEndUser(input: {
+            userId: string;
+        }): Promise<EndUserIdentity>;
+        getDelegationForEndUserAccount(input: {
+            userId: string;
+            address: string;
+        }): Promise<{
+            expiresAt: string;
+        }>;
+    };
+    policies: {
+        listPolicies(input: {
+            scope: 'project';
+        }): Promise<{
+            policies?: readonly {
+                id: string;
+                scope: string;
+                description?: string;
+                rules: unknown;
+            }[];
+        }>;
+    };
+    evm: {
+        getUserOperation(input: {
+            smartAccount: Address;
+            userOpHash: Hex;
+        }): Promise<{
+            network: string;
+            userOpHash: string;
+            transactionHash?: string;
+            status: string;
+            calls: readonly {
+                to: string;
+                data: string;
+                value: string | bigint;
+            }[];
+        }>;
+    };
+}
+export declare class SponsoredAccountRefusal extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+export declare class SponsoredAccountRuntime {
+    readonly cdp: SponsoredAccountCdp;
+    private readonly caps;
+    readonly clients: Readonly<Partial<Record<SponsoredChainId, PublicClient>>>;
+    readonly projectId: string;
+    readonly now: () => number;
+    constructor(cdp: SponsoredAccountCdp, caps: DelegationCapStore, clients: Readonly<Partial<Record<SponsoredChainId, PublicClient>>>, projectId: string, now?: () => number);
+    client(chainId: SponsoredChainId): PublicClient;
+    identity(accessToken: string, account: Address): Promise<{
+        userId: string;
+        current: EndUserIdentity;
+    }>;
+    authority(accessToken: string, account: Address, chainId: SponsoredChainId, rawActivation: SponsoredActivation, outputToken: Address, capability?: SponsoredCapability): Promise<SponsoredAuthority>;
+    /** Called synchronously under the operation handoff lock. Stop and request start are ordered by caps.db. */
+    withCurrentCap<T>(authority: SponsoredAuthority, start: () => T): T;
+    assertCurrentCap(authority: SponsoredAuthority): Promise<void>;
+    preflight(operation: SponsoredOperation): Promise<void>;
+    readAcknowledgement(operation: Pick<SponsoredOperation, 'userOpHash'> & {
+        context: Pick<SponsoredOperation['context'], 'account' | 'chainId'>;
+    }, expectedCalls: readonly SponsoredCall[]): Promise<SponsoredAcknowledgement>;
+}
+export {};

package/dist/execution-sponsored-runtime.js

@@ -0,0 +1,149 @@
+import { getAddress, keccak256, parseAbi } from 'viem';
+import { MODEL_B_CAP_RULESET_VERSION } from './execution-delegation-cap-store.js';
+import { policyRulesDigest } from './execution-policy-compatibility.js';
+import { SPONSORED_AUTHORITY_SCHEMA, SPONSORED_ACTIVATION_SCHEMA, sponsoredDigest, sponsoredChainTerms, sponsoredOutputToken, sponsoredActivationSupports, SPONSORED_USDC } from './execution-sponsored-definition.js';
+import { SPONSORED_CDP_NETWORKS } from './execution-sponsored-transport.js';
+export class SponsoredAccountRefusal extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = 'SponsoredAccountRefusal';
+    }
+}
+function refuse(code) { throw new SponsoredAccountRefusal(code); }
+function owns(user, account) {
+    return (user.evmAccountObjects ?? []).some(a => getAddress(a.address) === account);
+}
+function sameAddressSmartAccount(user, account) {
+    const matches = (user.evmSmartAccountObjects ?? []).filter(a => getAddress(a.address) === account);
+    return matches.length === 1 && matches[0].ownerAddresses.length === 1 && getAddress(matches[0].ownerAddresses[0]) === account;
+}
+export class SponsoredAccountRuntime {
+    cdp;
+    caps;
+    clients;
+    projectId;
+    now;
+    constructor(cdp, caps, clients, projectId, now = Date.now) {
+        this.cdp = cdp;
+        this.caps = caps;
+        this.clients = clients;
+        this.projectId = projectId;
+        this.now = now;
+    }
+    client(chainId) {
+        return this.clients[chainId] ?? refuse('SPONSOR_CHAIN_UNAVAILABLE');
+    }
+    async identity(accessToken, account) {
+        if (!accessToken || accessToken.length > 16384)
+            return refuse('SPONSOR_SESSION_REQUIRED');
+        try {
+            const token = await this.cdp.endUser.validateAccessToken({ accessToken });
+            if (!/^[a-zA-Z0-9-]{1,100}$/.test(token.userId))
+                return refuse('SPONSOR_SESSION_INVALID');
+            const current = await this.cdp.endUser.getEndUser({ userId: token.userId });
+            if (current.userId !== token.userId || !owns(token, account) || !owns(current, account))
+                return refuse('SPONSOR_OWNER_MISMATCH');
+            return { userId: token.userId, current };
+        }
+        catch (error) {
+            if (error instanceof SponsoredAccountRefusal)
+                throw error;
+            return refuse('SPONSOR_SESSION_INVALID');
+        }
+    }
+    async authority(accessToken, account, chainId, rawActivation, outputToken, capability = 'swap') {
+        const activation = SPONSORED_ACTIVATION_SCHEMA.parse(rawActivation);
+        if (!sponsoredActivationSupports(activation, capability))
+            return refuse('SPONSOR_CAPABILITY_UNAVAILABLE');
+        const output = sponsoredOutputToken(activation, chainId, outputToken);
+        if (activation.projectId !== this.projectId || activation.mode !== 'enabled' ||
+            activation.approvedAtMs > this.now() || activation.expiresAtMs <= this.now())
+            return refuse('SPONSOR_ACTIVATION_UNAVAILABLE');
+        if (!this.caps.available)
+            return refuse('SPONSOR_CAP_UNAVAILABLE');
+        const who = await this.identity(accessToken, account);
+        if (!sameAddressSmartAccount(who.current, account))
+            return refuse('SPONSOR_EXPLICIT_WALLET_UPGRADE_REQUIRED');
+        const [cap, generation, grant, policyReply] = await Promise.all([
+            this.caps.readActive(who.userId, this.now()), this.caps.readRevokeGeneration(who.userId),
+            this.cdp.endUser.getDelegationForEndUserAccount({ userId: who.userId, address: account }),
+            this.cdp.policies.listPolicies({ scope: 'project' }),
+        ]);
+        if (!cap || cap.state !== 'confirmed_active' || cap.requiredVersion !== MODEL_B_CAP_RULESET_VERSION ||
+            cap.revokeGeneration !== generation || Date.parse(cap.expiresAt) !== Date.parse(grant.expiresAt) ||
+            !Number.isFinite(Date.parse(grant.expiresAt)) || Date.parse(grant.expiresAt) <= this.now() ||
+            Date.parse(grant.expiresAt) > this.now() + 180 * 24 * 60 * 60 * 1000)
+            return refuse('SPONSOR_CURRENT_GRANT_REQUIRED');
+        const projectPolicies = (policyReply.policies ?? []).filter(p => p.scope === 'project');
+        if (projectPolicies.length !== 1 || projectPolicies[0].id !== activation.policyId ||
+            projectPolicies[0].description !== activation.policyName ||
+            policyRulesDigest(projectPolicies[0].rules) !== activation.policyRulesDigest)
+            return refuse('SPONSOR_POLICY_CHANGED');
+        const terms = sponsoredChainTerms(activation, chainId), client = this.client(chainId);
+        const block = await client.getBlock({ blockTag: 'latest' });
+        if (!block.number || !block.hash)
+            return refuse('SPONSOR_ACCOUNT_PROOF_UNAVAILABLE');
+        const [network, ownerCode, delegateCode, entryPointCode, paymasterCode, outputCode] = await Promise.all([
+            client.getChainId(), client.getCode({ address: account, blockNumber: block.number }),
+            client.getCode({ address: terms.delegate, blockNumber: block.number }),
+            client.getCode({ address: terms.entryPoint, blockNumber: block.number }),
+            client.getCode({ address: terms.paymaster, blockNumber: block.number }),
+            client.getCode({ address: output.address, blockNumber: block.number }),
+        ]);
+        if (network !== chainId || ownerCode?.toLowerCase() !== `0xef0100${terms.delegate.slice(2).toLowerCase()}` ||
+            !delegateCode || delegateCode === '0x' || keccak256(delegateCode).toLowerCase() !== terms.delegateCodeHash.toLowerCase() ||
+            !entryPointCode || entryPointCode === '0x' || keccak256(entryPointCode).toLowerCase() !== terms.entryPointCodeHash.toLowerCase() ||
+            !paymasterCode || paymasterCode === '0x' || keccak256(paymasterCode).toLowerCase() !== terms.paymasterCodeHash.toLowerCase() ||
+            !outputCode || outputCode === '0x' || keccak256(outputCode).toLowerCase() !== output.codeHash.toLowerCase() ||
+            (await client.getBlock({ blockNumber: block.number })).hash !== block.hash)
+            return refuse('SPONSOR_ACCOUNT_PROOF_MISMATCH');
+        const authority = SPONSORED_AUTHORITY_SCHEMA.parse({ userId: who.userId, account, mintKey: cap.mintKey,
+            grantExpiresAt: new Date(Date.parse(grant.expiresAt)).toISOString(), revokeGeneration: generation,
+            capVersion: cap.requiredVersion, perSwapCapUsd: cap.perSwapCapUsd,
+            activationDigest: sponsoredDigest(activation), policyRulesDigest: activation.policyRulesDigest });
+        await this.assertCurrentCap(authority);
+        return authority;
+    }
+    /** Called synchronously under the operation handoff lock. Stop and request start are ordered by caps.db. */
+    withCurrentCap(authority, start) {
+        if (!this.caps.available || !this.caps.withCurrentActiveCap)
+            return refuse('SPONSOR_CAP_UNAVAILABLE');
+        return this.caps.withCurrentActiveCap({ userId: authority.userId, mintKey: authority.mintKey,
+            expiresAt: authority.grantExpiresAt, perSwapCapUsd: authority.perSwapCapUsd,
+            requiredVersion: authority.capVersion, revokeGeneration: authority.revokeGeneration }, this.now, start);
+    }
+    async assertCurrentCap(authority) {
+        const [cap, generation] = await Promise.all([
+            this.caps.readActive(authority.userId, this.now()), this.caps.readRevokeGeneration(authority.userId),
+        ]);
+        if (!cap || cap.state !== 'confirmed_active' || cap.mintKey !== authority.mintKey ||
+            cap.requiredVersion !== authority.capVersion || cap.revokeGeneration !== generation || generation !== authority.revokeGeneration ||
+            cap.perSwapCapUsd !== authority.perSwapCapUsd || Date.parse(cap.expiresAt) !== Date.parse(authority.grantExpiresAt) ||
+            Date.parse(cap.expiresAt) <= this.now())
+            return refuse('SPONSOR_STOP_OR_CAP_CHANGED');
+    }
+    async preflight(operation) {
+        const client = this.client(operation.context.chainId);
+        const balance = await client.readContract({ address: SPONSORED_USDC[operation.context.chainId],
+            abi: parseAbi(['function balanceOf(address owner) view returns(uint256)']), functionName: 'balanceOf', args: [operation.context.account] });
+        if (balance < BigInt(operation.context.intent.fromAmount))
+            return refuse('SPONSOR_BALANCE_INSUFFICIENT');
+    }
+    async readAcknowledgement(operation, expectedCalls) {
+        if (!operation.userOpHash)
+            return refuse('SPONSOR_SUBMISSION_UNRESOLVED');
+        const result = await this.cdp.evm.getUserOperation({ smartAccount: operation.context.account, userOpHash: operation.userOpHash });
+        const calls = result.calls.map(call => ({ to: getAddress(call.to).toLowerCase(), data: call.data.toLowerCase(), value: call.value.toString() }));
+        if (result.userOpHash.toLowerCase() !== operation.userOpHash.toLowerCase() ||
+            result.network !== SPONSORED_CDP_NETWORKS[operation.context.chainId] ||
+            JSON.stringify(calls) !== JSON.stringify(expectedCalls) ||
+            !['pending', 'signed', 'broadcast', 'complete', 'dropped', 'failed'].includes(result.status) ||
+            (result.transactionHash && !/^0x[0-9a-fA-F]{64}$/.test(result.transactionHash)))
+            return refuse('SPONSOR_USER_OPERATION_MISMATCH');
+        return { userOpHash: result.userOpHash, status: result.status,
+            ...(result.transactionHash ? { transactionHash: result.transactionHash } : {}) };
+    }
+}
+//# sourceMappingURL=execution-sponsored-runtime.js.map

package/dist/execution-sponsored-settlement.d.ts

@@ -0,0 +1,15 @@
+import { type Address, type Hex, type TransactionReceipt, type PublicClient } from 'viem';
+import { type SponsoredOperation } from './execution-sponsored-definition.js';
+import type { ConfirmedSponsoredReceipt } from './execution-sponsored-receipt.js';
+/** Isolate execution logs belonging to this UserOp, excluding every other operation in its bundle. */
+export declare function sponsoredOperationLogs(receipt: TransactionReceipt, entryPoint: Address, userOpHash: Hex): import("viem").Log<bigint, number, false>[];
+export declare function readSponsoredSwapSettlement(operation: SponsoredOperation, confirmed: ConfirmedSponsoredReceipt, client: PublicClient): Promise<{
+    inputToken: `0x${string}`;
+    outputToken: `0x${string}`;
+    inputDebited: string;
+    outputReceived: string;
+    ottoFeeReceived: string;
+    allowanceAfter: "0";
+    userOpHash: `0x${string}`;
+    transactionHash: `0x${string}`;
+}>;