|
1 | 1 | # Assertion Monitor |
2 | 2 |
|
3 | | -This tool is designed to monitor assertions on Arbitrum chains. It performs comprehensive monitoring of both BOLD (Bounded Liquidity Delay) and Classic rollup chains, with the following checks: |
| 3 | +> For installation and general configuration, see the [main README](../../README.md). |
4 | 4 |
|
5 | | -## Chain Activity Monitoring |
6 | | -1. Tracks chain activity by monitoring block progression |
7 | | -2. Verifies the latest confirmed block number from the child chain |
8 | | -3. Detects periods of inactivity or stalled chain progress |
| 5 | +## Overview |
9 | 6 |
|
10 | | -## Assertion Creation Monitoring |
11 | | -1. No assertions created in the last 4 hours when there is chain activity |
12 | | -2. Tracks creation events and validates their frequency |
13 | | -3. Alerts when chain activity exists without new assertions |
| 7 | +The Assertion Monitor monitors the lifecycle of assertions in both BoLD (Bounded Liquidity Delay) and pre-BoLD rollup chains. [Learn more](https://docs.arbitrum.io/how-arbitrum-works/inside-arbitrum-nitro#arbitrum-rollup-protocol). |
14 | 8 |
|
15 | | -## Assertion Confirmation Monitoring |
16 | | -1. No assertions confirmed within the chain's confirmation period |
17 | | -2. Tracks unconfirmed assertions and their age |
18 | | -3. Monitors confirmation delays against the chain's configured period |
19 | | -4. Validates the time between creation and confirmation events |
| 9 | +## Command-Line Interface |
20 | 10 |
|
21 | | -## Alert Types |
22 | | -The monitor generates alerts for the following conditions: |
23 | | - |
24 | | -1. Creation Issues: |
25 | | - - No assertion creation events in the last 7 days |
26 | | - - Chain activity detected but no new assertions created in the last 4 hours |
27 | | - |
28 | | -2. Confirmation Issues: |
29 | | - - Parent chain confirmation issues - assertions not confirming |
30 | | - - Unconfirmed assertions present |
31 | | - - Assertion age exceeds confirmation period |
32 | | - - Confirmation delay exceeds the configured period |
33 | | - |
34 | | -3. Chain State Issues: |
35 | | - - Chain stalled or inactive |
36 | | - - Block synchronization issues |
37 | | - - Validator whitelist status changes |
38 | | - |
39 | | -Read more about assertions [here](https://docs.arbitrum.io/how-arbitrum-works/inside-arbitrum-nitro#arbitrum-rollup-protocol). |
40 | | - |
41 | | -## Prerequisites |
42 | | - |
43 | | -Before using this tool, make sure you have the following installed: |
44 | | - |
45 | | -- [Node.js](https://nodejs.org/en) |
46 | | -- [Yarn](https://classic.yarnpkg.com/lang/en/docs/install/#mac-stable) |
| 11 | +```bash |
| 12 | +yarn assertion-monitor [options] |
47 | 13 |
|
48 | | -Additionally, ensure that you have added your Arbitrum network configuration to the `config.json` file in the `lib` directory; |
| 14 | +Monitor assertion creation and validation on Arbitrum chains |
49 | 15 |
|
50 | | -## Installation |
| 16 | +Options: |
| 17 | + --help Show help [boolean] |
| 18 | + --version Show version number [boolean] |
| 19 | + --configPath Path to config file [string] [default: "config.json"] |
| 20 | + --enableAlerting Enable Slack alerts [boolean] [default: false] |
51 | 21 |
|
52 | | -From the root directory of the project, run the following command to install dependencies: |
| 22 | +Examples: |
| 23 | + yarn assertion-monitor Run with default config |
| 24 | + yarn assertion-monitor --enableAlerting Enable Slack notifications |
| 25 | + yarn assertion-monitor --configPath=custom.json Use custom config file |
53 | 26 |
|
54 | | -```bash |
55 | | -yarn install |
| 27 | +Environment Variables: |
| 28 | + ASSERTION_MONITORING_SLACK_TOKEN Slack API token for alerts |
| 29 | + ASSERTION_MONITORING_SLACK_CHANNEL Slack channel for alerts |
56 | 30 | ``` |
57 | 31 |
|
58 | | -## Execution |
| 32 | +## Monitor Details |
59 | 33 |
|
60 | | -### One-off Check |
| 34 | +The Assertion Monitor tracks assertions through their lifecycle, implementing distinct strategies for BoLD and pre-BoLD rollup chains. |
61 | 35 |
|
62 | | -To find assertion events and display their status for a specific block range, execute the following command: |
63 | | - |
64 | | -```bash |
65 | | -yarn dev [--configPath=<CONFIG_PATH>] |
66 | | -``` |
| 36 | +### Critical Events Monitored |
67 | 37 |
|
68 | | -- If `--configPath` is not provided, it defaults to `config.json`. |
69 | | -- This command will identify all assertion events (both creation and confirmation) from the parent chain to your Orbit chain within the specified block range. |
| 38 | +The monitor tracks five categories of blockchain events: |
70 | 39 |
|
71 | | -### Error Generation and Reporting |
| 40 | +- **Creation Events**: Records when new assertions and nodes are created on the chain to verify transaction execution |
| 41 | +- **Confirmation Events**: Identifies when assertions are confirmed on the parent chain after challenge periods end |
| 42 | +- **Validator Events**: Tracks validator participation metrics including stakes, challenges, and whitelist status |
| 43 | +- **Block Events**: Monitors block production rates, finalization timing, and synchronization between chains |
| 44 | +- **Chain State**: Analyzes the overall consistency between on-chain state and expected protocol behavior |
72 | 45 |
|
73 | | -To enable reporting, use `--enableAlerting` flag. |
| 46 | +### Alert Scenarios |
74 | 47 |
|
75 | | -This will enable alerts for all the conditions listed above in the Alert Types section. |
| 48 | +The monitor triggers alerts when these conditions are detected: |
76 | 49 |
|
77 | | -Additionally, you might also want to log these errors to Slack, for which you will need to configure, in the `.env` file: |
| 50 | +#### Creation Issues |
78 | 51 |
|
79 | | -- `NODE_ENV=CI` |
80 | | -- `ASSERTION_MONITORING_SLACK_TOKEN=<your-slack-token>` |
81 | | -- `ASSERTION_MONITORING_SLACK_CHANNEL=<your-slack-channel-key>` |
| 52 | +- No assertion creation events within configured time window |
| 53 | +- Chain activity without corresponding recent assertions |
| 54 | +- Extended node creation gaps on non-BoLD chains |
| 55 | +- Validator participation below required thresholds |
82 | 56 |
|
83 | | -Check [Slack integration documentation](https://api.slack.com/quickstart) for more information about getting these auth tokens. |
| 57 | +#### Confirmation Issues |
84 | 58 |
|
85 | | -## Chain Support |
| 59 | +- Parent chain block threshold exceeded |
| 60 | +- Assertions stuck in challenge period |
| 61 | +- Data inconsistencies between confirmation events and confirmed blocks |
| 62 | +- Confirmation events missing despite available creation events |
86 | 63 |
|
87 | | -The monitor automatically detects and adapts to different chain types: |
| 64 | +#### Other Issues |
88 | 65 |
|
89 | | -1. BOLD (Bounded Liquidity Delay) Chains: |
90 | | - - Uses BOLD-specific assertion formats and validation |
91 | | - - Tracks BOLD-specific confirmation processes |
92 | | - - Monitors BOLD genesis assertion hash |
| 66 | +- Validator whitelist disabled on pre-BoLD chains |
| 67 | +- Base stake below 1 ETH threshold on BoLD chains |
| 68 | +- Parent-child chain synchronization anomalies |
| 69 | +- State inconsistencies between expected and observed chain state |
93 | 70 |
|
94 | | -2. Classic Rollup Chains: |
95 | | - - Uses Classic node creation and confirmation events |
96 | | - - Monitors Classic-specific block validation |
97 | | - - Tracks node confirmation processes |
| 71 | +For implementation details and thresholds, see `alerts.ts` and `monitoring.ts`. |
0 commit comments