TokenOps
Disperse · Flows

The four disperse flows.

The singleton + wallet-pair architecture collapses every disperse campaign to four paths, each demoed end-to-end.

Prerequisite: operator approval

Before creating, funding, or dispersing, the token must approve this contract as an operator: call token.setOperator(<contract address>, deadline) first. Without it the transaction reverts with ERC7984UnauthorizedSpender (0x79f2cb38).

The SDK surfaces the missing approval as: “The token has not approved this contract as an operator. Call setOperator() (see /fhe operators) before this transaction.”

Do not route these calls through Multicall3. aggregate3 makes the Multicall3 contract the msg.sender, which breaks operator approvals and per-user clone authorization. Use the built-in batch functions instead: batchCreateVesting, disperse, batchDiscloseToParty.

  1. 1

    Register (one-time per user)

    Operator calls register(token) on the disperse singleton. Singleton deploys a deterministic wallet pair (wallet0 + wallet1) as ERC-1167 minimal-proxy clones via Clones.cloneDeterministic (OpenZeppelin): predictable addresses via Clones.predictDeterministicAddress, no per-recipient deploy.

    1. useRegister({ token }) — submits the registration tx
    2. Singleton clones WALLET_IMPLEMENTATION twice (wallet0 + wallet1) under deterministic salts
    3. useGetWallets({ user }) returns the deployed pair
    Hooks
    useRegisteruseGetWalletsusePredictWallets
    Story · Ch 1 — Register Aria's disperse account
  2. 2

    Approve the wallet pair

    ERC-7984 operator authorization is the pre-step for any flow that pulls funds. register() has the wallet pair approve the singleton as their operator for its token; wallet-mode disperses then pull the batch through wallet0/wallet1 at send time.

    1. setOperator (re-exported from @tokenops/sdk/fhe-disperse) for ERC-7984 operator grants
    2. useApproveTokenOnWallets({ token }) approves the registered pair for additional tokens
    3. Verify with useHasApprovedSubwallets({ user, token })
    Hooks
    useApproveTokenOnWalletsuseHasApprovedSubwallets
  3. 3

    Disperse to N recipients

    One call, N transfers. SDK builds the encrypted batch input proof; singleton verifies + atomically transfers to every recipient, splitting wallet-mode batches across wallet0/wallet1.

    1. usePreflightDisperse({ user, token, recipients, amounts, mode }) returns the full PreflightReport
    2. useDisperse.mutate({ token, mode, recipients, amounts }) encrypts the batch in one input proof, submits
    3. Receipt's WalletDistribution / DirectDistribution events list per-recipient handles
    Hooks
    useDisperseusePreflightDisperse
    Recipe: Mainnet readiness checklist Story · Ch 2 — Pay A, B, and C in one tx
  4. 4

    Recover + fee management

    Pull funds back from a subwallet after a campaign closes; PAUSER_ROLE pause/unpause; fee withdrawal.

    1. useRecoverFromWallets({ token, to }) returns residual balance to the `to` address you specify
    2. Fee-collector flow: useWithdrawTokenFee / useWithdrawGasFee
    3. usePause / useUnpause for incident response
    Hooks
    useRecoverFromWalletsuseWithdrawTokenFeeusePause
    Recipe: Error recovery patterns