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

package/CHANGELOG.md

@@ -5,13 +5,49 @@ 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
+### 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.
@@ -53,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.
@@ -227,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

@@ -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**) | `7175ac8`       | 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` (`7175ac8`, 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.