Agent skill

ton-scanner

Use when the user wants to audit TON smart contracts for security vulnerabilities, scan FunC or Tact contracts for message chain replay, bounce handling, or gas issues, review TON DeFi protocols for actor-model concurrency flaws, or analyze asynchronous message passing security.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/ton-scanner

SKILL.md

TON Scanner Skill

Purpose

Analyze TON (The Open Network) smart contracts written in FunC or Tact for security vulnerabilities. TON's actor-model architecture, asynchronous message passing, and TVM (TON Virtual Machine) create a fundamentally different security model from EVM-based chains.

TON Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                         TON Network                             │
│                                                                 │
│  ┌──────────────┐    async messages     ┌──────────────┐        │
│  │  Contract A   │ ──────────────────► │  Contract B   │        │
│  │  (Shard 1)    │ ◄────────────────── │  (Shard 2)    │        │
│  │               │    bounce/reply      │               │        │
│  │  FunC / Tact  │                      │  FunC / Tact  │        │
│  └──────┬───────┘                      └──────┬───────┘        │
│         │                                      │                │
│         ▼                                      ▼                │
│  ┌──────────────┐                      ┌──────────────┐        │
│  │    Storage    │                      │    Storage    │        │
│  │  (Cells/BoC)  │                      │  (Cells/BoC)  │        │
│  │  pays rent    │                      │  pays rent    │        │
│  └──────────────┘                      └──────────────┘        │
└─────────────────────────────────────────────────────────────────┘

Key Differences from EVM

Aspect EVM (Solidity) TON (FunC/Tact)
Execution Model Synchronous, atomic Asynchronous, actor-based messages
Cross-Contract Calls Atomic within transaction Non-atomic, separate transactions
Storage Cost One-time gas Ongoing rent (storage fees)
Data Structure Key-value mapping Cell trees (max 1023 bits, 4 refs)
Reentrancy Within same transaction Not possible (async messages)
Failure Handling Revert entire tx Bounce messages, partial failure
Languages Solidity, Vyper FunC (low-level), Tact (high-level)
Address Format 20-byte, single chain Workchain ID + 256-bit hash

Languages

Language Level Usage Security Characteristics
FunC Low-level Core contracts, jettons, NFTs Direct TVM access, manual cell serialization, easy to misuse
Tact High-level Modern contracts Type-safe, auto-serialization, safer defaults but newer
Fift Assembly-level Deployment scripts Direct TVM opcodes, used for contract deployment

Detection Capabilities

Critical Vulnerabilities

  • Message chain gas exhaustion: Multi-hop messages run out of gas before completing all operations
  • Missing bounce handling: Bounced messages not processed → permanent fund loss
  • Unbounded storage growth: Attacker-controlled data storage drains contract balance via rent
  • Missing replay protection: Same message processed multiple times

High Vulnerabilities

  • Carry-value attacks: Incoming message value used to fund outgoing messages without accounting
  • Cell overflow/underflow: Exceeding 1023-bit or 4-reference cell limits during serialization
  • Workchain ID confusion: Not validating workchain in address leads to cross-chain issues
  • Incorrect message mode flags: Wrong send mode causes unintended gas forwarding or balance drain

Medium Vulnerabilities

  • Storage fee drain: Contract balance slowly depleted by rent payments on stored data
  • Sharded message ordering: Assuming message order across shards causes race conditions
  • Tick-tock contract abuse: Automatic execution contracts with expensive operations
  • Missing accept_message() in external handlers: External messages silently dropped without gas acceptance

Real-World TON Incidents

Incident Vulnerability Impact
Early Jetton implementations Missing bounce handling Token loss on failed transfers
DNS auction contracts Gas exhaustion in multi-message chains Auctions stuck irrecoverably
Various NFT marketplaces Replay attacks (no seqno) Duplicate sales/purchases
Storage-based attacks Unbounded storage growth Contract balance drained by rent

Resources

  • TON Patterns — Full vulnerability patterns with FunC/Tact code
  • TON Audit Workflow — Step-by-step audit methodology

Related Scanners

  • Solidity Scanner — EVM comparison for cross-chain auditors
  • Solana Scanner — Another non-EVM async model for comparison

Error Code Reference

Common TON/FunC error codes encountered during audits. TON uses numeric exit codes in throw() / throw_if() / throw_unless() statements.

Standard TVM Exit Codes

Exit Code Name Meaning
0 Success Normal successful execution
2 Stack underflow Too few arguments on the stack — FunC function signature mismatch
3 Stack overflow Stack exceeded limits
4 Integer overflow Integer does not fit into 257-bit signed range
5 Integer out of range Value outside expected range for operation
6 Invalid opcode Unknown TVM instruction — possible code corruption
7 Type check error Wrong type on stack — e.g., expected cell, got integer
8 Cell overflow Cell data exceeds 1023 bits or 4 references
9 Cell underflow Attempted to read more data than cell contains
10 Dictionary error Invalid dictionary (hashmap) operation
11 Unknown error General "most common" error
13 Out of gas Computation exceeded gas limit
-14 Out of gas (credit) Gas credit depleted before accept_message()

Common Application Exit Codes (Convention)

Exit Code Range Convention Meaning
30-39 Auth errors Unauthorized sender (throw_unless(33, ...))
40-49 State errors Invalid contract state for operation
50-59 Balance errors Insufficient balance for operation
60-69 Validation errors Invalid input parameters
100-199 Jetton Standard Jetton (token) specific errors
200-299 NFT Standard NFT specific errors
300-399 DEX errors Liquidity pool / AMM errors
400+ Application-specific Custom application logic errors

Jetton Standard Error Codes

Exit Code Meaning
73 Insufficient jetton balance for transfer
74 Not enough TON for gas fees attached to transfer
75 Invalid sender — not the jetton wallet owner
76 Discovery: unknown jetton wallet

Troubleshooting

Issue Likely Cause Solution
Bounce handler vulnerabilities missed Scanner doesn't analyze bounced<> message handlers Audit all recv_internal branches that handle bounced messages — check for state rollback correctness
Message chain replay not detected Scanner analyzes single messages, not chains Trace full message chains: initial message → internal messages → bounces; check seqno/query_id uniqueness
Gas estimation issues not flagged Scanner doesn't model TON gas economics Flag messages without accept_message() or with insufficient gas forwarding via msg_value
Actor model concurrency bugs missed Scanner uses synchronous mental model Map all async message flows; check for time-of-check/time-of-use between separate messages
FunC vs Tact pattern mismatch Scanner patterns written for FunC, code is in Tact Verify Tact's auto-generated FunC output; Tact handles some safety checks automatically
Storage fee drain not caught Scanner doesn't model TON storage costs Check that contracts handle storage_fee deductions; verify minimum balance maintenance

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results