================== Websockets RPC API ================== Websockets Introduction ======================= The Websockets RPC API supports all of the RPC methods provided by the standard JSON RPC API, with several additional methods that require a persistent connection. This page only documents the RPC methods exclusive to the websockets API. eth_newFilter ^^^^^^^^^^^^^ Creates a filter object, based on filter options, to notify when the state changes (logs). To check if the state has changed, call `eth_getFilterChanges <#eth_getfilterchanges>`__. .. note:: Topics are order-dependent. A transaction with a log with topics [A, B] will be matched by the following topic filters: \* ``[]`` “anything” \* ``[A]`` “A in first position (and anything after)” \* ``[null, B]`` “anything in first position AND B in second position (and anything after)” \* ``[A, B]`` “A in first position AND B in second position (and anything after)” \* ``[[A, B], [A, B]]`` “(A OR B) in first position AND (A OR B) in second position (and anything after)” .. _parameters-33: Parameters '''''''''' 1. ``Object`` - The filter options: - ``fromBlock``: ``QUANTITY|TAG`` - (optional, default: ``"latest"``) Integer block number, or ``"latest"`` for the last mined block or ``"pending"``, ``"earliest"`` for not yet mined transactions. - ``toBlock``: ``QUANTITY|TAG`` - (optional, default: ``"latest"``) Integer block number, or ``"latest"`` for the last mined block or ``"pending"``, ``"earliest"`` for not yet mined transactions. - ``address``: ``DATA|Array``, 20 Bytes - (optional) Contract address or a list of addresses from which logs should originate. - ``topics``: ``Array of DATA``, - (optional) Array of 32 Bytes ``DATA`` topics. Topics are order-dependent. Each topic can also be an array of DATA with “or” options. .. _example-parameters-15: Example Parameters '''''''''''''''''' .. code-block:: js params: [{ "fromBlock": "0x1", "toBlock": "0x2", "address": "0x8888f1f195afa192cfee860698584c030f4c9db1", "topics": ["0x000000000000000000000000a94f5374fce5edbc8e2a8697c15331677e6ebf0b", null, ["0x000000000000000000000000a94f5374fce5edbc8e2a8697c15331677e6ebf0b", "0x0000000000000000000000000aff3454fce5edbc8cca8697c15331677e6ebccc"]] }] .. _returns-33: Returns ''''''' ``QUANTITY`` - A filter id. .. _example-33: Example ''''''' .. code-block:: js // Request >>> '{"jsonrpc":"2.0","method":"eth_newFilter","params":[{"topics":["0x0000000000000000000000000000000000000000000000000000000012341234"]}],"id":73}' // Result <<< { "id":1, "jsonrpc": "2.0", "result": "0x1" // 1 } -------------- eth_newBlockFilter ^^^^^^^^^^^^^^^^^^ Creates a filter in the node, to notify when a new block arrives. To check if the state has changed, call `eth_getFilterChanges <#eth_getfilterchanges>`__. .. _parameters-34: Parameters '''''''''' None .. _returns-34: Returns ''''''' ``QUANTITY`` - A filter id. .. _example-34: Example ''''''' .. code-block:: js // Request >>> '{"jsonrpc":"2.0","method":"eth_newBlockFilter","params":[],"id":73}' // Result <<< { "id":1, "jsonrpc": "2.0", "result": "0x1" // 1 } -------------- eth_newPendingTransactionFilter ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Creates a filter in the node, to notify when new pending transactions arrive. To check if the state has changed, call `eth_getFilterChanges <#eth_getfilterchanges>`__. .. _parameters-35: Parameters '''''''''' None .. _returns-35: Returns ''''''' ``QUANTITY`` - A filter id. .. _example-35: Example ''''''' .. code-block:: js // Request >>> '{"jsonrpc":"2.0","method":"eth_newPendingTransactionFilter","params":[],"id":73}' // Result <<< { "id":1, "jsonrpc": "2.0", "result": "0x1" // 1 } -------------- eth_uninstallFilter ^^^^^^^^^^^^^^^^^^^ Uninstalls a filter with given id. Should always be called when watch is no longer needed. Additonally Filters timeout when they aren’t requested with `eth_getFilterChanges <#eth_getfilterchanges>`__ for a period of time. .. _parameters-36: Parameters '''''''''' 1. ``QUANTITY`` - The filter id. .. _example-parameters-16: Example Parameters '''''''''''''''''' .. code-block:: js params: [ "0xb" // 11 ] .. _returns-36: Returns ''''''' ``Boolean`` - ``true`` if the filter was successfully uninstalled, otherwise ``false``. .. _example-36: Example ''''''' .. code-block:: js // Request >>> '{"jsonrpc":"2.0","method":"eth_uninstallFilter","params":["0xb"],"id":73}' // Result <<< { "id":1, "jsonrpc": "2.0", "result": true } -------------- eth_getFilterChanges ^^^^^^^^^^^^^^^^^^^^ Polling method for a filter, which returns an array of logs which occurred since last poll. .. _parameters-37: Parameters '''''''''' 1. ``QUANTITY`` - the filter id. .. _example-parameters-17: Example Parameters '''''''''''''''''' .. code-block:: js params: [ "0x16" // 22 ] .. _returns-37: Returns ''''''' ``Array`` - Array of log objects, or an empty array if nothing has changed since last poll. - For filters created with ``eth_newBlockFilter`` the return are block hashes (``DATA``, 32 Bytes), e.g. \ ``["0x3454645634534..."]``. - For filters created with ``eth_newPendingTransactionFilter`` the return are transaction hashes (``DATA``, 32 Bytes), e.g. \ ``["0x6345343454645..."]``. - For filters created with ``eth_newFilter`` logs are objects with following params: - ``removed``: ``TAG`` - ``true`` when the log was removed, due to a chain reorganization. ``false`` if its a valid log. - ``logIndex``: ``QUANTITY`` - integer of the log index position in the block. ``null`` when its pending log. - ``transactionIndex``: ``QUANTITY`` - integer of the transactions index position log was created from. ``null`` when its pending log. - ``transactionHash``: ``DATA``, 32 Bytes - hash of the transactions this log was created from. ``null`` when its pending log. - ``blockHash``: ``DATA``, 32 Bytes - hash of the block where this log was in. ``null`` when its pending. ``null`` when its pending log. - ``blockNumber``: ``QUANTITY`` - the block number where this log was in. ``null`` when its pending. ``null`` when its pending log. - ``address``: ``DATA``, 20 Bytes - address from which this log originated. - ``data``: ``DATA`` - contains the non-indexed arguments of the log. - ``topics``: ``Array of DATA`` - Array of 0 to 4 32 Bytes ``DATA`` of indexed log arguments. (In *solidity*: The first topic is the *hash* of the signature of the event (e.g. ``Deposit(address,bytes32,uint256)``), except you declared the event with the ``anonymous`` specifier.) .. _example-37: Example ''''''' .. code-block:: js // Request >>> '{"jsonrpc":"2.0","method":"eth_getFilterChanges","params":["0x16"],"id":73}' // Result <<< { "id":1, "jsonrpc":"2.0", "result": [{ "logIndex": "0x1", // 1 "blockNumber":"0x1b4", // 436 "blockHash": "0x8216c5785ac562ff41e2dcfdf5785ac562ff41e2dcfdf829c5a142f1fccd7d", "transactionHash": "0xdf829c5a142f1fccd7d8216c5785ac562ff41e2dcfdf5785ac562ff41e2dcf", "transactionIndex": "0x0", // 0 "address": "0x16c5785ac562ff41e2dcfdf829c5a142f1fccd7d", "data":"0x0000000000000000000000000000000000000000000000000000000000000000", "topics": ["0x59ebeb90bc63057b6515673c3ecf9438e5058bca0f92585014eced636878c9a5"] },{ ... }] } -------------- eth_getFilterLogs ^^^^^^^^^^^^^^^^^ Returns an array of all logs matching filter with given id. .. _parameters-38: Parameters '''''''''' 1. ``QUANTITY`` - The filter id. .. _example-parameters-18: Example Parameters '''''''''''''''''' .. code-block:: js params: [ "0x16" // 22 ] .. _returns-38: Returns ''''''' See `eth_getFilterChanges <#eth_getfilterchanges>`__ .. _example-38: Example ''''''' .. code-block:: js // Request >>> '{"jsonrpc":"2.0","method":"eth_getFilterLogs","params":["0x16"],"id":74}' Result see `eth_getFilterChanges <#eth_getfilterchanges>`__ -------------- Subscriptions ============= Geth supports 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} .. note:: 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. 5. within Rivet, you will be billed one request for every item served to you for a subscription. 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-40: Parameters '''''''''' 1. subscription name 2. optional arguments .. _example-40: Example ~~~~~~~ :: >> {"id": 1, "method": "eth_subscribe", "params": ["newHeads"]} << {"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-41: Parameters '''''''''' 1. subscription id .. _example-41: Example ~~~~~~~ :: >> {"id": 1, "method": "eth_unsubscribe", "params": ["0x9cef478923ff08bf67fde6c64013158d"]} << {"jsonrpc":"2.0","id":1,"result":true} 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-42: 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-42: 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-43: 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-43: Parameters '''''''''' none .. _example-44: 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-44: Parameters '''''''''' none .. _example-45: 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}}}} Rivet custom Subscriptions ========================== Rivet has some custom subscriptions to allow you to subscribe to data not available through the standard Web3 RPC Subscriptions. filteredPendingTransactions ^^^^^^^^^^^^^^^^^^^^^^^^^^^ Subscribing to newPendingTransactions provides the transaction hash of every new transaction, but this tells you very little about the transaction itself, and does not allow you to filter for transactions of interest to your application. Rivet’s filteredPendingTransactions gives you access to the full transaction, and allows you to filter for pending transactions of interest to you. .. _parameters-45: Parameters '''''''''' - criteria - hash: A list of transaction hashes you want to be notified when it is introduced the the transaction pool - from: A list of addresses you wish to be notified when they send transactions to the pool - to: A list of addresses you wish to be notified when a new transaction is sent to them - nonce: A list of nonces for transactions. This would usually be used in conjunction with ‘to’, perhaps to watch for replacement transactions .. _example-46: Example ~~~~~~~ :: >> {"id": 1, "method": "eth_subscribe", "params": ["filteredPendingTransactions", {}]} << {"jsonrpc":"2.0","id":1,"result":"0x1"} << {"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0x1","result":{"nonce":"0x1","gasPrice":"0x77359400","gas":"0x5208","to":"0x789c19ef373353e445165f26ca948939d64e3208","value":"0x2f4b318740000","input":"0x","v":"0x26","r":"0xa9bbc5ac3ef8d3d38c0c0e6a01a744d510882340680af16d79e18ba7b14a956e","s":"0x60141a5dbd43ce863f38ad52be290cee7abc391de7dccee2e162e91ffb15c419","hash":"0xe66d08be726dce470d0c00d46c39260a66a691c5550b0830e02af22b931e4c17"}}} << "jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0x1","result":{"nonce":"0xa4a","gasPrice":"0x3b9aca00","gas":"0x30d40","to":"0xac9bb427953ac7fddc562adca86cf42d988047fd","value":"0x0","input":"0xa9059cbb000000000000000000000000ad38af2762f8a210d8eb1c8cdd15a505b7a88e990000000000000000000000000000000000000000000000000de0b6b3a7640000","v":"0x25","r":"0xa8ba37f1c2200bf8b32d7e151a66c3f8a0645b4f8dae0252a46813ca76c53a","s":"0x52e5a0f61ca956cdd5665e10a7ff58caeb54e74602c9139597666cbfdadbee50","hash":"0xa9c115a4040927e04c8cef74899fa8aa62709ce96421a1fec87cf17b10d64cf1"}}} .. _example-2-1: Example 2 ~~~~~~~~~ :: >> {"id": 1, "method": "eth_subscribe", "params": ["filteredPendingTransactions", {"nonce": ["0x1"]}]} << {"jsonrpc":"2.0","id":1,"result":"0x1"} << {"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0x1","result":{"nonce":"0x1","gasPrice":"0x77359400","gas":"0x5208","to":"0x789c19ef373353e445165f26ca948939d64e3208","value":"0x2f4b318740000","input":"0x","v":"0x26","r":"0xa9bbc5ac3ef8d3d38c0c0e6a01a744d510882340680af16d79e18ba7b14a956e","s":"0x60141a5dbd43ce863f38ad52be290cee7abc391de7dccee2e162e91ffb15c419","hash":"0xe66d08be726dce470d0c00d46c39260a66a691c5550b0830e02af22b931e4c17"}}}