Skip to main content

foundry_linking/
lib.rs

1//! # foundry-linking
2//!
3//! EVM bytecode linker.
4
5#![cfg_attr(not(test), warn(unused_crate_dependencies))]
6#![cfg_attr(docsrs, feature(doc_cfg))]
7
8use alloy_primitives::{Address, B256, Bytes, hex::FromHexError, map::HashMap as AlloyHashMap};
9use foundry_compilers::{
10    Artifact, ArtifactId,
11    artifacts::{CompactBytecode, CompactContractBytecodeCow, Libraries},
12    contracts::ArtifactContracts,
13};
14use rayon::prelude::*;
15use std::{
16    cell::OnceCell,
17    collections::{BTreeMap, BTreeSet},
18    path::{Path, PathBuf},
19    str::FromStr,
20    sync::OnceLock,
21};
22
23/// Errors that can occur during linking.
24#[derive(Debug, thiserror::Error)]
25pub enum LinkerError {
26    #[error("wasn't able to find artifact for library {name} at {file}")]
27    MissingLibraryArtifact { file: String, name: String },
28    #[error("multiple library artifacts resolve to the same key {file}:{name}")]
29    ConflictingLibraryArtifacts { file: String, name: String },
30    #[error("target artifact is not present in provided artifacts set")]
31    MissingTargetArtifact,
32    #[error(transparent)]
33    InvalidAddress(FromHexError),
34    #[error("cyclic dependency found, can't link libraries via CREATE2")]
35    CyclicDependency,
36    #[error("failed linking {artifact}")]
37    LinkingFailed { artifact: String },
38}
39
40type Index = AlloyHashMap<PathBuf, AlloyHashMap<String, Vec<ArtifactId>>>;
41
42pub struct Linker<'a> {
43    /// Root of the project, used to determine whether artifact/library path can be stripped.
44    pub root: PathBuf,
45    /// Compilation artifacts.
46    pub contracts: ArtifactContracts<CompactContractBytecodeCow<'a>>,
47}
48
49/// Reuses artifact lookups across multiple linker operations.
50pub struct Resolver<'a, 'b> {
51    linker: &'b Linker<'a>,
52    index: OnceLock<Index>,
53}
54
55/// Output of the `link_with_nonce_or_address`
56pub struct LinkOutput {
57    /// Flattened resolved library addresses. Contains both user-provided and newly deployed
58    /// libraries, with stripped path prefixes. Auto-linked keys that resolve to different
59    /// addresses for different artifacts are omitted; use
60    /// [`DetailedLinkOutput::artifact_libraries`] for complete per-artifact mappings.
61    pub libraries: Libraries,
62    /// Addresses of libraries required by the linked targets.
63    pub library_addresses: Vec<Address>,
64    /// Vector of libraries that need to be deployed from sender address.
65    /// The order in which they appear in the vector is the order in which they should be deployed.
66    pub libs_to_deploy: Vec<Bytes>,
67}
68
69/// Detailed linker output for callers that need metadata about auto-linked libraries.
70pub struct DetailedLinkOutput {
71    /// The backwards-compatible linker output.
72    pub output: LinkOutput,
73    /// Complete transitive library address mapping selected for each linked artifact.
74    pub artifact_libraries: BTreeMap<ArtifactId, Libraries>,
75    /// Address selected for every resolved library artifact, including byte-identical variants.
76    pub artifact_addresses: BTreeMap<ArtifactId, Address>,
77    /// Unique physical library deployments and their linked creation bytecode.
78    ///
79    /// Multiple byte-identical artifacts can share one CREATE2 deployment. In that case, this
80    /// contains one representative artifact while [`Self::artifact_addresses`] preserves every
81    /// artifact identity.
82    pub linked_libraries: Vec<LinkedLibrary>,
83}
84
85/// An auto-linked library and the data used to deploy and classify it.
86#[derive(Clone, Debug)]
87pub struct LinkedLibrary {
88    /// Compilation artifact for the library.
89    pub id: ArtifactId,
90    /// Address assigned by the linker.
91    pub address: Address,
92    /// Fully linked creation bytecode.
93    pub bytecode: Bytes,
94}
95
96impl<'a> Linker<'a> {
97    pub fn new(
98        root: impl Into<PathBuf>,
99        contracts: ArtifactContracts<CompactContractBytecodeCow<'a>>,
100    ) -> Self {
101        Linker { root: root.into(), contracts }
102    }
103
104    /// Helper method to convert [ArtifactId] to the format in which libraries are stored in
105    /// [Libraries] object.
106    ///
107    /// Strips project root path from source file path.
108    fn convert_artifact_id_to_lib_path(&self, id: &ArtifactId) -> (PathBuf, String) {
109        // name is either {LibName} or {LibName}.{version}
110        let name = id.name.split('.').next().unwrap();
111
112        (self.project_relative_path(&id.source), name.to_owned())
113    }
114
115    fn project_relative_path(&self, path: &Path) -> PathBuf {
116        if path.is_relative() {
117            return path.to_path_buf();
118        }
119
120        if let Ok(stripped) = path.strip_prefix(&self.root) {
121            return stripped.to_path_buf();
122        }
123
124        if let Ok(root) = self.root.canonicalize()
125            && let Ok(path) = path.canonicalize()
126            && let Ok(stripped) = path.strip_prefix(root)
127        {
128            return stripped.to_path_buf();
129        }
130
131        path.to_path_buf()
132    }
133
134    fn index<'b>(&self, index: &'b OnceLock<Index>) -> &'b Index {
135        index.get_or_init(|| {
136            let mut artifacts = AlloyHashMap::<_, AlloyHashMap<_, Vec<_>>>::default();
137            for id in self.contracts.keys() {
138                let path = self.project_relative_path(&id.source);
139                let name = id.name.split('.').next().unwrap().to_owned();
140                artifacts.entry(path).or_default().entry(name).or_default().push(id.clone());
141            }
142            artifacts
143        })
144    }
145
146    /// Resolves `path` against the project root and canonicalizes it for comparison only.
147    fn canonical_path(&self, path: &Path) -> Option<PathBuf> {
148        let path = if path.is_relative() { self.root.join(path) } else { path.to_path_buf() };
149        path.canonicalize().ok()
150    }
151
152    fn path_matches(
153        &self,
154        path: &Path,
155        expected: &Path,
156        canonical_expected: Option<&Path>,
157    ) -> bool {
158        let path = self.project_relative_path(path);
159        path == expected
160            || canonical_expected
161                .is_some_and(|expected| self.canonical_path(&path).as_deref() == Some(expected))
162    }
163
164    fn link_bytecode(
165        &self,
166        bytecode: &mut CompactBytecode,
167        target: &ArtifactId,
168        file: &Path,
169        name: &str,
170        address: Address,
171    ) -> Result<(), LinkerError> {
172        self.link_bytecode_inner(bytecode, target, file, name, address, true)
173    }
174
175    fn link_bytecode_inner(
176        &self,
177        bytecode: &mut CompactBytecode,
178        target: &ArtifactId,
179        file: &Path,
180        name: &str,
181        address: Address,
182        canonical: bool,
183    ) -> Result<(), LinkerError> {
184        let file_relative = self.project_relative_path(file);
185        // Canonicalizing hits the file system, so only do it for a reference that needs it.
186        let canonical_file = OnceCell::new();
187        let mut references = Vec::new();
188        for (reference, libraries) in &bytecode.link_references {
189            if !libraries.contains_key(name) {
190                continue;
191            }
192            let reference_path = self.project_relative_path(Path::new(reference));
193            if reference_path == file_relative {
194                references.push(reference.clone());
195                continue;
196            }
197            if !canonical {
198                continue;
199            }
200            let canonical_file =
201                canonical_file.get_or_init(|| self.canonical_path(&file_relative)).as_deref();
202            if !self.path_matches(Path::new(reference), &file_relative, canonical_file) {
203                continue;
204            }
205            if let Some(id) =
206                self.find_artifact_id_by_library_path(None, reference, name, target)?
207            {
208                let (artifact_file, artifact_name) = self.convert_artifact_id_to_lib_path(id);
209                if artifact_file == file_relative && artifact_name == name {
210                    references.push(reference.clone());
211                }
212            }
213        }
214
215        if references.is_empty() && canonical {
216            bytecode.link(&file.to_string_lossy(), name, address);
217        } else {
218            for reference in references {
219                bytecode.link(&reference, name, address);
220            }
221        }
222        Ok(())
223    }
224
225    /// Finds an [ArtifactId] object in the given [ArtifactContracts] keys which corresponds to the
226    /// library path in the form of "./path/to/Lib.sol:Lib"
227    ///
228    /// Dependency lookups can use the index. Canonical paths retain the fallback scan required
229    /// for symlinked library aliases.
230    fn find_artifact_id_by_library_path<'b>(
231        &'b self,
232        index: Option<&'b OnceLock<Index>>,
233        file: &str,
234        name: &str,
235        target: &ArtifactId,
236    ) -> Result<Option<&'b ArtifactId>, LinkerError> {
237        let library_path = self.project_relative_path(Path::new(file));
238        let candidates = if let Some(index) = index {
239            self.index(index)
240                .get(&library_path)
241                .and_then(|artifacts| artifacts.get(name))
242                .into_iter()
243                .flatten()
244                .filter(|id| id.version == target.version)
245                .collect::<Vec<_>>()
246        } else {
247            self.contracts
248                .keys()
249                .filter(|id| {
250                    if id.version != target.version {
251                        return false;
252                    }
253                    let (artifact_path, artifact_name) = self.convert_artifact_id_to_lib_path(id);
254                    artifact_name == *name && artifact_path == library_path
255                })
256                .collect()
257        };
258        let candidates = if candidates.is_empty() {
259            let canonical_library_path = self.canonical_path(&library_path);
260            self.contracts
261                .keys()
262                .filter(|id| {
263                    if id.version != target.version {
264                        return false;
265                    }
266                    let (artifact_path, artifact_name) = self.convert_artifact_id_to_lib_path(id);
267                    artifact_name == *name
268                        && self.path_matches(
269                            &artifact_path,
270                            &library_path,
271                            canonical_library_path.as_deref(),
272                        )
273                })
274                .collect()
275        } else {
276            candidates
277        };
278        let same_build_and_profile = candidates
279            .iter()
280            .copied()
281            .filter(|id| id.build_id == target.build_id && id.profile == target.profile)
282            .collect::<Vec<_>>();
283        let same_profile = candidates
284            .iter()
285            .copied()
286            .filter(|id| id.profile == target.profile)
287            .collect::<Vec<_>>();
288        let candidates = if !same_build_and_profile.is_empty() {
289            same_build_and_profile
290        } else if !same_profile.is_empty() {
291            same_profile
292        } else {
293            candidates
294        };
295
296        if candidates.len() > 1 {
297            return Err(LinkerError::ConflictingLibraryArtifacts {
298                file: library_path.display().to_string(),
299                name: name.to_owned(),
300            });
301        }
302        Ok(candidates.into_iter().next())
303    }
304
305    fn direct_dependencies<'b>(
306        &'b self,
307        index: &'b OnceLock<Index>,
308        target: &ArtifactId,
309        references: &mut BTreeMap<&'b ArtifactId, BTreeSet<PathBuf>>,
310    ) -> Result<BTreeSet<&'b ArtifactId>, LinkerError> {
311        let contract = self.contracts.get(target).ok_or(LinkerError::MissingTargetArtifact)?;
312
313        let mut link_references: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
314        let mut extend = |bytecode: &CompactBytecode| {
315            for (file, libs) in &bytecode.link_references {
316                link_references.entry(file.clone()).or_default().extend(libs.keys().cloned());
317            }
318        };
319        if let Some(bytecode) = &contract.bytecode {
320            extend(bytecode);
321        }
322        if let Some(deployed_bytecode) = &contract.deployed_bytecode
323            && let Some(bytecode) = &deployed_bytecode.bytecode
324        {
325            extend(bytecode);
326        }
327
328        let mut dependencies = BTreeSet::new();
329        for (file, libs) in link_references {
330            for name in libs {
331                let id = self
332                    .find_artifact_id_by_library_path(Some(index), &file, &name, target)?
333                    .ok_or_else(|| LinkerError::MissingLibraryArtifact {
334                        file: file.clone(),
335                        name,
336                    })?;
337                references.entry(id).or_default().insert(file.clone().into());
338                dependencies.insert(id);
339            }
340        }
341
342        Ok(dependencies)
343    }
344
345    /// Performs DFS on the graph of link references, and populates `deps` with all found libraries.
346    fn collect_dependencies<'b>(
347        &'b self,
348        index: &'b OnceLock<Index>,
349        target: &ArtifactId,
350        deps: &mut BTreeSet<&'b ArtifactId>,
351        references: &mut BTreeMap<&'b ArtifactId, BTreeSet<PathBuf>>,
352    ) -> Result<(), LinkerError> {
353        for id in self.direct_dependencies(index, target, references)? {
354            if deps.insert(id) {
355                self.collect_dependencies(index, id, deps, references)?;
356            }
357        }
358
359        Ok(())
360    }
361
362    fn apply_configured_references(
363        &self,
364        references: &BTreeMap<&ArtifactId, BTreeSet<PathBuf>>,
365        libraries: &mut Libraries,
366    ) -> Result<(), LinkerError> {
367        for (id, references) in references {
368            let (file, name) = self.convert_artifact_id_to_lib_path(id);
369            let mut configured = references
370                .iter()
371                .filter_map(|reference| libraries.libs.get(reference)?.get(&name))
372                .map(|address| Address::from_str(address).map_err(LinkerError::InvalidAddress))
373                .collect::<Result<BTreeSet<_>, _>>()?;
374            let exact = !configured.is_empty();
375            if configured.is_empty()
376                && let Some(canonical_file) = self.canonical_path(&file)
377            {
378                configured = libraries
379                    .libs
380                    .iter()
381                    .filter_map(|(configured_file, libraries)| {
382                        if self.canonical_path(configured_file).as_deref() == Some(&canonical_file)
383                        {
384                            libraries.get(&name)
385                        } else {
386                            None
387                        }
388                    })
389                    .map(|address| Address::from_str(address).map_err(LinkerError::InvalidAddress))
390                    .collect::<Result<BTreeSet<_>, _>>()?;
391            }
392            if configured.len() > 1 {
393                return Err(LinkerError::ConflictingLibraryArtifacts {
394                    file: file.display().to_string(),
395                    name,
396                });
397            }
398            let Some(address) = configured.first().copied() else { continue };
399            let canonical = libraries.libs.entry(file).or_default();
400            if exact {
401                canonical.insert(name, address.to_checksum(None));
402            } else {
403                canonical.entry(name).or_insert_with(|| address.to_checksum(None));
404            }
405        }
406        Ok(())
407    }
408
409    fn collect_library_keys(
410        &self,
411        needed_libraries: &BTreeSet<&ArtifactId>,
412        libraries: &Libraries,
413    ) -> Result<BTreeSet<(PathBuf, String)>, LinkerError> {
414        let mut library_keys = BTreeSet::new();
415        for id in needed_libraries {
416            let (file, name) = self.convert_artifact_id_to_lib_path(id);
417            let is_configured =
418                libraries.libs.get(&file).is_some_and(|libraries| libraries.contains_key(&name));
419            if !library_keys.insert((file.clone(), name.clone())) && !is_configured {
420                return Err(LinkerError::ConflictingLibraryArtifacts {
421                    file: file.display().to_string(),
422                    name,
423                });
424            }
425        }
426        Ok(library_keys)
427    }
428
429    fn configured_library_address(
430        &self,
431        id: &ArtifactId,
432        libraries: &Libraries,
433    ) -> Result<Option<Address>, LinkerError> {
434        let (file, name) = self.convert_artifact_id_to_lib_path(id);
435        libraries
436            .libs
437            .get(&file)
438            .and_then(|libraries| libraries.get(&name))
439            .map(|address| Address::from_str(address).map_err(LinkerError::InvalidAddress))
440            .transpose()
441    }
442
443    fn libraries_for_artifact<'b>(
444        &'b self,
445        index: &'b OnceLock<Index>,
446        target: &ArtifactId,
447        configured: &Libraries,
448        addresses: &BTreeMap<&'b ArtifactId, Address>,
449    ) -> Result<Libraries, LinkerError> {
450        let mut libraries = configured.clone();
451        let mut dependencies = BTreeSet::new();
452        self.collect_dependencies(index, target, &mut dependencies, &mut BTreeMap::new())?;
453        for id in dependencies {
454            let Some(&address) = addresses.get(id) else { continue };
455            let (file, name) = self.convert_artifact_id_to_lib_path(id);
456            let entry = libraries.libs.entry(file.clone()).or_default().entry(name.clone());
457            if let std::collections::btree_map::Entry::Occupied(entry) = &entry
458                && Address::from_str(entry.get()).map_err(LinkerError::InvalidAddress)? != address
459            {
460                return Err(LinkerError::ConflictingLibraryArtifacts {
461                    file: file.display().to_string(),
462                    name,
463                });
464            }
465            entry.or_insert_with(|| address.to_checksum(None));
466        }
467        Ok(libraries)
468    }
469
470    fn artifact_libraries<'b>(
471        &'b self,
472        index: &'b OnceLock<Index>,
473        artifacts: impl IntoIterator<Item = &'b ArtifactId>,
474        configured: &Libraries,
475        addresses: &BTreeMap<&'b ArtifactId, Address>,
476    ) -> Result<BTreeMap<ArtifactId, Libraries>, LinkerError> {
477        artifacts
478            .into_iter()
479            .map(|id| {
480                Ok((id.clone(), self.libraries_for_artifact(index, id, configured, addresses)?))
481            })
482            .collect()
483    }
484
485    fn output_libraries(
486        &self,
487        mut libraries: Libraries,
488        addresses: &BTreeMap<&ArtifactId, Address>,
489    ) -> Libraries {
490        let mut by_key = BTreeMap::<(PathBuf, String), BTreeSet<Address>>::new();
491        for (&id, &address) in addresses {
492            by_key.entry(self.convert_artifact_id_to_lib_path(id)).or_default().insert(address);
493        }
494        for ((file, name), addresses) in by_key {
495            if let Some(address) = addresses.first().filter(|_| addresses.len() == 1) {
496                libraries
497                    .libs
498                    .entry(file)
499                    .or_default()
500                    .entry(name)
501                    .or_insert_with(|| address.to_checksum(None));
502            }
503        }
504        libraries
505    }
506
507    fn assigned_library_addresses(
508        &self,
509        addresses: &BTreeMap<&ArtifactId, Address>,
510    ) -> Vec<Address> {
511        addresses.values().copied().collect::<BTreeSet<_>>().into_iter().collect()
512    }
513
514    fn artifact_addresses(
515        &self,
516        addresses: &BTreeMap<&ArtifactId, Address>,
517    ) -> BTreeMap<ArtifactId, Address> {
518        addresses.iter().map(|(&id, &address)| (id.clone(), address)).collect()
519    }
520
521    fn artifact_addresses_from_libraries(
522        &self,
523        artifacts: impl IntoIterator<Item = &'a ArtifactId>,
524        libraries: &Libraries,
525    ) -> Result<BTreeMap<ArtifactId, Address>, LinkerError> {
526        artifacts
527            .into_iter()
528            .map(|id| {
529                let address = self
530                    .configured_library_address(id, libraries)?
531                    .ok_or_else(|| LinkerError::LinkingFailed { artifact: id.identifier() })?;
532                Ok((id.clone(), address))
533            })
534            .collect()
535    }
536
537    fn ensure_flattened_libraries(
538        &self,
539        artifact_libraries: &BTreeMap<ArtifactId, Libraries>,
540    ) -> Result<(), LinkerError> {
541        let mut addresses = BTreeMap::<(PathBuf, String), BTreeSet<Address>>::new();
542        for libraries in artifact_libraries.values() {
543            for (file, libraries) in &libraries.libs {
544                for (name, address) in libraries {
545                    addresses
546                        .entry((file.clone(), name.clone()))
547                        .or_default()
548                        .insert(Address::from_str(address).map_err(LinkerError::InvalidAddress)?);
549                }
550            }
551        }
552        if let Some(((file, name), _)) =
553            addresses.into_iter().find(|(_, addresses)| addresses.len() > 1)
554        {
555            return Err(LinkerError::ConflictingLibraryArtifacts {
556                file: file.display().to_string(),
557                name,
558            });
559        }
560        Ok(())
561    }
562
563    fn library_addresses(
564        &self,
565        library_keys: &BTreeSet<(PathBuf, String)>,
566        libraries: &Libraries,
567    ) -> Result<Vec<Address>, LinkerError> {
568        let addresses = library_keys
569            .iter()
570            .map(|(file, name)| {
571                let address =
572                    libraries.libs.get(file).and_then(|libraries| libraries.get(name)).ok_or_else(
573                        || LinkerError::LinkingFailed {
574                            artifact: format!("{}:{name}", file.display()),
575                        },
576                    )?;
577                Address::from_str(address).map_err(LinkerError::InvalidAddress)
578            })
579            .collect::<Result<BTreeSet<_>, _>>()?;
580        Ok(addresses.into_iter().collect())
581    }
582
583    /// Returns the resolved addresses of all libraries required by `target`.
584    pub fn linked_library_addresses(
585        &'a self,
586        target: &'a ArtifactId,
587        libraries: &Libraries,
588    ) -> Result<BTreeSet<Address>, LinkerError> {
589        Resolver::new(self).linked_library_addresses(target, libraries)
590    }
591
592    fn linked_library_addresses_inner<'b>(
593        &'b self,
594        index: &'b OnceLock<Index>,
595        target: &ArtifactId,
596        libraries: &Libraries,
597    ) -> Result<BTreeSet<Address>, LinkerError> {
598        let mut dependencies = BTreeSet::new();
599        let mut references = BTreeMap::new();
600        self.collect_dependencies(index, target, &mut dependencies, &mut references)?;
601        let mut libraries = libraries.clone();
602        self.apply_configured_references(&references, &mut libraries)?;
603
604        dependencies
605            .into_iter()
606            .map(|id| {
607                let (file, name) = self.convert_artifact_id_to_lib_path(id);
608                libraries
609                    .libs
610                    .get(&file)
611                    .and_then(|libs| libs.get(&name))
612                    .ok_or_else(|| LinkerError::LinkingFailed { artifact: id.identifier() })?
613                    .parse()
614                    .map_err(LinkerError::InvalidAddress)
615            })
616            .collect()
617    }
618
619    /// Returns the transitive set of libraries referenced by `target`.
620    pub fn dependencies(
621        &'a self,
622        target: &'a ArtifactId,
623    ) -> Result<BTreeSet<ArtifactId>, LinkerError> {
624        let index = OnceLock::new();
625        self.dependencies_inner(&index, target)
626    }
627
628    fn dependencies_inner<'b>(
629        &'b self,
630        index: &'b OnceLock<Index>,
631        target: &ArtifactId,
632    ) -> Result<BTreeSet<ArtifactId>, LinkerError> {
633        let mut dependencies = BTreeSet::new();
634        self.collect_dependencies(index, target, &mut dependencies, &mut BTreeMap::new())?;
635        Ok(dependencies.into_iter().cloned().collect())
636    }
637
638    fn linked_creation_bytecode(
639        &self,
640        target: &ArtifactId,
641        libraries: &Libraries,
642    ) -> Result<Bytes, LinkerError> {
643        let contract = self.link(target, libraries)?;
644        self.ensure_linked(&contract, target)?;
645        contract.get_bytecode_bytes().map(|code| code.into_owned()).ok_or_else(|| {
646            LinkerError::LinkingFailed { artifact: target.source.to_string_lossy().into_owned() }
647        })
648    }
649
650    /// Links given artifact with either given library addresses or address computed from sender and
651    /// nonce.
652    ///
653    /// Each key in `libraries` should either be a global path or relative to project root. All
654    /// remappings should be resolved.
655    ///
656    /// When calling for `target` being an external library itself, you should check that `target`
657    /// does not appear in `libs_to_deploy` to avoid deploying it twice. It may happen in cases
658    /// when there is a dependency cycle including `target`.
659    pub fn link_with_nonce_or_address(
660        &'a self,
661        libraries: Libraries,
662        sender: Address,
663        nonce: u64,
664        targets: impl IntoIterator<Item = &'a ArtifactId>,
665    ) -> Result<LinkOutput, LinkerError> {
666        let output = self.link_with_nonce_or_address_detailed(libraries, sender, nonce, targets)?;
667        self.ensure_flattened_libraries(&output.artifact_libraries)?;
668        Ok(output.output)
669    }
670
671    /// Links like [`Self::link_with_nonce_or_address`] and includes auto-linked library metadata.
672    pub fn link_with_nonce_or_address_detailed(
673        &'a self,
674        libraries: Libraries,
675        sender: Address,
676        mut nonce: u64,
677        targets: impl IntoIterator<Item = &'a ArtifactId>,
678    ) -> Result<DetailedLinkOutput, LinkerError> {
679        let index = OnceLock::new();
680        // Library paths in `link_references` keys are always stripped, so we have to strip
681        // user-provided paths to be able to match them correctly.
682        let mut libraries = libraries.with_stripped_file_prefixes(self.root.as_path());
683
684        let targets = targets.into_iter().collect::<Vec<_>>();
685        let mut needed_libraries = BTreeSet::new();
686        let mut references = BTreeMap::new();
687        for &target in &targets {
688            self.collect_dependencies(&index, target, &mut needed_libraries, &mut references)?;
689        }
690        self.apply_configured_references(&references, &mut libraries)?;
691
692        let mut addresses = BTreeMap::new();
693        let mut libs_to_deploy = Vec::new();
694        for &id in &needed_libraries {
695            let address = self.configured_library_address(id, &libraries)?.unwrap_or_else(|| {
696                let address = sender.create(nonce);
697                nonce += 1;
698                libs_to_deploy.push((id, address));
699                address
700            });
701            addresses.insert(id, address);
702        }
703
704        let artifact_libraries = self.artifact_libraries(
705            &index,
706            targets.iter().copied().chain(needed_libraries.iter().copied()),
707            &libraries,
708            &addresses,
709        )?;
710
711        // Link and collect bytecodes for `libs_to_deploy`.
712        let linked_libraries = libs_to_deploy
713            .into_par_iter()
714            .map(|(id, address)| {
715                let artifact_libraries = artifact_libraries.get(id).unwrap();
716                let bytecode =
717                    self.link(id, artifact_libraries)?.get_bytecode_bytes().unwrap().into_owned();
718                Ok(LinkedLibrary { id: id.clone(), address, bytecode })
719            })
720            .collect::<Result<Vec<_>, LinkerError>>()?;
721        let libs_to_deploy = linked_libraries.iter().map(|lib| lib.bytecode.clone()).collect();
722
723        let library_addresses = self.assigned_library_addresses(&addresses);
724        let artifact_addresses = self.artifact_addresses(&addresses);
725        let libraries = self.output_libraries(libraries, &addresses);
726        Ok(DetailedLinkOutput {
727            output: LinkOutput { libraries, library_addresses, libs_to_deploy },
728            artifact_libraries,
729            artifact_addresses,
730            linked_libraries,
731        })
732    }
733
734    pub fn link_with_create2(
735        &'a self,
736        libraries: Libraries,
737        sender: Address,
738        salt: B256,
739        targets: impl IntoIterator<Item = &'a ArtifactId>,
740    ) -> Result<LinkOutput, LinkerError> {
741        let output = self.link_with_create2_detailed(libraries, sender, salt, targets)?;
742        self.ensure_flattened_libraries(&output.artifact_libraries)?;
743        Ok(output.output)
744    }
745
746    /// Links like [`Self::link_with_create2`] and includes auto-linked library metadata.
747    pub fn link_with_create2_detailed(
748        &'a self,
749        libraries: Libraries,
750        sender: Address,
751        salt: B256,
752        targets: impl IntoIterator<Item = &'a ArtifactId>,
753    ) -> Result<DetailedLinkOutput, LinkerError> {
754        let index = OnceLock::new();
755        // Library paths in `link_references` keys are always stripped, so we have to strip
756        // user-provided paths to be able to match them correctly.
757        let mut libraries = libraries.with_stripped_file_prefixes(self.root.as_path());
758
759        let targets = targets.into_iter().collect::<Vec<_>>();
760        let mut needed_libraries = BTreeSet::new();
761        let mut references = BTreeMap::new();
762        for &target in &targets {
763            self.collect_dependencies(&index, target, &mut needed_libraries, &mut references)?;
764        }
765        self.apply_configured_references(&references, &mut libraries)?;
766
767        let mut addresses = BTreeMap::new();
768        let mut pending = Vec::new();
769        for &id in &needed_libraries {
770            if let Some(address) = self.configured_library_address(id, &libraries)? {
771                addresses.insert(id, address);
772            } else {
773                pending.push(id);
774            }
775        }
776        let mut linked_libraries = Vec::<LinkedLibrary>::new();
777
778        // Iteratively compute addresses and link libraries until we have no unlinked libraries
779        // left.
780        while !pending.is_empty() {
781            let mut deployable = None;
782            for (position, &id) in pending.iter().enumerate() {
783                let artifact_libraries =
784                    self.libraries_for_artifact(&index, id, &libraries, &addresses)?;
785                let bytecode = self.link(id, &artifact_libraries)?.bytecode.ok_or_else(|| {
786                    LinkerError::LinkingFailed { artifact: id.source.to_string_lossy().into() }
787                })?;
788                if !bytecode.object.is_unlinked() {
789                    deployable = Some((position, id, bytecode));
790                    break;
791                }
792            }
793            let Some((position, id, bytecode)) = deployable else {
794                return Err(LinkerError::CyclicDependency);
795            };
796            pending.swap_remove(position);
797            let code = bytecode.bytes().ok_or_else(|| LinkerError::LinkingFailed {
798                artifact: id.source.to_string_lossy().into(),
799            })?;
800            let address = sender.create2_from_code(salt, code);
801            if linked_libraries.iter().all(|library| library.address != address) {
802                linked_libraries.push(LinkedLibrary {
803                    id: id.clone(),
804                    address,
805                    bytecode: code.clone(),
806                });
807            }
808            addresses.insert(id, address);
809        }
810
811        let artifact_libraries = self.artifact_libraries(
812            &index,
813            targets.iter().copied().chain(needed_libraries.iter().copied()),
814            &libraries,
815            &addresses,
816        )?;
817        let libs_to_deploy = linked_libraries.iter().map(|lib| lib.bytecode.clone()).collect();
818        let library_addresses = self.assigned_library_addresses(&addresses);
819        let artifact_addresses = self.artifact_addresses(&addresses);
820        let libraries = self.output_libraries(libraries, &addresses);
821        Ok(DetailedLinkOutput {
822            output: LinkOutput { libraries, library_addresses, libs_to_deploy },
823            artifact_libraries,
824            artifact_addresses,
825            linked_libraries,
826        })
827    }
828
829    /// Relinks a target while assigning libraries not needed onchain to an isolated deployer.
830    pub fn link_with_partition(
831        &'a self,
832        libraries: Libraries,
833        sender: Address,
834        mut sender_nonce: u64,
835        local_deployer: Address,
836        required: &BTreeSet<ArtifactId>,
837        target: &'a ArtifactId,
838    ) -> Result<(DetailedLinkOutput, Vec<LinkedLibrary>), LinkerError> {
839        let index = OnceLock::new();
840        let mut libraries = libraries.with_stripped_file_prefixes(self.root.as_path());
841        let mut needed = BTreeSet::new();
842        let mut references = BTreeMap::new();
843        self.collect_dependencies(&index, target, &mut needed, &mut references)?;
844        self.apply_configured_references(&references, &mut libraries)?;
845        let library_keys = self.collect_library_keys(&needed, &libraries)?;
846        let mut required_with_dependencies = required.clone();
847        for id in required {
848            required_with_dependencies.extend(self.dependencies_inner(&index, id)?);
849        }
850        let mut local_nonce = 0;
851        let mut assigned = Vec::new();
852        for &id in &needed {
853            let (file, name) = self.convert_artifact_id_to_lib_path(id);
854            libraries.libs.entry(file).or_default().entry(name).or_insert_with(|| {
855                let onchain = required_with_dependencies.contains(id);
856                let address = if onchain {
857                    let address = sender.create(sender_nonce);
858                    sender_nonce += 1;
859                    address
860                } else {
861                    let address = local_deployer.create(local_nonce);
862                    local_nonce += 1;
863                    address
864                };
865                assigned.push((id, address, onchain));
866                address.to_checksum(None)
867            });
868        }
869        let linked = assigned
870            .into_iter()
871            .map(|(id, address, onchain)| {
872                let bytecode = self.linked_creation_bytecode(id, &libraries)?;
873                Ok((LinkedLibrary { id: id.clone(), address, bytecode }, onchain))
874            })
875            .collect::<Result<Vec<_>, LinkerError>>()?;
876        let libs_to_deploy = linked
877            .iter()
878            .filter(|(_, onchain)| *onchain)
879            .map(|(lib, _)| lib.bytecode.clone())
880            .collect();
881        let local =
882            linked.iter().filter(|(_, onchain)| !*onchain).map(|(lib, _)| lib.clone()).collect();
883        let linked_libraries = linked.into_iter().map(|(lib, _)| lib).collect();
884        let library_addresses = self.library_addresses(&library_keys, &libraries)?;
885        let artifact_addresses =
886            self.artifact_addresses_from_libraries(needed.iter().copied(), &libraries)?;
887        let artifact_libraries = BTreeMap::from([(target.clone(), libraries.clone())]);
888        Ok((
889            DetailedLinkOutput {
890                output: LinkOutput { libraries, library_addresses, libs_to_deploy },
891                artifact_libraries,
892                artifact_addresses,
893                linked_libraries,
894            },
895            local,
896        ))
897    }
898
899    /// Relinks a target with CREATE2 onchain assignments and isolated local assignments.
900    pub fn link_with_create2_partition(
901        &'a self,
902        libraries: Libraries,
903        create2_deployer: Address,
904        salt: B256,
905        local_deployer: Address,
906        required: &BTreeSet<ArtifactId>,
907        target: &'a ArtifactId,
908    ) -> Result<(DetailedLinkOutput, Vec<LinkedLibrary>), LinkerError> {
909        let index = OnceLock::new();
910        let mut libraries = libraries.with_stripped_file_prefixes(self.root.as_path());
911        let mut needed = BTreeSet::new();
912        let mut references = BTreeMap::new();
913        self.collect_dependencies(&index, target, &mut needed, &mut references)?;
914        self.apply_configured_references(&references, &mut libraries)?;
915        let library_keys = self.collect_library_keys(&needed, &libraries)?;
916        let mut required_with_dependencies = required.clone();
917        for id in required {
918            required_with_dependencies.extend(self.dependencies_inner(&index, id)?);
919        }
920        let mut local_ids = Vec::new();
921        let mut required_ids = Vec::new();
922        for &id in &needed {
923            let (file, name) = self.convert_artifact_id_to_lib_path(id);
924            if libraries.libs.get(&file).is_some_and(|libs| libs.contains_key(&name)) {
925                continue;
926            }
927            if required_with_dependencies.contains(id) {
928                required_ids.push(id);
929            } else {
930                let address = local_deployer.create(local_ids.len() as u64);
931                libraries.libs.entry(file).or_default().insert(name, address.to_checksum(None));
932                local_ids.push((id, address));
933            }
934        }
935
936        let mut pending = required_ids
937            .into_iter()
938            .map(|id| {
939                let contract = self.link(id, &libraries)?;
940                let bytecode = contract.bytecode.ok_or_else(|| LinkerError::LinkingFailed {
941                    artifact: id.source.to_string_lossy().into_owned(),
942                })?;
943                Ok((id, bytecode))
944            })
945            .collect::<Result<Vec<_>, LinkerError>>()?;
946        let mut onchain = Vec::new();
947        while !pending.is_empty() {
948            let Some(position) = pending.iter().position(|(_, code)| !code.object.is_unlinked())
949            else {
950                return Err(LinkerError::CyclicDependency);
951            };
952            let (id, code) = pending.swap_remove(position);
953            let bytecode = code.bytes().cloned().ok_or_else(|| LinkerError::LinkingFailed {
954                artifact: id.source.to_string_lossy().into_owned(),
955            })?;
956            let address = create2_deployer.create2_from_code(salt, &bytecode);
957            let (file, name) = self.convert_artifact_id_to_lib_path(id);
958            libraries
959                .libs
960                .entry(file.clone())
961                .or_default()
962                .insert(name.clone(), address.to_checksum(None));
963            for (target, pending_code) in &mut pending {
964                self.link_bytecode(pending_code.to_mut(), target, &file, &name, address)?;
965            }
966            onchain.push(LinkedLibrary { id: id.clone(), address, bytecode });
967        }
968
969        let local_bytecodes = local_ids
970            .iter()
971            .map(|(id, _)| self.linked_creation_bytecode(id, &libraries))
972            .collect::<Result<Vec<_>, LinkerError>>()?;
973        let mut linked_libraries = onchain.clone();
974        let local = local_ids
975            .into_iter()
976            .zip(local_bytecodes)
977            .map(|((id, address), bytecode)| LinkedLibrary { id: id.clone(), address, bytecode })
978            .collect::<Vec<_>>();
979        linked_libraries.extend(local.iter().cloned());
980        let libs_to_deploy = onchain.into_iter().map(|lib| lib.bytecode).collect();
981        let library_addresses = self.library_addresses(&library_keys, &libraries)?;
982        let artifact_addresses =
983            self.artifact_addresses_from_libraries(needed.iter().copied(), &libraries)?;
984        let artifact_libraries = BTreeMap::from([(target.clone(), libraries.clone())]);
985        Ok((
986            DetailedLinkOutput {
987                output: LinkOutput { libraries, library_addresses, libs_to_deploy },
988                artifact_libraries,
989                artifact_addresses,
990                linked_libraries,
991            },
992            local,
993        ))
994    }
995
996    /// Links given artifact with given libraries.
997    pub fn link(
998        &self,
999        target: &ArtifactId,
1000        libraries: &Libraries,
1001    ) -> Result<CompactContractBytecodeCow<'a>, LinkerError> {
1002        let mut contract =
1003            self.contracts.get(target).ok_or(LinkerError::MissingTargetArtifact)?.clone();
1004        let libraries = libraries
1005            .libs
1006            .iter()
1007            .flat_map(|(file, libraries)| {
1008                libraries.iter().map(move |(name, address)| {
1009                    Ok((
1010                        file,
1011                        name,
1012                        Address::from_str(address).map_err(LinkerError::InvalidAddress)?,
1013                    ))
1014                })
1015            })
1016            .collect::<Result<Vec<_>, LinkerError>>()?;
1017        let link = |bytecode: &mut CompactBytecode| -> Result<(), LinkerError> {
1018            for canonical in [false, true] {
1019                for &(file, name, address) in &libraries {
1020                    self.link_bytecode_inner(bytecode, target, file, name, address, canonical)?;
1021                }
1022            }
1023            Ok(())
1024        };
1025        if let Some(bytecode) = contract.bytecode.as_mut() {
1026            link(bytecode.to_mut())?;
1027        }
1028        if let Some(deployed_bytecode) =
1029            contract.deployed_bytecode.as_mut().and_then(|b| b.to_mut().bytecode.as_mut())
1030        {
1031            link(deployed_bytecode)?;
1032        }
1033        Ok(contract)
1034    }
1035
1036    /// Ensures that both initial and deployed bytecode are linked.
1037    pub fn ensure_linked(
1038        &self,
1039        contract: &CompactContractBytecodeCow<'a>,
1040        target: &ArtifactId,
1041    ) -> Result<(), LinkerError> {
1042        if let Some(bytecode) = &contract.bytecode
1043            && bytecode.object.is_unlinked()
1044        {
1045            return Err(LinkerError::LinkingFailed {
1046                artifact: target.source.to_string_lossy().into(),
1047            });
1048        }
1049        if let Some(deployed_bytecode) = &contract.deployed_bytecode
1050            && let Some(deployed_bytecode_obj) = &deployed_bytecode.bytecode
1051            && deployed_bytecode_obj.object.is_unlinked()
1052        {
1053            return Err(LinkerError::LinkingFailed {
1054                artifact: target.source.to_string_lossy().into(),
1055            });
1056        }
1057        Ok(())
1058    }
1059
1060    pub fn get_linked_artifacts(
1061        &self,
1062        libraries: &Libraries,
1063    ) -> Result<ArtifactContracts, LinkerError> {
1064        self.get_linked_artifacts_cow(libraries).map(ArtifactContracts::from_iter)
1065    }
1066
1067    pub fn get_linked_artifacts_cow(
1068        &self,
1069        libraries: &Libraries,
1070    ) -> Result<ArtifactContracts<CompactContractBytecodeCow<'a>>, LinkerError> {
1071        self.get_linked_artifacts_cow_with_artifact_libraries(libraries, &BTreeMap::new())
1072    }
1073
1074    pub fn get_linked_artifacts_cow_with_artifact_libraries(
1075        &self,
1076        libraries: &Libraries,
1077        artifact_libraries: &BTreeMap<ArtifactId, Libraries>,
1078    ) -> Result<ArtifactContracts<CompactContractBytecodeCow<'a>>, LinkerError> {
1079        self.contracts
1080            .par_iter()
1081            .map(|(id, _)| {
1082                let libraries = artifact_libraries.get(id).unwrap_or(libraries);
1083                Ok((id.clone(), self.link(id, libraries)?))
1084            })
1085            .collect::<Result<_, _>>()
1086            .map(ArtifactContracts)
1087    }
1088}
1089
1090impl<'a, 'b> Resolver<'a, 'b> {
1091    /// Creates a resolver that reuses artifact lookups across calls.
1092    pub const fn new(linker: &'b Linker<'a>) -> Self {
1093        Self { linker, index: OnceLock::new() }
1094    }
1095
1096    /// Returns the resolved addresses of all libraries required by `target`.
1097    pub fn linked_library_addresses(
1098        &self,
1099        target: &ArtifactId,
1100        libraries: &Libraries,
1101    ) -> Result<BTreeSet<Address>, LinkerError> {
1102        self.linker.linked_library_addresses_inner(&self.index, target, libraries)
1103    }
1104}
1105
1106#[cfg(test)]
1107mod tests {
1108    use super::*;
1109    use alloy_primitives::{address, fixed_bytes, map::HashMap};
1110    use foundry_compilers::{
1111        Project, ProjectCompileOutput, ProjectPathsConfig,
1112        artifacts::BytecodeObject,
1113        multi::MultiCompiler,
1114        solc::{Solc, SolcCompiler},
1115    };
1116    use semver::Version;
1117
1118    fn testdata() -> &'static Path {
1119        static CACHE: OnceLock<PathBuf> = OnceLock::new();
1120        CACHE.get_or_init(|| {
1121            PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../testdata").canonicalize().unwrap()
1122        })
1123    }
1124
1125    #[must_use]
1126    struct LinkerTest {
1127        project: Project,
1128        output: ProjectCompileOutput,
1129        dependency_assertions: HashMap<&'static str, Vec<(&'static str, Address)>>,
1130    }
1131
1132    impl LinkerTest {
1133        fn new(path: &Path, strip_prefixes: bool) -> Self {
1134            assert!(path.exists(), "Path {path:?} does not exist");
1135            let paths = ProjectPathsConfig::builder()
1136                .root(testdata())
1137                .lib(testdata().join("lib"))
1138                .sources(path)
1139                .tests(path)
1140                .build()
1141                .unwrap();
1142
1143            let solc = Solc::find_or_install(&Version::new(0, 8, 35)).unwrap();
1144            let project = Project::builder()
1145                .paths(paths)
1146                .ephemeral()
1147                .no_artifacts()
1148                .build(MultiCompiler { solc: Some(SolcCompiler::Specific(solc)), vyper: None })
1149                .unwrap();
1150
1151            let mut output = project.compile().unwrap();
1152
1153            if strip_prefixes {
1154                output = output.with_stripped_file_prefixes(project.root());
1155            }
1156
1157            Self { project, output, dependency_assertions: HashMap::default() }
1158        }
1159
1160        fn assert_dependencies(
1161            mut self,
1162            artifact_id: &'static str,
1163            deps: &[(&'static str, Address)],
1164        ) -> Self {
1165            self.dependency_assertions.insert(artifact_id, deps.to_vec());
1166            self
1167        }
1168
1169        fn test_with_sender_and_nonce(self, sender: Address, initial_nonce: u64) {
1170            let linker = Linker::new(self.project.root(), self.output.artifact_ids().collect());
1171            for (id, identifier) in self.iter_linking_targets(&linker) {
1172                let output = linker
1173                    .link_with_nonce_or_address(Default::default(), sender, initial_nonce, [id])
1174                    .expect("Linking failed");
1175                self.validate_assertions(identifier, output);
1176            }
1177        }
1178
1179        fn test_with_create2(self, sender: Address, salt: B256) {
1180            let linker = Linker::new(self.project.root(), self.output.artifact_ids().collect());
1181            for (id, identifier) in self.iter_linking_targets(&linker) {
1182                let output = linker
1183                    .link_with_create2(Default::default(), sender, salt, [id])
1184                    .expect("Linking failed");
1185                self.validate_assertions(identifier, output);
1186            }
1187        }
1188
1189        fn iter_linking_targets<'a>(
1190            &'a self,
1191            linker: &'a Linker<'_>,
1192        ) -> impl Iterator<Item = (&'a ArtifactId, String)> + 'a {
1193            self.sanity_check(linker);
1194            linker.contracts.keys().filter_map(move |id| {
1195                // If we didn't strip paths, artifacts will have absolute paths.
1196                // That's expected and we want to ensure that only `libraries` object has relative
1197                // paths, artifacts should be kept as is.
1198                let source = id
1199                    .source
1200                    .strip_prefix(self.project.root())
1201                    .unwrap_or(&id.source)
1202                    .to_string_lossy();
1203                let identifier = format!("{source}:{}", id.name);
1204
1205                // Skip test utils as they always have no dependencies.
1206                if identifier.contains("utils/") {
1207                    return None;
1208                }
1209
1210                Some((id, identifier))
1211            })
1212        }
1213
1214        fn sanity_check(&self, linker: &Linker<'_>) {
1215            assert!(!self.dependency_assertions.is_empty(), "Dependency assertions are empty");
1216            assert!(!linker.contracts.is_empty(), "Linker contracts are empty");
1217        }
1218
1219        fn validate_assertions(&self, identifier: String, output: LinkOutput) {
1220            let LinkOutput { libs_to_deploy, libraries, .. } = output;
1221
1222            let assertions = self
1223                .dependency_assertions
1224                .get(identifier.as_str())
1225                .unwrap_or_else(|| panic!("Unexpected artifact: {identifier}"));
1226
1227            assert_eq!(
1228                libs_to_deploy.len(),
1229                assertions.len(),
1230                "artifact {identifier} has more/less dependencies than expected ({} vs {}): {:#?}",
1231                libs_to_deploy.len(),
1232                assertions.len(),
1233                libs_to_deploy
1234            );
1235
1236            for &(dep_identifier, address) in assertions {
1237                let (file, name) = dep_identifier.split_once(':').unwrap();
1238                if let Some(lib_address) =
1239                    libraries.libs.get(Path::new(file)).and_then(|libs| libs.get(name))
1240                {
1241                    assert_eq!(
1242                        lib_address.parse::<Address>().unwrap(),
1243                        address,
1244                        "incorrect library address for dependency {dep_identifier} of {identifier}"
1245                    );
1246                } else {
1247                    panic!("Library {dep_identifier} not found");
1248                }
1249            }
1250        }
1251    }
1252
1253    fn link_test(path: impl AsRef<Path>, mut test_fn: impl FnMut(LinkerTest)) {
1254        fn link_test(path: &Path, test_fn: &mut dyn FnMut(LinkerTest)) {
1255            test_fn(LinkerTest::new(path, true));
1256            test_fn(LinkerTest::new(path, false));
1257        }
1258        link_test(path.as_ref(), &mut test_fn);
1259    }
1260
1261    #[test]
1262    #[should_panic = "assertions are empty"]
1263    fn no_assertions() {
1264        link_test(testdata().join("default/linking/simple"), |linker| {
1265            linker.test_with_sender_and_nonce(Address::default(), 1);
1266        });
1267    }
1268
1269    #[test]
1270    #[should_panic = "does not exist"]
1271    fn unknown_path() {
1272        link_test("doesnotexist", |linker| {
1273            linker
1274                .assert_dependencies("a:b", &[])
1275                .test_with_sender_and_nonce(Address::default(), 1);
1276        });
1277    }
1278
1279    #[test]
1280    fn link_simple() {
1281        link_test(testdata().join("default/linking/simple"), |linker| {
1282            linker
1283                .assert_dependencies("default/linking/simple/Simple.t.sol:Lib", &[])
1284                .assert_dependencies(
1285                    "default/linking/simple/Simple.t.sol:LibraryConsumer",
1286                    &[(
1287                        "default/linking/simple/Simple.t.sol:Lib",
1288                        address!("0x5a443704dd4b594b382c22a083e2bd3090a6fef3"),
1289                    )],
1290                )
1291                .assert_dependencies(
1292                    "default/linking/simple/Simple.t.sol:SimpleLibraryLinkingTest",
1293                    &[(
1294                        "default/linking/simple/Simple.t.sol:Lib",
1295                        address!("0x5a443704dd4b594b382c22a083e2bd3090a6fef3"),
1296                    )],
1297                )
1298                .test_with_sender_and_nonce(Address::default(), 1);
1299        });
1300    }
1301
1302    #[test]
1303    fn link_nested() {
1304        link_test(testdata().join("default/linking/nested"), |linker| {
1305            linker
1306                .assert_dependencies("default/linking/nested/Nested.t.sol:Lib", &[])
1307                .assert_dependencies(
1308                    "default/linking/nested/Nested.t.sol:NestedLib",
1309                    &[(
1310                        "default/linking/nested/Nested.t.sol:Lib",
1311                        address!("0x5a443704dd4b594b382c22a083e2bd3090a6fef3"),
1312                    )],
1313                )
1314                .assert_dependencies(
1315                    "default/linking/nested/Nested.t.sol:LibraryConsumer",
1316                    &[
1317                        // Lib shows up here twice, because the linker sees it twice, but it should
1318                        // have the same address and nonce.
1319                        (
1320                            "default/linking/nested/Nested.t.sol:Lib",
1321                            address!("0x5a443704dd4b594b382c22a083e2bd3090a6fef3"),
1322                        ),
1323                        (
1324                            "default/linking/nested/Nested.t.sol:NestedLib",
1325                            address!("0x47e9Fbef8C83A1714F1951F142132E6e90F5fa5D"),
1326                        ),
1327                    ],
1328                )
1329                .assert_dependencies(
1330                    "default/linking/nested/Nested.t.sol:NestedLibraryLinkingTest",
1331                    &[
1332                        (
1333                            "default/linking/nested/Nested.t.sol:Lib",
1334                            address!("0x5a443704dd4b594b382c22a083e2bd3090a6fef3"),
1335                        ),
1336                        (
1337                            "default/linking/nested/Nested.t.sol:NestedLib",
1338                            address!("0x47e9fbef8c83a1714f1951f142132e6e90f5fa5d"),
1339                        ),
1340                    ],
1341                )
1342                .test_with_sender_and_nonce(Address::default(), 1);
1343        });
1344    }
1345
1346    #[test]
1347    fn link_duplicate() {
1348        link_test(testdata().join("default/linking/duplicate"), |linker| {
1349            linker
1350                .assert_dependencies("default/linking/duplicate/Duplicate.t.sol:A", &[])
1351                .assert_dependencies("default/linking/duplicate/Duplicate.t.sol:B", &[])
1352                .assert_dependencies(
1353                    "default/linking/duplicate/Duplicate.t.sol:C",
1354                    &[(
1355                        "default/linking/duplicate/Duplicate.t.sol:A",
1356                        address!("0x5a443704dd4b594b382c22a083e2bd3090a6fef3"),
1357                    )],
1358                )
1359                .assert_dependencies(
1360                    "default/linking/duplicate/Duplicate.t.sol:D",
1361                    &[(
1362                        "default/linking/duplicate/Duplicate.t.sol:B",
1363                        address!("0x5a443704dd4b594b382c22a083e2bd3090a6fef3"),
1364                    )],
1365                )
1366                .assert_dependencies(
1367                    "default/linking/duplicate/Duplicate.t.sol:E",
1368                    &[
1369                        (
1370                            "default/linking/duplicate/Duplicate.t.sol:A",
1371                            address!("0x5a443704dd4b594b382c22a083e2bd3090a6fef3"),
1372                        ),
1373                        (
1374                            "default/linking/duplicate/Duplicate.t.sol:C",
1375                            address!("0x47e9fbef8c83a1714f1951f142132e6e90f5fa5d"),
1376                        ),
1377                    ],
1378                )
1379                .assert_dependencies(
1380                    "default/linking/duplicate/Duplicate.t.sol:LibraryConsumer",
1381                    &[
1382                        (
1383                            "default/linking/duplicate/Duplicate.t.sol:A",
1384                            address!("0x5a443704dd4b594b382c22a083e2bd3090a6fef3"),
1385                        ),
1386                        (
1387                            "default/linking/duplicate/Duplicate.t.sol:B",
1388                            address!("0x47e9fbef8c83a1714f1951f142132e6e90f5fa5d"),
1389                        ),
1390                        (
1391                            "default/linking/duplicate/Duplicate.t.sol:C",
1392                            address!("0x8be503bcded90ed42eff31f56199399b2b0154ca"),
1393                        ),
1394                        (
1395                            "default/linking/duplicate/Duplicate.t.sol:D",
1396                            address!("0x47c5e40890bce4a473a49d7501808b9633f29782"),
1397                        ),
1398                        (
1399                            "default/linking/duplicate/Duplicate.t.sol:E",
1400                            address!("0x29b2440db4a256b0c1e6d3b4cdcaa68e2440a08f"),
1401                        ),
1402                    ],
1403                )
1404                .assert_dependencies(
1405                    "default/linking/duplicate/Duplicate.t.sol:DuplicateLibraryLinkingTest",
1406                    &[
1407                        (
1408                            "default/linking/duplicate/Duplicate.t.sol:A",
1409                            address!("0x5a443704dd4b594b382c22a083e2bd3090a6fef3"),
1410                        ),
1411                        (
1412                            "default/linking/duplicate/Duplicate.t.sol:B",
1413                            address!("0x47e9fbef8c83a1714f1951f142132e6e90f5fa5d"),
1414                        ),
1415                        (
1416                            "default/linking/duplicate/Duplicate.t.sol:C",
1417                            address!("0x8be503bcded90ed42eff31f56199399b2b0154ca"),
1418                        ),
1419                        (
1420                            "default/linking/duplicate/Duplicate.t.sol:D",
1421                            address!("0x47c5e40890bce4a473a49d7501808b9633f29782"),
1422                        ),
1423                        (
1424                            "default/linking/duplicate/Duplicate.t.sol:E",
1425                            address!("0x29b2440db4a256b0c1e6d3b4cdcaa68e2440a08f"),
1426                        ),
1427                    ],
1428                )
1429                .test_with_sender_and_nonce(Address::default(), 1);
1430        });
1431    }
1432
1433    #[test]
1434    fn link_cycle() {
1435        link_test(testdata().join("default/linking/cycle"), |linker| {
1436            linker
1437                .assert_dependencies(
1438                    "default/linking/cycle/Cycle.t.sol:Foo",
1439                    &[
1440                        (
1441                            "default/linking/cycle/Cycle.t.sol:Foo",
1442                            address!("0x47e9Fbef8C83A1714F1951F142132E6e90F5fa5D"),
1443                        ),
1444                        (
1445                            "default/linking/cycle/Cycle.t.sol:Bar",
1446                            address!("0x5a443704dd4B594B382c22a083e2BD3090A6feF3"),
1447                        ),
1448                    ],
1449                )
1450                .assert_dependencies(
1451                    "default/linking/cycle/Cycle.t.sol:Bar",
1452                    &[
1453                        (
1454                            "default/linking/cycle/Cycle.t.sol:Foo",
1455                            address!("0x47e9Fbef8C83A1714F1951F142132E6e90F5fa5D"),
1456                        ),
1457                        (
1458                            "default/linking/cycle/Cycle.t.sol:Bar",
1459                            address!("0x5a443704dd4B594B382c22a083e2BD3090A6feF3"),
1460                        ),
1461                    ],
1462                )
1463                .test_with_sender_and_nonce(Address::default(), 1);
1464        });
1465    }
1466
1467    #[test]
1468    #[ignore = "addresses depend on testdata utils internals for some reason"]
1469    fn link_create2_nested() {
1470        link_test(testdata().join("default/linking/nested"), |linker| {
1471            linker
1472                .assert_dependencies("default/linking/nested/Nested.t.sol:Lib", &[])
1473                .assert_dependencies(
1474                    "default/linking/nested/Nested.t.sol:NestedLib",
1475                    &[(
1476                        "default/linking/nested/Nested.t.sol:Lib",
1477                        address!("0x773253227cce756e50c3993ec6366b3ec27786f9"),
1478                    )],
1479                )
1480                .assert_dependencies(
1481                    "default/linking/nested/Nested.t.sol:LibraryConsumer",
1482                    &[
1483                        // Lib shows up here twice, because the linker sees it twice, but it should
1484                        // have the same address and nonce.
1485                        (
1486                            "default/linking/nested/Nested.t.sol:Lib",
1487                            address!("0x773253227cce756e50c3993ec6366b3ec27786f9"),
1488                        ),
1489                        (
1490                            "default/linking/nested/Nested.t.sol:NestedLib",
1491                            address!("0xac231df03403867b05d092c26fc91b6b83f4bebe"),
1492                        ),
1493                    ],
1494                )
1495                .assert_dependencies(
1496                    "default/linking/nested/Nested.t.sol:NestedLibraryLinkingTest",
1497                    &[
1498                        (
1499                            "default/linking/nested/Nested.t.sol:Lib",
1500                            address!("0x773253227cce756e50c3993ec6366b3ec27786f9"),
1501                        ),
1502                        (
1503                            "default/linking/nested/Nested.t.sol:NestedLib",
1504                            address!("0xac231df03403867b05d092c26fc91b6b83f4bebe"),
1505                        ),
1506                    ],
1507                )
1508                .test_with_create2(
1509                    Address::default(),
1510                    fixed_bytes!(
1511                        "19bf59b7b67ae8edcbc6e53616080f61fa99285c061450ad601b0bc40c9adfc9"
1512                    ),
1513                );
1514        });
1515    }
1516
1517    #[test]
1518    fn link_samefile_union() {
1519        link_test(testdata().join("default/linking/samefile_union"), |linker| {
1520            linker
1521                .assert_dependencies("default/linking/samefile_union/Libs.sol:LInit", &[])
1522                .assert_dependencies("default/linking/samefile_union/Libs.sol:LRun", &[])
1523                .assert_dependencies(
1524                    "default/linking/samefile_union/SameFileUnion.t.sol:UsesBoth",
1525                    &[
1526                        (
1527                            "default/linking/samefile_union/Libs.sol:LInit",
1528                            address!("0x5a443704dd4b594b382c22a083e2bd3090a6fef3"),
1529                        ),
1530                        (
1531                            "default/linking/samefile_union/Libs.sol:LRun",
1532                            address!("0x47e9fbef8c83a1714f1951f142132e6e90f5fa5d"),
1533                        ),
1534                    ],
1535                )
1536                .test_with_sender_and_nonce(Address::default(), 1);
1537        });
1538    }
1539
1540    #[test]
1541    fn link_create2_multiple_targets_deduplicates_shared_dependencies() {
1542        let test = LinkerTest::new(&testdata().join("default/linking/simple"), true);
1543        let linker = Linker::new(test.project.root(), test.output.artifact_ids().collect());
1544        let consumer = linker.contracts.keys().find(|id| id.name == "LibraryConsumer").unwrap();
1545        let test_contract =
1546            linker.contracts.keys().find(|id| id.name == "SimpleLibraryLinkingTest").unwrap();
1547
1548        let output = linker
1549            .link_with_create2(
1550                Libraries::default(),
1551                Address::ZERO,
1552                B256::with_last_byte(1),
1553                [consumer, test_contract],
1554            )
1555            .unwrap();
1556
1557        assert_eq!(output.libs_to_deploy.len(), 1);
1558        assert_eq!(output.libraries.libs.values().map(BTreeMap::len).sum::<usize>(), 1);
1559
1560        let linked_address = output
1561            .libraries
1562            .libs
1563            .values()
1564            .flat_map(|libraries| libraries.values())
1565            .next()
1566            .unwrap()
1567            .parse::<Address>()
1568            .unwrap();
1569        for target in [consumer, test_contract] {
1570            let bytecode = linker.link(target, &output.libraries).unwrap().bytecode.unwrap();
1571            assert!(
1572                bytecode
1573                    .bytes()
1574                    .unwrap()
1575                    .windows(Address::len_bytes())
1576                    .any(|window| { window == linked_address.as_slice() }),
1577                "{} was not linked to {linked_address}",
1578                target.name
1579            );
1580        }
1581    }
1582
1583    #[test]
1584    fn detailed_linking_includes_transitive_library_addresses() {
1585        let test = LinkerTest::new(&testdata().join("default/linking/nested"), true);
1586        let linker = Linker::new(test.project.root(), test.output.artifact_ids().collect());
1587        let consumer = linker.contracts.keys().find(|id| id.name == "LibraryConsumer").unwrap();
1588        let resolver = Resolver::new(&linker);
1589
1590        let create2 = linker
1591            .link_with_create2_detailed(Libraries::default(), Address::ZERO, B256::ZERO, [consumer])
1592            .unwrap();
1593        let libraries = create2.artifact_libraries.get(consumer).unwrap();
1594        assert_eq!(resolver.linked_library_addresses(consumer, libraries).unwrap().len(), 2);
1595
1596        let nonce = linker
1597            .link_with_nonce_or_address_detailed(Libraries::default(), Address::ZERO, 0, [consumer])
1598            .unwrap();
1599        let libraries = nonce.artifact_libraries.get(consumer).unwrap();
1600        assert_eq!(resolver.linked_library_addresses(consumer, libraries).unwrap().len(), 2);
1601    }
1602
1603    #[test]
1604    fn linking_preserves_transitive_profile_identity() {
1605        let test = LinkerTest::new(&testdata().join("default/linking/profile_nested"), true);
1606        let linker = Linker::new(test.project.root(), test.output.artifact_ids().collect());
1607        let find = |name| {
1608            linker
1609                .contracts
1610                .iter()
1611                .find(|(id, _)| id.name == name)
1612                .map(|(id, contract)| (id.clone(), contract.clone()))
1613                .unwrap()
1614        };
1615        let (inner_id, inner) = find("Inner");
1616        let (outer_id, outer) = find("Outer");
1617        let (consumer_id, consumer) = find("Consumer");
1618
1619        let mut contracts = linker.contracts.clone();
1620        let mut other_inner_id = inner_id.clone();
1621        other_inner_id.build_id = "other".to_string();
1622        other_inner_id.profile = "other".to_string();
1623        contracts.insert(other_inner_id.clone(), inner);
1624        let mut other_outer_id = outer_id.clone();
1625        other_outer_id.build_id = "other".to_string();
1626        other_outer_id.profile = "other".to_string();
1627        contracts.insert(other_outer_id.clone(), outer);
1628        let mut other_consumer_id = consumer_id.clone();
1629        other_consumer_id.build_id = "other".to_string();
1630        other_consumer_id.profile = "other".to_string();
1631        contracts.insert(other_consumer_id.clone(), consumer);
1632
1633        for id in [&other_inner_id, &other_outer_id] {
1634            let bytecode = contracts.get_mut(id).unwrap().bytecode.as_mut().unwrap().to_mut();
1635            match &mut bytecode.object {
1636                BytecodeObject::Bytecode(bytes) => {
1637                    let mut distinct = bytes.to_vec();
1638                    distinct.push(0);
1639                    *bytes = distinct.into();
1640                }
1641                BytecodeObject::Unlinked(code) => code.push_str("00"),
1642            }
1643        }
1644
1645        let linker = Linker::new(test.project.root(), contracts);
1646        let consumers = [&consumer_id, &other_consumer_id];
1647        let profiles = [
1648            (&consumer_id, &outer_id, &inner_id),
1649            (&other_consumer_id, &other_outer_id, &other_inner_id),
1650        ];
1651        let assert_identity = |output: &DetailedLinkOutput| {
1652            assert_eq!(output.artifact_addresses.len(), 4);
1653            assert_eq!(
1654                output.output.libs_to_deploy,
1655                output
1656                    .linked_libraries
1657                    .iter()
1658                    .map(|library| library.bytecode.clone())
1659                    .collect::<Vec<_>>()
1660            );
1661
1662            for linked in &output.linked_libraries {
1663                assert_eq!(output.artifact_addresses[&linked.id], linked.address);
1664                assert_eq!(
1665                    linker
1666                        .linked_creation_bytecode(
1667                            &linked.id,
1668                            &output.artifact_libraries[&linked.id],
1669                        )
1670                        .unwrap(),
1671                    linked.bytecode
1672                );
1673            }
1674
1675            for (index, &(consumer, outer, inner)) in profiles.iter().enumerate() {
1676                let sibling_outer = profiles[1 - index].1;
1677                let sibling_inner = profiles[1 - index].2;
1678                let outer_address = output.artifact_addresses[outer];
1679                let inner_address = output.artifact_addresses[inner];
1680
1681                let consumer_bytecode = linker
1682                    .link(consumer, &output.artifact_libraries[consumer])
1683                    .unwrap()
1684                    .get_bytecode_bytes()
1685                    .unwrap()
1686                    .into_owned();
1687                assert!(
1688                    consumer_bytecode
1689                        .windows(Address::len_bytes())
1690                        .any(|window| { window == outer_address.as_slice() })
1691                );
1692                assert!(!consumer_bytecode.windows(Address::len_bytes()).any(|window| {
1693                    window == output.artifact_addresses[sibling_outer].as_slice()
1694                }));
1695
1696                let outer_bytecode = &output
1697                    .linked_libraries
1698                    .iter()
1699                    .find(|library| library.id == *outer)
1700                    .unwrap()
1701                    .bytecode;
1702                assert!(
1703                    outer_bytecode
1704                        .windows(Address::len_bytes())
1705                        .any(|window| window == inner_address.as_slice())
1706                );
1707                assert!(!outer_bytecode.windows(Address::len_bytes()).any(|window| {
1708                    window == output.artifact_addresses[sibling_inner].as_slice()
1709                }));
1710            }
1711        };
1712
1713        let sender = address!("1000000000000000000000000000000000000000");
1714        let nonce = 7;
1715        let output = linker
1716            .link_with_nonce_or_address_detailed(Libraries::default(), sender, nonce, consumers)
1717            .unwrap();
1718        assert_identity(&output);
1719        for (index, library) in output.linked_libraries.iter().enumerate() {
1720            assert_eq!(library.address, sender.create(nonce + index as u64));
1721        }
1722
1723        let salt = B256::with_last_byte(1);
1724        let output = linker
1725            .link_with_create2_detailed(Libraries::default(), sender, salt, consumers)
1726            .unwrap();
1727        assert_identity(&output);
1728        for library in &output.linked_libraries {
1729            assert_eq!(library.address, sender.create2_from_code(salt, &library.bytecode));
1730        }
1731    }
1732
1733    #[test]
1734    fn linking_handles_library_key_collisions_across_profiles() {
1735        let test = LinkerTest::new(&testdata().join("default/linking/simple"), true);
1736        let linker = Linker::new(test.project.root(), test.output.artifact_ids().collect());
1737        let (library_id, library) = linker
1738            .contracts
1739            .iter()
1740            .find(|(id, _)| id.name == "Lib")
1741            .map(|(id, contract)| (id.clone(), contract.clone()))
1742            .unwrap();
1743        let (consumer_id, consumer) = linker
1744            .contracts
1745            .iter()
1746            .find(|(id, _)| id.name == "LibraryConsumer")
1747            .map(|(id, contract)| (id.clone(), contract.clone()))
1748            .unwrap();
1749
1750        let mut contracts = linker.contracts.clone();
1751        let mut other_library_id = library_id.clone();
1752        other_library_id.build_id = "other".to_string();
1753        other_library_id.profile = "other".to_string();
1754        contracts.insert(other_library_id.clone(), library);
1755        let mut other_consumer_id = consumer_id.clone();
1756        other_consumer_id.build_id = "other".to_string();
1757        other_consumer_id.profile = "other".to_string();
1758        contracts.insert(other_consumer_id.clone(), consumer);
1759
1760        let linker = Linker::new(test.project.root(), contracts.clone());
1761        let detailed = linker
1762            .link_with_create2_detailed(
1763                Libraries::default(),
1764                Address::ZERO,
1765                B256::ZERO,
1766                [&consumer_id, &other_consumer_id],
1767            )
1768            .unwrap();
1769        assert_eq!(detailed.linked_libraries.len(), 1);
1770        assert_eq!(detailed.artifact_addresses.len(), 2);
1771        assert_eq!(detailed.artifact_addresses[&library_id], detailed.linked_libraries[0].address);
1772        assert_eq!(
1773            detailed.artifact_addresses[&other_library_id],
1774            detailed.linked_libraries[0].address
1775        );
1776
1777        let output = linker
1778            .link_with_create2(
1779                Libraries::default(),
1780                Address::ZERO,
1781                B256::ZERO,
1782                [&consumer_id, &other_consumer_id],
1783            )
1784            .unwrap();
1785        assert_eq!(output.libs_to_deploy.len(), 1);
1786
1787        let Err(err) = linker.link_with_nonce_or_address(
1788            Libraries::default(),
1789            Address::ZERO,
1790            0,
1791            [&consumer_id, &other_consumer_id],
1792        ) else {
1793            panic!("expected conflicting library artifacts");
1794        };
1795        assert!(matches!(err, LinkerError::ConflictingLibraryArtifacts { .. }));
1796
1797        let other_library = contracts.get_mut(&other_library_id).unwrap();
1798        let bytecode = other_library.bytecode.as_mut().unwrap().to_mut();
1799        let mut bytes = bytecode.object.as_bytes().unwrap().to_vec();
1800        bytes.push(0);
1801        bytecode.object = BytecodeObject::Bytecode(bytes.into());
1802
1803        let linker = Linker::new(test.project.root(), contracts);
1804        let output = linker
1805            .link_with_create2_detailed(
1806                Libraries::default(),
1807                Address::ZERO,
1808                B256::ZERO,
1809                [&consumer_id, &other_consumer_id],
1810            )
1811            .unwrap();
1812        assert_eq!(output.linked_libraries.len(), 2);
1813        assert_ne!(output.linked_libraries[0].address, output.linked_libraries[1].address);
1814        for (target, library) in
1815            [(&consumer_id, &library_id), (&other_consumer_id, &other_library_id)]
1816        {
1817            let expected = output
1818                .linked_libraries
1819                .iter()
1820                .find(|linked| linked.id == *library)
1821                .unwrap()
1822                .address;
1823            let (file, name) = linker.convert_artifact_id_to_lib_path(library);
1824            let actual =
1825                output.artifact_libraries[target].libs[&file][&name].parse::<Address>().unwrap();
1826            assert_eq!(actual, expected);
1827        }
1828
1829        let Err(err) = linker.link_with_create2(
1830            Libraries::default(),
1831            Address::ZERO,
1832            B256::ZERO,
1833            [&consumer_id, &other_consumer_id],
1834        ) else {
1835            panic!("expected conflicting library artifacts");
1836        };
1837        assert!(matches!(err, LinkerError::ConflictingLibraryArtifacts { .. }));
1838
1839        let output = linker
1840            .link_with_nonce_or_address_detailed(
1841                Libraries::default(),
1842                Address::ZERO,
1843                0,
1844                [&consumer_id, &other_consumer_id],
1845            )
1846            .unwrap();
1847        assert_eq!(output.linked_libraries.len(), 2);
1848        assert_ne!(output.linked_libraries[0].address, output.linked_libraries[1].address);
1849        for (target, library) in
1850            [(&consumer_id, &library_id), (&other_consumer_id, &other_library_id)]
1851        {
1852            let expected = output
1853                .linked_libraries
1854                .iter()
1855                .find(|linked| linked.id == *library)
1856                .unwrap()
1857                .address;
1858            let (file, name) = linker.convert_artifact_id_to_lib_path(library);
1859            let actual =
1860                output.artifact_libraries[target].libs[&file][&name].parse::<Address>().unwrap();
1861            assert_eq!(actual, expected);
1862        }
1863
1864        let Err(err) = linker.link_with_nonce_or_address(
1865            Libraries::default(),
1866            Address::ZERO,
1867            0,
1868            [&consumer_id, &other_consumer_id],
1869        ) else {
1870            panic!("expected conflicting library artifacts");
1871        };
1872        assert!(matches!(err, LinkerError::ConflictingLibraryArtifacts { .. }));
1873
1874        let configured_address = Address::with_last_byte(1);
1875        let (file, name) = linker.convert_artifact_id_to_lib_path(&library_id);
1876        let mut libraries = Libraries::default();
1877        libraries.libs.entry(file).or_default().insert(name, configured_address.to_checksum(None));
1878
1879        let output = linker
1880            .link_with_create2(
1881                libraries.clone(),
1882                Address::ZERO,
1883                B256::ZERO,
1884                [&consumer_id, &other_consumer_id],
1885            )
1886            .unwrap();
1887        assert!(output.libs_to_deploy.is_empty());
1888        assert_eq!(output.library_addresses, [configured_address]);
1889
1890        let output = linker
1891            .link_with_nonce_or_address(
1892                libraries,
1893                Address::ZERO,
1894                0,
1895                [&consumer_id, &other_consumer_id],
1896            )
1897            .unwrap();
1898        assert!(output.libs_to_deploy.is_empty());
1899        assert_eq!(output.library_addresses, [configured_address]);
1900    }
1901
1902    #[test]
1903    fn linking_resolves_same_version_library_from_target_build_or_profile() {
1904        let test = LinkerTest::new(&testdata().join("default/linking/simple"), true);
1905        let linker = Linker::new(test.project.root(), test.output.artifact_ids().collect());
1906        let (library_id, library) = linker
1907            .contracts
1908            .iter()
1909            .find(|(id, _)| id.name == "Lib")
1910            .map(|(id, contract)| (id.clone(), contract.clone()))
1911            .unwrap();
1912        let (consumer_id, consumer) = linker
1913            .contracts
1914            .iter()
1915            .find(|(id, _)| id.name == "LibraryConsumer")
1916            .map(|(id, contract)| (id.clone(), contract.clone()))
1917            .unwrap();
1918
1919        let mut contracts = linker.contracts.clone();
1920        let mut stale_consumer_id = consumer_id.clone();
1921        stale_consumer_id.build_id = "stale".to_string();
1922        contracts.insert(stale_consumer_id.clone(), consumer.clone());
1923        let mut other_library_id = library_id;
1924        other_library_id.build_id = "other".to_string();
1925        other_library_id.profile = "other".to_string();
1926        contracts.insert(other_library_id, library);
1927        let mut ambiguous_consumer_id = consumer_id.clone();
1928        ambiguous_consumer_id.build_id = "ambiguous".to_string();
1929        ambiguous_consumer_id.profile = "ambiguous".to_string();
1930        contracts.insert(ambiguous_consumer_id.clone(), consumer);
1931
1932        let linker = Linker::new(test.project.root(), contracts);
1933        linker
1934            .link_with_create2(Libraries::default(), Address::ZERO, B256::ZERO, [&consumer_id])
1935            .unwrap();
1936        linker
1937            .link_with_create2(
1938                Libraries::default(),
1939                Address::ZERO,
1940                B256::ZERO,
1941                [&stale_consumer_id],
1942            )
1943            .unwrap();
1944
1945        let Err(err) = linker.link_with_create2(
1946            Libraries::default(),
1947            Address::ZERO,
1948            B256::ZERO,
1949            [&ambiguous_consumer_id],
1950        ) else {
1951            panic!("expected conflicting library artifacts");
1952        };
1953        assert!(matches!(err, LinkerError::ConflictingLibraryArtifacts { .. }));
1954    }
1955
1956    #[test]
1957    fn link_output_excludes_unreferenced_configured_libraries() {
1958        let test = LinkerTest::new(&testdata().join("default/linking/simple"), true);
1959        let linker = Linker::new(test.project.root(), test.output.artifact_ids().collect());
1960        let consumer = linker.contracts.keys().find(|id| id.name == "LibraryConsumer").unwrap();
1961        let unrelated = Address::with_last_byte(1);
1962        let mut libraries = Libraries::default();
1963        libraries
1964            .libs
1965            .entry("src/Unrelated.sol".into())
1966            .or_default()
1967            .insert("Unrelated".to_string(), unrelated.to_checksum(None));
1968
1969        let output =
1970            linker.link_with_create2(libraries, Address::ZERO, B256::ZERO, [consumer]).unwrap();
1971
1972        assert_eq!(output.library_addresses.len(), 1);
1973        assert!(!output.library_addresses.contains(&unrelated));
1974    }
1975
1976    #[test]
1977    fn exact_artifact_match_uses_configured_library_alias() {
1978        let test = LinkerTest::new(&testdata().join("default/linking/simple"), true);
1979        let linker = Linker::new(test.project.root(), test.output.artifact_ids().collect());
1980        let mut contracts = linker.contracts.clone();
1981        let (library_id, library) = contracts
1982            .iter()
1983            .find(|(id, _)| id.name == "Lib")
1984            .map(|(id, contract)| (id.clone(), contract.clone()))
1985            .unwrap();
1986        let mut alias_id = library_id.clone();
1987        alias_id.source = "./default/linking/simple/Simple.t.sol".into();
1988        contracts.insert(alias_id, library);
1989        let linker = Linker::new(test.project.root(), contracts);
1990        let consumer = linker.contracts.keys().find(|id| id.name == "LibraryConsumer").unwrap();
1991        let configured = Address::with_last_byte(1);
1992        let alias = PathBuf::from("./default/linking/simple/Simple.t.sol");
1993        let generated_key = PathBuf::from("default/linking/simple/Simple.t.sol");
1994        let mut libraries = Libraries::default();
1995        libraries
1996            .libs
1997            .entry(alias.clone())
1998            .or_default()
1999            .insert("Lib".to_string(), configured.to_checksum(None));
2000
2001        let output =
2002            linker.link_with_nonce_or_address(libraries, Address::ZERO, 1, [consumer]).unwrap();
2003        let bytecode = linker.link(consumer, &output.libraries).unwrap().bytecode.unwrap();
2004        let bytecode = bytecode.bytes().unwrap();
2005
2006        assert!(output.libs_to_deploy.is_empty());
2007        assert_eq!(output.library_addresses, [configured]);
2008        assert!(
2009            bytecode.windows(Address::len_bytes()).any(|window| window == configured.as_slice())
2010        );
2011        assert_eq!(output.libraries.libs.len(), 2);
2012        assert!(output.libraries.libs.contains_key(&alias));
2013        assert!(output.libraries.libs.contains_key(&generated_key));
2014
2015        let exact = Address::with_last_byte(2);
2016        let references = BTreeMap::from([(&library_id, BTreeSet::from([alias.clone()]))]);
2017        let mut libraries = output.libraries;
2018        libraries.libs.get_mut(&alias).unwrap().insert("Lib".into(), exact.to_checksum(None));
2019        linker.apply_configured_references(&references, &mut libraries).unwrap();
2020        assert_eq!(libraries.libs[&generated_key]["Lib"], exact.to_checksum(None));
2021
2022        libraries
2023            .libs
2024            .get_mut(&generated_key)
2025            .unwrap()
2026            .insert("Lib".into(), configured.to_checksum(None));
2027        let fallback = PathBuf::from("default/linking/simple/../simple/Simple.t.sol");
2028        let references = BTreeMap::from([(&library_id, BTreeSet::from([fallback]))]);
2029        let err = linker.apply_configured_references(&references, &mut libraries).unwrap_err();
2030        assert!(matches!(err, LinkerError::ConflictingLibraryArtifacts { .. }));
2031    }
2032
2033    #[test]
2034    fn partition_with_nonce_assigns_required_and_local_libraries() {
2035        let test = LinkerTest::new(&testdata().join("default/linking/samefile_union"), true);
2036        let linker = Linker::new(test.project.root(), test.output.artifact_ids().collect());
2037        let find = |name| linker.contracts.keys().find(|id| id.name == name).unwrap();
2038        let (target, required_id) = (find("UsesBoth"), find("LInit").clone());
2039        let sender = address!("0x1000000000000000000000000000000000000000");
2040        let local_deployer = address!("0x2000000000000000000000000000000000000000");
2041        let required = BTreeSet::from([required_id.clone()]);
2042        let (detailed, local) = linker
2043            .link_with_partition(Libraries::default(), sender, 7, local_deployer, &required, target)
2044            .unwrap();
2045
2046        assert_eq!(detailed.linked_libraries.len(), 2);
2047        assert_eq!(detailed.output.libs_to_deploy.len(), 1);
2048        assert_eq!(local.len(), 1);
2049        assert_eq!(
2050            detailed.linked_libraries.iter().find(|lib| lib.id == required_id).unwrap().address,
2051            sender.create(7)
2052        );
2053        assert_eq!(local[0].address, local_deployer.create(0));
2054        linker
2055            .ensure_linked(&linker.link(target, &detailed.output.libraries).unwrap(), target)
2056            .unwrap();
2057        for library in &detailed.linked_libraries {
2058            assert!(!library.bytecode.is_empty());
2059        }
2060
2061        let mut configured = Libraries::default();
2062        let (file, name) = linker.convert_artifact_id_to_lib_path(find("LRun"));
2063        configured.libs.entry(file).or_default().insert(name, Address::ZERO.to_checksum(None));
2064        let (configured, local) = linker
2065            .link_with_partition(configured, sender, 7, local_deployer, &required, target)
2066            .unwrap();
2067        assert_eq!(configured.linked_libraries.len(), 1);
2068        assert!(local.is_empty());
2069    }
2070
2071    #[test]
2072    fn partition_with_create2_assigns_required_and_local_libraries() {
2073        let test = LinkerTest::new(&testdata().join("default/linking/samefile_union"), true);
2074        let linker = Linker::new(test.project.root(), test.output.artifact_ids().collect());
2075        let find = |name| linker.contracts.keys().find(|id| id.name == name).unwrap();
2076        let (target, required_id) = (find("UsesBoth"), find("LInit").clone());
2077        let required = BTreeSet::from([required_id.clone()]);
2078        let deployer = address!("0x3000000000000000000000000000000000000000");
2079        let local_deployer = address!("0x4000000000000000000000000000000000000000");
2080        let salt = fixed_bytes!("19bf59b7b67ae8edcbc6e53616080f61fa99285c061450ad601b0bc40c9adfc9");
2081        let (detailed, local) = linker
2082            .link_with_create2_partition(
2083                Libraries::default(),
2084                deployer,
2085                salt,
2086                local_deployer,
2087                &required,
2088                target,
2089            )
2090            .unwrap();
2091
2092        assert_eq!(detailed.output.libs_to_deploy.len(), 1);
2093        assert_eq!(local.len(), 1);
2094        let onchain =
2095            detailed.linked_libraries.iter().find(|library| library.id == required_id).unwrap();
2096        assert_eq!(onchain.address, deployer.create2_from_code(salt, &onchain.bytecode));
2097        assert_eq!(detailed.output.libs_to_deploy[0], onchain.bytecode);
2098        assert_eq!(local[0].address, local_deployer.create(0));
2099        linker
2100            .ensure_linked(&linker.link(target, &detailed.output.libraries).unwrap(), target)
2101            .unwrap();
2102    }
2103
2104    #[test]
2105    fn partition_with_create2_keeps_transitive_order_deterministic() {
2106        let test = LinkerTest::new(&testdata().join("default/linking/nested"), true);
2107        let linker = Linker::new(test.project.root(), test.output.artifact_ids().collect());
2108        let find = |name| linker.contracts.keys().find(|id| id.name == name).unwrap();
2109        let target = find("LibraryConsumer");
2110        let required = BTreeSet::from([find("NestedLib").clone()]);
2111        let deployer = address!("0x3000000000000000000000000000000000000000");
2112        let local_deployer = address!("0x4000000000000000000000000000000000000000");
2113        let salt = fixed_bytes!("19bf59b7b67ae8edcbc6e53616080f61fa99285c061450ad601b0bc40c9adfc9");
2114        let link = || {
2115            linker
2116                .link_with_create2_partition(
2117                    Libraries::default(),
2118                    deployer,
2119                    salt,
2120                    local_deployer,
2121                    &required,
2122                    target,
2123                )
2124                .unwrap()
2125        };
2126        let (first, local) = link();
2127        let (second, _) = link();
2128
2129        assert!(local.is_empty());
2130        assert_eq!(first.output.libs_to_deploy.len(), 2);
2131        assert_eq!(
2132            first.linked_libraries.iter().map(|lib| (&lib.id, lib.address)).collect::<Vec<_>>(),
2133            second.linked_libraries.iter().map(|lib| (&lib.id, lib.address)).collect::<Vec<_>>()
2134        );
2135        assert_eq!(first.linked_libraries[0].id.name, "Lib");
2136        assert_eq!(first.linked_libraries[1].id.name, "NestedLib");
2137        for library in &first.linked_libraries {
2138            assert_eq!(library.address, deployer.create2_from_code(salt, &library.bytecode));
2139        }
2140        linker
2141            .ensure_linked(&linker.link(target, &first.output.libraries).unwrap(), target)
2142            .unwrap();
2143    }
2144
2145    #[test]
2146    fn linking_failure() {
2147        let linker = LinkerTest::new(&testdata().join("default/linking/simple"), true);
2148        let linker_instance =
2149            Linker::new(linker.project.root(), linker.output.artifact_ids().collect());
2150
2151        // Create a libraries object with an incorrect library name that won't match any references
2152        let mut libraries = Libraries::default();
2153        libraries.libs.entry("default/linking/simple/Simple.t.sol".into()).or_default().insert(
2154            "NonExistentLib".to_string(),
2155            "0x5a443704dd4b594b382c22a083e2bd3090a6fef3".to_string(),
2156        );
2157
2158        // Try to link the LibraryConsumer contract with incorrect library
2159        let artifact_id = linker_instance
2160            .contracts
2161            .keys()
2162            .find(|id| id.name == "LibraryConsumer")
2163            .expect("LibraryConsumer contract not found");
2164
2165        let contract = linker_instance.contracts.get(artifact_id).unwrap();
2166
2167        // Verify that the artifact has unlinked bytecode
2168        assert!(
2169            linker_instance.ensure_linked(contract, artifact_id).is_err(),
2170            "Expected artifact to have unlinked bytecode"
2171        );
2172    }
2173}