0
# Security Utilities
1

2
Essential security patterns and utilities for protecting smart contracts against common vulnerabilities including reentrancy attacks, access control bypass, signature malleability, and unsafe operations.
3

4
## Capabilities
5

6
### Reentrancy Protection
7

8
Protection against reentrancy attacks through state-based guards that prevent recursive function calls.
9

10
```solidity { .api }
11
/**
12
 * @dev Contract module that helps prevent reentrant calls to a function.
13
 */
14
abstract contract ReentrancyGuard {
15
    /**
16
     * @dev Prevents a contract from calling itself, directly or indirectly.
17
     * Cannot be applied to a function with nonReentrant modifier.
18
     */
19
    modifier nonReentrant();
20
    
21
    /**
22
     * @dev Returns true if the reentrancy guard is currently set to "entered"
23
     */
24
    function _reentrancyGuardEntered() internal view returns (bool);
25
}
26

27
/**
28
 * @dev Variant of {ReentrancyGuard} that uses transient storage for more efficient reentrancy protection.
29
 * Available since Solidity 0.8.24 on networks with EIP-1153 support.
30
 */
31
abstract contract ReentrancyGuardTransient {
32
    /**
33
     * @dev Prevents reentrancy using transient storage for gas efficiency
34
     */
35
    modifier nonReentrant();
36
    
37
    /**
38
     * @dev Returns true if the reentrancy guard is currently set to "entered"
39
     */
40
    function _reentrancyGuardEntered() internal view returns (bool);
41
}
42
```
43

44
**Usage Example:**
45

46
```solidity
47
import "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
48

49
contract MyContract is ReentrancyGuard {
50
    mapping(address => uint256) public balances;
51
    
52
    function withdraw() external nonReentrant {
53
        uint256 amount = balances[msg.sender];
54
        balances[msg.sender] = 0;
55
        payable(msg.sender).transfer(amount);
56
    }
57
}
58
```
59

60
### Emergency Pause Functionality
61

62
Circuit breaker mechanism for emergency stops and controlled contract operations.
63

64
```solidity { .api }
65
/**
66
 * @dev Provides emergency stop mechanism through pausing functionality.
67
 */
68
abstract contract Pausable is Context {
69
    /**
70
     * @dev Returns true if the contract is paused, and false otherwise
71
     */
72
    function paused() public view virtual returns (bool);
73
    
74
    /**
75
     * @dev Triggers stopped state (can only be called when not paused)
76
     */
77
    function _pause() internal virtual whenNotPaused;
78
    
79
    /**
80
     * @dev Returns to normal state (can only be called when paused)
81
     */
82
    function _unpause() internal virtual whenPaused;
83
    
84
    /**
85
     * @dev Modifier to make a function callable only when the contract is not paused
86
     */
87
    modifier whenNotPaused();
88
    
89
    /**
90
     * @dev Modifier to make a function callable only when the contract is paused
91
     */
92
    modifier whenPaused();
93
    
94
    /**
95
     * @dev Throws if the contract is paused
96
     */
97
    function _requireNotPaused() internal view;
98
    
99
    /**
100
     * @dev Throws if the contract is not paused
101
     */
102
    function _requirePaused() internal view; 
103
}
104
```
105

106
**Usage Example:**
107

108
```solidity
109
import "@openzeppelin/contracts/utils/Pausable.sol";
110
import "@openzeppelin/contracts/access/Ownable.sol";
111

112
contract MyContract is Pausable, Ownable {
113
    function emergencyPause() external onlyOwner {
114
        _pause();
115
    }
116
    
117
    function unpause() external onlyOwner {
118
        _unpause(); 
119
    }
120
    
121
    function criticalFunction() external whenNotPaused {
122
        // This function can only be called when contract is not paused
123
    }
124
}
125
```
126

127
### Cryptographic Security Utilities
128

129
Secure cryptographic operations for signature verification, merkle proofs, and ECDSA recovery.
130

131
```solidity { .api }
132
/**
133
 * @dev Elliptic Curve Digital Signature Algorithm (ECDSA) operations.
134
 */
135
library ECDSA {
136
    /**
137
     * @dev Recovers the signer of the signed message hash
138
     */
139
    function recover(bytes32 hash, bytes memory signature) internal pure returns (address);
140
    
141
    /**
142
     * @dev Attempts to recover signer, returns (address, error) tuple
143
     */
144
    function tryRecover(bytes32 hash, bytes memory signature) internal pure returns (address, RecoverError);
145
    
146
    /**
147
     * @dev Returns an Ethereum Signed Message hash for the given hash
148
     */
149
    function toEthSignedMessageHash(bytes32 messageHash) internal pure returns (bytes32);
150
    
151
    /**
152
     * @dev Returns an Ethereum Signed Message hash for the given bytes
153
     */
154
    function toEthSignedMessageHash(bytes memory message) internal pure returns (bytes32);
155
}
156

157
/**
158
 * @dev Message hashing utilities for standard Ethereum message formats
159
 */
160
library MessageHashUtils {
161
    /**
162
     * @dev Returns an Ethereum Signed Message hash for the given message hash
163
     */
164
    function toEthSignedMessageHash(bytes32 messageHash) internal pure returns (bytes32);
165
    
166
    /**
167
     * @dev Returns an Ethereum Signed Message hash for the given bytes message
168
     */
169
    function toEthSignedMessageHash(bytes memory message) internal pure returns (bytes32);
170
    
171
    /**
172
     * @dev Returns the data hash for ERC-1271 with intended validator
173
     */
174
    function toDataWithIntendedValidatorHash(address validator, bytes memory data) internal pure returns (bytes32);
175
    
176
    /**
177
     * @dev Returns the data hash for ERC-1271 with intended validator and message hash
178
     */
179
    function toDataWithIntendedValidatorHash(address validator, bytes32 messageHash) internal pure returns (bytes32);
180
    
181
    /**
182
     * @dev Returns an ERC-712 typed data hash
183
     */
184
    function toTypedDataHash(bytes32 domainSeparator, bytes32 structHash) internal pure returns (bytes32);
185
}
186

187
/**
188
 * @dev Universal signature validator supporting both EOA (ECDSA) and contract (ERC-1271) signatures
189
 */
190
library SignatureChecker {
191
    /**
192
     * @dev Checks if signature is valid for given signer and hash
193
     */
194
    function isValidSignatureNow(address signer, bytes32 hash, bytes memory signature) internal view returns (bool);
195
    
196
    /**
197
     * @dev Checks if signature is valid using ERC-1271 for contract accounts
198
     */
199
    function isValidERC1271SignatureNow(address signer, bytes32 hash, bytes memory signature) internal view returns (bool);
200
}
201

202
/**
203
 * @dev Merkle tree proof verification library
204
 */
205
library MerkleProof {
206
    /**
207
     * @dev Verifies a Merkle proof proving the existence of a leaf in a Merkle tree
208
     */
209
    function verify(bytes32[] memory proof, bytes32 root, bytes32 leaf) internal pure returns (bool);
210
    
211
    /**
212
     * @dev Processes a Merkle proof and returns the computed root
213
     */
214
    function processProof(bytes32[] memory proof, bytes32 leaf) internal pure returns (bytes32);
215
    
216
    /**
217
     * @dev Verifies multiple merkle proofs in a single verification
218
     */
219
    function multiProofVerify(bytes32[] memory proof, bool[] memory proofFlags, bytes32[] memory leaves, bytes32 root) internal pure returns (bool);
220
}
221
```
222

223
### Safe Operations
224

225
Utilities for safe type casting, token operations, and low-level calls with proper error handling.
226

227
```solidity { .api }
228
/**
229
 * @dev Safe casting library that throws on overflow/underflow
230
 */
231
library SafeCast {
232
    /**
233
     * @dev Cast uint256 to uint248, reverting on overflow
234
     */
235
    function toUint248(uint256 value) internal pure returns (uint248);
236
    
237
    /**
238
     * @dev Cast uint256 to uint128, reverting on overflow
239
     */
240
    function toUint128(uint256 value) internal pure returns (uint128);
241
    
242
    /**
243
     * @dev Cast uint256 to int256, reverting on overflow
244
     */
245
    function toInt256(uint256 value) internal pure returns (int256);
246
    
247
    /**
248
     * @dev Cast int256 to uint256, reverting on negative values
249
     */
250
    function toUint256(int256 value) internal pure returns (uint256);
251
}
252

253
/**
254
 * @dev Safe ERC20 operations that handle non-standard token implementations
255
 */
256
library SafeERC20 {
257
    /**
258
     * @dev Safe token transfer that handles tokens not returning values
259
     */
260
    function safeTransfer(IERC20 token, address to, uint256 value) internal;
261
    
262
    /**
263
     * @dev Safe transferFrom that handles tokens not returning values
264
     */
265
    function safeTransferFrom(IERC20 token, address from, address to, uint256 value) internal;
266
    
267
    /**
268
     * @dev Safe allowance increase that handles race conditions
269
     */
270
    function safeIncreaseAllowance(IERC20 token, address spender, uint256 value) internal;
271
    
272
    /**
273
     * @dev Safe allowance decrease with underflow protection
274
     */
275
    function safeDecreaseAllowance(IERC20 token, address spender, uint256 requestedDecrease) internal;
276
}
277

278
/**
279
 * @dev Address utility library for safe low-level operations
280
 */
281
library Address {
282
    /**
283
     * @dev Returns true if account is a contract
284
     */
285
    function isContract(address account) internal view returns (bool);
286
    
287
    /**
288
     * @dev Performs Ether transfer with gas limit and proper error handling
289
     */
290
    function sendValue(address payable recipient, uint256 amount) internal;
291
    
292
    /**
293
     * @dev Performs low-level function call with return data and error propagation
294
     */
295
    function functionCall(address target, bytes memory data) internal returns (bytes memory);
296
    
297
    /**
298
     * @dev Performs low-level delegate call with return data and error propagation
299
     */
300
    function functionDelegateCall(address target, bytes memory data) internal returns (bytes memory);
301
}
302
```
303

304
### Replay Attack Protection
305

306
Nonce-based protection against replay attacks in meta-transactions and signature-based operations.
307

308
```solidity { .api }
309
/**
310
 * @dev Provides nonce tracking functionality for replay attack protection
311
 */
312
abstract contract Nonces {
313
    /**
314
     * @dev Returns the current nonce for an owner
315
     */
316
    function nonces(address owner) public view virtual returns (uint256);
317
    
318
    /**
319
     * @dev Consumes nonce: returns current value and increments nonce
320
     */
321
    function _useNonce(address owner) internal virtual returns (uint256);
322
    
323
    /**
324
     * @dev Consumes specific nonce if it matches current value
325
     */
326
    function _useCheckedNonce(address owner, uint256 nonce) internal virtual;
327
}
328
```
329

330
### Batch Operations
331

332
Secure batching of multiple function calls within a single transaction while preserving context.
333

334
```solidity { .api }
335
/**
336
 * @dev Provides multicall functionality to batch multiple calls in a single transaction
337
 */
338
abstract contract Multicall {
339
    /**
340
     * @dev Batch multiple function calls and return all results
341
     */
342
    function multicall(bytes[] calldata data) external virtual returns (bytes[] memory results);
343
}
344
```
345

346
### Meta-Transaction Support
347

348
Context utilities for secure meta-transaction implementations and execution context management.
349

350
```solidity { .api }
351
/**
352
 * @dev Provides information about the current execution context
353
 */
354
abstract contract Context {
355
    /**
356
     * @dev Returns the sender of the transaction (supports meta-transactions)
357
     */
358
    function _msgSender() internal view virtual returns (address);
359
    
360
    /**
361
     * @dev Returns the transaction data (supports meta-transactions)
362
     */
363
    function _msgData() internal view virtual returns (bytes calldata);
364
    
365
    /**
366
     * @dev Returns the length of context suffix for meta-transactions
367
     */
368
    function _contextSuffixLength() internal view virtual returns (uint256);
369
}
370
```
371

372
## Types
373

374
```solidity { .api }
375
/**
376
 * @dev Standard interface for signature validation by smart contracts (ERC-1271)
377
 */
378
interface IERC1271 {
379
    /**
380
     * @dev Should return whether the signature provided is valid for the provided data
381
     * @param hash Hash of the data to be signed
382
     * @param signature Signature byte array associated with hash
383
     * @return magicValue The bytes4 magic value 0x1626ba7e if valid, otherwise 0xffffffff
384
     */
385
    function isValidSignature(bytes32 hash, bytes memory signature) external view returns (bytes4 magicValue);
386
}
387

388
/**
389
 * @dev ECDSA recovery error types
390
 */
391
enum RecoverError {
392
    NoError,
393
    InvalidSignature,
394
    InvalidSignatureLength,
395
    InvalidSignatureS,
396
    InvalidSignatureV
397
}
398

399
/**
400
 * @dev Standard ERC20 interface for SafeERC20 operations
401
 */
402
interface IERC20 {
403
    function transfer(address to, uint256 value) external returns (bool);
404
    function transferFrom(address from, address to, uint256 value) external returns (bool);
405
    function balanceOf(address account) external view returns (uint256);
406
    function allowance(address owner, address spender) external view returns (uint256);
407
}
408
```