Every product subpath of v2.0.0-rc.1 sits on the same core: one Encryptor contract, one gas policy, one receipt mode, one telemetry interface and one error hierarchy. The product subpaths re-export most of it, so you rarely import these subpaths directly, but this is where each piece is defined and where its behaviour is documented once. Install with pnpm add @tokenops/sdk@next and the optional Zama peers at ~3.6.0.
The five shared subpaths#
The value exports below are read from the installed build, so they cannot list something the artifact does not export. Types are not listed; the API reference has those.
SDK_VERSION, the deployed-address registry and its accessors, chain helpers, branded hex types, gas helpers, receipt-mode types and the core error palette.
71 runtime value exports
AccessDeniedErrorAclNotPropagatedErrorAlreadyInitializedErrorapplyGasHeadroomasAirdropIdasEncryptedHandleasExternalInputProofasRoleasSignatureasTxHashasVestingIdBatchTooLargeErrorchainsWithDeploymentchainsWithKnownRegistryEntryContractRevertErrorDecryptionFailedErrorDEFAULT_GAS_HEADROOM_PERCENTDEPLOYED_ADDRESSESDeploymentAddressUnavailableErrorEncryptionFailedErrorFeatureDisabledErrorFheHandleNotAllowedErrorgetConfidentialTestTokenAddressgetDeployedAddressgetFheAirdropComplianceImplementationAddressgetFheAirdropEcdsaImplementationAddressgetFheAirdropFactoryAddressgetFheAirdropMerkleImplementationAddressgetFheDisperseSingletonAddressgetFheVestingFactoryAddressgetTestTokenAddressInsufficientBalanceErrorInsufficientFeeErrorInsufficientGasFundsErrorInvalidArgumentErrorInvalidSignatureErrorisSupportedChainIdisTokenOpsSdkErrorMAX_TRANSACTION_GASMissingAccountErrorMissingClientErrorMissingEncryptorErrorMissingPeerDependencyErrorMissingPublicClientErrorMissingWalletClientErrorNetworkErrorOPERATOR_NOT_APPROVED_REMEDIATIONOperatorNotApprovedErrorPausedErrorReceiptEventAmbiguousErrorReceiptEventNotFoundErrorReentrancyErrorRelayerUnreachableErrorrequireConfidentialTestTokenAddressrequireFheAirdropFactoryAddressrequireFheDisperseSingletonAddressrequireFheVestingFactoryAddressrequireTestTokenAddressSDK_VERSIONSigningFailedErrorSUPPORTED_CHAINSTokenOpsContractErrorTokenOpsSdkErrorTokenOpsValidationErrorTransferFailedErrorUnknownWriteFailureErrorUnsupportedChainErrorUserDecryptNotAllowedErrorUserRejectedSignatureErrorWalletChainMismatchErrorWalletRejectedErrorTelemetry sinks: NoopTelemetry, ConsoleTelemetry and TokenOpsTelemetry, plus withTelemetry and the SdkTelemetry interface.
4 runtime value exports
ConsoleTelemetryNoopTelemetryTokenOpsTelemetrywithTelemetryThe Encryptor contract, the Node and mock encryptors, ERC-7984 operator helpers, the FHEVM ACL registry, scaleRatio and the mock-token mint. Bundles without @zama-fhe/sdk.
65 runtime value exports
AccessDeniedErrorACL_ALLOWED_EVENTAclNotPropagatedErrorAlreadyInitializedErrorBatchTooLargeErrorContractRevertErrorcreateLocalFhevmEncryptorcreateMockEncryptorcreateMockErc7984ClientcreateSepoliaEncryptorDecryptionFailedErrorDEFAULT_GAS_HEADROOM_PERCENTDeploymentAddressUnavailableErrorEncryptionFailedErrorensureOperatorERC7984_OPERATOR_MAX_DEADLINEERC7984_SET_OPERATOR_ABIerc7984OperatorAbiFeatureDisabledErrorFHE_SPLIT_DENOMINATORFheHandleNotAllowedErrorFHEVM_ACL_ADDRESS_BY_CHAINgetFhevmAclAddressInsufficientBalanceErrorInsufficientFeeErrorInsufficientGasFundsErrorInvalidArgumentErrorInvalidSignatureErrorisOperatorisTokenOpsSdkErrorMAINNET_CHAIN_IDMAX_EUINT64_PER_INPUT_PROOFmintMockERC7984MissingAccountErrorMissingClientErrorMissingEncryptorErrorMissingPeerDependencyErrorMissingPublicClientErrorMissingWalletClientErrorMOCK_ERC7984_MINT_ABINetworkErrorOperatorNotApprovedErrorPausedErrorReceiptEventAmbiguousErrorReceiptEventNotFoundErrorReentrancyErrorRelayerUnreachableErrorrequireFhevmAclAddressresolveEncryptorrevokeOperatorscaleRatioSEPOLIA_CHAIN_IDsetOperatorshareSigningFailedErrorTokenOpsContractErrorTokenOpsSdkErrorTokenOpsValidationErrorTransferFailedErrorUnknownWriteFailureErrorUnsupportedChainErrorUserDecryptNotAllowedErrorUserRejectedSignatureErrorWalletChainMismatchErrorWalletRejectedErrorcreateSepoliaEncryptorWeb and its option and worker types. The only subpath a bundler resolves @zama-fhe/sdk for.
7 runtime value exports
createSepoliaEncryptorWebInvalidArgumentErrorisTokenOpsSdkErrorMAINNET_CHAIN_IDMissingPeerDependencyErrorSEPOLIA_CHAIN_IDTokenOpsSdkErrorCross-product React hooks, plus the errors those hooks throw for instanceof checks.
3 runtime hooks
useDecryptedHandleuseIsOperatoruseEnsureOperatorRatios for confidential splits#
Every confidential split uses one plaintext denominator, FHE_SPLIT_DENOMINATOR (90090000, the LCM of 1 to 16 and 10 000). A per-split denominator would reveal the split's shape without decrypting anything. share.fraction(n, m) (m from 1 to 16) and share.basisPoints(bps) (0 to 10 000) build exact numerators over it; pass the result with preScaled: true. scaleRatio scales any other ratio to the same denominator; its width defaults to "uint128", so pass "uint64" to check a split numerator against the bound the encryption enforces. All three come from /fhe and are re-exported by /fhe-vesting, whose splitVesting is the one split today.
import { share, scaleRatio } from "@tokenops/sdk/fhe-vesting";
share.fraction(1, 3); // { numerator: 30_030_000n, denominator: 90_090_000n }
share.basisPoints(250); // { numerator: 2_252_250n, denominator: 90_090_000n }, 2.5%
// Preview what auto-scaling would send, validated at the encrypt width.
scaleRatio({ numerator: 1n, denominator: 2n, width: "uint64" });
const ratio = share.basisPoints(50);
await manager.splitVesting({
vestingId,
numerator: ratio.numerator,
denominator: ratio.denominator,
preScaled: true, // share already scaled it exactly
newRecipient,
});Hex aliases#
The root exports EncryptedHandle, ExternalInputProof, TxHash, VestingId, AirdropId, Role and Signature. Each is a plain alias of viem's Hex, so they document what a value holds without nominal checking. The matching as* helpers (asTxHash, asVestingId and so on) are identity functions.
What changed since 1.6#
The full list, with every removal and its replacement, is in the migration guides. These are the changes that touch the shared core.
| Change | What to do | Read |
|---|---|---|
Zama peers move to ~3.6.0 | Upgrade @zama-fhe/sdk and @zama-fhe/react-sdk together; no range covers both 3.0 and 3.6. | Zama 3.0 to 3.6 |
Encryptor.encrypt resolves hex | Custom encryptors return { encryptedValues, inputProof } as Hex. Pass the ZamaSDK itself as the encryptor. | Encryptors |
createSepoliaEncryptorWeb moved | Import it from @tokenops/sdk/fhe/web. From the alphas only the path changed; from 1.6 it also gains auth and offload* options and some behaviour changes. | Browser encryptor |
| Mainnet relayer needs an API key | Pass auth from server code; point browsers at a proxy with relayerUrl. | Relayer API key |
UserDecryptor mirrors decryptValues | Pass userDecryptor: () => sdk.decryption and account to useDecryptedHandle. | Decryption |
| Gas headroom on every write | Nothing, unless you tune gasHeadroomPercent or pass a per-call gas. | Gas headroom |
| Wallet-chain check on every write | A wallet on a different chain than the public client now throws WalletChainMismatchError before estimating. | Error palette |
waitForReceipt: false | Safe and multisig signers get a Pending result instead of a hang; hooks resolve Mined | Pending. | Receipt-free writes |
query on every product read hook | TanStack cache options per read, minus queryKey and queryFn. | Query options |
| New error classes and codes | MissingPeerDependencyError, AclNotPropagatedError and new codes: an exhaustive switch on err.code needs the new cases. | Error palette |
SDK_VERSION on the root | Pass it as TokenOpsTelemetryOptions.sdkVersion. The vesting hook-fired telemetry event is gone. | Telemetry |
Upgrading code: from 1.x, from a 2.0 prerelease, and Zama SDK 3.0 to 3.6.
Pages in this section#
- Encryptors - The Encryptor contract, Node and mock encryptors, input-proof budget
- Browser encryptor - createSepoliaEncryptorWeb on /fhe/web, workers and threads
- Relayer API key - Mainnet relayer auth, server-only keys, browser proxy
- Decryption - UserDecryptor, useDecryptedHandle, ACL propagation
- Operators - setOperator, ensureOperator and the React pair
- Gas headroom - Padded estimates, per-call gas, the EIP-7825 cap
- Receipt-free writes - waitForReceipt: false for Safe and multisig signers
- Read-hook query options - query on every product read hook
- Telemetry - Sinks, spans, and what is never sent
- Deployments - DEPLOYED_ADDRESSES per product and chain
- Bundling + Node servers - Next.js, Vite, webpack, CSP, Express, wagmi v2 and v3
- Error palette - Every TokenOpsSdkError class and code
- Hooks - useDecryptedHandle, useIsOperator, useEnsureOperator