Subscriptions

Lasso supports Ethereum JSON-RPC subscriptions over WebSocket for real-time blockchain events. Use eth_subscribe to create subscriptions and eth_unsubscribe to cancel them.

Subscription Types

Lasso supports the following subscription types:

Type	Description
`newHeads`	New block headers as they arrive
`logs`	Log events matching a filter

Creating Subscriptions

Request:

{"jsonrpc":"2.0","method":"eth_subscribe","params":["newHeads"],"id":1}

Response:

{"jsonrpc":"2.0","id":1,"result":"0xabc123..."}

The result field contains the subscription ID. Save this ID to unsubscribe later. Subscription Events: As new blocks arrive, the server pushes events:

{
  "jsonrpc":"2.0",
  "method":"eth_subscription",
  "params":{
    "subscription":"0xabc123...",
    "result":{
      "parentHash":"0x...",
      "sha3Uncles":"0x...",
      "miner":"0x...",
      "stateRoot":"0x...",
      "transactionsRoot":"0x...",
      "receiptsRoot":"0x...",
      "logsBloom":"0x...",
      "difficulty":"0x0",
      "number":"0x8471c9a",
      "gasLimit":"0x1c9c380",
      "gasUsed":"0x5208",
      "timestamp":"0x65f3a2b0",
      "extraData":"0x...",
      "mixHash":"0x...",
      "nonce":"0x0000000000000000",
      "baseFeePerGas":"0x7",
      "hash":"0x..."
    }
  }
}

Request with filter:

{
  "jsonrpc":"2.0",
  "method":"eth_subscribe",
  "params":[
    "logs",
    {
      "address":"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "topics":["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
    }
  ],
  "id":2
}

This example subscribes to Transfer events from USDC on Ethereum. Response:

{"jsonrpc":"2.0","id":2,"result":"0xdef456..."}

Subscription Events: As matching logs are emitted, the server pushes events:

{
  "jsonrpc":"2.0",
  "method":"eth_subscription",
  "params":{
    "subscription":"0xdef456...",
    "result":{
      "address":"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "topics":[
        "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        "0x000000000000000000000000742d35cc6634c0532925a3b844bc454e4438f44e",
        "0x0000000000000000000000001e0049783f008a0085193e00003d00cd54003c71"
      ],
      "data":"0x0000000000000000000000000000000000000000000000000000000002faf080",
      "blockNumber":"0x8471c9a",
      "transactionHash":"0x...",
      "transactionIndex":"0x0",
      "blockHash":"0x...",
      "logIndex":"0x0",
      "removed":false
    }
  }
}

The logs subscription accepts a filter object with:

Field	Type	Description
`address`	string or array	Contract address(es) to filter. Omit for all contracts.
`topics`	array	Event signature and indexed parameters. Use `null` for wildcards.

Examples: All events from a contract:

{
  "address":"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
}

Specific event signature across all contracts:

{
  "topics":["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
}

Event from multiple contracts:

{
  "address":[
    "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "0xdac17f958d2ee523a2206206994597c13d831ec7"
  ],
  "topics":["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
}

Event with indexed parameter filter:

{
  "address":"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  "topics":[
    "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
    null,
    "0x0000000000000000000000001e0049783f008a0085193e00003d00cd54003c71"
  ]
}

This filters for Transfer events where the second indexed parameter (recipient) matches the specified address.

Unsubscribing

Cancel a subscription using eth_unsubscribe: Request:

{"jsonrpc":"2.0","method":"eth_unsubscribe","params":["0xabc123..."],"id":3}

Response:

{"jsonrpc":"2.0","id":3,"result":true}

A result of true indicates successful unsubscription. After unsubscribing, no more events will be pushed for that subscription ID.

Full Example

Here’s a complete subscription flow using wscat:

# Connect to WebSocket endpoint
wscat -c 'ws://localhost:4000/ws/rpc/ethereum'

# Subscribe to new blocks
> {"jsonrpc":"2.0","method":"eth_subscribe","params":["newHeads"],"id":1}
< {"jsonrpc":"2.0","id":1,"result":"0xabc123..."}

# Receive block events
< {"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0xabc123...","result":{...}}}
< {"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0xabc123...","result":{...}}}

# Unsubscribe
> {"jsonrpc":"2.0","method":"eth_unsubscribe","params":["0xabc123..."],"id":2}
< {"jsonrpc":"2.0","id":2,"result":true}

Subscription Lifecycle

Automatic Cleanup

Subscriptions are automatically cleaned up when:

The WebSocket connection closes
The connection times out (see Connection Lifecycle)
An eth_unsubscribe request is received

Multiple Subscriptions

You can create multiple subscriptions on a single WebSocket connection:

// Subscribe to blocks
{"jsonrpc":"2.0","method":"eth_subscribe","params":["newHeads"],"id":1}

// Subscribe to logs
{"jsonrpc":"2.0","method":"eth_subscribe","params":["logs",{"address":"0x..."}],"id":2}

Each subscription receives a unique subscription ID and events are tagged with the corresponding ID.

Error Handling

Invalid Subscription Type

Request:

{"jsonrpc":"2.0","method":"eth_subscribe","params":["invalidType"],"id":1}

Response:

{
  "jsonrpc":"2.0",
  "id":1,
  "error":{
    "code":-32602,
    "message":"Invalid subscription parameters"
  }
}

For logs, Core accepts a filter object and forwards it to the selected upstream. An unsupported field is not rejected locally with a fixed “malformed filter” response; upstream validation and error details can vary.

Unsubscribe Non-Existent Subscription

Request:

{"jsonrpc":"2.0","method":"eth_unsubscribe","params":["0xnonexistent"],"id":3}

Response:

{"jsonrpc":"2.0","id":3,"result":false}

A result of false indicates the subscription ID was not found.

Best Practices

Track Subscription IDs

Always store subscription IDs returned by eth_subscribe to unsubscribe later:

const subscriptionIds = new Map();

// Subscribe
const request = {jsonrpc: "2.0", method: "eth_subscribe", params: ["newHeads"], id: 1};
ws.send(JSON.stringify(request));

ws.on('message', (data) => {
  const response = JSON.parse(data);
  if (response.id === 1) {
    subscriptionIds.set('newHeads', response.result);
  }
});

// Unsubscribe
function cleanup() {
  const subId = subscriptionIds.get('newHeads');
  if (subId) {
    const request = {jsonrpc: "2.0", method: "eth_unsubscribe", params: [subId], id: 2};
    ws.send(JSON.stringify(request));
  }
}

Handle Reconnection

Subscriptions don’t persist across reconnections. Re-subscribe after reconnecting:

ws.on('open', () => {
  // Re-subscribe to all active subscriptions
  subscribeToNewHeads();
  subscribeToLogs();
});

Filter Logs Efficiently

Use specific filters to reduce network traffic:

// Good: Specific contract and event
{
  "address":"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  "topics":["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
}

// Avoid: No filter (receives all logs)
{}

Rate Limiting

Lasso RPC Core has no built-in incoming customer quota mechanism. Enforce ingress connection/request limits at your proxy and account for upstream-provider limits and subscription volume. Use bounded filters and follow the recovery and checkpoint guide. Cloud limits are a separate managed-service contract.

HTTP API

WebSocket API

Status and metrics

Reference

Releases and evidence

Subscriptions

Subscription Types

Creating Subscriptions

Unsubscribing

Full Example

Subscription Lifecycle

Automatic Cleanup

Multiple Subscriptions

Error Handling

Invalid Subscription Type

Unsubscribe Non-Existent Subscription

Best Practices

Track Subscription IDs

Handle Reconnection

Filter Logs Efficiently

Rate Limiting

​Subscription Types

​Creating Subscriptions

​Subscribe to New Block Headers

​Subscribe to Logs

​Log Filter Options

​Unsubscribing

​Full Example

​Subscription Lifecycle

​Automatic Cleanup

​Multiple Subscriptions

​Error Handling

​Invalid Subscription Type

​Unsubscribe Non-Existent Subscription

​Best Practices

​Track Subscription IDs

​Handle Reconnection

​Filter Logs Efficiently

​Rate Limiting

Subscription Types

Creating Subscriptions

Subscribe to New Block Headers

Subscribe to Logs

Log Filter Options

Unsubscribing

Full Example

Subscription Lifecycle

Automatic Cleanup

Multiple Subscriptions

Error Handling

Invalid Subscription Type

Unsubscribe Non-Existent Subscription

Best Practices

Track Subscription IDs

Handle Reconnection

Filter Logs Efficiently

Rate Limiting