USDC decimal ambiguity: 18 decimals as native gas token vs 6 decimals as ERC-20 — undocumented, causes silent value bugs

[osr21]

Summary

USDC on Arc has two distinct decimal representations depending on context:

Context	Decimals	Example: 1 USDC
Native gas token (used for gas fees)	18	1000000000000000000
ERC-20 transfer / contract interaction	6	1000000

This distinction is not documented anywhere in the Arc Network developer resources. Developers who look up the USDC contract decimals correctly get 6, but gas fee calculations from the node return values in 18-decimal format. The mismatch causes silent incorrect value display if not handled explicitly.

Impact

Developers building on Arc will hit this without any error message — values will just be wrong by a factor of 10^12. Specific scenarios:

1. Gas fee display — reading gasPrice * gasUsed from a receipt gives an 18-decimal value; displaying it as USDC without converting produces values like "0.000000000001 USDC" instead of "0.01 USDC"
2. Balance display — eth_getBalance returns the native USDC balance in 18 decimals while balanceOf on the ERC-20 contract returns 6 decimals for the same token, same address
3. Transfer amount validation — a developer testing whether a gas fee exceeds a transfer amount will compare two values in different scales and get incorrect results

Suggested Fix

Add a dedicated section in the developer documentation that explicitly states:

• Arc's native gas token is USDC with 18 decimals (used in gasPrice, value, eth_getBalance, receipts)
• The USDC ERC-20 contract (0x3600000000000000000000000000000000000000) uses 6 decimals for balanceOf, transfer, and transferFrom
• When displaying gas costs to users, convert from 18-decimal native to 6-decimal display using nativeAmount / 10^12

Context

Discovered while building Arc Pay. We document this in our internal replit.md as a known gotcha: "Always use 6 decimals for application-level transfers."

[osr21]

Additional context: how this bites developers in practice

The decimal ambiguity most commonly surfaces in two scenarios:

1. Displaying gas cost in USDC terms

eth_gasPrice returns values in 18-decimal wei units (e.g., 1000000000 = 1 Gwei = 0.000000001 USDC-gas-units). Converting this to display in USDC requires dividing by 10^18, not 10^6:

const feeData = await provider.getFeeData();
// ❌ Wrong: divides by 10^6 → shows 10^12x too large
const displayPrice = parseFloat(ethers.formatUnits(feeData.gasPrice!, 6));

// ✅ Correct: divides by 10^18 (wei → ETH-equivalent units)
const displayPrice = parseFloat(ethers.formatUnits(feeData.gasPrice!, 18));

2. USDC balanceOf() vs MetaMask balance display

MetaMask shows the native balance (18-decimal) as the wallet balance. The ERC-20 balanceOf() for USDC returns 6-decimal values. They represent the same underlying token but in different units:

Source	Call	Decimals	Example output for 1 USDC
MetaMask native balance	eth_getBalance	18	1000000000000000000
ERC-20 balance	usdc.balanceOf(address)	6	1000000

Recommendation: always use usdc.balanceOf() for token-related UI, never eth_getBalance.