otto-intel-mcp 0.1.2 → 0.1.4

package/dist/adapter/cdp-signer.js

@@ -28,19 +28,43 @@ import { createPublicClient, encodeFunctionData, http, serializeTransaction, } f
 import { base } from 'viem/chains';
 import { SealedReceiptTimeoutError, waitForSealedReceipt } from './chain.js';
 import { ERC20_APPROVE_ABI, readAllowance } from './erc20.js';
-import { isAdapterRefusal } from './refusal.js';
+import { AdapterRefusal, isAdapterRefusal } from './refusal.js';
+import { classifyEvmCallFailure, evmCallFailureDetail } from './evm-call-failure.js';
 import { assertPlanSignableBy } from './verify.js';
 export const CDP_CAPABILITIES = Object.freeze(['send_evm_transaction']);
 export const CHAIN_ID = 8453;
 export const NETWORK = 'base';
+/** Internal proof that a step failed before the raw CDP submission function was entered. */
+class DelegatedPreHandoffError extends Error {
+    original;
+    constructor(original) {
+        super('delegated step refused before the CDP hand-off');
+        this.original = original;
+        this.name = 'DelegatedPreHandoffError';
+    }
+}
 const RAW = new WeakMap();
 /** One lifecycle lock PER RIG — shared by every signer over it and by the rig's own public `revoke`. */
 const LOCKS = new WeakMap();
-/** Per rig: the users whose revocation has been REQUESTED (set before the raw revoke is issued; never cleared). */
+/**
+ * Per rig: the GRANTS whose revocation has been REQUESTED, keyed `userId\nexpiryMs`.
+ *
+ * 🔴 PER GRANT, NEVER PER USER (gate finding, HIGH — round 3). It used to be a set of user ids, added to
+ * before the raw revoke and never cleared. Once revoke became available in every screen state, a Stop
+ * press on a screen with NO grant marked the person permanently and bricked every later permission of
+ * theirs on that process. The key is now the grant itself, so a revoke can only ever stop the
+ * permission it was aimed at, and a revoke that found nothing to revoke marks nothing at all.
+ */
 const REVOKE_REQUESTED = new WeakMap();
-/** True once `rig.revoke(userId)` has been called on this rig, whatever it returned. */
-export function revocationRequested(rig, userId) {
-    return REVOKE_REQUESTED.get(rig)?.has(userId) ?? false;
+function grantKey(userId, expiresAt) {
+    return `${userId}\n${Date.parse(expiresAt)}`;
+}
+/**
+ * True once revocation was requested on this rig for THIS grant — the one expiring at `expiresAt`.
+ * A user with no live grant, or with a different one, is not marked.
+ */
+export function revocationRequested(rig, userId, expiresAt) {
+    return REVOKE_REQUESTED.get(rig)?.has(grantKey(userId, expiresAt)) ?? false;
 }
 /** Run `operation` after everything previously queued on this rig has settled; nothing else starts until it settles. */
 function serializedOn(rig, operation) {
@@ -52,9 +76,11 @@ function serializedOn(rig, operation) {
     return run;
 }
 /**
- * A delegated plan halted; `cause` is the structured class above, `allowanceCleared` says whether the
- * router allowance is known to be zero again. The message is for the operator; a consumer that must not
- * relay upstream text reads `cause` and the two fields only.
+ * A delegated plan halted; `cause` is the structured class above. `allowanceCleared` reports only
+ * whether the bounded cleanup's live, unpinned allowance read returned zero. It is diagnostic and is
+ * never sufficient to release a durable operation claim; finalized-canonical recovery owns that proof.
+ * The message is for the operator; a consumer that must not relay upstream text reads `cause` and the
+ * two fields only.
  */
 export class DelegatedPlanHaltedError extends Error {
     failedStep;
@@ -82,6 +108,10 @@ const ABSENT_DELEGATION_ERROR_TYPES = ['delegation_not_found', 'delegation_revok
 export function haltCauseOf(error) {
     if (error instanceof RevocationRequestedError)
         return 'delegation_not_active';
+    if (error instanceof DelegatedTransactionWouldRevertError)
+        return 'would_revert';
+    if (error instanceof DelegatedTransactionEstimateUnavailableError)
+        return 'estimate_unavailable';
     if (error instanceof SealedReceiptTimeoutError)
         return 'receipt_not_sealed';
     if (isAdapterRefusal(error))
@@ -111,13 +141,22 @@ export function createCdpRig(raw) {
         // it lands only after any in-flight plan on this rig and its allowance clear have settled, and a
         // plan queued behind it runs only after the read-back — where it is refused, because the user was
         // marked revocation-requested BEFORE the raw revoke was issued.
+        /**
+         * Revoke the grant this user holds RIGHT NOW, marking that grant — and only that grant —
+         * revocation-requested before the raw call, so a plan already queued behind this is refused whatever
+         * the read-back says. A user with NO live grant is a no-op success: there is nothing to stop, and
+         * marking them would take away permissions they have not been given yet.
+         */
         revoke: (userId) => serializedOn(rig, async () => {
-            requested.add(userId);
+            const before = await raw.readDelegation(userId);
+            if (!before)
+                return;
+            requested.add(grantKey(userId, before.expiresAt));
             try {
                 await raw.revoke(userId);
             }
             catch {
-                // A grant that never existed (or is already gone) reads back as absent below; other failures surface there.
+                // A grant that is already gone reads back as absent below; other failures surface there.
             }
             const after = await raw.readDelegation(userId);
             if (after)
@@ -164,8 +203,14 @@ export async function openCdpRig(credentials, rpcUrl) {
         throw new Error(`RPC reports chainId ${chainId}, expected ${CHAIN_ID} (Base mainnet)`);
     return createCdpRig({
         pub,
-        submit: async (user, transaction) => {
-            const result = await cdp.endUser.sendEvmTransaction({ userId: user.userId, address: user.address, transaction, network: NETWORK });
+        submit: async (user, transaction, idempotencyKey) => {
+            const result = await cdp.endUser.sendEvmTransaction({
+                userId: user.userId,
+                address: user.address,
+                transaction,
+                network: NETWORK,
+                ...(idempotencyKey ? { idempotencyKey } : {}),
+            });
             return result.transactionHash;
         },
         revoke: async (userId) => {
@@ -191,7 +236,41 @@ export async function openCdpRig(credentials, rpcUrl) {
 export function revokeDelegationByUserId(rig, userId) {
     return rig.revoke(userId);
 }
-async function buildUnsignedTransaction(pub, from, step) {
+/**
+ * A plan step whose gas estimate REVERTED. The node evaluates nothing of Coinbase's policy — the policy
+ * engine answers at submission, not at `eth_estimateGas` — so a reverting estimate is a transaction that
+ * would revert on chain, and broadcasting it anyway would spend the user's gas and buy nothing.
+ *
+ * 🔴 THIS IS WHAT THE STATIC 400,000 FALLBACK USED TO DO (2026-09-03, the first live delegated swap):
+ * the estimate reverted, the step went out at 400k, reverted on chain (234k gas burned), and only then
+ * did the halt path clear the allowance. 400k was also below every LI.FI swap's real need (~320–580k
+ * used, 1.1–1.4M quoted), so even a healthy route would have reverted under it. There is no fallback
+ * now: an estimate that reverts is a refusal, by name.
+ */
+export class DelegatedTransactionWouldRevertError extends AdapterRefusal {
+    stepKind;
+    constructor(stepKind, detail) {
+        super('DELEGATED_TX_WOULD_REVERT', `the ${stepKind} transaction would revert on chain (gas estimate reverted${detail ? `: ${detail}` : ''}); it was not broadcast, and no allowance was changed by this plan`);
+        this.stepKind = stepKind;
+        this.name = 'DelegatedTransactionWouldRevertError';
+    }
+}
+/**
+ * A plan step the node could not estimate AT ALL — a timeout, a rate limit, a dropped connection. Nothing
+ * is proven about the transaction, so nothing is broadcast without an estimate; but it is NOT a revert:
+ * the caller may retry, and no route is blamed (gate r7, finding 2).
+ */
+export class DelegatedTransactionEstimateUnavailableError extends AdapterRefusal {
+    stepKind;
+    constructor(stepKind, detail) {
+        super('DELEGATED_TX_ESTIMATE_UNAVAILABLE', `the ${stepKind} transaction could not be estimated by the node (${detail || 'no detail'}); nothing was broadcast — retry`);
+        this.stepKind = stepKind;
+        this.name = 'DelegatedTransactionEstimateUnavailableError';
+    }
+}
+/** The bounded limit the halt path's `approve(spender, 0)` uses when the node cannot estimate it. */
+export const ALLOWANCE_CLEAR_STATIC_GAS = 80000n;
+async function buildUnsignedTransaction(pub, from, step, onEstimateFailure) {
     const [nonce, fees] = await Promise.all([
         pub.getTransactionCount({ address: from, blockTag: 'pending' }),
         pub.estimateFeesPerGas(),
@@ -200,10 +279,24 @@ async function buildUnsignedTransaction(pub, from, step) {
     try {
         gas = ((await pub.estimateGas({ account: from, to: step.to, value: step.value, data: step.data })) * 12n) / 10n;
     }
-    catch {
-        // An out-of-policy transaction is still a valid transaction; a node-side estimate failure must not
-        // be confused with the policy engine refusing. Keep a generous static limit.
-        gas = 400000n;
+    catch (error) {
+        /**
+         * 🔴 TWO FACTS, TWO ANSWERS (gate r7, findings 1 and 2). The node either PROVED the transaction would
+         * revert, or it could not answer. A proven revert is never broadcast — not a plan step, and not the
+         * halt path's `approve(spender, 0)` either: a clear the node has already shown to revert is a spend
+         * with nothing bought, and the halt reports it as NOT cleared with the hand-off. A node that could
+         * not answer proves nothing: a plan step is refused as retriable (no route is blamed), while the
+         * halt's clear — the safety action, of a fixed shape — still goes out on a bounded static limit.
+         */
+        const failure = classifyEvmCallFailure(error);
+        const detail = evmCallFailureDetail(error);
+        if (failure === 'revert') {
+            throw new DelegatedTransactionWouldRevertError(onEstimateFailure.kind === 'refuse' ? onEstimateFailure.stepKind : 'allowance clear', detail);
+        }
+        if (onEstimateFailure.kind === 'refuse') {
+            throw new DelegatedTransactionEstimateUnavailableError(onEstimateFailure.stepKind, detail);
+        }
+        gas = ALLOWANCE_CLEAR_STATIC_GAS;
     }
     return serializeTransaction({
         type: 'eip1559',
@@ -224,6 +317,37 @@ export class CdpDelegatedSigner {
     #raw;
     #user;
     #sealedWait;
+    /**
+     * An ASYNC re-check the caller runs before every step (`execution-delegation.ts` passes one that
+     * re-reads the grant and its recorded per-swap cap). The synchronous guards below cover revocation and
+     * the plan's own freshness; they cannot cover a fact that lives behind a network read, and a plan
+     * cleared under one permission must not finish executing under the permission that replaced it.
+     * It THROWS to stop the plan; the caller's refusal is halted and the allowance cleared like any other.
+     */
+    #beforeEachStep;
+    /**
+     * The expiry of the grant this plan was CLEARED AGAINST. The revocation marker is per grant now, so
+     * the signer has to name the grant it is asking about; without it the check would be back to "has
+     * anything ever been revoked for this person", which is the sticky, over-broad shape that was wrong.
+     */
+    #grantExpiresAt;
+    /**
+     * 🔴 THE LAST AUTHORITATIVE CHECK, AND IT RUNS AFTER THE TRANSACTION IS BUILT (gate finding, HIGH —
+     * round 3): "the final asynchronous grant/cap check still happens before transaction construction …
+     * only a synchronous abort check precedes raw submission. A revoke/re-mint to a narrower cap during
+     * transaction building therefore escapes the last authoritative check."
+     *
+     * So there are two hooks, and the split is the fix:
+     *   `#afterBuild` — ASYNC, run once the nonce/fee/gas round trips are done. It RE-READS the grant and
+     *     the confirmed record, so a change that landed DURING construction is seen.
+     *   `#beforeSubmit` — SYNCHRONOUS, run immediately before the raw hand-off, asserting what that
+     *     re-read just found. It cannot await, because awaiting is what opens the window it closes.
+     *
+     * A signer given only the sync hook keeps the old behaviour; the delegated tool passes both.
+     */
+    #afterBuild;
+    #beforeSubmit;
+    #submissionJournal;
     constructor(rig, user, options = {}) {
         const raw = RAW.get(rig);
         if (!raw)
@@ -232,6 +356,11 @@ export class CdpDelegatedSigner {
         this.#raw = raw;
         this.#user = Object.freeze({ userId: user.userId, address: user.address });
         this.#sealedWait = options.sealedWait;
+        this.#beforeEachStep = options.beforeEachStep;
+        this.#afterBuild = options.afterBuild;
+        this.#beforeSubmit = options.beforeSubmit;
+        this.#grantExpiresAt = options.grantExpiresAt;
+        this.#submissionJournal = options.submissionJournal;
     }
     get address() {
         return this.#user.address;
@@ -243,20 +372,87 @@ export class CdpDelegatedSigner {
      * Assemble the unsigned transaction from chain reads, run `beforeSubmit` (the plan's freshness /
      * binding re-check, AFTER the RPC round trips and immediately before the hand-off), then submit.
      */
-    async #submit(step, beforeSubmit) {
-        const transaction = await buildUnsignedTransaction(this.#raw.pub, this.#user.address, step);
-        beforeSubmit?.();
-        return this.#raw.submit(this.#user, transaction);
+    async #submit(step, beforeSubmit, journalStep) {
+        let idempotencyKey;
+        let handedToCdp = false;
+        try {
+            // A plan step (it carries `beforeSubmit`) refuses on a reverting estimate; the halt path's clear does not.
+            // The build and journal prepare are inside this boundary: both are provably before the raw hand-off.
+            const transaction = await buildUnsignedTransaction(this.#raw.pub, this.#user.address, step, beforeSubmit ? { kind: 'refuse', stepKind: step.kind ?? 'plan' } : { kind: 'allowance_clear' });
+            if (this.#submissionJournal) {
+                if (!journalStep)
+                    throw new Error('a journaled submission needs a stable step identity');
+                ({ idempotencyKey } = await this.#submissionJournal.prepare({
+                    index: journalStep.index,
+                    kind: journalStep.kind,
+                    userId: this.#user.userId,
+                    address: this.#user.address,
+                    transaction,
+                    network: NETWORK,
+                }));
+            }
+            /**
+             * 🔴 THE AUTHORITATIVE RE-READ, AFTER CONSTRUCTION. A revoke or a narrower re-mint that landed while
+             * the nonce, fees and gas were being fetched is visible here and nowhere earlier.
+             *
+             * 🔴 AND ONLY FOR A PLAN STEP. `beforeSubmit` is passed by `sendPlan` and by nothing else, so it is
+             * the signal that this submission is part of the plan. The halt path's `approve(spender, 0)` goes
+             * out through this same method WITHOUT it, and it must never be gated: the clear is the safety
+             * action that runs precisely BECAUSE something went wrong, including the grant changing under it.
+             * Refusing to clear an allowance because the permission that opened it has gone is the one outcome
+             * nobody wants.
+             */
+            if (beforeSubmit) {
+                // The journal write above is asynchronous. Re-read authority AFTER it, so the final synchronous
+                // checks still stand immediately beside the CDP hand-off rather than before a database wait.
+                await this.#afterBuild?.();
+                beforeSubmit();
+                this.#beforeSubmit?.();
+            }
+            handedToCdp = true;
+            const hash = await this.#raw.submit(this.#user, transaction, idempotencyKey);
+            if (this.#submissionJournal && idempotencyKey && journalStep)
+                await this.#submissionJournal.submitted(journalStep.index, idempotencyKey, hash);
+            return Object.freeze({ hash, ...(idempotencyKey ? { idempotencyKey } : {}) });
+        }
+        catch (error) {
+            if (this.#submissionJournal && idempotencyKey && journalStep) {
+                try {
+                    if (handedToCdp)
+                        await this.#submissionJournal.unknown(journalStep.index, idempotencyKey);
+                    else
+                        await this.#submissionJournal.notSubmitted(journalStep.index, idempotencyKey);
+                }
+                catch {
+                    // The durable row already remains unresolved. Never replace the causal refusal with a journal
+                    // cleanup error, and never retry CDP to compensate for a local write failure.
+                }
+            }
+            // `handedToCdp` flips immediately before entering the raw submission function. While it is false,
+            // zero requests are a local fact, independent of the error class (build, journal, authority recheck,
+            // or any other pre-handoff failure). Preserve that fact for step 0 so no cleanup transaction creates
+            // the first ambiguous request.
+            if (!handedToCdp)
+                throw new DelegatedPreHandoffError(error);
+            throw error;
+        }
     }
-    /** Fail-closed: once revocation was requested for this user on this rig, nothing is submitted for them again. */
+    /**
+     * Fail-closed: once revocation was requested for THE GRANT THIS PLAN IS BOUND TO, nothing more is
+     * submitted under it. A signer built without a grant expiry (the adapter's own direct use) keeps the
+     * old, broader behaviour of refusing nothing here — the delegated tool always passes one.
+     */
     #assertNotRevoked() {
-        if (revocationRequested(this.#rig, this.#user.userId))
+        if (this.#grantExpiresAt !== undefined &&
+            revocationRequested(this.#rig, this.#user.userId, this.#grantExpiresAt)) {
             throw new RevocationRequestedError(this.#user.userId);
+        }
     }
     /**
      * `send_evm_transaction`, under delegation: only a plan `assertPlanSignableBy` accepts for THIS user,
-     * re-checked before every step AND again immediately before each hand-off to CDP (after the nonce /
-     * fee / gas round trips, so an artifact that expires during preparation is never submitted). The plan
+     * re-checked before every step — together with the caller's async `beforeEachStep`, which re-reads the
+     * GRANT and its recorded per-swap cap — AND again immediately before each hand-off to CDP (after the
+     * nonce / fee / gas round trips, so an artifact that expires during preparation is never submitted). The plan
      * halts at the first step that does not succeed; after ANY failure a bounded `approve(spender, 0)` is
      * attempted under the same policy and its real outcome — confirmed by an allowance read-back — is
      * reported. A failed reset may leave a pre-existing allowance, so step 0 is not exempt.
@@ -272,27 +468,61 @@ export class CdpDelegatedSigner {
                 try {
                     this.#assertNotRevoked();
                     assertPlanSignableBy(plan, this, Date.now());
+                    // The caller's async re-check: the grant is still the one this plan was cleared against, and its
+                    // recorded cap still admits it. Runs before EVERY step, so a delegation replaced mid-plan stops
+                    // the remaining ones rather than being carried by the check made before step 0.
+                    await this.#beforeEachStep?.();
                 }
                 catch (error) {
+                    // Before step 0 no transaction has been built, journaled, or handed to CDP. Propagate the
+                    // refusal directly so the caller's zero-step finalizer can release the exact claim. Trying an
+                    // allowance clear here would create the first ambiguous request under a grant that may already
+                    // have been revoked, turning provable no-send into an unnecessary unknown operation.
+                    if (index === 0)
+                        throw error;
                     throw await this.#halt(plan, index, `plan no longer signable before step ${index}: ${error instanceof Error ? error.message : String(error)}`, haltCauseOf(error));
                 }
                 let hash;
                 let receipt;
                 try {
-                    hash = await this.#submit(step, () => {
+                    const submitted = await this.#submit(step, () => {
                         this.#assertNotRevoked();
                         assertPlanSignableBy(plan, this, Date.now());
-                    });
+                    }, { index, kind: step.kind });
+                    hash = submitted.hash;
                     await this.#raw.pub.waitForTransactionReceipt({ hash }); // first sight (may be a preconfirmation) …
                     // … then only the SEALED, CANONICAL receipt counts: the next step is estimated against sealed state,
                     // and a preconfirmation omitted from the sealed block is never reported as success.
                     receipt = await waitForSealedReceipt(this.#raw.pub, hash, this.#sealedWait);
+                    if (this.#submissionJournal && submitted.idempotencyKey) {
+                        await this.#submissionJournal.receipt(index, submitted.idempotencyKey, {
+                            transactionHash: hash,
+                            status: receipt.status,
+                            blockNumber: receipt.blockNumber.toString(),
+                            blockHash: receipt.blockHash,
+                            gasUsed: receipt.gasUsed.toString(),
+                        });
+                    }
                 }
                 catch (error) {
+                    const cause = error instanceof DelegatedPreHandoffError ? error.original : error;
+                    if (index === 0 && error instanceof DelegatedPreHandoffError)
+                        throw cause;
+                    /**
+                     * 🔴 A REVERTING ESTIMATE BEFORE THE FIRST STEP IS A REFUSAL, NOT A HALT. Nothing of this plan has
+                     * reached the chain, so there is no allowance of ours to clear and no reason to spend the user's gas
+                     * on a clear; the caller gets the typed reason and may prepare again. From step 1 on, an earlier step
+                     * has landed (an allowance may stand), so the halt path runs and the cause is `would_revert`.
+                     */
+                    if ((cause instanceof DelegatedTransactionWouldRevertError ||
+                        cause instanceof DelegatedTransactionEstimateUnavailableError) &&
+                        index === 0) {
+                        throw cause;
+                    }
                     // The CAUSE is classified from the error's structure (`haltCauseOf`); the message carries the upstream
                     // text for the operator and is never what a consumer classifies on.
-                    const errorType = error.errorType;
-                    throw await this.#halt(plan, index, `delegated step ${index} (${step.kind}) failed: ${typeof errorType === 'string' && errorType ? `${errorType} | ` : ''}${error instanceof Error ? error.message : String(error)}`, haltCauseOf(error));
+                    const errorType = cause.errorType;
+                    throw await this.#halt(plan, index, `delegated step ${index} (${step.kind}) failed: ${typeof errorType === 'string' && errorType ? `${errorType} | ` : ''}${cause instanceof Error ? cause.message : String(cause)}`, haltCauseOf(cause));
                 }
                 if (receipt.status !== 'success') {
                     throw await this.#halt(plan, index, `delegated step ${index} (${step.kind}) reverted on-chain: ${hash}`, 'reverted');
@@ -312,21 +542,32 @@ export class CdpDelegatedSigner {
     }
     /**
      * After ANY failure: attempt `approve(spender, 0)` under the delegation, then READ the allowance back.
-     * `allowanceCleared` is true only when the read-back is zero — a mined clear whose read-back is not
-     * zero, a reverted clear, a failed submission or a failed read all report false with the hand-off.
+     * `allowanceCleared` is true only when the live read-back is zero — a mined clear whose read-back is
+     * not zero, a reverted clear, a failed submission or a failed read all report false with the hand-off.
+     * This is operator context, not finality or durable-claim release evidence.
      */
     async #halt(plan, failedStep, message, cause) {
         const handOff = `clear approve(${plan.spender}, 0) on ${plan.token} BEFORE revoking the delegation`;
         let hash;
         try {
-            hash = await this.#submit({
+            const submitted = await this.#submit({
                 to: plan.token,
                 value: 0n,
                 data: encodeFunctionData({ abi: ERC20_APPROVE_ABI, functionName: 'approve', args: [plan.spender, 0n] }),
-            });
+            }, undefined, { index: 3, kind: 'allowance_clear' });
+            hash = submitted.hash;
             await this.#raw.pub.waitForTransactionReceipt({ hash });
             // The read-back below must see the clear: only its sealed canonical receipt counts.
             const clearReceipt = await waitForSealedReceipt(this.#raw.pub, hash, this.#sealedWait);
+            if (this.#submissionJournal && submitted.idempotencyKey) {
+                await this.#submissionJournal.receipt(3, submitted.idempotencyKey, {
+                    transactionHash: hash,
+                    status: clearReceipt.status,
+                    blockNumber: clearReceipt.blockNumber.toString(),
+                    blockHash: clearReceipt.blockHash,
+                    gasUsed: clearReceipt.gasUsed.toString(),
+                });
+            }
             if (clearReceipt.status !== 'success') {
                 return new DelegatedPlanHaltedError(`${message}; allowance clear ${hash} reverted — ${handOff}`, failedStep, false, cause, hash);
             }

package/dist/adapter/evm-call-failure.d.ts

@@ -0,0 +1,29 @@
+/**
+ * evm-call-failure.ts — ONE classifier for "the node did not execute this call", shared by the delegated
+ * signer's gas estimate and the constructor's route simulation.
+ *
+ * 🔴 TWO DIFFERENT FACTS HIDE BEHIND ONE THROW (gate r7, findings 2 and 3). `eth_estimateGas` and
+ * `eth_call` reject for a transaction that WOULD REVERT — and also for a node that timed out, rate-limited
+ * (429), or dropped the connection. The first is proof about the transaction: never broadcast it, never
+ * prepare that route. The second proves nothing about the transaction: refusing to broadcast without an
+ * estimate is still right, but it is not a revert, it is retriable, and it must not blacklist a healthy
+ * route or deny a person a working plan. Calling a timeout `would_revert` is the error this module exists
+ * to prevent.
+ *
+ * viem wraps errors in a `cause` chain; the revert lives on an inner node (`ExecutionRevertedError`,
+ * `ContractFunctionRevertedError`, or a node whose `details` carry the node's "execution reverted …"
+ * text). Transport lives on the transport CLASSES (`HttpRequestError`, `TimeoutError`, socket/websocket,
+ * `LimitExceededRpcError`, …); `RpcRequestError` is a NODE answer, not transport. Anything not PROVEN a
+ * revert is `unavailable` — the conservative side.
+ *
+ * Nothing here returns a URL: viem's `message` embeds the RPC request (whose path carries an API key);
+ * only `details`/`shortMessage` survive, with any URL that slipped through replaced.
+ */
+export type EvmCallFailure = 'revert' | 'unavailable';
+/**
+ * `revert` only when some node in the cause chain PROVES it AND no node in the chain is transport
+ * evidence; everything else is `unavailable`.
+ */
+export declare function classifyEvmCallFailure(error: unknown): EvmCallFailure;
+/** A short, URL-free reason for the caller: the node's `details`, else the class, else the message. */
+export declare function evmCallFailureDetail(error: unknown): string;

package/dist/adapter/evm-call-failure.js

@@ -0,0 +1,109 @@
+/**
+ * evm-call-failure.ts — ONE classifier for "the node did not execute this call", shared by the delegated
+ * signer's gas estimate and the constructor's route simulation.
+ *
+ * 🔴 TWO DIFFERENT FACTS HIDE BEHIND ONE THROW (gate r7, findings 2 and 3). `eth_estimateGas` and
+ * `eth_call` reject for a transaction that WOULD REVERT — and also for a node that timed out, rate-limited
+ * (429), or dropped the connection. The first is proof about the transaction: never broadcast it, never
+ * prepare that route. The second proves nothing about the transaction: refusing to broadcast without an
+ * estimate is still right, but it is not a revert, it is retriable, and it must not blacklist a healthy
+ * route or deny a person a working plan. Calling a timeout `would_revert` is the error this module exists
+ * to prevent.
+ *
+ * viem wraps errors in a `cause` chain; the revert lives on an inner node (`ExecutionRevertedError`,
+ * `ContractFunctionRevertedError`, or a node whose `details` carry the node's "execution reverted …"
+ * text). Transport lives on the transport CLASSES (`HttpRequestError`, `TimeoutError`, socket/websocket,
+ * `LimitExceededRpcError`, …); `RpcRequestError` is a NODE answer, not transport. Anything not PROVEN a
+ * revert is `unavailable` — the conservative side.
+ *
+ * Nothing here returns a URL: viem's `message` embeds the RPC request (whose path carries an API key);
+ * only `details`/`shortMessage` survive, with any URL that slipped through replaced.
+ */
+const REVERT_ERROR_NAMES = new Set([
+    'ExecutionRevertedError',
+    'ContractFunctionRevertedError',
+]);
+/** The node's own revert text, in every phrasing seen from Base RPCs. */
+const REVERT_DETAIL_PATTERN = /execution reverted|\brevert(ed)?\b|out of gas|invalid opcode/i;
+/**
+ * 🔴 AFFIRMATIVE TRANSPORT EVIDENCE DOMINATES (gate r7 round 2). viem synthesises `ExecutionRevertedError`
+ * from any `details` text that looks like a revert — including a body an HTTP 429 happened to carry — so
+ * a chain can read `CallExecutionError → ExecutionRevertedError → HttpRequestError(status 429)`. That
+ * proves rate limiting, not a revert. The whole chain is scanned for a transport CLASS first; only a chain
+ * with none may be called a revert.
+ *
+ * 🔴 BY CLASS, NEVER BY A FIELD OF A RAW OBJECT (gate r7 rounds 3 and 4). viem keeps the raw JSON-RPC
+ * error object as `RpcRequestError.cause`, and a node can put ANYTHING in it: a stray `status: 503`
+ * (round 3) or a fabricated `name: "HttpRequestError"` (round 4) beside a code-3 "execution reverted".
+ * Both are PROVEN reverts; calling either transport would have let the halt path's clear broadcast on its
+ * static limit against a proven revert. So transport evidence is accepted ONLY from an actual `Error`
+ * instance whose name is one of viem's transport classes — a plain object can never impersonate one —
+ * plus the one node-level form viem itself treats as rate limiting: an actual `RpcRequestError` whose
+ * JSON-RPC `code` is 429 (HTTP 200), whatever its text says. Nothing else is transport.
+ */
+const TRANSPORT_ERROR_NAMES = new Set([
+    'HttpRequestError',
+    'TimeoutError',
+    'WebSocketRequestError',
+    'SocketClosedError',
+    'LimitExceededRpcError',
+    'ResourceUnavailableRpcError',
+]);
+/** JSON-RPC's rate-limit code, which viem retries on and which is never a statement about execution. */
+const JSON_RPC_RATE_LIMITED = 429;
+function* chain(error) {
+    let node = error;
+    for (let depth = 0; depth < 12 && node && typeof node === 'object'; depth += 1) {
+        yield node;
+        node = node.cause;
+    }
+}
+function isTransport(node) {
+    // A raw JSON object hanging off `RpcRequestError.cause` is never an Error, so it can claim nothing here.
+    if (!(node instanceof Error))
+        return false;
+    if (TRANSPORT_ERROR_NAMES.has(node.name))
+        return true;
+    return node.name === 'RpcRequestError' && node.code === JSON_RPC_RATE_LIMITED;
+}
+/**
+ * `revert` only when some node in the cause chain PROVES it AND no node in the chain is transport
+ * evidence; everything else is `unavailable`.
+ */
+export function classifyEvmCallFailure(error) {
+    const nodes = [...chain(error)];
+    if (nodes.some(isTransport))
+        return 'unavailable';
+    for (const node of nodes) {
+        // A revert CLASS counts only on an actual Error instance too; the node's own text counts wherever it is.
+        if (node instanceof Error && REVERT_ERROR_NAMES.has(node.name))
+            return 'revert';
+        const details = node.details;
+        if (typeof details === 'string' && REVERT_DETAIL_PATTERN.test(details))
+            return 'revert';
+    }
+    return 'unavailable';
+}
+/** A short, URL-free reason for the caller: the node's `details`, else the class, else the message. */
+export function evmCallFailureDetail(error) {
+    let text = '';
+    for (const node of chain(error)) {
+        if (typeof node.details === 'string' && node.details.trim()) {
+            text = node.details;
+            break;
+        }
+    }
+    if (!text) {
+        const top = error;
+        text =
+            typeof top?.shortMessage === 'string' && top.shortMessage
+                ? top.shortMessage
+                : typeof top?.name === 'string' && top.name !== 'Error'
+                    ? top.name
+                    : typeof top?.message === 'string'
+                        ? top.message
+                        : String(error);
+    }
+    return text.replace(/https?:\/\/\S+/g, '[url]').slice(0, 200);
+}
+//# sourceMappingURL=evm-call-failure.js.map

package/dist/adapter/refusal.d.ts

@@ -8,7 +8,7 @@
  * `errorType` mirrors `code` so the CDP kit's ladder — which only grades a *structured* refusal as
  * the fence biting — recognises adapter refusals without a second grading path.
  */
-export declare const ADAPTER_REFUSAL_CODES: readonly ["SCHEMA_INVALID", "UNSUPPORTED_OPERATION", "DIGEST_MISMATCH", "STALE_ARTIFACT", "ACCOUNT_BINDING_MISMATCH", "CAPABILITY_MISSING", "CHAIN_MISMATCH", "PLAN_SHAPE_INVALID", "APPROVAL_INVALID", "TARGET_NOT_ALLOWED", "SWAP_CALLDATA_INVALID", "RECEIVER_MISMATCH", "INTENT_MISMATCH", "MIN_OUTPUT_TOO_LOW", "ATTRIBUTION_MISSING", "ATTRIBUTION_MISMATCH", "FEE_CAP_EXCEEDED"];
+export declare const ADAPTER_REFUSAL_CODES: readonly ["SCHEMA_INVALID", "UNSUPPORTED_OPERATION", "DIGEST_MISMATCH", "STALE_ARTIFACT", "ACCOUNT_BINDING_MISMATCH", "CAPABILITY_MISSING", "CHAIN_MISMATCH", "PLAN_SHAPE_INVALID", "APPROVAL_INVALID", "TARGET_NOT_ALLOWED", "SWAP_CALLDATA_INVALID", "RECEIVER_MISMATCH", "DELEGATED_TX_WOULD_REVERT", "DELEGATED_TX_ESTIMATE_UNAVAILABLE", "INTENT_MISMATCH", "MIN_OUTPUT_TOO_LOW", "ATTRIBUTION_MISSING", "ATTRIBUTION_MISMATCH", "FEE_CAP_EXCEEDED"];
 export type AdapterRefusalCode = (typeof ADAPTER_REFUSAL_CODES)[number];
 export declare class AdapterRefusal extends Error {
     readonly code: AdapterRefusalCode;

package/dist/adapter/refusal.js

@@ -24,6 +24,19 @@ export const ADAPTER_REFUSAL_CODES = [
     'TARGET_NOT_ALLOWED',
     'SWAP_CALLDATA_INVALID',
     'RECEIVER_MISMATCH',
+    /**
+     * The node's gas estimate REVERTED for a plan step, so the transaction would revert on chain: it is not
+     * broadcast (a knowingly-reverting broadcast spends the user's gas and buys nothing). Raised by the
+     * delegated signer; surfaced to a delegated caller as `DELEGATED_PLAN_REFUSED [DELEGATED_TX_WOULD_REVERT]`
+     * when nothing of the plan had reached the chain, or as the cause of `DELEGATED_PLAN_HALTED` otherwise.
+     */
+    'DELEGATED_TX_WOULD_REVERT',
+    /**
+     * The node could not estimate a plan step at all — a timeout, a rate limit, a dropped connection —
+     * so nothing was proven about the transaction and nothing is broadcast without an estimate. Distinct
+     * from `DELEGATED_TX_WOULD_REVERT` on purpose: this one is RETRIABLE and blacklists nothing.
+     */
+    'DELEGATED_TX_ESTIMATE_UNAVAILABLE',
     // Intent binding — the artifact must be the trade the USER asked for
     'INTENT_MISMATCH',
     'MIN_OUTPUT_TOO_LOW',