voltaire-effect 1.0.0 → 1.0.1

package/dist/KZGService-B7PJerOb.d.ts

@@ -0,0 +1,146 @@
+import * as effect_Cause from 'effect/Cause';
+import * as effect_Types from 'effect/Types';
+import { KzgBlobType, KzgCommitmentType, KzgProofType } from '@tevm/voltaire';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+declare const KZGError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
+    readonly _tag: "KZGError";
+} & Readonly<A>;
+/**
+ * Error thrown when a KZG operation fails.
+ *
+ * @description
+ * Contains the operation that failed, error code, message, and optional cause.
+ *
+ * Common failure reasons:
+ * - Trusted setup not loaded (SETUP_NOT_LOADED)
+ * - Invalid blob size or format (INVALID_BLOB)
+ * - Invalid commitment format (INVALID_COMMITMENT)
+ * - Invalid proof format (INVALID_PROOF)
+ * - Verification failure
+ *
+ * @since 0.0.1
+ */
+declare class KZGError extends KZGError_base<{
+    /** Error code for programmatic handling */
+    readonly code: "SETUP_NOT_LOADED" | "INVALID_BLOB" | "INVALID_COMMITMENT" | "INVALID_PROOF" | "OPERATION_FAILED";
+    /** The KZG operation that failed */
+    readonly operation: "blobToKzgCommitment" | "computeBlobKzgProof" | "verifyBlobKzgProof" | "loadTrustedSetup" | "isInitialized";
+    /** Human-readable error message */
+    readonly message: string;
+    /** Underlying error that caused this failure */
+    readonly cause?: unknown;
+}> {
+}
+/**
+ * Shape interface for KZG commitment service operations.
+ *
+ * @description
+ * Defines the contract for KZG implementations. Operations require the trusted
+ * setup to be loaded first via loadTrustedSetup().
+ *
+ * @since 0.0.1
+ */
+interface KZGServiceShape {
+    /**
+     * Computes a KZG commitment for a blob.
+     * @param blob - The 128KB blob data
+     * @returns Effect containing the 48-byte commitment, or KZGError if operation fails
+     */
+    readonly blobToKzgCommitment: (blob: KzgBlobType) => Effect.Effect<KzgCommitmentType, KZGError>;
+    /**
+     * Computes a KZG proof for a blob and commitment.
+     * @param blob - The 128KB blob data
+     * @param commitment - The 48-byte commitment
+     * @returns Effect containing the 48-byte proof, or KZGError if operation fails
+     */
+    readonly computeBlobKzgProof: (blob: KzgBlobType, commitment: KzgCommitmentType) => Effect.Effect<KzgProofType, KZGError>;
+    /**
+     * Verifies a KZG proof against a blob and commitment.
+     * @param blob - The 128KB blob data
+     * @param commitment - The 48-byte commitment
+     * @param proof - The 48-byte proof
+     * @returns Effect containing true if proof is valid, or KZGError if operation fails
+     */
+    readonly verifyBlobKzgProof: (blob: KzgBlobType, commitment: KzgCommitmentType, proof: KzgProofType) => Effect.Effect<boolean, KZGError>;
+    /**
+     * Loads the trusted setup for KZG operations.
+     * @returns Effect that completes when setup is loaded, or KZGError if loading fails
+     */
+    readonly loadTrustedSetup: () => Effect.Effect<void, KZGError>;
+    /**
+     * Checks if the trusted setup has been initialized.
+     * @returns Effect containing true if initialized, or KZGError if check fails
+     */
+    readonly isInitialized: () => Effect.Effect<boolean, KZGError>;
+}
+declare const KZGService_base: Context.TagClass<KZGService, "KZGService", KZGServiceShape>;
+/**
+ * KZG polynomial commitment service for Effect-based applications.
+ * Implements EIP-4844 blob commitments for Ethereum proto-danksharding.
+ *
+ * @example
+ * ```typescript
+ * import { KZGService, KZGLive } from 'voltaire-effect/crypto'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const kzg = yield* KZGService
+ *   yield* kzg.loadTrustedSetup()
+ *   const commitment = yield* kzg.blobToKzgCommitment(blob)
+ *   const proof = yield* kzg.computeBlobKzgProof(blob, commitment)
+ *   return yield* kzg.verifyBlobKzgProof(blob, commitment, proof)
+ * }).pipe(Effect.provide(KZGLive))
+ * ```
+ * @since 0.0.1
+ */
+declare class KZGService extends KZGService_base {
+}
+/**
+ * Production layer for KZGService using native KZG implementation.
+ *
+ * @description
+ * Provides real KZG operations using the c-kzg-4844 library with Ethereum's
+ * trusted setup. The trusted setup must be loaded before other operations.
+ *
+ * @example
+ * ```typescript
+ * import { KZGService, KZGLive } from 'voltaire-effect/crypto/KZG'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const kzg = yield* KZGService
+ *   yield* kzg.loadTrustedSetup()
+ *   const commitment = yield* kzg.blobToKzgCommitment(blob)
+ *   return commitment
+ * }).pipe(Effect.provide(KZGLive))
+ * ```
+ *
+ * @since 0.0.1
+ * @see {@link KZGTest} for unit testing
+ */
+declare const KZGLive: Layer.Layer<KZGService, never, never>;
+/**
+ * Test layer for KZGService returning deterministic mock values.
+ *
+ * @description
+ * Provides mock implementations for unit testing. Returns zero-filled
+ * arrays for commitments/proofs and always verifies as true.
+ * Use when testing application logic without cryptographic overhead.
+ *
+ * @example
+ * ```typescript
+ * import { KZGService, KZGTest, blobToKzgCommitment } from 'voltaire-effect/crypto/KZG'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const testProgram = blobToKzgCommitment(blob).pipe(Effect.provide(KZGTest))
+ * // Returns Uint8Array(48) filled with zeros
+ * ```
+ *
+ * @since 0.0.1
+ */
+declare const KZGTest: Layer.Layer<KZGService, never, never>;
+
+export { KZGService as K, KZGError as a, KZGLive as b, type KZGServiceShape as c, KZGTest as d };

package/dist/ProviderService-BZ5pqDrD.d.ts

@@ -0,0 +1,319 @@
+import { Keccak256Hash } from '@tevm/voltaire';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as effect_Cause from 'effect/Cause';
+import * as effect_Types from 'effect/Types';
+
+/**
+ * @fileoverview Keccak-256 service definition and layer implementations for Effect.
+ *
+ * @description
+ * Provides the KeccakService Effect Tag and both production (KeccakLive) and
+ * test (KeccakTest) layer implementations. The service pattern enables
+ * dependency injection for testability and flexibility.
+ *
+ * @module Keccak256/KeccakService
+ * @since 0.0.1
+ */
+
+/**
+ * Shape interface for the Keccak-256 hashing service.
+ *
+ * @description
+ * Defines the contract for Keccak-256 hash implementations.
+ * Used as the service shape for {@link KeccakService}.
+ *
+ * @since 0.0.1
+ */
+interface KeccakServiceShape {
+    /**
+     * Computes the Keccak-256 hash of input data.
+     *
+     * @param {Uint8Array} data - The input bytes to hash (any length)
+     * @returns {Effect.Effect<Keccak256Hash>} Effect containing the 32-byte hash
+     */
+    readonly hash: (data: Uint8Array) => Effect.Effect<Keccak256Hash>;
+}
+declare const KeccakService_base: Context.TagClass<KeccakService, "KeccakService", KeccakServiceShape>;
+/**
+ * Keccak-256 hashing service for Effect-based applications.
+ *
+ * @description
+ * An Effect Context.Tag that provides the standard Ethereum hashing algorithm
+ * used for addresses, signatures, state roots, and more. The service pattern
+ * enables swapping implementations for testing or alternative backends.
+ *
+ * The service exposes a single `hash` method that takes arbitrary bytes and
+ * produces a 32-byte Keccak-256 hash.
+ *
+ * @example Basic usage with Effect.gen
+ * ```typescript
+ * import { KeccakService, KeccakLive } from 'voltaire-effect/crypto/Keccak256'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const keccak = yield* KeccakService
+ *   return yield* keccak.hash(new Uint8Array([1, 2, 3]))
+ * }).pipe(Effect.provide(KeccakLive))
+ *
+ * const hash = await Effect.runPromise(program)
+ * ```
+ *
+ * @example Chaining multiple hashes
+ * ```typescript
+ * import { KeccakService, KeccakLive } from 'voltaire-effect/crypto/Keccak256'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const doubleHash = Effect.gen(function* () {
+ *   const keccak = yield* KeccakService
+ *   const first = yield* keccak.hash(new Uint8Array([1, 2, 3]))
+ *   return yield* keccak.hash(first)
+ * }).pipe(Effect.provide(KeccakLive))
+ * ```
+ *
+ * @example Composing with other services
+ * ```typescript
+ * import { KeccakService, KeccakLive } from 'voltaire-effect/crypto/Keccak256'
+ * import { Secp256k1Service, Secp256k1Live } from 'voltaire-effect/crypto/Secp256k1'
+ * import * as Effect from 'effect/Effect'
+ * import * as Layer from 'effect/Layer'
+ *
+ * const program = Effect.gen(function* () {
+ *   const keccak = yield* KeccakService
+ *   const secp = yield* Secp256k1Service
+ *   const msgHash = yield* keccak.hash(message)
+ *   return yield* secp.sign(msgHash, privateKey)
+ * }).pipe(Effect.provide(Layer.merge(KeccakLive, Secp256k1Live)))
+ * ```
+ *
+ * @see {@link KeccakLive} - Production implementation
+ * @see {@link KeccakTest} - Test implementation
+ * @see {@link hash} - Standalone hash function
+ * @since 0.0.1
+ */
+declare class KeccakService extends KeccakService_base {
+}
+/**
+ * Production layer for KeccakService using native Keccak-256 implementation.
+ *
+ * @description
+ * Provides the real Keccak-256 hash implementation from the voltaire library.
+ * Use this layer in production applications for cryptographically secure hashing.
+ *
+ * The underlying implementation uses optimized native code (Zig/Rust) for
+ * high-performance hashing.
+ *
+ * @example Providing the live layer
+ * ```typescript
+ * import { KeccakService, KeccakLive } from 'voltaire-effect/crypto/Keccak256'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const keccak = yield* KeccakService
+ *   return yield* keccak.hash(new Uint8Array([0xde, 0xad, 0xbe, 0xef]))
+ * })
+ *
+ * const result = await Effect.runPromise(program.pipe(Effect.provide(KeccakLive)))
+ * ```
+ *
+ * @example Merging with other layers
+ * ```typescript
+ * import { KeccakLive } from 'voltaire-effect/crypto/Keccak256'
+ * import { SHA256Live } from 'voltaire-effect/crypto/SHA256'
+ * import * as Layer from 'effect/Layer'
+ *
+ * const CryptoLive = Layer.merge(KeccakLive, SHA256Live)
+ * ```
+ *
+ * @see {@link KeccakService} - The service tag
+ * @see {@link KeccakTest} - Test implementation for unit tests
+ * @since 0.0.1
+ */
+declare const KeccakLive: Layer.Layer<KeccakService, never, never>;
+/**
+ * Test layer for KeccakService returning deterministic zero-filled hashes.
+ *
+ * @description
+ * Provides a mock Keccak-256 implementation that always returns a 32-byte
+ * array filled with zeros. Use for unit testing without cryptographic overhead
+ * when the actual hash value doesn't matter for the test.
+ *
+ * This layer is useful for:
+ * - Unit tests that need deterministic output
+ * - Performance tests that want to isolate non-crypto logic
+ * - Tests where the hash value is not validated
+ *
+ * @example Using in tests
+ * ```typescript
+ * import { KeccakService, KeccakTest } from 'voltaire-effect/crypto/Keccak256'
+ * import * as Effect from 'effect/Effect'
+ * import { describe, it, expect } from 'vitest'
+ *
+ * describe('MyService', () => {
+ *   it('should hash data', async () => {
+ *     const program = Effect.gen(function* () {
+ *       const keccak = yield* KeccakService
+ *       return yield* keccak.hash(new Uint8Array([1, 2, 3]))
+ *     })
+ *
+ *     const result = await Effect.runPromise(program.pipe(Effect.provide(KeccakTest)))
+ *     expect(result).toEqual(new Uint8Array(32)) // All zeros
+ *   })
+ * })
+ * ```
+ *
+ * @see {@link KeccakService} - The service tag
+ * @see {@link KeccakLive} - Production implementation
+ * @since 0.0.1
+ */
+declare const KeccakTest: Layer.Layer<KeccakService, never, never>;
+
+/**
+ * @fileoverview Transport error class for JSON-RPC communication failures.
+ *
+ * @module TransportError
+ * @since 0.0.1
+ *
+ * @description
+ * Defines the error type used by all transport implementations when JSON-RPC
+ * communication fails. The error includes the JSON-RPC error code, message,
+ * and optional additional data for debugging.
+ *
+ * Common JSON-RPC error codes:
+ * - -32700: Parse error
+ * - -32600: Invalid request
+ * - -32601: Method not found
+ * - -32602: Invalid params
+ * - -32603: Internal error
+ * - -32000 to -32099: Server errors (implementation-defined)
+ *
+ * @see {@link TransportService} - The service that uses this error type
+ */
+declare const TransportError_base: new <A extends Record<string, any> = {}>(args: effect_Types.Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => effect_Cause.YieldableError & {
+    readonly _tag: "TransportError";
+} & Readonly<A>;
+/**
+ * Error thrown when a transport operation fails.
+ *
+ * @description
+ * Contains JSON-RPC error code and optional data for debugging.
+ * This error is thrown by all transport implementations (HttpTransport,
+ * WebSocketTransport, BrowserTransport) when a JSON-RPC request fails.
+ *
+ * The error includes:
+ * - `code`: Standard JSON-RPC error code
+ * - `message`: Human-readable error description
+ * - `data`: Optional additional error data from the provider
+ *
+ * @since 0.0.1
+ *
+ * @example Creating a transport error
+ * ```typescript
+ * const error = new TransportError({
+ *   code: -32603,
+ *   message: 'Internal error',
+ *   data: { details: 'Connection refused' }
+ * })
+ *
+ * console.log(error.code)    // -32603
+ * console.log(error.message) // 'Internal error'
+ * console.log(error.data)    // { details: 'Connection refused' }
+ * ```
+ *
+ * @example Handling transport errors in Effect
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { TransportService, TransportError, HttpTransport } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const transport = yield* TransportService
+ *   return yield* transport.request<string>('eth_blockNumber')
+ * }).pipe(
+ *   Effect.catchTag('TransportError', (error) => {
+ *     if (error.code === -32601) {
+ *       console.log('Method not supported by this node')
+ *     }
+ *     return Effect.fail(error)
+ *   }),
+ *   Effect.provide(HttpTransport('https://mainnet.infura.io/v3/YOUR_KEY'))
+ * )
+ * ```
+ *
+ * @see {@link TransportService} - The service that produces this error
+ */
+declare class TransportError extends TransportError_base<{
+    /**
+     * The original input that caused the error.
+     */
+    readonly input: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+    /**
+     * JSON-RPC error code.
+     */
+    readonly code: number;
+    /**
+     * Human-readable error message.
+     */
+    readonly message: string;
+    /**
+     * Additional error data from the JSON-RPC response.
+     *
+     * @description
+     * May contain provider-specific error details such as revert reasons,
+     * stack traces, or other debugging information.
+     */
+    readonly data?: unknown;
+    /**
+     * Optional underlying cause.
+     */
+    readonly cause?: unknown;
+    /**
+     * Optional context for debugging.
+     */
+    readonly context?: Record<string, unknown>;
+}> {
+    /**
+     * Creates a new TransportError.
+     *
+     * @param input - JSON-RPC error response containing code, message, and optional data
+     * @param message - Optional override for the error message
+     * @param options - Optional error options
+     * @param options.cause - Underlying error that caused this failure
+     */
+    constructor(input: {
+        code: number;
+        message: string;
+        data?: unknown;
+    }, message?: string, options?: {
+        cause?: unknown;
+        context?: Record<string, unknown>;
+    });
+}
+
+/**
+ * @fileoverview Minimal Provider service for blockchain JSON-RPC operations.
+ *
+ * @module ProviderService
+ * @since 0.0.1
+ */
+
+/**
+ * Minimal provider shape - only the request method.
+ * All operations are exposed as free functions that use this internally.
+ */
+type ProviderShape = {
+    readonly request: <T>(method: string, params?: unknown[]) => Effect.Effect<T, TransportError>;
+};
+declare const ProviderService_base: Context.TagClass<ProviderService, "ProviderService", ProviderShape>;
+/**
+ * Provider service for blockchain JSON-RPC operations.
+ * Use free functions (getBalance, getBlock, call, etc.) for operations.
+ */
+declare class ProviderService extends ProviderService_base {
+}
+
+export { KeccakService as K, ProviderService as P, TransportError as T, type ProviderShape as a, KeccakLive as b, KeccakTest as c, type KeccakServiceShape as d };