shuka

About

shuka is a CLI tool for fetching verified smart contract source code from blockchain explorers and saving the full source tree locally.

It is built for workflows where manually copying verified source files from explorer pages is slow, repetitive, and error-prone.

The project keeps explorer-specific fetching, parsing, and filesystem storage separated so new explorers can be added without rewriting the whole pipeline.

Features

• Fetch verified smart contract source code by address.
• Save raw explorer responses for inspection.
• Save single-file and multi-file Solidity source trees.
• Keep explorer-specific API logic separate from parsing and storage.

Supported Explorers

Installation

Prerequisites

Install Rust and Cargo:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Check installation:

rustc --version
cargo --version

Install from source

git clone https://github.com/Kode-n-Rolla/shuka.git
cd shuka
cargo install --path .

Install with Cargo

cargo install shuka

Configuration

Ethereum / Etherscan v2

Ethereum uses the Etherscan v2 API and requires an API key.

Create a local .env file:

ETHEREUM_API_KEY=your_key_here

Ethereum also requires --chain-id. For Ethereum Mainnet, use:

--chain-id 1

Battlechain Testnet

Battlechain does not require:

• API key
• chain id

Usage

shuka --help

shuka fetch --help

Fetch an Ethereum contract:

shuka fetch ethereum 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 --chain-id 1

Fetch a Battlechain contract:

shuka fetch battlechain 0x526Ed31aAfbbe40f077D94CEAfDF20B5f99Bd7B1

Choose an output directory:

shuka fetch ethereum 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 --chain-id 1 --out ./contracts/usdc

Print the optional banner:

shuka --with-banner fetch battlechain 0x526Ed31aAfbbe40f077D94CEAfDF20B5f99Bd7B1

By default, output is written to:

contracts/<explorer>/<address>/

Each output directory contains:

• raw_response.json
• extracted source files

Architecture

shuka is intentionally organized as a small pipeline where each stage has one responsibility.

The project follows a simple pipeline:

FetchRequest
  -> Explorer Adapter
  -> RawExplorerResponse
  -> Parser
  -> ParsedSourceBundle
  -> Storage
  -> SaveResult
  -> FetchOutcome

Module responsibilities:

• CLI parses arguments, builds FetchRequest, and displays results.
• App orchestrates the pipeline.
• Explorer adapters contain API-specific fetch logic.
• Parser transforms raw explorer responses into normalized source files.
• Storage writes files to disk and validates source paths.
• Types define shared data models.
• Error defines the unified project error type.

Important boundaries:

• Explorer adapters should not parse source files.
• Parser should not write files.
• Storage should not know explorer API details.
• CLI should stay thin.

Adding Another Explorer

Adding a new explorer usually means:

1. document the API behavior
2. add explorer enum support
3. implement a SourceExplorer adapter
4. register the adapter in the app layer
5. test raw response saving
6. update parser logic only if the raw response shape differs

See docs/adding-another-explorer.md for the full checklist.

Parser Notes

The current parser handles Etherscan-like response envelopes and supports:

1. plain Solidity source
2. structured multi-file source

If a new explorer fails to parse but raw_response.json is saved correctly, the fix usually belongs in the parser, not in the explorer adapter or storage layer. Full instructions 👉 docs/parser-notes.md