Profile Configuration

Profiles define how Lasso routes requests across blockchain networks and providers. Each profile specifies chains, monitoring settings, provider selection rules, and rate limits.

Frontmatter

The frontmatter section contains profile-level metadata and rate limiting configuration.

string

required

Human-readable profile name displayed in the dashboard and logs.

name: "Production RPC"

string

required

URL-safe identifier used in request paths. Must be unique across all profiles.

slug: "production"

Accessed via: /rpc/profile/production/:chain

integer

default:"100"

Per-API-key requests per second limit. Uses token bucket rate limiting.

rps_limit: 100

integer

default:"500"

Token bucket burst capacity. Allows short traffic spikes above rps_limit.

burst_limit: 500

Example Frontmatter

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

Chain Configuration

Each chain is defined under the chains: key with a unique identifier (e.g., ethereum, base, arbitrum).

Basic Fields

integer

required

EIP-155 chain ID. Used for request validation and multi-chain routing.

chain_id: 1  # Ethereum Mainnet

string

Display name for the chain. Defaults to the chain key if omitted.

name: "Ethereum Mainnet"

integer

Average block time in milliseconds. Used for optimistic lag calculation and timeout defaults.

block_time_ms: 12000  # 12 seconds for Ethereum

Typical values:

Ethereum: 12000
Base: 2000
Arbitrum: 250

Monitoring

Controls health probe frequency and lag alerting.

integer

default:"12000"

Interval between health checks in milliseconds. Set to approximately 1x block time for L1 chains, 2.5x for L2 chains.

monitoring:
  probe_interval_ms: 12000

integer

default:"5"

Log a warning when a provider lags this many blocks behind consensus.

monitoring:
  lag_alert_threshold_blocks: 5

Selection

Controls provider eligibility filtering during request routing.

integer

default:"1"

Exclude providers lagging more than this many blocks behind the highest known block.

selection:
  max_lag_blocks: 1  # L1: 1-2, L2: 3-10

Recommendations:

L1 chains (Ethereum): 1-2 blocks
Fast L2 chains (Arbitrum): 10 blocks
Standard L2 chains (Base): 5 blocks

integer

default:"128"

Number of blocks before data is considered “archival”. Requests for blocks older than head - threshold are only routed to providers marked as archival: true.

selection:
  archival_threshold: 128  # ~25 minutes on Ethereum

WebSocket

Controls upstream WebSocket subscription behavior for real-time block tracking.

Subscribe to newHeads events for real-time block tracking. Enables sub-second lag detection.

websocket:
  subscribe_new_heads: true

integer

default:"35000"

Timeout before marking a subscription as stale. Set to approximately 3x block time.

websocket:
  new_heads_timeout_ms: 35000

integer

default:"100"

Maximum number of blocks to fetch via HTTP during subscription failover to prevent gaps.

websocket:
  failover:
    max_backfill_blocks: 100

integer

default:"30000"

Timeout for backfill HTTP requests during failover.

websocket:
  failover:
    backfill_timeout_ms: 30000

UI Topology

Dashboard visualization settings for the topology view.

string

Hex color code for the chain node in the dashboard topology view.

ui-topology:
  color: "#627EEA"  # Ethereum blue

string

default:"md"

Node size in the topology view. Options: sm, md, lg, xl.

ui-topology:
  size: xl

Complete Example

Here’s a complete chain configuration for Ethereum Mainnet:

chains:
  ethereum:
    chain_id: 1
    name: "Ethereum Mainnet"
    block_time_ms: 12000

    monitoring:
      probe_interval_ms: 12000
      lag_alert_threshold_blocks: 5

    selection:
      max_lag_blocks: 1
      archival_threshold: 128

    websocket:
      subscribe_new_heads: true
      new_heads_timeout_ms: 35000
      failover:
        max_backfill_blocks: 100
        backfill_timeout_ms: 30000

    ui-topology:
      color: "#627EEA"
      size: xl

    providers:
      # See Provider Configuration page

L2 Chain Example

L2 chains have different timing characteristics:

chains:
  base:
    chain_id: 8453
    name: "Base Mainnet"
    block_time_ms: 2000  # 2 second blocks

    monitoring:
      probe_interval_ms: 5000  # 2.5x block time
      lag_alert_threshold_blocks: 5

    selection:
      max_lag_blocks: 5  # More tolerant for L2
      archival_threshold: 750  # ~25 minutes

    websocket:
      subscribe_new_heads: true
      new_heads_timeout_ms: 20000  # Shorter timeout
      failover:
        max_backfill_blocks: 100
        backfill_timeout_ms: 30000

    ui-topology:
      color: "#0052FF"
      size: lg

    providers:
      # ...

Best Practices

Match probe intervals to block time

Set probe_interval_ms to 1x block time for L1 chains and 2.5x for L2 chains. This balances responsiveness with overhead.

Adjust lag tolerance for chain speed

Fast L2 chains produce many blocks quickly. Increase max_lag_blocks to 5-10 to avoid false positives from temporary sync delays.

Calculate archival threshold by time

Use the ~25 minute rule: archival_threshold = (25 * 60 * 1000) / block_time_ms. This ensures consistent historical data access across chains.

Enable WebSocket subscriptions when available

WebSocket subscriptions provide real-time block tracking with sub-second lag detection. Disable only if providers don’t support it or stability is an issue.

Use descriptive chain keys

Chain keys (e.g., ethereum, base-sepolia) appear in URLs and logs. Use canonical names that clearly identify the network.

Next Steps

Provider Configuration

Learn how to configure providers for your chains

Get Started

Core Concepts

Configuration

Deployment

Observability

Advanced

Profile Configuration

Frontmatter

Example Frontmatter

Chain Configuration

Basic Fields

Monitoring

Selection

WebSocket

UI Topology

Complete Example

L2 Chain Example

Best Practices

Next Steps

Provider Configuration

​Frontmatter

​Example Frontmatter

​Chain Configuration

​Basic Fields

​Monitoring

​Selection

​WebSocket

​UI Topology

​Complete Example

​L2 Chain Example

​Best Practices

​Next Steps

Provider Configuration

Frontmatter

Example Frontmatter

Chain Configuration

Basic Fields

Monitoring

Selection

WebSocket

UI Topology

Complete Example

L2 Chain Example

Best Practices

Next Steps