JSONRPC: Transaction receipt subscription

[Kriys94]

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).

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

{
  "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, equal to the gas price.
   2.n. type: the transaction type.

{
  "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).

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

eth_subscribe response:

1. subscription id

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

eth_getFilterChanges response:

{
  "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"
      }
    [...]
  ]
}