@tokenops/sdk 1.0.0

package/dist/core/errors.d.ts

@@ -0,0 +1,687 @@
+import type { Address, Hex } from "viem";
+/**
+ * Cross-realm / cross-bundle safe brand. Consumers should narrow on this via
+ * {@link isTokenOpsSdkError} rather than `instanceof` when the SDK might be
+ * duplicated in their bundle graph (monorepos with hoisting issues, ESM/CJS
+ * dual loads, Next.js route-handler vs client-bundle splits, etc.). `instanceof`
+ * still works for the common case.
+ */
+declare const TOKENOPS_SDK_ERROR_BRAND: unique symbol;
+/**
+ * Stable, string-literal error codes. Codes are the machine contract — match
+ * on `error.code` in `onError` handlers and UI surfaces. Messages stay
+ * human-readable and may evolve between versions.
+ */
+export type TokenOpsSdkErrorCode = "TOKENOPS_UNSUPPORTED_CHAIN" | "TOKENOPS_DEPLOYMENT_ADDRESS_UNAVAILABLE" | "TOKENOPS_MISSING_PUBLIC_CLIENT" | "TOKENOPS_MISSING_WALLET_CLIENT" | "TOKENOPS_MISSING_ACCOUNT" | "TOKENOPS_MISSING_ENCRYPTOR" | "TOKENOPS_MISSING_CLIENT" | "TOKENOPS_INVALID_ARGUMENT" | "TOKENOPS_RECEIPT_EVENT_NOT_FOUND" | "TOKENOPS_RECEIPT_EVENT_AMBIGUOUS" | "TOKENOPS_CONTRACT_REVERT" | "TOKENOPS_PAUSED" | "TOKENOPS_ACCESS_DENIED" | "TOKENOPS_INSUFFICIENT_FEE" | "TOKENOPS_INSUFFICIENT_BALANCE" | "TOKENOPS_BATCH_TOO_LARGE" | "TOKENOPS_FEATURE_DISABLED" | "TOKENOPS_TRANSFER_FAILED" | "TOKENOPS_FHE_HANDLE_NOT_ALLOWED" | "TOKENOPS_ALREADY_INITIALIZED" | "TOKENOPS_REENTRANCY" | "TOKENOPS_INVALID_SIGNATURE" | "TOKENOPS_WALLET_REJECTED" | "TOKENOPS_WALLET_CHAIN_MISMATCH" | "TOKENOPS_NETWORK_ERROR" | "TOKENOPS_INSUFFICIENT_GAS_FUNDS" | "TOKENOPS_UNKNOWN_WRITE_FAILURE" | "TOKENOPS_USER_REJECTED" | "TOKENOPS_SIGNING_FAILED" | "TOKENOPS_RELAYER_UNREACHABLE" | "TOKENOPS_ENCRYPTION_FAILED" | "TOKENOPS_DECRYPTION_FAILED" | "TOKENOPS_USER_DECRYPT_NOT_ALLOWED" | "TOKENOPS_VESTING_NOT_FOUND" | "TOKENOPS_NOT_RECIPIENT" | "TOKENOPS_CLAIM_LOCKED" | "TOKENOPS_VESTING_REVOKED" | "TOKENOPS_NOT_REVOCABLE" | "TOKENOPS_VESTING_EXPIRED" | "TOKENOPS_TRANSFER_ALREADY_PENDING" | "TOKENOPS_NO_PENDING_TRANSFER" | "TOKENOPS_NOT_PENDING_RECIPIENT" | "TOKENOPS_TRANSFER_EXPIRED" | "TOKENOPS_ALREADY_CLAIMED" | "TOKENOPS_CLAIM_NOT_STARTED" | "TOKENOPS_CLAIM_WINDOW_CLOSED" | "TOKENOPS_NOT_REGISTERED" | "TOKENOPS_ALREADY_REGISTERED";
+export interface TokenOpsSdkErrorInit {
+    code: TokenOpsSdkErrorCode;
+    cause?: unknown;
+    context?: Record<string, unknown>;
+}
+/**
+ * Base class for every error the SDK throws. Carries a stable `code`
+ * discriminator (machine contract), a typed `context` payload (structured
+ * data for logs / UI), and the standard `cause` chain (set via
+ * `ErrorOptions`, so loggers and devtools follow it natively).
+ *
+ * Subclasses narrow `context` to a concrete shape and pin `code` to a single
+ * literal — `if (error.code === "TOKENOPS_MISSING_ENCRYPTOR") error.context.method` typechecks.
+ */
+export declare class TokenOpsSdkError extends Error {
+    readonly name: string;
+    readonly code: TokenOpsSdkErrorCode;
+    readonly context: Record<string, unknown>;
+    readonly [TOKENOPS_SDK_ERROR_BRAND] = true;
+    constructor(message: string, init?: TokenOpsSdkErrorInit);
+}
+/**
+ * Brand-based predicate. Prefer over `instanceof` when bundling boundaries
+ * may have caused duplicate SDK copies — `Symbol.for` is realm-global, so the
+ * brand survives.
+ */
+export declare function isTokenOpsSdkError(error: unknown): error is TokenOpsSdkError;
+export declare class UnsupportedChainError extends TokenOpsSdkError {
+    readonly name = "UnsupportedChainError";
+    readonly context: {
+        chainId: number;
+    };
+    constructor(chainId: number, options?: {
+        cause?: unknown;
+    });
+}
+export type DeploymentAddressUnavailableReason = "chain-id-missing" | "registry-not-deployed" | "registry-unknown-chain";
+/**
+ * Thrown when the SDK cannot resolve a deployed contract address for the
+ * caller's chain. `context.reason` tells you why — branch UI on it:
+ * - `chain-id-missing` — caller didn't pass `chainId` and `publicClient.chain` was undefined.
+ * - `registry-not-deployed` — chain is known to the SDK but the product isn't deployed there yet (`null` in registry).
+ * - `registry-unknown-chain` — chain id absent from the registry entirely.
+ *
+ * `context.overrideName` names the client-config knob the caller should set
+ * to bypass the registry (defaults to `"address"`). Infra contracts whose
+ * override lives under a different key — e.g. `aclAddress` on the FHE
+ * clients — set this so the error message points users at the right field.
+ */
+export declare class DeploymentAddressUnavailableError extends TokenOpsSdkError {
+    readonly name = "DeploymentAddressUnavailableError";
+    readonly context: {
+        reason: DeploymentAddressUnavailableReason;
+        product?: string;
+        contract?: string;
+        chainId?: number;
+        clientLabel?: string;
+        overrideName?: string;
+    };
+    constructor(args: {
+        reason: DeploymentAddressUnavailableReason;
+        product?: string;
+        contract?: string;
+        chainId?: number;
+        clientLabel?: string;
+        overrideName?: string;
+        cause?: unknown;
+    });
+}
+export declare class MissingPublicClientError extends TokenOpsSdkError {
+    readonly name = "MissingPublicClientError";
+    readonly context: {
+        method: string;
+    };
+    constructor(method: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare class MissingWalletClientError extends TokenOpsSdkError {
+    readonly name = "MissingWalletClientError";
+    readonly context: {
+        method: string;
+    };
+    constructor(method: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare class MissingAccountError extends TokenOpsSdkError {
+    readonly name = "MissingAccountError";
+    readonly context: {
+        method: string;
+    };
+    constructor(method: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare class MissingEncryptorError extends TokenOpsSdkError {
+    readonly name = "MissingEncryptorError";
+    readonly context: {
+        method: string;
+        hint?: string;
+    };
+    constructor(method: string, options?: {
+        hint?: string;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown by React hooks when their headless client (factory / manager /
+ * airdrop / disperse) could not be constructed — usually because the wagmi
+ * `publicClient` isn't ready yet or the chain id has no resolvable address.
+ * Tests gate on `enabled: !!client`, so this fires only on the mutation path.
+ */
+export declare class MissingClientError extends TokenOpsSdkError {
+    readonly name = "MissingClientError";
+    readonly context: {
+        hook: string;
+        clientKind: string;
+    };
+    constructor(hook: string, clientKind: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when an argument fails an SDK-side precondition (non-empty array,
+ * uint range, matching lengths, valid address, etc.). `context.argument`
+ * names the offending parameter; `context.reason` is the short explanation
+ * that's also embedded in the message.
+ */
+export declare class InvalidArgumentError extends TokenOpsSdkError {
+    readonly name = "InvalidArgumentError";
+    readonly context: {
+        method: string;
+        argument: string;
+        reason: string;
+        value?: unknown;
+    };
+    constructor(args: {
+        method: string;
+        argument: string;
+        reason: string;
+        value?: unknown;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when extracting an event from a transaction receipt finds zero
+ * matching entries — typically a silent revert, a misrouted log, or
+ * (most commonly for FHE flows) an ACL `Allowed` grant that didn't fire
+ * because the contract entrypoint took an early return path.
+ *
+ * Wraps the receipt-based handle extraction pattern described in
+ * CLAUDE.md Pitfall #1: SDK methods that return an encrypted handle MUST
+ * parse the receipt's ACL `Allowed` event, never `simulateContract().result`.
+ */
+export declare class ReceiptEventNotFoundError extends TokenOpsSdkError {
+    readonly name = "ReceiptEventNotFoundError";
+    readonly context: {
+        method: string;
+        eventName: string;
+        contractAddress: Address;
+        txHash: Hex;
+        hint?: string;
+    };
+    constructor(args: {
+        method: string;
+        eventName: string;
+        contractAddress: Address;
+        txHash: Hex;
+        hint?: string;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when receipt-event extraction finds more than one matching event
+ * from the target contract. Indicates either a re-entrancy surprise or an
+ * SDK bug in the filter shape — the SDK errs on the side of refusing to
+ * guess which entry is authoritative.
+ *
+ * **What to do.** This is not a retry candidate. Inspect the failing tx
+ * (`context.txHash`) on a block explorer: if multiple `Allowed` events
+ * appear, either a compound view emitted several or two encrypted views
+ * landed in the same tx. File a bug with the tx hash so the SDK can add a
+ * caller-specific helper rather than picking heuristically.
+ */
+export declare class ReceiptEventAmbiguousError extends TokenOpsSdkError {
+    readonly name = "ReceiptEventAmbiguousError";
+    readonly context: {
+        method: string;
+        eventName: string;
+        contractAddress: Address;
+        txHash: Hex;
+        count: number;
+    };
+    constructor(args: {
+        method: string;
+        eventName: string;
+        contractAddress: Address;
+        txHash: Hex;
+        count: number;
+        cause?: unknown;
+    });
+}
+/**
+ * Generic wrapper for any on-chain revert the SDK decodes but does not have a
+ * more specific typed subclass for. Always preferred over bubbling raw viem
+ * errors. `context.revertName` and `context.revertSelector` let consumers
+ * branch on specific contract errors without needing to import the contract's
+ * ABI; `context.revertArgs` carries the decoded arg tuple as-is.
+ *
+ * If the revert could not be decoded against the SDK's ABIs (custom error not
+ * in the ABI, raw `revert()` with no data, etc.), all three fields stay
+ * `undefined` and `context.rawRevertData` holds the original calldata. Always
+ * prefer this over letting viem's `ContractFunctionExecutionError` escape.
+ */
+export declare class ContractRevertError extends TokenOpsSdkError {
+    readonly name = "ContractRevertError";
+    readonly context: {
+        method: string;
+        contractAddress: Address;
+        revertName?: string;
+        revertSelector?: Hex;
+        revertArgs?: readonly unknown[];
+        revertReason?: string;
+        rawRevertData?: Hex;
+    };
+    constructor(args: {
+        method: string;
+        contractAddress: Address;
+        revertName?: string;
+        revertSelector?: Hex;
+        revertArgs?: readonly unknown[];
+        revertReason?: string;
+        rawRevertData?: Hex;
+        message?: string;
+        cause?: unknown;
+    });
+}
+/** Contract is paused. Read `paused()` before retrying. */
+export declare class PausedError extends TokenOpsSdkError {
+    readonly name = "PausedError";
+    readonly context: {
+        method: string;
+        contractAddress: Address;
+    };
+    constructor(args: {
+        method: string;
+        contractAddress: Address;
+        cause?: unknown;
+    });
+}
+/**
+ * OpenZeppelin AccessControl rejected the caller. `context.role` is the bytes32
+ * role selector when the SDK can decode it (`AccessControlUnauthorizedAccount`
+ * carries `(account, role)`); otherwise `undefined`. Callers can map the role
+ * selector back to a human name via the client's `roleConstants()` helper.
+ */
+export declare class AccessDeniedError extends TokenOpsSdkError {
+    readonly name = "AccessDeniedError";
+    readonly context: {
+        method: string;
+        contractAddress: Address;
+        account?: Address;
+        role?: Hex;
+    };
+    constructor(args: {
+        method: string;
+        contractAddress: Address;
+        account?: Address;
+        role?: Hex;
+        cause?: unknown;
+    });
+}
+/**
+ * Native ETH (gas) fee or token fee did not match what the contract requires.
+ * `feeKind === "gas"` means the `msg.value` was wrong; `"token"` means the
+ * encrypted token-fee BPS did not produce a matching encrypted total.
+ *
+ * The SDK does not echo plaintext FHE values — `provided` and `required` are
+ * populated only for the `gas` case where both sides are public.
+ */
+export declare class InsufficientFeeError extends TokenOpsSdkError {
+    readonly name = "InsufficientFeeError";
+    readonly context: {
+        method: string;
+        contractAddress: Address;
+        feeKind: "gas" | "token";
+        required?: bigint;
+        provided?: bigint;
+    };
+    constructor(args: {
+        method: string;
+        contractAddress: Address;
+        feeKind: "gas" | "token";
+        required?: bigint;
+        provided?: bigint;
+        cause?: unknown;
+    });
+}
+/**
+ * Balance is too low to cover the requested operation. `balanceKind` picks the
+ * asset class. For confidential balances the underlying value is encrypted, so
+ * `requested` / `available` stay `undefined` — the SDK never echoes plaintext
+ * FHE values into `context`.
+ */
+export declare class InsufficientBalanceError extends TokenOpsSdkError {
+    readonly name = "InsufficientBalanceError";
+    readonly context: {
+        method: string;
+        contractAddress: Address;
+        balanceKind: "eth" | "erc20" | "confidential";
+        requested?: bigint;
+        available?: bigint;
+    };
+    constructor(args: {
+        method: string;
+        contractAddress: Address;
+        balanceKind: "eth" | "erc20" | "confidential";
+        requested?: bigint;
+        available?: bigint;
+        cause?: unknown;
+    });
+}
+/**
+ * Batch size exceeds the contract's configured maximum.
+ *
+ * Note: `context.max` is `bigint` (the contract returns `uint256` for batch
+ * limits, even though realistic values fit comfortably in `Number`). Call
+ * `Number(error.context.max)` or `.toString()` before string-interpolating.
+ */
+export declare class BatchTooLargeError extends TokenOpsSdkError {
+    readonly name = "BatchTooLargeError";
+    readonly context: {
+        method: string;
+        contractAddress: Address;
+        requested: number;
+        /** `bigint` — call `Number(max)` or `max.toString()` before string interpolation. */
+        max: bigint;
+    };
+    constructor(args: {
+        method: string;
+        contractAddress: Address;
+        requested: number;
+        max: bigint;
+        cause?: unknown;
+    });
+}
+/**
+ * A feature toggle baked into the contract clone is off. For LibClone
+ * deployments these toggles are immutable (set at clone time) — the user
+ * cannot enable them after the fact and must deploy a new clone.
+ */
+export declare class FeatureDisabledError extends TokenOpsSdkError {
+    readonly name = "FeatureDisabledError";
+    readonly context: {
+        method: string;
+        contractAddress: Address;
+        feature: string;
+    };
+    constructor(args: {
+        method: string;
+        contractAddress: Address;
+        feature: string;
+        cause?: unknown;
+    });
+}
+/**
+ * Native ETH or ERC-20 transfer failed at the contract layer (e.g. recipient
+ * is a contract that rejects `receive()`, or the underlying ERC-20 returned
+ * false from `transfer`).
+ */
+export declare class TransferFailedError extends TokenOpsSdkError {
+    readonly name = "TransferFailedError";
+    readonly context: {
+        method: string;
+        contractAddress: Address;
+        asset: "eth" | Address;
+    };
+    constructor(args: {
+        method: string;
+        contractAddress: Address;
+        asset: "eth" | Address;
+        cause?: unknown;
+    });
+}
+/**
+ * Caller does not hold an FHEVM ACL grant on the encrypted handle they're
+ * trying to use (e.g. disclosure, re-share).
+ *
+ * **This is the on-chain side of the same logical problem as
+ * {@link UserDecryptNotAllowedError}.** Both mean "you don't have permission
+ * on this encrypted value"; they differ in *when* the SDK detects it:
+ *
+ * - `FheHandleNotAllowedError` (this class) fires when a contract entrypoint
+ *   calls `FHE.isSenderAllowed(handle)` on-chain and reverts. The tx made it
+ *   to the EVM but the contract refused.
+ * - `UserDecryptNotAllowedError` fires when the Zama relayer's user-decrypt
+ *   flow refuses to issue a decryption response. No on-chain tx was sent.
+ *
+ * `context.handle` is the offending handle (the public 32-byte ciphertext
+ * identifier), when extractable from the revert args. The SDK never decodes
+ * the underlying plaintext.
+ */
+export declare class FheHandleNotAllowedError extends TokenOpsSdkError {
+    readonly name = "FheHandleNotAllowedError";
+    readonly context: {
+        method: string;
+        contractAddress: Address;
+        handle?: Hex;
+        account?: Address;
+    };
+    constructor(args: {
+        method: string;
+        contractAddress: Address;
+        handle?: Hex;
+        account?: Address;
+        cause?: unknown;
+    });
+}
+/** Contract has already been initialized — `initialize()` may only run once. */
+export declare class AlreadyInitializedError extends TokenOpsSdkError {
+    readonly name = "AlreadyInitializedError";
+    readonly context: {
+        method: string;
+        contractAddress: Address;
+    };
+    constructor(args: {
+        method: string;
+        contractAddress: Address;
+        cause?: unknown;
+    });
+}
+/** OpenZeppelin ReentrancyGuardTransient blocked a nested call. */
+export declare class ReentrancyError extends TokenOpsSdkError {
+    readonly name = "ReentrancyError";
+    readonly context: {
+        method: string;
+        contractAddress: Address;
+    };
+    constructor(args: {
+        method: string;
+        contractAddress: Address;
+        cause?: unknown;
+    });
+}
+/**
+ * EIP-712 signature was malformed or did not recover to an authorized signer.
+ * Used by airdrop claims where the admin signs a `Claim(recipient, encryptedAmount)`
+ * struct off-chain.
+ */
+export declare class InvalidSignatureError extends TokenOpsSdkError {
+    readonly name = "InvalidSignatureError";
+    readonly context: {
+        method: string;
+        contractAddress: Address;
+    };
+    constructor(args: {
+        method: string;
+        contractAddress: Address;
+        cause?: unknown;
+    });
+}
+/**
+ * Wallet UI cancelled the request — e.g. the user clicked "Reject" on the
+ * transaction prompt, or the wallet bridge returned EIP-1193 code 4001.
+ * Retrying is safe; the underlying tx never reached the network.
+ */
+export declare class WalletRejectedError extends TokenOpsSdkError {
+    readonly name = "WalletRejectedError";
+    readonly context: {
+        method: string;
+        contractAddress?: Address;
+    };
+    constructor(args: {
+        method: string;
+        contractAddress?: Address;
+        cause?: unknown;
+    });
+}
+/**
+ * The connected wallet is on a different chain than the contract we tried to
+ * call. The user must switch networks before retrying.
+ */
+export declare class WalletChainMismatchError extends TokenOpsSdkError {
+    readonly name = "WalletChainMismatchError";
+    readonly context: {
+        method: string;
+        contractAddress?: Address;
+    };
+    constructor(args: {
+        method: string;
+        contractAddress?: Address;
+        cause?: unknown;
+    });
+}
+/**
+ * Network-level failure reaching the RPC endpoint (HTTP non-2xx, timeout,
+ * DNS, socket close). `statusCode` is set when the underlying viem
+ * `HttpRequestError` exposed an HTTP status. No on-chain state changed.
+ */
+export declare class NetworkError extends TokenOpsSdkError {
+    readonly name = "NetworkError";
+    readonly context: {
+        method: string;
+        contractAddress?: Address;
+        statusCode?: number;
+    };
+    constructor(args: {
+        method: string;
+        contractAddress?: Address;
+        statusCode?: number;
+        cause?: unknown;
+    });
+}
+/**
+ * Wallet account does not hold enough native balance to cover the
+ * transaction's gas estimate. Distinct from {@link InsufficientFeeError},
+ * which fires when the contract itself enforces a fee.
+ */
+export declare class InsufficientGasFundsError extends TokenOpsSdkError {
+    readonly name = "InsufficientGasFundsError";
+    readonly context: {
+        method: string;
+        contractAddress?: Address;
+    };
+    constructor(args: {
+        method: string;
+        contractAddress?: Address;
+        cause?: unknown;
+    });
+}
+/**
+ * Fallback for write failures the SDK could not classify against either an
+ * on-chain revert frame or a known viem non-revert error class. Inspect
+ * `error.cause` for diagnostics; this is the case to file a bug for.
+ */
+export declare class UnknownWriteFailureError extends TokenOpsSdkError {
+    readonly name = "UnknownWriteFailureError";
+    readonly context: {
+        method: string;
+        contractAddress?: Address;
+    };
+    constructor(args: {
+        method: string;
+        contractAddress?: Address;
+        cause?: unknown;
+    });
+}
+/** User cancelled the wallet signature prompt. */
+export declare class UserRejectedSignatureError extends TokenOpsSdkError {
+    readonly name = "UserRejectedSignatureError";
+    readonly context: {
+        method: string;
+        operation: string;
+    };
+    constructor(args: {
+        method: string;
+        operation: string;
+        cause?: unknown;
+    });
+}
+/**
+ * Wallet signature failed for a reason other than the user explicitly
+ * rejecting it (timeout, wallet crash, malformed request, etc.).
+ */
+export declare class SigningFailedError extends TokenOpsSdkError {
+    readonly name = "SigningFailedError";
+    readonly context: {
+        method: string;
+        operation: string;
+    };
+    constructor(args: {
+        method: string;
+        operation: string;
+        cause?: unknown;
+    });
+}
+/**
+ * Network call to the Zama relayer failed (HTTP non-2xx, timeout, DNS, etc.).
+ * `statusCode` is set when the underlying error exposed it.
+ */
+export declare class RelayerUnreachableError extends TokenOpsSdkError {
+    readonly name = "RelayerUnreachableError";
+    readonly context: {
+        method: string;
+        operation: string;
+        statusCode?: number;
+    };
+    constructor(args: {
+        method: string;
+        operation: string;
+        statusCode?: number;
+        cause?: unknown;
+    });
+}
+/** Encryption flow (input proof generation) failed. */
+export declare class EncryptionFailedError extends TokenOpsSdkError {
+    readonly name = "EncryptionFailedError";
+    readonly context: {
+        method: string;
+        operation: string;
+    };
+    constructor(args: {
+        method: string;
+        operation: string;
+        cause?: unknown;
+    });
+}
+/** Decryption flow (user-decrypt, public-decrypt) failed. */
+export declare class DecryptionFailedError extends TokenOpsSdkError {
+    readonly name = "DecryptionFailedError";
+    readonly context: {
+        method: string;
+        operation: string;
+    };
+    constructor(args: {
+        method: string;
+        operation: string;
+        cause?: unknown;
+    });
+}
+/**
+ * Zama ACL refused to grant decryption for the caller on the requested handle.
+ *
+ * **This is the off-chain side of the same logical problem as
+ * {@link FheHandleNotAllowedError}.** Both mean "you don't have permission
+ * on this encrypted value"; they differ in *when* the SDK detects it:
+ *
+ * - `UserDecryptNotAllowedError` (this class) fires before any chain
+ *   interaction — the Zama relayer / ACL precompile refused to issue a
+ *   decryption response, typically because no `FHE.allow(handle, sender)`
+ *   ever fired for this caller.
+ * - `FheHandleNotAllowedError` fires when a contract entrypoint calls
+ *   `FHE.isSenderAllowed(handle)` on-chain and reverts. The tx made it to
+ *   the EVM but the contract refused.
+ */
+export declare class UserDecryptNotAllowedError extends TokenOpsSdkError {
+    readonly name = "UserDecryptNotAllowedError";
+    readonly context: {
+        method: string;
+        handle?: Hex;
+        userAddress?: Address;
+    };
+    constructor(args: {
+        method: string;
+        handle?: Hex;
+        userAddress?: Address;
+        cause?: unknown;
+    });
+}
+/**
+ * Free-form validation error thrown by SDK helpers that don't have a more
+ * specific typed subclass yet (e.g. `normaliseAddress`). Accepts a free-form
+ * `context` object so call sites can attach whatever per-throw metadata they
+ * need; consumers branch on `error.code === "TOKENOPS_INVALID_ARGUMENT"` (the
+ * same code `InvalidArgumentError` uses).
+ */
+export declare class TokenOpsValidationError extends TokenOpsSdkError {
+    readonly name = "TokenOpsValidationError";
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Generic contract-interaction error thrown by SDK helpers that wrap
+ * `writeContract` + receipt-wait (e.g. `setOperator`, `mintMockERC7984`)
+ * outside the typed revert-mapper path. Accepts a free-form `context` object;
+ * consumers branch on `error.code === "TOKENOPS_CONTRACT_REVERT"`.
+ */
+export declare class TokenOpsContractError extends TokenOpsSdkError {
+    readonly name = "TokenOpsContractError";
+    constructor(message: string, context?: Record<string, unknown>);
+}
+export {};

package/dist/core/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./addresses.js";
+export * from "./brands.js";
+export * from "./chains.js";
+export * from "./errors.js";
+export * from "./preflight.js";
+export * from "./types.js";
+export { type SdkTelemetry, type SdkTelemetryTags } from "./telemetry.js";