name: Voltaire Effect Architecture description: This skill should be used when the user asks about "voltaire-effect architecture", "voltaire-effect overview", "how does voltaire-effect work", "what is voltaire-effect", "Effect.ts Ethereum library", "Voltaire Effect layers", "decode use provide pattern", "voltaire-effect vs viem", "voltaire-effect vs ethers", "voltaire-effect getting started", or needs a high-level understanding of how voltaire-effect integrates Voltaire Ethereum primitives with Effect.ts. version: 0.1.0

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

voltaire-effect-architecture

SKILL.md