@tokenops/sdk 1.0.0 → 1.5.1

package/dist/testnet-faucet/react/index.js

@@ -0,0 +1,220 @@
+import { useWagmiAccount } from '../../chunk-FT4LNBOS.js';
+import { createTestnetFaucetClient, isTestnetFaucetChainId } from '../../chunk-IJFQ5L4I.js';
+export { FaucetSupplyExhaustedError } from '../../chunk-IJFQ5L4I.js';
+import '../../chunk-SG65XWH7.js';
+import { getConfidentialTestTokenAddress } from '../../chunk-XGGTQQFH.js';
+import '../../chunk-ZA673I3O.js';
+import '../../chunk-Q2GP5UDC.js';
+import '../../chunk-KWFFIJYX.js';
+import { MissingClientError, UnsupportedChainError, DeploymentAddressUnavailableError } from '../../chunk-QBJ7O2B4.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, TransferFailedError, UnknownWriteFailureError, UnsupportedChainError, UserDecryptNotAllowedError, UserRejectedSignatureError, WalletChainMismatchError, WalletRejectedError, isTokenOpsSdkError } from '../../chunk-QBJ7O2B4.js';
+import { useQuery, useMutation } from '@tanstack/react-query';
+import { useMemo } from 'react';
+import { usePublicClient, useWalletClient } from 'wagmi';
+
+var TESTNET_FAUCET_KEY = "tokenops-sdk";
+var TESTNET_FAUCET_NAMESPACE = "testnet-faucet";
+function tryResolveSingletonAddress(override, chainId) {
+  if (chainId !== void 0 && !isTestnetFaucetChainId(chainId)) return void 0;
+  if (override) return override;
+  if (chainId === void 0) return void 0;
+  return getConfidentialTestTokenAddress(chainId);
+}
+function useMemoFaucetClient(opts = {}) {
+  const publicClient = usePublicClient({ chainId: opts.chainId });
+  const { data: walletClient } = useWalletClient({ chainId: opts.chainId });
+  const chainId = opts.chainId ?? publicClient?.chain?.id;
+  const resolvedAddress = tryResolveSingletonAddress(opts.address, chainId);
+  const resolutionError = computeSingletonResolutionError(opts.address, chainId);
+  const client = useMemo(() => {
+    if (!publicClient) return void 0;
+    if (!resolvedAddress) return void 0;
+    return createTestnetFaucetClient({
+      publicClient,
+      ...walletClient ? { walletClient } : {},
+      ...opts.address ? { address: resolvedAddress } : {},
+      ...chainId !== void 0 ? { chainId } : {}
+    });
+  }, [publicClient, walletClient, resolvedAddress, chainId]);
+  return {
+    client,
+    resolutionError,
+    publicClient,
+    walletClient: walletClient ?? void 0,
+    chainId,
+    resolvedAddress
+  };
+}
+function computeSingletonResolutionError(override, chainId) {
+  if (chainId !== void 0 && !isTestnetFaucetChainId(chainId)) {
+    return new UnsupportedChainError(chainId);
+  }
+  if (override) return void 0;
+  if (chainId === void 0) {
+    return new DeploymentAddressUnavailableError({
+      reason: "chain-id-missing",
+      product: "testnetFaucet",
+      contract: "confidentialTestToken",
+      clientLabel: "TestnetFaucetClient"
+    });
+  }
+  const resolved = getConfidentialTestTokenAddress(chainId);
+  if (!resolved) {
+    return new DeploymentAddressUnavailableError({
+      reason: "registry-not-deployed",
+      product: "testnetFaucet",
+      contract: "confidentialTestToken",
+      chainId,
+      clientLabel: "TestnetFaucetClient"
+    });
+  }
+  return void 0;
+}
+function buildQueryKey(method, chainId, address, ...args) {
+  return [
+    TESTNET_FAUCET_KEY,
+    TESTNET_FAUCET_NAMESPACE,
+    method,
+    chainId ?? null,
+    address ? address.toLowerCase() : null,
+    ...args.map(normalizeKeyArg)
+  ];
+}
+function normalizeKeyArg(value) {
+  if (typeof value === "bigint") return value.toString();
+  if (Array.isArray(value)) return value.map(normalizeKeyArg);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([k, v]) => [k, normalizeKeyArg(v)])
+    );
+  }
+  if (typeof value === "string" && value.startsWith("0x")) return value.toLowerCase();
+  return value;
+}
+
+// src/testnet-faucet/react/useConfidentialBalance.ts
+function useConfidentialBalance(args = {}) {
+  const { account, ...base } = args;
+  const { client, chainId, resolvedAddress } = useMemoFaucetClient(base);
+  const { address: connected } = useWagmiAccount();
+  const resolvedAccount = account ?? connected;
+  return useQuery({
+    queryKey: buildQueryKey("confidentialBalanceOf", chainId, resolvedAddress, resolvedAccount),
+    queryFn: () => client.confidentialBalanceOf(resolvedAccount),
+    enabled: !!client && !!resolvedAccount,
+    staleTime: 0
+  });
+}
+function useUnderlyingBalance(args = {}) {
+  const { account, ...base } = args;
+  const { client, chainId, resolvedAddress } = useMemoFaucetClient(base);
+  const { address: connected } = useWagmiAccount();
+  const resolvedAccount = account ?? connected;
+  return useQuery({
+    // The TTT is derived from the CTTT, which is already keyed via
+    // `resolvedAddress` — no separate underlying segment needed.
+    queryKey: buildQueryKey("underlyingBalanceOf", chainId, resolvedAddress, resolvedAccount),
+    queryFn: () => client.underlyingBalanceOf(resolvedAccount),
+    enabled: !!client && !!resolvedAccount,
+    staleTime: 0
+  });
+}
+function useFaucetRate(options = {}) {
+  const { client, chainId, resolvedAddress } = useMemoFaucetClient(options);
+  return useQuery({
+    queryKey: buildQueryKey("rate", chainId, resolvedAddress),
+    queryFn: () => client.rate(),
+    enabled: !!client,
+    // The conversion rate is fixed per deployment — never goes stale.
+    staleTime: Infinity
+  });
+}
+function useFaucetDecimals(options = {}) {
+  const { client, chainId, resolvedAddress } = useMemoFaucetClient(options);
+  return useQuery({
+    queryKey: buildQueryKey("decimals", chainId, resolvedAddress),
+    queryFn: () => client.decimals(),
+    enabled: !!client,
+    // CTTT decimals are fixed per deployment — never goes stale.
+    staleTime: Infinity
+  });
+}
+function useUnderlyingDecimals(options = {}) {
+  const { client, chainId, resolvedAddress } = useMemoFaucetClient(options);
+  return useQuery({
+    // The TTT is derived from the CTTT, which is already keyed via
+    // `resolvedAddress` — no separate underlying segment needed.
+    queryKey: buildQueryKey("underlyingDecimals", chainId, resolvedAddress),
+    queryFn: () => client.underlyingDecimals(),
+    enabled: !!client,
+    // TTT decimals are fixed per deployment — never goes stale.
+    staleTime: Infinity
+  });
+}
+function useUnderlyingTokenAddress(options = {}) {
+  const { client, chainId, resolvedAddress } = useMemoFaucetClient(options);
+  return useQuery({
+    // The TTT is derived from the CTTT, which is already keyed via
+    // `resolvedAddress` — no separate underlying segment needed.
+    queryKey: buildQueryKey("underlyingToken", chainId, resolvedAddress),
+    queryFn: () => client.underlyingToken(),
+    enabled: !!client,
+    // The backing token address is fixed per deployment — never goes stale.
+    staleTime: Infinity
+  });
+}
+function useInferredTotalSupply(options = {}) {
+  const { client, chainId, resolvedAddress } = useMemoFaucetClient(options);
+  return useQuery({
+    queryKey: buildQueryKey("inferredTotalSupply", chainId, resolvedAddress),
+    queryFn: () => client.inferredTotalSupply(),
+    enabled: !!client,
+    staleTime: 0
+  });
+}
+function useMaxTotalSupply(options = {}) {
+  const { client, chainId, resolvedAddress } = useMemoFaucetClient(options);
+  return useQuery({
+    queryKey: buildQueryKey("maxTotalSupply", chainId, resolvedAddress),
+    queryFn: () => client.maxTotalSupply(),
+    enabled: !!client,
+    // `type(uint64).max` is fixed per deployment — never goes stale.
+    staleTime: Infinity
+  });
+}
+function useFaucetMetadata(options = {}) {
+  const { client, chainId, resolvedAddress } = useMemoFaucetClient(options);
+  return useQuery({
+    // The `underlying` half of the metadata is derived from the CTTT, which is
+    // already keyed via `resolvedAddress` — no separate underlying segment needed.
+    queryKey: buildQueryKey("getMetadata", chainId, resolvedAddress),
+    queryFn: () => client.getMetadata(),
+    enabled: !!client,
+    // name/symbol/decimals/rate/maxTotalSupply are all fixed per deployment.
+    staleTime: Infinity
+  });
+}
+function useMintConfidential(options = {}) {
+  const { client, resolutionError } = useMemoFaucetClient(options);
+  return useMutation({
+    mutationFn: async (args) => {
+      if (!client) {
+        throw resolutionError ?? new MissingClientError("useMintConfidential", "testnet-faucet");
+      }
+      return client.mintConfidential(args);
+    }
+  });
+}
+function useMintUnderlying(options = {}) {
+  const { client, resolutionError } = useMemoFaucetClient(options);
+  return useMutation({
+    mutationFn: async (args) => {
+      if (!client) {
+        throw resolutionError ?? new MissingClientError("useMintUnderlying", "testnet-faucet");
+      }
+      return client.mintUnderlying(args);
+    }
+  });
+}
+
+export { TESTNET_FAUCET_KEY, TESTNET_FAUCET_NAMESPACE, useConfidentialBalance, useFaucetDecimals, useFaucetMetadata, useFaucetRate, useInferredTotalSupply, useMaxTotalSupply, useMintConfidential, useMintUnderlying, useUnderlyingBalance, useUnderlyingDecimals, useUnderlyingTokenAddress };

package/dist/testnet-faucet/react/useConfidentialBalance.d.ts

@@ -0,0 +1,25 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Address, Hex } from "viem";
+import { type BaseHookOptions } from "./_shared.js";
+export interface UseConfidentialBalanceArgs extends BaseHookOptions {
+    /**
+     * Account whose confidential balance handle to read. Defaults to the
+     * connected wallet (wagmi v2 `useAccount().address` / v3
+     * `useConnection().address`). The hook stays disabled until an account is
+     * available.
+     */
+    account?: Address;
+}
+/**
+ * Read the encrypted confidential balance handle (`euint64` ciphertext) for
+ * `account` — defaults to the connected wallet.
+ *
+ * Returns the `bytes32` handle. The account holds persistent ACL on its own
+ * balance, so pass this handle — with the CTTT contract address and the
+ * account's signer — to the Zama relayer's `userDecrypt` to obtain the
+ * plaintext. The SDK is the producer side only.
+ *
+ * @example
+ * const { data: handle } = useConfidentialBalance(); // my own balance handle
+ */
+export declare function useConfidentialBalance(args?: UseConfidentialBalanceArgs): UseQueryResult<Hex, Error>;

package/dist/testnet-faucet/react/useFaucetDecimals.d.ts

@@ -0,0 +1,9 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import { type BaseHookOptions } from "./_shared.js";
+/**
+ * Read the decimals of the confidential token (CTTT) — `6`.
+ *
+ * @example
+ * const { data: decimals } = useFaucetDecimals(); // 6
+ */
+export declare function useFaucetDecimals(options?: BaseHookOptions): UseQueryResult<number, Error>;

package/dist/testnet-faucet/react/useFaucetMetadata.d.ts

@@ -0,0 +1,14 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import { type FaucetMetadata } from "../types.js";
+import { type BaseHookOptions } from "./_shared.js";
+/**
+ * Read consolidated faucet metadata in a single hook — both tokens'
+ * name/symbol/decimals/address, the conversion `rate`, and the
+ * `maxTotalSupply` ceiling. Handy for rendering a faucet panel without
+ * composing several reads.
+ *
+ * @example
+ * const { data: meta } = useFaucetMetadata();
+ * // meta?.confidential.symbol, meta?.underlying.decimals, meta?.rate, ...
+ */
+export declare function useFaucetMetadata(options?: BaseHookOptions): UseQueryResult<FaucetMetadata, Error>;

package/dist/testnet-faucet/react/useFaucetRate.d.ts

@@ -0,0 +1,11 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import { type BaseHookOptions } from "./_shared.js";
+/**
+ * Read the decimal-conversion `rate` between underlying and confidential units:
+ * `1` CTTT 6-decimal unit is backed by `rate` TTT 18-decimal base units
+ * (`10^(18-6) = 10^12`).
+ *
+ * @example
+ * const { data: rate } = useFaucetRate(); // 1_000_000_000_000n
+ */
+export declare function useFaucetRate(options?: BaseHookOptions): UseQueryResult<bigint, Error>;

package/dist/testnet-faucet/react/useInferredTotalSupply.d.ts

@@ -0,0 +1,11 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import { type BaseHookOptions } from "./_shared.js";
+/**
+ * Read the wrapper's inferred total supply: underlying held in custody divided
+ * by `rate`, an upper bound on the confidential total supply, in CTTT
+ * 6-decimal units.
+ *
+ * @example
+ * const { data: supply } = useInferredTotalSupply();
+ */
+export declare function useInferredTotalSupply(options?: BaseHookOptions): UseQueryResult<bigint, Error>;

package/dist/testnet-faucet/react/useMaxTotalSupply.d.ts

@@ -0,0 +1,10 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import { type BaseHookOptions } from "./_shared.js";
+/**
+ * Read the max confidential total supply the wrapper supports
+ * (`type(uint64).max`).
+ *
+ * @example
+ * const { data: max } = useMaxTotalSupply();
+ */
+export declare function useMaxTotalSupply(options?: BaseHookOptions): UseQueryResult<bigint, Error>;

package/dist/testnet-faucet/react/useMintConfidential.d.ts

@@ -0,0 +1,35 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import { type MintConfidentialArgs, type MintConfidentialResult } from "../types.js";
+import { type BaseHookOptions } from "./_shared.js";
+/** Args for {@link useMintConfidential} — same shape as the headless `MintConfidentialArgs`. */
+export type UseMintConfidentialArgs = MintConfidentialArgs;
+/**
+ * Mint backed confidential test tokens (CTTT) to a recipient. Open and
+ * permissionless on testnet — anyone can mint any `uint64` amount, fully backed
+ * by freshly minted underlying TTT.
+ *
+ * The amount is PUBLIC (plaintext calldata + `ConfidentialMint` event); only
+ * the recipient's aggregated balance and later confidential transfers are
+ * private. Delegates 1:1 to {@link TestnetFaucetClient.mintConfidential} and
+ * returns its `MintConfidentialResult` (decoded from the `ConfidentialMint`
+ * event).
+ *
+ * Mutations do NOT auto-invalidate read queries — that's a consumer decision.
+ * After a successful mint, invalidate every faucet query for fresh balances:
+ *
+ * ```ts
+ * const queryClient = useQueryClient();
+ * const mint = useMintConfidential();
+ * mint.mutate({ amount: 1_000_000_000n }, {
+ *   onSuccess: () => {
+ *     queryClient.invalidateQueries({ queryKey: ["tokenops-sdk", "testnet-faucet"] });
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * const mint = useMintConfidential();
+ * mint.mutate({ amount: 1_000_000_000n }); // 1,000 CTTT (6-decimal units)
+ * // mint.data → { hash, to, amount, underlyingMinted, handle }
+ */
+export declare function useMintConfidential(options?: BaseHookOptions): UseMutationResult<MintConfidentialResult, Error, UseMintConfidentialArgs>;

package/dist/testnet-faucet/react/useMintUnderlying.d.ts

@@ -0,0 +1,31 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import { type MintUnderlyingArgs, type MintUnderlyingResult } from "../types.js";
+import { type BaseHookOptions } from "./_shared.js";
+/** Args for {@link useMintUnderlying} — same shape as the headless `MintUnderlyingArgs`. */
+export type UseMintUnderlyingArgs = MintUnderlyingArgs;
+/**
+ * Mint standard (non-confidential) ERC-20 test tokens (TTT) to a recipient.
+ * Open and permissionless on testnet. Use this when you want plain TTT — e.g.
+ * to then `approve` + `wrap` it into CTTT through the standard ERC-7984 flow.
+ *
+ * Delegates 1:1 to {@link TestnetFaucetClient.mintUnderlying}.
+ *
+ * Mutations do NOT auto-invalidate read queries. After a successful mint,
+ * invalidate every faucet query for fresh balances:
+ *
+ * ```ts
+ * const queryClient = useQueryClient();
+ * const mint = useMintUnderlying();
+ * mint.mutate({ amount: 1_000_000_000_000_000_000_000n }, {
+ *   onSuccess: () => {
+ *     queryClient.invalidateQueries({ queryKey: ["tokenops-sdk", "testnet-faucet"] });
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * const mint = useMintUnderlying();
+ * mint.mutate({ amount: 1_000_000_000_000_000_000_000n }); // 1,000 TTT (18-decimal units)
+ * // mint.data → { hash, to, amount }
+ */
+export declare function useMintUnderlying(options?: BaseHookOptions): UseMutationResult<MintUnderlyingResult, Error, UseMintUnderlyingArgs>;

package/dist/testnet-faucet/react/useUnderlyingBalance.d.ts

@@ -0,0 +1,19 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Address } from "viem";
+import { type BaseHookOptions } from "./_shared.js";
+export interface UseUnderlyingBalanceArgs extends BaseHookOptions {
+    /**
+     * Account whose underlying TTT balance to read. Defaults to the connected
+     * wallet (wagmi v2 `useAccount().address` / v3 `useConnection().address`).
+     * The hook stays disabled until an account is available.
+     */
+    account?: Address;
+}
+/**
+ * Read the plaintext underlying `TokenopsTestToken` (TTT) balance for
+ * `account` (defaults to the connected wallet), in TTT 18-decimal base units.
+ *
+ * @example
+ * const { data: balance } = useUnderlyingBalance(); // my own TTT balance
+ */
+export declare function useUnderlyingBalance(args?: UseUnderlyingBalanceArgs): UseQueryResult<bigint, Error>;

package/dist/testnet-faucet/react/useUnderlyingDecimals.d.ts

@@ -0,0 +1,9 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import { type BaseHookOptions } from "./_shared.js";
+/**
+ * Read the decimals of the underlying token (TTT) — `18`.
+ *
+ * @example
+ * const { data: decimals } = useUnderlyingDecimals(); // 18
+ */
+export declare function useUnderlyingDecimals(options?: BaseHookOptions): UseQueryResult<number, Error>;

package/dist/testnet-faucet/react/useUnderlyingTokenAddress.d.ts

@@ -0,0 +1,12 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Address } from "viem";
+import { type BaseHookOptions } from "./_shared.js";
+/**
+ * Read the underlying `TokenopsTestToken` (TTT) address backing the CTTT
+ * wrapper. Resolution order inside the client: registry → the wrapper's own
+ * `underlying()` getter.
+ *
+ * @example
+ * const { data: tttAddress } = useUnderlyingTokenAddress();
+ */
+export declare function useUnderlyingTokenAddress(options?: BaseHookOptions): UseQueryResult<Address, Error>;

package/dist/testnet-faucet/types.d.ts

@@ -0,0 +1,92 @@
+import type { Account, Address } from "viem";
+import type { EncryptedHandle, TxHash } from "../core/brands.js";
+/**
+ * Arguments for {@link TestnetFaucetClient.mintConfidential} — the open,
+ * fully-backed faucet mint on `ConfidentialTokenopsTestToken` (CTTT).
+ */
+export interface MintConfidentialArgs {
+    /**
+     * Recipient of the confidential balance. Defaults to the signing account
+     * (`account` override, else the wallet's account).
+     */
+    to?: Address;
+    /**
+     * Amount to mint, in CTTT's **6-decimal** units (a `uint64`).
+     *
+     * NOTE: this amount is PUBLIC — it is passed as plaintext calldata, emitted
+     * in the `ConfidentialMint` event, and wrapped via a trivial (non-secret)
+     * encryption. Only the recipient's *aggregated* balance and subsequent
+     * confidential transfers are private; the per-mint amount is not.
+     */
+    amount: bigint;
+    /** Signer override. Accepts a viem `Account` object or an `Address` string. */
+    account?: Account | Address;
+}
+/**
+ * Result of {@link TestnetFaucetClient.mintConfidential}, decoded from the
+ * `ConfidentialMint` event in the transaction receipt.
+ */
+export interface MintConfidentialResult {
+    /** Transaction hash of the mint. */
+    hash: TxHash;
+    /** Recipient credited with the confidential balance. */
+    to: Address;
+    /** Plaintext amount minted, in CTTT 6-decimal units (echoed — the faucet mint amount is public). */
+    amount: bigint;
+    /** Underlying TTT minted into the wrapper as 1:1 backing (= `amount * rate`, in TTT 18-decimal base units). */
+    underlyingMinted: bigint;
+    /**
+     * The minted ciphertext handle from the `ConfidentialMint` event. Informational —
+     * the recipient holds persistent ACL on their *balance*, which you read via
+     * {@link TestnetFaucetClient.confidentialBalanceOf} and pass to the Zama
+     * relayer's `userDecrypt`. The caller only receives transient ACL on this
+     * handle (valid within the mint tx), so it is not itself user-decryptable
+     * afterwards.
+     */
+    handle: EncryptedHandle;
+}
+/**
+ * Arguments for {@link TestnetFaucetClient.mintUnderlying} — the open mint on
+ * the standard ERC-20 `TokenopsTestToken` (TTT).
+ */
+export interface MintUnderlyingArgs {
+    /** Recipient of the TTT. Defaults to the signing account. */
+    to?: Address;
+    /** Amount to mint, in TTT's **18-decimal** base units (a `uint256`). */
+    amount: bigint;
+    /** Signer override. */
+    account?: Account | Address;
+}
+/** Result of {@link TestnetFaucetClient.mintUnderlying}. */
+export interface MintUnderlyingResult {
+    /** Transaction hash of the mint. */
+    hash: TxHash;
+    /** Recipient credited with the TTT. */
+    to: Address;
+    /** Plaintext amount minted, in TTT 18-decimal base units. */
+    amount: bigint;
+}
+/** Static metadata for one side of the faucet token pair. */
+export interface FaucetTokenMetadata {
+    address: Address;
+    name: string;
+    symbol: string;
+    decimals: number;
+}
+/**
+ * Consolidated faucet metadata — both tokens, the wrapper `rate`, and the
+ * `maxTotalSupply` ceiling. One convenience read for UI surfaces.
+ */
+export interface FaucetMetadata {
+    /** The confidential ERC-7984 wrapper (CTTT). */
+    confidential: FaucetTokenMetadata;
+    /** The underlying ERC-20 (TTT). */
+    underlying: FaucetTokenMetadata;
+    /**
+     * Decimal-conversion rate between underlying and confidential units:
+     * `1` CTTT unit is backed by `rate` TTT base units (`10^(18-6) = 10^12`).
+     */
+    rate: bigint;
+    /** Max confidential total supply the wrapper supports (`type(uint64).max`). */
+    maxTotalSupply: bigint;
+}

package/dist/testnet-faucet/validate.d.ts

@@ -0,0 +1,44 @@
+import type { Address } from "viem";
+/**
+ * Chain ids on which the testnet faucet is allowed to operate.
+ *
+ * The faucet mints **value-less** test tokens to anyone, so it must never be
+ * usable on a value-bearing network. We allow Sepolia (the canonical public
+ * testnet deployment) and the local Anvil/Hardhat dev chain id `31337` (used
+ * by the SDK's own FHEVM test fixtures, which deploy the token pair at test
+ * time). Every other chain — mainnet above all — is rejected at construction.
+ */
+export declare const TESTNET_FAUCET_SUPPORTED_CHAIN_IDS: readonly [11155111, 31337];
+/** `true` when `chainId` is a chain the faucet is permitted to run on. */
+export declare function isTestnetFaucetChainId(chainId: number): boolean;
+/**
+ * Hard testnet-only guard. Throws {@link UnsupportedChainError} when `chainId`
+ * is a known non-testnet chain (mainnet, or anything outside
+ * {@link TESTNET_FAUCET_SUPPORTED_CHAIN_IDS}).
+ *
+ * A `undefined` chain id is intentionally NOT rejected here — the client can
+ * still be constructed with an explicit `address` override on an
+ * unknown-chain `publicClient`, and address resolution raises the precise
+ * `DeploymentAddressUnavailableError("chain-id-missing")` when no override is
+ * present. The guard's job is to slam the door on mainnet, not to second-guess
+ * a deliberate local override.
+ */
+export declare function assertTestnetFaucetChain(chainId: number | undefined): void;
+/**
+ * Assert that `value` fits the confidential faucet's `uint64` amount domain.
+ * CTTT balances are `euint64`, so `mint(to, amount)` takes a `uint64`. Amounts
+ * are denominated in CTTT's 6-decimal units.
+ */
+export declare function assertUint64Amount(value: bigint, argument: string, method: string): void;
+/**
+ * Assert that `value` fits the underlying ERC-20's `uint256` amount domain.
+ * TTT amounts are denominated in 18-decimal base units.
+ */
+export declare function assertUint256Amount(value: bigint, argument: string, method: string): void;
+/**
+ * Normalise an address to EIP-55 checksum form, rejecting the zero address.
+ * Faucet recipients (`to`) must be a real account — the contracts revert with
+ * `ERC7984InvalidReceiver` / `ERC20InvalidReceiver` on the zero address, but
+ * catching it here gives a clearer, pre-flight `InvalidArgumentError`.
+ */
+export declare function assertNonZeroRecipient(input: Address, argument: string, method: string): Address;