@tokenops/sdk 1.0.0

package/dist/fhe-vesting/manager.d.ts

@@ -0,0 +1,808 @@
+import type { Account, Address, Hex, PublicClient, WalletClient } from "viem";
+import { type PreflightResult } from "../core/preflight.js";
+import { type EncryptedHandle, type Role, type TxHash, type VestingId } from "../core/brands.js";
+import { type SdkTelemetry } from "../core/telemetry.js";
+import { type Encryptor, type EncryptorSource } from "./encryption.js";
+import { FeeType, type DisclosureType, type EncryptedInput, type EncryptedViewResult, type PendingTransfer, type VestingInfo, type VestingParams } from "./types.js";
+export type { EncryptedViewResult } from "./types.js";
+export interface ConfidentialVestingManagerClientConfig {
+    publicClient: PublicClient;
+    walletClient?: WalletClient | undefined;
+    /** Manager clone address (per-user; use the factory's `predictManagerAddress` or `ManagerCreated` event). */
+    address: Address;
+    /**
+     * Default encryptor used by methods that take plaintext inputs. Optional at
+     * construction time, but **REQUIRED at call time** for any method that submits
+     * encrypted inputs: `createVesting`, `batchCreateVesting`, `partialClaim`,
+     * `splitVesting`, `withdrawAdmin`, `withdrawTokenFee`. These methods throw if
+     * no encryptor is resolvable when they run — TypeScript cannot catch this at
+     * construction time.
+     *
+     * Pass an eager {@link Encryptor} instance (server, vitest) or a
+     * `() => Encryptor | undefined` factory (React contexts, Vue refs, signals)
+     * whose result is resolved per-encryption so the live instance is always picked up.
+     */
+    encryptor?: EncryptorSource;
+    /**
+     * FHEVM ACL contract address override. When omitted, resolved from
+     * `publicClient.chain?.id` via the SDK's chain registry; the constructor
+     * throws `DeploymentAddressUnavailableError` if neither is available.
+     * Required because `#encryptedView` filters the receipt for ACL grants
+     * to extract the returned handle.
+     */
+    aclAddress?: Address;
+    /**
+     * Optional telemetry sink. When provided, the SDK brackets public write
+     * methods with named spans (`fhe-vesting.manager.pause`, etc.). Defaults to
+     * a no-op — zero overhead, zero leakage of consumer-side identifiers.
+     *
+     * Structurally compatible with `NoopTelemetry` / `ConsoleTelemetry` /
+     * `TokenOpsTelemetry` exported from `@tokenops/sdk/telemetry`.
+     */
+    telemetry?: SdkTelemetry | undefined;
+}
+/**
+ * Common fields for {@link CreateVestingArgs}. The encryption path is
+ * discriminated below — pass `encryptor` (SDK encrypts `amount`) XOR
+ * `encryptedInput` (caller pre-encrypted). Passing both is a compile error.
+ */
+interface CreateVestingArgsCommon {
+    params: VestingParams;
+    /**
+     * Plaintext token amount. The SDK encrypts it via `encryptor`.
+     *
+     * Supply **exactly one** of `amount` or `encryptedInput`. Passing both throws
+     * `InvalidArgumentError` — the SDK refuses to silently pick a side, which
+     * would let the plaintext metadata diverge from the on-chain ciphertext.
+     */
+    amount?: bigint;
+    /** Override the per-client `encryptor`. */
+    encryptor?: Encryptor;
+    /**
+     * Pre-encrypted input — bypasses `encryptor`. Use when callers manage their
+     * own encryption (e.g. server-side issuance). Mutually exclusive with `amount`.
+     */
+    encryptedInput?: EncryptedInput;
+    account?: Account | Address;
+}
+/**
+ * Discriminated union: provide EITHER an encryptor (the SDK encrypts the
+ * plaintext `amount`) OR a pre-built `encryptedInput`. Passing both is a TS
+ * error — the JSDoc previously documented this as a runtime contract; now
+ * it's enforced by the compiler.
+ */
+export type CreateVestingArgs = (CreateVestingArgsCommon & {
+    /** Plaintext token amount. The SDK encrypts it via `encryptor`. */
+    amount: bigint;
+    /** Override the per-client `encryptor`. */
+    encryptor?: Encryptor | undefined;
+    encryptedInput?: never;
+}) | (CreateVestingArgsCommon & {
+    /** Pre-encrypted input — bypasses `encryptor`. Use when callers manage their own encryption. */
+    encryptedInput: EncryptedInput;
+    amount?: never;
+    encryptor?: never;
+});
+export interface BatchCreateVestingArgs {
+    items: Array<{
+        params: VestingParams;
+        amount: bigint;
+    }>;
+    encryptor?: Encryptor | undefined;
+    account?: Account | Address | undefined;
+}
+/** Common fields for {@link ClaimArgs}. */
+interface ClaimArgsCommon {
+    /** bytes32 vesting schedule ID emitted in the `VestingCreated` event. */
+    vestingId: VestingId;
+    account?: Account | Address | undefined;
+}
+/**
+ * Arguments for {@link ConfidentialVestingManagerClient.claim} and
+ * {@link ConfidentialVestingManagerClient.adminClaim}, discriminated by
+ * `feeType` (read via `getFeeInfo()`).
+ *
+ * For `FeeType.Gas`, pass `value` (gas fee in wei).
+ * For `FeeType.DistributionToken`, omit `value` (token fee deducted on-chain).
+ */
+export type ClaimArgs = (ClaimArgsCommon & {
+    feeType: FeeType.Gas;
+    value: bigint;
+}) | (ClaimArgsCommon & {
+    feeType: FeeType.DistributionToken;
+    value?: never;
+});
+interface PartialClaimArgsCommon {
+    vestingId: Hex;
+    value?: bigint;
+    account?: Account | Address;
+}
+/**
+ * Discriminated union: provide EITHER an encryptor (the SDK encrypts `amount`)
+ * OR a pre-built `encryptedInput`. Passing both is a compile error.
+ */
+export type PartialClaimArgs = (PartialClaimArgsCommon & {
+    amount: bigint;
+    encryptor?: Encryptor | undefined;
+    encryptedInput?: never;
+}) | (PartialClaimArgsCommon & {
+    encryptedInput: EncryptedInput;
+    amount?: never;
+    encryptor?: never;
+});
+/** Common fields for {@link WithdrawAdminArgs} — discriminated below. */
+interface WithdrawAdminArgsCommon {
+    account?: Account | Address | undefined;
+}
+/**
+ * Discriminated union: provide EITHER an encryptor (the SDK encrypts `amount`)
+ * OR a pre-built `encryptedInput`. Passing both is a compile error.
+ */
+export type WithdrawAdminArgs = (WithdrawAdminArgsCommon & {
+    amount: bigint;
+    encryptor?: Encryptor | undefined;
+    encryptedInput?: never;
+}) | (WithdrawAdminArgsCommon & {
+    encryptedInput: EncryptedInput;
+    amount?: never;
+    encryptor?: never;
+});
+/** Common fields for {@link WithdrawTokenFeeArgs} — discriminated below. */
+interface WithdrawTokenFeeArgsCommon {
+    to: Address;
+    account?: Account | Address | undefined;
+}
+/**
+ * Discriminated union: provide EITHER an encryptor (the SDK encrypts `amount`)
+ * OR a pre-built `encryptedInput`. Passing both is a compile error.
+ */
+export type WithdrawTokenFeeArgs = (WithdrawTokenFeeArgsCommon & {
+    amount: bigint;
+    encryptor?: Encryptor | undefined;
+    encryptedInput?: never;
+}) | (WithdrawTokenFeeArgsCommon & {
+    encryptedInput: EncryptedInput;
+    amount?: never;
+    encryptor?: never;
+});
+export interface SplitVestingArgs {
+    /** bytes32 vesting schedule ID emitted in the `VestingCreated` event. */
+    vestingId: VestingId;
+    /**
+     * Plaintext share numerator (kept confidential on-chain — SDK encrypts it).
+     *
+     * Note: after auto-scaling, large numerators (close to `uint64` max after
+     * multiplication by the scale factor) will cause `assertUint64` to throw.
+     * Call `scaleRatio({ numerator, denominator })` manually first to preview
+     * the scaled values, then pass `preScaled: true` to skip double-scaling.
+     */
+    numerator: bigint;
+    /**
+     * Plaintext denominator. Auto-scaled to the universal privacy-preserving
+     * constant `FHE_SPLIT_DENOMINATOR` (`90_090_000` = LCM(1..16, 10_000)),
+     * which is well above the contract's `MIN_SPLIT_DENOMINATOR` (10_000) floor.
+     * Use the {@link share} builder (`share.fraction` / `share.basisPoints`)
+     * for exact-integer ratios without manual scaling.
+     */
+    denominator: bigint;
+    newRecipient: Address;
+    encryptor?: Encryptor | undefined;
+    /**
+     * Set to `true` if you have already called `scaleRatio` on the
+     * `numerator`/`denominator` pair. By default the SDK calls `scaleRatio`
+     * automatically; pass `preScaled: true` to skip it and use your values as-is.
+     */
+    preScaled?: boolean | undefined;
+    account?: Account | Address | undefined;
+}
+export interface InitiateTransferArgs {
+    vestingId: VestingId;
+    newRecipient: Address;
+    transferDurationSeconds: number;
+    account?: Account | Address | undefined;
+}
+export interface DiscloseArgs {
+    vestingId: VestingId;
+    party: Address;
+    disclosureType: DisclosureType;
+    account?: Account | Address | undefined;
+}
+/**
+ * Result of {@link ConfidentialVestingManagerClient.splitVesting}.
+ *
+ * The `newVestingId` is parsed from the `VestingSplit` event filtered by the
+ * `(originalVestingId, newRecipient)` indexed args — both supplied at call
+ * time, so the filter is exact.
+ */
+export interface SplitVestingResult {
+    hash: Hex;
+    newVestingId: Hex;
+}
+/**
+ * Result of {@link ConfidentialVestingManagerClient.discloseToParty} /
+ * {@link ConfidentialVestingManagerClient.adminDiscloseToParty}.
+ *
+ * The `handle` is the `euint128` ciphertext parsed from the `AmountDisclosed`
+ * event — `(vestingId, discloser=msg.sender, party)` are indexed and the
+ * filter pins all three.
+ */
+export interface DiscloseToPartyResult {
+    hash: Hex;
+    handle: Hex;
+}
+/** Result of {@link ConfidentialVestingManagerClient.batchDiscloseToParty} /
+ *  {@link ConfidentialVestingManagerClient.adminBatchDiscloseToParty}.
+ *
+ * `handles[i]` corresponds to `vestingIds[i]` from the input. Each handle
+ * comes from the `AmountDisclosed` event keyed on that vestingId.
+ */
+export interface BatchDiscloseToPartyResult {
+    hash: Hex;
+    handles: readonly Hex[];
+}
+/**
+ * Typed wrapper around a deployed `ConfidentialVestingManager` clone. The
+ * underlying contract delegates calls to its extension via `fallback()`; we
+ * merge both ABIs so the consumer sees one logical surface.
+ *
+ * Pass `encryptor` to enable methods that take plaintext `amount` inputs. The SDK
+ * encrypts them internally — callers never handle raw ciphertext.
+ *
+ * @example
+ * const manager = createConfidentialVestingManagerClient({
+ *   publicClient, walletClient,
+ *   address: managerAddress,
+ *   encryptor,   // RelayerNode / RelayerWeb / MockFhevmInstance
+ * });
+ */
+export declare class ConfidentialVestingManagerClient {
+    #private;
+    readonly publicClient: PublicClient;
+    readonly walletClient?: WalletClient;
+    readonly address: Address;
+    readonly encryptor?: EncryptorSource;
+    constructor(config: ConfidentialVestingManagerClientConfig);
+    /**
+     * The FHEVM ACL contract address used by encrypted-view methods to parse
+     * `ACL.Allowed` events. Resolved lazily on first access; throws
+     * `DeploymentAddressUnavailableError` if no override was passed and the
+     * SDK does not have an ACL deployed for the connected chain.
+     */
+    get aclAddress(): Address;
+    /**
+     * Return the ERC-7984 token address this manager clone is bound to.
+     * @returns Checksummed token address.
+     */
+    token(): Promise<Address>;
+    /**
+     * Return the fee model baked into this clone's immutable args.
+     * @returns `FeeType.Gas` (0) or `FeeType.DistributionToken` (1).
+     */
+    feeType(): Promise<FeeType>;
+    /**
+     * Return the raw fee value baked into this clone's immutable args.
+     * Interpretation depends on `feeType`: wei for `Gas`, basis points for `DistributionToken`.
+     * @returns Fee amount in the unit appropriate for `feeType`.
+     */
+    fee(): Promise<bigint>;
+    /**
+     * Read the manager's fee configuration in one call.
+     *
+     * Both fields are immutable (baked into the clone's bytecode at deploy time), so
+     * consumers should memoize the result for the manager's lifetime.
+     *
+     * @returns `{ feeType, fee }` — feed both into the discriminated
+     *   {@link ClaimArgs} union to construct the correct claim shape.
+     * @example
+     * const { feeType, fee } = await manager.getFeeInfo();
+     * await manager.claim(
+     *   feeType === FeeType.Gas
+     *     ? { feeType, vestingId, value: fee }
+     *     : { feeType, vestingId },
+     * );
+     */
+    getFeeInfo(): Promise<{
+        feeType: FeeType;
+        fee: bigint;
+    }>;
+    /**
+     * Return the block number at which this clone was deployed.
+     * Used for event log scanning — start from this block to avoid scanning from genesis.
+     * @returns Block number as `bigint`.
+     */
+    deploymentBlockNumber(): Promise<bigint>;
+    /**
+     * Return whether `splitVesting` is enabled on this clone.
+     * @returns `true` if the split feature is enabled.
+     */
+    isSplitEnabled(): Promise<boolean>;
+    /**
+     * Return whether this clone supports pause/unpause.
+     * @returns `true` if the clone is pausable.
+     */
+    isPausable(): Promise<boolean>;
+    /**
+     * Return the current pause state. Always `false` for non-pausable clones.
+     * @returns `true` if the manager is paused and claims are blocked.
+     */
+    paused(): Promise<boolean>;
+    /**
+     * Return the maximum number of vesting schedules allowed in a single `batchCreateVesting` call.
+     * @returns Batch size limit as `bigint`.
+     */
+    maxBatchSize(): Promise<bigint>;
+    /**
+     * Return the maximum number of vesting ids allowed in a single `batchRevokeVesting` call.
+     * @returns Revoke batch size limit as `bigint`.
+     */
+    maxRevokeBatchSize(): Promise<bigint>;
+    /**
+     * Return metadata for a vesting schedule. Returns a zero-struct when `vestingId` does not exist.
+     * @param vestingId The `bytes32` vesting schedule ID from the `VestingCreated` event.
+     * @returns `VestingInfo` struct; `startTimestamp === 0` means the schedule does not exist.
+     * @example
+     * const info = await manager.getVestingInfo(vestingId);
+     * if (info.startTimestamp === 0) throw new Error("vesting not found");
+     */
+    getVestingInfo(vestingId: VestingId): Promise<VestingInfo>;
+    /**
+     * Return all recipient addresses that have at least one vesting schedule on this manager.
+     * @returns Array of checksummed addresses; may be large — use `getAllRecipientsSliced` for pagination.
+     */
+    getAllRecipients(): Promise<readonly Address[]>;
+    /**
+     * Return the total number of unique recipients on this manager.
+     * @returns Count as `bigint`.
+     */
+    getAllRecipientsLength(): Promise<bigint>;
+    /**
+     * Slice of `getAllRecipients`, half-open `[start, end)`.
+     *
+     * Accepts `bigint | number` for `start` / `end` for ergonomics on read paths
+     * — CI scripts typically derive these from `Number(process.env.X)` and
+     * forcing bigint coercion at the call site is a pure paper cut. The
+     * underlying contract reads through unchanged (viem coerces). R22
+     * devops-integrator MINOR-4; R25 close.
+     */
+    getAllRecipientsSliced(start: bigint | number, end: bigint | number): Promise<readonly Address[]>;
+    /**
+     * Return whether `account` has at least one vesting schedule on this manager.
+     * @param account Address to check.
+     * @returns `true` if the account is a known recipient.
+     */
+    isRecipient(account: Address): Promise<boolean>;
+    /**
+     * Return all vesting schedule IDs for `recipient`.
+     * @param recipient Address of the vesting recipient.
+     * @returns Array of `bytes32` vesting IDs; may be large — use `getAllRecipientVestingsSliced` for pagination.
+     */
+    getAllRecipientVestings(recipient: Address): Promise<readonly VestingId[]>;
+    /**
+     * Return the number of vesting schedules for `recipient`.
+     * @param recipient Address of the vesting recipient.
+     * @returns Count as `bigint`.
+     */
+    getAllRecipientVestingsLength(recipient: Address): Promise<bigint>;
+    /**
+     * Slice of `getAllRecipientVestings(recipient)`, half-open `[start, end)`.
+     * See {@link getAllRecipientsSliced} for the bigint-permissiveness rationale.
+     */
+    getAllRecipientVestingsSliced(recipient: Address, start: bigint | number, end: bigint | number): Promise<readonly VestingId[]>;
+    /**
+     * Return the pending transfer details for a vesting schedule.
+     * @param vestingId The `bytes32` vesting schedule ID.
+     * @returns `{ newRecipient, initiatedAt, expiresAt }` — all zero if no transfer is pending.
+     */
+    getPendingVestingTransfer(vestingId: VestingId): Promise<PendingTransfer>;
+    /**
+     * Read-only preflight for {@link claim}. Runs the deterministic-from-off-chain
+     * checks in parallel and reports any blockers as typed {@link TokenOpsSdkError}s.
+     * Returns `{ ready: true, blockers: [] }` when the claim is safe to submit.
+     *
+     * Preflight is **opt-in**. Consumers who have already validated state can
+     * skip this call and invoke `claim` directly — they'll receive the same
+     * typed errors at write time via the revert mapper.
+     *
+     * Checks performed (all read-only, no gas):
+     * - Recipient match: `vestingInfo.recipient === caller`.
+     * - Schedule exists: `getVestingInfo` returns a non-zero startTimestamp.
+     * - Timelock elapsed: `block.timestamp ≥ startTimestamp + timelock`.
+     * - Manager is not paused (only when the clone has pause enabled).
+     * - ETH balance covers the gas fee (only when `feeType === FeeType.Gas`).
+     *
+     * Stochastic failures (FHE handle invalidation between read and write, ACL
+     * race conditions) cannot be detected off-chain and still surface as
+     * typed errors via the revert mapper.
+     *
+     * @returns `{ ready, blockers }` — same `code` shape as the write would throw.
+     */
+    preflightClaim(args: {
+        vestingId: Hex;
+        caller: Address;
+    }): Promise<PreflightResult>;
+    /**
+     * Get the vested amount at a given timestamp as an encrypted handle.
+     *
+     * Submits a transaction that calls `FHE.allow(handle, msg.sender)` — the handle
+     * is extracted from the receipt's ACL `Allowed` event, not from simulation. Pass
+     * `handle` to the Zama relayer's `userDecrypt` to obtain the plaintext.
+     *
+     * @param args.timestamp Unix timestamp to evaluate vesting at (use `Date.now() / 1000` for current).
+     * @returns `{ handle, hash }` — `handle` is a `euint128` granted to the caller.
+     */
+    getVestedAmount(args: {
+        vestingId: VestingId;
+        timestamp: number;
+        account?: Account | Address | undefined;
+    }): Promise<EncryptedViewResult>;
+    /**
+     * Get the currently claimable token amount as an encrypted handle.
+     *
+     * Like all encrypted view methods, this submits a transaction. Pass `handle`
+     * to the Zama relayer's `userDecrypt` to obtain the plaintext.
+     *
+     * @returns `{ handle, hash }` — `handle` is a `euint128` granted to the caller.
+     */
+    getClaimableAmount(args: {
+        vestingId: VestingId;
+        account?: Account | Address | undefined;
+    }): Promise<EncryptedViewResult>;
+    getTotalAllocation(args: {
+        vestingId: VestingId;
+        account?: Account | Address | undefined;
+    }): Promise<EncryptedViewResult>;
+    getSettledAmount(args: {
+        vestingId: VestingId;
+        account?: Account | Address | undefined;
+    }): Promise<EncryptedViewResult>;
+    adminGetVestedAmount(args: {
+        vestingId: VestingId;
+        timestamp: number;
+        account?: Account | Address | undefined;
+    }): Promise<EncryptedViewResult>;
+    adminGetClaimableAmount(args: {
+        vestingId: VestingId;
+        account?: Account | Address | undefined;
+    }): Promise<EncryptedViewResult>;
+    adminGetTotalAllocation(args: {
+        vestingId: VestingId;
+        account?: Account | Address | undefined;
+    }): Promise<EncryptedViewResult>;
+    adminGetSettledAmount(args: {
+        vestingId: VestingId;
+        account?: Account | Address | undefined;
+    }): Promise<EncryptedViewResult>;
+    adminGetTokenBalance(args?: {
+        account?: Account | Address;
+    }): Promise<EncryptedViewResult>;
+    /**
+     * Create a single vesting schedule. The SDK encrypts `amount` into an
+     * `externalEuint64` and submits it as the input proof — callers pass plaintext.
+     *
+     * Pass `encryptedInput` to bypass the encryptor when you manage encryption yourself.
+     *
+     * @returns Transaction hash. Parse the `VestingCreated` event to extract the `vestingId`.
+     * @example
+     * const hash = await manager.createVesting({
+     *   params: { recipient, startTimestamp, endTimestamp, cliffSeconds: 0,
+     *             releaseIntervalSecs: 86400, timelockSeconds: 0,
+     *             initialUnlockBps: 0, cliffAmountBps: 0, isRevocable: false },
+     *   amount: 1_000_000n,
+     * });
+     */
+    createVesting(args: CreateVestingArgs): Promise<Hex>;
+    /**
+     * Batch-create vesting schedules. All amounts are encrypted together under a
+     * single input proof, saving gas vs. multiple `createVesting` calls.
+     *
+     * Respects `maxBatchSize` — check before calling on large lists.
+     *
+     * @returns Transaction hash.
+     */
+    batchCreateVesting(args: BatchCreateVestingArgs): Promise<Hex>;
+    /**
+     * Claim all currently vested tokens for `vestingId`.
+     * For `FeeType.Gas` managers, pass `value` (gas fee in wei from `getFeeInfo()`).
+     * @param args Discriminated by `feeType`: pass `{ feeType, vestingId, value }` for Gas, `{ feeType, vestingId }` for DistributionToken.
+     * @returns Transaction hash.
+     * @example
+     * const { feeType, fee } = await manager.getFeeInfo();
+     * const hash = await manager.claim(
+     *   feeType === FeeType.Gas ? { feeType, vestingId, value: fee } : { feeType, vestingId },
+     * );
+     */
+    claim(args: ClaimArgs): Promise<Hex>;
+    /**
+     * Admin variant of `claim` — callable by the manager admin on behalf of any recipient.
+     * Useful for gas-sponsored claim flows. Same fee rules as `claim`.
+     * @param args Same discriminated union as `claim`.
+     * @returns Transaction hash.
+     */
+    adminClaim(args: ClaimArgs): Promise<Hex>;
+    /**
+     * Claim a specific encrypted amount from a vesting schedule rather than the full claimable balance.
+     * The SDK encrypts `amount` — pass plaintext. Alternatively pass `encryptedInput` to bypass encryption.
+     * @param args Includes `vestingId`, `amount` or `encryptedInput`, and optional `value` for Gas-fee managers.
+     * @returns Transaction hash.
+     */
+    partialClaim(args: PartialClaimArgs): Promise<Hex>;
+    /**
+     * Admin variant of `partialClaim` — callable by the manager admin on behalf of any recipient.
+     * @param args Same as `partialClaim`.
+     * @returns Transaction hash.
+     */
+    adminPartialClaim(args: PartialClaimArgs): Promise<Hex>;
+    /**
+     * Revoke a vesting schedule. Callable only when the schedule was created with `isRevocable: true`.
+     * The unvested remainder is returned to the manager admin.
+     * @param vestingId The `bytes32` vesting schedule ID to revoke.
+     * @returns Transaction hash.
+     */
+    revokeVesting(vestingId: Hex, account?: Account | Address): Promise<Hex>;
+    /**
+     * Revoke multiple vesting schedules in one transaction. Respects `maxRevokeBatchSize`.
+     * @param vestingIds Array of `bytes32` vesting schedule IDs to revoke.
+     * @returns Transaction hash.
+     */
+    batchRevokeVesting(vestingIds: readonly Hex[], account?: Account | Address): Promise<Hex>;
+    /**
+     * Split a vesting into two positions.
+     *
+     * The `numerator/denominator` ratio is auto-scaled via `scaleRatio` to the
+     * universal split constant `FHE_SPLIT_DENOMINATOR` (`90_090_000` =
+     * LCM(1..16, 10_000)) unless `args.preScaled` is set. Every confidential
+     * split lands on the same plaintext denominator so the constant itself
+     * leaks no information about the split's shape; only the encrypted
+     * numerator carries the share. `90_090_000` is well above the contract's
+     * `MIN_SPLIT_DENOMINATOR` (10_000) floor. The SDK encrypts `numerator` —
+     * pass plaintext.
+     *
+     * Two natural input shapes both produce exact integer numerators against
+     * the universal denominator:
+     * - `n/m` with `m ∈ 1..16` (halves, thirds, …, sixteenths)
+     * - `bps/10_000` (basis points)
+     *
+     * Use the {@link share} builder to construct them without manual math:
+     * `share.fraction(1, 7)` or `share.basisPoints(250)` → pass the returned
+     * `{ numerator, denominator }` with `preScaled: true`.
+     *
+     * @param args.numerator Plaintext share numerator (kept confidential on-chain).
+     * @param args.denominator Plaintext denominator — auto-scaled to 90_090_000.
+     * @param args.newRecipient Recipient address for the split-off position.
+     * @returns `{ hash, newVestingId }` — the receipt-derived id of the
+     *          newly-created vesting position, required for any follow-up call
+     *          (claim, transfer, disclose) on the split-off position.
+     * @example
+     * const { newVestingId } = await manager.splitVesting({
+     *   vestingId,
+     *   numerator: 1n, denominator: 2n,   // 50% split; SDK scales to 45_045_000 / 90_090_000
+     *   newRecipient: "0xNewRecipient",
+     * });
+     *
+     * @example
+     * // Basis-point style via the guided builder:
+     * const ratio = share.basisPoints(250);    // 2.5%
+     * const { newVestingId } = await manager.splitVesting({
+     *   vestingId,
+     *   numerator: ratio.numerator,
+     *   denominator: ratio.denominator,
+     *   preScaled: true,
+     *   newRecipient: "0xNewRecipient",
+     * });
+     */
+    splitVesting(args: SplitVestingArgs): Promise<SplitVestingResult>;
+    /**
+     * Initiate a vesting schedule transfer to a new recipient.
+     * The new recipient has `transferDurationSeconds` to accept before the offer expires.
+     * @param args `{ vestingId, newRecipient, transferDurationSeconds }`.
+     * @returns Transaction hash.
+     */
+    initiateVestingTransfer(args: InitiateTransferArgs): Promise<Hex>;
+    /**
+     * Accept a pending vesting transfer. Called by the `newRecipient` named in `initiateVestingTransfer`.
+     * @param vestingId The `bytes32` vesting schedule ID being transferred.
+     * @returns Transaction hash.
+     */
+    acceptVestingTransfer(vestingId: Hex, account?: Account | Address): Promise<Hex>;
+    /**
+     * Cancel a pending vesting transfer. Callable by either the original or new recipient.
+     * @param vestingId The `bytes32` vesting schedule ID with a pending transfer.
+     * @returns Transaction hash.
+     */
+    cancelVestingTransfer(vestingId: Hex, account?: Account | Address): Promise<Hex>;
+    /**
+     * Transfer ownership of a vesting schedule directly to `newOwner` without a time-locked acceptance window.
+     * Callable only by the manager admin.
+     * @param vestingId The `bytes32` vesting schedule ID to transfer.
+     * @param newOwner Address that will become the new recipient.
+     * @returns Transaction hash.
+     */
+    directVestingTransfer(vestingId: VestingId, newOwner: Address, account?: Account | Address): Promise<Hex>;
+    /**
+     * Disclose a single vesting amount to `party`, granting them persistent FHE
+     * ACL on the corresponding `euint128` handle. The handle is parsed from the
+     * `AmountDisclosed` event filtered by the indexed
+     * `(vestingId, discloser=caller, party)` tuple — exactly one match expected.
+     *
+     * @returns `{ hash, handle }` — pass `handle` to the Zama relayer's
+     *          `userDecrypt` (from the `party` side) to obtain the plaintext.
+     */
+    discloseToParty(args: DiscloseArgs): Promise<DiscloseToPartyResult>;
+    /**
+     * Disclose multiple vesting amounts to one `party` in a single tx. Handles
+     * are parsed from the matching `AmountDisclosed` events and returned in the
+     * same order as `args.vestingIds` (one handle per input id).
+     *
+     * @returns `{ hash, handles }` — `handles[i]` corresponds to `vestingIds[i]`.
+     */
+    batchDiscloseToParty(args: {
+        vestingIds: readonly VestingId[];
+        disclosureTypes: readonly DisclosureType[];
+        party: Address;
+        account?: Account | Address;
+    }): Promise<BatchDiscloseToPartyResult>;
+    /**
+     * Admin-only counterpart to {@link discloseToParty}. Same receipt-parsing
+     * semantics — returns the granted `euint128` handle from the
+     * `AmountDisclosed` event.
+     */
+    adminDiscloseToParty(args: DiscloseArgs): Promise<DiscloseToPartyResult>;
+    /**
+     * Admin-only counterpart to {@link batchDiscloseToParty}. Same return shape.
+     */
+    adminBatchDiscloseToParty(args: {
+        vestingIds: readonly VestingId[];
+        disclosureTypes: readonly DisclosureType[];
+        party: Address;
+        account?: Account | Address;
+    }): Promise<BatchDiscloseToPartyResult>;
+    /**
+     * Grant `party` persistent FHE ACL on an already-obtained encrypted handle.
+     * Use this when you hold a handle from a previous call and want to share it with another address.
+     * @param handle The `euint128` encrypted handle to disclose.
+     * @param party Address to grant ACL on the handle.
+     * @returns Transaction hash.
+     */
+    discloseHandleToParty(handle: EncryptedHandle, party: Address, account?: Account | Address): Promise<TxHash>;
+    /**
+     * Grant `party` persistent FHE ACL on multiple encrypted handles in one transaction.
+     * @param handles Array of `euint128` handles to disclose.
+     * @param party Address to grant ACL on all handles.
+     * @returns Transaction hash.
+     */
+    batchDiscloseHandlesToParty(handles: readonly EncryptedHandle[], party: Address, account?: Account | Address): Promise<TxHash>;
+    /**
+     * Withdraw a confidential token amount from the manager's balance back to the admin.
+     * The SDK encrypts `amount` — pass plaintext. Alternatively pass `encryptedInput`.
+     * @param args `{ amount }` (plaintext, SDK encrypts) or `{ encryptedInput }` (pre-encrypted).
+     * @returns Transaction hash.
+     */
+    withdrawAdmin(args: {
+        /** Plaintext amount. Mutually exclusive with `encryptedInput`. */
+        amount?: bigint;
+        encryptor?: Encryptor;
+        /** Pre-encrypted input. Mutually exclusive with `amount`. */
+        encryptedInput?: EncryptedInput;
+        account?: Account | Address;
+    }): Promise<Hex>;
+    /**
+     * Recover a plain ERC-20 token accidentally sent to this manager. Admin only.
+     * @param token ERC-20 token address to recover.
+     * @param to Recipient address for the recovered tokens.
+     * @returns Transaction hash.
+     */
+    withdrawOtherToken(token: Address, to: Address, account?: Account | Address): Promise<TxHash>;
+    /**
+     * Recover a confidential ERC-7984 token accidentally sent to this manager. Admin only.
+     * @param token ERC-7984 token address to recover.
+     * @param to Recipient address for the recovered tokens.
+     * @returns Transaction hash.
+     */
+    withdrawOtherConfidentialToken(token: Address, to: Address, account?: Account | Address): Promise<TxHash>;
+    /**
+     * Withdraw accumulated ETH gas fees from the manager to `to`. Admin only.
+     * @param to Recipient address.
+     * @param amount Amount in wei.
+     * @returns Transaction hash.
+     */
+    withdrawGasFee(to: Address, amount: bigint, account?: Account | Address): Promise<TxHash>;
+    /**
+     * Withdraw accumulated token fees from a `FeeType.DistributionToken` manager. Admin only.
+     * The SDK encrypts `amount` — pass plaintext. Alternatively pass `encryptedInput`.
+     * @param args `{ to, amount }` (plaintext, SDK encrypts) or `{ to, encryptedInput }` (pre-encrypted).
+     * @returns Transaction hash.
+     */
+    withdrawTokenFee(args: {
+        to: Address;
+        /** Plaintext amount. Mutually exclusive with `encryptedInput`. */
+        amount?: bigint;
+        encryptor?: Encryptor;
+        /** Pre-encrypted input. Mutually exclusive with `amount`. */
+        encryptedInput?: EncryptedInput;
+        account?: Account | Address;
+    }): Promise<Hex>;
+    /**
+     * Update the maximum number of vestings allowed in a single `batchCreateVesting` call. Admin only.
+     * @param newMax New batch size limit.
+     * @returns Transaction hash.
+     */
+    setMaxBatchSize(newMax: bigint, account?: Account | Address): Promise<TxHash>;
+    /**
+     * Update the maximum number of vestings allowed in a single `batchRevokeVesting` call. Admin only.
+     * @param newMax New revoke batch size limit.
+     * @returns Transaction hash.
+     */
+    setMaxRevokeBatchSize(newMax: bigint | number, account?: Account | Address): Promise<TxHash>;
+    /**
+     * Transfer the fee-collector role to a new address. Callable by the current fee collector.
+     * @param newCollector Address to assign the fee-collector role.
+     * @returns Transaction hash.
+     */
+    transferFeeCollectorRole(newCollector: Address, account?: Account | Address): Promise<TxHash>;
+    /**
+     * Pause the manager, blocking all claim operations. Requires `isPausable() === true`. PAUSER_ROLE only.
+     * @returns Transaction hash.
+     */
+    pause(account?: Account | Address): Promise<TxHash>;
+    /**
+     * Resume a paused manager, re-enabling claim operations. PAUSER_ROLE only.
+     * @returns Transaction hash.
+     */
+    unpause(account?: Account | Address): Promise<TxHash>;
+    /**
+     * Check whether `account` holds `role` on this manager.
+     * @param role `bytes32` role identifier — use the `roleConstants()` helper or the SDK's exported role constants.
+     * @param account Address to check.
+     * @returns `true` if the account holds the role.
+     */
+    hasRole(role: Role, account: Address): Promise<boolean>;
+    /**
+     * Grant `role` to `accountTarget`. Requires DEFAULT_ADMIN_ROLE.
+     * @param role `bytes32` role identifier.
+     * @param accountTarget Address to grant the role to.
+     * @returns Transaction hash.
+     */
+    grantRole(role: Role, accountTarget: Address, account?: Account | Address): Promise<TxHash>;
+    /**
+     * Revoke `role` from `accountTarget`. Requires DEFAULT_ADMIN_ROLE.
+     * @param role `bytes32` role identifier.
+     * @param accountTarget Address to revoke the role from.
+     * @returns Transaction hash.
+     */
+    revokeRole(role: Role, accountTarget: Address, account?: Account | Address): Promise<TxHash>;
+    /**
+     * Renounce a role held by the caller. `callerConfirm` must equal `msg.sender` (OpenZeppelin guard).
+     * @param role `bytes32` role identifier to renounce.
+     * @param callerConfirm Must equal the calling account address.
+     * @returns Transaction hash.
+     */
+    renounceRole(role: Role, callerConfirm: Address, account?: Account | Address): Promise<TxHash>;
+    /**
+     * Read all role identifiers from the contract in one multicall.
+     * @returns Object mapping role name to its `bytes32` identifier.
+     * @example
+     * const { VESTING_CREATOR_ROLE } = await manager.roleConstants();
+     * await manager.grantRole(VESTING_CREATOR_ROLE, creatorAddress);
+     */
+    roleConstants(): Promise<{
+        DEFAULT_ADMIN_ROLE: Role;
+        VESTING_CREATOR_ROLE: Role;
+        REVOKER_ROLE: Role;
+        WITHDRAWER_ROLE: Role;
+        CLAIMER_ROLE: Role;
+        FEE_COLLECTOR_ROLE: Role;
+        PAUSER_ROLE: Role;
+        DISCLOSURE_ADMIN_ROLE: Role;
+    }>;
+}
+/**
+ * Create a {@link ConfidentialVestingManagerClient}. Mirrors viem's `create*` convention.
+ *
+ * @example
+ * const manager = createConfidentialVestingManagerClient({
+ *   publicClient, walletClient,
+ *   address: "0xYourManagerClone",
+ *   encryptor,
+ * });
+ */
+export declare function createConfidentialVestingManagerClient(config: ConfidentialVestingManagerClientConfig): ConfidentialVestingManagerClient;