ethOnBlock

Name: ethOnBlock

ethOnBlock is a stream of changes in the EVM state when a new block is mined. The stream includes the results of eth_call and other RPC requests provided by users and is restricted based on the number of calls. This is a Gateway-API only stream.

Options

Key	Description	Values
include	Fields to include in the on block event stream	name, response, blockHeight, tag [Default: all]
call-params	Fields used to build an RPC call request	method- see chart below for available methods and additional fields required for each method tag- latest, 0, or negative number. [Default: 0] name- unique string identifier for call. [Default: integer counter]

Method	Call Documentation	Additional Fields
eth_call	https://eth.wiki/json-rpc/API#eth_call	from, to, gas, value, data
eth_getBalance	https://eth.wiki/json-rpc/API#eth_getbalance	address
eth_getTransactionCount	https://eth.wiki/json-rpc/API#eth_gettransactioncount	address
eth_getCode	https://eth.wiki/json-rpc/API#eth_getcode	address
eth_getStorageAt	https://eth.wiki/json-rpc/API#eth_getstorageat	address, pos
eth_blockNumber	https://eth.wiki/json-rpc/API#eth_blocknumber	None

Examples - Websocket

Gateway

Subscribing to the ethOnBlock stream via the Gateway-API in Python (Line 6 creates the subscription):

import asyncio, jason, websockets

async def main():
    async with websockets.connect(ws_uri) as websocket:
        payload = {
            "jsonrpc": "2.0",
            "id": 1,
            "method": "subscribe",
            "params": [
                "ethOnBlock",
                {
                    "include": ["name", "response", "block_height", "tag"],
                    "call-params": [
                        {
                            "name": "my_call_name",
                            "to": "0xd46e8dd67c5d32be8058bb8eb970870f07244567",
                            "gas": "0x76c0",
                            "value": "0x9184e72a",
                            "data": "0x00"
                        },
                        {
                            "name": "number",
                            "method": "eth_blockNumber"
                        }
                    ]
                }
            ]
        }
        await websocket.send(json.dumps(payload))
        subscription_id = await websocket.recv()
        while True:
            next_notification = await websocket.recv()
            print(next_notification)  # or process it generally
        await websocket.send(json.dumps({"jsonrpc": "2.0", "id": 2, "method": "unsubscribe", "params": [subscription_id]}))
        
if __name__ == '__main__':
    asyncio.get_event_loop().run_until_complete(main())

Cloud-API

The ethOnBlock stream is not available via Cloud-API.

ethOnBlock Event

TaskCompletedEventis received after all calls have been executed upon receipt of a block.TaskDisabledEvent is received if there is an error response to a call, indicating that the call has been disabled.

Python Gateway:

<<< {'name': 'balance', 'response': {'result': '0x1'}, 'blockHeight': 11654331, 'tag': 11654331}
{'name': 'height', 'response': {'result': '0xb1d4bb'}, 'blockHeight': 11654331, 'tag': 11654331}
{'name': 'TaskDisabledEvent', 'response': {'commandMethod': 'eth_getBalance', 'blockOffset': 0, 'callName': 'balance', 'callPayload': {'address': '0x0000000000000000000000000000000000000000'}, 'active': False}, 'blockHeight': 11654331, 'tag': 11654331}
{'name': 'number', 'response': {'result': '0x0'}, 'blockHeight': 11654331, 'tag': 11654331}
{'name': 'TaskCompletedEvent', 'response': {}, 'blockHeight': 11654331, 'tag': 11654331}}

Go Gateway:

<<< {'name': 'balance', 'response': '0x1', 'block_height': 11654331, 'tag': 11654331}
{'name': 'height', 'response': '0xb1d4bb', 'block_height': 11654331, 'tag': 11654331}
{'name': 'TaskDisabledEvent', 'response': '{commandMethod:eth_call blockOffset:0 callName:my_call callPayload:{"data":"0x00","to":"0x0000000000000000000000000000000000000000"} active:false}', 'block_height': '13462626', 'tag': '0xcd6c62'}
{'name': 'number', 'response': '0x0', 'block_height': 11654331, 'tag': 11654331}
{'name': 'TaskCompletedEvent', 'response': '', 'block_height': 11654331, 'tag': 11654331}}

Examples - gRPC

Gateway

Subscribing to Gateway ethOnBlock Stream in Go using gRPC.

package main

import (
	"context"
	"fmt"
	pb "github.com/bloXroute-Labs/gateway/v2/protobuf"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"time"
)

type blxrCredentials struct {
	authorization string
}

func (bc blxrCredentials) GetRequestMetadata(ctx context.Context, uri ...string) (map[string]string, error) {
	return map[string]string{
		"authorization": bc.authorization,
	}, nil
}

func (bc blxrCredentials) RequireTransportSecurity() bool {
	return false
}

func main() {
	// gRPC server default values
	gatewayHostIP := "localhost"
	gatewayGRPCPort := 5001
	
	// this will use localhost CA to verify the certificate
	creds := credentials.NewClientTLSFromCert(nil, "")

	// Open gRPC connection to Gateway.
	conn, _ := grpc.Dial(
		fmt.Sprintf("%v:%v", gatewayHostIP, gatewayGRPCPort),
		grpc.WithTransportCredentials(creds),
		grpc.WithPerRPCCredentials(blxrCredentials{authorization: "<YOUR-AUTHORIZATION-HEADER>"}),
	)

	// Use the Gateway client connection interface.
	client := pb.NewGatewayClient(conn)

	// create context and defer cancel of context
	callContext, cancel := context.WithTimeout(context.Background(), 24*time.Hour)
	defer cancel()

	// Create a subscription using the stream-specific method and request.
	stream, _ := client.EthOnBlock(callContext,
		&pb.EthOnBlockRequest{
			CallParams: []*pb.CallParams{
				{
					Params: map[string]string{
						"name":    "balance",
						"method":  "eth_getBalance",
						"address": "0x178B2A...d8E2F4",
					},
				},
				{
					Params: map[string]string{
						"name":   "number",
						"method": "eth_blockNumber",
					},
				},
			},
		},
	)

	for {
		subscriptionNotification, err := stream.Recv()
		if err == nil {
			fmt.Println(subscriptionNotification) // or process it generally
		}
	}	
}

Response (ethOnBlock Event)

TaskCompletedEventis received after all calls have been executed upon receipt of a block.TaskDisabledEvent is received if there is an error response to a call, indicating that the call has been disabled.

<<< name:"number"
response:"0x1cec877"
blockHeight:"0x1cec877"
tag:"0x1cec877"

name:"balance"
response:"0x10febdd5766d5b"
blockHeight:"0x1cec877"
tag:"0x1cec877"

name:"TaskCompletedEvent"
blockHeight:"0x1cec877"
tag:"0x1cec877"
...