@tokenops/sdk 1.0.0

package/dist/fhe-disperse/singleton.d.ts

@@ -0,0 +1,442 @@
+import type { Account, Address, Hex, PublicClient, WalletClient } from "viem";
+import { type TxHash } from "../core/brands.js";
+import { type SdkTelemetry } from "../core/telemetry.js";
+import { type Encryptor, type EncryptorSource } from "./encryption.js";
+import { type BatchLimits, type CalculateFeeArgs, type CalculatedFee, type CustomFee, type DisperseArgs, type DisperseResult, type DisclosureResult, type BatchDiscloseHandlesArgs, type DiscloseHandleArgs, type EncryptedInput, type EncryptedViewResult, type FeeConfig, type GetEncryptedFeeReserveArgs, type PreflightDisperseArgs, type PreflightReport, type RegisterResult, type SubwalletApprovalState, type UserFees, type WithdrawTokenFeeResult } from "./types.js";
+export interface ConfidentialDisperseClientConfig {
+    /** viem public client for read calls. */
+    publicClient: PublicClient;
+    /** viem wallet client for write calls. Optional for read-only usage. */
+    walletClient?: WalletClient | undefined;
+    /**
+     * Override the singleton address. Falls back to
+     * `DEPLOYED_ADDRESSES.fheDisperse.disperseConfidentialSingleton[chainId]`.
+     * Required when that entry is `null` (i.e., singleton not yet deployed on this chain).
+     */
+    address?: Address | undefined;
+    /**
+     * Chain id used to look up the default singleton address and the FHEVM ACL address.
+     * Defaults to `publicClient.chain?.id`.
+     */
+    chainId?: number | undefined;
+    /**
+     * Default encryptor for `disperse` and `getEncryptedFeeReserve`.
+     * Accepts an eager instance or a lazy factory (for React / Vue hosts).
+     *
+     * **Wallet-switch hazard.** A `RelayerWeb` instance binds to the signing
+     * keypair active when it was constructed. If you cache a single SDK client
+     * across wallet switches in a React/Vue app, the lazy factory MUST return
+     * a freshly constructed `RelayerWeb` for the new active account — returning
+     * a memoised instance built for the previous user will produce
+     * input-proofs the KMSVerifier rejects on-chain.
+     */
+    encryptor?: EncryptorSource | undefined;
+    /**
+     * FHEVM ACL contract address override. When omitted, resolved from the
+     * effective chain id (`chainId` arg or `publicClient.chain?.id`) via the
+     * SDK's chain registry; the constructor throws
+     * `DeploymentAddressUnavailableError` if neither is available. Required
+     * because `getEncryptedFeeReserve` filters the receipt for ACL grants
+     * to extract the returned handle.
+     */
+    aclAddress?: Address | undefined;
+    /**
+     * Optional telemetry sink. When provided, the SDK emits a `fhe-disperse.client.init`
+     * event on construction and brackets public write methods with named spans
+     * (`fhe-disperse.singleton.register`, `…disperse`, …). Defaults to a no-op —
+     * zero overhead, zero leakage of consumer-side identifiers.
+     *
+     * The shape is structurally compatible with `NoopTelemetry` / `ConsoleTelemetry` /
+     * `TokenOpsTelemetry` exported from `@tokenops/sdk/telemetry`.
+     */
+    telemetry?: SdkTelemetry | undefined;
+}
+/**
+ * Typed SDK wrapper for the deployed `DisperseConfidential` singleton.
+ *
+ * One `DisperseConfidential` exists per chain (no factory). This client is
+ * wired to a specific chain's singleton address, either by explicit `address`
+ * override or via `DEPLOYED_ADDRESSES.fheDisperse.disperseConfidentialSingleton[chainId]`.
+ *
+ * @example
+ * // On Sepolia or mainnet the singleton address auto-resolves from
+ * // `DEPLOYED_ADDRESSES.fheDisperse.disperseConfidentialSingleton[chainId]`;
+ * // pass `address` explicitly only for custom networks.
+ * const client = new ConfidentialDisperseClient({
+ *   publicClient,
+ *   walletClient,
+ *   encryptor,
+ * });
+ * await client.register({ token });
+ * await client.disperse({ token, mode: "direct", recipients, amounts });
+ */
+export declare class ConfidentialDisperseClient {
+    #private;
+    readonly publicClient: PublicClient;
+    readonly walletClient?: WalletClient;
+    readonly address: Address;
+    readonly encryptor?: EncryptorSource;
+    constructor(config: ConfidentialDisperseClientConfig);
+    /**
+     * The FHEVM ACL contract address used by encrypted-view methods to parse
+     * `ACL.Allowed` events. Resolved lazily on first access; throws
+     * `DeploymentAddressUnavailableError` if no override was passed and the
+     * SDK does not have an ACL deployed for the connected chain.
+     */
+    get aclAddress(): Address;
+    /**
+     * Check whether a user has registered their wallet pair via `register(token)`.
+     */
+    isRegistered(user: Address): Promise<boolean>;
+    /**
+     * Return the on-chain wallet pair for a registered user, or `null` if not registered.
+     *
+     * Both wallet addresses are fetched in parallel via `getUserWallet(user, 0|1)`.
+     * For unregistered users, call {@link predictWallets} to get the deterministic
+     * addresses they would get after registration.
+     */
+    getWallets(user: Address): Promise<[Address, Address] | null>;
+    /**
+     * Deterministically predict the wallet addresses a user would get after
+     * calling `register()`, even before registration.
+     *
+     * Reads `WALLET_IMPLEMENTATION()` once from chain, then applies the same
+     * `keccak256(abi.encodePacked(user, uint256(0|1)))` salt scheme used in the
+     * contract's `_registerWallets` function.
+     *
+     * Note: `Clones.predictDeterministicAddress(impl, salt)` without an explicit
+     * deployer uses `address(this)` (the singleton) as the deployer — mirrored here.
+     */
+    predictWallets(user: Address): Promise<[Address, Address]>;
+    /**
+     * Return consolidated fee information for a user in a single helper.
+     *
+     * Combines `getFeeAmounts(user)` (per-user resolved fees) and `feeConfig()`
+     * (global toggles) in two parallel RPC calls. UI code calls this to render
+     * the fee panel before the user submits.
+     */
+    getFees(user: Address): Promise<UserFees>;
+    /**
+     * Read the raw per-user fee override stored on-chain, BEFORE the global
+     * toggles are applied. Returns `{ enabled: false, gasFeeWei: 0n,
+     * tokenFeeBps: 0 }` when no override exists for `user`.
+     *
+     * Use this — not {@link getFees} — when you need to distinguish "no
+     * override set" from "override set but globally disabled". The resolved
+     * shape is in {@link getFees}.
+     */
+    getCustomFee(user: Address): Promise<CustomFee>;
+    /**
+     * Return the on-chain global fee configuration.
+     *
+     * Round-trips against {@link setFeeConfig} — pass the result back unchanged
+     * to update one toggle without re-stating the others. Note that ABI outputs
+     * are positional, not named — viem decodes the tuple as an array.
+     */
+    getFeeConfig(): Promise<FeeConfig>;
+    /**
+     * Return batch size limits for all three disperse modes.
+     * `0n` means no limit is configured.
+     */
+    getBatchLimits(): Promise<BatchLimits>;
+    /**
+     * Calculate the fee for a specific disperse call without writing to chain.
+     *
+     * Reads live fee data via `getFeeAmounts(user)` and computes:
+     * - `"wallet"` / `"direct"`: `ethValue = recipients * gasFeeWei`, no token fee.
+     * - `"wallet-token-fee"`: `ethValue = 0n`, `tokenFeeAmount = totalTokens * tokenFeeBps / 10000n`.
+     *
+     * **For `"wallet-token-fee"` mode**, the on-chain fee base is the
+     * post-cap subtotal sum (`subtotal0 + subtotal1`), not `sum(amounts[])`.
+     * The two differ only when the caller has independently constructed subtotals
+     * that don't match `sum(amounts)` — pass `totalTokens === subtotal0 +
+     * subtotal1` for the result to match the on-chain computation. Both this
+     * SDK and the contract round the BPS multiplication down (floor division).
+     *
+     * @throws {TokenOpsSdkError} if mode is `"wallet-token-fee"` and `totalTokens` is not provided.
+     */
+    calculateFee(args: CalculateFeeArgs): Promise<CalculatedFee>;
+    /**
+     * Check whether a user's registered subwallets have approved the singleton
+     * as an ERC-7984 operator for the given token.
+     *
+     * Calls `isOperator(wallet, singleton)` on the token contract for each wallet.
+     * Both wallets must return `true` for wallet-mode disperses to work.
+     *
+     * Note: this requires the user to already be registered. For unregistered
+     * users, call {@link predictWallets} first and check predicted addresses.
+     */
+    hasApprovedSubwallets(args: {
+        user: Address;
+        token: Address;
+    }): Promise<SubwalletApprovalState>;
+    /**
+     * Comprehensive pre-flight report. One call gives a UI everything it needs
+     * to render a "ready to disperse" checklist.
+     *
+     * Internally composes:
+     * - `isRegistered` + `getWallets` / `predictWallets`
+     * - `hasApprovedSubwallets` (wallet modes) or `isOperator(sender, singleton)` (direct mode)
+     * - `calculateFee` / `getBatchLimits`
+     * - Structural recipient + amount validation
+     */
+    preflightDisperse(args: PreflightDisperseArgs): Promise<PreflightReport>;
+    /**
+     * Register the caller's dedicated wallet pair for wallet-mode disperses.
+     *
+     * Deploys two deterministic ERC-1167 wallet clones and approves them for `token`.
+     * Can only be called once per user — subsequent calls revert with `UserAlreadyRegistered`.
+     *
+     * @returns `{ hash, wallets }` — `wallets` is parsed from the `UserRegistered` event.
+     * @throws {DisperseSubwalletNotFoundError} if no `UserRegistered` event matching the singleton is found.
+     */
+    register(args: {
+        token: Address;
+        account?: Account | Address;
+    }): Promise<RegisterResult>;
+    /**
+     * Approve the caller's existing registered wallets as ERC-7984 operators for `token`.
+     *
+     * Required for wallet-mode disperses when using a token different from the one
+     * passed at registration time.
+     */
+    approveTokenOnWallets(args: {
+        token: Address;
+        account?: Account | Address;
+    }): Promise<Hex>;
+    /**
+     * Revoke the operator approval on `token` for the caller's wallets.
+     *
+     * The user can re-approve later via `approveTokenOnWallets`.
+     */
+    revokeTokenOnWallets(args: {
+        token: Address;
+        account?: Account | Address;
+    }): Promise<Hex>;
+    /**
+     * Recover all residual confidential tokens from the caller's wallets to `to`.
+     *
+     * Use after a wallet-mode disperse where the subtotals were inflated and tokens
+     * remain locked in the wallets. Returns the bare tx hash (not a wrapped result
+     * object) — unlike `disperse()`, this method does not surface any additional
+     * receipt-derived data.
+     */
+    recoverFromWallets(args: {
+        token: Address;
+        to: Address;
+        account?: Account | Address;
+    }): Promise<Hex>;
+    /**
+     * Recover ERC-20 tokens accidentally sent to the caller's wallets. Returns the
+     * bare tx hash.
+     */
+    recoverERC20FromWallets(args: {
+        token: Address;
+        to: Address;
+        account?: Account | Address;
+    }): Promise<Hex>;
+    /**
+     * Disperse confidential tokens to multiple recipients.
+     *
+     * SDK responsibilities:
+     * 1. Validates input deterministically (lengths, zero addresses, per-amount
+     *    uint64 bounds, wallet-mode subtotal overflow, batch-limit for the
+     *    selected mode) — using the same {@link validateDisperseInputs} helper
+     *    `preflightDisperse` uses, so an oversized or malformed batch is rejected
+     *    before any FHE encryption time is spent.
+     * 2. For wallet modes: computes group subtotals using the contract's exact split rule.
+     * 3. Encrypts amounts + subtotals in a single batch call (one input proof).
+     * 4. Computes `msg.value` for gas-fee modes; `0` for token-fee mode.
+     * 5. Dispatches to the correct contract function based on `mode`.
+     *
+     * @throws {TokenOpsSdkError} on input validation failure (first deterministic error).
+     * @throws {TokenOpsSdkError} if no encryptor is available at call time.
+     */
+    disperse(args: DisperseArgs): Promise<DisperseResult>;
+    /**
+     * **This is a write transaction, not a free view. It costs gas.**
+     *
+     * Grant the caller persistent FHE ACL on the encrypted token fee reserve and
+     * return the handle. The handle is extracted from the receipt's ACL `Allowed`
+     * event — using `simulateContract` here would return a divergent handle that
+     * breaks user-decrypt downstream (Pitfall #1).
+     *
+     * If no fees have accrued for `token`, the contract does not emit an ACL event
+     * and this method throws {@link DisperseEncryptedReserveNotGrantedError}.
+     * Check `FHE.isInitialized` off-chain: a zero-hash handle means the reserve
+     * is uninitialised.
+     *
+     * Requires FEE_COLLECTOR_ROLE or DEFAULT_ADMIN_ROLE.
+     *
+     * @throws {DisperseEncryptedReserveNotGrantedError} when no ACL event is found
+     *   (i.e., reserve is uninitialised — no fees have accrued).
+     */
+    getEncryptedFeeReserve(args: GetEncryptedFeeReserveArgs): Promise<EncryptedViewResult>;
+    /**
+     * Grant `party` persistent FHE ACL on a single `handle`.
+     *
+     * Caller must already hold ACL on `handle`. FHEVM ACL is append-only — the
+     * grant cannot be revoked.
+     *
+     * @returns `{ hash, discloser, party, disclosedHandles }`. The non-`hash`
+     *   fields are parsed from the `HandlesDisclosedToParty` event when present;
+     *   if the event is absent (anomalous), they fall back to the call's inputs.
+     */
+    discloseHandleToParty(args: DiscloseHandleArgs): Promise<DisclosureResult>;
+    /**
+     * Batch variant — atomically grant `party` persistent ACL on all `handles`.
+     * Reverts on the first handle that fails caller-ACL or contract-ACL checks.
+     */
+    batchDiscloseHandlesToParty(args: BatchDiscloseHandlesArgs): Promise<DisclosureResult>;
+    /**
+     * Pause all disperse operations. Requires PAUSER_ROLE.
+     * @returns Transaction hash.
+     */
+    pause(account?: Account | Address): Promise<TxHash>;
+    /**
+     * Unpause the singleton. Requires PAUSER_ROLE.
+     * @returns Transaction hash.
+     */
+    unpause(account?: Account | Address): Promise<TxHash>;
+    /**
+     * Update the global fee configuration: enable/disable gas and token fees, set defaults.
+     * Requires FEE_MANAGER_ROLE.
+     * @returns Transaction hash.
+     */
+    setFeeConfig(config: FeeConfig, account?: Account | Address): Promise<Hex>;
+    /**
+     * Set a per-user fee override (gas fee in wei, token fee in BPS).
+     * Requires FEE_MANAGER_ROLE.
+     * @returns Transaction hash.
+     */
+    setCustomFee(user: Address, gasFee: bigint, tokenFee: number, account?: Account | Address): Promise<Hex>;
+    /**
+     * Remove a per-user fee override, falling back to the global defaults.
+     * Requires FEE_MANAGER_ROLE. Throws `CustomFeeNotSet` if no override exists.
+     * @returns Transaction hash.
+     */
+    disableCustomFee(user: Address, account?: Account | Address): Promise<Hex>;
+    /**
+     * Set the maximum batch size for `"wallet"` mode disperses. `0n` = no limit.
+     * Requires DEFAULT_ADMIN_ROLE.
+     * @returns Transaction hash.
+     */
+    setMaxBatchSizeHolding(size: bigint, account?: Account | Address): Promise<TxHash>;
+    /**
+     * Set the maximum batch size for `"direct"` mode disperses. `0n` = no limit.
+     * Requires DEFAULT_ADMIN_ROLE.
+     * @returns Transaction hash.
+     */
+    setMaxBatchSizeDirect(size: bigint, account?: Account | Address): Promise<TxHash>;
+    /**
+     * Set the maximum batch size for `"wallet-token-fee"` mode disperses. `0n` = no limit.
+     * Requires DEFAULT_ADMIN_ROLE.
+     * @returns Transaction hash.
+     */
+    setMaxBatchSizeTokenFee(size: bigint, account?: Account | Address): Promise<TxHash>;
+    /**
+     * Withdraw `amount` wei of accumulated ETH gas fees to `to`. The amount is
+     * not capped on-chain — callers MUST pass an explicit amount. There is no
+     * "drain full balance" sentinel: passing `0n` succeeds with no ETH movement.
+     * Read the singleton's ETH balance with `publicClient.getBalance(singleton)`
+     * to drain.
+     *
+     * Requires FEE_COLLECTOR_ROLE.
+     * @returns Transaction hash.
+     */
+    withdrawGasFee(to: Address, amount: bigint, account?: Account | Address): Promise<Hex>;
+    /**
+     * Withdraw accumulated encrypted token fees.
+     *
+     * The amount is encrypted by the caller — pass plaintext `amount` and an
+     * encryptor, or pass `encryptedInput` directly. The contract caps the
+     * withdrawal at the available reserve via `FHE.min`.
+     *
+     * Returns the tx hash plus the **transferred** handle parsed from the
+     * `TokenFeeWithdrawn` event. Decrypt the handle via Zama's `userDecrypt`
+     * to view the actual amount moved (which can be less than requested when
+     * the reserve was smaller than the request). The caller is granted
+     * persistent ACL on this handle by the contract.
+     *
+     * **`encryptedInput` is bound to (this singleton, this caller).** Zama's
+     * KMSVerifier rejects proofs whose `contractAddress` or `userAddress`
+     * don't match the executing tx. If you pre-encrypt on a different chain's
+     * singleton, or for a different caller, the on-chain submission will
+     * revert with a generic verification failure. The plaintext `amount`
+     * path is safer when the caller / chain isn't fixed yet.
+     */
+    withdrawTokenFee(args: {
+        token: Address;
+        to: Address;
+        /** Plaintext amount. Mutually exclusive with `encryptedInput` — supply exactly one. */
+        amount?: bigint;
+        encryptor?: Encryptor;
+        /** Pre-encrypted input. Mutually exclusive with `amount`. */
+        encryptedInput?: EncryptedInput;
+        account?: Account | Address;
+    }): Promise<WithdrawTokenFeeResult>;
+    /**
+     * Rescue accidentally-sent ERC-7984 confidential tokens from the singleton.
+     * Requires WITHDRAWER_ROLE.
+     * @returns Transaction hash.
+     */
+    rescueConfidentialTokens(token: Address, to: Address, account?: Account | Address): Promise<Hex>;
+    /**
+     * Rescue accidentally-sent ERC-20 tokens from the singleton.
+     * Requires WITHDRAWER_ROLE.
+     * @returns Transaction hash.
+     */
+    rescueERC20(token: Address, to: Address, account?: Account | Address): Promise<Hex>;
+    /**
+     * Check whether `address` holds `role` on the singleton.
+     * @example
+     * const isAdmin = await client.hasRole("0x0000...0000", account.address);
+     */
+    hasRole(role: Hex, address: Address): Promise<boolean>;
+    /**
+     * Grant `role` to `accountTarget`. Requires DEFAULT_ADMIN_ROLE.
+     * @returns Transaction hash.
+     */
+    grantRole(role: Hex, accountTarget: Address, account?: Account | Address): Promise<Hex>;
+    /**
+     * Revoke `role` from `accountTarget`. Requires DEFAULT_ADMIN_ROLE.
+     * @returns Transaction hash.
+     */
+    revokeRole(role: Hex, accountTarget: Address, account?: Account | Address): Promise<Hex>;
+    /**
+     * Voluntarily relinquish `role` from the caller. The contract enforces
+     * `callerConfirmation === msg.sender` (OZ AccessControl) as a guard against
+     * accidental renunciation via a wrapper contract — pass the connected
+     * wallet's address here.
+     *
+     * Use to permanently drop privileges from a fee-collector / withdrawer /
+     * pauser without needing an admin's `revokeRole`. Cannot be undone.
+     *
+     * @returns Transaction hash.
+     */
+    renounceRole(role: Hex, callerConfirmation: Address, account?: Account | Address): Promise<Hex>;
+    /** Whether the singleton is currently paused. */
+    paused(): Promise<boolean>;
+    /** Block number at which the singleton was deployed. */
+    deploymentBlockNumber(): Promise<bigint>;
+    /** The ERC-1167 `WALLET_IMPLEMENTATION` address used by `Clones.cloneDeterministic`. */
+    walletImplementation(): Promise<Address>;
+}
+/**
+ * Re-exported from `./subtotals.js` for backwards compatibility with the
+ * public `@tokenops/sdk/fhe-disperse` surface. The canonical implementation
+ * is shared with `./validate.ts`.
+ */
+export { computeSubtotals } from "./subtotals.js";
+/**
+ * Create a {@link ConfidentialDisperseClient}. Mirrors viem's `create*` convention.
+ *
+ * @example
+ * const client = createConfidentialDisperseClient({
+ *   publicClient,
+ *   walletClient,
+ *   address: "0x...",
+ *   encryptor,
+ * });
+ */
+export declare function createConfidentialDisperseClient(config: ConfidentialDisperseClientConfig): ConfidentialDisperseClient;

package/dist/fhe-disperse/subtotals.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Compute the two FHE-encrypted subtotals the singleton expects for
+ * wallet-mode disperses.
+ *
+ * The contract distributes amounts across two subwallets using the rule:
+ *   group0 = first (baseSize + remainder) recipients  →  wallet0
+ *   group1 = remaining baseSize recipients            →  wallet1
+ *
+ * This matches `_distributeFromWallets` in `DisperseConfidential.sol`.
+ */
+export declare function computeSubtotals(amounts: bigint[]): {
+    group0: bigint;
+    group1: bigint;
+};