Crate scope 

Scope Blockchain Analysis

A command-line tool and library for blockchain data analysis, address book management, and transaction investigation.

Features

• Address Analysis: Query balances (with USD valuation), transaction history, and token holdings (ERC-20, SPL, TRC-20) for blockchain addresses across multiple chains. Chain auto-detection from address format.

• Transaction Analysis: Look up and decode blockchain transactions across EVM chains (via Etherscan proxy API), Solana (via getTransaction RPC), and Tron (via TronGrid). Includes receipt data, gas usage, and status.

• Token Crawling: Crawl DEX data for any token with price, volume, liquidity, holder analysis, and risk scoring. Markdown report generation.

• Token Discovery: Browse trending and boosted tokens from DexScreener (scope discover) — featured profiles, recent boosts, top boosts. No API key.

• Live Monitoring: Real-time TUI dashboard with price/volume/candlestick charts, buy/sell gauges, activity logs, and Unicode-rich visualization.

• Address Book: Track multiple addresses (wallets, contracts) across chains with labels, tags, and aggregated balance views including ERC-20, SPL, and TRC-20 token balances.

• Data Export: Export transaction history in JSON or CSV with date range filtering. Chain auto-detection for addresses.

• Market Health: Peg and order book health for stablecoin markets. Fetches level-2 depth from Binance, Biconomy, or DEX liquidity (Ethereum/Solana via DexScreener). Configurable health checks (peg safety, bid/ask ratio, depth thresholds).

• Token Health Suite: Composite command (scope token-health) combining DEX analytics with optional market/order book summary. Venues: binance, biconomy, eth, solana.

• Unified Insights: Auto-detect addresses, transaction hashes, or tokens and run the appropriate analyses (scope insights).

• Compliance & Risk: Risk scoring, transaction pattern detection, taint analysis, and compliance reporting (scope compliance).

• Shell Completion: Tab-completion for bash, zsh, and fish (scope completions <shell>).

• Progress Indicators: Spinners and progress bars for all long-running operations. Non-TTY aware (hidden in pipes).

• Error Remediation: Actionable hints for common errors (invalid address, missing config, network failures, auth issues).

• USD Valuation: Native token prices via DexScreener for all supported chains (ETH, SOL, BNB, MATIC, etc.).

Supported Chains

EVM-Compatible

• Ethereum Mainnet
• Polygon
• Arbitrum
• Optimism
• Base
• BSC (BNB Smart Chain)

Non-EVM

• Solana
• Tron

Quick Start (CLI)

# Analyze an address
scope address 0x742d35Cc6634C0532925a3b844Bc9e7595f1b3c2

# Analyze a transaction
scope tx 0xabc123...

# Auto-detect and analyze any target
scope insights 0xabc123...

# Token DEX data
scope crawl USDC --chain ethereum

# Manage address book
scope address-book add 0x742d... --label "Main Wallet"
scope address-book list

# Export data
scope export --address 0x742d... --output history.json

# Shell tab-completion
scope completions zsh > ~/.zfunc/_scope

Library Usage

The Scope library can be used programmatically in your Rust applications:

use scope::{Config, chains::EthereumClient};

#[tokio::main]
async fn main() -> scope::Result<()> {
    // Load configuration
    let config = Config::load(None)?;
     
    // Create a chain client
    let client = EthereumClient::new(&config.chains)?;
     
    // Query an address balance (with USD valuation)
    let mut balance = client.get_balance("0x742d35Cc6634C0532925a3b844Bc9e7595f1b3c2").await?;
    client.enrich_balance_usd(&mut balance).await;
    println!("Balance: {} (${:.2})", balance.formatted, balance.usd_value.unwrap_or(0.0));
     
    // Look up a transaction
    let tx = client.get_transaction("0xabc123...").await?;
    println!("From: {}, Status: {:?}", tx.from, tx.status);
     
    // Fetch ERC-20 token balances
    let tokens = client.get_erc20_balances("0x742d35Cc6634C0532925a3b844Bc9e7595f1b3c2").await?;
    for token in &tokens {
        println!("{}: {}", token.token.symbol, token.formatted_balance);
    }
     
    Ok(())
}

Configuration

Scope reads configuration from ~/.config/scope/config.yaml:

chains:
  # EVM chains
  ethereum_rpc: "https://mainnet.infura.io/v3/YOUR_KEY"
  bsc_rpc: "https://bsc-dataseed.binance.org"

  # Non-EVM chains
  solana_rpc: "https://api.mainnet-beta.solana.com"
  tron_api: "https://api.trongrid.io"

  api_keys:
    etherscan: "YOUR_ETHERSCAN_KEY"
    polygonscan: "YOUR_POLYGONSCAN_KEY"
    bscscan: "YOUR_BSCSCAN_KEY"
    solscan: "YOUR_SOLSCAN_KEY"
    tronscan: "YOUR_TRONSCAN_KEY"

output:
  format: table  # table, json, csv, markdown
  color: true

address_book:
  data_dir: "~/.local/share/scope"

Error Handling

All fallible operations return Result<T>, which uses ScopeError as the error type. This provides detailed error context for debugging and user-friendly error messages.

use scope::{ScopeError, Result};

fn validate_address(addr: &str) -> Result<()> {
    if !addr.starts_with("0x") || addr.len() != 42 {
        return Err(ScopeError::InvalidAddress(addr.to_string()));
    }
    Ok(())
}

Modules

• chains: Blockchain client implementations (Ethereum/EVM, Solana, Tron, DexScreener)
• cli: Command-line interface definitions (address, tx, crawl, monitor, market, address-book, export)
• config: Configuration management
• market: Peg and order book health for stablecoin markets
• display: Terminal output utilities and markdown report generation
• error: Error types and result aliases
• tokens: Token alias storage for friendly name lookups

Re-exports

pub use config::Config;

pub use error::ConfigError;

pub use error::Result;

pub use error::ScopeError;

Modules

chains

Blockchain client implementations.

cli

Command-line interface definitions.

compliance

Compliance and risk analysis module.

config

Configuration management.

display

Display utilities for terminal output and reports.

error

Error types and result aliases.

market

Market module for peg and order book health analysis.

tokens

Token alias storage for saving token lookups.

web

Web server module for browser-based UI.

Constants

VERSION

Library version string.

Functions

version

Returns the library version.