mirror of https://github.com/status-im/EIPs.git
Automatically merged updates to draft EIP(s) 758
Hi, I'm a bot! This change was automatically merged because: - It only modifies existing Draft or Last Call EIP(s) - The PR was approved or written by at least one author of each modified EIP - The build is passing
This commit is contained in:
Domino Valdano
EIP Automerge Bot
parent
ed621645c8
commit
0fe9ffabd6
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
eip: 758
|
||||
title: Subscriptions and filters for transaction return data
|
||||
title: Subscriptions and filters for completed transactions
|
||||
author: Jack Peterson <jack@tinybike.net>
|
||||
type: Standards Track
|
||||
category: Interface
|
||||
|
|
@ -9,30 +9,50 @@ created: 2017-11-09
|
|||
---
|
||||
|
||||
## Simple Summary
|
||||
Provide a way for external callers to access the return data of functions executed during Ethereum transactions.
|
||||
Provide a way for external callers to be notified of completed transactions, and access the return data of functions executed when a transaction is mined.
|
||||
|
||||
## Abstract
|
||||
When a new transaction is submitted successfully to an Ethereum node, the node responds with the transaction's hash. If the transaction involved the execution of a contract function that returns data, the data is discarded. If the return data is state-dependent, which is common, there is no straightforward way for the caller to access or compute the return data. This EIP proposes that callers should be able to subscribe to (or poll for) the return data of their transactions. The Ethereum node then sends the return data to the caller when the transactions are sealed.
|
||||
When a new transaction is submitted successfully to an Ethereum node, the node responds with the transaction's hash. If the transaction involved the execution of a contract function that returns data, the data is discarded. If the return data is state-dependent, which is common, there is no straightforward way for the caller to access or compute the return data. This EIP proposes that callers should be able to subscribe to (or poll for) completed transactions. The Ethereum node sends the return data to the caller when the transactions are sealed.
|
||||
|
||||
## Motivation
|
||||
External callers presently have no way of accessing return data from Ethereum, if the function was executed via `eth_sendTransaction` or `eth_sendRawTransaction` RPC request. Access to function return data is in many cases a desirable feature. Making return data available to external callers also addresses the inconsistency between internal callers, which have access to return data within the context of the transaction, and external callers, which do not. Presently, a common workaround is to log the return data, which is bad for several reasons: it contributes to chain bloat, imposes additional gas costs on the caller, and can result in unused logs being written if the externally called function involves other (internal) function calls that log their return data.
|
||||
External callers presently have no way of accessing return data from Ethereum, if the function was executed via `eth_sendTransaction` or `eth_sendRawTransaction` RPC request. Access to function return data is in many cases a desirable feature. Making return data available to external callers also addresses the inconsistency between internal callers, which have access to return data within the context of the transaction, and external callers, which do not. Presently, a common workaround is to log the return data, which is bad for several reasons: it contributes to chain bloat, imposes additional gas costs on the caller, and can result in unused logs being written if the externally called function involves other (internal) function calls that log their return data. While implementing the original version of this EIP, it was decided to expand this functionality slightly to allow for external callers to be notified of their completed transactions even in the case where there is *no* return data. This could be either because the method called doesn't return a value, or because the transaction is a simple transfer of value.
|
||||
|
||||
## Specification
|
||||
|
||||
### Subscription
|
||||
A caller who wants to be notified of return data for their transactions sends an `eth_subscribe` RPC request with the parameter `"returnData"`:
|
||||
A caller who wants to be notified when transactions of theirs complete sends an `eth_subscribe` RPC request with the first parameter `"completedTransaction"`:
|
||||
|
||||
```json
|
||||
{"jsonrpc": "2.0", "id": 1, "method": "eth_subscribe", "params": ["returnData"]}
|
||||
{"jsonrpc": "2.0", "id": 1, "method": "eth_subscribe", "params": ["completedTransaction", filter]}
|
||||
```
|
||||
|
||||
The Ethereum node responds with a subscription ID:
|
||||
The `filter` parameter is a dictionary containing 3 optional named arguments: `from`, `to`, and `hasReturnData`. `from` and `to` can each either be single addresses, or a list of addresses. They are used to filter out any transactions not sent from an address in the `from` list and sent to an address in the to list. `hasReturnData` is a boolean--if it is specified and `true`, then notifications will be received only for completed transactions containing returnData.
|
||||
|
||||
For example, to restrict results to contract creations originating from either of two addresses (0x3f7d39bDBf1f5cE649c194571aEd3D2BbB2F85ce or 0x7097f41F1C1847D52407C629d0E0ae0fDD24fd58):
|
||||
|
||||
```json
|
||||
filter = { "from" : ["0x3f7d39bDBf1f5cE649c194571aEd3D2BbB2F85ce",
|
||||
"0x7097f41F1C1847D52407C629d0E0ae0fDD24fd58"],
|
||||
"to" : "0x0"
|
||||
}
|
||||
```
|
||||
|
||||
To restrict results to method calls on contract address 0xD9Cb531aB97A652c8fC60dcF6D263fcA2F5764e9:
|
||||
```json
|
||||
filter = { "to" : "0xD9Cb531aB97A652c8fC60dcF6D263fcA2F5764e9", "hasReturnData" : true }
|
||||
```
|
||||
Or to be notified of any transactions submitted by this rpc client when they complete, with no further restrictions:
|
||||
```json
|
||||
filter = {}
|
||||
```
|
||||
|
||||
After the request is recieved, the Ethereum node responds with a subscription ID:
|
||||
|
||||
```json
|
||||
{"jsonrpc": "2.0", "id": 1, "result": "0x00000000000000000000000000000b0b"}
|
||||
```
|
||||
|
||||
The caller submits a transaction via `eth_sendTransaction` or `eth_sendRawTransaction` RPC request which has the transaction hash `"0x00000000000000000000000000000000000000000000000000000000deadbeef"`. When the transaction is sealed (mined), the Ethereum node computes the return value (`"0x000000000000000000000000000000000000000000000000000000000000002a"`) and pushes a notification to the caller:
|
||||
Suppose the caller then submits a transaction via `eth_sendTransaction` or `eth_sendRawTransaction` RPC request which has the transaction hash `"0x00000000000000000000000000000000000000000000000000000000deadbeef"`. When the transaction is sealed (mined), the Ethereum node pushes a notification to the caller. If the transaction is a method call on a contract, this will include the return value (eg. `"0x000000000000000000000000000000000000000000000000000000000000002a"`) of the called function:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -48,17 +68,17 @@ The caller submits a transaction via `eth_sendTransaction` or `eth_sendRawTransa
|
|||
}
|
||||
```
|
||||
|
||||
The caller receives notifications about their transactions' return data in two cases: first when a transaction is sealed, and again (with an extra `"removed": true` field) if a transaction is affected by a chain reorganization. Notifications are sent to the client for all transactions submitted from the client that are sealed _after_ subscribing. As with other subscriptions, the caller can send an `eth_unsubscribe` RPC request to stop receiving push notifications:
|
||||
The caller receives notifications about their transactions in two cases: first when a transaction is sealed, and again (with an extra `"removed": true` field) if a transaction is affected by a chain reorganization. Notifications are sent to the client for all transactions submitted from the client that are sealed _after_ subscribing. If `from`, `to`, or `hasReturnData` is specified, then only those matching the filter criteria will generate notificaitons. As with other subscriptions, the caller can send an `eth_unsubscribe` RPC request to stop receiving push notifications:
|
||||
|
||||
```json
|
||||
{"jsonrpc": "2.0", "id": 2, "method": "eth_unsubscribe", "params": ["0x00000000000000000000000000000b0b"]}
|
||||
```
|
||||
|
||||
### Polling
|
||||
Push notifications require full duplex connections (i.e., websocket or IPC). Instead of subscribing, callers using HTTP send an `eth_newReturnDataFilter` request:
|
||||
Push notifications require full duplex connections (i.e., websocket or IPC). Instead of subscribing, callers using HTTP send an `eth_newCompletedTransactionFilter` request:
|
||||
|
||||
```json
|
||||
{"jsonrpc": "2.0", "id": 1, "method": "eth_newReturnDataFilter"}
|
||||
{"jsonrpc": "2.0", "id": 1, "method": "eth_newCompletedTransactionFilter", "params": [filter] }
|
||||
```
|
||||
|
||||
The Ethereum node responds with a filter ID:
|
||||
|
|
@ -67,7 +87,7 @@ The Ethereum node responds with a filter ID:
|
|||
{"jsonrpc": "2.0", "id": 1, "result": "0x1"}
|
||||
```
|
||||
|
||||
When a transaction is submitted, the Ethereum node computes the return data and pushes it to a queue, which is emptied when the caller polls using `eth_getFilterChanges`:
|
||||
When a transaction is submitted, the Ethereum node pushes the transaction notification, including return value, into a queue which is emptied when the caller polls using `eth_getFilterChanges`:
|
||||
|
||||
```json
|
||||
{"jsonrpc": "2.0", "id": 2, "method": "eth_getFilterChanges", "params": ["0x1"]}
|
||||
|
|
@ -86,7 +106,7 @@ The node responds with an array of transaction hashes and their corresponding re
|
|||
}
|
||||
```
|
||||
|
||||
All transactions submitted by the client that were sealed _after_ the initial `eth_newReturnDataFilter` request are included in this array.
|
||||
All transactions that were sealed _after_ the initial `eth_newCompletedTransactionFilter` request are included in this array. Again, if the `filter` param is a non-empty dictinary (contains either `from`, `to`, or `hasReturnData`) then only transactions matching the filter criteria generate notifications. Note that in the polling case, there is no way for the Ethereum node to be sure that an RPC client which submits a transaction was the same as the one who created the filter, so there is no restriction based on where the transaction was submitted.
|
||||
|
||||
|
||||
## Rationale
|
||||
|
|
|
|||
Loading…
Reference in New Issue