cyotee/Voltaire Effect Architecture

Voltaire Effect Architecture

Overview

voltaire-effect integrates Voltaire Ethereum primitives with Effect.ts, providing typed errors, dependency injection, and composable workflows for Ethereum development. It wraps Voltaire's branded Uint8Array types in Effect schemas for robust error handling and service-based composition.

┌─────────────────────────────────────────────────────────────────────────────┐
│                    VOLTAIRE-EFFECT ARCHITECTURE                              │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌────────────────────────────────────────────────────────────────────────┐ │
│  │                        APPLICATION CODE                                │ │
│  │                                                                        │ │
│  │   Effect.gen(function* () {                                           │ │
│  │     const addr = yield* S.decode(Address.Hex)(input)  // Schema      │ │
│  │     const bal  = yield* getBalance(addr)               // Effect     │ │
│  │     return bal                                                        │ │
│  │   })                                                                  │ │
│  └──────────────────────────────┬─────────────────────────────────────────┘ │
│                                 │                                            │
│                    Effect.provide(layers)                                    │
│                                 │                                            │
│  ┌──────────────────────────────▼─────────────────────────────────────────┐ │
│  │                         SERVICE LAYERS                                  │ │
│  │                                                                        │ │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐             │ │
│  │  │ Provider │  │  Signer  │  │ Transport│  │  Crypto  │  ...        │ │
│  │  │ Service  │  │ Service  │  │ Service  │  │ Services │             │ │
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘             │ │
│  │                                                                        │ │
│  │  Production: *Live layers    Testing: *Test layers                    │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
│                                 │                                            │
│  ┌──────────────────────────────▼─────────────────────────────────────────┐ │
│  │                      VOLTAIRE PRIMITIVES                                │ │
│  │                                                                        │ │
│  │  Branded Uint8Array types: Address, Hash, Signature, Transaction...   │ │
│  │  WASM-compiled crypto: keccak256 (9.2x faster than viem JS)           │ │
│  │  150+ Effect Schema wrappers for Ethereum data types                  │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Three-Layer Model

Organize applications using three composable layers:

1. Schema Layer - Validation & Type Coercion

Effect Schema wrappers decode raw input into Voltaire's branded types with typed errors:

import * as Address from 'voltaire-effect/primitives/Address'
import * as S from 'effect/Schema'

// Decode returns Effect<AddressType, ParseError, never>
const addr = S.decodeSync(Address.Hex)('0x742d35Cc6634C0532925a3b844Bc9e7595f251e3')

// Checksummed encoding requires KeccakService
const checksummed = S.encode(Address.Checksummed)(addr)
// Effect<string, ParseError, KeccakService>

2. Effect Layer - Composable Operations

Free functions return Effects with typed errors and service requirements:

import { getBalance, getBlockNumber } from 'voltaire-effect'

const program = Effect.gen(function* () {
  const block = yield* getBlockNumber()
  const balance = yield* getBalance(addr)
  return { block, balance }
})
// Type: Effect<{ block: bigint, balance: bigint }, GetBalanceError, ProviderService>

3. Services Layer - Dependency Injection

Declare services in type signatures and provide them at program boundaries:

import { Provider, HttpTransport } from 'voltaire-effect'

const ProviderLayer = Provider.pipe(
  Layer.provide(HttpTransport('https://eth.llamarpc.com'))
)

// Provide at the edge - not scattered through code
await Effect.runPromise(program.pipe(Effect.provide(ProviderLayer)))

Core Pattern: Decode → Use → Provide

  Input (string/hex)
        │
        ▼
  ┌─────────────┐
  │   DECODE     │  S.decode(Address.Hex)(input)
  │   (Schema)   │  → Effect<AddressType, ParseError>
  └──────┬──────┘
         │
         ▼
  ┌─────────────┐
  │    USE       │  getBalance(addr)
  │  (Effects)   │  → Effect<bigint, GetBalanceError, ProviderService>
  └──────┬──────┘
         │
         ▼
  ┌─────────────┐
  │   PROVIDE    │  Effect.provide(ProviderLayer)
  │  (Layers)    │  → Effect<bigint, GetBalanceError>
  └──────┬──────┘
         │
         ▼
  Effect.runPromise → bigint

Installation

pnpm add voltaire-effect @tevm/voltaire effect

Requirements: Effect 3.x, Voltaire 0.x, TypeScript 5.4+

Comparison with Alternatives

| Aspect | voltaire-effect | viem | ethers | |--------|-----------------|------|--------| | Type Safety | Branded Uint8Array | 0x${string} | String | | Errors | Typed values in signatures | Hidden exceptions | Hidden exceptions | | Composition | pipe / Effect.gen | Manual chaining | Class methods | | Testing | Layer swap (no code changes) | Mock imports | Mock classes | | Dependencies | Explicit in types | Implicit globals | Implicit globals | | Bundle | ~15KB Effect runtime overhead | Minimal | Heavier |

When to Choose voltaire-effect

Adopt it for complex workflows requiring typed errors, composable operations, service dependency testing, or when already leveraging Effect in your application. For simpler scripts or bundle-size-critical apps, base Voltaire or viem may suffice.

Layer Composition Rules

Compose layers once before providing, avoiding multiple chained Effect.provide calls:

// Independent layers → mergeAll
const AppLayer = Layer.mergeAll(TransportLayer, CryptoLayer)

// Dependent layers → pipe + provide
const ProviderLayer = Provider.pipe(Layer.provide(TransportLayer))

// Add services while preserving existing → provideMerge
const FullLayer = Layer.provideMerge(ProviderLayer, CryptoLayer)

Data-First API

Pass data as the first argument to enable pipeline composition:

// voltaire-effect style (data-first)
Address.toHex(addr)
pipe(addr, Address.toHex)

// NOT OOP style
addr.toHex()  // not used

Complete Example

End-to-end program demonstrating Decode → Use → Provide:

import { Effect, Layer } from 'effect'
import * as S from 'effect/Schema'
import * as Address from 'voltaire-effect/primitives/Address'
import { getBalance, getBlockNumber, Provider, HttpTransport } from 'voltaire-effect'

// 1. DECODE: Validate input at the boundary
const program = Effect.gen(function* () {
  const addr = yield* S.decode(Address.Hex)('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045')

  // 2. USE: Compose operations with typed errors
  const blockNumber = yield* getBlockNumber()
  const balance = yield* getBalance(addr)

  return { blockNumber, balance }
})
// Type: Effect<{ blockNumber: bigint, balance: bigint }, ParseError | GetBalanceError, ProviderService>

// 3. PROVIDE: Inject services at the edge
const ProviderLayer = Provider.pipe(
  Layer.provide(HttpTransport('https://eth.llamarpc.com'))
)

const result = await Effect.runPromise(program.pipe(Effect.provide(ProviderLayer)))
console.log(`Block ${result.blockNumber}: ${result.balance} wei`)

Errors propagate through the type signature as the program composes. The ParseError from S.decode and the GetBalanceError from getBalance both appear in the final type, enabling exhaustive handling with Effect.catchTag. See voltaire-effect-error-handling for patterns.

WASM-Compiled Crypto

Voltaire ships WASM-compiled cryptographic primitives. Keccak256 hashing runs 9.2x faster than viem's JavaScript implementation for 32-byte inputs. Import individual services (KeccakLive, Secp256k1Live) for tree-shaking, or use the combined CryptoLive layer for convenience. See voltaire-effect-crypto for the full service catalog.

Progressive Disclosure

For deeper understanding, see these related skills:

| Skill | Topic | |-------|-------| | voltaire-effect-schemas | Branded types and Schema validation | | voltaire-effect-services | Provider, Signer, Transport services | | voltaire-effect-error-handling | Typed errors, catchTag, Either patterns | | voltaire-effect-crypto | Cryptographic services (hashing, signing, encryption) | | voltaire-effect-contracts | Type-safe contract read/write/simulate | | voltaire-effect-testing | Test layers and mocking patterns | | voltaire-effect-streaming | Block and event streaming with reorg detection |

Reference

• Documentation: https://voltaire-effect.tevm.sh
• API Reference: https://voltaire-effect.tevm.sh/api-reference
• Cheatsheet: https://voltaire-effect.tevm.sh/cheatsheet