fhe-airdrop

Classes

ConfidentialAirdropClient

Typed wrapper around a deployed ConfidentialAirdropCloneable clone.

The admin issues claims by encrypting the allocation bound to the recipient address (Zama input proofs are bound to (contractAddress, userAddress) — the contract's FHE.fromExternal will reject any other binding) and signing the handle. The recipient calls ConfidentialAirdropClient.claim with exactly that { encryptedInput, signature } pair; the SDK never re-encrypts on the recipient side because the signature commits to a specific handle.

Example

const airdrop = createConfidentialAirdropClient({
  publicClient, walletClient,
  address: airdropAddress,
});
await airdrop.claim({ encryptedInput, signature });

Constructors

Constructor

new ConfidentialAirdropClient(config): ConfidentialAirdropClient;

Defined in: fhe-airdrop/airdrop.ts:179

Parameters

Parameter	Type
`config`	`ConfidentialAirdropClientConfig`

Returns

ConfidentialAirdropClient

Properties

Property	Modifier	Type	Defined in
`publicClient`	`readonly`	{ }	fhe-airdrop/airdrop.ts:172
`walletClient?`	`readonly`	... \| ...	fhe-airdrop/airdrop.ts:173
`address`	`readonly`	`0x${(...)}`	fhe-airdrop/airdrop.ts:174

Accessors

aclAddress

Get Signature

get aclAddress(): `0x${(...)}`;

Defined in: fhe-airdrop/airdrop.ts:208

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.

Returns

`0x${(...)}`

Methods

token()

token(): Promise<...>;

Defined in: fhe-airdrop/airdrop.ts:221

ERC-7984 confidential token this airdrop was deployed for. Immutable arg.

Returns

Promise<...>

gasFee()

gasFee(): Promise<...>;

Defined in: fhe-airdrop/airdrop.ts:226

Per-claim gas fee in wei. Immutable arg. Attached as msg.value by claim() automatically.

Returns

Promise<...>

startTime()

startTime(): Promise<...>;

Defined in: fhe-airdrop/airdrop.ts:231

Unix timestamp when claims become available. Immutable arg.

Returns

Promise<...>

canExtendClaimWindow()

canExtendClaimWindow(): Promise<...>;

Defined in: fhe-airdrop/airdrop.ts:236

Whether the admin can extend the claim window past endTime. Immutable arg.

Returns

Promise<...>

endTime()

endTime(): Promise<...>;

Defined in: fhe-airdrop/airdrop.ts:245

Unix timestamp when claims end. Mutable — can be extended by admin if canExtendClaimWindow.

Returns

Promise<...>

isPaused()

isPaused(): Promise<...>;

Defined in: fhe-airdrop/airdrop.ts:250

Whether claims are currently paused by the admin.

Returns

Promise<...>

deploymentBlockNumber()

deploymentBlockNumber(): Promise<...>;

Defined in: fhe-airdrop/airdrop.ts:255

Block number at which this clone was deployed.

Returns

Promise<...>

claimedSignatures()

claimedSignatures(signatureHash): Promise<...>;

Defined in: fhe-airdrop/airdrop.ts:271

Check whether a pre-computed signature hash has been consumed.

The contract keys claim replay-protection on keccak256(abi.encode(CLAIM_TYPEHASH, recipient, bytes32(encryptedAmountHandle))). Use this when you already hold the struct hash (e.g. you computed it server-side while building the claim payload). For the more common case where you hold the user address and the encrypted handle, use isSignatureClaimed instead — it computes the hash for you.

Parameters

Parameter	Type	Description
`signatureHash`	`0x${(...)}`	`bytes32` storage key — the EIP-712 struct hash of the Claim.

Returns

Promise<...>

isClaimWindowActive()

isClaimWindowActive(): Promise<...>;

Defined in: fhe-airdrop/airdrop.ts:282

true if within the claim time window and not paused. Free read — no gas.

Returns

Promise<...>

hasClaimStarted()

hasClaimStarted(): Promise<...>;

Defined in: fhe-airdrop/airdrop.ts:287

true if the current timestamp is past START_TIME.

Returns

Promise<...>

hasClaimEnded()

hasClaimEnded(): Promise<...>;

Defined in: fhe-airdrop/airdrop.ts:292

true if the current timestamp is past endTime.

Returns

Promise<...>

domainSeparator()

domainSeparator(): Promise<...>;

Defined in: fhe-airdrop/airdrop.ts:297

EIP-712 domain separator for the clone. Useful for off-chain signing tools.

Returns

Promise<...>

claimTypehash()

claimTypehash(): Promise<...>;

Defined in: fhe-airdrop/airdrop.ts:307

EIP-712 type hash for the Claim(address recipient, bytes32 encryptedAmount) struct. Off-chain signers that don't use signClaimAuthorization (e.g. custom HSM-backed signers, ledger flows) need this to assemble the typed-data payload manually.

Returns

Promise<...>

isSignatureClaimed()

isSignatureClaimed(user, encryptedAmountHandle): Promise<...>;

Defined in: fhe-airdrop/airdrop.ts:324

Check whether a claim has been consumed, given the user address and encrypted amount handle.

This is the method most frontend developers want. Pass the same user and encryptedAmountHandle that appear in the admin-issued claim payload; the contract recomputes the struct hash internally and looks it up in storage.

Prefer this over claimedSignatures unless you already hold the pre-computed bytes32 struct hash (e.g. from a server-side indexer).

Parameters

Parameter	Type	Description
`user`	`0x${(...)}`	Recipient address from the claim authorization.
`encryptedAmountHandle`	`0x${(...)}`	The `externalEuint64` handle (as `Hex`) from the claim payload.

Returns

Promise<...>

isSignatureValid()

isSignatureValid(args): Promise<...>;

Defined in: fhe-airdrop/airdrop.ts:360

Check whether an admin-issued claim authorization is valid for a specific caller, without consuming it.

Returns false (not a revert) when the signature is structurally valid but fails one of the on-chain checks: already-claimed, claim window inactive, or the signer lacks DEFAULT_ADMIN_ROLE. The on-chain implementation recomputes the EIP-712 struct hash over (msg.sender, encryptedAmount), so the result is caller-specific: a signature issued for recipient A is invalid when checked against caller B. Pass the address that will actually submit the claim.

Throws InvalidSignatureError (code TOKENOPS_INVALID_SIGNATURE) when the signature bytes are structurally malformed — wrong length, invalid s-value range, or unparseable. The on-chain ECDSA.recover reverts before the boolean logic runs in that case, so consumer code must catch this separately from the false return:

try {
  const ok = await airdrop.isSignatureValid({ encryptedAmountHandle, signature, caller });
  if (!ok) { /* signed by non-admin, window closed, or already claimed */ }
} catch (err) {
  if (err instanceof InvalidSignatureError) { /* malformed signature bytes */ }
}

Use this to show a pre-claim validation state in the UI before asking the user to pay gas.

Parameters

Parameter	Type
`args`	`IsSignatureValidArgs`

Returns

Promise<...>

preflightClaim()

preflightClaim(args): Promise<...>;

Defined in: fhe-airdrop/airdrop.ts:413

Read-only preflight for claim. Runs the deterministic-from-off-chain checks in parallel and reports any blockers as typed TokenOpsSdkErrors. Returns { ready: true, blockers: [] } when the claim is safe to submit.

Preflight is opt-in. Consumers who have already validated state can skip this call and invoke claim directly — they'll receive the same typed errors at write time via the revert mapper.

Checks performed (all read-only, no gas):

Claim window started (block.timestamp ≥ START_TIME).
Claim window not closed (block.timestamp ≤ endTime).
Claims not paused.
Signature not already redeemed by this caller.
ETH balance covers GAS_FEE() (the msg.value the claim must attach).

The EIP-712 admin-signature check is not preflight-detectable — the SDK cannot verify the signer's role without the contract round-trip — and will still surface as InvalidSignatureError at write time.

Pool balance is also not preflight-detectable: the clone's confidential balance is an encrypted euint64 handle that the SDK cannot read in plaintext. An unfunded clone will pass preflight and revert on-chain with FheHandleNotAllowedError (the FHEVM ACL rejects FHE.allowTransient on an uninitialized handle). Confirm the pool has been funded before showing ready: true.

Parameters

Parameter	Type
`args`	{ `caller`: ...; `encryptedAmountHandle`: ...; }
`args.caller`	...
`args.encryptedAmountHandle`	...

Returns

Promise<...>

{ ready, blockers } — same code shape the write would throw.

claim()

claim(args): Promise<...>;

Defined in: fhe-airdrop/airdrop.ts:496

Claim tokens using an EIP-712 admin signature. Sends GAS_FEE() ETH with the tx.

The encryptedInput must be the exact handle the admin signed in signClaimAuthorization. The signature commits to that handle, so the SDK does NOT re-encrypt — submit the admin-issued payload as-is.

Parameters

Parameter	Type
`args`	`ClaimArgs`

Returns

Promise<...>

Transaction hash.

Example

const fee = await airdrop.gasFee();
const hash = await airdrop.claim({ encryptedInput, signature });

getClaimAmount()

getClaimAmount(args): Promise<...>;

Defined in: fhe-airdrop/airdrop.ts:543

This is a write transaction, not a free view. It costs gas.

Verify the admin-signed claim allocation and grant the caller decrypt access to the encrypted amount. Budget gas and await the receipt before calling the Zama relayer's userDecrypt — the handle is only valid after the tx lands.

Internally the contract calls FHE.allow(handle, msg.sender), which persists the ACL grant on-chain. The handle is extracted from the receipt's ACL Allowed event — simulateContract would return a divergent handle and break decryption.

Does not consume the claim (the claimedSignatures bit is not set). Call claim when the user is ready to transfer tokens.

Parameters

Parameter	Type
`args`	`GetClaimAmountArgs`

Returns

Promise<...>

{ handle, hash } — handle is a euint64 granted to the caller; pass it to the Zama relayer's userDecrypt to obtain the plaintext amount.

withdraw()

withdraw(recipient, account?): Promise<...>;

Defined in: fhe-airdrop/airdrop.ts:622

Withdraw all confidential tokens to recipient. DEFAULT_ADMIN_ROLE only.

Calling on a clone whose pool was never funded throws FheHandleNotAllowedError (code TOKENOPS_FHE_HANDLE_NOT_ALLOWED). The contract calls FHE.allowTransient on the confidential balance handle; when the handle is uninitialized, the FHEVM ACL contract reverts with SenderNotAllowed(address). Confirm the pool has been funded (e.g. via the factory's createAndFund... variant or a follow-up confidentialTransfer) before calling.

Parameters

Parameter	Type
`recipient`	`0x${(...)}`
`account?`	... \| ... \| ...

Returns

Promise<...>

setPaused()

setPaused(paused, account?): Promise<...>;

Defined in: fhe-airdrop/airdrop.ts:628

Pause or unpause claims. DEFAULT_ADMIN_ROLE only.

Parameters

Parameter	Type
`paused`	`boolean`
`account?`	... \| ... \| ...

Returns

Promise<...>

extendClaimWindow()

extendClaimWindow(newEndTime, account?): Promise<...>;

Defined in: fhe-airdrop/airdrop.ts:638

Extend the claim window end time. DEFAULT_ADMIN_ROLE only. Requires CAN_EXTEND_CLAIM_WINDOW == true or the contract reverts.

Parameters

Parameter	Type
`newEndTime`	`number`
`account?`	... \| ... \| ...

Returns

Promise<...>

withdrawOtherToken()

withdrawOtherToken(
   tokenAddress, 
   recipient, 
account?): Promise<...>;

Defined in: fhe-airdrop/airdrop.ts:645

Rescue accidentally sent ERC20 tokens. DEFAULT_ADMIN_ROLE only.

Parameters

Parameter	Type
`tokenAddress`	`0x${(...)}`
`recipient`	`0x${(...)}`
`account?`	... \| ... \| ...

Returns

Promise<...>

withdrawOtherConfidentialToken()

withdrawOtherConfidentialToken(
   tokenAddress, 
   recipient, 
account?): Promise<...>;

Defined in: fhe-airdrop/airdrop.ts:656

Rescue accidentally sent ERC7984 confidential tokens. DEFAULT_ADMIN_ROLE only.

Parameters

Parameter	Type
`tokenAddress`	`0x${(...)}`
`recipient`	`0x${(...)}`
`account?`	... \| ... \| ...

Returns

Promise<...>

withdrawGasFee()

withdrawGasFee(
   recipient, 
   amount, 
account?): Promise<...>;

Defined in: fhe-airdrop/airdrop.ts:674

Withdraw collected ETH gas fees. FEE_COLLECTOR_ROLE only. Pass amount = 0n to withdraw the entire balance.

Parameters

Parameter	Type
`recipient`	`0x${(...)}`
`amount`	`bigint`
`account?`	... \| ... \| ...

Returns

Promise<...>

hasRole()

hasRole(role, account): Promise<...>;

Defined in: fhe-airdrop/airdrop.ts:687

Parameters

Parameter	Type
`role`	`0x${(...)}`
`account`	`0x${(...)}`

Returns

Promise<...>

grantRole()

grantRole(
   role, 
   accountTarget, 
account?): Promise<...>;

Defined in: fhe-airdrop/airdrop.ts:691

Parameters

Parameter	Type
`role`	`0x${(...)}`
`accountTarget`	`0x${(...)}`
`account?`	... \| ... \| ...

Returns

Promise<...>

revokeRole()

revokeRole(
   role, 
   accountTarget, 
account?): Promise<...>;

Defined in: fhe-airdrop/airdrop.ts:701

Parameters

Parameter	Type
`role`	`0x${(...)}`
`accountTarget`	`0x${(...)}`
`account?`	... \| ... \| ...

Returns

Promise<...>

AlreadyClaimedError

Defined in: fhe-airdrop/errors.ts:14

The admin-signed claim signature has already been used. Airdrops use a per-signature replay guard (claimedSignatures[structHash]); each signed (recipient, encryptedAmount) pair is single-use.

Extends

TokenOpsSdkError

Constructors

Constructor

new AlreadyClaimedError(args): AlreadyClaimedError;

Defined in: fhe-airdrop/errors.ts:22

Parameters

Parameter	Type
`args`	{ `method`: ...; `contractAddress`: ...; `caller?`: ...; `cause?`: ...; }
`args.method`	...
`args.contractAddress`	...
`args.caller?`	...
`args.cause?`	...

Returns

AlreadyClaimedError

Overrides

TokenOpsSdkError.constructor

Properties

Property	Modifier	Type	Default value	Overrides	Inherited from	Defined in
`code`	`readonly`	`TokenOpsSdkErrorCode`	`undefined`	-	`TokenOpsSdkError`.`code`	core/errors.ts:89
`[TOKENOPS_SDK_ERROR_BRAND]`	`readonly`	`true`	`true`	-	`TokenOpsSdkError`.`[TOKENOPS_SDK_ERROR_BRAND]`	core/errors.ts:91
`name`	`readonly`	`"AlreadyClaimedError"`	`"AlreadyClaimedError"`	`TokenOpsSdkError`.`name`	-	fhe-airdrop/errors.ts:15
`context`	`readonly`	{ `method`: ...; `contractAddress`: ...; `caller?`: ...; }	`undefined`	`TokenOpsSdkError`.`context`	-	fhe-airdrop/errors.ts:16
`context.method`	`public`	...	`undefined`	-	-	fhe-airdrop/errors.ts:17
`context.contractAddress`	`public`	...	`undefined`	-	-	fhe-airdrop/errors.ts:18
`context.caller?`	`public`	...	`undefined`	-	-	fhe-airdrop/errors.ts:19

ClaimNotStartedError

Defined in: fhe-airdrop/errors.ts:45

The airdrop's claim window has not opened yet. startsAt is populated when the SDK has read the immutable start time; UIs can render a countdown.

Extends

TokenOpsSdkError

Constructors

Constructor

new ClaimNotStartedError(args): ClaimNotStartedError;

Defined in: fhe-airdrop/errors.ts:54

Parameters

Parameter	Type
`args`	{ `method`: ...; `contractAddress`: ...; `startsAt?`: ...; `cause?`: ...; }
`args.method`	...
`args.contractAddress`	...
`args.startsAt?`	...
`args.cause?`	...

Returns

ClaimNotStartedError

Overrides

TokenOpsSdkError.constructor

Properties

Property	Modifier	Type	Default value	Description	Overrides	Inherited from	Defined in
`code`	`readonly`	`TokenOpsSdkErrorCode`	`undefined`	-	-	`TokenOpsSdkError`.`code`	core/errors.ts:89
`[TOKENOPS_SDK_ERROR_BRAND]`	`readonly`	`true`	`true`	-	-	`TokenOpsSdkError`.`[TOKENOPS_SDK_ERROR_BRAND]`	core/errors.ts:91
`name`	`readonly`	`"ClaimNotStartedError"`	`"ClaimNotStartedError"`	-	`TokenOpsSdkError`.`name`	-	fhe-airdrop/errors.ts:46
`context`	`readonly`	{ `method`: ...; `contractAddress`: ...; `startsAt?`: ...; }	`undefined`	-	`TokenOpsSdkError`.`context`	-	fhe-airdrop/errors.ts:47
`context.method`	`public`	...	`undefined`	-	-	-	fhe-airdrop/errors.ts:48
`context.contractAddress`	`public`	...	`undefined`	-	-	-	fhe-airdrop/errors.ts:49
`context.startsAt?`	`public`	...	`undefined`	Unix seconds. Multiply by 1000 for `new Date(...)`.	-	-	fhe-airdrop/errors.ts:51

ClaimWindowClosedError

Defined in: fhe-airdrop/errors.ts:78

The airdrop's claim window has closed. endedAt is populated when the SDK has read the current end time. For airdrops with CAN_EXTEND_CLAIM_WINDOW set, the admin can extend via extendClaimWindow.

Extends

TokenOpsSdkError

Constructors

Constructor

new ClaimWindowClosedError(args): ClaimWindowClosedError;

Defined in: fhe-airdrop/errors.ts:87

Parameters

Parameter	Type
`args`	{ `method`: ...; `contractAddress`: ...; `endedAt?`: ...; `cause?`: ...; }
`args.method`	...
`args.contractAddress`	...
`args.endedAt?`	...
`args.cause?`	...

Returns

ClaimWindowClosedError

Overrides

TokenOpsSdkError.constructor

Properties

Property	Modifier	Type	Default value	Description	Overrides	Inherited from	Defined in
`code`	`readonly`	`TokenOpsSdkErrorCode`	`undefined`	-	-	`TokenOpsSdkError`.`code`	core/errors.ts:89
`[TOKENOPS_SDK_ERROR_BRAND]`	`readonly`	`true`	`true`	-	-	`TokenOpsSdkError`.`[TOKENOPS_SDK_ERROR_BRAND]`	core/errors.ts:91
`name`	`readonly`	`"ClaimWindowClosedError"`	`"ClaimWindowClosedError"`	-	`TokenOpsSdkError`.`name`	-	fhe-airdrop/errors.ts:79
`context`	`readonly`	{ `method`: ...; `contractAddress`: ...; `endedAt?`: ...; }	`undefined`	-	`TokenOpsSdkError`.`context`	-	fhe-airdrop/errors.ts:80
`context.method`	`public`	...	`undefined`	-	-	-	fhe-airdrop/errors.ts:81
`context.contractAddress`	`public`	...	`undefined`	-	-	-	fhe-airdrop/errors.ts:82
`context.endedAt?`	`public`	...	`undefined`	Unix seconds. Multiply by 1000 for `new Date(...)`.	-	-	fhe-airdrop/errors.ts:84

ConfidentialAirdropFactoryClient

Defined in: fhe-airdrop/factory.ts:184

Typed wrapper around the deployed ConfidentialAirdropFactory. Resolves the factory address per chain and encapsulates FHE encryption for fund methods.

Example

const factory = createConfidentialAirdropFactoryClient({ publicClient, walletClient, encryptor });
const hash = await factory.createConfidentialAirdrop({ params, userSalt });

Extended by

ConfidentialAirdropFactoryAdvancedClient

Constructors

Constructor

new ConfidentialAirdropFactoryClient(config): ConfidentialAirdropFactoryClient;

Defined in: fhe-airdrop/factory.ts:191

Parameters

Parameter	Type
`config`	`ConfidentialAirdropFactoryClientConfig`

Returns

ConfidentialAirdropFactoryClient

Properties

Property	Modifier	Type	Defined in
`publicClient`	`readonly`	{ }	fhe-airdrop/factory.ts:185
`walletClient?`	`readonly`	... \| ...	fhe-airdrop/factory.ts:186
`address`	`readonly`	`0x${(...)}`	fhe-airdrop/factory.ts:187
`encryptor?`	`readonly`	... \| ...	fhe-airdrop/factory.ts:188

Methods

createConfidentialAirdrop()

createConfidentialAirdrop(args): Promise<...>;

Defined in: fhe-airdrop/factory.ts:245

Deploy a new airdrop clone via the factory and return its address, parsed from the ConfidentialAirdropCreated event in the tx receipt.

This is the headline factory entry point. It returns one rich-return shape: most consumers want the deployed address back, and the SDK already waits for and parses the event, so there's no reason to make consumers do it themselves.

Internally: writeContract → PublicClient.waitForTransactionReceipt → parseEventLogs({ eventName: "ConfidentialAirdropCreated" }).

For genuine pre-mine prediction (rare), import ConfidentialAirdropFactoryAdvancedClient from @tokenops/sdk/fhe-airdrop/advanced and call predictAirdropAddress.

Parameters

Parameter	Type
`args`	`CreateAirdropArgs`

Returns

Promise<...>

Example

const { hash, airdrop } = await factory.createConfidentialAirdrop({
  params, userSalt,
});

createAndFundConfidentialAirdrop()

createAndFundConfidentialAirdrop(args): Promise<...>;

Defined in: fhe-airdrop/factory.ts:277

Deploy and fund a new airdrop in a single transaction, and return its address. The SDK encrypts amount into an externalEuint64 before passing to the contract.

Prerequisites: caller must have set this factory as an operator on the token: token.setOperator(factoryAddress, deadline).

Symmetric with ConfidentialAirdropFactoryClient.createConfidentialAirdrop — both return { hash, airdrop } parsed from the ConfidentialAirdropCreated event.

Parameters

Parameter	Type
`args`	`CreateAndFundAirdropArgs`

Returns

Promise<...>

Example

const { hash, airdrop } = await factory.createAndFundConfidentialAirdrop({
  params, userSalt, amount: 1_000_000n,
});

fundConfidentialAirdrop()

fundConfidentialAirdrop(args): Promise<...>;

Defined in: fhe-airdrop/factory.ts:335

Fund an existing (or not-yet-deployed) airdrop with encrypted tokens.

Prerequisites: caller must have set this factory as an operator on the token: token.setOperator(factoryAddress, deadline)

Parameters

Parameter	Type
`args`	`FundAirdropArgs`

Returns

Promise<...>

Transaction hash.

createConfidentialAirdropAndGetAddress()

createConfidentialAirdropAndGetAddress(args): Promise<...>;

Defined in: fhe-airdrop/factory.ts:393

Deploy a new airdrop clone and return its address, parsed from the ConfidentialAirdropCreated event in the tx receipt.

Symmetry helper with the fhe-vesting client. Use this when you want a one-call "deploy and use" shape; otherwise call ConfidentialAirdropFactoryClient.createConfidentialAirdrop and parse the receipt yourself, or call ConfidentialAirdropFactoryClient.predictAirdropAddress before mining.

Internally: ConfidentialAirdropFactoryClient.createConfidentialAirdrop → PublicClient.waitForTransactionReceipt → parseEventLogs({ eventName: "ConfidentialAirdropCreated" }).

Parameters

Parameter	Type
`args`	`CreateAirdropArgs`

Returns

Promise<...>

Example

const { hash, airdrop } = await factory.createConfidentialAirdropAndGetAddress({
  params, userSalt,
});

createAndFundConfidentialAirdropAndGetAddress()

createAndFundConfidentialAirdropAndGetAddress(args): Promise<...>;

Defined in: fhe-airdrop/factory.ts:415

Deploy AND fund a new airdrop clone in one tx, returning its address parsed from the ConfidentialAirdropCreated event in the receipt.

Symmetry with ConfidentialAirdropFactoryClient.createConfidentialAirdropAndGetAddress — use this when you also need to seed the pool in the same transaction.

Internally: ConfidentialAirdropFactoryClient.createAndFundConfidentialAirdrop → PublicClient.waitForTransactionReceipt → parseEventLogs({ eventName: "ConfidentialAirdropCreated" }).

Parameters

Parameter	Type
`args`	`CreateAndFundAirdropArgs`

Returns

Promise<...>

Example

const { hash, airdrop } = await factory.createAndFundConfidentialAirdropAndGetAddress({
  params, userSalt, amount, encryptor,
});

setFeeCollector()

setFeeCollector(newFeeCollector, account?): Promise<...>;

Defined in: fhe-airdrop/factory.ts:424

Change the fee collector address. FEE_MANAGER_ROLE only.

Parameters

Parameter	Type
`newFeeCollector`	`0x${(...)}`
`account?`	... \| ... \| ...

Returns

Promise<...>

setDefaultGasFee()

setDefaultGasFee(newGasFee, account?): Promise<...>;

Defined in: fhe-airdrop/factory.ts:431

Change the default per-claim gas fee in wei. FEE_MANAGER_ROLE only.

Parameters

Parameter	Type
`newGasFee`	`bigint`
`account?`	... \| ... \| ...

Returns

Promise<...>

setCustomFee()

setCustomFee(
   campaignCreator, 
   gasFee, 
account?): Promise<...>;

Defined in: fhe-airdrop/factory.ts:438

Set a per-creator gas fee override. FEE_MANAGER_ROLE only.

Parameters

Parameter	Type
`campaignCreator`	`0x${(...)}`
`gasFee`	`bigint`
`account?`	... \| ... \| ...

Returns

Promise<...>

disableCustomFee()

disableCustomFee(campaignCreator, account?): Promise<...>;

Defined in: fhe-airdrop/factory.ts:449

Remove a per-creator fee override, reverting to defaultGasFee. FEE_MANAGER_ROLE only.

Parameters

Parameter	Type
`campaignCreator`	`0x${(...)}`
`account?`	... \| ... \| ...

Returns

Promise<...>

implementation()

implementation(): Promise<...>;

Defined in: fhe-airdrop/factory.ts:458

Current LibClone implementation address.

Returns

Promise<...>

airdropImplementation()

airdropImplementation(): Promise<...>;

Defined in: fhe-airdrop/factory.ts:474

Alias for ConfidentialAirdropFactoryClient.implementation that matches the contract's storage field name (_airdropImplementation).

Provided for parity with fhe-vesting's managerImplementation() alias. The airdrop factory has the same LibClone shape mirroring _airdropImplementation storage, so server devs reading the Solidity first reach for factory.airdropImplementation() via autocomplete and would otherwise hit a TS2551 on the SDK's implementation() shape. The canonical implementation() method is retained for backwards-compat and cross-factory uniformity.

Returns

Promise<...>

defaultGasFee()

defaultGasFee(): Promise<...>;

Defined in: fhe-airdrop/factory.ts:479

Default per-claim gas fee in wei. Used when no custom fee is set for the campaign creator.

Returns

Promise<...>

feeCollector()

feeCollector(): Promise<...>;

Defined in: fhe-airdrop/factory.ts:484

Address authorized to collect gas fees from airdrop clones.

Returns

Promise<...>

getCustomFee()

getCustomFee(campaignCreator): Promise<...>;

Defined in: fhe-airdrop/factory.ts:489

Per-creator custom fee override. enabled is false when no override is set.

Parameters

Parameter	Type
`campaignCreator`	`0x${(...)}`

Returns

Promise<...>

getInitCodeHash()

getInitCodeHash(args): Promise<...>;

Defined in: fhe-airdrop/factory.ts:503

Compute the CREATE2 init-code hash for a given set of params and gas fee. Useful for deriving the clone address off-chain. Use predictAirdropAddress from @tokenops/sdk/fhe-airdrop/advanced for the full address derivation.

Parameters

Parameter	Type	Description
`args`	{ `params`: ...; `gasFee`: ...; }	`{ params, gasFee }` — must match the values used at deploy time.
`args.params`	...	-
`args.gasFee`	...	-

Returns

Promise<...>

bytes32 init-code hash.

Interfaces

ConfidentialAirdropClientConfig

Defined in: fhe-airdrop/airdrop.ts:71

Properties

Property	Type	Description	Defined in
`publicClient`	{ }	-	fhe-airdrop/airdrop.ts:72
`walletClient?`	... \| ...	-	fhe-airdrop/airdrop.ts:73
`address`	`0x${(...)}`	Deployed airdrop clone address.	fhe-airdrop/airdrop.ts:75
`aclAddress?`	... \| ...	FHEVM ACL contract address override. When omitted, resolved from `publicClient.chain?.id` via the SDK's chain registry; the constructor throws `DeploymentAddressUnavailableError` if neither is available. Required because `getClaimAmount` filters the receipt for ACL grants to extract the returned handle.	fhe-airdrop/airdrop.ts:83
`telemetry?`	... \| ...	Optional telemetry sink. When provided, the SDK emits a `fhe-airdrop.client.init` event on construction and brackets public write methods with named spans (`fhe-airdrop.client.claim`, `…getClaimAmount`, …). 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`.	fhe-airdrop/airdrop.ts:93

ClaimArgs

Defined in: fhe-airdrop/airdrop.ts:111

Args for claim() / getClaimAmount().

The admin produces { encryptedInput, signature } off-chain (typically server-side) by encrypting the allocation with userAddress: recipient (the Zama input proof MUST be bound to the recipient — the contract's FHE.fromExternal rejects proofs bound to any other address) and then signing the resulting handle with signClaimAuthorization. The recipient submits exactly that pair — the SDK does not re-encrypt.

The signature commits to a specific bytes32 handle via EIP-712, so re-encrypting the same plaintext locally would produce a different handle and the signature would no longer match. That is why encryptedInput is required and there is no plaintext amount field on this type.

Properties

Property	Type	Description	Defined in
`encryptedInput`	`EncryptedInput`	Pre-encrypted external `euint64` input — must match the handle the admin signed.	fhe-airdrop/airdrop.ts:113
`signature`	`0x${(...)}`	EIP-712 signature from an address with DEFAULT_ADMIN_ROLE on this clone.	fhe-airdrop/airdrop.ts:115
`value?`	... \| ...	ETH value (in wei) to attach as `msg.value`. Defaults to `gasFee()` fetched live if omitted. Pre-fetch and cache with `await airdrop.gasFee()` when displaying the fee in the UI before the user clicks submit — this avoids an extra RPC round-trip and lets you present the exact cost upfront.	fhe-airdrop/airdrop.ts:124
`account?`	... \| ... \| ...	Override the submitting account. Defaults to `walletClient.account`.	fhe-airdrop/airdrop.ts:126

GetClaimAmountArgs

Defined in: fhe-airdrop/airdrop.ts:130

Args for ConfidentialAirdropClient.getClaimAmount — same shape as ClaimArgs minus value (the contract is not payable).

Properties

Property	Type	Description	Defined in
`encryptedInput`	`EncryptedInput`	Pre-encrypted external `euint64` input — must match the handle the admin signed.	fhe-airdrop/airdrop.ts:132
`signature`	`0x${(...)}`	EIP-712 signature from an address with DEFAULT_ADMIN_ROLE on this clone.	fhe-airdrop/airdrop.ts:134
`account?`	... \| ... \| ...	Override the submitting account. Defaults to `walletClient.account`.	fhe-airdrop/airdrop.ts:136

IsSignatureValidArgs

Defined in: fhe-airdrop/airdrop.ts:140

Args for ConfidentialAirdropClient.isSignatureValid.

Properties

Property	Type	Description	Defined in
`encryptedAmountHandle`	`0x${(...)}`	`externalEuint64` handle bytes32 — the same handle the admin signed.	fhe-airdrop/airdrop.ts:142
`signature`	`0x${(...)}`	EIP-712 admin signature over `Claim(address recipient, bytes32 encryptedAmount)`.	fhe-airdrop/airdrop.ts:144
`caller`	`0x${(...)}`	Address the contract will treat as `msg.sender` during the call. The on-chain check recomputes the struct hash over `(msg.sender, encryptedAmount)`, so the result varies per-caller — typically the wallet that intends to claim.	fhe-airdrop/airdrop.ts:150

Encryptor

Defined in: fhe-airdrop/encryption.ts:42

Subset of @zama-fhe/sdk RelayerSDK we depend on. Declared structurally so consumers can pass any v3 RelayerSDK without us importing the optional peer dep.

Methods

encrypt()

encrypt(params): Promise<...>;

Defined in: fhe-airdrop/encryption.ts:43

Parameters

Parameter	Type
`params`	{ `values`: ...; `contractAddress`: ...; `userAddress`: ...; }
`params.values`	...
`params.contractAddress`	...
`params.userAddress`	...

Returns

Promise<...>

EncryptUint64Args

Defined in: fhe-airdrop/encryption.ts:75

Properties

Property	Type	Defined in
`encryptor`	`Encryptor`	fhe-airdrop/encryption.ts:76
`contractAddress`	`0x${(...)}`	fhe-airdrop/encryption.ts:77
`userAddress`	`0x${(...)}`	fhe-airdrop/encryption.ts:78
`value`	`bigint`	fhe-airdrop/encryption.ts:79

EncryptUint64BatchArgs

Defined in: fhe-airdrop/encryption.ts:82

Properties

Property	Type	Defined in
`encryptor`	`Encryptor`	fhe-airdrop/encryption.ts:83
`contractAddress`	`0x${(...)}`	fhe-airdrop/encryption.ts:84
`userAddress`	`0x${(...)}`	fhe-airdrop/encryption.ts:85
`values`	...[]	fhe-airdrop/encryption.ts:86

ConfidentialAirdropFactoryClientConfig

Defined in: fhe-airdrop/factory.ts:40

Properties

Property	Type	Description	Defined in
`publicClient`	{ }	-	fhe-airdrop/factory.ts:41
`walletClient?`	... \| ...	-	fhe-airdrop/factory.ts:42
`address?`	... \| ...	Override the on-chain factory address. Falls back to `getFheAirdropFactoryAddress(chainId)`.	fhe-airdrop/factory.ts:44
`chainId?`	... \| ...	Explicit chain id used to look up the default factory address. Defaults to `publicClient.chain?.id`.	fhe-airdrop/factory.ts:46
`encryptor?`	... \| ...	Default encryptor used by fund methods. Optional at construction time but required at call time for `createAndFundConfidentialAirdrop` and `fundConfidentialAirdrop`.	fhe-airdrop/factory.ts:51
`telemetry?`	... \| ...	Optional telemetry sink. When provided, the SDK emits a `fhe-airdrop.client.init` event on construction and brackets public write methods with named spans (`fhe-airdrop.factory.createConfidentialAirdrop`, `…createAndFundConfidentialAirdrop`, …). 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`.	fhe-airdrop/factory.ts:61

CreateAirdropArgs

Defined in: fhe-airdrop/factory.ts:64

Properties

Property	Type	Description	Defined in
`params`	`AirdropParams`	-	fhe-airdrop/factory.ts:65
`userSalt`	`0x${(...)}`	Any unique 32-byte salt. Combined with msg.sender to derive the CREATE2 salt.	fhe-airdrop/factory.ts:67
`account?`	... \| ... \| ...	-	fhe-airdrop/factory.ts:68

CreateAirdropResult

Defined in: fhe-airdrop/factory.ts:155

Rich-return shape from ConfidentialAirdropFactoryClient.createConfidentialAirdrop and ConfidentialAirdropFactoryClient.createAndFundConfidentialAirdrop.

Branded hash: TxHash and airdrop: Address so consumers can't accidentally swap them at the destructure site.

Properties

Property	Type	Description	Defined in
`hash`	`0x${(...)}`	Tx hash that deployed the clone.	fhe-airdrop/factory.ts:157
`airdrop`	`0x${(...)}`	Address of the deployed clone, parsed from the `ConfidentialAirdropCreated` event.	fhe-airdrop/factory.ts:159

AirdropParams

Defined in: fhe-airdrop/types.ts:12

Parameters for creating a confidential airdrop.

startTimestamp and endTimestamp are unix timestamps (uint32). The SDK maps them to the on-chain struct fields startTime / endTime before encoding — do not pass the on-chain names directly.

Properties

Property	Type	Defined in
`token`	`0x${(...)}`	fhe-airdrop/types.ts:13
`startTimestamp`	`number`	fhe-airdrop/types.ts:14
`endTimestamp`	`number`	fhe-airdrop/types.ts:15
`canExtendClaimWindow`	`boolean`	fhe-airdrop/types.ts:16
`admin`	`0x${(...)}`	fhe-airdrop/types.ts:17

CustomFee

Defined in: fhe-airdrop/types.ts:21

Custom fee override for a campaign creator.

Properties

Property	Type	Defined in
`enabled`	`boolean`	fhe-airdrop/types.ts:22
`gasFee`	`bigint`	fhe-airdrop/types.ts:23

Type Aliases

FheValueInput

type FheValueInput = ... | ... | ...;

Defined in: fhe-airdrop/encryption.ts:20

FHE input values, discriminated by ciphertext type. Mirrors the shape of EncryptInput from @zama-fhe/sdk so that a RelayerWeb / RelayerNode / MockFhevmInstance instance is structurally assignable to Encryptor without casting.

EncryptorSource

type EncryptorSource = ... | ...;

Defined in: fhe-airdrop/encryption.ts:54

Eager or lazy Encryptor reference. Lazy form for React/Vue/signals hosts where the encryptor lifetime doesn't match the client's.

CreateAndFundAirdropArgs

type CreateAndFundAirdropArgs = ... | ...;

Defined in: fhe-airdrop/factory.ts:90

Discriminated union: provide EITHER an encryptor (the SDK encrypts amount) OR a pre-built encryptedInput. Passing both is a compile error.

FundAirdropArgs

type FundAirdropArgs = ... | ...;

Defined in: fhe-airdrop/factory.ts:134

Discriminated union: provide EITHER an encryptor (the SDK encrypts amount) OR a pre-built encryptedInput. Passing both is a compile error.

Variables

confidentialAirdropCloneableAbi

const confidentialAirdropCloneableAbi: readonly [..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ...];

Defined in: fhe-airdrop/abis/cloneable.ts:2

confidentialAirdropFactoryAbi

const confidentialAirdropFactoryAbi: readonly [..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ..., ...];

Defined in: fhe-airdrop/abis/factory.ts:2

Functions

createConfidentialAirdropClient()

function createConfidentialAirdropClient(config): ConfidentialAirdropClient;

Defined in: fhe-airdrop/airdrop.ts:848

Create a ConfidentialAirdropClient. Mirrors viem's create* convention.

Parameters

Parameter	Type
`config`	`ConfidentialAirdropClientConfig`

Returns

ConfidentialAirdropClient

Example

const airdrop = createConfidentialAirdropClient({
  publicClient, walletClient,
  address: "0xYourAirdropClone",
  encryptor,
});

resolveEncryptor()

function resolveEncryptor(source): ... | ...;

Defined in: fhe-airdrop/encryption.ts:70

Normalize an EncryptorSource to the underlying Encryptor, invoking the factory if lazy.

Parameters

Parameter	Type	Description
`source`	... \| ...	Eager encryptor instance or a lazy factory that returns one.

Returns

... | ...

The resolved Encryptor, or undefined if source is undefined or the factory returned undefined.

Example

// Server / test — eager instance
const encryptor = new RelayerNode({ transports: { ... }, getChainId: async () => sepolia.id });
const resolved = resolveEncryptor(encryptor); // returns encryptor directly

// React — lazy factory picks up the live ZamaSDK context
const zamaSDK = useZamaSDK();
const resolved = resolveEncryptor(() => zamaSDK.relayer);

encryptUint64()

function encryptUint64(args): Promise<...>;

Defined in: fhe-airdrop/encryption.ts:126

Encrypt a single uint64 value into an externalEuint64 handle + KMS input proof.

The handle and proof are bound to contractAddress and userAddress — they cannot be replayed against a different contract or sender. For airdrops the userAddress MUST be the recipient (not the admin), because the contract's FHE.fromExternal rejects proofs bound to any other address.

Parameters

Parameter	Type	Description
`args`	`EncryptUint64Args`	Encryption request; `value` must fit in `uint64` (0 to 2^64-1).

Returns

Promise<...>

{ handle: Hex, inputProof: Hex } — pass both to the contract.

Example

const encrypted = await encryptUint64({
  encryptor,
  contractAddress: airdropAddress,
  userAddress: recipientAddress, // must be the recipient, not the admin
  value: 1_000_000n,             // raw token units; ERC-7984 uses 6 decimals
});
const signature = await signClaimAuthorization({
  walletClient,
  airdropAddress,
  recipient: recipientAddress,
  encryptedAmountHandle: encrypted.handle,
});

encryptUint64Batch()

function encryptUint64Batch(__namedParameters): Promise<...>;

Defined in: fhe-airdrop/encryption.ts:155

Encrypt N uint64 values into N handles bound by a single input proof.

Parameters

Parameter	Type
`__namedParameters`	`EncryptUint64BatchArgs`

Returns

Promise<...>

signClaimAuthorization()

function signClaimAuthorization(args): Promise<...>;

Defined in: fhe-airdrop/encryption.ts:197

Build an EIP712 signature for a Claim(address recipient, bytes32 encryptedAmount) struct.

The admin calls this to sign a claim authorisation. The resulting signature is passed by the recipient to claim() or getClaimAmount().

Parameters

Parameter	Type	Description
`args`	{ `walletClient`: ...; `airdropAddress`: ...; `recipient`: ...; `encryptedAmountHandle`: ...; }	Claim signing request. `walletClient` must sign with DEFAULT_ADMIN_ROLE on the airdrop clone.
`args.walletClient`	...	-
`args.airdropAddress`	...	-
`args.recipient`	...	-
`args.encryptedAmountHandle`	...	-

Returns

Promise<...>

0x-prefixed ECDSA signature bytes.

createConfidentialAirdropFactoryClient()

function createConfidentialAirdropFactoryClient(config): ConfidentialAirdropFactoryClient;

Defined in: fhe-airdrop/factory.ts:690

Create a ConfidentialAirdropFactoryClient. Mirrors viem's create* convention.

Parameters

Parameter	Type
`config`	`ConfidentialAirdropFactoryClientConfig`

Returns

ConfidentialAirdropFactoryClient

Example

const factory = createConfidentialAirdropFactoryClient({ publicClient, walletClient, encryptor });

Classes​

ConfidentialAirdropClient​

Example​

Constructors​

Constructor​

Parameters​

Returns​

Properties​

Accessors​

aclAddress​

Get Signature​

Returns​

Methods​

token()​

Returns​

gasFee()​

Returns​

startTime()​

Returns​

canExtendClaimWindow()​

Returns​

endTime()​

Returns​

isPaused()​

Returns​

deploymentBlockNumber()​

Returns​

claimedSignatures()​

Parameters​

Returns​

isClaimWindowActive()​

Returns​

hasClaimStarted()​

Returns​

hasClaimEnded()​

Returns​

domainSeparator()​

Returns​

claimTypehash()​

Returns​

isSignatureClaimed()​

Parameters​

Returns​

isSignatureValid()​

Parameters​

Returns​

preflightClaim()​

Parameters​

Returns​

claim()​

Parameters​

Returns​

Example​

getClaimAmount()​

Parameters​

Returns​

withdraw()​

Parameters​

Returns​

setPaused()​

Parameters​

Returns​

extendClaimWindow()​

Parameters​

Returns​

withdrawOtherToken()​

Parameters​

Returns​

withdrawOtherConfidentialToken()​

Parameters​

Returns​

withdrawGasFee()​

Parameters​

Returns​

hasRole()​

Parameters​

Returns​

grantRole()​

Parameters​

Returns​

Classes

ConfidentialAirdropClient

Example

Constructors

Constructor

Parameters

Returns

Properties

Accessors

aclAddress

Get Signature

Returns

Methods

token()

Returns

gasFee()

Returns

startTime()

Returns

canExtendClaimWindow()

Returns

endTime()

Returns

isPaused()

Returns

deploymentBlockNumber()

Returns

claimedSignatures()

Parameters

Returns

isClaimWindowActive()

Returns

hasClaimStarted()

Returns

hasClaimEnded()

Returns

domainSeparator()

Returns

claimTypehash()

Returns

isSignatureClaimed()

Parameters

Returns

isSignatureValid()

Parameters

Returns

preflightClaim()

Parameters

Returns

claim()

Parameters

Returns

Example

getClaimAmount()

Parameters

Returns

withdraw()

Parameters

Returns

setPaused()

Parameters

Returns

extendClaimWindow()

Parameters

Returns

withdrawOtherToken()

Parameters

Returns

withdrawOtherConfidentialToken()

Parameters

Returns

withdrawGasFee()

Parameters

Returns

hasRole()

Parameters

Returns

grantRole()

Parameters

Returns