@valve-tech/viem-errors 0.10.1 → 0.11.0

package/AGENTS.md

@@ -0,0 +1,162 @@
+# AGENTS.md
+
+Terse reference for AI agents (Claude Code, Cursor, Aider, etc.) integrating
+`@valve-tech/viem-errors`. The full README is for humans; this file is for
+agents that need to ground their work in the package's actual surface
+quickly.
+
+## What this package does
+
+Cause-chain-aware error utilities for viem-based dapps. Pure functions
+over viem's nested `cause` chain that solve four problems every dapp
+re-implements (and most get slightly wrong):
+
+1. **Detect EIP-1193 user rejections** even when buried under wrapper
+   errors whose top-level message looks like a generic failure.
+2. **Extract decoded custom Solidity error names** (`HashMismatch`,
+   `InsufficientLiquidity`) from viem's nested `data.errorName`
+   regardless of how the error is wrapped.
+3. **Map raw RPC/wallet/contract errors to short user-facing copy**
+   with overridable patterns.
+4. **Route wagmi-style `onError` sinks** through one helper so every
+   write site has consistent UX.
+
+Pure functions, **no runtime dependencies**. `viem ^2.0.0` is a peer
+dependency used only for the `Hex` type — the runtime is plain JS.
+
+## Public API
+
+All exports live under `src/index.ts`. Single subpath; no sub-exports.
+
+```ts
+import {
+  // chain walk (the foundation everything else is built on)
+  walkErrorCause,
+  // rejection detection
+  isUserRejectionError,
+  USER_REJECTION_MESSAGE,
+  // custom Solidity error extraction
+  extractContractErrorName,
+  extractContractErrorNameFromMessage,
+  // friendly-message mapping
+  getUserFriendlyErrorMessage,
+  DEFAULT_ERROR_PATTERNS,
+  type ErrorPattern,
+  // one-call handler for wagmi onError / catch blocks
+  handleWalletError,
+  type HandleWalletErrorOptions,
+} from '@valve-tech/viem-errors'
+```
+
+## The five exports you'll actually call
+
+| Export | Shape | Use when |
+|---|---|---|
+| `isUserRejectionError(error)` | `boolean` | You need to tell rejection from failure to decide between "reset to idle" vs "show error toast". |
+| `extractContractErrorName(error)` | `string \| null` | You want to branch on the decoded Solidity error name (`'IntentExpired'`, `'HashMismatch'`, etc.) without parsing the raw revert message. |
+| `getUserFriendlyErrorMessage(error, opts?)` | `string` | You need short user-facing copy and don't want to write the rejection-vs-decoded-vs-pattern pipeline yourself. |
+| `handleWalletError(error, opts)` | `void` | One-liner for wagmi's `onError` callback or a catch block. Routes to `setStatus` / `setErrorMessage` / `toast.error|info` / `onError` sinks. |
+| `walkErrorCause(error, opts?)` | `Iterable<unknown>` | You're doing custom inspection — generator yields the error then each link in `.cause` (default `maxDepth: 8`). |
+
+## Why three signals for rejection detection
+
+`isUserRejectionError` walks the cause chain checking three signals at every link:
+
+1. EIP-1193 `code === 4001`
+2. Class name `UserRejectedRequestError` (viem's typed class)
+3. Message regex (`"User rejected"`, `"User denied"`, MetaMask's variants)
+
+Any one is sufficient. The reason: no single signal is reliable across every wallet + version on the wire. WalletConnect drops the EIP-1193 code in some flows; injected providers wrap it in their own error class; mobile wallets sometimes only set the message. Checking all three at every link in the cause chain is the only check that works in production.
+
+## Why walk the cause chain at all
+
+viem nests errors several layers deep:
+
+```
+ContractFunctionExecutionError
+  └─ cause: RpcRequestError
+       └─ cause: UserRejectedRequestError ← the real signal lives here
+```
+
+The wrapper's `.message` reads `"Failed to send transaction"`. Top-level message matching misses real rejections; top-level class checks miss them too. `walkErrorCause` is the foundation — every other detector in this package iterates with it.
+
+## The friendly-message pipeline
+
+`getUserFriendlyErrorMessage(error, opts)` runs this order — **rejection check FIRST**:
+
+```
+1. isUserRejectionError(error)           → USER_REJECTION_MESSAGE
+2. extractContractErrorName(error)       → opts.customErrors[name] (if matched)
+3. opts.patterns + DEFAULT_ERROR_PATTERNS → first match's message
+4. opts.fallback ?? "Something went wrong. Please try again."
+```
+
+Rejection-first matters because a `code === 4001` buried under a wrapper whose top-level message contains `"execution reverted"` must still produce the cancelled-by-user copy — not "transaction reverted on-chain".
+
+`DEFAULT_ERROR_PATTERNS` covers protocol-agnostic cases (insufficient gas, replacement underpriced, rate-limited, network down, generic revert). Protocol-specific decoded errors (`HashMismatch` → "Proof didn't match the deposit") belong in `customErrors`, not in this package.
+
+## `handleWalletError` — the one-line shape
+
+The canonical wagmi shape:
+
+```ts
+useContractWrite({
+  // ...
+  onError: (err) => handleWalletError(err, {
+    setStatus,                       // 'idle' on rejection, 'error' on failure
+    setErrorMessage: setError,       // null on rejection, friendly text on failure
+    toast,                           // toast.info on rejection, toast.error on failure
+    customErrors: {
+      HashMismatch: 'The proof did not match the deposit.',
+      InsufficientLiquidity: 'Not enough liquidity for this trade.',
+    },
+    onError: (e) => analytics.track('write.error', { message: e.message }),
+  }),
+})
+```
+
+`onError` is always called with the underlying error (coerced to `Error`) so analytics observers get the original. The other sinks branch by classification.
+
+## Pitfalls (read these)
+
+1. **Don't top-level-match for "user rejected".** Use `isUserRejectionError`. Top-level matches miss the buried-in-cause cases that production wallets actually emit.
+
+2. **Don't substring-match for "execution reverted" and bail with a generic message.** Call `extractContractErrorName` first — viem already decoded the error name into `data.errorName` somewhere in the cause chain. Falling back to "transaction failed" throws away the actual signal (`'IntentExpired'`, `'SlippageTooHigh'`).
+
+3. **Don't put protocol-specific copy in `DEFAULT_ERROR_PATTERNS`.** It's intentionally protocol-agnostic. Pass your protocol's custom-error map through `customErrors`.
+
+4. **Don't iterate `.cause` manually with a `while (e.cause) { e = e.cause }` loop.** It's an infinite loop on circular causes (rare, but real — some wallets emit them). `walkErrorCause`'s `maxDepth: 8` cap exists for this.
+
+5. **Don't catch and re-throw without preserving the original.** If you must wrap, set `cause: original` so the chain still walks. `handleWalletError`'s `onError` sink always receives the unwrapped original.
+
+6. **`getUserFriendlyErrorMessage` returns the FIRST pattern match.** If your custom pattern needs to win over a default, prepend it via `patterns: [...myPatterns, ...DEFAULT_ERROR_PATTERNS]` — order matters.
+
+7. **`handleWalletError` does NOT throw or re-throw.** It's a "side-effect-only" handler. If you want the catch block to bail after handling, throw yourself or split the catch:
+   ```ts
+   try { await writeAsync(...) }
+   catch (err) {
+     handleWalletError(err, { ... })
+     // pipeline-halt logic here
+     throw err
+   }
+   ```
+
+## Composition with sibling packages
+
+`@valve-tech/wallet-adapter`'s `sendTransactionWithHooks` already throws a typed `WalletRejectedError` on rejection (using this package's three-signal detector internally). If you're using wallet-adapter's helpers, you don't need `isUserRejectionError` directly — `instanceof WalletRejectedError` is the canonical discriminator. Use viem-errors directly when you're NOT going through wallet-adapter (raw wagmi `useContractWrite`, raw viem `walletClient.sendTransaction`, etc.).
+
+For decoded-error extraction, viem-errors stays valid even with wallet-adapter — `ContractRevertedError` carries the receipt, but `extractContractErrorName(err)` still gets you the decoded name from the cause chain regardless of which throw path you went through.
+
+## Skills (for AI agents)
+
+`skills/` ships in the npm tarball. If you're an AI agent working in a
+project that has installed this package, look in
+`node_modules/@valve-tech/viem-errors/skills/viem-errors-integration/SKILL.md`
+for trigger conditions, anti-pattern flags, and recipes.
+
+## Verifying provenance
+
+```bash
+npm view @valve-tech/viem-errors@latest --json | jq .dist.attestations
+npm audit signatures
+```

package/CHANGELOG.md

@@ -6,6 +6,19 @@ this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.11.0] — 2026-05-11
+
+### Notes
+
+- Synchronized release — no changes to this package. Bumped in
+  lockstep with the rest of the toolkit alongside the v0.11.0
+  feature work in `@valve-tech/gas-oracle` (20-block ring lifecycle,
+  reorg detection, gap bridging), `@valve-tech/tx-tracker` (audit
+  fixes — durable rehydrate, retention enforcement, replaced-by
+  dedup, receipt-poll race, helper extraction), `@valve-tech/
+  wallet-adapter` (five wallet bridge examples), and
+  `@valve-tech/chain-source` (canonical-owner docs for wire types).
+
 ## [0.10.1] — 2026-05-08
 
 Synchronized release — no changes to this package. Republished at

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valve-tech/viem-errors",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Cause-chain-aware error utilities for viem-based dapps. Detect EIP-1193 user rejections (4001 / class name / message regex), extract decoded custom Solidity error names from anywhere in viem's nested cause chain, map raw RPC/wallet/contract errors to short user-friendly messages with overridable patterns, and route wagmi-style onError sinks through one helper. Pure functions, no runtime dependencies. Part of the valve-tech/evm-toolkit synchronized release line.",
   "license": "MIT",
   "homepage": "https://github.com/valve-tech/evm-toolkit/tree/main/packages/viem-errors#readme",
@@ -34,7 +34,9 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
+    "AGENTS.md",
     "CHANGELOG.md",
     "LICENSE"
   ],

package/skills/viem-errors-integration/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: viem-errors-integration
+description: Integrate `@valve-tech/viem-errors` — cause-chain-aware error utilities for viem-based dapps — into wagmi `onError` callbacks, raw viem catch blocks, or anywhere a thrown error needs to be classified into "user rejected" vs "real failure" vs "decoded Solidity error". Use when the user is wiring `handleWalletError` into wagmi `useContractWrite` / `useSendTransaction`, calling `isUserRejectionError` to branch UI state to idle on rejection, calling `extractContractErrorName` to pull a decoded custom Solidity error name (`HashMismatch`, `InsufficientLiquidity`, `IntentExpired`) from viem's nested cause chain, mapping raw RPC errors to user-facing copy via `getUserFriendlyErrorMessage` + custom error patterns, or asks "why is my user-rejection check missing rejections" / "viem error is buried under a wrapper" / "how do I get the decoded error name from a `ContractFunctionExecutionError`". Also fires on imports of `@valve-tech/viem-errors` and questions about `walkErrorCause`, `DEFAULT_ERROR_PATTERNS`, `USER_REJECTION_MESSAGE`, the cause-chain `maxDepth` cap, or why three signals (EIP-1193 code, class name, message regex) are checked for rejection. Skip when the user is going through `@valve-tech/wallet-adapter`'s helpers (those throw typed `WalletRejectedError` / `ContractRevertedError` already — `instanceof` is the canonical discriminator there; delegate to wallet-adapter-integration), or when the user only wants generic JS error handling that has nothing to do with viem's cause-chain shape.
+---
+
+# Integrating `@valve-tech/viem-errors`
+
+Cause-chain-aware error utilities for viem-based dapps. Pure functions
+over viem's nested error chain — no runtime dependencies. This skill is
+for AI agents working in a project that imports the package, so they
+recommend the right primitive for the user's situation rather than
+re-implementing rejection/revert detection (which is what almost every
+dapp does, and most get wrong).
+
+## Decision tree: which primitive to use
+
+```
+Is the user inside wagmi's `onError` or a one-liner catch block where
+they want classification + UI sinks (toast / setStatus / setError)?
+├── Yes — call `handleWalletError(err, { setStatus, setErrorMessage,
+│         toast, customErrors })`. One line, all sinks routed.
+└── No — do they need to BRANCH on the classification themselves?
+         ├── "Is this a user rejection?" → `isUserRejectionError(err)`
+         ├── "What custom Solidity error was thrown?"
+         │       → `extractContractErrorName(err)`
+         ├── "Give me a user-facing message string"
+         │       → `getUserFriendlyErrorMessage(err, { customErrors })`
+         └── "I'm doing custom inspection across the cause chain"
+                 → iterate `walkErrorCause(err)` yourself
+```
+
+## How to recognize this package in the user's code
+
+```ts
+import {
+  isUserRejectionError,
+  extractContractErrorName,
+  getUserFriendlyErrorMessage,
+  handleWalletError,
+  walkErrorCause,
+} from '@valve-tech/viem-errors'
+```
+
+`package.json` will show `"@valve-tech/viem-errors": "^0.10.x"`.
+
+## The canonical wagmi shape
+
+```ts
+import { handleWalletError } from '@valve-tech/viem-errors'
+
+const { writeAsync } = useContractWrite({
+  address, abi, functionName,
+  onError: (err) => handleWalletError(err, {
+    setStatus,                       // 'idle' on rejection, 'error' on failure
+    setErrorMessage: setError,
+    toast,                           // toast.info on rejection, toast.error on failure
+    customErrors: {
+      HashMismatch: 'The proof did not match the deposit.',
+      IntentExpired: 'This intent has expired — please refresh.',
+      InsufficientLiquidity: 'Not enough liquidity for this trade.',
+    },
+    onError: (e) => analytics.track('write.error', { message: e.message }),
+  }),
+})
+```
+
+The `customErrors` map is the per-protocol layer; `DEFAULT_ERROR_PATTERNS` covers the protocol-agnostic cases (insufficient gas, rate-limited, network down, generic revert) automatically.
+
+## The branching shape (when you need control)
+
+```ts
+import { isUserRejectionError, extractContractErrorName } from '@valve-tech/viem-errors'
+
+try {
+  await wallet.sendTransaction(tx)
+} catch (err) {
+  if (isUserRejectionError(err)) {
+    setStatus('idle')             // do NOT show error toast
+    return
+  }
+  const decoded = extractContractErrorName(err)
+  if (decoded === 'IntentExpired') {
+    promptUserToRefresh()
+    return
+  }
+  if (decoded === 'HashMismatch') {
+    showProofMismatchDialog()
+    return
+  }
+  // fall through to generic error UI
+  toast.error(getUserFriendlyErrorMessage(err))
+  throw err
+}
+```
+
+## Anti-patterns to flag
+
+When reviewing user code, watch for these and suggest fixes:
+
+1. **Top-level message matching for rejection.**
+   ```ts
+   // ❌ misses real rejections buried under wrappers
+   if (err.message.includes('User rejected')) ...
+
+   // ✅
+   if (isUserRejectionError(err)) ...
+   ```
+   The wrapper's `.message` typically reads `"Failed to send transaction"` even when the cause is a 4001. Walk the chain.
+
+2. **Top-level class checks for rejection.**
+   ```ts
+   // ❌ misses cases where viem wraps the rejection in a different class
+   if (err instanceof UserRejectedRequestError) ...
+   ```
+   Same problem — the typed class lives at some link in the cause chain, not necessarily at the top. `isUserRejectionError` walks for it.
+
+3. **Substring-matching `"execution reverted"` and bailing with a generic message.** viem already decoded the actual Solidity error name into `data.errorName` somewhere in the cause chain. Call `extractContractErrorName` first; only fall back to generic if it returns `null`.
+
+4. **Manual `while (e.cause) { e = e.cause }` loops.** Infinite loop on circular causes (rare but real — some wallet middleware emits them). `walkErrorCause`'s default `maxDepth: 8` cap is the safety net. If you must iterate manually, copy the cap.
+
+5. **Putting protocol-specific copy in `DEFAULT_ERROR_PATTERNS`** by extending the array. The defaults are intentionally protocol-agnostic. Pass your protocol's custom-error map through `customErrors` (works against `data.errorName` matches, not pattern regex).
+
+6. **Custom patterns ordered AFTER `DEFAULT_ERROR_PATTERNS`.** Pattern matching is first-match-wins. To override a default, prepend:
+   ```ts
+   getUserFriendlyErrorMessage(err, { patterns: [...myPatterns, ...DEFAULT_ERROR_PATTERNS] })
+   ```
+
+7. **Expecting `handleWalletError` to throw or re-throw.** It's a side-effect-only handler that routes to sinks. If your catch block needs to bail after handling, throw yourself:
+   ```ts
+   try { await writeAsync(args) }
+   catch (err) {
+     handleWalletError(err, { setStatus, setErrorMessage, toast })
+     throw err  // explicit
+   }
+   ```
+
+8. **Re-implementing the three-signal rejection check.** Some dapps replicate the `code === 4001` + class name + regex logic inline. Just call `isUserRejectionError` — the three-signal check is the entire reason the package exists.
+
+9. **Wrapping errors without `cause`.** If you must throw a new error class, set `cause: original` so the chain still walks:
+   ```ts
+   // ❌ breaks the chain
+   throw new MyError(`Deposit failed: ${err.message}`)
+
+   // ✅ preserves it
+   throw new MyError('Deposit failed', { cause: err })
+   ```
+
+## When to skip this package
+
+- **Going through `@valve-tech/wallet-adapter`'s helpers.** `sendTransactionWithHooks` already throws typed `WalletRejectedError` / `ContractRevertedError`. `instanceof` is the canonical discriminator there — no need to call `isUserRejectionError` after the fact. Internally those typed errors are detected via this package's three-signal check, so the discrimination is correct; you just don't need to redo it.
+- **Non-viem error sources.** This package walks viem's cause chain shape. For raw HTTP errors, generic JS errors, or non-EVM SDKs, the helpers will return `null` / fall through to the fallback message — they won't crash, but they're not adding value either.
+
+## Composing with other packages
+
+- `@valve-tech/wallet-adapter` uses this package internally for its `WalletRejectedError` discriminator. You don't need to call viem-errors directly when going through wallet-adapter's helpers.
+- For decoded custom Solidity errors, `extractContractErrorName` works against `ContractRevertedError.cause` chains too — useful for branching after wallet-adapter's `instanceof ContractRevertedError` check.
+
+## Where to find more
+
+- Full API + types: `node_modules/@valve-tech/viem-errors/AGENTS.md`
+- Human-facing docs: `node_modules/@valve-tech/viem-errors/README.md`
+- Compiled output: `node_modules/@valve-tech/viem-errors/dist/`
+- Sibling skill: `wallet-adapter-integration` for the typed-error throw shape