voltaire-effect 0.2.23

package/src/services/Ccip/Ccip.test.ts

@@ -0,0 +1,569 @@
+import {
+	afterEach,
+	beforeEach,
+	describe,
+	expect,
+	it,
+	vi,
+} from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import { CcipError, CcipService } from "./CcipService.js";
+import { DefaultCcip } from "./DefaultCcip.js";
+import { NoopCcip } from "./NoopCcip.js";
+
+const createMockResponse = (options: {
+	ok?: boolean;
+	status?: number;
+	statusText?: string;
+	contentType?: string;
+	body?: unknown;
+	textBody?: string;
+	jsonThrows?: boolean;
+	textThrows?: boolean;
+}): Response => {
+	const {
+		ok = true,
+		status = 200,
+		statusText = "OK",
+		contentType = "application/json",
+		body = { data: "0xabcd" },
+		textBody,
+		jsonThrows = false,
+		textThrows = false,
+	} = options;
+
+	return {
+		ok,
+		status,
+		statusText,
+		headers: {
+			get: (name: string) => (name === "Content-Type" ? contentType : null),
+		},
+		json: jsonThrows
+			? () => Promise.reject(new Error("JSON parse error"))
+			: () => Promise.resolve(body),
+		text: textThrows
+			? () => Promise.reject(new Error("Text read error"))
+			: () => Promise.resolve(textBody ?? JSON.stringify(body)),
+	} as unknown as Response;
+};
+
+const baseRequest = {
+	sender: "0x1234567890123456789012345678901234567890" as const,
+	callData: "0xdeadbeef" as const,
+	callbackSelector: "0x12345678" as const,
+	extraData: "0x" as const,
+};
+
+/**
+ * Creates a properly typed fetch mock that includes the preconnect method.
+ */
+const createFetchMock = (impl: ReturnType<typeof vi.fn>) => {
+	const mock = impl as unknown as typeof fetch;
+	(mock as unknown as Record<string, unknown>).preconnect = vi.fn();
+	return mock;
+};
+
+describe("DefaultCcip", () => {
+	let originalFetch: typeof globalThis.fetch;
+
+	beforeEach(() => {
+		originalFetch = globalThis.fetch;
+	});
+
+	afterEach(() => {
+		globalThis.fetch = originalFetch;
+	});
+
+	describe("GET vs POST selection", () => {
+		it("uses GET when URL contains {data}", async () => {
+			const fetchMock = vi.fn().mockResolvedValue(createMockResponse({}));
+			globalThis.fetch = createFetchMock(fetchMock);
+
+			const program = Effect.gen(function* () {
+				const ccip = yield* CcipService;
+				return yield* ccip.request({
+					...baseRequest,
+					urls: ["https://gateway.example.com/{sender}/{data}"],
+				});
+			}).pipe(Effect.provide(DefaultCcip));
+
+			await Effect.runPromise(program);
+
+			expect(fetchMock).toHaveBeenCalledWith(
+				expect.stringContaining("0xdeadbeef"),
+				expect.objectContaining({ method: "GET" }),
+			);
+		});
+
+		it("uses POST when URL does not contain {data}", async () => {
+			const fetchMock = vi.fn().mockResolvedValue(createMockResponse({}));
+			globalThis.fetch = createFetchMock(fetchMock);
+
+			const program = Effect.gen(function* () {
+				const ccip = yield* CcipService;
+				return yield* ccip.request({
+					...baseRequest,
+					urls: ["https://gateway.example.com/{sender}"],
+				});
+			}).pipe(Effect.provide(DefaultCcip));
+
+			await Effect.runPromise(program);
+
+			expect(fetchMock).toHaveBeenCalledWith(
+				expect.any(String),
+				expect.objectContaining({
+					method: "POST",
+					body: JSON.stringify({
+						sender: baseRequest.sender,
+						data: baseRequest.callData,
+					}),
+					headers: { "Content-Type": "application/json" },
+				}),
+			);
+		});
+	});
+
+	describe("URL templating", () => {
+		it("replaces {sender} with lowercase address", async () => {
+			const fetchMock = vi.fn().mockResolvedValue(createMockResponse({}));
+			globalThis.fetch = createFetchMock(fetchMock);
+
+			const program = Effect.gen(function* () {
+				const ccip = yield* CcipService;
+				return yield* ccip.request({
+					...baseRequest,
+					sender: "0xABCDEF1234567890ABCDEF1234567890ABCDEF12",
+					urls: ["https://gateway.example.com/{sender}/{data}"],
+				});
+			}).pipe(Effect.provide(DefaultCcip));
+
+			await Effect.runPromise(program);
+
+			expect(fetchMock).toHaveBeenCalledWith(
+				expect.stringContaining("0xabcdef1234567890abcdef1234567890abcdef12"),
+				expect.any(Object),
+			);
+		});
+
+		it("replaces {data} with callData", async () => {
+			const fetchMock = vi.fn().mockResolvedValue(createMockResponse({}));
+			globalThis.fetch = createFetchMock(fetchMock);
+
+			const program = Effect.gen(function* () {
+				const ccip = yield* CcipService;
+				return yield* ccip.request({
+					...baseRequest,
+					callData: "0xcafebabe",
+					urls: ["https://gateway.example.com/{sender}/{data}"],
+				});
+			}).pipe(Effect.provide(DefaultCcip));
+
+			await Effect.runPromise(program);
+
+			expect(fetchMock).toHaveBeenCalledWith(
+				expect.stringContaining("0xcafebabe"),
+				expect.any(Object),
+			);
+		});
+	});
+
+	describe("multi-URL fallback", () => {
+		it("tries second URL when first fails", async () => {
+			let callCount = 0;
+			const fetchMock = vi.fn().mockImplementation(() => {
+				callCount++;
+				if (callCount === 1) {
+					return Promise.resolve(
+						createMockResponse({
+							ok: false,
+							status: 500,
+							statusText: "Internal Server Error",
+							textBody: "Server Error",
+						}),
+					);
+				}
+				return Promise.resolve(
+					createMockResponse({
+						contentType: "application/json",
+						body: { data: "0x5ccce55" },
+					}),
+				);
+			});
+			globalThis.fetch = createFetchMock(fetchMock);
+
+			const program = Effect.gen(function* () {
+				const ccip = yield* CcipService;
+				return yield* ccip.request({
+					...baseRequest,
+					urls: [
+						"https://first.example.com/{sender}/{data}",
+						"https://second.example.com/{sender}/{data}",
+					],
+				});
+			}).pipe(Effect.provide(DefaultCcip));
+
+			const result = await Effect.runPromise(program);
+
+			expect(result).toBe("0x5ccce55");
+			expect(fetchMock).toHaveBeenCalledTimes(2);
+		});
+
+		it("returns first successful result", async () => {
+			const fetchMock = vi.fn().mockResolvedValue(
+				createMockResponse({
+					contentType: "application/json",
+					body: { data: "0xf1257" },
+				}),
+			);
+			globalThis.fetch = createFetchMock(fetchMock);
+
+			const program = Effect.gen(function* () {
+				const ccip = yield* CcipService;
+				return yield* ccip.request({
+					...baseRequest,
+					urls: [
+						"https://first.example.com/{sender}/{data}",
+						"https://second.example.com/{sender}/{data}",
+					],
+				});
+			}).pipe(Effect.provide(DefaultCcip));
+
+			const result = await Effect.runPromise(program);
+
+			expect(result).toBe("0xf1257");
+			expect(fetchMock).toHaveBeenCalledTimes(1);
+		});
+	});
+
+	describe("error handling", () => {
+		it("fails with CcipError when URL list is empty", async () => {
+			const program = Effect.gen(function* () {
+				const ccip = yield* CcipService;
+				return yield* ccip.request({
+					...baseRequest,
+					urls: [],
+				});
+			}).pipe(Effect.provide(DefaultCcip));
+
+			const exit = await Effect.runPromiseExit(program);
+
+			expect(Exit.isFailure(exit)).toBe(true);
+			if (Exit.isFailure(exit)) {
+				const error = exit.cause._tag === "Fail" ? exit.cause.error : null;
+				expect(error).toBeInstanceOf(CcipError);
+				expect((error as CcipError).message).toBe(
+					"No URLs provided for CCIP lookup",
+				);
+			}
+		});
+
+		it("includes HTTP status in error message", async () => {
+			const fetchMock = vi.fn().mockResolvedValue(
+				createMockResponse({
+					ok: false,
+					status: 404,
+					statusText: "Not Found",
+					textBody: "Resource not found",
+				}),
+			);
+			globalThis.fetch = createFetchMock(fetchMock);
+
+			const program = Effect.gen(function* () {
+				const ccip = yield* CcipService;
+				return yield* ccip.request({
+					...baseRequest,
+					urls: ["https://gateway.example.com/{sender}/{data}"],
+				});
+			}).pipe(Effect.provide(DefaultCcip));
+
+			const exit = await Effect.runPromiseExit(program);
+
+			expect(Exit.isFailure(exit)).toBe(true);
+			if (Exit.isFailure(exit)) {
+				const error = exit.cause._tag === "Fail" ? exit.cause.error : null;
+				expect(error).toBeInstanceOf(CcipError);
+				expect((error as CcipError).message).toContain("404");
+			}
+		});
+
+		it("handles fetch rejection", async () => {
+			const fetchMock = vi.fn().mockRejectedValue(new Error("Network error"));
+			globalThis.fetch = createFetchMock(fetchMock);
+
+			const program = Effect.gen(function* () {
+				const ccip = yield* CcipService;
+				return yield* ccip.request({
+					...baseRequest,
+					urls: ["https://gateway.example.com/{sender}/{data}"],
+				});
+			}).pipe(Effect.provide(DefaultCcip));
+
+			const exit = await Effect.runPromiseExit(program);
+
+			expect(Exit.isFailure(exit)).toBe(true);
+			if (Exit.isFailure(exit)) {
+				const error = exit.cause._tag === "Fail" ? exit.cause.error : null;
+				expect(error).toBeInstanceOf(CcipError);
+				expect((error as CcipError).message).toContain("Fetch failed");
+				expect((error as CcipError).message).toContain("Network error");
+			}
+		});
+
+		it("handles JSON parse error", async () => {
+			const fetchMock = vi.fn().mockResolvedValue(
+				createMockResponse({
+					contentType: "application/json",
+					jsonThrows: true,
+				}),
+			);
+			globalThis.fetch = createFetchMock(fetchMock);
+
+			const program = Effect.gen(function* () {
+				const ccip = yield* CcipService;
+				return yield* ccip.request({
+					...baseRequest,
+					urls: ["https://gateway.example.com/{sender}/{data}"],
+				});
+			}).pipe(Effect.provide(DefaultCcip));
+
+			const exit = await Effect.runPromiseExit(program);
+
+			expect(Exit.isFailure(exit)).toBe(true);
+			if (Exit.isFailure(exit)) {
+				const error = exit.cause._tag === "Fail" ? exit.cause.error : null;
+				expect(error).toBeInstanceOf(CcipError);
+				expect((error as CcipError).message).toContain("JSON parse failed");
+			}
+		});
+
+		it("handles text read error", async () => {
+			const fetchMock = vi.fn().mockResolvedValue(
+				createMockResponse({
+					contentType: "text/plain",
+					textThrows: true,
+				}),
+			);
+			globalThis.fetch = createFetchMock(fetchMock);
+
+			const program = Effect.gen(function* () {
+				const ccip = yield* CcipService;
+				return yield* ccip.request({
+					...baseRequest,
+					urls: ["https://gateway.example.com/{sender}/{data}"],
+				});
+			}).pipe(Effect.provide(DefaultCcip));
+
+			const exit = await Effect.runPromiseExit(program);
+
+			expect(Exit.isFailure(exit)).toBe(true);
+			if (Exit.isFailure(exit)) {
+				const error = exit.cause._tag === "Fail" ? exit.cause.error : null;
+				expect(error).toBeInstanceOf(CcipError);
+				expect((error as CcipError).message).toContain("Text read failed");
+			}
+		});
+	});
+
+	describe("Content-Type parsing", () => {
+		it("parses JSON response when Content-Type is application/json", async () => {
+			const fetchMock = vi.fn().mockResolvedValue(
+				createMockResponse({
+					contentType: "application/json",
+					body: { data: "0xaabbccdd" },
+				}),
+			);
+			globalThis.fetch = createFetchMock(fetchMock);
+
+			const program = Effect.gen(function* () {
+				const ccip = yield* CcipService;
+				return yield* ccip.request({
+					...baseRequest,
+					urls: ["https://gateway.example.com/{sender}/{data}"],
+				});
+			}).pipe(Effect.provide(DefaultCcip));
+
+			const result = await Effect.runPromise(program);
+			expect(result).toBe("0xaabbccdd");
+		});
+
+		it("reads text response when Content-Type is not application/json", async () => {
+			const fetchMock = vi.fn().mockResolvedValue(
+				createMockResponse({
+					contentType: "text/plain",
+					textBody: "0x11223344",
+				}),
+			);
+			globalThis.fetch = createFetchMock(fetchMock);
+
+			const program = Effect.gen(function* () {
+				const ccip = yield* CcipService;
+				return yield* ccip.request({
+					...baseRequest,
+					urls: ["https://gateway.example.com/{sender}/{data}"],
+				});
+			}).pipe(Effect.provide(DefaultCcip));
+
+			const result = await Effect.runPromise(program);
+			expect(result).toBe("0x11223344");
+		});
+	});
+
+	describe("hex validation", () => {
+		it("succeeds with valid hex response", async () => {
+			const fetchMock = vi
+				.fn()
+				.mockResolvedValue(
+					createMockResponse({ body: { data: "0xABCDEF123456" } }),
+				);
+			globalThis.fetch = createFetchMock(fetchMock);
+
+			const program = Effect.gen(function* () {
+				const ccip = yield* CcipService;
+				return yield* ccip.request({
+					...baseRequest,
+					urls: ["https://gateway.example.com/{sender}/{data}"],
+				});
+			}).pipe(Effect.provide(DefaultCcip));
+
+			const result = await Effect.runPromise(program);
+			expect(result).toBe("0xABCDEF123456");
+		});
+
+		it("fails when response is not valid hex", async () => {
+			const fetchMock = vi
+				.fn()
+				.mockResolvedValue(createMockResponse({ body: { data: "not-hex" } }));
+			globalThis.fetch = createFetchMock(fetchMock);
+
+			const program = Effect.gen(function* () {
+				const ccip = yield* CcipService;
+				return yield* ccip.request({
+					...baseRequest,
+					urls: ["https://gateway.example.com/{sender}/{data}"],
+				});
+			}).pipe(Effect.provide(DefaultCcip));
+
+			const exit = await Effect.runPromiseExit(program);
+
+			expect(Exit.isFailure(exit)).toBe(true);
+			if (Exit.isFailure(exit)) {
+				const error = exit.cause._tag === "Fail" ? exit.cause.error : null;
+				expect(error).toBeInstanceOf(CcipError);
+				expect((error as CcipError).message).toContain("not valid hex");
+			}
+		});
+
+		it("fails when response is missing 0x prefix", async () => {
+			const fetchMock = vi
+				.fn()
+				.mockResolvedValue(createMockResponse({ body: { data: "abcdef" } }));
+			globalThis.fetch = createFetchMock(fetchMock);
+
+			const program = Effect.gen(function* () {
+				const ccip = yield* CcipService;
+				return yield* ccip.request({
+					...baseRequest,
+					urls: ["https://gateway.example.com/{sender}/{data}"],
+				});
+			}).pipe(Effect.provide(DefaultCcip));
+
+			const exit = await Effect.runPromiseExit(program);
+
+			expect(Exit.isFailure(exit)).toBe(true);
+			if (Exit.isFailure(exit)) {
+				const error = exit.cause._tag === "Fail" ? exit.cause.error : null;
+				expect(error).toBeInstanceOf(CcipError);
+				expect((error as CcipError).message).toContain("not valid hex");
+			}
+		});
+
+		it("fails when response contains non-hex characters", async () => {
+			const fetchMock = vi
+				.fn()
+				.mockResolvedValue(createMockResponse({ body: { data: "0xZZZZ" } }));
+			globalThis.fetch = createFetchMock(fetchMock);
+
+			const program = Effect.gen(function* () {
+				const ccip = yield* CcipService;
+				return yield* ccip.request({
+					...baseRequest,
+					urls: ["https://gateway.example.com/{sender}/{data}"],
+				});
+			}).pipe(Effect.provide(DefaultCcip));
+
+			const exit = await Effect.runPromiseExit(program);
+
+			expect(Exit.isFailure(exit)).toBe(true);
+			if (Exit.isFailure(exit)) {
+				const error = exit.cause._tag === "Fail" ? exit.cause.error : null;
+				expect(error).toBeInstanceOf(CcipError);
+				expect((error as CcipError).message).toContain("not valid hex");
+			}
+		});
+
+		it("accepts empty hex 0x", async () => {
+			const fetchMock = vi
+				.fn()
+				.mockResolvedValue(createMockResponse({ body: { data: "0x" } }));
+			globalThis.fetch = createFetchMock(fetchMock);
+
+			const program = Effect.gen(function* () {
+				const ccip = yield* CcipService;
+				return yield* ccip.request({
+					...baseRequest,
+					urls: ["https://gateway.example.com/{sender}/{data}"],
+				});
+			}).pipe(Effect.provide(DefaultCcip));
+
+			const result = await Effect.runPromise(program);
+			expect(result).toBe("0x");
+		});
+	});
+});
+
+describe("NoopCcip", () => {
+	it("always fails with CcipError", async () => {
+		const program = Effect.gen(function* () {
+			const ccip = yield* CcipService;
+			return yield* ccip.request({
+				...baseRequest,
+				urls: ["https://gateway.example.com/{sender}/{data}"],
+			});
+		}).pipe(Effect.provide(NoopCcip));
+
+		const exit = await Effect.runPromiseExit(program);
+
+		expect(Exit.isFailure(exit)).toBe(true);
+		if (Exit.isFailure(exit)) {
+			const error = exit.cause._tag === "Fail" ? exit.cause.error : null;
+			expect(error).toBeInstanceOf(CcipError);
+			expect((error as CcipError).message).toBe("CCIP disabled");
+		}
+	});
+
+	it("preserves URLs in error", async () => {
+		const urls = [
+			"https://first.example.com/{sender}/{data}",
+			"https://second.example.com/{sender}/{data}",
+		];
+
+		const program = Effect.gen(function* () {
+			const ccip = yield* CcipService;
+			return yield* ccip.request({
+				...baseRequest,
+				urls,
+			});
+		}).pipe(Effect.provide(NoopCcip));
+
+		const exit = await Effect.runPromiseExit(program);
+
+		expect(Exit.isFailure(exit)).toBe(true);
+		if (Exit.isFailure(exit)) {
+			const error = exit.cause._tag === "Fail" ? exit.cause.error : null;
+			expect(error).toBeInstanceOf(CcipError);
+			expect((error as CcipError).urls).toEqual(urls);
+		}
+	});
+});

package/src/services/Ccip/CcipService.ts

@@ -0,0 +1,106 @@
+/**
+ * @fileoverview CCIP (Cross-Chain Interoperability Protocol) service definition.
+ *
+ * @module CcipService
+ * @since 0.0.1
+ *
+ * @description
+ * Implements EIP-3668 (OffchainLookup) for fetching offchain data during contract calls.
+ * When a contract reverts with OffchainLookup, this service fetches the required data
+ * from offchain URLs and returns it for the callback.
+ *
+ * @see {@link DefaultCcip} - HTTP-based implementation
+ * @see {@link NoopCcip} - Disabled implementation for restricted environments
+ * @see https://eips.ethereum.org/EIPS/eip-3668
+ */
+
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import type * as Effect from "effect/Effect";
+
+/**
+ * Parameters for a CCIP offchain lookup request.
+ *
+ * @since 0.0.1
+ */
+export interface CcipRequest {
+	/** The contract address that initiated the lookup */
+	readonly sender: `0x${string}`;
+	/** URLs to try for fetching offchain data (tried in order) */
+	readonly urls: readonly string[];
+	/** The calldata to send to the offchain gateway */
+	readonly callData: `0x${string}`;
+	/** The callback function selector on the contract */
+	readonly callbackSelector: `0x${string}`;
+	/** Extra data to pass through to the callback */
+	readonly extraData: `0x${string}`;
+}
+
+/**
+ * Error returned when CCIP lookup fails.
+ *
+ * @since 0.0.1
+ */
+export class CcipError extends Data.TaggedError("CcipError")<{
+	/** The URLs that were attempted */
+	readonly urls: readonly string[];
+	/** Human-readable error message */
+	readonly message: string;
+	/** The underlying cause of the error */
+	readonly cause?: unknown;
+}> {}
+
+/**
+ * Shape of the CCIP service.
+ *
+ * @since 0.0.1
+ */
+export type CcipShape = {
+	/**
+	 * Performs a CCIP offchain lookup request.
+	 *
+	 * @param params - The CCIP request parameters
+	 * @returns The offchain data as hex bytes
+	 */
+	readonly request: (
+		params: CcipRequest,
+	) => Effect.Effect<`0x${string}`, CcipError>;
+};
+
+/**
+ * CCIP service for EIP-3668 offchain lookups.
+ *
+ * @description
+ * Provides the ability to fetch offchain data during contract calls.
+ * When a contract reverts with OffchainLookup, this service handles
+ * fetching the data from the specified gateway URLs.
+ *
+ * @since 0.0.1
+ *
+ * @example Basic usage with DefaultCcip
+ * ```typescript
+ * import { Effect } from 'effect'
+ * import { CcipService, DefaultCcip } from 'voltaire-effect'
+ *
+ * const program = Effect.gen(function* () {
+ *   const ccip = yield* CcipService
+ *   return yield* ccip.request({
+ *     sender: '0x...',
+ *     urls: ['https://gateway.example.com/{sender}/{data}'],
+ *     callData: '0x...',
+ *     callbackSelector: '0x...',
+ *     extraData: '0x'
+ *   })
+ * }).pipe(
+ *   Effect.provide(DefaultCcip)
+ * )
+ * ```
+ *
+ * @see {@link DefaultCcip} - HTTP-based implementation
+ * @see {@link NoopCcip} - Disabled implementation
+ * @see {@link CcipShape} - The service interface shape
+ */
+export class CcipService extends Context.Tag("CcipService")<
+	CcipService,
+	CcipShape
+>() {}