Crystal-Clear CLI: Smart Contract Supply Chain 🔗
Analyze and visualize Ethereum smart contract dependencies with ease. SCSC helps you understand contract interactions by generating detailed call graphs from on-chain data.
✨ Features
- 📊 Generate comprehensive call graphs from smart contract interactions
- 🔍 Analyze contract dependencies across specified block ranges
- 📈 Export visualizations in DOT format for further analysis
- ⚙️ Flexible configuration options for node connections and logging
🚀 Quick Start
Prerequisites
- Python 3.12 or higher
- Access to an Archive Ethereum node (local or remote)
- Allium API access: optional, used to enrich addresses with labels
- Etherscan API access: required for retrieving verified smart contract source code
- Poetry
Installation
# Clone the repository
git clone https://github.com/mab-xyz/crystal-clear.git
cd crystal-clear/webapp/backend/crystal-clear
# Install with Poetry
poetry install
# Activate the environment
poetry shell
💻 Usage
Crystal-Clear CLI provides two main commands:
1. Analyze Dependencies Command
Dependency Graph
# note the RPC node must have method trace_filter
crystal-clear dependency --node-url <node_url> \
--address <contract_address> \
--from-block <block> \
--to-block <block> \
[options]
# this exports the smart contract dependency graph
crystal-clear dependency --node-url <node_url>
--address 0xE592427A0AEce92De3Edee1F18E0157C05861564 \
--from-block 0x14c3b86 \
--to-block 0x14c3b90 \
--export-dot graph.dot
Risk analysis per contract (computes the risk factors, incl. proxy and permission risks)
You can select the scope of the analysis:
single– assesses the risk of the specified contract only.supply-chain– assesses the risk of the contract and all dependent contracts in its supply chain.
crystal-clear risk --etherscan-api-key <etherscan_api> \
--node-url <node_url> \
--scope [single|supply-chain]
--address <contract_address> \
[options]
crystal-clear risk
--address 0xE592427A0AEce92De3Edee1F18E0157C05861564 \
--scope single
--export-json analysis.json
Key Parameters
| Parameter | Description | Example |
|---|---|---|
--node-url |
Ethereum node URL | http://localhost:8545 |
--allium-api-key |
Allium API Key | `` |
--etherscan-api-key |
Etherscan API Key | `` |
--address |
Contract address to analyze | 0xE592427A0AEce92De3Edee1F18E0157C05861564 |
--from-block |
Starting block number (hex/decimal) | 0x14c3b86 or 21665670 |
--to-block |
Ending block number (hex/decimal) | 0x14c3b90 or 21665680 |
--log-level |
Logging verbosity (analyze only) | ERROR, INFO, DEBUG |
--export-dot |
Output file for DOT graph (analyze only) | output.dot |
--export-json |
Output file for JSON (analyze only) | output.json |
🛠️ Development
We use modern Python tools to maintain high code quality:
- Black: Code formatting
- Ruff: Fast Python linting
- pre-commit: Git hooks
Set up the development environment:
# Install development dependencies
poetry install --with dev
# Set up pre-commit hooks
pre-commit install
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
Release files for mab-crystal-clear 1.0.27
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| mab_crystal_clear-1.0.27.tar.gz | 34.5 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| mab_crystal_clear-1.0.27-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 76.6 kB
Release files / mab_crystal_clear-1.0.27.tar.gz
| Download URL | mab_crystal_clear-1.0.27.tar.gz |
|---|---|
| Size | 34.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
adbb953e2002cdd44af60761d04a7243e8112b1800d8afec287e5a739656282e
|
|
BLAKE2b-256 checksum How to use checksums |
372f165ae8ee1b6d7ad24700945fda078974b9e6096a01cf2171bcf63fa509f1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.5.1 CPython/3.12.15 Linux/6.17.0-1022-azure
|
Release files / mab_crystal_clear-1.0.27-py3-none-any.whl
| Download URL | mab_crystal_clear-1.0.27-py3-none-any.whl |
|---|---|
| Size | 42.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
11e450ad62aa6954aa6f425fe601b4fa7e28895232ded4a092ccb5b722368eaf
|
|
BLAKE2b-256 checksum How to use checksums |
6ede654e1ba8d3d683eeba8b7dde05acf78b0d99bcae62b61245e4c4b9c75121
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.5.1 CPython/3.12.15 Linux/6.17.0-1022-azure
|
Security for mab-crystal-clear 1.0.27
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
