Understanding the OKTC Websocket API for Real-Time Blockchain Data

·

The OKTC blockchain, built with the Cosmos SDK and utilizing Tendermint Core as its consensus engine, inherits its native event format from these technologies. However, to ensure full compatibility with the popular Ethereum Web3 standard, OKTC translates its Tendermint responses into Ethereum-compatible data types. This allows developers familiar with Ethereum's tools and interfaces to seamlessly interact with the OKTC network using the same patterns and protocols, particularly through the powerful Pub/Sub API over WebSockets.

This guide provides a comprehensive overview of using the OKTC Websocket API to subscribe to real-time blockchain events.

Establishing a Websocket Connection

To begin receiving real-time data, you must first establish a connection to the OKTC WebSocket endpoint.

Mainnet Websocket URL:
The primary endpoint for connecting to the OKTC mainnet is provided by the network.

Connection Initialization:
You can start a connection using the --wsport flag when initializing the REST server. The default port is typically 8546. Once the server is running, you can use any WebSocket client library, such as ws for Node.js, to initiate the connection from your application.

Creating a Subscription

Subscriptions are the core mechanism for receiving real-time updates. You create a subscription by making a regular RPC call to the WebSocket endpoint.

How to Create a Subscription

The method for creating a subscription is eth_subscribe. This call requires you to specify the type of event you wish to listen for.

Parameters:

  1. Subscription Name: The name of the event you want to subscribe to (e.g., newHeads, logs).
  2. Optional Arguments: Additional parameters required for certain subscription types, such as filter criteria for logs.

If the subscription is created successfully, the server will return a unique subscription ID. This ID is crucial for managing the subscription later.

Example Request:
This is an example of how you might structure a request to subscribe to new block headers.

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

Canceling a Subscription

To stop receiving events and free up resources, you should cancel active subscriptions when they are no longer needed.

How to Cancel a Subscription

Subscriptions are cancelled using the eth_unsubscribe method along with the subscription ID received during creation.

Parameters:

  1. Subscription ID: The unique identifier of the subscription you wish to terminate.

This RPC call returns a boolean value indicating whether the unsubscription request was successful.

Example Request:

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

Supported Subscription Types

The OKTC Websocket API supports several subscription types, mirroring the Ethereum Web3 standard for developer convenience.

newHeads

This subscription emits a notification every time a new block header is added to the chain. It is particularly useful for tracking the latest state of the blockchain.

👉 Explore real-time block header tracking

Logs

The logs subscription is essential for decentralized applications (dApps) that need to listen for specific smart contract events.

newPendingTransactions

This subscription provides the hashes of transactions as they enter the mempool (the pending state), before they are included in a block.

👉 Get advanced methods for monitoring transaction pools

syncing

The syncing subscription informs your application when the node it is connected to starts or stops synchronizing with the network.

Frequently Asked Questions

What is the main benefit of using a WebSocket API over standard HTTP RPC?
The WebSocket API provides a persistent, bidirectional connection that allows the server to push data to the client instantly. This is ideal for real-time applications like dashboards, wallets, and dApps that need immediate updates on new blocks, transactions, or log events, eliminating the need for inefficient constant polling.

How do I handle a chain reorganization when subscribed to 'logs'?
During a reorg, the API will send previously received logs from the old chain with a "removed": true flag. Your application logic should listen for this flag and undo any actions based on those now-orphaned logs. Subsequently, new logs from the canonical chain will be emitted, which you should process as new events.

Can I filter logs by multiple contract addresses?
Yes, the address parameter in the logs subscription accepts an array of addresses. This allows you to listen for events emitted from multiple smart contracts within a single subscription, making your code more efficient and easier to manage.

Is the 'newPendingTransactions' subscription guaranteed to show all transactions?
This subscription only returns transactions that are signed with a key available to the node (i.e., transactions sent from the node itself or those it is aware of). It may not show all transactions existing in the global network mempool, as that depends on the node's peer connections and propagation.

What happens if my WebSocket connection drops?
Most WebSocket clients support automatic reconnection. However, upon reconnection, all previous subscriptions are typically lost and must be recreated manually by your application. It's important to implement reconnection and re-subscription logic to ensure resilience.

What is the difference between 'newHeads' and 'newPendingTransactions'?
newHeads notifies you about finalized blocks that have been added to the canonical chain. newPendingTransactions notifies you about transactions that have been broadcasted but are not yet included in a block (i.e., they are in the mempool). The former is about certainty, the latter is about initial broadcast.