@tokenops/sdk 1.1.1 → 1.6.0

package/dist/fhe-vesting/index.d.cts

@@ -1,9 +1,9 @@
 export { ConfidentialVestingFactoryClient, createConfidentialVestingFactoryClient, type ConfidentialVestingFactoryClientConfig, type CreateManagerArgs, type CreateManagerResult, } from "./factory.js";
 export { ConfidentialVestingManagerClient, createConfidentialVestingManagerClient, type BatchCreateVestingArgs, type BatchDiscloseToPartyResult, type ClaimArgs, type ConfidentialVestingManagerClientConfig, type CreateVestingArgs, type DiscloseArgs, type DiscloseToPartyResult, type EncryptedViewResult, type InitiateTransferArgs, type PartialClaimArgs, type SplitVestingArgs, type SplitVestingResult, } from "./manager.js";
 export { encryptUint64, encryptUint64Batch, resolveEncryptor, type Encryptor, type EncryptorSource, type EncryptUint64Args, type EncryptUint64BatchArgs, type FheValueInput, } from "./encryption.js";
-export { DisclosureType, FeeType, feeTypeName, type CustomFee, type EncryptedInput, type EncryptedInputs, type PendingTransfer, type VestingInfo, type VestingParams, } from "./types.js";
+export { DisclosureType, FeeType, feeTypeName, type CreateVestingPreflightReport, type CustomFee, type EncryptedInput, type EncryptedInputs, type PendingTransfer, type VestingInfo, type VestingParams, } from "./types.js";
 export { confidentialVestingFactoryAbi, confidentialVestingManagerAbi, erc7984OperatorAbi, } from "./abis/index.js";
-export { TokenOpsSdkError, isTokenOpsSdkError, DeploymentAddressUnavailableError, UnsupportedChainError, MissingAccountError, MissingClientError, MissingEncryptorError, MissingPublicClientError, MissingWalletClientError, InvalidArgumentError, ReceiptEventAmbiguousError, ReceiptEventNotFoundError, TokenOpsValidationError, ContractRevertError, TokenOpsContractError, PausedError, AccessDeniedError, InsufficientFeeError, InsufficientBalanceError, BatchTooLargeError, FeatureDisabledError, TransferFailedError, FheHandleNotAllowedError, AlreadyInitializedError, ReentrancyError, InvalidSignatureError, WalletRejectedError, WalletChainMismatchError, NetworkError, InsufficientGasFundsError, UnknownWriteFailureError, UserRejectedSignatureError, SigningFailedError, RelayerUnreachableError, EncryptionFailedError, DecryptionFailedError, UserDecryptNotAllowedError, type DeploymentAddressUnavailableReason, type TokenOpsSdkErrorCode, } from "../core/errors.js";
+export { TokenOpsSdkError, isTokenOpsSdkError, DeploymentAddressUnavailableError, UnsupportedChainError, MissingAccountError, MissingClientError, MissingEncryptorError, MissingPublicClientError, MissingWalletClientError, InvalidArgumentError, ReceiptEventAmbiguousError, ReceiptEventNotFoundError, TokenOpsValidationError, ContractRevertError, TokenOpsContractError, PausedError, AccessDeniedError, OperatorNotApprovedError, InsufficientFeeError, InsufficientBalanceError, BatchTooLargeError, FeatureDisabledError, TransferFailedError, FheHandleNotAllowedError, AlreadyInitializedError, ReentrancyError, InvalidSignatureError, WalletRejectedError, WalletChainMismatchError, NetworkError, InsufficientGasFundsError, UnknownWriteFailureError, UserRejectedSignatureError, SigningFailedError, RelayerUnreachableError, EncryptionFailedError, DecryptionFailedError, UserDecryptNotAllowedError, type DeploymentAddressUnavailableReason, type TokenOpsSdkErrorCode, } from "../core/errors.js";
 export { type PreflightResult } from "../core/preflight.js";
 export { VestingNotFoundError, NotVestingRecipientError, ClaimLockedError, VestingRevokedError, VestingNotRevocableError, VestingExpiredError, TransferAlreadyPendingError, NoPendingTransferError, NotPendingRecipientError, TransferExpiredError, } from "./errors.js";
 export { FHE_SPLIT_DENOMINATOR, scaleRatio, share, type ScaleRatioArgs, type ScaleRatioWidth, type ScaledRatio, } from "../fhe/scale-ratio.js";

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

@@ -1,9 +1,9 @@
 export { ConfidentialVestingFactoryClient, createConfidentialVestingFactoryClient, type ConfidentialVestingFactoryClientConfig, type CreateManagerArgs, type CreateManagerResult, } from "./factory.js";
 export { ConfidentialVestingManagerClient, createConfidentialVestingManagerClient, type BatchCreateVestingArgs, type BatchDiscloseToPartyResult, type ClaimArgs, type ConfidentialVestingManagerClientConfig, type CreateVestingArgs, type DiscloseArgs, type DiscloseToPartyResult, type EncryptedViewResult, type InitiateTransferArgs, type PartialClaimArgs, type SplitVestingArgs, type SplitVestingResult, } from "./manager.js";
 export { encryptUint64, encryptUint64Batch, resolveEncryptor, type Encryptor, type EncryptorSource, type EncryptUint64Args, type EncryptUint64BatchArgs, type FheValueInput, } from "./encryption.js";
-export { DisclosureType, FeeType, feeTypeName, type CustomFee, type EncryptedInput, type EncryptedInputs, type PendingTransfer, type VestingInfo, type VestingParams, } from "./types.js";
+export { DisclosureType, FeeType, feeTypeName, type CreateVestingPreflightReport, type CustomFee, type EncryptedInput, type EncryptedInputs, type PendingTransfer, type VestingInfo, type VestingParams, } from "./types.js";
 export { confidentialVestingFactoryAbi, confidentialVestingManagerAbi, erc7984OperatorAbi, } from "./abis/index.js";
-export { TokenOpsSdkError, isTokenOpsSdkError, DeploymentAddressUnavailableError, UnsupportedChainError, MissingAccountError, MissingClientError, MissingEncryptorError, MissingPublicClientError, MissingWalletClientError, InvalidArgumentError, ReceiptEventAmbiguousError, ReceiptEventNotFoundError, TokenOpsValidationError, ContractRevertError, TokenOpsContractError, PausedError, AccessDeniedError, InsufficientFeeError, InsufficientBalanceError, BatchTooLargeError, FeatureDisabledError, TransferFailedError, FheHandleNotAllowedError, AlreadyInitializedError, ReentrancyError, InvalidSignatureError, WalletRejectedError, WalletChainMismatchError, NetworkError, InsufficientGasFundsError, UnknownWriteFailureError, UserRejectedSignatureError, SigningFailedError, RelayerUnreachableError, EncryptionFailedError, DecryptionFailedError, UserDecryptNotAllowedError, type DeploymentAddressUnavailableReason, type TokenOpsSdkErrorCode, } from "../core/errors.js";
+export { TokenOpsSdkError, isTokenOpsSdkError, DeploymentAddressUnavailableError, UnsupportedChainError, MissingAccountError, MissingClientError, MissingEncryptorError, MissingPublicClientError, MissingWalletClientError, InvalidArgumentError, ReceiptEventAmbiguousError, ReceiptEventNotFoundError, TokenOpsValidationError, ContractRevertError, TokenOpsContractError, PausedError, AccessDeniedError, OperatorNotApprovedError, InsufficientFeeError, InsufficientBalanceError, BatchTooLargeError, FeatureDisabledError, TransferFailedError, FheHandleNotAllowedError, AlreadyInitializedError, ReentrancyError, InvalidSignatureError, WalletRejectedError, WalletChainMismatchError, NetworkError, InsufficientGasFundsError, UnknownWriteFailureError, UserRejectedSignatureError, SigningFailedError, RelayerUnreachableError, EncryptionFailedError, DecryptionFailedError, UserDecryptNotAllowedError, type DeploymentAddressUnavailableReason, type TokenOpsSdkErrorCode, } from "../core/errors.js";
 export { type PreflightResult } from "../core/preflight.js";
 export { VestingNotFoundError, NotVestingRecipientError, ClaimLockedError, VestingRevokedError, VestingNotRevocableError, VestingExpiredError, TransferAlreadyPendingError, NoPendingTransferError, NotPendingRecipientError, TransferExpiredError, } from "./errors.js";
 export { FHE_SPLIT_DENOMINATOR, scaleRatio, share, type ScaleRatioArgs, type ScaleRatioWidth, type ScaledRatio, } from "../fhe/scale-ratio.js";

package/dist/fhe-vesting/index.js

@@ -1,12 +1,11 @@
+export { ClaimLockedError, ConfidentialVestingManagerClient, NoPendingTransferError, NotPendingRecipientError, NotVestingRecipientError, TransferAlreadyPendingError, TransferExpiredError, VestingExpiredError, VestingNotFoundError, VestingNotRevocableError, VestingRevokedError, confidentialVestingManagerAbi, createConfidentialVestingManagerClient } from '../chunk-TN65XNTI.js';
+import '../chunk-NFW7AUEX.js';
+export { FHE_SPLIT_DENOMINATOR, encryptUint64, encryptUint64Batch, resolveEncryptor, scaleRatio, share } from '../chunk-PD7ME2BT.js';
+import '../chunk-YPYCWLYP.js';
 export { erc7984OperatorAbi } from '../chunk-7VELUOMI.js';
-export { ClaimLockedError, ConfidentialVestingManagerClient, NoPendingTransferError, NotPendingRecipientError, NotVestingRecipientError, TransferAlreadyPendingError, TransferExpiredError, VestingExpiredError, VestingNotFoundError, VestingNotRevocableError, VestingRevokedError, confidentialVestingManagerAbi, createConfidentialVestingManagerClient, encryptUint64, encryptUint64Batch, resolveEncryptor } from '../chunk-X56UVEXS.js';
-import '../chunk-ZXCOJY2Z.js';
-export { FHE_SPLIT_DENOMINATOR, scaleRatio, share } from '../chunk-XSNLAS5M.js';
-import '../chunk-FYQ2UW4T.js';
-export { ConfidentialVestingFactoryClient, DisclosureType, FeeType, confidentialVestingFactoryAbi, createConfidentialVestingFactoryClient, feeTypeName } from '../chunk-IR5AK5U5.js';
-import '../chunk-JFLEEXKP.js';
-import '../chunk-M7V2EDPB.js';
-import '../chunk-BE2AIZ3K.js';
+export { ConfidentialVestingFactoryClient, DisclosureType, FeeType, confidentialVestingFactoryAbi, createConfidentialVestingFactoryClient, feeTypeName } from '../chunk-V5D7BHW3.js';
+import '../chunk-6WSNS3UV.js';
+import '../chunk-QKKBBH7I.js';
+import '../chunk-46T67CE2.js';
+export { AccessDeniedError, AlreadyInitializedError, BatchTooLargeError, ContractRevertError, DecryptionFailedError, DeploymentAddressUnavailableError, EncryptionFailedError, FeatureDisabledError, FheHandleNotAllowedError, InsufficientBalanceError, InsufficientFeeError, InsufficientGasFundsError, InvalidArgumentError, InvalidSignatureError, MissingAccountError, MissingClientError, MissingEncryptorError, MissingPublicClientError, MissingWalletClientError, NetworkError, OperatorNotApprovedError, PausedError, ReceiptEventAmbiguousError, ReceiptEventNotFoundError, ReentrancyError, RelayerUnreachableError, SigningFailedError, TokenOpsContractError, TokenOpsSdkError, TokenOpsValidationError, TransferFailedError, UnknownWriteFailureError, UnsupportedChainError, UserDecryptNotAllowedError, UserRejectedSignatureError, WalletChainMismatchError, WalletRejectedError, isTokenOpsSdkError } from '../chunk-DRSPMIZ7.js';
 import '../chunk-Q2GP5UDC.js';
-import '../chunk-KWFFIJYX.js';
-export { AccessDeniedError, AlreadyInitializedError, BatchTooLargeError, ContractRevertError, DecryptionFailedError, DeploymentAddressUnavailableError, EncryptionFailedError, FeatureDisabledError, FheHandleNotAllowedError, InsufficientBalanceError, InsufficientFeeError, InsufficientGasFundsError, InvalidArgumentError, InvalidSignatureError, MissingAccountError, MissingClientError, MissingEncryptorError, MissingPublicClientError, MissingWalletClientError, NetworkError, PausedError, ReceiptEventAmbiguousError, ReceiptEventNotFoundError, ReentrancyError, RelayerUnreachableError, SigningFailedError, TokenOpsContractError, TokenOpsSdkError, TokenOpsValidationError, TransferFailedError, UnknownWriteFailureError, UnsupportedChainError, UserDecryptNotAllowedError, UserRejectedSignatureError, WalletChainMismatchError, WalletRejectedError, isTokenOpsSdkError } from '../chunk-IVE3QEGD.js';

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

@@ -3,7 +3,7 @@ import { type PreflightResult } from "../core/preflight.js";
 import { type EncryptedHandle, type Role, type TxHash, type VestingId } from "../core/brands.js";
 import { type SdkTelemetry } from "../core/telemetry.js";
 import { type Encryptor, type EncryptorSource } from "./encryption.js";
-import { FeeType, type DisclosureType, type EncryptedInput, type EncryptedViewResult, type PendingTransfer, type VestingInfo, type VestingParams } from "./types.js";
+import { FeeType, type CreateVestingPreflightReport, type DisclosureType, type EncryptedInput, type EncryptedViewResult, type PendingTransfer, type VestingInfo, type VestingParams } from "./types.js";
 export type { EncryptedViewResult } from "./types.js";
 export interface ConfidentialVestingManagerClientConfig {
     publicClient: PublicClient;
@@ -419,6 +419,56 @@ export declare class ConfidentialVestingManagerClient {
         vestingId: Hex;
         caller: Address;
     }): Promise<PreflightResult>;
+    /**
+     * Read-only preflight for {@link createVesting} / {@link batchCreateVesting}.
+     * Runs the deterministic-from-off-chain checks and reports blockers both as
+     * human-readable strings (`blockers`) and as typed {@link TokenOpsSdkError}s
+     * (`blockerErrors`), index-aligned.
+     *
+     * Preflight is **opt-in**. Consumers who have already validated state can
+     * skip this call and invoke the write directly — they'll receive the same
+     * typed errors at write time via the revert mapper.
+     *
+     * Report fields: `token`, `hasCreatorRole`, `isOperatorSet`, `ready`,
+     * `blockers`, `blockerErrors` — see {@link CreateVestingPreflightReport} for
+     * the meaning of each.
+     *
+     * Checks performed (all read-only, no gas):
+     * - Structural `params` validation mirroring the contract's
+     *   `_validateVestingParams` (`InvalidArgumentError` blockers): recipient is
+     *   a checksummed non-zero address, `startTimestamp < endTimestamp`, cliff
+     *   within the window, `initialUnlockBps + cliffAmountBps ≤ 10000`.
+     * - Role: creator holds `VESTING_CREATOR_ROLE`
+     *   ({@link AccessDeniedError} blocker).
+     * - Operator: creator has approved this manager as an ERC-7984 operator on
+     *   the distribution token, required for the manager's
+     *   `confidentialTransferFrom` pull ({@link OperatorNotApprovedError} blocker).
+     *   If the bound `token` does not implement the ERC-7984 `isOperator`
+     *   view — a revert, or a zero-data response for an EOA / undeployed
+     *   address — operator status is undetermined rather than the call
+     *   throwing: `isOperatorSet` reports `false` and the read failure becomes
+     *   an {@link InvalidArgumentError} blocker on `token` instead (TOK-436).
+     *
+     * **Not preflight-detectable — read before trusting `ready: true`:**
+     * - The creator's confidential token balance is an encrypted `euint64` the
+     *   SDK cannot read in plaintext. An underfunded create does **not** revert:
+     *   the contract's all-or-nothing `FHE.select` pattern silently zeroes the
+     *   vesting amounts instead. Confirm the creator's balance covers the total
+     *   before submitting.
+     * - `batchCreateVesting` additionally enforces `items.length ≤ maxBatchSize()`
+     *   on-chain; check {@link maxBatchSize} for batches.
+     *
+     * Pausing the manager does NOT block vesting creation (only claims), so
+     * paused state is intentionally not a blocker here.
+     *
+     * @param args.params The vesting schedule parameters to validate.
+     * @param args.creator The address that will send the create transaction.
+     * @returns A {@link CreateVestingPreflightReport}.
+     */
+    preflightCreateVesting(args: {
+        params: VestingParams;
+        creator: Address;
+    }): Promise<CreateVestingPreflightReport>;
     /**
      * Get the vested amount at a given timestamp as an encrypted handle.
      *
@@ -480,6 +530,21 @@ export declare class ConfidentialVestingManagerClient {
      *
      * Pass `encryptedInput` to bypass the encryptor when you manage encryption yourself.
      *
+     * **Silent-zero transfers.** ERC-7984 transfers do not revert when the sender's encrypted balance is insufficient — the transfer succeeds and moves an encrypted zero instead. This is by design: reverting would leak balance information. The transaction receipt alone cannot tell you whether value actually moved.
+     *
+     * **Amount units:** TokenOps confidential (ERC-7984) tokens use a 6-decimals
+     * convention (1 token = 1_000_000 base units), not the 18 decimals typical of
+     * ERC-20. Amount parameters are base units of the token's actual decimals:
+     * for the CTTT test token (6 decimals) `1_000_000n` = 1 CTTT, while the
+     * transparent TTT test token uses 18 decimals.
+     *
+     * Prerequisites: caller must have set this manager as an operator on the
+     * token: `token.setOperator(managerAddress, deadline)` — or use
+     * `ensureOperator()` from `@tokenops/sdk/fhe`. Skipping it fails with
+     * {@link OperatorNotApprovedError} (the SDK's mapping of the on-chain
+     * `ERC7984UnauthorizedSpender` revert, whose message is the canonical
+     * `OPERATOR_NOT_APPROVED_REMEDIATION` copy).
+     *
      * @returns Transaction hash. Parse the `VestingCreated` event to extract the `vestingId`.
      * @example
      * const hash = await manager.createVesting({
@@ -496,12 +561,30 @@ export declare class ConfidentialVestingManagerClient {
      *
      * Respects `maxBatchSize` — check before calling on large lists.
      *
+     * **Silent-zero transfers.** ERC-7984 transfers do not revert when the sender's encrypted balance is insufficient — the transfer succeeds and moves an encrypted zero instead. This is by design: reverting would leak balance information. The transaction receipt alone cannot tell you whether value actually moved.
+     *
+     * **Amount units:** TokenOps confidential (ERC-7984) tokens use a 6-decimals
+     * convention (1 token = 1_000_000 base units), not the 18 decimals typical of
+     * ERC-20. Amount parameters are base units of the token's actual decimals:
+     * for the CTTT test token (6 decimals) `1_000_000n` = 1 CTTT, while the
+     * transparent TTT test token uses 18 decimals.
+     *
+     * Prerequisites: caller must have set this manager as an operator on the
+     * token: `token.setOperator(managerAddress, deadline)` — or use
+     * `ensureOperator()` from `@tokenops/sdk/fhe`. Skipping it fails with
+     * {@link OperatorNotApprovedError} (the SDK's mapping of the on-chain
+     * `ERC7984UnauthorizedSpender` revert, whose message is the canonical
+     * `OPERATOR_NOT_APPROVED_REMEDIATION` copy).
+     *
      * @returns Transaction hash.
      */
     batchCreateVesting(args: BatchCreateVestingArgs): Promise<Hex>;
     /**
      * Claim all currently vested tokens for `vestingId`.
      * For `FeeType.Gas` managers, pass `value` (gas fee in wei from `getFeeInfo()`).
+     *
+     * **Silent-zero transfers.** ERC-7984 transfers do not revert when the sender's encrypted balance is insufficient — the transfer succeeds and moves an encrypted zero instead. This is by design: reverting would leak balance information. The transaction receipt alone cannot tell you whether value actually moved.
+     *
      * @param args Discriminated by `feeType`: pass `{ feeType, vestingId, value }` for Gas, `{ feeType, vestingId }` for DistributionToken.
      * @returns Transaction hash.
      * @example
@@ -514,6 +597,9 @@ export declare class ConfidentialVestingManagerClient {
     /**
      * Admin variant of `claim` — callable by the manager admin on behalf of any recipient.
      * Useful for gas-sponsored claim flows. Same fee rules as `claim`.
+     *
+     * **Silent-zero transfers.** ERC-7984 transfers do not revert when the sender's encrypted balance is insufficient — the transfer succeeds and moves an encrypted zero instead. This is by design: reverting would leak balance information. The transaction receipt alone cannot tell you whether value actually moved.
+     *
      * @param args Same discriminated union as `claim`.
      * @returns Transaction hash.
      */
@@ -521,12 +607,30 @@ export declare class ConfidentialVestingManagerClient {
     /**
      * Claim a specific encrypted amount from a vesting schedule rather than the full claimable balance.
      * The SDK encrypts `amount` — pass plaintext. Alternatively pass `encryptedInput` to bypass encryption.
+     *
+     * **Silent-zero transfers.** ERC-7984 transfers do not revert when the sender's encrypted balance is insufficient — the transfer succeeds and moves an encrypted zero instead. This is by design: reverting would leak balance information. The transaction receipt alone cannot tell you whether value actually moved.
+     *
+     * **Amount units:** TokenOps confidential (ERC-7984) tokens use a 6-decimals
+     * convention (1 token = 1_000_000 base units), not the 18 decimals typical of
+     * ERC-20. Amount parameters are base units of the token's actual decimals:
+     * for the CTTT test token (6 decimals) `1_000_000n` = 1 CTTT, while the
+     * transparent TTT test token uses 18 decimals.
+     *
      * @param args Includes `vestingId`, `amount` or `encryptedInput`, and optional `value` for Gas-fee managers.
      * @returns Transaction hash.
      */
     partialClaim(args: PartialClaimArgs): Promise<Hex>;
     /**
      * Admin variant of `partialClaim` — callable by the manager admin on behalf of any recipient.
+     *
+     * **Silent-zero transfers.** ERC-7984 transfers do not revert when the sender's encrypted balance is insufficient — the transfer succeeds and moves an encrypted zero instead. This is by design: reverting would leak balance information. The transaction receipt alone cannot tell you whether value actually moved.
+     *
+     * **Amount units:** TokenOps confidential (ERC-7984) tokens use a 6-decimals
+     * convention (1 token = 1_000_000 base units), not the 18 decimals typical of
+     * ERC-20. Amount parameters are base units of the token's actual decimals:
+     * for the CTTT test token (6 decimals) `1_000_000n` = 1 CTTT, while the
+     * transparent TTT test token uses 18 decimals.
+     *
      * @param args Same as `partialClaim`.
      * @returns Transaction hash.
      */
@@ -673,6 +777,13 @@ export declare class ConfidentialVestingManagerClient {
     /**
      * Withdraw a confidential token amount from the manager's balance back to the admin.
      * The SDK encrypts `amount` — pass plaintext. Alternatively pass `encryptedInput`.
+     *
+     * **Amount units:** TokenOps confidential (ERC-7984) tokens use a 6-decimals
+     * convention (1 token = 1_000_000 base units), not the 18 decimals typical of
+     * ERC-20. Amount parameters are base units of the token's actual decimals:
+     * for the CTTT test token (6 decimals) `1_000_000n` = 1 CTTT, while the
+     * transparent TTT test token uses 18 decimals.
+     *
      * @param args `{ amount }` (plaintext, SDK encrypts) or `{ encryptedInput }` (pre-encrypted).
      * @returns Transaction hash.
      */
@@ -708,6 +819,13 @@ export declare class ConfidentialVestingManagerClient {
     /**
      * Withdraw accumulated token fees from a `FeeType.DistributionToken` manager. Admin only.
      * The SDK encrypts `amount` — pass plaintext. Alternatively pass `encryptedInput`.
+     *
+     * **Amount units:** TokenOps confidential (ERC-7984) tokens use a 6-decimals
+     * convention (1 token = 1_000_000 base units), not the 18 decimals typical of
+     * ERC-20. Amount parameters are base units of the token's actual decimals:
+     * for the CTTT test token (6 decimals) `1_000_000n` = 1 CTTT, while the
+     * transparent TTT test token uses 18 decimals.
+     *
      * @param args `{ to, amount }` (plaintext, SDK encrypts) or `{ to, encryptedInput }` (pre-encrypted).
      * @returns Transaction hash.
      */