@tokenops/sdk 1.0.0

package/dist/chunk-QIHZVLIK.js

@@ -0,0 +1,3388 @@
+import { mapZamaError } from './chunk-ZXCOJY2Z.js';
+import { getFhevmAclAddress, requireFhevmAclAddress, ACL_ALLOWED_EVENT } from './chunk-FYQ2UW4T.js';
+import { SDK_VERSION, isContractRevert, mapContractRevert } from './chunk-JFLEEXKP.js';
+import { getFheDisperseSingletonAddress } from './chunk-COPFW5Z4.js';
+import { normaliseAddress } from './chunk-BE2AIZ3K.js';
+import { withTelemetry } from './chunk-Q2GP5UDC.js';
+import { asExternalInputProof, asEncryptedHandle } from './chunk-KWFFIJYX.js';
+import { InvalidArgumentError, TokenOpsSdkError, DeploymentAddressUnavailableError, PausedError, InsufficientFeeError, MissingEncryptorError, ReceiptEventAmbiguousError, MissingWalletClientError, MissingAccountError, BatchTooLargeError } from './chunk-IVE3QEGD.js';
+import { bytesToHex, keccak256, encodePacked, parseEventLogs, isAddress, getCreate2Address } from 'viem';
+
+// src/fhe-disperse/abis/singleton.ts
+var disperseConfidentialAbi = [
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "admin_",
+        type: "address"
+      },
+      {
+        internalType: "address",
+        name: "feeCollector_",
+        type: "address"
+      },
+      {
+        components: [
+          {
+            internalType: "bool",
+            name: "gasFeeEnabled",
+            type: "bool"
+          },
+          {
+            internalType: "bool",
+            name: "tokenFeeEnabled",
+            type: "bool"
+          },
+          {
+            internalType: "uint96",
+            name: "defaultGasFee",
+            type: "uint96"
+          },
+          {
+            internalType: "uint16",
+            name: "defaultTokenFee",
+            type: "uint16"
+          }
+        ],
+        internalType: "struct IDisperseConfidential.FeeConfig",
+        name: "config_",
+        type: "tuple"
+      },
+      {
+        internalType: "uint256",
+        name: "maxBatchSizeHolding_",
+        type: "uint256"
+      },
+      {
+        internalType: "uint256",
+        name: "maxBatchSizeDirect_",
+        type: "uint256"
+      },
+      {
+        internalType: "uint256",
+        name: "maxBatchSizeTokenFee_",
+        type: "uint256"
+      }
+    ],
+    stateMutability: "nonpayable",
+    type: "constructor"
+  },
+  {
+    inputs: [],
+    name: "AccessControlBadConfirmation",
+    type: "error"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "account",
+        type: "address"
+      },
+      {
+        internalType: "bytes32",
+        name: "neededRole",
+        type: "bytes32"
+      }
+    ],
+    name: "AccessControlUnauthorizedAccount",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "ArrayLengthMismatch",
+    type: "error"
+  },
+  {
+    inputs: [
+      {
+        internalType: "uint256",
+        name: "requested",
+        type: "uint256"
+      },
+      {
+        internalType: "uint256",
+        name: "max",
+        type: "uint256"
+      }
+    ],
+    name: "BatchTooLarge",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "ContractNotAllowed",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "CustomFeeNotSet",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "EmptyBatch",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "EmptyRecipients",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "EnforcedPause",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "ExpectedPause",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "FailedDeployment",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "HandleNotAllowed",
+    type: "error"
+  },
+  {
+    inputs: [
+      {
+        internalType: "uint256",
+        name: "sent",
+        type: "uint256"
+      },
+      {
+        internalType: "uint256",
+        name: "required",
+        type: "uint256"
+      }
+    ],
+    name: "InsufficientAmount",
+    type: "error"
+  },
+  {
+    inputs: [
+      {
+        internalType: "uint256",
+        name: "balance",
+        type: "uint256"
+      },
+      {
+        internalType: "uint256",
+        name: "needed",
+        type: "uint256"
+      }
+    ],
+    name: "InsufficientBalance",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "InvalidAddress",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "InvalidWalletIndex",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "ReentrancyGuardReentrantCall",
+    type: "error"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "token",
+        type: "address"
+      }
+    ],
+    name: "SafeERC20FailedOperation",
+    type: "error"
+  },
+  {
+    inputs: [
+      {
+        internalType: "bytes32",
+        name: "handle",
+        type: "bytes32"
+      },
+      {
+        internalType: "address",
+        name: "sender",
+        type: "address"
+      }
+    ],
+    name: "SenderNotAllowedToUseHandle",
+    type: "error"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "sender",
+        type: "address"
+      }
+    ],
+    name: "SenderNotAllowed",
+    type: "error"
+  },
+  {
+    inputs: [
+      {
+        internalType: "uint16",
+        name: "fee",
+        type: "uint16"
+      }
+    ],
+    name: "TokenFeeTooHigh",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "TransferFailed",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "UserAlreadyRegistered",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "UserNotRegistered",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "ZamaProtocolUnsupported",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "ZeroAddressRecipient",
+    type: "error"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: true,
+        internalType: "address",
+        name: "token",
+        type: "address"
+      },
+      {
+        indexed: true,
+        internalType: "address",
+        name: "sender",
+        type: "address"
+      },
+      {
+        indexed: false,
+        internalType: "uint256",
+        name: "recipientCount",
+        type: "uint256"
+      },
+      {
+        indexed: false,
+        internalType: "uint8",
+        name: "feeType",
+        type: "uint8"
+      }
+    ],
+    name: "ConfidentialTokensDispersed",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: true,
+        internalType: "address",
+        name: "token",
+        type: "address"
+      },
+      {
+        indexed: true,
+        internalType: "address",
+        name: "to",
+        type: "address"
+      }
+    ],
+    name: "ConfidentialTokensRescued",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: true,
+        internalType: "address",
+        name: "user",
+        type: "address"
+      }
+    ],
+    name: "CustomFeeDisabled",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: true,
+        internalType: "address",
+        name: "user",
+        type: "address"
+      },
+      {
+        indexed: false,
+        internalType: "uint96",
+        name: "gasFee",
+        type: "uint96"
+      },
+      {
+        indexed: false,
+        internalType: "uint16",
+        name: "tokenFee",
+        type: "uint16"
+      }
+    ],
+    name: "CustomFeeSet",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: true,
+        internalType: "address",
+        name: "sender",
+        type: "address"
+      },
+      {
+        indexed: false,
+        internalType: "address[]",
+        name: "recipients",
+        type: "address[]"
+      },
+      {
+        indexed: false,
+        internalType: "euint64[]",
+        name: "requested",
+        type: "bytes32[]"
+      },
+      {
+        indexed: false,
+        internalType: "euint64[]",
+        name: "transferred",
+        type: "bytes32[]"
+      }
+    ],
+    name: "DirectDistribution",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: true,
+        internalType: "address",
+        name: "token",
+        type: "address"
+      },
+      {
+        indexed: true,
+        internalType: "address",
+        name: "to",
+        type: "address"
+      },
+      {
+        indexed: false,
+        internalType: "uint256",
+        name: "amount",
+        type: "uint256"
+      }
+    ],
+    name: "ERC20Rescued",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        components: [
+          {
+            internalType: "bool",
+            name: "gasFeeEnabled",
+            type: "bool"
+          },
+          {
+            internalType: "bool",
+            name: "tokenFeeEnabled",
+            type: "bool"
+          },
+          {
+            internalType: "uint96",
+            name: "defaultGasFee",
+            type: "uint96"
+          },
+          {
+            internalType: "uint16",
+            name: "defaultTokenFee",
+            type: "uint16"
+          }
+        ],
+        indexed: false,
+        internalType: "struct IDisperseConfidential.FeeConfig",
+        name: "config",
+        type: "tuple"
+      }
+    ],
+    name: "FeeConfigUpdated",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: true,
+        internalType: "address",
+        name: "to",
+        type: "address"
+      },
+      {
+        indexed: false,
+        internalType: "uint256",
+        name: "amount",
+        type: "uint256"
+      }
+    ],
+    name: "GasFeeWithdrawn",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: true,
+        internalType: "address",
+        name: "discloser",
+        type: "address"
+      },
+      {
+        indexed: true,
+        internalType: "address",
+        name: "party",
+        type: "address"
+      },
+      {
+        indexed: false,
+        internalType: "euint64[]",
+        name: "handles",
+        type: "bytes32[]"
+      }
+    ],
+    name: "HandlesDisclosedToParty",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: false,
+        internalType: "uint256",
+        name: "oldSize",
+        type: "uint256"
+      },
+      {
+        indexed: false,
+        internalType: "uint256",
+        name: "newSize",
+        type: "uint256"
+      }
+    ],
+    name: "MaxBatchSizeDirectUpdated",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: false,
+        internalType: "uint256",
+        name: "oldSize",
+        type: "uint256"
+      },
+      {
+        indexed: false,
+        internalType: "uint256",
+        name: "newSize",
+        type: "uint256"
+      }
+    ],
+    name: "MaxBatchSizeHoldingUpdated",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: false,
+        internalType: "uint256",
+        name: "oldSize",
+        type: "uint256"
+      },
+      {
+        indexed: false,
+        internalType: "uint256",
+        name: "newSize",
+        type: "uint256"
+      }
+    ],
+    name: "MaxBatchSizeTokenFeeUpdated",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: false,
+        internalType: "address",
+        name: "account",
+        type: "address"
+      }
+    ],
+    name: "Paused",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: true,
+        internalType: "bytes32",
+        name: "role",
+        type: "bytes32"
+      },
+      {
+        indexed: true,
+        internalType: "bytes32",
+        name: "previousAdminRole",
+        type: "bytes32"
+      },
+      {
+        indexed: true,
+        internalType: "bytes32",
+        name: "newAdminRole",
+        type: "bytes32"
+      }
+    ],
+    name: "RoleAdminChanged",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: true,
+        internalType: "bytes32",
+        name: "role",
+        type: "bytes32"
+      },
+      {
+        indexed: true,
+        internalType: "address",
+        name: "account",
+        type: "address"
+      },
+      {
+        indexed: true,
+        internalType: "address",
+        name: "sender",
+        type: "address"
+      }
+    ],
+    name: "RoleGranted",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: true,
+        internalType: "bytes32",
+        name: "role",
+        type: "bytes32"
+      },
+      {
+        indexed: true,
+        internalType: "address",
+        name: "account",
+        type: "address"
+      },
+      {
+        indexed: true,
+        internalType: "address",
+        name: "sender",
+        type: "address"
+      }
+    ],
+    name: "RoleRevoked",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: true,
+        internalType: "address",
+        name: "token",
+        type: "address"
+      },
+      {
+        indexed: true,
+        internalType: "address",
+        name: "to",
+        type: "address"
+      },
+      {
+        indexed: false,
+        internalType: "euint64",
+        name: "amount",
+        type: "bytes32"
+      }
+    ],
+    name: "TokenFeeWithdrawn",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: false,
+        internalType: "address",
+        name: "account",
+        type: "address"
+      }
+    ],
+    name: "Unpaused",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: true,
+        internalType: "address",
+        name: "user",
+        type: "address"
+      },
+      {
+        indexed: false,
+        internalType: "address",
+        name: "wallet0",
+        type: "address"
+      },
+      {
+        indexed: false,
+        internalType: "address",
+        name: "wallet1",
+        type: "address"
+      }
+    ],
+    name: "UserRegistered",
+    type: "event"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: true,
+        internalType: "address",
+        name: "sender",
+        type: "address"
+      },
+      {
+        indexed: false,
+        internalType: "address",
+        name: "wallet",
+        type: "address"
+      },
+      {
+        indexed: false,
+        internalType: "address[]",
+        name: "recipients",
+        type: "address[]"
+      },
+      {
+        indexed: false,
+        internalType: "euint64[]",
+        name: "requested",
+        type: "bytes32[]"
+      },
+      {
+        indexed: false,
+        internalType: "euint64[]",
+        name: "transferred",
+        type: "bytes32[]"
+      }
+    ],
+    name: "WalletDistribution",
+    type: "event"
+  },
+  {
+    inputs: [],
+    name: "BASIS_POINTS",
+    outputs: [
+      {
+        internalType: "uint256",
+        name: "",
+        type: "uint256"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "DEFAULT_ADMIN_ROLE",
+    outputs: [
+      {
+        internalType: "bytes32",
+        name: "",
+        type: "bytes32"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "DEPLOYMENT_BLOCK_NUMBER",
+    outputs: [
+      {
+        internalType: "uint256",
+        name: "",
+        type: "uint256"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "FEE_COLLECTOR_ROLE",
+    outputs: [
+      {
+        internalType: "bytes32",
+        name: "",
+        type: "bytes32"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "FEE_MANAGER_ROLE",
+    outputs: [
+      {
+        internalType: "bytes32",
+        name: "",
+        type: "bytes32"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "FEE_TYPE_GAS",
+    outputs: [
+      {
+        internalType: "uint8",
+        name: "",
+        type: "uint8"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "FEE_TYPE_GAS_DIRECT",
+    outputs: [
+      {
+        internalType: "uint8",
+        name: "",
+        type: "uint8"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "FEE_TYPE_TOKEN",
+    outputs: [
+      {
+        internalType: "uint8",
+        name: "",
+        type: "uint8"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "PAUSER_ROLE",
+    outputs: [
+      {
+        internalType: "bytes32",
+        name: "",
+        type: "bytes32"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "WALLET_IMPLEMENTATION",
+    outputs: [
+      {
+        internalType: "address",
+        name: "",
+        type: "address"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "WITHDRAWER_ROLE",
+    outputs: [
+      {
+        internalType: "bytes32",
+        name: "",
+        type: "bytes32"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "token",
+        type: "address"
+      }
+    ],
+    name: "accessEncryptedFeeReserve",
+    outputs: [
+      {
+        internalType: "euint64",
+        name: "reserve",
+        type: "bytes32"
+      }
+    ],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "token",
+        type: "address"
+      }
+    ],
+    name: "approveUserWalletsForToken",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "euint64[]",
+        name: "handles",
+        type: "bytes32[]"
+      },
+      {
+        internalType: "address",
+        name: "party",
+        type: "address"
+      }
+    ],
+    name: "batchDiscloseHandlesToParty",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "confidentialProtocolId",
+    outputs: [
+      {
+        internalType: "uint256",
+        name: "",
+        type: "uint256"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "user",
+        type: "address"
+      }
+    ],
+    name: "disableCustomFee",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "euint64",
+        name: "handle",
+        type: "bytes32"
+      },
+      {
+        internalType: "address",
+        name: "party",
+        type: "address"
+      }
+    ],
+    name: "discloseHandleToParty",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "token",
+        type: "address"
+      },
+      {
+        internalType: "address[]",
+        name: "recipients",
+        type: "address[]"
+      },
+      {
+        internalType: "externalEuint64[]",
+        name: "encryptedAmounts",
+        type: "bytes32[]"
+      },
+      {
+        internalType: "bytes",
+        name: "inputProof",
+        type: "bytes"
+      }
+    ],
+    name: "disperseConfidentialTokenDirect",
+    outputs: [],
+    stateMutability: "payable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "token",
+        type: "address"
+      },
+      {
+        internalType: "address[]",
+        name: "recipients",
+        type: "address[]"
+      },
+      {
+        internalType: "externalEuint64[]",
+        name: "encryptedAmounts",
+        type: "bytes32[]"
+      },
+      {
+        internalType: "externalEuint64[2]",
+        name: "encryptedSubtotals",
+        type: "bytes32[2]"
+      },
+      {
+        internalType: "bytes",
+        name: "inputProof",
+        type: "bytes"
+      }
+    ],
+    name: "disperseConfidentialTokens",
+    outputs: [],
+    stateMutability: "payable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "token",
+        type: "address"
+      },
+      {
+        internalType: "address[]",
+        name: "recipients",
+        type: "address[]"
+      },
+      {
+        internalType: "externalEuint64[]",
+        name: "encryptedAmounts",
+        type: "bytes32[]"
+      },
+      {
+        internalType: "externalEuint64[2]",
+        name: "encryptedSubtotals",
+        type: "bytes32[2]"
+      },
+      {
+        internalType: "bytes",
+        name: "inputProof",
+        type: "bytes"
+      }
+    ],
+    name: "disperseConfidentialTokensWithTokenFee",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "feeConfig",
+    outputs: [
+      {
+        internalType: "bool",
+        name: "gasFeeEnabled",
+        type: "bool"
+      },
+      {
+        internalType: "bool",
+        name: "tokenFeeEnabled",
+        type: "bool"
+      },
+      {
+        internalType: "uint96",
+        name: "defaultGasFee",
+        type: "uint96"
+      },
+      {
+        internalType: "uint16",
+        name: "defaultTokenFee",
+        type: "uint16"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "user",
+        type: "address"
+      }
+    ],
+    name: "getCustomFee",
+    outputs: [
+      {
+        internalType: "bool",
+        name: "enabled",
+        type: "bool"
+      },
+      {
+        internalType: "uint96",
+        name: "gasFee",
+        type: "uint96"
+      },
+      {
+        internalType: "uint16",
+        name: "tokenFee",
+        type: "uint16"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "user",
+        type: "address"
+      }
+    ],
+    name: "getFeeAmounts",
+    outputs: [
+      {
+        internalType: "bool",
+        name: "isCustomFee",
+        type: "bool"
+      },
+      {
+        internalType: "uint96",
+        name: "gasFee",
+        type: "uint96"
+      },
+      {
+        internalType: "uint16",
+        name: "tokenFee",
+        type: "uint16"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "user",
+        type: "address"
+      }
+    ],
+    name: "getGasFee",
+    outputs: [
+      {
+        internalType: "uint96",
+        name: "",
+        type: "uint96"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "bytes32",
+        name: "role",
+        type: "bytes32"
+      }
+    ],
+    name: "getRoleAdmin",
+    outputs: [
+      {
+        internalType: "bytes32",
+        name: "",
+        type: "bytes32"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "user",
+        type: "address"
+      }
+    ],
+    name: "getTokenFee",
+    outputs: [
+      {
+        internalType: "uint16",
+        name: "",
+        type: "uint16"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "user",
+        type: "address"
+      },
+      {
+        internalType: "uint256",
+        name: "index",
+        type: "uint256"
+      }
+    ],
+    name: "getUserWallet",
+    outputs: [
+      {
+        internalType: "address",
+        name: "",
+        type: "address"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "bytes32",
+        name: "role",
+        type: "bytes32"
+      },
+      {
+        internalType: "address",
+        name: "account",
+        type: "address"
+      }
+    ],
+    name: "grantRole",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "user",
+        type: "address"
+      }
+    ],
+    name: "hasCustomFee",
+    outputs: [
+      {
+        internalType: "bool",
+        name: "",
+        type: "bool"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "bytes32",
+        name: "role",
+        type: "bytes32"
+      },
+      {
+        internalType: "address",
+        name: "account",
+        type: "address"
+      }
+    ],
+    name: "hasRole",
+    outputs: [
+      {
+        internalType: "bool",
+        name: "",
+        type: "bool"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "user",
+        type: "address"
+      }
+    ],
+    name: "isRegistered",
+    outputs: [
+      {
+        internalType: "bool",
+        name: "",
+        type: "bool"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "maxBatchSizeDirect",
+    outputs: [
+      {
+        internalType: "uint256",
+        name: "",
+        type: "uint256"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "maxBatchSizeHolding",
+    outputs: [
+      {
+        internalType: "uint256",
+        name: "",
+        type: "uint256"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "maxBatchSizeTokenFee",
+    outputs: [
+      {
+        internalType: "uint256",
+        name: "",
+        type: "uint256"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "pause",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "paused",
+    outputs: [
+      {
+        internalType: "bool",
+        name: "",
+        type: "bool"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "token",
+        type: "address"
+      },
+      {
+        internalType: "address",
+        name: "to",
+        type: "address"
+      }
+    ],
+    name: "recoverERC20FromWallets",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "token",
+        type: "address"
+      },
+      {
+        internalType: "address",
+        name: "to",
+        type: "address"
+      }
+    ],
+    name: "recoverFromWallets",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "token",
+        type: "address"
+      }
+    ],
+    name: "register",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "bytes32",
+        name: "role",
+        type: "bytes32"
+      },
+      {
+        internalType: "address",
+        name: "callerConfirmation",
+        type: "address"
+      }
+    ],
+    name: "renounceRole",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "token",
+        type: "address"
+      },
+      {
+        internalType: "address",
+        name: "to",
+        type: "address"
+      }
+    ],
+    name: "rescueConfidentialTokens",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "token",
+        type: "address"
+      },
+      {
+        internalType: "address",
+        name: "to",
+        type: "address"
+      }
+    ],
+    name: "rescueERC20",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "bytes32",
+        name: "role",
+        type: "bytes32"
+      },
+      {
+        internalType: "address",
+        name: "account",
+        type: "address"
+      }
+    ],
+    name: "revokeRole",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "token",
+        type: "address"
+      }
+    ],
+    name: "revokeUserWalletsForToken",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "user",
+        type: "address"
+      },
+      {
+        internalType: "uint96",
+        name: "gasFee",
+        type: "uint96"
+      },
+      {
+        internalType: "uint16",
+        name: "tokenFee",
+        type: "uint16"
+      }
+    ],
+    name: "setCustomFee",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        components: [
+          {
+            internalType: "bool",
+            name: "gasFeeEnabled",
+            type: "bool"
+          },
+          {
+            internalType: "bool",
+            name: "tokenFeeEnabled",
+            type: "bool"
+          },
+          {
+            internalType: "uint96",
+            name: "defaultGasFee",
+            type: "uint96"
+          },
+          {
+            internalType: "uint16",
+            name: "defaultTokenFee",
+            type: "uint16"
+          }
+        ],
+        internalType: "struct IDisperseConfidential.FeeConfig",
+        name: "config",
+        type: "tuple"
+      }
+    ],
+    name: "setFeeConfig",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "uint256",
+        name: "size",
+        type: "uint256"
+      }
+    ],
+    name: "setMaxBatchSizeDirect",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "uint256",
+        name: "size",
+        type: "uint256"
+      }
+    ],
+    name: "setMaxBatchSizeHolding",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "uint256",
+        name: "size",
+        type: "uint256"
+      }
+    ],
+    name: "setMaxBatchSizeTokenFee",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "bytes4",
+        name: "interfaceId",
+        type: "bytes4"
+      }
+    ],
+    name: "supportsInterface",
+    outputs: [
+      {
+        internalType: "bool",
+        name: "",
+        type: "bool"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "unpause",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "to",
+        type: "address"
+      },
+      {
+        internalType: "uint256",
+        name: "amount",
+        type: "uint256"
+      }
+    ],
+    name: "withdrawGasFee",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "token",
+        type: "address"
+      },
+      {
+        internalType: "address",
+        name: "to",
+        type: "address"
+      },
+      {
+        internalType: "externalEuint64",
+        name: "encryptedAmount",
+        type: "bytes32"
+      },
+      {
+        internalType: "bytes",
+        name: "inputProof",
+        type: "bytes"
+      }
+    ],
+    name: "withdrawTokenFee",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  }
+];
+function resolveEncryptor(source) {
+  if (source === void 0) return void 0;
+  return typeof source === "function" ? source() : source;
+}
+var MAX_UINT64 = (1n << 64n) - 1n;
+function assertUint64(value, label) {
+  if (value < 0n || value > MAX_UINT64) {
+    throw new InvalidArgumentError({
+      method: "encryptUint64",
+      argument: label,
+      reason: "exceeds uint64 range (0..2^64-1)",
+      value
+    });
+  }
+}
+async function encryptUint64({
+  encryptor,
+  contractAddress,
+  userAddress,
+  value
+}) {
+  assertUint64(value, "value");
+  const { handles, inputProof } = await encryptor.encrypt({
+    values: [{ value, type: "euint64" }],
+    contractAddress,
+    userAddress
+  });
+  if (handles.length !== 1) {
+    throw new InvalidArgumentError({
+      method: "encryptUint64",
+      argument: "handles",
+      reason: `expected 1 handle, got ${handles.length}`,
+      value: handles.length
+    });
+  }
+  return {
+    handle: asEncryptedHandle(bytesToHex(handles[0])),
+    inputProof: asExternalInputProof(bytesToHex(inputProof))
+  };
+}
+async function encryptUint64Batch({
+  encryptor,
+  contractAddress,
+  userAddress,
+  values
+}) {
+  if (values.length === 0) {
+    throw new InvalidArgumentError({
+      method: "encryptUint64Batch",
+      argument: "values",
+      reason: "must be non-empty"
+    });
+  }
+  values.forEach((v, i) => assertUint64(v, `values[${i}]`));
+  const { handles, inputProof } = await encryptor.encrypt({
+    values: values.map((value) => ({ value, type: "euint64" })),
+    contractAddress,
+    userAddress
+  });
+  if (handles.length !== values.length) {
+    throw new InvalidArgumentError({
+      method: "encryptUint64Batch",
+      argument: "handles",
+      reason: `expected ${values.length} handles, got ${handles.length}`,
+      value: handles.length
+    });
+  }
+  return {
+    handles: handles.map((h) => asEncryptedHandle(bytesToHex(h))),
+    inputProof: asExternalInputProof(bytesToHex(inputProof))
+  };
+}
+
+// src/fhe-disperse/errors.ts
+var NotRegisteredError = class extends TokenOpsSdkError {
+  name = "NotRegisteredError";
+  constructor(args) {
+    super(
+      `${args.method}: ${args.user} has not registered with the disperse singleton. Call \`register(token)\` first.`,
+      {
+        code: "TOKENOPS_NOT_REGISTERED",
+        cause: args.cause,
+        context: {
+          method: args.method,
+          contractAddress: args.contractAddress,
+          user: args.user
+        }
+      }
+    );
+  }
+};
+var AlreadyRegisteredError = class extends TokenOpsSdkError {
+  name = "AlreadyRegisteredError";
+  constructor(args) {
+    super(
+      `${args.method}: ${args.user} is already registered. Use \`approveUserWalletsForToken\` to whitelist additional tokens.`,
+      {
+        code: "TOKENOPS_ALREADY_REGISTERED",
+        cause: args.cause,
+        context: {
+          method: args.method,
+          contractAddress: args.contractAddress,
+          user: args.user
+        }
+      }
+    );
+  }
+};
+
+// src/fhe-disperse/subtotals.ts
+function computeSubtotals(amounts) {
+  const count = amounts.length;
+  const baseSize = Math.floor(count / 2);
+  const remainder = count % 2;
+  const group0Size = baseSize + remainder;
+  let group0 = 0n;
+  let group1 = 0n;
+  for (let i = 0; i < group0Size; i++) group0 += amounts[i];
+  for (let i = group0Size; i < count; i++) group1 += amounts[i];
+  return { group0, group1 };
+}
+var ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+var MAX_UINT642 = (1n << 64n) - 1n;
+function validateDisperseInputs(args) {
+  const { recipients, amounts, mode, batchLimit, method, contractAddress } = args;
+  const errors = [];
+  if (recipients.length === 0) {
+    errors.push(
+      new InvalidArgumentError({
+        method,
+        argument: "recipients",
+        reason: "must be non-empty"
+      })
+    );
+  }
+  if (amounts.length !== recipients.length) {
+    errors.push(
+      new InvalidArgumentError({
+        method,
+        argument: "amounts",
+        reason: `length mismatch: recipients.length (${recipients.length}) !== amounts.length (${amounts.length})`
+      })
+    );
+  }
+  recipients.forEach((r, i) => {
+    if (!isAddress(r, { strict: true })) {
+      errors.push(
+        new InvalidArgumentError({
+          method,
+          argument: `recipients[${i}]`,
+          reason: "must be a valid EIP-55 checksummed address",
+          value: r
+        })
+      );
+      return;
+    }
+    if (r === ZERO_ADDRESS) {
+      errors.push(
+        new InvalidArgumentError({
+          method,
+          argument: `recipients[${i}]`,
+          reason: "zero address",
+          value: r
+        })
+      );
+    }
+  });
+  amounts.forEach((v, i) => {
+    if (v < 0n || v > MAX_UINT642) {
+      errors.push(
+        new InvalidArgumentError({
+          method,
+          argument: `amounts[${i}]`,
+          reason: "exceeds uint64 range (0..2^64-1)"
+        })
+      );
+    }
+  });
+  const perAmountOk = errors.every((e) => !e.context.argument?.toString().startsWith("amounts["));
+  const lengthsOk = recipients.length > 0 && amounts.length === recipients.length;
+  if (mode !== "direct" && perAmountOk && lengthsOk) {
+    const { group0, group1 } = computeSubtotals([...amounts]);
+    if (group0 > MAX_UINT642) {
+      errors.push(
+        new InvalidArgumentError({
+          method,
+          argument: "amounts",
+          reason: "wallet-mode subtotal exceeds uint64 range"
+        })
+      );
+    }
+    if (group1 > MAX_UINT642) {
+      errors.push(
+        new InvalidArgumentError({
+          method,
+          argument: "amounts",
+          reason: "wallet-mode subtotal exceeds uint64 range"
+        })
+      );
+    }
+    if (group0 <= MAX_UINT642 && group1 <= MAX_UINT642 && group0 + group1 > MAX_UINT642) {
+      errors.push(
+        new InvalidArgumentError({
+          method,
+          argument: "amounts",
+          reason: "wallet-mode subtotals sum exceeds uint64 range (would silently zero on-chain)"
+        })
+      );
+    }
+  }
+  if (batchLimit > 0n && BigInt(recipients.length) > batchLimit) {
+    errors.push(
+      new BatchTooLargeError({
+        method,
+        contractAddress,
+        requested: recipients.length,
+        max: batchLimit
+      })
+    );
+  }
+  return errors;
+}
+function assertChecksumAddress(value, argument, method) {
+  if (value === void 0) return;
+  if (!isAddress(value, { strict: true })) {
+    throw new InvalidArgumentError({
+      method,
+      argument,
+      reason: "must be a valid EIP-55 checksummed address \u2014 use viem's getAddress(addr) to fix the checksum",
+      value
+    });
+  }
+}
+function assertNonZeroChecksumAddress(value, argument, method) {
+  if (value === void 0) return;
+  assertChecksumAddress(value, argument, method);
+  if (value === ZERO_ADDRESS) {
+    throw new InvalidArgumentError({
+      method,
+      argument,
+      reason: "must not be the zero address",
+      value
+    });
+  }
+}
+function batchLimitForMode(mode, limits) {
+  if (mode === "direct") return limits.direct;
+  if (mode === "wallet-token-fee") return limits.tokenFee;
+  return limits.holding;
+}
+
+// src/fhe-disperse/types.ts
+var DisperseSubwalletNotFoundError = class extends TokenOpsSdkError {
+  name = "DisperseSubwalletNotFoundError";
+  constructor(txHash, singletonAddress) {
+    super(
+      `register: no UserRegistered event from singleton ${singletonAddress} in tx ${txHash} \u2014 the registration may have reverted silently.`,
+      {
+        code: "TOKENOPS_RECEIPT_EVENT_NOT_FOUND",
+        context: { txHash, singletonAddress }
+      }
+    );
+  }
+};
+var DisperseEncryptedReserveNotGrantedError = class extends TokenOpsSdkError {
+  name = "DisperseEncryptedReserveNotGrantedError";
+  constructor(txHash, callerAddress) {
+    super(
+      `getEncryptedFeeReserve: no ACL Allowed event granting ${callerAddress} access to the fee reserve handle was found in tx ${txHash}. The fee reserve for this token may be uninitialized (no fees have accrued yet).`,
+      {
+        code: "TOKENOPS_RECEIPT_EVENT_NOT_FOUND",
+        context: { txHash, callerAddress }
+      }
+    );
+  }
+};
+
+// src/fhe-disperse/singleton.ts
+var disperseProductMapper = (name, _args, ctx) => {
+  const user = ctx.productContext?.["user"] ?? ZERO_ADDRESS2;
+  switch (name) {
+    case "UserAlreadyRegistered":
+      return new AlreadyRegisteredError({ ...ctx, user });
+    case "UserNotRegistered":
+      return new NotRegisteredError({ ...ctx, user });
+    case "ContractNotAllowed":
+      return new InvalidArgumentError({
+        method: ctx.method,
+        argument: "handle",
+        reason: "the handle's origin contract did not grant this singleton persistent ACL on the handle. ERC-7984 `transferred` handles are scoped to the token contract \u2014 disclose them through the token, not through `DisperseConfidential`."
+      });
+    default:
+      return void 0;
+  }
+};
+var ZERO_ADDRESS2 = "0x0000000000000000000000000000000000000000";
+var ERC7984_IS_OPERATOR_ABI = [
+  {
+    inputs: [
+      { name: "holder", type: "address" },
+      { name: "spender", type: "address" }
+    ],
+    name: "isOperator",
+    outputs: [{ name: "", type: "bool" }],
+    stateMutability: "view",
+    type: "function"
+  }
+];
+function predictErc1167Address(implementation, salt, deployer) {
+  const initCode = `0x3d602d80600a3d3981f3363d3d373d3d3d363d73${implementation.slice(2)}5af43d82803e903d91602b57fd5bf3`;
+  return getCreate2Address({
+    from: deployer,
+    salt,
+    bytecodeHash: keccak256(initCode)
+  });
+}
+var ConfidentialDisperseClient = class {
+  publicClient;
+  walletClient;
+  address;
+  encryptor;
+  #aclAddressOverride;
+  #telemetry;
+  #cachedAclAddress;
+  constructor(config) {
+    this.publicClient = config.publicClient;
+    this.walletClient = config.walletClient;
+    this.encryptor = config.encryptor;
+    this.#telemetry = config.telemetry;
+    const chainId = config.chainId ?? config.publicClient.chain?.id;
+    const addressOverride = config.address ? normaliseAddress(config.address) : void 0;
+    const resolved = addressOverride ?? (chainId === void 0 ? void 0 : getFheDisperseSingletonAddress(chainId));
+    if (!resolved) {
+      throw new DeploymentAddressUnavailableError({
+        reason: chainId === void 0 ? "chain-id-missing" : "registry-not-deployed",
+        product: "fheDisperse",
+        contract: "disperseConfidentialSingleton",
+        chainId,
+        clientLabel: "ConfidentialDisperseClient"
+      });
+    }
+    this.address = resolved;
+    this.#aclAddressOverride = config.aclAddress;
+    this.#telemetry?.event("fhe-disperse.client.init", {
+      surface: "singleton",
+      chainId: chainId ?? null,
+      hasWallet: !!this.walletClient,
+      aclResolved: !!config.aclAddress || chainId !== void 0 && !!getFhevmAclAddress(chainId),
+      sdkVersion: SDK_VERSION
+    });
+  }
+  /**
+   * 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() {
+    if (this.#cachedAclAddress) return this.#cachedAclAddress;
+    this.#cachedAclAddress = this.#aclAddressOverride ?? requireFhevmAclAddress(this.publicClient.chain?.id, "ConfidentialDisperseClient");
+    return this.#cachedAclAddress;
+  }
+  // ============================================================
+  //                       READ METHODS
+  // ============================================================
+  /**
+   * Check whether a user has registered their wallet pair via `register(token)`.
+   */
+  async isRegistered(user) {
+    assertChecksumAddress(user, "user", "isRegistered");
+    return this.#read("isRegistered", [user]);
+  }
+  /**
+   * Return the on-chain wallet pair for a registered user, or `null` if not registered.
+   *
+   * Both wallet addresses are fetched in parallel via `getUserWallet(user, 0|1)`.
+   * For unregistered users, call {@link predictWallets} to get the deterministic
+   * addresses they would get after registration.
+   */
+  async getWallets(user) {
+    assertChecksumAddress(user, "user", "getWallets");
+    const registered = await this.isRegistered(user);
+    if (!registered) return null;
+    const [wallet0, wallet1] = await Promise.all([
+      this.#read("getUserWallet", [user, 0n]),
+      this.#read("getUserWallet", [user, 1n])
+    ]);
+    return [wallet0, wallet1];
+  }
+  /**
+   * Deterministically predict the wallet addresses a user would get after
+   * calling `register()`, even before registration.
+   *
+   * Reads `WALLET_IMPLEMENTATION()` once from chain, then applies the same
+   * `keccak256(abi.encodePacked(user, uint256(0|1)))` salt scheme used in the
+   * contract's `_registerWallets` function.
+   *
+   * Note: `Clones.predictDeterministicAddress(impl, salt)` without an explicit
+   * deployer uses `address(this)` (the singleton) as the deployer — mirrored here.
+   */
+  async predictWallets(user) {
+    assertChecksumAddress(user, "user", "predictWallets");
+    const impl = await this.#read("WALLET_IMPLEMENTATION");
+    const salt0 = keccak256(encodePacked(["address", "uint256"], [user, 0n]));
+    const salt1 = keccak256(encodePacked(["address", "uint256"], [user, 1n]));
+    const w0 = predictErc1167Address(impl, salt0, this.address);
+    const w1 = predictErc1167Address(impl, salt1, this.address);
+    return [w0, w1];
+  }
+  /**
+   * Return consolidated fee information for a user in a single helper.
+   *
+   * Combines `getFeeAmounts(user)` (per-user resolved fees) and `feeConfig()`
+   * (global toggles) in two parallel RPC calls. UI code calls this to render
+   * the fee panel before the user submits.
+   */
+  async getFees(user) {
+    assertChecksumAddress(user, "user", "getFees");
+    const [feeAmounts, cfg] = await Promise.all([
+      this.#read("getFeeAmounts", [user]),
+      this.#read("feeConfig")
+    ]);
+    const [isCustomFee, gasFee, tokenFee] = feeAmounts;
+    const [gasFeeEnabled, tokenFeeEnabled] = cfg;
+    return {
+      isCustom: isCustomFee,
+      gasFeeWei: gasFee,
+      tokenFeeBps: tokenFee,
+      gasFeeEnabled,
+      tokenFeeEnabled
+    };
+  }
+  /**
+   * Read the raw per-user fee override stored on-chain, BEFORE the global
+   * toggles are applied. Returns `{ enabled: false, gasFeeWei: 0n,
+   * tokenFeeBps: 0 }` when no override exists for `user`.
+   *
+   * Use this — not {@link getFees} — when you need to distinguish "no
+   * override set" from "override set but globally disabled". The resolved
+   * shape is in {@link getFees}.
+   */
+  async getCustomFee(user) {
+    assertChecksumAddress(user, "user", "getCustomFee");
+    const [enabled, gasFeeWei, tokenFeeBps] = await this.#read(
+      "getCustomFee",
+      [user]
+    );
+    return { enabled, gasFeeWei, tokenFeeBps };
+  }
+  /**
+   * Return the on-chain global fee configuration.
+   *
+   * Round-trips against {@link setFeeConfig} — pass the result back unchanged
+   * to update one toggle without re-stating the others. Note that ABI outputs
+   * are positional, not named — viem decodes the tuple as an array.
+   */
+  async getFeeConfig() {
+    const [gasFeeEnabled, tokenFeeEnabled, defaultGasFee, defaultTokenFee] = await this.#read("feeConfig");
+    return { gasFeeEnabled, tokenFeeEnabled, defaultGasFee, defaultTokenFee };
+  }
+  /**
+   * Return batch size limits for all three disperse modes.
+   * `0n` means no limit is configured.
+   */
+  async getBatchLimits() {
+    const [holding, direct, tokenFee] = await Promise.all([
+      this.#read("maxBatchSizeHolding"),
+      this.#read("maxBatchSizeDirect"),
+      this.#read("maxBatchSizeTokenFee")
+    ]);
+    return { holding, direct, tokenFee };
+  }
+  /**
+   * Calculate the fee for a specific disperse call without writing to chain.
+   *
+   * Reads live fee data via `getFeeAmounts(user)` and computes:
+   * - `"wallet"` / `"direct"`: `ethValue = recipients * gasFeeWei`, no token fee.
+   * - `"wallet-token-fee"`: `ethValue = 0n`, `tokenFeeAmount = totalTokens * tokenFeeBps / 10000n`.
+   *
+   * **For `"wallet-token-fee"` mode**, the on-chain fee base is the
+   * post-cap subtotal sum (`subtotal0 + subtotal1`), not `sum(amounts[])`.
+   * The two differ only when the caller has independently constructed subtotals
+   * that don't match `sum(amounts)` — pass `totalTokens === subtotal0 +
+   * subtotal1` for the result to match the on-chain computation. Both this
+   * SDK and the contract round the BPS multiplication down (floor division).
+   *
+   * @throws {TokenOpsSdkError} if mode is `"wallet-token-fee"` and `totalTokens` is not provided.
+   */
+  async calculateFee(args) {
+    const fees = await this.getFees(args.user);
+    if (args.mode === "wallet-token-fee") {
+      if (args.totalTokens === void 0) {
+        throw new InvalidArgumentError({
+          method: "calculateFee",
+          argument: "totalTokens",
+          reason: "is required for wallet-token-fee mode"
+        });
+      }
+      const tokenFeeAmount = args.totalTokens * BigInt(fees.tokenFeeBps) / 10000n;
+      return { ethValue: 0n, tokenFeeAmount };
+    }
+    return { ethValue: BigInt(args.recipients) * fees.gasFeeWei };
+  }
+  /**
+   * Check whether a user's registered subwallets have approved the singleton
+   * as an ERC-7984 operator for the given token.
+   *
+   * Calls `isOperator(wallet, singleton)` on the token contract for each wallet.
+   * Both wallets must return `true` for wallet-mode disperses to work.
+   *
+   * Note: this requires the user to already be registered. For unregistered
+   * users, call {@link predictWallets} first and check predicted addresses.
+   */
+  async hasApprovedSubwallets(args) {
+    assertChecksumAddress(args.user, "user", "hasApprovedSubwallets");
+    assertChecksumAddress(args.token, "token", "hasApprovedSubwallets");
+    const wallets = await this.getWallets(args.user);
+    if (!wallets) {
+      return { wallet0: false, wallet1: false, both: false };
+    }
+    const [w0, w1] = wallets;
+    const [ok0, ok1] = await Promise.all([
+      this.publicClient.readContract({
+        address: args.token,
+        abi: ERC7984_IS_OPERATOR_ABI,
+        functionName: "isOperator",
+        args: [w0, this.address]
+      }),
+      this.publicClient.readContract({
+        address: args.token,
+        abi: ERC7984_IS_OPERATOR_ABI,
+        functionName: "isOperator",
+        args: [w1, this.address]
+      })
+    ]);
+    return { wallet0: ok0, wallet1: ok1, both: ok0 && ok1 };
+  }
+  // ============================================================
+  //                    PRE-FLIGHT HELPER
+  // ============================================================
+  /**
+   * Comprehensive pre-flight report. One call gives a UI everything it needs
+   * to render a "ready to disperse" checklist.
+   *
+   * Internally composes:
+   * - `isRegistered` + `getWallets` / `predictWallets`
+   * - `hasApprovedSubwallets` (wallet modes) or `isOperator(sender, singleton)` (direct mode)
+   * - `calculateFee` / `getBatchLimits`
+   * - Structural recipient + amount validation
+   */
+  async preflightDisperse(args) {
+    const { user, token, recipients, amounts, mode } = args;
+    assertChecksumAddress(user, "user", "preflightDisperse");
+    assertChecksumAddress(token, "token", "preflightDisperse");
+    const [isUserRegistered, predictedWallets, batchLimits, callerBalance, isPaused] = await Promise.all([
+      this.isRegistered(user),
+      this.predictWallets(user),
+      this.getBatchLimits(),
+      this.publicClient.getBalance({ address: user }),
+      this.paused()
+    ]);
+    const wallets = isUserRegistered ? await this.getWallets(user) : null;
+    let hasApprovedSubwallets = {
+      wallet0: false,
+      wallet1: false,
+      both: false
+    };
+    let hasApprovedSingleton = null;
+    if (mode === "direct") {
+      hasApprovedSingleton = await this.publicClient.readContract({
+        address: token,
+        abi: ERC7984_IS_OPERATOR_ABI,
+        functionName: "isOperator",
+        args: [user, this.address]
+      });
+    } else {
+      if (isUserRegistered) {
+        hasApprovedSubwallets = await this.hasApprovedSubwallets({ user, token });
+      } else if (predictedWallets) {
+        const [ok0, ok1] = await Promise.all([
+          this.publicClient.readContract({
+            address: token,
+            abi: ERC7984_IS_OPERATOR_ABI,
+            functionName: "isOperator",
+            args: [predictedWallets[0], this.address]
+          }),
+          this.publicClient.readContract({
+            address: token,
+            abi: ERC7984_IS_OPERATOR_ABI,
+            functionName: "isOperator",
+            args: [predictedWallets[1], this.address]
+          })
+        ]);
+        hasApprovedSubwallets = { wallet0: ok0, wallet1: ok1, both: ok0 && ok1 };
+      }
+    }
+    const totalTokens = amounts.reduce((a, b) => a + b, 0n);
+    const fee = await this.calculateFee({
+      user,
+      mode,
+      recipients: recipients.length,
+      totalTokens: mode === "wallet-token-fee" ? totalTokens : void 0
+    });
+    const limit = batchLimitForMode(mode, batchLimits);
+    const batchOk = limit === 0n || BigInt(recipients.length) <= limit;
+    const recipientChecks = recipients.map((addr) => {
+      if (addr === "0x0000000000000000000000000000000000000000") {
+        return { address: addr, ok: false, reason: "Zero address" };
+      }
+      return { address: addr, ok: true };
+    });
+    const amountsOk = amounts.length === recipients.length && amounts.length > 0;
+    const allAmountsInUint64 = amountsOk && amounts.every((v) => v >= 0n && v < 1n << 64n);
+    let subtotals;
+    if (mode !== "direct" && allAmountsInUint64) {
+      subtotals = computeSubtotals([...amounts]);
+    }
+    const blockers = [];
+    const blockerErrors = [];
+    const deterministicErrors = validateDisperseInputs({
+      recipients,
+      amounts,
+      mode,
+      batchLimit: limit,
+      method: "preflightDisperse",
+      contractAddress: this.address
+    });
+    for (const err of deterministicErrors) {
+      blockerErrors.push(err);
+      blockers.push(err.message);
+    }
+    if (mode !== "direct" && !isUserRegistered) {
+      blockers.push("User is not registered");
+      blockerErrors.push(
+        new NotRegisteredError({
+          method: "preflightDisperse",
+          contractAddress: this.address,
+          user: args.user
+        })
+      );
+    } else if (mode === "wallet" || mode === "wallet-token-fee") {
+      if (!hasApprovedSubwallets.both)
+        blockers.push(
+          `Wallets not fully approved for token \u2014 wallet0: ${hasApprovedSubwallets.wallet0}, wallet1: ${hasApprovedSubwallets.wallet1}`
+        );
+    }
+    if (mode === "direct" && hasApprovedSingleton === false) {
+      blockers.push("Sender has not approved the singleton as operator on the token");
+    }
+    if (isPaused) {
+      blockers.push("Singleton is paused");
+      blockerErrors.push(
+        new PausedError({ method: "preflightDisperse", contractAddress: this.address })
+      );
+    }
+    if (callerBalance < fee.ethValue) {
+      blockerErrors.push(
+        new InsufficientFeeError({
+          method: "preflightDisperse",
+          contractAddress: this.address,
+          feeKind: "gas",
+          required: fee.ethValue,
+          provided: callerBalance
+        })
+      );
+      blockers.push(
+        `User ETH balance (${callerBalance.toString()} wei) is below the required gas fee (${fee.ethValue.toString()} wei)`
+      );
+    }
+    return {
+      isUserRegistered,
+      wallets,
+      predictedWallets,
+      hasApprovedSubwallets,
+      hasApprovedSingleton,
+      feeEth: fee.ethValue,
+      feeTokenAmount: fee.tokenFeeAmount,
+      batchLimit: limit,
+      batchOk,
+      recipientChecks,
+      amountsOk,
+      subtotals,
+      ready: blockers.length === 0,
+      blockers,
+      blockerErrors
+    };
+  }
+  // ============================================================
+  //                       WRITE METHODS
+  // ============================================================
+  /**
+   * Register the caller's dedicated wallet pair for wallet-mode disperses.
+   *
+   * Deploys two deterministic ERC-1167 wallet clones and approves them for `token`.
+   * Can only be called once per user — subsequent calls revert with `UserAlreadyRegistered`.
+   *
+   * @returns `{ hash, wallets }` — `wallets` is parsed from the `UserRegistered` event.
+   * @throws {DisperseSubwalletNotFoundError} if no `UserRegistered` event matching the singleton is found.
+   */
+  async register(args) {
+    return withTelemetry(this.#telemetry, "fhe-disperse.singleton.register", async () => {
+      assertChecksumAddress(args.token, "token", "register");
+      const wallet = this.#requireWallet("register");
+      const account = this.#resolveAccount(wallet, args.account, "register");
+      const userAddress = accountAddress(account);
+      await this.#preflightWrite("register", "register", [args.token], account, {
+        user: userAddress
+      });
+      let hash;
+      try {
+        hash = await wallet.writeContract({
+          address: this.address,
+          abi: disperseConfidentialAbi,
+          functionName: "register",
+          args: [args.token],
+          account,
+          chain: wallet.chain
+        });
+      } catch (err) {
+        throw this.#mapRevert("register", err, { user: userAddress }, userAddress);
+      }
+      const receipt = await this.publicClient.waitForTransactionReceipt({ hash });
+      const events = parseEventLogs({
+        abi: disperseConfidentialAbi,
+        eventName: "UserRegistered",
+        logs: receipt.logs
+      });
+      const ours = events.filter((ev2) => ev2.address.toLowerCase() === this.address.toLowerCase());
+      if (ours.length === 0) {
+        throw new DisperseSubwalletNotFoundError(hash, this.address);
+      }
+      const ev = ours[0];
+      return { hash, wallets: [ev.args.wallet0, ev.args.wallet1] };
+    });
+  }
+  /**
+   * Approve the caller's existing registered wallets as ERC-7984 operators for `token`.
+   *
+   * Required for wallet-mode disperses when using a token different from the one
+   * passed at registration time.
+   */
+  async approveTokenOnWallets(args) {
+    assertChecksumAddress(args.token, "token", "approveTokenOnWallets");
+    const user = this.#userAddressFromOverride(args.account, "approveTokenOnWallets");
+    return this.#write("approveUserWalletsForToken", [args.token], args.account, { user });
+  }
+  /**
+   * Revoke the operator approval on `token` for the caller's wallets.
+   *
+   * The user can re-approve later via `approveTokenOnWallets`.
+   */
+  async revokeTokenOnWallets(args) {
+    assertChecksumAddress(args.token, "token", "revokeTokenOnWallets");
+    const user = this.#userAddressFromOverride(args.account, "revokeTokenOnWallets");
+    return this.#write("revokeUserWalletsForToken", [args.token], args.account, { user });
+  }
+  /**
+   * Recover all residual confidential tokens from the caller's wallets to `to`.
+   *
+   * Use after a wallet-mode disperse where the subtotals were inflated and tokens
+   * remain locked in the wallets. Returns the bare tx hash (not a wrapped result
+   * object) — unlike `disperse()`, this method does not surface any additional
+   * receipt-derived data.
+   */
+  async recoverFromWallets(args) {
+    assertChecksumAddress(args.token, "token", "recoverFromWallets");
+    assertNonZeroChecksumAddress(args.to, "to", "recoverFromWallets");
+    const user = this.#userAddressFromOverride(args.account, "recoverFromWallets");
+    return this.#write("recoverFromWallets", [args.token, args.to], args.account, { user });
+  }
+  /**
+   * Recover ERC-20 tokens accidentally sent to the caller's wallets. Returns the
+   * bare tx hash.
+   */
+  async recoverERC20FromWallets(args) {
+    assertChecksumAddress(args.token, "token", "recoverERC20FromWallets");
+    assertNonZeroChecksumAddress(args.to, "to", "recoverERC20FromWallets");
+    const user = this.#userAddressFromOverride(args.account, "recoverERC20FromWallets");
+    return this.#write("recoverERC20FromWallets", [args.token, args.to], args.account, { user });
+  }
+  /**
+   * Disperse confidential tokens to multiple recipients.
+   *
+   * SDK responsibilities:
+   * 1. Validates input deterministically (lengths, zero addresses, per-amount
+   *    uint64 bounds, wallet-mode subtotal overflow, batch-limit for the
+   *    selected mode) — using the same {@link validateDisperseInputs} helper
+   *    `preflightDisperse` uses, so an oversized or malformed batch is rejected
+   *    before any FHE encryption time is spent.
+   * 2. For wallet modes: computes group subtotals using the contract's exact split rule.
+   * 3. Encrypts amounts + subtotals in a single batch call (one input proof).
+   * 4. Computes `msg.value` for gas-fee modes; `0` for token-fee mode.
+   * 5. Dispatches to the correct contract function based on `mode`.
+   *
+   * @throws {TokenOpsSdkError} on input validation failure (first deterministic error).
+   * @throws {TokenOpsSdkError} if no encryptor is available at call time.
+   */
+  async disperse(args) {
+    return withTelemetry(this.#telemetry, "fhe-disperse.singleton.disperse", async () => {
+      const { token, mode, recipients, amounts } = args;
+      assertChecksumAddress(token, "token", "disperse");
+      const wallet = this.#requireWallet("disperse");
+      const account = this.#resolveAccount(wallet, args.account, "disperse");
+      const enc = resolveEncryptor(this.encryptor);
+      if (!enc) {
+        throw new MissingEncryptorError("disperse", {
+          hint: "Pass `encryptor` to the call or the client config."
+        });
+      }
+      const batchLimits = await this.getBatchLimits();
+      const errors = validateDisperseInputs({
+        recipients,
+        amounts,
+        mode,
+        batchLimit: batchLimitForMode(mode, batchLimits),
+        method: "disperse",
+        contractAddress: this.address
+      });
+      if (errors[0]) throw errors[0];
+      const userAddr = accountAddress(account);
+      if (mode === "direct") {
+        return this.#disperseDirect({
+          token,
+          recipients,
+          amounts,
+          account,
+          wallet,
+          userAddr,
+          enc,
+          gasFeeOverride: args.gasFeeOverride
+        });
+      }
+      return this.#disperseWallet({
+        token,
+        mode,
+        recipients,
+        amounts,
+        account,
+        wallet,
+        userAddr,
+        enc,
+        gasFeeOverride: args.gasFeeOverride
+      });
+    });
+  }
+  // ============================================================
+  //           ENCRYPTED FEE RESERVE (ADMIN / FEE_COLLECTOR)
+  // ============================================================
+  /**
+   * **This is a write transaction, not a free view. It costs gas.**
+   *
+   * Grant the caller persistent FHE ACL on the encrypted token fee reserve and
+   * return the handle. The handle is extracted from the receipt's ACL `Allowed`
+   * event — using `simulateContract` here would return a divergent handle that
+   * breaks user-decrypt downstream (Pitfall #1).
+   *
+   * If no fees have accrued for `token`, the contract does not emit an ACL event
+   * and this method throws {@link DisperseEncryptedReserveNotGrantedError}.
+   * Check `FHE.isInitialized` off-chain: a zero-hash handle means the reserve
+   * is uninitialised.
+   *
+   * Requires FEE_COLLECTOR_ROLE or DEFAULT_ADMIN_ROLE.
+   *
+   * @throws {DisperseEncryptedReserveNotGrantedError} when no ACL event is found
+   *   (i.e., reserve is uninitialised — no fees have accrued).
+   */
+  async getEncryptedFeeReserve(args) {
+    assertChecksumAddress(args.token, "token", "getEncryptedFeeReserve");
+    const wallet = this.#requireWallet("getEncryptedFeeReserve");
+    const account = this.#resolveAccount(wallet, args.account, "getEncryptedFeeReserve");
+    await this.#preflightWrite(
+      "getEncryptedFeeReserve",
+      "accessEncryptedFeeReserve",
+      [args.token],
+      account,
+      { user: accountAddress(account) }
+    );
+    let hash;
+    try {
+      hash = await wallet.writeContract({
+        address: this.address,
+        abi: disperseConfidentialAbi,
+        functionName: "accessEncryptedFeeReserve",
+        args: [args.token],
+        account,
+        chain: wallet.chain
+      });
+    } catch (err) {
+      throw this.#mapRevert(
+        "getEncryptedFeeReserve",
+        err,
+        { user: accountAddress(account) },
+        accountAddress(account)
+      );
+    }
+    const receipt = await this.publicClient.waitForTransactionReceipt({ hash });
+    const callerAddress = accountAddress(account).toLowerCase();
+    const aclLogs = receipt.logs.filter(
+      (log) => log.address.toLowerCase() === this.aclAddress.toLowerCase()
+    );
+    const events = parseEventLogs({ abi: [ACL_ALLOWED_EVENT], logs: aclLogs });
+    const granted = events.filter(
+      (ev) => ev.args.account.toLowerCase() === callerAddress && ev.args.caller.toLowerCase() === this.address.toLowerCase()
+    );
+    if (granted.length === 0) {
+      throw new DisperseEncryptedReserveNotGrantedError(hash, accountAddress(account));
+    }
+    if (granted.length > 1) {
+      throw new ReceiptEventAmbiguousError({
+        method: "getEncryptedFeeReserve",
+        eventName: "Allowed",
+        contractAddress: this.aclAddress,
+        count: granted.length,
+        txHash: hash
+      });
+    }
+    const handle = granted[0].args.handle;
+    return { handle, hash };
+  }
+  // ============================================================
+  //                  DISCLOSURE METHODS
+  // ============================================================
+  /**
+   * Grant `party` persistent FHE ACL on a single `handle`.
+   *
+   * Caller must already hold ACL on `handle`. FHEVM ACL is append-only — the
+   * grant cannot be revoked.
+   *
+   * @returns `{ hash, discloser, party, disclosedHandles }`. The non-`hash`
+   *   fields are parsed from the `HandlesDisclosedToParty` event when present;
+   *   if the event is absent (anomalous), they fall back to the call's inputs.
+   */
+  async discloseHandleToParty(args) {
+    assertChecksumAddress(args.party, "party", "discloseHandleToParty");
+    const wallet = this.#requireWallet("discloseHandleToParty");
+    const acct = this.#resolveAccount(wallet, args.account, "discloseHandleToParty");
+    const hash = await this.#write(
+      "discloseHandleToParty",
+      [args.handle, args.party],
+      args.account
+    );
+    return this.#parseDisclosure(hash, accountAddress(acct), args.party, [args.handle]);
+  }
+  /**
+   * Batch variant — atomically grant `party` persistent ACL on all `handles`.
+   * Reverts on the first handle that fails caller-ACL or contract-ACL checks.
+   */
+  async batchDiscloseHandlesToParty(args) {
+    assertChecksumAddress(args.party, "party", "batchDiscloseHandlesToParty");
+    const wallet = this.#requireWallet("batchDiscloseHandlesToParty");
+    const acct = this.#resolveAccount(wallet, args.account, "batchDiscloseHandlesToParty");
+    const hash = await this.#write(
+      "batchDiscloseHandlesToParty",
+      [args.handles, args.party],
+      args.account
+    );
+    return this.#parseDisclosure(hash, accountAddress(acct), args.party, args.handles);
+  }
+  /**
+   * Parse a `HandlesDisclosedToParty` event from a disclosure receipt. If the
+   * event is missing (which would indicate a contract or parser anomaly),
+   * fall back to the inputs the caller passed — the tx already succeeded.
+   */
+  async #parseDisclosure(hash, fallbackDiscloser, fallbackParty, fallbackHandles) {
+    const receipt = await this.publicClient.waitForTransactionReceipt({ hash });
+    const events = parseEventLogs({
+      abi: disperseConfidentialAbi,
+      eventName: "HandlesDisclosedToParty",
+      logs: receipt.logs.filter((log) => log.address.toLowerCase() === this.address.toLowerCase())
+    });
+    const ev = events[0];
+    if (!ev) {
+      return {
+        hash,
+        discloser: fallbackDiscloser,
+        party: fallbackParty,
+        disclosedHandles: [...fallbackHandles]
+      };
+    }
+    return {
+      hash,
+      discloser: ev.args.discloser,
+      party: ev.args.party,
+      disclosedHandles: [...ev.args.handles]
+    };
+  }
+  // ============================================================
+  //              ADMIN / FEE-MANAGER / FEE-COLLECTOR WRITES
+  // ============================================================
+  /**
+   * Pause all disperse operations. Requires PAUSER_ROLE.
+   * @returns Transaction hash.
+   */
+  async pause(account) {
+    return withTelemetry(this.#telemetry, "fhe-disperse.singleton.pause", async () => {
+      return this.#write("pause", [], account);
+    });
+  }
+  /**
+   * Unpause the singleton. Requires PAUSER_ROLE.
+   * @returns Transaction hash.
+   */
+  async unpause(account) {
+    return withTelemetry(this.#telemetry, "fhe-disperse.singleton.unpause", async () => {
+      return this.#write("unpause", [], account);
+    });
+  }
+  /**
+   * Update the global fee configuration: enable/disable gas and token fees, set defaults.
+   * Requires FEE_MANAGER_ROLE.
+   * @returns Transaction hash.
+   */
+  async setFeeConfig(config, account) {
+    return withTelemetry(this.#telemetry, "fhe-disperse.singleton.setFeeConfig", async () => {
+      return this.#write(
+        "setFeeConfig",
+        [
+          {
+            gasFeeEnabled: config.gasFeeEnabled,
+            tokenFeeEnabled: config.tokenFeeEnabled,
+            defaultGasFee: config.defaultGasFee,
+            defaultTokenFee: config.defaultTokenFee
+          }
+        ],
+        account
+      );
+    });
+  }
+  /**
+   * Set a per-user fee override (gas fee in wei, token fee in BPS).
+   * Requires FEE_MANAGER_ROLE.
+   * @returns Transaction hash.
+   */
+  async setCustomFee(user, gasFee, tokenFee, account) {
+    assertChecksumAddress(user, "user", "setCustomFee");
+    return this.#write("setCustomFee", [user, gasFee, tokenFee], account);
+  }
+  /**
+   * Remove a per-user fee override, falling back to the global defaults.
+   * Requires FEE_MANAGER_ROLE. Throws `CustomFeeNotSet` if no override exists.
+   * @returns Transaction hash.
+   */
+  async disableCustomFee(user, account) {
+    assertChecksumAddress(user, "user", "disableCustomFee");
+    return this.#write("disableCustomFee", [user], account, { user });
+  }
+  /**
+   * Set the maximum batch size for `"wallet"` mode disperses. `0n` = no limit.
+   * Requires DEFAULT_ADMIN_ROLE.
+   * @returns Transaction hash.
+   */
+  async setMaxBatchSizeHolding(size, account) {
+    return withTelemetry(
+      this.#telemetry,
+      "fhe-disperse.singleton.setMaxBatchSizeHolding",
+      async () => {
+        return this.#write("setMaxBatchSizeHolding", [size], account);
+      }
+    );
+  }
+  /**
+   * Set the maximum batch size for `"direct"` mode disperses. `0n` = no limit.
+   * Requires DEFAULT_ADMIN_ROLE.
+   * @returns Transaction hash.
+   */
+  async setMaxBatchSizeDirect(size, account) {
+    return withTelemetry(
+      this.#telemetry,
+      "fhe-disperse.singleton.setMaxBatchSizeDirect",
+      async () => {
+        return this.#write("setMaxBatchSizeDirect", [size], account);
+      }
+    );
+  }
+  /**
+   * Set the maximum batch size for `"wallet-token-fee"` mode disperses. `0n` = no limit.
+   * Requires DEFAULT_ADMIN_ROLE.
+   * @returns Transaction hash.
+   */
+  async setMaxBatchSizeTokenFee(size, account) {
+    return withTelemetry(
+      this.#telemetry,
+      "fhe-disperse.singleton.setMaxBatchSizeTokenFee",
+      async () => {
+        return this.#write("setMaxBatchSizeTokenFee", [size], account);
+      }
+    );
+  }
+  /**
+   * Withdraw `amount` wei of accumulated ETH gas fees to `to`. The amount is
+   * not capped on-chain — callers MUST pass an explicit amount. There is no
+   * "drain full balance" sentinel: passing `0n` succeeds with no ETH movement.
+   * Read the singleton's ETH balance with `publicClient.getBalance(singleton)`
+   * to drain.
+   *
+   * Requires FEE_COLLECTOR_ROLE.
+   * @returns Transaction hash.
+   */
+  async withdrawGasFee(to, amount, account) {
+    assertNonZeroChecksumAddress(to, "to", "withdrawGasFee");
+    return this.#write("withdrawGasFee", [to, amount], account);
+  }
+  /**
+   * Withdraw accumulated encrypted token fees.
+   *
+   * The amount is encrypted by the caller — pass plaintext `amount` and an
+   * encryptor, or pass `encryptedInput` directly. The contract caps the
+   * withdrawal at the available reserve via `FHE.min`.
+   *
+   * Returns the tx hash plus the **transferred** handle parsed from the
+   * `TokenFeeWithdrawn` event. Decrypt the handle via Zama's `userDecrypt`
+   * to view the actual amount moved (which can be less than requested when
+   * the reserve was smaller than the request). The caller is granted
+   * persistent ACL on this handle by the contract.
+   *
+   * **`encryptedInput` is bound to (this singleton, this caller).** Zama's
+   * KMSVerifier rejects proofs whose `contractAddress` or `userAddress`
+   * don't match the executing tx. If you pre-encrypt on a different chain's
+   * singleton, or for a different caller, the on-chain submission will
+   * revert with a generic verification failure. The plaintext `amount`
+   * path is safer when the caller / chain isn't fixed yet.
+   */
+  async withdrawTokenFee(args) {
+    assertChecksumAddress(args.token, "token", "withdrawTokenFee");
+    assertNonZeroChecksumAddress(args.to, "to", "withdrawTokenFee");
+    const wallet = this.#requireWallet("withdrawTokenFee");
+    const account = this.#resolveAccount(wallet, args.account, "withdrawTokenFee");
+    const encrypted = await this.#encryptSingle(
+      args.amount,
+      args.encryptor,
+      args.encryptedInput,
+      account,
+      "withdrawTokenFee"
+    );
+    await this.#preflightWrite(
+      "withdrawTokenFee",
+      "withdrawTokenFee",
+      [args.token, args.to, encrypted.handle, encrypted.inputProof],
+      account
+    );
+    let hash;
+    try {
+      hash = await wallet.writeContract({
+        address: this.address,
+        abi: disperseConfidentialAbi,
+        functionName: "withdrawTokenFee",
+        args: [args.token, args.to, encrypted.handle, encrypted.inputProof],
+        account,
+        chain: wallet.chain
+      });
+    } catch (err) {
+      throw this.#mapRevert("withdrawTokenFee", err, void 0, accountAddress(account));
+    }
+    const receipt = await this.publicClient.waitForTransactionReceipt({ hash });
+    const events = parseEventLogs({
+      abi: disperseConfidentialAbi,
+      eventName: "TokenFeeWithdrawn",
+      logs: receipt.logs.filter((log) => log.address.toLowerCase() === this.address.toLowerCase())
+    });
+    const transferredHandle = events[0]?.args.amount;
+    return { hash, transferredHandle };
+  }
+  /**
+   * Rescue accidentally-sent ERC-7984 confidential tokens from the singleton.
+   * Requires WITHDRAWER_ROLE.
+   * @returns Transaction hash.
+   */
+  async rescueConfidentialTokens(token, to, account) {
+    assertChecksumAddress(token, "token", "rescueConfidentialTokens");
+    assertNonZeroChecksumAddress(to, "to", "rescueConfidentialTokens");
+    return this.#write("rescueConfidentialTokens", [token, to], account);
+  }
+  /**
+   * Rescue accidentally-sent ERC-20 tokens from the singleton.
+   * Requires WITHDRAWER_ROLE.
+   * @returns Transaction hash.
+   */
+  async rescueERC20(token, to, account) {
+    assertChecksumAddress(token, "token", "rescueERC20");
+    assertNonZeroChecksumAddress(to, "to", "rescueERC20");
+    return this.#write("rescueERC20", [token, to], account);
+  }
+  // ============================================================
+  //                     ROLE MANAGEMENT
+  // ============================================================
+  /**
+   * Check whether `address` holds `role` on the singleton.
+   * @example
+   * const isAdmin = await client.hasRole("0x0000...0000", account.address);
+   */
+  async hasRole(role, address) {
+    assertChecksumAddress(address, "address", "hasRole");
+    return this.#read("hasRole", [role, address]);
+  }
+  /**
+   * Grant `role` to `accountTarget`. Requires DEFAULT_ADMIN_ROLE.
+   * @returns Transaction hash.
+   */
+  async grantRole(role, accountTarget, account) {
+    assertChecksumAddress(accountTarget, "accountTarget", "grantRole");
+    return this.#write("grantRole", [role, accountTarget], account);
+  }
+  /**
+   * Revoke `role` from `accountTarget`. Requires DEFAULT_ADMIN_ROLE.
+   * @returns Transaction hash.
+   */
+  async revokeRole(role, accountTarget, account) {
+    assertChecksumAddress(accountTarget, "accountTarget", "revokeRole");
+    return this.#write("revokeRole", [role, accountTarget], account);
+  }
+  /**
+   * Voluntarily relinquish `role` from the caller. The contract enforces
+   * `callerConfirmation === msg.sender` (OZ AccessControl) as a guard against
+   * accidental renunciation via a wrapper contract — pass the connected
+   * wallet's address here.
+   *
+   * Use to permanently drop privileges from a fee-collector / withdrawer /
+   * pauser without needing an admin's `revokeRole`. Cannot be undone.
+   *
+   * @returns Transaction hash.
+   */
+  async renounceRole(role, callerConfirmation, account) {
+    assertChecksumAddress(callerConfirmation, "callerConfirmation", "renounceRole");
+    return this.#write("renounceRole", [role, callerConfirmation], account);
+  }
+  // ============================================================
+  //                       STATE READS
+  // ============================================================
+  /** Whether the singleton is currently paused. */
+  async paused() {
+    return this.#read("paused");
+  }
+  /** Block number at which the singleton was deployed. */
+  async deploymentBlockNumber() {
+    return this.#read("DEPLOYMENT_BLOCK_NUMBER");
+  }
+  /** The ERC-1167 `WALLET_IMPLEMENTATION` address used by `Clones.cloneDeterministic`. */
+  async walletImplementation() {
+    return this.#read("WALLET_IMPLEMENTATION");
+  }
+  // ============================================================
+  //                  INTERNAL HELPERS
+  // ============================================================
+  async #disperseDirect(args) {
+    const { token, recipients, amounts, account, wallet, userAddr, enc, gasFeeOverride } = args;
+    let encrypted;
+    try {
+      encrypted = await encryptUint64Batch({
+        encryptor: enc,
+        contractAddress: this.address,
+        userAddress: userAddr,
+        values: amounts
+      });
+    } catch (err) {
+      throw mapZamaError(err, { method: "disperse[direct]", operation: "encrypt" });
+    }
+    let ethValue = gasFeeOverride;
+    if (ethValue === void 0) {
+      const fees = await this.getFees(userAddr);
+      ethValue = BigInt(recipients.length) * fees.gasFeeWei;
+    }
+    await this.#preflightWrite(
+      "disperse[direct]",
+      "disperseConfidentialTokenDirect",
+      [token, recipients, encrypted.handles, encrypted.inputProof],
+      account,
+      { user: userAddr },
+      ethValue
+    );
+    let hash;
+    try {
+      hash = await wallet.writeContract({
+        address: this.address,
+        abi: disperseConfidentialAbi,
+        functionName: "disperseConfidentialTokenDirect",
+        args: [token, recipients, encrypted.handles, encrypted.inputProof],
+        account,
+        chain: wallet.chain,
+        value: ethValue
+      });
+    } catch (err) {
+      throw this.#mapRevert("disperse[direct]", err, { user: userAddr }, userAddr);
+    }
+    const distributions = await this.#parseDirectDistributions(hash);
+    return { hash, distributions };
+  }
+  async #disperseWallet(args) {
+    const { token, mode, recipients, amounts, account, wallet, userAddr, enc, gasFeeOverride } = args;
+    const count = amounts.length;
+    const { group0, group1 } = computeSubtotals(amounts);
+    const allValues = [...amounts, group0, group1];
+    let encrypted;
+    try {
+      encrypted = await encryptUint64Batch({
+        encryptor: enc,
+        contractAddress: this.address,
+        userAddress: userAddr,
+        values: allValues
+      });
+    } catch (err) {
+      throw mapZamaError(err, { method: `disperse[${mode}]`, operation: "encrypt" });
+    }
+    const amountHandles = encrypted.handles.slice(0, count);
+    const subtotal0Handle = encrypted.handles[count];
+    const subtotal1Handle = encrypted.handles[count + 1];
+    if (mode === "wallet-token-fee") {
+      const writeArgs = [
+        token,
+        recipients,
+        amountHandles,
+        [subtotal0Handle, subtotal1Handle],
+        encrypted.inputProof
+      ];
+      await this.#preflightWrite(
+        "disperse[wallet-token-fee]",
+        "disperseConfidentialTokensWithTokenFee",
+        writeArgs,
+        account,
+        { user: userAddr }
+      );
+      let hash2;
+      try {
+        hash2 = await wallet.writeContract({
+          address: this.address,
+          abi: disperseConfidentialAbi,
+          functionName: "disperseConfidentialTokensWithTokenFee",
+          args: writeArgs,
+          account,
+          chain: wallet.chain
+        });
+      } catch (err) {
+        throw this.#mapRevert("disperse[wallet-token-fee]", err, { user: userAddr }, userAddr);
+      }
+      const distributions2 = await this.#parseWalletDistributions(hash2);
+      return { hash: hash2, distributions: distributions2 };
+    }
+    let ethValue = gasFeeOverride;
+    if (ethValue === void 0) {
+      const fees = await this.getFees(userAddr);
+      ethValue = BigInt(count) * fees.gasFeeWei;
+    }
+    const walletWriteArgs = [
+      token,
+      recipients,
+      amountHandles,
+      [subtotal0Handle, subtotal1Handle],
+      encrypted.inputProof
+    ];
+    await this.#preflightWrite(
+      "disperse[wallet]",
+      "disperseConfidentialTokens",
+      walletWriteArgs,
+      account,
+      { user: userAddr },
+      ethValue
+    );
+    let hash;
+    try {
+      hash = await wallet.writeContract({
+        address: this.address,
+        abi: disperseConfidentialAbi,
+        functionName: "disperseConfidentialTokens",
+        args: walletWriteArgs,
+        account,
+        chain: wallet.chain,
+        value: ethValue
+      });
+    } catch (err) {
+      throw this.#mapRevert("disperse[wallet]", err, { user: userAddr }, userAddr);
+    }
+    const distributions = await this.#parseWalletDistributions(hash);
+    return { hash, distributions };
+  }
+  /**
+   * Parse the `DirectDistribution` event from a `disperseConfidentialTokenDirect`
+   * receipt. Filters logs by the singleton's own address to avoid picking up
+   * unrelated events from re-entrancy / hook contracts. Returns at most one
+   * row (the contract emits exactly one `DirectDistribution` per direct call)
+   * but tolerates zero gracefully.
+   */
+  async #parseDirectDistributions(hash) {
+    const receipt = await this.publicClient.waitForTransactionReceipt({ hash });
+    const ours = receipt.logs.filter(
+      (log) => log.address.toLowerCase() === this.address.toLowerCase()
+    );
+    const events = parseEventLogs({
+      abi: disperseConfidentialAbi,
+      eventName: "DirectDistribution",
+      logs: ours
+    });
+    return events.map((ev) => ({
+      recipients: [...ev.args.recipients],
+      requested: [...ev.args.requested],
+      transferred: [...ev.args.transferred]
+    }));
+  }
+  /**
+   * Parse `WalletDistribution` events from a wallet-mode disperse receipt.
+   * The contract emits one event per non-empty sub-wallet group — so up to
+   * two rows for a `disperse(...)` call. Filtered by singleton address.
+   */
+  async #parseWalletDistributions(hash) {
+    const receipt = await this.publicClient.waitForTransactionReceipt({ hash });
+    const ours = receipt.logs.filter(
+      (log) => log.address.toLowerCase() === this.address.toLowerCase()
+    );
+    const events = parseEventLogs({
+      abi: disperseConfidentialAbi,
+      eventName: "WalletDistribution",
+      logs: ours
+    });
+    return events.map((ev) => ({
+      wallet: ev.args.wallet,
+      recipients: [...ev.args.recipients],
+      requested: [...ev.args.requested],
+      transferred: [...ev.args.transferred]
+    }));
+  }
+  /**
+   * Resolve the encrypted-amount payload for a single-amount write. Enforces
+   * **exactly one** of `amount` / `encryptedInput` so callers cannot silently
+   * mix a stale plaintext with a pre-encrypted handle.
+   */
+  async #encryptSingle(amount, encryptor, preEncrypted, account, method) {
+    const hasAmount = amount !== void 0;
+    const hasInput = preEncrypted !== void 0;
+    if (hasAmount && hasInput) {
+      throw new InvalidArgumentError({
+        method,
+        argument: "amount/encryptedInput",
+        reason: "exactly one of `amount` (plaintext, SDK encrypts) or `encryptedInput` (pre-encrypted) must be supplied \u2014 got both"
+      });
+    }
+    if (!hasAmount && !hasInput) {
+      throw new InvalidArgumentError({
+        method,
+        argument: "amount/encryptedInput",
+        reason: "exactly one of `amount` (plaintext, SDK encrypts) or `encryptedInput` (pre-encrypted) must be supplied \u2014 got neither"
+      });
+    }
+    if (hasInput) return preEncrypted;
+    const enc = encryptor ?? resolveEncryptor(this.encryptor);
+    if (!enc) {
+      throw new MissingEncryptorError("encryptSingle", {
+        hint: "Pass `encryptor` to the call or the client config (eager or lazy factory)."
+      });
+    }
+    try {
+      return await encryptUint64({
+        encryptor: enc,
+        contractAddress: this.address,
+        userAddress: accountAddress(account),
+        value: amount
+      });
+    } catch (err) {
+      throw mapZamaError(err, { method: "encryptSingle", operation: "encrypt" });
+    }
+  }
+  #requireWallet(method) {
+    if (!this.walletClient) {
+      throw new MissingWalletClientError(method);
+    }
+    return this.walletClient;
+  }
+  #resolveAccount(wallet, override, method) {
+    const acct = override ?? wallet.account;
+    if (!acct) {
+      throw new MissingAccountError(method);
+    }
+    return acct;
+  }
+  /**
+   * Resolve the caller's address for productContext.user without doing the
+   * full `writeContract` prep. Required by the sub-wallet helpers so that
+   * any typed revert (e.g. `UserNotRegistered`) carries the actual caller
+   * in `error.context.user`, not the zero-address default the product
+   * mapper falls back to.
+   */
+  #userAddressFromOverride(override, method) {
+    const wallet = this.#requireWallet(method);
+    return accountAddress(this.#resolveAccount(wallet, override, method));
+  }
+  async #write(functionName, args, account, productContext) {
+    const wallet = this.#requireWallet(functionName);
+    const acct = this.#resolveAccount(wallet, account, functionName);
+    await this.#preflightWrite(functionName, functionName, args, acct, productContext);
+    try {
+      return await wallet.writeContract({
+        address: this.address,
+        abi: disperseConfidentialAbi,
+        functionName,
+        args,
+        account: acct,
+        chain: wallet.chain
+      });
+    } catch (err) {
+      throw this.#mapRevert(functionName, err, productContext, accountAddress(acct));
+    }
+  }
+  /**
+   * Pre-flight a write via `simulateContract` purely to surface typed reverts.
+   *
+   * The simulate's *return value* is discarded — FHE writes still need
+   * `writeContract` + receipt parsing because simulated FHE op handles diverge
+   * from the executed-tx handles (Pitfall #1). The only purpose of the
+   * simulate call here is to let viem decode any revert against the ABI and
+   * produce a `ContractFunctionRevertedError` frame the revert-mapper can
+   * classify (e.g. `AccessControlUnauthorizedAccount` → `AccessDeniedError`).
+   */
+  async #preflightWrite(method, functionName, args, account, productContext, value) {
+    try {
+      await this.publicClient.simulateContract({
+        address: this.address,
+        abi: disperseConfidentialAbi,
+        functionName,
+        args,
+        account,
+        ...value !== void 0 ? { value } : {}
+      });
+    } catch (err) {
+      if (isContractRevert(err)) {
+        throw this.#mapRevert(method, err, productContext, accountAddress(account));
+      }
+    }
+  }
+  #mapRevert(method, err, productContext, account) {
+    return mapContractRevert(err, {
+      method,
+      contractAddress: this.address,
+      abi: disperseConfidentialAbi,
+      productMapper: disperseProductMapper,
+      productContext,
+      account
+    });
+  }
+  async #read(functionName, args = []) {
+    const result = await this.publicClient.readContract({
+      address: this.address,
+      abi: disperseConfidentialAbi,
+      functionName,
+      args
+    });
+    return result;
+  }
+};
+function createConfidentialDisperseClient(config) {
+  return new ConfidentialDisperseClient(config);
+}
+function accountAddress(account) {
+  return typeof account === "string" ? account : account.address;
+}
+
+// src/fhe-disperse/abis/wallet.ts
+var disperseWalletAbi = [
+  {
+    inputs: [],
+    stateMutability: "nonpayable",
+    type: "constructor"
+  },
+  {
+    inputs: [],
+    name: "InvalidAddress",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "InvalidInitialization",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "NotController",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "NotInitializing",
+    type: "error"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "token",
+        type: "address"
+      }
+    ],
+    name: "SafeERC20FailedOperation",
+    type: "error"
+  },
+  {
+    inputs: [],
+    name: "ZamaProtocolUnsupported",
+    type: "error"
+  },
+  {
+    anonymous: false,
+    inputs: [
+      {
+        indexed: false,
+        internalType: "uint64",
+        name: "version",
+        type: "uint64"
+      }
+    ],
+    name: "Initialized",
+    type: "event"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "token",
+        type: "address"
+      }
+    ],
+    name: "approveToken",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [],
+    name: "controller",
+    outputs: [
+      {
+        internalType: "address",
+        name: "",
+        type: "address"
+      }
+    ],
+    stateMutability: "view",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "controller_",
+        type: "address"
+      }
+    ],
+    name: "initialize",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "token",
+        type: "address"
+      },
+      {
+        internalType: "address",
+        name: "to",
+        type: "address"
+      }
+    ],
+    name: "recoverConfidentialToken",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "token",
+        type: "address"
+      },
+      {
+        internalType: "address",
+        name: "to",
+        type: "address"
+      }
+    ],
+    name: "recoverERC20",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  },
+  {
+    inputs: [
+      {
+        internalType: "address",
+        name: "token",
+        type: "address"
+      }
+    ],
+    name: "revokeToken",
+    outputs: [],
+    stateMutability: "nonpayable",
+    type: "function"
+  }
+];
+
+// src/fhe-disperse/index.ts
+var FEE_COLLECTOR_ROLE = "0x2dca0f5ce7e75a4b43fe2b0d6f5d0b7a2bf92ecf89f8f0aa17b8308b67038821";
+var FEE_MANAGER_ROLE = "0x6c0757dc3e6b28b2580c03fd9e96c274acf4f99d91fbec9b418fa1d70604ff1c";
+var PAUSER_ROLE = "0x65d7a28e3265b37a6474929f336521b332c1681b933f6cb9f3376673440d862a";
+var WITHDRAWER_ROLE = "0x10dac8c06a04bec0b551627dad28bc00d6516b0caacd1c7b345fcdb5211334e4";
+var DEFAULT_ADMIN_ROLE = "0x0000000000000000000000000000000000000000000000000000000000000000";
+
+export { AlreadyRegisteredError, ConfidentialDisperseClient, DEFAULT_ADMIN_ROLE, DisperseEncryptedReserveNotGrantedError, DisperseSubwalletNotFoundError, FEE_COLLECTOR_ROLE, FEE_MANAGER_ROLE, NotRegisteredError, PAUSER_ROLE, WITHDRAWER_ROLE, computeSubtotals, createConfidentialDisperseClient, disperseConfidentialAbi, disperseWalletAbi, encryptUint64, encryptUint64Batch, resolveEncryptor };