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

package/dist/{chunk-LEYYG4RF.js → chunk-YMWMIWBP.js}

@@ -1,11 +1,14 @@
 import { isContractRevert } from './chunk-4RAAATVY.js';
-import { TokenOpsSdkError, InvalidArgumentError, FeatureDisabledError, UnsupportedChainError, FheHandleNotAllowedError, TransferFailedError, InsufficientBalanceError, InsufficientFeeError, PausedError, InvalidSignatureError, isTokenOpsSdkError } from './chunk-QBJ7O2B4.js';
-import { isAddressEqual, zeroAddress, isAddress, BaseError, ContractFunctionZeroDataError } from 'viem';
+import { TokenOpsSdkError, InvalidArgumentError, FeatureDisabledError, UnsupportedChainError, FheHandleNotAllowedError, TransferFailedError, InsufficientBalanceError, InsufficientFeeError, isTokenOpsSdkError, PausedError, InvalidSignatureError } from './chunk-QBJ7O2B4.js';
+import { isAddressEqual, zeroAddress, isAddress, keccak256, encodeAbiParameters, getAddress, getCreate2Address, BaseError, ContractFunctionZeroDataError } from 'viem';
 
 // src/fhe-airdrop/constants.ts
-var AIRDROP_CONTRACTS_COMMIT = "c5c12c2087f61bcd5bd1daa802563ed3cd68f002";
+var AIRDROP_CONTRACTS_COMMIT = "005980df194e0dc66053bd517e9759bd4d580047";
 var DEPLOYMENT_MODE = { clone: 0, uups: 1 };
 var DEDUP_MODE = { perAddress: 0, perDedupId: 1, both: 2, none: 3 };
+var DEDUP_MODE_BY_ORDINAL = new Map(
+  Object.keys(DEDUP_MODE).map((mode) => [DEDUP_MODE[mode], mode])
+);
 var UINT96_MAX = (1n << 96n) - 1n;
 
 // src/fhe-airdrop/errors.ts
@@ -95,6 +98,43 @@ var PredictionDriftError = class extends TokenOpsSdkError {
     );
   }
 };
+var CreateCommitmentMismatchError = class extends TokenOpsSdkError {
+  name = "CreateCommitmentMismatchError";
+  constructor(args) {
+    const rebuild = args.field === "airdrop" ? " Anything bound to the old prediction (Merkle leaves, vouchers, encrypted inputs) must be rebuilt." : "";
+    const { cause, ...context } = args;
+    super(
+      `${args.method}: the factory would deploy with ${args.field} = ${args.actual ?? "?"}, but the create committed to ${args.expected ?? "?"}. Nothing was deployed and the salt is unused; re-quote and retry.${rebuild}`,
+      { code: "TOKENOPS_CREATE_COMMITMENT_MISMATCH", cause, context }
+    );
+  }
+};
+var ClawbackRequiresPauseError = class extends TokenOpsSdkError {
+  name = "ClawbackRequiresPauseError";
+  constructor(args) {
+    super(
+      `${args.method}: withdrawConfidential is refused while the campaign is unpaused inside its claim window. Pause first (PAUSER_ROLE), or run it outside the window (before startTime or after endTime).`,
+      {
+        code: "TOKENOPS_CLAWBACK_REQUIRES_PAUSE",
+        cause: args.cause,
+        context: { method: args.method, contractAddress: args.contractAddress }
+      }
+    );
+  }
+};
+var NativeRescueRequiresZeroFeeError = class extends TokenOpsSdkError {
+  name = "NativeRescueRequiresZeroFeeError";
+  constructor(args) {
+    super(
+      `${args.method}: rescueNativeToken is only available on a zero-fee campaign; this instance charges a gas fee, so its ETH is fee revenue - use withdrawGasFee.`,
+      {
+        code: "TOKENOPS_NATIVE_RESCUE_REQUIRES_ZERO_FEE",
+        cause: args.cause,
+        context: { method: args.method, contractAddress: args.contractAddress }
+      }
+    );
+  }
+};
 var UpgradeabilityNotAllowedError = class extends TokenOpsSdkError {
   name = "UpgradeabilityNotAllowedError";
   constructor(args) {
@@ -287,12 +327,16 @@ var airdropProductMapper = (name, errArgs, ctx) => {
       return new FheHandleNotAllowedError({ ...ctx, handle });
     }
     // ---- Merkle-specific ----------------------------------------------
-    case "InvalidMerkleProof":
+    case "InvalidMerkleProof": {
+      const leaf = errArgs?.[0];
+      const merkleRoot = errArgs?.[1];
       return new InvalidArgumentError({
         method: ctx.method,
         argument: "merkleProof",
-        reason: "the contract reverted with `InvalidMerkleProof` \u2014 the proof does not verify against the current on-chain root. If the root was recently rotated, rebuild the proof against the new root."
+        reason: "the contract reverted with `InvalidMerkleProof` \u2014 the proof does not verify against the current on-chain root. If the root was recently rotated, rebuild the proof against the new root.",
+        ...leaf !== void 0 || merkleRoot !== void 0 ? { value: { leaf, merkleRoot } } : {}
       });
+    }
     case "RootImmutable":
       return new FeatureDisabledError({ ...ctx, feature: "merkleRootRotation" });
     case "ZeroAccount":
@@ -330,13 +374,10 @@ var airdropProductMapper = (name, errArgs, ctx) => {
       return new GasFeeNotAcceptedError({ ...ctx, resolvedFee, maxAcceptedGasFee });
     }
     case "GasFeeExceedsMaximum": {
-      const gasFee = errArgs?.[0];
-      const maxGasFee = errArgs?.[1];
-      return new InvalidArgumentError({
+      return gasFeeExceedsMaximumError({
         method: ctx.method,
-        argument: "gasFee",
-        reason: `exceeds the factory's own maximum${gasFee !== void 0 && maxGasFee !== void 0 ? ` (${gasFee} wei > ${maxGasFee} wei)` : ""}; \`setMaxGasFee\` is DEFAULT_ADMIN_ROLE-gated and bounds what FEE_MANAGER_ROLE may configure`,
-        value: gasFee
+        gasFee: errArgs?.[0],
+        maxGasFee: errArgs?.[1]
       });
     }
     case "ZeroUnwrapRequestId":
@@ -402,7 +443,7 @@ var airdropProductMapper = (name, errArgs, ctx) => {
         ctx,
         "complianceDelegate",
         name,
-        "required while the default compliance-delegate policy is on"
+        "the factory requires a non-zero delegate (constructor, setter and create)"
       );
     case "IndexOutOfBounds": {
       const index = errArgs?.[0];
@@ -425,6 +466,48 @@ var airdropProductMapper = (name, errArgs, ctx) => {
         value: existingAirdrop
       });
     }
+    case "PredictionMismatch":
+    case "ManagerImplementationMismatch":
+    case "ComplianceDelegateMismatch": {
+      const field = name === "PredictionMismatch" ? "airdrop" : name === "ManagerImplementationMismatch" ? "complianceManagerImpl" : "complianceDelegate";
+      return new CreateCommitmentMismatchError({
+        method: ctx.method,
+        contractAddress: ctx.contractAddress,
+        field,
+        expected: errArgs?.[0],
+        actual: errArgs?.[1]
+      });
+    }
+    case "InvalidImplementation":
+      return invalidArg(ctx, "implementation", name, void 0, errArgs?.[0]);
+    case "EndTimeInPast": {
+      const endTime = numberArg(errArgs?.[0]);
+      const currentTime = numberArg(errArgs?.[1]);
+      return invalidArg(
+        ctx,
+        "endTime",
+        name,
+        endTime !== void 0 && currentTime !== void 0 ? `endTime ${endTime} is not after the chain time ${currentTime}` : void 0,
+        endTime !== void 0 || currentTime !== void 0 ? { endTime, currentTime } : void 0
+      );
+    }
+    case "InvalidDuration": {
+      const fromTime = numberArg(errArgs?.[0]);
+      const toTime = numberArg(errArgs?.[1]);
+      return invalidArg(
+        ctx,
+        "duration",
+        name,
+        fromTime !== void 0 && toTime !== void 0 ? `${toTime} does not come after ${fromTime}` : void 0,
+        fromTime !== void 0 || toTime !== void 0 ? { fromTime, toTime } : void 0
+      );
+    }
+    case "UninitializedHandle":
+      return invalidArg(ctx, "handle", name);
+    case "ClawbackRequiresPause":
+      return new ClawbackRequiresPauseError(ctx);
+    case "NativeRescueRequiresZeroFee":
+      return new NativeRescueRequiresZeroFeeError(ctx);
     case "ZeroSigner":
       return invalidArg(ctx, "signer", name);
     case "ZeroMerkleRoot":
@@ -432,7 +515,7 @@ var airdropProductMapper = (name, errArgs, ctx) => {
         ctx,
         "merkleRoot",
         name,
-        "a zero root is only permitted when `isMerkleRootMutable` is true"
+        "a zero root is permitted only at create on a mutable-root campaign, and never as a rotation target"
       );
     // ---- compliance manager clone (`ComplianceRoleManager`) --------------
     case "ZeroAirdrop":
@@ -472,15 +555,26 @@ var airdropProductMapper = (name, errArgs, ctx) => {
       return void 0;
   }
 };
-function invalidArg(ctx, argument, revertName, detail) {
+function gasFeeExceedsMaximumError(args) {
+  const { gasFee, maxGasFee } = args;
+  return new InvalidArgumentError({
+    method: args.method,
+    argument: "gasFee",
+    reason: `exceeds the factory's own maximum${gasFee !== void 0 && maxGasFee !== void 0 ? ` (${gasFee} wei > ${maxGasFee} wei)` : ""}; \`setMaxGasFee\` is DEFAULT_ADMIN_ROLE-gated and bounds what FEE_MANAGER_ROLE may configure`,
+    value: gasFee
+  });
+}
+function invalidArg(ctx, argument, revertName, detail, value) {
   const suffix = detail ? ` ${detail}.` : "";
   return new InvalidArgumentError({
     method: ctx.method,
     argument,
-    reason: `the contract reverted with \`${revertName}\`.${suffix}`
+    reason: `the contract reverted with \`${revertName}\`.${suffix}`,
+    ...value !== void 0 ? { value } : {}
   });
 }
 function numberArg(value) {
+  if (typeof value === "number") return value;
   return typeof value === "bigint" ? Number(value) : void 0;
 }
 var SUPPORTED_CHAIN_IDS = [1, 11155111, 31337];
@@ -547,9 +641,12 @@ function assertMaxAcceptedGasFeeRange(value, method) {
     });
   }
 }
-async function assertGasFeeAccepted(args) {
-  assertMaxAcceptedGasFeeRange(args.maxAcceptedGasFee, args.method);
-  const resolvedFee = await args.factory.resolveGasFee(args.creator);
+function assertWithinCeiling(method, resolvedFee, maxGasFee) {
+  if (resolvedFee > maxGasFee) {
+    throw gasFeeExceedsMaximumError({ method, gasFee: resolvedFee, maxGasFee });
+  }
+}
+function assertResolvedFeeAccepted(args, resolvedFee) {
   if (resolvedFee <= args.maxAcceptedGasFee) return;
   throw new GasFeeNotAcceptedError({
     method: args.method,
@@ -558,6 +655,15 @@ async function assertGasFeeAccepted(args) {
     maxAcceptedGasFee: args.maxAcceptedGasFee
   });
 }
+async function assertCreateGasFee(args) {
+  assertMaxAcceptedGasFeeRange(args.maxAcceptedGasFee, args.method);
+  const [resolvedFee, maxGasFee] = await Promise.all([
+    args.factory.resolveGasFee(args.creator),
+    args.factory.maxGasFee()
+  ]);
+  assertWithinCeiling(args.method, resolvedFee, maxGasFee);
+  assertResolvedFeeAccepted(args, resolvedFee);
+}
 function assertPredictionFresh(args) {
   if (args.initCodeHashBefore.toLowerCase() === args.initCodeHashAfter.toLowerCase()) return;
   throw new PredictionDriftError({
@@ -568,6 +674,112 @@ function assertPredictionFresh(args) {
     predictedAddress: args.predictedAddress
   });
 }
+var END_TIME_MARGIN_SECONDS = 60;
+function invalidCreateParam(method, argument, revertName, reason, value) {
+  return new InvalidArgumentError({
+    method,
+    argument,
+    reason: `${reason}; the instance initializer reverts \`${revertName}\``,
+    value
+  });
+}
+function assertCreateParamsWellFormed(args, method) {
+  const { common } = args.params;
+  if (isAddressEqual(common.token, zeroAddress)) {
+    throw invalidCreateParam(
+      method,
+      "common.token",
+      "ZeroToken",
+      "is the zero address",
+      common.token
+    );
+  }
+  const now = Math.floor(Date.now() / 1e3);
+  if (common.endTime <= now + END_TIME_MARGIN_SECONDS) {
+    throw invalidCreateParam(
+      method,
+      "common.endTime",
+      "EndTimeInPast",
+      `is not at least ${END_TIME_MARGIN_SECONDS}s in the future`,
+      common.endTime
+    );
+  }
+  if (common.startTime > common.endTime) {
+    throw invalidCreateParam(
+      method,
+      "common.startTime",
+      "InvalidStartTime",
+      "is after `endTime`",
+      common.startTime
+    );
+  }
+  if (common.startTime === common.endTime) {
+    throw invalidCreateParam(
+      method,
+      "common.startTime",
+      "InvalidDuration",
+      "equals `endTime`, leaving a zero-length claim window",
+      common.startTime
+    );
+  }
+  if (args.variant === "merkle") {
+    const { merkleRoot, isMerkleRootMutable } = args.params;
+    if (!isMerkleRootMutable && BigInt(merkleRoot) === 0n) {
+      throw invalidCreateParam(
+        method,
+        "merkleRoot",
+        "ZeroMerkleRoot",
+        "is zero on an immutable-root campaign, so no claim could ever verify",
+        merkleRoot
+      );
+    }
+  } else if (isAddressEqual(args.params.signer, zeroAddress)) {
+    throw invalidCreateParam(
+      method,
+      "signer",
+      "ZeroSigner",
+      "is the zero address",
+      args.params.signer
+    );
+  }
+}
+function resolvePlannedCreate(args) {
+  const { method, params, expected, expectedInitCodeHash, plan } = args;
+  if (!plan) return { expected, expectedInitCodeHash };
+  if (params.merkleRoot.toLowerCase() !== plan.root.toLowerCase()) {
+    throw new InvalidArgumentError({
+      method,
+      argument: "params.merkleRoot",
+      reason: "differs from plan.root; the plan's entries verify only against the root they were built into",
+      value: params.merkleRoot
+    });
+  }
+  if (expected?.airdrop !== void 0 && !isAddressEqual(expected.airdrop, plan.predictedAddress)) {
+    throw new InvalidArgumentError({
+      method,
+      argument: "expected.airdrop",
+      reason: "differs from plan.predictedAddress; a plan's leaves are bound to its predicted address, so the two cannot name different instances",
+      value: expected.airdrop
+    });
+  }
+  if (expectedInitCodeHash !== void 0 && expectedInitCodeHash.toLowerCase() !== plan.initCodeHashAfter.toLowerCase()) {
+    throw new InvalidArgumentError({
+      method,
+      argument: "expectedInitCodeHash",
+      reason: "differs from plan.initCodeHashAfter; pass one or the other",
+      value: expectedInitCodeHash
+    });
+  }
+  return {
+    expected: { ...definedFields(expected), airdrop: plan.predictedAddress },
+    expectedInitCodeHash: plan.initCodeHashAfter
+  };
+}
+var COMMITMENT_FIELDS = ["airdrop", "complianceManagerImpl", "complianceDelegate"];
+function definedFields(pinned) {
+  if (!pinned) return {};
+  return Object.fromEntries(Object.entries(pinned).filter(([, value]) => value !== void 0));
+}
 async function preflightCreate(args) {
   const method = args.variant === "merkle" ? "createMerkleAirdrop" : "createEcdsaAirdrop";
   const blockers = [];
@@ -580,15 +792,34 @@ async function preflightCreate(args) {
     () => assertMaxAcceptedGasFeeRange(args.params.common.maxAcceptedGasFee, method)
   );
   if (!encodable) return { ready: false, blockers };
-  await collectAsync(
-    blockers,
-    () => assertGasFeeAccepted({
-      factory: args.factory,
-      creator: args.creator,
-      maxAcceptedGasFee: args.params.common.maxAcceptedGasFee,
-      method
-    })
-  );
+  collect(blockers, () => assertCreateParamsWellFormed(args, method));
+  let pins = { expected: args.expected, expectedInitCodeHash: args.expectedInitCodeHash };
+  if (args.variant === "merkle") {
+    const { params, plan } = args;
+    collect(blockers, () => {
+      pins = resolvePlannedCreate({ method, params, ...pins, plan });
+    });
+  }
+  const { expected, expectedInitCodeHash } = pins;
+  await collectAsync(blockers, async () => {
+    const [resolvedFee, maxGasFee] = await Promise.all([
+      args.factory.resolveGasFee(args.creator),
+      args.factory.maxGasFee()
+    ]);
+    collect(blockers, () => assertWithinCeiling(method, resolvedFee, maxGasFee));
+    collect(
+      blockers,
+      () => assertResolvedFeeAccepted(
+        {
+          factory: args.factory,
+          creator: args.creator,
+          maxAcceptedGasFee: args.params.common.maxAcceptedGasFee,
+          method
+        },
+        resolvedFee
+      )
+    );
+  });
   const predictArgs = {
     mode: args.mode,
     deployer: args.creator,
@@ -620,7 +851,7 @@ async function preflightCreate(args) {
     blockers,
     () => assertSaltAvailable({
       publicClient: args.factory.publicClient,
-      predictedAddress,
+      predictedAddress: expected?.airdrop ?? predictedAddress,
       variant: args.variant,
       mode: args.mode,
       deployer: args.creator,
@@ -628,19 +859,53 @@ async function preflightCreate(args) {
       method
     })
   );
-  if (args.expectedInitCodeHash !== void 0) {
+  if (expectedInitCodeHash !== void 0) {
+    const initCodeHashBefore = expectedInitCodeHash;
     collect(
       blockers,
       () => assertPredictionFresh({
         variant: args.variant,
-        initCodeHashBefore: args.expectedInitCodeHash,
+        initCodeHashBefore,
         initCodeHashAfter: liveInitCodeHash,
-        predictedAddress,
+        predictedAddress: expected?.airdrop ?? predictedAddress,
         method
       })
     );
   }
-  return { ready: blockers.length === 0, blockers };
+  const pinned = Object.keys(definedFields(expected)).length > 0;
+  let fresh;
+  try {
+    fresh = await args.factory.quoteCreateCommitments({
+      ...args.variant === "merkle" ? { variant: "merkle", params: args.params } : { variant: "ecdsa", params: args.params },
+      mode: args.mode,
+      deployer: args.creator,
+      userSalt: args.userSalt,
+      expected: { airdrop: predictedAddress }
+    });
+  } catch (err) {
+    if (pinned) {
+      if (!isTokenOpsSdkError(err)) throw err;
+      blockers.push(err);
+    }
+  }
+  let commitments;
+  if (fresh) {
+    commitments = { ...fresh, ...definedFields(expected) };
+    for (const field of COMMITMENT_FIELDS) {
+      const pinned2 = expected?.[field];
+      if (pinned2 === void 0 || isAddressEqual(pinned2, fresh[field])) continue;
+      blockers.push(
+        new CreateCommitmentMismatchError({
+          method,
+          contractAddress: args.factory.address,
+          field,
+          expected: pinned2,
+          actual: fresh[field]
+        })
+      );
+    }
+  }
+  return { ready: blockers.length === 0, blockers, ...commitments ? { commitments } : {} };
 }
 async function assertKnownAirdrop(args) {
   if (args.factory.chainId !== args.chainId) {
@@ -659,10 +924,9 @@ async function assertKnownAirdrop(args) {
   });
 }
 function assertMerkleClaimIdentity(args) {
-  const { method, account, submitter, boundTo, to, entrypoint = "claim" } = args;
+  const { method, account, submitter, to, entrypoint = "claim" } = args;
   for (const [argument, value] of [
     ["account", account],
-    ["entry.boundTo", boundTo],
     ["to", to],
     ["submitter", submitter]
   ]) {
@@ -682,13 +946,6 @@ function assertMerkleClaimIdentity(args) {
       reason: "is the zero address; the claim identity is mandatory and is never defaulted from the caller"
     });
   }
-  if (boundTo !== void 0 && !isAddressEqual(boundTo, submitter)) {
-    throw new InvalidArgumentError({
-      method,
-      argument: "entry.boundTo",
-      reason: `is ${boundTo}, but this transaction is sent from ${submitter}; the FHE input proof is bound to the sender, so only ${boundTo} can submit this entry`
-    });
-  }
   if (entrypoint === "claimAndUnwrap") {
     if (!isAddressEqual(account, submitter)) {
       throw new InvalidArgumentError({
@@ -807,5 +1064,21 @@ async function collectAsync(blockers, run) {
     blockers.push(err);
   }
 }
+var CLONE_INIT_CODE_PREFIX = "0x3d602d80600a3d3981f3363d3d373d3d3d363d73";
+var CLONE_INIT_CODE_SUFFIX = "5af43d82803e903d91602b57fd5bf3";
+function predictComplianceManagerClone(args) {
+  const salt = keccak256(
+    encodeAbiParameters(
+      [{ type: "address" }, { type: "string" }],
+      [getAddress(args.airdrop), "compliance"]
+    )
+  );
+  const initCode = `${CLONE_INIT_CODE_PREFIX}${getAddress(args.managerImplementation).slice(2).toLowerCase()}${CLONE_INIT_CODE_SUFFIX}`;
+  return getCreate2Address({
+    from: getAddress(args.factory),
+    salt,
+    bytecodeHash: keccak256(initCode)
+  });
+}
 
-export { AIRDROP_CONTRACTS_COMMIT, AlreadyClaimedError, ClaimNotStartedError, ClaimWindowClosedError, DEDUP_MODE, DEPLOYMENT_MODE, DedupIdConsumedError, FeeCollectorSelfAdministeredError, GasFeeNotAcceptedError, MerkleUupsUnsupportedError, NonStockWrapperError, PredictionDriftError, SaltCollisionError, SignatureExpiredError, UINT96_MAX, UnauthorizedRedirectError, UnrecognisedAirdropError, UpgradeabilityNotAllowedError, airdropProductMapper, assertGasFeeAccepted, assertMerkleClaimIdentity, assertMerkleModeSupported, assertPredictionFresh, assertSaltAvailable, assertStockWrapper, assertSupportedChain, preflightClaim, preflightCreate };
+export { AIRDROP_CONTRACTS_COMMIT, AlreadyClaimedError, ClaimNotStartedError, ClaimWindowClosedError, ClawbackRequiresPauseError, CreateCommitmentMismatchError, DEDUP_MODE, DEDUP_MODE_BY_ORDINAL, DEPLOYMENT_MODE, DedupIdConsumedError, FeeCollectorSelfAdministeredError, GasFeeNotAcceptedError, MerkleUupsUnsupportedError, NativeRescueRequiresZeroFeeError, NonStockWrapperError, PredictionDriftError, SaltCollisionError, SignatureExpiredError, UINT96_MAX, UnauthorizedRedirectError, UnrecognisedAirdropError, UpgradeabilityNotAllowedError, airdropProductMapper, assertCreateGasFee, assertMerkleClaimIdentity, assertMerkleModeSupported, assertPredictionFresh, assertSaltAvailable, assertStockWrapper, assertSupportedChain, predictComplianceManagerClone, preflightClaim, preflightCreate, resolvePlannedCreate };

package/dist/core/addresses.d.ts

@@ -15,16 +15,16 @@ export declare const DEPLOYED_ADDRESSES: {
     };
     readonly fheAirdrop: {
         readonly airdropFactory: {
-            readonly 11155111: "0xA10ff713cfeE5348313Cda0B2CA1b190A1194cab";
+            readonly 11155111: "0xD5906f366Ff50909F403c8EDfDe680015563046a";
         };
         readonly ecdsaImplementation: {
-            readonly 11155111: "0x8d4E8F379f73D5488a76B6C3CC8a2fD489936BDe";
+            readonly 11155111: "0xE27A2aF9dCBda2B06535d5502e6dbB90364b43bA";
         };
         readonly merkleImplementation: {
-            readonly 11155111: "0x4B4F43Ed9aB3F9D10468b59C03d14f55A9d4E82F";
+            readonly 11155111: "0xccea0A916dBe5aB939915a402942EE6AFDcD505E";
         };
         readonly complianceManagerImplementation: {
-            readonly 11155111: "0x14bdE71e6b32b50dF1a5Dca1bccD150a319168e2";
+            readonly 11155111: "0x076719596c21F0Eb358AC45649C3db387D98FADf";
         };
     };
     readonly fheDisperse: {

package/dist/core/errors.d.ts

@@ -13,7 +13,7 @@ declare const TOKENOPS_SDK_ERROR_BRAND: unique symbol;
  * human-readable and may evolve between versions.
  * @public
  */
-export type TokenOpsSdkErrorCode = "TOKENOPS_UNSUPPORTED_CHAIN" | "TOKENOPS_DEPLOYMENT_ADDRESS_UNAVAILABLE" | "TOKENOPS_MISSING_PUBLIC_CLIENT" | "TOKENOPS_MISSING_WALLET_CLIENT" | "TOKENOPS_MISSING_ACCOUNT" | "TOKENOPS_MISSING_ENCRYPTOR" | "TOKENOPS_MISSING_CLIENT" | "TOKENOPS_INVALID_ARGUMENT" | "TOKENOPS_RECEIPT_EVENT_NOT_FOUND" | "TOKENOPS_RECEIPT_EVENT_AMBIGUOUS" | "TOKENOPS_CONTRACT_REVERT" | "TOKENOPS_PAUSED" | "TOKENOPS_ACCESS_DENIED" | "TOKENOPS_OPERATOR_NOT_APPROVED" | "TOKENOPS_INSUFFICIENT_FEE" | "TOKENOPS_INSUFFICIENT_BALANCE" | "TOKENOPS_BATCH_TOO_LARGE" | "TOKENOPS_FEATURE_DISABLED" | "TOKENOPS_TRANSFER_FAILED" | "TOKENOPS_FHE_HANDLE_NOT_ALLOWED" | "TOKENOPS_ALREADY_INITIALIZED" | "TOKENOPS_REENTRANCY" | "TOKENOPS_INVALID_SIGNATURE" | "TOKENOPS_WALLET_REJECTED" | "TOKENOPS_WALLET_CHAIN_MISMATCH" | "TOKENOPS_NETWORK_ERROR" | "TOKENOPS_INSUFFICIENT_GAS_FUNDS" | "TOKENOPS_UNKNOWN_WRITE_FAILURE" | "TOKENOPS_USER_REJECTED" | "TOKENOPS_SIGNING_FAILED" | "TOKENOPS_RELAYER_UNREACHABLE" | "TOKENOPS_ENCRYPTION_FAILED" | "TOKENOPS_DECRYPTION_FAILED" | "TOKENOPS_USER_DECRYPT_NOT_ALLOWED" | "TOKENOPS_VESTING_NOT_FOUND" | "TOKENOPS_NOT_RECIPIENT" | "TOKENOPS_CLAIM_LOCKED" | "TOKENOPS_VESTING_REVOKED" | "TOKENOPS_NOT_REVOCABLE" | "TOKENOPS_VESTING_EXPIRED" | "TOKENOPS_TRANSFER_ALREADY_PENDING" | "TOKENOPS_NO_PENDING_TRANSFER" | "TOKENOPS_NOT_PENDING_RECIPIENT" | "TOKENOPS_TRANSFER_EXPIRED" | "TOKENOPS_ALREADY_CLAIMED" | "TOKENOPS_CLAIM_NOT_STARTED" | "TOKENOPS_CLAIM_WINDOW_CLOSED" | "TOKENOPS_NOT_REGISTERED" | "TOKENOPS_ALREADY_REGISTERED" | "TOKENOPS_SUBWALLETS_NOT_APPROVED" | "TOKENOPS_SINGLETON_NOT_APPROVED" | "TOKENOPS_FAUCET_SUPPLY_EXHAUSTED" | "TOKENOPS_MERKLE_UUPS_UNSUPPORTED" | "TOKENOPS_NON_STOCK_WRAPPER" | "TOKENOPS_UPGRADEABILITY_NOT_ALLOWED" | "TOKENOPS_FEE_COLLECTOR_SELF_ADMINISTERED" | "TOKENOPS_DEDUP_ID_CONSUMED" | "TOKENOPS_SIGNATURE_EXPIRED" | "TOKENOPS_SALT_COLLISION" | "TOKENOPS_PREDICTION_DRIFT" | "TOKENOPS_UNAUTHORIZED_REDIRECT" | "TOKENOPS_GAS_FEE_NOT_ACCEPTED" | "TOKENOPS_UNRECOGNISED_AIRDROP";
+export type TokenOpsSdkErrorCode = "TOKENOPS_UNSUPPORTED_CHAIN" | "TOKENOPS_DEPLOYMENT_ADDRESS_UNAVAILABLE" | "TOKENOPS_MISSING_PUBLIC_CLIENT" | "TOKENOPS_MISSING_WALLET_CLIENT" | "TOKENOPS_MISSING_ACCOUNT" | "TOKENOPS_MISSING_ENCRYPTOR" | "TOKENOPS_MISSING_CLIENT" | "TOKENOPS_INVALID_ARGUMENT" | "TOKENOPS_RECEIPT_EVENT_NOT_FOUND" | "TOKENOPS_RECEIPT_EVENT_AMBIGUOUS" | "TOKENOPS_CONTRACT_REVERT" | "TOKENOPS_PAUSED" | "TOKENOPS_ACCESS_DENIED" | "TOKENOPS_OPERATOR_NOT_APPROVED" | "TOKENOPS_INSUFFICIENT_FEE" | "TOKENOPS_INSUFFICIENT_BALANCE" | "TOKENOPS_BATCH_TOO_LARGE" | "TOKENOPS_FEATURE_DISABLED" | "TOKENOPS_TRANSFER_FAILED" | "TOKENOPS_FHE_HANDLE_NOT_ALLOWED" | "TOKENOPS_ALREADY_INITIALIZED" | "TOKENOPS_REENTRANCY" | "TOKENOPS_INVALID_SIGNATURE" | "TOKENOPS_WALLET_REJECTED" | "TOKENOPS_WALLET_CHAIN_MISMATCH" | "TOKENOPS_NETWORK_ERROR" | "TOKENOPS_INSUFFICIENT_GAS_FUNDS" | "TOKENOPS_UNKNOWN_WRITE_FAILURE" | "TOKENOPS_UNEXPECTED_CONTRACT_RESPONSE" | "TOKENOPS_USER_REJECTED" | "TOKENOPS_SIGNING_FAILED" | "TOKENOPS_RELAYER_UNREACHABLE" | "TOKENOPS_ENCRYPTION_FAILED" | "TOKENOPS_DECRYPTION_FAILED" | "TOKENOPS_USER_DECRYPT_NOT_ALLOWED" | "TOKENOPS_VESTING_NOT_FOUND" | "TOKENOPS_NOT_RECIPIENT" | "TOKENOPS_CLAIM_LOCKED" | "TOKENOPS_VESTING_REVOKED" | "TOKENOPS_NOT_REVOCABLE" | "TOKENOPS_VESTING_EXPIRED" | "TOKENOPS_TRANSFER_ALREADY_PENDING" | "TOKENOPS_NO_PENDING_TRANSFER" | "TOKENOPS_NOT_PENDING_RECIPIENT" | "TOKENOPS_TRANSFER_EXPIRED" | "TOKENOPS_ALREADY_CLAIMED" | "TOKENOPS_CLAIM_NOT_STARTED" | "TOKENOPS_CLAIM_WINDOW_CLOSED" | "TOKENOPS_NOT_REGISTERED" | "TOKENOPS_ALREADY_REGISTERED" | "TOKENOPS_SUBWALLETS_NOT_APPROVED" | "TOKENOPS_SINGLETON_NOT_APPROVED" | "TOKENOPS_FAUCET_SUPPLY_EXHAUSTED" | "TOKENOPS_MERKLE_UUPS_UNSUPPORTED" | "TOKENOPS_NON_STOCK_WRAPPER" | "TOKENOPS_UPGRADEABILITY_NOT_ALLOWED" | "TOKENOPS_FEE_COLLECTOR_SELF_ADMINISTERED" | "TOKENOPS_DEDUP_ID_CONSUMED" | "TOKENOPS_SIGNATURE_EXPIRED" | "TOKENOPS_SALT_COLLISION" | "TOKENOPS_CREATE_COMMITMENT_MISMATCH" | "TOKENOPS_CLAWBACK_REQUIRES_PAUSE" | "TOKENOPS_NATIVE_RESCUE_REQUIRES_ZERO_FEE" | "TOKENOPS_PREDICTION_DRIFT" | "TOKENOPS_UNAUTHORIZED_REDIRECT" | "TOKENOPS_GAS_FEE_NOT_ACCEPTED" | "TOKENOPS_UNRECOGNISED_AIRDROP";
 /** @public */
 export interface TokenOpsSdkErrorInit {
     code: TokenOpsSdkErrorCode;

package/dist/core/index.d.ts

@@ -2,6 +2,7 @@ export * from "./addresses.js";
 export * from "./brands.js";
 export * from "./chains.js";
 export * from "./errors.js";
+export * from "./pending.js";
 export * from "./preflight.js";
 export * from "./types.js";
 export { type SdkTelemetry, type SdkTelemetryTags } from "./telemetry.js";

package/dist/core/pending.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Marks a write result returned before its transaction was observed executing, because the
+ * write was sent with `waitForReceipt: false` (a Safe / multisig signer whose submission is a
+ * `safeTxHash` that never mines until threshold owners co-sign).
+ *
+ * Every receipt-free result in the SDK extends this, and every mined counterpart extends
+ * {@link MinedWrite}, so one check narrows a result from any product:
+ *
+ * @example
+ * const result = await factory.createManager({ token, userSalt, waitForReceipt });
+ * if (result.pending) return trackSafeTx(result.hash);
+ * openManager(result.manager); // `Address`
+ *
+ * @public
+ */
+export interface PendingWrite {
+    /** The transaction has not been observed executing. */
+    pending: true;
+}
+/**
+ * The mined counterpart of {@link PendingWrite}: the receipt was read and every receipt-derived
+ * field is set. `pending` is never present; it is declared so `if (result.pending)` compiles on
+ * the union.
+ *
+ * @public
+ */
+export interface MinedWrite {
+    /** Never set on a mined result. */
+    pending?: never;
+}
+/**
+ * The `waitForReceipt` option of every receipt-free write. It is kept off the base `*Args`
+ * types, so a value typed as one of them still resolves to the mined overload; the methods
+ * take `Args & ReceiptMode<...>` instead.
+ *
+ * - `ReceiptMode<true>`: omitted or `true`. The SDK waits for the receipt and returns the
+ *   mined result ({@link MinedWrite}) with every receipt-derived field set.
+ * - `ReceiptMode<false>`: `false`, for a Safe / multisig signer whose submission returns a
+ *   `safeTxHash` that never mines until threshold owners co-sign. The call returns on
+ *   submission with a {@link PendingWrite} result; read the executed transaction's logs for
+ *   anything the receipt would have supplied.
+ * - `ReceiptMode` (`boolean`): a runtime value, as hooks and dynamic callers pass. The result
+ *   is the union of the two, narrowed by `pending`.
+ *
+ * @example
+ * async function deploy(args: CreateManagerArgs & ReceiptMode) {
+ *   const result = await factory.createManager(args);
+ *   return result.pending ? undefined : result.manager;
+ * }
+ *
+ * @public
+ */
+export type ReceiptMode<W extends boolean = boolean> = [W] extends [false] ? {
+    waitForReceipt: false;
+} : {
+    waitForReceipt?: W | undefined;
+};

package/dist/core/version.d.ts

@@ -12,4 +12,4 @@
  * Keep in sync with `package.json` via the `prepublishOnly` gate. If the two
  * drift, telemetry funnels will report a stale version.
  */
-export declare const SDK_VERSION = "1.0.0";
+export declare const SDK_VERSION = "2.0.0-alpha.4";

package/dist/fhe/operators.d.ts

@@ -73,9 +73,10 @@ export interface SetOperatorArgs {
     /** ERC-7984 token contract address. */
     token: Address;
     /**
-     * Address being authorized to pull tokens — typically a manager clone
-     * (`/fhe-vesting`), an airdrop clone (`/fhe-airdrop`), or the disperse
-     * singleton (`/fhe-disperse`).
+     * Address being authorized to pull tokens - typically a manager clone
+     * (`/fhe-vesting`), the airdrop FACTORY (`/fhe-airdrop`, which pulls the pool on
+     * every create-and-fund and `fundAirdrop`), or the disperse singleton
+     * (`/fhe-disperse`).
      */
     spender: Address;
     /**
@@ -147,7 +148,7 @@ export interface RevokeOperatorArgs {
     token: Address;
     /**
      * Address whose operator authorization should be revoked — typically a
-     * stale manager clone (`/fhe-vesting`), a closed airdrop clone
+     * stale manager clone (`/fhe-vesting`), a factory you no longer fund through
      * (`/fhe-airdrop`), or a singleton no longer in use (`/fhe-disperse`).
      */
     spender: Address;
@@ -208,7 +209,7 @@ export interface IsOperatorArgs {
     holder: Address;
     /**
      * Address whose operator status is being checked — typically a manager
-     * clone (`/fhe-vesting`), an airdrop clone/factory (`/fhe-airdrop`), or
+     * clone (`/fhe-vesting`), the airdrop factory (`/fhe-airdrop`), or
      * the disperse singleton (`/fhe-disperse`).
      */
     spender: Address;

package/dist/fhe/types.d.ts

@@ -36,7 +36,7 @@ export interface EncryptedInputs {
  * the contract emits `FHE.allow(handle, grantee)` (usually `msg.sender`) and the SDK extracts
  * `handle` from the receipt's ACL `Allowed` event.
  *
- * Pass `handle` to the Zama relayer's `userDecrypt` to obtain the plaintext — AS THE GRANTEE. Most entrypoints grant the caller, but not all: `MerkleAirdropClient.getClaimAmount` grants the entry's `account`, so a third-party submitter receives a valid handle it is not authorised to read.
+ * Pass `handle` to the Zama relayer's `userDecrypt` to obtain the plaintext - AS THE GRANTEE. Most entrypoints grant the caller, but not all: `MerkleAirdropClient.getClaimAmount` grants the entry's `account`, so a third-party sender (any address may submit a Merkle entry) receives a valid handle it is not authorised to read.
  * `hash` is the tx that committed the persistent ACL grant — surface it if
  * your UI needs to show the receipt.
  * @public