feat(contracts): add contract upgrade version check (#2112)

* feat(contracts): enable deterministic bytecode output

Add `cbor_metadata = false` and `bytecode_hash = 'none'` to both
host-contracts and gateway-contracts foundry.toml. This strips
compiler metadata from deployed bytecode, making bytecode comparison
across branches reliable for upgrade hygiene checks.

Also add OZ remappings to gateway-contracts for Foundry compatibility.

* feat(contracts): add contract upgrade hygiene CI check

New workflow + Bun/TypeScript script that compares deployed bytecode
between main and PR for every contract in upgrade-manifest.json.

When bytecode changes, the check enforces:
- REINITIALIZER_VERSION must be bumped
- A reinitializeV{N-1}() function must exist (not just commented out)
- At least one of MAJOR/MINOR/PATCH_VERSION must be bumped

When bytecode is unchanged, spurious REINITIALIZER_VERSION bumps are
flagged. Uses matrix strategy for host-contracts and gateway-contracts.
Addresses are generated via `make ensure-addresses` (same as upgrade tests).

* feat(ci): compare bytecode against last deployed release tag

Compare PR bytecode against UPGRADE_FROM_TAG (v0.11.0) instead of main.
This avoids unnecessary reinitializer bumps when multiple PRs modify the
same contract between deployments — only the first change after a release
requires a bump. Keeps the tag in sync with *-upgrade-tests.yml workflows.

* fix(ci): remove deleted source files from baseline before compiling

When comparing against the v0.11.0 baseline, forge tries to compile all
.sol files including ones that were deleted in the PR (e.g.
MultichainACLChecks.sol). These reference removed address constants and
break compilation of unrelated contracts like GatewayConfig, causing
false positives. Strip deleted files from the baseline before compiling.

* fix(ci): fall back to source comparison when baseline compilation fails

When forge can't compile the baseline (e.g. deleted contracts break
unrelated imports), compare source files directly instead of blindly
treating all contracts as changed. If the contract source is identical
between baseline and PR, bytecode is unchanged — no version bump needed.

Fixes false positive for GatewayConfig which is unchanged since v0.11.0
but couldn't be compiled because MultichainACLChecks.sol (deleted in PR)
was still imported by other v0.11.0 files.

* fix(ci): merge address constants from both baseline and PR

When comparing bytecode between the baseline tag and the PR, both sides
must compile with identical address constants (they're embedded in
bytecode).  Previously we generated addresses only on the PR side and
copied them to the baseline.  This broke when contracts were removed
between versions — the baseline still had source files importing the
deleted constant, causing forge compilation to fail for the entire
project, including unrelated unchanged contracts.

Add ci/merge-address-constants.ts: generates addresses on both sides
independently, then merges them.  PR values win for shared constants,
baseline-only constants (removed contracts) are preserved so the
baseline compiles, and PR-only constants (new contracts) are preserved
so the PR compiles.

Reverts the source-comparison fallback in check-upgrade-hygiene.ts —
both sides now compile successfully so we always compare real bytecode.

* refactor(ci): rename upgrade hygiene to upgrade version check

Rename workflow, script, job names, and all references from the
ambiguous "upgrade hygiene" to the descriptive "upgrade version check".

* chore: remove accidentally committed plan file

Author: Eikix

.github/workflows/contracts-upgrade-version-check.yml

@@ -0,0 +1,118 @@
+name: contracts-upgrade-version-check
+
+permissions: {}
+
+on:
+  pull_request:
+
+# Compare PR bytecode against the last deployed release, not main.
+# This avoids unnecessary reinitializer bumps when multiple PRs modify
+# the same contract between deployments. Keep in sync with *-upgrade-tests.yml.
+env:
+  UPGRADE_FROM_TAG: v0.11.0
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+jobs:
+  check-changes:
+    name: contracts-upgrade-version-check/check-changes
+    permissions:
+      contents: 'read' # Required to checkout repository code
+      pull-requests: 'read' # Required to read pull request for paths-filter
+    runs-on: ubuntu-latest
+    outputs:
+      packages: ${{ steps.filter.outputs.changes }}
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: 'false'
+      - uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        id: filter
+        with:
+          filters: |
+            host-contracts:
+              - .github/workflows/contracts-upgrade-version-check.yml
+              - ci/check-upgrade-versions.ts
+              - ci/merge-address-constants.ts
+              - host-contracts/**
+            gateway-contracts:
+              - .github/workflows/contracts-upgrade-version-check.yml
+              - ci/check-upgrade-versions.ts
+              - ci/merge-address-constants.ts
+              - gateway-contracts/**
+
+  check:
+    name: contracts-upgrade-version-check/${{ matrix.package }} (bpr)
+    needs: check-changes
+    if: ${{ needs.check-changes.outputs.packages != '[]' }}
+    permissions:
+      contents: 'read' # Required to checkout repository code
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        package: ${{ fromJSON(needs.check-changes.outputs.packages) }}
+        include:
+          - package: host-contracts
+            extra-deps: forge soldeer install
+          - package: gateway-contracts
+            extra-deps: ''
+    steps:
+      - name: Checkout PR branch
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: 'false'
+
+      - name: Checkout baseline (last deployed release)
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          ref: ${{ env.UPGRADE_FROM_TAG }}
+          path: baseline
+          persist-credentials: 'false'
+
+      - name: Install Bun
+        uses: oven-sh/setup-bun@735343b667d3e6f658f44d0eca948eb6282f2b76 # v2.0.2
+
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@82dee4ba654bd2146511f85f0d013af94670c4de # v1.4.0
+
+      - name: Install PR dependencies
+        working-directory: ${{ matrix.package }}
+        run: npm ci
+
+      - name: Install baseline dependencies
+        working-directory: baseline/${{ matrix.package }}
+        run: npm ci
+
+      - name: Install Forge dependencies
+        if: matrix.extra-deps != ''
+        env:
+          PACKAGE: ${{ matrix.package }}
+          EXTRA_DEPS: ${{ matrix.extra-deps }}
+        run: |
+          (cd "$PACKAGE" && $EXTRA_DEPS)
+          (cd "baseline/$PACKAGE" && $EXTRA_DEPS)
+
+      - name: Setup compilation
+        env:
+          PACKAGE: ${{ matrix.package }}
+        run: |
+          # Generate addresses on both sides independently, then merge them.
+          # Address constants are embedded in bytecode, so both sides must compile
+          # with identical values.  We can't just copy one side's addresses to the
+          # other because contracts may be added or removed between versions — the
+          # baseline would fail to compile if it references a removed constant, or
+          # the PR would fail if it references a new one.  Merging gives both sides
+          # the full union of constants with consistent values (PR wins for shared).
+          (cd "$PACKAGE" && make ensure-addresses)
+          (cd "baseline/$PACKAGE" && make ensure-addresses)
+          bun ci/merge-address-constants.ts "baseline/$PACKAGE/addresses" "$PACKAGE/addresses"
+          # Use PR's foundry.toml for both so compiler settings match (cbor_metadata, bytecode_hash)
+          cp "$PACKAGE/foundry.toml" "baseline/$PACKAGE/foundry.toml"
+
+      - name: Run upgrade version check
+        env:
+          PACKAGE: ${{ matrix.package }}
+        run: bun ci/check-upgrade-versions.ts "baseline/$PACKAGE" "$PACKAGE"

ci/check-upgrade-versions.ts

@@ -0,0 +1,147 @@
+#!/usr/bin/env bun
+// Checks that upgradeable contracts have proper version bumps when bytecode changes.
+// Usage: bun ci/check-upgrade-versions.ts <baseline-pkg-dir> <pr-pkg-dir>
+
+import { readFileSync, existsSync } from "fs";
+import { execSync } from "child_process";
+import { join } from "path";
+
+const [baselineDir, prDir] = process.argv.slice(2);
+if (!baselineDir || !prDir) {
+  console.error("Usage: bun ci/check-upgrade-versions.ts <baseline-pkg-dir> <pr-pkg-dir>");
+  process.exit(1);
+}
+
+const manifestPath = join(prDir, "upgrade-manifest.json");
+if (!existsSync(manifestPath)) {
+  console.error(`::error::upgrade-manifest.json not found in ${prDir}`);
+  process.exit(1);
+}
+
+const VERSION_RE = /(?<name>REINITIALIZER_VERSION|MAJOR_VERSION|MINOR_VERSION|PATCH_VERSION)\s*=\s*(?<value>\d+)/g;
+
+function extractVersions(filePath: string) {
+  const source = readFileSync(filePath, "utf-8");
+  const versions: Record<string, number> = {};
+  for (const { groups } of source.matchAll(VERSION_RE)) {
+    versions[groups!.name] = Number(groups!.value);
+  }
+  return { versions, source };
+}
+
+function forgeInspect(contract: string, root: string): string | null {
+  try {
+    const raw = execSync(`forge inspect "contracts/${contract}.sol:${contract}" --root "${root}" deployedBytecode`, {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env, NO_COLOR: "1" },
+    });
+    // Extract hex bytecode — forge may prepend ANSI codes or compilation progress to stdout
+    const match = raw.match(/0x[0-9a-fA-F]+/);
+    return match ? match[0] : null;
+  } catch (e: any) {
+    if (e.stderr) console.error(String(e.stderr));
+    return null;
+  }
+}
+
+const contracts: string[] = JSON.parse(readFileSync(manifestPath, "utf-8"));
+let errors = 0;
+
+for (const name of contracts) {
+  console.log(`::group::Checking ${name}`);
+  try {
+    const baseSol = join(baselineDir, "contracts", `${name}.sol`);
+    const prSol = join(prDir, "contracts", `${name}.sol`);
+
+    if (!existsSync(baseSol)) {
+      console.log(`Skipping ${name} (new contract, not in baseline)`);
+      continue;
+    }
+
+    if (!existsSync(prSol)) {
+      console.error(`::error::${name} listed in upgrade-manifest.json but missing in PR`);
+      errors++;
+      continue;
+    }
+
+    const { versions: baseV } = extractVersions(baseSol);
+    const { versions: prV, source: prSrc } = extractVersions(prSol);
+
+    let parseFailed = false;
+    for (const key of ["REINITIALIZER_VERSION", "MAJOR_VERSION", "MINOR_VERSION", "PATCH_VERSION"]) {
+      if (baseV[key] == null || prV[key] == null) {
+        console.error(`::error::Failed to parse ${key} for ${name}`);
+        errors++;
+        parseFailed = true;
+      }
+    }
+    if (parseFailed) continue;
+
+    const prBytecode = forgeInspect(name, prDir);
+    if (prBytecode == null) {
+      console.error(`::error::Failed to compile ${name} on PR`);
+      errors++;
+      continue;
+    }
+
+    const baseBytecode = forgeInspect(name, baselineDir);
+    if (baseBytecode == null) {
+      console.error(`::error::Failed to compile ${name} on baseline`);
+      errors++;
+      continue;
+    }
+    const bytecodeChanged = baseBytecode !== prBytecode;
+    const reinitChanged = baseV.REINITIALIZER_VERSION !== prV.REINITIALIZER_VERSION;
+    const versionChanged =
+      baseV.MAJOR_VERSION !== prV.MAJOR_VERSION ||
+      baseV.MINOR_VERSION !== prV.MINOR_VERSION ||
+      baseV.PATCH_VERSION !== prV.PATCH_VERSION;
+
+    if (!bytecodeChanged) {
+      console.log(`${name}: bytecode unchanged`);
+      if (reinitChanged) {
+        console.error(
+          `::error::${name} REINITIALIZER_VERSION bumped (${baseV.REINITIALIZER_VERSION} -> ${prV.REINITIALIZER_VERSION}) but bytecode is unchanged`,
+        );
+        errors++;
+      }
+      continue;
+    }
+
+    console.log(`${name}: bytecode CHANGED`);
+
+    if (!reinitChanged) {
+      console.error(
+        `::error::${name} bytecode changed but REINITIALIZER_VERSION was not bumped (still ${prV.REINITIALIZER_VERSION})`,
+      );
+      errors++;
+    } else {
+      // Convention: reinitializeV{N-1} for REINITIALIZER_VERSION=N
+      const expectedFn = `reinitializeV${prV.REINITIALIZER_VERSION - 1}`;
+      const uncommented = prSrc.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/.*$/gm, "");
+      if (!new RegExp(`function\\s+${expectedFn}\\s*\\(`).test(uncommented)) {
+        console.error(
+          `::error::${name} has REINITIALIZER_VERSION=${prV.REINITIALIZER_VERSION} but no ${expectedFn}() function found`,
+        );
+        errors++;
+      }
+    }
+
+    if (!versionChanged) {
+      console.error(
+        `::error::${name} bytecode changed but semantic version was not bumped (still v${prV.MAJOR_VERSION}.${prV.MINOR_VERSION}.${prV.PATCH_VERSION})`,
+      );
+      errors++;
+    }
+  } finally {
+    console.log("::endgroup::");
+  }
+}
+
+if (errors > 0) {
+  console.error(`::error::Upgrade version check failed with ${errors} error(s)`);
+  process.exit(1);
+}
+
+console.log("All contracts passed upgrade version checks");