ethclient: add SubscribeTransactionReceipts (#32869)

Add `SubscribeTransactionReceipts` for ethclient. This is a complement
to https://github.com/ethereum/go-ethereum/pull/32697.

eth/filters/api.go

@@ -299,15 +299,27 @@ func (api *FilterAPI) Logs(ctx context.Context, crit FilterCriteria) (*rpc.Subsc
 	return rpcSub, nil
 }
 
-// TransactionReceiptsFilter defines criteria for transaction receipts subscription.
+// TransactionReceiptsQuery defines criteria for transaction receipts subscription.
-// If TransactionHashes is nil or empty, receipts for all transactions included in new blocks will be delivered.
+// Same as ethereum.TransactionReceiptsQuery but with UnmarshalJSON() method.
-// Otherwise, only receipts for the specified transactions will be delivered.
+type TransactionReceiptsQuery ethereum.TransactionReceiptsQuery
-type TransactionReceiptsFilter struct {
+
-	TransactionHashes []common.Hash `json:"transactionHashes,omitempty"`
+// UnmarshalJSON sets *args fields with given data.
+func (args *TransactionReceiptsQuery) UnmarshalJSON(data []byte) error {
+	type input struct {
+		TransactionHashes []common.Hash `json:"transactionHashes"`
+	}
+
+	var raw input
+	if err := json.Unmarshal(data, &raw); err != nil {
+		return err
+	}
+
+	args.TransactionHashes = raw.TransactionHashes
+	return nil
 }
 
 // TransactionReceipts creates a subscription that fires transaction receipts when transactions are included in blocks.
-func (api *FilterAPI) TransactionReceipts(ctx context.Context, filter *TransactionReceiptsFilter) (*rpc.Subscription, error) {
+func (api *FilterAPI) TransactionReceipts(ctx context.Context, filter *TransactionReceiptsQuery) (*rpc.Subscription, error) {
 	notifier, supported := rpc.NotifierFromContext(ctx)
 	if !supported {
 		return &rpc.Subscription{}, rpc.ErrNotificationsUnsupported

ethclient/ethclient.go

@@ -350,6 +350,15 @@ func (ec *Client) TransactionReceipt(ctx context.Context, txHash common.Hash) (*
 	return r, err
 }
 
+// SubscribeTransactionReceipts subscribes to notifications about transaction receipts.
+func (ec *Client) SubscribeTransactionReceipts(ctx context.Context, q *ethereum.TransactionReceiptsQuery, ch chan<- []*types.Receipt) (ethereum.Subscription, error) {
+	sub, err := ec.c.EthSubscribe(ctx, ch, "transactionReceipts", q)
+	if err != nil {
+		return nil, err
+	}
+	return sub, nil
+}
+
 // SyncProgress retrieves the current progress of the sync algorithm. If there's
 // no sync currently running, it returns nil.
 func (ec *Client) SyncProgress(ctx context.Context) (*ethereum.SyncProgress, error) {

interfaces.go

@@ -62,6 +62,13 @@ type ChainReader interface {
 	SubscribeNewHead(ctx context.Context, ch chan<- *types.Header) (Subscription, error)
 }
 
+// TransactionReceiptsQuery defines criteria for transaction receipts subscription.
+// If TransactionHashes is empty, receipts for all transactions included in new blocks will be delivered.
+// Otherwise, only receipts for the specified transactions will be delivered.
+type TransactionReceiptsQuery struct {
+	TransactionHashes []common.Hash
+}
+
 // TransactionReader provides access to past transactions and their receipts.
 // Implementations may impose arbitrary restrictions on the transactions and receipts that
 // can be retrieved. Historic transactions may not be available.
@@ -81,6 +88,11 @@ type TransactionReader interface {
 	// transaction may not be included in the current canonical chain even if a receipt
 	// exists.
 	TransactionReceipt(ctx context.Context, txHash common.Hash) (*types.Receipt, error)
+	// SubscribeTransactionReceipts subscribes to notifications about transaction receipts.
+	// The receipts are delivered in batches when transactions are included in blocks.
+	// If q is nil or has empty TransactionHashes, all receipts from new blocks will be delivered.
+	// Otherwise, only receipts for the specified transaction hashes will be delivered.
+	SubscribeTransactionReceipts(ctx context.Context, q *TransactionReceiptsQuery, ch chan<- []*types.Receipt) (Subscription, error)
 }
 
 // ChainStateReader wraps access to the state trie of the canonical blockchain. Note that