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

**Service available via Gateway-API only.**

## Stream Endpoint

* Method: `ethOnBlock`
* Gateway-API Endpoint: `ws://127.0.0.1:28333/ws`
* Request type: `gRPC`*`,WSS`*

### Parameters

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

| 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*                           |

### **Example**

{% tabs %}
{% tab title="WebSocket" %}
Subscribing to the **`ethOnBlock`** stream via the Gateway-API in Python (Line 6 creates the subscription):

```python
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())
```

{% endtab %}

{% tab title="gRPC" %}
Subscribing to Gateway `ethOnBlock` Stream in Go using gRPC.

```go
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
		}
	}	
}
```

{% endtab %}
{% endtabs %}

#### Response

{% tabs %}
{% tab title="WebSocket" %}
**`TaskCompletedEvent`**&#x69;s 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:

```bash
<<< {'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:

```bash
<<< {'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}}
```

{% endtab %}

{% tab title="gRPC" %}

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

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

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

{% endtab %}
{% endtabs %}