FunC Smart Contract Analyzer

Static analyzer for TON blockchain FunC smart contracts. Provides comprehensive analysis of call graphs, constants, and dependencies with LLM-optimized JSON output.

Why This Tool Matters

The Problem: Modern FunC contracts use complex include hierarchies and modular architecture. Traditional tools miss critical dependencies or incorrectly identify functional modules as deployable contracts.

Real Example: SwapCoffee's pool contracts

# This file looks like a contract but only contains includes:
pool_constant_product.fc:
  #include "pool/amm/constant_product.fc"
  #include "pool/include/jetton_based.fc"  
  #include "pool/include/recv_internal.fc"

# Without proper analysis, you'd miss jetton_based.fc entirely

Our Solution: Reverse thinking algorithm correctly identifies pool_constant_product.fc as the deployable contract while including all its dependencies like jetton_based.fc and compare_fractions().

Quick Start

# Analyze any TON contract instantly
npx func-contract-analyzer@latest path/to/contract.fc

# Generate JSON for LLM analysis
npx func-contract-analyzer@latest contract.fc --mode json -o analysis.json

# Analyze entire project with filtering
npx func-contract-analyzer@latest project/ --exclude "test/**,mock/**"

Real-World Impact

SwapCoffee Analysis

Before: Missed jetton_based.fc module containing critical compare_fractions() function
After: Complete dependency analysis including all 10 pool contracts

Torch DEX Analysis

Result: 9 true entry points correctly identified (pools, vaults, factory)
Value: No false positives from functional modules

Complex Include Chains

pool_constant_product.fc → jetton_based.fc → math.fc → compare_fractions()

Complete dependency tree captured in single analysis

Core Features

🎯 True Entry Point Detection

Uses reverse thinking algorithm to distinguish deployable contracts from library modules:

• ✅ pool_constant_product.fc → True entry point (deployable)
• ❌ pool/include/recv_internal.fc → Functional module (library)

📊 Complete Call Graph Analysis

Visual tree representation of function calls:

recv_internal
├── deposit_liquidity
│   ├── compare_fractions
│   └── add_liquidity_impl
└── swap_internal
    └── perform_swap

🔍 Smart Constant Resolution

Resolves complex constant expressions and dependencies:

const int base_fee = 1000;
const int swap_fee = base_fee * 3;  // Correctly evaluates to 3000

📋 LLM-Optimized Output

JSON format designed for AI vulnerability analysis with complete source code and metadata.

Output Modes

Console Mode (Default)

func-analyzer contract.fc

Beautiful formatted output for development and debugging.

JSON Mode

func-analyzer contract.fc --mode json -o analysis.json

Complete structured data including:

• All functions with source code
• Complete call graph with locations
• Resolved constants with values
• File dependency tree

Installation

NPX (Recommended)

npx func-contract-analyzer@latest path/to/contract.fc

Global Installation

npm install -g func-contract-analyzer
func-analyzer path/to/contract.fc

From Source

git clone https://github.com/alan890104/func-analyzer.git
cd func-analyzer
bun install
bun run src/main.ts contract.fc

CLI Reference

Usage: func-analyzer [options] <contract-path>

Arguments:
  contract-path         Path to FunC contract file or directory

Options:
  --mode <mode>         console | json (default: console)
  --exclude <patterns>  Comma-separated gitignore-style patterns
  --max-depth <n>       Maximum call tree depth  
  -o, --output <file>   Output file (required for JSON mode)
  --wasm-path <path>    Custom tree-sitter-func.wasm path
  -q, --quiet           Suppress output except results
  -h, --help            Show help

Examples:
  func-analyzer contract.fc
  func-analyzer project/ --exclude "test/**,*mock*"
  func-analyzer contract.fc --mode json -o analysis.json

Architecture

Built on Clean Architecture principles:

• Interfaces: TypeScript contracts defining behavior
• Implementations: Business logic with dependency injection
• Universal Analysis: No hardcoded patterns, works with any TON project
• Tree-sitter Parsing: Robust AST-based analysis, no regex

Key Components

src/
├── implementations/
│   ├── FileManager.ts           # Reverse thinking algorithm
│   ├── ContractAnalyzer.ts      # Main analysis coordinator  
│   ├── CallGraphAnalyzer.ts     # Function relationships
│   └── ConstantsResolver.ts     # Expression evaluation
├── interfaces/                  # Type definitions
└── grammer/                     # Tree-sitter FunC grammar

Development

Requirements

• Bun runtime (required for performance)
• TypeScript 5.0+

Commands

bun install                      # Install dependencies
bun run src/main.ts contract.fc  # Development mode
bun test                         # Run 150+ tests
bun run build:main               # Production build

Testing

All tests use real tree-sitter parsing with actual FunC contracts:

• 150 tests covering all major TON projects
• Real filesystem testing with dependency injection
• No mocks - validates against actual contract parsing

Recent Updates

v0.8.0 - Reverse Thinking Algorithm

• ✅ Fixed duplicate analysis: Functional modules no longer appear as contracts
• ✅ True entry point detection: Correctly identifies deployable vs library files
• ✅ SwapCoffee support: Now properly analyzes complex modular contracts
• ✅ 150 tests pass: Full backward compatibility maintained

Contributing

See CLAUDE.md for development guidelines. The project follows Clean Architecture with dependency injection and extensive test coverage.

License

MIT License - see LICENSE file for details.

Built for security researchers and TON developers who need comprehensive contract analysis.