@valve-tech/viem-errors 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to `@valve-tech/viem-errors` are documented in
+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/).
+
+## [Unreleased]
+
+### Added
+
+- Initial implementation. Functions extracted from a real-world dapp
+  (Provex) where they had been re-derived inline; this is the first
+  upstream packaging for general use.
+  - `walkErrorCause(error, options?)` — generator over the viem
+    cause chain. Default `maxDepth: 8`.
+  - `isUserRejectionError(error)` — three-signal check across the
+    cause chain (EIP-1193 `code === 4001`, class name
+    `UserRejectedRequestError`, message regex fallback).
+  - `USER_REJECTION_MESSAGE` — default rejection copy.
+  - `extractContractErrorName(error)` — finds decoded custom
+    Solidity error names on `data.errorName` anywhere in the cause
+    chain.
+  - `extractContractErrorNameFromMessage(raw)` — scrape fallback for
+    flattened messages.
+  - `getUserFriendlyErrorMessage(error, options?)` — pipeline:
+    rejection → decoded custom error → consumer patterns → default
+    patterns → fallback.
+  - `DEFAULT_ERROR_PATTERNS` — protocol-agnostic patterns
+    (wallet / gas / replacement / network / rate-limit / revert).
+  - `handleWalletError(error, options)` — wagmi `onError`-shape
+    sink with separate rejection vs real-error paths.
+- 49 unit tests covering cause-chain traversal, rejection detection,
+  custom-error extraction, message mapping, override precedence, and
+  sink routing.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Valve Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# `@valve-tech/viem-errors`
+
+Cause-chain-aware error utilities for viem-based dapps. Detect EIP-1193
+user rejections, extract decoded custom Solidity error names from
+anywhere in viem's nested error 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. viem is a peer dependency
+(used only for the `Hex` type — the runtime is plain JS).
+
+## Why
+
+Every dapp re-implements wallet error handling, and most get it
+slightly wrong:
+
+- **Top-level message matching misses real rejections.** viem nests
+  errors several layers deep (`ContractFunctionExecutionError` →
+  `RpcRequestError` → `UserRejectedRequestError`). The wrapper's
+  `.message` reads `"Failed to send transaction"` — looks like a
+  generic failure, but the cause is actually a user rejection that
+  should reset the UI to idle, not show a red error toast.
+- **Decoded custom Solidity errors get hidden.** The wrapping message
+  contains `"execution reverted"` so dapps short-circuit to a generic
+  "transaction failed" message, ignoring the actual `data.errorName`
+  (`HashMismatch`, `InsufficientLiquidity`, etc.) that viem decoded
+  for them.
+- **Generic copy is the same everywhere.** "Insufficient funds for
+  gas", "previous transaction is still pending", "rate limited" — all
+  re-derived per project from raw RPC strings.
+
+This package solves all three at the primitive layer. Extend the
+default error map with your protocol's custom errors; everything else
+just works.
+
+## Install
+
+```sh
+npm install @valve-tech/viem-errors viem
+# or
+yarn add @valve-tech/viem-errors viem
+```
+
+## Quick start
+
+### Detect a wallet rejection
+
+```ts
+import { isUserRejectionError } from '@valve-tech/viem-errors'
+
+try {
+  await wallet.sendTransaction(tx)
+} catch (err) {
+  if (isUserRejectionError(err)) {
+    // Reset to idle. Do NOT show a "transaction failed" error.
+    return
+  }
+  throw err
+}
+```
+
+### Centralised error handling for wagmi `onError`
+
+```ts
+import { handleWalletError } from '@valve-tech/viem-errors'
+
+const { writeAsync } = useContractWrite({
+  // ...
+  onError: (err) => handleWalletError(err, {
+    setStatus,
+    setErrorMessage: setError,
+    toast,
+    onError: (e) => analytics.track('write.error', { message: e.message }),
+    customErrors: {
+      HashMismatch: 'The proof did not match the deposit.',
+      InsufficientLiquidity: 'Not enough liquidity for this trade.',
+    },
+  }),
+})
+```
+
+### Extract a decoded custom error
+
+```ts
+import { extractContractErrorName } from '@valve-tech/viem-errors'
+
+catch (err) {
+  const name = extractContractErrorName(err)
+  if (name === 'IntentExpired') {
+    promptUserToRefresh()
+    return
+  }
+  // ...
+}
+```
+
+## API
+
+| Export | Shape |
+| --- | --- |
+| `walkErrorCause(error, opts?)` | Generator yielding `error` then each link in its `.cause` chain (default `maxDepth: 8`). |
+| `isUserRejectionError(error)` | `true` if any link has EIP-1193 `code === 4001`, name `UserRejectedRequestError`, or matches the rejection-message regex. |
+| `USER_REJECTION_MESSAGE` | Toast-friendly rejection copy. |
+| `extractContractErrorName(error)` | First valid Solidity error name from `data.errorName` in the cause chain, else `null`. |
+| `extractContractErrorNameFromMessage(raw)` | Scrape viem's `"reverted with the following reason:\n<Name>"` format from a flattened message string. |
+| `getUserFriendlyErrorMessage(error, opts?)` | Short user-facing message. Pipeline: rejection → decoded custom error → consumer patterns → default patterns → fallback. |
+| `DEFAULT_ERROR_PATTERNS` | Protocol-agnostic patterns covering wallet/gas/network/RPC/rate-limit/revert. |
+| `handleWalletError(error, opts)` | Apply `getUserFriendlyErrorMessage` + sinks (`setStatus`, `setErrorMessage`, `toast`, `onError`). |
+
+## Design notes
+
+- **`walkErrorCause` is a generator.** Consumers can break early without
+  scanning the whole chain. Default depth of 8 caps a circular cause
+  reference instead of looping forever.
+- **`isUserRejectionError` checks three signals at every link.** Any one of
+  `code === 4001` / class name / message regex is sufficient. Three
+  signals exist because no single one is reliable across every wallet
+  + version on the wire.
+- **`getUserFriendlyErrorMessage` puts rejection detection FIRST.** A 4001
+  buried in a wrapper whose top-level message contains "execution
+  reverted" must still produce the cancelled-by-user copy.
+- **Default patterns are deliberately protocol-agnostic.** Custom-error
+  copy (`HashMismatch` → "Proof did not match the deposit") belongs
+  in your dapp's `customErrors` map, not in this package.
+
+## License
+
+MIT

package/dist/contract-error.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview Extract the decoded custom Solidity error name from a viem
+ * revert error.
+ *
+ * viem's `ContractFunctionRevertedError` exposes
+ * `data: { errorName, args, ... }` for decoded custom errors when the ABI
+ * is supplied. The decoded name is what the UI actually wants to surface
+ * ("HashMismatch" or "InsufficientDepositLiquidity") — much more useful
+ * than the wrapper's generic "execution reverted" text.
+ *
+ * The hard part is that viem's `data` field can sit several layers deep
+ * in the cause chain — sometimes flattened across an RPC boundary. We
+ * provide both a structured walk (`extractContractErrorName`) and a
+ * message-scraping fallback (`extractContractErrorNameFromMessage`) for
+ * the case where the cause chain has been collapsed.
+ */
+/**
+ * Walk the cause chain and return the first valid Solidity error name found
+ * on `data.errorName`. Returns null if no such name is present.
+ *
+ * @example
+ * ```ts
+ * const name = extractContractErrorName(error)
+ * if (name) {
+ *   showFriendlyMessage(name)
+ * }
+ * ```
+ */
+export declare function extractContractErrorName(error: unknown): string | null;
+/**
+ * Fall back to scraping viem's stringified message when the cause chain has
+ * been flattened (e.g. across an RPC boundary or after JSON round-tripping).
+ * Matches the literal "reverted with the following reason:\n<ErrorName>"
+ * shape viem produces.
+ */
+export declare function extractContractErrorNameFromMessage(raw: string): string | null;
+//# sourceMappingURL=contract-error.d.ts.map

package/dist/contract-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-error.d.ts","sourceRoot":"","sources":["../src/contract-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAYH;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAWtE;AAED;;;;;GAKG;AACH,wBAAgB,mCAAmC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI9E"}

package/dist/contract-error.js

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview Extract the decoded custom Solidity error name from a viem
+ * revert error.
+ *
+ * viem's `ContractFunctionRevertedError` exposes
+ * `data: { errorName, args, ... }` for decoded custom errors when the ABI
+ * is supplied. The decoded name is what the UI actually wants to surface
+ * ("HashMismatch" or "InsufficientDepositLiquidity") — much more useful
+ * than the wrapper's generic "execution reverted" text.
+ *
+ * The hard part is that viem's `data` field can sit several layers deep
+ * in the cause chain — sometimes flattened across an RPC boundary. We
+ * provide both a structured walk (`extractContractErrorName`) and a
+ * message-scraping fallback (`extractContractErrorNameFromMessage`) for
+ * the case where the cause chain has been collapsed.
+ */
+import { walkErrorCause } from './walk.js';
+/**
+ * Solidity custom error names start with an uppercase ASCII letter and
+ * contain only ASCII letters, digits, and underscores. Anything outside
+ * that pattern is rejected to avoid false positives — `data` fields named
+ * `errorName` exist on a few non-revert error shapes too.
+ */
+const ERROR_NAME_PATTERN = /^[A-Z][A-Za-z0-9_]*$/;
+/**
+ * Walk the cause chain and return the first valid Solidity error name found
+ * on `data.errorName`. Returns null if no such name is present.
+ *
+ * @example
+ * ```ts
+ * const name = extractContractErrorName(error)
+ * if (name) {
+ *   showFriendlyMessage(name)
+ * }
+ * ```
+ */
+export function extractContractErrorName(error) {
+    for (const link of walkErrorCause(error)) {
+        if (link === null || link === undefined || typeof link !== 'object')
+            continue;
+        const data = link.data;
+        if (data === null || data === undefined || typeof data !== 'object')
+            continue;
+        const name = data.errorName;
+        if (typeof name !== 'string')
+            continue;
+        if (!ERROR_NAME_PATTERN.test(name))
+            continue;
+        return name;
+    }
+    return null;
+}
+/**
+ * Fall back to scraping viem's stringified message when the cause chain has
+ * been flattened (e.g. across an RPC boundary or after JSON round-tripping).
+ * Matches the literal "reverted with the following reason:\n<ErrorName>"
+ * shape viem produces.
+ */
+export function extractContractErrorNameFromMessage(raw) {
+    if (raw.length === 0)
+        return null;
+    const match = raw.match(/reverted with the following reason:\s*\n?\s*([A-Z][A-Za-z0-9_]*)\(?/);
+    return match?.[1] ?? null;
+}
+//# sourceMappingURL=contract-error.js.map

package/dist/contract-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-error.js","sourceRoot":"","sources":["../src/contract-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAE1C;;;;;GAKG;AACH,MAAM,kBAAkB,GAAG,sBAAsB,CAAA;AAEjD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAc;IACrD,KAAK,MAAM,IAAI,IAAI,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;QACzC,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,SAAQ;QAC7E,MAAM,IAAI,GAAI,IAA2B,CAAC,IAAI,CAAA;QAC9C,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,SAAQ;QAC7E,MAAM,IAAI,GAAI,IAAgC,CAAC,SAAS,CAAA;QACxD,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,SAAQ;QACtC,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,SAAQ;QAC5C,OAAO,IAAI,CAAA;IACb,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mCAAmC,CAAC,GAAW;IAC7D,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IACjC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,qEAAqE,CAAC,CAAA;IAC9F,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAA;AAC3B,CAAC"}

package/dist/handle.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @fileoverview Centralised error handler for wagmi / viem write paths.
+ *
+ * Encapsulates the rejection-detection + friendly-message + status-reset
+ * pattern so every catch block / `onError` callback is a single line. The
+ * downstream payoff: a dapp's wallet UX stays consistent across every
+ * write site instead of each one re-implementing rejection-vs-failure
+ * detection (and getting it slightly wrong).
+ */
+import { type ErrorPattern } from './messages.js';
+/**
+ * Sinks the helper writes into when classifying an error.
+ */
+export interface HandleWalletErrorOptions {
+    /** Callback to set a UI status — `idle` on rejection, `error` on real failure. */
+    setStatus?: (status: 'idle' | 'error') => void;
+    /** Callback to store the user-facing message — `null` on rejection, friendly text on failure. */
+    setErrorMessage?: (message: string | null) => void;
+    /** Toast bridge (e.g. sonner). Rejection → `info`, real error → `error`. */
+    toast?: {
+        error: (message: string) => void;
+        info: (message: string) => void;
+    };
+    /** Always called with the underlying error (coerced to `Error`). */
+    onError?: (error: Error) => void;
+    /** Forwarded to `getUserFriendlyErrorMessage`. */
+    customErrors?: Record<string, string>;
+    /** Forwarded to `getUserFriendlyErrorMessage`. */
+    patterns?: readonly ErrorPattern[];
+    /** Forwarded to `getUserFriendlyErrorMessage`. */
+    fallback?: string;
+}
+/**
+ * Classify a thrown value as either a user rejection or a real failure, then
+ * route the configured sinks accordingly.
+ *
+ * @example
+ * ```ts
+ * // wagmi onError shape
+ * onError: (err) => handleWalletError(err, {
+ *   setStatus: setTxStatus,
+ *   setErrorMessage: setError,
+ *   toast,
+ *   customErrors: { HashMismatch: 'Proof did not match.' },
+ * })
+ *
+ * // catch block shape
+ * try {
+ *   await writeAsync(args)
+ * } catch (err) {
+ *   handleWalletError(err, { setStatus, setErrorMessage, toast })
+ * }
+ * ```
+ */
+export declare function handleWalletError(error: unknown, options?: HandleWalletErrorOptions): void;
+//# sourceMappingURL=handle.d.ts.map

package/dist/handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../src/handle.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,KAAK,YAAY,EAA+B,MAAM,eAAe,CAAA;AAE9E;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,kFAAkF;IAClF,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,KAAK,IAAI,CAAA;IAC9C,iGAAiG;IACjG,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;IAClD,4EAA4E;IAC5E,KAAK,CAAC,EAAE;QAAE,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;QAAC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAA;IAC7E,oEAAoE;IACpE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;IAChC,kDAAkD;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACrC,kDAAkD;IAClD,QAAQ,CAAC,EAAE,SAAS,YAAY,EAAE,CAAA;IAClC,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,wBAA6B,GACrC,IAAI,CAeN"}

package/dist/handle.js

@@ -0,0 +1,49 @@
+/**
+ * @fileoverview Centralised error handler for wagmi / viem write paths.
+ *
+ * Encapsulates the rejection-detection + friendly-message + status-reset
+ * pattern so every catch block / `onError` callback is a single line. The
+ * downstream payoff: a dapp's wallet UX stays consistent across every
+ * write site instead of each one re-implementing rejection-vs-failure
+ * detection (and getting it slightly wrong).
+ */
+import { USER_REJECTION_MESSAGE, isUserRejectionError } from './rejection.js';
+import { getUserFriendlyErrorMessage } from './messages.js';
+/**
+ * Classify a thrown value as either a user rejection or a real failure, then
+ * route the configured sinks accordingly.
+ *
+ * @example
+ * ```ts
+ * // wagmi onError shape
+ * onError: (err) => handleWalletError(err, {
+ *   setStatus: setTxStatus,
+ *   setErrorMessage: setError,
+ *   toast,
+ *   customErrors: { HashMismatch: 'Proof did not match.' },
+ * })
+ *
+ * // catch block shape
+ * try {
+ *   await writeAsync(args)
+ * } catch (err) {
+ *   handleWalletError(err, { setStatus, setErrorMessage, toast })
+ * }
+ * ```
+ */
+export function handleWalletError(error, options = {}) {
+    const { setStatus, setErrorMessage, toast, onError, customErrors, patterns, fallback } = options;
+    if (isUserRejectionError(error)) {
+        setStatus?.('idle');
+        setErrorMessage?.(null);
+        toast?.info(USER_REJECTION_MESSAGE);
+    }
+    else {
+        const message = getUserFriendlyErrorMessage(error, { customErrors, patterns, fallback });
+        setStatus?.('error');
+        setErrorMessage?.(message);
+        toast?.error(message);
+    }
+    onError?.(error instanceof Error ? error : new Error(String(error)));
+}
+//# sourceMappingURL=handle.js.map

package/dist/handle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle.js","sourceRoot":"","sources":["../src/handle.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AAC7E,OAAO,EAAqB,2BAA2B,EAAE,MAAM,eAAe,CAAA;AAsB9E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAc,EACd,UAAoC,EAAE;IAEtC,MAAM,EAAE,SAAS,EAAE,eAAe,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAA;IAEhG,IAAI,oBAAoB,CAAC,KAAK,CAAC,EAAE,CAAC;QAChC,SAAS,EAAE,CAAC,MAAM,CAAC,CAAA;QACnB,eAAe,EAAE,CAAC,IAAI,CAAC,CAAA;QACvB,KAAK,EAAE,IAAI,CAAC,sBAAsB,CAAC,CAAA;IACrC,CAAC;SAAM,CAAC;QACN,MAAM,OAAO,GAAG,2BAA2B,CAAC,KAAK,EAAE,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAA;QACxF,SAAS,EAAE,CAAC,OAAO,CAAC,CAAA;QACpB,eAAe,EAAE,CAAC,OAAO,CAAC,CAAA;QAC1B,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;IACvB,CAAC;IAED,OAAO,EAAE,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;AACtE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Public API of `@valve-tech/viem-errors`.
+ */
+export { walkErrorCause } from './walk.js';
+export { isUserRejectionError, USER_REJECTION_MESSAGE } from './rejection.js';
+export { extractContractErrorName, extractContractErrorNameFromMessage } from './contract-error.js';
+export { getUserFriendlyErrorMessage, DEFAULT_ERROR_PATTERNS, type ErrorPattern, } from './messages.js';
+export { handleWalletError, type HandleWalletErrorOptions } from './handle.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC1C,OAAO,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAA;AAC7E,OAAO,EAAE,wBAAwB,EAAE,mCAAmC,EAAE,MAAM,qBAAqB,CAAA;AACnG,OAAO,EACL,2BAA2B,EAC3B,sBAAsB,EACtB,KAAK,YAAY,GAClB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Public API of `@valve-tech/viem-errors`.
+ */
+export { walkErrorCause } from './walk.js';
+export { isUserRejectionError, USER_REJECTION_MESSAGE } from './rejection.js';
+export { extractContractErrorName, extractContractErrorNameFromMessage } from './contract-error.js';
+export { getUserFriendlyErrorMessage, DEFAULT_ERROR_PATTERNS, } from './messages.js';
+export { handleWalletError } from './handle.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC1C,OAAO,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAA;AAC7E,OAAO,EAAE,wBAAwB,EAAE,mCAAmC,EAAE,MAAM,qBAAqB,CAAA;AACnG,OAAO,EACL,2BAA2B,EAC3B,sBAAsB,GAEvB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,iBAAiB,EAAiC,MAAM,aAAa,CAAA"}

package/dist/messages.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @fileoverview Map raw viem / wagmi / wallet errors to short user-friendly
+ * messages.
+ *
+ * The default `DEFAULT_ERROR_PATTERNS` is deliberately protocol-agnostic —
+ * wallet rejection, gas/funds, replacement-tx, network/RPC, rate-limit,
+ * generic revert. Consumers add their protocol-specific custom-Solidity-error
+ * messages via the `customErrors` option on `getUserFriendlyErrorMessage`,
+ * and can prepend additional patterns via the `patterns` option without
+ * editing the default list.
+ *
+ * Match order at runtime:
+ *   1. Wallet rejection — surfaced first so a 4001 buried inside a wrapper
+ *      whose top-level message contains "execution reverted" still produces
+ *      the cancelled-by-user copy instead of the generic on-chain fallback.
+ *   2. Decoded custom-error name from `data.errorName` anywhere in the
+ *      cause chain — best signal when the ABI is wired through viem.
+ *   3. Custom-error name extracted from the wrapper's stringified message —
+ *      a flattened-cause-chain fallback.
+ *   4. Caller-supplied additional patterns (checked BEFORE defaults so a
+ *      consumer can override generic copy).
+ *   5. Default protocol-agnostic patterns.
+ *   6. The configured `fallback`, or a generic message.
+ */
+/** A pattern → message pair used by `getUserFriendlyErrorMessage`. */
+export interface ErrorPattern {
+    pattern: RegExp;
+    message: string;
+}
+/**
+ * Default protocol-agnostic patterns. Consumers can prepend their own
+ * via the `patterns` option; the consumer entries win.
+ */
+export declare const DEFAULT_ERROR_PATTERNS: readonly ErrorPattern[];
+/**
+ * Convert a raw error into a short, user-friendly message safe to display.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.signalIntent(params)
+ * } catch (error) {
+ *   const message = getUserFriendlyErrorMessage(error, {
+ *     customErrors: { HashMismatch: 'The proof did not match the deposit.' },
+ *   })
+ *   showToast(message)
+ * }
+ * ```
+ */
+export declare function getUserFriendlyErrorMessage(error: unknown, options?: {
+    customErrors?: Record<string, string>;
+    patterns?: readonly ErrorPattern[];
+    fallback?: string;
+}): string;
+//# sourceMappingURL=messages.d.ts.map

package/dist/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,sEAAsE;AACtE,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,YAAY,EA4BzD,CAAA;AAKD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,OAAO,EACd,OAAO,GAAE;IACP,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACrC,QAAQ,CAAC,EAAE,SAAS,YAAY,EAAE,CAAA;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAA;CACb,GACL,MAAM,CAqBR"}

package/dist/messages.js

@@ -0,0 +1,114 @@
+/**
+ * @fileoverview Map raw viem / wagmi / wallet errors to short user-friendly
+ * messages.
+ *
+ * The default `DEFAULT_ERROR_PATTERNS` is deliberately protocol-agnostic —
+ * wallet rejection, gas/funds, replacement-tx, network/RPC, rate-limit,
+ * generic revert. Consumers add their protocol-specific custom-Solidity-error
+ * messages via the `customErrors` option on `getUserFriendlyErrorMessage`,
+ * and can prepend additional patterns via the `patterns` option without
+ * editing the default list.
+ *
+ * Match order at runtime:
+ *   1. Wallet rejection — surfaced first so a 4001 buried inside a wrapper
+ *      whose top-level message contains "execution reverted" still produces
+ *      the cancelled-by-user copy instead of the generic on-chain fallback.
+ *   2. Decoded custom-error name from `data.errorName` anywhere in the
+ *      cause chain — best signal when the ABI is wired through viem.
+ *   3. Custom-error name extracted from the wrapper's stringified message —
+ *      a flattened-cause-chain fallback.
+ *   4. Caller-supplied additional patterns (checked BEFORE defaults so a
+ *      consumer can override generic copy).
+ *   5. Default protocol-agnostic patterns.
+ *   6. The configured `fallback`, or a generic message.
+ */
+import { extractContractErrorName, extractContractErrorNameFromMessage } from './contract-error.js';
+import { isUserRejectionError } from './rejection.js';
+/**
+ * Default protocol-agnostic patterns. Consumers can prepend their own
+ * via the `patterns` option; the consumer entries win.
+ */
+export const DEFAULT_ERROR_PATTERNS = [
+    // Gas / balance — should match before generic "execution reverted" because
+    // these are more specific.
+    { pattern: /insufficient funds/i, message: 'Insufficient funds for gas fees.' },
+    { pattern: /gas required exceeds/i, message: 'Transaction requires more gas than allowed.' },
+    // Replacement / nonce — single message because the user fix is identical
+    // (wait or speed up the prior pending tx).
+    {
+        pattern: /could not replace existing tx|replacement transaction underpriced|nonce too low/i,
+        message: 'A previous transaction is still pending. Please wait for it to confirm or speed it up in your wallet.',
+    },
+    // Network / RPC connectivity. "disconnected" before "could not detect" so
+    // the more user-actionable copy wins.
+    { pattern: /disconnected|not connected/i, message: 'Wallet disconnected. Please reconnect and try again.' },
+    { pattern: /could not detect network|network changed/i, message: 'Network connection issue. Please check your wallet network.' },
+    { pattern: /timeout|etimedout/i, message: 'Request timed out. Please try again.' },
+    { pattern: /fetch failed|econnrefused|enotfound/i, message: 'Unable to reach the server. Please check your connection.' },
+    // Rate limiting / service availability.
+    { pattern: /\b429\b|too many requests/i, message: 'Too many requests. Please wait a moment and try again.' },
+    { pattern: /\b503\b|service unavailable/i, message: 'Service temporarily unavailable. Please try again shortly.' },
+    // Generic on-chain revert — last resort. Specific custom-error extraction
+    // happens earlier in the pipeline, so reaching here means the revert
+    // wasn't decoded.
+    { pattern: /execution reverted/i, message: 'Transaction failed on-chain.' },
+];
+const DEFAULT_FALLBACK = 'Something went wrong. Please try again.';
+const DEFAULT_REJECTION_COPY = 'Transaction was cancelled.';
+/**
+ * Convert a raw error into a short, user-friendly message safe to display.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.signalIntent(params)
+ * } catch (error) {
+ *   const message = getUserFriendlyErrorMessage(error, {
+ *     customErrors: { HashMismatch: 'The proof did not match the deposit.' },
+ *   })
+ *   showToast(message)
+ * }
+ * ```
+ */
+export function getUserFriendlyErrorMessage(error, options = {}) {
+    if (isUserRejectionError(error))
+        return DEFAULT_REJECTION_COPY;
+    const raw = stringifyError(error);
+    const errorName = extractContractErrorName(error) ?? extractContractErrorNameFromMessage(raw);
+    if (errorName !== null) {
+        const friendly = options.customErrors?.[errorName];
+        return friendly !== undefined
+            ? `${friendly} (${errorName})`
+            : `Transaction failed: ${humaniseErrorName(errorName)}.`;
+    }
+    const consumerPatterns = options.patterns ?? [];
+    for (const { pattern, message } of consumerPatterns) {
+        if (pattern.test(raw))
+            return message;
+    }
+    for (const { pattern, message } of DEFAULT_ERROR_PATTERNS) {
+        if (pattern.test(raw))
+            return message;
+    }
+    return options.fallback ?? DEFAULT_FALLBACK;
+}
+/** "PaymentVerificationFailed" → "Payment Verification Failed" */
+function humaniseErrorName(name) {
+    return name.replace(/([A-Z])/g, ' $1').trim();
+}
+/** Normalise an unknown thrown value into a string for pattern matching. */
+function stringifyError(error) {
+    if (error === null || error === undefined)
+        return '';
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === 'string')
+        return error;
+    try {
+        return JSON.stringify(error);
+    }
+    catch {
+        return String(error);
+    }
+}
+//# sourceMappingURL=messages.js.map

package/dist/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"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"}

package/dist/rejection.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @fileoverview Detect a user-initiated wallet rejection.
+ *
+ * Wallet UX needs to distinguish *I cancelled* from *something failed*.
+ * The two surfaces look superficially similar — both throw, both reach
+ * `catch` blocks — but they call for different UI: rejection → reset to
+ * idle, real failure → show error message and offer retry.
+ *
+ * The challenge: rejection text varies by wallet, locale, and error
+ * version (`User rejected the request`, `user cancelled`, `User denied
+ * transaction signature`, `User disapproved`, etc.). Top-level
+ * `.message` matching alone is fragile because viem nests the actual
+ * rejection several layers deep — the wrapper's message reads
+ * `Failed to send transaction`, which would otherwise look like a
+ * generic failure and get the wrong UI.
+ */
+/** Toast-friendly message shown when the user rejects a wallet prompt. */
+export declare const USER_REJECTION_MESSAGE = "Transaction was rejected in wallet.";
+/**
+ * Check whether an error represents a user-initiated wallet rejection.
+ *
+ * Walks the cause chain (viem nests rejections several layers deep —
+ * typically `ContractFunctionExecutionError` → `RpcRequestError` →
+ * `UserRejectedRequestError`) and checks three independent signals at
+ * each level:
+ *   1. **EIP-1193 `code === 4001`** — the spec-mandated rejection code,
+ *      language-independent. The most reliable signal when present.
+ *   2. **Error name `UserRejectedRequestError`** — viem's class name.
+ *   3. **Message text regex** — fallback for wallets that bypass the
+ *      standard error class.
+ *
+ * Any one of those three is sufficient at any level in the chain.
+ */
+export declare function isUserRejectionError(error: unknown): boolean;
+//# sourceMappingURL=rejection.d.ts.map

package/dist/rejection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rejection.d.ts","sourceRoot":"","sources":["../src/rejection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,0EAA0E;AAC1E,eAAO,MAAM,sBAAsB,wCAAwC,CAAA;AAS3E;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAe5D"}

package/dist/rejection.js

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview Detect a user-initiated wallet rejection.
+ *
+ * Wallet UX needs to distinguish *I cancelled* from *something failed*.
+ * The two surfaces look superficially similar — both throw, both reach
+ * `catch` blocks — but they call for different UI: rejection → reset to
+ * idle, real failure → show error message and offer retry.
+ *
+ * The challenge: rejection text varies by wallet, locale, and error
+ * version (`User rejected the request`, `user cancelled`, `User denied
+ * transaction signature`, `User disapproved`, etc.). Top-level
+ * `.message` matching alone is fragile because viem nests the actual
+ * rejection several layers deep — the wrapper's message reads
+ * `Failed to send transaction`, which would otherwise look like a
+ * generic failure and get the wrong UI.
+ */
+import { walkErrorCause } from './walk.js';
+/** Toast-friendly message shown when the user rejects a wallet prompt. */
+export const USER_REJECTION_MESSAGE = 'Transaction was rejected in wallet.';
+/**
+ * Wallet-rejection text varies by wallet/locale ("User rejected the request",
+ * "user cancelled", "User denied transaction signature", …) so message
+ * matching alone is fragile. Order: most-common viem/MetaMask phrasing first.
+ */
+const REJECTION_MESSAGE_PATTERN = /user rejected|user denied|rejected the request|user cancelled|user canceled|user disapproved/i;
+/**
+ * Check whether an error represents a user-initiated wallet rejection.
+ *
+ * Walks the cause chain (viem nests rejections several layers deep —
+ * typically `ContractFunctionExecutionError` → `RpcRequestError` →
+ * `UserRejectedRequestError`) and checks three independent signals at
+ * each level:
+ *   1. **EIP-1193 `code === 4001`** — the spec-mandated rejection code,
+ *      language-independent. The most reliable signal when present.
+ *   2. **Error name `UserRejectedRequestError`** — viem's class name.
+ *   3. **Message text regex** — fallback for wallets that bypass the
+ *      standard error class.
+ *
+ * Any one of those three is sufficient at any level in the chain.
+ */
+export function isUserRejectionError(error) {
+    for (const link of walkErrorCause(error)) {
+        if (link === null || link === undefined)
+            continue;
+        if (typeof link === 'string') {
+            if (REJECTION_MESSAGE_PATTERN.test(link))
+                return true;
+            continue;
+        }
+        if (typeof link !== 'object')
+            continue;
+        const node = link;
+        if (node.code === 4001)
+            return true;
+        if (typeof node.name === 'string' && node.name === 'UserRejectedRequestError')
+            return true;
+        if (typeof node.message === 'string' && REJECTION_MESSAGE_PATTERN.test(node.message))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=rejection.js.map

package/dist/rejection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rejection.js","sourceRoot":"","sources":["../src/rejection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAE1C,0EAA0E;AAC1E,MAAM,CAAC,MAAM,sBAAsB,GAAG,qCAAqC,CAAA;AAE3E;;;;GAIG;AACH,MAAM,yBAAyB,GAAG,+FAA+F,CAAA;AAEjI;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,KAAK,MAAM,IAAI,IAAI,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;QACzC,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS;YAAE,SAAQ;QACjD,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,IAAI,yBAAyB,CAAC,IAAI,CAAC,IAAI,CAAC;gBAAE,OAAO,IAAI,CAAA;YACrD,SAAQ;QACV,CAAC;QACD,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,SAAQ;QAEtC,MAAM,IAAI,GAAG,IAA6D,CAAA;QAC1E,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI;YAAE,OAAO,IAAI,CAAA;QACnC,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,KAAK,0BAA0B;YAAE,OAAO,IAAI,CAAA;QAC1F,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,IAAI,yBAAyB,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,OAAO,IAAI,CAAA;IACnG,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC"}

package/dist/walk.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Walk an error's `cause` chain.
+ *
+ * viem nests errors several levels deep — `ContractFunctionExecutionError`
+ * wraps `RpcRequestError` wraps `UserRejectedRequestError`, etc. — so checks
+ * that only inspect the top-level error miss the actual underlying cause.
+ * This generator yields each link in order so callers can decide what to look
+ * for at each depth.
+ */
+/**
+ * Walk an error and its `cause` chain, yielding each link in order, starting
+ * with the error itself. Stops at `null`/`undefined`, when the chain hits a
+ * primitive that has no `cause`, or when `maxDepth` is reached. Default depth
+ * is 8 — enough for every viem stack we've seen in the wild without risking
+ * a runaway loop on a circular chain.
+ *
+ * @example
+ * ```ts
+ * for (const link of walkErrorCause(error)) {
+ *   if (typeof link === 'object' && link && 'code' in link && link.code === 4001) {
+ *     return true
+ *   }
+ * }
+ * ```
+ */
+export declare function walkErrorCause(error: unknown, options?: {
+    maxDepth?: number;
+}): Generator<unknown, void, unknown>;
+//# sourceMappingURL=walk.d.ts.map

package/dist/walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,wBAAiB,cAAc,CAC7B,KAAK,EAAE,OAAO,EACd,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,CASnC"}

package/dist/walk.js

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview Walk an error's `cause` chain.
+ *
+ * viem nests errors several levels deep — `ContractFunctionExecutionError`
+ * wraps `RpcRequestError` wraps `UserRejectedRequestError`, etc. — so checks
+ * that only inspect the top-level error miss the actual underlying cause.
+ * This generator yields each link in order so callers can decide what to look
+ * for at each depth.
+ */
+/**
+ * Walk an error and its `cause` chain, yielding each link in order, starting
+ * with the error itself. Stops at `null`/`undefined`, when the chain hits a
+ * primitive that has no `cause`, or when `maxDepth` is reached. Default depth
+ * is 8 — enough for every viem stack we've seen in the wild without risking
+ * a runaway loop on a circular chain.
+ *
+ * @example
+ * ```ts
+ * for (const link of walkErrorCause(error)) {
+ *   if (typeof link === 'object' && link && 'code' in link && link.code === 4001) {
+ *     return true
+ *   }
+ * }
+ * ```
+ */
+export function* walkErrorCause(error, options = {}) {
+    const maxDepth = options.maxDepth ?? 8;
+    let current = error;
+    for (let depth = 0; depth < maxDepth; depth++) {
+        if (current === null || current === undefined)
+            return;
+        yield current;
+        if (typeof current !== 'object')
+            return;
+        current = current.cause;
+    }
+}
+//# sourceMappingURL=walk.js.map

package/dist/walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.js","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,SAAS,CAAC,CAAC,cAAc,CAC7B,KAAc,EACd,UAAiC,EAAE;IAEnC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAA;IACtC,IAAI,OAAO,GAAY,KAAK,CAAA;IAC5B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,QAAQ,EAAE,KAAK,EAAE,EAAE,CAAC;QAC9C,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,SAAS;YAAE,OAAM;QACrD,MAAM,OAAO,CAAA;QACb,IAAI,OAAO,OAAO,KAAK,QAAQ;YAAE,OAAM;QACvC,OAAO,GAAI,OAA+B,CAAC,KAAK,CAAA;IAClD,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@valve-tech/viem-errors",
+  "version": "0.3.1",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/valve-tech/evm-toolkit.git",
+    "directory": "packages/viem-errors"
+  },
+  "bugs": {
+    "url": "https://github.com/valve-tech/evm-toolkit/issues"
+  },
+  "keywords": [
+    "ethereum",
+    "evm",
+    "viem",
+    "wagmi",
+    "errors",
+    "user-rejection",
+    "eip-1193",
+    "custom-error",
+    "wallet"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p .",
+    "typecheck": "tsc -p . --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "prepare": "yarn build"
+  },
+  "peerDependencies": {
+    "viem": "^2.0.0"
+  }
+}