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

package/dist/fhe-airdrop/react/useMerkleClaimAndUnwrap.d.ts

@@ -7,11 +7,22 @@ import { type AirdropInstanceClientOptions } from "./_shared.js";
  * wrapper's unwrap, making `to` the underlying ERC-20 beneficiary.
  *
  * **Self-only, unlike {@link useMerkleClaim}.** This entrypoint takes no claim identity:
- * the leaf, the accounting and the input proof are all `msg.sender`, so an entry whose
- * `account` is not the submitter is refused before the write. Gate the button on
- * `submitter === entry.account` and fall back to `useMerkleClaim` for relayed claims.
+ * the leaf and the accounting are both `msg.sender`, so an entry whose `account` is not
+ * the sender is refused before the write. Gate the button on `sender === entry.account`
+ * and fall back to `useMerkleClaim` for third-party claims.
  * Also requires an unwrappable campaign - see `useAirdropConfig().unwrappable`.
  *
+ * A third party can still settle the same entry first through `useMerkleClaim`, after
+ * which an unwrap pays an encrypted zero; see {@link MerkleClaimArgs.entry}.
+ *
+ * **The amount is public from the claim transaction.** With the stock wrapper the unwrapped
+ * amount is publicly decryptable at once (the emitted `unwrapRequestId` is its handle);
+ * `finalizeUnwrap` only releases the ERC-20. Only a plain claim keeps it confidential.
+ *
+ * Resolves to the claim's transaction hash; the underlying ERC-20 moves only at the
+ * wrapper's later `finalizeUnwrap`. Pass the hash to `useUnwrapRequest` for the
+ * `unwrapRequestId` that call takes.
+ *
  * **Invalidates:** `useClaimedAmount` for the SENDING account on this instance. The
  * contract advances `claimedAmount[msg.sender]` here, so the key is built from the
  * sender resolved in `onMutate` (`variables.account ?? walletClient.account`) and NOT

package/dist/fhe-airdrop/react/usePlanMerkleCampaign.d.ts

@@ -19,8 +19,13 @@ export type UsePlanMerkleCampaignArgs = Omit<PlanMerkleCampaignArgs, "factory" |
  * hook breaks it with the factory's CREATE2 prediction oracle, then feeds
  * `root` to {@link useCreateMerkleAirdrop} (or
  * {@link useCreateAndFundMerkleAirdrop}) with the SAME `mode`, `creator` and
- * `userSalt`. `initCodeHashAfter` is what `preflightCreateAirdrop`'s
- * `expectedInitCodeHash` wants.
+ * `userSalt`.
+ *
+ * Pass the returned plan to that create as `plan` (and to `usePreflightCreateAirdrop`). The
+ * entries are bound to `plan.predictedAddress`, so the create pins it, checks the root, and
+ * refuses to send once the factory's Merkle implementation has moved since planning
+ * ({@link PredictionDriftError}). `expected: { airdrop: plan.predictedAddress }` is the
+ * lower-level equivalent of the pin alone.
  *
  * **Surface {@link PredictionDriftError}, never swallow it.** It means the
  * factory's Merkle implementation pointer moved mid-build, so every entry is
@@ -34,6 +39,9 @@ export type UsePlanMerkleCampaignArgs = Omit<PlanMerkleCampaignArgs, "factory" |
  * `(variant, mode, creator, userSalt)` predict the same address however
  * different their params.
  *
+ * One relayer request per 32 recipients, issued concurrently; every leaf is
+ * submittable by any address.
+ *
  * **Invalidates:** nothing. Two init-code-hash reads and a prediction — no
  * state moves until the create lands.
  *
@@ -44,9 +52,16 @@ export type UsePlanMerkleCampaignArgs = Omit<PlanMerkleCampaignArgs, "factory" |
  *
  * @example
  * const plan = usePlanMerkleCampaign({ encryptor: () => sdk.relayer });
- * const { root, entries, predictedAddress } = await plan.mutateAsync({
+ * const create = useCreateMerkleAirdrop();
+ * const planned = await plan.mutateAsync({
  *   params, mode: "clone", creator, userSalt, recipients,
  * });
+ * await create.mutateAsync({
+ *   params: { ...params, merkleRoot: planned.root, isMerkleRootMutable: false },
+ *   mode: "clone",
+ *   userSalt,
+ *   plan: planned,
+ * });
  *
  * @alpha
  */

package/dist/fhe-airdrop/react/usePreflightClaim.d.ts

@@ -13,7 +13,7 @@ export interface UsePreflightClaimArgs extends AirdropInstanceHookOptions<Prefli
     dedupMode?: DedupMode;
     /** The account that will SEND the claim and therefore pays the exact-equality gas fee. On a relayed Merkle claim this is the relayer. */
     claimant?: Address;
-    /** Merkle campaigns only: the claim identity, when it is not the submitter. Defaults to `claimant`. */
+    /** Merkle campaigns only: the claim identity, when it is not the sender. Defaults to `claimant`. Any address may send a Merkle claim; only the account itself may redirect with `to`. */
     account?: Address;
     /** The payout destination, if one will be passed. */
     to?: Address;

package/dist/fhe-airdrop/react/usePreflightCreateAirdrop.d.ts

@@ -1,21 +1,30 @@
 import { type UseQueryResult } from "@tanstack/react-query";
 import type { Address, Hex } from "viem";
-import type { PreflightResult } from "../../core/preflight.js";
 import type { DeploymentMode } from "../constants.js";
-import type { EcdsaAirdropParams, MerkleAirdropParams } from "../types.js";
+import { type PreflightCreateResult } from "../guards.js";
+import type { CreateCommitments, EcdsaAirdropParams, MerkleAirdropParams, PlannedCampaign } from "../types.js";
 import { type AirdropHookOptions } from "./_shared.js";
 /** The variant-independent half of {@link UsePreflightCreateAirdropArgs}. */
 /** @alpha */
-export interface PreflightCreateAirdropCommon extends AirdropHookOptions<PreflightResult> {
+export interface PreflightCreateAirdropCommon extends AirdropHookOptions<PreflightCreateResult> {
     mode?: DeploymentMode;
     /** The account that will send `create*`. CREATE2 salts are per-deployer. */
     creator?: Address;
     userSalt?: Hex;
     /**
-     * Pass `plan.initCodeHashAfter` to turn the implementation-drift check on.
-     * Omitting it skips that one check.
+     * The init-code hash the address was predicted against. Supplying it turns
+     * the implementation-drift check on; omitting it skips that one check. A
+     * Merkle `plan` supplies it for you.
      */
     expectedInitCodeHash?: Hex;
+    /**
+     * Commitments to pin instead of quoting fresh at send time. Anything omitted is read
+     * from the factory just before the transaction. For a {@link PlannedCampaign}, pass
+     * `plan` on the Merkle arm instead; `{ airdrop: plan.predictedAddress }` here is the
+     * lower-level equivalent of its pin. A pinned field that differs from the factory's
+     * fresh quote is reported as a `CreateCommitmentMismatchError` blocker.
+     */
+    expected?: Partial<CreateCommitments> | undefined;
 }
 /**
  * `variant` and `params` are correlated, mirroring the headless
@@ -34,22 +43,35 @@ export type UsePreflightCreateAirdropArgs = PreflightCreateAirdropCommon & ({
 } | {
     variant: "merkle";
     params?: MerkleAirdropParams;
+    /**
+     * The {@link PlannedCampaign} the create will realise: pins its address and
+     * checks drift against `plan.initCodeHashAfter`. A disagreeing root, pin or
+     * `expectedInitCodeHash` is reported as an `InvalidArgumentError` blocker.
+     */
+    plan?: PlannedCampaign;
 });
 /**
  * Read-only preflight for `useCreateEcdsaAirdrop` / `useCreateMerkleAirdrop`.
  * Runs every create-time guardrail the write path enforces - chain support,
- * the Merkle/UUPS refusal, the creator's effective upgradeability policy for
+ * the Merkle/UUPS refusal, params the new instance's initializer would revert
+ * on (zero token, an `endTime` less than a minute away, a window that does not
+ * open before it closes, a zero immutable Merkle root, a zero ECDSA signer),
+ * the resolved fee against the factory's ceiling and the creator's bound,
+ * the creator's effective upgradeability policy for
  * `mode: "uups"`, the stock-wrapper probe when `params.common.unwrappable` is
- * set, a salt collision on the predicted address, and implementation drift
- * when `expectedInitCodeHash` is supplied.
+ * set, a salt collision on the predicted address, a pinned `expected`
+ * commitment that drifted from the fresh quote, and implementation drift
+ * when `expectedInitCodeHash` (or a Merkle `plan`) is supplied.
  *
  * **The point is disabling the submit button, not catching after the fact.**
  * `blockers` carries the same typed errors `create*` would have thrown, so a
  * UI branches on `error.code` here exactly as it does in `onError`.
+ * `commitments` is what the create would be sent with, for showing the creator
+ * before they sign.
  *
  * Disabled until `variant`, `params`, `mode`, `creator` and `userSalt` are all
- * set. Refetch after the user changes their target mode or the factory's
- * implementation pointer moves.
+ * set. Factory writes made through this SDK's admin hooks invalidate it;
+ * refetch after a factory change made anywhere else.
  *
  * @remarks
  * Named `…Airdrop` rather than `…Create` so a consumer importing both this and
@@ -57,11 +79,10 @@ export type UsePreflightCreateAirdropArgs = PreflightCreateAirdropCommon & ({
  *
  * @example
  * const { data: report } = usePreflightCreateAirdrop({
- *   variant: "merkle", params, mode: "clone", creator, userSalt,
- *   expectedInitCodeHash: plan.initCodeHashAfter,
+ *   variant: "merkle", params, mode: "clone", creator, userSalt, plan,
  * });
  * const canSubmit = report?.ready === true;
  *
  * @alpha
  */
-export declare function usePreflightCreateAirdrop(args?: UsePreflightCreateAirdropArgs): UseQueryResult<PreflightResult, Error>;
+export declare function usePreflightCreateAirdrop(args?: UsePreflightCreateAirdropArgs): UseQueryResult<PreflightCreateResult, Error>;

package/dist/fhe-airdrop/react/useRefreshComplianceBalance.d.ts

@@ -0,0 +1,36 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { EncryptedViewResult } from "../../fhe/types.js";
+import type { WriteAccountOverride } from "../airdrop-base.js";
+import { type AirdropInstanceClientOptions } from "./_shared.js";
+/**
+ * **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** (audit-04), 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 (CLAUDE.md
+ * Pitfall #1).
+ *
+ * **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`.
+ *
+ * @example
+ * const refresh = useRefreshComplianceBalance({ address: airdropAddress });
+ * const { handle } = await refresh.mutateAsync();
+ *
+ * @alpha
+ */
+export declare function useRefreshComplianceBalance(options: AirdropInstanceClientOptions): UseMutationResult<EncryptedViewResult, Error, WriteAccountOverride | void>;

package/dist/fhe-airdrop/react/useRescueERC20.d.ts

@@ -13,9 +13,9 @@ export interface RescueERC20Args extends WriteAccountOverride {
  * Sweep a plain ERC-20 that was sent to an airdrop instance by mistake.
  * Requires `RESCUER_ROLE`.
  *
- * The campaign's own token is ERC-7984, not ERC-20, so the distribution pool
- * cannot be reached through this path at all — use
- * {@link useWithdrawConfidential} (`TREASURY_ROLE`) for the pool, and
+ * Passing the campaign's own token reverts `CannotRescueAirdropToken` (a wrapper token
+ * answers both interfaces, so this is a check, not an assumption); use
+ * {@link useWithdrawConfidential} for the pool and
  * {@link useRescueOtherConfidentialToken} for a stranded ERC-7984.
  *
  * **Invalidates:** nothing. This subpath has no read hook over arbitrary

package/dist/fhe-airdrop/react/useRescueNativeToken.d.ts

@@ -0,0 +1,23 @@
+import { type UseMutationResult } from "@tanstack/react-query";
+import type { Address, Hex } from "viem";
+import type { WriteAccountOverride } from "../airdrop-base.js";
+import { type AirdropInstanceClientOptions } from "./_shared.js";
+/**
+ * Sweep ETH stranded on a zero-fee airdrop instance (a forced send, or a transfer to the
+ * predicted address before deploy) to `recipient`. Requires `RESCUER_ROLE`.
+ *
+ * Refused on a fee-charging campaign (`NativeRescueRequiresZeroFeeError`): there the ETH is
+ * fee revenue and belongs to `withdrawGasFee`.
+ *
+ * **Invalidates:** nothing. No read hook in this subpath exposes the instance's ETH balance,
+ * so there is no cached query left stale by the sweep.
+ *
+ * @example
+ * const rescue = useRescueNativeToken({ address: airdropAddress });
+ * await rescue.mutateAsync({ recipient: treasuryAddress });
+ *
+ * @alpha
+ */
+export declare function useRescueNativeToken(options: AirdropInstanceClientOptions): UseMutationResult<Hex, Error, {
+    recipient: Address;
+} & WriteAccountOverride>;

package/dist/fhe-airdrop/react/useResolveGasFee.d.ts

@@ -0,0 +1,30 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Address } from "viem";
+import { type AirdropHookOptions } from "./_shared.js";
+/** @alpha */
+export interface UseResolveGasFeeArgs extends AirdropHookOptions<bigint> {
+    /** The account that will send `create*`. Fee overrides are per-creator. */
+    creator?: Address;
+}
+/**
+ * The per-claim fee a `create*` from `creator` would freeze into the new
+ * instance right now: their `setCustomFee` override when enabled, else the
+ * factory default.
+ *
+ * **This is the number `common.maxAcceptedGasFee` is checked against**, so it is
+ * what a create form should show before the creator picks a bound. Composing it
+ * from `useFactoryFees` and `useFactoryCustomFee` by hand means re-implementing
+ * the override-over-default rule in every consumer, and getting it wrong reads
+ * as "no fee" on exactly the accounts that have one.
+ *
+ * **A snapshot, not a quote.** `FEE_MANAGER_ROLE` can move it between this read
+ * and the create landing, which is the case `maxAcceptedGasFee` exists to catch -
+ * so treat this as what to *show*, never as a reason to skip the bound.
+ *
+ * @example
+ * const { data: fee } = useResolveGasFee({ creator: address });
+ * // then: params.common.maxAcceptedGasFee = fee ?? 0n
+ *
+ * @alpha
+ */
+export declare function useResolveGasFee(args?: UseResolveGasFeeArgs): UseQueryResult<bigint, Error>;

package/dist/fhe-airdrop/react/useRotateMerkleRoot.d.ts

@@ -1,6 +1,6 @@
 import { type UseMutationResult } from "@tanstack/react-query";
 import type { WriteAccountOverride } from "../airdrop-base.js";
-import { type CampaignSubmitterOption, type RotatedCampaign } from "../campaign.js";
+import { type RotatedCampaign } from "../campaign.js";
 import type { CampaignRecipient } from "../types.js";
 import { type AirdropInstanceClientOptions } from "./_shared.js";
 /**
@@ -8,7 +8,7 @@ import { type AirdropInstanceClientOptions } from "./_shared.js";
  *
  * @alpha
  */
-export interface UseRotateMerkleRootArgs extends CampaignSubmitterOption, WriteAccountOverride {
+export interface UseRotateMerkleRootArgs extends WriteAccountOverride {
     /** The FULL updated roster, carrying each account's new CUMULATIVE total — never the delta since the last root. */
     recipients: readonly CampaignRecipient[];
 }
@@ -23,6 +23,9 @@ export interface UseRotateMerkleRootArgs extends CampaignSubmitterOption, WriteA
  * rosters. A total below what an account already received pays nothing; a
  * rotation cannot claw back.
  *
+ * One relayer request per 32 recipients, issued concurrently; every leaf is
+ * submittable by any address.
+ *
  * The root is published LAST, so a failed rebuild leaves the previous campaign
  * intact and claimable. Once it lands the old proofs stop verifying:
  * **distribute the new entries to every recipient**, including those whose

package/dist/fhe-airdrop/react/useSignClaimAuthorization.d.ts

@@ -19,6 +19,10 @@ export interface SignClaimAuthorizationArgs extends WriteAccountOverride {
  * dedupId, uint256 deadline)` authorization for an `ECDSAConfidentialAirdrop`
  * instance. The signer must hold `SIGNER_ROLE` on that instance.
  *
+ * **Never sign with an EIP-7702-delegated key.** A delegation switches verification to
+ * ERC-1271 against the delegate, so every outstanding voucher fails although the key
+ * keeps the role. See {@link signClaimAuthorization}.
+ *
  * `airdrop` and `chainId` come from the hook's own options, so a component
  * supplies only the claim fields.
  *

package/dist/fhe-airdrop/react/useTokenOf.d.ts

@@ -0,0 +1,29 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Address } from "viem";
+import { type AirdropHookOptions } from "./_shared.js";
+/** @alpha */
+export interface UseTokenOfArgs extends AirdropHookOptions<Address> {
+    /** The airdrop instance whose recorded token to resolve. */
+    airdrop?: Address;
+}
+/**
+ * Resolve the token the factory recorded for an airdrop instance at create - what
+ * `fundAirdrop` pulls, regardless of what the instance reports today.
+ *
+ * A zero address means the instance did not come from this factory.
+ *
+ * Cached indefinitely once non-zero: the mapping is written once, inside `createX`.
+ * A zero answer (not created yet, or not from this factory) is not cached forever: it
+ * stays stale and refetches on the next mount, focus or `refetch`, because the address
+ * can be created later by another tab, a server or the headless client, none of which
+ * reaches a hook invalidation. The create hooks in this subpath also invalidate this
+ * key for the address they deploy, so a zero already on screen updates immediately;
+ * the per-result `staleTime` covers every other create path, the same policy as
+ * {@link useIsAirdrop}. Override through `query.staleTime`.
+ *
+ * @example
+ * const { data: token } = useTokenOf({ airdrop: airdropAddress });
+ *
+ * @alpha
+ */
+export declare function useTokenOf(args?: UseTokenOfArgs): UseQueryResult<Address, Error>;

package/dist/fhe-airdrop/react/useUnwrapRequest.d.ts

@@ -0,0 +1,25 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { Hex } from "viem";
+import type { UnwrapRequest } from "../airdrop-base.js";
+import { type AirdropInstanceHookOptions } from "./_shared.js";
+/** @alpha */
+export type UseUnwrapRequestArgs = AirdropInstanceHookOptions<UnwrapRequest> & {
+    /** The `claimAndUnwrap` transaction hash. The query stays idle until it is set. */
+    hash: Hex | undefined;
+};
+/**
+ * The unwrap request a `claimAndUnwrap` started: waits for `hash` to be mined and
+ * decodes the instance's `ClaimedAndUnwrapInitiated` event.
+ *
+ * Hand `unwrapRequestId` to the wrapper's `finalizeUnwrap` to release the underlying
+ * ERC-20; with Zama's SDK, `sdk.createToken(wrapper).finalizeUnwrap(unwrapRequestId)`.
+ * The amount was already public from the claim transaction; finalizing discloses nothing new.
+ * A mined receipt does not change, so the result never goes stale.
+ *
+ * @example
+ * const unwrap = useEcdsaClaimAndUnwrap({ address: airdropAddress });
+ * const { data: request } = useUnwrapRequest({ address: airdropAddress, hash: unwrap.data });
+ *
+ * @alpha
+ */
+export declare function useUnwrapRequest(args: UseUnwrapRequestArgs): UseQueryResult<UnwrapRequest, Error>;

package/dist/fhe-airdrop/react/useWithdrawConfidential.d.ts

@@ -8,6 +8,10 @@ import { type AirdropInstanceClientOptions } from "./_shared.js";
  * never appears in plaintext anywhere — the contract reads its own encrypted
  * balance and moves all of it.
  *
+ * Refused while the campaign is unpaused inside its claim window
+ * (`ClawbackRequiresPauseError`): pause with {@link useAirdropPause} first, or run it
+ * outside the window.
+ *
  * **Invalidates:** nothing. No read hook in this subpath's list exposes the
  * confidential pool balance (see {@link useFundAirdrop}'s TSDoc for the same
  * reasoning), so there is no cached query left stale by a withdrawal.

package/dist/fhe-airdrop/roles.d.ts

@@ -26,6 +26,10 @@ export interface InstanceRoleAssignment {
     disclosureAdmin?: Address;
     upgrader?: Address;
     merkleAdmin?: Address;
+    /**
+     * `SIGNER_ROLE`. A dedicated key that is never EIP-7702-delegated (or an ERC-1271 contract
+     * signer): a delegation invalidates every outstanding voucher.
+     */
     signer?: Address;
     /** Granting this always fails from DEFAULT_ADMIN — see planInstanceRoleSplit. */
     feeCollector?: Address;
@@ -66,20 +70,18 @@ export interface RoleGrantOutcome {
  * would only revert on-chain:
  *
  * 1. **`feeCollector`.** `FEE_COLLECTOR_ROLE` is self-administered
- *    (`_setRoleAdmin(FEE_COLLECTOR_ROLE, FEE_COLLECTOR_ROLE)`,
- *    `ConfidentialAirdropBase.sol:142`) — `DEFAULT_ADMIN_ROLE` cannot grant
- *    it, only an existing member can, and the campaign creator never is one
- *    (the factory's collector is seeded instead, `:143`).
+ *    (`_setRoleAdmin(FEE_COLLECTOR_ROLE, FEE_COLLECTOR_ROLE)` at initialization)
+ *    - `DEFAULT_ADMIN_ROLE` cannot grant it, only an existing member can, and
+ *    the campaign creator never is one (the factory's collector is seeded instead).
  * 2. **`admin` set to the zero address.** Mirrors the contract's
- *    unconditional `ZeroAdminGrant` guard (`_grantRole`, `:281`).
+ *    unconditional `ZeroAdminGrant` guard in `_grantRole`.
  * 3. **A variant-only role on the wrong campaign** — `merkleAdmin` on an
  *    ECDSA instance, or `signer` on a Merkle one. Neither role exists there;
  *    the getter itself would revert.
  *
  * `admin`, when present, always produces two steps — grant the new admin,
  * then revoke `args.caller` — and the revoke is always ORDERED LAST, after
- * every other step in the plan. `_revokeRole`'s `LastAdmin` floor
- * (`ConfidentialAirdropBase.sol:261`) blocks removing the sole
+ * every other step in the plan. `_revokeRole`'s `LastAdmin` floor blocks removing the sole
  * `DEFAULT_ADMIN_ROLE` member, so revoking the creator first would strand
  * every later grant with no admin left to authorize it.
  *
@@ -96,6 +98,73 @@ export declare function planInstanceRoleSplit(args: {
     caller: Address;
     airdropType: "ecdsa" | "merkle";
 }): RoleGrantStep[];
+/**
+ * One call of a Safe MultiSend batch: a zero-value `grantRole` / `revokeRole`
+ * on the instance.
+ *
+ * @alpha
+ */
+export interface InstanceRoleCall {
+    to: Address;
+    data: Hex;
+    value: 0n;
+}
+/**
+ * The `bytes32` constants {@link encodeInstanceRoleSplit} encodes, keyed by
+ * {@link RoleName}. Read them off the instance (the `*_ROLE()` getters on
+ * `AirdropBaseClient` and its subclasses, or `useAirdropRoleConstants`);
+ * hashing the names yourself would silently grant a role nothing checks if a
+ * constant is ever renamed. `DEFAULT_ADMIN_ROLE` may be omitted: it is
+ * OpenZeppelin's fixed `bytes32(0)`.
+ *
+ * @alpha
+ */
+export type InstanceRoleConstants = Partial<Record<RoleName, Hex>>;
+/**
+ * Encode a {@link planInstanceRoleSplit} plan as the ordered calls a Safe
+ * executes in one MultiSend batch - the multisig counterpart of
+ * {@link grantInstanceRoles}.
+ *
+ * {@link grantInstanceRoles} must mine each step before simulating the next,
+ * which a threshold Safe cannot do in one session. A batch does not need to:
+ * its calls run in order inside one transaction, so the plan's
+ * grant-before-revoke ordering holds and the `LastAdmin` floor never sees the
+ * new admin missing. Plan with `caller` set to the Safe address, since the Safe
+ * is the account whose `DEFAULT_ADMIN_ROLE` the handoff revokes.
+ *
+ * The batch is atomic: one reverting call reverts the whole split, unlike the
+ * per-step outcomes of {@link grantInstanceRoles}.
+ *
+ * To keep the Safe as co-admin (the `revokeFromCreator: false` of
+ * {@link grantInstanceRoles}), drop the `revoke` `DEFAULT_ADMIN_ROLE` step
+ * from the plan before encoding.
+ *
+ * Each call is a plain CALL, so `operation` is omitted. Safe SDKs type `value`
+ * as a decimal string; map it when handing the calls over.
+ *
+ * @param args.airdrop The instance the calls target.
+ * @param args.steps The plan, in the order {@link planInstanceRoleSplit} returned it.
+ * @param args.roleConstants The role constants read off the instance.
+ * @returns One {@link InstanceRoleCall} per step, in plan order.
+ * @throws {@link InvalidArgumentError} when a step names a role whose constant is missing.
+ *
+ * @example
+ * const steps = planInstanceRoleSplit({ assignment, caller: safeAddress, airdropType: "merkle" });
+ * const calls = encodeInstanceRoleSplit({
+ *   airdrop,
+ *   steps,
+ *   roleConstants: { PAUSER_ROLE: await client.PAUSER_ROLE() },
+ * });
+ * // One MultiSend transaction; Safe SDKs take `value` as a string.
+ * const transactions = calls.map((c) => ({ ...c, value: "0" }));
+ *
+ * @alpha
+ */
+export declare function encodeInstanceRoleSplit(args: {
+    airdrop: Address;
+    steps: readonly RoleGrantStep[];
+    roleConstants: InstanceRoleConstants;
+}): InstanceRoleCall[];
 /**
  * Execute an {@link InstanceRoleAssignment} against a live instance:
  * {@link planInstanceRoleSplit} the steps, then submit them one at a time,
@@ -113,6 +182,12 @@ export declare function planInstanceRoleSplit(args: {
  * intentionally: correctness of the ordering guarantee in
  * {@link planInstanceRoleSplit} depends on it.
  *
+ * **Safe / multisig signers cannot use this.** A threshold Safe cannot mine
+ * one step before proposing the next, so there is deliberately no
+ * `waitForReceipt: false` here. Plan with {@link planInstanceRoleSplit}
+ * (`caller` = the Safe) and submit {@link encodeInstanceRoleSplit}'s calls as
+ * one MultiSend batch instead.
+ *
  * **This is several transactions, not one — never atomic.** Each step is
  * caught individually, so one failing grant or revoke does not abort the
  * rest; inspect each {@link RoleGrantOutcome} rather than assuming