@sip-protocol/sdk 0.7.3 → 0.8.0

package/dist/interface-Bf7w1PLW.d.ts

@@ -0,0 +1,679 @@
+import { ProofSystem, SingleProof, HexString, ProofProviderCapabilities, ProofAggregationStrategy, ProofCompositionConfig, CompositionEventListener, ComposedProof, ProofProviderStatus, CompositionResult, VerificationResult } from '@sip-protocol/types';
+
+/**
+ * Proof Composer SDK Types
+ *
+ * SDK-specific types for the proof composition system.
+ * These extend the base types from @sip-protocol/types with
+ * implementation-specific details.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Registration entry for a proof provider
+ */
+interface ProofProviderRegistration {
+    /** Unique identifier for this provider instance */
+    id: string;
+    /** The proof system */
+    system: ProofSystem;
+    /** Provider capabilities */
+    capabilities: ProofProviderCapabilities;
+    /** Priority for provider selection (higher = preferred) */
+    priority: number;
+    /** Whether this provider is enabled */
+    enabled: boolean;
+}
+/**
+ * Options for registering a proof provider
+ */
+interface RegisterProviderOptions {
+    /** Override existing provider with same system */
+    override?: boolean;
+    /** Priority for this provider */
+    priority?: number;
+    /** Enable immediately */
+    enabled?: boolean;
+}
+/**
+ * Request to generate a proof
+ */
+interface ProofGenerationRequest {
+    /** Circuit to use */
+    circuitId: string;
+    /** Private inputs (not revealed) */
+    privateInputs: Record<string, unknown>;
+    /** Public inputs (revealed in proof) */
+    publicInputs: Record<string, unknown>;
+    /** Optional: specific provider to use */
+    providerId?: string;
+    /** Optional: specific proof system to use */
+    system?: ProofSystem;
+    /** Optional: timeout override */
+    timeoutMs?: number;
+}
+/**
+ * Result of proof generation
+ */
+interface ProofGenerationResult {
+    /** Whether generation was successful */
+    success: boolean;
+    /** The generated proof (if successful) */
+    proof?: SingleProof;
+    /** Error message (if failed) */
+    error?: string;
+    /** Generation time in milliseconds */
+    timeMs: number;
+    /** Provider that generated the proof */
+    providerId: string;
+}
+/**
+ * Options for composing proofs
+ */
+interface ComposeProofsOptions {
+    /** Proofs to compose */
+    proofs: SingleProof[];
+    /** Override default strategy */
+    strategy?: ProofAggregationStrategy;
+    /** Override default config */
+    config?: Partial<ProofCompositionConfig>;
+    /** Event listener for progress updates */
+    onProgress?: CompositionEventListener;
+    /** Abort signal for cancellation */
+    abortSignal?: AbortSignal;
+}
+/**
+ * Options for verifying a composed proof
+ */
+interface VerifyComposedProofOptions {
+    /** The composed proof to verify */
+    composedProof: ComposedProof;
+    /** Whether to verify individual proofs */
+    verifyIndividual?: boolean;
+    /** Whether to use batch verification if available */
+    useBatchVerification?: boolean;
+    /** Timeout for verification */
+    timeoutMs?: number;
+}
+/**
+ * Options for aggregating proofs
+ */
+interface AggregateProofsOptions {
+    /** Proofs to aggregate */
+    proofs: SingleProof[];
+    /** Target proof system for aggregated proof */
+    targetSystem: ProofSystem;
+    /** Whether to verify before aggregating */
+    verifyFirst?: boolean;
+    /** Maximum recursion depth */
+    maxRecursionDepth?: number;
+}
+/**
+ * Result of proof aggregation
+ */
+interface AggregationResult {
+    /** Whether aggregation was successful */
+    success: boolean;
+    /** The aggregated proof (if successful) */
+    aggregatedProof?: HexString;
+    /** Error message (if failed) */
+    error?: string;
+    /** Aggregation metrics */
+    metrics: {
+        inputProofCount: number;
+        outputProofSize: number;
+        timeMs: number;
+        recursionDepth: number;
+    };
+}
+/**
+ * Options for converting proof formats
+ */
+interface ConvertProofOptions {
+    /** Source proof */
+    proof: SingleProof;
+    /** Target proof system */
+    targetSystem: ProofSystem;
+    /** Whether to preserve metadata */
+    preserveMetadata?: boolean;
+}
+/**
+ * Result of proof conversion
+ */
+interface ConversionResult {
+    /** Whether conversion was successful */
+    success: boolean;
+    /** The converted proof (if successful) */
+    convertedProof?: SingleProof;
+    /** Error message (if failed) */
+    error?: string;
+    /** Whether conversion was lossless */
+    lossless: boolean;
+}
+/**
+ * Cache entry for a proof
+ */
+interface ProofCacheEntry {
+    /** The cached proof */
+    proof: SingleProof | ComposedProof;
+    /** When the entry was created */
+    createdAt: number;
+    /** When the entry expires */
+    expiresAt: number;
+    /** Number of times this entry was accessed */
+    accessCount: number;
+    /** Last access timestamp */
+    lastAccessedAt: number;
+    /** Size in bytes */
+    sizeBytes: number;
+}
+/**
+ * Cache statistics
+ */
+interface CacheStats {
+    /** Total entries in cache */
+    entryCount: number;
+    /** Total size in bytes */
+    totalSizeBytes: number;
+    /** Hit rate (0-1) */
+    hitRate: number;
+    /** Number of cache hits */
+    hits: number;
+    /** Number of cache misses */
+    misses: number;
+    /** Number of evictions */
+    evictions: number;
+}
+/**
+ * Configuration for the worker pool
+ */
+interface WorkerPoolConfig {
+    /** Minimum number of workers */
+    minWorkers: number;
+    /** Maximum number of workers */
+    maxWorkers: number;
+    /** Worker idle timeout (milliseconds) */
+    idleTimeoutMs: number;
+    /** Task queue size limit */
+    maxQueueSize: number;
+    /** Whether to use shared array buffers */
+    useSharedMemory: boolean;
+}
+/**
+ * Status of the worker pool
+ */
+interface WorkerPoolStatus {
+    /** Number of active workers */
+    activeWorkers: number;
+    /** Number of idle workers */
+    idleWorkers: number;
+    /** Number of tasks in queue */
+    queuedTasks: number;
+    /** Number of tasks being processed */
+    processingTasks: number;
+    /** Average task completion time (milliseconds) */
+    avgTaskTimeMs: number;
+}
+/**
+ * Compatibility matrix entry
+ */
+interface SystemCompatibility {
+    /** Source system */
+    source: ProofSystem;
+    /** Target system */
+    target: ProofSystem;
+    /** Whether conversion is supported */
+    conversionSupported: boolean;
+    /** Whether aggregation is supported */
+    aggregationSupported: boolean;
+    /** Compatibility notes */
+    notes?: string;
+}
+/**
+ * Full compatibility matrix
+ */
+type CompatibilityMatrix = Record<ProofSystem, Record<ProofSystem, SystemCompatibility>>;
+/**
+ * Fallback strategy configuration
+ */
+interface FallbackConfig {
+    /** Primary proof system */
+    primary: ProofSystem;
+    /** Fallback chain (in order of preference) */
+    fallbackChain: ProofSystem[];
+    /** Whether to retry on failure */
+    retryOnFailure: boolean;
+    /** Maximum retry attempts */
+    maxRetries: number;
+    /** Delay between retries (milliseconds) */
+    retryDelayMs: number;
+    /** Whether to use exponential backoff */
+    exponentialBackoff: boolean;
+}
+/**
+ * Telemetry data for proof operations
+ */
+interface ProofTelemetry {
+    /** Operation type */
+    operation: 'generate' | 'verify' | 'compose' | 'aggregate' | 'convert';
+    /** Proof system used */
+    system: ProofSystem;
+    /** Circuit ID */
+    circuitId: string;
+    /** Duration in milliseconds */
+    durationMs: number;
+    /** Whether operation succeeded */
+    success: boolean;
+    /** Error code (if failed) */
+    errorCode?: string;
+    /** Memory usage (bytes) */
+    memoryUsage?: number;
+    /** Timestamp */
+    timestamp: number;
+}
+/**
+ * Telemetry collector interface
+ */
+interface TelemetryCollector {
+    /** Record a telemetry event */
+    record(telemetry: ProofTelemetry): void;
+    /** Flush pending telemetry */
+    flush(): Promise<void>;
+    /** Get aggregated metrics */
+    getMetrics(): ProofTelemetryMetrics;
+}
+/**
+ * Aggregated telemetry metrics
+ */
+interface ProofTelemetryMetrics {
+    /** Operations by type */
+    operationCounts: Record<string, number>;
+    /** Average duration by operation type */
+    avgDurationMs: Record<string, number>;
+    /** Success rate by operation type */
+    successRates: Record<string, number>;
+    /** Total operations */
+    totalOperations: number;
+    /** Time window for these metrics */
+    timeWindowMs: number;
+}
+
+/**
+ * Proof Composer Interface
+ *
+ * Defines the core interfaces for proof composition, including:
+ * - ProofComposer: Main composition orchestrator
+ * - ComposableProofProvider: Abstract provider for proof systems
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Abstract interface for proof providers that can participate in composition.
+ *
+ * Implementations of this interface provide proof generation and verification
+ * for a specific proof system (Noir, Halo2, Kimchi, etc.).
+ *
+ * @example
+ * ```typescript
+ * class Halo2Provider implements ComposableProofProvider {
+ *   readonly system = 'halo2'
+ *
+ *   async initialize() {
+ *     // Load WASM, setup keys, etc.
+ *   }
+ *
+ *   async generateProof(request) {
+ *     // Generate Halo2 proof
+ *   }
+ *
+ *   async verifyProof(proof) {
+ *     // Verify Halo2 proof
+ *   }
+ * }
+ * ```
+ */
+interface ComposableProofProvider {
+    /**
+     * The proof system this provider implements
+     */
+    readonly system: ProofSystem;
+    /**
+     * Provider capabilities
+     */
+    readonly capabilities: ProofProviderCapabilities;
+    /**
+     * Current provider status
+     */
+    readonly status: ProofProviderStatus;
+    /**
+     * Initialize the provider.
+     * Must be called before generating or verifying proofs.
+     *
+     * @throws Error if initialization fails
+     */
+    initialize(): Promise<void>;
+    /**
+     * Wait for provider to be ready with optional timeout.
+     *
+     * @param timeoutMs - Maximum wait time in milliseconds (default: 30000)
+     * @throws Error if timeout reached or initialization fails
+     */
+    waitUntilReady(timeoutMs?: number): Promise<void>;
+    /**
+     * Generate a proof for the given request.
+     *
+     * @param request - Proof generation request
+     * @returns Generation result with proof or error
+     */
+    generateProof(request: ProofGenerationRequest): Promise<ProofGenerationResult>;
+    /**
+     * Verify a single proof.
+     *
+     * @param proof - The proof to verify
+     * @returns true if valid, false otherwise
+     */
+    verifyProof(proof: SingleProof): Promise<boolean>;
+    /**
+     * Verify multiple proofs in a batch (if supported).
+     *
+     * @param proofs - Proofs to verify
+     * @returns Array of verification results
+     */
+    verifyBatch?(proofs: SingleProof[]): Promise<boolean[]>;
+    /**
+     * Get available circuits for this provider.
+     *
+     * @returns Array of circuit identifiers
+     */
+    getAvailableCircuits(): string[];
+    /**
+     * Check if a specific circuit is available.
+     *
+     * @param circuitId - Circuit identifier
+     * @returns true if circuit is available
+     */
+    hasCircuit(circuitId: string): boolean;
+    /**
+     * Dispose of resources used by this provider.
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * Main interface for the proof composition system.
+ *
+ * ProofComposer orchestrates the composition of proofs from multiple
+ * proof systems, handling:
+ * - Provider registration and management
+ * - Proof generation across systems
+ * - Proof composition and aggregation
+ * - Verification of composed proofs
+ * - Caching and optimization
+ *
+ * @example
+ * ```typescript
+ * const composer = new ProofComposer(config)
+ *
+ * // Register providers
+ * await composer.registerProvider(noirProvider)
+ * await composer.registerProvider(halo2Provider)
+ *
+ * // Generate proofs
+ * const proof1 = await composer.generateProof({
+ *   circuitId: 'funding_proof',
+ *   privateInputs: { balance: 1000n },
+ *   publicInputs: { minRequired: 100n },
+ * })
+ *
+ * const proof2 = await composer.generateProof({
+ *   circuitId: 'validity_proof',
+ *   privateInputs: { sender: '0x...' },
+ *   publicInputs: { intentHash: '0x...' },
+ * })
+ *
+ * // Compose proofs
+ * const result = await composer.compose({
+ *   proofs: [proof1.proof!, proof2.proof!],
+ *   strategy: ProofAggregationStrategy.PARALLEL,
+ * })
+ *
+ * // Verify composed proof
+ * const verification = await composer.verify({
+ *   composedProof: result.composedProof!,
+ * })
+ * ```
+ */
+interface ProofComposer {
+    /**
+     * Current configuration
+     */
+    readonly config: ProofCompositionConfig;
+    /**
+     * Update configuration.
+     *
+     * @param config - Partial configuration to merge
+     */
+    updateConfig(config: Partial<ProofCompositionConfig>): void;
+    /**
+     * Register a proof provider.
+     *
+     * @param provider - The provider to register
+     * @param options - Registration options
+     * @returns Registration entry
+     */
+    registerProvider(provider: ComposableProofProvider, options?: RegisterProviderOptions): Promise<ProofProviderRegistration>;
+    /**
+     * Unregister a provider.
+     *
+     * @param providerId - Provider ID to unregister
+     * @returns true if provider was removed
+     */
+    unregisterProvider(providerId: string): boolean;
+    /**
+     * Get a registered provider by ID.
+     *
+     * @param providerId - Provider ID
+     * @returns Provider or undefined
+     */
+    getProvider(providerId: string): ComposableProofProvider | undefined;
+    /**
+     * Get provider for a specific proof system.
+     *
+     * @param system - Proof system
+     * @returns Provider or undefined
+     */
+    getProviderForSystem(system: ProofSystem): ComposableProofProvider | undefined;
+    /**
+     * Get all registered providers.
+     *
+     * @returns Array of provider registrations
+     */
+    getProviders(): ProofProviderRegistration[];
+    /**
+     * Get available proof systems.
+     *
+     * @returns Array of available systems
+     */
+    getAvailableSystems(): ProofSystem[];
+    /**
+     * Generate a proof using the appropriate provider.
+     *
+     * @param request - Proof generation request
+     * @returns Generation result
+     */
+    generateProof(request: ProofGenerationRequest): Promise<ProofGenerationResult>;
+    /**
+     * Generate multiple proofs in parallel.
+     *
+     * @param requests - Array of proof requests
+     * @returns Array of generation results
+     */
+    generateProofs(requests: ProofGenerationRequest[]): Promise<ProofGenerationResult[]>;
+    /**
+     * Compose multiple proofs into a single composed proof.
+     *
+     * @param options - Composition options
+     * @returns Composition result
+     */
+    compose(options: ComposeProofsOptions): Promise<CompositionResult>;
+    /**
+     * Aggregate proofs into a single proof (if supported).
+     *
+     * @param options - Aggregation options
+     * @returns Aggregation result
+     */
+    aggregate(options: AggregateProofsOptions): Promise<AggregationResult>;
+    /**
+     * Verify a composed proof.
+     *
+     * @param options - Verification options
+     * @returns Verification result
+     */
+    verify(options: VerifyComposedProofOptions): Promise<VerificationResult>;
+    /**
+     * Verify a single proof.
+     *
+     * @param proof - Proof to verify
+     * @returns true if valid
+     */
+    verifySingle(proof: SingleProof): Promise<boolean>;
+    /**
+     * Convert a proof to a different format.
+     *
+     * @param options - Conversion options
+     * @returns Conversion result
+     */
+    convert(options: ConvertProofOptions): Promise<ConversionResult>;
+    /**
+     * Get the compatibility matrix for proof systems.
+     *
+     * @returns Compatibility matrix
+     */
+    getCompatibilityMatrix(): CompatibilityMatrix;
+    /**
+     * Check if two systems are compatible for composition.
+     *
+     * @param source - Source system
+     * @param target - Target system
+     * @returns true if compatible
+     */
+    areSystemsCompatible(source: ProofSystem, target: ProofSystem): boolean;
+    /**
+     * Get cache statistics.
+     *
+     * @returns Cache stats
+     */
+    getCacheStats(): CacheStats;
+    /**
+     * Clear the proof cache.
+     *
+     * @param olderThan - Optional: only clear entries older than this timestamp
+     */
+    clearCache(olderThan?: number): void;
+    /**
+     * Get worker pool status.
+     *
+     * @returns Worker pool status
+     */
+    getWorkerPoolStatus(): WorkerPoolStatus;
+    /**
+     * Scale worker pool.
+     *
+     * @param targetWorkers - Target number of workers
+     */
+    scaleWorkerPool(targetWorkers: number): Promise<void>;
+    /**
+     * Set fallback configuration.
+     *
+     * @param config - Fallback configuration
+     */
+    setFallbackConfig(config: FallbackConfig): void;
+    /**
+     * Get current fallback configuration.
+     *
+     * @returns Fallback config or undefined
+     */
+    getFallbackConfig(): FallbackConfig | undefined;
+    /**
+     * Add an event listener.
+     *
+     * @param listener - Event listener
+     * @returns Unsubscribe function
+     */
+    addEventListener(listener: CompositionEventListener): () => void;
+    /**
+     * Remove an event listener.
+     *
+     * @param listener - Listener to remove
+     */
+    removeEventListener(listener: CompositionEventListener): void;
+    /**
+     * Set telemetry collector.
+     *
+     * @param collector - Telemetry collector
+     */
+    setTelemetryCollector(collector: TelemetryCollector): void;
+    /**
+     * Initialize the composer and all providers.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Dispose of resources.
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * Factory for creating proof providers
+ */
+type ProofProviderFactory = (config?: Record<string, unknown>) => Promise<ComposableProofProvider>;
+/**
+ * Registry of proof provider factories
+ */
+interface ProofProviderRegistry {
+    /** Register a provider factory */
+    register(system: ProofSystem, factory: ProofProviderFactory): void;
+    /** Get a provider factory */
+    get(system: ProofSystem): ProofProviderFactory | undefined;
+    /** Create a provider instance */
+    create(system: ProofSystem, config?: Record<string, unknown>): Promise<ComposableProofProvider>;
+    /** Get all registered systems */
+    getSystems(): ProofSystem[];
+}
+/**
+ * Error thrown during proof composition
+ */
+declare class ProofCompositionError extends Error {
+    readonly code: string;
+    readonly system?: ProofSystem;
+    readonly proofId?: string;
+    readonly cause?: Error;
+    constructor(code: string, message: string, options?: {
+        system?: ProofSystem;
+        proofId?: string;
+        cause?: Error;
+    });
+}
+/**
+ * Error thrown when a provider is not found
+ */
+declare class ProviderNotFoundError extends ProofCompositionError {
+    constructor(system: ProofSystem);
+}
+/**
+ * Error thrown when composition times out
+ */
+declare class CompositionTimeoutError extends ProofCompositionError {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+/**
+ * Error thrown when proof systems are incompatible
+ */
+declare class IncompatibleSystemsError extends ProofCompositionError {
+    readonly source: ProofSystem;
+    readonly target: ProofSystem;
+    constructor(source: ProofSystem, target: ProofSystem);
+}
+
+export { type AggregateProofsOptions as A, CompositionTimeoutError as C, type FallbackConfig as F, IncompatibleSystemsError as I, ProofCompositionError as P, type RegisterProviderOptions as R, type SystemCompatibility as S, type TelemetryCollector as T, type VerifyComposedProofOptions as V, type WorkerPoolConfig as W, ProviderNotFoundError as a, type ComposableProofProvider as b, type ProofComposer as c, type ProofProviderFactory as d, type ProofProviderRegistry as e, type ProofProviderRegistration as f, type ProofGenerationRequest as g, type ProofGenerationResult as h, type ComposeProofsOptions as i, type AggregationResult as j, type ConvertProofOptions as k, type ConversionResult as l, type ProofCacheEntry as m, type CacheStats as n, type WorkerPoolStatus as o, type CompatibilityMatrix as p, type ProofTelemetry as q, type ProofTelemetryMetrics as r };