docs: interop + multichain ecosystem tutorials (#150)

Adds two new tutorials:
1. Setup a multichain ecosystem with chains that settle on Gateway
2. Build a crosschain defi app using interop messages

---------

Co-authored-by: Antonio <tonioufa@gmail.com>

Author: sarahschwartz

code/interop-messages/contracts/.gitignore

@@ -0,0 +1,26 @@
+# Node modules
+/node_modules
+
+# Compilation output
+/dist
+
+# pnpm deploy output
+/bundle
+
+# Hardhat Build Artifacts
+/artifacts
+
+# Hardhat compilation (v2) support directory
+/cache
+
+# Typechain output
+/types
+
+# Hardhat coverage reports
+/coverage
+
+# Environment
+.env
+
+# Deployments
+ignition/deployments

code/interop-messages/contracts/bun.lock

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.27;
+
+import { ERC20 } from '@openzeppelin/contracts/token/ERC20/ERC20.sol';
+import { Ownable } from '@openzeppelin/contracts/access/Ownable.sol';
+import { IMessageVerification } from '@matterlabs/zksync-contracts/contracts/l1-contracts/state-transition/chain-interfaces/IMessageVerification.sol';
+import { L2Message } from '@matterlabs/zksync-contracts/contracts/l1-contracts/common/Messaging.sol';
+
+contract InteropToken is ERC20, Ownable {
+  // mapping of chain IDs to the approved staking contract address
+  mapping(uint256 => address) public approvedStakingContracts;
+
+  // mapping of addresses to if they have minted tokens or not
+  mapping(address => bool) public addressesThatMinted;
+
+  // mapping of chain IDs to number of adresses that have minted some tokens
+  mapping(uint256 => uint256) public rewardsByChain;
+
+  // the chain ID with the most rewards
+  uint256 public winningChainId;
+  address constant L2_MESSAGE_VERIFICATION_ADDRESS = 0x0000000000000000000000000000000000010009;
+
+  IMessageVerification public l2MessageVerifier = IMessageVerification(L2_MESSAGE_VERIFICATION_ADDRESS);
+
+  constructor(
+    uint256[] memory _chainIds,
+    address[] memory _stakingContracts
+  ) ERC20('InteropToken', 'INTR') Ownable(msg.sender) {
+    require(_chainIds.length == _stakingContracts.length, 'Length mismatch');
+    for (uint256 i = 0; i < _chainIds.length; ++i) {
+      require(_stakingContracts[i] != address(0), 'Zero address used');
+      require(approvedStakingContracts[_chainIds[i]] == address(0), 'Staking contract address already set');
+      approvedStakingContracts[_chainIds[i]] = _stakingContracts[i];
+    }
+  }
+
+  function mint(
+    uint256 _sourceChainId,
+    uint256 _l1BatchNumber,
+    uint256 _l2MessageIndex,
+    L2Message calldata _l2MessageData,
+    bytes32[] calldata _proof
+  ) external {
+    // token can only be minted once per address
+    require(addressesThatMinted[msg.sender] == false, 'Token already minted');
+    require(approvedStakingContracts[_sourceChainId] == _l2MessageData.sender, 'Message origin not approved');
+    bool result = checkMessageProof(_sourceChainId, _l1BatchNumber, _l2MessageIndex, _l2MessageData, _proof);
+    require(result == true, 'Message not verified');
+    address sender = abi.decode(_l2MessageData.data, (address));
+    require(sender == msg.sender, 'Message sender is not depositor');
+    rewardsByChain[_sourceChainId]++;
+    if (rewardsByChain[_sourceChainId] > rewardsByChain[winningChainId]) {
+      winningChainId = _sourceChainId;
+    }
+    addressesThatMinted[msg.sender] = true;
+    _mint(msg.sender, 1);
+  }
+
+  function checkMessageProof(
+    uint256 _sourceChainId,
+    uint256 _l1BatchNumber,
+    uint256 _l2MessageIndex,
+    L2Message calldata _l2MessageData,
+    bytes32[] calldata _proof
+  ) public view returns (bool) {
+    bool result = l2MessageVerifier.proveL2MessageInclusionShared(
+      _sourceChainId,
+      _l1BatchNumber,
+      _l2MessageIndex,
+      _l2MessageData,
+      _proof
+    );
+    return result;
+  }
+}

code/interop-messages/contracts/contracts/InteropToken.sol

@@ -0,0 +1,35 @@
+//SPDX-License-Identifier: Unlicense
+pragma solidity ^0.8.21;
+import { IL1Messenger } from '@matterlabs/zksync-contracts/contracts/system-contracts/interfaces/IL1Messenger.sol';
+
+contract Staking {
+  address constant L2_TO_L1_MESSENGER_SYSTEM_CONTRACT_ADDR = 0x0000000000000000000000000000000000008008;
+  IL1Messenger public L1Messenger = IL1Messenger(L2_TO_L1_MESSENGER_SYSTEM_CONTRACT_ADDR);
+
+  struct Deposit {
+    uint256 amount;
+    bool madeFirstDeposit;
+  }
+
+  // mapping to address to deposit amount and timestamp
+  mapping(address => Deposit) public deposits;
+
+  function deposit() external payable {
+    require(msg.value > 0, 'no amount deposited');
+    Deposit memory lastDeposit = deposits[msg.sender];
+    deposits[msg.sender].amount = lastDeposit.amount + msg.value;
+    if (lastDeposit.madeFirstDeposit != true) {
+      deposits[msg.sender].madeFirstDeposit = true;
+      bytes memory message = abi.encode(msg.sender);
+      L1Messenger.sendToL1(message);
+    }
+  }
+
+  function withdraw() external {
+    Deposit memory lastDeposit = deposits[msg.sender];
+    require(lastDeposit.amount > 0, 'no amount deposited');
+    deposits[msg.sender].amount = 0;
+    (bool sent, ) = msg.sender.call{ value: lastDeposit.amount }('');
+    require(sent, 'send failed');
+  }
+}

code/interop-messages/contracts/contracts/Staking.sol

@@ -0,0 +1,58 @@
+import type { HardhatUserConfig } from 'hardhat/config';
+import hardhatToolboxMochaEthersPlugin from '@nomicfoundation/hardhat-toolbox-mocha-ethers';
+import hardhatKeystore from '@nomicfoundation/hardhat-keystore';
+import { configVariable } from 'hardhat/config';
+
+const config: HardhatUserConfig = {
+  plugins: [hardhatToolboxMochaEthersPlugin, hardhatKeystore],
+  solidity: {
+    profiles: {
+      default: {
+        version: '0.8.28',
+      },
+      production: {
+        version: '0.8.28',
+        settings: {
+          optimizer: {
+            enabled: true,
+            runs: 200,
+          },
+        },
+      },
+    },
+  },
+  ignition: {
+    requiredConfirmations: 1,
+  },
+  networks: {
+    hardhatMainnet: {
+      type: 'edr-simulated',
+      chainType: 'l1',
+    },
+    zksyncGateway: {
+      type: 'http',
+      url: 'http://localhost:3150',
+      chainType: 'generic',
+    },
+    stakingChain1: {
+      type: 'http',
+      url: 'http://localhost:3050',
+      chainType: 'generic',
+      accounts: [configVariable('WALLET_PRIVATE_KEY')],
+    },
+    stakingChain2: {
+      type: 'http',
+      url: 'http://localhost:3250',
+      chainType: 'generic',
+      accounts: [configVariable('WALLET_PRIVATE_KEY')],
+    },
+    rewardsChain: {
+      type: 'http',
+      url: 'http://localhost:3350',
+      chainType: 'generic',
+      accounts: [configVariable('WALLET_PRIVATE_KEY')],
+    },
+  },
+};
+
+export default config;

code/interop-messages/contracts/hardhat.config.ts

@@ -0,0 +1,17 @@
+import { buildModule } from '@nomicfoundation/hardhat-ignition/modules';
+
+const STAKING_CHAIN_1_CONTRACT_ADDRESS = '0x...';
+const STAKING_CHAIN_2_CONTRACT_ADDRESS = '0x...';
+
+// make sure chain ids match the chains you created in the ecosystem setup
+const STAKING_CHAIN_1_ID = '34234';
+const STAKING_CHAIN_2_ID = '5328';
+
+export default buildModule('InteropTokenModule', (m) => {
+  const approvedChainIds = [STAKING_CHAIN_1_ID, STAKING_CHAIN_2_ID];
+  const approvedStakingContracts = [STAKING_CHAIN_1_CONTRACT_ADDRESS, STAKING_CHAIN_2_CONTRACT_ADDRESS];
+  console.log('Approved staking contracts:', approvedStakingContracts);
+  const counter = m.contract('InteropToken', [approvedChainIds, approvedStakingContracts]);
+
+  return { counter };
+});

code/interop-messages/contracts/ignition/modules/InteropToken.ts

@@ -0,0 +1,7 @@
+import { buildModule } from '@nomicfoundation/hardhat-ignition/modules';
+
+export default buildModule('StakingModule', (m) => {
+  const counter = m.contract('Staking');
+
+  return { counter };
+});

code/interop-messages/contracts/ignition/modules/Staking.ts

@@ -0,0 +1,33 @@
+{
+  "name": "contracts",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "compile": "hardhat compile",
+    "deploy:staking": "hardhat ignition deploy ignition/modules/Staking.ts",
+    "deploy:token": "hardhat ignition deploy ignition/modules/InteropToken.ts --network rewardsChain",
+    "interop": "hardhat run ./scripts/interop-test.ts"
+  },
+  "devDependencies": {
+    "@matterlabs/zksync-contracts": "^29.0.0",
+    "@nomicfoundation/hardhat-ignition": "^3.0.0",
+    "@nomicfoundation/hardhat-keystore": "^3.0.1",
+    "@nomicfoundation/hardhat-toolbox-mocha-ethers": "^3.0.0",
+    "@nomicfoundation/hardhat-toolbox-viem": "^5.0.0",
+    "@openzeppelin/contracts": "^5.4.0",
+    "@types/chai": "^4.3.20",
+    "@types/chai-as-promised": "^8.0.2",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^22.18.0",
+    "chai": "^5.3.3",
+    "ethers": "^6.15.0",
+    "forge-std": "github:foundry-rs/forge-std#v1.9.4",
+    "hardhat": "^3.0.1",
+    "mocha": "^11.7.1",
+    "typescript": "~5.8.0",
+    "zksync-ethers": "^6.21.0"
+  },
+  "dependencies": {
+    "dotenv": "^17.2.1"
+  }
+}

code/interop-messages/contracts/package.json

@@ -0,0 +1,13 @@
+/* Based on https://github.com/tsconfig/bases/blob/501da2bcd640cf95c95805783e1012b992338f28/bases/node22.json */
+{
+  "compilerOptions": {
+    "lib": ["es2023"],
+    "module": "node16",
+    "target": "es2022",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "moduleResolution": "node16",
+    "outDir": "dist"
+  }
+}