voltaire-effect 0.2.23

package/src/primitives/ContractSignature/ContractSignature.test.ts

@@ -0,0 +1,111 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import { describe, expect, it, vi } from "vitest";
+import { ProviderService } from "../../services/Provider/index.js";
+import * as ContractSignature from "./index.js";
+
+describe("ContractSignature.Struct", () => {
+	it("validates input structure", () => {
+		const input = {
+			hash: new Uint8Array(32).fill(1),
+			signature: new Uint8Array(65).fill(2),
+			expectedSigner: new Uint8Array(20).fill(3),
+			returnData: new Uint8Array(32).fill(4),
+		};
+		const result = Schema.decodeSync(ContractSignature.Struct)(input);
+		expect(result.hash).toEqual(input.hash);
+		expect(result.signature).toEqual(input.signature);
+	});
+});
+
+describe("ERC1271_MAGIC_VALUE", () => {
+	it("has correct value", () => {
+		expect(ContractSignature.ERC1271_MAGIC_VALUE).toBeDefined();
+	});
+});
+
+describe("checkReturnData", () => {
+	it("returns true for magic value", () => {
+		const magicValue = new Uint8Array([0x16, 0x26, 0xba, 0x7e]);
+		expect(ContractSignature.checkReturnData(magicValue)).toBe(true);
+	});
+
+	it("returns false for wrong value", () => {
+		const wrongValue = new Uint8Array([0x00, 0x00, 0x00, 0x00]);
+		expect(ContractSignature.checkReturnData(wrongValue)).toBe(false);
+	});
+
+	it("returns false for short data", () => {
+		const shortData = new Uint8Array([0x16, 0x26]);
+		expect(ContractSignature.checkReturnData(shortData)).toBe(false);
+	});
+});
+
+describe("verifySignature", () => {
+	const mockProvider = {
+		call: vi.fn(),
+		getLogs: vi.fn(),
+		getBlockNumber: vi.fn(),
+		getBalance: vi.fn(),
+		getBlock: vi.fn(),
+		getTransaction: vi.fn(),
+		getTransactionReceipt: vi.fn(),
+		getTransactionCount: vi.fn(),
+		getCode: vi.fn(),
+		getStorageAt: vi.fn(),
+		estimateGas: vi.fn(),
+		getChainId: vi.fn(),
+		getGasPrice: vi.fn(),
+	};
+
+	const _MockProviderLayer = Layer.succeed(
+		ProviderService,
+		mockProvider as any,
+	);
+
+	it("exports verifySignature function", () => {
+		expect(typeof ContractSignature.verifySignature).toBe("function");
+	});
+
+	it("exports SignatureVerificationError", () => {
+		expect(ContractSignature.SignatureVerificationError).toBeDefined();
+	});
+
+	it("exports InvalidSignatureFormatError", () => {
+		expect(ContractSignature.InvalidSignatureFormatError).toBeDefined();
+	});
+
+	it("SignatureVerificationError is catchable with Effect.catchTag", async () => {
+		const error = new ContractSignature.SignatureVerificationError({
+			input: { address: "0x123", hash: new Uint8Array(32) },
+			message: "test error",
+		});
+
+		const program = Effect.fail(error).pipe(
+			Effect.catchTag("SignatureVerificationError", (e) =>
+				Effect.succeed(`caught: ${e.message}`),
+			),
+		);
+
+		const result = await Effect.runPromise(program);
+		expect(result).toBe("caught: test error");
+	});
+
+	it("InvalidSignatureFormatError has correct _tag", () => {
+		const error = new ContractSignature.InvalidSignatureFormatError({
+			message: "bad format",
+		});
+		expect(error._tag).toBe("InvalidSignatureFormatError");
+		expect(error.name).toBe("InvalidSignatureFormatError");
+	});
+
+	it("SignatureVerificationError has correct _tag", () => {
+		const error = new ContractSignature.SignatureVerificationError({
+			input: { address: "0x123", hash: new Uint8Array(32) },
+			message: "verification failed",
+		});
+		expect(error._tag).toBe("SignatureVerificationError");
+		expect(error.name).toBe("SignatureVerificationError");
+	});
+});

package/src/primitives/ContractSignature/Struct.ts

@@ -0,0 +1,67 @@
+import { ContractSignature } from "@tevm/voltaire";
+import * as S from "effect/Schema";
+
+/**
+ * ERC-1271 magic value returned by contracts for valid signatures.
+ * Value: 0x1626ba7e
+ * @since 0.1.0
+ */
+export const ERC1271_MAGIC_VALUE = ContractSignature.EIP1271_MAGIC_VALUE;
+
+/**
+ * Input type for contract signature verification.
+ * @since 0.1.0
+ */
+export type ContractSignatureInput = {
+	hash: Uint8Array;
+	signature: Uint8Array;
+	expectedSigner: Uint8Array;
+	returnData: Uint8Array;
+};
+
+/**
+ * Schema for contract signature verification inputs.
+ *
+ * @description
+ * Validates input for ERC-1271 contract signature verification.
+ *
+ * @example
+ * ```typescript
+ * import * as ContractSignature from 'voltaire-effect/primitives/ContractSignature'
+ * import * as S from 'effect/Schema'
+ *
+ * const input = S.decodeSync(ContractSignature.Struct)({
+ *   hash: messageHash,
+ *   signature: sigBytes,
+ *   expectedSigner: contractAddress,
+ *   returnData: callResult
+ * })
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const Struct = S.Struct({
+	hash: S.Uint8ArrayFromSelf,
+	signature: S.Uint8ArrayFromSelf,
+	expectedSigner: S.Uint8ArrayFromSelf,
+	returnData: S.Uint8ArrayFromSelf,
+}).annotations({ identifier: "ContractSignature.Struct" });
+
+export { Struct as ContractSignatureInputSchema };
+
+/**
+ * Checks if return data matches ERC-1271 magic value.
+ *
+ * @param returnData - The return data from isValidSignature call
+ * @returns true if the magic value matches
+ * @since 0.1.0
+ */
+export const checkReturnData = (returnData: Uint8Array): boolean => {
+	if (returnData.length < 4) return false;
+	return (
+		returnData[0] === 0x16 &&
+		returnData[1] === 0x26 &&
+		returnData[2] === 0xba &&
+		returnData[3] === 0x7e
+	);
+};

package/src/primitives/ContractSignature/index.ts

@@ -0,0 +1,68 @@
+/**
+ * @module ContractSignature
+ * @description Effect Schemas for ERC-1271 smart contract signature verification.
+ *
+ * ERC-1271 defines a standard for contract-based signature verification,
+ * enabling smart contract wallets to authorize transactions.
+ *
+ * ## Type Declarations
+ *
+ * ```typescript
+ * import * as ContractSignature from 'voltaire-effect/primitives/ContractSignature'
+ *
+ * function verifySignature(input: ContractSignature.ContractSignatureInput) {
+ *   // ...
+ * }
+ * ```
+ *
+ * ## Schemas
+ *
+ * | Schema | Description |
+ * |--------|-------------|
+ * | `ContractSignature.Struct` | Verification input (hash, signature, signer, returnData) |
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import * as ContractSignature from 'voltaire-effect/primitives/ContractSignature'
+ * import * as S from 'effect/Schema'
+ *
+ * const input = S.decodeSync(ContractSignature.Struct)({
+ *   hash: messageHash,
+ *   signature: sigBytes,
+ *   expectedSigner: contractAddress,
+ *   returnData: callResult
+ * })
+ *
+ * // Check if signature is valid
+ * const valid = ContractSignature.checkReturnData(input.returnData)
+ * ```
+ *
+ * ## Constants
+ *
+ * ```typescript
+ * ContractSignature.ERC1271_MAGIC_VALUE  // 0x1626ba7e
+ * ```
+ *
+ * ## Pure Functions
+ *
+ * ```typescript
+ * ContractSignature.checkReturnData(returnData)  // boolean
+ * ```
+ *
+ * @since 0.1.0
+ */
+export {
+	type ContractSignatureInput,
+	ContractSignatureInputSchema,
+	checkReturnData,
+	ERC1271_MAGIC_VALUE,
+	Struct,
+} from "./Struct.js";
+
+export {
+	InvalidSignatureFormatError,
+	type SignatureInput,
+	SignatureVerificationError,
+	verifySignature,
+} from "./verifySignature.js";

package/src/primitives/ContractSignature/verifySignature.ts

@@ -0,0 +1,254 @@
+/**
+ * @module ContractSignature/verifySignature
+ * @description Effect wrapper for contract signature verification.
+ *
+ * Provides typed error handling for EIP-1271 and EOA signature verification.
+ *
+ * @since 0.1.0
+ */
+
+import {
+	Address,
+	type BrandedAddress,
+	type BrandedHash,
+	ContractSignature,
+	Secp256k1,
+} from "@tevm/voltaire";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Runtime from "effect/Runtime";
+import { ProviderService } from "../../services/Provider/index.js";
+
+type AddressType = BrandedAddress.AddressType;
+type HashType = BrandedHash.HashType;
+
+/**
+ * Signature components or raw bytes
+ */
+export type SignatureInput =
+	| { r: Uint8Array; s: Uint8Array; v: number }
+	| Uint8Array;
+
+/**
+ * Error thrown when signature verification fails due to an error (not invalid signature).
+ * @since 0.1.0
+ */
+export class SignatureVerificationError extends Data.TaggedError(
+	"SignatureVerificationError",
+)<{
+	readonly input: {
+		address: string;
+		hash: Uint8Array;
+	};
+	readonly message: string;
+	readonly code?: number;
+	readonly context?: Record<string, unknown>;
+	readonly cause?: unknown;
+}> {}
+
+/**
+ * Error thrown when signature format is invalid.
+ * @since 0.1.0
+ */
+export class InvalidSignatureFormatError extends Data.TaggedError(
+	"InvalidSignatureFormatError",
+)<{
+	readonly message: string;
+	readonly code?: number;
+	readonly context?: Record<string, unknown>;
+	readonly cause?: unknown;
+}> {}
+
+const SIGNATURE_LENGTH = 65;
+const SIGNATURE_COMPONENT_LENGTH = 32;
+
+const assertSignatureComponentLength = (
+	component: Uint8Array,
+	name: "r" | "s",
+) => {
+	if (component.length !== SIGNATURE_COMPONENT_LENGTH) {
+		throw new InvalidSignatureFormatError({
+			message: `Signature ${name} must be ${SIGNATURE_COMPONENT_LENGTH} bytes`,
+		});
+	}
+};
+
+const toSignatureComponents = (
+	signature: SignatureInput,
+): { r: Uint8Array; s: Uint8Array; v: number } => {
+	if (signature instanceof Uint8Array) {
+		if (signature.length !== SIGNATURE_LENGTH) {
+			throw new InvalidSignatureFormatError({
+				message: `Signature must be ${SIGNATURE_LENGTH} bytes`,
+			});
+		}
+		return {
+			r: signature.slice(0, 32),
+			s: signature.slice(32, 64),
+			v: signature[64] ?? 0,
+		};
+	}
+	assertSignatureComponentLength(signature.r, "r");
+	assertSignatureComponentLength(signature.s, "s");
+	return signature;
+};
+
+const concatSignature = (signature: {
+	r: Uint8Array;
+	s: Uint8Array;
+	v: number;
+}): Uint8Array => {
+	assertSignatureComponentLength(signature.r, "r");
+	assertSignatureComponentLength(signature.s, "s");
+	const result = new Uint8Array(SIGNATURE_LENGTH);
+	result.set(signature.r, 0);
+	result.set(signature.s, 32);
+	result[64] = signature.v;
+	return result;
+};
+
+const toSignatureBytes = (signature: SignatureInput): Uint8Array =>
+	signature instanceof Uint8Array ? signature : concatSignature(signature);
+
+const bytesToBigInt = (bytes: Uint8Array): bigint => {
+	let result = 0n;
+	for (const byte of bytes) {
+		result = (result << 8n) | BigInt(byte);
+	}
+	return result;
+};
+
+const isEmptyCode = (code: unknown): code is string =>
+	typeof code === "string" &&
+	(code === "0x" || code === "0x0" || code === "0x00");
+
+/**
+ * Verify a signature for both EOA and contract accounts (EIP-1271).
+ *
+ * Unlike the base voltaire function which silently returns `false` for errors,
+ * this Effect wrapper properly distinguishes between:
+ * - Invalid signatures (returns `false`)
+ * - Format errors (throws `InvalidSignatureFormatError`)
+ * - Network/verification errors (throws `SignatureVerificationError`)
+ *
+ * @param address - Address to verify signature for (EOA or contract)
+ * @param hash - Message hash that was signed
+ * @param signature - ECDSA signature (65 bytes or {r, s, v} components)
+ * @returns Effect that resolves to `true` if valid, `false` if invalid
+ *
+ * @example
+ * ```typescript
+ * import * as ContractSignature from 'voltaire-effect/primitives/ContractSignature'
+ * import * as Effect from 'effect/Effect'
+ *
+ * const program = ContractSignature.verifySignature(
+ *   signerAddress,
+ *   messageHash,
+ *   signature
+ * ).pipe(
+ *   Effect.catchTag("InvalidSignatureFormatError", (e) =>
+ *     Effect.succeed(false) // Treat format errors as invalid
+ *   ),
+ *   Effect.catchTag("SignatureVerificationError", (e) =>
+ *     Effect.fail(e) // Re-throw network errors
+ *   )
+ * )
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const verifySignature = (
+	address: AddressType | `0x${string}`,
+	hash: HashType | Uint8Array,
+	signature: SignatureInput,
+): Effect.Effect<
+	boolean,
+	SignatureVerificationError | InvalidSignatureFormatError,
+	ProviderService
+> =>
+	Effect.gen(function* () {
+		const provider = yield* ProviderService;
+		const runtime = yield* Effect.runtime();
+		const runPromise = Runtime.runPromise(runtime);
+
+		const addressStr =
+			typeof address === "string" ? address : Address.toHex(address);
+
+		return yield* Effect.tryPromise({
+			try: async () => {
+				const providerAdapter = {
+					request: async (method: string, params: unknown[]) => {
+						if (method === "eth_getCode") {
+							const [addr, block] = params as [string, string];
+							return runPromise(
+								provider.getCode(addr as `0x${string}`, block as any),
+							);
+						}
+						if (method === "eth_call") {
+							const [callObj] = params as [{ to: string; data: string }];
+							return runPromise(
+								provider.call({
+									to: callObj.to as `0x${string}`,
+									data: callObj.data as `0x${string}`,
+								}),
+							);
+						}
+						throw new Error(`Unsupported method: ${method}`);
+					},
+				};
+
+				const addressHex =
+					typeof address === "string" ? address : Address.toHex(address);
+				const code = await providerAdapter.request("eth_getCode", [
+					addressHex,
+					"latest",
+				]);
+
+				if (isEmptyCode(code)) {
+					const sigComponents = toSignatureComponents(signature);
+					const publicKey = Secp256k1.recoverPublicKey(
+						sigComponents,
+						hash as any,
+					);
+					const x = bytesToBigInt(publicKey.slice(0, 32));
+					const y = bytesToBigInt(publicKey.slice(32, 64));
+					const recoveredAddress = Address.fromPublicKey(x, y);
+					const expectedAddress =
+						typeof address === "string" ? Address(address) : address;
+					return Address.equals(recoveredAddress, expectedAddress);
+				}
+
+				const signatureBytes = toSignatureBytes(signature);
+				return await ContractSignature.isValidSignature(
+					providerAdapter,
+					address as any,
+					hash as any,
+					signatureBytes,
+				);
+			},
+			catch: (e) => {
+				if (e instanceof InvalidSignatureFormatError) {
+					return e;
+				}
+				if (
+					e instanceof Error &&
+					(e.name === "InvalidSignatureFormatError" ||
+						e.name === "InvalidSignatureError")
+				) {
+					return new InvalidSignatureFormatError({
+						message: e.message,
+						cause: e,
+					});
+				}
+				return new SignatureVerificationError({
+					input: {
+						address: addressStr,
+						hash: hash instanceof Uint8Array ? hash : new Uint8Array(hash),
+					},
+					message:
+						e instanceof Error ? e.message : "Signature verification failed",
+					cause: e,
+				});
+			},
+		});
+	});

package/src/primitives/DecodedData/DecodedDataSchema.ts

@@ -0,0 +1,72 @@
+import { DecodedData } from "@tevm/voltaire";
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+
+/**
+ * Type representing decoded ABI data with values and their types.
+ * @since 0.0.1
+ */
+export type DecodedDataType<T = unknown> = DecodedData.DecodedDataType<T>;
+
+const DecodedDataTypeSchema = S.declare<DecodedDataType>(
+	(u): u is DecodedDataType =>
+		u !== null &&
+		typeof u === "object" &&
+		"values" in u &&
+		"types" in u &&
+		Array.isArray((u as any).types),
+	{ identifier: "DecodedData" },
+);
+
+/**
+ * Input type for creating DecodedData.
+ * @since 0.0.1
+ */
+export type DecodedDataInput<T = unknown> = {
+	readonly values: T;
+	readonly types: readonly string[];
+};
+
+/**
+ * Effect Schema for validating decoded ABI data.
+ * Wraps values with their ABI type information.
+ *
+ * @example
+ * ```typescript
+ * import * as DecodedData from 'voltaire-effect/DecodedData'
+ * import * as Schema from 'effect/Schema'
+ *
+ * const decoded = Schema.decodeSync(DecodedData.DecodedDataSchema)({
+ *   values: [100n, '0x...'],
+ *   types: ['uint256', 'address']
+ * })
+ * ```
+ * @since 0.0.1
+ */
+export const DecodedDataSchema: S.Schema<DecodedDataType, DecodedDataInput> =
+	S.transformOrFail(
+		S.Struct({
+			values: S.Unknown,
+			types: S.Array(S.String),
+		}),
+		DecodedDataTypeSchema,
+		{
+			strict: true,
+			decode: (input, _options, ast) => {
+				try {
+					return ParseResult.succeed(
+						DecodedData.from(input.values, input.types),
+					);
+				} catch (e) {
+					return ParseResult.fail(
+						new ParseResult.Type(ast, input, (e as Error).message),
+					);
+				}
+			},
+			encode: (data) =>
+				ParseResult.succeed({
+					values: data.values,
+					types: data.types,
+				}),
+		},
+	).annotations({ identifier: "DecodedDataSchema" });

package/src/primitives/DecodedData/index.ts

@@ -0,0 +1,11 @@
+/**
+ * DecodedData module for working with decoded ABI data.
+ * Provides Effect-based operations for creating decoded data with type information.
+ * @module
+ * @since 0.0.1
+ */
+export {
+	type DecodedDataInput,
+	DecodedDataSchema,
+	type DecodedDataType,
+} from "./DecodedDataSchema.js";

package/src/primitives/Denomination/EtherSchema.ts

@@ -0,0 +1,87 @@
+/**
+ * @fileoverview Effect Schema definitions for Ether denomination values.
+ * Provides type-safe schemas for parsing and validating Ether amounts.
+ * @module Denomination/EtherSchema
+ * @since 0.0.1
+ */
+
+import { Uint } from "@tevm/voltaire";
+import * as ParseResult from "effect/ParseResult";
+import * as S from "effect/Schema";
+
+/**
+ * Branded type representing Ether (10^18 Wei).
+ *
+ * @description
+ * Ether is the primary currency of Ethereum, used for transaction fees and
+ * value transfers. This type represents whole Ether units (not Wei).
+ * - 1 Ether = 10^18 Wei
+ * - 1 Ether = 10^9 Gwei
+ *
+ * @example
+ * ```typescript
+ * import type { EtherType } from 'voltaire-effect/primitives/Denomination'
+ *
+ * const amount: EtherType = 10n as EtherType // 10 ETH
+ * ```
+ *
+ * @since 0.0.1
+ */
+export type EtherType = bigint & { readonly __tag: "Ether" };
+
+/**
+ * Internal schema declaration for validating EtherType instances.
+ * Ensures the value is a non-negative bigint.
+ *
+ * @internal
+ */
+const EtherTypeSchema = S.declare<EtherType>(
+	(u): u is EtherType => typeof u === "bigint" && u >= 0n,
+	{ identifier: "Ether" },
+);
+
+/**
+ * Effect Schema for validating Ether values.
+ *
+ * @description
+ * Transforms bigint, number, or string inputs into branded EtherType values.
+ * Ether is the human-readable unit commonly used in wallets and UIs.
+ *
+ * @example
+ * ```typescript
+ * import * as Denomination from 'voltaire-effect/primitives/Denomination'
+ * import * as Schema from 'effect/Schema'
+ *
+ * // Parse 1 ETH
+ * const eth = Schema.decodeSync(Denomination.EtherSchema)(1n)
+ *
+ * // From string
+ * const fromStr = Schema.decodeSync(Denomination.EtherSchema)('10')
+ *
+ * // Encode back
+ * const encoded = Schema.encodeSync(Denomination.EtherSchema)(eth)
+ * ```
+ *
+ * @throws ParseResult.Type - When the input is negative or cannot be converted
+ * @see {@link WeiSchema} for base unit values
+ * @see {@link GweiSchema} for gas price units
+ * @since 0.0.1
+ */
+export const EtherSchema: S.Schema<EtherType, bigint | number | string> =
+	S.transformOrFail(
+		S.Union(S.BigIntFromSelf, S.Number, S.String),
+		EtherTypeSchema,
+		{
+			strict: true,
+			decode: (value, _options, ast) => {
+				try {
+					return ParseResult.succeed(Uint.from(value) as unknown as EtherType);
+				} catch (e) {
+					return ParseResult.fail(
+						new ParseResult.Type(ast, value, (e as Error).message),
+					);
+				}
+			},
+			encode: (ether) => ParseResult.succeed(ether),
+		},
+	).annotations({ identifier: "EtherSchema" });