feat(contracts): add contract upgrade version check

.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");