145 lines
8.0 KiB
Markdown
145 lines
8.0 KiB
Markdown
|
---
|
||
|
|
title: RPS pub-sub
|
||
|
|
---
|
||
|
|
# Introduction
|
||
|
|
|
||
|
|
From version 1.4 geth has **_experimental_** support for pub/sub using subscriptions as defined in the JSON-RPC 2.0 specification. This allows clients to wait for events instead of polling for them.
|
||
|
|
|
||
|
|
It works by subscribing to particular events. The node will return a subscription id. For each event that matches the subscription a notification with relevant data is send together with the subscription id.
|
||
|
|
|
||
|
|
Example:
|
||
|
|
|
||
|
|
// create subscription
|
||
|
|
>> {"id": 1, "method": "eth_subscribe", "params": ["newHeads", {}]}
|
||
|
|
<< {"jsonrpc":"2.0","id":1,"result":"0xcd0c3e8af590364c09d0fa6a1210faf5"}
|
||
|
|
|
||
|
|
// incoming notifications
|
||
|
|
<< {"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0xcd0c3e8af590364c09d0fa6a1210faf5","result":{"difficulty":"0xd9263f42a87",<...>, "uncles":[]}}}
|
||
|
|
<< {"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0xcd0c3e8af590364c09d0fa6a1210faf5","result":{"difficulty":"0xd90b1a7ad02", <...>, "uncles":["0x80aacd1ea4c9da32efd8c2cc9ab38f8f70578fcd46a1a4ed73f82f3e0957f936"]}}}
|
||
|
|
|
||
|
|
// cancel subscription
|
||
|
|
>> {"id": 1, "method": "eth_unsubscribe", "params": ["0xcd0c3e8af590364c09d0fa6a1210faf5"]}
|
||
|
|
<< {"jsonrpc":"2.0","id":1,"result":true}
|
||
|
|
|
||
|
|
# Considerations
|
||
|
|
1. notifications are send for current events and not for past events. If your use case requires you not to miss any notifications than subscriptions are probably not the best option.
|
||
|
|
2. subscriptions require a full duplex connection. Geth offers such connections in the form of websockets (enable with --ws) and ipc (enabled by default).
|
||
|
|
3. subscriptions are coupled to a connection. If the connection is closed all subscriptions that are created over this connection are removed.
|
||
|
|
4. notifications are stored in an internal buffer and sent from this buffer to the client. If the client is unable to keep up and the number of buffered notifications reaches a limit (currently 10k) the connection is closed. Keep in mind that subscribing to some events can cause a flood of notifications, e.g. listening for all logs/blocks when the node starts to synchronize.
|
||
|
|
|
||
|
|
## Create subscription
|
||
|
|
Subscriptions are creates with a regular RPC call with `eth_subscribe` as method and the subscription name as first parameter. If successful it returns the subscription id.
|
||
|
|
|
||
|
|
### Parameters
|
||
|
|
1. subscription name
|
||
|
|
2. optional arguments
|
||
|
|
|
||
|
|
### Example
|
||
|
|
|
||
|
|
>> {"id": 1, "method": "eth_subscribe", "params": ["newHeads", {"includeTransactions": true}]}
|
||
|
|
<< {"id": 1, "jsonrpc": "2.0", "result": "0x9cef478923ff08bf67fde6c64013158d"}
|
||
|
|
|
||
|
|
## Cancel subscription
|
||
|
|
Subscriptions are cancelled with a regular RPC call with `eth_unsubscribe` as method and the subscription id as first parameter. It returns a bool indicating if the subscription was cancelled successful.
|
||
|
|
|
||
|
|
### Parameters
|
||
|
|
1. subscription id
|
||
|
|
|
||
|
|
### Example
|
||
|
|
|
||
|
|
>> {"id": 1, "method": "eth_unsubscribe", "params": ["0x9cef478923ff08bf67fde6c64013158d"]}
|
||
|
|
<< {"jsonrpc":"2.0","id":1,"result":true}
|
||
|
|
|
||
|
|
# Supported subscriptions
|
||
|
|
|
||
|
|
## newHeads
|
||
|
|
Fires a notification each time a new header is appended to the chain, including chain reorganizations. Users can use the bloom filter to determine if the block contains logs that are interested to them.
|
||
|
|
|
||
|
|
In case of a chain reorganization the subscription will emit all new headers for the new chain. Therefore the subscription can emit multiple headers on the same height.
|
||
|
|
|
||
|
|
### Example
|
||
|
|
```
|
||
|
|
>> {"id": 1, "method": "eth_subscribe", "params": ["newHeads"]}
|
||
|
|
<< {"jsonrpc":"2.0","id":2,"result":"0x9ce59a13059e417087c02d3236a0b1cc"}
|
||
|
|
|
||
|
|
<< {
|
||
|
|
"jsonrpc": "2.0",
|
||
|
|
"method": "eth_subscription",
|
||
|
|
"params": {
|
||
|
|
"result": {
|
||
|
|
"difficulty": "0x15d9223a23aa",
|
||
|
|
"extraData": "0xd983010305844765746887676f312e342e328777696e646f7773",
|
||
|
|
"gasLimit": "0x47e7c4",
|
||
|
|
"gasUsed": "0x38658",
|
||
|
|
"logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
|
||
|
|
"miner": "0xf8b483dba2c3b7176a3da549ad41a48bb3121069",
|
||
|
|
"nonce": "0x084149998194cc5f",
|
||
|
|
"number": "0x1348c9",
|
||
|
|
"parentHash": "0x7736fab79e05dc611604d22470dadad26f56fe494421b5b333de816ce1f25701",
|
||
|
|
"receiptRoot": "0x2fab35823ad00c7bb388595cb46652fe7886e00660a01e867824d3dceb1c8d36",
|
||
|
|
"sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
|
||
|
|
"stateRoot": "0xb3346685172db67de536d8765c43c31009d0eb3bd9c501c9be3229203f15f378",
|
||
|
|
"timestamp": "0x56ffeff8",
|
||
|
|
"transactionsRoot": "0x0167ffa60e3ebc0b080cdb95f7c0087dd6c0e61413140e39d94d3468d7c9689f"
|
||
|
|
},
|
||
|
|
"subscription": "0x9ce59a13059e417087c02d3236a0b1cc"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## logs
|
||
|
|
Returns logs that are included in new imported blocks and match the given filter criteria.
|
||
|
|
|
||
|
|
In case of a chain reorganization previous sent logs that are on the old chain will be resend with the `removed` property set to true. Logs from transactions that ended up in the new chain are emitted. Therefore a subscription can emit logs for the same transaction multiple times.
|
||
|
|
|
||
|
|
### Parameters
|
||
|
|
1. `object` with the following (optional) fields
|
||
|
|
- **address**, either an address or an array of addresses. Only logs that are created from these addresses are returned (optional)
|
||
|
|
- **topics**, only logs which match the specified topics (optional)
|
||
|
|
|
||
|
|
|
||
|
|
### Example
|
||
|
|
>> {"id": 1, "method": "eth_subscribe", "params": ["logs", {"address": "0x8320fe7702b96808f7bbc0d4a888ed1468216cfd", "topics": ["0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902"]}]}
|
||
|
|
<< {"jsonrpc":"2.0","id":2,"result":"0x4a8a4c0517381924f9838102c5a4dcb7"}
|
||
|
|
|
||
|
|
<< {"jsonrpc":"2.0","method":"eth_subscription","params": {"subscription":"0x4a8a4c0517381924f9838102c5a4dcb7","result":{"address":"0x8320fe7702b96808f7bbc0d4a888ed1468216cfd","blockHash":"0x61cdb2a09ab99abf791d474f20c2ea89bf8de2923a2d42bb49944c8c993cbf04","blockNumber":"0x29e87","data":"0x00000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000003","logIndex":"0x0","topics":["0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902"],"transactionHash":"0xe044554a0a55067caafd07f8020ab9f2af60bdfe337e395ecd84b4877a3d1ab4","transactionIndex":"0x0"}}}
|
||
|
|
|
||
|
|
## newPendingTransactions
|
||
|
|
Returns the hash for all transactions that are added to the pending state and are signed with a key that is available in the node.
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
### Parameters
|
||
|
|
none
|
||
|
|
|
||
|
|
### Example
|
||
|
|
>> {"id": 1, "method": "eth_subscribe", "params": ["newPendingTransactions"]}
|
||
|
|
<< {"jsonrpc":"2.0","id":2,"result":"0xc3b33aa549fb9a60e95d21862596617c"}
|
||
|
|
|
||
|
|
<< {
|
||
|
|
"jsonrpc":"2.0",
|
||
|
|
"method":"eth_subscription",
|
||
|
|
"params":{
|
||
|
|
"subscription":"0xc3b33aa549fb9a60e95d21862596617c",
|
||
|
|
"result":"0xd6fdc5cc41a9959e922f30cb772a9aef46f4daea279307bc5f7024edc4ccd7fa"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
|
||
|
|
## syncing
|
||
|
|
Indicates when the node starts or stops synchronizing. The result can either be a boolean indicating that the synchronization has started (true), finished (false) or an object with various progress indicators.
|
||
|
|
|
||
|
|
### Parameters
|
||
|
|
none
|
||
|
|
|
||
|
|
### Example
|
||
|
|
>> {"id": 1, "method": "eth_subscribe", "params": ["syncing"]}
|
||
|
|
<< {"jsonrpc":"2.0","id":2,"result":"0xe2ffeb2703bcf602d42922385829ce96"}
|
||
|
|
|
||
|
|
<< {"subscription":"0xe2ffeb2703bcf602d42922385829ce96","result":{"syncing":true,"status":{"startingBlock":674427,"currentBlock":67400,"highestBlock":674432,"pulledStates":0,"knownStates":0}}}}
|
||
|
|
|
||
|
|
|
||
|
|
## Possible future subscription:
|
||
|
|
- balance changes
|
||
|
|
- account changes
|
||
|
|
- nonce changes
|
||
|
|
- storage changes in contracts
|