PolkaGuard

A comprehensive Rust-based CLI tool for analyzing Solidity smart contracts targeting PolkaVM deployment via the pallet-revive module.

Demo : https://youtu.be/k75scr4ofBQ (Old Demo to be Updated with New Features)

PolkaGuard-Council : https://github.com/rtb-12/PolkaGuard-Council

PolkaGuard-VS-Code-Extension : https://github.com/rtb-12/PolkaGuard-Extension

🚀 Key Features

🔍 Zero-Knowledge Exploit Proof Generation 🆕

Private Vulnerability Disclosure: Generate cryptographic proofs of exploit knowledge without revealing report details
Groth16 Proofs: Full implementation using arkworks library with actual trusted setup
Merkle Tree Circuits: Advanced ZK circuits with merkle tree validation for report integrity
Anonymous Security Research: Prove you found an exploit without revealing the attack vector
On-chain Verification: Generate Solidity verifier contracts for blockchain validation

✅ Smart Contract Analysis

PolkaVM Compatibility: Detects EVM-incompatible opcodes (selfdestruct, extcodesize, etc.)
Security Vulnerabilities: Reentrancy detection, unchecked calls, access control validation
Resource Estimation: ref_time, proof_size, storage usage with complexity metrics
Best Practices: SPDX license, pragma directives, function visibility, NatSpec documentation
Syntax Linting: Comprehensive code quality checks with severity levels

💰 Multi-Network Cost Calculations

Polkadot (DOT): 10 decimal places, mainnet pricing
Kusama (KSM): 12 decimal places, canary network
Westend (WND): 12 decimal places, testnet (no USD value)
Rococo (ROC): 12 decimal places, testnet (no USD value)
Local (UNIT): 12 decimal places, development environment

🔧 Advanced CLI Features

Zero-Knowledge Proofs: exploit-report command for generating ZK proofs from markdown reports
Local PolkaVM Fork: run-fork command for local testing with Hardhat integration
Selective Analysis: --checks compatibility,security,resources,best-practices
Network Selection: --network polkadot|kusama|westend|rococo|local
Multiple Output Formats: Text with colors/emojis and structured JSON
Memory Configuration: Custom --stack-size and --heap-size limits
Contract Disassembly: PolkaVM bytecode generation with --overwrite support
Initialization: Project setup with init command

📦 Installation

Prerequisites

Rust 1.70+: Install Rust
Solidity Compiler: npm install -g solc or download from releases
Resolc Compiler: download from releases

Install from Crates.io (Recommended)

# Install directly from crates.io
cargo install polkaguard

# Verify installation
polkaguard --version

📦 Available on crates.io

Build from Source

# Clone the repository
git clone https://github.com/rtb-12/polkaguard.git
cd polkaguard

# Build optimized release
cargo build --release

# Run directly
./target/release/polkaguard --help

# Install globally (optional)
cargo install --path .

🎯 Quick Start

Basic Analysis

# Analyze with default Polkadot network
polkaguard --path ./contracts/MyContract.sol analyze

# Selective checks
polkaguard --path ./contracts/MyContract.sol --checks security,compatibility analyze

# Different network with JSON output
polkaguard --path ./contracts/MyContract.sol --network kusama --format json analyze

🔐 Zero-Knowledge Exploit Proof Generation

# Generate ZK proof from exploit report
polkaguard --path ./contracts exploit-report \
  --report-path ./vulnerability_report.md \
  --contract-address 0x742d35Cc6634C0532925a3b8D9BAcD2d6b7C3756 \
  --exploit-signature "reentrancy_withdrawal_exploit"

# Custom proof parameters with verifier generation
polkaguard --path ./contracts exploit-report \
  --report-path ./detailed_report.md \
  --contract-address 0x1234567890abcdef1234567890abcdef12345678 \
  --exploit-signature "integer_overflow_rewards" \
  --chunk-size 64 \
  --tree-height 16 \
  --generate-verifier \
  --output-dir ./zk_proofs

# JSON output for programmatic use
polkaguard --path ./contracts --format json exploit-report \
  --report-path ./report.md \
  --contract-address 0xabcdef1234567890abcdef1234567890abcdef12 \
  --exploit-signature "access_control_bypass"

🌐 Local PolkaVM Fork Mode

PolkaGuard includes a powerful fork mode feature that creates a local PolkaVM-compatible development environment using Hardhat and the hardhat-polkadot ecosystem.

# Start local PolkaVM fork with automatic dependency management
polkaguard --path ./contracts run-fork --auto-install

# Run fork in background (daemon mode)
polkaguard --path ./contracts run-fork --daemon

# Stop running fork daemon
polkaguard --path ./contracts run-fork --stop

# Custom configuration
polkaguard --path ./contracts run-fork \
  --port 9545 \
  --node-binary ./target/release/substrate-node \
  --adapter-binary ./target/release/revive-eth-rpc \
  --project-dir ./my-polkavm-project

What Fork Mode Does Automatically

🔍 Dependency Detection: Checks for Node.js ≥16, npm, and required binaries
⚙️ Configuration Generation: Creates hardhat.config.js, package.json, and .env files
📦 Package Installation: Installs hardhat-polkadot and related dependencies
🔄 Process Management: Manages Substrate node and ETH-RPC adapter processes
🌐 RPC Endpoint: Provides HTTP RPC at http://localhost:8545 (configurable)
🧪 Test Environment: Pre-funded accounts with standard test mnemonic

Integration Examples

# Development workflow
polkaguard --path ./contracts run-fork --daemon    # Start fork
# Deploy and test contracts using any Ethereum tooling
polkaguard --path ./MyContract.sol analyze          # Analyze compatibility
polkaguard --path ./contracts run-fork --stop      # Clean up

# Use with MetaMask, web3.js, ethers.js
# Network: http://localhost:8545, Chain ID: 31337

📖 Complete Fork Mode Guide - Detailed setup, configuration, and troubleshooting

Network Cost Comparison

# Compare costs across networks
polkaguard --path ./contracts/MyContract.sol --network polkadot analyze
polkaguard --path ./contracts/MyContract.sol --network kusama analyze
polkaguard --path ./contracts/MyContract.sol --network westend analyze

Advanced Usage

# Custom memory limits
polkaguard --path ./contracts/MyContract.sol --stack-size 65536 --heap-size 131072 analyze

# Contract disassembly
polkaguard --path ./contracts/MyContract.sol --overwrite disassemble

# Project initialization
polkaguard --path ./contracts init --config-path ./polkaguard.json

📊 Sample Output

Text Output (Polkadot Network)

Resource Usage Analysis:
------------------------
1. Resource Usage Estimation:
   - Computation Time (ref_time): 36000 units
   - State Proof Size: 1.37 KB bytes
   - Storage Deposit: 0.000000 DOT
   - Storage Usage: 0.00 B bytes

2. Cost Implications:
   Network: Polkadot (DOT)
   - Computation Cost: 0.000360 DOT (3600000 plancks)
   - Proof Size Cost: 0.000140 DOT (1400000 plancks)
   - Storage Deposit: 0.000000 DOT (0 plancks)
   - Total Estimated Cost: 0.000500 DOT (≈ $0.00 USD)

   📊 Cost Calculation Methodology:
     • ref_time: 36000 units × 100 plancks/unit = 3600000 plancks
     • proof_size: 1400 bytes × 1000 plancks/byte = 1400000 plancks
     • storage_deposit: 0 bytes × 1000000000 plancks/byte = 0 plancks
     • 1 DOT = 10^10 plancks

JSON Output Structure

{
  "analysis_results": {
    "contract_name": "Owner",
    "complexity": 11,
    "compatibility_issues": [],
    "security_vulnerabilities": ["Potential reentrancy vulnerability"],
    "resource_usage": {
      "ref_time": 36000,
      "proof_size": 1400,
      "storage_deposit": 0,
      "storage_usage": 0
    },
    "cost_breakdown": {
      "network": {
        "name": "Polkadot",
        "token_symbol": "DOT",
        "token_decimals": 10,
        "ref_time_price_per_unit": 100,
        "proof_size_price_per_byte": 1000,
        "storage_deposit_per_byte": 1000000000,
        "token_price_usd": 7.0
      },
      "total_cost_tokens": 0.0005,
      "total_cost_usd": 0.0035
    },
    "best_practices": []
  }
}

🎮 CLI Commands

Core Commands

# Initialize project with config
polkaguard --path ./contracts init [--config-path ./config.json]

# Analyze contract (supports all check types)
polkaguard --path ./contract.sol analyze

# Generate zero-knowledge exploit proofs
polkaguard --path ./contracts exploit-report --report-path ./report.md

# Run local PolkaVM fork for testing
polkaguard --path ./contracts run-fork [--daemon|--stop]

# List available checks
polkaguard --path ./contracts list-checks

# Disassemble to PolkaVM bytecode
polkaguard --path ./contract.sol disassemble [--overwrite]

# Version information
polkaguard --version --help

Global Options

--path <PATH>              Path to contract or directory
--network <NETWORK>        polkadot|kusama|westend|rococo|local (default: polkadot)
--checks <CHECKS>          compatibility,security,resources,best-practices
--format <FORMAT>          text|json (default: text)
--stack-size <SIZE>        Custom stack size in bytes
--heap-size <SIZE>         Custom heap size in bytes
--overwrite               Overwrite existing .pvm files

🧪 Testing

Run the comprehensive test suite with 21 tests covering all features:

# Make executable and run tests
chmod +x test_polkaguard.sh
./test_polkaguard.sh

Test Coverage

Tests 1-2: Project initialization
Tests 3-11: Contract analysis with different networks and options
Tests 12-15: Check listing and help functionality
Tests 16-19: Contract disassembly and bytecode generation
Tests 20: Version information
Test 21: Network cost comparison across all 5 networks

📚 Documentation

📖 Complete Documentation Hub - Comprehensive guides and references

Quick Links

Cost Calculation Guide: Detailed DOT/KSM cost methodology
Configuration Reference: Complete configuration options and examples
Network Guide: Multi-network support and cost comparisons
Development Guide: Architecture, contributing, and extending PolkaGuard
ZK Exploit Proofs: Zero-knowledge vulnerability disclosure and anonymous reporting

Key Resources

21 Automated Tests: Run ./test_polkaguard.sh for comprehensive validation
5 Network Support: Polkadot, Kusama, Westend, Rococo, Local with accurate cost calculations
Production Ready: Extensive testing, robust error handling, precise cost calculations

🚀 Production Ready

PolkaGuard has been extensively tested with:

✅ 21 automated tests covering all functionality
✅ 5 network configurations (Polkadot, Kusama, Westend, Rococo, Local)
✅ Accurate DOT/KSM cost calculations with plancks precision
✅ Comprehensive security analysis with reentrancy detection
✅ PolkaVM compatibility checks for pallet-revive deployment

⚠️ Development Notice: Some advanced features are still in active development. If you encounter any errors or unexpected behavior, please raise an issue with detailed information about your use case and the error encountered. Your feedback helps improve PolkaGuard!

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Polkadot team for PolkaVM and pallet-revive
Solidity team for the compiler
Rust and Cargo communities for excellent tooling

Name		Name	Last commit message	Last commit date
Latest commit History 48 Commits
assets		assets
docs		docs
src		src
.gitignore		.gitignore
Cargo.toml		Cargo.toml
LICENSE		LICENSE
MyContract.sol:MyContract.pvm		MyContract.sol:MyContract.pvm
README.md		README.md
build.rs		build.rs
polkaguard.json		polkaguard.json
test_exploit_report.md		test_exploit_report.md
test_exploit_report_generation.sh		test_exploit_report_generation.sh
test_polkaguard.sh		test_polkaguard.sh
test_polkaguard_fork.sh		test_polkaguard_fork.sh

License

rtb-12/PolkaGuard

Folders and files

Latest commit

History

Repository files navigation