voltaire-effect 0.2.25 → 0.3.0

package/README.md

@@ -1,6 +1,121 @@
 # voltaire-effect
 
-Effect-TS integration for the [Voltaire](https://github.com/evmts/voltaire) Ethereum primitives library.
+Effect-TS integration for the [Voltaire](https://github.com/evmts/voltaire) Ethereum primitives library. Type-safe contract interactions with composable, error-handled operations.
+
+## Quick Start
+
+**viem** - implicit 3 retries hidden in transport config:
+```typescript
+import { createPublicClient, http } from 'viem'
+
+const client = createPublicClient({
+  transport: http('https://eth.llamarpc.com', { retryCount: 3 }) // hidden default
+})
+
+const balance = await client.readContract({
+  address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+  abi: erc20Abi,
+  functionName: 'balanceOf',
+  args: [userAddress]
+})
+```
+
+**voltaire-effect** - explicit control over retry, timeout, and composition:
+```typescript
+import { Effect } from 'effect'
+import { ContractRegistryService, makeContractRegistry, HttpProvider } from 'voltaire-effect'
+
+const Contracts = makeContractRegistry({
+  USDC: { abi: erc20Abi, address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' },
+  WETH: { abi: erc20Abi, address: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2' },
+})
+
+const program = Effect.gen(function* () {
+  const { USDC, WETH } = yield* ContractRegistryService
+  const usdcBalance = yield* USDC.read.balanceOf(userAddress)
+  const wethBalance = yield* WETH.read.balanceOf(userAddress)
+  return { usdcBalance, wethBalance }
+}).pipe(
+  Effect.retry({ times: 3 }),           // explicit retry policy
+  Effect.timeout('10 seconds'),         // explicit timeout
+  Effect.provide(Contracts),
+  Effect.provide(HttpProvider('https://eth.llamarpc.com'))
+)
+
+const { usdcBalance, wethBalance } = await Effect.runPromise(program)
+```
+
+**viem** - Address and Bytecode are both `0x${string}`, easily confused:
+```typescript
+import { type Address, type Hex } from 'viem'
+
+const address: Address = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
+const bytecode: Hex = '0x608060405234801561001057600080fd5b50'
+
+// TypeScript allows this - runtime bug waiting to happen
+await client.readContract({
+  address: bytecode,  // oops, passed bytecode as address - compiles fine!
+  abi: erc20Abi,
+  functionName: 'balanceOf',
+  args: [address]
+})
+```
+
+**voltaire-effect** - branded types prevent mixing:
+```typescript
+import * as Address from '@tevm/voltaire/Address'
+import * as Bytecode from '@tevm/voltaire/Bytecode'
+
+const address = Address.from('0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48')
+const bytecode = Bytecode.from('0x608060405234801561001057600080fd5b50')
+
+await client.readContract({
+  address: bytecode,  // Type error: Bytecode is not assignable to Address
+  ...
+})
+```
+
+### Performance: encodeFunctionData
+
+Both encode the same calldata, but Voltaire's WASM-optimized keccak256 (used for function selectors) is ~9x faster:
+
+**viem**:
+```typescript
+import { encodeFunctionData } from 'viem'
+
+const calldata = encodeFunctionData({
+  abi: erc20Abi,
+  functionName: 'transfer',
+  args: [recipient, amount]
+})
+// Throws on error - must wrap in try/catch
+```
+
+**voltaire**:
+```typescript
+import * as Abi from '@tevm/voltaire/Abi'
+
+const calldata = Abi.encodeFunction(erc20Abi, 'transfer', [recipient, amount])
+```
+
+**voltaire-effect** (typed errors):
+```typescript
+import { Effect } from 'effect'
+import { encodeFunctionData } from 'voltaire-effect/primitives/Abi'
+
+const calldata = await Effect.runPromise(
+  encodeFunctionData(erc20Abi, 'transfer', [recipient, amount])
+)
+// Effect<Hex, AbiItemNotFoundError | AbiEncodingError>
+```
+
+| Operation | viem | voltaire | Speedup |
+|-----------|------|----------|---------|
+| keccak256 (32B) | 3.22 µs | 349 ns | **9.2x** |
+| keccak256 (256B) | 6.23 µs | 571 ns | **10.9x** |
+| keccak256 (1KB) | 24.4 µs | 1.87 µs | **13x** |
+
+*Benchmarks on Apple M3 Max, bun 1.3.4. Voltaire uses WASM-compiled Zig keccak256.*
 
 ## Installation
 
@@ -10,33 +125,90 @@ npm install voltaire-effect effect @tevm/voltaire
 
 ## Features
 
+- **Contract Registry**: Define contracts once, use everywhere with full type safety
 - **Typed Errors**: All operations return `Effect<A, E, R>` with precise error types
 - **Composable**: Chain operations using Effect's powerful combinators
-- **Services**: Dependency injection for crypto operations
+- **Services**: Dependency injection for Provider, Signer, and contracts
 - **Zero Runtime Overhead**: Effect's tree-shaking keeps bundles small
 
-## Usage
+## Contract Patterns
+
+### Pre-configured Contracts (Addressed Mode)
+
+When you provide an address, you get a fully instantiated `ContractInstance`:
+
+```typescript
+const Contracts = makeContractRegistry({
+  USDC: { abi: erc20Abi, address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' }
+})
+
+const program = Effect.gen(function* () {
+  const { USDC } = yield* ContractRegistryService
+  const balance = yield* USDC.read.balanceOf(account)
+  const txHash = yield* USDC.write.transfer(recipient, amount)
+})
+```
+
+### Factory Pattern (No Address)
+
+When you omit the address, you get a `ContractFactory` with an `.at()` method:
 
 ```typescript
-import { Effect } from "effect";
-import * as Address from "voltaire-effect/primitives";
-import * as Keccak from "voltaire-effect/crypto";
+const Contracts = makeContractRegistry({
+  ERC20: { abi: erc20Abi }  // No address
+})
 
 const program = Effect.gen(function* () {
-  const addr = yield* Address.from("0x1234567890abcdef1234567890abcdef12345678");
-  const hash = yield* Keccak.keccak256(new Uint8Array([1, 2, 3]));
-  return { addr, hash };
-});
+  const { ERC20 } = yield* ContractRegistryService
+  const token = yield* ERC20.at(userProvidedAddress)
+  const balance = yield* token.read.balanceOf(account)
+})
+```
+
+### Mixed Mode
 
-Effect.runPromise(program);
+Combine both patterns:
+
+```typescript
+const Contracts = makeContractRegistry({
+  // Known addresses
+  USDC: { abi: erc20Abi, address: USDC_ADDRESS },
+  WETH: { abi: wethAbi, address: WETH_ADDRESS },
+  // Generic factories
+  ERC20: { abi: erc20Abi },
+  ERC721: { abi: erc721Abi }
+})
+```
+
+## Single Contract Usage
+
+For one-off contracts, use `Contract()` directly:
+
+```typescript
+import { Contract, HttpProvider } from 'voltaire-effect'
+
+const program = Effect.gen(function* () {
+  const token = yield* Contract(tokenAddress, erc20Abi)
+  const balance = yield* token.read.balanceOf(userAddress)
+  return balance
+}).pipe(
+  Effect.provide(HttpProvider('https://eth.llamarpc.com'))
+)
 ```
 
 ## Subpath Exports
 
-- `voltaire-effect` - Main entry
+- `voltaire-effect` - Main entry (services, contracts, provider)
 - `voltaire-effect/primitives` - Address, Hex, Bytes32, etc.
 - `voltaire-effect/crypto` - Keccak, secp256k1, etc.
 
+## Documentation
+
+- [Contract Registry Service](./docs/services/contract-registry.mdx)
+- [Contract Factory](./docs/services/contract.mdx)
+- [Provider Service](./docs/services/provider.mdx)
+- [Signer Service](./docs/services/signer.mdx)
+
 ## License
 
 MIT

package/dist/{index-BCOuszKZ.d.ts → index-3UKSP3cd.d.ts}

@@ -1,7 +1,7 @@
 import { BrandedSiwe, Siwe, BeaconBlockRoot, BinaryTree, BrandedBlob as BrandedBlob$a, Block, BlockBody, BlockFilter, BlockHash, BlockHeader, BlockNumber, BrandedBloomFilter, CallTrace, ChainHead, CompilerVersion, ContractCode, ContractResult, BrandedAddress as BrandedAddress$1, BrandedHash, DecodedData, Domain, DomainSeparator, EncodedData, Ens, Epoch, ErrorSignature, EventSignature, FilterId, ForkId, FunctionSignature, GasEstimate, Gas, GasRefund, GasUsed, Hardfork as Hardfork$2, BrandedInt8, BrandedInt16, BrandedInt32, BrandedInt64, BrandedInt128, BrandedInt256, License, LogIndex, MemoryDump, MerkleTree, Metadata, MultiTokenId, NodeInfo, Opcode, OpStep, PeerId, PeerInfo, PendingTransactionFilter, Permit, Proof as Proof$4, ProtocolVersion, Proxy, ReturnData, RevertReason, RuntimeCode, SignedData, Slot, SourceMap, State, StateDiff, StateProof, StorageProof, TokenBalance, TokenId, TransactionIndex, TransactionStatus, TransactionUrl, BrandedUint8, BrandedUint16, BrandedUint32, Uint64, BrandedUint128, Uncle, ValidatorIndex, Withdrawal, WithdrawalIndex } from '@tevm/voltaire';
 import * as S from 'effect/Schema';
 import { Signature as Signature$1, GetMessageHash, InvalidFieldError, InvalidNonceLengthError, InvalidSiweMessageError, MissingFieldError, SiweParseError, Verify, VerifyMessage } from '@tevm/voltaire/Siwe';
-import { Effect as Effect$1 } from 'effect';
+import { Effect as Effect$1, Redacted } from 'effect';
 import { AddressType as AddressType$1, InvalidAddressError, InvalidHexFormatError, InvalidAddressLengthError, InvalidValueError as InvalidValueError$1, InvalidAbiEncodedPaddingError, Address, InvalidChecksumError, BrandedAddress, HEX_SIZE, InvalidHexStringError, NATIVE_ASSET_ADDRESS, NotImplementedError, SIZE, ZERO_ADDRESS } from '@tevm/voltaire/Address';
 import { BrandedAccessList, Item, ADDRESS_COST, COLD_ACCOUNT_ACCESS_COST, COLD_STORAGE_ACCESS_COST, STORAGE_KEY_COST, WARM_STORAGE_ACCESS_COST } from '@tevm/voltaire/AccessList';
 import { InvalidFormatError, InvalidLengthError, DecodingError, ValidationError } from '@tevm/voltaire/errors';
@@ -15917,6 +15917,31 @@ declare namespace index$P {
  */
 
 declare const Bytes$d: S.Schema<PrivateKeyType, Uint8Array>;
+/**
+ * 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
+ */
+declare const RedactedBytes: S.Schema<Redacted.Redacted<PrivateKeyType>, Uint8Array>;
 
 /**
  * Schema for PrivateKey encoded as a hex string.
@@ -15945,6 +15970,30 @@ declare const Bytes$d: S.Schema<PrivateKeyType, Uint8Array>;
  */
 
 declare const Hex$d: S.Schema<PrivateKeyType, string>;
+/**
+ * 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
+ */
+declare const RedactedHex: S.Schema<Redacted.Redacted<PrivateKeyType>, string>;
 
 /**
  * @fileoverview Effect-based private key validation.
@@ -15991,63 +16040,57 @@ declare const random: () => Effect.Effect<PrivateKeyType>;
  * @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** |
  *
- * ## Usage
+ * ## Redacted Schemas (Recommended)
+ *
+ * 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'
+ * import * as PrivateKey from 'voltaire-effect/primitives/PrivateKey'
+ * import * as S from 'effect/Schema'
  *
- * 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 }
- * })
+ * 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
  */
 
+declare const index$O_RedactedBytes: typeof RedactedBytes;
+declare const index$O_RedactedHex: typeof RedactedHex;
 declare const index$O_random: typeof random;
 declare namespace index$O {
-  export { Bytes$d as Bytes, Hex$d as Hex, isValid$2 as isValid, index$O_random as random };
+  export { Bytes$d as Bytes, Hex$d as Hex, index$O_RedactedBytes as RedactedBytes, index$O_RedactedHex as RedactedHex, isValid$2 as isValid, index$O_random as random };
 }
 
 type ProofType$1 = Proof$4.ProofType;