@tokenops/sdk 2.0.0-alpha.1 → 2.0.0-alpha.3

package/CHANGELOG.md

@@ -5,6 +5,71 @@ 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).
 
+## [2.0.0-alpha.3] - 2026-09-16
+
+> **Pre-release built against internally-audited, externally-unaudited contracts.** Continues the `2.0.0-alpha` line. `/fhe-airdrop` in this build targets `tokenops-fhe-airdrop-v2` at commit `c5c12c2087f61bcd5bd1daa802563ed3cd68f002`, which closes the internal audit round (audit-03 through audit-16) but has not completed an external security audit. Every Sepolia `fheAirdrop` address moved again in this build. Breaking changes may land between any two alpha builds without a major bump (SemVer prerelease semantics). Published on the `alpha` dist-tag; `latest` stays on `1.6.0`. **For internal testing, not production value.**
+>
+> Migration guide: [`docs/migration/airdrop-v1-to-v2.md`](docs/migration/airdrop-v1-to-v2.md). Support policy: [`SUPPORT.md`](SUPPORT.md).
+
+### Changed - BREAKING
+
+- **`CommonAirdropParams` gains a required `maxAcceptedGasFee`.** The factory resolves the creator's per-claim fee at execution time and reverts `GasFeeNotAccepted` above this bound (audit-09). It is required rather than defaulted because the fee is frozen into the instance for its lifetime and the value that resolves is chosen by the factory's fee manager, not the creator - a default would hand that decision back to whoever is not making it. Pass `UINT96_MAX` (newly exported) to keep the previous behaviour of accepting any fee.
+- **Every Sepolia `fheAirdrop` address moved.** CREATE3 returns a consumed salt's existing address without comparing codehashes, so the audit redeploy bumped the canonical salt version `2.0.0` → `2.0.2` rather than redeploying over itself. Instances created through the previous factory are unreachable from this release; a campaign planned against it fails `PredictionDriftError`.
+- **`AirdropInitialized` gained a `uint256 gasFee` argument.** The SDK resolves creates from `ConfidentialAirdropCreated` and is unaffected, but any consumer filtering the old topic must re-derive it.
+
+### Added
+
+- **`factory.isAirdrop(candidate)`** and **`useIsAirdrop`** - the genuineness check (audit-10). Nothing readable at an instance proves which factory deployed it, and a claim against a look-alike **succeeds** and delivers nothing rather than reverting. `preflightClaim` gains an optional `factory` that folds the check in alongside every other blocker; supplying it turns the check on, omitting it leaves the existing call shape untouched. New `UnrecognisedAirdropError` (`TOKENOPS_UNRECOGNISED_AIRDROP`).
+- **`refreshComplianceBalance()`** and **`useRefreshComplianceBalance`** - permissionless restoration of the compliance clone's live-balance grant (audit-04). The token rotates the instance's balance handle on every incoming transfer, including a direct one no airdrop code observes, so without this a campaign can be left with a clone that cannot read the pool and no admin around to fix it. The handle it returns is granted to the CLONE, not the caller.
+- **`factory.setMaxGasFee` / `maxGasFee()`**, the factory's own ceiling on every configurable fee, gated by `DEFAULT_ADMIN_ROLE` rather than `FEE_MANAGER_ROLE` (audit-09). `useFactoryFees` now returns `maxGasFee` alongside `feeCollector` and `defaultGasFee`.
+- **`factory.resolveGasFee(creator)`** - the number `maxAcceptedGasFee` is actually checked against, folding a per-creator override over the default. `GasFeeNotAcceptedError` carries it next to the declared bound, so a raised default is distinguishable from a custom override the creator did not know they had.
+- **`useSetMaxGasFee`** (advanced/react) and **`useResolveGasFee`** (react). Every other factory fee control already had a hook; the ceiling did not, and composing the resolved fee by hand meant re-implementing the override-over-default rule in each consumer. `useSetDefaultGasFee`, `useSetCustomFee` and `useDisableCustomFee` now invalidate the resolved-fee key too.
+- Revert mapping for `GasFeeNotAccepted`, `GasFeeExceedsMaximum` and `ZeroUnwrapRequestId`; `LastAdmin` and `ZeroAdminGrant` are now reachable from the factory as well as the instances.
+
+### Fixed
+
+- **`getClaimAmount` was documented as a free, repeatable preview.** It now reverts once the claim is consumed, raising the consuming path's own error in the consuming path's own order (audit-07). The docs point availability checks at `isSignatureValid`, which never reverts.
+- **`discloseHandleToParty` gate #1 now demands PERSISTENT user-decryption ACL on both legs** (audit-06). A handle fresh out of an FHE op carries only a transient allowance and no longer passes; the TSDoc names that trap rather than leaving it to be discovered.
+- **`rescueERC20` refuses the campaign token** (audit-05). Our doc claimed it was out of reach because the pool is ERC-7984 - but a wrapper token answers both interfaces, so that was an assumption, not a guarantee.
+- **The factory admin set can no longer be emptied** (audit-14). A test asserted the opposite; it and the `LastAdmin` message, which said "instance", are corrected.
+- **`ContractCommonParams` is derived from the vendored ABI** instead of being a hand-written mirror. It carried a comment promising a struct change would surface as a type error - it did not, because every write path passes `unknown[]` at the viem edge. The next struct change now fails the build.
+- `useCreateEcdsaAirdrop` and `useCreateMerkleAirdrop` spelled the registry query key inline rather than through `airdropKeys`, the drift `keys.ts` exists to prevent. All four create hooks now go through it and also invalidate `isAirdropAll`.
+- **`preflightCreate` could reject instead of collecting.** An out-of-range `maxAcceptedGasFee` was collected as a blocker and then encoded anyway by the next read, so viem's `IntegerOutOfRangeError` escaped from a function documented never to throw. The range check now short-circuits before any ABI-dependent read, and the regression test uses a real viem client because the suite's mock harness bypasses encoding entirely.
+- **The provenance check had no chain identity.** `preflightClaim` could be handed an instance on one chain and a factory on another, and a registry hit over there would read as a clean `true`. `AirdropRegistry` now carries `chainId` and a mismatch is refused before the registry is consulted.
+- **`useIsAirdrop` cached a negative answer forever.** The registry is append-only so `true` is immutable, but `false` is not: the address can be created later by a process the hook never hears from. Only positive answers are cached now. The `address` override is also documented as what it is - the trust root for a security check.
+- Factory role documentation still described the pre-audit-14 behaviour in four places (`factory.renounceRole`, `useFactoryRenounceRole`, `useFactoryRevokeRole`, `useFactoryRoleMembers`), telling UIs to plan for a state the factory now rejects. The compliance clone genuinely has no floor and is unchanged.
+- `refreshComplianceBalance` was described as making the clone's read permanent. Append-only ACL keeps the returned handle readable, but the next incoming transfer rotates the instance onto a handle the clone was never granted on - it is a snapshot, not a subscription. Pinned by a local test that funds between two refreshes.
+- Restored the create methods' error labels. A blanket ABI-name replacement had changed `error.context.method` from `createEcdsaAirdrop` / `createMerkleAirdrop` to the Solidity entrypoint names, pointing callers at methods they cannot call; a test now pins them.
+
+## [2.0.0-alpha.2] - 2026-09-10
+
+> **Pre-release built against unaudited contracts.** Continues the `2.0.0-alpha` line. `/fhe-airdrop` in this build targets `tokenops-fhe-airdrop-v2`, frozen at commit `7175ac82f467f0f88c05aba1a4536892999b4251`, which has not completed a final security audit. Every Sepolia `fheAirdrop` address moved in this build, and breaking changes may land between any two alpha builds without a major bump (SemVer prerelease semantics). Published on the `alpha` dist-tag; `latest` stays on `1.6.0`. **For internal testing, not production value.**
+>
+> Migration guide: [`docs/migration/airdrop-v1-to-v2.md`](docs/migration/airdrop-v1-to-v2.md). Support policy: [`SUPPORT.md`](SUPPORT.md).
+
+### Changed - BREAKING
+
+- **`MerkleAirdropClient.claim` and `.getClaimAmount` submit an explicit claim identity.** The contracts gained a leading `address account`, which decoupled the leaf/accounting identity from the address the FHE input proof binds to. A relayer can now settle a leaf on a recipient's behalf.
+- **`CampaignEntry` is `{ account, boundTo, handle, inputProof, merkleProof }`.** `recipient` is removed with **no alias**, as are `MerkleLeafInput.recipient` and `LeafOfArgs.recipient`. The field meant "leaf identity and submitter" at once and those are now different addresses, so an alias would have kept compiling while meaning something else. Entries serialised under `2.0.0-alpha.1` must be re-keyed; their handles remain valid, since leaf hashing did not change.
+- **Every Sepolia `fheAirdrop` address moved.** `claim`'s breaking signature forced a fresh Merkle implementation and the deploy script redeploys the whole system, factory included. Instances created through the previous factory are unreachable from this release, and a campaign planned against it now fails `PredictionDriftError`.
+- `claimAndUnwrap` is deliberately **unchanged** and remains submitted for the caller: publishing an allocation as a plain ERC-20 transfer is the recipient's own choice, so a relayed unwrap is unrepresentable rather than rejected. A `submitter`-bound campaign therefore has no unwrap path.
+- `SenderNotAllowedToUseHandle` is gone from the Merkle ABI — that path no longer calls `FHE.fromExternal`.
+
+### Added
+
+- **Batched relayed rosters are chunked at 32 recipients**, the 2048-bit input-ciphertext limit for `euint64`. `@zama-fhe/sdk` does not enforce it client-side, so an unchunked batch would have failed inside the prover; each chunk's proof is bound to the same submitter, so claims are unaffected.
+- **`submitter?: Address` on every campaign builder** (`CampaignSubmitterOption`, accepted by `buildMerkleCampaign`, `encryptCampaignAmounts`, `planMerkleCampaign` and `rotateMerkleRoot`). Omitted keeps per-recipient binding; set binds the whole roster to one address under a single `encryptUint64Batch` call with one shared `inputProof`. The two shapes are mutually exclusive because an input proof carries exactly one `userAddress`, which is why bulk distribution needs a relayer. Shaped so a per-recipient `submitters?: Address[]` stays additive.
+- **`UnauthorizedRedirectError`** (`TOKENOPS_UNAUTHORIZED_REDIRECT`), carrying `account`, `to` and `submitter` — the relation is the error, so blaming a single argument would mislead. Thrown before the write and mapped from the contract revert. `ZeroAccount` maps to `InvalidArgumentError`.
+- **72 React hooks**, completing parity with the headless surface. Recipient, creator, campaign-owner and compliance-manager tiers on `@tokenops/sdk/fhe-airdrop/react`; the factory-admin tier (fee setters, implementation pointers, policy setters) on `@tokenops/sdk/fhe-airdrop/advanced/react`. Includes the encrypted-view mutations (`useAccessMerkleClaimAmount`, `useAccessEcdsaClaimAmount`, `useAdminGetCurrentBalance` and the disclosure family) that submit a transaction and return a handle recovered from the receipt.
+- `useMemoComplianceManagerClient`, so the compliance-manager surface has a hook path at all.
+
+### Fixed
+
+- **`useMerkleClaim` invalidated the wrong account.** It keyed `getClaimedAmount` on the transaction sender; the contract keys `claimedAmount` on the claim identity, so every relayed claim invalidated the relayer's cache entry and left the recipient's read stale.
+- **`getClaimAmount` extracted the ACL handle for the wrong grantee.** The contract grants the outstanding handle to `account`, never the caller, so a relayed preview threw `ReceiptEventNotFoundError` after its transaction had already been mined. Silent on the self-preview path.
+- The vendored local-fixture bytecode was a commit behind the vendored ABIs, so local Merkle suites deployed an implementation carrying the old `claim` selector.
+- The ABI generator now emits `@alpha` itself, instead of relying on a hand-added tag that every regeneration silently dropped.
+
 ## [1.6.0](https://github.com/VestingLabs/tokenops-sdk/compare/v1.5.1...v1.6.0) (2026-07-28)
 
 ### Features
@@ -24,7 +89,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 >
 > Migration guide: [`docs/migration/airdrop-v1-to-v2.md`](docs/migration/airdrop-v1-to-v2.md). Support policy: [`SUPPORT.md`](SUPPORT.md).
 
-### Changed — BREAKING
+### Changed - BREAKING
 
 - **`/fhe-airdrop` now targets confidential airdrop v2.** The subpath name is unchanged; everything behind it is new. v1 and v2 are different contract systems, not two versions of one — there is no in-place upgrade path for a deployed v1 airdrop. `AIRDROP_CONTRACTS_COMMIT` pins the contract commit the vendored ABIs were generated from.
 - **`DEPLOYED_ADDRESSES.fheAirdrop` reshaped from one key to four.** Previously a single `confidentialAirdropFactory`; now `{ airdropFactory, ecdsaImplementation, merkleImplementation, complianceManagerImplementation }`. Code reading `DEPLOYED_ADDRESSES.fheAirdrop[chainId]` must read `.airdropFactory[chainId]`. Note this member is `@public`, not `@alpha` — it is the one breaking change outside the alpha-tagged surface.
@@ -198,7 +263,7 @@ _Tagged but never published — the release workflow failed on this tag; the con
 - **`ConfidentialVestingFactoryClient.createManager`, `ConfidentialAirdropFactoryClient.createConfidentialAirdrop`, and `ConfidentialAirdropFactoryClient.createAndFundConfidentialAirdrop` now block on `waitForTransactionReceipt` + `parseEventLogs` internally before resolving.** The returned `Create*Result` carries a fully-parsed `manager` / `airdrop` address when the promise resolves — callers no longer need a separate `waitForTransactionReceipt` + event-log scan after the call. Consumer-visible behavior change: if your code was doing `const { hash } = await createManager(...); const receipt = await waitForTransactionReceipt(hash)` you will now double-wait (harmless, but an extra round-trip). Drop the extra `waitForTransactionReceipt` call.
 - **`createManagerAndGetAddress` and `createConfidentialAirdropAndGetAddress` are now passthroughs** — they no longer add a second wait step on top of the base creator. They remain exported as convenience aliases for consumers who discovered them first, but the base methods are the canonical entry point.
 
-### Changed — BREAKING (pre-1.0 publish)
+### Changed - BREAKING (pre-1.0 publish)
 
 The package has not been published to npm yet (`npm view @tokenops/sdk` returns 404), so the entries below land as direct shape changes rather than additive `*AndGetX` helpers.
 

package/README.md

@@ -32,9 +32,9 @@ All subpaths are independently tree-shakeable. The `/react` paths keep React dep
 | `@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`                | **v2, unaudited** — `alpha` dist-tag, factory live on Sepolia | ECDSA + Merkle confidential airdrop campaigns — see [Compatibility](#compatibility)                                                                      |
-| `@tokenops/sdk/fhe-airdrop/react`          | **v2, unaudited**                                             | React/wagmi hooks for confidential airdrops                                                                                                              |
+| `@tokenops/sdk/fhe-airdrop/react`          | **v2, unaudited**                                             | React/wagmi hooks for recipients, campaign creators, campaign owners and the compliance manager                                                          |
 | `@tokenops/sdk/fhe-airdrop/advanced`       | **v2, unaudited**                                             | Prediction-freshness / salt-availability guards for CREATE2 address prediction (prediction itself is on the headline `ConfidentialAirdropFactoryClient`) |
-| `@tokenops/sdk/fhe-airdrop/advanced/react` | **v2, unaudited**                                             | `usePredictEcdsaAirdropAddress` / `usePredictMerkleAirdropAddress`                                                                                       |
+| `@tokenops/sdk/fhe-airdrop/advanced/react` | **v2, unaudited**                                             | Address-prediction hooks plus the factory-admin tier (fee setters, implementation pointers, policy setters)                                              |
 | `@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                                                |
@@ -46,10 +46,16 @@ The canonical exports map is in [`package.json`](https://github.com/VestingLabs/
 
 Which contract generation a given SDK version talks to, and where that generation is deployed:
 
-| SDK             | Airdrop contracts  | Contract commit | Chains  |
-| --------------- | ------------------ | --------------- | ------- |
-| `2.0.0-alpha.x` | v2 (**unaudited**) | `8e5b144`       | Sepolia |
-| `1.x`           | v1                 | n/a             | Sepolia |
+| SDK                       | Airdrop contracts        | Contract commit | Chains  |
+| ------------------------- | ------------------------ | --------------- | ------- |
+| `2.0.0-alpha.3`           | v2 (internal audit only) | `c5c12c2`       | Sepolia |
+| `2.0.0-alpha.1`-`alpha.2` | v2 (unaudited)           | `7175ac8`       | Sepolia |
+| `1.x`                     | v1                       | n/a             | Sepolia |
+
+Alpha builds are pinned to a contract generation, and every generation so far has moved every
+deployed address. An instance created through one generation's factory is unreachable from a
+build pinned to another - read `AIRDROP_CONTRACTS_COMMIT` at runtime to confirm which one you
+have.
 
 `2.x`'s `/fhe-airdrop` is a full replacement of v1, not an extension — see
 [`docs/migration/airdrop-v1-to-v2.md`](docs/migration/airdrop-v1-to-v2.md) for the symbol-by-symbol
@@ -284,7 +290,7 @@ See [Confidential Vesting — React hooks on docs.tokenops.xyz](https://docs.tok
 
 ## Quickstart — confidential airdrop
 
-> **v2, unaudited.** `/fhe-airdrop` targets `tokenops-fhe-airdrop-v2` (`8e5b144`, Sepolia only, `alpha` dist-tag) — see [Compatibility](#compatibility). Migrating from `1.x`? See [`docs/migration/airdrop-v1-to-v2.md`](docs/migration/airdrop-v1-to-v2.md).
+> **v2, internally audited only.** `/fhe-airdrop` targets `tokenops-fhe-airdrop-v2` (`c5c12c2`, Sepolia only, `alpha` dist-tag) - see [Compatibility](#compatibility). Migrating from `1.x`? See [`docs/migration/airdrop-v1-to-v2.md`](docs/migration/airdrop-v1-to-v2.md).
 
 Two claim-authorisation variants share one factory: **ECDSA** (an off-chain signature from a `SIGNER_ROLE` holder) and **Merkle** (inclusion in a published tree). The example below is ECDSA — see [`docs/fhe-airdrop/README.md`](docs/fhe-airdrop/README.md#quickstart--merkle-campaign) for the Merkle flow.
 
@@ -524,7 +530,7 @@ function RecipientClaim({
 }
 ```
 
-See [`docs/fhe-airdrop/README.md`](docs/fhe-airdrop/README.md) for the full hook catalogue (including the Merkle-side `useCreateMerkleAirdrop` / `useMerkleClaim` / `useSetMerkleRoot`), encryptor wiring, address overrides, and query-key reference.
+See [`docs/fhe-airdrop/README.md`](docs/fhe-airdrop/README.md) for the full hook catalogue across both import paths (`/fhe-airdrop/react` for recipients, creators, owners and compliance; `/fhe-airdrop/advanced/react` for prediction and factory admin), encryptor wiring, address overrides, and query-key reference.
 
 ## Quickstart — confidential disperse