@tokenops/sdk 1.0.0

package/dist/chunk-ZHFLRKFY.js

@@ -0,0 +1,41 @@
+import { ConfidentialAirdropFactoryClient, confidentialAirdropFactoryAbi } from './chunk-UOG4PJL5.js';
+
+// src/fhe-airdrop/advanced/factory-advanced.ts
+var ConfidentialAirdropFactoryAdvancedClient = class extends ConfidentialAirdropFactoryClient {
+  /**
+   * Compute the deterministic CREATE2 address for an airdrop clone without
+   * deploying it.
+   *
+   * Note: `gasFee` must match what the factory would charge the deployer at
+   * deploy time (custom fee if set, otherwise `defaultGasFee`). Use
+   * `getCustomFee(deployer)` and `defaultGasFee()` to resolve it correctly —
+   * a mismatch silently targets the wrong address.
+   *
+   * For the common "deploy a clone and learn its address" flow, use the
+   * headline `factory.createConfidentialAirdrop` instead — it parses the
+   * address from the tx receipt's `ConfidentialAirdropCreated` event without
+   * any `gasFee` guessing.
+   */
+  async predictAirdropAddress(args) {
+    return this.publicClient.readContract({
+      address: this.address,
+      abi: confidentialAirdropFactoryAbi,
+      functionName: "predictAirdropAddress",
+      args: [toAbiParams(args.params), args.userSalt, args.deployer, args.gasFee]
+    });
+  }
+};
+function createConfidentialAirdropFactoryAdvancedClient(config) {
+  return new ConfidentialAirdropFactoryAdvancedClient(config);
+}
+function toAbiParams(params) {
+  return {
+    token: params.token,
+    startTime: params.startTimestamp,
+    endTime: params.endTimestamp,
+    canExtendClaimWindow: params.canExtendClaimWindow,
+    admin: params.admin
+  };
+}
+
+export { ConfidentialAirdropFactoryAdvancedClient, createConfidentialAirdropFactoryAdvancedClient };

package/dist/chunk-ZXCOJY2Z.js

@@ -0,0 +1,87 @@
+import { TokenOpsSdkError, InvalidArgumentError, DecryptionFailedError, EncryptionFailedError, RelayerUnreachableError, SigningFailedError, UserRejectedSignatureError, UserDecryptNotAllowedError } from './chunk-IVE3QEGD.js';
+
+// src/core/zama-error-mapper.ts
+function mapZamaError(error, args) {
+  if (error instanceof TokenOpsSdkError) return error;
+  const zama = readZamaError(error);
+  if (zama?.code) {
+    switch (zama.code) {
+      case "SIGNING_REJECTED":
+        return new UserRejectedSignatureError({ ...args, cause: error });
+      case "SIGNING_FAILED":
+        return new SigningFailedError({ ...args, cause: error });
+      case "RELAYER_REQUEST_FAILED":
+        return new RelayerUnreachableError({
+          ...args,
+          statusCode: zama.statusCode,
+          cause: error
+        });
+      case "ENCRYPTION_FAILED":
+        return new EncryptionFailedError({ ...args, cause: error });
+      case "DECRYPTION_FAILED":
+        return new DecryptionFailedError({ ...args, cause: error });
+      case "CONFIGURATION":
+        return new InvalidArgumentError({
+          method: args.method,
+          argument: "config",
+          reason: "Zama SDK configuration is invalid (chain id, type, or signer state).",
+          cause: error
+        });
+    }
+  }
+  const message = readMessage(error);
+  if (message) {
+    if (USER_REJECTION_PATTERNS.some((pat) => pat.test(message))) {
+      return new UserRejectedSignatureError({ ...args, cause: error });
+    }
+    if (USER_DECRYPT_NOT_ALLOWED_PATTERNS.some((pat) => pat.test(message))) {
+      return new UserDecryptNotAllowedError({ method: args.method, cause: error });
+    }
+    if (INVALID_INPUT_PATTERNS.some((pat) => pat.test(message))) {
+      return new InvalidArgumentError({
+        method: args.method,
+        argument: "input",
+        reason: "encrypted input value rejected by FHE SDK \u2014 see `error.cause` for details",
+        cause: error
+      });
+    }
+  }
+  return args.operation === "encrypt" ? new EncryptionFailedError({ ...args, cause: error }) : new DecryptionFailedError({ ...args, cause: error });
+}
+function readZamaError(err) {
+  if (typeof err !== "object" || err === null) return void 0;
+  const e = err;
+  const code = typeof e.code === "string" ? e.code : void 0;
+  const statusCode = typeof e.statusCode === "number" ? e.statusCode : void 0;
+  const message = typeof e.message === "string" ? e.message : void 0;
+  if (code === void 0 && statusCode === void 0) return void 0;
+  return { code, statusCode, message };
+}
+function readMessage(err) {
+  if (err instanceof Error) return err.message;
+  if (typeof err === "object" && err !== null && typeof err.message === "string") {
+    return err.message;
+  }
+  return void 0;
+}
+var USER_REJECTION_PATTERNS = [
+  /user rejected/i,
+  /user denied/i,
+  /4001/
+  // EIP-1193 error code
+];
+var USER_DECRYPT_NOT_ALLOWED_PATTERNS = [
+  /not authorized to user decrypt/i,
+  /not authorized to decrypt/i,
+  /is not allowed for public decryption/i
+];
+var INVALID_INPUT_PATTERNS = [
+  /invalid unsigned integer value/i,
+  /exceeds the maximum allowed value/i,
+  /invalid address value/i,
+  /chainId exceeds maximum/i,
+  /packing more than .* in a single input/i,
+  /fhevm assertion failed/i
+];
+
+export { mapZamaError };

package/dist/core/addresses.d.ts

@@ -0,0 +1,59 @@
+import type { Address } from "viem";
+/**
+ * Pre-deployed contract addresses per chain. The SDK calls into these only —
+ * there are no factory-deployment helpers.
+ *
+ * Prefer the accessors (`getFheVestingFactoryAddress`, etc.) over reaching
+ * into this object directly. They normalize the `null` / missing-key cases
+ * to `undefined` and keep the trust-boundary policy in one place.
+ */
+export declare const DEPLOYED_ADDRESSES: {
+    readonly fheVesting: {
+        readonly confidentialVestingFactory: {
+            readonly 11155111: "0xA87701CE9A52D43681600583a99c85b50DbE3150";
+        };
+    };
+    readonly fheAirdrop: {
+        readonly confidentialAirdropFactory: {
+            readonly 11155111: "0xbE6A3B78B36684fFee48De77d47Bc3393F5Acd4c";
+        };
+    };
+    readonly fheDisperse: {
+        readonly disperseConfidentialSingleton: {
+            readonly 1: "0x4fC0d28cBe4B82D512Ad0B42F6787480Cc98cC70";
+            readonly 11155111: "0x710dD9885Cc9986EfD234E7719483147a6d8DBb4";
+        };
+    };
+};
+export type DeployedAddresses = typeof DEPLOYED_ADDRESSES;
+export type ProductKey = keyof DeployedAddresses;
+export type ContractKey<P extends ProductKey> = keyof DeployedAddresses[P];
+/**
+ * Generic accessor. Returns `undefined` when the (product, contract, chainId)
+ * tuple has no usable address — whether because the chain is absent from the
+ * registry or because the registry explicitly records `null` (known chain,
+ * not deployed).
+ */
+export declare function getDeployedAddress<P extends ProductKey, C extends ContractKey<P>>(product: P, contract: C, chainId: number): Address | undefined;
+export declare function getFheVestingFactoryAddress(chainId: number): Address | undefined;
+export declare function requireFheVestingFactoryAddress(chainId: number): Address;
+export declare function getFheAirdropFactoryAddress(chainId: number): Address | undefined;
+export declare function requireFheAirdropFactoryAddress(chainId: number): Address;
+export declare function getFheDisperseSingletonAddress(chainId: number): Address | undefined;
+export declare function requireFheDisperseSingletonAddress(chainId: number): Address;
+/**
+ * Chains with a registry entry for `product`, including ones explicitly
+ * marked `null` (known chain, not yet deployed). Useful when the consumer
+ * wants to surface "deployment pending" UI separately from "unsupported
+ * chain" UI.
+ */
+export declare function chainsWithKnownRegistryEntry<P extends ProductKey>(product: P): number[];
+/**
+ * Chains where `product` is actually usable — every contract under the
+ * product has a non-null address on that chain. For single-contract products
+ * (the current shape) this equals "the contract is deployed there"; for a
+ * future multi-contract product, a chain is included only when all of the
+ * product's contracts are deployed (a partial deployment is not "usable").
+ * Use this to gate UI / RPC selection.
+ */
+export declare function chainsWithDeployment<P extends ProductKey>(product: P): number[];

package/dist/core/brands.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Branded primitive types for the public SDK surface.
+ *
+ * Why brands? `Hex` is `0x${string}`, which means any `0x`-prefixed string in
+ * the consumer's universe is structurally assignable to every contract handle,
+ * vesting id, role hash, encrypted handle, and tx hash the SDK returns.
+ *
+ * That's a footgun. `external-dev-typescript-purist` Round 03 + Round 04
+ * probes flagged it as a NAMED-FIELD mistake: `EncryptedViewResult = { handle:
+ * Hex; hash: Hex }` — a consumer can swap them by accident and pass `hash` to
+ * the relayer's `userDecrypt`. The compiler will not stop them.
+ *
+ * The fix is `unique symbol` intersection branding (Dan Vanderkam's pattern,
+ * popularised by viem's own `Address`, `Hex`, `Hash` types). The brand is
+ * erased at runtime; the type system tracks origin at zero cost.
+ *
+ * ```ts
+ * import { asEncryptedHandle, type EncryptedHandle } from "@tokenops/sdk";
+ *
+ * declare const raw: `0x${string}`;
+ * const handle: EncryptedHandle = raw;          // ERROR — raw is unbranded
+ * const safe: EncryptedHandle = asEncryptedHandle(raw); // OK — explicit
+ * ```
+ *
+ * The `as*` helpers are zero-cost casts. They exist to make the brand
+ * acquisition explicit at the boundary where a value enters the SDK's typed
+ * universe (a contract read, an event log, a user-supplied string after
+ * `isAddress` / `isHex` validation).
+ */
+import type { Address, Hex } from "viem";
+/**
+ * `bytes32` handle for an `externalEuint*` ciphertext. Returned by the Zama
+ * relayer / `MockFhevmInstance` `encrypt()` call, consumed by FHE-aware
+ * contracts as the off-chain side of `FHE.fromExternal`.
+ */
+export type EncryptedHandle = Hex;
+/**
+ * KMS-issued input proof binding an {@link EncryptedHandle} to a
+ * `(contractAddress, userAddress)` pair. Re-using a proof across
+ * contracts / users is rejected by `FHE.fromExternal` on-chain.
+ */
+export type ExternalInputProof = Hex;
+/** Transaction hash returned by `eth_sendRawTransaction` / `walletClient.writeContract`. */
+export type TxHash = Hex;
+/** `bytes32` vesting schedule id, emitted in `VestingCreated`. */
+export type VestingId = Hex;
+/** `bytes32` airdrop id, emitted in `AirdropCreated`. */
+export type AirdropId = Hex;
+/** `bytes32` disperse id, emitted in `DisperseExecuted`. */
+export type DisperseId = Hex;
+/** `bytes32` role identifier — the `keccak256("ROLE_NAME")` hash AccessControl uses. */
+export type Role = Hex;
+/**
+ * 65-byte ECDSA signature returned by `walletClient.signTypedData` (EIP-712)
+ * or `walletClient.signMessage` (EIP-191). NOT a transaction hash — these
+ * bytes are never broadcast directly; they're handed off-chain to a verifier.
+ *
+ * Canonical producer: {@link useSignClaimAuthorization} in `/fhe-airdrop/react`.
+ */
+export type Signature = Hex;
+/**
+ * Mark a raw {@link Hex} value as an {@link EncryptedHandle}. Caller asserts
+ * the value came from a trusted source — either a Zama relayer `encrypt`
+ * result, a contract read of `externalEuint*`, or the `ACL.Allowed` event of
+ * an `FHE.allow(handle, msg.sender)` call.
+ */
+export declare const asEncryptedHandle: (h: Hex) => EncryptedHandle;
+/** Mark a raw {@link Hex} value as an {@link ExternalInputProof}. */
+export declare const asExternalInputProof: (h: Hex) => ExternalInputProof;
+/** Mark a raw {@link Hex} value as a {@link TxHash}. */
+export declare const asTxHash: (h: Hex) => TxHash;
+/** Mark a raw {@link Hex} value as a {@link VestingId}. */
+export declare const asVestingId: (h: Hex) => VestingId;
+/** Mark a raw {@link Hex} value as an {@link AirdropId}. */
+export declare const asAirdropId: (h: Hex) => AirdropId;
+/** Mark a raw {@link Hex} value as a {@link DisperseId}. */
+export declare const asDisperseId: (h: Hex) => DisperseId;
+/** Mark a raw {@link Hex} value as a {@link Role}. */
+export declare const asRole: (h: Hex) => Role;
+/**
+ * Mark a raw {@link Hex} value as a {@link Signature}. Caller asserts the
+ * bytes are the output of `signTypedData` / `signMessage` and NOT a tx hash —
+ * the alias exists as a reading-clarity annotation so that call sites
+ * distinguish signature bytes from transaction hashes.
+ */
+export declare const asSignature: (h: Hex) => Signature;
+export type { Address };

package/dist/core/chains.d.ts

@@ -0,0 +1,102 @@
+export declare const SUPPORTED_CHAINS: {
+    readonly 1: {
+        blockExplorers: {
+            readonly default: {
+                readonly name: "Etherscan";
+                readonly url: "https://etherscan.io";
+                readonly apiUrl: "https://api.etherscan.io/api";
+            };
+        };
+        blockTime: 12000;
+        contracts: {
+            readonly ensUniversalResolver: {
+                readonly address: "0xeeeeeeee14d718c2b47d9923deab1335e144eeee";
+                readonly blockCreated: 23085558;
+            };
+            readonly multicall3: {
+                readonly address: "0xca11bde05977b3631167028862be2a173976ca11";
+                readonly blockCreated: 14353601;
+            };
+        };
+        ensTlds?: readonly string[] | undefined;
+        id: 1;
+        name: "Ethereum";
+        nativeCurrency: {
+            readonly name: "Ether";
+            readonly symbol: "ETH";
+            readonly decimals: 18;
+        };
+        experimental_preconfirmationTime?: number | undefined | undefined;
+        rpcUrls: {
+            readonly default: {
+                readonly http: readonly ["https://eth.merkle.io"];
+            };
+        };
+        sourceId?: number | undefined | undefined;
+        testnet?: boolean | undefined | undefined;
+        custom?: Record<string, unknown> | undefined;
+        extendSchema?: Record<string, unknown> | undefined;
+        fees?: import("viem").ChainFees<undefined> | undefined;
+        formatters?: undefined;
+        prepareTransactionRequest?: ((args: import("viem").PrepareTransactionRequestParameters, options: {
+            phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+        }) => Promise<import("viem").PrepareTransactionRequestParameters>) | [fn: ((args: import("viem").PrepareTransactionRequestParameters, options: {
+            phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+        }) => Promise<import("viem").PrepareTransactionRequestParameters>) | undefined, options: {
+            runAt: readonly ("beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters")[];
+        }] | undefined;
+        serializers?: import("viem").ChainSerializers<undefined, import("viem").TransactionSerializable> | undefined;
+        verifyHash?: ((client: import("viem").Client, parameters: import("viem").VerifyHashActionParameters) => Promise<import("viem").VerifyHashActionReturnType>) | undefined;
+    };
+    readonly 11155111: {
+        blockExplorers: {
+            readonly default: {
+                readonly name: "Etherscan";
+                readonly url: "https://sepolia.etherscan.io";
+                readonly apiUrl: "https://api-sepolia.etherscan.io/api";
+            };
+        };
+        blockTime?: number | undefined | undefined;
+        contracts: {
+            readonly multicall3: {
+                readonly address: "0xca11bde05977b3631167028862be2a173976ca11";
+                readonly blockCreated: 751532;
+            };
+            readonly ensUniversalResolver: {
+                readonly address: "0xeeeeeeee14d718c2b47d9923deab1335e144eeee";
+                readonly blockCreated: 8928790;
+            };
+        };
+        ensTlds?: readonly string[] | undefined;
+        id: 11155111;
+        name: "Sepolia";
+        nativeCurrency: {
+            readonly name: "Sepolia Ether";
+            readonly symbol: "ETH";
+            readonly decimals: 18;
+        };
+        experimental_preconfirmationTime?: number | undefined | undefined;
+        rpcUrls: {
+            readonly default: {
+                readonly http: readonly ["https://11155111.rpc.thirdweb.com"];
+            };
+        };
+        sourceId?: number | undefined | undefined;
+        testnet: true;
+        custom?: Record<string, unknown> | undefined;
+        extendSchema?: Record<string, unknown> | undefined;
+        fees?: import("viem").ChainFees<undefined> | undefined;
+        formatters?: undefined;
+        prepareTransactionRequest?: ((args: import("viem").PrepareTransactionRequestParameters, options: {
+            phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+        }) => Promise<import("viem").PrepareTransactionRequestParameters>) | [fn: ((args: import("viem").PrepareTransactionRequestParameters, options: {
+            phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
+        }) => Promise<import("viem").PrepareTransactionRequestParameters>) | undefined, options: {
+            runAt: readonly ("beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters")[];
+        }] | undefined;
+        serializers?: import("viem").ChainSerializers<undefined, import("viem").TransactionSerializable> | undefined;
+        verifyHash?: ((client: import("viem").Client, parameters: import("viem").VerifyHashActionParameters) => Promise<import("viem").VerifyHashActionReturnType>) | undefined;
+    };
+};
+export type SupportedChainId = keyof typeof SUPPORTED_CHAINS;
+export declare function isSupportedChainId(chainId: number): chainId is SupportedChainId;