Metadata-Version: 2.4
Name: solderx
Version: 0.1.4
Summary: ⚡️ SolderX – Melt Imports. Solder Solidity. Flatten Everything 🔥
Home-page: https://github.com/sidarth16/solderx
Author: Sidarth S
Author-email: Sidarth S <ssidarth1999@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/sidarth16/solderx
Keywords: solidity,flattener,smart-contracts,cli,etherscan,imports
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Utilities
Classifier: Intended Audience :: Developers
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3.0.0,>=2.28.0
Requires-Dist: toml
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# ⚡️ SolderX
>Fuse, Flatten & Forge Solidity Contracts <br/>

**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.

---

[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
[![PyPI version](https://img.shields.io/pypi/v/solderx.svg)](https://pypi.org/project/solderx/)
![GitHub Release Date](https://img.shields.io/github/release-date/sidarth16/SolderX)
[![Downloads](https://pepy.tech/badge/solderx)](https://pepy.tech/project/solderx)

---
## Installation
```bash
pip install solderx
```
**SolderX** is now available on [PyPI](https://pypi.org/project/solderx/) — 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**](https://github.com/your-org/solderx) | [Hardhat](https://github.com/NomicFoundation/hardhat) / [Foundry](https://github.com/foundry-rs/foundry) / [Remix](https://github.com/ethereum/remix-project) | [poa/solidity-flattener](https://github.com/poanetwork/solidity-flattener) | [solidity-flattener](https://github.com/BlockCatIO/solidity-flattener) | [truffle-flattener](https://github.com/nomiclabs/truffle-flattener) | [sol-merger](https://github.com/RyuuGan/sol-merger) | [slither-flatten](https://github.com/crytic/slither) |
|--------------------------------------------|----------------|-----------------------------|-------------------------|---------------------|--------------------|-------------|------------------|
|  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    | ✅               |


<br/>

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


---

## CLI Usage

```bash
# 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
```
```bash
# 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
```
```bash
# 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
```python
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.<br/>
>Want more scenarios covered? [Open an issue](https://github.com/sidarth16/solderx/issues)


## 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](https://github.com/sidarth16/solderx).<br/>
Let’s **forge ahead with SolderX** — and make Solidity flattening reliable, intuitive, and developer-friendly.
