0
# Cross-Chain Integration
1

2
OpenZeppelin Contracts provides cross-chain messaging utilities that enable smart contracts to communicate across different blockchain networks, supporting various Layer 2 solutions and bridges.
3

4
## Core Imports
5

6
Import cross-chain contracts using Solidity import statements:
7

8
```solidity
9
import "@openzeppelin/contracts/crosschain/CrossChainEnabled.sol";
10
import "@openzeppelin/contracts/crosschain/optimism/CrossChainEnabledOptimism.sol";
11
import "@openzeppelin/contracts/crosschain/arbitrum/CrossChainEnabledArbitrumL1.sol";
12
import "@openzeppelin/contracts/crosschain/arbitrum/CrossChainEnabledArbitrumL2.sol";
13
import "@openzeppelin/contracts/crosschain/polygon/CrossChainEnabledPolygonChild.sol";
14
import "@openzeppelin/contracts/crosschain/amb/CrossChainEnabledAMB.sol";
15
```
16

17
## Capabilities
18

19
### Base Cross-Chain Framework
20

21
Core abstraction for cross-chain message handling that provides a unified interface across different bridge implementations.
22

23
```solidity { .api }
24
abstract contract CrossChainEnabled {
25
    function _isCrossChain() internal view virtual returns (bool);
26
    function _crossChainSender() internal view virtual returns (address);
27
}
28
```
29

30
**Errors:**
31
- `NotCrossChainCall()` - Called when function is not executed from cross-chain context
32
- `InvalidCrossChainSender(address actual, address expected)` - Invalid cross-chain message sender
33

34
**Modifiers:**
35
- `onlyCrossChain()` - Restricts function to cross-chain calls only
36
- `onlyCrossChainSender(address expected)` - Restricts to specific cross-chain sender
37

38
### Optimism Integration
39

40
Cross-chain messaging integration for Optimism Layer 2 network using the Optimism bridge.
41

42
```solidity { .api }
43
abstract contract CrossChainEnabledOptimism is CrossChainEnabled {
44
    constructor(address crossChainMessenger);
45
    
46
    function crossChainMessenger() public view virtual returns (address);
47
}
48
```
49

50
**Usage Example:**
51

52
```solidity
53
contract OptimismContract is CrossChainEnabledOptimism {
54
    constructor() CrossChainEnabledOptimism(0x25ace71c97B33Cc4729CF772ae268934F7ab5fA1) {}
55
    
56
    function handleCrossChainMessage(uint256 data) external onlyCrossChain {
57
        address sender = _crossChainSender();
58
        // Process cross-chain message
59
    }
60
}
61
```
62

63
### Arbitrum L1 Integration
64

65
Cross-chain messaging for Arbitrum Layer 1 contracts that need to communicate with Arbitrum Layer 2.
66

67
```solidity { .api }
68
abstract contract CrossChainEnabledArbitrumL1 is CrossChainEnabled {
69
    constructor(address bridge);
70
    
71
    function bridge() public view virtual returns (address);
72
}
73
```
74

75
### Arbitrum L2 Integration
76

77
Cross-chain messaging for Arbitrum Layer 2 contracts communicating with Layer 1.
78

79
```solidity { .api }
80
abstract contract CrossChainEnabledArbitrumL2 is CrossChainEnabled {
81
    constructor(address arbSys);
82
    
83
    function arbSys() public view virtual returns (address);
84
}
85
```
86

87
### Polygon PoS Bridge Integration
88

89
Cross-chain integration for Polygon Proof-of-Stake bridge enabling communication between Ethereum mainnet and Polygon.
90

91
```solidity { .api }
92
abstract contract CrossChainEnabledPolygonChild is CrossChainEnabled {
93
    constructor(address fxChild);
94
    
95
    function fxChild() public view virtual returns (address);
96
}
97
```
98

99
### Arbitrary Message Bridge (AMB)
100

101
Generic cross-chain messaging through Arbitrary Message Bridge protocol, supporting various bridge implementations.
102

103
```solidity { .api }
104
abstract contract CrossChainEnabledAMB is CrossChainEnabled {
105
    constructor(address bridge);
106
    
107
    function bridge() public view virtual returns (address);
108
}
109
```
110

111
## Cross-Chain Patterns
112

113
### Synchronized State Management
114

115
Maintain synchronized state across multiple chains:
116

117
```solidity
118
contract MultiChainRegistry is CrossChainEnabledOptimism {
119
    mapping(bytes32 => address) public registry;
120
    
121
    event CrossChainRegistryUpdate(bytes32 indexed key, address indexed value, address indexed sender);
122
    
123
    function updateRegistry(bytes32 key, address value) external onlyCrossChain {
124
        address sender = _crossChainSender();
125
        registry[key] = value;
126
        emit CrossChainRegistryUpdate(key, value, sender);
127
    }
128
    
129
    function localUpdate(bytes32 key, address value) external {
130
        registry[key] = value;
131
        // Trigger cross-chain update to other networks
132
    }
133
}
134
```
135

136
### Cross-Chain Access Control
137

138
Implement access control that works across multiple chains:
139

140
```solidity
141
contract CrossChainAccessControl is AccessControl, CrossChainEnabledOptimism {
142
    bytes32 public constant CROSS_CHAIN_ADMIN = keccak256("CROSS_CHAIN_ADMIN");
143
    
144
    modifier onlyCrossChainAdmin() {
145
        require(
146
            hasRole(CROSS_CHAIN_ADMIN, _msgSender()) || 
147
            (_isCrossChain() && hasRole(CROSS_CHAIN_ADMIN, _crossChainSender())),
148
            "Not cross-chain admin"
149
        );
150
        _;
151
    }
152
    
153
    function crossChainGrantRole(bytes32 role, address account) external onlyCrossChainAdmin {
154
        _grantRole(role, account);
155
    }
156
}
157
```
158

159
### Cross-Chain Token Bridging
160

161
Basic pattern for cross-chain token operations:
162

163
```solidity
164
contract CrossChainToken is ERC20, CrossChainEnabledOptimism {
165
    mapping(uint256 => bool) public processedMessages;
166
    
167
    event CrossChainMint(address indexed to, uint256 amount, uint256 indexed messageId);
168
    event CrossChainBurn(address indexed from, uint256 amount, uint256 indexed messageId);
169
    
170
    function crossChainMint(address to, uint256 amount, uint256 messageId) 
171
        external 
172
        onlyCrossChain 
173
    {
174
        require(!processedMessages[messageId], "Message already processed");
175
        processedMessages[messageId] = true;
176
        
177
        _mint(to, amount);
178
        emit CrossChainMint(to, amount, messageId);
179
    }
180
    
181
    function crossChainBurn(uint256 amount, uint256 messageId) external {
182
        _burn(msg.sender, amount);
183
        emit CrossChainBurn(msg.sender, amount, messageId);
184
        // Trigger cross-chain mint on destination
185
    }
186
}
187
```
188

189
## Security Considerations
190

191
### Message Validation
192

193
Always validate cross-chain messages and their senders:
194

195
```solidity
196
contract SecureCrossChain is CrossChainEnabledOptimism {
197
    address public trustedL1Contract;
198
    
199
    function processMessage(bytes calldata data) external onlyCrossChainSender(trustedL1Contract) {
200
        // Process validated cross-chain message
201
    }
202
}
203
```
204

205
### Replay Attack Prevention
206

207
Implement nonces or message IDs to prevent replay attacks:
208

209
```solidity
210
contract ReplayProtected is CrossChainEnabledOptimism {
211
    mapping(uint256 => bool) public processedMessages;
212
    uint256 public nextMessageId;
213
    
214
    function processMessage(uint256 messageId, bytes calldata data) external onlyCrossChain {
215
        require(!processedMessages[messageId], "Message replayed");
216
        processedMessages[messageId] = true;
217
        // Process message
218
    }
219
}
220
```
221

222
### Bridge-Specific Considerations
223

224
1. **Optimism**: Messages can be replayed on L1, implement proper validation
225
2. **Arbitrum**: Different gas mechanics between L1 and L2
226
3. **Polygon**: FxPortal requires specific message formats
227
4. **AMB**: Bridge-specific validation requirements
228

229
## Supported Networks
230

231
- **Optimism**: Ethereum ↔ Optimism
232
- **Arbitrum**: Ethereum ↔ Arbitrum One/Nova
233
- **Polygon**: Ethereum ↔ Polygon PoS
234
- **xDai**: Ethereum ↔ Gnosis Chain (via AMB)
235
- **Custom Bridges**: Extensible through AMB pattern
236

237
## Best Practices
238

239
1. **Validation**: Always validate cross-chain message authenticity
240
2. **Replay Protection**: Implement message deduplication
241
3. **Gas Management**: Account for different gas costs across chains
242
4. **Error Handling**: Implement robust error handling for failed messages
243
5. **Monitoring**: Monitor cross-chain message delivery
244
6. **Testing**: Thoroughly test cross-chain interactions on testnets