0
# Library Management
1

2
Management and linking of Solidity libraries used by contracts during verification, with automatic library address detection and manual override support.
3

4
## Capabilities
5

6
### Library Address Resolution
7

8
Core functionality for resolving and linking Solidity library addresses during contract verification.
9

10
```typescript { .api }
11
/**
12
 * Library addresses mapping by source file and library name
13
 * Used to specify library addresses for contracts that use libraries
14
 */
15
interface Libraries {
16
  [sourceName: string]: {
17
    [libraryName: string]: string;
18
  };
19
}
20

21
/**
22
 * Library name information for undetectable libraries
23
 * Used to report libraries that couldn't be automatically detected
24
 */
25
interface LibraryNames {
26
  sourceName: string;
27
  libName: string;
28
}
29

30
/**
31
 * Get library links and detect undetectable libraries
32
 * Resolves library addresses and identifies libraries that couldn't be auto-detected
33
 * @param contractInformation - Contract compilation information
34
 * @param libraries - User-provided library addresses
35
 * @returns Object containing resolved library links and undetectable libraries
36
 */
37
function getLibraryLinks(
38
  contractInformation: ContractInformation,
39
  libraries: Libraries
40
): Promise<{
41
  libraryLinks: ResolvedLinks;
42
  undetectableLibraries: LibraryNames[];
43
}>;
44

45
/**
46
 * Resolved library links in the format expected by Solidity compiler
47
 * Maps source files to library names and their deployed addresses
48
 */
49
interface ResolvedLinks {
50
  [sourceName: string]: {
51
    [libraryName: string]: string;
52
  };
53
}
54
```
55

56
**Usage Examples:**
57

58
```typescript
59
// Library addresses configuration
60
const libraries: Libraries = {
61
  "contracts/utils/Math.sol": {
62
    "SafeMath": "0x1234567890123456789012345678901234567890"
63
  },
64
  "contracts/utils/Arrays.sol": {
65
    "ArrayUtils": "0x0987654321098765432109876543210987654321"
66
  }
67
};
68

69
// Get resolved library links
70
const { libraryLinks, undetectableLibraries } = await getLibraryLinks(
71
  contractInformation,
72
  libraries
73
);
74
```
75

76
### Library Configuration Subtask
77

78
Internal subtask that processes library addresses from configuration files.
79

80
```typescript { .api }
81
/**
82
 * Process library addresses from command line option or file
83
 * Handles loading library addresses from JavaScript modules
84
 */
85
interface LibrariesSubtaskArgs {
86
  /** Path to JavaScript module exporting library addresses */
87
  librariesModule?: string;
88
}
89
```
90

91
**Command Line Usage:**
92

93
```bash
94
# Verify with library addresses from file
95
npx hardhat verify --network mainnet --libraries libraries.js 0x1234...5678
96
```
97

98
### Library Configuration File Format
99

100
When using the `--libraries` option, the file must export an object mapping library names to addresses:
101

102
```javascript
103
// libraries.js - CommonJS format
104
module.exports = {
105
  "contracts/utils/SafeMath.sol": {
106
    "SafeMath": "0x1234567890123456789012345678901234567890"
107
  },
108
  "contracts/utils/Arrays.sol": {
109
    "ArrayUtils": "0x0987654321098765432109876543210987654321",
110
    "StringUtils": "0x1122334455667788990011223344556677889900"
111
  }
112
};
113
```
114

115
```typescript
116
// libraries.ts - ES Module format
117
export default {
118
  "contracts/utils/SafeMath.sol": {
119
    "SafeMath": "0x1234567890123456789012345678901234567890"
120
  }
121
} as const;
122
```
123

124
### Automatic Library Detection
125

126
The plugin attempts to automatically detect library addresses from the deployed contract bytecode:
127

128
```typescript { .api }
129
/**
130
 * Extract library information from contract bytecode
131
 * Analyzes deployed bytecode to identify linked library addresses
132
 * Some libraries may be undetectable if only used in constructor
133
 */
134
interface LibraryInformation {
135
  /** Libraries that couldn't be detected from bytecode */
136
  undetectableLibraries: LibraryNames;
137
}
138

139
/**
140
 * Extended contract information including library details
141
 * Combines contract compilation info with library linking information
142
 */
143
type ExtendedContractInformation = ContractInformation & LibraryInformation;
144
```
145

146
### Library Linking Process
147

148
The library linking process follows these steps:
149

150
1. **Automatic Detection**: Scan contract bytecode for library addresses
151
2. **Manual Override**: Apply user-provided library addresses
152
3. **Validation**: Ensure all required libraries have addresses
153
4. **Error Reporting**: Report undetectable libraries that may need manual specification
154

155
```typescript
156
// Internal workflow (simplified)
157
const contractInformation = await run(TASK_VERIFY_GET_CONTRACT_INFORMATION, {
158
  contractFQN,
159
  deployedBytecode,
160
  matchingCompilerVersions,
161
  libraries
162
});
163

164
// contractInformation now includes:
165
// - libraryLinks: resolved library addresses
166
// - undetectableLibraries: libraries that couldn't be auto-detected
167
```
168

169
### Undetectable Libraries
170

171
Some libraries cannot be automatically detected from bytecode, particularly those only used in the contract constructor:
172

173
```solidity
174
// Example of undetectable library usage
175
contract MyContract {
176
    constructor() {
177
        // Library only used in constructor - address not in runtime bytecode
178
        MyLibrary.initialize();
179
    }
180
    
181
    function someFunction() {
182
        // Library used in runtime - address detectable in bytecode
183
        return MyOtherLibrary.calculate();
184
    }
185
}
186
```
187

188
When undetectable libraries are found, the verification will include a helpful error message:
189

190
```
191
This contract makes use of libraries whose addresses are undetectable by the plugin.
192
Keep in mind that this verification failure may be due to passing in the wrong
193
address for one of these libraries:
194
  * contracts/utils/Math.sol:SafeMath
195
  * contracts/utils/Arrays.sol:ArrayUtils
196
```
197

198
### Library Address Validation
199

200
Library addresses must be valid Ethereum addresses:
201

202
```typescript
203
// Valid library addresses
204
const validLibraries = {
205
  "contracts/Math.sol": {
206
    "SafeMath": "0x1234567890123456789012345678901234567890", // Valid address
207
    "MathUtils": "0x0000000000000000000000000000000000000000" // Zero address is valid
208
  }
209
};
210

211
// Invalid library addresses will cause verification to fail
212
const invalidLibraries = {
213
  "contracts/Math.sol": {
214
    "SafeMath": "0xinvalid", // Invalid format
215
    "MathUtils": "1234567890123456789012345678901234567890" // Missing 0x prefix
216
  }
217
};
218
```
219

220
### Integration with Verification
221

222
Library information is automatically integrated into the verification process:
223

224
```typescript { .api }
225
/**
226
 * Verification subtask args include processed library information
227
 */
228
interface VerificationSubtaskArgs {
229
  address: string;
230
  constructorArguments: any[];
231
  contract?: string;
232
  /** Processed and resolved library addresses */
233
  libraries: Libraries;
234
  noCompile: boolean;
235
}
236
```
237

238
The resolved library links are included in the compiler input sent to Etherscan:
239

240
```typescript
241
// Library links are added to compiler input settings
242
compilerInput.settings.libraries = contractInformation.libraryLinks;
243

244
// Example compiler input with libraries
245
{
246
  "settings": {
247
    "libraries": {
248
      "contracts/utils/Math.sol": {
249
        "SafeMath": "0x1234567890123456789012345678901234567890"
250
      }
251
    }
252
  }
253
}
254
```
255

256
### Error Handling
257

258
The library system provides detailed error messages for common issues:
259

260
- **Invalid library module format**: When the libraries file doesn't export the correct object structure
261
- **Missing library addresses**: When required libraries don't have addresses specified
262
- **Invalid addresses**: When library addresses are not valid Ethereum addresses
263
- **Undetectable libraries**: When libraries can't be automatically detected and may need manual specification
264

265
```typescript
266
// Example error for invalid library module
267
// Error: The module /path/to/libraries.js doesn't export a dictionary. The module should look like this:
268
//   module.exports = { lib1: "0x...", lib2: "0x...", ... };
269
```