@tokenops/sdk 1.0.0 → 1.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (162) hide show
  1. package/README.md +120 -26
  2. package/dist/{chunk-5SGMJADP.cjs → chunk-2NCLOQ56.cjs} +9 -9
  3. package/dist/{chunk-QIHZVLIK.js → chunk-2PWNH3UE.js} +35 -6
  4. package/dist/{chunk-T5LVV3KY.cjs → chunk-4WPGQSNT.cjs} +3 -3
  5. package/dist/{chunk-SUOG3BQS.cjs → chunk-5X5WL5CU.cjs} +266 -103
  6. package/dist/{chunk-56UI7LUR.cjs → chunk-67OV5CX2.cjs} +19 -0
  7. package/dist/{chunk-WRCUDSUJ.js → chunk-6BMP4ICG.js} +2 -2
  8. package/dist/{chunk-XXXDQSHE.js → chunk-6R4KNAPK.js} +5 -3
  9. package/dist/{chunk-XSNLAS5M.js → chunk-AOP6HMPW.js} +1 -1
  10. package/dist/{chunk-62DF53UQ.cjs → chunk-C7BRZXJA.cjs} +19 -21
  11. package/dist/{chunk-UOG4PJL5.js → chunk-DUZIIRPF.js} +181 -14
  12. package/dist/{chunk-Q7ARQSUH.cjs → chunk-FAXIIH5R.cjs} +3 -3
  13. package/dist/chunk-FT4LNBOS.js +11 -0
  14. package/dist/chunk-IJFQ5L4I.js +2171 -0
  15. package/dist/{chunk-52TC6BF7.js → chunk-IXLO7GO5.js} +210 -47
  16. package/dist/{chunk-CQIPRNS7.cjs → chunk-JK4XMMKM.cjs} +3 -3
  17. package/dist/{chunk-ITQ7WKVC.cjs → chunk-JYOTGRSO.cjs} +8 -8
  18. package/dist/{chunk-VDXVNZCO.cjs → chunk-KLKI352M.cjs} +85 -29
  19. package/dist/{chunk-5SA2HF2W.cjs → chunk-MCRBVJGZ.cjs} +24 -22
  20. package/dist/{chunk-ECT3NL2L.js → chunk-NTZY6IB7.js} +4 -4
  21. package/dist/{chunk-ZHFLRKFY.js → chunk-ODLTEGHB.js} +1 -1
  22. package/dist/{chunk-HGXNRR25.js → chunk-ORFTDNFZ.js} +4 -4
  23. package/dist/{chunk-72YGZEQE.js → chunk-OXTLPTO3.js} +9 -11
  24. package/dist/{chunk-HTOMTEA3.cjs → chunk-PFXURMBZ.cjs} +77 -48
  25. package/dist/{chunk-OLDGMKW2.cjs → chunk-PUPKNW3R.cjs} +35 -2
  26. package/dist/{chunk-IVE3QEGD.js → chunk-QBJ7O2B4.js} +18 -1
  27. package/dist/{chunk-JFLEEXKP.js → chunk-SG65XWH7.js} +58 -2
  28. package/dist/{chunk-K6MFFDBJ.cjs → chunk-T46YXSBP.cjs} +11 -11
  29. package/dist/{chunk-NS44KBV5.cjs → chunk-TEBM66WA.cjs} +12 -12
  30. package/dist/{chunk-6ECAHP5O.cjs → chunk-TIUKIY5V.cjs} +200 -33
  31. package/dist/{chunk-QCA7O2Q5.cjs → chunk-V2PXZVBF.cjs} +4 -4
  32. package/dist/{chunk-JFR5J4FL.cjs → chunk-W7IGCOVL.cjs} +11 -11
  33. package/dist/chunk-WENHUPZC.cjs +2180 -0
  34. package/dist/{chunk-ZXCOJY2Z.js → chunk-WMACINXO.js} +1 -1
  35. package/dist/{chunk-COPFW5Z4.js → chunk-XGGTQQFH.js} +31 -2
  36. package/dist/{chunk-CMRETRZO.js → chunk-YQIBBEFJ.js} +1 -1
  37. package/dist/{chunk-BE2AIZ3K.js → chunk-ZA673I3O.js} +1 -1
  38. package/dist/chunk-ZQUE2B3Q.cjs +33 -0
  39. package/dist/{chunk-FYQ2UW4T.js → chunk-ZWXJTBZO.js} +1 -1
  40. package/dist/core/addresses.d.ts +22 -0
  41. package/dist/core/errors.d.ts +41 -1
  42. package/dist/core/revert-mapper.d.ts +77 -0
  43. package/dist/core/telemetry.d.ts +0 -3
  44. package/dist/core/wagmi-compat.d.ts +40 -0
  45. package/dist/fhe/index.cjs +112 -66
  46. package/dist/fhe/index.d.cts +1 -1
  47. package/dist/fhe/index.d.ts +1 -1
  48. package/dist/fhe/index.js +50 -8
  49. package/dist/fhe/operators.d.ts +1 -1
  50. package/dist/fhe/react/index.cjs +7 -7
  51. package/dist/fhe/react/index.js +2 -2
  52. package/dist/fhe/sepolia-encryptor-web.d.ts +27 -1
  53. package/dist/fhe/sepolia-encryptor.d.ts +38 -0
  54. package/dist/fhe-airdrop/advanced/factory-advanced.d.ts +3 -3
  55. package/dist/fhe-airdrop/advanced/index.cjs +9 -8
  56. package/dist/fhe-airdrop/advanced/index.d.cts +2 -2
  57. package/dist/fhe-airdrop/advanced/index.d.ts +2 -2
  58. package/dist/fhe-airdrop/advanced/index.js +7 -6
  59. package/dist/fhe-airdrop/advanced/react/index.cjs +14 -13
  60. package/dist/fhe-airdrop/advanced/react/index.d.cts +1 -1
  61. package/dist/fhe-airdrop/advanced/react/index.d.ts +1 -1
  62. package/dist/fhe-airdrop/advanced/react/index.js +10 -9
  63. package/dist/fhe-airdrop/airdrop.d.ts +2 -0
  64. package/dist/fhe-airdrop/encryption.d.ts +8 -0
  65. package/dist/fhe-airdrop/factory.d.ts +94 -11
  66. package/dist/fhe-airdrop/index.cjs +61 -57
  67. package/dist/fhe-airdrop/index.d.cts +3 -3
  68. package/dist/fhe-airdrop/index.d.ts +3 -3
  69. package/dist/fhe-airdrop/index.js +7 -7
  70. package/dist/fhe-airdrop/react/index.cjs +163 -133
  71. package/dist/fhe-airdrop/react/index.d.cts +4 -3
  72. package/dist/fhe-airdrop/react/index.d.ts +4 -3
  73. package/dist/fhe-airdrop/react/index.js +38 -13
  74. package/dist/fhe-airdrop/react/useAirdropClaim.d.ts +2 -0
  75. package/dist/fhe-airdrop/react/useAirdropIsSignatureValid.d.ts +3 -2
  76. package/dist/fhe-airdrop/react/useClaim.d.ts +2 -0
  77. package/dist/fhe-airdrop/react/useCreateAndFundConfidentialAirdrop.d.ts +8 -0
  78. package/dist/fhe-airdrop/react/useCreateAndFundConfidentialAirdropAndGetAddress.d.ts +8 -0
  79. package/dist/fhe-airdrop/react/useFundConfidentialAirdrop.d.ts +8 -0
  80. package/dist/fhe-airdrop/react/usePreflightCreateAirdrop.d.ts +51 -0
  81. package/dist/fhe-airdrop/types.d.ts +45 -0
  82. package/dist/fhe-disperse/encryption.d.ts +8 -0
  83. package/dist/fhe-disperse/index.cjs +69 -65
  84. package/dist/fhe-disperse/index.d.cts +1 -1
  85. package/dist/fhe-disperse/index.d.ts +1 -1
  86. package/dist/fhe-disperse/index.js +8 -8
  87. package/dist/fhe-disperse/react/index.cjs +90 -86
  88. package/dist/fhe-disperse/react/index.d.cts +1 -1
  89. package/dist/fhe-disperse/react/index.d.ts +1 -1
  90. package/dist/fhe-disperse/react/index.js +10 -10
  91. package/dist/fhe-disperse/react/useCalculateFee.d.ts +7 -0
  92. package/dist/fhe-disperse/react/useDisperse.d.ts +9 -0
  93. package/dist/fhe-disperse/react/usePreflightDisperse.d.ts +7 -0
  94. package/dist/fhe-disperse/react/useSingletonCalculateFee.d.ts +7 -0
  95. package/dist/fhe-disperse/react/useSingletonWithdrawTokenFee.d.ts +8 -2
  96. package/dist/fhe-disperse/react/useWithdrawTokenFee.d.ts +6 -0
  97. package/dist/fhe-disperse/singleton.d.ts +29 -0
  98. package/dist/fhe-disperse/subtotals.d.ts +6 -0
  99. package/dist/fhe-vesting/advanced/factory-advanced.d.ts +2 -2
  100. package/dist/fhe-vesting/advanced/index.cjs +8 -8
  101. package/dist/fhe-vesting/advanced/index.d.cts +2 -2
  102. package/dist/fhe-vesting/advanced/index.d.ts +2 -2
  103. package/dist/fhe-vesting/advanced/index.js +6 -6
  104. package/dist/fhe-vesting/advanced/react/index.cjs +15 -14
  105. package/dist/fhe-vesting/advanced/react/index.d.cts +1 -1
  106. package/dist/fhe-vesting/advanced/react/index.d.ts +1 -1
  107. package/dist/fhe-vesting/advanced/react/index.js +12 -11
  108. package/dist/fhe-vesting/encryption.d.ts +8 -0
  109. package/dist/fhe-vesting/factory.d.ts +6 -8
  110. package/dist/fhe-vesting/index.cjs +79 -75
  111. package/dist/fhe-vesting/index.d.cts +2 -2
  112. package/dist/fhe-vesting/index.d.ts +2 -2
  113. package/dist/fhe-vesting/index.js +9 -9
  114. package/dist/fhe-vesting/manager.d.ts +101 -3
  115. package/dist/fhe-vesting/react/index.cjs +241 -219
  116. package/dist/fhe-vesting/react/index.d.cts +3 -2
  117. package/dist/fhe-vesting/react/index.d.ts +3 -2
  118. package/dist/fhe-vesting/react/index.js +29 -12
  119. package/dist/fhe-vesting/react/useAdminClaim.d.ts +2 -0
  120. package/dist/fhe-vesting/react/useAdminPartialClaim.d.ts +2 -0
  121. package/dist/fhe-vesting/react/useBatchCreateVesting.d.ts +8 -0
  122. package/dist/fhe-vesting/react/useClaim.d.ts +2 -0
  123. package/dist/fhe-vesting/react/useCreateVesting.d.ts +8 -0
  124. package/dist/fhe-vesting/react/useManagerWithdrawTokenFee.d.ts +7 -1
  125. package/dist/fhe-vesting/react/usePartialClaim.d.ts +8 -0
  126. package/dist/fhe-vesting/react/usePreflightCreateVesting.d.ts +37 -0
  127. package/dist/fhe-vesting/react/useVestingClaim.d.ts +2 -0
  128. package/dist/fhe-vesting/react/useWithdrawAdmin.d.ts +6 -0
  129. package/dist/fhe-vesting/react/useWithdrawTokenFee.d.ts +6 -0
  130. package/dist/fhe-vesting/types.d.ts +34 -2
  131. package/dist/index.cjs +73 -49
  132. package/dist/index.d.cts +1 -1
  133. package/dist/index.d.ts +1 -1
  134. package/dist/index.js +2 -2
  135. package/dist/testnet-faucet/abis/confidential-test-token.d.ts +1039 -0
  136. package/dist/testnet-faucet/abis/index.d.ts +2 -0
  137. package/dist/testnet-faucet/abis/test-token.d.ts +253 -0
  138. package/dist/testnet-faucet/errors.d.ts +21 -0
  139. package/dist/testnet-faucet/faucet.d.ts +173 -0
  140. package/dist/testnet-faucet/index.cjs +212 -0
  141. package/dist/testnet-faucet/index.d.cts +8 -0
  142. package/dist/testnet-faucet/index.d.ts +8 -0
  143. package/dist/testnet-faucet/index.js +7 -0
  144. package/dist/testnet-faucet/react/_shared.d.ts +61 -0
  145. package/dist/testnet-faucet/react/index.cjs +384 -0
  146. package/dist/testnet-faucet/react/index.d.cts +39 -0
  147. package/dist/testnet-faucet/react/index.d.ts +39 -0
  148. package/dist/testnet-faucet/react/index.js +220 -0
  149. package/dist/testnet-faucet/react/useConfidentialBalance.d.ts +25 -0
  150. package/dist/testnet-faucet/react/useFaucetDecimals.d.ts +9 -0
  151. package/dist/testnet-faucet/react/useFaucetMetadata.d.ts +14 -0
  152. package/dist/testnet-faucet/react/useFaucetRate.d.ts +11 -0
  153. package/dist/testnet-faucet/react/useInferredTotalSupply.d.ts +11 -0
  154. package/dist/testnet-faucet/react/useMaxTotalSupply.d.ts +10 -0
  155. package/dist/testnet-faucet/react/useMintConfidential.d.ts +35 -0
  156. package/dist/testnet-faucet/react/useMintUnderlying.d.ts +31 -0
  157. package/dist/testnet-faucet/react/useUnderlyingBalance.d.ts +19 -0
  158. package/dist/testnet-faucet/react/useUnderlyingDecimals.d.ts +9 -0
  159. package/dist/testnet-faucet/react/useUnderlyingTokenAddress.d.ts +12 -0
  160. package/dist/testnet-faucet/types.d.ts +92 -0
  161. package/dist/testnet-faucet/validate.d.ts +44 -0
  162. package/package.json +79 -30
package/README.md CHANGED
@@ -3,9 +3,9 @@
3
3
  [![npm version](https://img.shields.io/npm/v/%40tokenops%2Fsdk?style=flat-square)](https://www.npmjs.com/package/@tokenops/sdk)
4
4
  [![license](https://img.shields.io/npm/l/%40tokenops%2Fsdk?style=flat-square)](https://github.com/VestingLabs/tokenops-sdk/blob/main/LICENSE)
5
5
 
6
- 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.
6
+ 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.
7
7
 
8
- **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).
8
+ **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).
9
9
 
10
10
  ## Install
11
11
 
@@ -21,22 +21,24 @@ Node `>= 22` is required (constraint from `@zama-fhe/sdk`).
21
21
 
22
22
  All subpaths are independently tree-shakeable. The `/react` paths keep React deps out of the server bundle.
23
23
 
24
- | Subpath | Status | Description |
25
- | ------------------------------------------ | ----------------------------------- | ---------------------------------------------------------------------------------- |
26
- | `@tokenops/sdk` | stable | Root re-exports (version, core error types) |
27
- | `@tokenops/sdk/telemetry` | stable | Telemetry sink adapters (`NoopTelemetry`, `ConsoleTelemetry`, `TokenOpsTelemetry`) |
28
- | `@tokenops/sdk/fhe` | stable | FHE utility helpers (ratio scaling, encrypted-input types, operator helpers) |
29
- | `@tokenops/sdk/fhe/react` | stable | React hooks for shared FHE utilities |
30
- | `@tokenops/sdk/fhe-vesting` | factory live on Sepolia | Confidential vesting (LibClone + packed immutable args) |
31
- | `@tokenops/sdk/fhe-vesting/react` | stable | React/wagmi hooks for confidential vesting |
32
- | `@tokenops/sdk/fhe-vesting/advanced` | stable | Pre-mine address prediction (`predictManagerAddress`) |
33
- | `@tokenops/sdk/fhe-vesting/advanced/react` | stable | React hooks for advanced vesting flows |
34
- | `@tokenops/sdk/fhe-airdrop` | factory live on Sepolia | ConfidentialAirdrop (EIP-712 gated confidential claims) |
35
- | `@tokenops/sdk/fhe-airdrop/react` | stable | React/wagmi hooks for confidential airdrops |
36
- | `@tokenops/sdk/fhe-airdrop/advanced` | stable | Pre-mine address prediction (`predictAirdropAddress`) |
37
- | `@tokenops/sdk/fhe-airdrop/advanced/react` | stable | React hooks for advanced airdrop flows |
38
- | `@tokenops/sdk/fhe-disperse` | singleton live on mainnet + Sepolia | DisperseConfidential (singleton + per-user wallet-pair clones) |
39
- | `@tokenops/sdk/fhe-disperse/react` | stable | React/wagmi hooks for confidential disperse |
24
+ | Subpath | Status | Description |
25
+ | ------------------------------------------ | ----------------------------------- | --------------------------------------------------------------------------------------------------------- |
26
+ | `@tokenops/sdk` | stable | Root re-exports (version, core error types) |
27
+ | `@tokenops/sdk/telemetry` | stable | Telemetry sink adapters (`NoopTelemetry`, `ConsoleTelemetry`, `TokenOpsTelemetry`) |
28
+ | `@tokenops/sdk/fhe` | stable | FHE utility helpers (ratio scaling, encrypted-input types, operator helpers) |
29
+ | `@tokenops/sdk/fhe/react` | stable | React hooks for shared FHE utilities |
30
+ | `@tokenops/sdk/fhe-vesting` | factory live on Sepolia | Confidential vesting (LibClone + packed immutable args) |
31
+ | `@tokenops/sdk/fhe-vesting/react` | stable | React/wagmi hooks for confidential vesting |
32
+ | `@tokenops/sdk/fhe-vesting/advanced` | stable | Pre-mine address prediction (`predictManagerAddress`) |
33
+ | `@tokenops/sdk/fhe-vesting/advanced/react` | stable | React hooks for advanced vesting flows |
34
+ | `@tokenops/sdk/fhe-airdrop` | factory live on Sepolia | ConfidentialAirdrop (EIP-712 gated confidential claims) |
35
+ | `@tokenops/sdk/fhe-airdrop/react` | stable | React/wagmi hooks for confidential airdrops |
36
+ | `@tokenops/sdk/fhe-airdrop/advanced` | stable | Pre-mine address prediction (`predictAirdropAddress`) |
37
+ | `@tokenops/sdk/fhe-airdrop/advanced/react` | stable | React hooks for advanced airdrop flows |
38
+ | `@tokenops/sdk/fhe-disperse` | singleton live on mainnet + Sepolia | DisperseConfidential (singleton + per-user wallet-pair clones) |
39
+ | `@tokenops/sdk/fhe-disperse/react` | stable | React/wagmi hooks for confidential disperse |
40
+ | `@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 |
41
+ | `@tokenops/sdk/testnet-faucet/react` | stable | React/wagmi hooks for the testnet faucet |
40
42
 
41
43
  The canonical exports map is in [`package.json`](https://github.com/VestingLabs/tokenops-sdk/blob/main/package.json) under `"exports"`.
42
44
 
@@ -635,19 +637,110 @@ function DispersePanel({
635
637
 
636
638
  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.
637
639
 
640
+ ## Quickstart — testnet faucet
641
+
642
+ 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.
643
+
644
+ ```ts
645
+ import { createPublicClient, createWalletClient, http } from "viem";
646
+ import { sepolia } from "viem/chains";
647
+ import { privateKeyToAccount } from "viem/accounts";
648
+ import { createTestnetFaucetClient } from "@tokenops/sdk/testnet-faucet";
649
+
650
+ const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
651
+ const rpcUrl = process.env.RPC_URL!;
652
+ const publicClient = createPublicClient({ chain: sepolia, transport: http(rpcUrl) });
653
+ const walletClient = createWalletClient({ account, chain: sepolia, transport: http(rpcUrl) });
654
+
655
+ // CTTT + TTT addresses resolve automatically from DEPLOYED_ADDRESSES on Sepolia.
656
+ const faucet = createTestnetFaucetClient({ publicClient, walletClient });
657
+
658
+ // Mint 1,000 CTTT (6-decimal units) to myself, fully backed by freshly minted TTT.
659
+ // The amount is PUBLIC; only the recipient's aggregated balance stays confidential.
660
+ const { hash } = await faucet.mintConfidential({ amount: 1_000_000_000n });
661
+ console.log("Confidential mint tx:", hash);
662
+
663
+ // Read my encrypted confidential balance handle, then user-decrypt it with your
664
+ // own @zama-fhe/sdk relayer instance (the SDK is the producer side only).
665
+ const balanceHandle = await faucet.confidentialBalanceOf();
666
+
667
+ // Or mint plain ERC-20 TTT (18-decimal units) — e.g. to approve + wrap yourself.
668
+ await faucet.mintUnderlying({ amount: 5n * 10n ** 18n });
669
+ ```
670
+
671
+ ### Quickstart — testnet faucet (React hooks)
672
+
673
+ Uses `@tokenops/sdk/testnet-faucet/react`. Requires `wagmi` and `@tanstack/react-query` — but **not** `@zama-fhe/react-sdk` (no encryptor for public faucet mints).
674
+
675
+ ```tsx
676
+ import { useQueryClient } from "@tanstack/react-query";
677
+ import {
678
+ useFaucetMetadata,
679
+ useConfidentialBalance,
680
+ useMintConfidential,
681
+ } from "@tokenops/sdk/testnet-faucet/react";
682
+
683
+ // Wrap your app in wagmi's <WagmiProvider> + <QueryClientProvider>.
684
+ // No <ZamaProvider> needed — faucet mints take PUBLIC plaintext amounts.
685
+
686
+ function FaucetPanel() {
687
+ const queryClient = useQueryClient();
688
+ const { data: meta } = useFaucetMetadata();
689
+ const { data: balanceHandle } = useConfidentialBalance(); // my own encrypted balance handle
690
+ const mint = useMintConfidential();
691
+
692
+ return (
693
+ <div>
694
+ {meta && (
695
+ <p>
696
+ {meta.confidential.symbol} · {meta.confidential.decimals} decimals · rate{" "}
697
+ {meta.rate.toString()}
698
+ </p>
699
+ )}
700
+ <button
701
+ onClick={() =>
702
+ mint.mutate(
703
+ { amount: 1_000_000_000n }, // 1,000 CTTT (6-decimal units)
704
+ {
705
+ onSuccess: () =>
706
+ queryClient.invalidateQueries({ queryKey: ["tokenops-sdk", "testnet-faucet"] }),
707
+ },
708
+ )
709
+ }
710
+ disabled={mint.isPending}
711
+ >
712
+ {mint.isPending ? "Minting…" : "Mint 1,000 CTTT"}
713
+ </button>
714
+ </div>
715
+ );
716
+ }
717
+ ```
718
+
719
+ 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.
720
+
638
721
  ## Peer dependencies
639
722
 
640
- | Package | Range | Required for |
641
- | ----------------------- | -------- | ------------------------------------------------------------------------------ |
642
- | `viem` | `^2.47` | all subpaths (hard required) |
643
- | `@zama-fhe/sdk` | `^3.0.0` | encryption + decryption + FHE write flows on every FHE subpath (optional peer) |
644
- | `@zama-fhe/react-sdk` | `^3.0.0` | `/react` hook subpaths that submit encrypted inputs (optional peer) |
645
- | `react` | `>=18` | `/react` hook subpaths (optional peer) |
646
- | `wagmi` | `^2` | `/react` hook subpaths (optional peer) |
647
- | `@tanstack/react-query` | `^5` | `/react` hook subpaths (optional peer) |
723
+ | Package | Range | Required for |
724
+ | ----------------------- | ------------ | ------------------------------------------------------------------------------ |
725
+ | `viem` | `^2.47` | all subpaths (hard required) |
726
+ | `@zama-fhe/sdk` | `^3.0.0` | encryption + decryption + FHE write flows on every FHE subpath (optional peer) |
727
+ | `@zama-fhe/react-sdk` | `^3.0.0` | `/react` hook subpaths that submit encrypted inputs (optional peer) |
728
+ | `react` | `>=18` | `/react` hook subpaths (optional peer) |
729
+ | `wagmi` | `^2 \|\| ^3` | `/react` hook subpaths (optional peer) |
730
+ | `@tanstack/react-query` | `^5` | `/react` hook subpaths (optional peer) |
648
731
 
649
732
  All peers except `viem` are marked `optional` via `peerDependenciesMeta` so read-only / ABI-only consumers can install the package without pulling them in. Install `@zama-fhe/sdk` explicitly the first time you encrypt, decrypt, or submit an FHE write; install the React peers if you use any `/react` hook subpath.
650
733
 
734
+ ### wagmi v2 and v3
735
+
736
+ The SDK supports both wagmi majors. wagmi v3 renamed `useAccount` → `useConnection`; the SDK resolves the right hook internally at runtime, so no code change is needed on your side when you upgrade — the hooks' public API is identical under both majors. CI typechecks and runs the hook suites against both.
737
+
738
+ **Still seeing `ERESOLVE` after upgrading to wagmi v3?** The error is almost certainly coming from _another_ package in your dependency tree, not from `@tokenops/sdk` (which accepts `^2.0.0 || ^3.0.0`). To diagnose:
739
+
740
+ 1. Read the `ERESOLVE` output carefully — npm names the package whose peer range could not be satisfied (`Could not resolve dependency: peer wagmi@"^2.x" from <package>@<version>`). If `<package>` is not `@tokenops/sdk`, that package still pins wagmi v2.
741
+ 2. Confirm with `npm ls wagmi` (or `pnpm why wagmi`) — it prints every dependent and the range each one declares.
742
+ 3. Fix by upgrading the offending package to a wagmi-v3-compatible release, or — if none exists yet — stay on wagmi v2 (fully supported by this SDK) until it does. npm's `--legacy-peer-deps` / pnpm's looser peer handling can silence the error, but you are then running that package against a wagmi major it does not declare support for.
743
+
651
744
  ## Design
652
745
 
653
746
  - **Single package, subpath exports.** No companion `@tokenops/react-sdk` — hooks live at `@tokenops/sdk/<product>/react`.
@@ -660,6 +753,7 @@ All peers except `viem` are marked `optional` via `peerDependenciesMeta` so read
660
753
  - [Confidential Vesting (`@tokenops/sdk/fhe-vesting`)](https://docs.tokenops.xyz/sdk/fhe-vesting)
661
754
  - [Confidential Airdrop (`@tokenops/sdk/fhe-airdrop`)](https://docs.tokenops.xyz/sdk/fhe-airdrop)
662
755
  - [Confidential Disperse (`@tokenops/sdk/fhe-disperse`)](https://docs.tokenops.xyz/sdk/fhe-disperse)
756
+ - [Testnet Faucet (`@tokenops/sdk/testnet-faucet`)](https://docs.tokenops.xyz/sdk/testnet-faucet)
663
757
  - [Local dev with `link:`](https://docs.tokenops.xyz/sdk/local-dev)
664
758
 
665
759
  ## Development
@@ -1,6 +1,6 @@
1
1
  'use strict';
2
2
 
3
- var chunk56UI7LUR_cjs = require('./chunk-56UI7LUR.cjs');
3
+ var chunk67OV5CX2_cjs = require('./chunk-67OV5CX2.cjs');
4
4
 
5
5
  // src/fhe/scale-ratio.ts
6
6
  var FHE_SPLIT_DENOMINATOR = 90090000n;
@@ -15,7 +15,7 @@ function scaleRatio({
15
15
  width = "uint128"
16
16
  }) {
17
17
  if (denominator <= 0n) {
18
- throw new chunk56UI7LUR_cjs.InvalidArgumentError({
18
+ throw new chunk67OV5CX2_cjs.InvalidArgumentError({
19
19
  method: "scaleRatio",
20
20
  argument: "denominator",
21
21
  reason: `must be > 0, got ${denominator}`,
@@ -23,7 +23,7 @@ function scaleRatio({
23
23
  });
24
24
  }
25
25
  if (numerator < 0n) {
26
- throw new chunk56UI7LUR_cjs.InvalidArgumentError({
26
+ throw new chunk67OV5CX2_cjs.InvalidArgumentError({
27
27
  method: "scaleRatio",
28
28
  argument: "numerator",
29
29
  reason: `must be >= 0, got ${numerator}`,
@@ -31,7 +31,7 @@ function scaleRatio({
31
31
  });
32
32
  }
33
33
  if (minDenominator <= 0n) {
34
- throw new chunk56UI7LUR_cjs.InvalidArgumentError({
34
+ throw new chunk67OV5CX2_cjs.InvalidArgumentError({
35
35
  method: "scaleRatio",
36
36
  argument: "minDenominator",
37
37
  reason: `must be > 0, got ${minDenominator}`,
@@ -51,7 +51,7 @@ function scaleRatio({
51
51
  function assertWithinWidth(value, width, label) {
52
52
  const max = width === "uint64" ? MAX_UINT64 : MAX_UINT128;
53
53
  if (value > max) {
54
- throw new chunk56UI7LUR_cjs.InvalidArgumentError({
54
+ throw new chunk67OV5CX2_cjs.InvalidArgumentError({
55
55
  method: "scaleRatio",
56
56
  argument: label,
57
57
  reason: `exceeds ${width} range`,
@@ -78,7 +78,7 @@ var share = {
78
78
  const n = toIntegerBigInt(numerator, "share.fraction", "numerator");
79
79
  const m = toIntegerBigInt(denominator, "share.fraction", "denominator");
80
80
  if (m <= 0n || m > MAX_FRACTION_DENOMINATOR) {
81
- throw new chunk56UI7LUR_cjs.InvalidArgumentError({
81
+ throw new chunk67OV5CX2_cjs.InvalidArgumentError({
82
82
  method: "share.fraction",
83
83
  argument: "denominator",
84
84
  reason: `must be in 1..${MAX_FRACTION_DENOMINATOR}, got ${m}`,
@@ -86,7 +86,7 @@ var share = {
86
86
  });
87
87
  }
88
88
  if (n < 0n || n > m) {
89
- throw new chunk56UI7LUR_cjs.InvalidArgumentError({
89
+ throw new chunk67OV5CX2_cjs.InvalidArgumentError({
90
90
  method: "share.fraction",
91
91
  argument: "numerator",
92
92
  reason: `must be in 0..${m} (denominator), got ${n}`,
@@ -111,7 +111,7 @@ var share = {
111
111
  basisPoints(bps) {
112
112
  const value = toIntegerBigInt(bps, "share.basisPoints", "bps");
113
113
  if (value < 0n || value > BASIS_POINT_SCALE) {
114
- throw new chunk56UI7LUR_cjs.InvalidArgumentError({
114
+ throw new chunk67OV5CX2_cjs.InvalidArgumentError({
115
115
  method: "share.basisPoints",
116
116
  argument: "bps",
117
117
  reason: `must be in 0..${BASIS_POINT_SCALE}, got ${value}`,
@@ -124,7 +124,7 @@ var share = {
124
124
  function toIntegerBigInt(value, method, argument) {
125
125
  if (typeof value === "bigint") return value;
126
126
  if (!Number.isInteger(value)) {
127
- throw new chunk56UI7LUR_cjs.InvalidArgumentError({
127
+ throw new chunk67OV5CX2_cjs.InvalidArgumentError({
128
128
  method,
129
129
  argument,
130
130
  reason: `must be an integer, got ${value}`,
@@ -1,11 +1,11 @@
1
- import { mapZamaError } from './chunk-ZXCOJY2Z.js';
2
- import { getFhevmAclAddress, requireFhevmAclAddress, ACL_ALLOWED_EVENT } from './chunk-FYQ2UW4T.js';
3
- import { SDK_VERSION, isContractRevert, mapContractRevert } from './chunk-JFLEEXKP.js';
4
- import { getFheDisperseSingletonAddress } from './chunk-COPFW5Z4.js';
5
- import { normaliseAddress } from './chunk-BE2AIZ3K.js';
1
+ import { mapZamaError } from './chunk-WMACINXO.js';
2
+ import { getFhevmAclAddress, requireFhevmAclAddress, ACL_ALLOWED_EVENT } from './chunk-ZWXJTBZO.js';
3
+ import { SDK_VERSION, isContractRevert, mapContractRevert } from './chunk-SG65XWH7.js';
4
+ import { getFheDisperseSingletonAddress } from './chunk-XGGTQQFH.js';
5
+ import { normaliseAddress } from './chunk-ZA673I3O.js';
6
6
  import { withTelemetry } from './chunk-Q2GP5UDC.js';
7
7
  import { asExternalInputProof, asEncryptedHandle } from './chunk-KWFFIJYX.js';
8
- import { InvalidArgumentError, TokenOpsSdkError, DeploymentAddressUnavailableError, PausedError, InsufficientFeeError, MissingEncryptorError, ReceiptEventAmbiguousError, MissingWalletClientError, MissingAccountError, BatchTooLargeError } from './chunk-IVE3QEGD.js';
8
+ import { InvalidArgumentError, TokenOpsSdkError, DeploymentAddressUnavailableError, PausedError, InsufficientFeeError, MissingEncryptorError, ReceiptEventAmbiguousError, MissingWalletClientError, MissingAccountError, BatchTooLargeError } from './chunk-QBJ7O2B4.js';
9
9
  import { bytesToHex, keccak256, encodePacked, parseEventLogs, isAddress, getCreate2Address } from 'viem';
10
10
 
11
11
  // src/fhe-disperse/abis/singleton.ts
@@ -2166,6 +2166,13 @@ var ConfidentialDisperseClient = class {
2166
2166
  * subtotal1` for the result to match the on-chain computation. Both this
2167
2167
  * SDK and the contract round the BPS multiplication down (floor division).
2168
2168
  *
2169
+ * **Amount units:** TokenOps confidential (ERC-7984) tokens use a 6-decimals
2170
+ * convention (1 token = 1_000_000 base units), not the 18 decimals typical of
2171
+ * ERC-20. Amount parameters are base units of the token's actual decimals:
2172
+ * for the CTTT test token (6 decimals) `1_000_000n` = 1 CTTT, while the
2173
+ * transparent TTT test token uses 18 decimals. `totalTokens` follows this
2174
+ * convention.
2175
+ *
2169
2176
  * @throws {TokenOpsSdkError} if mode is `"wallet-token-fee"` and `totalTokens` is not provided.
2170
2177
  */
2171
2178
  async calculateFee(args) {
@@ -2229,6 +2236,13 @@ var ConfidentialDisperseClient = class {
2229
2236
  * - `hasApprovedSubwallets` (wallet modes) or `isOperator(sender, singleton)` (direct mode)
2230
2237
  * - `calculateFee` / `getBatchLimits`
2231
2238
  * - Structural recipient + amount validation
2239
+ *
2240
+ * **Amount units:** TokenOps confidential (ERC-7984) tokens use a 6-decimals
2241
+ * convention (1 token = 1_000_000 base units), not the 18 decimals typical of
2242
+ * ERC-20. Amount parameters are base units of the token's actual decimals:
2243
+ * for the CTTT test token (6 decimals) `1_000_000n` = 1 CTTT, while the
2244
+ * transparent TTT test token uses 18 decimals. Pass `amounts[]` in the same
2245
+ * units you will pass to `disperse` so the report reflects the real call.
2232
2246
  */
2233
2247
  async preflightDisperse(args) {
2234
2248
  const { user, token, recipients, amounts, mode } = args;
@@ -2474,6 +2488,15 @@ var ConfidentialDisperseClient = class {
2474
2488
  * 4. Computes `msg.value` for gas-fee modes; `0` for token-fee mode.
2475
2489
  * 5. Dispatches to the correct contract function based on `mode`.
2476
2490
  *
2491
+ * **Silent-zero transfers.** ERC-7984 transfers do not revert when the sender's encrypted balance is insufficient — the transfer succeeds and moves an encrypted zero instead. This is by design: reverting would leak balance information. The transaction receipt alone cannot tell you whether value actually moved.
2492
+ *
2493
+ * **Amount units:** TokenOps confidential (ERC-7984) tokens use a 6-decimals
2494
+ * convention (1 token = 1_000_000 base units), not the 18 decimals typical of
2495
+ * ERC-20. Amount parameters are base units of the token's actual decimals:
2496
+ * for the CTTT test token (6 decimals) `1_000_000n` = 1 CTTT, while the
2497
+ * transparent TTT test token uses 18 decimals. Every entry of `amounts[]`
2498
+ * follows this convention.
2499
+ *
2477
2500
  * @throws {TokenOpsSdkError} on input validation failure (first deterministic error).
2478
2501
  * @throws {TokenOpsSdkError} if no encryptor is available at call time.
2479
2502
  */
@@ -2789,6 +2812,12 @@ var ConfidentialDisperseClient = class {
2789
2812
  * encryptor, or pass `encryptedInput` directly. The contract caps the
2790
2813
  * withdrawal at the available reserve via `FHE.min`.
2791
2814
  *
2815
+ * **Amount units:** TokenOps confidential (ERC-7984) tokens use a 6-decimals
2816
+ * convention (1 token = 1_000_000 base units), not the 18 decimals typical of
2817
+ * ERC-20. Amount parameters are base units of the token's actual decimals:
2818
+ * for the CTTT test token (6 decimals) `1_000_000n` = 1 CTTT, while the
2819
+ * transparent TTT test token uses 18 decimals.
2820
+ *
2792
2821
  * Returns the tx hash plus the **transferred** handle parsed from the
2793
2822
  * `TokenFeeWithdrawn` event. Decrypt the handle via Zama's `userDecrypt`
2794
2823
  * to view the actual amount moved (which can be less than requested when
@@ -1,9 +1,9 @@
1
1
  'use strict';
2
2
 
3
- var chunk6ECAHP5O_cjs = require('./chunk-6ECAHP5O.cjs');
3
+ var chunkTIUKIY5V_cjs = require('./chunk-TIUKIY5V.cjs');
4
4
 
5
5
  // src/fhe-airdrop/advanced/factory-advanced.ts
6
- var ConfidentialAirdropFactoryAdvancedClient = class extends chunk6ECAHP5O_cjs.ConfidentialAirdropFactoryClient {
6
+ var ConfidentialAirdropFactoryAdvancedClient = class extends chunkTIUKIY5V_cjs.ConfidentialAirdropFactoryClient {
7
7
  /**
8
8
  * Compute the deterministic CREATE2 address for an airdrop clone without
9
9
  * deploying it.
@@ -21,7 +21,7 @@ var ConfidentialAirdropFactoryAdvancedClient = class extends chunk6ECAHP5O_cjs.C
21
21
  async predictAirdropAddress(args) {
22
22
  return this.publicClient.readContract({
23
23
  address: this.address,
24
- abi: chunk6ECAHP5O_cjs.confidentialAirdropFactoryAbi,
24
+ abi: chunkTIUKIY5V_cjs.confidentialAirdropFactoryAbi,
25
25
  functionName: "predictAirdropAddress",
26
26
  args: [toAbiParams(args.params), args.userSalt, args.deployer, args.gasFee]
27
27
  });