Provider Capabilities

Capabilities declare what a provider supports and its operational limits. Lasso uses this information to filter eligible providers and classify errors during request routing.

Overview

The capabilities field in provider configuration allows you to specify:

Unsupported methods - RPC methods the provider doesn’t support
Limits - Block range and age restrictions
Error rules - Custom error classification for provider-specific error codes

When capabilities are omitted, Lasso assumes the provider is fully capable (only local_only methods are blocked by default).

Unsupported Methods

Unsupported Categories

capabilities.unsupported_categories

array

List of method categories this provider doesn’t support. Requests for these methods will skip this provider during routing.

capabilities:
  unsupported_categories: [debug, trace, txpool]

Available categories:

debug - Debug namespace methods (debug_*)
trace - Trace namespace methods (trace_*)
txpool - Transaction pool methods (txpool_*)
eip4844 - EIP-4844 blob methods
filters - Filter methods (eth_newFilter, eth_getFilterChanges, etc.)
subscriptions - WebSocket subscriptions

Unsupported Methods

capabilities.unsupported_methods

array

List of specific RPC methods this provider doesn’t support.

capabilities:
  unsupported_methods:
    - eth_getLogs
    - eth_protocolVersion

Example: Public Provider Restrictions

providers:
  - id: "publicnode_ethereum"
    url: "https://ethereum-rpc.publicnode.com"
    capabilities:
      unsupported_categories: [debug, trace, txpool, eip4844, filters]
      unsupported_methods:
        - eth_protocolVersion

This configuration prevents Lasso from routing debug traces, transaction pool queries, or filter-based subscriptions to PublicNode.

Limits

Limits define operational boundaries for the provider. Lasso uses these to filter providers before sending requests.

Block Range Limit

capabilities.limits.max_block_range

integer

Maximum block range for eth_getLogs and similar range queries.

capabilities:
  limits:
    max_block_range: 1000

If a request exceeds this range, Lasso skips the provider or splits the request into smaller chunks (depending on routing strategy).

Block Age Limit

capabilities.limits.max_block_age

integer

Maximum age (in blocks) for state methods on pruned providers.

capabilities:
  limits:
    max_block_age: 1000

Providers with this limit are excluded for requests older than current_block - max_block_age.

capabilities.limits.block_age_methods

array

Methods subject to max_block_age limit. Typically state-reading methods.

capabilities:
  limits:
    max_block_age: 1000
    block_age_methods:
      - eth_call
      - eth_getBalance
      - eth_getCode
      - eth_getStorageAt
      - eth_getTransactionCount

Example: Pruned Provider Configuration

providers:
  - id: "publicnode_ethereum"
    url: "https://ethereum-rpc.publicnode.com"
    archival: false
    capabilities:
      limits:
        max_block_age: 1000
        max_block_range: 1000
        block_age_methods:
          - eth_call
          - eth_getBalance
          - eth_getCode
          - eth_getStorageAt
          - eth_getTransactionCount

This provider:

Only serves data from the last 1000 blocks
Limits eth_getLogs queries to 1000-block ranges
Automatically excluded for historical state queries

Error Rules

Error rules allow you to classify provider-specific error codes for better routing decisions. Lasso uses error categories to determine retry behavior and provider health.

capabilities.error_rules

array

List of error classification rules. First matching rule wins.Each rule can match by:

code - JSON-RPC error code
message_contains - Substring in error message

And assigns a category:

capability_violation - Provider doesn’t support the method
rate_limit - Provider rate limit exceeded
requires_archival - Request needs archival data
internal_error - Provider internal error

capabilities:
  error_rules:
    - code: 35
      category: capability_violation
    - message_contains: "timeout on the free tier"
      category: rate_limit

Error Categories

Category	Description	Retry Behavior
`capability_violation`	Method not supported	Skip provider permanently for this method
`rate_limit`	Rate limit exceeded	Circuit breaker opens, retry other providers
`requires_archival`	Needs historical data	Skip non-archival providers
`internal_error`	Provider-side error	Retry with exponential backoff

Example: dRPC Error Rules

providers:
  - id: "ethereum_drpc"
    url: "https://eth.drpc.org"
    capabilities:
      error_rules:
        # Code 30 with specific message = rate limit
        - code: 30
          message_contains: "timeout on the free tier"
          category: rate_limit
        
        # Code 30 without message = generic rate limit
        - code: 30
          category: rate_limit
        
        # Code 35 = unsupported method
        - code: 35
          category: capability_violation

Example: PublicNode Error Rules

providers:
  - id: "ethereum_publicnode"
    url: "https://ethereum-rpc.publicnode.com"
    capabilities:
      error_rules:
        # Custom error code for unsupported methods
        - code: -32701
          category: capability_violation
        
        # Message-based detection for pruned data
        - message_contains: "pruned"
          category: requires_archival

Complete Example

Here’s a fully configured provider with all capability types:

providers:
  - id: "ethereum_drpc"
    name: "dRPC Ethereum"
    url: "https://eth.drpc.org"
    ws_url: "wss://eth.drpc.org"
    archival: true
    capabilities:
      # Method restrictions
      unsupported_categories: []
      unsupported_methods: []
      
      # Operational limits
      limits:
        max_block_range: 10000
      
      # Error classification
      error_rules:
        - code: 30
          message_contains: "timeout on the free tier"
          category: rate_limit
        - code: 30
          category: rate_limit
        - code: 35
          category: capability_violation

Default Behavior

When capabilities is omitted entirely:

providers:
  - id: "my_provider"
    url: "https://my-rpc.example.com"
    # No capabilities field

Lasso assumes:

All methods are supported except local_only category
No block range or age limits
Standard error code interpretation

This is appropriate for:

Your own full nodes
Enterprise provider subscriptions with full support
Initial testing before fine-tuning capabilities

Testing Capabilities

After configuring capabilities, verify they work correctly:

Test Unsupported Methods

# Should fail or skip provider
curl -X POST http://localhost:4000/rpc/provider/publicnode_ethereum/ethereum \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"debug_traceTransaction","params":["0x123..."],"id":1}'

Test Block Range Limits

# Should skip providers with max_block_range < 10000
curl -X POST http://localhost:4000/rpc/ethereum \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"eth_getLogs",
    "params":[{"fromBlock":"0x1","toBlock":"0x2710"}],
    "id":1
  }'

Test Error Rules

Trigger rate limits or capability violations and check the dashboard for correct error categorization.

Best Practices

Start permissive, narrow down

Begin with no capabilities configured. Monitor errors in the dashboard and add restrictions based on actual provider behavior.

Document provider limits

Use YAML comments to note where capability values came from (provider docs, observed behavior, support tickets).

capabilities:
  limits:
    max_block_range: 1000  # From provider docs: https://...

Match error rules to provider docs

Provider API documentation often lists error codes. Create rules for rate limits, method restrictions, and data availability.

Test fallback behavior

Verify that requests fail over correctly when a provider’s capabilities are insufficient.

Update capabilities as providers evolve

Provider capabilities change (new methods, increased limits). Review configurations periodically.

Real-World Examples from default.yml

Archival Provider (dRPC)

- id: "ethereum_drpc"
  url: "https://eth.drpc.org"
  archival: true
  capabilities:
    limits:
      max_block_range: 10000
    error_rules:
      - code: 30
        message_contains: "timeout on the free tier"
        category: rate_limit
      - code: 30
        category: rate_limit
      - code: 35
        category: capability_violation

Pruned Provider (PublicNode)

- id: "ethereum_publicnode"
  url: "https://ethereum-rpc.publicnode.com"
  archival: false
  capabilities:
    unsupported_categories: [debug, trace, txpool, eip4844, filters]
    limits:
      max_block_age: 1000
      block_age_methods:
        - eth_call
        - eth_getBalance
        - eth_getCode
        - eth_getStorageAt
        - eth_getTransactionCount
    error_rules:
      - code: -32701
        category: capability_violation
      - message_contains: "pruned"
        category: requires_archival

Limited Free Provider (Merkle)

- id: "ethereum_merkle"
  url: "https://eth.merkle.io"
  archival: false
  capabilities:
    limits:
      max_block_range: 1000

Get Started

Core Concepts

Configuration

Deployment

Observability

Advanced

Provider Capabilities

Overview

Unsupported Methods

Unsupported Categories

Unsupported Methods

Example: Public Provider Restrictions

Limits

Block Range Limit

Block Age Limit

Example: Pruned Provider Configuration

Error Rules

Error Categories

Example: dRPC Error Rules

Example: PublicNode Error Rules

Complete Example

Default Behavior

Testing Capabilities

Test Unsupported Methods

Test Block Range Limits

Test Error Rules

Best Practices

Real-World Examples from default.yml

Archival Provider (dRPC)

Pruned Provider (PublicNode)

Limited Free Provider (Merkle)

Next Steps

Environment Variables

Provider Configuration

Get Started

Core Concepts

Configuration

Deployment

Observability

Advanced

​Overview

​Unsupported Methods

​Unsupported Categories

​Unsupported Methods

​Example: Public Provider Restrictions

​Limits

​Block Range Limit

​Block Age Limit

​Example: Pruned Provider Configuration

​Error Rules

​Error Categories

​Example: dRPC Error Rules

​Example: PublicNode Error Rules

​Complete Example

​Default Behavior

​Testing Capabilities

​Test Unsupported Methods

​Test Block Range Limits

​Test Error Rules

​Best Practices

​Real-World Examples from default.yml

​Archival Provider (dRPC)

​Pruned Provider (PublicNode)

​Limited Free Provider (Merkle)

​Next Steps

Environment Variables

Provider Configuration

Overview

Unsupported Methods

Unsupported Categories

Unsupported Methods

Example: Public Provider Restrictions

Limits

Block Range Limit

Block Age Limit

Example: Pruned Provider Configuration

Error Rules

Error Categories

Example: dRPC Error Rules

Example: PublicNode Error Rules

Complete Example

Default Behavior

Testing Capabilities

Test Unsupported Methods

Test Block Range Limits

Test Error Rules

Best Practices

Real-World Examples from default.yml

Archival Provider (dRPC)

Pruned Provider (PublicNode)

Limited Free Provider (Merkle)

Next Steps