@tokenops/sdk 1.0.0

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

@@ -0,0 +1,332 @@
+import type { Account, Address, Hex } from "viem";
+import type { EncryptedHandle, TxHash } from "../core/brands.js";
+import { TokenOpsSdkError } from "../core/errors.js";
+import type { EncryptedInput, EncryptedInputs, EncryptedViewResult } from "../fhe/types.js";
+import type { Encryptor } from "./encryption.js";
+export type { EncryptedInput, EncryptedInputs, EncryptedViewResult };
+/**
+ * Disperse mode. Maps to the three `DisperseConfidential` entry points:
+ * - `"wallet"` — per-user wallet pair, gas fee in ETH per recipient.
+ * - `"wallet-token-fee"` — per-user wallet pair, token BPS fee on subtotals.
+ * - `"direct"` — direct `confidentialTransferFrom`, gas fee in ETH per recipient.
+ */
+export type DisperseMode = "wallet" | "wallet-token-fee" | "direct";
+/**
+ * Resolved fee configuration for a given user.
+ * Combines `getFeeAmounts(user)` and `feeConfig()` global toggles.
+ */
+export interface UserFees {
+    /** `true` when the user has a per-user custom fee override. */
+    isCustom: boolean;
+    /** Resolved gas fee per recipient in wei (0 if gas fee is disabled). */
+    gasFeeWei: bigint;
+    /** Resolved token fee in basis points (0 if token fee is disabled). */
+    tokenFeeBps: number;
+    /** Whether gas fees are globally enabled. */
+    gasFeeEnabled: boolean;
+    /** Whether token fees are globally enabled. */
+    tokenFeeEnabled: boolean;
+}
+/**
+ * Global fee configuration (on-chain `feeConfig` struct).
+ *
+ * Field names match the contract ABI exactly so the type round-trips through
+ * `getFeeConfig()` (read) and `setFeeConfig(config)` (write).
+ */
+export interface FeeConfig {
+    gasFeeEnabled: boolean;
+    tokenFeeEnabled: boolean;
+    /** Default gas fee per recipient, in wei. */
+    defaultGasFee: bigint;
+    /** Default token fee in basis points. */
+    defaultTokenFee: number;
+}
+/**
+ * Batch size limits. `0n` means no limit.
+ */
+export interface BatchLimits {
+    /** Max recipients for wallet-mode disperses. `0n` = no limit. */
+    holding: bigint;
+    /** Max recipients for direct-mode disperses. `0n` = no limit. */
+    direct: bigint;
+    /** Max recipients for token-fee wallet-mode disperses. `0n` = no limit. */
+    tokenFee: bigint;
+}
+/**
+ * Calculated fee for a specific disperse call.
+ * - For `"wallet"` and `"direct"` modes: `ethValue` covers the gas fee; `tokenFeeAmount` is `undefined`.
+ * - For `"wallet-token-fee"`: `ethValue` is `0n`; `tokenFeeAmount` is the BPS fee on the subtotals.
+ */
+export interface CalculatedFee {
+    ethValue: bigint;
+    tokenFeeAmount?: bigint | undefined;
+}
+/**
+ * Raw per-user fee override as stored on-chain. Distinct from {@link UserFees}
+ * (which combines this with global toggles into the *resolved* fee).
+ *
+ * Use to surface "this user has an override of 0 BPS that's currently being
+ * masked by `tokenFeeEnabled = false`" in admin UIs.
+ */
+export interface CustomFee {
+    /** `true` when the user has an override set. `false` means no override. */
+    enabled: boolean;
+    /** Override gas fee per recipient, in wei. Only meaningful when `enabled`. */
+    gasFeeWei: bigint;
+    /** Override token fee in basis points. Only meaningful when `enabled`. */
+    tokenFeeBps: number;
+}
+/**
+ * Per-recipient validation result inside a {@link PreflightReport}.
+ */
+export interface RecipientCheck {
+    address: Address;
+    /** `true` when no structural problem was detected for this recipient. */
+    ok: boolean;
+    /** Human-readable description if `ok === false`. */
+    reason?: string | undefined;
+}
+/**
+ * Comprehensive pre-flight report returned by
+ * `ConfidentialDisperseClient.preflightDisperse`.
+ *
+ * One call gives a UI everything it needs to render a "ready to disperse"
+ * checklist. Compose it; do not implement each check inline.
+ */
+export interface PreflightReport {
+    /** Whether the user has already registered via `register(token)`. */
+    isUserRegistered: boolean;
+    /**
+     * On-chain wallet pair for the user. `null` if not registered.
+     * For wallet modes, these wallets must exist before dispersing.
+     */
+    wallets: [Address, Address] | null;
+    /**
+     * Deterministically predicted wallet addresses — present regardless of
+     * registration state.
+     */
+    predictedWallets: [Address, Address];
+    /** Per-wallet approval state for the given token. Only relevant for wallet modes. */
+    hasApprovedSubwallets: {
+        wallet0: boolean;
+        wallet1: boolean;
+        both: boolean;
+    };
+    /**
+     * For `"direct"` mode: whether the sender itself has approved the singleton as operator.
+     * `null` for wallet modes (approval is on the subwallets, not the sender).
+     */
+    hasApprovedSingleton: boolean | null;
+    /** ETH to attach as `msg.value`. */
+    feeEth: bigint;
+    /** Token BPS fee amount. Defined only for `"wallet-token-fee"` mode. */
+    feeTokenAmount?: bigint | undefined;
+    /** Current batch limit for the selected mode. `0n` = no limit. */
+    batchLimit: bigint;
+    /** `true` when `recipients.length <= batchLimit` (or limit is 0). */
+    batchOk: boolean;
+    /** Per-recipient structural checks (zero-address, etc.). */
+    recipientChecks: RecipientCheck[];
+    /** `true` when `amounts.length === recipients.length` and lengths are non-zero. */
+    amountsOk: boolean;
+    /**
+     * Pre-computed group subtotals for wallet modes. Matches the split the SDK
+     * will use inside `disperse()`. `undefined` for `"direct"` mode.
+     */
+    subtotals?: {
+        group0: bigint;
+        group1: bigint;
+    };
+    /** `true` when no blockers are present — green light to call `disperse`. */
+    ready: boolean;
+    /**
+     * Human-readable reasons that prevent dispersing. Empty when `ready === true`.
+     *
+     * @deprecated Use {@link blockerErrors} instead — typed `TokenOpsSdkError`s
+     *   give you `error.code` to branch on. This field stays for backward
+     *   compatibility; it will be removed in the next major.
+     */
+    blockers: string[];
+    /**
+     * Typed errors that would otherwise be thrown at write time. Same shape as
+     * the generic {@link PreflightResult.blockers} contract used by
+     * `preflightClaim` on the vesting and airdrop clients. Empty when
+     * `ready === true`. Branch on `error.code` to render UI.
+     */
+    blockerErrors: TokenOpsSdkError[];
+}
+/**
+ * Approval state of a user's subwallet pair for a specific token.
+ */
+export interface SubwalletApprovalState {
+    wallet0: boolean;
+    wallet1: boolean;
+    both: boolean;
+}
+/** Result of `register()`. */
+export interface RegisterResult {
+    /** Transaction hash. */
+    hash: TxHash;
+    /** The two subwallet addresses parsed from the `UserRegistered` event. */
+    wallets: [Address, Address];
+}
+/**
+ * Per-wallet (wallet modes) or single (direct mode) distribution row, parsed
+ * from a `WalletDistribution` / `DirectDistribution` event in the disperse
+ * receipt.
+ */
+export interface DisperseDistribution {
+    /**
+     * Sub-wallet that funded this distribution, for wallet-mode disperses.
+     * `undefined` for direct mode (sender transfers directly).
+     */
+    wallet?: Address;
+    /** Recipients in this distribution row, in contract emission order. */
+    recipients: Address[];
+    /**
+     * Encrypted `euint64` handles for the per-recipient **requested** amount —
+     * the value the caller passed into `disperse`.
+     */
+    requested: Hex[];
+    /**
+     * Encrypted `euint64` handles for the per-recipient **transferred** amount —
+     * what the ERC-7984 `confidentialTransfer`/`confidentialTransferFrom`
+     * actually moved. Can be less than `requested` when the sender's confidential
+     * balance was insufficient, or zero on a subtotal overflow.
+     */
+    transferred: Hex[];
+}
+/** Result of `disperse()`. */
+export interface DisperseResult {
+    /** Transaction hash. */
+    hash: Hex;
+    /**
+     * Distributions parsed from the receipt. One entry per `WalletDistribution`
+     * (wallet modes — up to two entries) or a single entry per
+     * `DirectDistribution` (direct mode). Empty array if no distribution event
+     * was emitted (which would indicate a contract or parse anomaly).
+     */
+    distributions: DisperseDistribution[];
+}
+/** Result of `withdrawTokenFee()`. */
+export interface WithdrawTokenFeeResult {
+    /** Transaction hash. */
+    hash: Hex;
+    /**
+     * Encrypted `euint64` handle for the **actual** transferred amount, parsed
+     * from the `TokenFeeWithdrawn` event. May be less than the requested
+     * withdrawal when the reserve was lower (the contract caps via `FHE.min`).
+     * Pass to Zama's `userDecrypt` to view the plaintext.
+     *
+     * `undefined` if no `TokenFeeWithdrawn` event was found in the receipt.
+     */
+    transferredHandle?: Hex;
+}
+/** Result of `discloseHandleToParty()` / `batchDiscloseHandlesToParty()`. */
+export interface DisclosureResult {
+    /** Transaction hash. */
+    hash: Hex;
+    /** Caller that initiated the disclosure (from the `HandlesDisclosedToParty` event). */
+    discloser: Address;
+    /** Address that received persistent ACL on the disclosed handles. */
+    party: Address;
+    /** Handles whose ACL was granted to `party`. */
+    disclosedHandles: Hex[];
+}
+/** Arguments for `disperse()`. */
+export interface DisperseArgs {
+    /** ERC-7984 token address. */
+    token: Address;
+    /** Disperse mode. */
+    mode: DisperseMode;
+    /** Array of recipient addresses. Must be non-empty, no zero addresses. */
+    recipients: Address[];
+    /** Plaintext per-recipient amounts in raw token units. SDK encrypts these. */
+    amounts: bigint[];
+    /** Override the ETH value — skips live fee read for gas/direct modes. */
+    gasFeeOverride?: bigint | undefined;
+    /** Override signer account. Falls back to `walletClient.account`. */
+    account?: Account | Address | undefined;
+}
+/** Arguments for `getEncryptedFeeReserve()`. */
+export interface GetEncryptedFeeReserveArgs {
+    /** ERC-7984 token to query the fee reserve for. */
+    token: Address;
+    /** Override signer account. Falls back to `walletClient.account`. */
+    account?: Account | Address | undefined;
+}
+/** Arguments for `discloseHandleToParty()`. */
+export interface DiscloseHandleArgs {
+    /** The `euint64` handle to re-share. */
+    handle: EncryptedHandle;
+    /** The address receiving persistent decrypt access. */
+    party: Address;
+    account?: Account | Address | undefined;
+}
+/** Arguments for `batchDiscloseHandlesToParty()`. */
+export interface BatchDiscloseHandlesArgs {
+    /** The `euint64` handles to re-share. */
+    handles: EncryptedHandle[];
+    /** The address receiving persistent decrypt access. */
+    party: Address;
+    account?: Account | Address | undefined;
+}
+/** Common fields for {@link WithdrawTokenFeeArgs} — discriminated below. */
+interface WithdrawTokenFeeArgsCommon {
+    token: Address;
+    to: Address;
+    account?: Account | Address | undefined;
+}
+/**
+ * Discriminated union: provide EITHER an encryptor (the SDK encrypts `amount`)
+ * OR a pre-built `encryptedInput`. Passing both is a compile error.
+ */
+export type WithdrawTokenFeeArgs = (WithdrawTokenFeeArgsCommon & {
+    amount: bigint;
+    encryptor?: Encryptor | undefined;
+    encryptedInput?: never;
+}) | (WithdrawTokenFeeArgsCommon & {
+    encryptedInput: EncryptedInput;
+    amount?: never;
+    encryptor?: never;
+});
+/** Arguments for `preflightDisperse()`. */
+export interface PreflightDisperseArgs {
+    user: Address;
+    token: Address;
+    recipients: Address[];
+    amounts: bigint[];
+    mode: DisperseMode;
+}
+/** Arguments for `calculateFee()`. */
+export interface CalculateFeeArgs {
+    user: Address;
+    mode: DisperseMode;
+    recipients: number;
+    /** Required for `"wallet-token-fee"` to compute the token fee. */
+    totalTokens?: bigint | undefined;
+}
+/**
+ * Thrown by `register()` when no `UserRegistered` event matching the
+ * singleton address is found in the transaction receipt.
+ */
+export declare class DisperseSubwalletNotFoundError extends TokenOpsSdkError {
+    name: string;
+    readonly context: {
+        txHash: Hex;
+        singletonAddress: Address;
+    };
+    constructor(txHash: Hex, singletonAddress: Address);
+}
+/**
+ * Thrown by `getEncryptedFeeReserve()` when no ACL `Allowed` event granting
+ * the caller access to the fee reserve handle is found in the receipt.
+ */
+export declare class DisperseEncryptedReserveNotGrantedError extends TokenOpsSdkError {
+    name: string;
+    readonly context: {
+        txHash: Hex;
+        callerAddress: Address;
+    };
+    constructor(txHash: Hex, callerAddress: Address);
+}

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

@@ -0,0 +1,78 @@
+/**
+ * Shared deterministic validation for `disperse` / `preflightDisperse`.
+ *
+ * The same input rules (length match, non-zero recipients, uint64 bounds per
+ * amount, wallet-mode subtotal overflow, batch-limit) must apply in two
+ * places:
+ * - `preflightDisperse()` — reports them as blockers in the UI report.
+ * - `disperse()` — throws them before encryption, so an oversized or
+ *   malformed batch does not spend client-side FHE encryption time and then
+ *   revert on-chain.
+ *
+ * This module is the single source of truth. It is **synchronous + pure** —
+ * no chain calls, no contract reads. Callers fetch `batchLimits` once and
+ * pass the relevant limit in.
+ */
+import type { Address } from "viem";
+import type { TokenOpsSdkError } from "../core/errors.js";
+import type { DisperseMode } from "./types.js";
+export interface ValidateDisperseInputsArgs {
+    recipients: ReadonlyArray<Address>;
+    amounts: ReadonlyArray<bigint>;
+    mode: DisperseMode;
+    /**
+     * The relevant batch limit for `mode`, fetched via `getBatchLimits()`. A
+     * value of `0n` means "unlimited" (matches the contract's encoding).
+     */
+    batchLimit: bigint;
+    /**
+     * Method name used in produced error contexts — `"disperse"` for the write
+     * path, `"preflightDisperse"` for the report path. The downstream `code`
+     * is the same; this just sharpens the message.
+     */
+    method: "disperse" | "preflightDisperse";
+    /** Contract address for `BatchTooLargeError.contractAddress`. */
+    contractAddress: Address;
+}
+/**
+ * Deterministic input checks that must hold for any `disperse` call. Returns
+ * the typed errors that would block submission. Empty array == valid.
+ *
+ * Checks performed:
+ * 1. `recipients` non-empty.
+ * 2. `amounts.length === recipients.length`.
+ * 3. No zero address in `recipients`.
+ * 4. Each amount fits in `uint64` (0..2^64-1).
+ * 5. Wallet-mode group subtotals fit in `uint64` (the contract splits amounts
+ *    across two FHE-encrypted subwallets — each subtotal is an `euint64`).
+ * 6. Batch size ≤ `batchLimit` (when `batchLimit > 0`).
+ */
+export declare function validateDisperseInputs(args: ValidateDisperseInputsArgs): TokenOpsSdkError[];
+/**
+ * Reject any `Address` argument that is not a strict EIP-55 checksum.
+ *
+ * viem's `isAddress(addr, { strict: true })` accepts all-lowercase (treats it
+ * as "no checksum claim"). The actual failure mode this guards against is
+ * **mixed-case** addresses whose case does not match the EIP-55 checksum —
+ * those typically come from copy-paste typos and should be surfaced as a
+ * typed `InvalidArgumentError` instead of leaking through as a raw viem
+ * `InvalidAddressError` from inside `writeContract`.
+ *
+ * No-op for `undefined` so optional address args can be passed through.
+ */
+export declare function assertChecksumAddress(value: Address | undefined, argument: string, method: string): void;
+/**
+ * Stricter variant of {@link assertChecksumAddress} that also rejects the
+ * zero address. Use for write-method recipient/`to` args where the contract
+ * already reverts on zero with `Errors.InvalidAddress` — failing client-side
+ * saves the gas round-trip and surfaces the same typed error.
+ */
+export declare function assertNonZeroChecksumAddress(value: Address | undefined, argument: string, method: string): void;
+/**
+ * Select the relevant batch limit for `mode` from a `BatchLimits` reading.
+ */
+export declare function batchLimitForMode(mode: DisperseMode, limits: {
+    direct: bigint;
+    holding: bigint;
+    tokenFee: bigint;
+}): bigint;