@inco/lightning-js 0.0.0-bootstrap.0

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

@@ -0,0 +1,37 @@
+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;
+    EXECUTOR_ADDRESS: Schema.brand<Schema.filter<Schema.TemplateLiteral<`0x${string}`>>, "Address">;
+    NETWORK_PUBKEY: Schema.optional<Schema.TemplateLiteral<`0x${string}`>>;
+    SENDER_ADDRESS: Schema.brand<Schema.filter<Schema.TemplateLiteral<`0x${string}`>>, "Address">;
+    SENDER_PRIVATE_KEY: Schema.TemplateLiteral<`0x${string}`>;
+    EIP712_SIGNER_ADDRESS: Schema.optional<Schema.TemplateLiteral<`0x${string}`>>;
+    PEPPER: typeof Schema.String;
+    COVALIDATOR_NETWORK_PRIVATE_KEY: Schema.optional<Schema.TemplateLiteral<`0x${string}`>>;
+    COVALIDATOR_EIP712_PRIVATE_SIGNING_KEY: Schema.optional<Schema.TemplateLiteral<`0x${string}`>>;
+    COVALIDATOR_INCO_EXECUTOR_ADDR: Schema.brand<Schema.filter<Schema.TemplateLiteral<`0x${string}`>>, "Address">;
+    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

@@ -0,0 +1,56 @@
+import { Schema } from 'effect';
+import { Address } from 'viem';
+declare const baseEIP712: Schema.Struct<{
+    domain: Schema.Struct<{
+        chainId: typeof Schema.BigInt;
+        name: typeof Schema.String;
+        version: typeof Schema.String;
+        verifyingContract: Schema.optional<Schema.TemplateLiteral<`0x${string}`>>;
+    }>;
+    primaryType: typeof Schema.String;
+    types: Schema.Record$<typeof Schema.String, Schema.Array$<Schema.Struct<{
+        name: typeof Schema.String;
+        type: typeof Schema.String;
+    }>>>;
+}>;
+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;
+    primaryTypeFields: BaseEIP712['types'][PrimaryType];
+    message: Message;
+    verifyingContract?: Address;
+    domainName: string;
+    domainVersion: string;
+}): EIP712<Message>;
+export {};

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

@@ -0,0 +1,2 @@
+export * from './eip712.js';
+export * from './types.js';

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

@@ -0,0 +1,48 @@
+import { Address } from 'viem';
+import { HexString } from '../binary.js';
+import { CiphertextOf, EncryptionScheme, PlaintextOf, SupportedTeeType } from '../encryption/encryption.js';
+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 SupportedTeeType>(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 SupportedTeeType> = {
+    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;
+    eip712Signature: HexString;
+    ephemeralKeypair: EKP;
+}

package/dist/types/retry.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Configuration for exponential backoff retry logic.
+ */
+export type BackoffConfig = {
+    maxRetries: number;
+    baseDelayInMs: number;
+    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
+ * @param config - Optional backoff configuration
+ * @returns Promise that resolves with the result of the function
+ */
+export declare function retryWithBackoff<T>(fn: () => Promise<T>, { maxRetries, baseDelayInMs, backoffFactor, errHandler, }?: Partial<BackoffConfig>): Promise<T>;

package/dist/types/schema.d.ts

@@ -0,0 +1,4 @@
+import { Schema } from 'effect';
+import { ParseOptions } from 'effect/SchemaAST';
+export declare function parse<A, I>(schema: Schema.Schema<A, I>, obj: unknown, options?: ParseOptions): A;
+export declare function parseJson<A, I>(schema: Schema.Schema<A, I>, json: string | Uint8Array, options?: ParseOptions): A;

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

@@ -0,0 +1,20 @@
+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 {};