@tokenops/sdk 2.0.0-alpha.2 → 2.0.0-alpha.4

package/dist/fhe-airdrop/index.d.ts

@@ -2,9 +2,10 @@
  * `@tokenops/sdk/fhe-airdrop` - confidential airdrop campaigns on the
  * TokenOps airdrop v2 contracts.
  *
- * **Unaudited contracts. Alpha software. No stability promise.** This module
- * targets `tokenops-fhe-airdrop-v2`, which has not been audited. It is
- * intended for the `alpha` npm dist-tag only, and must not be published to
+ * **Alpha software. No stability promise.**
+ * This module targets `tokenops-fhe-airdrop-v2` at `AIRDROP_CONTRACTS_COMMIT`, through
+ * the Sepolia deployment in `DEPLOYED_ADDRESSES`. It is intended for the `alpha` npm
+ * dist-tag only, and must not be published to
  * `latest`: the release that first ships this module is the one that sets
  * that tag. Two contract
  * behaviours would otherwise produce a wrong result rather than a revert,
@@ -27,22 +28,23 @@
  * Address prediction and its integrity guards live on the
  * `@tokenops/sdk/fhe-airdrop/advanced` subpath.
  */
-export { AIRDROP_CONTRACTS_COMMIT, DEDUP_MODE, DEPLOYMENT_MODE, type DedupMode, type DeploymentMode, } from "./constants.js";
+export { AIRDROP_CONTRACTS_COMMIT, DEDUP_MODE, DEPLOYMENT_MODE, UINT96_MAX, type DedupMode, type DeploymentMode, } from "./constants.js";
 export { ConfidentialAirdropFactoryClient, createConfidentialAirdropFactoryClient, FACTORY_ROLE_CONCENTRATION_NOTE, type CompliancePolicy, type ConfidentialAirdropFactoryClientConfig, type CustomFee, type FundInput, type UpgradeabilityPolicy, } from "./factory.js";
-export { AirdropBaseClient, createAirdropBaseClient, type AirdropBaseClientConfig, type WriteAccountOverride, } from "./airdrop-base.js";
+export { AirdropBaseClient, createAirdropBaseClient, type AirdropBaseClientConfig, type UnwrapRequest, type UnwrapRequestSource, type WriteAccountOverride, } from "./airdrop-base.js";
 export { CLAIM_TYPEHASH, CLAIM_TYPES, createEcdsaAirdropClient, EcdsaAirdropClient, EIP712_DOMAIN_NAME, EIP712_DOMAIN_VERSION, type Eip712Domain, type EcdsaAirdropClientConfig, type EcdsaClaimArgs, type GetClaimAmountArgs as EcdsaGetClaimAmountArgs, type IsSignatureValidArgs, } from "./ecdsa.js";
 export { createMerkleAirdropClient, MerkleAirdropClient, type GetClaimAmountArgs as MerkleGetClaimAmountArgs, type MerkleClaimArgs, } from "./merkle.js";
 export { buildMerkleTree, leafOf, type BuildMerkleTreeArgs, type BuiltMerkleTree, type LeafOfArgs, type MerkleLeafInput, } from "./merkle-tree.js";
 export { ComplianceManagerClient, createComplianceManagerClient, isAclPropagationError, type ComplianceManagerClientConfig, } from "./compliance.js";
-export type { BuiltCampaign, CampaignEntry, CampaignRecipient, CommonAirdropParams, CreateAirdropArgs, CreateAirdropResult, EcdsaAirdropParams, MerkleAirdropParams, } from "./types.js";
+export type { AirdropVariantParams, BuiltCampaign, CampaignEntry, CampaignRecipient, CommonAirdropParams, CreateAirdropArgs, CreateAirdropResult, CreateCommitments, CreateMerkleAirdropArgs, EcdsaAirdropParams, MerkleAirdropParams, PendingCreateAirdropResult, } from "./types.js";
+export type { MinedWrite, PendingWrite, ReceiptMode } from "../core/pending.js";
 export type { EncryptedInput, EncryptedInputs, EncryptedViewResult } from "../fhe/types.js";
-export { buildMerkleCampaign, encryptCampaignAmounts, planMerkleCampaign, rotateMerkleRoot, validateCampaignRecipients, type BuildMerkleCampaignArgs, type CampaignSubmitterOption, type EncryptCampaignAmountsArgs, type EncryptedCampaignLeaf, type PlanMerkleCampaignArgs, type PlannedCampaign, type RotatedCampaign, type RotateMerkleRootArgs, } from "./campaign.js";
-export { grantInstanceRoles, planInstanceRoleSplit, type InstanceRoleAssignment, type RoleGrantOutcome, type RoleGrantStep, type RoleName, } from "./roles.js";
+export { buildMerkleCampaign, encryptCampaignAmounts, MERKLE_BATCH_LIMIT, planMerkleCampaign, rotateMerkleRoot, validateCampaignRecipients, type BuildMerkleCampaignArgs, type EncryptCampaignAmountsArgs, type EncryptedCampaignLeaf, type PlanMerkleCampaignArgs, type PlannedCampaign, type RotatedCampaign, type RotateMerkleRootArgs, } from "./campaign.js";
+export { encodeInstanceRoleSplit, grantInstanceRoles, planInstanceRoleSplit, type InstanceRoleAssignment, type InstanceRoleCall, type InstanceRoleConstants, type RoleGrantOutcome, type RoleGrantStep, type RoleName, } from "./roles.js";
 export { encryptUint64, encryptUint64Batch, resolveEncryptor, signClaimAuthorization, type Encryptor, type EncryptorSource, type EncryptUint64Args, type EncryptUint64BatchArgs, type FheValueInput, } from "./encryption.js";
-export { preflightClaim, preflightCreate, type ClaimPreflightTarget, type EcdsaClaimPreflightSignature, type PreflightClaimArgs, type PreflightCreateArgs, } from "./guards.js";
+export { preflightClaim, preflightCreate, type AirdropRegistry, type ClaimPreflightTarget, type EcdsaClaimPreflightSignature, type PreflightClaimArgs, type PreflightCreateArgs, type PreflightCreateResult, } from "./guards.js";
 export { type PreflightResult } from "../core/preflight.js";
 export { airdropFactoryAbi, complianceRoleManagerAbi, confidentialAirdropBaseAbi, ecdsaConfidentialAirdropAbi, merkleConfidentialAirdropAbi, } from "./abis/index.js";
-export { AlreadyClaimedError, ClaimNotStartedError, ClaimWindowClosedError, DedupIdConsumedError, FeeCollectorSelfAdministeredError, MerkleUupsUnsupportedError, NonStockWrapperError, PredictionDriftError, SaltCollisionError, SignatureExpiredError, UnauthorizedRedirectError, UpgradeabilityNotAllowedError, type AirdropVariant, } from "./errors.js";
+export { AlreadyClaimedError, ClaimNotStartedError, ClaimWindowClosedError, ClawbackRequiresPauseError, CreateCommitmentMismatchError, DedupIdConsumedError, FeeCollectorSelfAdministeredError, GasFeeNotAcceptedError, MerkleUupsUnsupportedError, NativeRescueRequiresZeroFeeError, NonStockWrapperError, PredictionDriftError, SaltCollisionError, SignatureExpiredError, UnauthorizedRedirectError, UnrecognisedAirdropError, UpgradeabilityNotAllowedError, type AirdropVariant, } from "./errors.js";
 export { TokenOpsSdkError, isTokenOpsSdkError, DeploymentAddressUnavailableError, UnsupportedChainError, MissingAccountError, MissingClientError, MissingEncryptorError, MissingPublicClientError, MissingWalletClientError, InvalidArgumentError, ReceiptEventAmbiguousError, ReceiptEventNotFoundError, TokenOpsValidationError, ContractRevertError, TokenOpsContractError, PausedError, AccessDeniedError, OperatorNotApprovedError, InsufficientFeeError, InsufficientBalanceError, BatchTooLargeError, FeatureDisabledError, TransferFailedError, FheHandleNotAllowedError, AlreadyInitializedError, ReentrancyError, InvalidSignatureError, WalletRejectedError, WalletChainMismatchError, NetworkError, InsufficientGasFundsError, UnknownWriteFailureError, UserRejectedSignatureError, SigningFailedError, RelayerUnreachableError, EncryptionFailedError, DecryptionFailedError, UserDecryptNotAllowedError, type DeploymentAddressUnavailableReason, type TokenOpsSdkErrorCode, } from "../core/errors.js";
 export { ERC7984_OPERATOR_MAX_DEADLINE, revokeOperator, setOperator, type RevokeOperatorArgs, type SetOperatorArgs, } from "../fhe/operators.js";
 export { erc7984OperatorAbi } from "../fhe/erc7984-abi.js";

package/dist/fhe-airdrop/index.js

@@ -1,12 +1,12 @@
-export { buildMerkleCampaign, buildMerkleTree, encryptCampaignAmounts, grantInstanceRoles, leafOf, planInstanceRoleSplit, planMerkleCampaign, rotateMerkleRoot, validateCampaignRecipients } from '../chunk-GADGBQJO.js';
-export { AirdropBaseClient, CLAIM_TYPEHASH, CLAIM_TYPES, ComplianceManagerClient, ConfidentialAirdropFactoryClient, EIP712_DOMAIN_NAME, EIP712_DOMAIN_VERSION, EcdsaAirdropClient, FACTORY_ROLE_CONCENTRATION_NOTE, MerkleAirdropClient, airdropFactoryAbi, complianceRoleManagerAbi, confidentialAirdropBaseAbi, createAirdropBaseClient, createComplianceManagerClient, createConfidentialAirdropFactoryClient, createEcdsaAirdropClient, createMerkleAirdropClient, ecdsaConfidentialAirdropAbi, encryptUint64, encryptUint64Batch, isAclPropagationError, merkleConfidentialAirdropAbi, resolveEncryptor, signClaimAuthorization } from '../chunk-X7WBPCEU.js';
-export { AIRDROP_CONTRACTS_COMMIT, AlreadyClaimedError, ClaimNotStartedError, ClaimWindowClosedError, DEDUP_MODE, DEPLOYMENT_MODE, DedupIdConsumedError, FeeCollectorSelfAdministeredError, MerkleUupsUnsupportedError, NonStockWrapperError, PredictionDriftError, SaltCollisionError, SignatureExpiredError, UnauthorizedRedirectError, UpgradeabilityNotAllowedError, preflightClaim, preflightCreate } from '../chunk-VW356KR3.js';
+export { MERKLE_BATCH_LIMIT, buildMerkleCampaign, buildMerkleTree, encodeInstanceRoleSplit, encryptCampaignAmounts, grantInstanceRoles, leafOf, planInstanceRoleSplit, planMerkleCampaign, rotateMerkleRoot, validateCampaignRecipients } from '../chunk-KJUNBOJQ.js';
+export { AirdropBaseClient, CLAIM_TYPEHASH, CLAIM_TYPES, ComplianceManagerClient, ConfidentialAirdropFactoryClient, EIP712_DOMAIN_NAME, EIP712_DOMAIN_VERSION, EcdsaAirdropClient, FACTORY_ROLE_CONCENTRATION_NOTE, MerkleAirdropClient, airdropFactoryAbi, complianceRoleManagerAbi, confidentialAirdropBaseAbi, createAirdropBaseClient, createComplianceManagerClient, createConfidentialAirdropFactoryClient, createEcdsaAirdropClient, createMerkleAirdropClient, ecdsaConfidentialAirdropAbi, encryptUint64, encryptUint64Batch, isAclPropagationError, merkleConfidentialAirdropAbi, resolveEncryptor, signClaimAuthorization } from '../chunk-67Q6KSVV.js';
+export { AIRDROP_CONTRACTS_COMMIT, AlreadyClaimedError, ClaimNotStartedError, ClaimWindowClosedError, ClawbackRequiresPauseError, CreateCommitmentMismatchError, DEDUP_MODE, DEPLOYMENT_MODE, DedupIdConsumedError, FeeCollectorSelfAdministeredError, GasFeeNotAcceptedError, MerkleUupsUnsupportedError, NativeRescueRequiresZeroFeeError, NonStockWrapperError, PredictionDriftError, SaltCollisionError, SignatureExpiredError, UINT96_MAX, UnauthorizedRedirectError, UnrecognisedAirdropError, UpgradeabilityNotAllowedError, preflightClaim, preflightCreate } from '../chunk-YMWMIWBP.js';
 export { ERC7984_OPERATOR_MAX_DEADLINE, revokeOperator, setOperator } from '../chunk-4TSDNZQ3.js';
 import '../chunk-ZWXJTBZO.js';
 export { erc7984OperatorAbi } from '../chunk-7VELUOMI.js';
-import '../chunk-NWFMBLSQ.js';
+import '../chunk-7KY4K4PH.js';
 import '../chunk-4RAAATVY.js';
-import '../chunk-A4DCEE33.js';
+import '../chunk-GHGF65LN.js';
 import '../chunk-ZA673I3O.js';
 import '../chunk-KWFFIJYX.js';
 export { AccessDeniedError, AlreadyInitializedError, BatchTooLargeError, ContractRevertError, DecryptionFailedError, DeploymentAddressUnavailableError, EncryptionFailedError, FeatureDisabledError, FheHandleNotAllowedError, InsufficientBalanceError, InsufficientFeeError, InsufficientGasFundsError, InvalidArgumentError, InvalidSignatureError, MissingAccountError, MissingClientError, MissingEncryptorError, MissingPublicClientError, MissingWalletClientError, NetworkError, OperatorNotApprovedError, PausedError, ReceiptEventAmbiguousError, ReceiptEventNotFoundError, ReentrancyError, RelayerUnreachableError, SigningFailedError, TokenOpsContractError, TokenOpsSdkError, TokenOpsValidationError, TransferFailedError, UnknownWriteFailureError, UnsupportedChainError, UserDecryptNotAllowedError, UserRejectedSignatureError, WalletChainMismatchError, WalletRejectedError, isTokenOpsSdkError } from '../chunk-QBJ7O2B4.js';

package/dist/fhe-airdrop/merkle-tree.d.ts

@@ -23,9 +23,9 @@ export declare function leafOf(args: LeafOfArgs): Hex;
  * The minimum a leaf must carry. `buildMerkleTree` is generic over anything wider, so a
  * caller's own fields ride along onto the entry.
  *
- * Deliberately does NOT include `boundTo`: the tree does not commit the submitter, so it
- * is not needed to build one. Pass it anyway (alongside `inputProof`) and it rides through
- * to the entry, which is what makes the result assignable to {@link CampaignEntry}.
+ * Deliberately does NOT include `inputProof`: the tree does not commit it, so it is not
+ * needed to build one. Pass it anyway and it rides through to the entry, which is what
+ * makes the result assignable to {@link CampaignEntry}.
  *
  * @alpha
  */
@@ -62,15 +62,15 @@ export interface BuiltMerkleTree<L extends MerkleLeafInput> {
  *
  * **Pure.** No relayer, no chain access, no encryptor — same leaves in, same root out.
  *
- * **The tree commits to the handle, not the amount, and not the submitter.** `_leafOf`
- * hashes `(instance, account, handle)`, so whoever encrypted must have bound each input
- * to `(instance, the intended submitter)`. This function cannot check that: it will
+ * **The tree commits to the handle, not the amount.** `_leafOf` hashes
+ * `(instance, account, handle)`, so whoever encrypted must have bound each input to
+ * `(instance, instance)`. This function cannot check that: it will
  * happily build a tree over wrongly-bound handles, and the failure surfaces at claim time
  * inside the coprocessor.
  *
  * **Extra fields ride along.** Whatever a leaf carries beyond `account` and `handle` —
- * `boundTo`, an `inputProof`, your own row id — comes back on the entry, still aligned
- * with its proof. Passing `{ account, boundTo, handle, inputProof }` therefore yields a
+ * an `inputProof`, your own row id - comes back on the entry, still aligned with its
+ * proof. Passing `{ account, handle, inputProof }` therefore yields a
  * value structurally assignable to {@link CampaignEntry}.
  *
  * @param args The instance the leaves are scoped to, and the leaves.
@@ -80,7 +80,7 @@ export interface BuiltMerkleTree<L extends MerkleLeafInput> {
  * @example
  * const { root, entries } = buildMerkleTree({
  *   instance: airdrop,
- *   leaves: [{ account: alice, boundTo: alice, handle, inputProof }],
+ *   leaves: [{ account: alice, handle, inputProof }],
  * });
  * await merkle.setMerkleRoot({ newRoot: root });
  *

package/dist/fhe-airdrop/merkle.d.ts

@@ -23,9 +23,15 @@ export interface MerkleClaimArgs extends WriteAccountOverride {
      * The proof-bearing claim entry, built by a campaign builder (`campaign.ts`).
      *
      * `entry.account` is submitted as the claim identity and selects the leaf.
-     * `entry.boundTo` must be the sending account, because the coprocessor verifies
-     * the input proof against the literal caller — the SDK checks this before the
-     * write rather than letting the transaction revert.
+     *
+     * Anyone may submit an entry - the input proof is bound to the instance itself, not to a
+     * caller. The contract pays `entry.account` (or `to`, when `entry.account` is the sender)
+     * and advances `entry.account`'s delivered total. A submission by someone else therefore
+     * settles the recipient's leaf on their behalf; the recipient's own later claim pays an
+     * encrypted zero and still costs the fee, so check
+     * {@link MerkleAirdropClient.getClaimedAmount} first. A stranger who submits first settles
+     * the leaf to `entry.account` confidentially, so a redirect or unwrap the recipient
+     * intended no longer happens.
      */
     entry: CampaignEntry;
 }
@@ -36,9 +42,9 @@ export interface MerkleClaimArgs extends WriteAccountOverride {
  */
 export interface GetClaimAmountArgs extends WriteAccountOverride {
     /**
-     * Same binding rule as {@link MerkleClaimArgs.entry}: `entry.boundTo` must be the
-     * calling account. The preview's result is ACL'd to `entry.account`, so a relayer
-     * can confirm a leaf verifies without being able to read the amount.
+     * Same entry as {@link MerkleClaimArgs.entry}, and any address may submit it. The
+     * preview's result is ACL'd to `entry.account`, so a relayer can confirm a leaf verifies
+     * without being able to read the amount.
      */
     entry: CampaignEntry;
 }
@@ -80,6 +86,10 @@ export declare class MerkleAirdropClient extends AirdropBaseClient {
      * Requires `msg.value == gasFee()` exactly — handled for you; see the
      * class TSDoc.
      *
+     * Anyone may submit an entry, and a stranger who submits first settles the recipient's
+     * leaf on their behalf; see {@link MerkleClaimArgs.entry} for what that costs the
+     * recipient, and check {@link getClaimedAmount} before offering a claim.
+     *
      * @remarks
      * There is no per-leaf consumption on this variant — replay safety is the
      * accounting itself, not a spent-flag. Re-presenting an already-settled
@@ -92,8 +102,7 @@ export declare class MerkleAirdropClient extends AirdropBaseClient {
      *
      * @throws {@link ClaimNotStartedError} before `startTime`.
      * @throws {@link ClaimWindowClosedError} after `endTime`.
-     * @throws {@link InvalidArgumentError} (`argument: "entry.boundTo"`) when the entry's proof is bound to
-     *   another address, or (`argument: "merkleProof"`) when the proof does not verify against the current root.
+     * @throws {@link InvalidArgumentError} (`argument: "merkleProof"`) when the proof does not verify against the current root.
      * @throws {@link UnauthorizedRedirectError} when a third-party submitter passes a `to` other than `entry.account`.
      * @returns The transaction hash.
      */
@@ -115,9 +124,18 @@ export declare class MerkleAirdropClient extends AirdropBaseClient {
      * refused before the write. A third party can still submit a confidential
      * {@link claim}.
      *
-     * @returns The transaction hash. The underlying ERC-20 is released later by
-     *   a separate, permissionless `finalizeUnwrap` — this hash is only the
-     *   unwrap request.
+     * **Discloses the amount immediately.** With the stock wrapper the unwrapped amount is
+     * publicly decryptable from this claim transaction (the emitted `unwrapRequestId` is its
+     * handle), so anyone can learn it at once; `finalizeUnwrap` only releases the ERC-20.
+     *
+     * Anyone may still settle this entry first through {@link claim}, after which an unwrap
+     * pays an encrypted zero; see {@link MerkleClaimArgs.entry}.
+     *
+     * @returns The transaction hash. It is only the unwrap request: the underlying
+     *   ERC-20 is released later by the wrapper's permissionless `finalizeUnwrap`. Read
+     *   its `unwrapRequestId` with {@link AirdropBaseClient.readUnwrapRequest} (or
+     *   {@link AirdropBaseClient.parseUnwrapRequest} over a receipt you hold), then
+     *   finalize with Zama's `sdk.createToken(wrapper).finalizeUnwrap(unwrapRequestId)`.
      */
     claimAndUnwrap(args: MerkleClaimArgs): Promise<Hex>;
     /**
@@ -133,6 +151,9 @@ export declare class MerkleAirdropClient extends AirdropBaseClient {
      * someone's behalf gets a valid handle it cannot read — that is the contract's intent,
      * and it is what makes a blind relayed submission possible.
      *
+     * A leaf someone else already settled previews as an encrypted zero; see
+     * {@link MerkleClaimArgs.entry}.
+     *
      * @returns `{ handle, hash }` — pass `handle` to the Zama relayer's `userDecrypt`, as `entry.account`.
      */
     getClaimAmount(args: GetClaimAmountArgs): Promise<EncryptedViewResult>;

package/dist/fhe-airdrop/react/_shared.d.ts

@@ -1,5 +1,5 @@
-import type { UseQueryOptions } from "@tanstack/react-query";
-import type { Address, PublicClient, WalletClient } from "viem";
+import type { Query, UseQueryOptions } from "@tanstack/react-query";
+import { type Address, type PublicClient, type WalletClient } from "viem";
 import { DeploymentAddressUnavailableError } from "../../core/errors.js";
 import type { SdkTelemetry } from "../../core/telemetry.js";
 import { type AirdropBaseClient } from "../airdrop-base.js";
@@ -56,6 +56,12 @@ export declare function airdropQueryKeyPrefix(params: {
     address: Address | undefined;
     fn?: string;
 }): unknown[];
+/**
+ * Per-result `staleTime` for a factory mapping that is written once at create:
+ * fresh forever once non-zero, always stale while zero (the address may be created
+ * later on a path no hook invalidation reaches). The policy {@link useIsAirdrop} uses.
+ */
+export declare function staleUntilNonZeroAddress(query: Query<Address, Error>): number;
 /**
  * The client-construction subset of every hook's options — deliberately NOT
  * generic over `TData`. Client-memo helpers (`useMemoAirdropBaseClient`,
@@ -168,13 +174,13 @@ export declare function useMemoComplianceManagerClient(opts: AirdropInstanceClie
     chainId: number | undefined;
 };
 /**
- * Per-hook overrides for {@link useMemoEcdsaAirdropClient} — `dedupMode` has no on-chain getter, so it must be supplied.
+ * Per-hook overrides for {@link useMemoEcdsaAirdropClient} - `dedupMode` is optional; read it from the chain with `useDedupMode`.
  *
  * @alpha
  */
 export type EcdsaAirdropInstanceHookOptions<TData = unknown> = AirdropInstanceHookOptions<TData> & {
-    /** @see EcdsaAirdropClientConfig.dedupMode */
-    dedupMode: DedupMode;
+    /** @deprecated Read the policy from the chain with `useDedupMode`. */
+    dedupMode?: DedupMode | undefined;
 };
 /**
  * Non-generic version of {@link EcdsaAirdropInstanceHookOptions}, for the memo helper.
@@ -182,7 +188,7 @@ export type EcdsaAirdropInstanceHookOptions<TData = unknown> = AirdropInstanceHo
  * @alpha
  */
 export type EcdsaAirdropInstanceClientOptions = AirdropInstanceClientOptions & {
-    dedupMode: DedupMode;
+    dedupMode?: DedupMode | undefined;
 };
 /** Memoize an {@link EcdsaAirdropClient} for `opts.address`. */
 export declare function useMemoEcdsaAirdropClient(opts: EcdsaAirdropInstanceClientOptions): {