@tokenops/sdk 1.0.0

package/dist/fhe-vesting/react/_shared.d.ts

@@ -0,0 +1,122 @@
+import type { Address, PublicClient, WalletClient } from "viem";
+import { DeploymentAddressUnavailableError } from "../../core/errors.js";
+import type { SdkTelemetry } from "../../core/telemetry.js";
+import { type Encryptor, type EncryptorSource } from "../encryption.js";
+import { type ConfidentialVestingFactoryClient } from "../factory.js";
+import { type ConfidentialVestingManagerClient } from "../manager.js";
+/** Common per-hook overrides — every public hook accepts these alongside its own args. */
+export interface BaseHookOptions {
+    /** Override the on-chain contract address. Defaults to {@link getFheVestingFactoryAddress} keyed by chain id. */
+    address?: Address;
+    /** Override the chain id used for default address resolution. Defaults to `usePublicClient().chain?.id`. */
+    chainId?: number;
+    /**
+     * Optional telemetry adapter. Forwarded into the headless client so spans
+     * and `*.client.init` events from `factory.*` writes flow through whichever
+     * sink the consumer wires up (PostHog, OTel, Sentry, custom).
+     */
+    telemetry?: SdkTelemetry;
+}
+/** Per-hook overrides for FHE-vesting *manager* hooks — `address` is required (per-user clone). */
+export interface ManagerHookOptions {
+    address: Address;
+    /**
+     * Lazy or eager encryptor source. Optional at hook level; **required at call
+     * time** for methods that submit encrypted inputs (`useCreateVesting`,
+     * `useBatchCreateVesting`, `usePartialClaim`, `useAdminPartialClaim`,
+     * `useSplitVesting`, `useWithdrawAdmin`, `useWithdrawTokenFee`).
+     *
+     * Recommended in React: capture `useZamaSDK()` once at the top of your
+     * component and wire `encryptor: () => sdk.relayer` — the SDK
+     * calls this per-encryption so it picks up the live `ZamaSDK` instance
+     * rather than a stale capture (CLAUDE.md Pitfall #3). An eager `Encryptor`
+     * instance also type-checks and is appropriate for server-side or test code.
+     *
+     * The SDK does NOT call `useZamaSDK()` automatically — calling a React hook
+     * from inside a mutation body would violate the rules of hooks. If
+     * `encryptor` is omitted and a method that needs one runs, the SDK throws
+     * `TokenOpsSdkError("Missing encryptor — pass ...")`.
+     */
+    encryptor?: EncryptorSource;
+    /** Override the FHEVM ACL address (defaults to chain-id lookup). */
+    aclAddress?: Address;
+    /** Override the chain id used for ACL/public-client lookup. Defaults to `usePublicClient().chain?.id`. */
+    chainId?: number;
+    /**
+     * Optional telemetry adapter. Forwarded into the headless client so spans
+     * and `*.client.init` events from `manager.*` writes flow through whichever
+     * sink the consumer wires up.
+     */
+    telemetry?: SdkTelemetry;
+}
+/** Stable query-key prefix for every hook in this subpath. */
+export declare const FHE_VESTING_KEY: "tokenops-sdk";
+export declare const FHE_VESTING_NAMESPACE: "fhe-vesting";
+/**
+ * Resolve the FHE-vesting factory address for `chainId`, mirroring the
+ * headless client's resolution. Throws the same {@link TokenOpsSdkError} the
+ * headless client would throw at construction time.
+ */
+export declare function resolveFactoryAddress(override: Address | undefined, chainId: number | undefined): Address;
+/**
+ * Same as {@link resolveFactoryAddress} but returns `undefined` instead of
+ * throwing. Used by query-key builders and `enabled` gates.
+ */
+export declare function tryResolveFactoryAddress(override: Address | undefined, chainId: number | undefined): Address | undefined;
+/**
+ * Memoize an {@link ConfidentialVestingFactoryClient} keyed on
+ * `(publicClient, walletClient, address)`. The factory client only takes a
+ * stable address, so we can safely instantiate once per identity tuple.
+ *
+ * @returns `{ client, publicClient, walletClient }`. `client` is `undefined`
+ *   when no `publicClient` is available (wagmi may briefly return `undefined`
+ *   during reconnects) — gate queries with `enabled: !!client`.
+ */
+export declare function useMemoFactoryClient(opts?: BaseHookOptions): {
+    client: ConfidentialVestingFactoryClient | undefined;
+    resolutionError: DeploymentAddressUnavailableError | undefined;
+    publicClient: PublicClient | undefined;
+    walletClient: WalletClient | undefined;
+    chainId: number | undefined;
+    resolvedAddress: Address | undefined;
+};
+/**
+ * Memoize a {@link ConfidentialVestingManagerClient} keyed on
+ * `(publicClient, walletClient, address)`. The encryptor source is passed
+ * through as a **lazy** function (mirroring Pitfall #3 from CLAUDE.md): the
+ * SDK calls it per-encryption, picking up the live React context at submit
+ * time rather than baking in a stale capture.
+ */
+export declare function useMemoManagerClient(opts: ManagerHookOptions): {
+    client: ConfidentialVestingManagerClient | undefined;
+    publicClient: PublicClient | undefined;
+    walletClient: WalletClient | undefined;
+    chainId: number | undefined;
+};
+/**
+ * Resolve the encryptor for a mutation call. Order:
+ * 1. Explicit `override` (eager `Encryptor` or lazy `() => Encryptor | undefined`).
+ * 2. The hook-level `encryptor` source from `ManagerHookOptions`.
+ *
+ * Both are resolved per-call (not cached), mirroring the lazy `EncryptorSource`
+ * pattern from CLAUDE.md Pitfall #3 — the consumer's React context is the
+ * source of truth.
+ *
+ * If both are missing, throws an actionable error. The hook layer does NOT
+ * dynamically import `@zama-fhe/react-sdk` — calling `useZamaSDK()` from
+ * inside `mutationFn` would violate the rules of hooks. Consumers wire the
+ * encryptor at hook construction. The safe pattern is two lines:
+ * `const sdk = useZamaSDK();` then `encryptor: () => sdk.relayer` — never
+ * `() => useZamaSDK().relayer` inline (that calls a React hook inside a
+ * mutation body, violating the rules of hooks).
+ */
+export declare function resolveCallTimeEncryptor(override: Encryptor | EncryptorSource | undefined, hookLevelSource: EncryptorSource | undefined): Encryptor;
+/**
+ * Build a stable TanStack Query key for an FHE-vesting hook.
+ *
+ * Conventions:
+ * - Lowercase the contract address (TanStack uses structural equality; viem
+ *   sometimes returns checksummed addresses).
+ * - Convert bigints to base-10 strings (TanStack's serializer doesn't handle bigints).
+ */
+export declare function buildQueryKey(method: string, chainId: number | undefined, address: Address | undefined, ...args: ReadonlyArray<unknown>): ReadonlyArray<unknown>;