mirror of https://github.com/hyperledger/besu
An enterprise-grade Java-based, Apache 2.0 licensed Ethereum client https://wiki.hyperledger.org/display/besu
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
253 lines
9.4 KiB
253 lines
9.4 KiB
description: Using RPC Pub/Sub with Pantheon Web Socket API
|
|
<!--- END of page meta data -->
|
|
|
|
# RPC Pub/Sub
|
|
|
|
## Introduction
|
|
|
|
Use the RPC Pub/Sub methods over [WebSockets](../Reference/Using-JSON-RPC-API.md#endpoint-address-and-port)
|
|
to wait for events instead of polling for them. For example, if a Dapp submits a transaction to the network,
|
|
you can use the RPC Pub/Sub interface to wait for the transaction confirmation followed by a specified
|
|
number of new blocks before confirming the transaction to the user.
|
|
|
|
The RPC Pub/Sub methods are:
|
|
|
|
* `eth_subscribe` - call to create a subscription for specific events.
|
|
* `eth_unsubscribe` - call to cancel a subscription.
|
|
* `eth_subscription` - invoked to publish event notifications to your client.
|
|
|
|
!!!info
|
|
Notifications are published by `eth_subscription`; you do not need to call `eth_subscription`.
|
|
|
|
!!!important
|
|
Unlike other [JSON RPC-API methods](../Reference/JSON-RPC-API-Methods.md),
|
|
the RPC Pub/Sub methods cannot be called over HTTP as well as WebSockets.
|
|
|
|
### Subscription ID
|
|
|
|
`eth_subscribe` returns a subscription ID for each subscription created. Notifications include the subscription ID.
|
|
|
|
|
|
!!!example
|
|
For example, to create a synchonizing subscription
|
|
|
|
```json
|
|
{"id": 1, "method": "eth_subscribe", "params": ["syncing"]}
|
|
```
|
|
The result includes the subscription ID of `"0x1"`:
|
|
```json
|
|
{"jsonrpc":"2.0","id":1,"result":"0x1"}
|
|
```
|
|
The notifications also include the subscription ID of `"0x1"`:
|
|
```json
|
|
{"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0x1","result":{"startingBlock":"0x0","currentBlock":"0x50","highestBlock":"0x343c19"}}}
|
|
```
|
|
|
|
### Notifications when Synchronizing
|
|
|
|
Subscribing to some events (for example, logs) can cause a flood of notifications while the node is synchronizing.
|
|
|
|
Notifications are stored in an internal buffer to be sent to the client.
|
|
If the client falls behind and the number of buffered notifications reaches the limit of ==10,000==, the connection is closed.
|
|
|
|
## Subscribing
|
|
|
|
Use `eth_subscribe` to create subscriptions for the following event types:
|
|
|
|
* [New headers](#new-headers)
|
|
* [Logs](#logs)
|
|
* [Pending transactions](#pending-transactions)
|
|
* [Sychronizng](#synchronizing)
|
|
|
|
If the WebSockets connection is closed, all subscriptions are removed.
|
|
|
|
### New Headers
|
|
|
|
Use the `newHeads` parameter with `eth_subscribe` to be notified each time a new header is added to the blockchain.
|
|
|
|
If a chain reorganization occurs, the subscription publishes notifications for headers in the new chain.
|
|
This means the subscription can publish notifications for multiple headers at the same height on the blockchain.
|
|
|
|
The new headers notification returns [Block Objects](Objects#block-object). Use the `logsBloom` parameter
|
|
to filter blocks to determine which blocks have logs of interest to you.
|
|
|
|
!!!example
|
|
To subscribe to new header notifications:
|
|
|
|
```json
|
|
{"id": 1, "method": "eth_subscribe", "params": ["newHeads"]}
|
|
```
|
|
|
|
Example result:
|
|
```json
|
|
{"jsonrpc":"2.0","id":2,"result":"0x1"}
|
|
```
|
|
|
|
Example notification:
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"method": "eth_subscription",
|
|
"params":{
|
|
"subscription":"0x1",
|
|
"result": {
|
|
"number":"0x40c22",
|
|
"hash":"0x16af2ee1672203c7ac13ff280822008be0f38e1e5bdc675760015ae3192c0e3a",
|
|
"parentHash":"0x1fcf5dadfaf2ab4d985eb05d40eaa23605b0db25d736610c4b87173bfe438f91",
|
|
"nonce":"0x0000000000000000",
|
|
"sha3Uncles":"0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
|
|
"logsBloom":"0x00008000000000080000000000000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000040000000000000000000000000000000000000000001000000000000000000000040000000000000000000000000000000000000400000000010000000000000000100000000000020000000000000000000000000000000000010000000000000000000000000000000000000000000",
|
|
"transactionsRoot":"0x5b2e3c1a49352f1ca9fb5dfe74b7ffbbb6d70e23a12693444e26058d8a8e6296",
|
|
"stateRoot":"0xbe8d3bc58bd982421a3ea8b66753404502df0f464ae78a17661d157c406dd38b",
|
|
"receiptsRoot":"0x81b175ec1f4d44fbbd6ba08f1bd3950663b307b7cb35751c067b535cc0b58f12",
|
|
"miner":"0x0000000000000000000000000000000000000000",
|
|
"difficulty":"0x1",
|
|
"totalDifficulty":"0x7c16e",
|
|
"extraData":"0xd783010600846765746887676f312e372e33856c696e757800000000000000002160f780bb1f61eda045c67cdb1297ba37d8349df8035533cb0cf82a7e45f23f3d72bbec125a9f499b3eb110b7d1918d466cb2ede90b38296cfe2aaf452c513f00",
|
|
"size":"0x3a1",
|
|
"gasLimit":"0x47e7c4",
|
|
"gasUsed":"0x11ac3a",
|
|
"timestamp":"0x592afc24",
|
|
"uncles":[],
|
|
"transactions":["0x419c69d21b14e2e8f911def22bb6d0156c876c0e1c61067de836713043364d6c","0x70a5b2cb2cee6e0b199232a1757fc2a9d6053a4691a7afef8508fd88aeeec703","0x4b3035f1d32339fe1a4f88147dc197a0fe5bbd63d3b9dec2dad96a3b46e4fddd"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Logs
|
|
|
|
Use the `logs` parameter with `eth_subscribe` to be notified of logs included in new blocks.
|
|
|
|
Logs subscriptions have an `object` parameter with the following fields:
|
|
|
|
- `address` - (optional) Either an address or an array of addresses. Returns only logs created from these addresses.
|
|
- `topics` - (optional) Returns only logs that match the specified topics.
|
|
|
|
If a chain reorganization occurs, the subscription publishes notifications for logs from the old chain
|
|
with the `removed` property in the [log object](../Reference/JSON-RPC-API-Objects.md#log-object) set to `true`.
|
|
This means the subscription can publish notifications for multiple logs for the same transaction.
|
|
|
|
The logs subscription returns [Log objects](../Reference/JSON-RPC-API-Objects.md#log-object).
|
|
|
|
!!!exemple
|
|
To subscribe to all logs notifications:
|
|
```json
|
|
{"id": 1, "method": "eth_subscribe", "params": ["logs",{}]}
|
|
```
|
|
To subscribe to logs for a specific address and topic:
|
|
```json
|
|
{"id": 1, "method": "eth_subscribe", "params": ["logs", {"address": "0x8320fe7702b96808f7bbc0d4a888ed1468216cfd", "topics": ["0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902"]}]}
|
|
```
|
|
|
|
Example result:
|
|
```json
|
|
{"jsonrpc":"2.0","id":1,"result":"0x2"}
|
|
```
|
|
Example notification:
|
|
```json
|
|
{
|
|
"jsonrpc":"2.0",
|
|
"method":"eth_subscription",
|
|
"params":{
|
|
"subscription":"0x2",
|
|
"result":{
|
|
"logIndex":"0x0",
|
|
"removed":false,
|
|
"blockNumber":"0x2174",
|
|
"blockHash":"0x7bc83837534aa13df55ff7db77784b1d1ba666d4c4bdd223cae9fe09c7c37eba",
|
|
"transactionHash":"0x942179373e413824c6bc7045e92295aff91b679215446549b4aeb084da46495b",
|
|
"transactionIndex":"0x0",
|
|
"address":"0x9b8397f1b0fecd3a1a40cdd5e8221fa461898517",
|
|
"data":"0x",
|
|
"topics":["0x199cd93e851e4c78c437891155e2112093f8f15394aa89dab09e38d6ca072787","0x0000000000000000000000000000000000000000000000000000000000000005"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Pending Transactions
|
|
|
|
Use the `newPendingTransactions` parameter with `eth_subscribe` to be notified of new pending transactions of which your node is aware.
|
|
|
|
The pending transactions subscription returns the transaction hashes of the pending transactions.
|
|
|
|
If a chain reorganization occurs, transactions are resubmitted to be included in the new canonical chain.
|
|
This means the subscription can publish notifications for the same pending transaction more than once.
|
|
|
|
!!!example
|
|
To subscribe to pending transaction notifications:
|
|
|
|
```json
|
|
{"id": 1, "method": "eth_subscribe", "params": ["newPendingTransactions"]}
|
|
```
|
|
|
|
Example result:
|
|
```json
|
|
{"jsonrpc":"2.0","id":1,"result":"0x1"}
|
|
```
|
|
|
|
|
|
Example notification:
|
|
```json
|
|
{
|
|
"jsonrpc":"2.0",
|
|
"method":"eth_subscription",
|
|
"params":{
|
|
"subscription":"0x1",
|
|
"result":"0x5705bc8bf875ff03e98adb98489428835892dc6ba6a6b139fee1becbc26db0b8"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Synchronizing
|
|
|
|
Use the `syncing` parameter with `eth_subscribe` to be notified about synchronization progress.
|
|
|
|
The sychronizing subscription either returns `false` indicating the synchronization has finished
|
|
or an `object` indicating the synchronization progress.
|
|
|
|
!!!example
|
|
To subscribe to synchronizing notifications:
|
|
```json
|
|
{"id": 1, "method": "eth_subscribe", "params": ["syncing"]}
|
|
```
|
|
|
|
Example result:
|
|
```json
|
|
{"jsonrpc":"2.0","id":1,"result":"0x4"}
|
|
```
|
|
|
|
Example notification:
|
|
|
|
```json
|
|
{
|
|
"jsonrpc":"2.0",
|
|
"method":"eth_subscription",
|
|
"params":{
|
|
"subscription":"0x4",
|
|
"result":{
|
|
"startingBlock":"0x0",
|
|
"currentBlock":"0x3e80",
|
|
"highestBlock":"0x67b93c"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Unsubscribing
|
|
|
|
Use the [subscription ID](#subscription-id) with `eth_unsubscribe` to cancel a subscription.
|
|
|
|
!!!example
|
|
To unsubscribe from a subsciption with subscription ID of `0x1`:
|
|
```json
|
|
{"id": 1, "method": "eth_unsubscribe", "params": ["0x1"]}
|
|
```
|
|
|
|
`eth_unsubscribe` returns `true` if subscription succuessfully unsubscribed; otherwise, an error is returned.
|
|
|
|
Example result:
|
|
```json
|
|
{"jsonrpc":"2.0","id":1,"result":true}
|
|
``` |