Add Superchain interop message passing

.changeset/some-fans-tell.md

@@ -0,0 +1,7 @@
+---
+'@openzeppelin/wizard': patch
+'@openzeppelin/wizard-common': patch
+'@openzeppelin/contracts-mcp': patch
+---
+
+Solidity: Add option for Superchain interop message passing in Custom contracts

packages/common/src/ai/descriptions/solidity.ts

@@ -95,3 +95,10 @@ export const solidityGovernorDescriptions = {
   storage: 'Enable storage of proposal details and enumerability of proposals',
   settings: 'Allow governance to update voting settings (delay, period, proposal threshold)',
 };
+
+export const solidityCustomDescriptions = {
+  crossChainMessaging:
+    'Whether to add an example for Superchain interop message passing. Options are "superchain" or false',
+  crossChainFunctionName:
+    'The name of a custom function that will be callable from another chain, default is "myFunction". Only used if crossChainMessaging is set to "superchain"',
+};

packages/core/solidity/package.json

@@ -25,6 +25,7 @@
     "@openzeppelin/community-contracts": "https://github.com/OpenZeppelin/openzeppelin-community-contracts",
     "@openzeppelin/contracts": "^5.3.0",
     "@openzeppelin/contracts-upgradeable": "^5.3.0",
+    "@eth-optimism/contracts-bedrock": "^0.17.3",
     "@types/node": "^20.0.0",
     "@types/semver": "^7.5.7",
     "ava": "^6.0.0",

packages/core/solidity/remappings.txt

@@ -1,2 +1,3 @@
 @openzeppelin/community-contracts/=node_modules/@openzeppelin/community-contracts/contracts/
 @openzeppelin/contracts-upgradeable/=node_modules/@openzeppelin/contracts-upgradeable/
+@eth-optimism/contracts-bedrock/=node_modules/@eth-optimism/contracts-bedrock/

packages/core/solidity/src/add-superchain-messaging.ts

@@ -0,0 +1,119 @@
+import type { ContractBuilder } from './contract';
+import { type BaseFunction } from './contract';
+import { OptionsError } from './error';
+import type { Access } from './set-access-control';
+import { requireAccessControl } from './set-access-control';
+import { toIdentifier } from './utils/to-identifier';
+
+export function addSuperchainMessaging(c: ContractBuilder, functionName: string, access: Access, pausable: boolean) {
+  const sanitizedFunctionName = safeSanitizeFunctionName(functionName);
+
+  addCustomErrors(c);
+  addCrossDomainMessengerImmutable(c);
+  addOnlyCrossDomainCallbackModifier(c);
+  addSourceFunction(sanitizedFunctionName, access, c, pausable);
+  addDestinationFunction(sanitizedFunctionName, c, pausable);
+}
+
+function safeSanitizeFunctionName(functionName: string) {
+  const sanitizedFunctionName = toIdentifier(functionName, false);
+  if (sanitizedFunctionName.length === 0) {
+    throw new OptionsError({
+      crossChainFunctionName: 'Not a valid function name',
+    });
+  }
+  return sanitizedFunctionName;
+}
+
+function addCustomErrors(c: ContractBuilder) {
+  c.addCustomError('CallerNotL2ToL2CrossDomainMessenger');
+  c.addCustomError('InvalidCrossDomainSender');
+  c.addCustomError('InvalidDestination');
+}
+
+function addCrossDomainMessengerImmutable(c: ContractBuilder) {
+  c.addImportOnly({
+    name: 'IL2ToL2CrossDomainMessenger',
+    path: '@eth-optimism/contracts-bedrock/src/L2/IL2ToL2CrossDomainMessenger.sol',
+    transpiled: false,
+  });
+  c.addImportOnly({
+    name: 'Predeploys',
+    path: '@eth-optimism/contracts-bedrock/src/libraries/Predeploys.sol',
+    transpiled: false,
+  });
+
+  const allowImmutableNatspec = {
+    key: '@custom:oz-upgrades-unsafe-allow',
+    value: 'state-variable-immutable',
+  };
+  c.addVariable(
+    'IL2ToL2CrossDomainMessenger public immutable messenger = IL2ToL2CrossDomainMessenger(Predeploys.L2_TO_L2_CROSS_DOMAIN_MESSENGER);',
+    [allowImmutableNatspec],
+  );
+}
+
+function addOnlyCrossDomainCallbackModifier(c: ContractBuilder) {
+  c.addModifierDefinition({
+    name: 'onlyCrossDomainCallback',
+    code: [
+      'if (msg.sender != address(messenger)) revert CallerNotL2ToL2CrossDomainMessenger();',
+      'if (messenger.crossDomainMessageSender() != address(this)) revert InvalidCrossDomainSender();',
+      '_;',
+    ],
+  });
+}
+
+function addSourceFunction(sanitizedFunctionName: string, access: Access, c: ContractBuilder, pausable: boolean) {
+  const sourceFn: BaseFunction = {
+    name: `call${sanitizedFunctionName.replace(/^(.)/, c => c.toUpperCase())}`,
+    kind: 'public' as const,
+    args: [{ name: 'toChainId', type: 'uint256' }],
+  };
+
+  if (access) {
+    requireAccessControl(c, sourceFn, access, 'CROSSCHAIN_CALLER', 'crossChainCaller');
+  } else {
+    c.setFunctionComments(['/// @dev NOTE: This function is unprotected. Anyone can call this function.'], sourceFn);
+  }
+
+  if (pausable) {
+    c.addModifier('whenNotPaused', sourceFn);
+  }
+
+  c.setFunctionBody(
+    [
+      'if (toChainId == block.chainid) revert InvalidDestination();',
+      `messenger.sendMessage(toChainId, address(this), abi.encodeCall(this.${sanitizedFunctionName}, (/* TODO: Add arguments */)));`,
+    ],
+    sourceFn,
+  );
+}
+
+function addDestinationFunction(sanitizedFunctionName: string, c: ContractBuilder, pausable: boolean) {
+  const destFn: BaseFunction = {
+    name: sanitizedFunctionName,
+    kind: 'external' as const,
+    args: [],
+    argInlineComment: 'TODO: Add arguments',
+  };
+  c.setFunctionComments(
+    [
+      '/**',
+      ' * @dev IMPORTANT: This function trusts contracts at the same address on other chains.',
+      ' * If an unauthorized contract is deployed at the same address on any chain in the Superchain, it could allow',
+      ' * malicious actors to invoke your function from that chain.',
+      " * To prevent this, you must either design the deployer to allow only this contract's bytecode to be deployed",
+      ' * through it, or use CREATE2 from a deployer contract that is itself deployed by an EOA you control.',
+      ' */',
+    ],
+    destFn,
+  );
+
+  c.addModifier('onlyCrossDomainCallback', destFn);
+  if (pausable) {
+    c.addModifier('whenNotPaused', destFn);
+  }
+
+  c.addFunctionCode('// TODO: Implement logic for the function that will be called from another chain', destFn);
+}

packages/core/solidity/src/contract.ts

@@ -9,8 +9,19 @@ export interface Contract {
   functions: ContractFunction[];
   constructorCode: string[];
   constructorArgs: FunctionArgument[];
-  variables: string[];
+  variables: Variable[];
   upgradeable: boolean;
+  customErrors: CustomError[];
+  modifierDefinitions: ModifierDefinition[];
+}
+
+export interface CustomError {
+  name: string;
+}
+
+export interface Variable {
+  code: string;
+  natspecTags?: NatspecTag[];
 }
 
 export type Value = string | number | { lit: string } | { note: string; value: Value };
@@ -35,9 +46,15 @@ export interface Using {
   usingFor: string;
 }
 
+export interface ModifierDefinition {
+  name: string;
+  code: string[];
+}
+
 export interface BaseFunction {
   name: string;
   args: FunctionArgument[];
+  argInlineComment?: string;
   returns?: string[];
   kind: FunctionKind;
   mutability?: FunctionMutability;
@@ -52,7 +69,7 @@ export interface ContractFunction extends BaseFunction {
   comments: string[];
 }
 
-export type FunctionKind = 'internal' | 'public';
+export type FunctionKind = 'internal' | 'public' | 'external';
 export type FunctionMutability = (typeof mutabilityRank)[number];
 
 // Order is important
@@ -82,10 +99,12 @@ export class ContractBuilder implements Contract {
 
   readonly constructorArgs: FunctionArgument[] = [];
   readonly constructorCode: string[] = [];
-  readonly variableSet: Set<string> = new Set();
+  readonly customErrorSet: Set<string> = new Set();
 
   private parentMap: Map<string, Parent> = new Map<string, Parent>();
   private functionMap: Map<string, ContractFunction> = new Map();
+  private modifierDefinitionsMap: Map<string, ModifierDefinition> = new Map<string, ModifierDefinition>();
+  private variableMap: Map<string, Variable> = new Map<string, Variable>();
 
   constructor(name: string) {
     this.name = toIdentifier(name, true);
@@ -113,8 +132,16 @@ export class ContractBuilder implements Contract {
     return [...this.functionMap.values()];
   }
 
-  get variables(): string[] {
-    return [...this.variableSet];
+  get variables(): Variable[] {
+    return [...this.variableMap.values()];
+  }
+
+  get customErrors(): CustomError[] {
+    return [...this.customErrorSet].map(name => ({ name }));
+  }
+
+  get modifierDefinitions(): ModifierDefinition[] {
+    return [...this.modifierDefinitionsMap.values()];
   }
 
   addParent(contract: ImportContract, params: Value[] = []): boolean {
@@ -214,9 +241,21 @@ export class ContractBuilder implements Contract {
   /**
    * Note: The type in the variable is not currently transpiled, even if it refers to a contract
    */
-  addVariable(code: string): boolean {
-    const present = this.variableSet.has(code);
-    this.variableSet.add(code);
+  addVariable(code: string, natspecTags?: NatspecTag[]): boolean {
+    const present = this.variableMap.has(code);
+    this.variableMap.set(code, { code, natspecTags });
+    return !present;
+  }
+
+  addCustomError(name: string): boolean {
+    const present = this.customErrorSet.has(name);
+    this.customErrorSet.add(name);
+    return !present;
+  }
+
+  addModifierDefinition(modifier: ModifierDefinition): boolean {
+    const present = this.modifierDefinitionsMap.has(modifier.name);
+    this.modifierDefinitionsMap.set(modifier.name, modifier);
     return !present;
   }
 }

packages/core/solidity/src/custom.test.ts

@@ -1,4 +1,5 @@
 import test from 'ava';
+import type { OptionsError } from '.';
 import { custom } from '.';
 
 import type { CustomOptions } from './custom';
@@ -66,6 +67,27 @@ testCustom('access control managed', {
   access: 'managed',
 });
 
+testCustom('superchain messaging', {
+  crossChainMessaging: 'superchain',
+});
+
+testCustom('superchain messaging ownable pausable', {
+  crossChainMessaging: 'superchain',
+  access: 'ownable',
+  pausable: true,
+});
+
+test('superchain messaging, invalid function name', async t => {
+  const error = t.throws(() =>
+    buildCustom({
+      name: 'MyContract',
+      crossChainMessaging: 'superchain',
+      crossChainFunctionName: '  ',
+    }),
+  );
+  t.is((error as OptionsError).messages.crossChainFunctionName, 'Not a valid function name');
+});
+
 testCustom('upgradeable uups with access control disabled', {
   // API should override access to true since it is required for UUPS
   access: false,
@@ -81,13 +103,17 @@ testAPIEquivalence('custom API full upgradeable', {
   access: 'roles',
   pausable: true,
   upgradeable: 'uups',
+  crossChainMessaging: 'superchain',
+  crossChainFunctionName: 'myCustomFunction',
 });
 
 testAPIEquivalence('custom API full upgradeable with managed', {
   name: 'CustomContract',
   access: 'managed',
   pausable: true,
   upgradeable: 'uups',
+  crossChainMessaging: 'superchain',
+  crossChainFunctionName: 'myCustomFunction',
 });
 
 test('custom API assert defaults', async t => {