v2.0.0-rc.1 release candidate

The API is frozen and later candidates carry fixes only, except the receipt-free and Safe create surface of /fhe-airdrop, which is @beta. Published on the next dist-tag; latest stays on 1.6.0 until 2.0.0.

Encrypted readuseMutationencrypted handle

useRefreshComplianceBalance

Submits a transaction. Re-grants the compliance-manager clone on the instance's current pool balance and returns the handle it was granted on.

Import

@tokenops/sdk/fhe-airdrop/react

Return

{ mutate, mutateAsync, isPending, error, data }

Lifecycle

Encrypted read

Description

Submits a transaction. Re-grants the compliance-manager clone on the instance's current pool balance and returns the handle it was granted on.

Permissionless, unlike every other disclosure hook here. The token rotates the instance's balance handle on every incoming transfer, including a direct one no airdrop code observes, and the clone's existing grant does not follow. Anyone may restore it because there is no argument to abuse: the only handle read is the instance's own balance and the only grantee is the clone wired at initialization.

The handle comes from the receipt's ACL Allowed event naming the CLONE, not the caller - so unless the connected account is the clone, it cannot decrypt what this returns. That is also why it is a mutation: the entrypoint calls FHE.allow, so its handle can never come from a simulation.

A snapshot, not a subscription. The handle stays readable forever (ACL is append-only), but the next incoming transfer rotates the instance onto a new handle the clone was never granted on. Re-run this after any transfer in.

Invalidates: nothing, and nothing invalidates it - a mutation result is not a cache entry, so no write can refresh it. Re-run it yourself after useFundAirdrop or useWithdrawConfidential.

Signature

@tokenops/sdk/fhe-airdrop/react

function useRefreshComplianceBalance(options: AirdropInstanceClientOptions): UseMutationResult<EncryptedViewResult, Error, WriteAccountOverride | void>;

Want to run a similar shape interactively? The Playground ships 12 ready presets across vesting / airdrop / disperse / faucet — deploy a manager, create a vesting, claim, and run the product equivalents. The deep-link above auto-selects the closest preset to useRefreshComplianceBalance; pick another from the dropdown if you'd rather start there.

Example

@tokenops/sdk/fhe-airdrop/react · @example

tsx

const refresh = useRefreshComplianceBalance({ address: airdropAddress });
const { handle } = await refresh.mutateAsync();

Pulled directly from the hook's TSDoc block — the same snippet your IDE shows on hover.

Errors

This mutation can reject with SDK-level, product-level, or generic-fallback errors. Product classes carry the offending value as fields — render them inline instead of a generic "transaction failed." See Airdrop v2 › Errors for the per-class recovery table.

Invalidation recipe

After this mutation succeeds, invalidate the queries it affects so consumer UI re-fetches fresh state. The SDK never auto-invalidates — that's a consumer decision (different apps cache different shapes).

patterns/invalidation.ts

import { useQueryClient } from "@tanstack/react-query";

const queryClient = useQueryClient();
const refreshComplianceBalance = useRefreshComplianceBalance(/* options */);

refreshComplianceBalance.mutate(args, {
  onSuccess() {
    // Coarse invalidation: refresh every cached read on this product surface.
    queryClient.invalidateQueries({
      queryKey: ["tokenops-sdk", "fhe-airdrop"],
    });
  },
});