EIPs/EIPS/eip-758.md

eip	title	author	type	category	status	created
758	Subscriptions and filters for transaction return data	Jack Peterson <jack@tinybike.net>	Standards Track	Interface	Draft	2017-11-09

Simple Summary

Provide a way for external callers to access the return data of functions executed during Ethereum transactions.

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.

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.

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":

{"jsonrpc": "2.0", "id": 1, "method": "eth_subscribe", "params": ["returnData"]}

The Ethereum node responds with a subscription ID:

{"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:

{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "result": {
      "transactionHash": "0x00000000000000000000000000000000000000000000000000000000deadbeef",
      "returnData": "0x000000000000000000000000000000000000000000000000000000000000002a"
    },
    "subscription": "0x00000000000000000000000000000b0b"
  }
}

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:

{"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_newFilter request:

{"jsonrpc": "2.0", "id": 1, "method": "eth_newFilter", "params": ["returnData"]}

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:

{"jsonrpc": "2.0", "id": 2, "method": "eth_getFilterChanges", "params": ["0x1"]}

The node responds with an array of transaction hashes and their corresponding return data, in the order they were computed:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": [{
    "transactionHash": "0x00000000000000000000000000000000000000000000000000000000deadbeef",
    "returnData": "0x000000000000000000000000000000000000000000000000000000000000002a"
  }]
}

All transactions submitted by the client that were sealed after the initial eth_newFilter request are included in this array.

Rationale

EIP 658 originally proposed adding return data to transaction receipts. However, return data is not charged for (as it is not stored on the blockchain), so adding it to transaction receipts could result in DoS and spam opportunities. Instead, a simple Boolean status field was added to transaction receipts. This modified version of EIP 658 was included in the Byzantium hard fork. While the status field is useful, applications often need the return data as well.

The primary advantage of using the strategy outlined here is efficiency: no extra data needs to be stored on the blockchain, and minimal extra computational load is imposed on nodes. Although after-the-fact lookups of the return value would not be supported, this is consistent with the conventional use of return data, which are only accessible to the caller when the function returns, and are not stored for later use.

Copyright

Copyright and related rights waived via CC0.