@tokenops/sdk 1.0.0 → 1.1.1

package/README.md

@@ -3,9 +3,9 @@
 [![npm version](https://img.shields.io/npm/v/%40tokenops%2Fsdk?style=flat-square)](https://www.npmjs.com/package/@tokenops/sdk)
 [![license](https://img.shields.io/npm/l/%40tokenops%2Fsdk?style=flat-square)](https://github.com/VestingLabs/tokenops-sdk/blob/main/LICENSE)
 
-Typed viem-first SDK for TokenOps FHEVM contracts — confidential vesting, confidential airdrops, and confidential disperse. Works with [viem](https://viem.sh) `publicClient` / `walletClient` directly; no framework required.
+Typed viem-first SDK for TokenOps FHEVM contracts — confidential vesting, confidential airdrops, confidential disperse, and a testnet faucet for the TokenOps test-token pair. Works with [viem](https://viem.sh) `publicClient` / `walletClient` directly; no framework required.
 
-**Deployed factories only.** The SDK calls into pre-deployed factories / singletons; there are no `deployFactory` helpers. Currently deployed: `@tokenops/sdk/fhe-vesting` (factory live on Sepolia), `@tokenops/sdk/fhe-airdrop` (factory live on Sepolia), `@tokenops/sdk/fhe-disperse` (singleton live on mainnet + Sepolia).
+**Deployed factories only.** The SDK calls into pre-deployed factories / singletons; there are no `deployFactory` helpers. Currently deployed: `@tokenops/sdk/fhe-vesting` (factory live on Sepolia), `@tokenops/sdk/fhe-airdrop` (factory live on Sepolia), `@tokenops/sdk/fhe-disperse` (singleton live on mainnet + Sepolia), and `@tokenops/sdk/testnet-faucet` (token pair live on Sepolia).
 
 ## Install
 
@@ -21,22 +21,24 @@ Node `>= 22` is required (constraint from `@zama-fhe/sdk`).
 
 All subpaths are independently tree-shakeable. The `/react` paths keep React deps out of the server bundle.
 
-| Subpath                                    | Status                              | Description                                                                        |
-| ------------------------------------------ | ----------------------------------- | ---------------------------------------------------------------------------------- |
-| `@tokenops/sdk`                            | stable                              | Root re-exports (version, core error types)                                        |
-| `@tokenops/sdk/telemetry`                  | stable                              | Telemetry sink adapters (`NoopTelemetry`, `ConsoleTelemetry`, `TokenOpsTelemetry`) |
-| `@tokenops/sdk/fhe`                        | stable                              | FHE utility helpers (ratio scaling, encrypted-input types, operator helpers)       |
-| `@tokenops/sdk/fhe/react`                  | stable                              | React hooks for shared FHE utilities                                               |
-| `@tokenops/sdk/fhe-vesting`                | factory live on Sepolia             | Confidential vesting (LibClone + packed immutable args)                            |
-| `@tokenops/sdk/fhe-vesting/react`          | stable                              | React/wagmi hooks for confidential vesting                                         |
-| `@tokenops/sdk/fhe-vesting/advanced`       | stable                              | Pre-mine address prediction (`predictManagerAddress`)                              |
-| `@tokenops/sdk/fhe-vesting/advanced/react` | stable                              | React hooks for advanced vesting flows                                             |
-| `@tokenops/sdk/fhe-airdrop`                | factory live on Sepolia             | ConfidentialAirdrop (EIP-712 gated confidential claims)                            |
-| `@tokenops/sdk/fhe-airdrop/react`          | stable                              | React/wagmi hooks for confidential airdrops                                        |
-| `@tokenops/sdk/fhe-airdrop/advanced`       | stable                              | Pre-mine address prediction (`predictAirdropAddress`)                              |
-| `@tokenops/sdk/fhe-airdrop/advanced/react` | stable                              | React hooks for advanced airdrop flows                                             |
-| `@tokenops/sdk/fhe-disperse`               | singleton live on mainnet + Sepolia | DisperseConfidential (singleton + per-user wallet-pair clones)                     |
-| `@tokenops/sdk/fhe-disperse/react`         | stable                              | React/wagmi hooks for confidential disperse                                        |
+| Subpath                                    | Status                              | Description                                                                                               |
+| ------------------------------------------ | ----------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `@tokenops/sdk`                            | stable                              | Root re-exports (version, core error types)                                                               |
+| `@tokenops/sdk/telemetry`                  | stable                              | Telemetry sink adapters (`NoopTelemetry`, `ConsoleTelemetry`, `TokenOpsTelemetry`)                        |
+| `@tokenops/sdk/fhe`                        | stable                              | FHE utility helpers (ratio scaling, encrypted-input types, operator helpers)                              |
+| `@tokenops/sdk/fhe/react`                  | stable                              | React hooks for shared FHE utilities                                                                      |
+| `@tokenops/sdk/fhe-vesting`                | factory live on Sepolia             | Confidential vesting (LibClone + packed immutable args)                                                   |
+| `@tokenops/sdk/fhe-vesting/react`          | stable                              | React/wagmi hooks for confidential vesting                                                                |
+| `@tokenops/sdk/fhe-vesting/advanced`       | stable                              | Pre-mine address prediction (`predictManagerAddress`)                                                     |
+| `@tokenops/sdk/fhe-vesting/advanced/react` | stable                              | React hooks for advanced vesting flows                                                                    |
+| `@tokenops/sdk/fhe-airdrop`                | factory live on Sepolia             | ConfidentialAirdrop (EIP-712 gated confidential claims)                                                   |
+| `@tokenops/sdk/fhe-airdrop/react`          | stable                              | React/wagmi hooks for confidential airdrops                                                               |
+| `@tokenops/sdk/fhe-airdrop/advanced`       | stable                              | Pre-mine address prediction (`predictAirdropAddress`)                                                     |
+| `@tokenops/sdk/fhe-airdrop/advanced/react` | stable                              | React hooks for advanced airdrop flows                                                                    |
+| `@tokenops/sdk/fhe-disperse`               | singleton live on mainnet + Sepolia | DisperseConfidential (singleton + per-user wallet-pair clones)                                            |
+| `@tokenops/sdk/fhe-disperse/react`         | stable                              | React/wagmi hooks for confidential disperse                                                               |
+| `@tokenops/sdk/testnet-faucet`             | token pair live on Sepolia          | Testnet faucet for the TokenOps test-token pair — TTT (plain ERC-20) + CTTT (ERC-7984 wrapper); open mint |
+| `@tokenops/sdk/testnet-faucet/react`       | stable                              | React/wagmi hooks for the testnet faucet                                                                  |
 
 The canonical exports map is in [`package.json`](https://github.com/VestingLabs/tokenops-sdk/blob/main/package.json) under `"exports"`.
 
@@ -635,6 +637,87 @@ function DispersePanel({
 
 See [Confidential Disperse — React hooks on docs.tokenops.xyz](https://docs.tokenops.xyz/sdk/fhe-disperse#react-hooks) for the full hook catalogue, encryptor wiring, address overrides, `usePreflightDisperse` gating pattern, `useGetEncryptedFeeReserve` encrypted-view flow, and query-key reference.
 
+## Quickstart — testnet faucet
+
+A **testnet-only** faucet for the TokenOps test-token pair: TTT (plain ERC-20, 18 decimals) and CTTT (its ERC-7984 confidential wrapper, 6 decimals). Both mints are open and permissionless. Unlike the FHE products, faucet mints take **PUBLIC plaintext** amounts — no encryptor, no `@zama-fhe/sdk` relayer needed. The client throws `UnsupportedChainError` on any value-bearing chain (mainnet); it only runs on Sepolia and local Anvil. See [Testnet Faucet on docs.tokenops.xyz](https://docs.tokenops.xyz/sdk/testnet-faucet) for the full API reference.
+
+```ts
+import { createPublicClient, createWalletClient, http } from "viem";
+import { sepolia } from "viem/chains";
+import { privateKeyToAccount } from "viem/accounts";
+import { createTestnetFaucetClient } from "@tokenops/sdk/testnet-faucet";
+
+const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
+const rpcUrl = process.env.RPC_URL!;
+const publicClient = createPublicClient({ chain: sepolia, transport: http(rpcUrl) });
+const walletClient = createWalletClient({ account, chain: sepolia, transport: http(rpcUrl) });
+
+// CTTT + TTT addresses resolve automatically from DEPLOYED_ADDRESSES on Sepolia.
+const faucet = createTestnetFaucetClient({ publicClient, walletClient });
+
+// Mint 1,000 CTTT (6-decimal units) to myself, fully backed by freshly minted TTT.
+// The amount is PUBLIC; only the recipient's aggregated balance stays confidential.
+const { hash } = await faucet.mintConfidential({ amount: 1_000_000_000n });
+console.log("Confidential mint tx:", hash);
+
+// Read my encrypted confidential balance handle, then user-decrypt it with your
+// own @zama-fhe/sdk relayer instance (the SDK is the producer side only).
+const balanceHandle = await faucet.confidentialBalanceOf();
+
+// Or mint plain ERC-20 TTT (18-decimal units) — e.g. to approve + wrap yourself.
+await faucet.mintUnderlying({ amount: 5n * 10n ** 18n });
+```
+
+### Quickstart — testnet faucet (React hooks)
+
+Uses `@tokenops/sdk/testnet-faucet/react`. Requires `wagmi` and `@tanstack/react-query` — but **not** `@zama-fhe/react-sdk` (no encryptor for public faucet mints).
+
+```tsx
+import { useQueryClient } from "@tanstack/react-query";
+import {
+  useFaucetMetadata,
+  useConfidentialBalance,
+  useMintConfidential,
+} from "@tokenops/sdk/testnet-faucet/react";
+
+// Wrap your app in wagmi's <WagmiProvider> + <QueryClientProvider>.
+// No <ZamaProvider> needed — faucet mints take PUBLIC plaintext amounts.
+
+function FaucetPanel() {
+  const queryClient = useQueryClient();
+  const { data: meta } = useFaucetMetadata();
+  const { data: balanceHandle } = useConfidentialBalance(); // my own encrypted balance handle
+  const mint = useMintConfidential();
+
+  return (
+    <div>
+      {meta && (
+        <p>
+          {meta.confidential.symbol} · {meta.confidential.decimals} decimals · rate{" "}
+          {meta.rate.toString()}
+        </p>
+      )}
+      <button
+        onClick={() =>
+          mint.mutate(
+            { amount: 1_000_000_000n }, // 1,000 CTTT (6-decimal units)
+            {
+              onSuccess: () =>
+                queryClient.invalidateQueries({ queryKey: ["tokenops-sdk", "testnet-faucet"] }),
+            },
+          )
+        }
+        disabled={mint.isPending}
+      >
+        {mint.isPending ? "Minting…" : "Mint 1,000 CTTT"}
+      </button>
+    </div>
+  );
+}
+```
+
+See [Testnet Faucet — React hooks on docs.tokenops.xyz](https://docs.tokenops.xyz/sdk/testnet-faucet#react-hooks) for the full hook catalogue (reads, mints, metadata), address overrides, and query-key reference.
+
 ## Peer dependencies
 
 | Package                 | Range    | Required for                                                                   |
@@ -660,6 +743,7 @@ All peers except `viem` are marked `optional` via `peerDependenciesMeta` so read
 - [Confidential Vesting (`@tokenops/sdk/fhe-vesting`)](https://docs.tokenops.xyz/sdk/fhe-vesting)
 - [Confidential Airdrop (`@tokenops/sdk/fhe-airdrop`)](https://docs.tokenops.xyz/sdk/fhe-airdrop)
 - [Confidential Disperse (`@tokenops/sdk/fhe-disperse`)](https://docs.tokenops.xyz/sdk/fhe-disperse)
+- [Testnet Faucet (`@tokenops/sdk/testnet-faucet`)](https://docs.tokenops.xyz/sdk/testnet-faucet)
 - [Local dev with `link:`](https://docs.tokenops.xyz/sdk/local-dev)
 
 ## Development

package/dist/{chunk-HTOMTEA3.cjs → chunk-23F7JIK5.cjs}

@@ -3,7 +3,7 @@
 var chunkNS44KBV5_cjs = require('./chunk-NS44KBV5.cjs');
 var chunkQ7ARQSUH_cjs = require('./chunk-Q7ARQSUH.cjs');
 var chunkVDXVNZCO_cjs = require('./chunk-VDXVNZCO.cjs');
-var chunkOLDGMKW2_cjs = require('./chunk-OLDGMKW2.cjs');
+var chunk3ZRHDTEX_cjs = require('./chunk-3ZRHDTEX.cjs');
 var chunkCQIPRNS7_cjs = require('./chunk-CQIPRNS7.cjs');
 var chunkVJKZWYYJ_cjs = require('./chunk-VJKZWYYJ.cjs');
 var chunk66IHPTOK_cjs = require('./chunk-66IHPTOK.cjs');
@@ -2013,7 +2013,7 @@ var ConfidentialDisperseClient = class {
     this.#telemetry = config.telemetry;
     const chainId = config.chainId ?? config.publicClient.chain?.id;
     const addressOverride = config.address ? chunkCQIPRNS7_cjs.normaliseAddress(config.address) : void 0;
-    const resolved = addressOverride ?? (chainId === void 0 ? void 0 : chunkOLDGMKW2_cjs.getFheDisperseSingletonAddress(chainId));
+    const resolved = addressOverride ?? (chainId === void 0 ? void 0 : chunk3ZRHDTEX_cjs.getFheDisperseSingletonAddress(chainId));
     if (!resolved) {
       throw new chunk56UI7LUR_cjs.DeploymentAddressUnavailableError({
         reason: chainId === void 0 ? "chain-id-missing" : "registry-not-deployed",

package/dist/{chunk-ECT3NL2L.js → chunk-3PQ2RFPC.js}

@@ -1,6 +1,6 @@
-import { createConfidentialVestingManagerClient, resolveEncryptor } from './chunk-52TC6BF7.js';
-import { createConfidentialVestingFactoryClient } from './chunk-72YGZEQE.js';
-import { getFheVestingFactoryAddress } from './chunk-COPFW5Z4.js';
+import { createConfidentialVestingManagerClient, resolveEncryptor } from './chunk-X56UVEXS.js';
+import { createConfidentialVestingFactoryClient } from './chunk-IR5AK5U5.js';
+import { getFheVestingFactoryAddress } from './chunk-M7V2EDPB.js';
 import { DeploymentAddressUnavailableError } from './chunk-IVE3QEGD.js';
 import { useMemo, useRef, useEffect } from 'react';
 import { usePublicClient, useWalletClient } from 'wagmi';

package/dist/{chunk-OLDGMKW2.cjs → chunk-3ZRHDTEX.cjs}

@@ -21,6 +21,23 @@ var DEPLOYED_ADDRESSES = {
       [chains.mainnet.id]: "0x4fC0d28cBe4B82D512Ad0B42F6787480Cc98cC70",
       [chains.sepolia.id]: "0x710dD9885Cc9986EfD234E7719483147a6d8DBb4"
     }
+  },
+  // Testnet-only faucet token pair (see `/testnet-faucet`). The standard
+  // `TokenopsTestToken` (TTT, 18-decimal ERC-20, open mint) and its
+  // confidential ERC-7984 wrapper `ConfidentialTokenopsTestToken` (CTTT,
+  // 6-decimal, open backed faucet mint). Sepolia only — these mint value-less
+  // test tokens to anyone, so they MUST NOT appear on mainnet.
+  // `confidentialTestToken` is the UUPS *proxy* address; call it with the
+  // implementation ABI.
+  testnetFaucet: {
+    testToken: {
+      [chains.sepolia.id]: "0x37a057Fa8C201a7bf8caF32dfa9A0878f577D92b"
+      // mainnet omitted — testnet-only by design.
+    },
+    confidentialTestToken: {
+      [chains.sepolia.id]: "0x258F9D60dc023870e4E3109c894D834D5377361a"
+      // mainnet omitted — testnet-only by design.
+    }
   }
 };
 function getDeployedAddress(product, contract, chainId) {
@@ -58,6 +75,18 @@ function getFheDisperseSingletonAddress(chainId) {
 function requireFheDisperseSingletonAddress(chainId) {
   return requireDeployedAddress("fheDisperse", "disperseConfidentialSingleton", chainId);
 }
+function getTestTokenAddress(chainId) {
+  return getDeployedAddress("testnetFaucet", "testToken", chainId);
+}
+function requireTestTokenAddress(chainId) {
+  return requireDeployedAddress("testnetFaucet", "testToken", chainId);
+}
+function getConfidentialTestTokenAddress(chainId) {
+  return getDeployedAddress("testnetFaucet", "confidentialTestToken", chainId);
+}
+function requireConfidentialTestTokenAddress(chainId) {
+  return requireDeployedAddress("testnetFaucet", "confidentialTestToken", chainId);
+}
 function chainsWithKnownRegistryEntry(product) {
   const productEntry = DEPLOYED_ADDRESSES[product];
   const ids = /* @__PURE__ */ new Set();
@@ -84,10 +113,14 @@ function chainsWithDeployment(product) {
 exports.DEPLOYED_ADDRESSES = DEPLOYED_ADDRESSES;
 exports.chainsWithDeployment = chainsWithDeployment;
 exports.chainsWithKnownRegistryEntry = chainsWithKnownRegistryEntry;
+exports.getConfidentialTestTokenAddress = getConfidentialTestTokenAddress;
 exports.getDeployedAddress = getDeployedAddress;
 exports.getFheAirdropFactoryAddress = getFheAirdropFactoryAddress;
 exports.getFheDisperseSingletonAddress = getFheDisperseSingletonAddress;
 exports.getFheVestingFactoryAddress = getFheVestingFactoryAddress;
+exports.getTestTokenAddress = getTestTokenAddress;
+exports.requireConfidentialTestTokenAddress = requireConfidentialTestTokenAddress;
 exports.requireFheAirdropFactoryAddress = requireFheAirdropFactoryAddress;
 exports.requireFheDisperseSingletonAddress = requireFheDisperseSingletonAddress;
 exports.requireFheVestingFactoryAddress = requireFheVestingFactoryAddress;
+exports.requireTestTokenAddress = requireTestTokenAddress;