@tokenops/sdk 1.0.0

package/dist/core/normalise.d.ts

@@ -0,0 +1,27 @@
+import type { Address } from "viem";
+/**
+ * Normalise a hex-string address to its EIP-55 checksum form.
+ *
+ * Closes nextjs-integrator MAJOR `2026-05-24-nextjs-integrator-isaddress-strict-trap.md`:
+ * viem's `isAddress(value, { strict: true })` (the default since v2) rejects
+ * any non-checksum input — but consumers routinely paste raw lowercase
+ * addresses from etherscan, env files, or wallet UIs. The footgun is silent:
+ * `isAddress` returns `false`, the SDK rejects the input, the consumer gets
+ * "invalid address" with no hint that EIP-55 checksum is the problem.
+ *
+ * This helper:
+ *   1. Accepts any address shape (lowercase, uppercase, mixed, checksummed).
+ *   2. Validates structural correctness via `isAddress(..., { strict: false })`.
+ *   3. Normalises to checksum via `getAddress` — the canonical form every
+ *      downstream contract call expects.
+ *
+ * Throws {@link TokenOpsValidationError} (not viem's `InvalidAddressError`)
+ * so consumers' \`instanceof TokenOpsSdkError\` blocks catch it consistently.
+ *
+ * ```ts
+ * import { normaliseAddress } from "@tokenops/sdk";
+ * const recipient = normaliseAddress(req.body.recipient);
+ * await factory.createManager({ recipient, ... });
+ * ```
+ */
+export declare function normaliseAddress(input: string): Address;

package/dist/core/preflight.d.ts

@@ -0,0 +1,25 @@
+import type { TokenOpsSdkError } from "./errors.js";
+/**
+ * Result of a read-only preflight on a write operation.
+ *
+ * The SDK exposes opt-in preflight helpers (`preflightClaim`, `preflightDisperse`,
+ * etc.) that run the deterministic-from-off-chain checks in parallel — array
+ * length / fee balance / claim window / batch limit / role membership — and
+ * return whether the write is safe to submit. `blockers` carries the typed
+ * errors that *would* have been thrown at write time: same `code`, same
+ * `context`, just collected instead of thrown. UIs can render them with the
+ * same branching they use in `onError`.
+ *
+ * Preflight is opt-in. Consumers who have already validated state can skip the
+ * preflight and call the write directly.
+ */
+export interface PreflightResult {
+    /** `true` when no blockers were detected — green light to submit the write. */
+    ready: boolean;
+    /**
+     * Typed errors that would otherwise be thrown at write time. Empty when
+     * `ready === true`. Branch on `error.code` to render UI; the same `code`
+     * values appear here that the write path would throw.
+     */
+    blockers: TokenOpsSdkError[];
+}

package/dist/core/revert-mapper.d.ts

@@ -0,0 +1,74 @@
+import type { Abi, Address } from "viem";
+import { TokenOpsSdkError } from "./errors.js";
+/** Per-product mapping: contract error name → typed SDK error constructor. */
+export type RevertNameMapper = (name: string, args: readonly unknown[] | undefined, ctx: RevertMapperContext) => TokenOpsSdkError | undefined;
+/** Context passed into product mappers. `productContext` lets the call site forward args (vestingId, user, etc.) for the mapper to embed in the typed error. */
+export interface RevertMapperContext {
+    method: string;
+    contractAddress: Address;
+    /**
+     * Optional bag of arguments from the call site that the product mapper can
+     * pick up — e.g. `{ vestingId }` for vesting writes, `{ user }` for disperse
+     * writes. The mapper does NOT trust this for security decisions; it's only
+     * used to populate UI-facing context fields.
+     */
+    productContext?: Record<string, unknown>;
+}
+export interface MapContractRevertArgs {
+    /** Method label that appears in `error.context.method`. */
+    method: string;
+    /** Contract whose ABI is used to decode the revert; also surfaced in `context`. */
+    contractAddress: Address;
+    /** ABI used for `decodeErrorResult`. Pass the product-specific ABI (manager / airdrop / disperse). */
+    abi: Abi;
+    /**
+     * Optional product-specific mapper run BEFORE the cross-product default
+     * mapper. Return a typed error to short-circuit, or `undefined` to fall
+     * through to {@link defaultRevertNameMapper}.
+     *
+     * Use this to wire product-specific revert names (e.g. `"VestingNotFound"`
+     * → `VestingNotFoundError`).
+     */
+    productMapper?: RevertNameMapper;
+    /** Forwarded into `RevertMapperContext.productContext` for product mappers. */
+    productContext?: Record<string, unknown>;
+    /** Wallet account, surfaced into `AccessDeniedError.context.account` when present. */
+    account?: Address;
+}
+/**
+ * Translate any error thrown by a `writeContract` / `readContract` / `simulateContract`
+ * call into a {@link TokenOpsSdkError}. Always succeeds — falls back to
+ * {@link ContractRevertError} when no typed mapping applies.
+ *
+ * The mapper walks the viem `BaseError` chain to find a
+ * {@link ContractFunctionRevertedError}, decodes the revert data against the
+ * supplied ABI, and runs the per-product mapper before the default
+ * cross-product mapper ({@link defaultRevertNameMapper}). Errors that already
+ * brand as `TokenOpsSdkError` pass through unchanged so SDK-thrown errors
+ * (`InvalidArgumentError`, `MissingEncryptorError`, etc.) aren't re-wrapped.
+ */
+export declare function mapContractRevert(error: unknown, args: MapContractRevertArgs): TokenOpsSdkError;
+/**
+ * Convenience wrapper: run a write builder and translate any thrown error
+ * through {@link mapContractRevert}.
+ */
+export declare function withMappedRevert<T>(args: MapContractRevertArgs, builder: () => Promise<T>): Promise<T>;
+/**
+ * Cross-product mapping for revert names that mean the same thing everywhere.
+ * Product-specific revert names should be handled by a `productMapper` passed
+ * to {@link mapContractRevert} and only fall through to this when not matched.
+ */
+export declare function defaultRevertNameMapper(name: string, errArgs: readonly unknown[] | undefined, ctx: RevertMapperContext, account?: Address): TokenOpsSdkError | undefined;
+/**
+ * Heuristic: does an error from `simulateContract` / `writeContract` represent
+ * an on-chain contract revert (vs. a transport, decoder, or stub-mock
+ * failure)?
+ *
+ * Used by per-product `#preflightWrite` helpers to decide whether to surface
+ * the simulate failure through the typed mapper or swallow it and let the
+ * subsequent `writeContract` call report the issue with full fidelity. The
+ * preflight exists exclusively to recover revert metadata that wallet
+ * transports drop during gas estimation — anything that isn't a revert isn't
+ * the preflight's signal to report.
+ */
+export declare function isContractRevert(error: unknown): boolean;

package/dist/core/telemetry.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Tag values accepted by {@link SdkTelemetry.scope}. Mirrors `Record<string, unknown>`
+ * but pinned to the primitives a structured logger can serialise without surprise.
+ *
+ * `string | number | boolean` only — no nested objects, no `Date`, no arrays.
+ * Adapters that need richer tags can widen at the consumer boundary.
+ */
+export type SdkTelemetryTags = Record<string, string | number | boolean>;
+export interface SdkTelemetry {
+    /** Fire-and-forget event. Implementations must not throw. */
+    event(name: string, props?: Record<string, unknown>): void;
+    /** Wrap an async operation; implementations decide what to time/log. */
+    span<T>(name: string, fn: () => Promise<T>): Promise<T>;
+    /** Report an error. Implementations must not re-throw. */
+    error(err: Error, context?: Record<string, unknown>): void;
+    /**
+     * Return a child telemetry that automatically prepends `tags` to every
+     * subsequent `event` / `span` / `error` call.
+     *
+     * Pattern parity with pino's `logger.child(bindings)` and winston's
+     * `logger.child(meta)`. Lets a server build a per-request telemetry
+     * (`telemetry.scope({ requestId, userId })`) without monkey-patching.
+     *
+     * **Optional on the interface** — adapters that don't carry scope context
+     * (NoopTelemetry, third-party adapters where child-loggers aren't a fit)
+     * can omit. The SDK never calls `.scope` internally; it's a consumer-side
+     * affordance for downstream correlation.
+     *
+     * Adapters that DO implement it should return a NEW telemetry instance —
+     * mutating `this` would leak tags across unrelated consumers sharing the
+     * same SDK client.
+     *
+     * Added per backend-integrator-r14 nit-positive friction
+     * (`docs/feedback/resolved/2026-05-24-backend-integrator-r14-minor-sdktelemetry-shape-matches-node-logger-pattern-cleanly.md`).
+     */
+    scope?(tags: SdkTelemetryTags): SdkTelemetry;
+}
+export declare class NoopTelemetry implements SdkTelemetry {
+    event(): void;
+    span<T>(_name: string, fn: () => Promise<T>): Promise<T>;
+    error(): void;
+    /**
+     * No-op telemetry has no state to carry — returning `this` is correct and
+     * avoids a per-request allocation. Consumers that swap to a real adapter
+     * will get a fresh child instance per call.
+     */
+    scope(_tags: SdkTelemetryTags): SdkTelemetry;
+}
+/** Helper used inside SDK clients: span + error forwarding. */
+export declare function withTelemetry<T>(telemetry: SdkTelemetry | undefined, name: string, fn: () => Promise<T>): Promise<T>;

package/dist/core/types.d.ts

@@ -0,0 +1,10 @@
+import type { Address, Hex, PublicClient, WalletClient } from "viem";
+export type { Address, Hex };
+export interface ClientPair {
+    publicClient: PublicClient;
+    walletClient?: WalletClient;
+}
+export type ContractRef = {
+    address: Address;
+    chainId: number;
+};

package/dist/core/version.d.ts

@@ -0,0 +1,15 @@
+/**
+ * SDK version baked at build time. Mirrors `package.json#version`.
+ *
+ * Hard-coded rather than read at runtime because:
+ * (a) consumers ship the SDK as ESM/CJS in serverless/browser environments
+ *     where `node:fs` is not available and `import.meta.url`-based lookups
+ *     are flaky across bundlers;
+ * (b) the value participates in `fhe-vesting.client.init` telemetry, which
+ *     must work the moment the constructor runs — there's no time for an
+ *     async read.
+ *
+ * Keep in sync with `package.json` via the `prepublishOnly` gate. If the two
+ * drift, telemetry funnels will report a stale version.
+ */
+export declare const SDK_VERSION = "1.0.0";

package/dist/core/zama-error-mapper.d.ts

@@ -0,0 +1,27 @@
+import { TokenOpsSdkError } from "./errors.js";
+/**
+ * Wrap any error produced by `@zama-fhe/sdk` (`RelayerWeb`, `RelayerNode`,
+ * `MockFhevmInstance`) or `@fhevm/mock-utils` into a {@link TokenOpsSdkError}.
+ * Always succeeds — falls back to {@link EncryptionFailedError} or
+ * {@link DecryptionFailedError} depending on the caller's `operation`.
+ *
+ * Errors already branded as `TokenOpsSdkError` pass through unchanged so
+ * SDK-thrown errors (`InvalidArgumentError` from `assertUint64`, etc.) aren't
+ * re-wrapped.
+ *
+ * @param error Error caught from a Zama-SDK call.
+ * @param args.method Method label that appears in `error.context.method`.
+ * @param args.operation Logical operation: `"encrypt"`, `"user-decrypt"`,
+ *   `"public-decrypt"`, etc. Drives the fallback when the Zama error code is
+ *   missing or unknown.
+ */
+export declare function mapZamaError(error: unknown, args: {
+    method: string;
+    operation: ZamaOperation;
+}): TokenOpsSdkError;
+/** Convenience: run a Zama-SDK call and translate any thrown error. */
+export declare function withMappedZamaError<T>(args: {
+    method: string;
+    operation: ZamaOperation;
+}, call: () => Promise<T>): Promise<T>;
+export type ZamaOperation = "encrypt" | "user-decrypt" | "public-decrypt" | "delegated-user-decrypt" | "request-zk-proof";

package/dist/fhe/acl.d.ts

@@ -0,0 +1,73 @@
+import type { Address } from "viem";
+/**
+ * FHEVM ACL contract addresses indexed by chain id. Encrypted-view helpers in
+ * product modules (`fhe-vesting`, `fhe-airdrop`, `fhe-disperse`) filter
+ * receipt logs by this address to identify ACL grants emitted during the tx —
+ * picking the wrong address means the strict-singleton check spuriously fails
+ * or, worse, returns the wrong handle.
+ *
+ * Keep this map as the single source of truth across products. Update all
+ * three entries together when Zama publishes new host contracts.
+ *
+ * - Hardhat / Anvil (forge-fhevm) — see `@zama-fhe/sdk` `HardhatConfig`.
+ * - Sepolia — `SepoliaConfig.aclContractAddress`.
+ * - Mainnet — `MainnetConfig.aclContractAddress`.
+ *
+ * Prefer the accessors {@link getFhevmAclAddress} / {@link requireFhevmAclAddress}
+ * over reaching into this object directly — they centralise chain-id
+ * resolution and the typed-error policy. Indexing the map directly is still
+ * supported for advanced consumers who need raw registry access.
+ */
+export declare const FHEVM_ACL_ADDRESS_BY_CHAIN: {
+    readonly 31337: "0x50157CFfD6bBFA2DECe204a89ec419c23ef5755D";
+    readonly 11155111: "0xf0Ffdc93b7E186bC2f8CB3dAA75D86d1930A433D";
+    readonly 1: "0xcA2E8f1F656CD25C01F05d0b243Ab1ecd4a8ffb6";
+};
+/**
+ * `Allowed(address indexed caller, address indexed account, bytes32 handle)`
+ * — emitted by the FHEVM ACL contract whenever a handle is granted to an
+ * address. Encrypted-view helpers parse this from the tx receipt to extract
+ * the handle the contract granted to the caller; using `simulateContract` for
+ * the same purpose returns a divergent handle that has no ACL grant.
+ */
+export declare const ACL_ALLOWED_EVENT: {
+    readonly name: "Allowed";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "caller";
+        readonly indexed: true;
+    }, {
+        readonly type: "address";
+        readonly name: "account";
+        readonly indexed: true;
+    }, {
+        readonly type: "bytes32";
+        readonly name: "handle";
+    }];
+};
+/**
+ * Resolve the FHEVM ACL contract address for `chainId`, returning `undefined`
+ * when the chain isn't recognised. Mirrors the `get*Address` shape in
+ * `core/addresses.ts`.
+ *
+ * Use this when the caller wants to handle "no ACL on this chain" without
+ * a throw — e.g. constructing a product client lazily and deferring the
+ * error to first encrypted-view use.
+ */
+export declare function getFhevmAclAddress(chainId: number): Address | undefined;
+/**
+ * Resolve the FHEVM ACL contract address for `chainId`, throwing
+ * {@link DeploymentAddressUnavailableError} when it can't be determined.
+ * Mirrors the `require*Address` shape in `core/addresses.ts`.
+ *
+ * Accepts `chainId: undefined` so callers can pass `publicClient.chain?.id`
+ * directly without a pre-check; the helper handles the `chain-id-missing`
+ * branch itself.
+ *
+ * `clientLabel` is embedded in the thrown error so consumers can tell which
+ * client misconfigured ACL (e.g. `"ConfidentialVestingManagerClient"`).
+ * The error's `context.overrideName` is set to `"aclAddress"` so the
+ * message points users at the right config knob.
+ */
+export declare function requireFhevmAclAddress(chainId: number | undefined, clientLabel: string): Address;

package/dist/fhe/erc7984-abi.d.ts

@@ -0,0 +1,53 @@
+export declare const erc7984OperatorAbi: readonly [{
+    readonly inputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "holder";
+        readonly type: "address";
+    }, {
+        readonly internalType: "address";
+        readonly name: "spender";
+        readonly type: "address";
+    }];
+    readonly name: "isOperator";
+    readonly outputs: readonly [{
+        readonly internalType: "bool";
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "operator";
+        readonly type: "address";
+    }, {
+        readonly internalType: "uint48";
+        readonly name: "until";
+        readonly type: "uint48";
+    }];
+    readonly name: "setOperator";
+    readonly outputs: readonly [];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}, {
+    readonly anonymous: false;
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly internalType: "address";
+        readonly name: "holder";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly internalType: "address";
+        readonly name: "operator";
+        readonly type: "address";
+    }, {
+        readonly indexed: false;
+        readonly internalType: "uint48";
+        readonly name: "until";
+        readonly type: "uint48";
+    }];
+    readonly name: "OperatorSet";
+    readonly type: "event";
+}];