evm-token-decimals

This skill is designed to eliminate silent and often costly errors caused by incorrect handling of ERC-20 token decimals across EVM-compatible blockchains. In many DeFi and blockchain applications, developers mistakenly assume a fixed decimal precision for tokens, which can lead to balances, pricing, and portfolio valuations being off by orders of magnitude without any runtime errors. This issue becomes even more complex in cross-chain environments where the same token symbol may have different decimal configurations depending on the chain or bridged representation.

The skill focuses on enforcing safe and accurate decimal handling by requiring runtime retrieval of the `decimals()` value directly from the token contract. It supports caching strategies keyed by `(chain_id, token_address)` to reduce redundant on-chain calls while maintaining correctness. It also encourages defensive programming practices such as fallback handling when `decimals()` is unavailable, and the use of precise numeric types like `Decimal` or `BigInt` instead of floating-point arithmetic. Additionally, it provides normalization strategies for converting token amounts into a consistent 18-decimal WAD format, making internal accounting and comparisons reliable across heterogeneous assets and chains.

This skill is primarily intended for developers building DeFi protocols, trading bots, portfolio trackers, analytics dashboards, or any system that aggregates or compares token balances across multiple environments. It is especially useful in cross-chain applications and systems dealing with bridged assets, where decimal inconsistencies are common. By standardizing decimal handling practices, it helps ensure correctness in financial calculations and prevents subtle bugs that could otherwise lead to significant valuation errors.