@inco/lightning-js 0.0.0-bootstrap.0

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

@@ -0,0 +1,459 @@
+import { Account, Chain, GetContractReturnType, PublicClient, Transport, WalletClient } from 'viem';
+import type { PrivateKeyAccount } from 'viem/accounts';
+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 { EListDecryptionAttestation, EncryptedEListDecryptionAttestation } from '../elistattesteddecrypt/index.js';
+import { EncryptionScheme, SupportedTeeType } 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 { TeeType } from '../handle.js';
+import { LocalNodeEnv } from '../local/index.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;
+export type DeploymentByName = DistributedPick<Deployment, 'name' | 'chainId'>;
+export type DeploymentByExecutor = DistributedPick<Deployment, 'executorAddress' | 'chainId'>;
+export type DeploymentId = DeploymentByName | DeploymentByExecutor;
+export type Pepper = Deployment['pepper'];
+export type LocalNodePepper = keyof typeof localNodeLightningConfig;
+export type ChainId = Deployment['chainId'];
+export type SupportedNativeType = boolean | bigint | number;
+export type EncryptionContext = {
+    accountAddress: string;
+    dappAddress: string;
+    handleType: TeeType;
+};
+export type DeploymentSlice = {
+    executorAddress: string;
+    chainId: number;
+};
+export type CustomConfig = {
+    executorAddress: string;
+    chainId: number;
+    covalidatorUrls: string[];
+    signers?: Address[];
+    hostChainRpcUrls?: readonly string[] | string[];
+    senderPrivateKey?: HexString;
+};
+export type CustomDeployment = DeploymentSlice & CustomConfig;
+export type IncoVerifierConfig = {
+    threshold: number;
+    signers: Address[];
+    networkPubkey: HexString;
+};
+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;
+    private readonly covalidatorUrls;
+    private readonly signers;
+    private readonly threshold;
+    private readonly networkPubkey;
+    private readonly publicClient;
+    readonly executorAddress: Address;
+    readonly chainId: bigint;
+    private readonly kmsQuorumClient;
+    private encryptor;
+    private encryptionScheme;
+    private constructor();
+    private getEncryptor;
+    /**
+     * Get the encryption scheme version used by this Lightning instance.
+     * 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 Base mainnet.
+     *
+     * @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 baseMainnet(options?: {
+        hostChainRpcUrls?: readonly string[];
+    }): Promise<Lightning<Deployment>>;
+    /**
+     * 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(options?: {
+        hostChainRpcUrls?: readonly string[];
+    }): Promise<Lightning<Deployment>>;
+    /**
+     * Get a Lightning instance bound to our canonical Anvil-based test node and test Covalidator node
+     *
+     * These can be run in docker-compose using images pushed to dockerhub as:
+     *   - inconetwork/local-node-anvil
+     *   - inconetwork/local-node-covalidator
+     *
+     * See the sample docker-compose file here: https://github.com/Inco-fhevm/lightning-rod/blob/main/docker-compose.yaml
+     *
+     * @param env either a Pepper such as 'testnet', 'devnet', 'alphanet' or a LocalNodeEnv object containing the
+     * executorAddress, networkPubkey, chainId, covalidatorUrl and senderPrivateKey. If none is provided, it defaults to
+     * the 'testnet' Pepper. This produces allows connection to a local node running against a state dump of the
+     * corresponding Pepper.
+     *
+     */
+    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(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
+     * @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, options?: {
+        hostChainRpcUrls?: readonly string[];
+    }): Promise<Lightning<Deployment>>;
+    /**
+     * Get a Lightning deployment for a local or custom node
+     *
+     * @param config this is an object containing the executorAddress, networkPubkey, chainId and covalidatorUrl.
+     *    additional fields past will be made available as part of the `deployment` property.
+     */
+    static custom<T extends CustomConfig>(config: T): Promise<Lightning<DeploymentSlice & T>>;
+    /**
+     * 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.
+     *
+     * @param pepper the pepper to use to filter the deployments
+     * @param chainId the chainId to use to filter the deployments
+     */
+    static latestDeployment<P extends Pepper>(pepper: P, chainId: ChainId): Deployment;
+    /**
+     * Get the latest Lightning deployment for a given pepper amd chainId unconditionally.
+     * Note that if you upgrade the library the latest deployment may change and contracts deployed to a previous version
+     * 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 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, 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 (X-Wing).
+     * The encryption scheme is automatically detected based on the public key length.
+     *
+     * @param value a boolean or numeric value to encrypt
+     * @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
+     * @param handleType (optional) the handle type to be used for encrypting the value - this is required in case of non-default handle types
+     *                    default handle types:
+     *                      - boolean -> handleTypes.ebool
+     *                      - number | bigint -> handleTypes.euint256
+     * @returns a promise that resolves to the encrypted value as a HexString
+     */
+    encrypt<T extends SupportedNativeType>(value: T, { accountAddress, dappAddress, handleType }: EncryptionContext): Promise<HexString>;
+    /**
+     * Grants a session key allowance voucher for secure reencryption operations.
+     *
+     * This method creates a signed allowance voucher that authorizes a specific requester address
+     * to perform reencryption operations using session keys. The voucher includes an expiration time
+     * and can optionally specify a custom session verifier contract address.
+     *
+     * @param walletClient - The wallet client used for signing the allowance voucher
+     * @param granteeAddress - The address of the entity requesting the session key allowance
+     * @param expiresAt - The timestamp when the allowance voucher expires (as a bigint)
+     * @param sessionVerifierAddress - Optional custom session verifier contract address. If not provided, uses the executor address
+     * @returns A promise that resolves to an AllowanceVoucherWithSig containing the signed allowance voucher
+     *
+     * @example
+     * ```typescript
+     * const voucher = await lightning.grantSessionKeyAllowanceVoucher(
+     *   walletClient,
+     *   "0x1234...",
+     *   BigInt(Date.now() + 3600000), // 1 hour from now
+     *   "0x5678..." // optional custom verifier
+     * );
+     * ```
+     */
+    grantSessionKeyAllowanceVoucher(walletClient: WalletClient<Transport, Chain, Account>, granteeAddress: string, expiresAt: Date, sessionVerifierAddress: string): Promise<AllowanceVoucherWithSig>;
+    /**
+     * Grants a session key allowance voucher using a custom session verifier contract.
+     *
+     * This method creates a signed allowance voucher that authorizes reencryption operations
+     * using a custom session verifier. Unlike `grantSessionKeyAllowanceVoucher`, this method
+     * allows specifying custom `sharerArgData` for use with custom verifier contracts that
+     * require additional authorization parameters.
+     *
+     * @param walletClient - The wallet client used for signing the allowance voucher
+     * @param sessionVerifierAddress - The address of the custom session verifier contract
+     * @param sharerArgData - Custom encoded arguments for the session verifier's `canUseSession` function
+     * @returns A promise that resolves to an AllowanceVoucherWithSig containing the signed allowance voucher
+     *
+     * @example
+     * ```typescript
+     * const sharerArgData = encodeAbiParameters(
+     *   [{ type: 'address' }, { type: 'uint256' }],
+     *   [granteeAddress, expiresAt]
+     * );
+     * const voucher = await lightning.grantCustomSessionKeyAllowanceVoucher(
+     *   walletClient,
+     *   "0x5678...", // custom verifier address
+     *   sharerArgData
+     * );
+     * ```
+     */
+    grantCustomSessionKeyAllowanceVoucher(walletClient: WalletClient<Transport, Chain, Account>, sessionVerifierAddress: string, sharerArgData: HexString): Promise<AllowanceVoucherWithSig>;
+    /**
+     * Updates the active session nonce for the given wallet client.
+     *
+     * This method updates the active session nonce for the given wallet client.
+     * It nullifies all the previous shared addresses accessing the voucher.
+     *
+     * @param walletClient - The wallet client used for updating the session nonce
+     * @returns The transaction hash of the updateActiveVouchersSessionNonce transaction
+     */
+    updateActiveVouchersSessionNonce(walletClient: WalletClient<Transport, Chain, Account>): Promise<HexString>;
+    /**
+     * Requests attested decrypts signed by the covalidator using a wallet client.
+     *
+     * @param walletClient Wallet used to sign the EIP-712 request.
+     * @param handles 32-byte handles to decrypt.
+     * @param backoffConfig Optional retry configuration.
+     *
+     * @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], {
+     *   reencryptPubKey: delegatePubKey,
+     * });
+     * console.log(encrypted[0].encryptedPlaintext.ciphertext.value);
+     * ```
+     *
+     * @example Reencrypt and decrypt locally
+     * ```ts
+     * 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[], opts?: AttestedOptsEphemeral): Promise<Array<DecryptionAttestation<EncryptionScheme, SupportedTeeType>>>;
+    attestedDecrypt(walletClient: WalletClient<Transport, Chain, Account>, handles: HexString[], opts: AttestedOptsEncrypted): Promise<Array<EncryptedDecryptionAttestation<EncryptionScheme, SupportedTeeType>>>;
+    attestedDecrypt(walletClient: WalletClient<Transport, Chain, Account>, handles: HexString[], opts: AttestedOptsDecrypted): Promise<Array<DecryptionAttestation<EncryptionScheme, SupportedTeeType>>>;
+    /**
+     * Requests attested decrypts using a voucher-backed session key.
+     *
+     * @param ephemeralAccount Session Account matching the voucher grantee.
+     * @param allowanceVoucherWithSig Signed allowance voucher.
+     * @param handles Handles to decrypt.
+     * @param opts Optional reencryption/backoff configuration.
+     *
+     * @example Plaintext results
+     * ```ts
+     * const attestations = await lightning.attestedDecryptWithVoucher(
+     *   ephemeralAccount,
+     *   voucher,
+     *   [handle],
+     * );
+     * ```
+     *
+     * @example Reencrypt for a delegate
+     * ```ts
+     * const encrypted = await lightning.attestedDecryptWithVoucher(
+     *   ephemeralAccount,
+     *   voucher,
+     *   [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, SupportedTeeType>>>;
+    attestedDecryptWithVoucher(ephemeralAccount: PrivateKeyAccount, allowanceVoucherWithSig: AllowanceVoucherWithSig, handles: HexString[], opts: AttestedWithVoucherOptsEncrypted): Promise<Array<EncryptedDecryptionAttestation<EncryptionScheme, SupportedTeeType>>>;
+    attestedDecryptWithVoucher(ephemeralAccount: PrivateKeyAccount, allowanceVoucherWithSig: AllowanceVoucherWithSig, handles: HexString[], opts: AttestedWithVoucherOptsDecrypted): Promise<Array<DecryptionAttestation<EncryptionScheme, SupportedTeeType>>>;
+    eListAttestedDecrypt(walletClient: WalletClient<Transport, Chain, Account>, handle: HexString, opts?: AttestedOptsEphemeral): Promise<EListDecryptionAttestation<EncryptionScheme, SupportedTeeType>>;
+    eListAttestedDecrypt(walletClient: WalletClient<Transport, Chain, Account>, handle: HexString, opts: AttestedOptsEncrypted): Promise<EncryptedEListDecryptionAttestation<EncryptionScheme, SupportedTeeType>>;
+    eListAttestedDecrypt(walletClient: WalletClient<Transport, Chain, Account>, handle: HexString, opts: AttestedOptsDecrypted): Promise<EListDecryptionAttestation<EncryptionScheme, SupportedTeeType>>;
+    /**
+     * 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
+     */
+    eListAttestedReveal(handle: HexString, opts?: AttestedRevealOpts): Promise<EListDecryptionAttestation<EncryptionScheme, SupportedTeeType>>;
+    /**
+     * Get an attested compute for the given wallet client.
+     *
+     * @param walletClient - The wallet client used for signing the attested compute request
+     * @param lhsHandle - The handle to compute
+     * @param op - The operation to perform
+     * @param rhsPlaintext - The plaintext to compute with
+     * @param opts - Optional configuration (reencryption keys and/or backoff config)
+     * @returns The decryption attestation
+     *
+     * @example Plaintext result
+     * ```typescript
+     * import { AttestedComputeSupportedOps } from '../lite/attested-compute.js';
+     * const lhsHandle = '0x...';
+     * const rhsPlaintext = 1337n;
+     * const op = AttestedComputeSupportedOps.Eq;
+     * const response = await lightning.attestedCompute(walletClient, lhsHandle, op, rhsPlaintext);
+     * const { plaintext, covalidatorSignature, handle } = response;
+     * ```
+     *
+     * @example Reencrypt for a delegate
+     * ```ts
+     * const encrypted = await lightning.attestedCompute(
+     *   walletClient,
+     *   lhsHandle,
+     *   op,
+     *   rhsPlaintext,
+     *   { reencryptPubKey: delegatePubKey },
+     * );
+     * console.log(encrypted.encryptedPlaintext.ciphertext.value);
+     * ```
+     *
+     * @example Reencrypt and decrypt locally
+     * ```ts
+     * const decrypted = await lightning.attestedCompute(
+     *   walletClient,
+     *   lhsHandle,
+     *   op,
+     *   rhsPlaintext,
+     *   { reencryptPubKey: keypair.encodePublicKey(), reencryptKeypair: keypair },
+     * );
+     * console.log(decrypted.plaintext.value);
+     * ```
+     */
+    attestedCompute(walletClient: WalletClient<Transport, Chain, Account>, lhsHandle: HexString, op: AttestedComputeOP, rhsPlaintext: bigint | boolean, opts?: AttestedOptsEphemeral): Promise<DecryptionAttestation<EncryptionScheme, SupportedTeeType>>;
+    attestedCompute(walletClient: WalletClient<Transport, Chain, Account>, lhsHandle: HexString, op: AttestedComputeOP, rhsPlaintext: bigint | boolean, opts: AttestedOptsEncrypted): Promise<EncryptedDecryptionAttestation<EncryptionScheme, SupportedTeeType>>;
+    attestedCompute(walletClient: WalletClient<Transport, Chain, Account>, lhsHandle: HexString, op: AttestedComputeOP, rhsPlaintext: bigint | boolean, opts: AttestedOptsDecrypted): Promise<DecryptionAttestation<EncryptionScheme, SupportedTeeType>>;
+    /**
+     * Performs attested compute via a voucher-backed session key.
+     *
+     * @example Plaintext result
+     * ```ts
+     * const attestation = await lightning.attestedComputeWithVoucher(
+     *   ephemeralAccount,
+     *   voucher,
+     *   lhsHandle,
+     *   AttestedComputeSupportedOps.Eq,
+     *   true,
+     * );
+     * ```
+     *
+     * @example Reencrypt for a delegate
+     * ```ts
+     * const encrypted = await lightning.attestedComputeWithVoucher(
+     *   ephemeralAccount,
+     *   voucher,
+     *   lhsHandle,
+     *   AttestedComputeSupportedOps.Eq,
+     *   true,
+     *   { reencryptPubKey: delegatePubKey },
+     * );
+     * console.log(encrypted.encryptedPlaintext.ciphertext.value);
+     * ```
+     *
+     * @example Reencrypt and decrypt locally
+     * ```ts
+     * const decrypted = await lightning.attestedComputeWithVoucher(
+     *   ephemeralAccount,
+     *   voucher,
+     *   lhsHandle,
+     *   AttestedComputeSupportedOps.Eq,
+     *   true,
+     *   { reencryptPubKey: keypair.encodePublicKey(), reencryptKeypair: keypair },
+     * );
+     * console.log(decrypted.plaintext.value);
+     * ```
+     */
+    attestedComputeWithVoucher(ephemeralAccount: PrivateKeyAccount, allowanceVoucherWithSig: AllowanceVoucherWithSig, lhsHandle: HexString, op: AttestedComputeOP, rhsPlaintext: bigint | boolean, opts?: AttestedWithVoucherOptsEphemeral): Promise<DecryptionAttestation<EncryptionScheme, SupportedTeeType>>;
+    attestedComputeWithVoucher(ephemeralAccount: PrivateKeyAccount, allowanceVoucherWithSig: AllowanceVoucherWithSig, lhsHandle: HexString, op: AttestedComputeOP, rhsPlaintext: bigint | boolean, opts: AttestedWithVoucherOptsEncrypted): Promise<EncryptedDecryptionAttestation<EncryptionScheme, SupportedTeeType>>;
+    attestedComputeWithVoucher(ephemeralAccount: PrivateKeyAccount, allowanceVoucherWithSig: AllowanceVoucherWithSig, lhsHandle: HexString, op: AttestedComputeOP, rhsPlaintext: bigint | boolean, opts: AttestedWithVoucherOptsDecrypted): Promise<DecryptionAttestation<EncryptionScheme, SupportedTeeType>>;
+    /**
+     * Get an decryption of publicly revealed handles.
+     *
+     * @param handles - The handles to decrypt
+     * @param backoffConfig - The backoff configuration for the attested decrypt request
+     * @returns The decryption attestations
+     *
+     * @example
+     * ```typescript
+     * const response = await lightning.attestedReveal([handle1, handle2]);
+     * const { plaintext, covalidatorSignature } = response[0];
+     * ```
+     */
+    attestedReveal(handles: HexString[], opts?: AttestedRevealOpts): Promise<Array<DecryptionAttestation<EncryptionScheme, SupportedTeeType>>>;
+    /**
+     * Get the GRPC endpoint for the covalidator that services this deployment.
+     */
+    static getCovalidatorUrls(deployment: DeploymentSlice & {
+        pepper: 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 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 XWING public key.
+     */
+    private static getVerifierContractDetails;
+    private static getChainConfig;
+    private static supportsThresholdRetrieval;
+}
+export {};