> ## Documentation Index
> Fetch the complete documentation index at: https://docs.extractor.live/llms.txt
> Use this file to discover all available pages before exploring further.

# Contract Hash Verification for security

> Verify proxy contract upgrades against expected bytecode hashes, alerting whenever an unexpected or unauthorized implementation is deployed.

## Overview

The Contract Hash Verification detector watches for `Upgraded` events emitted by proxy contracts on the EVM network. When an upgrade is detected, the detector fetches the bytecode of the new implementation contract via RPC, computes its hash, and compares it against a pre-configured expected checksum.

An alert is fired if the checksums do not match, indicating that an unexpected or unauthorised implementation was deployed.

There are two moments when verification runs:

* **On startup** — if `initial_check` is enabled, the current implementation's bytecode is verified immediately against the expected checksum before any transactions are processed
* **On upgrade** — every time an `Upgraded` event is detected in a transaction for a monitored proxy address

<Note>
  No alert is sent when the checksum matches — a silent pass indicates successful verification.
</Note>

## Contract Bytecode Checksum

The expected hash of the implementation contract's compiled bytecode. This is the value the detector compares against the live on-chain bytecode hash after every upgrade.

| Field      | Type     | Required |
| ---------- | -------- | -------- |
| `checksum` | `string` | Yes      |

The checksum must be computed using the same hash function selected in `hash_type`. To obtain it, hash the deployed bytecode of the known-good implementation contract.

## Hash Type

| Value    | Algorithm                      |
| -------- | ------------------------------ |
| `KECCAK` | Keccak-256 (standard EVM hash) |
| `SHA256` | SHA-256                        |

## Initial Check

Controls whether the detector verifies the current implementation bytecode immediately on startup, before any upgrade event is observed.

| Field           | Type   | Default |
| --------------- | ------ | ------- |
| `initial_check` | `bool` | `true`  |

When enabled, the detector fetches and hashes the bytecode at the monitored proxy address during initialisation. If the hash does not match `checksum`, a `contract_checksum_mismatch` alert is emitted immediately with no associated transaction.

Use this to catch pre-existing mismatches or to validate the initial configuration before live monitoring begins.

## Alert Types

| Event Type                   | Trigger                                                                                                                     |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `contract_checksum_mismatch` | Deployed bytecode hash does not match `checksum`, either on startup (if `initial_check: true`) or after an `Upgraded` event |

## Alert Metadata

| Field                | Description                                                                                        |
| -------------------- | -------------------------------------------------------------------------------------------------- |
| `tx_hash`            | Hash of the transaction that contained the `Upgraded` event (empty string if triggered on startup) |
| `tx_from`            | Sender of that transaction (empty string if triggered on startup)                                  |
| `tx_to`              | Recipient of that transaction (empty string if triggered on startup)                               |
| `monitored_contract` | Address of the monitored proxy contract                                                            |
| `hash_type`          | Hash algorithm used for verification (`KECCAK` or `SHA256`)                                        |
| `deployed_hash`      | Checksum computed from the live on-chain bytecode of the new implementation                        |
| `expected_hash`      | The configured expected checksum                                                                   |

## FAQ

**What triggers a verification check?**
Two things: an `Upgraded` event emitted by the monitored proxy contract in any transaction, and — if `initial_check` is enabled — the startup of the detector itself.

**What is the `Upgraded` event?**
A standard event emitted by OpenZeppelin-compatible upgradeable proxy contracts when their implementation address is changed. It carries the address of the new implementation as a field.

**What hash should I put in the `checksum` field?**
Compute the Keccak-256 (or SHA-256, if using that mode) of the **deployed bytecode** of the authorised implementation contract. This can be done with standard EVM tooling (e.g. `cast keccak $(cast code <address>)`).

**What happens if the checksums match?**
Nothing — no alert is sent. A match means the deployed implementation is the expected one.

**What happens if the checksum is not configured?**
The configuration is skipped entirely and a warning is logged. The address will not be monitored until a valid checksum is provided.