@zama-fhe/sdk 1.0.0-alpha.2

package/dist/token.types-D1ELXBX9.d.ts

@@ -0,0 +1,550 @@
+import * as SDK from '@zama-fhe/relayer-sdk/bundle';
+import { FhevmInstanceConfig, Address, ZKProofLike, KmsDelegatedUserDecryptEIP712Type, InputProofBytesType } from '@zama-fhe/relayer-sdk/bundle';
+
+/**
+ * Optional logger for worker client observability.
+ * Pass to `WorkerClientConfig` or `NodeWorkerClientConfig` to observe
+ * request lifecycle (start, success, error, timeout).
+ */
+interface GenericLogger {
+    info: (message: string, data?: Record<string, unknown>) => void;
+    debug: (message: string, data?: Record<string, unknown>) => void;
+    warn: (message: string, data?: Record<string, unknown>) => void;
+    error: (message: string, data?: Record<string, unknown>) => void;
+}
+type WorkerRequestType = "INIT" | "NODE_INIT" | "UPDATE_CSRF" | "ENCRYPT" | "USER_DECRYPT" | "PUBLIC_DECRYPT" | "GENERATE_KEYPAIR" | "CREATE_EIP712" | "CREATE_DELEGATED_EIP712" | "DELEGATED_USER_DECRYPT" | "REQUEST_ZK_PROOF_VERIFICATION" | "GET_PUBLIC_KEY" | "GET_PUBLIC_PARAMS";
+interface BaseRequest {
+    id: string;
+    type: WorkerRequestType;
+}
+interface InitRequest extends BaseRequest {
+    type: "INIT";
+    payload: {
+        cdnUrl: string;
+        fhevmConfig: FhevmInstanceConfig;
+        csrfToken: string;
+        /** Expected SHA-384 hex digest for integrity verification. */
+        integrity?: string;
+    };
+}
+interface NodeInitRequest extends BaseRequest {
+    type: "NODE_INIT";
+    payload: {
+        fhevmConfig: FhevmInstanceConfig;
+    };
+}
+interface UpdateCsrfRequest extends BaseRequest {
+    type: "UPDATE_CSRF";
+    payload: {
+        csrfToken: string;
+    };
+}
+interface EncryptRequest extends BaseRequest {
+    type: "ENCRYPT";
+    payload: {
+        values: bigint[];
+        contractAddress: Address;
+        userAddress: Address;
+    };
+}
+interface UserDecryptRequest extends BaseRequest {
+    type: "USER_DECRYPT";
+    payload: {
+        handles: string[];
+        contractAddress: Address;
+        signedContractAddresses: Address[];
+        privateKey: string;
+        publicKey: string;
+        signature: string;
+        signerAddress: Address;
+        startTimestamp: number;
+        durationDays: number;
+    };
+}
+interface PublicDecryptRequest extends BaseRequest {
+    type: "PUBLIC_DECRYPT";
+    payload: {
+        handles: string[];
+    };
+}
+interface GenerateKeypairRequest extends BaseRequest {
+    type: "GENERATE_KEYPAIR";
+    payload: Record<string, never>;
+}
+interface CreateEIP712Request extends BaseRequest {
+    type: "CREATE_EIP712";
+    payload: {
+        publicKey: string;
+        contractAddresses: Address[];
+        startTimestamp: number;
+        durationDays: number;
+    };
+}
+interface CreateDelegatedEIP712Request extends BaseRequest {
+    type: "CREATE_DELEGATED_EIP712";
+    payload: {
+        publicKey: string;
+        contractAddresses: Address[];
+        delegatorAddress: string;
+        startTimestamp: number;
+        durationDays: number;
+    };
+}
+interface DelegatedUserDecryptRequest extends BaseRequest {
+    type: "DELEGATED_USER_DECRYPT";
+    payload: {
+        handles: string[];
+        contractAddress: Address;
+        signedContractAddresses: Address[];
+        privateKey: string;
+        publicKey: string;
+        signature: string;
+        delegatorAddress: Address;
+        delegateAddress: Address;
+        startTimestamp: number;
+        durationDays: number;
+    };
+}
+interface RequestZKProofVerificationRequest extends BaseRequest {
+    type: "REQUEST_ZK_PROOF_VERIFICATION";
+    payload: {
+        zkProof: ZKProofLike;
+    };
+}
+interface GetPublicKeyRequest extends BaseRequest {
+    type: "GET_PUBLIC_KEY";
+    payload: Record<string, never>;
+}
+interface GetPublicParamsRequest extends BaseRequest {
+    type: "GET_PUBLIC_PARAMS";
+    payload: {
+        bits: number;
+    };
+}
+type WorkerRequest = InitRequest | NodeInitRequest | UpdateCsrfRequest | EncryptRequest | UserDecryptRequest | PublicDecryptRequest | GenerateKeypairRequest | CreateEIP712Request | CreateDelegatedEIP712Request | DelegatedUserDecryptRequest | RequestZKProofVerificationRequest | GetPublicKeyRequest | GetPublicParamsRequest;
+type EncryptPayload = EncryptRequest["payload"];
+type UserDecryptPayload = UserDecryptRequest["payload"];
+type DelegatedUserDecryptPayload = DelegatedUserDecryptRequest["payload"];
+type CreateEIP712Payload = CreateEIP712Request["payload"];
+type CreateDelegatedEIP712Payload = CreateDelegatedEIP712Request["payload"];
+interface BaseResponse {
+    id: string;
+    type: WorkerRequestType;
+}
+interface SuccessResponse<T> extends BaseResponse {
+    success: true;
+    data: T;
+}
+interface ErrorResponse extends BaseResponse {
+    success: false;
+    error: string;
+    /** HTTP status code from the relayer, when available. */
+    statusCode?: number;
+}
+type WorkerResponse<T> = SuccessResponse<T> | ErrorResponse;
+interface EncryptResponseData {
+    handles: Uint8Array[];
+    inputProof: Uint8Array;
+}
+interface UserDecryptResponseData {
+    clearValues: Record<string, bigint>;
+}
+interface PublicDecryptResponseData {
+    clearValues: Record<string, bigint>;
+    abiEncodedClearValues: string;
+    decryptionProof: Address;
+}
+interface GenerateKeypairResponseData {
+    publicKey: string;
+    privateKey: string;
+}
+interface CreateEIP712ResponseData {
+    domain: {
+        name: string;
+        version: string;
+        chainId: number;
+        verifyingContract: Address;
+    };
+    types: {
+        UserDecryptRequestVerification: Array<{
+            name: string;
+            type: string;
+        }>;
+    };
+    message: {
+        publicKey: string;
+        contractAddresses: string[];
+        startTimestamp: bigint;
+        durationDays: bigint;
+        extraData: string;
+    };
+}
+type CreateDelegatedEIP712ResponseData = KmsDelegatedUserDecryptEIP712Type;
+interface DelegatedUserDecryptResponseData {
+    clearValues: Record<string, bigint>;
+}
+type RequestZKProofVerificationResponseData = InputProofBytesType;
+interface GetPublicKeyResponseData {
+    result: {
+        publicKeyId: string;
+        publicKey: Uint8Array;
+    } | null;
+}
+interface GetPublicParamsResponseData {
+    result: {
+        publicParams: Uint8Array;
+        publicParamsId: string;
+    } | null;
+}
+
+/** Generic hex-encoded string (signatures, tx hashes, proofs, etc.). */
+type Hex = `0x${string}`;
+/** Network configuration for the Relayer SDK */
+type NetworkType = "hardhat" | "sepolia" | "mainnet";
+/** Security options for RelayerWeb. */
+interface RelayerWebSecurityConfig {
+    /** Resolve the current CSRF token. Called before each authenticated network request. */
+    getCsrfToken?: () => string;
+    /** Verify SHA-384 integrity of the CDN bundle. Defaults to `true`. Set to `false` only in test environments with mocked SDK scripts. */
+    integrityCheck?: boolean;
+}
+/** Configuration for RelayerWeb (browser backend) initialization. */
+interface RelayerWebConfig {
+    transports: Record<number, Partial<SDK.FhevmInstanceConfig>>;
+    /** Resolve the current chain ID. Called lazily before each operation; the worker is re-initialized when the value changes. */
+    getChainId: () => Promise<number>;
+    /** Security options (CSRF, CDN integrity). */
+    security?: RelayerWebSecurityConfig;
+    /** Optional logger for observing worker lifecycle and request timing. */
+    logger?: GenericLogger;
+}
+/** Result from encryption operation */
+interface EncryptResult {
+    handles: Uint8Array[];
+    inputProof: Uint8Array;
+}
+/** Parameters for encryption */
+interface EncryptParams {
+    values: bigint[];
+    contractAddress: Address;
+    userAddress: Address;
+}
+/** Parameters for user decryption */
+interface UserDecryptParams {
+    handles: string[];
+    contractAddress: Address;
+    signedContractAddresses: Address[];
+    privateKey: string;
+    publicKey: string;
+    signature: string;
+    signerAddress: Address;
+    startTimestamp: number;
+    durationDays: number;
+}
+/** Result from public decryption */
+interface PublicDecryptResult {
+    clearValues: Record<string, bigint>;
+    abiEncodedClearValues: string;
+    decryptionProof: Address;
+}
+/** Keypair for FHE operations */
+interface FHEKeypair {
+    publicKey: string;
+    privateKey: string;
+}
+/** EIP712 typed data structure */
+interface EIP712TypedData {
+    domain: {
+        name: string;
+        version: string;
+        chainId: number;
+        verifyingContract: Address;
+    };
+    types: {
+        [key: string]: Array<{
+            name: string;
+            type: string;
+        }>;
+    };
+    message: {
+        publicKey: string;
+        contractAddresses: string[];
+        startTimestamp: bigint;
+        durationDays: bigint;
+        extraData: string;
+    };
+}
+/** Parameters for delegated user decryption */
+interface DelegatedUserDecryptParams {
+    handles: string[];
+    contractAddress: Address;
+    signedContractAddresses: Address[];
+    privateKey: string;
+    publicKey: string;
+    signature: string;
+    delegatorAddress: Address;
+    delegateAddress: Address;
+    startTimestamp: number;
+    durationDays: number;
+}
+/** SDK status */
+type RelayerSDKStatus = "idle" | "initializing" | "ready" | "error";
+
+/**
+ * Framework-agnostic event decoders for confidential token contracts.
+ * No viem/ethers dependency — works with raw log data from any provider.
+ */
+
+/** Framework-agnostic log shape compatible with any Ethereum provider. */
+interface RawLog {
+    /** Indexed event topics (topic[0] is the event signature hash). */
+    readonly topics: readonly string[];
+    /** ABI-encoded non-indexed event data. */
+    readonly data: string;
+}
+/**
+ * Event topic0 constants (keccak256 of the canonical Solidity signature).
+ * Pass to `getLogs({ topics: [Object.values(Topics)] })` to fetch all events.
+ */
+declare const Topics: {
+    /** `ConfidentialTransfer(address indexed from, address indexed to, bytes32 indexed amount)` */
+    readonly ConfidentialTransfer: "0x67500e8d0ed826d2194f514dd0d8124f35648ab6e3fb5e6ed867134cffe661e9";
+    /** `Wrapped(uint64 mintAmount, uint256 amountIn, uint256 feeAmount, address indexed to_, uint256 indexed mintTxId)` */
+    readonly Wrapped: "0x1f7907f4d84043abe0fb7c74e8865ee5fe93fe4f691c54a7b8fa9d6fb17c7cba";
+    /** `UnwrapRequested(address indexed receiver, bytes32 amount)` */
+    readonly UnwrapRequested: "0x77d02d353c5629272875d11f1b34ec4c65d7430b075575b78cd2502034c469ee";
+    /** `UnwrappedFinalized(bytes32 indexed burntAmountHandle, ...)` */
+    readonly UnwrappedFinalized: "0xc64e7c81b18b674fc5b037d8a0041bfe3332d86c780a4688f404ee01fbabb152";
+    /** `UnwrappedStarted(bool returnVal, uint256 indexed requestId, ...)` */
+    readonly UnwrappedStarted: "0x3838891d4843c6d7f9f494570b6fd8843f4e3c3ddb817c1411760bd31b819806";
+};
+/** Decoded `ConfidentialTransfer` event — an encrypted token transfer. */
+interface ConfidentialTransferEvent {
+    readonly eventName: "ConfidentialTransfer";
+    /** Sender address. */
+    readonly from: string;
+    /** Receiver address. */
+    readonly to: string;
+    /** FHE ciphertext handle for the transferred amount. */
+    readonly encryptedAmountHandle: string;
+}
+/** Decoded `Wrapped` event — an ERC-20 shield (wrap) operation. */
+interface WrappedEvent {
+    readonly eventName: "Wrapped";
+    /** Confidential tokens minted. */
+    readonly mintAmount: bigint;
+    /** Underlying ERC-20 tokens deposited. */
+    readonly amountIn: bigint;
+    /** Fee deducted during wrapping. */
+    readonly feeAmount: bigint;
+    /** Receiver of the minted confidential tokens. */
+    readonly to: string;
+    /** On-chain mint transaction ID. */
+    readonly mintTxId: bigint;
+}
+/** Decoded `UnwrapRequested` event — an unshield request submitted. */
+interface UnwrapRequestedEvent {
+    readonly eventName: "UnwrapRequested";
+    /** Address that will receive the unwrapped ERC-20 tokens. */
+    readonly receiver: string;
+    /** FHE ciphertext handle for the requested unshield amount. */
+    readonly encryptedAmount: Address;
+}
+/** Decoded `UnwrappedFinalized` event — an unshield completed on-chain. */
+interface UnwrappedFinalizedEvent {
+    readonly eventName: "UnwrappedFinalized";
+    /** FHE handle of the burnt confidential balance. */
+    readonly burntAmountHandle: string;
+    /** Whether the finalization succeeded. */
+    readonly finalizeSuccess: boolean;
+    /** Whether the fee transfer succeeded. */
+    readonly feeTransferSuccess: boolean;
+    /** Amount of confidential tokens burnt. */
+    readonly burnAmount: bigint;
+    /** Amount of underlying ERC-20 tokens returned. */
+    readonly unwrapAmount: bigint;
+    /** Fee deducted during unwrapping. */
+    readonly feeAmount: bigint;
+    /** Next on-chain transaction ID. */
+    readonly nextTxId: bigint;
+}
+/** Decoded `UnwrappedStarted` event — the relayer began processing an unshield. */
+interface UnwrappedStartedEvent {
+    readonly eventName: "UnwrappedStarted";
+    /** Whether the unwrap start succeeded. */
+    readonly returnVal: boolean;
+    /** On-chain request ID. */
+    readonly requestId: bigint;
+    /** On-chain transaction ID. */
+    readonly txId: bigint;
+    /** Receiver address. */
+    readonly to: string;
+    /** Refund address (if applicable). */
+    readonly refund: string;
+    /** FHE handle of the requested amount. */
+    readonly requestedAmount: string;
+    /** FHE handle of the burn amount. */
+    readonly burnAmount: string;
+}
+/** Union of all decoded confidential token event types. */
+type OnChainEvent = ConfidentialTransferEvent | WrappedEvent | UnwrapRequestedEvent | UnwrappedFinalizedEvent | UnwrappedStartedEvent;
+/**
+ * ConfidentialTransfer(address indexed from, address indexed to, bytes32 indexed amount)
+ * All 3 params indexed → topics[1..3], no data.
+ */
+declare function decodeConfidentialTransfer(log: RawLog): ConfidentialTransferEvent | null;
+/**
+ * Wrapped(uint64 mintAmount, uint256 amountIn, uint256 feeAmount, address indexed to_, uint256 indexed mintTxId)
+ * Indexed: to_ (topics[1]), mintTxId (topics[2])
+ * Data: mintAmount (uint64, abi-encoded as uint256), amountIn, feeAmount
+ */
+declare function decodeWrapped(log: RawLog): WrappedEvent | null;
+/**
+ * UnwrapRequested(address indexed receiver, bytes32 amount)
+ * Indexed: receiver (topics[1])
+ * Data: amount (bytes32)
+ */
+declare function decodeUnwrapRequested(log: RawLog): UnwrapRequestedEvent | null;
+/**
+ * UnwrappedFinalized(bytes32 indexed burntAmountHandle, bool finalizeSuccess, bool feeTransferSuccess,
+ *                    uint64 burnAmount, uint256 unwrapAmount, uint256 feeAmount, uint256 indexed nextTxId)
+ * Indexed: burntAmountHandle (topics[1]), nextTxId (topics[2])
+ * Data: finalizeSuccess, feeTransferSuccess, burnAmount, unwrapAmount, feeAmount
+ */
+declare function decodeUnwrappedFinalized(log: RawLog): UnwrappedFinalizedEvent | null;
+/**
+ * UnwrappedStarted(bool returnVal, uint256 indexed requestId, uint256 indexed txId, address indexed to,
+ *                  address refund, bytes32 requestedAmount, bytes32 burnAmount)
+ * Indexed: requestId (topics[1]), txId (topics[2]), to (topics[3])
+ * Data: returnVal, refund, requestedAmount, burnAmount
+ */
+declare function decodeUnwrappedStarted(log: RawLog): UnwrappedStartedEvent | null;
+/**
+ * Try all decoders on a single log and return the first match, or `null`.
+ *
+ * @example
+ * ```ts
+ * const event = decodeOnChainEvent(log);
+ * if (event?.eventName === "ConfidentialTransfer") {
+ *   console.log(event.from, event.to);
+ * }
+ * ```
+ */
+declare function decodeOnChainEvent(log: RawLog): OnChainEvent | null;
+/**
+ * Batch-decode an array of logs, skipping unrecognized entries.
+ *
+ * @example
+ * ```ts
+ * const events = decodeOnChainEvents(receipt.logs);
+ * ```
+ */
+declare function decodeOnChainEvents(logs: readonly RawLog[]): OnChainEvent[];
+/**
+ * Find the first {@link UnwrapRequestedEvent} in a logs array.
+ *
+ * @example
+ * ```ts
+ * const event = findUnwrapRequested(receipt.logs);
+ * if (event) console.log(event.receiver, event.encryptedAmount);
+ * ```
+ */
+declare function findUnwrapRequested(logs: readonly RawLog[]): UnwrapRequestedEvent | null;
+/**
+ * Find the first {@link WrappedEvent} in a logs array.
+ *
+ * @example
+ * ```ts
+ * const event = findWrapped(receipt.logs);
+ * if (event) console.log(event.to, event.amountIn);
+ * ```
+ */
+declare function findWrapped(logs: readonly RawLog[]): WrappedEvent | null;
+/**
+ * All 5 confidential token event topic0 hashes.
+ * Pass to `getLogs({ topics: [TOKEN_TOPICS] })` to fetch
+ * all confidential token events in a single RPC call.
+ */
+declare const TOKEN_TOPICS: readonly ["0x67500e8d0ed826d2194f514dd0d8124f35648ab6e3fb5e6ed867134cffe661e9", "0x1f7907f4d84043abe0fb7c74e8865ee5fe93fe4f691c54a7b8fa9d6fb17c7cba", "0x77d02d353c5629272875d11f1b34ec4c65d7430b075575b78cd2502034c469ee", "0xc64e7c81b18b674fc5b037d8a0041bfe3332d86c780a4688f404ee01fbabb152", "0x3838891d4843c6d7f9f494570b6fd8843f4e3c3ddb817c1411760bd31b819806"];
+
+/** Framework-agnostic transaction receipt (only the fields the SDK needs). */
+interface TransactionReceipt {
+    /** Event logs emitted during the transaction. */
+    readonly logs: readonly RawLog[];
+}
+/** Result of a write operation: the tx hash and its mined receipt. */
+interface TransactionResult {
+    /** The transaction hash. */
+    txHash: Hex;
+    /** The mined transaction receipt. */
+    receipt: TransactionReceipt;
+}
+/**
+ * Minimal contract call configuration.
+ * Matches the shape returned by contract call builder functions in `src/contracts/`.
+ */
+interface ContractCallConfig {
+    /** Target contract address. */
+    readonly address: Address;
+    /** ABI fragment for the function being called. */
+    readonly abi: readonly unknown[];
+    /** Solidity function name. */
+    readonly functionName: string;
+    /** Encoded function arguments. */
+    readonly args: readonly unknown[];
+    /** Native value to send with the transaction (for payable functions). */
+    readonly value?: bigint;
+    /** Gas limit override. */
+    readonly gas?: bigint;
+}
+/**
+ * Framework-agnostic signer interface.
+ * Wallet devs implement this with their library of choice.
+ * The React SDK ships pre-built adapters for wagmi/viem/ethers.
+ */
+interface GenericSigner {
+    /** Return the chain ID of the connected network. */
+    getChainId(): Promise<number>;
+    /** The connected wallet address. */
+    getAddress: () => Promise<Address>;
+    /** Sign EIP-712 typed data (used for decrypt authorization). */
+    signTypedData(typedData: EIP712TypedData): Promise<Hex>;
+    /** Send a write transaction and return the tx hash. */
+    writeContract<C extends ContractCallConfig>(config: C): Promise<Hex>;
+    /** Execute a read-only call and return the decoded result. */
+    readContract<T = unknown, C extends ContractCallConfig = ContractCallConfig>(config: C): Promise<T>;
+    /** Wait for a transaction to be mined and return its receipt. */
+    waitForTransactionReceipt(hash: Hex): Promise<TransactionReceipt>;
+}
+/** Pluggable key-value store for persisting FHE credentials. */
+interface GenericStringStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+/** Stored FHE credential data (serialized as JSON in the credential store). */
+interface StoredCredentials {
+    /** FHE public key (hex-encoded). */
+    publicKey: string;
+    /** FHE private key (hex-encoded, encrypted at rest via AES-GCM). */
+    privateKey: string;
+    /** EIP-712 signature authorizing decryption. */
+    signature: string;
+    /** Contract addresses this credential is authorized for. */
+    contractAddresses: Address[];
+    /** Unix timestamp (seconds) when the credential became valid. */
+    startTimestamp: number;
+    /** Number of days the credential remains valid. */
+    durationDays: number;
+}
+/** Progress callbacks for multi-step unshield operations. */
+interface UnshieldCallbacks {
+    /** Fired after the unwrap transaction is submitted. */
+    onUnwrapSubmitted?: (txHash: Hex) => void;
+    /** Fired when the finalization step begins (receipt parsed, about to finalize). */
+    onFinalizing?: () => void;
+    /** Fired after the finalize transaction is submitted. */
+    onFinalizeSubmitted?: (txHash: Hex) => void;
+}
+
+export { findUnwrapRequested as $, TOKEN_TOPICS as A, Topics as B, type ContractCallConfig as C, type DelegatedUserDecryptParams as D, type EIP712TypedData as E, type FHEKeypair as F, type GenericSigner as G, type Hex as H, type UnwrapRequestedEvent as I, type UnwrappedFinalizedEvent as J, type UnwrappedStartedEvent as K, type WrappedEvent as L, decodeConfidentialTransfer as M, type NetworkType as N, type OnChainEvent as O, type PublicDecryptResult as P, decodeOnChainEvent as Q, type RequestZKProofVerificationResponseData as R, type StoredCredentials as S, type TransactionReceipt as T, type UserDecryptParams as U, decodeOnChainEvents as V, type WorkerRequest as W, decodeUnwrapRequested as X, decodeUnwrappedFinalized as Y, decodeUnwrappedStarted as Z, decodeWrapped as _, type EncryptParams as a, findWrapped as a0, type EncryptResult as b, type GenericLogger as c, type WorkerRequestType as d, type WorkerResponse as e, type GenerateKeypairResponseData as f, type CreateEIP712Payload as g, type CreateEIP712ResponseData as h, type EncryptPayload as i, type EncryptResponseData as j, type UserDecryptPayload as k, type UserDecryptResponseData as l, type PublicDecryptResponseData as m, type CreateDelegatedEIP712Payload as n, type CreateDelegatedEIP712ResponseData as o, type DelegatedUserDecryptPayload as p, type DelegatedUserDecryptResponseData as q, type GetPublicKeyResponseData as r, type GetPublicParamsResponseData as s, type GenericStringStorage as t, type RelayerWebConfig as u, type TransactionResult as v, type UnshieldCallbacks as w, type RawLog as x, type ConfidentialTransferEvent as y, type RelayerSDKStatus as z };