Architecture

​

System Overview

​

Core Design Principles

• Each Lasso node operates autonomously with complete, isolated supervision trees
• Routing decisions based on local latency measurements only
• No cluster coordination in the request hot path
• Single nodes work standalone without clustering

• Independent routing configurations per profile
• Isolated metrics and circuit breakers per (profile, chain) pair
• Shared provider infrastructure for efficiency

• Unified pipeline routes across HTTP and WebSocket
• Real-time performance-based transport selection
• Method-specific benchmarking per transport

​

Geo-Distributed Proxy Design

​

Regional Latency Awareness

• Applications connect to their nearest Lasso node
• Each node independently measures provider latency
• Routing optimizes for regional performance

​

Observability-First Clustering

# Enable clustering with DNS-based discovery
export CLUSTER_DNS_QUERY="lasso.internal"
export LASSO_NODE_ID="us-east-1"

• Unified dashboard view across regions
• Per-region provider performance comparison
• Topology monitoring (node health)
• No routing impact - clustering is purely observational

​

OTP Supervision Architecture

Lasso.Application
├── Phoenix.PubSub (cluster messaging)
├── Finch (HTTP connection pools)
├── Cluster.Supervisor (libcluster node discovery)
├── Task.Supervisor (async operations)
├── Lasso.Cluster.Topology (cluster membership & health)
├── Lasso.Benchmarking.BenchmarkStore (latency metrics)
├── Lasso.Benchmarking.Persistence (metrics history)
├── Lasso.Config.ConfigStore (profile configuration)
├── LassoWeb.Dashboard.MetricsStore (cluster metrics cache)
├── Lasso.Dashboard.StreamSupervisor (DynamicSupervisor)
│   └── EventStream {profile} (real-time dashboard)
├── Lasso.Providers.InstanceDynamicSupervisor
│   └── InstanceSupervisor {instance_id}
│       ├── CircuitBreaker {instance_id, :http}
│       ├── CircuitBreaker {instance_id, :ws}
│       ├── WSConnection {instance_id}
│       └── InstanceSubscriptionManager {instance_id}
├── Lasso.Providers.ProbeSupervisor (DynamicSupervisor)
│   └── ProbeCoordinator {chain}
├── Lasso.BlockSync.DynamicSupervisor
│   └── BlockSync.Worker {chain, instance_id}
├── ProfileChainSupervisor (DynamicSupervisor)
│   └── ChainSupervisor {profile, chain}
│       ├── TransportRegistry
│       ├── ClientSubscriptionRegistry
│       ├── UpstreamSubscriptionPool
│       └── StreamSupervisor
│           └── StreamCoordinator {subscription_key}
└── LassoWeb.Endpoint (Phoenix HTTP/WS)

​

Key Components

​

Provider Instance Management

• Pure module (not GenServer) for O(1) provider lookups
• Maps profiles to shared provider instances
• Builds ETS catalog from ConfigStore, swaps via persistent_term atomically
• Instance deduplication: same URL + chain = same instance across profiles

• Per-instance supervisor for shared infrastructure
• Started under InstanceDynamicSupervisor
• Children: CircuitBreaker (HTTP), CircuitBreaker (WS), WSConnection, InstanceSubscriptionManager
• Shared across all profiles using the same upstream

​

Health Monitoring

• Per-chain health probe coordinator (one per unique chain)
• 200ms tick cycle with exponential backoff on failures
• Probes one instance per tick to avoid thundering herd
• Writes health status to :lasso_instance_state ETS

​

Provider Selection

• Pure ETS reads (no GenServer) for minimal latency
• 7-stage filter pipeline (see Provider Selection)
• Returns candidates with availability, circuit state, and rate limit status

​

Profile-Scoped Supervision

• Top-level dynamic supervisor for (profile, chain) pairs
• Enables independent lifecycle per configuration
• Hot-add/remove chains without restarts

• Per-(profile, chain) supervisor providing policy isolation
• Children:
  • TransportRegistry: HTTP/WS channel discovery
  • ClientSubscriptionRegistry: WebSocket fan-out to clients
  • UpstreamSubscriptionPool: Multiplexes client subscriptions
  • StreamSupervisor: Per-subscription continuity management

​

Profile System

name: "Lasso Public"
slug: "default"
rps_limit: 100
burst_limit: 500

chains:
  ethereum:
    chain_id: 1
    monitoring:
      probe_interval_ms: 12000
    providers:
      - id: "ethereum_llamarpc"
        url: "https://eth.llamarpc.com"
        ws_url: "wss://eth.llamarpc.com"

​

URL Routing

# Profile-aware routes
POST /rpc/profile/:profile/:chain
POST /rpc/profile/:profile/fastest/:chain

# Default profile (uses "default" slug)
POST /rpc/:chain
POST /rpc/fastest/:chain

​

Profile Isolation

• Independent circuit breakers
• Isolated metrics and benchmarking
• Separate rate limits
• Dedicated WebSocket subscriptions

• Provider instances (URL + chain hash)
• Circuit breakers (shared across profiles)
• WebSocket connections (shared across profiles)
• Block height tracking (shared across profiles)

​

Block Height Monitoring

​

HTTP Polling (Always Running)

• Bounded observation delay (probe_interval_ms)
• Reliable foundation for lag calculation
• Continues during WebSocket failures

​

WebSocket Subscription (Optional)

• Sub-second block notifications when healthy
• Degrades gracefully to HTTP on failure
• Provider-specific via subscribe_new_heads: true

# Registry key structure
{:height, chain, instance_id} => {height, timestamp, source, metadata}

# Example
{:height, "arbitrum", "drpc"} => {421_535_503, 1736894871234, :http, %{latency_ms: 45}}

​

Optimistic Lag Calculation

elapsed_ms = now - timestamp
block_time_ms = Registry.get_block_time_ms(chain) || config.block_time_ms
staleness_credit = min(div(elapsed_ms, block_time_ms), div(30_000, block_time_ms))
optimistic_height = height + staleness_credit
optimistic_lag = optimistic_height - consensus_height

reported_height: 421,535,503
consensus_height: 421,535,511
raw_lag: -8 blocks

elapsed: 2000ms → credit: 2000/250 = 8 blocks
optimistic_height: 421,535,503 + 8 = 421,535,511
optimistic_lag: 0 blocks ✓

​

WebSocket Subscription Management

Client (Viem/Wagmi)
     ↓
RPCSocket (Phoenix Channel)
     ↓
SubscriptionRouter
     ↓
UpstreamSubscriptionPool (multiplexing)
     ↓
WSConnection (upstream provider)
     ↓
StreamCoordinator (per-subscription key)
     ↓
├─→ GapFiller (HTTP backfill)
└─→ ClientSubscriptionRegistry (fan-out)

​

Multiplexing

​

Failover with Gap-Filling

1. StreamCoordinator detects failure
2. Computes gap: last_seen_block to current head
3. GapFiller backfills missed blocks via HTTP
4. Injects backfilled events into stream
5. Subscribes to new provider

​

Cluster Topology & Aggregation

​

Node Lifecycle States

​

Dashboard Event Streaming

• Subscribes to: topology changes, routing decisions, circuit events, block sync
• Batches events (50ms intervals, max 100 per batch)
• Computes per-provider metrics grouped by region
• Broadcasts to LiveView subscribers

MetricsStore.get_provider_leaderboard("default", "ethereum")
# => %{data: [...], coverage: %{responding: 3, total: 3}, stale: false}

• Cache TTL: 15 seconds
• RPC timeout: 5 seconds
• Aggregation: Weighted averages by call volume

​

Performance Characteristics

​

Overhead

​

Scalability

• Concurrent requests: 10,000+ simultaneous (BEAM lightweight processes)
• Subscriptions per upstream: 1,000+ clients per upstream subscription
• Memory per request: <1KB (RequestContext + temporary state)
• ETS table scans: <1ms P99 (consensus height calculation)

​

Configuration

# Single node (default)
No additional configuration needed

# Multi-node cluster
export CLUSTER_DNS_QUERY="lasso.internal"
export LASSO_NODE_ID="us-east-1"

​

Next Steps