if (data.pending) return; before reading a receipt-derived field. The receipt-free create surface is beta; see Receipt-free writes.gasHeadroomPercent, and mutation variables that are an object take a per-call gas (Gas headroom). The ECDSA instance hooks take no dedupMode; read the policy with useDedupMode. Read hooks accept query (TanStack options minus queryKey / queryFn), and a function-form query.enabled is honoured; it can turn a ready query off, never an unready one on (query options). On a chain the SDK does not support, the instance hooks no longer throw from render: read hooks stay disabled and mutations reject with the client's UnsupportedChainError. TokenOpsContractError and TokenOpsValidationError are re-exported from @tokenops/sdk/fhe-airdrop/react for instanceof checks./fhe-vesting, the write hooks here invalidate the reads they affect on success, scoped to that instance and function. After a headless client write, invalidate yourself with the exported key builders: queryClient.invalidateQueries({ queryKey: airdropQueryKeyPrefix({ chainId, address, fn: "merkleRoot" }) }). airdropQueryKey builds the full key, args included.Every airdrop v2 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-airdrop/react.
Setup · deploy · 4
Deploy a factory clone or register with the singleton — the one-time entrypoint.
useCreateEcdsaAirdropDeploy an ECDSA-authorised airdrop instance via the factory.
useMutationuseCreateMerkleAirdropDeploy a Merkle-proof airdrop instance via the factory.
useMutationuseCreateAndFundEcdsaAirdropDeploy an ECDSA-authorised airdrop instance and seed its pool in one transaction.
useMutation·Encrypts inputuseCreateAndFundMerkleAirdropDeploy a Merkle-proof airdrop instance and seed its pool in one transaction.
useMutation·Encrypts input
Configure · 13
Set fees, batch limits, claim windows. Caller is usually the factory or clone owner.
useSetMerkleRootRotate the published root on a MerkleConfidentialAirdrop instance.
useMutationuseExtendClaimWindowAdmin extends the claim deadline.
useMutationuseDisableCustomFeeDrop a creator's per-creator fee override, reverting them to the factory's defaultGasFee.
useMutationuseSetComplianceDelegateSet the platform-designated compliance delegate that every new compliance-manager clone wires in.
useMutationuseSetComplianceManagerImplPoint future compliance-manager clones at a new implementation.
useMutationuseSetCompliancePolicyOverride the factory's default delegate-to-compliance policy for one creator.
useMutationuseSetCustomFeeOverride the factory's default per-claim gas fee for one creator.
useMutationuseSetDefaultDelegateToComplianceSet the factory-wide default for whether new instances delegate compliance disclosure to the platform delegate.
useMutationuseSetDefaultGasFeeSet the per-claim gas fee that new instances default to when their creator has no setCustomFee override.
useMutationuseSetMaxGasFeeSet the factory's ceiling on every fee setDefaultGasFee / setCustomFee may configure, and on the fee resolved at create.
useMutationuseSetDefaultUpgradeableSet the factory-wide default for whether a create* may deploy mode: "uups".
useMutationuseSetFeeCollectorSet the account seeded with FEE_COLLECTOR_ROLE on instances the factory creates after this call.
useMutationuseSetUpgradeabilityPolicyOverride the factory's default upgradeability policy for one creator.
useMutation
Write · 16
Headline writes — submit a tx through the connected wallet.
useFundAirdropTop up an already-deployed instance's pool through the factory.
useMutation·Encrypts inputuseEcdsaClaimClaim a signed encrypted allocation on an ECDSAConfidentialAirdrop instance.
useMutationuseMerkleClaimClaim the outstanding amount for a proof-bearing entry on a MerkleConfidentialAirdrop instance.
useMutationuseGrantInstanceRolesSplit an airdrop instance's roles after create — one grantRole / revokeRole transaction per requested assignment, submitted in the order planInstanceRoleSplit computes.
useMutationuseAddComplianceDelegateGrant delegate permanent user-decryption delegation over this compliance clone's airdrop.
useMutationuseAirdropUpgradeToAndCallPoint an airdrop instance's ERC-1967 proxy at a new implementation, optionally calling into it in the same transaction.
useMutationuseBuildMerkleCampaignEncrypt a roster and build the Merkle tree those ciphertexts belong to, for an instance that already exists — the mutable-root path.
useMutation·Encrypts inputuseEcdsaClaimAndUnwrapClaim a signed encrypted allocation and route it straight into the wrapper's unwrap, making to the underlying ERC-20 beneficiary.
useMutationuseEncryptCampaignAmountsEncrypt a plaintext roster into per-recipient handles, without building a tree.
useMutation·Encrypts inputuseMerkleClaimAndUnwrapClaim a proof-bearing Merkle entry and route the allocation straight into the wrapper's unwrap, making to the underlying ERC-20 beneficiary.
useMutationusePlanMerkleCampaignBuild a campaign for a Merkle instance that does not exist yet, so its root can be baked in at create time — the immutable-root path.
useMutation·Encrypts inputuseRevokeComplianceDelegateRevoke a client delegate's user-decryption delegation.
useMutationuseRotateMerkleRootRebuild a campaign against updated totals and publish the new root in one call.
useMutation·Encrypts inputuseClearCompliancePolicyDrop a creator's useSetCompliancePolicy override, reverting them to the factory default.
useMutationuseClearUpgradeabilityPolicyDrop a creator's useSetUpgradeabilityPolicy override, reverting them to the factory default.
useMutationuseEnsureOperatorEnsure spender is an ERC-7984 operator for the connected account on token, sending a setOperator transaction only when the grant is missing.
useMutation
Disclose · ACL · 1
Grant ACL on a ciphertext handle to a third party (auditor, tax authority).
Encrypted read · 8
Returns a ciphertext handle. Some are useQuery; some are useMutation (FHE.allow grants ACL inside a tx). Pair with useDecryptedHandle.
useDiscloseHandleToPartyGrant ACL on a single ciphertext handle to a third party (e.g. an auditor).
useMutation·Reads encrypted handleuseAdminBatchDiscloseBalanceToPartiesSubmits a transaction. Discloses the instance's confidential pool balance to several parties at once.
useMutation·Reads encrypted handleuseAdminDiscloseBalanceToPartySubmits a transaction. Discloses the instance's confidential pool balance to party.
useMutation·Reads encrypted handleuseAdminGetCurrentBalanceSubmits a transaction. Reads the instance's remaining confidential pool balance as an euint64 handle the caller may decrypt - pass data.handle to the Zama relayer's userDecrypt.
useMutation·Reads encrypted handleuseRefreshComplianceBalanceSubmits a transaction. Re-grants the compliance-manager clone on the instance's current pool balance and returns the handle it was granted on.
useMutation·Reads encrypted handleuseAccessEcdsaClaimAmountSubmits a transaction. Previews a signed encrypted allocation as an encrypted handle.
useMutation·Reads encrypted handleuseAccessMerkleClaimAmountSubmits a transaction. Previews the outstanding amount for a proof-bearing Merkle entry as an encrypted handle.
useMutation·Reads encrypted handleuseDecryptedHandleSubscribe to a single encrypted handle and reactively decrypt via the connected wallet.
custom·Reads encrypted handle
Read · 35
Plaintext on-chain reads. TanStack Query envelope, cached + refetched.
useAirdropTokenRead the ERC-7984 token an airdrop instance distributes.
useQueryuseAirdropWindowRead an airdrop instance's claim-window snapshot in one round trip.
useQueryuseAirdropGasFeeRead the per-claim ETH fee (wei) an instance charges; 0n on a fee-free campaign.
useQueryuseMerkleRootRead a MerkleConfidentialAirdrop instance's currently published root.
useQueryuseClaimedAmountRead account's cumulative delivered total on a MerkleConfidentialAirdrop instance, as an encrypted handle — pass it to the Zama relayer's userDecrypt to see the plaintext.
useQueryuseComplianceManagerRead an airdrop instance's own compliance-manager clone — the only contract the instance itself grants persistent ACL on its pool and claim handles.
useQueryuseFactoryFeesRead the airdrop factory's chain-wide fee configuration: feeCollector, defaultGasFee and maxGasFee in one round trip.
useQueryuseResolveGasFeeThe per-claim fee a create* from creator would freeze into the new instance right now: their setCustomFee override when enabled, else the factory default.
useQueryuseFactoryRegistryPage through every instance the factory has deployed, plus the total count — the two reads a "list my campaigns" admin view needs together.
useQueryuseIsAirdropAsk the canonical factory whether it created candidate - the genuineness check.
useQueryuseEffectiveUpgradeableWhether creator's NEXT create* may deploy mode: "uups" — the factory default, overridden per-creator via setUpgradeabilityPolicy.
useQueryuseAirdropConfigRead an airdrop instance's immutable configuration in one round trip.
useQueryuseAirdropDeploymentModeRead which deployment shell an airdrop instance is: a minimal-proxy "clone", or a "uups" ERC-1967 proxy that useAirdropUpgradeToAndCall can actually move.
useQueryuseAirdropRoleAdminWhich role's holders may grant and revoke role on an airdrop instance.
useQueryuseAirdropRoleMembersList who holds role on an airdrop instance, with the member count.
useQueryuseComplianceInfoRead a compliance-manager clone's whole wiring in one round trip - the airdrop it serves, its platform delegate, and its client-delegate set.
useQueryuseComplianceManagerOfResolve the ComplianceRoleManager clone bound to an airdrop instance, by asking the factory.
useQueryuseComplianceRoleMembersList who holds role on a compliance-manager clone, with the member count.
useQueryuseDedupModeRead an ECDSA airdrop instance's replay-protection policy from the chain.
useQueryuseEcdsaDomainRead an ECDSA instance's CLAIM_TYPEHASH, domain separator and ERC-5267 domain in one round trip - the three deployment-verification reads nobody wants one at a time (same call as useAirdropWindow).
useQueryuseEffectiveDelegateToComplianceWhether creator's NEXT create* will wire the platform compliance delegate into the instance's compliance-manager clone - their setCompliancePolicy override when they have one, else the factory default.
useQueryuseIsActiveDelegateWhether delegate currently holds user-decryption delegation over this compliance-manager clone's airdrop.
useQueryuseIsMerkleRootMutableWhether this MerkleConfidentialAirdrop instance permits root rotation at all.
useQueryuseIsSignatureValidWhether an ECDSA claim authorization would be accepted right now for recipient, without spending an FHE op or a transaction.
useQueryusePreflightClaimReport what would stop a claim right now - chain support, the pause flag, both ends of the claim window, whether claimant can cover the exact-equality gas fee, the Merkle argument-relation rules when account/entrypoint are given, and for an ECDSA campaign given signature, whether the authorisation is valid and unconsumed.
useQueryusePreflightCreateAirdropRead-only preflight for useCreateEcdsaAirdrop / useCreateMerkleAirdrop.
useQueryuseTokenOfResolve the token the factory recorded for an airdrop instance at create - what fundAirdrop pulls, regardless of what the instance reports today.
useQueryuseUnwrapRequestThe unwrap request a claimAndUnwrap started: waits for hash to be mined and decodes the instance's ClaimedAndUnwrapInitiated event.
useQueryuseFactoryComplianceDelegateThe platform-designated compliance delegate the FACTORY wires into every new compliance-manager clone.
useQueryuseFactoryCompliancePolicyThe admin's per-creator compliance view: the stored override AND the value the factory resolves for that creator.
useQueryuseFactoryCustomFeeRead one creator's per-claim fee override.
useQueryuseFactoryImplementationsRead all three of the factory's implementation pointers in one round trip - the row an admin panel shows together, so they are bundled rather than shipped as three one-line hooks over three parallel eth_calls.
useQueryuseFactoryRoleMembersList who holds role on the factory, with the member count.
useQueryuseFactoryUpgradeabilityPolicyThe admin panel's full upgradeability answer for one creator, in one round trip: the factory default, the per-creator override, and the resolved value.
useQueryuseIsOperatorRead spender's ERC-7984 operator status for holder on token.
useQuery
Roles · RBAC · 12
RBAC — grant, revoke, renounce. Read role constants + membership.
useAirdropHasRoleWhether holder holds role on an airdrop instance.
useQueryuseComplianceHasRoleWhether holder holds role on a compliance-manager clone.
useQueryuseAirdropGrantRoleGrant one role on one airdrop instance.
useMutationuseAirdropRenounceRoleGive up a role on an airdrop instance yourself.
useMutationuseAirdropRevokeRoleRevoke one role from one holder on one airdrop instance.
useMutationuseComplianceGrantRoleGrant one role on a compliance-manager clone.
useMutationuseComplianceRenounceRoleGive up a role on a compliance-manager clone yourself.
useMutationuseComplianceRevokeRoleRevoke one role from one holder on a compliance-manager clone.
useMutationuseFactoryGrantRoleGrant one factory role.
useMutationuseFactoryHasRoleWhether holder holds role on the factory.
useQueryuseFactoryRenounceRoleGive up a factory role yourself.
useMutationuseFactoryRevokeRoleRevoke one factory role from one holder.
useMutation
Recovery · 7
Pause / unpause / withdraw / rescue — recover the system or its funds.
useAirdropPausedWhether claiming is currently halted (PausableUpgradeable.paused()).
useQueryuseAirdropPauseSet an airdrop instance's pause flag.
useMutationuseWithdrawConfidentialSweep an airdrop instance's entire remaining confidential balance to recipient.
useMutationuseRescueNativeTokenSweep ETH stranded on a zero-fee airdrop instance (a forced send, or a transfer to the predicted address before deploy) to recipient.
useMutationuseRescueERC20Sweep stranded plain ERC-20 tokens (e.g. someone sent the wrong token).
useMutationuseRescueOtherConfidentialTokenSweep a different ERC-7984 token that was sent to an airdrop instance by mistake.
useMutationuseWithdrawGasFeeWithdraw an airdrop instance's accrued per-claim fee ETH to recipient.
useMutation
Signature helper · 1
Off-chain EIP-712 signing helper — no chain interaction.
Introspection · 9
Deterministic CREATE2 inputs, role bytes, immutable deployment metadata.
useAirdropRoleConstantsRead an airdrop instance's role identifiers in one fan-out.
useQueryuseComplianceRoleConstantsRead a compliance-manager clone's role identifiers.
useQueryusePredictEcdsaAirdropAddressWhere an ECDSA create* from deployer with this (mode, userSalt) pair would land.
useQueryusePredictMerkleAirdropAddressWhere a Merkle create* from deployer with this (mode, userSalt) pair would land.
useQueryuseEcdsaInitCodeHashInit-code hash of the ECDSA proxy the factory would deploy for mode.
useQueryuseFactoryRoleConstantsRead the factory's role identifiers in one fan-out.
useQueryuseMerkleInitCodeHashInit-code hash of the Merkle proxy the factory would deploy for mode - the Merkle counterpart of useEcdsaInitCodeHash, with the same before/after bracketing job and the same /advanced/react home.
useQueryuseSetEcdsaImplementationPoint future createEcdsaAirdrop* calls at a new ECDSA implementation.
useMutationuseSetMerkleImplementationPoint future createMerkleAirdrop* calls at a new Merkle implementation.
useMutation