voltaire-effect 0.3.0 → 1.0.1

package/src/services/BlockExplorerApi/BlockExplorerApiErrors.ts

@@ -0,0 +1,176 @@
+/**
+ * @fileoverview Block Explorer API error definitions.
+ *
+ * @module BlockExplorerApiErrors
+ * @since 0.0.1
+ *
+ * @description
+ * Strongly typed error classes for Block Explorer API operations.
+ * All errors are compatible with Effect.catchTag for type-safe error handling.
+ */
+
+import * as Data from "effect/Data";
+import type { ExplorerSourceId } from "./BlockExplorerApiTypes.js";
+
+/**
+ * Error thrown when configuration is invalid.
+ * @since 0.0.1
+ */
+export class BlockExplorerConfigError extends Data.TaggedError(
+	"BlockExplorerConfigError",
+)<{
+	readonly message: string;
+}> {
+	constructor(message: string) {
+		super({ message });
+	}
+}
+
+/**
+ * Error thrown when no ABI is found from any configured source.
+ * @since 0.0.1
+ */
+export class BlockExplorerNotFoundError extends Data.TaggedError(
+	"BlockExplorerNotFoundError",
+)<{
+	readonly address: `0x${string}`;
+	readonly attemptedSources: ReadonlyArray<string>;
+	readonly message: string;
+}> {
+	constructor(
+		address: `0x${string}`,
+		attemptedSources: ReadonlyArray<string>,
+	) {
+		super({
+			address,
+			attemptedSources,
+			message: `No ABI found for ${address}. Attempted sources: ${attemptedSources.join(", ")}`,
+		});
+	}
+}
+
+/**
+ * Error thrown when rate limited by a block explorer source.
+ * @since 0.0.1
+ */
+export class BlockExplorerRateLimitError extends Data.TaggedError(
+	"BlockExplorerRateLimitError",
+)<{
+	readonly source: ExplorerSourceId;
+	readonly address: `0x${string}`;
+	readonly message: string;
+	readonly retryAfterSeconds?: number;
+}> {
+	constructor(
+		source: ExplorerSourceId,
+		address: `0x${string}`,
+		message: string,
+		retryAfterSeconds?: number,
+	) {
+		super({ source, address, message, retryAfterSeconds });
+	}
+}
+
+/**
+ * Error thrown when a block explorer returns a non-200 response or network error.
+ * @since 0.0.1
+ */
+export class BlockExplorerResponseError extends Data.TaggedError(
+	"BlockExplorerResponseError",
+)<{
+	readonly source: ExplorerSourceId;
+	readonly address: `0x${string}`;
+	readonly status?: number;
+	readonly message: string;
+	readonly body?: string;
+}> {
+	constructor(
+		source: ExplorerSourceId,
+		address: `0x${string}`,
+		message: string,
+		options?: { status?: number; body?: string },
+	) {
+		super({
+			source,
+			address,
+			message,
+			status: options?.status,
+			body: options?.body,
+		});
+	}
+}
+
+/**
+ * Error thrown when a block explorer response cannot be decoded.
+ * @since 0.0.1
+ */
+export class BlockExplorerDecodeError extends Data.TaggedError(
+	"BlockExplorerDecodeError",
+)<{
+	readonly source: ExplorerSourceId;
+	readonly address: `0x${string}`;
+	readonly message: string;
+	readonly bodySnippet?: string;
+}> {
+	constructor(
+		source: ExplorerSourceId,
+		address: `0x${string}`,
+		message: string,
+		bodySnippet?: string,
+	) {
+		super({ source, address, message, bodySnippet });
+	}
+}
+
+/**
+ * Error thrown when proxy resolution fails.
+ * @since 0.0.1
+ */
+export class BlockExplorerProxyResolutionError extends Data.TaggedError(
+	"BlockExplorerProxyResolutionError",
+)<{
+	readonly address: `0x${string}`;
+	readonly message: string;
+}> {
+	constructor(address: `0x${string}`, message: string) {
+		super({ address, message });
+	}
+}
+
+/**
+ * Catch-all error for unexpected failures.
+ * @since 0.0.1
+ */
+export class BlockExplorerUnexpectedError extends Data.TaggedError(
+	"BlockExplorerUnexpectedError",
+)<{
+	readonly phase:
+		| "getAbi"
+		| "getContract"
+		| "getSources"
+		| "followProxies"
+		| "bestEffortRecovery";
+	readonly message: string;
+	readonly cause: unknown;
+}> {
+	constructor(
+		phase: BlockExplorerUnexpectedError["phase"],
+		message: string,
+		cause: unknown,
+	) {
+		super({ phase, message, cause });
+	}
+}
+
+/**
+ * Union of all Block Explorer API errors.
+ * @since 0.0.1
+ */
+export type BlockExplorerApiError =
+	| BlockExplorerConfigError
+	| BlockExplorerNotFoundError
+	| BlockExplorerRateLimitError
+	| BlockExplorerResponseError
+	| BlockExplorerDecodeError
+	| BlockExplorerProxyResolutionError
+	| BlockExplorerUnexpectedError;

package/src/services/BlockExplorerApi/BlockExplorerApiService.ts

@@ -0,0 +1,60 @@
+/**
+ * @fileoverview Block Explorer API service definition.
+ *
+ * @module BlockExplorerApiService
+ * @since 0.0.1
+ *
+ * @description
+ * The BlockExplorerApiService provides typed access to block explorer APIs
+ * for resolving contract ABIs, metadata, and source code.
+ */
+
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type {
+	AbiItem,
+	ContractSourceFile,
+	ExplorerContractInstance,
+	GetAbiOptions,
+	GetContractOptions,
+	GetSourcesOptions,
+} from "./BlockExplorerApiTypes.js";
+import type { BlockExplorerApiError } from "./BlockExplorerApiErrors.js";
+
+/**
+ * Service interface for Block Explorer API operations.
+ * @since 0.0.1
+ */
+export interface BlockExplorerApiShape {
+	/**
+	 * Fetch contract with callable read/write methods.
+	 */
+	readonly getContract: (
+		address: `0x${string}`,
+		options?: GetContractOptions,
+	) => Effect.Effect<ExplorerContractInstance, BlockExplorerApiError>;
+
+	/**
+	 * Convenience wrapper for getContract(...).abi
+	 */
+	readonly getAbi: (
+		address: `0x${string}`,
+		options?: GetAbiOptions,
+	) => Effect.Effect<ReadonlyArray<AbiItem>, BlockExplorerApiError>;
+
+	/**
+	 * Convenience wrapper for getContract(...).sources
+	 */
+	readonly getSources: (
+		address: `0x${string}`,
+		options?: GetSourcesOptions,
+	) => Effect.Effect<ReadonlyArray<ContractSourceFile>, BlockExplorerApiError>;
+}
+
+/**
+ * Block Explorer API service for resolving contract ABIs and metadata.
+ * @since 0.0.1
+ */
+export class BlockExplorerApiService extends Context.Tag(
+	"BlockExplorerApiService",
+)<BlockExplorerApiService, BlockExplorerApiShape>() {}

package/src/services/BlockExplorerApi/BlockExplorerApiTypes.ts

@@ -0,0 +1,225 @@
+/**
+ * @fileoverview Block Explorer API type definitions.
+ *
+ * @module BlockExplorerApiTypes
+ * @since 0.0.1
+ *
+ * @description
+ * Defines types for Block Explorer API configuration, responses, and errors.
+ * Used by BlockExplorerApiService to resolve ABIs and contract metadata.
+ */
+
+import type { Redacted } from "effect";
+import type * as Effect from "effect/Effect";
+import type { ContractCallError, ContractWriteError } from "../Contract/ContractTypes.js";
+import type { ProviderService } from "../Provider/ProviderService.js";
+import type { SignerService } from "../Signer/SignerService.js";
+
+/**
+ * Identifier for supported block explorer sources.
+ * @since 0.0.1
+ */
+export type ExplorerSourceId = "sourcify" | "etherscanV2" | "blockscout";
+
+/**
+ * Configuration for the Block Explorer API service.
+ * @since 0.0.1
+ */
+export interface BlockExplorerApiConfig {
+	readonly sources: {
+		readonly sourcify?: {
+			readonly enabled: boolean;
+			/** Custom Sourcify instance URL */
+			readonly baseUrl?: string;
+		};
+		readonly etherscanV2?: {
+			readonly enabled: boolean;
+			readonly apiKey?: Redacted.Redacted<string> | string;
+			/** Custom Etherscan-compatible API URL */
+			readonly baseUrl?: string;
+		};
+		readonly blockscout?: {
+			readonly enabled: boolean;
+			readonly apiKey?: Redacted.Redacted<string> | string;
+			/** Custom Blockscout instance URL */
+			readonly baseUrl?: string;
+		};
+	};
+
+	/**
+	 * Order for "verified-first" resolution.
+	 * Defaults to ["sourcify", "etherscanV2", "blockscout"].
+	 */
+	readonly sourceOrder?: ReadonlyArray<ExplorerSourceId>;
+
+	/**
+	 * Default behavior for proxy following.
+	 */
+	readonly followProxiesByDefault?: boolean;
+
+	/**
+	 * Enable best-effort ABI recovery (ABR) when verified ABI is missing.
+	 * Intended for inspection tooling.
+	 */
+	readonly enableBestEffortAbiRecovery?: boolean;
+
+	/**
+	 * Cache resolved ABIs.
+	 */
+	readonly cache?: {
+		readonly enabled: boolean;
+		readonly ttlMillis?: number;
+		readonly capacity?: number;
+	};
+}
+
+/**
+ * Single item in an ABI definition.
+ * Standard Solidity ABI format.
+ * @since 0.0.1
+ */
+export type AbiItem = {
+	readonly type: string;
+	readonly name?: string;
+	readonly inputs?: ReadonlyArray<{
+		readonly name?: string;
+		readonly type: string;
+		readonly indexed?: boolean;
+		readonly components?: ReadonlyArray<{ readonly name?: string; readonly type: string }>;
+	}>;
+	readonly outputs?: ReadonlyArray<{
+		readonly name?: string;
+		readonly type: string;
+		readonly components?: ReadonlyArray<{ readonly name?: string; readonly type: string }>;
+	}>;
+	readonly stateMutability?: "pure" | "view" | "nonpayable" | "payable";
+	readonly anonymous?: boolean;
+};
+
+/**
+ * Source file from a verified contract.
+ * @since 0.0.1
+ */
+export interface ContractSourceFile {
+	readonly path: string;
+	readonly content: string;
+}
+
+/**
+ * How the ABI was resolved.
+ * @since 0.0.1
+ */
+export type AbiResolution =
+	| { readonly mode: "verified"; readonly source: ExplorerSourceId }
+	| { readonly mode: "best-effort"; readonly source: "whatsabi" };
+
+/**
+ * Proxy chain entry for debugging/UX.
+ * @since 0.0.1
+ */
+export interface ProxyInfo {
+	readonly kind: string;
+	readonly address: `0x${string}`;
+}
+
+/**
+ * Result of resolving a contract from block explorers.
+ * @since 0.0.1
+ */
+export interface ResolvedExplorerContract {
+	/** Resolved address (implementation if proxies followed) */
+	readonly address: `0x${string}`;
+	/** Original input address */
+	readonly requestedAddress: `0x${string}`;
+	/** Contract name if available */
+	readonly name?: string;
+	/** Resolved ABI */
+	readonly abi: ReadonlyArray<AbiItem>;
+	/** How the ABI was resolved */
+	readonly resolution: AbiResolution;
+	/** Source files if requested and available */
+	readonly sources?: ReadonlyArray<ContractSourceFile>;
+	/** Proxy chain if followProxies was true */
+	readonly proxies?: ReadonlyArray<ProxyInfo>;
+}
+
+/**
+ * Options for getContract.
+ * @since 0.0.1
+ */
+export interface GetContractOptions {
+	/**
+	 * Resolution mode for ABI retrieval.
+	 * - "verified-only": Only verified ABIs, fail if not found
+	 * - "verified-first": Try verified first, fail if not found (default)
+	 * - "best-effort": Fall back to ABI recovery when unverified
+	 */
+	readonly resolution?: "verified-only" | "verified-first" | "best-effort";
+	/** Include source files in response */
+	readonly includeSources?: boolean;
+	/** Follow proxy contracts to implementation */
+	readonly followProxies?: boolean;
+}
+
+/**
+ * Options for getAbi.
+ * @since 0.0.1
+ */
+export interface GetAbiOptions {
+	readonly resolution?: "verified-only" | "verified-first" | "best-effort";
+	readonly followProxies?: boolean;
+}
+
+/**
+ * Options for getSources.
+ * @since 0.0.1
+ */
+export interface GetSourcesOptions {
+	readonly followProxies?: boolean;
+}
+
+/**
+ * Dynamic contract instance with callable methods.
+ * Returned by getContract() for interacting with contracts.
+ * @since 0.0.1
+ */
+export interface ExplorerContractInstance {
+	/** Resolved address (implementation if proxies followed) */
+	readonly address: `0x${string}`;
+	/** Original input address */
+	readonly requestedAddress: `0x${string}`;
+	/** Resolved ABI */
+	readonly abi: ReadonlyArray<AbiItem>;
+	/** How the ABI was resolved */
+	readonly resolution: AbiResolution;
+	/** Contract name if available */
+	readonly name?: string;
+	/** Source files if requested and available */
+	readonly sources?: ReadonlyArray<ContractSourceFile>;
+	/** Proxy chain if followProxies was true */
+	readonly proxies?: ReadonlyArray<ProxyInfo>;
+
+	/** Read-only methods (view/pure) */
+	readonly read: Record<
+		string,
+		(...args: ReadonlyArray<unknown>) => Effect.Effect<unknown, ContractCallError, ProviderService>
+	>;
+
+	/** Simulate state-changing methods */
+	readonly simulate: Record<
+		string,
+		(...args: ReadonlyArray<unknown>) => Effect.Effect<unknown, ContractCallError, ProviderService>
+	>;
+
+	/** State-changing methods */
+	readonly write: Record<
+		string,
+		(...args: ReadonlyArray<unknown>) => Effect.Effect<`0x${string}`, ContractWriteError, SignerService>
+	>;
+
+	/** Explicit signature-based access */
+	readonly call: (
+		signature: string,
+		args: ReadonlyArray<unknown>,
+	) => Effect.Effect<unknown, ContractCallError, ProviderService>;
+}

package/src/services/BlockExplorerApi/index.ts

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview Block Explorer API module exports.
+ *
+ * @module BlockExplorerApi
+ * @since 0.0.1
+ */
+
+// Types
+export type {
+	AbiItem,
+	AbiResolution,
+	BlockExplorerApiConfig,
+	ContractSourceFile,
+	ExplorerContractInstance,
+	ExplorerSourceId,
+	GetAbiOptions,
+	GetContractOptions,
+	GetSourcesOptions,
+	ProxyInfo,
+	ResolvedExplorerContract,
+} from "./BlockExplorerApiTypes.js";
+
+// Errors
+export {
+	BlockExplorerConfigError,
+	BlockExplorerDecodeError,
+	BlockExplorerNotFoundError,
+	BlockExplorerProxyResolutionError,
+	BlockExplorerRateLimitError,
+	BlockExplorerResponseError,
+	BlockExplorerUnexpectedError,
+	type BlockExplorerApiError,
+} from "./BlockExplorerApiErrors.js";
+
+// Service
+export {
+	BlockExplorerApiService,
+	type BlockExplorerApiShape,
+} from "./BlockExplorerApiService.js";
+
+// Layer factory
+export { BlockExplorerApi } from "./BlockExplorerApi.js";

package/src/services/Contract/Contract.test.ts

@@ -1,10 +1,7 @@
-// @ts-nocheck - TODO: Fix ABI type inference issues
 import { beforeEach, describe, expect, it, vi } from "@effect/vitest";
 import { Address } from "@tevm/voltaire";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
-import * as S from "effect/Schema";
-import { fromArray } from "../../primitives/Abi/AbiSchema.js";
 import { ProviderService } from "../Provider/index.js";
 import { SignerService } from "../Signer/index.js";
 import { Contract } from "./Contract.js";
@@ -13,8 +10,7 @@ type HexType = `0x${string}`;
 
 const testAddress = Address("0x6B175474E89094C44Da98b954EecdEfaE6E286AB");
 
-// Cast to any to bypass strict ABI type checking - schema returns Item[] not strongly typed ABI
-const erc20Abi = S.decodeUnknownSync(fromArray)([
+const erc20Abi = [
 	{
 		type: "function",
 		name: "balanceOf",
@@ -99,7 +95,7 @@ const erc20Abi = S.decodeUnknownSync(fromArray)([
 			{ name: "value", type: "uint256", indexed: false },
 		],
 	},
-]) as any;
+] as const;
 
 const mockCallFn = vi.fn();
 const mockGetLogsFn = vi.fn();

package/src/services/Contract/ContractTypes.ts

@@ -328,10 +328,30 @@ type ExtractEventNames<TAbi extends Abi> =
 type AbiInputsToArgs<
 	TInputs extends readonly { type: string; name?: string }[],
 > = {
-	[K in keyof TInputs]: AbiTypeToTs<TInputs[K]["type"]>;
+	[K in keyof TInputs]: AbiTypeToInput<TInputs[K]["type"]>;
 };
 
-type AbiTypeToTs<T extends string> = T extends `uint${string}`
+type BytesInput = Uint8Array | `0x${string}`;
+
+type AbiTypeToInput<T extends string> = T extends `uint${string}`
+	? bigint
+	: T extends `int${string}`
+		? bigint
+		: T extends "address"
+			? AddressType
+			: T extends "bool"
+				? boolean
+				: T extends "string"
+					? string
+					: T extends `bytes${string}` | "bytes"
+						? BytesInput
+						: T extends `${string}[]`
+								? readonly unknown[]
+								: T extends `tuple`
+									? Record<string, unknown>
+									: unknown;
+
+type AbiTypeToOutput<T extends string> = T extends `uint${string}`
 	? bigint
 	: T extends `int${string}`
 		? bigint
@@ -341,11 +361,9 @@ type AbiTypeToTs<T extends string> = T extends `uint${string}`
 				? boolean
 				: T extends "string"
 					? string
-					: T extends `bytes${string}`
-						? HexType
-						: T extends "bytes"
-							? HexType
-							: T extends `${string}[]`
+					: T extends `bytes${string}` | "bytes"
+						? Uint8Array
+						: T extends `${string}[]`
 								? readonly unknown[]
 								: T extends `tuple`
 									? Record<string, unknown>
@@ -354,7 +372,7 @@ type AbiTypeToTs<T extends string> = T extends `uint${string}`
 type AbiOutputToTs<TOutputs extends readonly { type: string }[]> =
 	TOutputs extends readonly [{ type: infer T }]
 		? T extends string
-			? AbiTypeToTs<T>
+			? AbiTypeToOutput<T>
 			: unknown
 		: TOutputs extends readonly []
 			? undefined

package/src/services/Contract/estimateGas.test.ts

@@ -1,10 +1,7 @@
-// @ts-nocheck - TODO: Fix ABI type inference issues
 import { beforeEach, describe, expect, it, vi } from "@effect/vitest";
 import { Address, BrandedAbi } from "@tevm/voltaire";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
-import * as S from "effect/Schema";
-import { fromArray } from "../../primitives/Abi/AbiSchema.js";
 import { ProviderService } from "../Provider/index.js";
 import { Contract } from "./Contract.js";
 
@@ -12,7 +9,7 @@ type HexType = `0x${string}`;
 
 const testAddress = Address("0x6B175474E89094C44Da98b954EecdEfaE6E286AB");
 
-const erc20Abi = S.decodeUnknownSync(fromArray)([
+const erc20Abi = [
 	{
 		type: "function",
 		name: "transfer",
@@ -30,7 +27,7 @@ const erc20Abi = S.decodeUnknownSync(fromArray)([
 		inputs: [],
 		outputs: [],
 	},
-]);
+] as const;
 
 const mockEstimateGasFn = vi.fn();
 
@@ -76,7 +73,7 @@ describe("Contract.estimateGas", () => {
 
 		const callArgs = mockEstimateGasFn.mock.calls[0][0];
 		const expectedData = BrandedAbi.encodeFunction(
-			erc20Abi as unknown as BrandedAbi.Abi,
+			erc20Abi,
 			"transfer",
 			[recipient, amount],
 		);
@@ -98,7 +95,7 @@ describe("Contract.estimateGas", () => {
 
 		const callArgs = mockEstimateGasFn.mock.calls[0][0];
 		const expectedData = BrandedAbi.encodeFunction(
-			erc20Abi as unknown as BrandedAbi.Abi,
+			erc20Abi,
 			"deposit",
 			[],
 		);