Skip to main content

foundry_common/
namespaced_storage.rs

1//! ERC-7201 namespaced storage layouts.
2//!
3//! solc's `storageLayout` output only covers conventional storage. Namespaces declared with
4//! `@custom:storage-location erc7201:<id>` are computed with Solar and appended to it, so storage
5//! decoding labels namespaced fields as `<id>.<field>`.
6
7use alloy_primitives::U256;
8use eyre::Result;
9use foundry_compilers::{
10    ArtifactId, ProjectCompileOutput,
11    artifacts::{Remapping, Sources, StorageLayout},
12};
13use path_slash::PathExt;
14use solar::{
15    ast::{ContractKind, NatSpecKind},
16    data_structures::{Never, map::FxIndexSet},
17    interface::{
18        ColorChoice, Session,
19        config::{CompileOpts, ImportRemapping},
20        source_map::{FileLoader, FileName, SourceMap},
21    },
22    sema::{Compiler, CompilerRef, Gcx, hir, output::StorageLayoutOutput},
23};
24use std::{
25    collections::{BTreeMap, HashMap},
26    io,
27    ops::ControlFlow,
28    path::{Path, PathBuf},
29    sync::Arc,
30};
31
32/// Returns the storage layouts of `output`'s artifacts with ERC-7201 namespaces appended.
33///
34/// See [`extend_storage_layouts`].
35pub fn project_storage_layouts(
36    output: &mut ProjectCompileOutput,
37    root: &Path,
38) -> Vec<(ArtifactId, StorageLayout)> {
39    let layouts = output
40        .artifact_ids()
41        .filter_map(|(id, artifact)| {
42            artifact.storage_layout.as_ref().map(|layout| (id, layout.clone()))
43        })
44        .collect::<Vec<_>>();
45    extend_storage_layouts(output.parser_mut().solc_mut().compiler_mut(), root, layouts)
46}
47
48/// Returns `layouts` with the ERC-7201 namespaces of each contract appended.
49///
50/// `compiler` must contain the parsed sources of the artifacts; it is lowered if necessary. Source
51/// names are made relative to `root` to match solc's. Namespaces are optional decoding metadata, so
52/// failures are logged and leave the affected layouts unchanged.
53pub fn extend_storage_layouts(
54    compiler: &mut Compiler,
55    root: &Path,
56    layouts: impl IntoIterator<Item = (ArtifactId, StorageLayout)>,
57) -> Vec<(ArtifactId, StorageLayout)> {
58    let mut layouts = layouts.into_iter().collect::<Vec<_>>();
59    if layouts.is_empty() || !has_annotations(compiler) {
60        return layouts;
61    }
62    let result = compiler.enter_mut(|compiler| -> Result<()> {
63        lower(compiler)?;
64        let gcx = compiler.gcx();
65        let contracts = contracts_by_source(gcx, root);
66        for (id, layout) in &mut layouts {
67            let source = id.source.strip_prefix(root).unwrap_or(&id.source).to_slash_lossy();
68            // Artifact names may include compiler version and profile suffixes.
69            let name = id.name.split('.').next().unwrap();
70            let Some(&contract) = contracts.get(&(source.into_owned(), name.to_owned())) else {
71                continue;
72            };
73            if let Err(err) = extend_storage_layout(layout, gcx, root, contract) {
74                warn!(target: "erc7201", artifact = %id.identifier(), %err, "skipping ERC-7201 namespaces");
75            }
76        }
77        Ok(())
78    });
79    if let Err(err) = result {
80        warn!(target: "erc7201", %err, "skipping ERC-7201 namespaces");
81    }
82    layouts
83}
84
85/// Appends the ERC-7201 namespaces of `contract`, its bases, and the libraries they reference to
86/// its storage layout.
87///
88/// Namespaced fields are labeled `<namespace>.<field>`. Malformed annotations, duplicate namespace
89/// roots, and errors emitted while computing types in the contract and its bases are errors, in
90/// which case `layout` is unchanged. Such problems in libraries only skip the affected namespace.
91pub fn extend_storage_layout(
92    layout: &mut StorageLayout,
93    gcx: Gcx<'_>,
94    root: &Path,
95    contract: hir::ContractId,
96) -> Result<()> {
97    merge_storage_namespaces(layout, collect_storage_layouts(gcx, root, contract)?)
98}
99
100/// Lowers the parsed sources to HIR unless that has already happened.
101///
102/// Only the HIR and the types reachable from namespaced structs are needed, so this does not run
103/// full semantic analysis; solc has already validated the sources. Diagnostics emitted while
104/// lowering unrelated sources are not errors here.
105pub fn lower(compiler: &mut CompilerRef<'_>) -> Result<()> {
106    if compiler.gcx().stage().is_none_or(|stage| stage.is_parsing())
107        && !matches!(compiler.lower_asts(), Ok(ControlFlow::Continue(())))
108    {
109        return Err(solar_error(compiler.sess()));
110    }
111    Ok(())
112}
113
114/// Parses Standard JSON `sources`, keyed by source unit name, without touching the filesystem.
115///
116/// Returns `None` if no source declares an ERC-7201 namespace.
117pub fn parse_standard_json(sources: &Sources, remappings: &[Remapping]) -> Option<Compiler> {
118    if !sources.values().any(|source| has_annotation(&source.content)) {
119        return None;
120    }
121    let source_map = Arc::new(SourceMap::empty());
122    source_map.set_file_loader(NoFileLoader);
123    let opts = CompileOpts {
124        standard_json: true,
125        import_remappings: remappings
126            .iter()
127            .filter_map(|remapping| remapping.to_string().parse::<ImportRemapping>().ok())
128            .collect(),
129        ..Default::default()
130    };
131    let sess = Session::builder()
132        .source_map(source_map)
133        .with_buffer_emitter(ColorChoice::Never)
134        .opts(opts)
135        .build();
136    let mut compiler = Compiler::new(sess);
137    let _ = compiler.enter_mut(|compiler| -> solar::interface::Result {
138        let mut pcx = compiler.parse();
139        pcx.par_load_files_with_contents(
140            sources
141                .iter()
142                .map(|(path, source)| (path.clone(), source.content.as_str().to_owned()))
143                .collect::<Vec<_>>(),
144        )?;
145        pcx.parse();
146        Ok(())
147    });
148    Some(compiler)
149}
150
151/// Returns the contract `name` declared in the source `path`, relative to `root`.
152pub fn find_contract(
153    gcx: Gcx<'_>,
154    root: &Path,
155    path: &Path,
156    name: &str,
157) -> Option<hir::ContractId> {
158    let source = path.strip_prefix(root).unwrap_or(path).to_slash_lossy().into_owned();
159    contracts_by_source(gcx, root).remove(&(source, name.to_owned()))
160}
161
162/// The NatSpec tag content that marks a namespace; cheap to search for in source text.
163const ANNOTATION: &str = "erc7201";
164
165/// A storage namespace declared by a struct in a contract or one of its bases.
166#[derive(Clone, Debug)]
167struct StorageNamespace {
168    /// The identifier following `erc7201:` in the storage-location annotation.
169    id: String,
170    /// The fully qualified name of the declaring struct.
171    declaration: String,
172    /// The ERC-7201 root slot.
173    root: U256,
174    /// The struct's fields at absolute slots, with nested members at relative slots.
175    ///
176    /// Type IDs are scoped to this namespace so they cannot alias solc-generated IDs.
177    /// AST IDs originate from Solar and are not solc AST IDs.
178    layout: StorageLayout,
179}
180
181/// Rejects filesystem access, so Standard JSON imports only resolve to the supplied sources.
182struct NoFileLoader;
183
184impl FileLoader for NoFileLoader {
185    fn canonicalize_path(&self, path: &Path) -> io::Result<PathBuf> {
186        Ok(path.to_path_buf())
187    }
188
189    fn load_stdin(&self) -> io::Result<String> {
190        Err(io::ErrorKind::Unsupported.into())
191    }
192
193    fn load_file(&self, _path: &Path) -> io::Result<String> {
194        Err(io::ErrorKind::NotFound.into())
195    }
196
197    fn load_binary_file(&self, _path: &Path) -> io::Result<Vec<u8>> {
198        Err(io::ErrorKind::NotFound.into())
199    }
200}
201
202/// Returns whether any parsed source mentions an ERC-7201 storage location.
203pub fn has_annotations(compiler: &Compiler) -> bool {
204    compiler.sess().source_map().files().iter().any(|file| has_annotation(&file.src))
205}
206
207/// Returns whether `source` mentions an ERC-7201 storage location.
208fn has_annotation(source: &str) -> bool {
209    source.contains(ANNOTATION)
210}
211
212/// Maps `(source, name)` to contracts, with sources relative to `root` and slash-separated.
213fn contracts_by_source(gcx: Gcx<'_>, root: &Path) -> HashMap<(String, String), hir::ContractId> {
214    gcx.hir
215        .contract_ids()
216        .filter_map(|id| {
217            let contract = gcx.hir.contract(id);
218            let FileName::Real(path) = &gcx.hir.source(contract.source).file.name else {
219                return None;
220            };
221            let source = path.strip_prefix(root).unwrap_or(path).to_slash_lossy().into_owned();
222            Some(((source, contract.name.to_string()), id))
223        })
224        .collect()
225}
226
227/// Returns namespaces declared in `contract`, its linearized bases, and the libraries their code
228/// references, once per declaration.
229///
230/// Unrelated contracts, unreferenced libraries, and file-level structs are excluded: importing a
231/// declaration does not establish that the selected contract uses its storage. Unknown
232/// storage-location schemes are ignored. Malformed ERC-7201 annotations in the contract and its
233/// bases are errors. Library namespaces are best-effort: malformed ones, and ones whose root is
234/// already declared by a base or an earlier library, are logged and skipped.
235fn collect_storage_layouts(
236    gcx: Gcx<'_>,
237    root: &Path,
238    contract: hir::ContractId,
239) -> Result<Vec<StorageNamespace>> {
240    let mut namespaces = Vec::new();
241    let bases = gcx.hir.contract(contract).linearized_bases;
242    for &base in bases.iter().rev() {
243        for id in gcx.hir.contract(base).items.iter().filter_map(|item| item.as_struct()) {
244            namespaces.extend(struct_namespace(gcx, root, base, id)?);
245        }
246    }
247    if !has_library_annotations(gcx) {
248        return Ok(namespaces);
249    }
250    for library in referenced_libraries(gcx, bases) {
251        for id in gcx.hir.contract(library).items.iter().filter_map(|item| item.as_struct()) {
252            match struct_namespace(gcx, root, library, id) {
253                Ok(Some(namespace)) => {
254                    if let Some(previous) = namespaces.iter().find(|n| n.root == namespace.root) {
255                        warn!(
256                            target: "erc7201",
257                            namespace = %namespace.id,
258                            declaration = %namespace.declaration,
259                            previous = %previous.declaration,
260                            "skipping duplicate library ERC-7201 namespace"
261                        );
262                    } else {
263                        namespaces.push(namespace);
264                    }
265                }
266                Ok(None) => {}
267                Err(err) => warn!(
268                    target: "erc7201",
269                    library = %gcx.contract_fully_qualified_name(library),
270                    %err,
271                    "skipping library ERC-7201 namespace"
272                ),
273            }
274        }
275    }
276    Ok(namespaces)
277}
278
279/// Returns the namespace declared by struct `id` in `contract`, if any.
280///
281/// Errors if the annotation is malformed or Solar emits errors while computing the layout.
282fn struct_namespace(
283    gcx: Gcx<'_>,
284    root: &Path,
285    contract: hir::ContractId,
286    id: hir::StructId,
287) -> Result<Option<StorageNamespace>> {
288    let strukt = gcx.hir.strukt(id);
289    let Some(namespace) = storage_namespace(gcx, strukt)? else { return Ok(None) };
290    // Match solc's project-relative source names.
291    let contract_name = match &gcx.hir.source(gcx.hir.contract(contract).source).file.name {
292        FileName::Real(path) => format!(
293            "{}:{}",
294            path.strip_prefix(root).unwrap_or(path).to_slash_lossy(),
295            gcx.hir.contract(contract).name
296        ),
297        _ => gcx.contract_fully_qualified_name(contract).to_string(),
298    };
299    let slot = crate::erc7201(namespace).into();
300    // Only errors emitted for this struct count; earlier ones may come from unrelated sources.
301    let errors = gcx.sess.dcx.err_count();
302    let mut output = gcx.storage_layout_for_struct(id, slot);
303    if gcx.sess.dcx.err_count() > errors {
304        return Err(solar_error(gcx.sess));
305    }
306    scope_layout(&mut output, namespace, &contract_name);
307    Ok(Some(StorageNamespace {
308        id: namespace.to_owned(),
309        declaration: format!("{contract_name}.{}", strukt.name),
310        root: slot,
311        layout: serde_json::from_value(serde_json::to_value(output)?)?,
312    }))
313}
314
315/// Returns whether any library declares a struct that mentions an ERC-7201 storage location.
316///
317/// Finding referenced libraries walks function bodies, so it is skipped when no library could
318/// contribute a namespace, such as when only base contracts declare them.
319fn has_library_annotations(gcx: Gcx<'_>) -> bool {
320    gcx.hir.strukt_ids().any(|id| {
321        let strukt = gcx.hir.strukt(id);
322        strukt
323            .contract
324            .is_some_and(|contract| gcx.hir.contract(contract).kind == ContractKind::Library)
325            && gcx
326                .hir
327                .doc(strukt.doc)
328                .ast_comments()
329                .iter()
330                .any(|doc| doc.natspec.iter().any(|tag| has_annotation(tag.content())))
331    })
332}
333
334/// Returns the libraries referenced by `contracts`, directly or through other libraries and free
335/// functions, in discovery order and excluding `contracts` themselves.
336///
337/// Library code runs against the caller's storage, so a namespace declared in a library, such as
338/// `Storage.get()` returning a namespaced struct, belongs to every contract that reaches it.
339/// `using ... global` directives declared in other sources are not followed.
340fn referenced_libraries(gcx: Gcx<'_>, contracts: &[hir::ContractId]) -> Vec<hir::ContractId> {
341    let mut references = LibraryReferences {
342        gcx,
343        libraries: FxIndexSet::default(),
344        functions: FxIndexSet::default(),
345    };
346    // Most-base first, matching the order of base namespaces.
347    for &contract in contracts.iter().rev() {
348        references.visit_contract_code(contract);
349    }
350    // Code reached from libraries and free functions is appended, so this reaches a fixed point.
351    let (mut libraries, mut functions) = (0, 0);
352    loop {
353        if let Some(&library) = references.libraries.get_index(libraries) {
354            libraries += 1;
355            references.visit_contract_code(library);
356        } else if let Some(&function) = references.functions.get_index(functions) {
357            functions += 1;
358            let _ = hir::Visit::visit_nested_function(&mut references, function);
359        } else {
360            break;
361        }
362    }
363    // An inspected library is its own base, and its namespaces are collected as such.
364    references.libraries.into_iter().filter(|id| !contracts.contains(id)).collect()
365}
366
367/// Collects the libraries that visited code refers to by name, type, modifier, or `using`, and
368/// the free functions it calls, so their bodies can be visited too.
369struct LibraryReferences<'hir> {
370    gcx: Gcx<'hir>,
371    libraries: FxIndexSet<hir::ContractId>,
372    functions: FxIndexSet<hir::FunctionId>,
373}
374
375impl<'hir> LibraryReferences<'hir> {
376    /// Visits a contract's items, its storage layout specifier, and the `using` directives that
377    /// apply to it.
378    fn visit_contract_code(&mut self, id: hir::ContractId) {
379        let contract = self.gcx.hir.contract(id);
380        let _ = hir::Visit::visit_contract(self, contract);
381        if let Some(layout) = contract.layout {
382            let _ = hir::Visit::visit_expr(self, layout);
383        }
384        self.visit_usings(contract.usings);
385        self.visit_usings(self.gcx.hir.source(contract.source).usings);
386    }
387
388    /// Records the library that declares `item`, `item` itself if it is a library, or `item` if
389    /// it is a free function.
390    fn add_owner(&mut self, item: hir::ItemId) {
391        match item {
392            hir::ItemId::Contract(id) => self.add(id),
393            hir::ItemId::Function(id) if self.gcx.hir.function(id).contract.is_none() => {
394                self.functions.insert(id);
395            }
396            _ => {
397                if let Some(id) = self.gcx.hir.item(item).contract() {
398                    self.add(id);
399                }
400            }
401        }
402    }
403
404    fn add(&mut self, id: hir::ContractId) {
405        if self.gcx.hir.contract(id).kind == ContractKind::Library {
406            self.libraries.insert(id);
407        }
408    }
409
410    fn visit_usings(&mut self, usings: &'hir [hir::UsingDirective<'hir>]) {
411        for directive in usings {
412            for entry in directive.entries {
413                match entry.kind {
414                    hir::UsingEntryKind::Library(library) => self.add(library),
415                    hir::UsingEntryKind::Functions(functions) => {
416                        for &function in functions {
417                            self.add_owner(function.into());
418                        }
419                    }
420                    hir::UsingEntryKind::Err(_) => {}
421                }
422            }
423        }
424    }
425}
426
427impl<'hir> hir::Visit<'hir> for LibraryReferences<'hir> {
428    type BreakValue = Never;
429
430    fn hir(&self) -> &'hir hir::Hir<'hir> {
431        &self.gcx.hir
432    }
433
434    fn visit_expr(&mut self, expr: &'hir hir::Expr<'hir>) -> ControlFlow<Self::BreakValue> {
435        if let hir::ExprKind::Ident(resolutions) = expr.kind {
436            for resolution in resolutions {
437                if let hir::Res::Item(item) = *resolution {
438                    self.add_owner(item);
439                }
440            }
441        } else if let hir::ExprKind::Member(base, member) = expr.kind {
442            let mut names = vec![member];
443            let mut root = base.peel_parens();
444            while let hir::ExprKind::Member(base, member) = root.kind {
445                names.push(member);
446                root = base.peel_parens();
447            }
448            if let hir::ExprKind::Ident(resolutions) = root.kind {
449                names.reverse();
450                for resolution in resolutions {
451                    if let hir::Res::Namespace(source) = *resolution
452                        && let Some(resolutions) =
453                            self.gcx.source_path_resolutions(&names, source, None)
454                        && let Some(targets) = resolutions.last()
455                    {
456                        // Keep every overload of namespace-qualified free functions.
457                        for target in targets {
458                            if let hir::Res::Item(item) = *target {
459                                self.add_owner(item);
460                            }
461                        }
462                    }
463                }
464            }
465        }
466        self.walk_expr(expr)
467    }
468
469    fn visit_modifier(
470        &mut self,
471        modifier: &'hir hir::Modifier<'hir>,
472    ) -> ControlFlow<Self::BreakValue> {
473        self.add_owner(modifier.id);
474        self.walk_modifier(modifier)
475    }
476
477    fn visit_ty(&mut self, ty: &'hir hir::Type<'hir>) -> ControlFlow<Self::BreakValue> {
478        if let hir::TypeKind::Custom(item) = ty.kind {
479            self.add_owner(item);
480        }
481        self.walk_ty(ty)
482    }
483
484    fn visit_function(
485        &mut self,
486        function: &'hir hir::Function<'hir>,
487    ) -> ControlFlow<Self::BreakValue> {
488        if function.contract.is_none() {
489            self.visit_usings(self.gcx.hir.source(function.source).usings);
490        }
491        self.walk_function(function)
492    }
493}
494
495/// Returns the ERC-7201 namespace declared by a struct's `@custom:storage-location` tag.
496pub fn storage_namespace<'a>(gcx: Gcx<'a>, strukt: &hir::Struct<'_>) -> Result<Option<&'a str>> {
497    let mut namespace = None;
498    for doc in gcx.hir.doc(strukt.doc).ast_comments().iter() {
499        for tag in doc.natspec.iter() {
500            if let NatSpecKind::Custom { name } = tag.kind
501                && name.as_str() == "storage-location"
502                && let Some(id) = parse_namespace(tag.content())?
503                && namespace.replace(id).is_some()
504            {
505                eyre::bail!("multiple ERC-7201 annotations on struct `{}`", strukt.name);
506            }
507        }
508    }
509    Ok(namespace)
510}
511
512fn parse_namespace(annotation: &str) -> Result<Option<&str>> {
513    let annotation = annotation.trim();
514    let Some(id) = annotation.strip_prefix("erc7201:") else {
515        eyre::ensure!(
516            annotation.split_whitespace().next() != Some(ANNOTATION),
517            "expected `erc7201:<namespace>` storage location"
518        );
519        return Ok(None);
520    };
521    eyre::ensure!(
522        !id.is_empty() && !id.contains(char::is_whitespace),
523        "ERC-7201 namespace must be nonempty and contain no whitespace"
524    );
525    Ok(Some(id))
526}
527
528/// Prefix of a type ID scoped to a namespace, `erc7201(<namespace>)::<id>`.
529const SCOPE_PREFIX: &str = "erc7201(";
530/// Separator between a scoped type ID's namespace and the ID itself.
531const SCOPE_SEPARATOR: &str = ")::";
532
533/// Returns the type ID as the compiler wrote it, without the namespace scope `scope_layout` adds.
534///
535/// IDs that are not scoped are returned as is.
536pub fn unscoped_type_id(id: &str) -> &str {
537    id.strip_prefix(SCOPE_PREFIX)
538        .and_then(|scoped| scoped.rsplit_once(SCOPE_SEPARATOR))
539        .map_or(id, |(_, id)| id)
540}
541
542/// Scopes type IDs to `namespace` and attributes every entry to `contract`.
543fn scope_layout(output: &mut StorageLayoutOutput, namespace: &str, contract: &str) {
544    let scope = |id: &mut String| *id = format!("{SCOPE_PREFIX}{namespace}{SCOPE_SEPARATOR}{id}");
545    for entry in &mut output.storage {
546        scope(&mut entry.r#type);
547        entry.contract = contract.to_owned();
548    }
549    let Some(types) = &mut output.types else { return };
550    *types = std::mem::take(types)
551        .into_iter()
552        .map(|(mut id, mut ty)| {
553            for reference in [&mut ty.base, &mut ty.key, &mut ty.value].into_iter().flatten() {
554                scope(reference);
555            }
556            for member in &mut ty.members {
557                scope(&mut member.r#type);
558                member.contract = contract.to_owned();
559            }
560            scope(&mut id);
561            (id, ty)
562        })
563        .collect();
564}
565
566/// Merges namespaces, rejecting duplicate declarations before `layout` is modified.
567///
568/// Type IDs are scoped to their namespace, so they can't collide with each other or with solc's.
569fn merge_storage_namespaces(
570    layout: &mut StorageLayout,
571    namespaces: Vec<StorageNamespace>,
572) -> Result<()> {
573    let mut declarations = BTreeMap::new();
574    for namespace in &namespaces {
575        if let Some(previous) = declarations.insert(namespace.root, &namespace.declaration) {
576            eyre::bail!(
577                "Duplicate ERC-7201 namespace `{}` in `{previous}` and `{}`",
578                namespace.id,
579                namespace.declaration
580            );
581        }
582    }
583    for namespace in namespaces {
584        layout.types.extend(namespace.layout.types);
585        for mut entry in namespace.layout.storage {
586            entry.label = format!("{}.{}", namespace.id, entry.label);
587            layout.storage.push(entry);
588        }
589    }
590    Ok(())
591}
592
593fn solar_error(sess: &Session) -> eyre::Error {
594    let diagnostics = sess.dcx.emitted_diagnostics().map(|d| d.to_string()).unwrap_or_default();
595    eyre::eyre!("Solar failed while inspecting ERC-7201 storage\n{diagnostics}")
596}
597
598#[cfg(test)]
599mod tests {
600    use super::*;
601    use foundry_compilers::artifacts::Source;
602
603    /// Lowers `compiler` and collects the namespaces of `name` in `path`.
604    fn erc7201_storage_layouts(
605        compiler: &mut Compiler,
606        root: &Path,
607        path: &Path,
608        name: Option<&str>,
609    ) -> Result<Vec<StorageNamespace>> {
610        compiler.enter_mut(|compiler| {
611            lower(compiler)?;
612            let gcx = compiler.gcx();
613            let contract = find_contract(gcx, root, path, name.unwrap()).unwrap();
614            let namespaces = collect_storage_layouts(gcx, root, contract)?;
615            if gcx.sess.dcx.has_errors().is_err() {
616                return Err(solar_error(gcx.sess));
617            }
618            Ok(namespaces)
619        })
620    }
621
622    fn parser_at(source: &str, path: &str) -> Compiler {
623        let mut compiler = Compiler::new(Session::builder().with_test_emitter().build());
624        compiler.enter_mut(|compiler| {
625            let file =
626                compiler.sess().source_map().new_source_file(PathBuf::from(path), source).unwrap();
627            let mut parser = compiler.parse();
628            parser.add_file(file);
629            parser.parse();
630        });
631        compiler
632    }
633
634    fn layouts(source: &str, contract: &str) -> Result<Vec<StorageNamespace>> {
635        erc7201_storage_layouts(
636            &mut parser_at(source, "test.sol"),
637            Path::new(""),
638            Path::new("test.sol"),
639            Some(contract),
640        )
641    }
642
643    #[test]
644    fn project_relative_source_names() {
645        let mut parser = parser_at(
646            r#"contract C {
647            struct Inner { uint256 x; }
648            /// @custom:storage-location erc7201:example
649            struct Data { Inner inner; }
650        }"#,
651            "/project/src/test.sol",
652        );
653        let namespaces = erc7201_storage_layouts(
654            &mut parser,
655            Path::new("/project"),
656            Path::new("/project/src/test.sol"),
657            Some("C"),
658        )
659        .unwrap();
660        let namespace = &namespaces[0];
661        assert_eq!(namespace.declaration, "src/test.sol:C.Data");
662        assert_eq!(namespace.layout.storage[0].contract, "src/test.sol:C");
663        let ty = &namespace.layout.types[&namespace.layout.storage[0].storage_type];
664        assert_eq!(ty.other["members"][0]["contract"], "src/test.sol:C");
665    }
666
667    #[test]
668    fn repeated_inspection() {
669        let mut parser = parser_at(
670            r#"contract C {
671            /// @custom:storage-location erc7201:example
672            struct Data { uint256 value; }
673        }"#,
674            "test.sol",
675        );
676        let mut inspect = || {
677            erc7201_storage_layouts(&mut parser, Path::new(""), Path::new("test.sol"), Some("C"))
678                .unwrap()
679        };
680        assert_eq!(inspect()[0].layout, inspect()[0].layout);
681    }
682
683    #[test]
684    fn inherited_namespaces_and_type_graph() {
685        let namespaces = layouts(
686            r#"
687            type Amount is uint128;
688            contract Base {
689                enum State { Off, On }
690                struct Nested { uint128 x; bool y; }
691                /** @custom:storage-location erc7201:example.base */
692                struct Data {
693                    address owner;
694                    bool paused;
695                    Nested nested;
696                    uint128[3] fixedValues;
697                    mapping(address => Nested[]) accounts;
698                    bytes data;
699                    string name;
700                    Amount amount;
701                    State state;
702                    function() external callback;
703                }
704            }
705            contract Left is Base {}
706            contract Right is Base {}
707            contract Derived is Left, Right {
708                /// @custom:storage-location erc7201:example.derived
709                struct OtherData { uint256 value; }
710            }
711            contract Unrelated {
712                /// @custom:storage-location erc7201:example.base
713                struct Data { uint256 ignored; }
714            }
715        "#,
716            "Derived",
717        )
718        .unwrap();
719        assert_eq!(
720            namespaces.iter().map(|n| n.id.as_str()).collect::<Vec<_>>(),
721            ["example.base", "example.derived"]
722        );
723        assert_eq!(namespaces[0].declaration, "test.sol:Base.Data");
724        let layout = &namespaces[0].layout;
725        let root = namespaces[0].root;
726        assert_eq!(
727            layout
728                .storage
729                .iter()
730                .map(|s| (s.slot.parse::<U256>().unwrap() - root, s.offset))
731                .collect::<Vec<_>>(),
732            [(0, 0), (0, 20), (1, 0), (2, 0), (4, 0), (5, 0), (6, 0), (7, 0), (7, 16), (8, 0)]
733                .map(|(slot, offset)| (U256::from(slot), offset))
734        );
735        for ty in layout.types.values() {
736            for id in [&ty.key, &ty.value].into_iter().flatten() {
737                assert!(layout.types.contains_key(id), "missing {id}");
738            }
739            if let Some(base) = ty.other.get("base") {
740                assert!(layout.types.contains_key(base.as_str().unwrap()));
741            }
742            if let Some(members) = ty.other.get("members") {
743                for member in members.as_array().unwrap() {
744                    assert!(layout.types.contains_key(member["type"].as_str().unwrap()));
745                    assert_eq!(member["slot"], "0");
746                }
747            }
748        }
749        assert!(layout.types.keys().all(|id| id.starts_with("erc7201(example.base)::")));
750    }
751
752    #[test]
753    fn referenced_library_namespaces() {
754        let namespaces = layouts(
755            r#"
756            library Storage {
757                /// @custom:storage-location erc7201:example.storage
758                struct Data { uint256 value; }
759                function get() internal pure returns (Data storage $) {
760                    assembly { $.slot := 0 }
761                }
762            }
763            library Logic {
764                function bump() external { Storage.get().value += 1; }
765            }
766            library Math {
767                /// @custom:storage-location erc7201:example.math
768                struct Data { uint256 value; }
769                function double(uint256 x) internal pure returns (uint256) { return x * 2; }
770            }
771            library Unused {
772                /// @custom:storage-location erc7201:example.unused
773                struct Data { uint256 value; }
774            }
775            abstract contract Base {
776                function bump() public { Logic.bump(); }
777            }
778            contract C is Base {
779                using Math for uint256;
780            }
781        "#,
782            "C",
783        )
784        .unwrap();
785        assert_eq!(
786            namespaces.iter().map(|n| n.declaration.as_str()).collect::<Vec<_>>(),
787            ["test.sol:Math.Data", "test.sol:Storage.Data"]
788        );
789    }
790
791    fn declarations(source: &str, contract: &str) -> Vec<String> {
792        layouts(source, contract).unwrap().into_iter().map(|n| n.declaration).collect()
793    }
794
795    #[test]
796    fn library_artifact_namespaces() {
797        let source = r#"
798            library Storage {
799                /// @custom:storage-location erc7201:example.storage
800                struct Data { uint256 value; }
801                function get() internal pure returns (Data storage $) {
802                    assembly { $.slot := 0 }
803                }
804            }
805        "#;
806        assert_eq!(declarations(source, "Storage"), ["test.sol:Storage.Data"]);
807    }
808
809    #[test]
810    fn library_reference_kinds() {
811        const LIBRARY: &str = r#"
812            library L {
813                /// @custom:storage-location erc7201:lib
814                struct Data { uint256 value; }
815                uint256 internal constant K = 1;
816                function f() internal pure returns (uint256) { return 1; }
817                function g(uint256 x) internal pure returns (uint256) { return x; }
818            }
819        "#;
820        for code in [
821            "contract C { function h(L.Data storage) internal {} }",
822            "contract C { modifier m(uint256) { _; } function h() public m(L.f()) {} }",
823            "contract B { constructor(uint256) {} } contract C is B(L.f()) {}",
824            "using L for uint256; contract C {}",
825            "contract C { using {L.g} for uint256; }",
826            "function free() pure returns (uint256) { return L.f(); }
827             contract C { function h() public pure { free(); } }",
828            "function inc(uint256 x) pure returns (uint256) { return L.g(x); }
829             contract C { using {inc} for uint256; }",
830            "contract C layout at L.K {}",
831        ] {
832            let source = format!("{LIBRARY}\n{code}");
833            assert_eq!(declarations(&source, "C"), ["test.sol:L.Data"], "{code}");
834        }
835        assert!(declarations(&format!("{LIBRARY}\ncontract C {{}}"), "C").is_empty());
836    }
837
838    #[test]
839    fn library_namespaces_are_best_effort() {
840        // A base's namespace takes precedence over a library's.
841        let source = r#"
842            library L {
843                /// @custom:storage-location erc7201:app.main
844                struct Data { uint256 value; }
845                function f() internal {}
846            }
847            contract C {
848                /// @custom:storage-location erc7201:app.main
849                struct Main { uint256 value; }
850                function g() public { L.f(); }
851            }
852        "#;
853        assert_eq!(declarations(source, "C"), ["test.sol:C.Main"]);
854
855        // Of vendored copies, the first discovered library wins.
856        let source = r#"
857            library LibA {
858                /// @custom:storage-location erc7201:app.shared
859                struct Data { uint256 value; }
860                function f() internal {}
861            }
862            library LibB {
863                /// @custom:storage-location erc7201:app.shared
864                struct Data { uint256 value; }
865                function f() internal {}
866            }
867            contract C {
868                /// @custom:storage-location erc7201:app.own
869                struct Own { uint256 value; }
870                function g() public { LibA.f(); LibB.f(); }
871            }
872        "#;
873        assert_eq!(declarations(source, "C"), ["test.sol:C.Own", "test.sol:LibA.Data"]);
874
875        // Malformed library annotations only skip their struct.
876        let source = r#"
877            library Util {
878                /// @custom:storage-location erc7201
879                struct Broken { uint256 value; }
880                /// @custom:storage-location erc7201:util.valid
881                struct Valid { uint256 value; }
882                function id(uint256 x) internal pure returns (uint256) { return x; }
883            }
884            contract C {
885                /// @custom:storage-location erc7201:app.own
886                struct Own { uint256 value; }
887                function g() public pure returns (uint256) { return Util.id(1); }
888            }
889        "#;
890        assert_eq!(declarations(source, "C"), ["test.sol:C.Own", "test.sol:Util.Valid"]);
891    }
892
893    #[test]
894    fn namespace_import_alias() {
895        for (import, exports, accessor) in [
896            ("Lib.sol", "", "L.Storage"),
897            ("Exports.sol", r#"import {Storage} from "./Lib.sol";"#, "L.Storage"),
898            ("Exports.sol", r#"import {Storage as Store} from "./Lib.sol";"#, "L.Store"),
899            ("Exports.sol", r#"import "./Lib.sol" as Inner;"#, "L.Inner.Storage"),
900            ("Exports.sol", r#"import "./Lib.sol" as Inner;"#, "(L).Inner.Storage"),
901        ] {
902            let sources = Sources::from_iter([
903                (
904                    PathBuf::from("src/Lib.sol"),
905                    Source::new(
906                        r#"library Storage {
907                            /// @custom:storage-location erc7201:example.storage
908                            struct Data { uint256 value; }
909                            function get() internal pure returns (Data storage $) {
910                                bytes32 slot = keccak256(abi.encode(uint256(keccak256("example.storage")) - 1)) & ~bytes32(uint256(0xff));
911                                assembly { $.slot := slot }
912                            }
913                        }"#,
914                    ),
915                ),
916                (PathBuf::from("src/Exports.sol"), Source::new(exports)),
917                (
918                    PathBuf::from("src/C.sol"),
919                    Source::new(format!(
920                        r#"import "./{import}" as L;
921                        contract C {{ function f() public {{ {accessor}.get().value = 1; }} }}"#
922                    )),
923                ),
924            ]);
925            let mut compiler = parse_standard_json(&sources, &[]).unwrap();
926            let mut layout = StorageLayout::default();
927            compiler
928                .enter_mut(|compiler| {
929                    lower(compiler)?;
930                    let gcx = compiler.gcx();
931                    let contract =
932                        find_contract(gcx, Path::new(""), Path::new("src/C.sol"), "C").unwrap();
933                    extend_storage_layout(&mut layout, gcx, Path::new(""), contract)
934                })
935                .unwrap();
936            assert_eq!(
937                layout
938                    .storage
939                    .iter()
940                    .map(|s| (s.label.as_str(), s.contract.as_str()))
941                    .collect::<Vec<_>>(),
942                [("example.storage.value", "src/Lib.sol:Storage")],
943                "{import}: {exports} {accessor}"
944            );
945        }
946    }
947
948    #[test]
949    fn free_function_source_usings() {
950        for using in ["using Storage for uint256;", "using {Storage.bump} for uint256;"] {
951            for (import, call) in [
952                (r#"import {bump} from "./Free.sol";"#, "bump"),
953                (r#"import "./Free.sol" as F;"#, "F.bump"),
954                (r#"import "./Free.sol" as F;"#, "(F).bump"),
955            ] {
956                let sources = Sources::from_iter([
957                    (
958                        PathBuf::from("src/Lib.sol"),
959                        Source::new(
960                            r#"library Storage {
961                            /// @custom:storage-location erc7201:example.storage
962                            struct Data { uint256 value; }
963                            function bump(uint256 x) internal returns (uint256) {
964                                Data storage $;
965                                bytes32 slot = keccak256(abi.encode(uint256(keccak256("example.storage")) - 1)) & ~bytes32(uint256(0xff));
966                                assembly { $.slot := slot }
967                                return $.value += x;
968                            }
969                        }"#,
970                        ),
971                    ),
972                    (
973                        PathBuf::from("src/Free.sol"),
974                        Source::new(format!(
975                            r#"import {{Storage}} from "./Lib.sol";
976                        {using}
977                        function bump(uint256 x) returns (uint256) {{ return x.bump(); }}
978                        function bump(address) pure returns (uint256) {{ return 0; }}"#
979                        )),
980                    ),
981                    (
982                        PathBuf::from("src/C.sol"),
983                        Source::new(format!(
984                            r#"{import}
985                        contract C {{
986                            function f() public returns (uint256) {{ return {call}(uint256(1)); }}
987                        }}
988                        contract Unused {{}}"#,
989                        )),
990                    ),
991                ]);
992                let mut compiler = parse_standard_json(&sources, &[]).unwrap();
993                for (name, expected) in [
994                    ("C", vec![("example.storage.value", "src/Lib.sol:Storage")]),
995                    ("Unused", vec![]),
996                ] {
997                    let mut layout = StorageLayout::default();
998                    compiler
999                        .enter_mut(|compiler| {
1000                            lower(compiler)?;
1001                            let gcx = compiler.gcx();
1002                            let contract =
1003                                find_contract(gcx, Path::new(""), Path::new("src/C.sol"), name)
1004                                    .unwrap();
1005                            extend_storage_layout(&mut layout, gcx, Path::new(""), contract)
1006                        })
1007                        .unwrap();
1008                    assert_eq!(
1009                        layout
1010                            .storage
1011                            .iter()
1012                            .map(|s| (s.label.as_str(), s.contract.as_str()))
1013                            .collect::<Vec<_>>(),
1014                        expected,
1015                        "{name}: {using} {import} {call}"
1016                    );
1017                }
1018            }
1019        }
1020    }
1021
1022    #[test]
1023    fn annotation_errors_and_non_namespaced_contracts() {
1024        for annotation in ["erc7201:", "erc7201:two words", "erc7201"] {
1025            assert!(layouts(&format!("contract C {{\n/// @custom:storage-location {annotation}\nstruct Data {{ uint256 x; }}\n}}"), "C").is_err());
1026        }
1027        assert!(
1028            layouts(
1029                r#"contract C {
1030            /// @custom:storage-location erc7201:first
1031            /// @custom:storage-location erc7201:second
1032            struct Data { uint256 x; }
1033        }"#,
1034                "C"
1035            )
1036            .is_err()
1037        );
1038        assert!(
1039            layouts(
1040                r#"contract C {
1041            /// @custom:storage-location other:example
1042            struct Data { uint256 x; }
1043            uint256 value;
1044        }"#,
1045                "C"
1046            )
1047            .unwrap()
1048            .is_empty()
1049        );
1050        // Duplicate declarations are retained for the merge's collision policy.
1051        assert_eq!(
1052            layouts(
1053                r#"contract C {
1054            /// @custom:storage-location erc7201:same
1055            struct A { uint256 x; }
1056            /// @custom:storage-location erc7201:same
1057            struct B { uint256 y; }
1058        }"#,
1059                "C"
1060            )
1061            .unwrap()
1062            .len(),
1063            2
1064        );
1065    }
1066
1067    #[test]
1068    fn annotations() {
1069        assert_eq!(parse_namespace(" erc7201:example.main \n").unwrap(), Some("example.main"));
1070        assert_eq!(parse_namespace("erc9999:example.main").unwrap(), None);
1071        for invalid in ["erc7201", "erc7201:", "erc7201:two words"] {
1072            assert!(parse_namespace(invalid).is_err());
1073        }
1074    }
1075
1076    #[test]
1077    fn duplicate_namespaces_leave_layout_unchanged() {
1078        let namespace = |id: &str, root: u64| StorageNamespace {
1079            id: id.into(),
1080            declaration: format!("test.sol:C.{id}"),
1081            root: U256::from(root),
1082            layout: serde_json::from_value(serde_json::json!({
1083                "storage": [{
1084                    "astId": 1, "contract": "test.sol:C", "label": "x", "offset": 0,
1085                    "slot": root.to_string(), "type": format!("erc7201({id})::t_uint256")
1086                }],
1087                "types": {format!("erc7201({id})::t_uint256"): {
1088                    "encoding": "inplace", "label": "uint256", "numberOfBytes": "32"
1089                }}
1090            }))
1091            .unwrap(),
1092        };
1093        let mut layout = StorageLayout::default();
1094        assert_eq!(
1095            merge_storage_namespaces(
1096                &mut layout,
1097                vec![namespace("a", 1), namespace("b", 2), namespace("c", 1)]
1098            )
1099            .unwrap_err()
1100            .to_string(),
1101            "Duplicate ERC-7201 namespace `c` in `test.sol:C.a` and `test.sol:C.c`"
1102        );
1103        assert_eq!(layout, StorageLayout::default());
1104
1105        merge_storage_namespaces(&mut layout, vec![namespace("a", 1), namespace("b", 2)]).unwrap();
1106        assert_eq!(
1107            layout.storage.iter().map(|s| s.label.as_str()).collect::<Vec<_>>(),
1108            ["a.x", "b.x"]
1109        );
1110        assert_eq!(layout.types.len(), 2);
1111    }
1112
1113    #[test]
1114    fn artifact_layouts() {
1115        let mut parser = parser_at(
1116            r#"contract C {
1117            /// @custom:storage-location erc7201:example
1118            struct Data { uint256 value; }
1119        }
1120        contract Plain { uint256 value; }"#,
1121            "/project/src/test.sol",
1122        );
1123        let id = |name: &str| ArtifactId {
1124            path: PathBuf::new(),
1125            name: name.to_owned(),
1126            source: PathBuf::from("src/test.sol"),
1127            version: semver::Version::new(0, 8, 30),
1128            build_id: String::new(),
1129            profile: String::new(),
1130        };
1131        let layouts = extend_storage_layouts(
1132            &mut parser,
1133            Path::new("/project"),
1134            [
1135                (id("C"), StorageLayout::default()),
1136                (id("C.via-ir"), StorageLayout::default()),
1137                (id("C.0.8.30"), StorageLayout::default()),
1138                (id("C.0.8.30.via-ir"), StorageLayout::default()),
1139                (id("Plain"), StorageLayout::default()),
1140            ],
1141        );
1142        assert_eq!(
1143            layouts
1144                .iter()
1145                .map(|(id, layout)| (
1146                    id.name.as_str(),
1147                    layout.storage.iter().map(|s| s.label.as_str()).collect::<Vec<_>>()
1148                ))
1149                .collect::<Vec<_>>(),
1150            [
1151                ("C", vec!["example.value"]),
1152                ("C.via-ir", vec!["example.value"]),
1153                ("C.0.8.30", vec!["example.value"]),
1154                ("C.0.8.30.via-ir", vec!["example.value"]),
1155                ("Plain", vec![]),
1156            ]
1157        );
1158        for (_, layout) in &layouts[..4] {
1159            assert_eq!(layout.storage[0].contract, "src/test.sol:C");
1160        }
1161    }
1162
1163    #[test]
1164    fn standard_json_sources() {
1165        let sources = Sources::from_iter([
1166            (
1167                PathBuf::from("src/Token.sol"),
1168                foundry_compilers::artifacts::Source::new(
1169                    r#"import "@oz/Base.sol";
1170                    contract Token is Base {}"#,
1171                ),
1172            ),
1173            (
1174                PathBuf::from("lib/oz/Base.sol"),
1175                foundry_compilers::artifacts::Source::new(
1176                    r#"contract Base {
1177                    /// @custom:storage-location erc7201:openzeppelin.storage.ERC20
1178                    struct ERC20Storage { mapping(address => uint256) balances; uint256 totalSupply; }
1179                }"#,
1180                ),
1181            ),
1182        ]);
1183        let remappings = ["@oz/=lib/oz/".parse::<Remapping>().unwrap()];
1184        let mut compiler = parse_standard_json(&sources, &remappings).unwrap();
1185        let mut layout = StorageLayout::default();
1186        compiler
1187            .enter_mut(|compiler| {
1188                lower(compiler)?;
1189                let gcx = compiler.gcx();
1190                let contract =
1191                    find_contract(gcx, Path::new(""), Path::new("src/Token.sol"), "Token").unwrap();
1192                extend_storage_layout(&mut layout, gcx, Path::new(""), contract)
1193            })
1194            .unwrap();
1195        assert_eq!(
1196            layout
1197                .storage
1198                .iter()
1199                .map(|s| (s.label.as_str(), s.contract.as_str()))
1200                .collect::<Vec<_>>(),
1201            [
1202                ("openzeppelin.storage.ERC20.balances", "lib/oz/Base.sol:Base"),
1203                ("openzeppelin.storage.ERC20.totalSupply", "lib/oz/Base.sol:Base"),
1204            ]
1205        );
1206
1207        let plain = Sources::from_iter([(
1208            PathBuf::from("src/Plain.sol"),
1209            foundry_compilers::artifacts::Source::new("contract Plain { uint256 x; }"),
1210        )]);
1211        assert!(parse_standard_json(&plain, &[]).is_none());
1212    }
1213
1214    #[test]
1215    fn profiled_artifact_layouts_keep_source_identity() {
1216        let sources =
1217            Sources::from_iter([("Left", "left"), ("Right", "right")].map(|(file, namespace)| {
1218                (
1219                    PathBuf::from(format!("src/{file}.sol")),
1220                    foundry_compilers::artifacts::Source::new(format!(
1221                        "contract C {{
1222                            /// @custom:storage-location erc7201:{namespace}
1223                            struct Data {{ uint256 value; }}
1224                        }}"
1225                    )),
1226                )
1227            }));
1228        let mut compiler = parse_standard_json(&sources, &[]).unwrap();
1229        let ids = ["Left", "Right"].map(|file| ArtifactId {
1230            path: PathBuf::from(format!("out/{file}.sol/C.via-ir.json")),
1231            name: "C.via-ir".into(),
1232            source: PathBuf::from(format!("src/{file}.sol")),
1233            version: semver::Version::new(0, 8, 30),
1234            build_id: file.into(),
1235            profile: "via-ir".into(),
1236        });
1237        let layouts = extend_storage_layouts(
1238            &mut compiler,
1239            Path::new(""),
1240            ids.iter().cloned().map(|id| (id, StorageLayout::default())),
1241        );
1242        assert_eq!(
1243            layouts.iter().map(|(id, _)| id).collect::<Vec<_>>(),
1244            ids.iter().collect::<Vec<_>>()
1245        );
1246        assert_eq!(
1247            layouts
1248                .iter()
1249                .map(|(_, layout)| layout
1250                    .storage
1251                    .iter()
1252                    .map(|s| s.label.as_str())
1253                    .collect::<Vec<_>>())
1254                .collect::<Vec<_>>(),
1255            [vec!["left.value"], vec!["right.value"]]
1256        );
1257    }
1258
1259    #[test]
1260    fn unscopes_type_ids() {
1261        assert_eq!(unscoped_type_id("t_uint256"), "t_uint256");
1262        assert_eq!(
1263            unscoped_type_id("erc7201(example.main)::t_userDefinedValueType(Id)12"),
1264            "t_userDefinedValueType(Id)12"
1265        );
1266        assert_eq!(
1267            unscoped_type_id("erc7201(example.main)::t_mapping(t_address,t_uint256)"),
1268            "t_mapping(t_address,t_uint256)"
1269        );
1270        // Namespaces may contain the separator; compiler type IDs never do.
1271        assert_eq!(
1272            unscoped_type_id("erc7201(a)::b)::t_userDefinedValueType(Id)12"),
1273            "t_userDefinedValueType(Id)12"
1274        );
1275    }
1276}