truent-utils 0.6.0

Truent: Utility functions for the Truent multi-chain smart contract security analyzer.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
//! Solidity compiler (solc) management and execution.
//!
//! This module handles finding, downloading, and running the solc compiler
//! to generate JSON AST output for Solidity smart contracts.

use anyhow::{anyhow, bail, Context, Result};
use serde::{Deserialize, Serialize};
use std::path::{Path, PathBuf};
use std::process::Command;
use tracing::info;

/// Minimum supported solc version
pub const MIN_SOLC_VERSION: &str = "0.6.0";

/// Version fetched when no solc is present on the system.
///
/// Was pinned at 0.8.21, which cannot compile the `pragma ^0.8.24` that
/// current contracts declare. Override with `TRUENT_SOLC_VERSION` when a
/// project needs a specific release.
pub const DEFAULT_SOLC_VERSION: &str = "0.8.28";

/// Represents the solc compiler manager
#[derive(Debug, Clone)]
pub struct SolcManager {
    solc_path: PathBuf,
    version: String,
}

/// Solc combined JSON output
#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct SolcOutput {
    /// Contract data keyed by fully qualified name
    pub contracts: std::collections::HashMap<String, serde_json::Value>,
    /// Source files with AST
    pub sources: std::collections::HashMap<String, SourceData>,
}

/// Source file data with AST
#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct SourceData {
    #[serde(rename = "AST")]
    /// Raw AST JSON value from solc output
    pub ast: serde_json::Value,
}

impl SolcManager {
    /// Find or download a compatible solc binary
    ///
    /// Search order:
    /// 1. SOLC_PATH environment variable
    /// 2. solc on system PATH
    /// 3. ~/.truent/solc/solc (cached download)
    /// 4. Download latest stable from binaries.soliditylang.org
    pub fn new() -> Result<Self> {
        // Try SOLC_PATH environment variable
        if let Ok(path) = std::env::var("SOLC_PATH") {
            let path = PathBuf::from(path);
            if path.exists() {
                let version = Self::get_version(&path)?;
                info!(
                    "Using solc from SOLC_PATH: {} (v{})",
                    path.display(),
                    version
                );
                return Ok(Self {
                    solc_path: path,
                    version,
                });
            }
        }

        // Try solc on system PATH
        if let Ok(output) = Command::new("solc").arg("--version").output() {
            if output.status.success() {
                let version_str = String::from_utf8_lossy(&output.stdout);
                let version = Self::parse_version(&version_str)?;
                info!("Using system solc (v{})", version);
                return Ok(Self {
                    solc_path: PathBuf::from("solc"),
                    version,
                });
            }
        }

        // Try cached download
        let cache_path = Self::cache_path();
        if cache_path.exists() {
            let version = Self::get_version(&cache_path)?;
            info!(
                "Using cached solc from {} (v{})",
                cache_path.display(),
                version
            );
            return Ok(Self {
                solc_path: cache_path,
                version,
            });
        }

        // Download latest stable
        info!("solc not found locally, downloading...");
        Self::download_solc()
    }

    /// Get the full AST JSON output for a Solidity file.
    ///
    /// Compiled with the optimizer on, and retried through the IR pipeline if
    /// the legacy code generator runs out of stack slots. Without either,
    /// "Stack too deep" rejects any contract with a moderately wide function —
    /// a routine shape, not an exotic one — and the whole dynamic analysis is
    /// lost for that file.
    pub fn get_ast_json(&self, source_path: &Path) -> Result<SolcOutput> {
        match self.run_solc(source_path, false) {
            Ok(out) => Ok(out),
            Err(e) => {
                let msg = e.to_string();
                if Self::is_stack_too_deep(&msg) {
                    info!(
                        "solc hit 'stack too deep' on {}; retrying with --via-ir",
                        source_path.display()
                    );
                    self.run_solc(source_path, true).map_err(|via_ir_err| {
                        anyhow!(
                            "solc failed on {} with and without --via-ir.\n\
                             legacy: {}\n--via-ir: {}",
                            source_path.display(),
                            msg,
                            via_ir_err
                        )
                    })
                } else {
                    Err(e)
                }
            }
        }
    }

    /// True when solc rejected the source only because the legacy code
    /// generator ran out of stack slots — recoverable via the IR pipeline.
    fn is_stack_too_deep(stderr: &str) -> bool {
        stderr.contains("Stack too deep")
    }

    fn run_solc(&self, source_path: &Path, via_ir: bool) -> Result<SolcOutput> {
        let mut cmd = Command::new(&self.solc_path);
        cmd.args([
            "--combined-json",
            "ast,abi,bin,bin-runtime,srcmap,srcmap-runtime",
            "--allow-paths",
            ".",
            // The optimizer is what frees up stack slots; without it even
            // ordinary contracts fail to compile.
            "--optimize",
        ]);
        if via_ir {
            cmd.arg("--via-ir");
        }

        let output = cmd
            .arg(source_path)
            .output()
            .with_context(|| format!("Failed to run solc on: {}", source_path.display()))?;

        if !output.status.success() {
            let stderr = String::from_utf8_lossy(&output.stderr);
            // Only fail on fatal errors, not warnings
            if Self::has_fatal_errors(&stderr) {
                bail!("solc failed on {}: {}", source_path.display(), stderr);
            }
        }

        let stdout = String::from_utf8_lossy(&output.stdout);
        serde_json::from_str(&stdout).with_context(|| {
            format!(
                "Failed to parse solc JSON output for: {}",
                source_path.display()
            )
        })
    }

    /// Get AST for source code string (writes to temp file)
    pub fn get_ast_for_source(&self, source: &str, _filename: &str) -> Result<SolcOutput> {
        let tmp = tempfile::Builder::new().suffix(".sol").tempfile()?;
        std::fs::write(tmp.path(), source)?;
        self.get_ast_json(tmp.path())
    }

    fn cache_path() -> PathBuf {
        let home = std::env::var("HOME").unwrap_or_else(|_| "/tmp".to_string());
        PathBuf::from(home)
            .join(".truent")
            .join("solc")
            .join("solc")
    }

    fn get_version(path: &Path) -> Result<String> {
        let output = Command::new(path).arg("--version").output()?;
        let stdout = String::from_utf8_lossy(&output.stdout);
        Self::parse_version(&stdout)
    }

    fn parse_version(output: &str) -> Result<String> {
        // Extract version from "solc, the solidity compiler programm
        // Version: 0.8.21+commit.d9974bed"
        output
            .lines()
            .find(|l| l.contains("Version:"))
            .and_then(|l| l.split_whitespace().nth(1))
            .map(|v| v.split('+').next().unwrap_or(v).to_string())
            .ok_or_else(|| anyhow!("Could not parse solc version"))
    }

    fn has_fatal_errors(stderr: &str) -> bool {
        stderr
            .lines()
            .any(|l| l.to_lowercase().contains("error:") && !l.contains("Warning:"))
    }

    fn download_solc() -> Result<Self> {
        let cache_path = Self::cache_path();
        std::fs::create_dir_all(cache_path.parent().unwrap())?;
        Self::clean_stale_downloads(cache_path.parent().unwrap());

        let platform = if cfg!(target_os = "macos") {
            "macosx-amd64"
        } else if cfg!(target_os = "windows") {
            "windows-amd64"
        } else {
            "linux-amd64"
        };

        let version_owned = std::env::var("TRUENT_SOLC_VERSION")
            .unwrap_or_else(|_| DEFAULT_SOLC_VERSION.to_string());
        let version = version_owned.as_str();

        // Every published solc binary is named with a build suffix —
        // `solc-linux-amd64-v0.8.21+commit.d9974bed`, not `...-v0.8.21`. The
        // bare form 404s, which took the whole dynamic engine offline on any
        // machine without a system solc. The suffix is not derivable, so it is
        // resolved from the official manifest.
        let url = Self::resolve_download_url(platform, version)?;

        info!(
            "Downloading solc v{} for {} from {}",
            version, platform, url
        );

        let response = ureq::get(&url)
            .call()
            .map_err(|e| anyhow!("Failed to download solc from {}: {}", url, e))?;

        // Download to a private temporary file, then rename it into place.
        //
        // Writing straight to the shared cache path meant that when several
        // processes started at once on a machine with no solc — a test suite
        // running in parallel, or several scans in a CI matrix — one would
        // still be writing the binary while another tried to execute it, and
        // the second failed with ETXTBSY ("Text file busy"). Each writer now
        // has its own file, and `rename` is atomic on the same filesystem, so
        // a reader ever only sees a complete binary.
        let unique = format!(
            "solc.{}.{}.part",
            std::process::id(),
            std::time::SystemTime::now()
                .duration_since(std::time::UNIX_EPOCH)
                .map(|d| d.as_nanos())
                .unwrap_or(0)
        );
        let staging = cache_path.with_file_name(unique);

        {
            let mut file = std::fs::File::create(&staging)?;
            std::io::copy(&mut response.into_reader(), &mut file)?;
            file.sync_all()?;
        }

        // Make executable on Unix, before it is visible under the real name.
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            let mut perms = std::fs::metadata(&staging)?.permissions();
            perms.set_mode(0o755);
            std::fs::set_permissions(&staging, perms)?;
        }

        Self::install_binary(&staging, &cache_path)?;

        info!("Downloaded solc to {}", cache_path.display());

        Ok(Self {
            solc_path: cache_path,
            version: version.to_string(),
        })
    }

    /// Move a freshly downloaded binary into its final location atomically.
    ///
    /// Separate from the download so the concurrency behaviour can be tested
    /// without fetching 15MB: the rename is what prevents a half-written file
    /// from ever being executed, and losing the race to another process is
    /// success as long as a usable binary ends up in place.
    fn install_binary(staging: &Path, dest: &Path) -> Result<()> {
        match std::fs::rename(staging, dest) {
            Ok(()) => Ok(()),
            Err(e) => {
                let _ = std::fs::remove_file(staging);
                if dest.exists() {
                    // Another process installed it first. Nothing to do.
                    Ok(())
                } else {
                    Err(anyhow!(
                        "failed to install solc into {}: {e}",
                        dest.display()
                    ))
                }
            }
        }
    }

    /// Delete leftover `.part` files from downloads that never finished.
    ///
    /// A process killed mid-download leaves its staging file behind; without
    /// this they accumulate in the cache directory forever.
    fn clean_stale_downloads(dir: &Path) {
        let Ok(entries) = std::fs::read_dir(dir) else {
            return;
        };
        for entry in entries.flatten() {
            let path = entry.path();
            if path.extension().and_then(|e| e.to_str()) == Some("part") {
                let _ = std::fs::remove_file(path);
            }
        }
    }

    /// Resolve the real download URL for `version` on `platform`.
    ///
    /// Reads `list.json`, the manifest solc publishes alongside the binaries,
    /// and takes the `path` recorded for the requested release. Falls back to
    /// the longest-standing naming convention only if the manifest cannot be
    /// fetched, so an offline failure still produces a usable error rather
    /// than a silent 404.
    fn resolve_download_url(platform: &str, version: &str) -> Result<String> {
        let list_url = format!("https://binaries.soliditylang.org/{platform}/list.json");

        let manifest: serde_json::Value = ureq::get(&list_url)
            .call()
            .map_err(|e| anyhow!("Failed to fetch solc manifest {}: {}", list_url, e))?
            .into_json()
            .map_err(|e| anyhow!("Malformed solc manifest at {}: {}", list_url, e))?;

        // `releases` maps a bare version to its exact filename.
        if let Some(path) = manifest
            .get("releases")
            .and_then(|r| r.get(version))
            .and_then(|p| p.as_str())
        {
            return Ok(format!(
                "https://binaries.soliditylang.org/{platform}/{path}"
            ));
        }

        // Fall back to scanning `builds` for the same version.
        if let Some(path) = manifest
            .get("builds")
            .and_then(|b| b.as_array())
            .and_then(|builds| {
                builds
                    .iter()
                    .find(|b| b.get("version").and_then(|v| v.as_str()) == Some(version))
                    .and_then(|b| b.get("path"))
                    .and_then(|p| p.as_str())
            })
        {
            return Ok(format!(
                "https://binaries.soliditylang.org/{platform}/{path}"
            ));
        }

        Err(anyhow!(
            "solc v{} is not published for {} (checked {})",
            version,
            platform,
            list_url
        ))
    }

    /// Get the version of the managed solc binary
    pub fn version(&self) -> &str {
        &self.version
    }

    /// Get the path to the solc binary
    pub fn path(&self) -> &Path {
        &self.solc_path
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_parse_version() {
        let output = "solc, the solidity compiler programm\nVersion: 0.8.21+commit.d9974bed";
        let version = SolcManager::parse_version(output).unwrap();
        assert_eq!(version, "0.8.21");
    }

    #[test]
    fn test_has_fatal_errors() {
        assert!(SolcManager::has_fatal_errors("Error: Something went wrong"));
        assert!(!SolcManager::has_fatal_errors("Warning: Be careful"));
        assert!(SolcManager::has_fatal_errors(
            "Warning: Be careful\nError: Failed"
        ));
    }
}

#[cfg(test)]
mod download_concurrency_tests {
    use super::*;

    /// Regression: the downloader wrote straight to the shared cache path, so
    /// a second process could execute a half-written binary and fail with
    /// ETXTBSY ("Text file busy"). Reproduced by a parallel test run on a
    /// machine with no solc — which is every CI runner.
    #[test]
    fn install_is_atomic_and_tolerates_losing_the_race() {
        let dir = tempfile::tempdir().expect("tempdir");
        let dest = dir.path().join("solc");

        let staging = dir.path().join("solc.1.part");
        std::fs::write(&staging, b"binary-a").expect("write");
        SolcManager::install_binary(&staging, &dest).expect("first install");
        assert_eq!(std::fs::read(&dest).expect("read"), b"binary-a");
        assert!(!staging.exists(), "staging file should be consumed");

        // A second writer arriving later must still end with a usable binary
        // in place and no staging file left behind.
        let staging2 = dir.path().join("solc.2.part");
        std::fs::write(&staging2, b"binary-b").expect("write");
        SolcManager::install_binary(&staging2, &dest).expect("second install");
        assert!(dest.exists());
        assert!(!staging2.exists());
    }

    #[test]
    fn stale_part_files_are_cleaned_up() {
        let dir = tempfile::tempdir().expect("tempdir");
        std::fs::write(dir.path().join("solc.999.part"), b"abandoned").expect("write");
        std::fs::write(dir.path().join("solc"), b"real").expect("write");

        SolcManager::clean_stale_downloads(dir.path());

        assert!(
            !dir.path().join("solc.999.part").exists(),
            "stale part removed"
        );
        assert!(dir.path().join("solc").exists(), "real binary kept");
    }
}