useRegister, useDisperse and useWithdrawTokenFee accept waitForReceipt, and so do useDiscloseHandleToParty / useBatchDiscloseHandlesToParty. A hook cannot overload on it, so data is the mined result or its Pending*Result: narrow with if (data.pending) return; before reading wallets, distributions, transferredHandle or disclosedHandles.address, chainId and telemetry; the write hooks add encryptor, aclAddress and gasHeadroomPercent, and most write variables accept a per-call gas. Read hooks take query (ReadHookQueryOptions) for staleTime, refetchInterval, select or enabled. Role hooks name the address holder.Every disperse 2.0 method, as a hook.
Filter by lifecycle (where in the flow), TanStack shape (how to wire it), or encryptor dependency. Import path is @tokenops/sdk/fhe-disperse/react.
Setup · deploy · 3
Deploy a factory clone or register with the singleton — the one-time entrypoint.
useRegisterFirst-time setup for a deployer — singleton creates the two ERC-1167 subwallets.
useMutationuseApproveTokenOnWalletsApprove the singleton as an ERC-7984 operator over the caller's registered subwallets for a single token.
useMutationuseRevokeTokenOnWalletsRevoke operator approval on the subwallets (rollback).
useMutation
Configure · 6
Set fees, batch limits, claim windows. Caller is usually the factory or clone owner.
useSetFeeConfigAdmin: update the global fee configuration — enable/disable gas and token fees, set the defaults.
useMutationuseSetCustomFeeAdmin: install a per-user fee override (gas fee in wei, token fee in BPS).
useMutationuseDisableCustomFeeAdmin: remove a per-user fee override, falling back to the global defaults.
useMutationuseSetMaxBatchSizeHoldingAdmin: set the maximum batch size for "wallet" mode disperses.
useMutationuseSetMaxBatchSizeDirectAdmin: set the maximum batch size for "direct" mode disperses.
useMutationuseSetMaxBatchSizeTokenFeeAdmin: set the maximum batch size for "wallet-token-fee" mode disperses.
useMutation
Write · 2
Headline writes — submit a tx through the connected wallet.
Disclose · ACL · 2
Grant ACL on a ciphertext handle to a third party (auditor, tax authority).
Encrypted read · 2
Returns a ciphertext handle. Some are useQuery; some are useMutation (FHE.allow grants ACL inside a tx). Pair with useDecryptedHandle.
useAccessEncryptedFeeReserveMUTATION — submits a transaction (costs gas). Mirrors the on-chain accessEncryptedFeeReserve(token) function: grants the caller persistent decrypt access to the encrypted token fee reserve as an euint64 handle.
useMutation·Reads encrypted handleuseDecryptedHandleSubscribe to a single encrypted handle and reactively decrypt via the connected wallet.
custom·Reads encrypted handle
Read · 9
Plaintext on-chain reads. TanStack Query envelope, cached + refetched.
useIsRegisteredHas this deployer already called register?
useQueryuseGetWalletsRead the deployer's two registered subwallet addresses.
useQueryuseGetFeesRead consolidated fee information for user — combines per-user resolved fees (getFeeAmounts) with the global feeConfig toggles in one read.
useQueryuseGetFeeConfigRead the singleton's { gasFeeEnabled, tokenFeeEnabled, defaultGasFee, defaultTokenFee } fee config.
useQueryuseGetBatchLimitsRead the maximum batch size for each of the three disperse modes ("wallet", "direct", "wallet-token-fee").
useQueryuseCalculateFeeQuote the on-chain fee config for a given disperse batch shape (count + mode).
useQueryuseHasApprovedSubwalletsCheck whether a user's registered subwallets have approved the singleton as an ERC-7984 operator for token.
useQueryusePreflightDisperseDry-run validator — checks operator + balance + paused state before broadcasting.
useQueryuseIsOperatorRead spender's ERC-7984 operator status for holder on token.
useQuery
Roles · RBAC · 3
RBAC — grant, revoke, renounce. Read role constants + membership.
useHasRoleRead AccessControl: is account a member of role on the singleton? All five role constants (DEFAULT_ADMIN_ROLE, FEE_MANAGER_ROLE, FEE_COLLECTOR_ROLE, PAUSER_ROLE, WITHDRAWER_ROLE) are exported from @tokenops/sdk/fhe-disperse/react.
useQueryuseGrantRoleAccessControl: grant role to holder on the singleton.
useMutationuseRevokeRoleAccessControl: revoke role from holder on the singleton.
useMutation
Recovery · 9
Pause / unpause / withdraw / rescue — recover the system or its funds.
useIsPausedRead the singleton's paused flag.
useQueryuseRecoverFromWalletsRecover residual confidential ERC-7984 tokens from the caller's registered wallets to to.
useMutationuseRecoverERC20FromWalletsRecover ERC-20 tokens accidentally sent to the caller's registered wallets.
useMutationusePauseAdmin: pause all disperse operations on the singleton.
useMutationuseUnpauseAdmin: unpause the singleton.
useMutationuseWithdrawGasFeeFee-collector: withdraw amount wei of accumulated ETH gas fees from the singleton to to.
useMutationuseWithdrawTokenFeeFee-collector: withdraw accumulated encrypted token fees.
useMutation·Encrypts inputuseRescueConfidentialTokensSweep stranded confidential tokens out of the singleton contract (admin-only).
useMutationuseRescueERC20Sweep stranded plain ERC-20 tokens (e.g. someone sent the wrong token).
useMutation
Introspection · 3
Deterministic CREATE2 inputs, role bytes, immutable deployment metadata.
usePredictWalletsCompute the deterministic subwallet addresses for a deployer without registering.
useQueryuseDeploymentBlockNumberRead the block number at which the singleton was deployed — useful as the fromBlock argument to getLogs when subscribing to events.
useQueryuseWalletImplementationRead the WALLET_IMPLEMENTATION address — the singleton clones this deterministically (Clones.cloneDeterministic) for each registered user to derive their wallet pair.
useQuery