feat(common): add ABI compatibility checks and reorganize CI scripts (#2182)

* feat(ci): add contract ABI compatibility checks

* fix(ci): improve abi compat script output

* fix(contracts): allow accepted ABI deltas in CI

* fix(contracts): fail local abi wrapper on setup errors

* fix(contracts): document workflow permissions

* fix(contracts): remove abi check note from readme

* docs(common): add ci readme for abi checks

* fix(contracts): explain workflow default permissions

* refactor(contracts): group abi compat scripts under ci

* refactor(contracts): remove old abi compat script paths

* fix(contracts): update upgrade check abi helper path

* fix(contracts): correct nested abi compat repo root

* fix(ci): correct broken import in abi-compat exceptions

* refactor(ci): move merge-address-constants to ci/shared

Used by both abi-compat and upgrade-check subsystems.

* refactor(ci): group upgrade-check scripts under ci/upgrade-check

Mirrors the ci/abi-compat/ structure: check.ts (CI entrypoint),
lib.ts (core logic), list.ts (local multi-package report), hints.ts
(domain config).

* fix(ci): harden upgrade-check list.ts error handling

Capture exec errors with truncated output instead of swallowing them.
Clean up worktrees explicitly on failure instead of relying on prune.
Matches the pattern established in abi-compat/list.ts.

* refactor(ci): extract upgrade-check config to match abi-compat pattern

* docs(ci): update readme with upgrade-check and shared entries

* fix(ci): use inline permission comments for zizmor compliance

* fix(ci): remove --force from forge inspect and fix minor code smells

- Remove --force flag from forge inspect in abi-compat/lib.ts to avoid
  redundant recompilation (4x per side per package).
- Simplify printPackageReport return in abi-compat/list.ts.
- Derive valid package names from PACKAGE_CONFIG in upgrade-check
  parseArgs instead of hardcoding strings.

* fix(ci): restore --force on forge inspect to avoid stale cache

Without --force, a prior failed compilation (e.g. before address
constants are generated) leaves error artifacts in forge's cache.
Subsequent runs reuse the cached failure even after the source
files are fixed. Reproduced by: forge clean, attempt compilation
without addresses (fails), generate addresses, run check — forge
returns the cached error for Decryption while other contracts work.

* fix(ci): extract JSON from forge stdout to handle compilation preamble

Forge may prepend compilation progress text to stdout on the first
invocation in a clean directory. This caused Decryption (the first
contract checked) to fail JSON.parse in CI while subsequent contracts
succeeded from cache. Extract the JSON array from the output instead
of parsing the whole string, matching the approach used by the
upgrade-check bytecode extraction.

* fix(common): include deployed ABI compat contracts

* chore(common): retrigger ci

* refactor(common): derive abi compat coverage from manifests

* fix(ci): log abi inspect parse failures

Author: Eikix

.github/workflows/contracts-abi-compat-check.yml

@@ -0,0 +1,109 @@
+name: contracts-abi-compat-check
+
+# Default to no token permissions at the workflow level; each job opts into the
+# minimum read scopes it needs.
+permissions: {}
+
+on:
+  pull_request:
+
+env:
+  ABI_COMPAT_FROM_TAG: v0.11.1
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+jobs:
+  check-changes:
+    name: contracts-abi-compat-check/check-changes
+    permissions:
+      contents: read # Required by actions/checkout to clone the repository
+      pull-requests: read # Required by dorny/paths-filter to inspect changed files
+    runs-on: ubuntu-latest
+    outputs:
+      packages: ${{ steps.filter.outputs.changes }}
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+        with:
+          persist-credentials: "false"
+      - uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36
+        id: filter
+        with:
+          filters: |
+            host-contracts:
+              - .github/workflows/contracts-abi-compat-check.yml
+              - ci/abi-compat/**
+              - ci/shared/**
+              - host-contracts/**
+            gateway-contracts:
+              - .github/workflows/contracts-abi-compat-check.yml
+              - ci/abi-compat/**
+              - ci/shared/**
+              - gateway-contracts/**
+
+  check:
+    name: contracts-abi-compat-check/${{ matrix.package }}
+    needs: check-changes
+    if: ${{ needs.check-changes.outputs.packages != '[]' }}
+    permissions:
+      contents: read # Required by actions/checkout to clone the PR branch and baseline tag
+    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
+        with:
+          persist-credentials: "false"
+
+      - name: Checkout baseline
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+        with:
+          ref: ${{ env.ABI_COMPAT_FROM_TAG }}
+          path: baseline
+          persist-credentials: "false"
+
+      - name: Install Bun
+        uses: oven-sh/setup-bun@735343b667d3e6f658f44d0eca948eb6282f2b76
+
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@82dee4ba654bd2146511f85f0d013af94670c4de
+
+      - 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: |
+          (cd "$PACKAGE" && make ensure-addresses)
+          (cd "baseline/$PACKAGE" && make ensure-addresses)
+          bun ci/shared/merge-address-constants.ts "baseline/$PACKAGE/addresses" "$PACKAGE/addresses"
+          cp "$PACKAGE/foundry.toml" "baseline/$PACKAGE/foundry.toml"
+
+      - name: Run ABI compatibility check
+        env:
+          PACKAGE: ${{ matrix.package }}
+        run: bun ci/abi-compat/check.ts "baseline/$PACKAGE" "$PACKAGE" "$PACKAGE"

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

@@ -34,15 +34,13 @@ jobs:
           filters: |
             host-contracts:
               - .github/workflows/contracts-upgrade-version-check.yml
-              - ci/check-upgrade-versions.ts
-              - ci/merge-address-constants.ts
-              - ci/upgrade-version-check-lib.ts
+              - ci/upgrade-check/**
+              - ci/shared/**
               - host-contracts/**
             gateway-contracts:
               - .github/workflows/contracts-upgrade-version-check.yml
-              - ci/check-upgrade-versions.ts
-              - ci/merge-address-constants.ts
-              - ci/upgrade-version-check-lib.ts
+              - ci/upgrade-check/**
+              - ci/shared/**
               - gateway-contracts/**
 
   check:
@@ -110,11 +108,11 @@ jobs:
           # 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"
+          bun ci/shared/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"
+        run: bun ci/upgrade-check/check.ts "baseline/$PACKAGE" "$PACKAGE"

ci/README.md

@@ -0,0 +1,5 @@
+# CI Scripts
+
+- [`abi-compat/`](./abi-compat/README.md): contract ABI compatibility checks
+- [`upgrade-check/`](./upgrade-check/): contract upgrade version checks
+- [`shared/`](./shared/): utilities shared across CI subsystems

ci/abi-compat/README.md

@@ -0,0 +1,24 @@
+# ABI Compatibility
+
+ABI coverage is derived from each package's `upgrade-manifest.json`.
+Stable-surface policy lives in [`config.ts`](./config.ts): initializer, ownership, upgrade,
+and other intentionally non-public entrypoints are excluded there.
+
+Compare the stable contract ABI surface between two refs locally with:
+
+```bash
+bun ci/abi-compat/list.ts --from v0.11.1 --to v0.12.0-0
+```
+
+Limit the scope with:
+
+```bash
+bun ci/abi-compat/list.ts --from v0.11.1 --to v0.12.0-0 --package host-contracts
+bun ci/abi-compat/list.ts --from v0.11.1 --to v0.12.0-0 --package gateway-contracts
+```
+
+Use the lower-level checker when both package directories are already prepared:
+
+```bash
+bun ci/abi-compat/check.ts <baseline-pkg-dir> <target-pkg-dir> <host-contracts|gateway-contracts>
+```

ci/abi-compat/check.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env bun
+import { PACKAGE_CONFIG, type PackageName } from "./config";
+import { collectAbiCompatResults } from "./lib";
+
+const [baselineDir, targetDir, pkg] = process.argv.slice(2) as [
+  string | undefined,
+  string | undefined,
+  PackageName | undefined,
+];
+
+if (!baselineDir || !targetDir || !pkg || !(pkg in PACKAGE_CONFIG)) {
+  console.error(
+    "Usage: bun ci/abi-compat/check.ts <baseline-pkg-dir> <target-pkg-dir> <host-contracts|gateway-contracts>",
+  );
+  process.exit(1);
+}
+
+const results = collectAbiCompatResults(baselineDir, targetDir, pkg);
+let errors = 0;
+
+for (const result of results) {
+  console.log(`::group::Checking ${result.name}`);
+  try {
+    if (!result.baselineExists) {
+      console.log(`Skipping ${result.name} (new contract, not in baseline)`);
+      continue;
+    }
+
+    console.log(
+      `${result.name}: ${result.baselineStableCount} stable baseline ABI entries, ${result.targetStableCount} stable target ABI entries`,
+    );
+
+    for (const error of result.errors) {
+      console.error(`::error::${error}`);
+      errors++;
+    }
+
+    for (const signature of result.missing) {
+      console.error(`::error::${result.name} missing stable ABI signature: ${signature}`);
+      errors++;
+    }
+
+    if (result.allowedMissing.length > 0) {
+      console.log(`${result.name}: accepted stable ABI exceptions`);
+      for (const signature of result.allowedMissing) {
+        console.log(`  ~ ${signature}`);
+      }
+    }
+
+    if (result.added.length > 0) {
+      console.log(`${result.name}: added stable ABI entries`);
+      for (const signature of result.added) {
+        console.log(`  + ${signature}`);
+      }
+    }
+
+    if (result.errors.length === 0 && result.missing.length === 0 && result.added.length === 0) {
+      console.log(`${result.name}: no stable ABI changes`);
+    }
+  } finally {
+    console.log("::endgroup::");
+  }
+}
+
+if (errors > 0) {
+  console.error(`::error::ABI compatibility check failed with ${errors} error(s)`);
+  process.exit(1);
+}
+
+console.log("All contracts passed ABI compatibility checks");

ci/abi-compat/config.ts

@@ -0,0 +1,42 @@
+export type PackageName = "host-contracts" | "gateway-contracts";
+
+export const EXCLUDED_MODIFIERS = new Set([
+  "onlyOwner",
+  "onlyACLOwner",
+  "onlyGatewayOwner",
+  "onlyFromEmptyProxy",
+  "onlyPauser",
+  "onlyCoprocessorTxSender",
+  "onlyKmsTxSender",
+  "onlyRegisteredHostChain",
+  "onlyHandleFromRegisteredHostChain",
+  "onlyDecryptionContract",
+  "onlyInputVerificationContract",
+]);
+
+export const EXCLUDED_FUNCTION_PATTERNS = [
+  /^initialize/,
+  /^reinitializeV\d+$/,
+  /^acceptOwnership$/,
+  /^owner$/,
+  /^transferOwnership$/,
+  /^upgradeToAndCall$/,
+];
+
+// ABI coverage is derived from each package's upgrade-manifest.json.
+// Keep only stable-surface exclusions here.
+export const EXCLUDED_CONTRACT_FUNCTION_PATTERNS: Record<string, RegExp[]> = {
+  HCULimit: [/^checkHCUFor/],
+};
+
+export const PACKAGE_CONFIG: Record<
+  PackageName,
+  {
+    extraDeps?: string;
+  }
+> = {
+  "host-contracts": {
+    extraDeps: "forge soldeer install",
+  },
+  "gateway-contracts": {},
+};

ci/abi-compat/exceptions.ts

@@ -0,0 +1,22 @@
+import type { PackageName } from "./config";
+
+export const ABI_COMPAT_EXCEPTIONS: Partial<Record<PackageName, Partial<Record<string, string[]>>>> = {
+  "host-contracts": {
+    ACL: ["error ExpirationDateBeforeOneHour()"],
+    KMSVerifier: ["event NewContextSet(address[],uint256)"],
+  },
+  "gateway-contracts": {
+    Decryption: [
+      "error AccountNotAllowedToUseCiphertext(bytes32,address)",
+      "error PublicDecryptNotAllowed(bytes32)",
+      "error UserDecryptionNotDelegated(uint256,address,address,address)",
+      "function isDelegatedUserDecryptionReady((address,address),(bytes32,address)[],bytes) returns (bool)",
+    ],
+    GatewayConfig: [
+      "event InitializeGatewayConfig((string,string),(uint256,uint256,uint256,uint256,uint256),(address,address,string,string)[],(address,address,string)[],(address,address,bytes)[])",
+      "event UpdateKmsNodes((address,address,string,string)[],uint256,uint256,uint256,uint256)",
+      "function getPublicDecryptionThreshold() returns (uint256)",
+      "function getUserDecryptionThreshold() returns (uint256)",
+    ],
+  },
+};