Configure event notifications

Raylz supports publish and subscribe functionality through JSON-RPC notifications. When enabled, clients can listen for events instead of continuously polling for them.

The notification mechanism allows subscription to specific server events by checking a node's subscription ID against events published in the server. Events that have matching subscription IDs trigger a notification containing relevant data and the subscription ID.

Notifications are only sent for current server events. Events that occurred before enabling this feature will not trigger notifications.

Event notifications are stored in an internal buffer, with a cap of 10,000 notifications by default. When the buffer is reached, the server connection is closed.

Subscriptions require a full-duplex connection, available through WebSocket and IPC server configuration. Subscriptions are removed when the connection closes.

Supported subscriptions

Raylz supports subscriptions to the following events: newHeads, logs, newPendingTransactions, and syncing.

newHeads

The newHeads event occurs when new headers are appended to the chain. This event is also triggered by chain reorganizations.

To subscribe to newHeads events, pass the event as a JSON object for "params".

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

logs

The logs event applies to new imported blocks. Logs are returned based on criteria from a provided filter.

To subscribe to logs events, pass the event and a search filter as a JSON object to "params".

{ "id": 1, "jsonrpc": "2.0", "method": "eth_subscribe", "params": ["logs", {"address": "...", "topics": [...] }] }

newPendingTransactions

The newPendingTransactions event occurs after transactions are added to the pending state. This event is triggered when the transaction hash is returned.

To subscribe to newPendingTransactions events, pass the event name as a JSON object to "params".

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

syncing

The syncing event indicates when a node starts or stops synchronization with the server. Notifications can return a Boolean value or an object with progress indicators.

To subscribe to syncing events, pass the event name as a JSON object to "params".

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

Subscription management

Create subscription

Initiate subscriptions with eth_subscribe. Pass in the subscription name and other arguments as needed.

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

When successful, this command returns a subscription ID.

{ "id": 1, "jsonrpc": "2.0", "result": "0xcd0c3e8af590364c09d0fa6a1210faf5" }

Receive notifications

Notifications can be enabled for all events at once. To receive all event notifications, pass eth_subscribe and a "difficulty" value if applicable.

{ "jsonrpc": "2.0", "method": "eth_subscription", "params": {"subscription": "0xcd0c3e8af590364c09d0fa6a1210faf5", "result": {"difficulty": "0xd9263f42a87", ...}} }
{ "jsonrpc": "2.0", "method": "eth_subscription", "params": {"subscription": "0xcd0c3e8af590364c09d0fa6a1210faf5", "result": {"difficulty": "0xd90b1a7ad02", ...}} }

Cancel subscription

Cancel subscriptions with the eth_unsubscribe method. Pass the method with a valid subscription ID.

{ "id": 1, "jsonrpc": "2.0", "method": "eth_unsubscribe", "params": ["0x9cef478923ff08bf67fde6c64013158d"] }

When successful, the method returns a Boolean to represent the canceled subscription.

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

---

This page is a subsection of JSON-RPC server implementation.