feat: check for protocol version for interop

Author: vasyl-ivanchuk

src/adapters/__tests__/adapter-harness.ts

@@ -38,6 +38,9 @@ const IL1AssetRouter = new Interface(IL1AssetRouterABI as any);
 const IL1Nullifier = new Interface(IL1NullifierABI as any);
 const IERC20 = new Interface(IERC20ABI as any);
 const L2NativeTokenVault = new Interface(L2NativeTokenVaultABI as any);
+const IChainTypeManager = new Interface([
+  'function getSemverProtocolVersion() view returns (uint32,uint32,uint32)',
+]);
 
 const lower = (value: string) => value.toLowerCase();
 type ResultValue = unknown | unknown[];
@@ -77,6 +80,7 @@ export const ADAPTER_TEST_ADDRESSES = {
   l1Nullifier: '0xc000000000000000000000000000000000000000' as Address,
   l1NativeTokenVault: '0xd000000000000000000000000000000000000000' as Address,
   baseTokenFor324: '0xbee0000000000000000000000000000000000000' as Address,
+  chainTypeManager: '0xe000000000000000000000000000000000000000' as Address,
   signer: '0x1111111111111111111111111111111111111111' as Address,
 } as const;
 
@@ -365,6 +369,26 @@ function seedDefaults(registry: CallRegistry, baseToken: Address) {
     ADAPTER_TEST_ADDRESSES.l1NativeTokenVault,
   );
   registry.set(ADAPTER_TEST_ADDRESSES.bridgehub, IBridgehub, 'baseToken', baseToken, [324n]);
+  registry.set(
+    ADAPTER_TEST_ADDRESSES.bridgehub,
+    IBridgehub,
+    'chainTypeManager',
+    ADAPTER_TEST_ADDRESSES.chainTypeManager,
+    [324n],
+  );
+  registry.set(
+    ADAPTER_TEST_ADDRESSES.bridgehub,
+    IBridgehub,
+    'chainTypeManager',
+    ADAPTER_TEST_ADDRESSES.chainTypeManager,
+    [325n],
+  );
+  registry.set(
+    ADAPTER_TEST_ADDRESSES.chainTypeManager,
+    IChainTypeManager,
+    'getSemverProtocolVersion',
+    [0n, 31n, 0n],
+  );
 }
 
 export function createEthersHarness(opts: BaseOpts = {}): EthersHarness {

src/adapters/__tests__/client.test.ts

@@ -1,13 +1,17 @@
 import { describe, it, expect } from 'bun:test';
+import { Interface } from 'ethers';
 
 import {
   ADAPTER_TEST_ADDRESSES,
   type AdapterHarness,
   describeForAdapters,
 } from './adapter-harness';
 import type { Address } from '../../core/types/primitives';
+import { IBridgehubABI } from '../../core/abi';
 
 const toLower = (value: Address) => value.toLowerCase();
+const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000' as Address;
+const IBridgehub = new Interface(IBridgehubABI as any);
 
 function assertContractAddress(harness: AdapterHarness, contract: any, expected: Address) {
   if (harness.kind === 'ethers') {
@@ -66,6 +70,36 @@ describeForAdapters('adapters client', (kind, factory) => {
     expect(toLower(baseToken)).toBe(toLower(ADAPTER_TEST_ADDRESSES.baseTokenFor324));
   });
 
+  it('getSemverProtocolVersion resolves the registered CTM semver', async () => {
+    const harness = factory();
+    if (harness.kind !== 'ethers') {
+      expect('getSemverProtocolVersion' in harness.client).toBe(false);
+      return;
+    }
+
+    const semver = await harness.client.getSemverProtocolVersion();
+    expect(semver).toEqual([0, 31, 0]);
+  });
+
+  it('getSemverProtocolVersion returns null when chain CTM is not registered', async () => {
+    const harness = factory();
+    if (harness.kind !== 'ethers') {
+      expect('getSemverProtocolVersion' in harness.client).toBe(false);
+      return;
+    }
+
+    harness.registry.set(
+      ADAPTER_TEST_ADDRESSES.bridgehub,
+      IBridgehub,
+      'chainTypeManager',
+      ZERO_ADDRESS,
+      [324n],
+    );
+
+    const semver = await harness.client.getSemverProtocolVersion();
+    expect(semver).toBeNull();
+  });
+
   it('respects manual overrides without hitting discovery calls', async () => {
     const overrides = {
       bridgehub: '0x1000000000000000000000000000000000000001',

src/adapters/__tests__/interop/resource.test.ts

@@ -1,7 +1,9 @@
 import { describe, it, expect } from 'bun:test';
+import { Interface } from 'ethers';
 
 import { createInteropResource } from '../../ethers/resources/interop/index.ts';
 import {
+  ADAPTER_TEST_ADDRESSES,
   createEthersHarness,
   setErc20Allowance,
   setL2TokenRegistration,
@@ -12,6 +14,9 @@ const RECIPIENT = '0x2222222222222222222222222222222222222222' as Address;
 const TX_HASH = `0x${'aa'.repeat(32)}` as Hex;
 const ERC20_TOKEN = '0x3333333333333333333333333333333333333333' as Address;
 const ASSET_ID = `0x${'11'.repeat(32)}` as Hex;
+const IChainTypeManager = new Interface([
+  'function getSemverProtocolVersion() view returns (uint32,uint32,uint32)',
+]);
 
 describe('adapters/interop/resource', () => {
   it('status returns SENT when source receipt is not yet available', async () => {
@@ -125,4 +130,29 @@ describe('adapters/interop/resource', () => {
     expect(txCountCalls).toBe(0);
     expect(sentNonces).toEqual([42, 43, 44]);
   });
+
+  it('prepare fails when protocol minor version is below 31', async () => {
+    const harness = createEthersHarness();
+    const interop = createInteropResource(harness.client);
+
+    harness.registry.set(
+      ADAPTER_TEST_ADDRESSES.chainTypeManager,
+      IChainTypeManager,
+      'getSemverProtocolVersion',
+      [0n, 30n, 0n],
+    );
+
+    let caught: unknown;
+    try {
+      await interop.prepare({
+        dstChain: harness.l2 as any,
+        actions: [{ type: 'sendNative', to: RECIPIENT, amount: 1n }],
+      });
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeDefined();
+    expect(String(caught)).toMatch(/interop requires protocol version 31\+/i);
+  });
 });

src/adapters/ethers/client.ts

@@ -28,9 +28,16 @@ import {
 import { createError } from '../../core/errors/factory';
 import { OP_DEPOSITS, OP_CLIENT } from '../../core/types';
 import { createErrorHandlers } from './errors/error-ops';
+import { FORMAL_ETH_ADDRESS } from '../../core/constants';
 
 // error handling
 const { wrapAs, wrap } = createErrorHandlers('client');
+// Single function, instead of the whole ABI. If more fns are needed, consider adding the whole ABI.
+const ChainTypeManagerABI = [
+  'function getSemverProtocolVersion() view returns (uint32,uint32,uint32)',
+] as const;
+
+export type ProtocolVersion = readonly [number, number, number];
 
 export interface ResolvedAddresses {
   bridgehub: Address;
@@ -84,6 +91,9 @@ export interface EthersClient {
   /** Lookup the base token for a given chain ID via Bridgehub.baseToken(chainId) */
   baseToken(chainId: bigint): Promise<Address>;
 
+  /** Read semver protocol version for the CTM of a chain. */
+  getProtocolVersion(chainId?: bigint): Promise<ProtocolVersion>;
+
   /** Get a signer connected to a specific provider */
   signerFor(target?: 'l1' | AbstractProvider): Signer;
 }
@@ -298,6 +308,48 @@ export function createEthersClient(args: InitArgs): EthersClient {
     })) as Address;
   }
 
+  async function getProtocolVersion(chainId?: bigint): Promise<ProtocolVersion> {
+    const targetChainId = chainId ?? (await l2.getNetwork()).chainId;
+    const { bridgehub } = await ensureAddresses();
+    const bh = new Contract(bridgehub, IBridgehubABI, l1);
+
+    const chainTypeManager = (await wrapAs(
+      'CONTRACT',
+      OP_CLIENT.getSemverProtocolVersion,
+      () => bh.chainTypeManager(targetChainId),
+      {
+        ctx: { where: 'bridgehub.chainTypeManager', bridgehub, chainId: targetChainId },
+        message: 'Failed to read chain type manager.',
+      },
+    )) as Address;
+
+    if (chainTypeManager.toLowerCase() === FORMAL_ETH_ADDRESS) {
+      throw createError('STATE', {
+        resource: 'client',
+        operation: OP_CLIENT.getSemverProtocolVersion,
+        message: 'No registered chain type manager for the chain.',
+        context: { chainId },
+      });
+    }
+
+    const ctm = new Contract(chainTypeManager, ChainTypeManagerABI, l1);
+    const semver = (await wrapAs(
+      'CONTRACT',
+      OP_CLIENT.getSemverProtocolVersion,
+      () => ctm.getSemverProtocolVersion(),
+      {
+        ctx: {
+          where: 'chainTypeManager.getSemverProtocolVersion',
+          chainId: targetChainId,
+          chainTypeManager,
+        },
+        message: 'Failed to read semver protocol version.',
+      },
+    )) as [number, number, number];
+
+    return semver;
+  }
+
   /** Signer helpers */
   function signerFor(target?: 'l1' | AbstractProvider): Signer {
     if (target === 'l1') {
@@ -323,6 +375,7 @@ export function createEthersClient(args: InitArgs): EthersClient {
     contracts,
     refresh,
     baseToken,
+    getProtocolVersion,
     signerFor,
   };
 

src/adapters/ethers/resources/interop/context.ts

@@ -1,7 +1,7 @@
 // src/adapters/ethers/resources/interop/context.ts
 import type { AbstractProvider } from 'ethers';
 import { Interface } from 'ethers';
-import type { EthersClient } from '../../client';
+import type { EthersClient, ProtocolVersion } from '../../client';
 import type { Address } from '../../../../core/types/primitives';
 import type { CommonCtx } from '../../../../core/types/flows/base';
 import type { InteropParams } from '../../../../core/types/flows/interop';
@@ -10,6 +10,39 @@ import type { TokensResource } from '../../../../core/types/flows/token';
 import type { AttributesResource } from '../../../../core/resources/interop/attributes/resource';
 import type { ContractsResource } from '../contracts';
 import { IInteropHandlerABI, InteropCenterABI } from '../../../../core/abi';
+import { createError } from '../../../../core/errors/factory';
+import { OP_INTEROP } from '../../../../core/types/errors';
+
+const MIN_INTEROP_PROTOCOL = 31;
+
+async function assertInteropProtocolVersion(
+  client: EthersClient,
+  srcChainId: bigint,
+  dstChainId: bigint,
+): Promise<void> {
+  const [srcProtocolVersion, dstProtocolVersion] = await Promise.all([
+    client.getProtocolVersion(srcChainId),
+    client.getProtocolVersion(dstChainId),
+  ]);
+
+  const assertProtocolVersion = (chainId: bigint, protocolVersion: ProtocolVersion): void => {
+    if (protocolVersion[1] < MIN_INTEROP_PROTOCOL) {
+      throw createError('VALIDATION', {
+        resource: 'interop',
+        operation: OP_INTEROP.context.protocolVersion,
+        message: `Interop requires protocol version 31.0+. Found: ${protocolVersion[1]}.${protocolVersion[2]} for chain: ${chainId}.`,
+        context: {
+          chainId,
+          requiredMinor: MIN_INTEROP_PROTOCOL,
+          semver: protocolVersion,
+        },
+      });
+    }
+  };
+
+  assertProtocolVersion(srcChainId, srcProtocolVersion);
+  assertProtocolVersion(dstChainId, dstProtocolVersion);
+}
 
 // Common context for building interop (L2 -> L2) transactions
 export interface BuildCtx extends CommonCtx {
@@ -54,6 +87,8 @@ export async function commonCtx(
     l2MessageVerification,
   } = await contracts.addresses();
 
+  await assertInteropProtocolVersion(client, chainId, dstChainId);
+
   const [srcBaseToken, dstBaseToken] = await Promise.all([
     client.baseToken(chainId),
     client.baseToken(dstChainId),

src/core/types/errors.ts

@@ -195,6 +195,7 @@ export type TryResult<T> = { ok: true; value: T } | { ok: false; error: ZKsyncEr
 
 export const OP_CLIENT = {
   ensureAddresses: 'client.ensureAddresses',
+  getSemverProtocolVersion: 'client.getSemverProtocolVersion',
 } as const;
 
 // Operation constants for Deposit error contexts
@@ -314,7 +315,10 @@ export const OP_INTEROP = {
   tryWait: 'interop.tryWait',
   finalize: 'interop.finalize',
   tryFinalize: 'interop.tryFinalize',
-
+  context: {
+    chainTypeManager: 'interop.chainTypeManager',
+    protocolVersion: 'interop.protocolVersion',
+  },
   // route-specific ops (keep names aligned with files)
   routes: {
     direct: {