token-integration-analyzer

What this skill does

# Token Integration Analyzer

## Purpose

Systematically analyzes the codebase for token-related security concerns using Trail of Bits' token integration checklist:

1. **Token Implementations**: Analyze if your token follows ERC20/ERC721 standards or has non-standard behavior
2. **Token Integrations**: Analyze how your protocol handles arbitrary tokens, including weird/non-standard tokens
3. **On-chain Analysis**: Query deployed contracts for scarcity, distribution, and configuration
4. **Security Assessment**: Identify risks from 20+ known weird token patterns

**Framework**: Building Secure Contracts - Token Integration Checklist + Weird ERC20 Database

---

## How This Works

### Phase 1: Context Discovery
Determines analysis context:
- **Token implementation**: Are you building a token contract?
- **Token integration**: Does your protocol interact with external tokens?
- **Platform**: Ethereum, other EVM chains, or different platform?
- **Token types**: ERC20, ERC721, or both?

### Phase 2: Slither Analysis (if Solidity)
For Solidity projects, I'll help run:
- `slither-check-erc` - ERC conformity checks
- `slither --print human-summary` - Complexity and upgrade analysis
- `slither --print contract-summary` - Function analysis
- `slither-prop` - Property generation for testing

### Phase 3: Code Analysis
Analyzes:
- Contract composition and complexity
- Owner privileges and centralization risks
- ERC20/ERC721 conformity
- Known weird token patterns
- Integration safety patterns

### Phase 4: On-chain Analysis (if deployed)
If you provide a contract address, I'll query:
- Token scarcity and distribution
- Total supply and holder concentration
- Exchange listings
- On-chain configuration

### Phase 5: Risk Assessment
Provides:
- Identified vulnerabilities
- Non-standard behaviors
- Integration risks
- Prioritized recommendations

---

## Assessment Categories

I check 10 comprehensive categories covering all aspects of token security. For detailed criteria, patterns, and checklists, see [ASSESSMENT_CATEGORIES.md](resources/ASSESSMENT_CATEGORIES.md).

### Quick Reference:

1. **General Considerations** - Security reviews, team transparency, security contacts
2. **Contract Composition** - Complexity analysis, SafeMath usage, function count, entry points
3. **Owner Privileges** - Upgradeability, minting, pausability, blacklisting, team accountability
4. **ERC20 Conformity** - Return values, metadata, decimals, race conditions, Slither checks
5. **ERC20 Extension Risks** - External calls/hooks, transfer fees, rebasing/yield-bearing tokens
6. **Token Scarcity Analysis** - Supply distribution, holder concentration, exchange distribution, flash loan/mint risks
7. **Weird ERC20 Patterns** (24 patterns including):
   - Reentrant calls (ERC777 hooks)
   - Missing return values (USDT, BNB, OMG)
   - Fee on transfer (STA, PAXG)
   - Balance modifications outside transfers (Ampleforth, Compound)
   - Upgradable tokens (USDC, USDT)
   - Flash mintable (DAI)
   - Blocklists (USDC, USDT)
   - Pausable tokens (BNB, ZIL)
   - Approval race protections (USDT, KNC)
   - Revert on approval/transfer to zero address
   - Revert on zero value approvals/transfers
   - Multiple token addresses
   - Low decimals (USDC: 6, Gemini: 2)
   - High decimals (YAM-V2: 24)
   - transferFrom with src == msg.sender
   - Non-string metadata (MKR)
   - No revert on failure (ZRX, EURS)
   - Revert on large approvals (UNI, COMP)
   - Code injection via token name
   - Unusual permit function (DAI, RAI, GLM)
   - Transfer less than amount (cUSDCv3)
   - ERC-20 native currency representation (Celo, Polygon, zkSync)
   - [And more...](resources/ASSESSMENT_CATEGORIES.md#7-weird-erc20-patterns)
8. **Token Integration Safety** - Safe transfer patterns, balance verification, allowlists, wrappers, defensive patterns
9. **ERC721 Conformity** - Transfer to 0x0, safeTransferFrom, metadata, ownerOf, approval clearing, token ID immutability
10. **ERC721 Common Risks** - onERC721Received reentrancy, safe minting, burning approval clearing

---

## Example Output

When analysis is complete, you'll receive a comprehensive report structured as follows:

```
=== TOKEN INTEGRATION ANALYSIS REPORT ===

Project: MultiToken DEX
Token Analyzed: Custom Reward Token + Integration Safety
Platform: Solidity 0.8.20
Analysis Date: March 15, 2024

---

## EXECUTIVE SUMMARY

Token Type: ERC20 Implementation + Protocol Integrating External Tokens
Overall Risk Level: MEDIUM
Critical Issues: 2
High Issues: 3
Medium Issues: 4

**Top Concerns:**
⚠ Fee-on-transfer tokens not handled correctly
⚠ No validation for missing return values (USDT compatibility)
⚠ Owner can mint unlimited tokens without cap

**Recommendation:** Address critical/high issues before mainnet launch.

---

## 1. GENERAL CONSIDERATIONS

✓ Contract audited by CertiK (June 2023)
✓ Team contactable via [email protected]
✗ No security mailing list for critical announcements

**Risk:** Users won't be notified of critical issues
**Action:** Set up [email protected] mailing list

---

## 2. CONTRACT COMPOSITION

### Complexity Analysis

**Slither human-summary Results:**
- 456 lines of code
- Cyclomatic complexity: Average 6, Max 14 (transferWithFee())
- 12 functions, 8 state variables
- Inheritance depth: 3 (moderate)

✓ Contract complexity is reasonable
⚠ transferWithFee() complexity high (14) - consider splitting

### SafeMath Usage

✓ Using Solidity 0.8.20 (built-in overflow protection)
✓ No unchecked blocks found
✓ All arithmetic operations protected

### Non-Token Functions

**Functions Beyond ERC20:**
- setFeeCollector() - Admin function ✓
- setTransferFee() - Admin function ✓
- withdrawFees() - Admin function ✓
- pause()/unpause() - Emergency functions ✓

⚠ 4 non-token functions (acceptable but adds complexity)

### Address Entry Points

✓ Single contract address
✓ No proxy with multiple entry points
✓ No token migration creating address confusion

**Status:** PASS

---

## 3. OWNER PRIVILEGES

### Upgradeability

⚠ Contract uses TransparentUpgradeableProxy
**Risk:** Owner can change contract logic at any time

**Current Implementation:**
- ProxyAdmin: 0x1234... (2/3 multisig) ✓
- Timelock: None ✗

**Recommendation:** Add 48-hour timelock to all upgrades

### Minting Capabilities

❌ CRITICAL: Unlimited minting
File: contracts/RewardToken.sol:89
```solidity
function mint(address to, uint256 amount) external onlyOwner {
    _mint(to, amount);  // No cap!
}
```

**Risk:** Owner can inflate supply arbitrarily
**Fix:** Add maximum supply cap or rate-limited minting

### Pausability

✓ Pausable pattern implemented (OpenZeppelin)
✓ Only owner can pause
⚠ Paused state affects all transfers (including existing holders)

**Risk:** Owner can trap all user funds
**Mitigation:** Use multi-sig for pause function (already implemented ✓)

### Blacklisting

✗ No blacklist functionality
**Assessment:** Good - no centralized censorship risk

### Team Transparency

✓ Team members public (team.md)
✓ Company registered in Switzerland
✓ Accountable and contactable

**Status:** ACCEPTABLE

---

## 4. ERC20 CONFORMITY

### Slither-check-erc Results

Command: slither-check-erc . RewardToken --erc erc20

✓ transfer returns bool
✓ transferFrom returns bool
✓ name, decimals, symbol present
✓ decimals returns uint8 (value: 18)
✓ Race condition mitigated (increaseAllowance/decreaseAllowance)

**Status:** FULLY COMPLIANT

### slither-prop Test Results

Command: slither-prop . --contract RewardToken

**Generated 12 properties, all passed:**
✓ Transfer doesn't change total supply
✓ Allowance correctly updates
✓ Balance updates match transfer amounts
✓ No balance manipulation possible
[... 8 more properties ...]

**Echidna fuzzing:** 50,000 runs, no violations ✓

**Status:** EXCELLENT

---

## 5. WEIRD TOKEN PATTERN ANALYSIS

### Integration Safety Check

**Your Protocol Integrates 5 External Tokens:**
1. USDT (0xdac17f9...)
2. USDC (0xa0b86991...)
3. DAI (0x6b175474...)
4. WETH (