Chain Pulse

Collect packets relayed to and from a given blockchain, computing which packets are effected or not and by whom they were relayed.

The collected data is stored in a SQLite database and the metrics are exported to Prometheus.

Installation

1. Clone this repository shell $ git clone https://github.com/informalsystems/chainpulse

2. Build the chainpulse executable shell $ cargo build --release

3. The chainpulse executable can now be found in target/release

Configuration

Create a configuration file at chainpulse.toml with the following content:

```toml [chains] endpoints = [ { name = "neutron", cometversion = "0.34", url = "wss://neutron-rpc.lavenderfive.com/websocket" }, { name = "osmosis", cometversion = "0.34", url = "wss://rpc.osmosis.zone/websocket" }, ]

[database] path = "data.db"

[metrics] enabled = true port = 3000 ```

Note: The comet_version field is optional and defaults to "0.34".

Usage

``` Collect and analyze txs containing IBC messages, export the collected metrics for Prometheus

Usage: chainpulse [OPTIONS]

Options: -c, --config Path to the configuration file [default: chainpulse.toml] -h, --help Print help ```

Run the collector using the configuration file above to collect packet metrics on Osmosis and Neutron:

```shell $ chainpulse --config chainpulse.toml 2023-05-26T10:17:28.378380Z INFO Metrics server listening at http://localhost:3000/metrics 2023-05-26T10:17:28.386299Z INFO collect{chain=neutron}: Connecting to wss://neutron-rpc.lavenderfive.com/websocket... 2023-05-26T10:17:28.386951Z INFO collect{chain=osmosis}: Connecting to wss://rpc.osmosis.zone/websocket... 2023-05-26T10:17:28.932084Z INFO collect{chain=neutron}: Subscribing to NewBlock events... 2023-05-26T10:17:29.012893Z INFO collect{chain=neutron}: Waiting for new blocks... 2023-05-26T10:17:29.078725Z INFO collect{chain=osmosis}: Subscribing to NewBlock events... 2023-05-26T10:17:29.254485Z INFO collect{chain=osmosis}: Waiting for new blocks...

... ```

Prometheus Metrics

The built-in HTTP server at /metrics exports the following Prometheus metrics:

```

HELP ibceffectedpackets The number of IBC packets that are effected

TYPE ibceffectedpackets counter

ibceffectedpackets{chainid, srcchannel, srcport, dstchannel, dst_port, signer, memo} ```

```

HELP ibcuneffectedpackets The number of IBC packets that are not effected

TYPE ibcuneffectedpackets counter

ibcuneffectedpackets{chainid, srcchannel, srcport, dstchannel, dst_port, signer, memo} ```

```

HELP ibcfrontruncounter The number of times a signer gets frontrun by the original signer

TYPE ibcfrontruncounter counter

ibcfrontruncounter{chainid, srcchannel, srcport, dstchannel, dstport, signer, frontrunnedby, memo, effected_memo}

HELP ibcstuckpackets The number of packets stuck on an IBC channel

TYPE ibcstuckpackets gauge

ibcstuckpackets{dstchain,srcchain,src_channel} 1 ```

Internal metrics

The following internal metrics are also available, for monitor Chain Pulse itself:

```

HELP chainpulse_chains The number of chains being monitored

TYPE chainpulse_chains gauge

chainpulse_chains 2 ```

```

HELP chainpulse_packets The number of packets processed

TYPE chainpulse_packets counter

chainpulsepackets{chainid} ```

```

HELP chainpulse_reconnects The number of times we had to reconnect to the WebSocket

TYPE chainpulse_reconnects counter

chainpulsereconnects{chainid} ```

```

HELP chainpulse_txs The number of txs processed

TYPE chainpulse_txs counter

chainpulsetxs{chainid} ```

Attribution

This project is heavily inspired and partly ported from @clemensgg's relayer-metrics-exporter

License

Copyright © 2023 Informal Systems Inc. and Hermes authors.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use the files in this repository except in compliance with the License. You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.