@tokenops/sdk 1.0.0

package/dist/fhe/operators.d.ts

@@ -0,0 +1,190 @@
+import type { Account, Address, Hex, PublicClient, WalletClient } from "viem";
+import { type SdkTelemetry } from "../core/telemetry.js";
+/**
+ * Minimal `setOperator` ABI fragment. Embedded inline (rather than imported
+ * from a shared mock-token ABI) because every ERC-7984-conformant token —
+ * production or mock — exposes this exact 4-byte selector. No artifact
+ * dependency.
+ *
+ * The contract signature is:
+ *
+ * ```solidity
+ * function setOperator(address operator, uint48 until) external;
+ * ```
+ *
+ * `uint48` upper bound (`2**48 - 1 ≈ 8.9e+14`) is comfortably past year 9999
+ * in unix seconds, so a "far-future" deadline is structurally safe.
+ */
+export declare const ERC7984_SET_OPERATOR_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "setOperator";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "operator";
+        readonly type: "address";
+    }, {
+        readonly name: "until";
+        readonly type: "uint48";
+    }];
+    readonly outputs: readonly [];
+}];
+/**
+ * Far-future `uint48` deadline. The on-chain `until` parameter is a `uint48`
+ * unix timestamp; this constant is the maximum value the type can hold
+ * (`2**48 - 1`). Use as the default deadline when a consumer doesn't care
+ * about expiry — typical for local-chain dev loops and end-to-end fixture
+ * setup. For production flows, scope the deadline to the expected operation
+ * window (e.g. `Date.now()/1000 + 3600`).
+ */
+export declare const ERC7984_OPERATOR_MAX_DEADLINE: bigint;
+export interface SetOperatorArgs {
+    /** Read-only viem client for receipt waiting. */
+    publicClient: PublicClient;
+    /** Wallet client used to send the `setOperator` call. */
+    walletClient: WalletClient;
+    /**
+     * Account that owns the tokens being authorized. Pass an `Address` (looked
+     * up on `walletClient`) when the wallet has multiple accounts, or omit and
+     * the wallet's default account is used.
+     */
+    /**
+     * Account that owns the tokens being authorized. Accepts either a full
+     * viem `Account` object (e.g. from `privateKeyToAccount`) or an `Address`
+     * string. Mirrors `CreateVestingArgsCommon.account` and viem's own
+     * `writeContract` flexibility.
+     *
+     * Fallback hierarchy when this arg is omitted:
+     *   1. `walletClient.account` — the full account object the wallet was
+     *      built with (preferred — viem signs locally → `eth_sendRawTransaction`).
+     *   2. throws `TokenOpsContractError` — no signer available.
+     *
+     * **Why `Account | Address` and not just `Address`:**
+     * viem's `writeContract` calls `eth_sendTransaction` (custodial-wallet path,
+     * rejected by Alchemy / Infura / public RPCs) when handed a string address,
+     * and `eth_sendRawTransaction` (local-signing path) when handed an `Account`
+     * object with a `signTransaction` method. Pass the full object you got from
+     * `privateKeyToAccount` to get local signing; pass an address only when the
+     * wallet has multiple custodial accounts and you want to pick one by name.
+     */
+    account?: Account | Address;
+    /** ERC-7984 token contract address. */
+    token: Address;
+    /**
+     * Address being authorized to pull tokens — typically a manager clone
+     * (`/fhe-vesting`), an airdrop clone (`/fhe-airdrop`), or the disperse
+     * singleton (`/fhe-disperse`).
+     */
+    spender: Address;
+    /**
+     * `uint48` unix timestamp after which the operator authorization expires.
+     * Defaults to {@link ERC7984_OPERATOR_MAX_DEADLINE} ("forever" within
+     * `uint48`).
+     */
+    deadline?: bigint;
+    /**
+     * If `true` (default), waits for the transaction to be mined before
+     * returning. Set to `false` for fire-and-forget flows where the caller
+     * waits separately.
+     */
+    waitForReceipt?: boolean;
+    /** Optional telemetry sink — span emits as `fhe.setOperator`. */
+    telemetry?: SdkTelemetry;
+}
+/**
+ * Authorize `spender` to pull ERC-7984 tokens from `account` until
+ * `deadline`. Required pre-step before any `/fhe-vesting`, `/fhe-airdrop`,
+ * or `/fhe-disperse` flow that takes funds from the operator's balance.
+ *
+ * Resolves to the transaction hash. Waits for the transaction to be mined
+ * by default (`waitForReceipt: true`) — the receipt is the strongest
+ * "operator is now authorized" signal a consumer can build the next call on
+ * top of. Pass `waitForReceipt: false` if your call site manages receipt
+ * polling itself.
+ *
+ * @example
+ * ```ts
+ * import { setOperator, ERC7984_OPERATOR_MAX_DEADLINE } from "@tokenops/sdk/fhe";
+ *
+ * await setOperator({
+ *   publicClient,
+ *   walletClient,
+ *   token: DEPLOYED_ADDRESSES.tokens.testConfidential[31337]!,
+ *   spender: manager,
+ *   // deadline defaults to ERC7984_OPERATOR_MAX_DEADLINE (forever).
+ * });
+ *
+ * // Now safe to call manager.createVesting / factory.fundConfidentialAirdrop / etc.
+ * ```
+ *
+ * @throws {@link TokenOpsContractError} if the writeContract or receipt-wait
+ *   step throws. The original viem error is attached as the cause.
+ */
+export declare function setOperator(args: SetOperatorArgs): Promise<Hex>;
+/**
+ * Arguments for {@link revokeOperator}. Identical to {@link SetOperatorArgs}
+ * minus the `deadline` field — revoke is a fixed `until=0` call that cannot
+ * accept a non-zero deadline (the ERC-7984 contract treats `0` as the revoke
+ * convention; any non-zero `until` would be a re-grant, not a revoke).
+ */
+export interface RevokeOperatorArgs {
+    /** Read-only viem client for receipt waiting. */
+    publicClient: PublicClient;
+    /** Wallet client used to send the `setOperator(..., 0)` call. */
+    walletClient: WalletClient;
+    /**
+     * Account that owns the tokens. Same fallback hierarchy as
+     * {@link SetOperatorArgs} — preserves the `Account` object when present so
+     * viem signs locally via `eth_sendRawTransaction` rather than the
+     * custodial `eth_sendTransaction` path that public RPCs reject.
+     */
+    account?: Account | Address;
+    /** ERC-7984 token contract address. */
+    token: Address;
+    /**
+     * Address whose operator authorization should be revoked — typically a
+     * stale manager clone (`/fhe-vesting`), a closed airdrop clone
+     * (`/fhe-airdrop`), or a singleton no longer in use (`/fhe-disperse`).
+     */
+    spender: Address;
+    /**
+     * If `true` (default), waits for the transaction to be mined before
+     * returning. Set to `false` for fire-and-forget flows where the caller
+     * waits separately.
+     */
+    waitForReceipt?: boolean;
+    /** Optional telemetry sink — span emits as `fhe.revokeOperator`. */
+    telemetry?: SdkTelemetry;
+}
+/**
+ * Revoke a previously granted ERC-7984 operator authorization. Calls
+ * `token.setOperator(spender, 0)` — the ERC-7984 convention where `until=0`
+ * means "no future authorization" (the on-chain timestamp check `until >=
+ * block.timestamp` fails immediately).
+ *
+ * **When to use this.** Any `setOperator` flow leaves the spender authorized
+ * for the deadline window. The default deadline is
+ * {@link ERC7984_OPERATOR_MAX_DEADLINE} (uint48 max ≈ year 8.9e+14) — useful
+ * for local-chain dev loops, hostile for production deployments where a
+ * stale manager clone (replaced by a new one) would otherwise keep operator
+ * rights forever. R19 evm-audit M-3: the original `setOperator` shipped
+ * without a revoke sibling, forcing consumers to hand-roll
+ * `walletClient.writeContract({ ..., args: [spender, 0] })`.
+ *
+ * @example
+ * ```ts
+ * import { revokeOperator } from "@tokenops/sdk/fhe";
+ *
+ * await revokeOperator({
+ *   publicClient,
+ *   walletClient,
+ *   token: DEPLOYED_ADDRESSES.tokens.testConfidential[31337]!,
+ *   spender: staleManager, // old manager clone after deploying a new one
+ * });
+ * // `staleManager` can no longer call `confidentialTransferFrom` against
+ * // the caller's balance.
+ * ```
+ *
+ * @throws {@link TokenOpsContractError} if the writeContract or receipt-wait
+ *   step throws. The original viem error is attached as the cause.
+ */
+export declare function revokeOperator(args: RevokeOperatorArgs): Promise<Hex>;

package/dist/fhe/react/index.cjs

@@ -0,0 +1,102 @@
+'use strict';
+
+require('../../chunk-66IHPTOK.cjs');
+var chunk56UI7LUR_cjs = require('../../chunk-56UI7LUR.cjs');
+var react = require('react');
+
+function resolveUserDecryptor(source) {
+  if (source === void 0) return void 0;
+  return typeof source === "function" ? source() : source;
+}
+function useDecryptedHandle(opts) {
+  const [state, setState] = react.useState({
+    status: "idle",
+    value: void 0,
+    error: void 0
+  });
+  const decryptorSourceRef = react.useRef(opts.userDecryptor);
+  decryptorSourceRef.current = opts.userDecryptor;
+  const { handle, contractAddress, relayerParams, enabled } = opts;
+  const enabledNorm = enabled !== false;
+  const handleStr = handle;
+  const contractStr = contractAddress;
+  const relayerKey = relayerParams ? JSON.stringify(serializableSlice(relayerParams)) : "";
+  react.useEffect(() => {
+    if (!enabledNorm) {
+      setState({ status: "idle", value: void 0, error: void 0 });
+      return;
+    }
+    if (!handleStr || !contractStr) {
+      setState({ status: "idle", value: void 0, error: void 0 });
+      return;
+    }
+    const userDecryptor = resolveUserDecryptor(decryptorSourceRef.current);
+    if (!userDecryptor) {
+      setState({
+        status: "error",
+        value: void 0,
+        error: new chunk56UI7LUR_cjs.TokenOpsValidationError(
+          "useDecryptedHandle: no `userDecryptor` resolved \u2014 pass `userDecryptor: () => useZamaSDK().relayer` (or an eager RelayerSDK / MockFhevmInstance).",
+          { method: "useDecryptedHandle" }
+        )
+      });
+      return;
+    }
+    let cancelled = false;
+    setState({ status: "loading", value: void 0, error: void 0 });
+    void (async () => {
+      try {
+        const result = await userDecryptor.userDecrypt({
+          handleContractPairs: [{ handle: handleStr, contractAddress: contractStr }],
+          ...relayerParams ?? {}
+        });
+        const plain = result[handleStr];
+        if (plain === void 0) {
+          throw new chunk56UI7LUR_cjs.TokenOpsValidationError(
+            `useDecryptedHandle: relayer returned no value for handle ${handleStr} on contract ${contractStr} \u2014 check ACL grant + (handle, contractAddress, userAddress) triple`,
+            { method: "useDecryptedHandle", contractAddress: contractStr }
+          );
+        }
+        const value = typeof plain === "bigint" ? plain : BigInt(plain);
+        if (!cancelled) setState({ status: "success", value, error: void 0 });
+      } catch (err) {
+        if (!cancelled) {
+          const error = err instanceof Error ? err : new Error(String(err));
+          setState({ status: "error", value: void 0, error });
+        }
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [enabledNorm, handleStr, contractStr, relayerKey]);
+  return state;
+}
+function serializableSlice(v) {
+  const out = {};
+  for (const k of Object.keys(v)) {
+    const val = v[k];
+    if (val === void 0) continue;
+    if (typeof val === "function" || typeof val === "symbol") continue;
+    out[k] = typeof val === "bigint" ? val.toString() : val;
+  }
+  return out;
+}
+
+Object.defineProperty(exports, "TokenOpsContractError", {
+  enumerable: true,
+  get: function () { return chunk56UI7LUR_cjs.TokenOpsContractError; }
+});
+Object.defineProperty(exports, "TokenOpsSdkError", {
+  enumerable: true,
+  get: function () { return chunk56UI7LUR_cjs.TokenOpsSdkError; }
+});
+Object.defineProperty(exports, "TokenOpsValidationError", {
+  enumerable: true,
+  get: function () { return chunk56UI7LUR_cjs.TokenOpsValidationError; }
+});
+Object.defineProperty(exports, "isTokenOpsSdkError", {
+  enumerable: true,
+  get: function () { return chunk56UI7LUR_cjs.isTokenOpsSdkError; }
+});
+exports.useDecryptedHandle = useDecryptedHandle;

package/dist/fhe/react/index.d.cts

@@ -0,0 +1,10 @@
+/**
+ * Cross-product React hooks living in the `@tokenops/sdk/fhe/react` subpath.
+ *
+ * Per-product React hooks (`useCreateVesting`, `useDisperse`, etc.) live in
+ * each product's `src/<product>/react/` barrel. This barrel hosts hooks that
+ * span products — e.g. `useDecryptedHandle` (works on any product's
+ * `EncryptedHandle` return value).
+ */
+export { useDecryptedHandle, type UseDecryptedHandleOptions, type UseDecryptedHandleResult, type UserDecryptor, type UserDecryptorSource, } from "./use-decrypted-handle.js";
+export { TokenOpsSdkError, isTokenOpsSdkError, TokenOpsValidationError, TokenOpsContractError, } from "../../core/errors.js";

package/dist/fhe/react/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Cross-product React hooks living in the `@tokenops/sdk/fhe/react` subpath.
+ *
+ * Per-product React hooks (`useCreateVesting`, `useDisperse`, etc.) live in
+ * each product's `src/<product>/react/` barrel. This barrel hosts hooks that
+ * span products — e.g. `useDecryptedHandle` (works on any product's
+ * `EncryptedHandle` return value).
+ */
+export { useDecryptedHandle, type UseDecryptedHandleOptions, type UseDecryptedHandleResult, type UserDecryptor, type UserDecryptorSource, } from "./use-decrypted-handle.js";
+export { TokenOpsSdkError, isTokenOpsSdkError, TokenOpsValidationError, TokenOpsContractError, } from "../../core/errors.js";

package/dist/fhe/react/index.js

@@ -0,0 +1,85 @@
+import '../../chunk-KWFFIJYX.js';
+import { TokenOpsValidationError } from '../../chunk-IVE3QEGD.js';
+export { TokenOpsContractError, TokenOpsSdkError, TokenOpsValidationError, isTokenOpsSdkError } from '../../chunk-IVE3QEGD.js';
+import { useState, useRef, useEffect } from 'react';
+
+function resolveUserDecryptor(source) {
+  if (source === void 0) return void 0;
+  return typeof source === "function" ? source() : source;
+}
+function useDecryptedHandle(opts) {
+  const [state, setState] = useState({
+    status: "idle",
+    value: void 0,
+    error: void 0
+  });
+  const decryptorSourceRef = useRef(opts.userDecryptor);
+  decryptorSourceRef.current = opts.userDecryptor;
+  const { handle, contractAddress, relayerParams, enabled } = opts;
+  const enabledNorm = enabled !== false;
+  const handleStr = handle;
+  const contractStr = contractAddress;
+  const relayerKey = relayerParams ? JSON.stringify(serializableSlice(relayerParams)) : "";
+  useEffect(() => {
+    if (!enabledNorm) {
+      setState({ status: "idle", value: void 0, error: void 0 });
+      return;
+    }
+    if (!handleStr || !contractStr) {
+      setState({ status: "idle", value: void 0, error: void 0 });
+      return;
+    }
+    const userDecryptor = resolveUserDecryptor(decryptorSourceRef.current);
+    if (!userDecryptor) {
+      setState({
+        status: "error",
+        value: void 0,
+        error: new TokenOpsValidationError(
+          "useDecryptedHandle: no `userDecryptor` resolved \u2014 pass `userDecryptor: () => useZamaSDK().relayer` (or an eager RelayerSDK / MockFhevmInstance).",
+          { method: "useDecryptedHandle" }
+        )
+      });
+      return;
+    }
+    let cancelled = false;
+    setState({ status: "loading", value: void 0, error: void 0 });
+    void (async () => {
+      try {
+        const result = await userDecryptor.userDecrypt({
+          handleContractPairs: [{ handle: handleStr, contractAddress: contractStr }],
+          ...relayerParams ?? {}
+        });
+        const plain = result[handleStr];
+        if (plain === void 0) {
+          throw new TokenOpsValidationError(
+            `useDecryptedHandle: relayer returned no value for handle ${handleStr} on contract ${contractStr} \u2014 check ACL grant + (handle, contractAddress, userAddress) triple`,
+            { method: "useDecryptedHandle", contractAddress: contractStr }
+          );
+        }
+        const value = typeof plain === "bigint" ? plain : BigInt(plain);
+        if (!cancelled) setState({ status: "success", value, error: void 0 });
+      } catch (err) {
+        if (!cancelled) {
+          const error = err instanceof Error ? err : new Error(String(err));
+          setState({ status: "error", value: void 0, error });
+        }
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [enabledNorm, handleStr, contractStr, relayerKey]);
+  return state;
+}
+function serializableSlice(v) {
+  const out = {};
+  for (const k of Object.keys(v)) {
+    const val = v[k];
+    if (val === void 0) continue;
+    if (typeof val === "function" || typeof val === "symbol") continue;
+    out[k] = typeof val === "bigint" ? val.toString() : val;
+  }
+  return out;
+}
+
+export { useDecryptedHandle };

package/dist/fhe/react/use-decrypted-handle.d.ts

@@ -0,0 +1,102 @@
+import type { Address } from "viem";
+import { type EncryptedHandle } from "../../core/brands.js";
+/**
+ * Subset of `@zama-fhe/sdk` `RelayerSDK` we depend on for user-decryption.
+ * Declared structurally so consumers can pass any v3 RelayerSDK
+ * (`RelayerWeb`, `RelayerNode`, or a mock like `MockFhevmInstance`) without
+ * us importing the optional peer dep.
+ */
+export interface UserDecryptor {
+    userDecrypt(params: {
+        handleContractPairs: {
+            handle: string;
+            contractAddress: string;
+        }[];
+        privateKey?: unknown;
+        publicKey?: unknown;
+        signature?: unknown;
+        contractAddresses?: string[];
+        userAddress?: string;
+        requestValidity?: {
+            startTimestamp: bigint | number;
+            durationDays: bigint | number;
+        };
+        contractsChainId?: bigint | number;
+    }): Promise<Readonly<Record<string, unknown>>>;
+}
+/** Eager or lazy {@link UserDecryptor} reference — mirrors EncryptorSource. */
+export type UserDecryptorSource = UserDecryptor | (() => UserDecryptor | undefined);
+/** Options accepted by {@link useDecryptedHandle}. */
+export interface UseDecryptedHandleOptions {
+    /**
+     * The encrypted handle to decrypt. `undefined` keeps the hook in `idle`
+     * state — useful when the handle comes from a downstream query that hasn't
+     * resolved yet.
+     */
+    handle?: EncryptedHandle | undefined;
+    /**
+     * The contract that granted ACL access to the handle. The relayer enforces
+     * `(handle, contractAddress, userAddress)` triples — passing the wrong
+     * contract here returns an empty result with no diagnostic.
+     */
+    contractAddress?: Address | undefined;
+    /**
+     * Lazy or eager Zama RelayerSDK / MockFhevmInstance / RelayerWeb / RelayerNode.
+     * Recommended in React: `userDecryptor: () => useZamaSDK().relayer` — the
+     * SDK calls this per-decryption so it picks up the live RelayerSDK instance
+     * rather than a stale capture (CLAUDE.md Pitfall #3).
+     */
+    userDecryptor?: UserDecryptorSource | undefined;
+    /**
+     * Extra params passed straight through to the relayer's `userDecrypt`. The
+     * Zama `RelayerWeb` / `RelayerNode` require `privateKey`, `publicKey`,
+     * `signature`, `requestValidity`, `contractsChainId`. `MockFhevmInstance`
+     * tolerates a partial shape. Hosts that wrap their own keypair management
+     * pass the full shape here.
+     */
+    relayerParams?: Omit<Parameters<UserDecryptor["userDecrypt"]>[0], "handleContractPairs"> | undefined;
+    /**
+     * Skip the decrypt — defaults to `false`. Useful when the consumer wants
+     * to render an "Encrypted" placeholder until the user opts in.
+     */
+    enabled?: boolean | undefined;
+}
+/** Discriminated state machine for the hook's return. */
+export type UseDecryptedHandleResult = {
+    status: "idle";
+    value: undefined;
+    error: undefined;
+} | {
+    status: "loading";
+    value: undefined;
+    error: undefined;
+} | {
+    status: "success";
+    value: bigint;
+    error: undefined;
+} | {
+    status: "error";
+    value: undefined;
+    error: Error;
+};
+/**
+ * Decrypt a single `EncryptedHandle` returned by an FHE-product encrypted
+ * view (e.g. `EncryptedViewResult.handle` from
+ * `ConfidentialVestingManagerClient.getTokenBalance()`).
+ *
+ * ```ts
+ * import { useDecryptedHandle } from "@tokenops/sdk/fhe/react";
+ *
+ * const { status, value } = useDecryptedHandle({
+ *   handle: viewResult?.handle,
+ *   contractAddress: managerAddress,
+ *   userDecryptor: () => useZamaSDK().relayer,
+ *   relayerParams: { ...keypair, requestValidity, contractsChainId },
+ * });
+ * ```
+ *
+ * The relayer source resolves lazily per decrypt — the hook does NOT
+ * memoize the SDK client across renders, because user-decrypt is a one-shot
+ * action (no benefit to client caching).
+ */
+export declare function useDecryptedHandle(opts: UseDecryptedHandleOptions): UseDecryptedHandleResult;

package/dist/fhe/scale-ratio.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Fixed plaintext denominator used by every confidential split call.
+ *
+ * = LCM(1..16, 10_000) = 2⁴ × 3² × 5⁴ × 7 × 11 × 13 = 90,090,000.
+ *
+ * The denominator lives in plaintext (calldata or storage). Sizing it
+ * per-call to fit each specific split would leak the split's shape — a
+ * `1/2` split would use a different plaintext denominator than a `1/7`
+ * split, and observers could distinguish them without decrypting anything.
+ * Pinning every split to a single universal constant removes that side
+ * channel.
+ *
+ * `90_090_000` specifically is the smallest integer divisible by every
+ * common human split shape we support, in two flavours:
+ * - `n/m` with `m ∈ 1..16` (halves, thirds, …, sixteenths and their
+ *   combinations) — produces an exact integer numerator because `m`
+ *   divides `90_090_000`.
+ * - `o/10_000` (basis points, `o ∈ 0..10_000`) — produces an exact integer
+ *   numerator because `90_090_000 = 10_000 × 9_009`, so `bps` maps to
+ *   `bps × 9_009`.
+ *
+ * No rounding artifacts in either case — the denominator itself is the
+ * only signal an observer sees, and it never changes, so the leak surface
+ * is zero. Use the {@link share} builder to construct ratios from either
+ * shape ergonomically.
+ *
+ * Overflow is not a concern. The confidential-vesting contract upcasts
+ * the encrypted numerator to `euint128` before multiplying by the holder
+ * balance, so the intermediate `amount × numerator` math happens in
+ * `euint128` space (max ~3.4 × 10³⁸). For a 6-decimal ERC-7984 balance
+ * (max ~1.84 × 10¹⁹) and our denominator (~9 × 10⁷) the product tops out
+ * at ~1.7 × 10²⁷ — eleven orders of magnitude under the `euint128`
+ * ceiling. The plaintext denominator itself fits trivially in the
+ * contract's `uint128 denominator` parameter.
+ *
+ * Do NOT shrink this. All split-style SDK methods must use the same
+ * value — the leak surface is only zero when every product agrees on
+ * one constant. Today that's `fhe-vesting` `splitVesting`; future
+ * split-style surfaces (weighted disperses, weighted airdrops if added)
+ * must pin to this same constant.
+ */
+export declare const FHE_SPLIT_DENOMINATOR = 90090000n;
+/**
+ * Bit-width to validate the scaled numerator/denominator against.
+ *
+ * - `"uint64"` matches the encrypted-numerator width every confidential
+ *   split path actually uses (the SDK routes through `encryptUint64`).
+ *   Hit `splitVesting`-style call sites with this so the validator's
+ *   bound matches the encryption path's bound — same `InvalidArgumentError`
+ *   instead of a less specific `EncryptionFailedError` downstream.
+ * - `"uint128"` is the legacy default kept for non-split contract surfaces
+ *   that the helper might also serve in the future.
+ */
+export type ScaleRatioWidth = "uint64" | "uint128";
+export interface ScaledRatio {
+    numerator: bigint;
+    denominator: bigint;
+}
+export interface ScaleRatioArgs {
+    numerator: bigint;
+    denominator: bigint;
+    /**
+     * Target denominator for the scaled output. Defaults to
+     * {@link FHE_SPLIT_DENOMINATOR} (`90_090_000`) — the privacy-preserving
+     * constant every confidential split must agree on. Override only for
+     * non-split contract surfaces that have a different precision floor.
+     */
+    minDenominator?: bigint;
+    /**
+     * Bit-width the scaled values are validated against. Defaults to
+     * `"uint128"`. Pass `"uint64"` for confidential split paths whose
+     * encrypted numerator goes through `encryptUint64`, so the bound the
+     * helper reports matches the bound the encryption call would enforce.
+     */
+    width?: ScaleRatioWidth;
+}
+/**
+ * Scale a plaintext ratio so the output denominator equals the
+ * privacy-preserving split constant ({@link FHE_SPLIT_DENOMINATOR},
+ * default `90_090_000`) while keeping both values within `uint128`.
+ *
+ * For arbitrary `numerator/denominator` inputs the output is the closest
+ * exact-integer numerator under that constant — i.e. `numerator ×
+ * (90_090_000 / denominator)` when `denominator` divides `90_090_000`
+ * (every `1..16` fraction and every basis-point amount), or
+ * `ceil(90_090_000 × numerator / denominator)` for general inputs (with
+ * the denominator still pinned to `90_090_000`).
+ *
+ * Pre-scaled inputs whose denominator already matches `minDenominator`
+ * are returned unchanged; pre-scaled inputs whose denominator exceeds
+ * `minDenominator` are also returned unchanged (the caller is asking for
+ * higher precision than the standard constant, e.g. for a non-split
+ * surface).
+ *
+ * Most consumers should use {@link share} instead — its builders express
+ * the two natural shapes (`n/m`, basis points) directly and produce
+ * `ScaledRatio` outputs that are exact-integer by construction.
+ *
+ * @example
+ * scaleRatio({ numerator: 1n, denominator: 2n });
+ * // → { numerator: 45_045_000n, denominator: 90_090_000n }   // 50% of 90_090_000
+ *
+ * @example
+ * scaleRatio({ numerator: 2n, denominator: 3n });
+ * // → { numerator: 60_060_000n, denominator: 90_090_000n }   // exact: 2/3 × 90_090_000
+ */
+export declare function scaleRatio({ numerator, denominator, minDenominator, width, }: ScaleRatioArgs): ScaledRatio;
+/**
+ * Guided builders for the two split shapes the SDK supports as
+ * exact-integer numerators over {@link FHE_SPLIT_DENOMINATOR}
+ * (`90_090_000` = LCM(1..16, 10_000)).
+ *
+ * Use these when you know your split as one of:
+ * - a simple fraction `n/m` with `m ∈ 1..16` (halves, thirds, …,
+ *   sixteenths), or
+ * - a basis-point amount `bps/10_000` with `bps ∈ 0..10_000`
+ *   (1 bp = 0.01%, 100 bp = 1%, 10_000 bp = 100%).
+ *
+ * Both shapes land on `90_090_000` with no rounding artifacts. The
+ * returned `ScaledRatio` is ready to pass to split-style SDK calls with
+ * `preScaled: true` — the auto-scaling path is skipped because the math
+ * has already been done exactly.
+ *
+ * @example
+ * share.fraction(1, 3)       // → { numerator: 30_030_000n, denominator: 90_090_000n }
+ * share.basisPoints(250)     // → { numerator:  2_252_250n, denominator: 90_090_000n }  // 2.5%
+ *
+ * @example
+ * const ratio = share.basisPoints(50);  // 0.5%
+ * await manager.splitVesting({
+ *   vestingId,
+ *   numerator: ratio.numerator,
+ *   denominator: ratio.denominator,
+ *   preScaled: true,                    // skip auto-scaling; share already did it
+ *   newRecipient,
+ * });
+ */
+export declare const share: {
+    /**
+     * Build a `ScaledRatio` from a simple fraction `n/m`.
+     *
+     * - `m` must be in `1..16` — every integer in this range divides
+     *   {@link FHE_SPLIT_DENOMINATOR} cleanly, so the result is exact.
+     * - `n` must be in `0..m` — `0` is a zero-share (no-op split) and `m`
+     *   itself is the whole position.
+     *
+     * Both arguments accept `number` (must be an integer) or `bigint` —
+     * use whichever is convenient at the call site.
+     *
+     * @throws InvalidArgumentError if `m` is outside `1..16` or `n` is
+     *         outside `0..m`, or either input is a non-integer `number`.
+     */
+    readonly fraction: (numerator: number | bigint, denominator: number | bigint) => ScaledRatio;
+    /**
+     * Build a `ScaledRatio` from a basis-point amount.
+     *
+     * `bps` must be in `0..10_000` — `0` is a zero-share and `10_000` is
+     * the whole position (= 100%). `10_000` divides
+     * {@link FHE_SPLIT_DENOMINATOR} cleanly, so the result is exact:
+     * `bps × 9_009` over `90_090_000`.
+     *
+     * Accepts `number` (must be an integer) or `bigint`.
+     *
+     * @throws InvalidArgumentError if `bps` is outside `0..10_000`, or is
+     *         a non-integer `number`.
+     */
+    readonly basisPoints: (bps: number | bigint) => ScaledRatio;
+};