Airdrop v2 type surface.

Fields shared by both variants at create time. Deliberately has no admin field - the factory sets admin = msg.sender; split roles afterward with grantInstanceRoles. maxAcceptedGasFee is required and has no default: the per-claim fee is frozen into the instance for its lifetime and the value that resolves is the factory fee manager's choice, so a default would hand that decision back to whoever is not making it. Pass 0n to accept only a zero-fee campaign, or UINT96_MAX to accept whatever resolves. complianceAdmin (zero means the creator) is both the compliance clone's admin and its first client delegate, with never-expiring decrypt rights over the instance from create.

createEcdsaAirdrop input. signer is the address that will hold SIGNER_ROLE; dedupMode is frozen at init. Read it back with readDedupMode() / useDedupMode.

createMerkleAirdrop input. A zero merkleRoot is only valid when isMerkleRootMutable is true.

ECDSA replay-protection dimension, mirrors the DEDUP_MODE const object. Fixed at createEcdsaAirdrop time; readDedupMode() decodes the on-chain dedupMode() getter, and throws TOKENOPS_UNEXPECTED_CONTRACT_RESPONSE for an ordinal this SDK does not know.

Instance shell: an EIP-1167 clone (cheap, non-upgradeable) or a UUPS proxy (upgradeable, factory-gated). Merkle refuses uups outright.

Generic over EcdsaAirdropParams / MerkleAirdropParams. userSalt is combined with the deployer address to derive the CREATE2 salt. expected pins any create commitment instead of quoting it fresh at send time.

The Merkle creates. A plan pins expected.airdrop to plan.predictedAddress, requires params.merkleRoot to equal plan.root, and refuses the send once the Merkle implementation has moved.

What every create commits to. The factory reverts before consuming the salt when any of them drifted; the SDK quotes all three at send time unless pinned.

Input to factory.quoteCreateCommitments - ties the variant to its params type.

Factory deploy output. The compliance fields are read from the create receipt's ComplianceManagerCloned log, not a follow-up registry call.

What a create returns with waitForReceipt: false (Safe signers). Every address is still set, built from the commitments, because the factory reverts unless it deploys exactly there.

Mixed into each receipt-free-capable write as Args & ReceiptMode. The literal false selects the Pending overload; omitting it keeps the mined result type.

The shared discriminant on every receipt-free result. if (result.pending) narrows the same way in all three products.

Discriminated union guarded with never - supply exactly one of a plaintext amount (SDK encrypts) or a pre-encrypted input.

Mixed into nearly every write-method args type. Overrides the client's default signer for that one call, and carries the per-call gas.

Accepted by every client config and hook. Percent added on top of each write's gas estimate; defaults to DEFAULT_GAS_HEADROOM_PERCENT, 0 sends the bare estimate, and the padded limit is clamped to MAX_TRANSACTION_GAS (the EIP-7825 cap, exported from the root).

Per-call gas limit sent as is, skipping the estimate and headroom. A wallet or Safe that sets its own limit may ignore it.

EcdsaAirdropClient.claim / claimAndUnwrap input. The gas fee is attached automatically; no value field to set by hand.

Preview an ECDSA claim amount. Aliased at the package root from the shared GetClaimAmountArgs name - does not consume replay state.

Gas-free ECDSA claim validity preview. Simulated as an eth_call from recipient, so the wrong recipient always returns false.

MerkleAirdropClient.claim input. entry.account is the claim identity and is paid unless it submits itself and sets a different to; anyone may submit. account? is the sending-account override, not the claim identity - never pass the recipient there on a relayed claim.

Preview a Merkle claim amount. Grants the ACL handle to entry.account, not the caller - a relayer previewing learns nothing itself. account? is the sending-account override, not the claim identity.

Decoded ClaimedAndUnwrapInitiated event. Pass unwrapRequestId to the wrapper's finalizeUnwrap to release the underlying ERC-20.

What parseUnwrapRequest reads. Only this instance's event counts; two in one transaction throw ReceiptEventAmbiguousError.

Everything merkle.claim needs for one recipient. account is the claim identity; the input is bound to the instance, so any address may submit it.

Factory client constructor. address falls back to DEPLOYED_ADDRESSES on mainnet and Sepolia. encryptor is the default for fund-methods when passing a plaintext amount.

Shared constructor shape for both claim variants - address is the deployed instance, clone or UUPS proxy.

An alias: the ECDSA client takes no variant-specific config. The replay policy is read from the chain with readDedupMode().

address is the ComplianceRoleManager clone, not the airdrop instance. Read it back with complianceManagerOf(airdrop).

Output of buildMerkleCampaign - a published root plus every recipient's CampaignEntry.

Input roster row. cumulativeTotal is the recipient's running lifetime allocation, never a per-drop tranche.

Mutable-root path - the instance already exists, encrypt + build the tree against its real address.

Immutable-root path - predicts the CREATE2 address first, then encrypts and builds against that predicted address.

planMerkleCampaign's output. Two init-code-hash reads bracket the build to catch a mid-flight implementation swap. Pass it as plan to the Merkle create.

Rebuilds a live campaign's full tree and calls setMerkleRoot in one step. Root is published last, so a failed rebuild never touches the live campaign.

rotateMerkleRoot's output - the new tree plus the setMerkleRoot transaction hash.

Minimum shape buildMerkleTree needs - the tree only commits (instance, account, handle). Extra fields ride through onto the entry.

Input to leafOf - computes keccak256(keccak256(abi.encode(instance, account, handle))), byte-for-byte matching the contract's _leafOf.

Input to buildMerkleTree. Pure - no relayer, no chain access. Generic over anything wider than MerkleLeafInput, so a caller's own fields ride along onto the entry.

buildMerkleTree's output - the root to publish, plus every leaf with its Merkle proof attached, in input order.

Input to encryptCampaignAmounts - encrypts a roster against (instance, instance), 32 values per proof (MERKLE_BATCH_LIMIT), without building a tree. Mutable-root path only: instance must already be deployed.

encryptCampaignAmounts' per-recipient output - everything buildMerkleTree needs for one leaf, plus the input proof the tree itself doesn't touch.

Input to factory.predictEcdsaAirdropAddress / predictMerkleAirdropAddress. Only mode, deployer, and userSalt affect the CREATE2 address - params travels along generically but isn't part of the salt.

Input to getEcdsaInitCodeHash / getMerkleInitCodeHash - narrower than PredictArgs on purpose: the hash covers only the proxy init-code, so deployer and userSalt can't affect it.

Input to setOperator (@tokenops/sdk/fhe) - authorizes spender (the airdrop factory - funding always routes through it) to pull the caller's ERC-7984 tokens until deadline. Required before fundAirdrop / createAndFund*.

Input to revokeOperator - identical to SetOperatorArgs minus deadline; calls setOperator(spender, 0), the ERC-7984 revoke convention, for a stale or replaced clone.

Target holders for planInstanceRoleSplit / grantInstanceRoles - instances are create-then-grant, never atomic.

One ordered step in a role-split plan. holder is the grantee (account means the sender everywhere else in the module). An admin reassignment always emits grant-then-revoke, in that order; planInstanceRoleSplit refuses assignment.admin equal to the caller with InvalidArgumentError - omit admin to keep it.

Per-step result from grantInstanceRoles - exactly one of hash or error is set. Never collapsed into a single status.

One grantRole / revokeRole call from encodeInstanceRoleSplit, in plan order - what a Safe submits as one MultiSend batch.

The bytes32 role constants encodeInstanceRoleSplit encodes, keyed by role name. Read them from the instance once.

The 9-member union planInstanceRoleSplit accepts. FEE_COLLECTOR_ROLE is deliberately excluded - it is self-administered, not grantable from an admin role.

Per-creator override state on the factory. overridden distinguishes an explicit choice from unset-use-the-default.

Same override-over-default shape, gating whether a creator may pass mode: "uups" at all.

Per-creator gas-fee override read from the factory. Moved here from a shared types module in v1 - same shape, now declared in factory.ts.

Input to the free function preflightCreate. plan is Merkle-only. A pinned expected field that differs from the fresh quote is a CreateCommitmentMismatchError blocker.

What preflightCreate returns. commitments is exactly what the create would be sent with.

Input to preflightClaim. Takes a structural ClaimPreflightTarget rather than a concrete client class to avoid an import cycle. Supplying factory turns on the genuineness check. Blockers carry the entrypoint they would stop (default "claim") as method, and a claimant whose ETH is below the gas fee is an InsufficientBalanceError (balanceKind: "eth"), not an InsufficientFeeError.

The slice of ConfidentialAirdropFactoryClient the genuineness check reads. chainId is checked against the instance's own chain before the registry is consulted - a registry answer from the wrong chain is worse than no answer, because it reads as a clean true.

Generic cross-product report re-exported from core. Replaces the bespoke CreateAirdropPreflightReport v1 used to return.

Satisfied by AirdropBaseClient, EcdsaAirdropClient, or MerkleAirdropClient - whatever preflightClaim is checking against.

The signature fields preflightClaim needs to run isSignatureValid as part of an ECDSA claim preview.

Input to assertPredictionFresh - a pure comparison of two init-code-hash reads bracketing a prediction's use. Mismatch means an implementation rotation landed mid-flight.

Input to assertSaltAvailable - one eth_getCode check on the predicted address before create; non-empty code throws SaltCollisionError.

Mirrors ZamaSDK.encrypt, so a ZamaSDK, createSepoliaEncryptor (@tokenops/sdk/fhe) or createSepoliaEncryptorWeb (@tokenops/sdk/fhe/web) result is assignable without a cast. resolveEncryptor unwraps an EncryptorSource into one.

Eager-or-lazy encryptor input accepted by client configs and campaign-building functions.

One euint64 in, one { handle, inputProof } out, bound to the (contractAddress, userAddress) pair.

Input to encryptUint64Batch - N euint64 values encrypted under one shared KMS input proof instead of N independent ones.

Discriminated FHE input mirroring upstream EncryptInput: the euint8 to euint256 types take a bigint, ebool takes boolean | 1n | 0n, eaddress takes an Address.

One euint64 ciphertext + its KMS input proof - encryptUint64's return shape, and FundInput's encryptedInput branch.

N ciphertexts sharing one input proof - encryptUint64Batch's return shape. handles[i] corresponds to the i-th plaintext value passed in.

eip712Domain()'s return shape on EcdsaAirdropClient - fields, name, version, chainId, verifyingContract, salt, extensions.

Returned by every disclosure/claim-amount method. Decrypt handle with ZamaSDK decryption.decryptValues, or useDecryptedHandle in React.

Labels which claim variant a prediction guard or preflight result is evaluating.

Every /fhe-airdrop/react mutation names its variables <Action>Args, or <Action>Variables where the headless subpath already exports <Action>Args. The old Use* names are gone; see the from-alpha migration for the rename table.

Variables of useCreateEcdsaAirdrop / useCreateMerkleAirdrop. waitForReceipt is accepted, so data resolves CreateAirdropResult | PendingCreateAirdropResult - narrow with if (data.pending) return; before reading receipt-derived fields.

Variables of the two createAndFund hooks, same Mined | Pending result.

Variables of the four campaign-tooling hooks. Named Variables because the headless subpath exports BuildMerkleCampaignArgs and the rest.

Variables of the four disclosure hooks, without the former Use prefix.

Named variable types for hooks that typed them inline before. Each accepts a per-call gas.

Variables of useSignClaimAuthorization; the hook supplies airdrop and chainId from its options. No gas field: signing sends no transaction.

DeploymentAddressUnavailableError.context.reason's three values - branch UI copy on which one fired rather than parsing the message.

The stable string-literal union every TokenOpsSdkError.code takes. Match on error.code in onError handlers - messages may evolve between SDK versions, codes don't.