ethereum / ethereum/execution-apis

JSONRPC: Transaction receipt subscription

Open
#611 1 comment 1 reaction 0 assignees View on GitHub
Dominant language
Io
Stars
1.1k
Forks
530
Avg merge
5d 8h
Merged PRs (30d)
9

Description

### Motivation
___
As a Dapp/Wallet, the way to be notified of a block inclusion of a transaction are as follows:

1. Use private non-standard subscription method https://docs.alchemy.com/reference/alchemy-minedtransactions
2. Polling mechanism of eth_getTransactionReceipt(txHash)

But
1. It is not great for a Dapp/Wallet to use a proprietary API, whereas the open standard RPC interface is more reliable.
2. L1 and L2s have significantly different throughputs; ideally, a different polling mechanism should be put in place for each network, but that is not a great developer experience to maintain this configuration. In addition, some RPC endpoints, like public endpoints, do not well support fast polling due to a low rate limit.

Instead, the open specification should propose a push mechanism for a mature user and developer experience for transaction inclusion notification

### Websocket specification
___

Parameters:

1. `transactionReceipts`
2. `object`
2.a. `addresses`: list of addresses to filter transaction receipts by `to` or `from`
2.b. `includeRemoved` (optional): boolean specifier to include transactions that have been removed from the cannonical chain (or re-orged).

```json
{
"jsonrpc": "2.0",
"method": "eth_subscribe",
"params": [
"transactionReceipts",
{
"addresses": [
{
"to": "0x9f3ce0ad29b767d809642a53c2bccc9a130659d7",
"from": "0x228f108fd09450d083bb33fe0cc50ae449bc7e11"
},
{
"from": "0x1be82f08385faf6d00f88935c236497f94daa06f"
}
],
"includeRemoved": false,
}
],
"id": 1
}
```

eth_subscribe response:
1. `subscription id`

```json
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x9ce59a13059e417087c02d3236a0b1cc"
}
```

Notification Response:
1. `subscription id`
2. `result`
2.a. `blockHash`: 32 bytes. Hash of the block including this transaction
2.b. `blockNumber`: Block number including this transaction.
2.c. `transactionIndex`: Hexadecimal of the transaction's index position in the block.
2.d. `transactionHash`: 32 bytes. The hash of the transaction.
2.e. `from`: The address of the sender.
2.f. `to`: 20 bytes. The address of the receiver. null when the transaction is a contract creation transaction.
2.g. `cumulativeGasUsed`: The total amount of gas used when this transaction was executed in the block.
2.h. `gasUsed`: The amount of gas used by this specific transaction alone.
2.i. `contractAddress`: 20 bytes. The contract address created if the transaction was a contract creation, otherwise null.
2.j. `logs`: (Array) An array of log objects generated by this transaction.
2.k. `logsBloom`: 256 bytes. Bloom filter for light clients to quickly retrieve related logs.
2.l. `status`: Either 1 (success) or 0 (failure)
2.m. `effectiveGasPrice`: The actual value per gas deducted from the sender's account. Before [EIP-1559](https://docs.metamask.io/services/concepts/transaction-types/#eip-1559-transactions), equal to the gas price.
2.n. `type`: the [transaction type](https://docs.metamask.io/services/concepts/transaction-types/).

```json
{
"jsonrpc": "2.0",
"method": "eth_subscription",
"params": {
"subscription": "0x9ce59a13059e417087c02d3236a0b1cc",
"result": {
"blockHash": "0x66103840578be3bc9c865e0961c4a4de31b5df7a45dcd13ffe2679ff9c7315d8",
"blockNumber": "0x10023ee",
"contractAddress": null,
"cumulativeGasUsed": "0x9dd8f4",
"effectiveGasPrice": "0x95792911f",
"from": "0x1be82f08385faf6d00f88935c236497f94daa06f",
"gasUsed": "0x4a328",
"logs": [
{
"address": "0x000000000022d473030f116ddee9f6b43ac78ba3",
"topics": [
"0xc6a377bfc4eb120024a8ac08eef205be16b817020812c73223e81d1bdb9708ec",
"0x0000000000000000000000001be82f08385faf6d00f88935c236497f94daa06f",
"0x00000000000000000000000034103e1190b824a44c6a638438d425cba21143ba",
"0x000000000000000000000000ef1c6e67703c7bd7107eed8303fbe6ec2554bf6b"
],
"data": "0x000000000000000000000000ffffffffffffffffffffffffffffffffffffffff000000000000000000000000000000000000000000000000000000006430932d0000000000000000000000000000000000000000000000000000000000000000",
"blockNumber": "0x10023ee",
"transactionHash": "0xf033310487c37a86db8099a738ffa2bb62bb06efeb486a65ff595d411b5321f4",
"transactionIndex": "0x63",
"blockHash": "0x66103840578be3bc9c865e0961c4a4de31b5df7a45dcd13ffe2679ff9c7315d8",
"logIndex": "0xda",
"removed": false
},
[...]
{
"address": "0x1417be63afec8d175c2dc8a691fca1a898bc5b8d",
"topics": [
"0xd78ad95fa46c994b6551d0da85fc275fe613ce37657fb8d5e3d130840159d822",
"0x000000000000000000000000ef1c6e67703c7bd7107eed8303fbe6ec2554bf6b",
"0x0000000000000000000000001be82f08385faf6d00f88935c236497f94daa06f"
],
"data": "0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000c81b15967b79f200000000000000000000000000000000000000000000001920aa875deb611cad0000000000000000000000000000000000000000000000000000000000000000",
"blockNumber": "0x10023ee",
"transactionHash": "0xf033310487c37a86db8099a738ffa2bb62bb06efeb486a65ff595d411b5321f4",
"transactionIndex": "0x63",
"blockHash": "0x66103840578be3bc9c865e0961c4a4de31b5df7a45dcd13ffe2679ff9c7315d8",
"logIndex": "0xe5",
"removed": false
}
],
"logsBloom": "0x00210000000000000002004080000000000000080000000000008100000000000000000000000000010000000000000402010000880000000000000000280000000000000080000000004008000000200000000000000800000084000000000000000200000000000000000000000000002000100800000000000010000000000000004000000000000000080000000100000000000000080000004000000800021800000000010000000000000000000401000000000000000000000000000000004022000000000000400000000014400200000000001000000000000000800010200000000000000000100000000000000800000000000000000080000400",
"status": "0x1",
"to": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"transactionHash": "0xf033310487c37a86db8099a738ffa2bb62bb06efeb486a65ff595d411b5321f4",
"transactionIndex": "0x63",
"type": "0x2"
}
}
}
```

### HTTP filter subscription specification
___

Parameters:

1. `object`
1.a. `addresses`: list of addresses to filter transaction receipts by `to` or `from`
1.b. `includeRemoved` (optional): boolean specifier to include transactions that have been removed from the cannonical chain (or re-orged).

```json
{
"jsonrpc": "2.0",
"method": "eth_newTransactionReceiptFilter",
"params": [
{
"addresses": [
{
"to": "0x9f3ce0ad29b767d809642a53c2bccc9a130659d7",
"from": "0x228f108fd09450d083bb33fe0cc50ae449bc7e11"
},
{
"from": "0x1be82f08385faf6d00f88935c236497f94daa06f"
}
],
"includeRemoved": false,
}
],
"id": 1
}
```

eth_subscribe response:
1. `subscription id`

```json
{
"jsonrpc": "2.0",
"id": 1,
"result": "0x9ce59a13059e417087c02d3236a0b1cc"
}
```

eth_getFilterChanges response:

```json
{
"jsonrpc": "2.0",
"method": "eth_getFilterChanges,
"params": ["0x9ce59a13059e417087c02d3236a0b1cc"],
"id": 1
}
>>>
{
"jsonrpc": "2.0",
"result": [
{
"blockHash": "0x66103840578be3bc9c865e0961c4a4de31b5df7a45dcd13ffe2679ff9c7315d8",
"blockNumber": "0x10023ee",
"contractAddress": null,
"cumulativeGasUsed": "0x9dd8f4",
"effectiveGasPrice": "0x95792911f",
"from": "0x1be82f08385faf6d00f88935c236497f94daa06f",
"gasUsed": "0x4a328",
"logs": [
{
"address": "0x000000000022d473030f116ddee9f6b43ac78ba3",
"topics": [
"0xc6a377bfc4eb120024a8ac08eef205be16b817020812c73223e81d1bdb9708ec",
"0x0000000000000000000000001be82f08385faf6d00f88935c236497f94daa06f",
"0x00000000000000000000000034103e1190b824a44c6a638438d425cba21143ba",
"0x000000000000000000000000ef1c6e67703c7bd7107eed8303fbe6ec2554bf6b"
],
"data": "0x000000000000000000000000ffffffffffffffffffffffffffffffffffffffff000000000000000000000000000000000000000000000000000000006430932d0000000000000000000000000000000000000000000000000000000000000000",
"blockNumber": "0x10023ee",
"transactionHash": "0xf033310487c37a86db8099a738ffa2bb62bb06efeb486a65ff595d411b5321f4",
"transactionIndex": "0x63",
"blockHash": "0x66103840578be3bc9c865e0961c4a4de31b5df7a45dcd13ffe2679ff9c7315d8",
"logIndex": "0xda",
"removed": false
},
[...]
{
"address": "0x1417be63afec8d175c2dc8a691fca1a898bc5b8d",
"topics": [
"0xd78ad95fa46c994b6551d0da85fc275fe613ce37657fb8d5e3d130840159d822",
"0x000000000000000000000000ef1c6e67703c7bd7107eed8303fbe6ec2554bf6b",
"0x0000000000000000000000001be82f08385faf6d00f88935c236497f94daa06f"
],
"data": "0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000c81b15967b79f200000000000000000000000000000000000000000000001920aa875deb611cad0000000000000000000000000000000000000000000000000000000000000000",
"blockNumber": "0x10023ee",
"transactionHash": "0xf033310487c37a86db8099a738ffa2bb62bb06efeb486a65ff595d411b5321f4",
"transactionIndex": "0x63",
"blockHash": "0x66103840578be3bc9c865e0961c4a4de31b5df7a45dcd13ffe2679ff9c7315d8",
"logIndex": "0xe5",
"removed": false
}
],
"logsBloom": "0x00210000000000000002004080000000000000080000000000008100000000000000000000000000010000000000000402010000880000000000000000280000000000000080000000004008000000200000000000000800000084000000000000000200000000000000000000000000002000100800000000000010000000000000004000000000000000080000000100000000000000080000004000000800021800000000010000000000000000000401000000000000000000000000000000004022000000000000400000000014400200000000001000000000000000800010200000000000000000100000000000000800000000000000000080000400",
"status": "0x1",
"to": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"transactionHash": "0xf033310487c37a86db8099a738ffa2bb62bb06efeb486a65ff595d411b5321f4",
"transactionIndex": "0x63",
"type": "0x2"
}
[...]
]
}
```

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.