@tokenops/sdk 1.5.1 → 1.6.0

package/CHANGELOG.md

@@ -5,6 +5,152 @@ All notable changes to `@tokenops/sdk` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.0](https://github.com/VestingLabs/tokenops-sdk/compare/v1.5.1...v1.6.0) (2026-07-28)
+
+
+### Features
+
+* **fhe:** add operator prerequisite DX helpers (S2, TOK-75) ([#63](https://github.com/VestingLabs/tokenops-sdk/issues/63)) ([ef45c2e](https://github.com/VestingLabs/tokenops-sdk/commit/ef45c2e61529f57a2b2338c7573b466e57fbf2cf))
+
+
+### Bug Fixes
+
+* **airdrop:** stop preflightCreateAirdrop throwing on a non-ERC7984 token (TOK-436) ([b650324](https://github.com/VestingLabs/tokenops-sdk/commit/b6503243cb430fe224913fbbb39251586a4d4925))
+* correct operator-deadline guidance in SECURITY.md, record advisory rationale ([b09273d](https://github.com/VestingLabs/tokenops-sdk/commit/b09273d7d911a4dcfdfe8e2ae7f4e3a24c2130e8))
+* **fhe-vesting:** point Sepolia factory at the redeployed address ([0888404](https://github.com/VestingLabs/tokenops-sdk/commit/08884040987d0ebb4326d1fb80a2c2d630a6e3a6))
+* **vesting:** stop preflightCreateVesting throwing on a non-ERC7984 token ([dfbc795](https://github.com/VestingLabs/tokenops-sdk/commit/dfbc795fa7f0fd2aee9e1abfb711e82bca22ec4c))
+
+## [Unreleased]
+
+### Added — operator prerequisite DX helpers (TOK-75)
+
+- **`isOperator()` and `ensureOperator()`** — new headless operator-prerequisite helpers on `@tokenops/sdk/fhe`. `isOperator({ publicClient, token, holder, spender })` is a read-only check of `spender`'s ERC-7984 operator status for `holder` on `token` (an expired grant reads `false` — expiry needs no revoke tx). `ensureOperator({ publicClient, walletClient, token, spender, deadline, account?, waitForReceipt? })` is the idempotent check-then-set: it resolves `{ alreadyOperator: true, hash: null }` without sending a transaction when the grant is already active (cost: one `eth_call`), and otherwise performs the `setOperator` write and returns its hash. `deadline` is **required** — unlike `setOperator`, `ensureOperator` refuses to silently default a security-sensitive approval window to the never-expiring `ERC7984_OPERATOR_MAX_DEADLINE`; pass that constant explicitly if forever is what you want. Out-of-range deadlines (`<= 0` or `> 2**48 - 1`) and unresolvable accounts throw `TokenOpsContractError` before any RPC call. Caveat (documented in TSDoc): the pre-check confirms the grant is currently active, not until when — `ensureOperator` does not refresh a grant that expires mid-flow; call `setOperator` directly to extend a window.
+- **`useIsOperator` and `useEnsureOperator` React hooks** — the same prerequisite pair for wagmi + TanStack Query apps, exported from `@tokenops/sdk/fhe/react` and re-exported from `@tokenops/sdk/fhe-vesting/react`, `@tokenops/sdk/fhe-airdrop/react`, and `@tokenops/sdk/fhe-disperse/react`. `useIsOperator({ token, spender, holder?, chainId?, enabled? })` returns `UseQueryResult<boolean, Error>` — `holder` defaults to the connected account and the query stays disabled until `token`, `holder`, and `spender` are all present. Query key: `["tokenops-sdk", "fhe", "isOperator", chainId, token, holder, spender]` (lowercased addresses) — invalidate it after a successful grant. `useEnsureOperator({ chainId? })` returns `UseMutationResult<EnsureOperatorResult, Error, EnsureOperatorVariables>` and throws `MissingPublicClientError` / `MissingWalletClientError` when the wagmi clients are unavailable.
+- New exported types: `IsOperatorArgs`, `EnsureOperatorArgs`, `EnsureOperatorResult` from `@tokenops/sdk/fhe`; `UseIsOperatorOptions`, `UseEnsureOperatorOptions`, `EnsureOperatorVariables` from `@tokenops/sdk/fhe/react` and the three product `/react` subpaths.
+- `ConfidentialVestingManagerClient.createVesting` and `.batchCreateVesting` TSDoc now documents the operator prerequisite (set the manager as operator via `token.setOperator(...)` or `ensureOperator()`) and the `OperatorNotApprovedError` thrown when it is skipped. Documentation only; no runtime change.
+
+### Added — typed approval blockers in `preflightDisperse` (TOK-69)
+
+- **`SubwalletsNotApprovedError` and `SingletonNotApprovedError`** — `ConfidentialDisperseClient.preflightDisperse` now pushes typed errors into `PreflightReport.blockerErrors[]` for the two approval checks that were previously string-only entries in the deprecated `blockers: string[]`: `SubwalletsNotApprovedError` (`TOKENOPS_SUBWALLETS_NOT_APPROVED`, `context.{wallet0Approved,wallet1Approved}`; emitted in `"wallet"` / `"wallet-token-fee"` modes when the **registered** sub-wallet pair is not fully approved — unregistered users get only `NotRegisteredError`, with approval state still reported informationally via `hasApprovedSubwallets`) and `SingletonNotApprovedError` (`TOKENOPS_SINGLETON_NOT_APPROVED`; emitted in `"direct"` mode when the sender has not approved the singleton as ERC-7984 operator). Both classes are exported from `@tokenops/sdk/fhe-disperse` and `/fhe-disperse/react`; both codes join the `TokenOpsSdkErrorCode` union. Errors are collected, never thrown — the preflight contract is unchanged.
+
+### Added
+
+- **`Encryptor`, `EncryptorSource`, and `FheValueInput` re-exported from `@tokenops/sdk/fhe`** — next to the `createSepoliaEncryptor*` / `createMockEncryptor` factories that produce them. Previously these types were only importable from the product subpaths even though the factories live on `/fhe` (TOK-69).
+- **Opt-in `threads` option on `createSepoliaEncryptorWeb`** — `CreateSepoliaEncryptorWebOpts.threads?: number` is forwarded to the Zama relayer's WASM worker pool for multi-threaded encryption (~2–3× faster at 4–8 threads). Requires a cross-origin-isolated page (`Cross-Origin-Opener-Policy: same-origin` + `Cross-Origin-Embedder-Policy: require-corp`); when `threads > 1` is set on a non-isolated page the SDK logs a warning (configured logger or `console.warn`) explaining that encryption will silently run single-threaded and which headers to add. Omitting `threads` keeps the single-threaded default (TOK-69).
+
+### Changed
+
+- **Sepolia `confidentialVestingFactory` address updated to `0x059d6Bb8ff9a13E794fe416d4757d7310CdC69ab`** (was `0xA87701CE9A52D43681600583a99c85b50DbE3150`). The factory was redeployed with the post-audit fix that packs a constant zero as the clone's deployment-block-number immutable arg (the `DEPLOYMENT_BLOCK_NUMBER` getter surfaced as `ConfidentialVestingManagerClient.deploymentBlockNumber()`), and with `defaultGasFee = 0` instead of `3500000000000`. `getFheVestingFactoryAddress(sepolia.id)` and `DEPLOYED_ADDRESSES.fheVesting.confidentialVestingFactory[11155111]` now resolve to the new address. Managers already created through the old factory are unaffected and remain usable — construct their clients with an explicit `address`. Side effect of the constant-zero packing: `predictManagerAddress` against the new factory is block-stable (predict-then-deploy works on Sepolia again), unlike the old factory where the packed `block.number` made predictions single-block.
+- **`createMockEncryptor` / `createSepoliaEncryptor` peer-dependency errors now carry `cause`** — the `Error` thrown when a required peer dependency fails to dynamically import now attaches the original import failure as `error.cause`, restoring the error chain for programmatic inspection. Message unchanged; no migration needed.
+
+### Deprecated
+
+- **`useGet*` encrypted-view hooks renamed to `useAccess*`** (TOK-69) — the encrypted-view hooks are mutations that submit a transaction, and the `useGet*` names read as free queries, which misled integrators. `@tokenops/sdk/fhe-vesting/react` now exports `useAccessVestedAmount`, `useAccessClaimableAmount`, `useAccessTotalAllocation`, `useAccessSettledAmount` (plus `UseAccess*Args` types); `@tokenops/sdk/fhe-airdrop/react` now exports `useAccessClaimAmount`. The old `useGetVestedAmount` / `useGetClaimableAmount` / `useGetTotalAllocation` / `useGetSettledAmount` / `useGetClaimAmount` names (and `UseGet*Args` types) remain exported as `@deprecated` aliases of the same function objects — identical behavior, arguments, and thrown errors — and will be removed in the next major. Migration: rename the import; nothing else changes. Only visible delta: the `MissingClientError` raised when no client is available now names the `useAccess*` hook in its message and `context.hook`, even when called via the alias.
+
+### Fixed
+
+- **`preflightCreateAirdrop` no longer throws on a non-ERC-7984 token** (TOK-436). Passing a `params.token` that is not a confidential token — a deployed contract without the `isOperator(address,address)` selector, or an EOA/undeployed address — previously rejected the preflight's internal `Promise.all` and threw the raw viem error out of `ConfidentialAirdropFactoryClient.preflightCreateAirdrop`. It now resolves with `ready: false` and a typed `InvalidArgumentError` (`TOKENOPS_INVALID_ARGUMENT`, `context.argument: "params.token"`) in `blockers`/`blockerErrors`; `isFactoryOperator` reports `false` (undetermined). Infrastructure failures (HTTP errors, timeouts) still propagate, so an RPC outage is never misreported as a bad token. `usePreflightCreateAirdrop` now resolves with the report instead of entering its query error state.
+- **`preflightCreateVesting` no longer throws on a non-ERC-7984 token.** Same fix on `ConfidentialVestingManagerClient.preflightCreateVesting`: a failed `isOperator` read on the manager's bound distribution token becomes a typed `InvalidArgumentError` blocker instead of a thrown error; `isOperatorSet` reports `false` (undetermined). Affects `usePreflightCreateVesting` the same way.
+- **Duplicate operator blocker suppressed in both create-preflights.** An invalid token previously produced two blockers in `preflightCreateAirdrop` — the token `InvalidArgumentError` plus a spurious `OperatorNotApprovedError` telling the user to approve an operator on an address that cannot hold a token (and the same double-report would have appeared in `preflightCreateVesting` once its `isOperator` failure became a blocker). Both preflights now emit the operator blocker only when the token was actually readable, so checklist UIs get exactly one actionable item. Migration note: consumers who caught a thrown error from these preflights to detect a bad token must switch to inspecting `report.blockerErrors`; don't render approve-operator prompts from `isFactoryOperator` / `isOperatorSet` alone — check `blockerErrors` for `TOKENOPS_OPERATOR_NOT_APPROVED`.
+
+### Fixed — docs sweep
+
+- `CreateAirdropPreflightReport.isFactoryOperator` TSDoc: clarified that `false` also covers "could not be determined" (structurally invalid token address, or a non-ERC-7984 token whose operator read failed and became a blocker), not just "not approved" (TOK-436).
+- `ConfidentialAirdropClient.claim` + `useClaim` TSDoc: the silent-zero note (insufficient encrypted balance moves an encrypted zero rather than reverting) must not be generalized to a never-funded pool — that claim reverts with `FheHandleNotAllowedError`, and `preflightClaim` cannot detect it because the pool balance is an encrypted `euint64` the SDK cannot read. Previously this warning appeared only on the preflight surface (TOK-434).
+- `useAdminPartialClaim` TSDoc: documents the 6-decimals convention of TokenOps confidential (ERC-7984) tokens (1 token = 1_000_000 base units); the hook shares `PartialClaimArgs` with `usePartialClaim`, and an 18-decimals assumption over-claims by 10^12 (TOK-435).
+- Deleted the dead, never-exported `useAirdropClaim` hook file — it was absent from the `@tokenops/sdk/fhe-airdrop/react` barrel so no consumer could reach it, and its JSDoc described a plaintext-`amount` re-encryption flow the SDK deliberately does not implement (the admin signature commits to a specific handle). The exported `useClaim` is the real claim hook. No API change (TOK-437).
+- Fixed four `@example` blocks on `@tokenops/sdk/fhe` (`mintMockERC7984`, `createMockErc7984Client`, `setOperator`, `revokeOperator`) that referenced the nonexistent `DEPLOYED_ADDRESSES.tokens.testConfidential[...]` path (the registry has no `tokens` key) — two also imported symbols from entry points that don't export them. Examples now use placeholder addresses and every import specifier resolves.
+- `SECURITY.md` operator-deadline guidance corrected: the old text misspelled the constant (`ERC_7984_OPERATOR_MAX_DEADLINE`), recommended the never-expiring deadline for production (the inverse of the `setOperator` TSDoc guidance), and claimed a past-deadline warning that does not exist. It now matches actual behavior: the SDK validates only that the deadline is within uint48 range; use `ERC7984_OPERATOR_MAX_DEADLINE` for dev loops and fixtures, scope deadlines (and `revokeOperator`) in production.
+- `SECURITY.md` gains a "Known Advisories" section: remaining open Dependabot alerts (`axios` via `wagmi` → `@wagmi/connectors` → `@base-org/account` → `@coinbase/cdp-sdk`; `hono` via `porto`) are reachable only through the consumer's own `wagmi` peer tree, not through the SDK's sole runtime dependency (`abitype`); the repo's `pnpm.overrides` protect only this repo's lockfile, so consumer-side `npm audit` findings there are remediated upstream in wagmi.
+
+### Security
+
+- Development-tree dependency floors raised to clear 20+ Dependabot alerts — brace-expansion CVE-2026-14257 across the 1.x / 2.x / 5.x lines (floors 1.1.16 / 2.1.3 / 5.0.8), postcss GHSA-r28c-9q8g-f849 (pinned 8.5.23), plus axios / fast-uri / hono / js-yaml / linkify-it advisories — and eslint upgraded 9 → 10. **Dev-tree only:** all of these live in `devDependencies` / `pnpm.overrides`; the published package's runtime dependency (`abitype ^1.0.8`) and every peerDependency range are unchanged, so consumer dependency trees are unaffected.
+
+## [1.5.1] - 2026-07-23
+
+_Republish baseline._ No code or API changes — the package content is identical to 1.5.0 apart from the version number. Published minutes after 1.5.0 as the last release of the same 2026-07-23 per-merge auto-publish run; later that day 1.2.0–1.5.0 were unpublished from npm (burned versions; npm forbids reusing them), leaving **1.5.1 as the first npm-installable version that actually delivers everything from [1.2.0] through [1.5.0]** to consumers. (The repo-only `BOUNTY_DX_TRIAGE.md` added in #56 is not part of the npm tarball.)
+
+## [1.5.0] - 2026-07-23 [YANKED]
+
+_Published and unpublished from npm the same day; its changes reach consumers via [1.5.1]._
+
+### Added
+
+- **wagmi v3 peer support** (S7, TOK-70, #57) — the `wagmi` peer dependency range widens from `^2.0.0` to `^2.0.0 || ^3.0.0`; wagmi v2 remains fully supported and no other peer range changes. wagmi v3 renamed `useAccount` to `useConnection`, and the SDK now resolves the installed major's account hook internally, so the three hooks that default to the connected wallet — `useAirdropIsSignatureValid` (`@tokenops/sdk/fhe-airdrop/react`), `useConfidentialBalance` and `useUnderlyingBalance` (`@tokenops/sdk/testnet-faucet/react`) — work under either major with no code change; all hook signatures and return types are unchanged, and `usePublicClient` / `useWalletClient` usage is unaffected. README gains a "wagmi v2 and v3" section documenting dual-major support and how to diagnose `ERESOLVE` errors after a wagmi v3 upgrade (`npm ls wagmi` / `pnpm why wagmi` — the offending peer range usually belongs to another package, not `@tokenops/sdk`).
+
+## [1.4.2] - 2026-07-23 [YANKED]
+
+_Published and unpublished from npm the same day; its changes reach consumers via [1.5.1]._
+
+### Docs
+
+- **6-decimals amount convention surfaced at every amount-taking entry point** (S6, TOK-71, #65) — a canonical TSDoc note now ships on each public API that takes a token amount: TokenOps confidential (ERC-7984) tokens use a 6-decimals convention (1 token = 1_000_000 base units), not the 18 decimals typical of ERC-20; amount parameters are base units of the token's actual decimals — for the CTTT test token (6 decimals) `1_000_000n` = 1 CTTT, while the transparent TTT test token uses 18 decimals. Surfaced on the exported `encryptUint64` helpers of all three products (covering `encryptUint64Batch` values), `computeSubtotals`, `ConfidentialVestingManagerClient.{createVesting, batchCreateVesting, partialClaim, adminPartialClaim, withdrawAdmin, withdrawTokenFee}`, `ConfidentialAirdropFactoryClient.{createAndFundConfidentialAirdrop, fundConfidentialAirdrop, createAndFundConfidentialAirdropAndGetAddress}`, `ConfidentialDisperseClient.{calculateFee, preflightDisperse, disperse, withdrawTokenFee}`, and the corresponding amount-taking React hooks in `/fhe-vesting/react`, `/fhe-airdrop/react`, and `/fhe-disperse/react`. Documentation-only; no branded decimals type was introduced and no runtime behavior changed.
+
+## [1.4.1] - 2026-07-23 [YANKED]
+
+_Published and unpublished from npm the same day; its changes reach consumers via [1.5.1]._
+
+### Docs
+
+- **Silent-zero transfer warning** (S5, TOK-72, #58) — every public method and React mutation hook that moves confidential tokens or funds a contract now carries a canonical TSDoc warning: ERC-7984 transfers do not revert when the sender's encrypted balance is insufficient — the transfer succeeds and moves an encrypted zero instead (by design: reverting would leak balance information), so the transaction receipt alone cannot tell you whether value actually moved. Applied to `ConfidentialVestingManagerClient.{createVesting, batchCreateVesting, claim, adminClaim, partialClaim, adminPartialClaim}`, `ConfidentialAirdropClient.claim`, `ConfidentialAirdropFactoryClient.{createAndFundConfidentialAirdrop, fundConfidentialAirdrop, createAndFundConfidentialAirdropAndGetAddress}`, `ConfidentialDisperseClient.disperse`, and the corresponding claim / fund / disperse mutation hooks in the three `/react` subpaths. Documentation-only; no runtime behavior changed.
+
+## [1.4.0] - 2026-07-23 [YANKED]
+
+_Published and unpublished from npm the same day; its changes reach consumers via [1.5.1]._
+
+### Added
+
+- **`EncryptorInitPhase` and the `onPhase` init-phase callback** (S4, TOK-73, #61) — new exported type on `@tokenops/sdk/fhe`: the union `"initializing" | "downloading-params" | "ready"`, plus an optional `onPhase?: (phase: EncryptorInitPhase) => void` option on both `createSepoliaEncryptorWeb` (`CreateSepoliaEncryptorWebOpts`) and `createSepoliaEncryptor` (`CreateSepoliaEncryptorOptions`). Motivation: the first in-browser encryption downloads several MB of FHE public material with no signal — `onPhase` gives UIs a loading-state hook. Web semantics: `"initializing"` fires during relayer construction, `"downloading-params"` when the Web Worker's lazy init and FHE key/params download actually begin (near-instant on a warm IndexedDB cache), `"ready"` on completion; the last two can re-fire if the relayer re-initializes (e.g. chain switch). Node semantics: `RelayerNode` exposes no status events, so phases bracket the first `encrypt()` call; a failed first attempt re-fires `"downloading-params"` on the next call. Deliberate design points: no fake progress (the Zama SDKs expose no download-progress API), no error phase (init failures surface as rejections from the pending operation), and callback exceptions are swallowed so a throwing UI observer can never break the encryption path.
+
+## [1.3.0] - 2026-07-23 [YANKED]
+
+_Published and unpublished from npm the same day; its changes reach consumers via [1.5.1]._
+
+### Added — create-side preflight for vesting and airdrop (S3, TOK-74, #59)
+
+- **`ConfidentialVestingManagerClient.preflightCreateVesting({ params, creator })`** (`@tokenops/sdk/fhe-vesting`) — read-only, opt-in create-side preflight for `createVesting` / `batchCreateVesting`. Returns the new `CreateVestingPreflightReport` (`token`, `hasCreatorRole`, `isOperatorSet`, `ready`, `blockers`, `blockerErrors`) reporting structural param violations (`InvalidArgumentError`, mirroring the contract's `_validateVestingParams` invariants), missing `VESTING_CREATOR_ROLE` (`AccessDeniedError`), and missing ERC-7984 operator approval of the manager on the distribution token (`OperatorNotApprovedError`). `blockerErrors` are typed `TokenOpsSdkError`s index-aligned with the human-readable `blockers` strings — branch on `error.code`. RPC failures propagate rather than producing a false report; paused state is deliberately not a blocker (pause only blocks claims). Documented not-detectable: the creator's encrypted `euint64` balance (an underfunded create silently zeroes amounts via `FHE.select` instead of reverting) and `batchCreateVesting`'s `maxBatchSize()`.
+- **`ConfidentialAirdropFactoryClient.preflightCreateAirdrop(args)`** (`@tokenops/sdk/fhe-airdrop`) — same for `createConfidentialAirdrop` / `createAndFundConfidentialAirdrop`, with new `PreflightCreateAirdropArgs` (`params`, `creator`, optional `userSalt`, optional `funding`) and `CreateAirdropPreflightReport` (`isFactoryOperator`, `gasFee`, `predictedAirdrop?`, `alreadyDeployed?`, `ready`, `blockers`, `blockerErrors`) types. Validates params structurally (non-zero `token` / `admin`, timestamp ordering, `endTimestamp` in the future), reports the resolved per-claim `gasFee` (creator's custom fee when enabled, else `defaultGasFee`), treats a missing factory-operator approval as a blocker only with `funding: true` (informational via `isFactoryOperator` otherwise), and — when `userSalt` is supplied — predicts the CREATE2 clone address and flags an existing deployment as an `AlreadyInitializedError` blocker.
+- **`usePreflightCreateVesting`** (`@tokenops/sdk/fhe-vesting/react`) and **`usePreflightCreateAirdrop`** (`@tokenops/sdk/fhe-airdrop/react`) — TanStack Query wrappers over the two preflights (disabled until `params` and `creator` are set, `staleTime: 0`), with new `UsePreflightCreateVestingArgs` / `UsePreflightCreateAirdropArgs` types; the report types are re-exported from the `/react` subpaths.
+
+### Changed
+
+- **`OperatorNotApprovedError` gains optional `tokenAddress`** — constructor args and `context` now carry `tokenAddress?: Address` identifying the ERC-7984 token whose operator approval is missing; populated by the new create-side preflights where the token is statically known. Additive and optional — no migration needed.
+
+## [1.2.0] - 2026-07-23 [YANKED]
+
+_Published and unpublished from npm the same day; its changes reach consumers via [1.5.1]._
+
+### Added — ERC-7984 reverts translated into actionable errors (S1, TOK-76, #60)
+
+- **`OperatorNotApprovedError`** — new typed error with code `TOKENOPS_OPERATOR_NOT_APPROVED` (new member of the `TokenOpsSdkErrorCode` union), thrown when an ERC-7984 confidential token rejects a TokenOps contract as spender (`ERC7984UnauthorizedSpender`, selector `0x79f2cb38`) because the holder never called `setOperator()` — the common failure in vesting creation, airdrop funding, and disperse token pulls. Carries `context.holder` and `context.spender` decoded from the revert, and a remediation-first message telling you to call `setOperator()` via the `/fhe` operator helpers. Exported from the root entrypoint and from `/fhe`, `/fhe-vesting`, `/fhe-airdrop`, `/fhe-disperse`, `/testnet-faucet`, and each product's `/react` subpath.
+- **`OPERATOR_NOT_APPROVED_REMEDIATION`** — exported string constant (root entrypoint) holding the canonical `OperatorNotApprovedError` message, for surfaces that need the exact remediation copy.
+
+### Changed
+
+- **ERC-7984 revert decoding across all clients** — `ConfidentialVestingManagerClient`, `ConfidentialVestingFactoryClient`, `ConfidentialAirdropClient`, `ConfidentialAirdropFactoryClient`, `ConfidentialDisperseClient`, and `TestnetFaucetClient` now decode token-originated ERC-7984 standard reverts that appear in none of the vesting / airdrop / disperse product ABIs (the testnet faucet's confidential test-token ABI already declared most of them; 1.2.0 adds the shared decode set and the name-based mapping for every client). Besides `ERC7984UnauthorizedSpender` → `OperatorNotApprovedError`, the sibling errors `ERC7984UnauthorizedCaller`, `ERC7984UnauthorizedUseOfEncryptedAmount`, `ERC7984InvalidReceiver`, `ERC7984InvalidSender`, `ERC7984ZeroBalance`, and `ERC7984InvalidGatewayRequest` now surface as `ContractRevertError` with `context.revertName` / `revertArgs` populated instead of a raw selector hex string (exception: `ERC7984InvalidReceiver` on `TestnetFaucetClient` keeps its pre-existing `InvalidArgumentError` mapping via the faucet product mapper). Works across the simulate, wallet-transport, and raw-RPC error paths; errors declared in the product ABI keep precedence (e.g. `EnforcedPause` still maps to `PausedError`). Migration: code matching raw `0x79f2cb38` data or selector-hex `ContractRevertError` messages should switch to `instanceof OperatorNotApprovedError` / `error.code === "TOKENOPS_OPERATOR_NOT_APPROVED"`, or to `context.revertName`.
+
+## [1.1.1] - 2026-06-23
+
+Release-pipeline fixes only (npm OIDC trusted publishing via npm >= 11.5.1; `--provenance` dropped because npm rejects it for private packages); no consumer-facing changes relative to [1.1.0] — the published contents are identical apart from the version field and dev-only package.json fields (`devDependencies` / `pnpm.overrides`). Because 1.1.0 never reached npm, **1.1.1 is the first published release of the 1.1.x line** and the version that delivered the testnet-faucet subpath to npm consumers. Dev-tree dependency bumps only (`vitest` 2 → 3, `pnpm.overrides` churn); `dependencies` / `peerDependencies` unchanged.
+
+## [1.1.0] - 2026-06-22
+
+_Tagged but never published — the release workflow failed on this tag; the content first reached npm in [1.1.1]._
+
+### Added
+
+- **New `@tokenops/sdk/testnet-faucet` subpath** — a headless, viem-first client for the testnet-only TokenOps test-token pair: `TokenopsTestToken` (TTT, plain 18-decimal ERC-20 with an open mint) and its ERC-7984 confidential wrapper `ConfidentialTokenopsTestToken` (CTTT, 6-decimal, open fully-backed faucet mint). Exports `TestnetFaucetClient` / `createTestnetFaucetClient` (config: `publicClient`, optional `walletClient`, optional CTTT proxy `address` override, `chainId`, `telemetry`); reads `underlyingToken`, `confidentialBalanceOf` (euint64 ciphertext handle), `underlyingBalanceOf`, `rate` (10^12), `decimals` (6), `underlyingDecimals` (18), `inferredTotalSupply`, `maxTotalSupply`, `getMetadata`; writes `mintConfidential` (returns `{ hash, to, amount, underlyingMinted, handle }` decoded from the `ConfidentialMint` event) and `mintUnderlying` (returns `{ hash, to, amount }`). Faucet mint amounts are **public plaintext** (`uint64` in CTTT 6-decimal units / `uint256` in TTT 18-decimal units) — no encryptor and no `@zama-fhe/sdk` peer is needed anywhere in the faucet subpaths. The backing TTT is never supplied by the consumer: it resolves from the registry for the canonical CTTT, or from a custom CTTT's own authoritative `underlying()` getter.
+- **Testnet-only chain guard** — `TESTNET_FAUCET_SUPPORTED_CHAIN_IDS` (Sepolia `11155111` and local dev chain `31337`), `isTestnetFaucetChainId`, and `assertTestnetFaucetChain`. `TestnetFaucetClient` throws `UnsupportedChainError` at construction on any other chain — the faucet can never run on mainnet.
+- **New `@tokenops/sdk/testnet-faucet/react` subpath** — wagmi + TanStack Query hooks mirroring every client method: reads `useConfidentialBalance`, `useUnderlyingBalance`, `useFaucetRate`, `useFaucetDecimals`, `useUnderlyingDecimals`, `useUnderlyingTokenAddress`, `useInferredTotalSupply`, `useMaxTotalSupply`, `useFaucetMetadata`; mutations `useMintConfidential`, `useMintUnderlying`. All hooks accept `BaseHookOptions` (`{ address?, chainId? }`); query keys follow `["tokenops-sdk", "testnet-faucet", method, chainId, address, ...args]` with exported constants `TESTNET_FAUCET_KEY` / `TESTNET_FAUCET_NAMESPACE`. On an unsupported chain the hooks never construct a client during render, and mutations surface the typed `UnsupportedChainError` / `DeploymentAddressUnavailableError` rather than a generic `MissingClientError`. Mutations do not auto-invalidate read queries — invalidate `["tokenops-sdk", "testnet-faucet"]` yourself. Requires only the `wagmi` and `@tanstack/react-query` peers, not `@zama-fhe/react-sdk`.
+- **New error `FaucetSupplyExhaustedError`** (code `TOKENOPS_FAUCET_SUPPLY_EXHAUSTED`, new member of the `TokenOpsSdkErrorCode` union) — thrown when the confidential wrapper's backing reaches `maxTotalSupply` (`type(uint64).max`), mapped from the on-chain `ERC7984TotalSupplyOverflow` revert. Both faucet subpaths also re-export the full canonical TokenOps error vocabulary for parity with the other product subpaths.
+- **`DEPLOYED_ADDRESSES.testnetFaucet` registry and address accessors** — Sepolia deployments for TTT (`0x37a057Fa8C201a7bf8caF32dfa9A0878f577D92b`) and the CTTT UUPS proxy (`0x258F9D60dc023870e4E3109c894D834D5377361a`), with new functions `getTestTokenAddress`, `requireTestTokenAddress`, `getConfidentialTestTokenAddress`, `requireConfidentialTestTokenAddress` on the root `@tokenops/sdk` and re-exported from `/testnet-faucet`. ABIs `tokenopsTestTokenAbi` and `confidentialTokenopsTestTokenAbi` are exported too.
+
+### Docs
+
+- README: new "Quickstart — testnet faucet" sections (headless and React hooks) and subpath-table entries for `@tokenops/sdk/testnet-faucet` and `@tokenops/sdk/testnet-faucet/react`.
+- TSDoc cleanup in published typings: internal audit-pipeline codenames removed from doc comments across 23 modules, so the `.d.ts` documentation shipped in the package no longer references internal process artifacts.
+
 ## [1.0.0] - 2026-05-27
 
 ### Changed — factory create methods now block on receipt before returning
@@ -202,6 +348,16 @@ The package has not been published to npm yet (`npm view @tokenops/sdk` returns
 - Sepolia factory address wired in `src/core/addresses.ts` (`0xA87701CE9A52D43681600583a99c85b50DbE3150`).
 - Three-surface test rig: unit, local FHEVM (anvil + forge-fhevm host contracts + `@fhevm/mock-utils`), Sepolia smoke.
 
-[1.1.0]: https://github.com/VestingLabs/tokenops-sdk/compare/v1.0.0...v1.1.0
-[1.0.0]: https://github.com/VestingLabs/tokenops-sdk/compare/v1.0.0-alpha.0...v1.0.0
+[unreleased]: https://github.com/VestingLabs/tokenops-sdk/compare/v1.5.1...HEAD
+[1.5.1]: https://github.com/VestingLabs/tokenops-sdk/compare/v1.5.0...v1.5.1
+[1.5.0]: https://github.com/VestingLabs/tokenops-sdk/compare/v1.4.2...v1.5.0
+[1.4.2]: https://github.com/VestingLabs/tokenops-sdk/compare/v1.4.1...v1.4.2
+[1.4.1]: https://github.com/VestingLabs/tokenops-sdk/compare/v1.4.0...v1.4.1
+[1.4.0]: https://github.com/VestingLabs/tokenops-sdk/compare/v1.3.0...v1.4.0
+[1.3.0]: https://github.com/VestingLabs/tokenops-sdk/compare/v1.2.0...v1.3.0
+[1.2.0]: https://github.com/VestingLabs/tokenops-sdk/compare/v1.1.1...v1.2.0
+[1.1.1]: https://github.com/VestingLabs/tokenops-sdk/compare/v1.1.0...v1.1.1
+[1.1.0]: https://github.com/VestingLabs/tokenops-sdk/compare/efda6cd...v1.1.0
+[1.0.0]: https://github.com/VestingLabs/tokenops-sdk/commit/efda6cd
+[1.0.0-rc.1]: https://github.com/VestingLabs/tokenops-sdk/releases/tag/v1.0.0-rc.1
 [1.0.0-alpha.0]: https://github.com/VestingLabs/tokenops-sdk/releases/tag/v1.0.0-alpha.0

package/SECURITY.md

@@ -46,7 +46,7 @@ The following are **not in scope** for this SDK's security policy:
 
 **Encryptor binding is address-scoped.** Input proofs from `encryptUint64` are bound to `(contractAddress, userAddress)` — they cannot be replayed against a different contract or submitted by a different sender. Do not reuse proofs across different contract deployments.
 
-**Operator approvals (`setOperator`) have a deadline.** Set the deadline appropriately for your use case. The SDK exports `ERC_7984_OPERATOR_MAX_DEADLINE` for production flows and warns when the deadline is in the past.
+**Operator approvals (`setOperator`) have a deadline — scope it in production.** The SDK exports `ERC7984_OPERATOR_MAX_DEADLINE` (the `uint48` max, effectively forever) as the default when a consumer doesn't care about expiry — appropriate for local-chain dev loops and test fixtures, not for production. For production flows, scope the deadline to the expected operation window (e.g. `Date.now()/1000 + 3600`) and call `revokeOperator` when the authorization is no longer needed. The SDK validates that the deadline is within the `uint48` range but does **not** warn when a supplied deadline is already in the past — a past-but-otherwise-valid deadline is accepted silently.
 
 ## Supported Versions
 
@@ -54,6 +54,12 @@ The following are **not in scope** for this SDK's security policy:
 | ------- | ------------------ |
 | 1.x     | :white_check_mark: |
 
+## Known Advisories
+
+Open Dependabot alerts against this repo are all **transitive** — the SDK's only runtime dependency is `abitype`. The remaining alerts (e.g. `axios`, reached via `wagmi` → `@wagmi/connectors` → `@base-org/account` → `@coinbase/cdp-sdk`; and `hono`, reached via `porto`) come in through the `wagmi` **peer** dependency tree, not through anything this SDK ships at runtime.
+
+This repo's `pnpm.overrides` pin those transitive versions for our own lockfile, which fixes CI and our security dashboard — but that pin has no effect for consumers, who resolve their own `wagmi`/peer dependency tree at install time. Consumers running `npm audit` (or similar) against their own install may still see these advisories; that reflects their resolved tree, not a vulnerability this SDK ships. Real remediation is upstream, in `wagmi`'s own dependency graph.
+
 ## Acknowledgments
 
 We will acknowledge reporters in the relevant release notes unless they request anonymity.

package/dist/{chunk-67OV5CX2.cjs → chunk-2RNW4MIJ.cjs}

@@ -494,6 +494,16 @@ var TokenOpsContractError = class extends TokenOpsSdkError {
   }
 };
 
+// src/core/brands.ts
+var asEncryptedHandle = (h) => h;
+var asExternalInputProof = (h) => h;
+var asTxHash = (h) => h;
+var asVestingId = (h) => h;
+var asAirdropId = (h) => h;
+var asDisperseId = (h) => h;
+var asRole = (h) => h;
+var asSignature = (h) => h;
+
 exports.AccessDeniedError = AccessDeniedError;
 exports.AlreadyInitializedError = AlreadyInitializedError;
 exports.BatchTooLargeError = BatchTooLargeError;
@@ -532,4 +542,12 @@ exports.UserDecryptNotAllowedError = UserDecryptNotAllowedError;
 exports.UserRejectedSignatureError = UserRejectedSignatureError;
 exports.WalletChainMismatchError = WalletChainMismatchError;
 exports.WalletRejectedError = WalletRejectedError;
+exports.asAirdropId = asAirdropId;
+exports.asDisperseId = asDisperseId;
+exports.asEncryptedHandle = asEncryptedHandle;
+exports.asExternalInputProof = asExternalInputProof;
+exports.asRole = asRole;
+exports.asSignature = asSignature;
+exports.asTxHash = asTxHash;
+exports.asVestingId = asVestingId;
 exports.isTokenOpsSdkError = isTokenOpsSdkError;

package/dist/{chunk-KLKI352M.cjs → chunk-43RFBQ73.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunk67OV5CX2_cjs = require('./chunk-67OV5CX2.cjs');
+var chunk2RNW4MIJ_cjs = require('./chunk-2RNW4MIJ.cjs');
 var viem = require('viem');
 
 // src/core/version.ts
@@ -49,7 +49,7 @@ var ERC7984_ERRORS_ABI = [
   }
 ];
 function mapContractRevert(error, args) {
-  if (error instanceof chunk67OV5CX2_cjs.TokenOpsSdkError) return error;
+  if (error instanceof chunk2RNW4MIJ_cjs.TokenOpsSdkError) return error;
   const ctx = {
     method: args.method,
     contractAddress: args.contractAddress,
@@ -84,7 +84,7 @@ function mapContractRevert(error, args) {
     const fromDefault = defaultRevertNameMapper(revertName, revertArgs, ctx, args.account);
     if (fromDefault) return attachCause(fromDefault, error);
   }
-  return new chunk67OV5CX2_cjs.ContractRevertError({
+  return new chunk2RNW4MIJ_cjs.ContractRevertError({
     method: args.method,
     contractAddress: args.contractAddress,
     revertName,
@@ -112,66 +112,66 @@ function defaultRevertNameMapper(name, errArgs, ctx, account) {
     case "EnforcedPause":
     case "PausableUpgradeable__Paused":
     case "ClaimsPaused":
-      return new chunk67OV5CX2_cjs.PausedError(ctx);
+      return new chunk2RNW4MIJ_cjs.PausedError(ctx);
     case "AccessControlUnauthorizedAccount": {
       const acct = errArgs?.[0] ?? account;
       const role = errArgs?.[1];
-      return new chunk67OV5CX2_cjs.AccessDeniedError({ ...ctx, account: acct, role });
+      return new chunk2RNW4MIJ_cjs.AccessDeniedError({ ...ctx, account: acct, role });
     }
     case "AccessControlBadConfirmation":
-      return new chunk67OV5CX2_cjs.InvalidArgumentError({
+      return new chunk2RNW4MIJ_cjs.InvalidArgumentError({
         method: ctx.method,
         argument: "callerConfirmation",
         reason: "must equal msg.sender for renounceRole"
       });
     case "InvalidInitialization":
     case "Initializable_InvalidInitialization":
-      return new chunk67OV5CX2_cjs.AlreadyInitializedError(ctx);
+      return new chunk2RNW4MIJ_cjs.AlreadyInitializedError(ctx);
     case "ReentrancyGuardReentrantCall":
     case "ReentrancyGuardTransient":
-      return new chunk67OV5CX2_cjs.ReentrancyError(ctx);
+      return new chunk2RNW4MIJ_cjs.ReentrancyError(ctx);
     // Cross-product custom errors with stable, unambiguous meaning.
     case "InsufficientFee":
     case "InsufficientGasFee":
-      return new chunk67OV5CX2_cjs.InsufficientFeeError({ ...ctx, feeKind: "gas" });
+      return new chunk2RNW4MIJ_cjs.InsufficientFeeError({ ...ctx, feeKind: "gas" });
     case "InsufficientAmount": {
       const provided = errArgs?.[0];
       const required = errArgs?.[1];
-      return new chunk67OV5CX2_cjs.InsufficientFeeError({ ...ctx, feeKind: "gas", required, provided });
+      return new chunk2RNW4MIJ_cjs.InsufficientFeeError({ ...ctx, feeKind: "gas", required, provided });
     }
     case "ZeroBalance":
     case "InsufficientBalance":
-      return new chunk67OV5CX2_cjs.InsufficientBalanceError({ ...ctx, balanceKind: "eth" });
+      return new chunk2RNW4MIJ_cjs.InsufficientBalanceError({ ...ctx, balanceKind: "eth" });
     case "BatchTooLarge": {
       const requested = Number(errArgs?.[0] ?? 0);
       const max = errArgs?.[1] ?? 0n;
-      return new chunk67OV5CX2_cjs.BatchTooLargeError({ ...ctx, requested, max });
+      return new chunk2RNW4MIJ_cjs.BatchTooLargeError({ ...ctx, requested, max });
     }
     case "SplitDisabled":
-      return new chunk67OV5CX2_cjs.FeatureDisabledError({ ...ctx, feature: "split" });
+      return new chunk2RNW4MIJ_cjs.FeatureDisabledError({ ...ctx, feature: "split" });
     case "PausableDisabled":
-      return new chunk67OV5CX2_cjs.FeatureDisabledError({ ...ctx, feature: "pause" });
+      return new chunk2RNW4MIJ_cjs.FeatureDisabledError({ ...ctx, feature: "pause" });
     case "ExtensionNotAllowed":
-      return new chunk67OV5CX2_cjs.FeatureDisabledError({ ...ctx, feature: "extendClaimWindow" });
+      return new chunk2RNW4MIJ_cjs.FeatureDisabledError({ ...ctx, feature: "extendClaimWindow" });
     case "TransferFailed":
-      return new chunk67OV5CX2_cjs.TransferFailedError({ ...ctx, asset: "eth" });
+      return new chunk2RNW4MIJ_cjs.TransferFailedError({ ...ctx, asset: "eth" });
     case "HandleNotAllowed":
-      return new chunk67OV5CX2_cjs.FheHandleNotAllowedError({ ...ctx, account });
+      return new chunk2RNW4MIJ_cjs.FheHandleNotAllowedError({ ...ctx, account });
     case "SenderNotAllowedToUseHandle": {
       const handle = errArgs?.[0];
       const sender = errArgs?.[1] ?? account;
-      return new chunk67OV5CX2_cjs.FheHandleNotAllowedError({ ...ctx, handle, account: sender });
+      return new chunk2RNW4MIJ_cjs.FheHandleNotAllowedError({ ...ctx, handle, account: sender });
     }
     case "SenderNotAllowed": {
       const sender = errArgs?.[0] ?? account;
-      return new chunk67OV5CX2_cjs.FheHandleNotAllowedError({ ...ctx, account: sender });
+      return new chunk2RNW4MIJ_cjs.FheHandleNotAllowedError({ ...ctx, account: sender });
     }
     case "InvalidSignature":
-      return new chunk67OV5CX2_cjs.InvalidSignatureError(ctx);
+      return new chunk2RNW4MIJ_cjs.InvalidSignatureError(ctx);
     case "ERC7984UnauthorizedSpender": {
       const holder = errArgs?.[0];
       const spender = errArgs?.[1];
-      return new chunk67OV5CX2_cjs.OperatorNotApprovedError({
+      return new chunk2RNW4MIJ_cjs.OperatorNotApprovedError({
         method: ctx.method,
         contractAddress: ctx.contractAddress,
         holder,
@@ -211,7 +211,7 @@ function defaultRevertNameMapper(name, errArgs, ctx, account) {
     case "ArrayLengthMismatch":
     case "VestingIdsNotStrictlyAsc":
     case "CustomFeeNotSet":
-      return new chunk67OV5CX2_cjs.InvalidArgumentError({
+      return new chunk2RNW4MIJ_cjs.InvalidArgumentError({
         method: ctx.method,
         argument: invalidArgumentLabelFor(name),
         reason: `the contract reverted with \`${name}\`. If you did not pass an invalid value, this may be an SDK bug \u2014 please file an issue.`
@@ -284,7 +284,7 @@ function isContractRevert(error) {
 }
 function classifyNonRevert(error, args) {
   if (!(error instanceof viem.BaseError)) {
-    return new chunk67OV5CX2_cjs.UnknownWriteFailureError({
+    return new chunk2RNW4MIJ_cjs.UnknownWriteFailureError({
       method: args.method,
       contractAddress: args.contractAddress,
       cause: error
@@ -295,21 +295,21 @@ function classifyNonRevert(error, args) {
     return predicate(frame) ? frame : void 0;
   };
   if (walk((e) => e instanceof viem.UserRejectedRequestError) || walk((e) => e instanceof viem.TransactionRejectedRpcError)) {
-    return new chunk67OV5CX2_cjs.WalletRejectedError({
+    return new chunk2RNW4MIJ_cjs.WalletRejectedError({
       method: args.method,
       contractAddress: args.contractAddress,
       cause: error
     });
   }
   if (walk((e) => e instanceof viem.ChainMismatchError)) {
-    return new chunk67OV5CX2_cjs.WalletChainMismatchError({
+    return new chunk2RNW4MIJ_cjs.WalletChainMismatchError({
       method: args.method,
       contractAddress: args.contractAddress,
       cause: error
     });
   }
   if (walk((e) => e instanceof viem.InsufficientFundsError)) {
-    return new chunk67OV5CX2_cjs.InsufficientGasFundsError({
+    return new chunk2RNW4MIJ_cjs.InsufficientGasFundsError({
       method: args.method,
       contractAddress: args.contractAddress,
       cause: error
@@ -317,7 +317,7 @@ function classifyNonRevert(error, args) {
   }
   const httpFrame = walk((e) => e instanceof viem.HttpRequestError);
   if (httpFrame) {
-    return new chunk67OV5CX2_cjs.NetworkError({
+    return new chunk2RNW4MIJ_cjs.NetworkError({
       method: args.method,
       contractAddress: args.contractAddress,
       statusCode: httpFrame.status,
@@ -325,13 +325,13 @@ function classifyNonRevert(error, args) {
     });
   }
   if (walk((e) => e instanceof viem.TimeoutError)) {
-    return new chunk67OV5CX2_cjs.NetworkError({
+    return new chunk2RNW4MIJ_cjs.NetworkError({
       method: args.method,
       contractAddress: args.contractAddress,
       cause: error
     });
   }
-  return new chunk67OV5CX2_cjs.UnknownWriteFailureError({
+  return new chunk2RNW4MIJ_cjs.UnknownWriteFailureError({
     method: args.method,
     contractAddress: args.contractAddress,
     cause: error

package/dist/{chunk-ZA673I3O.js → chunk-46T67CE2.js}

@@ -1,4 +1,4 @@
-import { TokenOpsValidationError } from './chunk-QBJ7O2B4.js';
+import { TokenOpsValidationError } from './chunk-DRSPMIZ7.js';
 import { isAddress, getAddress } from 'viem';
 
 function normaliseAddress(input) {

package/dist/{chunk-6BMP4ICG.js → chunk-4KJ66YRH.js}

@@ -1,6 +1,7 @@
-import { normaliseAddress } from './chunk-ZA673I3O.js';
+import { erc7984OperatorAbi } from './chunk-7VELUOMI.js';
+import { normaliseAddress } from './chunk-46T67CE2.js';
+import { TokenOpsContractError } from './chunk-DRSPMIZ7.js';
 import { withTelemetry } from './chunk-Q2GP5UDC.js';
-import { TokenOpsContractError } from './chunk-QBJ7O2B4.js';
 
 // src/fhe/operators.ts
 var ERC7984_SET_OPERATOR_ABI = [
@@ -92,5 +93,62 @@ async function revokeOperator(args) {
     });
   });
 }
+async function isOperator(args) {
+  const token = normaliseAddress(args.token);
+  const holder = normaliseAddress(args.holder);
+  const spender = normaliseAddress(args.spender);
+  return withTelemetry(args.telemetry, "fhe.isOperator", async () => {
+    try {
+      return await args.publicClient.readContract({
+        address: token,
+        abi: erc7984OperatorAbi,
+        functionName: "isOperator",
+        args: [holder, spender]
+      });
+    } catch (err) {
+      throw new TokenOpsContractError(
+        `isOperator: readContract failed (token=${token}, holder=${holder}, spender=${spender})`,
+        { contract: "ERC7984", call: "isOperator", token, holder, spender, cause: err }
+      );
+    }
+  });
+}
+async function ensureOperator(args) {
+  return withTelemetry(args.telemetry, "fhe.ensureOperator", async () => {
+    if (args.deadline <= 0n || args.deadline > ERC7984_OPERATOR_MAX_DEADLINE) {
+      throw new TokenOpsContractError(
+        `ensureOperator: deadline ${args.deadline} out of range (0, ${ERC7984_OPERATOR_MAX_DEADLINE}]`,
+        { contract: "ERC7984", call: "ensureOperator", deadline: args.deadline.toString() }
+      );
+    }
+    const fromAccount = args.account ?? args.walletClient.account;
+    if (!fromAccount) {
+      throw new TokenOpsContractError(
+        "ensureOperator: no account available \u2014 pass `account` explicitly or attach an account to the walletClient",
+        { contract: "ERC7984", call: "ensureOperator" }
+      );
+    }
+    const holder = typeof fromAccount === "string" ? fromAccount : fromAccount.address;
+    const authorized = await isOperator({
+      publicClient: args.publicClient,
+      token: args.token,
+      holder,
+      spender: args.spender
+    });
+    if (authorized) {
+      return { alreadyOperator: true, hash: null };
+    }
+    const hash = await setOperator({
+      publicClient: args.publicClient,
+      walletClient: args.walletClient,
+      ...args.account !== void 0 ? { account: args.account } : {},
+      token: args.token,
+      spender: args.spender,
+      deadline: args.deadline,
+      ...args.waitForReceipt !== void 0 ? { waitForReceipt: args.waitForReceipt } : {}
+    });
+    return { alreadyOperator: false, hash };
+  });
+}
 
-export { ERC7984_OPERATOR_MAX_DEADLINE, ERC7984_SET_OPERATOR_ABI, revokeOperator, setOperator };
+export { ERC7984_OPERATOR_MAX_DEADLINE, ERC7984_SET_OPERATOR_ABI, ensureOperator, isOperator, revokeOperator, setOperator };

package/dist/{chunk-JYOTGRSO.cjs → chunk-4ZCXK4VI.cjs}

@@ -1,8 +1,9 @@
 'use strict';
 
-var chunkJK4XMMKM_cjs = require('./chunk-JK4XMMKM.cjs');
+var chunkFWHYQZ5E_cjs = require('./chunk-FWHYQZ5E.cjs');
+var chunkVR3FREBX_cjs = require('./chunk-VR3FREBX.cjs');
+var chunk2RNW4MIJ_cjs = require('./chunk-2RNW4MIJ.cjs');
 var chunkVJKZWYYJ_cjs = require('./chunk-VJKZWYYJ.cjs');
-var chunk67OV5CX2_cjs = require('./chunk-67OV5CX2.cjs');
 
 // src/fhe/operators.ts
 var ERC7984_SET_OPERATOR_ABI = [
@@ -20,19 +21,19 @@ var ERC7984_SET_OPERATOR_ABI = [
 var ERC7984_OPERATOR_MAX_DEADLINE = (1n << 48n) - 1n;
 async function setOperator(args) {
   const { publicClient, walletClient, account, waitForReceipt = true, telemetry } = args;
-  const token = chunkJK4XMMKM_cjs.normaliseAddress(args.token);
-  const spender = chunkJK4XMMKM_cjs.normaliseAddress(args.spender);
+  const token = chunkVR3FREBX_cjs.normaliseAddress(args.token);
+  const spender = chunkVR3FREBX_cjs.normaliseAddress(args.spender);
   const deadline = args.deadline ?? ERC7984_OPERATOR_MAX_DEADLINE;
   return chunkVJKZWYYJ_cjs.withTelemetry(telemetry, "fhe.setOperator", async () => {
     const fromAccount = account ?? walletClient.account;
     if (!fromAccount) {
-      throw new chunk67OV5CX2_cjs.TokenOpsContractError(
+      throw new chunk2RNW4MIJ_cjs.TokenOpsContractError(
         "setOperator: no account available \u2014 pass `account` explicitly or attach an account to the walletClient",
         { contract: "ERC7984", call: "setOperator" }
       );
     }
     if (deadline < 0n || deadline > ERC7984_OPERATOR_MAX_DEADLINE) {
-      throw new chunk67OV5CX2_cjs.TokenOpsContractError(
+      throw new chunk2RNW4MIJ_cjs.TokenOpsContractError(
         `setOperator: deadline ${deadline} out of uint48 range [0, ${ERC7984_OPERATOR_MAX_DEADLINE}]`,
         { contract: "ERC7984", call: "setOperator", deadline: deadline.toString() }
       );
@@ -53,7 +54,7 @@ async function setOperator(args) {
         chain: walletClient.chain
       });
     } catch (err) {
-      throw new chunk67OV5CX2_cjs.TokenOpsContractError(
+      throw new chunk2RNW4MIJ_cjs.TokenOpsContractError(
         `setOperator: writeContract failed (token=${token}, spender=${spender})`,
         {
           contract: "ERC7984",
@@ -68,7 +69,7 @@ async function setOperator(args) {
       try {
         await publicClient.waitForTransactionReceipt({ hash });
       } catch (err) {
-        throw new chunk67OV5CX2_cjs.TokenOpsContractError(`setOperator: receipt wait failed (tx=${hash})`, {
+        throw new chunk2RNW4MIJ_cjs.TokenOpsContractError(`setOperator: receipt wait failed (tx=${hash})`, {
           contract: "ERC7984",
           call: "setOperator",
           tx: hash,
@@ -94,8 +95,67 @@ async function revokeOperator(args) {
     });
   });
 }
+async function isOperator(args) {
+  const token = chunkVR3FREBX_cjs.normaliseAddress(args.token);
+  const holder = chunkVR3FREBX_cjs.normaliseAddress(args.holder);
+  const spender = chunkVR3FREBX_cjs.normaliseAddress(args.spender);
+  return chunkVJKZWYYJ_cjs.withTelemetry(args.telemetry, "fhe.isOperator", async () => {
+    try {
+      return await args.publicClient.readContract({
+        address: token,
+        abi: chunkFWHYQZ5E_cjs.erc7984OperatorAbi,
+        functionName: "isOperator",
+        args: [holder, spender]
+      });
+    } catch (err) {
+      throw new chunk2RNW4MIJ_cjs.TokenOpsContractError(
+        `isOperator: readContract failed (token=${token}, holder=${holder}, spender=${spender})`,
+        { contract: "ERC7984", call: "isOperator", token, holder, spender, cause: err }
+      );
+    }
+  });
+}
+async function ensureOperator(args) {
+  return chunkVJKZWYYJ_cjs.withTelemetry(args.telemetry, "fhe.ensureOperator", async () => {
+    if (args.deadline <= 0n || args.deadline > ERC7984_OPERATOR_MAX_DEADLINE) {
+      throw new chunk2RNW4MIJ_cjs.TokenOpsContractError(
+        `ensureOperator: deadline ${args.deadline} out of range (0, ${ERC7984_OPERATOR_MAX_DEADLINE}]`,
+        { contract: "ERC7984", call: "ensureOperator", deadline: args.deadline.toString() }
+      );
+    }
+    const fromAccount = args.account ?? args.walletClient.account;
+    if (!fromAccount) {
+      throw new chunk2RNW4MIJ_cjs.TokenOpsContractError(
+        "ensureOperator: no account available \u2014 pass `account` explicitly or attach an account to the walletClient",
+        { contract: "ERC7984", call: "ensureOperator" }
+      );
+    }
+    const holder = typeof fromAccount === "string" ? fromAccount : fromAccount.address;
+    const authorized = await isOperator({
+      publicClient: args.publicClient,
+      token: args.token,
+      holder,
+      spender: args.spender
+    });
+    if (authorized) {
+      return { alreadyOperator: true, hash: null };
+    }
+    const hash = await setOperator({
+      publicClient: args.publicClient,
+      walletClient: args.walletClient,
+      ...args.account !== void 0 ? { account: args.account } : {},
+      token: args.token,
+      spender: args.spender,
+      deadline: args.deadline,
+      ...args.waitForReceipt !== void 0 ? { waitForReceipt: args.waitForReceipt } : {}
+    });
+    return { alreadyOperator: false, hash };
+  });
+}
 
 exports.ERC7984_OPERATOR_MAX_DEADLINE = ERC7984_OPERATOR_MAX_DEADLINE;
 exports.ERC7984_SET_OPERATOR_ABI = ERC7984_SET_OPERATOR_ABI;
+exports.ensureOperator = ensureOperator;
+exports.isOperator = isOperator;
 exports.revokeOperator = revokeOperator;
 exports.setOperator = setOperator;