SDK 2.1: platform toolkit + vesting engine
v2.1.0 stable
SDK 2.1 is the stable release on the latest dist-tag. Install it with pnpm add @tokenops/sdk. The receipt-free and Safe create surface of /fhe-airdrop remains @beta.
Vesting 2.x · Types · 48@tokenops/sdk/fhe-vesting

Vesting 2.x type surface.

The subpath exports both chain-facing client types and SDK 2.1's pure versioned-engine vocabulary. Client args preserve encrypted unions and fee discriminants; Schedule and VestingEngine model explicit plaintext simulation.

Versioned engine (new in 2.1)· 7

  • ManagerVersionstring

    Selector accepted by createVestingEngine. KNOWN_MANAGER_VERSIONS is a frozen readonly registry containing only "v1"; an unknown string throws EngineError instead of falling back.

    Concept primer →
  • VestingEngine{ version, vested, isTerminal, claimable, unlockInstant, claimState, validateSchedule, tokenFeeTransfer, splitAmounts, revokeEffect }

    Pure, version-selected manager math. Every timestamp and plaintext amount is supplied by the caller; the engine performs no RPC, decryption or clock read.

    Concept primer →
  • Schedule{ start, cliff, end, initialBps, cliffBps, intervalSeconds, timelockSeconds, revocable }

    Neutral engine schedule. Times and basis points are numbers; calculation methods take chain time, allocation, settled amount and revoke time separately as bigints.

    Concept primer →
  • ClaimStateInput / ClaimStateResult{ t, schedule, paused, isRecipient, revealedClaimable } → { state, nextUnlock }

    Contract-order classification. A null revealedClaimable becomes "unknown" because the pure engine does not decrypt.

    Concept primer →
  • Violation{ code: ViolationCode, field: ViolationField }

    One validateSchedule finding. The function accumulates width, recipient, timestamp, basis-point, cliff, timelock and optional allocation violations.

    Concept primer →
  • FeeSplit / SplitResult / RevokeResult{ transfer, fee } / { original, child, originalSettled, childSettled } / { unvested }

    Plaintext previews from tokenFeeTransfer, splitAmounts and revokeEffect.

    Concept primer →
  • EngineError{ name: "EngineError", code, version?, argument? }

    Thrown for UnsupportedManagerVersion, FeeOutOfRange, InvalidSplitDenominator or InputOutOfRange. Unknown engine versions never select a default.

    Concept primer →

Id aliases (root export)· 2

  • VestingIdHex alias

    bytes32 schedule id from VestingCreated. Exported from the @tokenops/sdk root with asVestingId, not from the fhe-vesting subpath.

  • EncryptedHandleHex alias

    bytes32 pointer to an FHE ciphertext. Root export; the /fhe export of the same name is removed in 2.0, so import it from the root or use Hex.

Args· 13

  • VestingParams{ recipient, startTimestamp, endTimestamp, cliffSeconds, releaseIntervalSecs, timelockSeconds, initialUnlockBps, cliffAmountBps, isRevocable }

    Plaintext schedule struct, field for field with the contract.

  • CreateManagerArgs{ token, userSalt, splitEnabled?, pausableEnabled?, account?, gas? }

    Input to createManager / createManagerAndGetAddress. waitForReceipt is not part of it: the methods take CreateManagerArgs & ReceiptMode.

  • CreateVestingArgs{ params, amount, encryptor?, account?, gas? } | { params, encryptedInput, account?, gas? }

    Input to createVesting / useCreateVesting. Passing both amount and encryptedInput is a compile error.

  • BatchCreateVestingArgs{ items: { params, amount }[], encryptor?, account?, gas? }

    All amounts share one input proof, so items.length is capped at MAX_EUINT64_PER_INPUT_PROOF (32), and by maxBatchSize on chain.

  • ClaimArgs{ vestingId, feeType: FeeType.Gas, value, account?, gas? } | { vestingId, feeType: FeeType.DistributionToken, account?, gas? }

    claim / adminClaim. Gas managers need value (the fee in wei); DistributionToken managers deduct the fee on chain.

  • PartialClaimArgs{ vestingId, account?, gas? } & ({ feeType: FeeType.Gas, value } | { feeType: FeeType.DistributionToken }) & ({ amount, encryptor? } | { encryptedInput })

    partialClaim / adminPartialClaim and their hooks. Discriminated by feeType like ClaimArgs, so a value on a DistributionToken manager, or a missing one on a Gas manager, fails to compile.

  • SplitVestingArgs{ vestingId, numerator, denominator, newRecipient, encryptor?, preScaled?, account?, gas? }

    The ratio is scaled to FHE_SPLIT_DENOMINATOR unless preScaled. splitVesting takes SplitVestingArgs & ReceiptMode.

  • InitiateTransferArgs{ vestingId, newRecipient, transferDurationSeconds, account?, gas? }

    Recipient-side handoff; the new recipient has transferDurationSeconds to accept.

  • DiscloseArgs{ vestingId, party, disclosureType, account?, gas? }

    Grant a third party ACL on one encrypted view of a vesting.

  • WithdrawAdminArgs{ account?, gas? } & ({ amount, encryptor? } | { encryptedInput })

    withdrawAdmin. Exactly one of amount or encryptedInput.

  • WithdrawTokenFeeArgs{ to, account?, gas? } & ({ amount, encryptor? } | { encryptedInput })

    withdrawTokenFee. Exactly one of amount or encryptedInput.

  • SetOperatorArgs{ publicClient, walletClient, token, spender, account?, deadline?, waitForReceipt?, telemetry?, gas?, gasHeadroomPercent? }

    setOperator, now exported from /fhe-vesting. spender is the manager clone. deadline defaults to ERC7984_OPERATOR_MAX_DEADLINE. RevokeOperatorArgs is the same without deadline.

    Concept primer →
  • EncryptUint64Args{ encryptor, contractAddress, userAddress, value }

    encryptUint64: an EncryptedInput bound to the (contract, user) pair. EncryptUint64BatchArgs takes readonly values.

    Concept primer →

Results· 11

  • CreateManagerResult{ hash, manager, pending?: never }

    Mined result of createManager(AndGetAddress); manager is parsed from ManagerCreated. Extends MinedWrite.

  • PendingCreateManagerResult{ hash, manager: undefined, pending: true }

    With waitForReceipt: false. hash is what the wallet returned (a safeTxHash from a Safe). Extends PendingWrite.

    Concept primer →
  • SplitVestingResult{ hash, newVestingId, pending?: never }

    Mined result of splitVesting; newVestingId is parsed from VestingSplit.

  • PendingSplitVestingResult{ hash, newVestingId: undefined, pending: true }

    With waitForReceipt: false; read the executed transaction's VestingSplit log for the id.

    Concept primer →
  • EncryptedViewResult{ handle, hash }

    Returned by the encrypted views (useAccessVestedAmount and the rest). The handle is granted to the caller for user-decryption.

  • DiscloseToPartyResult{ hash, handle }

    discloseToParty / adminDiscloseToParty; handle comes from the AmountDisclosed event.

  • BatchDiscloseToPartyResult{ hash, handles }

    handles[i] corresponds to vestingIds[i], paired by vestingId and disclosure type.

  • CreateVestingPreflightReport{ token, hasCreatorRole, isOperatorSet, ready, blockerErrors }

    preflightCreateVesting / usePreflightCreateVesting. blockerErrors is TokenOpsSdkError[]; branch on error.code or render error.message. isOperatorSet is also false when approval could not be read, so check blockerErrors first.

  • PreflightResult{ ready, blockers }

    preflightClaim (headless only). blockers holds the typed errors the claim would throw, such as InsufficientBalanceError for a wallet short of the gas fee.

  • VestingInfo{ recipient, startTimestamp, endTimestamp, revokeTimestamp, cliffReleaseTimestamp, releaseIntervalSecs, timelock, initialUnlockBps, cliffAmountBps, isRevocable }

    getVestingInfo / useVestingInfo. startTimestamp === 0 means the schedule does not exist.

  • PendingTransfer{ newRecipient, initiatedAt, expiresAt }

    usePendingVestingTransfer; all zero when no transfer is pending.

Receipt, gas and query options· 5

  • ReceiptModeReceiptMode<true> = { waitForReceipt?: true }, ReceiptMode<false> = { waitForReceipt: false }, ReceiptMode = { waitForReceipt?: boolean }

    Selects the mined or pending overload. A runtime boolean, as hooks pass, uses the default form and yields the union narrowed by pending. MinedWrite and PendingWrite are the two halves.

    Concept primer →
  • GasHeadroomOption{ gasHeadroomPercent? }

    On every client config and hook option. Default DEFAULT_GAS_HEADROOM_PERCENT (25); 0 sends the bare estimate.

    Concept primer →
  • GasOverride{ gas? }

    A per-call gas limit sent as is, on every argument-object write and the encrypted-view, disclosure and withdraw hook variables.

    Concept primer →
  • ReadHookQueryOptions{ query?: Omit<UseQueryOptions, 'queryKey' | 'queryFn'> }

    From /fhe-vesting/react and /fhe-vesting/advanced/react. query.enabled can only turn a ready query off; query.select keeps the hook's data type.

    Concept primer →
  • PredictManagerArgs{ token, userSalt, deployer, blockNumber, splitEnabled?, pausableEnabled? }

    predictManagerAddress on the advanced client. Exported from /fhe-vesting/advanced and /fhe-vesting/advanced/react only.

Config and enums· 5

  • FeeTypeenum { Gas = 0, DistributionToken = 1 }

    The claim discriminant. feeTypeName() stringifies it for logs.

  • DisclosureTypeenum { TotalAllocation = 0, SettledAmount = 1, VestedAmount = 2, ClaimableAmount = 3 }

    Which encrypted view discloseToParty discloses.

  • CustomFee{ enabled, preferredFeeType, gasFee, tokenFee }

    Per-creator fee override on the factory, read with getCustomFee.

  • ConfidentialVestingFactoryClientConfig{ publicClient, walletClient?, address?, chainId?, telemetry?, gasHeadroomPercent? }

    address defaults to the registry entry for the chain id.

  • ConfidentialVestingManagerClientConfig{ publicClient, walletClient?, address, encryptor?, aclAddress?, telemetry?, gasHeadroomPercent? }

    aclAddress overrides the chain-registry FHEVM ACL lookup the encrypted views use.

Encryptor· 5

  • Encryptor{ encrypt({ values, contractAddress, userAddress }) => { encryptedValues, inputProof } }

    Mirrors ZamaSDK.encrypt from @zama-fhe/sdk 3.6, so a ZamaSDK satisfies it directly.

    Concept primer →
  • EncryptorSourceEncryptor | () => Encryptor | undefined

    What clients and hooks accept. In React pass encryptor: () => zamaSDK so the live instance is used per encryption.

    Concept primer →
  • FheValueInput{ type: euint8..euint256, value: bigint } | { type: 'ebool', value } | { type: 'eaddress', value }

    Mirrors upstream EncryptInput.

  • EncryptedInput{ handle, inputProof }

    One externalEuint64 ciphertext plus its input proof, bound to (contract, user).

  • EncryptedInputs{ handles, inputProof }

    Several ciphertexts under one proof; handles[i] is the i-th value.