{"id":19533917,"url":"https://github.com/ethereum-optimism/monitorism","last_synced_at":"2025-04-26T14:34:31.476Z","repository":{"id":235759404,"uuid":"791185666","full_name":"ethereum-optimism/monitorism","owner":"ethereum-optimism","description":"Suite of tools for Monitoring OP Stack Chains 🔴 Offers real-time detection and Incident response capabilities ✨ ","archived":false,"fork":false,"pushed_at":"2024-09-19T10:10:36.000Z","size":435,"stargazers_count":13,"open_issues_count":6,"forks_count":5,"subscribers_count":14,"default_branch":"main","last_synced_at":"2024-09-19T12:19:04.111Z","etag":null,"topics":["monitoring","onchain","optimism","security"],"latest_commit_sha":null,"homepage":"https://www.optimism.io/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ethereum-optimism.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-24T08:48:26.000Z","updated_at":"2024-09-19T10:37:54.000Z","dependencies_parsed_at":"2024-06-03T19:17:17.708Z","dependency_job_id":"318148ca-1883-4cf3-a274-474cb5f8961f","html_url":"https://github.com/ethereum-optimism/monitorism","commit_stats":null,"previous_names":["ethereum-optimism/monitorism"],"tags_count":8,"template":false,"template_full_name":"ethereum-optimism/.github","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethereum-optimism%2Fmonitorism","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethereum-optimism%2Fmonitorism/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethereum-optimism%2Fmonitorism/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethereum-optimism%2Fmonitorism/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ethereum-optimism","download_url":"https://codeload.github.com/ethereum-optimism/monitorism/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224036272,"owners_count":17245035,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["monitoring","onchain","optimism","security"],"created_at":"2024-11-11T02:10:53.532Z","updated_at":"2025-04-26T14:34:31.388Z","avatar_url":"https://github.com/ethereum-optimism.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"- [Monitorism](#monitorism)\n  - [Docker Images](#docker-images)\n  - [Monitors Components](#monitors-components)\n    - [Global Events Monitor](#global-events-monitor)\n    - [Liveness Expiration Monitor](#liveness-expiration-monitor)\n    - [Withdrawals Monitor](#withdrawals-monitor)\n    - [Balances Monitor](#balances-monitor)\n    - [Fault Monitor](#fault-monitor)\n    - [Multisig Monitor](#multisig-monitor)\n    - [Drippie Monitor](#drippie-monitor)\n    - [Secrets Monitor](#secrets-monitor)\n    - [Transaction Monitor](#transaction-monitor)\n    - [ETH Conservation Monitor](#eth-conservation-monitor)\n    - [Faultproof Withdrawals](#faultproof-withdrawal)\n  - [Defender Components](#defender-components)\n    - [HTTP API PSP Executor Service](#http-api-psp-executor-service)\n  - [CLI \u0026amp; Docs](#cli--docs)\n    - [Bootstrap](#bootstrap)\n    - [Command line Options](#command-line-options)\n\n# Monitorism\n\n_Monitorism_ is a tooling suite that supports monitoring and active remediation actions for the OP Stack chain.\n\nThe suite is composed of two main components: `op-monitorism` and `op-defender`, that can be used together or separately and see below for more details.\n\n## Docker images\n\n### Op-Monitorism\n\nOp-Monitorism Docker images are published with each release and build, ensuring you have access to the latest features and fixes.\n\nThe latest release version for linux/amd64 can be found in the [release notes](https://github.com/ethereum-optimism/monitorism/releases)\n\nTo pull the latest Docker image, run:\n\n```bash\ndocker pull --platform linux/amd64 us-docker.pkg.dev/oplabs-tools-artifacts/images/op-monitorism:latest\n```\n\nTo pull a specific release version\n\n```bash\ndocker pull --platform linux/amd64 us-docker.pkg.dev/oplabs-tools-artifacts/images/op-monitorism:v0.0.4\n```\n\nNote: The --platform flag is necessary for Mac computers with ARM chips to ensure compatibility with the linux/amd64 architecture.\n\nTo build the Docker image locally, execute the following command:\n\n```bash\ndocker build -t op-monitorism ./op-monitorism\n```\n\nUse \"-t op-monitorism\" to tag the image with the name op-monitorism for easier reference.\n\n## Monitors Components\n\nThe `monitors` are passive security services that provide automated monitoring for the OP Stack.\nThere are components that are designed to make monitoring of the OP stack and alerting on specific events, that could be a sign of a security incident.\n\nThe list of all the monitors currently built into `op-monitorism` is below.\n\n### Global Events Monitor\n\n![df2b94999628ce8eee98fb60f45667e54be9b13db82add6aa77888f355137329](https://github.com/ethereum-optimism/monitorism/assets/23560242/b8d36a0f-8a17-4e22-be5a-3e9f3586b3ab)\n\nThe Global Events Monitor is made for to taking YAML rules as configuration and monitoring the events that are emitted on the chain.\n\n| `op-monitorism/global_events` | [README](https://github.com/ethereum-optimism/monitorism/blob/main/op-monitorism/global_events/README.md) |\n| ----------------------------- | --------------------------------------------------------------------------------------------------------- |\n\n### Liveness Expiration Monitor\n\n![ab27497cea05fbd51b7b1c2ecde5bc69307ac0f27349f6bba4f3f21423116071](https://github.com/ethereum-optimism/monitorism/assets/23560242/af7a7e29-fff5-4df3-82f0-94c2f28fde84)\n\nThe Liveness Expiration Monitor is made for monitoring the liveness expiration on Safes.\n\n| `op-monitorism/liveness_expiration` | [README](https://github.com/ethereum-optimism/monitorism/blob/main/op-monitorism/liveness_expiration/README.md) |\n| ----------------------------------- | --------------------------------------------------------------------------------------------------------------- |\n\n### Withdrawals Monitor\n\n![6d5477f5585cb49ff2f8bd147c2e7037772de6a1dd128ce4331596b011ce6ea9](https://github.com/user-attachments/assets/ac5e0a61-b495-4254-b32a-86abf61f0dc1)\n\nThe withdrawals monitor checks for new withdrawals that have been proven to the `OptimismPortal` contract.\nEach withdrawal is checked against the `L2ToL1MessagePasser` contract.\n\n| `op-monitorism/withdrawals` | [README](https://github.com/ethereum-optimism/monitorism/blob/main/op-monitorism/withdrawals/README.md) |\n| --------------------------- | ------------------------------------------------------------------------------------------------------- |\n\n### Balances Monitor\n\n![5cd47a6e0f2fb7d921001db9eea24bb62bb892615011d03f275e02a147823827](https://github.com/user-attachments/assets/44884a76-e06d-4f58-a21f-94c2275e9d8b)\n\nThe balances monitor simply emits a metric reporting the balances for the configured accounts.\n\n| `op-monitorism/balances` | [README](https://github.com/ethereum-optimism/monitorism/blob/main/op-monitorism/balances/README.md) |\n| ------------------------ | ---------------------------------------------------------------------------------------------------- |\n\n### Fault Monitor\n\n\u003cimg width=\"1696\" alt=\"148f61f4600327b94b55be39ca42c58c797d70d7017dbb7d56dbefa208cc7164\" src=\"https://github.com/user-attachments/assets/68ecfaa0-ee6d-46be-b760-a9eb8b232d65\"\u003e\n\nThe fault monitor checks for changes in output roots posted to the `L2OutputOracle` contract.\nOn change, reconstructing the output root from a trusted L2 source and looking for a match.\n\n| `op-monitorism/fault` | [README](https://github.com/ethereum-optimism/monitorism/blob/main/op-monitorism/fault/README.md) |\n| --------------------- | ------------------------------------------------------------------------------------------------- |\n\n### Multisig Monitor\n\n![7dab260ee38122980274fee27b114c590405cff2e5a68e6090290ecb786b68f2](https://github.com/user-attachments/assets/0eeb161b-923a-40fd-b561-468df3d5091d)\n\nThe multisig monitor reports the paused status of the `OptimismPortal` contract.\nIf set, the latest nonce of the configured `Safe` address. And also if set, the latest presigned nonce stored in One Password.\nThe latest presigned nonce is identified by looking for items in the configured vault that follow a `ready-\u003cnonce\u003e.json` name.\nThe highest nonce of this item name format is reported.\n\n| `op-monitorism/multisig` | [README](https://github.com/ethereum-optimism/monitorism/blob/main/op-monitorism/multisig/README.md) |\n| ------------------------ | ---------------------------------------------------------------------------------------------------- |\n\n### Drippie Monitor\n\nThe drippie monitor tracks the execution and executability of drips within a Drippie contract.\n\n| `op-monitorism/drippie` | [README](https://github.com/ethereum-optimism/monitorism/blob/main/op-monitorism/drippie/README.md) |\n| ----------------------- | --------------------------------------------------------------------------------------------------- |\n\n### Secrets Monitor\n\nThe secrets monitor takes a Drippie contract as a parameter and monitors for any drips within that contract that use the CheckSecrets dripcheck contract. CheckSecrets is a dripcheck that allows a drip to begin once a specific secret has been revealed (after a delay period) and cancels the drip if a second secret is revealed. It's important to monitor for these secrets being revealed as this could be a sign that the secret storage platform has been compromised and someone is attempting to exfiltrate the ETH controlled by that drip.\n\n| `op-monitorism/secrets` | [README](https://github.com/ethereum-optimism/monitorism/blob/main/op-monitorism/secrets/README.md) |\n| ----------------------- | --------------------------------------------------------------------------------------------------- |\n\n### Transaction Monitor\n\nThe transaction monitor takes in a yaml config in order to run, and monitors transaction sent by a specific address, tracking both cumulative eth sent, as well as tunable thresholds for specific alerts. It is also configurable to support working against factory contracts, right now just the `FaultDisputeGame` factory to ensure the addresses are only interacting with valid fault dispute games.\n\n| `op-monitorism/transaction_monitor` | [README](https://github.com/ethereum-optimism/monitorism/blob/main/op-monitorism/transaction_monitor/README.md) |\n| ----------------------------------- | --------------------------------------------------------------------------------------------------------------- |\n\n### ETH Conservation Monitor\n\nThe ETH conservation monitor traces L2 blocks and asserts that they adhere to the L2 ETH conservation invariant.\n\n| `op-monitorism/conservation_monitor` | [README](https://github.com/ethereum-optimism/monitorism/blob/main/op-monitorism/conservation_monitor/README.md) |\n| ----------------------------------- | --------------------------------------------------------------------------------------------------------------- |\n\n### Faultproof Withdrawal\n\nThe Faultproof Withdrawal component monitors ProvenWithdrawals events on the [OptimismPortal](https://github.com/ethereum-optimism/superchain-registry/blob/d454618b6cf885417aa8cc8c760bd9ed0429c131/superchain/configs/mainnet/op.toml#L50) contract and performs checks to detect any violations of invariant conditions on the chain. If a violation is detected, it logs the issue and sets a Prometheus metric for the event.\n\nThis component is designed to work exclusively with chains that are already utilizing the [Fault Proofs system](https://docs.optimism.io/stack/protocol/fault-proofs/explainer).\nThis is a new version of the deprecated [chain-mon faultproof-wd-mon](https://github.com/ethereum-optimism/optimism/tree/chain-mon/v1.2.1/packages/chain-mon/src/faultproof-wd-mon).\nFor detailed information on how the component works and the algorithms used, please refer to the component README.\n\n| `op-monitorism/faultproof_withdrawals` | [README](https://github.com/ethereum-optimism/monitorism/blob/main/op-monitorism/faultproof_withdrawals/README.md) |\n| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |\n\n## Defender Components\n\nThe _defenders_ are active security service allowing to provide automated defense for the OP Stack.\nThere are components that are designed to make immediate actions onchain/offchain to protect the assets.\n\nThe list of all the defender currently built into `op-defender` is below.\n\n### HTTP API PSP Executor Service\n\n![f112841bad84c59ea3ed1ca380740f5694f553de8755b96b1a40ece4d1c26f81](https://github.com/user-attachments/assets/17235e99-bf25-40a5-af2c-a0d9990c6276)\n\nThe PSP Executor Service is made for executing PSP onchain faster to increase our readiness and speed in case of incident response.\n\n| `op-defender/psp_executor` | [README](https://github.com/ethereum-optimism/monitorism/blob/main/op-defender/psp_executor/README.md) |\n| -------------------------- | ------------------------------------------------------------------------------------------------------ |\n\n## CLI \u0026 Docs\n\n### Bootstrap\n\nAfter cloning, please run `./bootstrap.sh` to set up the development environment correctly.\n\n### Command line Options\n\nThe cli has the ability to spin up a monitor for varying activities, each emitting metrics used to setup alerts.\n\n```\nCOMMANDS:\n   multisig                Monitors OptimismPortal pause status, Safe nonce, and Pre-Signed nonce stored in 1Password\n   fault                   Monitors output roots posted on L1 against L2\n   withdrawals             Monitors proven withdrawals on L1 against L2\n   balances                Monitors account balances\n   drippie                 Monitors Drippie contract\n   secrets                 Monitors secrets revealed in the CheckSecrets dripcheck\n   global_events           Monitors global events with YAML configuration\n   liveness_expiration     Monitor the liveness expiration on Gnosis Safe.\n   faultproof_withdrawals  Monitors withdrawals on the OptimismPortal in order to detect forgery. Note: Requires chains with Fault Proofs.\n   version                 Show version\n   help, h                 Shows a list of commands or help for one command\n```\n\nEach monitor has some common configuration, configurable both via cli or env with defaults.\n\n```\nOPTIONS:\n   --log.level value           [$MONITORISM_LOG_LEVEL]           The lowest log level that will be output (default: INFO)\n   --log.format value          [$MONITORISM_LOG_FORMAT]          Format the log output. Supported formats: 'text', 'terminal', 'logfmt', 'json', 'json-pretty', (default: text)\n   --log.color                 [$MONITORISM_LOG_COLOR]           Color the log output if in terminal mode (default: false)\n   --metrics.enabled           [$MONITORISM_METRICS_ENABLED]     Enable the metrics server (default: false)\n   --metrics.addr value        [$MONITORISM_METRICS_ADDR]        Metrics listening address (default: \"0.0.0.0\")\n   --metrics.port value        [$MONITORISM_METRICS_PORT]        Metrics listening port (default: 7300)\n   --loop.interval.msec value  [$MONITORISM_LOOP_INTERVAL_MSEC]  Loop interval of the monitor in milliseconds (default: 60000)\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethereum-optimism%2Fmonitorism","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fethereum-optimism%2Fmonitorism","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethereum-optimism%2Fmonitorism/lists"}