voltaire-effect 0.2.25 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voltaire-effect",
-  "version": "0.2.25",
+  "version": "0.3.0",
   "description": "Effect-TS integration for Voltaire Ethereum primitives library",
   "author": "TEVM",
   "license": "MIT",
@@ -78,20 +78,20 @@
   },
   "sideEffects": false,
   "peerDependencies": {
-    "effect": "^3.12.0",
-    "@tevm/voltaire": "0.2.25"
-  },
-  "dependencies": {
-    "@effect/platform": "^0.77.0"
+    "@effect/platform": "^0.94.0",
+    "effect": "^3.19.0",
+    "@tevm/voltaire": "0.2.28"
   },
   "optionalDependencies": {
-    "@effect/platform-browser": "^0.57.0",
-    "@effect/platform-bun": "^0.60.0",
-    "@effect/platform-node": "^0.77.0"
+    "@effect/platform-browser": "^0.74.0",
+    "@effect/platform-bun": "^0.87.0",
+    "@effect/platform-node": "^0.104.0"
   },
   "devDependencies": {
-    "@effect/platform-node": "^0.77.0",
-    "@effect/vitest": "^0.18.1",
+    "@effect/platform": "^0.94.0",
+    "@effect/platform-node": "^0.104.0",
+    "@effect/vitest": "^0.27.0",
+    "effect": "^3.19.0",
     "astro": "^5.0.0",
     "tsup": "^8.4.0",
     "typescript": "^5.9.3",

package/src/primitives/Abi/encodeFunctionData.bench.ts

@@ -0,0 +1,79 @@
+/**
+ * Benchmark: voltaire vs voltaire-effect vs viem encodeFunctionData
+ */
+
+import { Effect } from "effect";
+import { bench, run } from "mitata";
+import { encodeFunctionData as viemEncodeFunctionData } from "viem";
+import * as Abi from "@tevm/voltaire/Abi";
+import { encodeFunctionData } from "./encodeFunctionData.js";
+
+const erc20Abi = [
+	{
+		type: "function",
+		name: "transfer",
+		stateMutability: "nonpayable",
+		inputs: [
+			{ type: "address", name: "to" },
+			{ type: "uint256", name: "amount" },
+		],
+		outputs: [{ type: "bool", name: "" }],
+	},
+	{
+		type: "function",
+		name: "balanceOf",
+		stateMutability: "view",
+		inputs: [{ type: "address", name: "account" }],
+		outputs: [{ type: "uint256", name: "" }],
+	},
+	{
+		type: "function",
+		name: "approve",
+		stateMutability: "nonpayable",
+		inputs: [
+			{ type: "address", name: "spender" },
+			{ type: "uint256", name: "amount" },
+		],
+		outputs: [{ type: "bool", name: "" }],
+	},
+] as const;
+
+const recipient = "0x742d35cc6634c0532925a3b844bc9e7595f251e3";
+const amount = 1000000000000000000n;
+
+bench("encodeFunctionData - viem", () => {
+	viemEncodeFunctionData({
+		abi: erc20Abi,
+		functionName: "transfer",
+		args: [recipient, amount],
+	});
+});
+
+bench("encodeFunctionData - voltaire", () => {
+	Abi.encodeFunction(erc20Abi, "transfer", [recipient, amount]);
+});
+
+bench("encodeFunctionData - voltaire-effect (sync)", () => {
+	Effect.runSync(encodeFunctionData(erc20Abi, "transfer", [recipient, amount]));
+});
+
+await run();
+
+// Also test balanceOf (single param)
+bench("balanceOf - viem", () => {
+	viemEncodeFunctionData({
+		abi: erc20Abi,
+		functionName: "balanceOf",
+		args: [recipient],
+	});
+});
+
+bench("balanceOf - voltaire", () => {
+	Abi.encodeFunction(erc20Abi, "balanceOf", [recipient]);
+});
+
+bench("balanceOf - voltaire-effect (sync)", () => {
+	Effect.runSync(encodeFunctionData(erc20Abi, "balanceOf", [recipient]));
+});
+
+await run();

package/src/primitives/Address/Hex.ts

@@ -11,6 +11,12 @@ import * as ParseResult from "effect/ParseResult";
 import * as S from "effect/Schema";
 import { AddressTypeSchema } from "./AddressSchema.js";
 
+// Pre-computed example addresses for schema annotations
+const EXAMPLE_ADDRESSES: readonly [AddressType, AddressType] = [
+	Address("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"),
+	Address("0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"),
+] as const;
+
 /**
  * Schema for Address encoded as a hex string.
  *
@@ -53,4 +59,12 @@ export const Hex: S.Schema<AddressType, string> = S.transformOrFail(
 			return ParseResult.succeed(Address.toHex(addr));
 		},
 	},
-).annotations({ identifier: "Address.Hex" });
+).annotations({
+	identifier: "Address.Hex",
+	title: "Ethereum Address",
+	description:
+		"A 20-byte Ethereum address as a hex string. Accepts checksummed, lowercase, or uppercase.",
+	examples: EXAMPLE_ADDRESSES,
+	message: () =>
+		"Invalid Ethereum address: expected 40 hex characters with 0x prefix",
+});

package/src/primitives/Block/BlockSchema.ts

@@ -198,4 +198,4 @@ export const BlockSchema: Schema.Schema<BlockType> = Schema.declare(
 
 		return true;
 	},
-);
+).annotations({ identifier: "BlockSchema" });

package/src/primitives/PrivateKey/Bytes.ts

@@ -24,6 +24,7 @@
  */
 
 import { PrivateKey, type PrivateKeyType } from "@tevm/voltaire/PrivateKey";
+import { Redacted } from "effect";
 import * as ParseResult from "effect/ParseResult";
 import * as S from "effect/Schema";
 
@@ -57,3 +58,37 @@ export const Bytes: S.Schema<PrivateKeyType, Uint8Array> = S.transformOrFail(
 		},
 	},
 ).annotations({ identifier: "PrivateKey.Bytes" });
+
+/**
+ * Schema for PrivateKey encoded as raw bytes, wrapped in Redacted.
+ *
+ * @description
+ * Transforms Uint8Array to Redacted<PrivateKeyType> for secure handling.
+ * The redacted wrapper prevents accidental logging of private keys.
+ * Use `Redacted.value()` to explicitly unwrap for cryptographic operations.
+ *
+ * @example Decoding
+ * ```typescript
+ * import * as PrivateKey from 'voltaire-effect/primitives/PrivateKey'
+ * import { Redacted } from 'effect'
+ * import * as S from 'effect/Schema'
+ *
+ * const bytes = new Uint8Array(32).fill(1)
+ * const pk = S.decodeSync(PrivateKey.RedactedBytes)(bytes)
+ * console.log(pk) // Redacted(<redacted>)
+ *
+ * const unwrapped = Redacted.value(pk)
+ * // Use unwrapped for signing
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const RedactedBytes: S.Schema<
+	Redacted.Redacted<PrivateKeyType>,
+	Uint8Array
+> = Bytes.pipe(S.Redacted).annotations({
+	identifier: "PrivateKey.RedactedBytes",
+	title: "Private Key (Redacted)",
+	description:
+		"A 32-byte secp256k1 private key wrapped in Redacted to prevent accidental logging",
+});

package/src/primitives/PrivateKey/Hex.ts

@@ -29,9 +29,15 @@ import {
 	PrivateKey,
 	type PrivateKeyType,
 } from "@tevm/voltaire/PrivateKey";
+import { Redacted } from "effect";
 import * as ParseResult from "effect/ParseResult";
 import * as S from "effect/Schema";
 
+// Pre-computed example private key for schema annotations (test vector only)
+const EXAMPLE_PRIVATE_KEY: PrivateKeyType = PrivateKey.from(
+	"0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+);
+
 const PrivateKeyTypeSchema = S.declare<PrivateKeyType>(
 	(u): u is PrivateKeyType => u instanceof Uint8Array && u.length === 32,
 	{ identifier: "PrivateKey" },
@@ -61,4 +67,46 @@ export const Hex: S.Schema<PrivateKeyType, string> = S.transformOrFail(
 			}
 		},
 	},
-).annotations({ identifier: "PrivateKey.Hex" });
+).annotations({
+	identifier: "PrivateKey.Hex",
+	title: "Private Key",
+	description:
+		"A 32-byte secp256k1 private key as a hex string. NEVER log or expose this value.",
+	examples: [EXAMPLE_PRIVATE_KEY],
+	message: () => "Invalid private key: expected 64 hex characters (32 bytes)",
+});
+
+/**
+ * Schema for PrivateKey encoded as hex string, wrapped in Redacted.
+ *
+ * @description
+ * Transforms hex strings to Redacted<PrivateKeyType> for secure handling.
+ * The redacted wrapper prevents accidental logging of private keys.
+ * Use `Redacted.value()` to explicitly unwrap for cryptographic operations.
+ *
+ * @example Decoding
+ * ```typescript
+ * import * as PrivateKey from 'voltaire-effect/primitives/PrivateKey'
+ * import { Redacted } from 'effect'
+ * import * as S from 'effect/Schema'
+ *
+ * const pk = S.decodeSync(PrivateKey.RedactedHex)('0x0123...')
+ * console.log(pk) // Redacted(<redacted>)
+ *
+ * const unwrapped = Redacted.value(pk)
+ * // Use unwrapped for signing
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const RedactedHex: S.Schema<
+	Redacted.Redacted<PrivateKeyType>,
+	string
+> = Hex.pipe(S.Redacted).annotations({
+	identifier: "PrivateKey.RedactedHex",
+	title: "Private Key (Redacted)",
+	description:
+		"A 32-byte secp256k1 private key wrapped in Redacted to prevent accidental logging. NEVER log or expose the unwrapped value.",
+	examples: [Redacted.make(EXAMPLE_PRIVATE_KEY)],
+	message: () => "Invalid private key: expected 64 hex characters (32 bytes)",
+});

package/src/primitives/PrivateKey/PrivateKey.error.test.ts

@@ -0,0 +1,167 @@
+import { describe, expect, it } from "@effect/vitest";
+import { TreeFormatter } from "effect/ParseResult";
+import * as S from "effect/Schema";
+import * as PrivateKey from "./index.js";
+
+const formatError = TreeFormatter.formatErrorSync;
+
+describe("PrivateKey parse error messages", () => {
+	describe("PrivateKey.Hex", () => {
+		it("shows helpful error for wrong length (too short)", () => {
+			const result = S.decodeUnknownEither(PrivateKey.Hex)("0x1234");
+
+			expect(result._tag).toBe("Left");
+			if (result._tag === "Left") {
+				const formatted = formatError(result.left);
+
+				// Should mention expected length
+				expect(formatted).toContain("64");
+
+				// Should NOT expose the attempted value
+				expect(formatted).not.toContain("1234");
+
+				expect(formatted).toMatchInlineSnapshot(`"Invalid private key: expected 64 hex characters (32 bytes)"`);
+			}
+		});
+
+		it("shows helpful error for invalid hex characters", () => {
+			const result = S.decodeUnknownEither(PrivateKey.Hex)("0x" + "gg".repeat(32));
+
+			expect(result._tag).toBe("Left");
+			if (result._tag === "Left") {
+				const formatted = formatError(result.left);
+
+				// Should NOT expose the invalid input
+				expect(formatted).not.toContain("gggg");
+
+				expect(formatted).toMatchInlineSnapshot(`"Invalid private key: expected 64 hex characters (32 bytes)"`);
+			}
+		});
+
+		it("shows helpful error for wrong type (number)", () => {
+			const result = S.decodeUnknownEither(PrivateKey.Hex)(12345);
+
+			expect(result._tag).toBe("Left");
+			if (result._tag === "Left") {
+				const formatted = formatError(result.left);
+
+				expect(formatted).toMatchInlineSnapshot(`
+					"PrivateKey.Hex
+					└─ Encoded side transformation failure
+					   └─ Expected string, actual 12345"
+				`);
+			}
+		});
+
+		it("shows helpful error for null", () => {
+			const result = S.decodeUnknownEither(PrivateKey.Hex)(null);
+
+			expect(result._tag).toBe("Left");
+			if (result._tag === "Left") {
+				const formatted = formatError(result.left);
+
+				expect(formatted).toContain("Expected");
+				expect(formatted).toMatchInlineSnapshot(`
+					"PrivateKey.Hex
+					└─ Encoded side transformation failure
+					   └─ Expected string, actual null"
+				`);
+			}
+		});
+
+		it("does not leak key material in errors for almost valid key", () => {
+			// 62 valid hex chars + 2 invalid chars - almost looks like a real key
+			const almostValidKey = "0x" + "ab".repeat(31) + "xx";
+			const result = S.decodeUnknownEither(PrivateKey.Hex)(almostValidKey);
+
+			expect(result._tag).toBe("Left");
+			if (result._tag === "Left") {
+				const formatted = formatError(result.left);
+
+				// Error should NOT contain ANY of the key material
+				expect(formatted).not.toContain("abab");
+				expect(formatted).not.toContain("ab".repeat(31));
+				expect(formatted).not.toContain(almostValidKey);
+				expect(formatted).not.toContain(almostValidKey.slice(2)); // without 0x
+			}
+		});
+	});
+
+	describe("PrivateKey.Bytes", () => {
+		it("shows helpful error for wrong length (too short)", () => {
+			const bytes = new Uint8Array(16);
+			const result = S.decodeUnknownEither(PrivateKey.Bytes)(bytes);
+
+			expect(result._tag).toBe("Left");
+			if (result._tag === "Left") {
+				const formatted = formatError(result.left);
+
+				// Should mention expected length
+				expect(formatted).toContain("32");
+
+				expect(formatted).toMatchInlineSnapshot(`
+					"PrivateKey.Bytes
+					└─ Transformation process failure
+					   └─ Private key must be 32 bytes, got 16
+
+					Docs: https://voltaire.dev/primitives/private-key"
+				`);
+			}
+		});
+
+		it("shows helpful error for wrong type (not Uint8Array)", () => {
+			const result = S.decodeUnknownEither(PrivateKey.Bytes)([1, 2, 3]);
+
+			expect(result._tag).toBe("Left");
+			if (result._tag === "Left") {
+				const formatted = formatError(result.left);
+
+				expect(formatted).toMatchInlineSnapshot(`
+					"PrivateKey.Bytes
+					└─ Encoded side transformation failure
+					   └─ Expected Uint8ArrayFromSelf, actual [1,2,3]"
+				`);
+			}
+		});
+	});
+
+	describe("PrivateKey.RedactedHex", () => {
+		it("does not leak key material for invalid input", () => {
+			const almostValidKey = "0x" + "cd".repeat(31) + "zz";
+			const result = S.decodeUnknownEither(PrivateKey.RedactedHex)(almostValidKey);
+
+			expect(result._tag).toBe("Left");
+			if (result._tag === "Left") {
+				const formatted = formatError(result.left);
+
+				// Redacted schema should be extra careful
+				expect(formatted).not.toContain("cdcd");
+				expect(formatted).not.toContain(almostValidKey);
+
+				expect(formatted).toMatchInlineSnapshot(`"Invalid private key: expected 64 hex characters (32 bytes)"`);
+			}
+		});
+	});
+
+	describe("PrivateKey.RedactedBytes", () => {
+		it("shows helpful error for wrong length", () => {
+			const bytes = new Uint8Array(31);
+			const result = S.decodeUnknownEither(PrivateKey.RedactedBytes)(bytes);
+
+			expect(result._tag).toBe("Left");
+			if (result._tag === "Left") {
+				const formatted = formatError(result.left);
+
+				expect(formatted).toMatchInlineSnapshot(`
+					"PrivateKey.RedactedBytes
+					└─ Encoded side transformation failure
+					   └─ PrivateKey.Bytes
+					      └─ Transformation process failure
+					         └─ Private key must be 32 bytes, got 31
+
+					Docs: https://voltaire.dev/primitives/private-key"
+				`);
+			}
+		});
+	});
+});

package/src/primitives/PrivateKey/PrivateKey.test.ts

@@ -3,6 +3,7 @@ import { Hash } from "@tevm/voltaire";
 import { PrivateKey as CorePrivateKey } from "@tevm/voltaire/PrivateKey";
 import * as Secp256k1 from "@tevm/voltaire/Secp256k1";
 import * as Effect from "effect/Effect";
+import { Redacted } from "effect";
 import * as S from "effect/Schema";
 import * as PrivateKey from "./index.js";
 
@@ -373,6 +374,84 @@ describe("cryptographic operations", () => {
 	});
 });
 
+describe("PrivateKey.RedactedHex", () => {
+	it("decodes to Redacted type", () => {
+		const pk = S.decodeSync(PrivateKey.RedactedHex)(validHex);
+		expect(Redacted.isRedacted(pk)).toBe(true);
+	});
+
+	it("does not expose value when logged", () => {
+		const pk = S.decodeSync(PrivateKey.RedactedHex)(validHex);
+		expect(String(pk)).toBe("<redacted>");
+		expect(String(pk)).not.toContain("ab");
+	});
+
+	it("allows explicit unwrap", () => {
+		const pk = S.decodeSync(PrivateKey.RedactedHex)(validHex);
+		const unwrapped = Redacted.value(pk);
+		expect(unwrapped).toBeInstanceOf(Uint8Array);
+		expect(unwrapped.length).toBe(32);
+	});
+
+	it("round-trips correctly", () => {
+		const pk = S.decodeSync(PrivateKey.RedactedHex)(validHex);
+		const encoded = S.encodeSync(PrivateKey.RedactedHex)(pk);
+		expect(encoded).toBe(validHex.toLowerCase());
+	});
+
+	it("works with cryptographic operations after unwrap", () => {
+		const pk = S.decodeSync(PrivateKey.RedactedHex)(validHex);
+		const unwrapped = Redacted.value(pk);
+		const publicKey = Secp256k1.derivePublicKey(unwrapped);
+		expect(publicKey.length).toBe(64);
+	});
+
+	it("fails on invalid hex", () => {
+		expect(() => S.decodeSync(PrivateKey.RedactedHex)("0x1234")).toThrow();
+	});
+
+	it("parses without prefix", () => {
+		const pk = S.decodeSync(PrivateKey.RedactedHex)(validHexNoPrefix);
+		expect(Redacted.isRedacted(pk)).toBe(true);
+		expect(Redacted.value(pk).length).toBe(32);
+	});
+});
+
+describe("PrivateKey.RedactedBytes", () => {
+	it("decodes to Redacted type", () => {
+		const bytes = new Uint8Array(32).fill(0xab);
+		const pk = S.decodeSync(PrivateKey.RedactedBytes)(bytes);
+		expect(Redacted.isRedacted(pk)).toBe(true);
+	});
+
+	it("does not expose value when logged", () => {
+		const bytes = new Uint8Array(32).fill(0xab);
+		const pk = S.decodeSync(PrivateKey.RedactedBytes)(bytes);
+		expect(String(pk)).toBe("<redacted>");
+	});
+
+	it("allows explicit unwrap", () => {
+		const bytes = new Uint8Array(32).fill(0xab);
+		const pk = S.decodeSync(PrivateKey.RedactedBytes)(bytes);
+		const unwrapped = Redacted.value(pk);
+		expect(unwrapped).toBeInstanceOf(Uint8Array);
+		expect(unwrapped.length).toBe(32);
+	});
+
+	it("round-trips correctly", () => {
+		const bytes = new Uint8Array(32).fill(0xab);
+		const pk = S.decodeSync(PrivateKey.RedactedBytes)(bytes);
+		const encoded = S.encodeSync(PrivateKey.RedactedBytes)(pk);
+		expect([...encoded]).toEqual([...bytes]);
+	});
+
+	it("fails on wrong length", () => {
+		expect(() =>
+			S.decodeSync(PrivateKey.RedactedBytes)(new Uint8Array(31)),
+		).toThrow();
+	});
+});
+
 describe("secp256k1 curve constraints", () => {
 	it("rejects zero private key", () => {
 		const zeroKey = new Uint8Array(32);

package/src/primitives/PrivateKey/index.ts

@@ -2,61 +2,53 @@
  * @module PrivateKey
  * @description Effect Schemas for secp256k1 private keys with cryptographic operations.
  *
- * ## Type Declarations
- *
- * ```typescript
- * import * as PrivateKey from 'voltaire-effect/primitives/PrivateKey'
- *
- * function signMessage(key: PrivateKey.PrivateKeyType) {
- *   // ...
- * }
- * ```
- *
  * ## Schemas
  *
- * | Schema | Input | Output |
- * |--------|-------|--------|
- * | `PrivateKey.Hex` | hex string | PrivateKeyType |
- * | `PrivateKey.Bytes` | Uint8Array | PrivateKeyType |
+ * | Schema | Input | Output | Use Case |
+ * |--------|-------|--------|----------|
+ * | `PrivateKey.Hex` | hex string | PrivateKeyType | Development |
+ * | `PrivateKey.Bytes` | Uint8Array | PrivateKeyType | Development |
+ * | `PrivateKey.RedactedHex` | hex string | Redacted<PrivateKeyType> | **Production** |
+ * | `PrivateKey.RedactedBytes` | Uint8Array | Redacted<PrivateKeyType> | **Production** |
+ *
+ * ## Redacted Schemas (Recommended)
  *
- * ## Usage
+ * Use `RedactedHex` or `RedactedBytes` in production to prevent accidental logging:
  *
  * ```typescript
  * import * as PrivateKey from 'voltaire-effect/primitives/PrivateKey'
+ * import { Redacted } from 'effect'
  * import * as S from 'effect/Schema'
  *
- * // Decode (parse input)
- * const pk = S.decodeSync(PrivateKey.Hex)('0x0123456789abcdef...')
+ * const pk = S.decodeSync(PrivateKey.RedactedHex)('0x0123...')
+ * console.log(pk)  // Redacted(<redacted>)
  *
- * // Encode (format output)
- * const hex = S.encodeSync(PrivateKey.Hex)(pk)
- * const bytes = S.encodeSync(PrivateKey.Bytes)(pk)
+ * // Explicit unwrap for crypto operations
+ * const unwrapped = Redacted.value(pk)
+ * const sig = Secp256k1.sign(hash, unwrapped)
  * ```
  *
- * ## Cryptographic Operations
+ * ## Standard Usage
  *
  * ```typescript
- * import * as Effect from 'effect/Effect'
- *
- * const program = Effect.gen(function* () {
- *   const pk = yield* PrivateKey.random()
- *   const publicKey = yield* PrivateKey.toPublicKey(pk)
- *   const address = yield* PrivateKey.toAddress(pk)
- *   const signature = yield* PrivateKey.sign(pk, messageHash)
- *   return { publicKey, address, signature }
- * })
+ * import * as PrivateKey from 'voltaire-effect/primitives/PrivateKey'
+ * import * as S from 'effect/Schema'
+ *
+ * const pk = S.decodeSync(PrivateKey.Hex)('0x0123456789abcdef...')
+ * const hex = S.encodeSync(PrivateKey.Hex)(pk)
  * ```
  *
  * ## Pure Functions
  *
  * ```typescript
  * PrivateKey.isValid(value)  // Effect<boolean>
+ * PrivateKey.random()        // Effect<PrivateKeyType>
  * ```
  *
  * @since 0.1.0
  */
 
-export { Bytes } from "./Bytes.js";
-export { Hex } from "./Hex.js";
+export { Bytes, RedactedBytes } from "./Bytes.js";
+export { Hex, RedactedHex } from "./Hex.js";
 export { isValid } from "./isValid.js";
 export { random } from "./random.js";