@tokenops/sdk 1.0.0

package/dist/fhe/sepolia-encryptor-web.d.ts

@@ -0,0 +1,101 @@
+import type { PublicClient, WalletClient } from "viem";
+import type { Encryptor } from "../fhe-vesting/encryption.js";
+import { type SepoliaEncryptorLogger } from "./sepolia-encryptor.js";
+/**
+ * Configuration for {@link createSepoliaEncryptorWeb}. Minimal by design:
+ * the browser path doesn't expose worker pool sizing or storage knobs (the
+ * Web Worker is single-threaded by default, and `RelayerWeb` already
+ * defaults to `IndexedDBStorage` for FHE artifact caching).
+ */
+export interface CreateSepoliaEncryptorWebOpts {
+    /** Viem `PublicClient` — used only to resolve the chain id for the
+     * encryptor's `getChainId` callback. The encryptor itself never reads
+     * from the chain; encrypted handles + proofs are produced locally and
+     * the relayer is queried over HTTP. */
+    publicClient: PublicClient;
+    /** Viem `WalletClient` — kept on the options object for symmetry with
+     * the Node helper, even though `RelayerWeb` doesn't need it. Consumers
+     * compose the encryptor with the same client they pass to the SDK's
+     * vesting / disperse / airdrop factories. */
+    walletClient: WalletClient;
+    /**
+     * Override the Zama relayer URL. Defaults to Zama's public Sepolia
+     * testnet relayer (`https://relayer.testnet.zama.org/v2`) baked into
+     * `@zama-fhe/sdk`'s `SepoliaConfig`. Set this only for private relayer
+     * forks (rare; Zama-internal).
+     */
+    relayerUrl?: string;
+    /**
+     * Override the chain id this encryptor binds to. Defaults to
+     * {@link SEPOLIA_CHAIN_ID}. Pass {@link MAINNET_CHAIN_ID} for the
+     * mainnet relayer once Zama enables it; pre-mainnet this stays Sepolia.
+     */
+    chainId?: number;
+    /**
+     * Optional logger for tracing worker lifecycle and request timing. Same
+     * shape as the Node helper. Mirrored here for surface parity — when a
+     * consumer migrates a server-side script to a browser app, the logger
+     * config moves over unchanged.
+     *
+     * Any missing methods are filled with no-op stubs before reaching the
+     * underlying Zama relayer (see {@link createSepoliaEncryptor} for the
+     * background on why).
+     */
+    logger?: SepoliaEncryptorLogger;
+}
+/**
+ * Returned by {@link createSepoliaEncryptorWeb}. Same structural
+ * {@link Encryptor} contract as the Node version, plus the underlying
+ * `RelayerWeb` for callers that need `userDecrypt` / `publicDecrypt`
+ * (which the structural `Encryptor` interface doesn't surface) or
+ * explicit `terminate()` on page unload.
+ */
+export interface SepoliaEncryptorWeb extends Encryptor {
+    /**
+     * The underlying `RelayerWeb`. Typed `unknown` to avoid leaking the
+     * optional `@zama-fhe/sdk` peer dep into the SDK's public types. Cast
+     * to `import("@zama-fhe/sdk").RelayerWeb` at the use site.
+     */
+    readonly instance: unknown;
+    /** Chain id this encryptor is bound to (`11155111` for Sepolia). */
+    readonly chainId: number;
+    /**
+     * Tear down the Web Worker. The browser path doesn't require this —
+     * the worker is GC'd when the page unloads — but long-lived SPAs that
+     * swap encryptors (chain switch, user logout) should call it to free
+     * the WASM heap explicitly.
+     */
+    terminate(): void;
+}
+/**
+ * Construct an SDK-shaped {@link Encryptor} backed by Zama's `RelayerWeb`
+ * against the public Sepolia (or mainnet) relayer. The browser parity peer
+ * of {@link createSepoliaEncryptor} — same Encryptor contract, no
+ * `node:worker_threads` / `node:module` in the import graph, so bundlers
+ * (Next, Vite, etc.) follow only browser-safe paths.
+ *
+ * @example
+ * ```ts
+ * import { createSepoliaEncryptorWeb } from "@tokenops/sdk/fhe";
+ * import { createConfidentialVestingManagerClient } from "@tokenops/sdk/fhe-vesting";
+ *
+ * const encryptor = await createSepoliaEncryptorWeb({ publicClient, walletClient });
+ * const mgr = createConfidentialVestingManagerClient({
+ *   publicClient, walletClient, address: manager, encryptor,
+ * });
+ * await mgr.createVesting({ params, amount: 1_000_000n });
+ * ```
+ *
+ * @remarks
+ *   This is the **Sepolia / mainnet** path. For local Anvil
+ *   (`pnpm fhevm:up`), use `createMockEncryptor` instead. Mock and real
+ *   relayer ciphertexts are not interchangeable.
+ *
+ * @remarks
+ *   Unlike the Node helper, `RelayerWeb` owns a `Worker` (not
+ *   `worker_threads`); it does not keep the event loop alive. Calling
+ *   `terminate()` is optional in browsers — the worker is GC'd when the
+ *   page unloads. Call it explicitly on chain-switch or user-logout in
+ *   long-lived SPAs.
+ */
+export declare function createSepoliaEncryptorWeb(opts: CreateSepoliaEncryptorWebOpts): Promise<SepoliaEncryptorWeb>;

package/dist/fhe/sepolia-encryptor.d.ts

@@ -0,0 +1,132 @@
+import type { Encryptor } from "../fhe-vesting/encryption.js";
+/** Sepolia testnet chain id (`11155111`). Re-exported as a typed literal so
+ * consumers indexing `DEPLOYED_ADDRESSES` against this constant get the
+ * narrow return type, not `Address | undefined`. */
+export declare const SEPOLIA_CHAIN_ID: 11155111;
+/** Mainnet chain id (`1`). Same use as {@link SEPOLIA_CHAIN_ID}. */
+export declare const MAINNET_CHAIN_ID: 1;
+/** Subset of `@zama-fhe/sdk/node`'s `GenericLogger` we accept. Mirrored
+ * structurally so consumers don't need to import the optional peer dep just
+ * to type-narrow a logger arg. */
+export interface SepoliaEncryptorLogger {
+    debug?: (...args: unknown[]) => void;
+    info?: (...args: unknown[]) => void;
+    warn?: (...args: unknown[]) => void;
+    error?: (...args: unknown[]) => void;
+}
+/** Subset of `@zama-fhe/sdk/node`'s `GenericStorage` we accept. Mirrored
+ * structurally for the same reason as {@link SepoliaEncryptorLogger}. The
+ * RelayerNode caches FHE public-key + params here across sessions; default is
+ * an in-process memory map. Pass a redis-backed implementation for
+ * cross-restart persistence in long-lived Node servers. */
+export interface SepoliaEncryptorStorage {
+    get<T = unknown>(key: string): Promise<T | null>;
+    set<T = unknown>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * Configuration for {@link createSepoliaEncryptor}. All fields are optional;
+ * defaults match the Zama public Sepolia relayer.
+ */
+export interface CreateSepoliaEncryptorOptions {
+    /**
+     * Override the Zama relayer URL. Defaults to Zama's public Sepolia
+     * testnet relayer (`https://relayer.testnet.zama.org/v2`) baked into
+     * `@zama-fhe/sdk/node`'s `SepoliaConfig`. Set this only when running
+     * against a private relayer fork (rare; usually only Zama internal).
+     */
+    relayerUrl?: string;
+    /**
+     * Override the chain id this encryptor binds to. Defaults to
+     * {@link SEPOLIA_CHAIN_ID}. Pass {@link MAINNET_CHAIN_ID} for the
+     * mainnet relayer once Zama enables it; pre-mainnet this stays Sepolia.
+     */
+    chainId?: number;
+    /**
+     * Worker pool size. Defaults to `min(os.availableParallelism(), 4)` inside
+     * `@zama-fhe/sdk`. Each worker loads ~50–100 MB of WASM — decrease to 1–2
+     * on memory-constrained hosts, increase to match CPU cores for
+     * high-throughput batch encryption.
+     */
+    poolSize?: number;
+    /**
+     * Optional logger for tracing worker lifecycle and request timing. Useful
+     * during onboarding to see when the relayer round-trips happen; remove for
+     * production to avoid noisy logs.
+     */
+    logger?: SepoliaEncryptorLogger;
+    /**
+     * Persistent storage for FHE public key + params cache. Defaults to an
+     * in-process memory map (lost on restart). Pass a redis-backed
+     * `GenericStorage` for cross-restart persistence in long-lived servers —
+     * the public params are several MB; re-fetching on every restart adds
+     * seconds of cold start.
+     */
+    fheArtifactStorage?: SepoliaEncryptorStorage;
+    /**
+     * Cache TTL in seconds for FHE public material. Default: 86400 (24h).
+     * Set to 0 to revalidate on every operation (rare; only useful for tests
+     * that want to exercise the fetch path).
+     */
+    fheArtifactCacheTTL?: number;
+}
+/**
+ * Returned by {@link createSepoliaEncryptor}. Carries the underlying
+ * `RelayerNode` so consumers who need user-decrypt or worker lifecycle
+ * control can reach it, plus the chain id this encryptor is bound to.
+ */
+export interface SepoliaEncryptor extends Encryptor {
+    /**
+     * The underlying `RelayerNode`. Use this for `userDecrypt` /
+     * `publicDecrypt` flows the SDK's structural {@link Encryptor} interface
+     * doesn't surface. Typed `unknown` to avoid importing the optional
+     * `@zama-fhe/sdk` peer dep into the SDK's public types.
+     */
+    readonly instance: unknown;
+    /** Chain id this encryptor is bound to (`11155111` for Sepolia). */
+    readonly chainId: number;
+    /**
+     * Tear down the underlying worker thread pool. **Must be called** before
+     * `process.exit()` (or at the end of any Node script) — RelayerNode owns
+     * `node:worker_threads` that keep the event loop alive. Forgetting to call
+     * `terminate()` is the #1 reason Sepolia scripts hang after `main()`
+     * resolves.
+     */
+    terminate(): void;
+}
+/**
+ * Construct an SDK-shaped {@link Encryptor} backed by Zama's `RelayerNode`
+ * against the public Sepolia (or mainnet) relayer. One call replaces the
+ * hand-rolled `new RelayerNode({ transports: { 11155111: SepoliaConfig }, getChainId: async () => 11155111 })`
+ * boilerplate every Sepolia consumer used to copy from
+ * `node_modules/@zama-fhe/sdk/dist/esm/node/index.d.ts`.
+ *
+ * @example
+ * ```ts
+ * import { createSepoliaEncryptor } from "@tokenops/sdk/fhe";
+ * import { createConfidentialVestingManagerClient } from "@tokenops/sdk/fhe-vesting";
+ *
+ * const encryptor = await createSepoliaEncryptor();
+ * try {
+ *   const mgr = createConfidentialVestingManagerClient({
+ *     publicClient, walletClient, address: manager, encryptor,
+ *   });
+ *   await mgr.createVesting({ params, amount: 1_000_000n });
+ * } finally {
+ *   encryptor.terminate(); // RelayerNode owns worker_threads — always tear down.
+ * }
+ * ```
+ *
+ * @remarks
+ *   This is the **Sepolia / mainnet** path. For local Anvil
+ *   (`pnpm fhevm:up`), use {@link createMockEncryptor} instead. The mock and
+ *   the real relayer do not share a bytestream — handles are not portable
+ *   across them.
+ *
+ * @remarks
+ *   The returned encryptor owns a `node:worker_threads` pool. Always wrap the
+ *   create + use cycle in a `try / finally { encryptor.terminate(); }` so the
+ *   pool tears down even on errors. Without `terminate()` the Node process
+ *   hangs after `main()` resolves.
+ */
+export declare function createSepoliaEncryptor(options?: CreateSepoliaEncryptorOptions): Promise<SepoliaEncryptor>;

package/dist/fhe/types.d.ts

@@ -0,0 +1,62 @@
+import type { Hex } from "viem";
+/**
+ * A single `externalEuint64` ciphertext: the on-chain handle plus the KMS
+ * input proof that authorises it. Produced by `encryptUint64` and consumed
+ * by every `@tokenops/sdk` write method that takes an encrypted amount.
+ *
+ * The handle and proof are bound to the `(contractAddress, userAddress)`
+ * pair passed at encryption time and cannot be replayed against a different
+ * contract or sender. Field names match the on-chain calldata layout
+ * (`bytes32 handle, bytes inputProof`) so the value spreads directly into
+ * contract calls.
+ *
+ * The current SDK only produces uint64 ciphertexts. If a future version
+ * adds encryption helpers for other widths (e.g. `encryptUint128`), this
+ * type may be specialised; existing uint64 usage will keep type-checking.
+ */
+export interface EncryptedInput {
+    handle: Hex;
+    inputProof: Hex;
+}
+/**
+ * N `externalEuint64` ciphertexts sharing a single KMS input proof. One
+ * proof per batch is cheaper than N independent proofs and is the shape the
+ * encryptor returns from a batched `encrypt({ values: [...] })` call.
+ *
+ * `handles[i]` corresponds to the i-th plaintext value passed in.
+ */
+export interface EncryptedInputs {
+    handles: Hex[];
+    inputProof: Hex;
+}
+/**
+ * Return shape for SDK methods that perform an on-chain encrypted-view tx —
+ * the contract emits `FHE.allow(handle, msg.sender)` and the SDK extracts
+ * `handle` from the receipt's ACL `Allowed` event.
+ *
+ * Pass `handle` to the Zama relayer's `userDecrypt` to obtain the plaintext.
+ * `hash` is the tx that committed the persistent ACL grant — surface it if
+ * your UI needs to show the receipt.
+ */
+export interface EncryptedViewResult {
+    handle: Hex;
+    hash: Hex;
+}
+/**
+ * @deprecated Use {@link EncryptedInput}. Earlier versions of
+ * `@tokenops/sdk/fhe` exported this name with field `proof`, which did not
+ * match the rest of the SDK or the on-chain calldata layout (the contracts
+ * accept `bytes inputProof`). This alias points at the corrected shape and
+ * will be removed in the next major.
+ */
+export type EncryptedInput64 = EncryptedInput;
+/**
+ * @deprecated Use `Hex` from `viem` directly. This alias added no narrowing
+ * beyond `Hex` and will be removed in the next major.
+ */
+export type EncryptedHandle = Hex;
+/**
+ * @deprecated Use `Hex` from `viem` directly. This alias added no narrowing
+ * beyond `Hex` and will be removed in the next major.
+ */
+export type ExternalInputProof = Hex;