otto-intel-mcp 0.1.2 → 0.1.3

package/README.md

@@ -2,7 +2,7 @@
 
 Market intelligence and trade construction for AI agents, over MCP: SEC filings and insider flow for US stocks, tokenized equities on Robinhood Chain, Base and Polymarket market context, plus four **constructors** that build a ready-to-sign swap, bridge, Polymarket order or Hyperliquid perp order for an address you supply. Pay per call in USDC on Base; on the hosted server the first call from your network address is free.
 
-- Hosted: `https://mcp.ottoai.services` — 21 tools.
+- Hosted: `https://mcp.ottoai.services` — 22 tools.
 - Local: `npx otto-intel-mcp` — the 10 intelligence tools, paid from a wallet you configure.
 - Docs: https://docs.useotto.xyz/acp-swarm/otto-intel-mcp
 
@@ -96,6 +96,8 @@ A constructor builds the transaction; **your wallet signs and sends it.** Give i
 | `otto_prepare_polymarket_order` | A Polymarket CTF Exchange V2 limit order as typed data, tick and size validated against the live market | Your Polygon EOA |
 | `otto_prepare_perp_order` | A Hyperliquid perp limit order (optional take-profit / stop-loss), as the L1 action plus the exact EIP-712 recipe to sign | Your Hyperliquid account |
 
+On a server with a chain view (the hosted rail), a quoted swap route is also **simulated from the address that will sign it** before it is prepared: the quote's shape is asserted first, then the asserted call is run against the node with the plan's own balance and allowance overridden. A route that reverts is re-quoted with that exchange denied; a route that cannot be simulated — a token whose storage layout has not been proven on-chain, a node that ignores overrides — is **refused by name rather than prepared unproven**. Today the proven tokens are USDC on Base and the two Yield Copilot vault shares (`gtUSDCp`, `steakUSDC`).
+
 To verify, sign and submit an envelope from the command line or from code, use the companion [`otto-execute`](https://www.npmjs.com/package/otto-execute) (CLI + library, `npm install otto-execute`) — see the [execution seam docs](https://docs.useotto.xyz/acp-swarm/execution-seam).
 
 ### Always free
@@ -231,6 +233,6 @@ Field-by-field documentation: https://docs.useotto.xyz/acp-swarm/execution-seam.
 - Docs: https://docs.useotto.xyz/acp-swarm/otto-intel-mcp · execution seam: https://docs.useotto.xyz/acp-swarm/execution-seam
 - The full Otto x402 catalog: https://x402.ottoai.services
 - Otto AI: https://useotto.xyz · X: [@useOttoAI](https://x.com/useOttoAI)
-- Changelog: 0.1.2 — the hosted front door (`GET /`, `/health`) reports the live tool registry (21 tools, never a literal), the local server carries the settlement receipt like the hosted one, constructor descriptions state the freshness window, `serverInfo.version` = the package version; 0.1.1 — README rewritten for first-time users and agents, source maps removed from the package, publish gated by a privacy audit; 0.1.0 — first release (hosted + local server, execution constructors, library entries).
+- Changelog: 0.1.3 — swap-shaped constructors on a server with a chain view now SIMULATE the quoted route from the signing account before preparing it (a reverting exchange tool is re-quoted and denied; an unprovable route is refused by name — see the execution constructors section), and the library entries ship the fence-v2 policy lineage (`MODEL_B_POLICY_*_V2`, `MODEL_B_POLICY_DIGEST_BY_NAME`) that the `otto-execute` CLI needs to recognise the current fence; 0.1.2 — the hosted front door (`GET /`, `/health`) reports the live tool registry (21 tools, never a literal), the local server carries the settlement receipt like the hosted one, constructor descriptions state the freshness window, `serverInfo.version` = the package version; 0.1.1 — README rewritten for first-time users and agents, source maps removed from the package, publish gated by a privacy audit; 0.1.0 — first release (hosted + local server, execution constructors, library entries).
 
 Running the hosted server yourself, or building from the monorepo: see `SETUP.md` in the repository.

package/dist/adapter/cdp-signer.d.ts

@@ -27,6 +27,7 @@
 import { type Address, type Hex, type PublicClient } from 'viem';
 import { type SealedWaitOptions } from './chain.js';
 import type { SentStep } from './sent-step.js';
+import { AdapterRefusal } from './refusal.js';
 import { type SigningCapability, type VerifiedSwap } from './verify.js';
 export declare const CDP_CAPABILITIES: readonly SigningCapability[];
 export declare const CHAIN_ID: 8453;
@@ -63,14 +64,21 @@ export interface CdpRawOperations {
         expiresAt: string;
     } | undefined>;
 }
-/** True once `rig.revoke(userId)` has been called on this rig, whatever it returned. */
-export declare function revocationRequested(rig: CdpRig, userId: string): boolean;
+/**
+ * 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 declare function revocationRequested(rig: CdpRig, userId: string, expiresAt: string): boolean;
 /**
  * Why a delegated plan halted — a closed vocabulary the signer sets from STRUCTURED facts only (the CDP
  * `errorType`, an error's class, the receipt status, its own checks). Message text never selects it, so
  * upstream text cannot steer the class a consumer reports.
  */
-export type DelegatedHaltCause = 'policy_violation' | 'delegation_not_active' | 'artifact_no_longer_signable' | 'reverted' | 'receipt_not_sealed' | 'upstream_failure';
+export type DelegatedHaltCause = 'policy_violation' | 'delegation_not_active' | 'artifact_no_longer_signable' | 'reverted'
+/** A later step's gas estimate reverted after an earlier step had landed; nothing more was broadcast. */
+ | 'would_revert'
+/** The node could not estimate a later step (timeout, rate limit, transport); nothing more was broadcast. */
+ | 'estimate_unavailable' | 'receipt_not_sealed' | 'upstream_failure';
 /**
  * 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
@@ -103,19 +111,50 @@ export declare function openCdpRig(credentials: CdpDeveloperCredentials, rpcUrl?
  * This IS `rig.revoke`: serialized on the rig, lock held through the read-back, fail-closed afterwards.
  */
 export declare function revokeDelegationByUserId(rig: CdpRig, userId: string): Promise<void>;
+/**
+ * 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 declare class DelegatedTransactionWouldRevertError extends AdapterRefusal {
+    readonly stepKind: string;
+    constructor(stepKind: string, detail: string);
+}
+/**
+ * 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 declare class DelegatedTransactionEstimateUnavailableError extends AdapterRefusal {
+    readonly stepKind: string;
+    constructor(stepKind: string, detail: string);
+}
+/** The bounded limit the halt path's `approve(spender, 0)` uses when the node cannot estimate it. */
+export declare const ALLOWANCE_CLEAR_STATIC_GAS = 80000n;
 export declare class CdpDelegatedSigner {
     #private;
     readonly capabilities: readonly SigningCapability[];
     readonly chainId: 8453;
     constructor(rig: CdpRig, user: CdpEndUser, options?: {
         readonly sealedWait?: SealedWaitOptions;
+        readonly beforeEachStep?: () => Promise<void>;
+        readonly afterBuild?: () => Promise<void>;
+        readonly beforeSubmit?: () => void;
+        readonly grantExpiresAt?: string;
     });
     get address(): Address;
     get user(): CdpEndUser;
     /**
      * `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.

package/dist/adapter/cdp-signer.js

@@ -28,7 +28,8 @@ 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;
@@ -36,11 +37,25 @@ export const NETWORK = 'base';
 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) {
@@ -82,6 +97,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 +130,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)
@@ -191,7 +219,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 +262,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 +300,36 @@ 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;
     constructor(rig, user, options = {}) {
         const raw = RAW.get(rig);
         if (!raw)
@@ -232,6 +338,10 @@ 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;
     }
     get address() {
         return this.#user.address;
@@ -244,19 +354,44 @@ export class CdpDelegatedSigner {
      * 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?.();
+        // A plan step (it carries `beforeSubmit`) refuses on a reverting estimate; the halt path's clear does not.
+        const transaction = await buildUnsignedTransaction(this.#raw.pub, this.#user.address, step, beforeSubmit ? { kind: 'refuse', stepKind: step.kind ?? 'plan' } : { kind: 'allowance_clear' });
+        /**
+         * 🔴 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) {
+            await this.#afterBuild?.();
+            beforeSubmit();
+            // …and the caller's own last word, synchronous, on what that re-read just found. Nothing is
+            // awaited between here and the hand-off, because an await is the window this exists to close.
+            this.#beforeSubmit?.();
+        }
         return this.#raw.submit(this.#user, transaction);
     }
-    /** 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,6 +407,10 @@ 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) {
                     throw await this.#halt(plan, index, `plan no longer signable before step ${index}: ${error instanceof Error ? error.message : String(error)}`, haltCauseOf(error));
@@ -289,6 +428,17 @@ export class CdpDelegatedSigner {
                     receipt = await waitForSealedReceipt(this.#raw.pub, hash, this.#sealedWait);
                 }
                 catch (error) {
+                    /**
+                     * 🔴 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 ((error instanceof DelegatedTransactionWouldRevertError ||
+                        error instanceof DelegatedTransactionEstimateUnavailableError) &&
+                        index === 0) {
+                        throw error;
+                    }
                     // 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;

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',