eth_subscribe

zkLink Nova chain RPC Methods & API Documentation


eth_subscribe RPC method

💡

eth_subscribe Ethereum method is only available through WebSockets.

eth_subscribe is a JSON-RPC method available on zkLink Nova (Ethereum and so on..) nodes that allows you to subscribe to specific events such as new block headers, new pending transactions, and logs matching a filter. The node will push updates to the client when these events occur.

Returns

Subscription ID to identify Subscription Notifications in the future.

Notifications - After you recieve the Subscription ID, you'll recieve notifications about state changes, that you subcribed to as they happen on chain.

Parameters

  • subscription name [required] - String - The type of event you want to subscribe to (i.e., newHeads, logs, pendingTransactions, newPendingTransactions). There are the following subscription types:

    • newHeads - It fires a notification each time a new block is appended to the chain, including chain reorganizations.

    • logs - It returns logs that are included in new imported blocks and match the given filter criteria.

      • address [optional] - either an address or an array of addresses. Only logs that are created from these addresses are returned
      • topics [optional] - only logs which match the specified topics are returned. 👉 Learn more (opens in a new tab)
    • newPendingTransactions - Returns the hash for all transactions that are added to the pending state. When a transaction that was previously part of the canonical chain isn't part of the new canonical chain after a reogranization its again emitted. It includes only the hash of the transaction.

    • newPendingTransactionsWithBody - Returns the hash for all transactions that are added to the pending state. When a transaction that was previously part of the canonical chain isn't part of the new canonical chain after a reogranization its again emitted. It includes the details of the transaction.

💡

Parameter syncing - Indicates when the node starts or stops synchronizing. We do not support it at CHAINNODES.ORG as our nodes are always synced for you.

💡 Confusing?

Ask our experienced blockchain developers in Telegram

Request

POST https://<network>.chainnodes.org/YOUR-API-KEY

Example

  • WSS Request with a JSON RPC call in the body
  • Replace YOUR-API-KEY with the API key from your CHAINNODES.ORG Dashboard
  • You can use a different supported network by replacing zklink-nova-mainnet
wscat \
    -c wss://zklink-nova-mainnet.chainnodes.org/YOUR-API-KEY
 
# newHeads
> { "jsonrpc": "2.0", "method": "eth_subscribe", "params": ["newHeads"], "id": 1 }
 
# newPendingTransactions
> { "jsonrpc": "2.0", "method": "eth_subscribe", "params": ["newPendingTransactions"], "id": 1 }
 
#  newPendingTransactionsWithBody
> { "jsonrpc": "2.0", "method": "eth_subscribe", "params": ["newPendingTransactionsWithBody"], "id": 1 }
 
#  logs
> { "jsonrpc": "2.0", "method": "eth_subscribe", "params": ["logs", {}], "id": 1 }
 

Need RPC API keys?

Get 12.5M archival requests for free today.

Body

{
    "result": "0x44567e1f7aa50f78e15c1a93dd9cbfd3",
    "jsonrpc": "2.0",
    "id": 1
}
 
# newHeads Notification
 
{
    "method": "eth_subscription",
    "jsonrpc": "2.0",
    "params": {
        "result": {
            "baseFeePerGas": "0x6df25209b",
            "gasLimit": "0x1c9c380",
            "gasUsed": "0x1b97286",
            "difficulty": "0x0",
            "number": "0x1032297",
            "logsBloom": "0xffbfc3d867d8b68364d88634a199ff397b93db2f45f7124cfa9fbf515e8e3f8755e7dbf5da7a2b2860397b7e5b3b775bf7a72ffbfe4bed317acece97d8beb84c85b2d3fc5a49ddecead1461d53ff38f184767cd9ddd71ff92f5f1e559b52bd7ddf76af79e6dbed03a5daf828cb9b7dc0db1d2ed76c5c44fa06a7a0d2be2ea67c2af79e5bebf74772e26b9e52b776053763ecbcdff108b9f9e5395a705e517a6fbbdae9fed1f3eaea1f6bddb6e733250026e2cc35fbb6ffef0dfb86964d3cb5c8795e41e7092efc332ffb5f82dc4bb19551fc77275effbfd5efbd351f7e32e1555cdfbfec99d6f3b86b8d162eabab5ca5cc35d119197cc4d12049f81f92f6e435",
            "nonce": "0x0000000000000000",
            "miner": "0x5f927395213ee6b95de97bddcb1b2b1c0f16844f",
            "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
            "stateRoot": "0xd9123f041043b652b4b46c1344c261375a8cd0a829091c036f5c2d24bd537400",
            "transactionsRoot": "0x4e5bfefc867ab744b106a4748f6f813e292f376f79761c60bf365e9696337fe8",
            "hash": "0xae09310a90217c76ac480020653894dae089aa7a133291e2820b88daf7c0532c",
            "receiptsRoot": "0x678c4e640727c287b95b2ff6f189b9d3da2a371e49884329bfb45cae319cc410",
            "timestamp": "0x642d6e2f",
            "mixHash": "0xb73b134acb9a46aac06da0c51c0da97169ace6085d61f23a279b1963fea0f36c",
            "parentHash": "0x0cc56df5cd37b06c230b241dd93e9664244cb86099944bc503fbee35edd59a8d",
            "extraData": "0x6d616e74612d6275696c646572",
            "withdrawalsRoot": null
        },
        "subscription": "0x44567e1f7aa50f78e15c1a93dd9cbfd3"
    }
}
 
# newPendingTransactions Notification
{
    "params": {
        "result": "0x9b0a6b7fd5817e86267547c57cc9dcf1b64626214bb5fb84b90b8cf0f02a95c4",
        "subscription": "0x9ac5c0ccb2faa00f094046cd9283a637"
    },
    "method": "eth_subscription",
    "jsonrpc": "2.0"
}
 
#  newPendingTransactionsWithBody Notification
{
    "jsonrpc": "2.0",
    "method": "eth_subscription",
    "params": {
        "subscription": "0x0f659211bd6b7d0c962bee40a6b5d8c1",
        "result": {
            "gasPrice": "0x843f70300",
            "maxPriorityFeePerGas": null,
            "value": "0x0",
            "s": "0x47ebeadc00156cf2fe70189694b722f21289970d8c49f59aaef875b1ec7e41b3",
            "nonce": "0xb5",
            "hash": "0x1029809f7d98a29c45e06ed628ebd3b8b46f987404eb56fe3295c52fcb9f95be",
            "type": "0x0",
            "input": "0xa9059cbb00000000000000000000000075e89d5979e4f6fba9f97c104c2f0afb3f1dcb88000000000000000000000000000000000000000000000b7797828d2afca04000",
            "to": "0x9040e237c3bf18347bb00957dc22167d0f2b999d",
            "v": "0x26",
            "gas": "0xd804",
            "maxFeePerGas": null,
            "r": "0x1edd331ee93e2591def7b7018cdd985f31e4e8b1865f55ab36bc2bf95e7f6123"
        }
    }
}
 
#  logs Notification
{
    "jsonrpc": "2.0",
    "method": "eth_subscription",
    "params": {
        "result": {
            "transactionIndex": "0xb",
            "data": "0x0000000000000000000000000000000000000000000000000000000011e1a300",
            "blockHash": "0xddeaf530bea356aae7c55540386f2e32a202eb308b110f5bb8174bf410ec16d1",
            "address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
            "topics": [
                "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
                "0x0000000000000000000000000951b39561e01151c99c16739c1a9b9264bea56c",
                "0x0000000000000000000000001689a089aa12d6cbbd88bc2755e4c192f8702000"
            ],
            "transactionHash": "0xcfafa178fcf2ed2ad48a2b664a3d5070d1a0ddb5b6dbeb35b65a488b180184b5",
            "logIndex": "0x11",
            "blockNumber": "0x10322ac",
            "removed": false
        },
        "subscription": "0xd4a23c4ae337b37920e97eca96ba581f"
    }
}