Profile configuration

Profile File Structure

# config/profiles/<slug>.yml

# --- Frontmatter (YAML document separator) ---
---
name: "My Profile"           # Display name
slug: "my-profile"           # URL identifier (used in /rpc/profile/:slug/...)
rps_limit: 100               # Dashboard tester maximum RPS
burst_limit: 500             # Metadata; not enforced by OSS
---

# --- Body: Chain configurations ---
chains:
  ethereum:
    chain_id: 1
    providers:
      - id: "my_provider"
        url: "https://..."

Frontmatter fields:

Field	Type	Required	Description
`name`	string	Yes	Human-readable profile name
`slug`	string	Yes	URL-safe identifier. Must be unique across profiles
`rps_limit`	integer	No	Maximum RPS offered by dashboard tester controls (default: 100)
`burst_limit`	integer	No	Profile metadata (default: 500); no OSS ingress enforcement

OSS does not authenticate clients or enforce per-client request quotas. Configure authentication and inbound rate limiting at your reverse proxy. Provider quota and circuit-breaker backoff are separate routing controls. Unknown YAML fields and invalid types are rejected. Use booleans (false), not quoted strings ("false"). A failed reload keeps the previous active configuration. Errors identify the field without printing credential values. Profile slugs must match their .yml filenames. Files beginning with _ or . are skipped. Keep a public.yml profile: routes without a profile use public, and it is required at startup. unlisted: true hides a profile from the selector; its endpoints remain accessible.

Chain Configuration

Each chain is a key under chains: with the following structure:

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:
      - id: "ethereum_llamarpc"
        # ...

Chain Fields

Field	Type	Required	Description
`chain_id`	integer	Yes	EIP-155 chain ID
`name`	string	No	Display name (defaults to chain key)
`block_time_ms`	integer	No	Average block time in milliseconds. Used for optimistic lag calculation and the continuity freshness bound
`head_policy`	string	No	`off` (default), `local` (one process), or `global` (enrolled fleet). Global mode requires the publication journal and fleet setup

Monitoring

Controls probe frequency and the dashboard lag status threshold. Shared upstreams use the shortest configured probe interval across profiles; HTTP polling slows while WebSocket block updates are active.

Field	Type	Default	Description
`probe_interval_ms`	integer	12000	Health check polling interval. Set to ~1x block time for L1, ~2.5x for L2
`lag_alert_threshold_blocks`	integer	3	Dashboard lag status threshold; this setting does not emit lag warning logs

Selection

Controls provider eligibility filtering during request routing.

Field	Type	Default	Description
`max_lag_blocks`	integer	unset	Exclude providers lagging more than N blocks. L1: 1-2, L2: 3-10
`archival_threshold`	integer	128	Blocks before data is considered “archival”. Requests for blocks older than `head - threshold` are only routed to archival providers

WebSocket

Controls upstream WebSocket subscription behavior.

Field	Type	Default	Description
`subscribe_new_heads`	boolean	true	Enable `newHeads` block tracking and eligibility for client `newHeads` subscriptions
`new_heads_timeout_ms`	integer	42000	Timeout before marking subscription stale (~3x block time)
`failover.max_backfill_blocks`	integer	100	Max blocks to fetch via HTTP during subscription failover
`failover.backfill_timeout_ms`	integer	30000	Timeout for backfill HTTP requests

Failover limits are captured from the active profile at the beginning of each recovery, including after YAML reload. An in-progress recovery keeps its captured limits. The backfill timeout is also bounded by the overall 30-second recovery deadline. Gaps beyond max_backfill_blocks terminate continuity rather than silently skipping missing blocks.

UI Topology

Dashboard visualization settings.

Field	Type	Default	Description
`color`	string	-	Hex color for the chain node in the dashboard topology
`size`	string	`md`	Node size: `sm`, `md`, `lg`, `xl`

For live updates, see Profiles and reload.

Get Started

Core Concepts

Configuration

Deployment

Observability

Advanced

Profile configuration

Profile File Structure

Chain Configuration

Chain Fields

Monitoring

Selection

WebSocket

UI Topology

​Profile File Structure

​Chain Configuration

​Chain Fields

​Monitoring

​Selection

​WebSocket

​UI Topology

Profile File Structure

Chain Configuration

Chain Fields

Monitoring

Selection

WebSocket

UI Topology