⚡️ SolderX

Fuse, Flatten & Forge Solidity Contracts

Lightweight Solidity source flattener tool & dependency resolver.

SolderX is a developer-first Solidity flattener that handles local files, project folders, and verified contracts from blockchain explorers. Explorer sources are resolved directly from the API response and flattened on the fly, without requiring the source tree to be saved locally first.

It handles nested and relative imports, remappings, SPDX normalization, topological dependency ordering, import deduplication, and cyclic dependency detection.

Built for Solidity developers, researchers, auditors, and security tooling — including source verification, audits, and static analysis.

---

---

Installation

pip install solderx

SolderX is now available on PyPI — install it in seconds and start soldering Solidity contracts effortlessly.

✅ Requirements: Python 3.8+

---

Why use SolderX ? :

SolderX takes care of everything:

• ✅ Flatten a single file, entire project folder, or verified solidity contracts from explorers (like Etherscan)
• ✅ Supports remappings, relative imports, and handles complex cyclic dependencies
• ✅ Fully in-memory parsing — no .sol clutter or manual cleanup from explorer downloads

One powerful CLI + Python tool — clean, audit-ready output in seconds.

Most flatteners break on remappings, folder imports, or explorer parsings — SolderX doesn't.

---

Features Overview

Feature	Description	Status
Flatten Everything	Flatten from single files, full folders, or on-chain verified contracts	✅
Smart Import Resolver	Handles nested imports, multiline/same-line cases, and deduplicates cleanly	✅
Scan from Explorers	Supports Etherscan, Polygonscan, BscScan, Arbiscan, Base, Optimism, Avalanche	✅
In-Memory Flattening	No temp or unflattened junk files saved — All flattening done in-memory	✅
Remapping Support	Supports & resolves robust remappings (basic, deep, longest-match)	✅ (file)
Relative Imports in Remappings	Resolves ./ and ../ paths even within remapped libraries	✅ (file)
Import Parsing Engine	Extracts imports safely — ignores inside comments and strings	✅
Cyclic Import Detection	Flags and breaks infinite loops in import trees	✅
Folder-Aware Flattening	Detects and blocks out-of-scope imports across folder boundaries	✅
Chain + Address Validation	Catches malformed contract addresses and unsupported chains	✅
SPDX Header Merging	Deduplicates and merges license headers cleanly	✅
Import Deduplication	Ensures each dependency is flattened only once	✅
Python API Support	Expose all core functions (file, folder, scan) via clean Python API	✅
Professional CLI Interface	Clear status messages and concise error output	✅
Fast & Lightweight	Built with Python, no heavy dependencies	✅
Static Analysis Ready	Output works with all static analyzers	✅
Pluggable Design	Designed to extend — GitHub flattening, config aliasing, IDE plugins	Planned

---

How SolderX Compares :

⚠️ Note: This comparison is a working draft. Feature support for third-party tools may be evolving, and accuracy is based on current public documentation and observed behavior. Final evaluation pending deeper testing.

Feature	SolderX	Hardhat / Foundry / Remix	poa/solidity-flattener	solidity-flattener	truffle-flattener	sol-merger	slither-flatten
Standalone file flattening	✅	✅	✅	✅	✅	✅	✅
Folder/project flattening	✅	❌	❌	⚠️ Limited	⚠️ Partial	✅	❌
Etherscan flattening (verified source)	✅	❌	❌	❌	❌	❌	✅
On-the-fly (no temp files saved)	✅	❌	❌	❌	❌	❌	❌
Smart remapping resolution (@...)	✅ Deep	⚠️ Hardcoded	❌	❌	❌	✅ Basic	❌
Relative imports in remapped libs	✅	❌	❌	❌	❌	❌	❌
Multiline & nested import handling	✅	⚠️ Partial	❌	❌	❌	❌	❌
Cyclic import detection & handling	✅	❌	❌	❌	❌	❌	❌
SPDX / license metadata cleanup	✅	❌	❌	❌	❌	❌	❌
Deduplicated output	✅	❌	❌	❌	❌	⚠️ Partial	❌
Comment-aware import extraction	✅	❌	❌	❌	❌	❌	❌
Python API support	✅	❌	❌	❌	❌	❌	✅
CLI with clear status output	✅	⚠️ Basic	❌	❌	✅ Basic	❌	⚠️ Minimal
Slither-compatible output	✅	✅	⚠️ Maybe	⚠️ Maybe	⚠️ Maybe	⚠️ Maybe	✅
Chain/address validation (Etherscan)	✅	❌	❌	❌	❌	❌	❌
Future-ready: GitHub flattening, aliases	✅ Planned	❌	❌	❌	❌	❌	⚠️ Limited
Maintained actively	✅	✅	❌	❌	❌	⚠️ Rare	✅

⚡️ SolderX brings file, folder, and verified explorer flattening together in a single lightweight interface

---

CLI Usage

# Simple file
solderx MyContract.sol

# Simple file with output path
solderx MyContract.sol --output MyContract_Flat.sol

# With remappings
solderx path/to/Contract.sol -r remappings.json

# Project folder with inline remapping
solderx src/ --remappings "@a=lib/a,@b=node_modules/b"

# With a remappings json
solderx project/contracts --remappings remappings.json

# With remappings and output filepath
solderx path/to/project/ -r remappings.json -o flattened/soldered_project.sol

# fetch from etherscan 
solderx 0xAbC...123 -chain eth --api-key YOUR_API_KEY

# also fetch from etherscan 
solderx eth:0xAbC...123 --api-key YOUR_API_KEY

Python API Usage

from solderx import solder_file, solder_folder, solder_scan

# 🔹 1. Flatten a single file
flattened_code = solder_file("path/to/Contract.sol")

# With remappings
flattened_code = solder_file("path/to/Contract.sol", remappings={"@oz": "lib/openzeppelin-contracts"})


# 🔹 2. Flatten an entire folder
flattened_code = solderx("contracts/")

# With remappings
flattened_code = solder_file("path/to/Contract.sol", remappings={"@oz": "lib/openzeppelin-contracts"})


# 🔹 3. Flatten from verified explorer source

# Flatten from Etherscan
flattened_code = solderx("0x123..789", chain = 'eth')

flattened_code = solderx("eth:0x123..789")


# 🔹 save file (default = False)
_ = solder_file("path/to/Contract.sol", save_file=True)

# save file in specified path
_ = solder_file("path/to/Contract.sol", output_path='./Contract_Flat.sol')

---

Real Use Cases

• Re-verify contracts on Etherscan after audits or refactors
• Feed single files into static analyzers like Slither, Mythril, Semgrep
• Compare bytecode outputs between flattened and deployed versions
• Onboard contributors by flattening large repos for easier reading
• Pipeline-ready for CI/CD - security scans, or deployment packaging

---

Test Summary :

Category	solder_file()	solder_folder()	solder_scan()
Flat imports	✅	✅	✅
Nested imports	✅	✅	✅
Save Flat File	✅	✅	✅
Multiline imports	✅	✅	✅
Multiple imports on same line	✅	✅	✅
Missing import (in-scope)	✅	✅	✅
Missing import (out-of-scope)	N/A	✅	✅
Import outside folder scope detection	N/A	✅	✅
Cyclic imports	✅	✅	✅
Remapping (basic + deep + longest)	✅✅✅	🔧 N/A	🔧 N/A
SPDX header merging	✅	✅	✅
Import deduplication	✅	✅	✅
Handle empty files	✅	✅	✅
Relative imports in remapped libs	✅	🔧 N/A	🔧 N/A
Relative import resolution	✅	✅	✅
Flattened & multi-file JSON parsing	N/A	N/A	✅
Contract name parsing	N/A	N/A	✅
Chain support handling	N/A	N/A	✅
Invalid address handling	N/A	N/A	✅

All core behaviors are verified using Pytest.
Want more scenarios covered? Open an issue

Roadmap & Future Additions

• Aliasing via config file (solderx.toml)
• Github repo flattening
• Strip all comments (inline, block, NatSpec - toggleable)
• Flatten by contract name (regex filtering)
• Color logs and interactive CLI summaries
• solc output validation (AST / compile test)
• Plugin support: slither, mythril, sourcify

---

Contributing

Pull requests are welcome!
If you’ve found a bug, a confusing case, or have feature ideas — open an issue or discussion on the repo.

We’re building this tool for Solidity developers like you.

---

License

SolderX is released under the Apache-2.0 License
Copyright 2025 Sidarth S

If you use SolderX in your project, product, or tooling, please consider acknowledging SolderX and linking to the project.

---

Support & Updates

We’re just getting started — expect support for more chains, deeper integrations, and smart dev-first features soon.

👉 Track progress, report issues, or request enhancements on the GitHub repo.
Let’s forge ahead with SolderX — and make Solidity flattening reliable, intuitive, and developer-friendly.