@inco/js 0.9.0-devnet-test-10 → 0.10.0-devnet-2

package/dist/types/kms/thresholdPromises.d.ts

@@ -1,7 +1,8 @@
 /**
- * Executes promises and returns results as soon as threshold is reached
+ * Executes all promises and returns all successful results.
+ * Rejects early if it becomes mathematically impossible to reach the threshold.
  * @param promises Array of promises to execute
- * @param threshold Number of successful responses needed
- * @returns Promise that resolves with threshold number of results
+ * @param threshold Minimum number of successful responses required
+ * @returns Promise that resolves with all successful results (length >= threshold)
  */
 export declare function executeWithThreshold<T>(promises: Promise<T>[], threshold: number): Promise<T[]>;

package/dist/types/lite/attested-compute.d.ts

@@ -1,6 +1,6 @@
-import { ATTESTED_COMPUTE_DOMAIN_NAME, DEFAULT_ATTESTED_COMPUTE_DOMAIN_VERSION, type IncoLiteAttestedComputeArgs } from '../attestedcompute/attested-compute.js';
+import { ATTESTED_COMPUTE_DOMAIN_NAME, type IncoLiteAttestedComputeArgs } from '../attestedcompute/attested-compute.js';
 import type { AttestedCompute, AttestedComputeFnArgs } from '../attestedcompute/types.js';
 import { AttestedComputeSupportedOps } from '../attestedcompute/types.js';
 import type { AttestedDecryptFnArgs } from '../attesteddecrypt/types.js';
-export { ATTESTED_COMPUTE_DOMAIN_NAME, AttestedComputeSupportedOps, DEFAULT_ATTESTED_COMPUTE_DOMAIN_VERSION, };
+export { ATTESTED_COMPUTE_DOMAIN_NAME, AttestedComputeSupportedOps };
 export type { AttestedCompute, AttestedComputeFnArgs, AttestedDecryptFnArgs, IncoLiteAttestedComputeArgs, };

package/dist/types/lite/attested-decrypt.d.ts

@@ -1,4 +1,4 @@
 import { type IncoLiteAttestedDecryptorArgs } from '../attesteddecrypt/attested-decrypt.js';
 export type { IncoLiteAttestedDecryptorArgs };
-import { ATTESTED_DECRYPT_DOMAIN_NAME, DEFAULT_ATTESTED_DECRYPT_DOMAIN_VERSION } from '../attesteddecrypt/attested-decrypt.js';
-export { ATTESTED_DECRYPT_DOMAIN_NAME, DEFAULT_ATTESTED_DECRYPT_DOMAIN_VERSION, };
+import { ATTESTED_DECRYPT_DOMAIN_NAME } from '../attesteddecrypt/attested-decrypt.js';
+export { ATTESTED_DECRYPT_DOMAIN_NAME };

package/dist/types/lite/hadu.d.ts

@@ -1,4 +1,4 @@
-import { PlaintextWithContext } from '../encryption/index.js';
+import { PlaintextWithContext } from '../encryption/encryption.js';
 import { InputPayload } from '../generated/es/inco/covalidator/compute/v1/types_pb.js';
 export declare function encodeInput({ plaintext, context, }: PlaintextWithContext): Uint8Array;
 export declare function decodeInput(input: Uint8Array): InputPayload;

package/dist/types/lite/index.d.ts

@@ -1,9 +1,13 @@
+export { AttestedComputeError } from '../attestedcompute/types.js';
+export { AttestedDecryptError } from '../attesteddecrypt/types.js';
+export { AttestedRevealError } from '../attestedreveal/types.js';
 export * from '../generated/abis/lightning.js';
 export type { AttestedComputeRequest, AttestedDecryptRequest, KmsService, } from '../generated/es/inco/kms/lite/v1/kms_service_pb.js';
 export type { HandleWithProof } from '../generated/es/inco/kms/lite/v1/types_pb.js';
 export * from './attested-compute.js';
 export * from './attested-decrypt.js';
 export * from './deployments.js';
-export * from './hadu.js';
 export * from './lightning.js';
-export { TEST_NETWORK_SEED_KEY, TEST_NETWORK_XWING_PUBKEY, XWING_PUBLIC_KEY_SIZE, decodeXwingPrivateKey, decodeXwingPublicKey, decrypt, deriveXwingKeypairFromSeed, encodeXwingPublicKey, encrypt, generateXwingKeypair, getXwingDecryptor, getXwingEncryptor, type XwingDecryptorArgs, type XwingEncryptorArgs, type XwingKeypair, } from './xwing.js';
+export type { AttestedOpts, AttestedOptsDecrypted, AttestedOptsEncrypted, AttestedOptsEphemeral, AttestedRevealOpts, AttestedWithVoucherOpts, AttestedWithVoucherOptsDecrypted, AttestedWithVoucherOptsEncrypted, AttestedWithVoucherOptsEphemeral, } from './types.js';
+export { generateXwingKeypair } from './xwing.js';
+export type { XwingKeypair } from './xwing.js';

package/dist/types/lite/lightning.d.ts

@@ -4,14 +4,14 @@ import { AllowanceVoucherWithSig } from '../advancedacl/types.js';
 import { AttestedComputeOP } from '../attestedcompute/types.js';
 import { DecryptionAttestation, EncryptedDecryptionAttestation } from '../attesteddecrypt/index.js';
 import { Address, HexString } from '../binary.js';
-import { EncryptionScheme, SupportedFheType } from '../encryption/index.js';
+import { EListDecryptionAttestation, EncryptedEListDecryptionAttestation } from '../elistattesteddecrypt/index.js';
+import { EncryptionScheme, SupportedFheType } from '../encryption/encryption.js';
 import { incoVerifierAbi } from '../generated/abis/verifier.js';
 import { lightningDeployments } from '../generated/lightning.js';
 import { localNodeLightningConfig } from '../generated/local-node.js';
 import { FheType } from '../handle.js';
 import { LocalNodeEnv } from '../local/index.js';
-import { BackoffConfig } from '../retry.js';
-import { XwingKeypair } from './xwing.js';
+import type { AttestedOptsDecrypted, AttestedOptsEncrypted, AttestedOptsEphemeral, AttestedRevealOpts, AttestedWithVoucherOptsDecrypted, AttestedWithVoucherOptsEncrypted, AttestedWithVoucherOptsEphemeral } from './types.js';
 type TupleToUnion<T> = T extends readonly unknown[] ? T[number] : never;
 type Deployment = TupleToUnion<typeof lightningDeployments>;
 type DistributedPick<T, K> = T extends any ? Pick<T, Extract<keyof T, K>> : never;
@@ -36,7 +36,7 @@ export type CustomConfig = {
     chainId: number;
     covalidatorUrls: string[];
     signers?: Address[];
-    hostChainRpcUrl?: string;
+    hostChainRpcUrls?: readonly string[] | string[];
     senderPrivateKey?: HexString;
 };
 export type CustomDeployment = DeploymentSlice & CustomConfig;
@@ -58,6 +58,7 @@ export declare class Lightning<T extends DeploymentSlice = DeploymentSlice> {
     private readonly signers;
     private readonly threshold;
     private readonly networkPubkey;
+    private readonly publicClient;
     readonly executorAddress: Address;
     readonly chainId: bigint;
     private readonly kmsQuorumClient;
@@ -67,14 +68,19 @@ export declare class Lightning<T extends DeploymentSlice = DeploymentSlice> {
     private getEncryptor;
     /**
      * Get the encryption scheme version used by this Lightning instance.
-     * Returns 1 for ECIES or 2 for X-Wing.
+     * Returns the X-Wing encryption scheme identifier.
      * This is a convenience method to get the encryption scheme used by this Lightning instance.
      */
     getEncryptionScheme(): Promise<EncryptionScheme>;
     /**
      * Get a Lightning instance bound to the latest Lightning deployment for the Base Sepolia testnet.
+     *
+     * @param options.hostChainRpcUrls optional list of RPC URLs for the host chain. When multiple URLs are
+     *   provided, viem's fallback transport is used and providers are tried in order on failure.
      */
-    static baseSepoliaTestnet(): Promise<Lightning<Deployment>>;
+    static baseSepoliaTestnet(options?: {
+        hostChainRpcUrls?: readonly string[];
+    }): Promise<Lightning<Deployment>>;
     /**
      * Get a Lightning instance bound to our canonical Anvil-based test node and test Covalidator node
      *
@@ -101,8 +107,12 @@ export declare class Lightning<T extends DeploymentSlice = DeploymentSlice> {
      * Get a Lightning deployment by name or executor address on a particular chain.
      *
      * @param id this is an object containing either the pair of name and chainId or the executorAddress and chainId
+     * @param options.hostChainRpcUrls optional list of RPC URLs for the host chain. When multiple URLs are
+     *   provided, viem's fallback transport is used and providers are tried in order on failure.
      */
-    static at(id: DeploymentId): Promise<Lightning<Deployment>>;
+    static at(id: DeploymentId, options?: {
+        hostChainRpcUrls?: readonly string[];
+    }): Promise<Lightning<Deployment>>;
     /**
      * Get a Lightning deployment for a local or custom node
      *
@@ -124,12 +134,17 @@ export declare class Lightning<T extends DeploymentSlice = DeploymentSlice> {
      * will not be compatible with the new version.
      *
      * @param pepper the pepper to use to filter the deployments
-     * @param chain the chain to use to filter the deployments
+     * @param chainId the chainId to use to filter the deployments
+     * @param options.hostChainRpcUrls optional list of RPC URLs for the host chain. When multiple URLs are
+     *   provided, viem's fallback transport is used and providers are tried in order on failure.
      */
-    static latest<P extends Pepper>(pepper: P, chainId: ChainId): Promise<Lightning<Deployment>>;
+    static latest<P extends Pepper>(pepper: P, chainId: ChainId, options?: {
+        hostChainRpcUrls?: readonly string[];
+    }): Promise<Lightning<Deployment>>;
+    /** Returns a shallow copy of the deployment configuration this Lightning instance is bound to. */
     get deployment(): T;
     /**
-     * Encrypt a value using the network's public key (ECIES or X-Wing).
+     * Encrypt a value using the network's public key (X-Wing).
      * The encryption scheme is automatically detected based on the public key length.
      *
      * @param value a boolean or numeric value to encrypt
@@ -218,39 +233,37 @@ export declare class Lightning<T extends DeploymentSlice = DeploymentSlice> {
      *
      * @example Reencrypt for a delegate
      * ```ts
-     * const encrypted = await lightning.attestedDecrypt(walletClient, [handle], delegatePubKey);
+     * const encrypted = await lightning.attestedDecrypt(walletClient, [handle], {
+     *   reencryptPubKey: delegatePubKey,
+     * });
      * console.log(encrypted[0].encryptedPlaintext.ciphertext.value);
      * ```
      *
      * @example Reencrypt and decrypt locally
      * ```ts
-     * const decrypted = await lightning.attestedDecrypt(
-     *   walletClient,
-     *   [handle],
-     *   keypair.encodePublicKey(),
-     *   keypair,
-     * );
+     * const decrypted = await lightning.attestedDecrypt(walletClient, [handle], {
+     *   reencryptPubKey: keypair.encodePublicKey(),
+     *   reencryptKeypair: keypair,
+     * });
      * console.log(decrypted[0].plaintext.value);
      * ```
      */
-    attestedDecrypt(walletClient: WalletClient<Transport, Chain, Account>, handles: HexString[], backoffConfig?: Partial<BackoffConfig>): Promise<Array<DecryptionAttestation<EncryptionScheme, SupportedFheType>>>;
-    attestedDecrypt(walletClient: WalletClient<Transport, Chain, Account>, handles: HexString[], reencryptPubKey: Uint8Array, backoffConfig?: Partial<BackoffConfig>): Promise<Array<EncryptedDecryptionAttestation<EncryptionScheme, SupportedFheType>>>;
-    attestedDecrypt(walletClient: WalletClient<Transport, Chain, Account>, handles: HexString[], reencryptPubKey: Uint8Array, reencryptKeypair: XwingKeypair, backoffConfig?: Partial<BackoffConfig>): Promise<Array<DecryptionAttestation<EncryptionScheme, SupportedFheType>>>;
+    attestedDecrypt(walletClient: WalletClient<Transport, Chain, Account>, handles: HexString[], opts?: AttestedOptsEphemeral): Promise<Array<DecryptionAttestation<EncryptionScheme, SupportedFheType>>>;
+    attestedDecrypt(walletClient: WalletClient<Transport, Chain, Account>, handles: HexString[], opts: AttestedOptsEncrypted): Promise<Array<EncryptedDecryptionAttestation<EncryptionScheme, SupportedFheType>>>;
+    attestedDecrypt(walletClient: WalletClient<Transport, Chain, Account>, handles: HexString[], opts: AttestedOptsDecrypted): Promise<Array<DecryptionAttestation<EncryptionScheme, SupportedFheType>>>;
     /**
      * Requests attested decrypts using a voucher-backed session key.
      *
      * @param ephemeralAccount Session Account matching the voucher grantee.
      * @param allowanceVoucherWithSig Signed allowance voucher.
-     * @param ethClient - A public eth client or eth wallet client used for signing the attested decrypt request
      * @param handles Handles to decrypt.
-     * @param options Optional reencryption/backoff configuration.
+     * @param opts Optional reencryption/backoff configuration.
      *
      * @example Plaintext results
      * ```ts
      * const attestations = await lightning.attestedDecryptWithVoucher(
      *   ephemeralAccount,
      *   voucher,
-     *   ethClient,
      *   [handle],
      * );
      * ```
@@ -260,15 +273,36 @@ export declare class Lightning<T extends DeploymentSlice = DeploymentSlice> {
      * const encrypted = await lightning.attestedDecryptWithVoucher(
      *   ephemeralAccount,
      *   voucher,
-     *   ethClient,
      *   [handle],
      *   { reencryptPubKey: delegateKeypair.encodePublicKey() },
      * );
      * ```
+     *
+     * @example Reencrypt and decrypt locally
+     * ```ts
+     * const decrypted = await lightning.attestedDecryptWithVoucher(
+     *   ephemeralAccount,
+     *   voucher,
+     *   [handle],
+     *   { reencryptPubKey: keypair.encodePublicKey(), reencryptKeypair: keypair },
+     * );
+     * ```
+     */
+    attestedDecryptWithVoucher(ephemeralAccount: PrivateKeyAccount, allowanceVoucherWithSig: AllowanceVoucherWithSig, handles: HexString[], opts?: AttestedWithVoucherOptsEphemeral): Promise<Array<DecryptionAttestation<EncryptionScheme, SupportedFheType>>>;
+    attestedDecryptWithVoucher(ephemeralAccount: PrivateKeyAccount, allowanceVoucherWithSig: AllowanceVoucherWithSig, handles: HexString[], opts: AttestedWithVoucherOptsEncrypted): Promise<Array<EncryptedDecryptionAttestation<EncryptionScheme, SupportedFheType>>>;
+    attestedDecryptWithVoucher(ephemeralAccount: PrivateKeyAccount, allowanceVoucherWithSig: AllowanceVoucherWithSig, handles: HexString[], opts: AttestedWithVoucherOptsDecrypted): Promise<Array<DecryptionAttestation<EncryptionScheme, SupportedFheType>>>;
+    eListAttestedDecrypt(walletClient: WalletClient<Transport, Chain, Account>, handle: HexString, opts?: AttestedOptsEphemeral): Promise<EListDecryptionAttestation<EncryptionScheme, SupportedFheType>>;
+    eListAttestedDecrypt(walletClient: WalletClient<Transport, Chain, Account>, handle: HexString, opts: AttestedOptsEncrypted): Promise<EncryptedEListDecryptionAttestation<EncryptionScheme, SupportedFheType>>;
+    eListAttestedDecrypt(walletClient: WalletClient<Transport, Chain, Account>, handle: HexString, opts: AttestedOptsDecrypted): Promise<EListDecryptionAttestation<EncryptionScheme, SupportedFheType>>;
+    /**
+     * Reveal a single elist handle without wallet authentication.
+     * Returns plaintext values along with an attestation of the checksum.
+     *
+     * @param handle - The elist handle to reveal
+     * @param opts - Optional backoff configuration
+     * @returns The elist decryption attestation with plaintext values
      */
-    attestedDecryptWithVoucher(ephemeralAccount: PrivateKeyAccount, allowanceVoucherWithSig: AllowanceVoucherWithSig, ethClient: PublicClient<Transport, Chain> | WalletClient<Transport, Chain, Account>, handles: HexString[], requesterArgData?: HexString, backoffConfig?: Partial<BackoffConfig>): Promise<Array<DecryptionAttestation<EncryptionScheme, SupportedFheType>>>;
-    attestedDecryptWithVoucher(ephemeralAccount: PrivateKeyAccount, allowanceVoucherWithSig: AllowanceVoucherWithSig, ethClient: PublicClient<Transport, Chain> | WalletClient<Transport, Chain, Account>, handles: HexString[], reencryptPubKey: Uint8Array, requesterArgData?: HexString, backoffConfig?: Partial<BackoffConfig>): Promise<Array<EncryptedDecryptionAttestation<EncryptionScheme, SupportedFheType>>>;
-    attestedDecryptWithVoucher(ephemeralAccount: PrivateKeyAccount, allowanceVoucherWithSig: AllowanceVoucherWithSig, ethClient: PublicClient<Transport, Chain> | WalletClient<Transport, Chain, Account>, handles: HexString[], reencryptPubKey: Uint8Array, reencryptKeypair: XwingKeypair, requesterArgData?: HexString, backoffConfig?: Partial<BackoffConfig>): Promise<Array<DecryptionAttestation<EncryptionScheme, SupportedFheType>>>;
+    eListAttestedReveal(handle: HexString, opts?: AttestedRevealOpts): Promise<EListDecryptionAttestation<EncryptionScheme, SupportedFheType>>;
     /**
      * Get an attested compute for the given wallet client.
      *
@@ -276,7 +310,7 @@ export declare class Lightning<T extends DeploymentSlice = DeploymentSlice> {
      * @param lhsHandle - The handle to compute
      * @param op - The operation to perform
      * @param rhsPlaintext - The plaintext to compute with
-     * @param backoffConfig - The backoff configuration for the attested compute request
+     * @param opts - Optional configuration (reencryption keys and/or backoff config)
      * @returns The decryption attestation
      *
      * @example Plaintext result
@@ -296,7 +330,7 @@ export declare class Lightning<T extends DeploymentSlice = DeploymentSlice> {
      *   lhsHandle,
      *   op,
      *   rhsPlaintext,
-     *   delegatePubKey,
+     *   { reencryptPubKey: delegatePubKey },
      * );
      * console.log(encrypted.encryptedPlaintext.ciphertext.value);
      * ```
@@ -308,15 +342,14 @@ export declare class Lightning<T extends DeploymentSlice = DeploymentSlice> {
      *   lhsHandle,
      *   op,
      *   rhsPlaintext,
-     *   keypair.encodePublicKey(),
-     *   keypair,
+     *   { reencryptPubKey: keypair.encodePublicKey(), reencryptKeypair: keypair },
      * );
      * console.log(decrypted.plaintext.value);
      * ```
      */
-    attestedCompute(walletClient: WalletClient<Transport, Chain, Account>, lhsHandle: HexString, op: AttestedComputeOP, rhsPlaintext: bigint | boolean, backoffConfig?: Partial<BackoffConfig>): Promise<DecryptionAttestation<EncryptionScheme, SupportedFheType>>;
-    attestedCompute(walletClient: WalletClient<Transport, Chain, Account>, lhsHandle: HexString, op: AttestedComputeOP, rhsPlaintext: bigint | boolean, reencryptPubKey: Uint8Array, backoffConfig?: Partial<BackoffConfig>): Promise<EncryptedDecryptionAttestation<EncryptionScheme, SupportedFheType>>;
-    attestedCompute(walletClient: WalletClient<Transport, Chain, Account>, lhsHandle: HexString, op: AttestedComputeOP, rhsPlaintext: bigint | boolean, reencryptPubKey: Uint8Array, reencryptKeypair: XwingKeypair, backoffConfig?: Partial<BackoffConfig>): Promise<DecryptionAttestation<EncryptionScheme, SupportedFheType>>;
+    attestedCompute(walletClient: WalletClient<Transport, Chain, Account>, lhsHandle: HexString, op: AttestedComputeOP, rhsPlaintext: bigint | boolean, opts?: AttestedOptsEphemeral): Promise<DecryptionAttestation<EncryptionScheme, SupportedFheType>>;
+    attestedCompute(walletClient: WalletClient<Transport, Chain, Account>, lhsHandle: HexString, op: AttestedComputeOP, rhsPlaintext: bigint | boolean, opts: AttestedOptsEncrypted): Promise<EncryptedDecryptionAttestation<EncryptionScheme, SupportedFheType>>;
+    attestedCompute(walletClient: WalletClient<Transport, Chain, Account>, lhsHandle: HexString, op: AttestedComputeOP, rhsPlaintext: bigint | boolean, opts: AttestedOptsDecrypted): Promise<DecryptionAttestation<EncryptionScheme, SupportedFheType>>;
     /**
      * Performs attested compute via a voucher-backed session key.
      *
@@ -325,7 +358,6 @@ export declare class Lightning<T extends DeploymentSlice = DeploymentSlice> {
      * const attestation = await lightning.attestedComputeWithVoucher(
      *   ephemeralAccount,
      *   voucher,
-     *   ethClient,
      *   lhsHandle,
      *   AttestedComputeSupportedOps.Eq,
      *   true,
@@ -340,7 +372,7 @@ export declare class Lightning<T extends DeploymentSlice = DeploymentSlice> {
      *   lhsHandle,
      *   AttestedComputeSupportedOps.Eq,
      *   true,
-     *   delegatePubKey,
+     *   { reencryptPubKey: delegatePubKey },
      * );
      * console.log(encrypted.encryptedPlaintext.ciphertext.value);
      * ```
@@ -353,15 +385,14 @@ export declare class Lightning<T extends DeploymentSlice = DeploymentSlice> {
      *   lhsHandle,
      *   AttestedComputeSupportedOps.Eq,
      *   true,
-     *   keypair.encodePublicKey(),
-     *   keypair,
+     *   { reencryptPubKey: keypair.encodePublicKey(), reencryptKeypair: keypair },
      * );
      * console.log(decrypted.plaintext.value);
      * ```
      */
-    attestedComputeWithVoucher(ephemeralAccount: PrivateKeyAccount, allowanceVoucherWithSig: AllowanceVoucherWithSig, ethClient: PublicClient<Transport, Chain> | WalletClient<Transport, Chain, Account>, lhsHandle: HexString, op: AttestedComputeOP, rhsPlaintext: bigint | boolean, requesterArgData?: HexString, backoffConfig?: Partial<BackoffConfig>): Promise<DecryptionAttestation<EncryptionScheme, SupportedFheType>>;
-    attestedComputeWithVoucher(ephemeralAccount: PrivateKeyAccount, allowanceVoucherWithSig: AllowanceVoucherWithSig, ethClient: PublicClient<Transport, Chain> | WalletClient<Transport, Chain, Account>, lhsHandle: HexString, op: AttestedComputeOP, rhsPlaintext: bigint | boolean, reencryptPubKey: Uint8Array, requesterArgData?: HexString, backoffConfig?: Partial<BackoffConfig>): Promise<EncryptedDecryptionAttestation<EncryptionScheme, SupportedFheType>>;
-    attestedComputeWithVoucher(ephemeralAccount: PrivateKeyAccount, allowanceVoucherWithSig: AllowanceVoucherWithSig, ethClient: PublicClient<Transport, Chain> | WalletClient<Transport, Chain, Account>, lhsHandle: HexString, op: AttestedComputeOP, rhsPlaintext: bigint | boolean, reencryptPubKey: Uint8Array, reencryptKeypair: XwingKeypair, requesterArgData?: HexString, backoffConfig?: Partial<BackoffConfig>): Promise<DecryptionAttestation<EncryptionScheme, SupportedFheType>>;
+    attestedComputeWithVoucher(ephemeralAccount: PrivateKeyAccount, allowanceVoucherWithSig: AllowanceVoucherWithSig, lhsHandle: HexString, op: AttestedComputeOP, rhsPlaintext: bigint | boolean, opts?: AttestedWithVoucherOptsEphemeral): Promise<DecryptionAttestation<EncryptionScheme, SupportedFheType>>;
+    attestedComputeWithVoucher(ephemeralAccount: PrivateKeyAccount, allowanceVoucherWithSig: AllowanceVoucherWithSig, lhsHandle: HexString, op: AttestedComputeOP, rhsPlaintext: bigint | boolean, opts: AttestedWithVoucherOptsEncrypted): Promise<EncryptedDecryptionAttestation<EncryptionScheme, SupportedFheType>>;
+    attestedComputeWithVoucher(ephemeralAccount: PrivateKeyAccount, allowanceVoucherWithSig: AllowanceVoucherWithSig, lhsHandle: HexString, op: AttestedComputeOP, rhsPlaintext: bigint | boolean, opts: AttestedWithVoucherOptsDecrypted): Promise<DecryptionAttestation<EncryptionScheme, SupportedFheType>>;
     /**
      * Get an decryption of publicly revealed handles.
      *
@@ -371,31 +402,49 @@ export declare class Lightning<T extends DeploymentSlice = DeploymentSlice> {
      *
      * @example
      * ```typescript
-     * const response = await lightning.attestedReveal([handle1, handle2], ethClient);
+     * const response = await lightning.attestedReveal([handle1, handle2]);
      * const { plaintext, covalidatorSignature } = response[0];
      * ```
      */
-    attestedReveal(handles: HexString[], backoffConfig?: Partial<BackoffConfig>): Promise<Array<DecryptionAttestation<EncryptionScheme, SupportedFheType>>>;
+    attestedReveal(handles: HexString[], opts?: AttestedRevealOpts): Promise<Array<DecryptionAttestation<EncryptionScheme, SupportedFheType>>>;
     /**
      * Get the GRPC endpoint for the covalidator that services this deployment.
      */
     static getCovalidatorUrls(deployment: DeploymentSlice & {
         pepper: string;
-    }, threshold: number): string[];
+        majorVersion: number;
+    }, signers: Address[]): string[];
     private static isIdByName;
     private static plaintextFromValue;
+    /**
+     * Reads the network public key from the on-chain Inco Verifier contract.
+     *
+     * Falls back to the legacy `eciesPubkey()` getter for older contract versions.
+     *
+     * @param client - A viem public client connected to the host chain.
+     * @param executorAddress - The address of the Inco Lightning executor contract.
+     * @returns The network public key as a hex string.
+     */
     static getNetworkPubkey(client: PublicClient, executorAddress: Address): Promise<HexString>;
+    /**
+     * Resolves the Inco Verifier contract instance associated with a Lightning executor.
+     *
+     * Reads the `incoVerifier` address from the executor contract and returns a typed contract handle.
+     *
+     * @param client - A viem public client connected to the host chain.
+     * @param executorAddress - The address of the Inco Lightning executor contract.
+     * @returns A viem contract instance bound to the Inco Verifier ABI.
+     */
     static getIncoVerifierContract(client: PublicClient, executorAddress: Address): Promise<GetContractReturnType<typeof incoVerifierAbi, PublicClient, Address>>;
     /**
-     * Retrieves the verifier contract details including threshold, signers, and ECIES public key from the Inco Verifier contract.
+     * Retrieves the verifier contract details including threshold, signers, and XWING public key from the Inco Verifier contract.
      *
      * @param executorAddress The address of the Inco Lightning executor contract.
      * @param client The public client to interact with the blockchain.
-     * @returns An object containing the threshold, signers, and ECIES public key.
+     * @returns An object containing the threshold, signers, and XWING public key.
      */
     private static getVerifierContractDetails;
     private static getChainConfig;
     private static supportsThresholdRetrieval;
-    private static getDefaultThresholdAndSigners;
 }
 export {};

package/dist/types/lite/types.d.ts

@@ -0,0 +1,47 @@
+import type { HexString } from '../binary.js';
+import type { BackoffConfig } from '../retry.js';
+import type { XwingKeypair } from './xwing.js';
+/**
+ * Options for attested methods when no reencrypt keys are provided.
+ * The KMS generates an ephemeral keypair and returns plaintext.
+ */
+export type AttestedOptsEphemeral = {
+    reencryptPubKey?: never;
+    reencryptKeypair?: never;
+    backoffConfig?: Partial<BackoffConfig>;
+};
+/**
+ * Options for attested methods when only a reencrypt public key is provided.
+ * The KMS encrypts the result under the provided key; caller receives ciphertext.
+ */
+export type AttestedOptsEncrypted = {
+    reencryptPubKey: Uint8Array;
+    reencryptKeypair?: never;
+    backoffConfig?: Partial<BackoffConfig>;
+};
+/**
+ * Options for attested methods when both a reencrypt key and keypair are provided.
+ * The KMS reencrypts under the public key; the SDK decrypts locally using the keypair.
+ */
+export type AttestedOptsDecrypted = {
+    reencryptPubKey: Uint8Array;
+    reencryptKeypair: XwingKeypair;
+    backoffConfig?: Partial<BackoffConfig>;
+};
+/** Union of all valid opts for attestedDecrypt / attestedCompute. */
+export type AttestedOpts = AttestedOptsEphemeral | AttestedOptsEncrypted | AttestedOptsDecrypted;
+/** Extends the base opts with voucher-specific fields for WithVoucher methods. */
+export type AttestedWithVoucherOptsEphemeral = AttestedOptsEphemeral & {
+    requesterArgData?: HexString;
+};
+export type AttestedWithVoucherOptsEncrypted = AttestedOptsEncrypted & {
+    requesterArgData?: HexString;
+};
+export type AttestedWithVoucherOptsDecrypted = AttestedOptsDecrypted & {
+    requesterArgData?: HexString;
+};
+export type AttestedWithVoucherOpts = AttestedWithVoucherOptsEphemeral | AttestedWithVoucherOptsEncrypted | AttestedWithVoucherOptsDecrypted;
+/** Options for attestedReveal. */
+export type AttestedRevealOpts = {
+    backoffConfig?: Partial<BackoffConfig>;
+};

package/dist/types/lite/xwing.d.ts

@@ -5,8 +5,33 @@ import { PubKeyEncodable } from '../reencryption/index.js';
  * Combining ML-KEM-768 (1184 bytes) and X25519 (32 bytes).
  */
 export declare const XWING_PUBLIC_KEY_SIZE: number;
+/**
+ * WARNING: TEST KEY - DO NOT USE IN PRODUCTION
+ * This is a well-known test seed (all zeros) that provides NO security.
+ * Anyone can derive the private key from this seed and decrypt all data.
+ * Only use for local development and testing.
+ */
 export declare const TEST_NETWORK_SEED_KEY = "0x0000000000000000000000000000000000000000000000000000000000000000";
+/**
+ * WARNING: TEST KEY - DO NOT USE IN PRODUCTION
+ * This is the public key derived from TEST_NETWORK_SEED_KEY (all zeros).
+ * Data encrypted with this key can be decrypted by anyone who knows the seed.
+ * Only use for local development and testing.
+ *
+ * Generated from Go with seed of all zeros using HPKE layer: hpke.KEM_XWING.Scheme().DeriveKeyPair(seed)
+ * This matches the key used in covalidator's GetXwingPrivateKeyForTesting() via DeriveXwingPrivateKey
+ */
 export declare const TEST_NETWORK_XWING_PUBKEY = "0xca882388911c7c762aafc20debd63e845b3bed28c9d5262cdea7771fb31bd660a1ae7b395a9a7df3d12c7b118e8eda5057572c1ba05cd9b635edf33dabca4cac7291e0848f19c20e5beb850c3818f3543d49b3a5c729cb86a28fda539775d04feda112fe0c81d138aaf623aea7d507a4e826e890105db6065a44aba76a10d771c00d1b33f4ac51869806aae18eada68f19047024542d64a7aa1c91a5e1aa49d93613b5224b415bcc7aa166e4b55033438d20c641f9664fdb1689b53208181463e3d1325d46b30f07c5945b7e3fa1418bf833d975258461b294664eaf60795964924a280729c10a37fc6e967440bdd55d4ca53596286383481291152365303d44517cef369c00933b0b30368a230353e729c031075e8388673678a56b3ba84a165b28096ee9bd684483e1844258b451c365c41fa534152a3b64120041450128e960c7d6437d717ee266bdde7aaeec225ed93b958d188e97407349f1382976ca47d761ecc59a6f394487eb015c083abb490584677240eb47f838c838568a496119378b8bb81484610a50792b5d9c9939db188e7d0249d3cb918c436f111a2898849b286b0743a22c57464c709c5eaceac1ba493adca3328c0b14b5e38d3aea74e328b622b17e7181c35ad11c2103bdb7f2b209d93dcbc4ab61a06bc37139e6d2b7a06c5b7e9267bef3a8918a706f793271a5acc2574532da79e5a10cf074b998147a3c43586a411a513bba0d11cc19a36c83b19277f28022c88b120abfdba7076a8263e05336e3245aef7033eb3c762b5bbfa5791ac960398b649d5cbb652ddc6b2398143a0861ab3b410b696328879c099098adf819fbf7ac170030e86675e7f45c22ac9e1cf52c3102487bb0b91ab592afdc69c6e3a9b71876b86260b6c736b8291098f1130d3b763525cbad540ce2d042eacb6ed43b7bcba898f712c412f26066e09945f44ec7026c8ef959831abc10719d2017a12a41728b41c02371a5f5756ebc79406be708ea41bbd21563c874a0b791a3b4e4224a609967004f065c5ab4f3b4c61cb35df70573269da53179c3701fc5205f61974426f9b794c1b5826494b70842b6920c17752029369264dc8590b898b85c9d89a258e1f46c1b0490efd17c485cb51687cea272041e90b8e629521d3c5e3fa7518161bad7a159295b63cc6c0077897b53d47db8bc0ecb820f550705b65715a1a1094d04854f56acd26aa0baa10cb8447fad6211f53105796a42882328e6852e8de821c283b51eaab9bc95c4dc53615626049d63b1f9a457193805276b1905b0ab39353b5cf91fdd6023d4d816aef9cce4a3cfb3d12190172df221ae61d427563a098cc60e3dc9997ef54959180be5dc64a911157db6be3a01be2ee343caab33b8729abf0c50c674758c511291941fceac646232920907c2e88b9ec10211161729c797643a553a6ae5c4b7483c04e3263bd291e311c609071348b7c3310aa97d6b8318e0a4afe8399fa22f951049a9bb8860f7c69a333d3cc1aaf0129ab560713bf29eb3a01f9a276c78e54e3a3648b2447c80242b271b11406866389426d8b59796540d6b5702092ab21ee217c075cfc0c17ef826ce9ea29b9e61617457a5b1aaa23a58615dc53c59183beb36ea19498c21820b70ab47adeb678f1c52bf8768b3597b608ea1a8a15cd62e8a29bec4a1ac248ef9f02de0144bca06025f95a42bd6c8eaaaaaa2366328561d";
+/**
+ * Check if a byte array matches the test seed key.
+ * Logs a warning if it does.
+ */
+export declare function warnIfTestSeed(seed: Uint8Array): boolean;
+/**
+ * Check if a byte array matches the test public key.
+ * Logs a warning if it does.
+ */
+export declare function warnIfTestPubKey(pubKeyBytes: Uint8Array): boolean;
 /**
  * X-Wing keypair interface.
  * X-Wing is a post-quantum hybrid KEM combining ML-KEM-768 and X25519.
@@ -72,7 +97,7 @@ export type XwingDecryptorArgs = {
 /**
  * Encrypt using X-Wing HPKE (RFC 9180) with ChaCha20-Poly1305 AEAD.
  *
- * Output format: encappedKey (1184 bytes) || ciphertext (variable length)
+ * Output format: encappedKey (1120 bytes) || ciphertext (variable length)
  *
  * @param pubKeyA - Recipient's public key
  * @param msg - Message to encrypt
@@ -84,7 +109,7 @@ export declare function encrypt(pubKeyA: CryptoKey, msg: Uint8Array, aad?: Uint8
 /**
  * Decrypt using X-Wing HPKE (RFC 9180) with ChaCha20-Poly1305 AEAD.
  *
- * Input format: encappedKey (1184 bytes) || ciphertext (variable length)
+ * Input format: encappedKey (1120 bytes) || ciphertext (variable length)
  *
  * @param privKeyA - Recipient's private key
  * @param encryptedData - Encrypted data (encappedKey || ciphertext)
@@ -121,3 +146,9 @@ export declare function getXwingEncryptor({ pubKeyA, }: XwingEncryptorArgs): Enc
  * @returns Decryptor function
  */
 export declare function getXwingDecryptor({ privKeyA, }: XwingDecryptorArgs): Decryptor<XwingScheme>;
+/**
+ * Returns true if the raw public key bytes match the public key encoded by the keypair.
+ * Used to catch caller mistakes before sending the keypair to the covalidator, where a
+ * mismatch would produce a cryptic signature error instead of a clear failure.
+ */
+export declare function reencryptPublicKeysMatch(reencryptPubKey: Uint8Array, reencryptKeypair: XwingKeypair): boolean;

package/dist/types/local/local-node.d.ts

@@ -1,4 +1,10 @@
 import { Schema } from 'effect';
+/**
+ * Schema for the environment variables required to connect to a local Inco node.
+ *
+ * Includes executor/sender addresses, keys, covalidator settings, and optional
+ * remote compute-server overrides. Typically populated from a `.env` file.
+ */
 export declare const LocalNodeEnv: Schema.Struct<{
     DEPLOYER_ADDRESS: Schema.brand<Schema.filter<Schema.TemplateLiteral<`0x${string}`>>, "Address">;
     STATE_DUMP: typeof Schema.String;
@@ -14,6 +20,18 @@ export declare const LocalNodeEnv: Schema.Struct<{
     COVALIDATOR_HOST_CHAIN_ID: Schema.optional<typeof Schema.String>;
     COVALIDATOR_URL: Schema.optional<typeof Schema.String>;
     COVALIDATOR_HOST_CHAIN_RPC_URL: Schema.optional<typeof Schema.String>;
+    COVALIDATOR_COMPUTE_TYPE: Schema.optional<typeof Schema.String>;
+    COVALIDATOR_STORAGE_KEY: Schema.optional<Schema.TemplateLiteral<`0x${string}`>>;
 }>;
+/** Parsed local node environment configuration. */
 export type LocalNodeEnv = typeof LocalNodeEnv.Type;
+/**
+ * Parses a dotenv-formatted string or `Buffer` into a validated {@link LocalNodeEnv}.
+ *
+ * Falls back to `process.env` when no argument is provided.
+ *
+ * @param envFileOrObj - A dotenv-formatted string, `Buffer`, or `undefined` to use `process.env`.
+ * @returns A validated `LocalNodeEnv` object.
+ * @throws If required environment variables are missing or invalid.
+ */
 export declare function parseLocalEnv(envFileOrObj?: string | Buffer): LocalNodeEnv;

package/dist/types/reencryption/eip712.d.ts

@@ -14,9 +14,36 @@ declare const baseEIP712: Schema.Struct<{
     }>>>;
 }>;
 type BaseEIP712 = typeof baseEIP712.Type;
+/**
+ * An EIP-712 typed data payload with a generic `message` field.
+ *
+ * Extends the base EIP-712 structure (domain, primaryType, types) with
+ * a strongly-typed `message` object for signing.
+ *
+ * @typeParam Message - The shape of the application-specific message to sign.
+ */
 export interface EIP712<Message extends object> extends BaseEIP712 {
     message: Message;
 }
+/**
+ * Creates an EIP-712 typed data payload for user signing.
+ *
+ * Used to verify the user controls the private key corresponding to the ephemeral
+ * public key embedded in the payload. The `message` keys must exactly match the
+ * `name` values in `primaryTypeFields`.
+ *
+ * @typeParam PrimaryType - The EIP-712 primary type name.
+ * @typeParam Message - The shape of the message to sign.
+ * @param params.chainId - The chain ID for the EIP-712 domain.
+ * @param params.primaryType - The primary type name (e.g. `"Reencrypt"`).
+ * @param params.primaryTypeFields - The field definitions for the primary type.
+ * @param params.message - The message object to sign (must match `primaryTypeFields`).
+ * @param params.verifyingContract - Optional verifying contract address for the domain.
+ * @param params.domainName - Human-readable name for the EIP-712 domain.
+ * @param params.domainVersion - Version string for the EIP-712 domain.
+ * @returns A complete {@link EIP712} payload ready for signing.
+ * @throws If message keys do not match `primaryTypeFields` names.
+ */
 export declare function createEIP712Payload<PrimaryType extends string, Message extends object>({ chainId, primaryType, primaryTypeFields, message, verifyingContract, domainName, domainVersion, }: {
     chainId: bigint;
     primaryType: PrimaryType;

package/dist/types/reencryption/types.d.ts

@@ -4,18 +4,42 @@ import { CiphertextOf, EncryptionScheme, PlaintextOf, SupportedFheType } from '.
 import { Handle } from '../handle.js';
 import type { XwingKeypair } from '../lite/xwing.js';
 import type { BackoffConfig } from '../retry.js';
+/**
+ * The core reencryption function type. Takes a handle (and optional ciphertext) and returns
+ * the decrypted plaintext. Supports retry configuration for handles that are not yet available.
+ *
+ * @typeParam S - The encryption scheme (e.g. X-Wing).
+ */
 export type Reencryptor<S extends EncryptionScheme> = <T extends SupportedFheType>(args: ReencryptFnArgs<S, T>, backoffConfig?: Partial<BackoffConfig>) => Promise<PlaintextOf<S, T>>;
+/** Arguments required to construct a {@link Reencryptor}. */
 export interface ReencryptorArgs {
     chainId: bigint;
 }
+/**
+ * Arguments for a single reencryption call.
+ *
+ * @typeParam S - The encryption scheme.
+ * @typeParam T - The ENCRYPTION type of the ciphertext.
+ */
 export type ReencryptFnArgs<S extends EncryptionScheme, T extends SupportedFheType> = {
     handle: Handle;
+    /**
+     * Optional ciphertext hint. If provided, the reencrypt endpoint may use it directly
+     * instead of fetching from the covalidators.
+     */
     ciphertext?: CiphertextOf<S, T>;
 };
+/** Union of supported ephemeral keypair types for reencryption (currently X-Wing only). */
 export type SupportedEphemeralKeypairs = XwingKeypair;
+/** An object whose public key can be serialized to a `Uint8Array`. */
 export interface PubKeyEncodable {
     encodePublicKey(): Uint8Array;
 }
+/**
+ * A reencryption request to be sent to a reencrypt endpoint.
+ *
+ * @typeParam EKP - The type of ephemeral keypair used for the reencryption session.
+ */
 export interface ReencryptEndpointRequest<EKP extends SupportedEphemeralKeypairs> {
     userAddress: Address;
     handle: Handle;

package/dist/types/retry.d.ts

@@ -7,6 +7,20 @@ export type BackoffConfig = {
     backoffFactor: number;
     errHandler?: (error: Error, attempt: number) => 'stop' | 'continue';
 };
+/**
+ * Checks if an error is safe to retry.
+ * Only transient errors matching the allowlist should return true.
+ * All other errors fail fast to avoid masking security-critical failures.
+ *
+ * @param error - The error to check
+ * @returns true if the error is transient and safe to retry, false otherwise
+ */
+export declare function isRetryableError(error: Error): boolean;
+/**
+ * Default error handler that only retries known transient errors.
+ * Security-critical errors will fail fast.
+ */
+export declare function defaultRetryErrorHandler(error: Error): 'stop' | 'continue';
 /**
  * Helper function to implement exponential backoff retry logic.
  * @param fn - The function to retry

package/dist/types/test/mocks.d.ts

@@ -1,15 +1,20 @@
-import { Account, Chain, Transport, WalletClient } from 'viem';
+import { Account, Chain, PublicClient, Transport, WalletClient } from 'viem';
 import { vi } from 'vitest';
 import { KmsClient } from '../kms/client.js';
 import { KmsQuorumClient } from '../kms/quorumClient.js';
 interface MinimalKmsClient {
     attestedCompute: ReturnType<typeof vi.fn>;
     attestedDecrypt: ReturnType<typeof vi.fn>;
+    attestedReveal: ReturnType<typeof vi.fn>;
+    eListAttestedDecrypt: ReturnType<typeof vi.fn>;
+    eListAttestedReveal: ReturnType<typeof vi.fn>;
     key: ReturnType<typeof vi.fn>;
     reencrypt: ReturnType<typeof vi.fn>;
 }
 export declare function createMockKmsClient(): MinimalKmsClient & KmsClient;
 export declare function createMockQuorumClient(): KmsQuorumClient;
 export declare function setupMockInQuorumClient(quorumClient: KmsQuorumClient, mockKmsClient: MinimalKmsClient & KmsClient): void;
+export declare function createMockPublicClient(): PublicClient<Transport, Chain>;
 export declare function createTestWalletClient(): WalletClient<Transport, Chain, Account>;
+export declare function createFallbackWalletClient(): WalletClient<Transport, Chain, Account>;
 export {};