Skip to main content

forge_lint/sol/high/
protected_vars.rs

1//! Slither-compatible protected-variable control-flow analysis.
2//!
3//! Storage references are tracked as may-alias sets across internal calls and control-flow joins.
4//! Calls are memoized by their storage, slot, and guard context so recursive propagation
5//! terminates.
6
7use super::ProtectedVars;
8use crate::{
9    linter::{LateLintPass, LintContext},
10    sol::{
11        Severity, SolLint,
12        analysis::{
13            branch_always_exits, is_builtin, is_loop_termination_if, lhs_local_var, loop_update,
14            runtime_entry_points,
15        },
16    },
17};
18use solar::{
19    ast::{BinOpKind, ContractKind, DataLocation, FunctionKind},
20    interface::sym,
21    sema::{
22        Gcx,
23        builtins::Builtin,
24        hir::{
25            self, CallArgs, ContractId, ExprId, ExprKind, FunctionId, ItemId, LoopSource,
26            NatSpecKind, Res, StmtKind, VariableId,
27        },
28        ty::{CallableParamSource, Ty, TyAbiPrinter, TyAbiPrinterMode, TyKind},
29    },
30};
31use std::collections::{HashMap, HashSet};
32
33type StorageRoots = HashSet<VariableId>;
34type RootMap = HashMap<VariableId, StorageRoots>;
35
36declare_forge_lint!(
37    PROTECTED_VARS,
38    Severity::High,
39    "protected-vars",
40    "protected variable is written without its required protection"
41);
42
43impl<'gcx> LateLintPass<'gcx> for ProtectedVars {
44    fn check_nested_contract(
45        &mut self,
46        ctx: &LintContext,
47        gcx: Gcx<'gcx>,
48        contract_id: ContractId,
49    ) {
50        let contract = gcx.hir.contract(contract_id);
51        if !matches!(contract.kind, ContractKind::Contract | ContractKind::AbstractContract)
52            || contract.linearization_failed()
53            || !is_most_derived_contract(&gcx.hir, contract_id)
54        {
55            return;
56        }
57        let bases = contract.linearized_bases;
58
59        let protected = protected_variables(gcx, bases);
60        if protected.is_empty() {
61            return;
62        }
63        let targets = protection_targets(gcx, bases);
64
65        // The effective runtime dispatch surface: most-derived overrides plus the inherited
66        // fallback/receive functions.
67        let entries = runtime_entry_points(gcx, contract_id);
68
69        for entry_id in entries {
70            let entry = gcx.hir.function(entry_id);
71            let span = entry.name.map_or(entry.keyword_span(), |name| name.span);
72            let context = if entry.contract == Some(contract_id) {
73                String::new()
74            } else {
75                format!(" in most-derived contract `{}`", contract.name)
76            };
77            let mut writes: Vec<_> = analyze_entry(gcx, bases, entry_id).into_iter().collect();
78            writes.sort_unstable_by_key(|(var_id, _)| *var_id);
79            for (var_id, guards) in writes {
80                let Some(requirements) = protected.get(&var_id) else { continue };
81                let variable = gcx
82                    .hir
83                    .variable(var_id)
84                    .name
85                    .map_or("<unnamed>".to_string(), |n| n.to_string());
86                for requirement in requirements {
87                    let msg = match requirement {
88                        Some(signature) => {
89                            if targets.get(signature).is_some_and(|target| guards.contains(target))
90                            {
91                                continue;
92                            }
93                            format!(
94                                "protected variable `{variable}` is written without `{signature}`{context}"
95                            )
96                        }
97                        None => format!(
98                            "protected variable `{variable}` has a malformed write-protection annotation{context}"
99                        ),
100                    };
101                    ctx.emit_with_msg(&PROTECTED_VARS, span, msg);
102                }
103            }
104        }
105    }
106}
107
108/// Slither analyzes the effective entry points of leaf contracts so inherited declarations are
109/// interpreted in the context in which they are ultimately deployed.
110fn is_most_derived_contract(hir: &hir::Hir<'_>, contract_id: ContractId) -> bool {
111    !hir.contract_ids().any(|candidate_id| {
112        candidate_id != contract_id
113            && hir.contract(candidate_id).linearized_bases[1..].contains(&contract_id)
114    })
115}
116
117/// Protected state variables with their `@custom:security write-protection="<sig>"` requirements;
118/// `None` marks a malformed annotation.
119fn protected_variables(
120    gcx: Gcx<'_>,
121    bases: &[ContractId],
122) -> HashMap<VariableId, Vec<Option<String>>> {
123    let mut protected = HashMap::new();
124    for var_id in bases.iter().flat_map(|&cid| gcx.hir.contract(cid).variables()) {
125        let var = gcx.hir.variable(var_id);
126        if !var.kind.is_state() {
127            continue;
128        }
129        let mut requirements = Vec::new();
130        for item in gcx.natspec_doc_comments(var.doc) {
131            let NatSpecKind::Custom { name } = item.kind else { continue };
132            let content = item.content();
133            let Some(index) = write_protection_token(content) else { continue };
134            if name.as_str() != "security" {
135                continue;
136            }
137            let requirement = content[index + "write-protection".len()..]
138                .strip_prefix("=\"")
139                .and_then(|value| value.split_once('"'))
140                .map(|(signature, _)| signature)
141                .filter(|signature| !signature.is_empty())
142                .map(str::to_owned);
143            if !requirements.contains(&requirement) {
144                requirements.push(requirement);
145            }
146        }
147        if !requirements.is_empty() {
148            protected.insert(var_id, requirements);
149        }
150    }
151    protected
152}
153
154/// Byte offset of a standalone `write-protection` token in `content`.
155fn write_protection_token(content: &str) -> Option<usize> {
156    let is_token_char = |c: char| c.is_alphanumeric() || matches!(c, '_' | '-');
157    content.match_indices("write-protection").find_map(|(index, token)| {
158        let before = content[..index].chars().next_back();
159        let after = content[index + token.len()..].chars().next();
160        (!before.is_some_and(is_token_char) && !after.is_some_and(is_token_char)).then_some(index)
161    })
162}
163
164/// Guard functions and modifiers by Slither signature. Functions take precedence over modifiers;
165/// within a kind, linearization order keeps the most-derived declaration and drops shadowed ones.
166fn protection_targets(gcx: Gcx<'_>, bases: &[ContractId]) -> HashMap<String, FunctionId> {
167    let mut targets = HashMap::new();
168    for kind in [FunctionKind::Function, FunctionKind::Modifier] {
169        for fid in bases.iter().flat_map(|&cid| gcx.hir.contract(cid).functions()) {
170            let function = gcx.hir.function(fid);
171            if function.kind == kind && function.name.is_some() {
172                targets.entry(callable_signature(gcx, fid)).or_insert(fid);
173            }
174        }
175    }
176    targets
177}
178
179fn callable_signature(gcx: Gcx<'_>, function_id: FunctionId) -> String {
180    let function = gcx.hir.function(function_id);
181    let params = function.parameters.iter().map(|&parameter| {
182        let ty = gcx.type_of_item(parameter.into());
183        if function.kind == FunctionKind::Modifier {
184            source_type_signature(gcx, ty)
185        } else {
186            slither_function_parameter(gcx, ty, &mut HashSet::new())
187        }
188    });
189    format!("{}({})", function.name.unwrap().as_str(), params.collect::<Vec<_>>().join(","))
190}
191
192/// Formats the source-level types used by Slither modifier signatures.
193fn source_type_signature<'gcx>(gcx: Gcx<'gcx>, ty: Ty<'gcx>) -> String {
194    let mut signature = ty.display(gcx).to_string();
195    for prefix in ["contract ", "struct ", "enum "] {
196        signature = signature.replace(prefix, "");
197    }
198    for suffix in
199        [" storage", " memory", " calldata", " external", " internal", " pure", " view", " payable"]
200    {
201        signature = signature.replace(suffix, "");
202    }
203    signature.replace("function ", "function").replace("returns ", "returns")
204}
205
206/// Formats the Solidity-signature types used by Slither function lookup.
207fn slither_function_parameter<'gcx>(
208    gcx: Gcx<'gcx>,
209    ty: Ty<'gcx>,
210    seen_structs: &mut HashSet<hir::StructId>,
211) -> String {
212    match ty.kind {
213        TyKind::Fn(_) | TyKind::Mapping(..) => source_type_signature(gcx, ty),
214        TyKind::Ref(inner, _) => slither_function_parameter(gcx, inner, seen_structs),
215        TyKind::DynArray(inner) => {
216            format!("{}[]", slither_function_parameter(gcx, inner, seen_structs))
217        }
218        TyKind::Array(inner, length) => {
219            format!("{}[{length}]", slither_function_parameter(gcx, inner, seen_structs))
220        }
221        TyKind::Struct(struct_id) => {
222            if !seen_structs.insert(struct_id) {
223                return source_type_signature(gcx, ty);
224            }
225            let fields = gcx
226                .struct_field_types(struct_id)
227                .iter()
228                .map(|&field| slither_function_parameter(gcx, field, seen_structs))
229                .collect::<Vec<_>>();
230            format!("({})", fields.join(","))
231        }
232        _ => {
233            let mut signature = String::new();
234            TyAbiPrinter::new(gcx, &mut signature, TyAbiPrinterMode::Signature)
235                .print(ty)
236                .expect("writing to a String cannot fail");
237            signature
238        }
239    }
240}
241
242#[derive(Clone, Default, PartialEq, Eq)]
243struct AliasState {
244    /// Storage pointer locals to the state variables they may alias.
245    storage: RootMap,
246    /// Yul locals holding a `.slot` to the state variables they may denote.
247    slots: RootMap,
248}
249
250#[derive(Clone, Default, PartialEq, Eq)]
251struct FlowState {
252    aliases: AliasState,
253    /// Guards that have run on every path reaching this point.
254    guards: HashSet<FunctionId>,
255}
256
257impl FlowState {
258    fn merge(&self, other: &Self) -> Self {
259        fn merge_roots(lhs: &RootMap, rhs: &RootMap) -> RootMap {
260            let mut merged = lhs.clone();
261            for (&var_id, roots) in rhs {
262                merged.entry(var_id).or_default().extend(roots);
263            }
264            merged
265        }
266        Self {
267            aliases: AliasState {
268                storage: merge_roots(&self.aliases.storage, &other.aliases.storage),
269                slots: merge_roots(&self.aliases.slots, &other.aliases.slots),
270            },
271            guards: self.guards.intersection(&other.guards).copied().collect(),
272        }
273    }
274}
275
276/// Joins `state` into the accumulated state of the paths that reach a point.
277fn join(destination: &mut Option<FlowState>, state: FlowState) {
278    *destination = Some(match destination.take() {
279        Some(current) => current.merge(&state),
280        None => state,
281    });
282}
283
284/// A finite call-graph key that distinguishes storage aliases without depending on values.
285#[derive(Clone, Debug, PartialEq, Eq, Hash)]
286struct CallContext {
287    function_id: FunctionId,
288    storage: Vec<(VariableId, Vec<VariableId>)>,
289    slots: Vec<(VariableId, Vec<VariableId>)>,
290    guards: Vec<FunctionId>,
291}
292
293impl CallContext {
294    fn new(
295        function_id: FunctionId,
296        function: &hir::Function<'_>,
297        aliases: &AliasState,
298        guards: &HashSet<FunctionId>,
299    ) -> Self {
300        let roots = |aliases: &RootMap| {
301            function
302                .parameters
303                .iter()
304                .filter_map(|&parameter| {
305                    let mut roots: Vec<_> = aliases.get(&parameter)?.iter().copied().collect();
306                    roots.sort_unstable();
307                    Some((parameter, roots))
308                })
309                .collect()
310        };
311        let mut guards: Vec<_> = guards.iter().copied().collect();
312        guards.sort_unstable();
313        Self { function_id, storage: roots(&aliases.storage), slots: roots(&aliases.slots), guards }
314    }
315}
316
317#[derive(Clone, PartialEq, Eq)]
318struct CallSummary {
319    /// Storage roots that may be returned in each return slot.
320    returns: Vec<StorageRoots>,
321    /// Guards that hold after the call.
322    guards: HashSet<FunctionId>,
323    /// Whether the call can complete normally.
324    completes: bool,
325}
326
327/// States collected at `break`/`continue` statements of the innermost loop.
328#[derive(Default)]
329struct LoopFlow {
330    breaks: Option<FlowState>,
331    continues: Option<FlowState>,
332}
333
334/// What `_` resumes: the rest of the modifier chain and the function body.
335#[derive(Clone, Copy)]
336struct ModifierContinuation<'gcx> {
337    modifiers: &'gcx [hir::Modifier<'gcx>],
338    next: usize,
339    body: hir::Block<'gcx>,
340}
341
342/// Runs the entry to a fixpoint over the memoized call summaries and returns, per written state
343/// variable, the guards that held on every path to some write.
344fn analyze_entry<'gcx>(
345    gcx: Gcx<'gcx>,
346    bases: &'gcx [ContractId],
347    entry_id: FunctionId,
348) -> HashMap<VariableId, HashSet<FunctionId>> {
349    let mut call_summaries = HashMap::new();
350    let mut previous_writes = HashMap::new();
351    loop {
352        let mut analyzer = EntryAnalyzer {
353            gcx,
354            bases,
355            writes: HashMap::new(),
356            aliases: AliasState::default(),
357            guards: HashSet::new(),
358            call_returns: HashMap::new(),
359            call_summaries: call_summaries.clone(),
360            seen_calls: HashSet::new(),
361            evaluated_calls: HashSet::new(),
362            stack: Vec::new(),
363            return_stack: Vec::new(),
364            return_flow: Vec::new(),
365            loop_flow: Vec::new(),
366            modifier_continuations: Vec::new(),
367            assembly_depth: 0,
368        };
369        analyzer.analyze_function(entry_id);
370        if analyzer.writes == previous_writes && analyzer.call_summaries == call_summaries {
371            return analyzer.writes;
372        }
373        previous_writes = analyzer.writes;
374        call_summaries = analyzer.call_summaries;
375    }
376}
377
378struct EntryAnalyzer<'gcx> {
379    gcx: Gcx<'gcx>,
380    bases: &'gcx [ContractId],
381    /// Written state variables to the guards that held at every write.
382    writes: HashMap<VariableId, HashSet<FunctionId>>,
383    aliases: AliasState,
384    guards: HashSet<FunctionId>,
385    /// Storage roots returned by each analyzed call expression.
386    call_returns: HashMap<ExprId, Vec<StorageRoots>>,
387    call_summaries: HashMap<CallContext, CallSummary>,
388    /// Contexts currently being analyzed (recursion detection).
389    seen_calls: HashSet<CallContext>,
390    /// Contexts already analyzed in this pass.
391    evaluated_calls: HashSet<CallContext>,
392    stack: Vec<FunctionId>,
393    /// Per active function, the storage roots flowing into each return slot.
394    return_stack: Vec<Vec<StorageRoots>>,
395    /// Per active function, the joined state at its `return` statements.
396    return_flow: Vec<Option<FlowState>>,
397    loop_flow: Vec<LoopFlow>,
398    modifier_continuations: Vec<ModifierContinuation<'gcx>>,
399    assembly_depth: usize,
400}
401
402impl<'gcx> EntryAnalyzer<'gcx> {
403    fn analyze_function(&mut self, function_id: FunctionId) -> CallSummary {
404        let function = self.gcx.hir.function(function_id);
405        let empty_returns = || function.returns.iter().map(|_| StorageRoots::new()).collect();
406        let Some(body) = function.body else {
407            return CallSummary {
408                returns: empty_returns(),
409                guards: self.guards.clone(),
410                completes: true,
411            };
412        };
413        self.stack.push(function_id);
414        self.return_stack.push(empty_returns());
415        self.return_flow.push(None);
416        let completes = self.analyze_modifier_chain(function.modifiers, 0, body);
417        if completes && !body.stmts.iter().any(|expr| branch_always_exits(self.gcx, expr)) {
418            self.capture_named_returns();
419        }
420        let returned = self.return_flow.pop().expect("return flow frame").is_some();
421        let returns = self.return_stack.pop().expect("return frame");
422        self.stack.pop();
423        CallSummary { returns, guards: self.guards.clone(), completes: completes || returned }
424    }
425
426    /// Analyzes the modifier at `index` (or the body once the chain is exhausted). Returns whether
427    /// control can complete normally.
428    fn analyze_modifier_chain(
429        &mut self,
430        modifiers: &'gcx [hir::Modifier<'gcx>],
431        index: usize,
432        body: hir::Block<'gcx>,
433    ) -> bool {
434        let Some(modifier) = modifiers.get(index) else {
435            let previous_returns = self.return_flow.last_mut().and_then(Option::take);
436            let falls_through = self.analyze_block(body);
437            let mut completions = self.return_flow.last_mut().and_then(Option::take);
438
439            // Returns from the function body resume in each enclosing modifier postlude. They
440            // therefore become ordinary placeholder completions here and must not also escape
441            // the whole modifier chain through `return_flow`: a reverting postlude can still
442            // prevent the call from completing. Keep only returns captured in modifier prefixes
443            // outside the body continuation.
444            *self.return_flow.last_mut().expect("return flow frame") = previous_returns;
445
446            if falls_through {
447                join(&mut completions, self.flow_state());
448            }
449            let Some(state) = completions else { return false };
450            self.set_flow_state(state);
451            return true;
452        };
453        if !modifier.args.exprs().all(|argument| self.analyze_expr(argument)) {
454            return false;
455        }
456
457        let Some(declared_id) = modifier.id.as_function() else { return false };
458        let Some(modifier_id) = self.gcx.resolve_modifier_target(self.bases[0], modifier) else {
459            return false;
460        };
461        self.guards.insert(modifier_id);
462        let arguments = self.ordered_call_arguments(declared_id, modifier.args, None);
463        let bound = self.argument_aliases(modifier_id, &arguments);
464        for parameter in self.gcx.hir.function(modifier_id).parameters {
465            self.aliases.storage.remove(parameter);
466        }
467        self.aliases.storage.extend(bound.storage);
468
469        let Some(modifier_body) = self.gcx.hir.function(modifier_id).body else { return false };
470        self.modifier_continuations.push(ModifierContinuation { modifiers, next: index + 1, body });
471        let completes = self.analyze_block(modifier_body);
472        self.modifier_continuations.pop();
473        completes
474    }
475
476    fn analyze_call(
477        &mut self,
478        function_id: FunctionId,
479        arguments: &[&'gcx hir::Expr<'gcx>],
480    ) -> CallSummary {
481        let bound = self.argument_aliases(function_id, arguments);
482        let saved_aliases = std::mem::replace(&mut self.aliases, bound);
483
484        let function = self.gcx.hir.function(function_id);
485        let context = CallContext::new(function_id, function, &self.aliases, &self.guards);
486        let cached = if self.seen_calls.contains(&context) {
487            // Recursive call: assume the summary so far, or a non-completing call.
488            Some(self.call_summaries.get(&context).cloned().unwrap_or_else(|| CallSummary {
489                returns: Vec::new(),
490                guards: self.guards.clone(),
491                completes: false,
492            }))
493        } else if self.evaluated_calls.contains(&context) {
494            self.call_summaries.get(&context).cloned()
495        } else {
496            None
497        };
498        let summary = match cached {
499            Some(summary) => {
500                self.guards = summary.guards.clone();
501                summary
502            }
503            None => {
504                self.seen_calls.insert(context.clone());
505                self.evaluated_calls.insert(context.clone());
506                let summary = self.analyze_function(function_id);
507                self.seen_calls.remove(&context);
508                self.call_summaries.insert(context, summary.clone());
509                summary
510            }
511        };
512        self.aliases = saved_aliases;
513        summary
514    }
515
516    /// Aliases of `function_id`'s parameters when bound to `arguments` under the current state.
517    fn argument_aliases(
518        &self,
519        function_id: FunctionId,
520        arguments: &[&'gcx hir::Expr<'gcx>],
521    ) -> AliasState {
522        let function = self.gcx.hir.function(function_id);
523        let mut bound = AliasState::default();
524        for (&parameter, &argument) in function.parameters.iter().zip(arguments) {
525            if self.gcx.hir.variable(parameter).data_location == Some(DataLocation::Storage) {
526                let roots = self.storage_roots(argument);
527                if !roots.is_empty() {
528                    bound.storage.insert(parameter, roots);
529                }
530            }
531            if function.is_yul {
532                let roots = self.slot_roots(argument);
533                if !roots.is_empty() {
534                    bound.slots.insert(parameter, roots);
535                }
536            }
537        }
538        bound
539    }
540
541    fn analyze_block(&mut self, block: hir::Block<'gcx>) -> bool {
542        block.stmts.iter().all(|statement| self.analyze_stmt(statement))
543    }
544
545    /// Analyzes each alternative from the current state and joins the states of those that
546    /// complete (plus `merged`, the state of any implicit fall-through path). Returns whether any
547    /// path completes.
548    fn analyze_alternatives<T: Copy>(
549        &mut self,
550        alternatives: impl IntoIterator<Item = T>,
551        mut merged: Option<FlowState>,
552        analyze: impl Fn(&mut Self, T) -> bool,
553    ) -> bool {
554        let before = self.flow_state();
555        for alternative in alternatives {
556            self.set_flow_state(before.clone());
557            if analyze(self, alternative) {
558                join(&mut merged, self.flow_state());
559            }
560        }
561        let Some(merged) = merged else { return false };
562        self.set_flow_state(merged);
563        true
564    }
565
566    /// Analyzes a statement, returning whether control can continue past it.
567    fn analyze_stmt(&mut self, statement: &'gcx hir::Stmt<'gcx>) -> bool {
568        match statement.kind {
569            StmtKind::DeclSingle(variable_id) => {
570                let Some(initializer) = self.gcx.hir.variable(variable_id).initializer else {
571                    return true;
572                };
573                if !self.analyze_expr(initializer) {
574                    return false;
575                }
576                self.alias_local_from_expr(variable_id, initializer);
577                true
578            }
579            StmtKind::DeclMulti(variables, expression) => {
580                if !self.analyze_expr(expression) {
581                    return false;
582                }
583                for (index, variable_id) in variables.iter().enumerate() {
584                    if let Some(variable_id) = variable_id {
585                        let roots =
586                            self.storage_roots_for_output(expression, index, variables.len());
587                        self.alias_local(*variable_id, roots);
588                    }
589                }
590                true
591            }
592            StmtKind::Emit(expression) | StmtKind::Expr(expression) => {
593                self.analyze_expr(expression) && !branch_always_exits(self.gcx, statement)
594            }
595            StmtKind::Revert(expression) => {
596                self.analyze_expr(expression);
597                false
598            }
599            StmtKind::Return(Some(expression)) => {
600                if self.analyze_expr(expression) {
601                    self.set_return_aliases(expression);
602                    self.capture_return_flow();
603                }
604                false
605            }
606            StmtKind::Return(None) => {
607                self.capture_named_returns();
608                self.capture_return_flow();
609                false
610            }
611            StmtKind::Block(block) | StmtKind::UncheckedBlock(block) => self.analyze_block(block),
612            StmtKind::AssemblyBlock(block, _) => {
613                self.assembly_depth += 1;
614                let continues = self.analyze_block(block);
615                self.assembly_depth -= 1;
616                continues
617            }
618            StmtKind::Loop(block, source) => self.analyze_loop(block, source),
619            StmtKind::If(condition, then_statement, else_statement) => {
620                self.analyze_expr(condition)
621                    && self.analyze_alternatives(
622                        [Some(then_statement), else_statement],
623                        None,
624                        |this, arm| arm.is_none_or(|arm| this.analyze_stmt(arm)),
625                    )
626            }
627            StmtKind::Try(try_statement) => {
628                self.analyze_expr(&try_statement.expr)
629                    && self.analyze_alternatives(try_statement.clauses, None, |this, clause| {
630                        this.analyze_block(clause.block)
631                    })
632            }
633            StmtKind::Switch(switch) => {
634                if !self.analyze_expr(switch.selector) {
635                    return false;
636                }
637                // A value matching no `case` falls through unless a `default` (stored last, with
638                // no constant) is present.
639                let has_default = switch.cases.last().is_some_and(|case| case.constant.is_none());
640                let fallthrough = (!has_default).then(|| self.flow_state());
641                self.analyze_alternatives(switch.cases, fallthrough, |this, case| {
642                    this.analyze_block(case.body)
643                })
644            }
645            StmtKind::Break | StmtKind::Continue => {
646                let state = self.flow_state();
647                if let Some(flow) = self.loop_flow.last_mut() {
648                    let destination = if matches!(statement.kind, StmtKind::Break) {
649                        &mut flow.breaks
650                    } else {
651                        &mut flow.continues
652                    };
653                    join(destination, state);
654                }
655                false
656            }
657            StmtKind::Placeholder => self
658                .modifier_continuations
659                .last()
660                .copied()
661                .is_none_or(|c| self.analyze_modifier_chain(c.modifiers, c.next, c.body)),
662            StmtKind::Err(_) => true,
663        }
664    }
665
666    /// Iterates the loop body from the joined loop-head state until the alias/guard state stops
667    /// changing. Returns whether the loop can be left normally.
668    fn analyze_loop(&mut self, block: hir::Block<'gcx>, source: LoopSource<'gcx>) -> bool {
669        let mut head = self.flow_state();
670        let mut exits = None;
671        loop {
672            self.set_flow_state(head.clone());
673            let (mut breaks, continues, completes) = self.analyze_loop_stmts(|this| {
674                this.analyze_block(block)
675                    && loop_update(source).is_none_or(|update| this.analyze_stmt(update))
676            });
677            let mut backedges = completes.then(|| self.flow_state());
678            // `continue` in a do-while still evaluates the lowered `if (!cond) break;`.
679            let epilogue = matches!(source, LoopSource::DoWhile)
680                .then(|| block.stmts.last())
681                .flatten()
682                .filter(|epilogue| is_loop_termination_if(epilogue));
683            match (continues, epilogue) {
684                (Some(state), Some(epilogue)) => {
685                    self.set_flow_state(state);
686                    let (epilogue_breaks, epilogue_continues, completes) =
687                        self.analyze_loop_stmts(|this| this.analyze_stmt(epilogue));
688                    if completes {
689                        join(&mut backedges, self.flow_state());
690                    }
691                    breaks = breaks.into_iter().chain(epilogue_breaks).reduce(|a, b| a.merge(&b));
692                    backedges =
693                        backedges.into_iter().chain(epilogue_continues).reduce(|a, b| a.merge(&b));
694                }
695                (Some(state), None) => join(&mut backedges, state),
696                (None, _) => {}
697            }
698            if let Some(breaks) = breaks {
699                join(&mut exits, breaks);
700            }
701            let Some(backedges) = backedges else { break };
702            let next = head.merge(&backedges);
703            if next == head {
704                break;
705            }
706            head = next;
707        }
708        let Some(exits) = exits else { return false };
709        self.set_flow_state(exits);
710        true
711    }
712
713    /// Runs `analyze` inside a fresh loop frame, returning the `break` state, the `continue` state
714    /// and whether the body completed.
715    fn analyze_loop_stmts(
716        &mut self,
717        analyze: impl FnOnce(&mut Self) -> bool,
718    ) -> (Option<FlowState>, Option<FlowState>, bool) {
719        self.loop_flow.push(LoopFlow::default());
720        let completes = analyze(self);
721        let flow = self.loop_flow.pop().expect("loop flow frame");
722        (flow.breaks, flow.continues, completes)
723    }
724
725    fn flow_state(&self) -> FlowState {
726        FlowState { aliases: self.aliases.clone(), guards: self.guards.clone() }
727    }
728
729    fn set_flow_state(&mut self, state: FlowState) {
730        self.aliases = state.aliases;
731        self.guards = state.guards;
732    }
733
734    fn capture_return_flow(&mut self) {
735        let state = self.flow_state();
736        if let Some(exits) = self.return_flow.last_mut() {
737            join(exits, state);
738        }
739    }
740
741    /// Analyzes an expression, returning whether its evaluation can complete.
742    fn analyze_expr(&mut self, expression: &'gcx hir::Expr<'gcx>) -> bool {
743        match &expression.peel_parens().kind {
744            ExprKind::Assign(lhs, operator, rhs) => {
745                if !(self.analyze_expr(rhs) && self.analyze_expr(lhs)) {
746                    return false;
747                }
748                self.apply_assignment(lhs, rhs, operator.is_some());
749                true
750            }
751            ExprKind::Delete(inner) => {
752                if !self.analyze_expr(inner) {
753                    return false;
754                }
755                self.record_write(inner);
756                true
757            }
758            ExprKind::Unary(operator, inner) => {
759                if !self.analyze_expr(inner) {
760                    return false;
761                }
762                if operator.kind.has_side_effects() {
763                    self.record_write(inner);
764                }
765                true
766            }
767            ExprKind::Call(callee, args) => {
768                let (callee, options) = callee.split_call_options();
769                if !(self.analyze_expr(callee)
770                    && options
771                        .iter()
772                        .flat_map(|options| options.args)
773                        .all(|option| self.analyze_expr(&option.value))
774                    && args.exprs().all(|argument| self.analyze_expr(argument)))
775                {
776                    return false;
777                }
778
779                if let ExprKind::Member(base, _) = &callee.peel_parens().kind
780                    && let Some(
781                        builtin @ (Builtin::ArrayPush0 | Builtin::ArrayPush | Builtin::ArrayPop),
782                    ) = self.gcx.resolved_builtin(callee)
783                {
784                    self.record_write(base);
785                    if builtin == Builtin::ArrayPush0 {
786                        let roots = self.storage_roots(base);
787                        self.store_call_returns(expression.id, vec![roots]);
788                    }
789                }
790
791                if self.gcx.resolved_builtin(callee) == Some(Builtin::YulSstore)
792                    && let Some(slot) = args.exprs().next()
793                {
794                    let roots = self.slot_roots(slot);
795                    self.record_roots(roots);
796                }
797
798                if let Some((_, function_id, receiver)) = self.resolved_internal_call(callee) {
799                    self.guards.insert(function_id);
800                    let arguments = receiver
801                        .into_iter()
802                        .chain(
803                            (0..args.len())
804                                .filter_map(|index| self.gcx.call_arg(expression, index)),
805                        )
806                        .collect::<Vec<_>>();
807                    let summary = self.analyze_call(function_id, &arguments);
808                    self.store_call_returns(expression.id, summary.returns);
809                    return summary.completes;
810                }
811                true
812            }
813            ExprKind::CallOptions(callee, options) => {
814                self.analyze_expr(callee)
815                    && options.args.iter().all(|option| self.analyze_expr(&option.value))
816            }
817            ExprKind::Binary(lhs, operator, rhs) => {
818                self.analyze_expr(lhs)
819                    && if matches!(operator.kind, BinOpKind::And | BinOpKind::Or) {
820                        // The right operand may be skipped.
821                        self.analyze_alternatives([Some(*rhs), None], None, |this, rhs| {
822                            rhs.is_none_or(|rhs| this.analyze_expr(rhs))
823                        })
824                    } else {
825                        self.analyze_expr(rhs)
826                    }
827            }
828            ExprKind::Index(base, index) => {
829                self.analyze_expr(base) && index.is_none_or(|index| self.analyze_expr(index))
830            }
831            ExprKind::Slice(base, start, end) => {
832                self.analyze_expr(base)
833                    && start.is_none_or(|start| self.analyze_expr(start))
834                    && end.is_none_or(|end| self.analyze_expr(end))
835            }
836            ExprKind::Member(base, _) | ExprKind::YulMember(base, _) | ExprKind::Payable(base) => {
837                self.analyze_expr(base)
838            }
839            ExprKind::Ternary(condition, if_true, if_false) => {
840                self.analyze_expr(condition)
841                    && self.analyze_alternatives([*if_true, *if_false], None, |this, arm| {
842                        this.analyze_expr(arm)
843                    })
844            }
845            ExprKind::Array(expressions) => {
846                expressions.iter().all(|expression| self.analyze_expr(expression))
847            }
848            ExprKind::Tuple(expressions) => {
849                expressions.iter().flatten().all(|expression| self.analyze_expr(expression))
850            }
851            ExprKind::New(_)
852            | ExprKind::TypeCall(_)
853            | ExprKind::Type(_)
854            | ExprKind::Ident(_)
855            | ExprKind::Lit(_)
856            | ExprKind::Err(_) => true,
857        }
858    }
859
860    fn record_write(&mut self, expression: &hir::Expr<'_>) {
861        self.record_roots(self.storage_roots(expression));
862    }
863
864    fn record_roots(&mut self, roots: StorageRoots) {
865        for variable_id in roots {
866            self.writes
867                .entry(variable_id)
868                .and_modify(|guards| guards.retain(|guard| self.guards.contains(guard)))
869                .or_insert_with(|| self.guards.clone());
870        }
871    }
872
873    fn set_storage_alias(&mut self, variable_id: VariableId, roots: StorageRoots) {
874        let variable = self.gcx.hir.variable(variable_id);
875        if !variable.kind.is_state()
876            && variable.data_location == Some(DataLocation::Storage)
877            && !roots.is_empty()
878        {
879            self.aliases.storage.insert(variable_id, roots);
880        } else {
881            self.aliases.storage.remove(&variable_id);
882        }
883    }
884
885    fn set_slot_alias(&mut self, variable_id: VariableId, roots: StorageRoots) {
886        if roots.is_empty() {
887            self.aliases.slots.remove(&variable_id);
888        } else {
889            self.aliases.slots.insert(variable_id, roots);
890        }
891    }
892
893    /// Storage pointer locals alias the roots they are bound to; inside assembly, Yul locals also
894    /// track the slots they hold.
895    fn alias_local(&mut self, variable_id: VariableId, roots: StorageRoots) {
896        if self.assembly_depth > 0 {
897            self.set_slot_alias(variable_id, roots.clone());
898        }
899        self.set_storage_alias(variable_id, roots);
900    }
901
902    fn alias_local_from_expr(&mut self, variable_id: VariableId, expression: &hir::Expr<'_>) {
903        if self.assembly_depth > 0 {
904            let roots = self.slot_roots(expression);
905            self.set_slot_alias(variable_id, roots);
906        }
907        let roots = self.storage_roots(expression);
908        self.set_storage_alias(variable_id, roots);
909    }
910
911    fn apply_assignment(
912        &mut self,
913        lhs: &'gcx hir::Expr<'gcx>,
914        rhs: &'gcx hir::Expr<'gcx>,
915        compound: bool,
916    ) {
917        let lhs = lhs.peel_parens();
918        if compound {
919            return self.record_write(lhs);
920        }
921        match &lhs.kind {
922            // `pointer.slot := x` retargets a storage pointer.
923            ExprKind::YulMember(base, member)
924                if member.as_str() == "slot"
925                    && let Some(local) = lhs_local_var(self.gcx, base) =>
926            {
927                let roots = self.slot_roots(rhs);
928                self.set_storage_alias(local, roots);
929            }
930            ExprKind::Tuple(expressions) => {
931                for (index, expression) in expressions.iter().enumerate() {
932                    let Some(expression) = expression else { continue };
933                    if let Some(local) = lhs_local_var(self.gcx, expression) {
934                        let roots = self.storage_roots_for_output(rhs, index, expressions.len());
935                        self.alias_local(local, roots);
936                    } else {
937                        self.record_write(expression);
938                    }
939                }
940            }
941            _ => match lhs_local_var(self.gcx, lhs) {
942                Some(local) => self.alias_local_from_expr(local, rhs),
943                None => self.record_write(lhs),
944            },
945        }
946    }
947
948    fn set_return_aliases(&mut self, expression: &'gcx hir::Expr<'gcx>) {
949        let Some(&function_id) = self.stack.last() else { return };
950        let outputs = self.gcx.hir.function(function_id).returns.len();
951        let roots: Vec<_> = (0..outputs)
952            .map(|index| self.storage_roots_for_output(expression, index, outputs))
953            .collect();
954        self.extend_returns(roots);
955    }
956
957    fn capture_named_returns(&mut self) {
958        let Some(&function_id) = self.stack.last() else { return };
959        let function = self.gcx.hir.function(function_id);
960        let aliases = if function.is_yul { &self.aliases.slots } else { &self.aliases.storage };
961        let roots: Vec<_> = function
962            .returns
963            .iter()
964            .map(|return_id| aliases.get(return_id).cloned().unwrap_or_default())
965            .collect();
966        self.extend_returns(roots);
967    }
968
969    fn extend_returns(&mut self, roots: Vec<StorageRoots>) {
970        if let Some(frame) = self.return_stack.last_mut() {
971            for (returned, roots) in frame.iter_mut().zip(roots) {
972                returned.extend(roots);
973            }
974        }
975    }
976
977    /// Storage roots flowing into output `index` of `outputs` from `expression`.
978    fn storage_roots_for_output(
979        &self,
980        expression: &hir::Expr<'_>,
981        index: usize,
982        outputs: usize,
983    ) -> StorageRoots {
984        match &expression.peel_parens().kind {
985            ExprKind::Tuple(expressions) if outputs > 1 => expressions
986                .get(index)
987                .copied()
988                .flatten()
989                .map_or_else(StorageRoots::new, |expression| self.storage_roots(expression)),
990            ExprKind::Call(..) => self
991                .call_returns
992                .get(&expression.id)
993                .and_then(|returns| returns.get(index))
994                .cloned()
995                .unwrap_or_default(),
996            _ if outputs == 1 && index == 0 => self.storage_roots(expression),
997            _ => StorageRoots::new(),
998        }
999    }
1000
1001    fn store_call_returns(&mut self, expression_id: ExprId, returns: Vec<StorageRoots>) {
1002        if returns.is_empty() {
1003            return;
1004        }
1005        let stored = self.call_returns.entry(expression_id).or_default();
1006        if stored.len() < returns.len() {
1007            stored.resize_with(returns.len(), StorageRoots::new);
1008        }
1009        for (stored, returned) in stored.iter_mut().zip(returns) {
1010            stored.extend(returned);
1011        }
1012    }
1013
1014    /// Call arguments in declaration order of `declared_id`'s parameters, the attached receiver
1015    /// first.
1016    fn ordered_call_arguments(
1017        &self,
1018        declared_id: FunctionId,
1019        arguments: CallArgs<'gcx>,
1020        receiver: Option<&'gcx hir::Expr<'gcx>>,
1021    ) -> Vec<&'gcx hir::Expr<'gcx>> {
1022        let names = self.gcx.callable_param_names(CallableParamSource::Function {
1023            id: declared_id,
1024            skips_receiver: receiver.is_some(),
1025        });
1026        let arguments = (0..names.len())
1027            .filter_map(|index| arguments.argument_for_parameter(index, Some(&names)));
1028        receiver.into_iter().chain(arguments).collect()
1029    }
1030
1031    /// `(declared, dispatched, attached receiver)` for a call that executes contract code in this
1032    /// storage context: bare identifiers, `using for` attached calls, library calls and
1033    /// `super.`/`Base.`/`Lib.` qualified calls.
1034    fn resolved_internal_call(
1035        &self,
1036        callee: &'gcx hir::Expr<'gcx>,
1037    ) -> Option<(FunctionId, FunctionId, Option<&'gcx hir::Expr<'gcx>>)> {
1038        let resolved = self.gcx.resolved_callee(callee.peel_parens().id)?;
1039        let function_id = resolved.res.as_function()?;
1040        let attached = resolved.attached;
1041        match &callee.peel_parens().kind {
1042            ExprKind::Ident(_) => Some((function_id, self.dispatch_function(function_id), None)),
1043            ExprKind::Member(base, _) if attached => Some((function_id, function_id, Some(base))),
1044            ExprKind::Member(base, _)
1045                if self.is_library_function(function_id)
1046                    || is_static_internal_base(self.gcx, base) =>
1047            {
1048                Some((function_id, function_id, None))
1049            }
1050            _ => None,
1051        }
1052    }
1053
1054    fn is_library_function(&self, function_id: FunctionId) -> bool {
1055        self.gcx
1056            .hir
1057            .function(function_id)
1058            .contract
1059            .is_some_and(|contract_id| self.gcx.hir.contract(contract_id).kind.is_library())
1060    }
1061
1062    /// The most-derived override of a virtual function or modifier in the analyzed hierarchy.
1063    fn dispatch_function(&self, function_id: FunctionId) -> FunctionId {
1064        self.gcx.resolve_virtual_function(self.bases[0], function_id)
1065    }
1066
1067    /// State variables an lvalue may write: state roots, aliased storage pointers and
1068    /// storage-returning calls.
1069    fn storage_roots(&self, expression: &hir::Expr<'_>) -> StorageRoots {
1070        let mut roots = StorageRoots::new();
1071        self.collect_storage_roots(expression, &mut roots);
1072        roots
1073    }
1074
1075    fn collect_storage_roots(&self, expression: &hir::Expr<'_>, roots: &mut StorageRoots) {
1076        let expression = expression.peel_parens();
1077        match &expression.kind {
1078            ExprKind::Ident(_) => {
1079                if let Some(variable_id) = self.gcx.resolved_variable(expression) {
1080                    if self.gcx.hir.variable(variable_id).kind.is_state() {
1081                        roots.insert(variable_id);
1082                    } else if let Some(aliases) = self.aliases.storage.get(&variable_id) {
1083                        roots.extend(aliases);
1084                    }
1085                }
1086            }
1087            ExprKind::Index(base, _)
1088            | ExprKind::Slice(base, ..)
1089            | ExprKind::Member(base, _)
1090            | ExprKind::YulMember(base, _)
1091            | ExprKind::Payable(base)
1092            | ExprKind::Unary(_, base)
1093            | ExprKind::Delete(base) => self.collect_storage_roots(base, roots),
1094            ExprKind::Tuple(expressions) => {
1095                for expression in expressions.iter().flatten() {
1096                    self.collect_storage_roots(expression, roots);
1097                }
1098            }
1099            ExprKind::Ternary(_, if_true, if_false) => {
1100                self.collect_storage_roots(if_true, roots);
1101                self.collect_storage_roots(if_false, roots);
1102            }
1103            ExprKind::Call(..) => {
1104                roots.extend(self.call_returns.get(&expression.id).into_iter().flatten().flatten());
1105            }
1106            _ => {}
1107        }
1108    }
1109
1110    /// State variables whose slot a Yul expression may evaluate to.
1111    fn slot_roots(&self, expression: &hir::Expr<'_>) -> StorageRoots {
1112        let mut roots = StorageRoots::new();
1113        self.collect_slot_roots(expression, &mut roots);
1114        roots
1115    }
1116
1117    fn collect_slot_roots(&self, expression: &hir::Expr<'_>, roots: &mut StorageRoots) {
1118        let expression = expression.peel_parens();
1119        match &expression.kind {
1120            ExprKind::Ident(_) => {
1121                if let Some(variable_id) = self.gcx.resolved_variable(expression)
1122                    && let Some(aliases) = self.aliases.slots.get(&variable_id)
1123                {
1124                    roots.extend(aliases);
1125                }
1126            }
1127            ExprKind::YulMember(base, member) if member.as_str() == "slot" => {
1128                self.collect_storage_roots(base, roots);
1129            }
1130            ExprKind::Call(..) if self.call_returns.contains_key(&expression.id) => {
1131                roots.extend(self.call_returns[&expression.id].iter().flatten());
1132            }
1133            // Any other expression may propagate a slot computed from its operands.
1134            ExprKind::Call(callee, args) => {
1135                let (callee, options) = callee.split_call_options();
1136                self.collect_slot_roots(callee, roots);
1137                for option in options.iter().flat_map(|options| options.args) {
1138                    self.collect_slot_roots(&option.value, roots);
1139                }
1140                for argument in args.exprs() {
1141                    self.collect_slot_roots(argument, roots);
1142                }
1143            }
1144            ExprKind::Assign(lhs, _, rhs) | ExprKind::Binary(lhs, _, rhs) => {
1145                self.collect_slot_roots(lhs, roots);
1146                self.collect_slot_roots(rhs, roots);
1147            }
1148            ExprKind::Index(base, index) => {
1149                for expression in [Some(*base), *index].into_iter().flatten() {
1150                    self.collect_slot_roots(expression, roots);
1151                }
1152            }
1153            ExprKind::Slice(base, start, end) => {
1154                for expression in [Some(*base), *start, *end].into_iter().flatten() {
1155                    self.collect_slot_roots(expression, roots);
1156                }
1157            }
1158            ExprKind::Ternary(condition, if_true, if_false) => {
1159                for expression in [condition, if_true, if_false] {
1160                    self.collect_slot_roots(expression, roots);
1161                }
1162            }
1163            ExprKind::Member(base, _)
1164            | ExprKind::YulMember(base, _)
1165            | ExprKind::Payable(base)
1166            | ExprKind::Unary(_, base)
1167            | ExprKind::Delete(base) => self.collect_slot_roots(base, roots),
1168            ExprKind::Array(expressions) => {
1169                for expression in *expressions {
1170                    self.collect_slot_roots(expression, roots);
1171                }
1172            }
1173            ExprKind::Tuple(expressions) => {
1174                for expression in expressions.iter().flatten() {
1175                    self.collect_slot_roots(expression, roots);
1176                }
1177            }
1178            _ => {}
1179        }
1180    }
1181}
1182
1183/// `super.f`, `Base.f` or `Lib.f`: a statically dispatched internal call.
1184fn is_static_internal_base(gcx: Gcx<'_>, base: &hir::Expr<'_>) -> bool {
1185    is_builtin(gcx, base, sym::super_)
1186        || matches!(
1187            gcx.resolved_expr(base),
1188            Some(Res::Item(ItemId::Contract(_)) | Res::Namespace(_))
1189        )
1190}