Block History Integrity Checks (BHIC)

If you are on-call, you may need run the block history integrity checks for a new chain in the Superchain. The steps to complete these requests are outlined below.

Add a New Chain

If the current BHICs do not include the chain that you want to run the checks for, you will need to make a pull request to the security tools repo.

The process of adding a new chain can be complicated if the chain you’re adding lies outside of standard deploy processes. We will describe the happy path below (I (@Blaine Malone) can assist the first time we need to perform the BHIC for a new chain so feel free to ping me):

1. Create a PR to the security-tools repo that covers everything in this example PR: https://github.com/ethereum-optimism/security-tools/pull/178
   1. Before you start, please make sure your local environment is configured correctly: https://github.com/ethereum-optimism/security-tools/blob/main/README.md#getting-started
      1. Run BHIC for the new <chain-id> e.g. pnpm check-block-history-integrity <chain-id>. Work your way through the errors in the logs if there are any. Once the command runs fully without any errors, you’ll need to look at the log output in order to know what addresses/commits etc to add to the PR. There are more comments in the PR above that addresses these points.
   2. Using the PR as a template, make all the necessary updates.
   3. Request a backfill on Shadow.xyz: [Shadow.xyz Requesting a Backfill](https://oplabs.notion.site/Shadow-xyz-Requesting-a-Backfill-c963abbb88b64493b714f0cb4bde870a)
2. Once this is merged to the main branch, continue to the How to Manually Run the Block History Integrity Checks section below.
   1. Make sure to study the results from each integrity check i.e.
      1. Integrity of current L1 smart contracts.
      2. Integrity of past L1 smart contracts.
      3. Integrity of output Roots posted to L1.
      4. Integrity of L2 predeploys and genesis state.
         1. Please note that ‘genesis checks’ are not performed as part of BHIC in security-tools. This functionality lives in superchain-registry. Before you can fill out the email template on the next step, you must confirm that the genesis checks have already been completed in the superchain-registry. Right now, it is expected that these genesis checks have already been performed before requesting to run BHIC for a chain.
         2. Recorded video call going over how these genesis check happen in superchain-registry: https://drive.google.com/drive/u/0/folders/1XELLOh0UCERX5QWYZS0MiqwSx0J1ETr9
3. If successful, extract the results from CircleCI and fill in the following email template (this template is inspired by the original email we sent to Jing when the BHICs were performed for Metal, Mode & Zora):
   • Pre-Key Handover Email Template: https://docs.google.com/document/d/1jxw9EOB5uOVcn1tOVKcydkDbAdDOeyvswp3amxT3Ouo/edit?usp=drive_link
     • Note: you’ll have to manually go through the CircleCI logs (from step 2) to find these values that will substitute the placeholders in the email template.
4. Wait for key handover to fully complete then pick any CircleCI output from that point and fill in the following email template for a follow up email:
   1. Post-Key Handover Email Template: https://docs.google.com/document/d/1-gLHlPN4MidUJNvE2ChYrG8wfT50wa23OVxp1UZqumk/edit?tab=t.0

<aside> 💡 Congrats, you successfully ran the Block History Integrity checks for a new chain. If you’ve any questions, or run into any issues, please reach out to @Blaine Malone on Slack.

</aside>