The OKTC blockchain, built with the Cosmos SDK and leveraging Tendermint Core as its consensus engine, utilizes a unique event format. To ensure compatibility with the widely adopted Ethereum Web3 standard, OKTC translates its native Tendermint responses into Ethereum data types. This allows developers familiar with Ethereum's tools, like the PubSub API, to interact seamlessly with the OKTC network through WebSocket connections for real-time data streaming.
You can initiate a connection to the Ethereum-compatible WebSocket by using the --wsport flag when starting your REST server. The default port for this connection is 8546. Once the server is running, you can establish a WebSocket subscription using clients such as ws or any other preferred WebSocket client library.
How to Establish a WebSocket Connection
Connecting to the OKTC network via WebSocket is straightforward. After initializing your node or connecting to a remote endpoint, your application can open a persistent connection to begin receiving real-time updates.
Creating a Subscription
To create a subscription, you make a standard JSON-RPC call. The method for this call is eth_subscribe, and the first parameter should be the name of the subscription you wish to create, such as newHeads or logs. Additional optional arguments may be required depending on the subscription type. Upon success, the call returns a unique subscription ID, which is essential for managing the subscription later.
Key Parameters for Subscription Creation
- Subscription Name: The specific event you want to subscribe to (e.g.,
newHeads). - Optional Arguments: For some subscriptions, like
logs, you may need to provide an object with filter criteria.
Example Subscription Request
A typical request to subscribe to new block headers would look like this in your client application.
Canceling a Subscription
Subscriptions are canceled using a similar JSON-RPC call. The method for cancellation is eth_unsubscribe, and the sole parameter is the subscription ID received when the subscription was created. The call returns a boolean value indicating whether the unsubscription was successful.
Key Parameters for Subscription Cancellation
- Subscription ID: The unique identifier of the active subscription you wish to terminate.
Example Cancellation Request
To stop receiving updates, send an unsubscribe request with the relevant subscription ID.
Supported Subscription Types
OKTC's WebSocket API supports several subscription types, mirroring Ethereum's standards to provide developers with familiar functionality.
newHeads
This subscription emits a notification every time a new block header is added to the blockchain. This includes events triggered by chain reorganizations, ensuring you have the most current view of the chain's head.
Parameters for newHeads
- None required.
Example newHeads Output
You will receive a data object containing all the relevant header information for each new block.
Logs
The logs subscription is powerful for monitoring on-chain events. It returns logs that are included in newly imported blocks and match specific filter criteria you provide. In the event of a chain reorganization, logs from orphaned blocks are re-sent with a removed property set to true, while logs from the new canonical chain are emitted as new.
Parameters for Logs
Filter Object: An optional object containing:
address: A single address or an array of addresses. Only logs emitted from these addresses will be returned.topics: An array of topics to filter logs by.
Example Logs Output
Your application will receive a stream of log objects that match your specified filters, providing real-time insight into contract events.
newPendingTransactions
This subscription type sends a notification for every new transaction that is added to the mempool (the pending state) and is signed with a key that is available in your node. If a transaction is removed from the canonical chain due to a reorganization and then re-added, it will be emitted again.
Parameters for newPendingTransactions
- None required.
Example newPendingTransactions Output
You will receive the transaction hash for each new pending transaction that meets the criteria.
syncing
The syncing subscription indicates when the node begins or finishes synchronizing with the network. The result can be a simple boolean (true for started, false for finished) or a detailed object containing various progress indicators, such as current block height and highest known block.
Parameters for syncing
- None required.
Example syncing Output
The output will provide clear status updates on your node's synchronization process.
👉 Explore more strategies for real-time data monitoring
Frequently Asked Questions
What is the default WebSocket port for OKTC?
The default port for connecting to the OKTC WebSocket API is 8546. You specify this using the --wsport flag when initializing your node's REST server.
How do I filter events by a specific smart contract address?
When subscribing to logs, you can include an address parameter in your filter object. This parameter can be a single Ethereum-style address or an array of addresses to monitor multiple contracts simultaneously.
What happens to my subscription during a chain reorganization?
The API is designed to handle reorganizations gracefully. For newHeads, you will receive new headers for the canonical chain. For logs, events from orphaned blocks are marked as removed, and events from the new chain are emitted as new, ensuring data consistency.
Can I subscribe to multiple events over a single WebSocket connection?
Yes, a single WebSocket connection can support multiple active subscriptions. Each subscription is managed independently with its own unique ID for creation and cancellation.
Is there a way to check if my unsubscribe request was successful?
Yes, the response to an eth_unsubscribe RPC call is a boolean value. A return value of true confirms that the subscription was successfully terminated.
What is the main advantage of using WebSocket over standard HTTP APIs?
WebSocket provides a persistent, bidirectional communication channel. This allows the server to push data to your client instantly as events occur on the blockchain, eliminating the need for constant polling and providing truly real-time updates.