token-integration-safety

# Token Integration Safety ## Always Use SafeERC20 This is the single most important rule. Never call `transfer`, `transferFrom`, or `approve` directly. ```solidity import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol"; import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol"; contract Vault { using SafeERC20 for IERC20; function deposit(IERC20 token, uint256 amount) external { token.safeTransferFrom(msg.sender, address(this), amount); } function withdraw(IERC20 token, uint256 amount) external { token.safeTransfer(msg.sender, amount); } function approve(IERC20 token, address spender, uint256 amount) external { token.forceApprove(spender, amount); } } ``` ## USDT — No Return Value USDT's `transfer()` and `transferFrom()` don't return a `bool`. Direct calls via the `IERC20` interface will revert because Solidity expects return data. ```solidity // BROKEN with USDT: IERC20(usdt).transfer(to, amount); // reverts — no return data // WORKS with USDT: IERC20(usdt).safeTransfer(to, amount); // SafeERC20 handles missing return ``` USDT also requires approval to be set to 0 before changing to a non-zero value: ```solidity // BROKEN with USDT: IERC20(usdt).approve(spender, newAmount); // reverts if current approval != 0 // WORKS with USDT: IERC20(usdt).forceApprove(spender, newAmount); // sets to 0 first, then newAmount ``` ## USDC — 6 Decimals and Blacklist ```solidity // USDC uses 6 decimals, not 18 // 1 USDC = 1_000_000 (1e6), NOT 1e18 // VULNERABLE: hardcoded 18 decimals uint256 usdcAmount = ethAmount * ethPrice / 1e18; // wrong! // SAFE: use actual decimals uint8 decimals = IERC20Metadata(address(usdc)).decimals(); // returns 6 uint256 usdcAmount = ethAmount * ethPrice / (10 ** (18 - decimals + 18)); ``` USDC has a blacklist. Blacklisted addresses cannot send or receive USDC. Your protocol must handle transfer failures gracefully. ```solidity // If a blacklisted user has funds in your vault, they cannot withdraw // Consider: allow withdrawal to a different address (with proper auth) function withdrawTo(address token, address recipient, uint256 amount) external { if (balances[msg.sender] < amount) revert InsufficientBalance(); balances[msg.sender] -= amount; IERC20(token).safeTransfer(recipient, amount); } ``` ## Fee-on-Transfer Tokens Some tokens deduct a fee on every transfer. The received amount is less than the sent amount. ```solidity // VULNERABLE: assumes received amount equals sent amount function deposit(IERC20 token, uint256 amount) external { token.safeTransferFrom(msg.sender, address(this), amount); balances[msg.sender] += amount; // WRONG: received less than amount } // SAFE: measure actual received amount function deposit(IERC20 token, uint256 amount) external { uint256 balanceBefore = token.balanceOf(address(this)); token.safeTransferFrom(msg.sender, address(this), amount); uint256 received = token.balanceOf(address(this)) - balanceBefore; balances[msg.sender] += received; emit Deposited(msg.sender, address(token), received); } ``` **Decision**: Many protocols explicitly reject fee-on-transfer tokens for simplicity. Document this clearly if so. ## Rebasing Tokens (stETH, aTokens) Rebasing tokens change balances automatically. `balanceOf()` returns different values over time without transfers. ```solidity // PROBLEM: stored balance becomes stale mapping(address => uint256) public balances; function deposit(uint256 amount) external { stETH.safeTransferFrom(msg.sender, address(this), amount); balances[msg.sender] += amount; // balance will change via rebasing } // SOLUTION 1: Use the wrapped, non-rebasing version // stETH → wstETH (wrapped stETH, non-rebasing) // aUSDC → use share-based accounting internally // SOLUTION 2: Share-based accounting (ERC-4626 pattern) function deposit(uint256 assets) external returns (uint256 shares) { shares = convertToShares(assets); _mint(msg.sender, shares); stETH.safeTransferFrom(msg.sender, address(this), assets); } ``` ## ERC-777 Callbacks ERC-777 tokens call `tokensToSend()` on the sender and `tokensReceived()` on the recipient. This creates reentrancy vectors. ```solidity // Risk: any transfer of an ERC-777 token triggers a callback // If your contract receives an ERC-777 token, tokensReceived() is called // An attacker can exploit this callback for reentrancy // Defense: ReentrancyGuard on all functions that transfer tokens function deposit(IERC20 token, uint256 amount) external nonReentrant { token.safeTransferFrom(msg.sender, address(this), amount); _updateBalance(msg.sender, amount); } ``` ## Tokens with Blocklists USDC, USDT, and others can freeze/blocklist addresses. Your protocol should handle this. ```solidity // Consider: what happens if a user gets blocklisted after depositing? // - They can't receive tokens back // - Their position may become unliquidatable // - Protocol accounting may break // Mitigation: allow withdrawal to alternative addresses // Mitigation: allow admin rescue for stuck funds (with timelock) ``` ## Pausable Tokens Some tokens (USDC, USDT) can be paused globally by their admin, blocking all transfers. ```solidity // If the underlying token is paused: // - deposits fail // - withdrawals fail // - liquidations fail (potentially dangerous) // Mitigation: emergency mode that accounts for paused underlying // Mitigation: alternative settlement paths ``` ## Permit2 Integration Permit2 provides a universal approval mechanism for all ERC-20 tokens (even those without EIP-2612). ```solidity import {IPermit2} from "permit2/interfaces/IPermit2.sol"; contract VaultWithPermit2 { IPermit2 public immutable PERMIT2; function depositWithPermit2( address token, uint256 amount, uint256 nonce, uint256 deadline, bytes calldata signature ) external { PERMIT2.permitTransferFrom( IPermit2.PermitTransferFrom({ permitted: IPermit2.TokenPermissions({token: token, amount: amount}), nonce: nonce, deadline: deadline }), IPermit2.SignatureTransferDetails({ to: address(this), requestedAmount: amount }), msg.sender, signature ); _recordDeposit(msg.sender, token, amount); } } ``` ## Token Quirks Reference | Token | Decimals | Return Bool | Blocklist | Pausable | Fee-on-Transfer | Rebasing | |-------|----------|-------------|-----------|----------|-----------------|----------| | USDT | 6 | No | Yes | Yes | No | No | | USDC | 6 | Yes | Yes | Yes | No | No | | DAI | 18 | Yes | No | No | No | No | | WETH | 18 | Yes | No | No | No | No | | WBTC | 8 | Yes | No | No | No | No | | stETH | 18 | Yes | No | No | No | Yes | | PAXG | 18 | Yes | Yes | Yes | Yes (0.02%) | No | ## Token Integration Checklist - [ ] SafeERC20 used for all token operations - [ ] `forceApprove` used instead of `approve` (USDT compatibility) - [ ] No assumption of 18 decimals — query `decimals()` - [ ] Fee-on-transfer handled (measure balance diff) or explicitly rejected - [ ] Rebasing tokens: use wrapped version or share-based accounting - [ ] ERC-777 callbacks: ReentrancyGuard on all token-handling functions - [ ] Blocklist handling: alternative withdrawal paths - [ ] Pausable token failure paths considered - [ ] Permit2 supported for gasless approvals - [ ] Token behavior documented in protocol docs