@inco/js 0.6.8 → 0.7.0

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

@@ -1,13 +1,12 @@
-import { Account, Chain, Transport, WalletClient } from 'viem';
+import { Account, Chain, PublicClient, Transport, WalletClient } from 'viem';
 import { AllowanceVoucherWithSig } from '../advancedacl/types.js';
 import { AttestedComputeOP } from '../attestedcompute/types.js';
-import { DecryptionAttestation } from '../attesteddecrypt/index.js';
+import { DecryptionAttestation, EncryptedDecryptionAttestation } from '../attesteddecrypt/index.js';
 import { Address, HexString } from '../binary.js';
-import { EciesScheme, PlaintextOf, SupportedFheType } from '../encryption/index.js';
+import { EciesScheme, Encryptor, SupportedFheType } from '../encryption/index.js';
 import { lightningDeployments } from '../generated/lightning.js';
 import { localNodeLightningConfig } from '../generated/local-node.js';
 import { LocalNodeEnv } from '../local/index.js';
-import type { Reencryptor } from '../reencryption/index.js';
 import { BackoffConfig } from '../retry.js';
 import { Secp256k1Keypair } from './ecies.js';
 type TupleToUnion<T> = T extends readonly unknown[] ? T[number] : never;
@@ -26,36 +25,38 @@ export type EncryptionContext = {
 };
 export type DeploymentSlice = {
     executorAddress: string;
-    eciesPublicKey: string;
     chainId: number;
 };
 export type CustomConfig = {
     executorAddress: string;
-    eciesPublicKey: string;
     chainId: number;
-    covalidatorUrl: string;
+    covalidatorUrls: string[];
+    signers?: Address[];
     hostChainRpcUrl?: string;
     senderPrivateKey?: HexString;
 };
 export type CustomDeployment = DeploymentSlice & CustomConfig;
+type LocalNodeEnvFileSource = {
+    filePath: string;
+};
 /**
  * The Lightning class provides a convenient way to interact with the Inco Lightning contract by binding to a specific
  * deployment.
  */
 export declare class Lightning<T extends DeploymentSlice = DeploymentSlice> {
     private readonly _deployment;
-    readonly covalidatorUrl: string;
+    readonly covalidatorUrls: string[];
+    readonly signers: Address[];
+    readonly threshold: number;
     readonly executorAddress: Address;
-    readonly eciesPublicKey: HexString;
     readonly chainId: bigint;
-    private readonly encryptor;
     private readonly ephemeralKeypair;
-    private readonly kmsClient;
+    private readonly kmsQuorumClient;
     private constructor();
     /**
      * Get a Lightning instance bound to the latest Lightning deployment for the Base Sepolia testnet.
      */
-    static baseSepoliaTestnet(): Lightning<Deployment>;
+    static baseSepoliaTestnet(): Promise<Lightning<Deployment>>;
     /**
      * Get a Lightning instance bound to our canonical Anvil-based test node and test Covalidator node
      *
@@ -71,26 +72,27 @@ export declare class Lightning<T extends DeploymentSlice = DeploymentSlice> {
      * corresponding Pepper.
      *
      */
-    static localNode(env?: LocalNodeEnv | LocalNodePepper): Lightning<CustomDeployment>;
+    static localNode(env?: LocalNodeEnv | LocalNodePepper): Promise<Lightning<CustomDeployment>>;
     /**
      * Get a Lightning instance bound to a local node from a file containing a LocalNodeEnv environment .
      *
      * @param filePath the path to the file containing the environment variables in dotenv format
      */
-    static localNodeFromEnv(filePath?: string): Promise<Lightning<CustomDeployment>>;
+    static localNodeFromEnv(source?: string | Buffer | LocalNodeEnvFileSource): Promise<Lightning<CustomDeployment>>;
     /**
      * 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
      */
-    static at(id: DeploymentId): Lightning<Deployment>;
+    static at(id: DeploymentId): Promise<Lightning<Deployment>>;
     /**
      * Get a Lightning deployment for a local or custom node
      *
      * @param config this is an object containing the executorAddress, eciesPublicKey, chainId and covalidatorUrl.
      *    additional fields past will be made available as part of the `deployment` property.
      */
-    static custom<T extends CustomConfig>(config: T): Lightning<DeploymentSlice & T>;
+    static custom<T extends CustomConfig>(config: T): Promise<Lightning<DeploymentSlice & T>>;
+    static getEciesPublicKey(client: PublicClient, executorAddress: Address): Promise<HexString>;
     /**
      * Get the latest deployment for a given pepper, which usually denotes a family of deployments distinct from their
      * version such as 'devnet', 'testnet', 'mainnet', etc.
@@ -105,9 +107,9 @@ 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 chainId the chainId to use to filter the deployments
+     * @param chain the chain to use to filter the deployments
      */
-    static latest<P extends Pepper>(pepper: P, chainId: ChainId): Lightning<Deployment>;
+    static latest<P extends Pepper>(pepper: P, chainId: ChainId): Promise<Lightning<Deployment>>;
     get deployment(): T;
     /**
      * Encrypt a value using the public ECIES key of the Lightning deployment.
@@ -116,15 +118,14 @@ export declare class Lightning<T extends DeploymentSlice = DeploymentSlice> {
      * @param accountAddress the address of the account interacting with the dapp contract, normally an Externally Owned Account (EOA)
      * @param dappAddress the address of the dapp contract that interacts with the Inco Lightning contract or library
      */
-    encrypt<T extends SupportedNativeType>(value: T, { accountAddress, dappAddress }: EncryptionContext): Promise<HexString>;
+    encrypt<T extends SupportedNativeType>(value: T, { accountAddress, dappAddress }: EncryptionContext, encryptor: Encryptor<EciesScheme>): Promise<HexString>;
     /**
-     * Obtain a reencryptor for a particular Externally Owned Account (EOA) to request decrypted values.
-     * The account associated with the walletClient must have permissions to decrypt the handle or ciphertext passed
-     * to the reencryptor function.
+     * Get the encryptor for a specific ECIES public key.
      *
-     * @param walletClient the wallet client to use for signing the reencrypt request.
+     * @param eciesPubkey the ECIES public key to use for encryption
+     * @returns an Encryptor instance configured for the specified ECIES public key
      */
-    getReencryptor(walletClient: WalletClient<Transport, Chain, Account>): Promise<Reencryptor<EciesScheme>>;
+    getEncryptor(eciesPubkey: HexString): Encryptor<EciesScheme>;
     /**
      * Grants a session key allowance voucher for secure reencryption operations.
      *
@@ -149,24 +150,6 @@ export declare class Lightning<T extends DeploymentSlice = DeploymentSlice> {
      * ```
      */
     grantSessionKeyAllowanceVoucher(walletClient: WalletClient<Transport, Chain, Account>, granteeAddress: string, expiresAt: Date, sessionVerifierAddress: string): Promise<AllowanceVoucherWithSig>;
-    /**
-     * Creates a session key reencryptor for secure data reencryption operations.
-     *
-     * This method returns a reencryptor instance that can be used to perform reencryption
-     * operations using session keys. The reencryptor is configured with the provided
-     * allowance voucher and ephemeral keypair for secure communication.
-     *
-     * @param allowanceVoucherWithSig - The signed allowance voucher obtained from grantSessionKeyAllowanceVoucher
-     * @param ephemeralKeypair - The ephemeral keypair used for secure communication with the KMS make sure it has allowance to voucher
-     * @returns A reencryptor instance configured for session key operations
-     *
-     * @example
-     * ```typescript
-     * const reencryptor = await lightning.getSessionKeyRencryptor(voucher, ephemeralKeypair);
-     * const decryptedValue = await reencryptor({handle: resultHandle});
-     * ```
-     */
-    getSessionKeyRencryptor(allowanceVoucherWithSig: AllowanceVoucherWithSig, ephemeralKeypair: Secp256k1Keypair): Promise<(<T_1 extends SupportedFheType>({ handle, }: import("../reencryption/types.js").ReencryptFnArgs<EciesScheme, T_1>) => Promise<PlaintextOf<1, 0 | 5 | 7 | 8>>)>;
     /**
      * Updates the active session nonce for the given wallet client.
      *
@@ -178,35 +161,68 @@ export declare class Lightning<T extends DeploymentSlice = DeploymentSlice> {
      */
     updateActiveVouchersSessionNonce(walletClient: WalletClient<Transport, Chain, Account>): Promise<HexString>;
     /**
-     * Get an attested decryptor for the given wallet client.
+     * Requests attested decrypts signed by the covalidator using a wallet client.
      *
-     * @param walletClient - The wallet client used for signing the attested decrypt request
-     * @param handles - The handles to decrypt
-     * @param backoffConfig - The backoff configuration for the attested decrypt request
-     * @returns The decryption attestations
+     * @param walletClient Wallet used to sign the EIP-712 request.
+     * @param handles 32-byte handles to decrypt.
+     * @param backoffConfig Optional retry configuration.
      *
-     * @example
-     * ```typescript
-     * const response = await lightning.attestedDecrypt(walletClient, [handle1, handle2]);
-     * const { plaintext, covalidatorSignature } = response[0];
+     * @example Plaintext results
+     * ```ts
+     * const attestations = await lightning.attestedDecrypt(walletClient, [handle]);
+     * console.log(attestations[0].plaintext.value);
+     * ```
+     *
+     * @example Reencrypt for a delegate
+     * ```ts
+     * const encrypted = await lightning.attestedDecrypt(walletClient, [handle], delegatePubKey);
+     * console.log(encrypted[0].encryptedPlaintext.ciphertext.value);
+     * ```
+     *
+     * @example Reencrypt and decrypt locally
+     * ```ts
+     * const decrypted = await lightning.attestedDecrypt(
+     *   walletClient,
+     *   [handle],
+     *   keypair.encodePublicKey(),
+     *   keypair,
+     * );
+     * console.log(decrypted[0].plaintext.value);
      * ```
      */
     attestedDecrypt(walletClient: WalletClient<Transport, Chain, Account>, handles: HexString[], backoffConfig?: Partial<BackoffConfig>): Promise<Array<DecryptionAttestation<EciesScheme, SupportedFheType>>>;
+    attestedDecrypt(walletClient: WalletClient<Transport, Chain, Account>, handles: HexString[], reencryptPubKey: Uint8Array, backoffConfig?: Partial<BackoffConfig>): Promise<Array<EncryptedDecryptionAttestation<EciesScheme, SupportedFheType>>>;
+    attestedDecrypt(walletClient: WalletClient<Transport, Chain, Account>, handles: HexString[], reencryptPubKey: Uint8Array, reencryptKeypair: Secp256k1Keypair, backoffConfig?: Partial<BackoffConfig>): Promise<Array<DecryptionAttestation<EciesScheme, SupportedFheType>>>;
     /**
-     * @notice Attested decryption using a session key.
-     * @dev This method is used when you want to perform attested decryption
-     *      via an ephemeral session key and an allowance voucher. The session
-     *      key setup is typically faster and more flexible than using a wallet.
+     * Requests attested decrypts using a voucher-backed session key.
+     *
+     * @param ephemeralKeypair Session keypair matching the voucher grantee.
+     * @param allowanceVoucherWithSig Signed allowance voucher.
+     * @param handles Handles to decrypt.
+     * @param options Optional reencryption/backoff configuration.
      *
-     * @param ephemeralKeypair The ephemeral Secp256k1 keypair used for secure communication.
-     * @param allowanceVoucherWithSig The signed allowance voucher, obtained from
-     *        `grantSessionKeyAllowanceVoucher`, proving the session key's decryption rights.
-     * @param handles The encrypted handles to be decrypted.
-     * @param backoffConfig Optional configuration for retry and backoff strategy.
+     * @example Plaintext results
+     * ```ts
+     * const attestations = await lightning.attestedDecryptWithVoucher(
+     *   ephemeralKeypair,
+     *   voucher,
+     *   [handle],
+     * );
+     * ```
      *
-     * @returns A promise that resolves to an array of decryption attestations.
+     * @example Reencrypt for a delegate
+     * ```ts
+     * const encrypted = await lightning.attestedDecryptWithVoucher(
+     *   ephemeralKeypair,
+     *   voucher,
+     *   [handle],
+     *   { reencryptPubKey: delegateKeypair.encodePublicKey() },
+     * );
+     * ```
      */
-    attestedDecrypt(ephemeralKeypair: Secp256k1Keypair, allowanceVoucherWithSig: AllowanceVoucherWithSig, handles: HexString[], backoffConfig?: Partial<BackoffConfig>): Promise<Array<DecryptionAttestation<EciesScheme, SupportedFheType>>>;
+    attestedDecryptWithVoucher(ephemeralKeypair: Secp256k1Keypair, allowanceVoucherWithSig: AllowanceVoucherWithSig, handles: HexString[], backoffConfig?: Partial<BackoffConfig>): Promise<Array<DecryptionAttestation<EciesScheme, SupportedFheType>>>;
+    attestedDecryptWithVoucher(ephemeralKeypair: Secp256k1Keypair, allowanceVoucherWithSig: AllowanceVoucherWithSig, handles: HexString[], reencryptPubKey: Uint8Array, backoffConfig?: Partial<BackoffConfig>): Promise<Array<EncryptedDecryptionAttestation<EciesScheme, SupportedFheType>>>;
+    attestedDecryptWithVoucher(ephemeralKeypair: Secp256k1Keypair, allowanceVoucherWithSig: AllowanceVoucherWithSig, handles: HexString[], reencryptPubKey: Uint8Array, reencryptKeypair: Secp256k1Keypair, backoffConfig?: Partial<BackoffConfig>): Promise<Array<DecryptionAttestation<EciesScheme, SupportedFheType>>>;
     /**
      * Get an attested compute for the given wallet client.
      *
@@ -229,29 +245,45 @@ export declare class Lightning<T extends DeploymentSlice = DeploymentSlice> {
      */
     attestedCompute(walletClient: WalletClient<Transport, Chain, Account>, lhsHandle: HexString, op: AttestedComputeOP, rhsPlaintext: bigint | boolean, backoffConfig?: Partial<BackoffConfig>): Promise<DecryptionAttestation<EciesScheme, SupportedFheType>>;
     /**
-     * @notice Attested compute using a session key.
-     * @dev This method is used when you want to perform attested compute
-     *      via an ephemeral session key and an allowance voucher. The session
-     *      key setup is typically faster and more flexible than using a wallet.
+     * Performs attested compute via a voucher-backed session key.
+     *
+     * @example
+     * ```ts
+     * const attestation = await lightning.attestedComputeWithVoucher(
+     *   ephemeralKeypair,
+     *   voucher,
+     *   lhsHandle,
+     *   AttestedComputeSupportedOps.Eq,
+     *   true,
+     * );
+     * ```
+     */
+    attestedComputeWithVoucher(ephemeralKeypair: Secp256k1Keypair, allowanceVoucherWithSig: AllowanceVoucherWithSig, lhsHandle: HexString, op: AttestedComputeOP, rhsPlaintext: bigint | boolean, backoffConfig?: Partial<BackoffConfig>): Promise<DecryptionAttestation<EciesScheme, SupportedFheType>>;
+    /**
+     * Get an decryption of publicly revealed handles.
      *
-     * @param ephemeralKeypair The ephemeral Secp256k1 keypair used for secure communication.
-     * @param lhsHandle The handle to compute on
-     * @param op The operation to perform
-     * @param rhsPlaintext The plaintext to compute with
-     * @param allowanceVoucherWithSig The signed allowance voucher, obtained from
-     *        `grantSessionKeyAllowanceVoucher`, proving the session key's compute rights.
-     * @param backoffConfig Optional configuration for retry and backoff strategy.
+     * @param handles - The handles to decrypt
+     * @param backoffConfig - The backoff configuration for the attested decrypt request
+     * @returns The decryption attestations
      *
-     * @returns A promise that resolves to a compute attestation.
+     * @example
+     * ```typescript
+     * const response = await lightning.attestedReveal([handle1, handle2]);
+     * const { plaintext, covalidatorSignature } = response[0];
+     * ```
      */
-    attestedCompute(ephemeralKeypair: Secp256k1Keypair, lhsHandle: HexString, op: AttestedComputeOP, rhsPlaintext: bigint | boolean, allowanceVoucherWithSig: AllowanceVoucherWithSig, backoffConfig?: Partial<BackoffConfig>): Promise<DecryptionAttestation<EciesScheme, SupportedFheType>>;
+    attestedReveal(handles: HexString[], backoffConfig?: Partial<BackoffConfig>): Promise<Array<DecryptionAttestation<EciesScheme, SupportedFheType>>>;
     /**
      * Get the GRPC endpoint for the covalidator that services this deployment.
      */
-    static getCovalidatorUrl(deployment: DeploymentSlice & {
+    static getCovalidatorUrls(deployment: DeploymentSlice & {
         pepper: string;
-    }): string;
+    }, threshold: number): string[];
     private static isIdByName;
     private static plaintextFromValue;
+    private static getContractThresholdAndSigners;
+    private static getThresholdAndSigners;
+    private static supportsThresholdRetrieval;
+    private static getDefaultThresholdAndSigners;
 }
 export {};