otto-intel-mcp 0.1.2 → 0.1.4

package/dist/execution-sponsored-store.js

@@ -0,0 +1,517 @@
+import { ACCOUNT_GAS_FAILURE_SCHEMA } from './execution-account-gas-view.js';
+import { accountGasCallsCommitment } from './execution-account-gas-quote.js';
+import { nativeYieldUserOpRecordedCalls } from './native-yield-userop.js';
+import { lpUserOpRecordedCalls } from './lp-userop.js';
+import { ACCOUNT_GAS_REVIEW_SCHEMA } from './execution-account-gas-review.js';
+import { SPONSORED_OPERATION_SCHEMA as SPONSORED_STORAGE_SCHEMA, assertExecutionStorageSchema, assertDeclaredExecutionStorage } from './execution-journal-tables.js';
+/** Sponsored reviews and operations share the existing cross-rail claim database. */
+import { randomUUID } from 'node:crypto';
+import { access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { sqliteWalRuntimeIsSafe } from './execution-delegation-operation-store.js';
+import { assertExecutionJournalCompatible, claimSponsoredExecution, releaseSponsoredExecutionClaim, readUserExecutionClaim, readExecutionJournalStatus, requireSponsoredExecutionJournalReady, requireNativeUserOpJournalReady, requireLpUserOpJournalReady } from './execution-journal-schema.js';
+import { SPONSORED_OPERATION_SCHEMA, SPONSORED_CONTEXT_SCHEMA, SPONSORED_STORED_REQUEST_SCHEMA, SPONSORED_RECEIPT_SCHEMA, SPONSORED_SETTLEMENT_SCHEMA, sponsoredDigest, sponsoredReviewCommitment, sponsoredPlan, sponsoredCalls, sponsoredChainTerms, SPONSORED_USDC, } from './execution-sponsored-definition.js';
+import { SPONSORED_CDP_NETWORKS } from './execution-sponsored-transport.js';
+import { NATIVE_USEROP_CONTEXT_SCHEMA, assertNativeUserOpContext, validateNativeUserOpOperation, nativeUserOpReviewCommitment } from './native-yield-userop-operation.js';
+import { NATIVE_YIELD_USEROP_SETTLEMENT_SCHEMA } from './native-yield-userop-definition.js';
+import { LP_USEROP_CONTEXT_SCHEMA, assertLpUserOpContext, validateLpUserOpOperation, lpUserOpReviewCommitment } from './lp-userop-operation.js';
+import { LP_USEROP_SETTLEMENT_SCHEMA } from './lp-userop-settlement.js';
+import { LP_USEROP_SUBMIT_EVIDENCE_SCHEMA } from './lp-userop.js';
+const handoffProofBrand = Symbol('sponsored-uninvoked-handoff');
+const isNativeContext = (context) => 'kind' in context && context.kind === 'native-yield-userop';
+const isLpContext = (context) => 'kind' in context && context.kind === 'lp-collect-userop';
+function validateSponsoredRecord(raw) {
+    if (!raw || typeof raw !== 'object' || !('version' in raw))
+        return invalid();
+    let op;
+    switch (raw.version) {
+        case 1:
+            op = validateSponsoredOperation(raw);
+            break;
+        case 2:
+            op = validateNativeUserOpOperation(raw);
+            break;
+        case 3:
+            op = validateLpUserOpOperation(raw);
+            break;
+        default: return invalid();
+    }
+    if (op.gasReview) {
+        const quote = op.gasReview.quote, terms = sponsoredChainTerms(op.context.activation, op.context.chainId);
+        const calls = op.version === 1 ? sponsoredCalls(sponsoredPlan(op.context)) : op.version === 2
+            ? nativeYieldUserOpRecordedCalls(op.context.envelope) : lpUserOpRecordedCalls(op.context.envelope);
+        if (!op.context.activation.gasPaymentReviewEnabled || quote.account.toLowerCase() !== op.context.account.toLowerCase() ||
+            quote.chainId !== op.context.chainId || quote.entryPoint.toLowerCase() !== terms.entryPoint.toLowerCase() ||
+            quote.callsCommitment !== accountGasCallsCommitment(calls))
+            invalid();
+    }
+    return op;
+}
+function artifactKey(context) {
+    return isNativeContext(context) || isLpContext(context) ? context.envelope.commitment : context.envelope.submission.artifact_digest;
+}
+function assertFreshContext(context, now) {
+    if (isNativeContext(context))
+        assertNativeUserOpContext(context, true, now);
+    else if (isLpContext(context))
+        assertLpUserOpContext(context, true, now);
+    else
+        sponsoredPlan(context, true, now);
+}
+const unresolved = (op) => op.reviewConsumed && !['completed', 'failed'].includes(op.state);
+function invalid() { throw new Error('SPONSOR_JOURNAL_INVALID'); }
+export function validateSponsoredOperation(raw) {
+    const op = SPONSORED_OPERATION_SCHEMA.parse(raw), context = op.context;
+    if (op.userId !== context.authority.userId || context.account !== context.authority.account ||
+        context.authority.activationDigest !== sponsoredDigest(context.activation) ||
+        context.authority.policyRulesDigest !== context.activation.policyRulesDigest ||
+        op.reviewCommitment !== sponsoredReviewCommitment(op.operationId, context, op.gasReview) ||
+        (op.state === 'review') !== !op.reviewConsumed || op.updatedAtMs < op.createdAtMs ||
+        context.reviewedAtMs !== op.createdAtMs || context.validUntilMs <= context.reviewedAtMs ||
+        context.validUntilMs > Date.parse(context.envelope.valid_until) || context.validUntilMs > context.activation.expiresAtMs)
+        invalid();
+    const plan = sponsoredPlan(context), terms = sponsoredChainTerms(context.activation, context.chainId);
+    if (plan.token !== SPONSORED_USDC[context.chainId] || plan.gross > BigInt(Math.min(context.authority.perSwapCapUsd, context.activation.maxSwapUsdc)) * 1000000n)
+        invalid();
+    if (op.request) {
+        const body = JSON.parse(op.request.body);
+        const expectedBody = JSON.stringify({ network: SPONSORED_CDP_NETWORKS[context.chainId], calls: sponsoredCalls(plan),
+            useCdpPaymaster: false, ...(op.gasReview?.payer === 'account' ? {} : { paymasterAlias: `pimlico:${context.chainId}`, paymasterContext: { sponsorshipPolicyId: terms.sponsorshipPolicyId } }) });
+        if (op.request.userId !== op.userId || op.request.account !== context.account || op.request.chainId !== context.chainId ||
+            op.request.idempotencyKey !== op.operationId.slice(3) ||
+            op.request.path !== `/platform/v2/embedded-wallet-api/end-users/${op.userId}/evm/smart-accounts/${context.account.toLowerCase()}/send` ||
+            op.request.body !== expectedBody ||
+            'paymasterUrl' in body || body.useCdpPaymaster !== false)
+            invalid();
+    }
+    if (op.handoffAttempted && !op.request)
+        invalid();
+    if (op.state === 'review' && (op.request || op.handoffAttempted || op.userOpHash || op.transactionHash))
+        invalid();
+    if ((op.userOpHash || op.transactionHash || op.receipt) && !op.handoffAttempted)
+        invalid();
+    if (op.transactionHash && !op.userOpHash)
+        invalid();
+    if (op.receipt && (op.receipt.userOpHash.toLowerCase() !== op.userOpHash?.toLowerCase() ||
+        op.receipt.transactionHash.toLowerCase() !== op.transactionHash?.toLowerCase() || op.receipt.chainId !== context.chainId ||
+        op.receipt.account !== context.account || op.receipt.paymaster !== (op.gasReview?.payer === 'account' ? '0x0000000000000000000000000000000000000000' : terms.paymaster) ||
+        (op.gasReview?.payer !== 'account' && BigInt(op.receipt.actualGasCostWei) > BigInt(terms.maxGasCostWei))))
+        invalid();
+    if (op.gasCapBreach && (op.gasReview?.payer === 'account' || !op.handoffAttempted || op.state !== 'submitted' || op.receipt || op.settlement ||
+        op.failureCode !== 'SPONSOR_GAS_CAP_EXCEEDED' ||
+        op.gasCapBreach.userOpHash.toLowerCase() !== op.userOpHash?.toLowerCase() ||
+        op.gasCapBreach.transactionHash.toLowerCase() !== op.transactionHash?.toLowerCase() ||
+        op.gasCapBreach.chainId !== context.chainId || op.gasCapBreach.account !== context.account ||
+        op.gasCapBreach.paymaster !== terms.paymaster ||
+        BigInt(op.gasCapBreach.actualGasCostWei) <= BigInt(terms.maxGasCostWei)))
+        invalid();
+    if (op.state === 'completed') {
+        const result = op.settlement;
+        if (op.receipt?.status !== 'success' || !result || result.userOpHash !== op.userOpHash ||
+            result.transactionHash !== op.transactionHash || result.inputToken !== plan.token || result.outputToken !== plan.outputToken ||
+            BigInt(result.inputDebited) !== plan.gross || BigInt(result.outputReceived) < plan.minAmountOut ||
+            BigInt(result.ottoFeeReceived) < plan.ottoFee)
+            invalid();
+    }
+    else if (op.settlement)
+        invalid();
+    if (op.state === 'failed' && op.handoffAttempted && op.receipt?.status !== 'reverted')
+        invalid();
+    if (op.state === 'submitted' && !op.userOpHash)
+        invalid();
+    return op;
+}
+export class SponsoredOperationStore {
+    db;
+    now;
+    kind;
+    handoffProofs = new WeakMap();
+    constructor(db, now = Date.now, kind = 'swap') {
+        this.db = db;
+        this.now = now;
+        this.kind = kind;
+        assertExecutionJournalCompatible(db, 4);
+        assertExecutionStorageSchema(db, SPONSORED_STORAGE_SCHEMA);
+        this.transaction(() => {
+            const operations = this.all();
+            for (const op of operations.filter(unresolved))
+                this.requireClaim(op);
+            const claims = db.prepare("SELECT user_id,claim_id FROM user_execution_claims WHERE kind='sponsored'").all();
+            if (claims.some(c => !operations.some(op => unresolved(op) && op.userId === c.user_id && op.operationId === c.claim_id)))
+                invalid();
+        });
+    }
+    /** Typed view of the SAME connection, table, transaction, cross-rail claim and gas budget. */
+    forNativeYieldUserOp() {
+        return new SponsoredOperationStore(this.db, this.now, 'native-yield-userop');
+    }
+    forLpV3CollectUserOp() {
+        return new SponsoredOperationStore(this.db, this.now, 'lp-collect-userop');
+    }
+    narrow(op) {
+        const version = this.kind === 'swap' ? 1 : this.kind === 'native-yield-userop' ? 2 : 3;
+        if (op.version !== version)
+            throw new Error('SPONSOR_OPERATION_KIND_MISMATCH');
+        return op;
+    }
+    journalStatus() { assertExecutionJournalCompatible(this.db, 4); return readExecutionJournalStatus(this.db); }
+    assertReadyForNewOperations() {
+        requireSponsoredExecutionJournalReady(this.db);
+        if (this.kind === 'native-yield-userop')
+            requireNativeUserOpJournalReady(this.db);
+        if (this.kind === 'lp-collect-userop')
+            requireLpUserOpJournalReady(this.db);
+    }
+    transaction(fn) {
+        const outer = this.db.isTransaction === true, savepoint = `sponsor_${randomUUID().replaceAll('-', '')}`;
+        this.db.exec(outer ? `SAVEPOINT ${savepoint}` : 'BEGIN IMMEDIATE');
+        try {
+            assertExecutionJournalCompatible(this.db, 4);
+            const result = fn();
+            this.db.exec(outer ? `RELEASE ${savepoint}` : 'COMMIT');
+            return result;
+        }
+        catch (error) {
+            try {
+                if (outer) {
+                    this.db.exec(`ROLLBACK TO ${savepoint}`);
+                    this.db.exec(`RELEASE ${savepoint}`);
+                }
+                else
+                    this.db.exec('ROLLBACK');
+            }
+            catch { /* preserve refusal */ }
+            throw error;
+        }
+    }
+    decode(row) {
+        if (!row)
+            return undefined;
+        const r = row;
+        const op = validateSponsoredRecord(JSON.parse(r.record_json));
+        const schema = readExecutionJournalStatus(this.db).schemaVersion;
+        if ((op.version === 2 && schema < 5) || (op.version === 3 && schema < 6))
+            invalid();
+        if (op.operationId !== r.operation_id || op.userId !== r.user_id || artifactKey(op.context) !== r.artifact_key)
+            invalid();
+        return op;
+    }
+    all() {
+        return this.db.prepare('SELECT * FROM sponsored_operations').all().map(row => this.decode(row));
+    }
+    assertContextBudgetAvailable(context) {
+        if (this.all().some(op => op.context.activation.id === context.activation.id &&
+            op.context.chainId === context.chainId && op.gasCapBreach))
+            throw new Error('SPONSOR_BUDGET_HALTED');
+    }
+    /** Also checks reviews admitted before another user's proven provider-cap breach. */
+    assertBudgetAvailable(userId, operationId) {
+        this.assertContextBudgetAvailable(this.read(userId, operationId).context);
+    }
+    /** Linearize a transport handoff with every durable gas-cap breach. The callback starts
+     * fetch synchronously and returns its promise; this transaction never awaits the network. */
+    handoff(userId, operationId, start) {
+        let pending;
+        try {
+            return this.transaction(() => {
+                const op = this.read(userId, operationId);
+                this.requireClaim(op);
+                if (!op.handoffAttempted || !op.request || op.state !== 'unknown' || op.userOpHash ||
+                    (op.version === 3 && !op.submitEvidence))
+                    invalid();
+                this.assertContextBudgetAvailable(op.context);
+                assertFreshContext(op.context, this.now());
+                if (op.context.validUntilMs <= this.now())
+                    throw new Error('SPONSOR_REVIEW_EXPIRED');
+                pending = start();
+                return pending;
+            });
+        }
+        catch (error) {
+            // A commit error cannot undo an invoked fetch. Retain its durable attempted claim,
+            // and handle a later rejection while the caller reports the original uncertainty.
+            void pending?.catch(() => undefined);
+            throw error;
+        }
+    }
+    requireClaim(op) {
+        const claim = readUserExecutionClaim(this.db, op.userId);
+        if (claim?.kind !== 'sponsored' || claim.claimId !== op.operationId)
+            invalid();
+    }
+    read(userId, operationId) {
+        assertExecutionJournalCompatible(this.db, 4);
+        const op = this.decode(this.db.prepare('SELECT * FROM sponsored_operations WHERE user_id=? AND operation_id=?').get(userId, operationId));
+        if (!op)
+            throw new Error('SPONSOR_OPERATION_NOT_FOUND');
+        if (unresolved(op))
+            this.requireClaim(op);
+        return this.narrow(op);
+    }
+    save(op) {
+        op.updatedAtMs = this.now();
+        validateSponsoredRecord(op);
+        const result = this.db.prepare('UPDATE sponsored_operations SET record_json=? WHERE user_id=? AND operation_id=?')
+            .run(JSON.stringify(op), op.userId, op.operationId);
+        if (Number(result.changes) !== 1)
+            invalid();
+        return op;
+    }
+    create(raw) {
+        return this.transaction(() => {
+            this.assertReadyForNewOperations();
+            const context = this.kind === 'native-yield-userop' ? NATIVE_USEROP_CONTEXT_SCHEMA.parse(raw)
+                : this.kind === 'lp-collect-userop' ? LP_USEROP_CONTEXT_SCHEMA.parse(raw) : SPONSORED_CONTEXT_SCHEMA.parse(raw);
+            const operationId = `sp_${randomUUID()}`, now = this.now();
+            this.assertContextBudgetAvailable(context);
+            if (readUserExecutionClaim(this.db, context.authority.userId))
+                throw new Error('SPONSOR_EXECUTION_BUSY');
+            const op = this.narrow(validateSponsoredRecord({ version: this.kind === 'native-yield-userop' ? 2 : this.kind === 'lp-collect-userop' ? 3 : 1, operationId, userId: context.authority.userId, context,
+                reviewCommitment: isNativeContext(context) ? nativeUserOpReviewCommitment(operationId, context)
+                    : isLpContext(context) ? lpUserOpReviewCommitment(operationId, context) : sponsoredReviewCommitment(operationId, context), reviewConsumed: false,
+                state: 'review', createdAtMs: context.reviewedAtMs, updatedAtMs: now, handoffAttempted: false }));
+            this.db.prepare('INSERT INTO sponsored_operations(operation_id,user_id,artifact_key,record_json) VALUES(?,?,?,?)')
+                .run(operationId, op.userId, artifactKey(context), JSON.stringify(op));
+            return op;
+        });
+    }
+    /** Re-price only an unconsumed review or an exact, terminal proof that no request started.
+     * The same operation ID remains the recovery identity; changed gas terms require new consent. */
+    reviewGas(userId, operationId, expectedReviewCommitment, raw) {
+        return this.transaction(() => {
+            this.assertReadyForNewOperations();
+            const op = this.read(userId, operationId);
+            if (op.reviewCommitment !== expectedReviewCommitment || op.handoffAttempted || op.userOpHash ||
+                op.transactionHash || op.receipt || op.settlement || op.gasCapBreach ||
+                (op.state !== 'review' && !(op.state === 'failed' && op.failureCode === 'SPONSOR_NOT_SUBMITTED')) ||
+                !op.context.activation.gasPaymentReviewEnabled || op.context.validUntilMs <= this.now() ||
+                readUserExecutionClaim(this.db, userId))
+                throw new Error('ACCOUNT_GAS_REVIEW_UNAVAILABLE');
+            const gasReview = ACCOUNT_GAS_REVIEW_SCHEMA.parse(raw);
+            if (gasReview.revision !== (op.gasReview?.revision ?? 0) + 1 ||
+                gasReview.quote.account.toLowerCase() !== op.context.account.toLowerCase() || gasReview.quote.chainId !== op.context.chainId)
+                throw new Error('ACCOUNT_GAS_REVIEW_INVALID');
+            op.gasReview = gasReview;
+            op.reviewCommitment = isNativeContext(op.context) ? nativeUserOpReviewCommitment(operationId, op.context, gasReview)
+                : isLpContext(op.context) ? lpUserOpReviewCommitment(operationId, op.context, gasReview)
+                    : sponsoredReviewCommitment(operationId, op.context, gasReview);
+            op.state = 'review';
+            op.reviewConsumed = false;
+            delete op.request;
+            delete op.failureCode;
+            delete op.gasReviewFailure;
+            if ('submitEvidence' in op)
+                delete op.submitEvidence;
+            return this.save(op);
+        });
+    }
+    recordGasReviewFailure(userId, operationId, failure) {
+        return this.transaction(() => {
+            const op = this.read(userId, operationId);
+            if (op.handoffAttempted || op.userOpHash || op.transactionHash ||
+                (op.state !== 'review' && !(op.state === 'failed' && op.failureCode === 'SPONSOR_NOT_SUBMITTED')))
+                return op;
+            op.gasReviewFailure = ACCOUNT_GAS_FAILURE_SCHEMA.parse(failure);
+            return this.save(op);
+        });
+    }
+    begin(userId, operationId, reviewCommitment, authority) {
+        return this.transaction(() => {
+            this.assertReadyForNewOperations();
+            const op = this.read(userId, operationId);
+            if (op.state !== 'review' || op.reviewConsumed || op.reviewCommitment !== reviewCommitment ||
+                op.context.validUntilMs <= this.now() || sponsoredDigest(authority) !== sponsoredDigest(op.context.authority))
+                throw new Error('SPONSOR_REVIEW_REQUIRED');
+            this.assertContextBudgetAvailable(op.context);
+            const terms = sponsoredChainTerms(op.context.activation, op.context.chainId);
+            let total = 0n, user = 0n;
+            for (const prior of this.all()) {
+                if (prior.gasReview?.payer === 'account' || !prior.reviewConsumed || prior.context.activation.id !== op.context.activation.id || prior.context.chainId !== op.context.chainId)
+                    continue;
+                const cost = prior.receipt ? BigInt(prior.receipt.actualGasCostWei) : prior.state === 'failed' && !prior.handoffAttempted
+                    ? 0n : BigInt(sponsoredChainTerms(prior.context.activation, prior.context.chainId).maxGasCostWei);
+                total += cost;
+                if (prior.userId === userId)
+                    user += cost;
+            }
+            if (op.gasReview?.payer !== 'account' && (total + BigInt(terms.maxGasCostWei) > BigInt(terms.maxTotalGasCostWei) ||
+                user + BigInt(terms.maxGasCostWei) > BigInt(terms.maxUserGasCostWei)))
+                throw new Error('SPONSOR_BUDGET_EXHAUSTED');
+            if (claimSponsoredExecution(this.db, { userId, operationId }, this.now()).outcome !== 'started')
+                throw new Error('SPONSOR_EXECUTION_BUSY');
+            op.reviewConsumed = true;
+            op.state = 'active';
+            return this.save(op);
+        });
+    }
+    prepare(userId, operationId, request) {
+        return this.transaction(() => {
+            const op = this.read(userId, operationId);
+            this.requireClaim(op);
+            if (op.state !== 'active' || op.request || op.handoffAttempted)
+                invalid();
+            op.request = SPONSORED_STORED_REQUEST_SCHEMA.parse(request);
+            return this.save(op);
+        });
+    }
+    /** Write the final independent submit baseline once, before the durable attempted stamp and fetch. */
+    recordLpVerification(userId, operationId, raw) {
+        return this.transaction(() => {
+            const op = this.read(userId, operationId);
+            this.requireClaim(op);
+            if (op.version !== 3 || op.state !== 'active' || op.handoffAttempted || !op.request || op.userOpHash || op.submitEvidence)
+                invalid();
+            op.submitEvidence = LP_USEROP_SUBMIT_EVIDENCE_SCHEMA.parse(raw);
+            return this.save(op);
+        });
+    }
+    attempted(userId, operationId) {
+        return this.transaction(() => {
+            const op = this.read(userId, operationId);
+            this.requireClaim(op);
+            if (!op.request || op.handoffAttempted || op.state !== 'active' || (op.version === 3 && !op.submitEvidence))
+                invalid();
+            op.handoffAttempted = true;
+            op.state = 'unknown';
+            return this.save(op);
+        });
+    }
+    /** Only a successfully committed standalone stamp can mint this one-use process proof.
+     * Losing it on crash/restart deliberately leaves the original attempted claim unresolved. */
+    attemptedWithProof(userId, operationId) {
+        if (this.db.isTransaction === true)
+            invalid();
+        const op = this.attempted(userId, operationId);
+        const proof = Object.freeze({ [handoffProofBrand]: true });
+        this.handoffProofs.set(proof, { userId, operationId, recordDigest: sponsoredDigest(op) });
+        return proof;
+    }
+    uninvokedHandoff(proof) {
+        const recorded = proof && this.handoffProofs.get(proof);
+        if (!recorded)
+            invalid();
+        try {
+            const op = this.read(recorded.userId, recorded.operationId);
+            this.requireClaim(op);
+            if (op.state !== 'unknown' || !op.handoffAttempted || !op.request || op.userOpHash || op.transactionHash ||
+                op.receipt || op.gasCapBreach || sponsoredDigest(op) !== recorded.recordDigest)
+                invalid();
+            return op;
+        }
+        catch (error) {
+            // A changed row can never regain this process proof by later restoring old bytes.
+            this.handoffProofs.delete(proof);
+            throw error;
+        }
+    }
+    /** Called under handoff's writer lock immediately BEFORE the actual provider callback.
+     * A synchronous callback throw is therefore ambiguous and can never release the claim. */
+    consumeHandoffProof(proof) {
+        if (this.db.isTransaction !== true)
+            invalid();
+        this.uninvokedHandoff(proof);
+        this.handoffProofs.delete(proof);
+    }
+    /** Same-process, exact-row non-invocation is the sole exception to retaining a stamped claim. */
+    failUninvokedHandoff(proof) {
+        const op = this.transaction(() => {
+            const current = this.uninvokedHandoff(proof);
+            current.handoffAttempted = false;
+            current.state = 'failed';
+            current.failureCode = 'SPONSOR_NOT_SUBMITTED';
+            this.save(current);
+            releaseSponsoredExecutionClaim(this.db, { userId: current.userId, operationId: current.operationId });
+            return current;
+        });
+        this.handoffProofs.delete(proof);
+        return op;
+    }
+    acknowledged(userId, operationId, result) {
+        return this.transaction(() => {
+            const op = this.read(userId, operationId);
+            this.requireClaim(op);
+            if (!op.handoffAttempted || (op.userOpHash && op.userOpHash.toLowerCase() !== result.userOpHash.toLowerCase()) ||
+                (op.transactionHash && result.transactionHash && op.transactionHash.toLowerCase() !== result.transactionHash.toLowerCase()))
+                invalid();
+            op.userOpHash = result.userOpHash;
+            if (result.transactionHash)
+                op.transactionHash = result.transactionHash;
+            op.state = 'submitted';
+            return this.save(op);
+        });
+    }
+    failBeforeHandoff(userId, operationId) {
+        return this.transaction(() => {
+            const op = this.read(userId, operationId);
+            this.requireClaim(op);
+            if (op.handoffAttempted)
+                invalid();
+            op.state = 'failed';
+            op.failureCode = 'SPONSOR_NOT_SUBMITTED';
+            this.save(op);
+            releaseSponsoredExecutionClaim(this.db, { userId, operationId });
+            return op;
+        });
+    }
+    recordGasCapBreach(userId, operationId, receipt) {
+        return this.transaction(() => {
+            const op = this.read(userId, operationId);
+            this.requireClaim(op);
+            const proof = SPONSORED_RECEIPT_SCHEMA.parse(receipt);
+            if (op.gasCapBreach && sponsoredDigest(op.gasCapBreach) !== sponsoredDigest(proof))
+                invalid();
+            op.gasCapBreach = proof;
+            op.failureCode = 'SPONSOR_GAS_CAP_EXCEEDED';
+            // Validation binds the canonical proof to this exact submitted operation and a real cap breach.
+            // The original cross-rail claim remains held. There is deliberately no automatic circuit reset.
+            return this.save(op);
+        });
+    }
+    finish(userId, operationId, receipt, settlement) {
+        return this.transaction(() => {
+            const op = this.read(userId, operationId);
+            this.requireClaim(op);
+            op.receipt = SPONSORED_RECEIPT_SCHEMA.parse(receipt);
+            op.state = receipt.status === 'success' ? 'completed' : 'failed';
+            if (op.version === 2)
+                op.settlement = NATIVE_YIELD_USEROP_SETTLEMENT_SCHEMA.parse(settlement);
+            else if (op.version === 3)
+                op.settlement = LP_USEROP_SETTLEMENT_SCHEMA.parse(settlement);
+            else if (receipt.status === 'success')
+                op.settlement = SPONSORED_SETTLEMENT_SCHEMA.parse(settlement);
+            if (receipt.status === 'reverted')
+                op.failureCode = 'SPONSOR_USER_OPERATION_REVERTED';
+            this.save(op);
+            releaseSponsoredExecutionClaim(this.db, { userId, operationId });
+            return op;
+        });
+    }
+}
+/** Does not initialize or migrate: the coordinated offline rollout must already have installed v4. */
+export async function openSponsoredOperationStore(root, now = Date.now) {
+    const path = join(root, 'operations.db');
+    await access(path);
+    const specifier = 'node:sqlite';
+    const { DatabaseSync } = await import(specifier);
+    const uri = pathToFileURL(path);
+    uri.searchParams.set('mode', 'rw');
+    const db = new DatabaseSync(uri.href);
+    try {
+        const version = db.prepare('SELECT sqlite_version() AS version').get()?.version;
+        if (!sqliteWalRuntimeIsSafe(version))
+            throw new Error('SPONSOR_SQLITE_RUNTIME_UNSAFE');
+        db.exec('PRAGMA busy_timeout=5000');
+        assertExecutionJournalCompatible(db, 4);
+        assertDeclaredExecutionStorage(db, readExecutionJournalStatus(db).schemaVersion);
+        db.exec('PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL; PRAGMA foreign_keys=ON;');
+        if (!db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='operations'").get())
+            invalid();
+        return new SponsoredOperationStore(db, now);
+    }
+    catch (error) {
+        db.close();
+        throw error;
+    }
+}
+//# sourceMappingURL=execution-sponsored-store.js.map

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

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+import { type SponsoredGasPolicyProof } from './execution-sponsored-gas-policy.js';
+/** Self-contained public declarations: inspecting an inactive entry needs no optional SDK. */
+export interface SponsoredCredentials {
+    readonly apiKeyId?: string;
+    readonly apiKeySecret?: string;
+    readonly walletSecret?: string;
+}
+export interface SponsoredAuthOptions extends SponsoredCredentials {
+    readonly requestMethod: string;
+    readonly requestHost: string;
+    readonly requestPath: string;
+    readonly requestBody?: unknown;
+    readonly source?: string;
+}
+export type SponsoredAuth = (options: SponsoredAuthOptions) => Promise<Record<string, string>>;
+export declare const SPONSORED_CDP_NETWORKS: {
+    readonly 1: "ethereum";
+    readonly 8453: "base";
+    readonly 42161: "arbitrum";
+    readonly 10: "optimism";
+    readonly 137: "polygon";
+};
+export type SponsoredChainId = keyof typeof SPONSORED_CDP_NETWORKS;
+export type SponsoredGasPayer = 'sponsor' | 'account';
+declare const callSchema: z.ZodObject<{
+    to: z.ZodString;
+    data: z.ZodString;
+    value: z.ZodString;
+}, z.core.$strict>;
+declare const responseSchema: z.ZodObject<{
+    network: z.ZodString;
+    userOpHash: z.ZodString;
+    calls: z.ZodArray<z.ZodObject<{
+        to: z.ZodString;
+        data: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strict>>;
+    status: z.ZodEnum<{
+        failed: "failed";
+        pending: "pending";
+        signed: "signed";
+        broadcast: "broadcast";
+        complete: "complete";
+        dropped: "dropped";
+    }>;
+    transactionHash: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<"">]>>;
+}, z.core.$strip>;
+export type SponsoredCall = Readonly<z.infer<typeof callSchema>>;
+export interface SponsoredBinding {
+    readonly userId: string;
+    readonly account: string;
+    readonly chainId: SponsoredChainId;
+    readonly idempotencyKey: string;
+}
+export interface SponsoredProviderConfig {
+    readonly chainId: SponsoredChainId;
+    /** Operator-owned URL; never accepted from an MCP request or exposed in a tool response. */
+    readonly paymasterUrl: string;
+    readonly sponsorshipPolicyId: string;
+}
+export interface PreparedSponsoredRequest extends SponsoredBinding {
+    readonly path: string;
+    /** Persistable calls/policy/provider alias. Never contains the paymaster URL or credential. */
+    readonly body: string;
+    readonly digest: string;
+}
+export interface SponsoredAcknowledgement {
+    readonly userOpHash: `0x${string}`;
+    readonly status: z.infer<typeof responseSchema>['status'];
+    readonly transactionHash?: `0x${string}`;
+}
+export declare class SponsoredTransportError extends Error {
+    readonly code: 'SPONSOR_CONFIGURATION_INVALID' | 'SPONSOR_REQUEST_INVALID' | 'SPONSOR_AUTH_UNAVAILABLE' | 'SPONSOR_SUBMISSION_UNCERTAIN';
+    constructor(code: 'SPONSOR_CONFIGURATION_INVALID' | 'SPONSOR_REQUEST_INVALID' | 'SPONSOR_AUTH_UNAVAILABLE' | 'SPONSOR_SUBMISSION_UNCERTAIN');
+}
+export declare function createSponsoredCdpTransport(options: {
+    readonly providers: readonly SponsoredProviderConfig[];
+    readonly credentials: SponsoredCredentials;
+    readonly fetch?: typeof fetch;
+    readonly auth?: SponsoredAuth;
+    readonly now?: () => number;
+    readonly monotonic?: () => number;
+}): Readonly<{
+    prepare: (binding: SponsoredBinding, calls: readonly SponsoredCall[], payer?: SponsoredGasPayer) => PreparedSponsoredRequest;
+    checkGasPolicy: (chainId: SponsoredChainId) => Promise<Readonly<SponsoredGasPolicyProof>>;
+    /** Readiness/Stop/capability must be checked by the owning service after auth and immediately before POST. */
+    send(request: PreparedSponsoredRequest, beforeHandoff: () => Promise<void>, handoff?: (start: (onInvoke?: (gasPolicy?: SponsoredGasPolicyProof) => void) => Promise<Response>) => Promise<Response>): Promise<SponsoredAcknowledgement>;
+}>;
+export {};