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

🛠️ 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.