first commit

docs/money/finance/cryptocurrency/src/tokens/token-data.md

@@ -0,0 +1,64 @@
+# token-data
+
+## Purpose
+
+Provides the `COMMON_TOKENS` constant: a curated list of eight well-known ERC-20 tokens on Ethereum mainnet — USDT, USDC, DAI, WBTC, WETH, LINK, UNI, MATIC. The list is used as the default seed for `TokenRegistry` when constructed with `preload = true` (the default). Consumers that want a richer registry can construct `new TokenRegistry(false)` and call `addToken` themselves, or build on top of `COMMON_TOKENS` by spreading the array.
+
+This module exists as a static export so consumers can dead-code-eliminate it when they don't need a token registry; the entries here are byte-identical to upstream so any consumer relying on the addresses or decimals keeps working.
+
+## Features
+
+- Eight well-known mainnet ERC-20s: USDT, USDC, DAI, WBTC, WETH, LINK, UNI, MATIC.
+- Every entry carries `address`, `symbol`, `decimals`, `chainId` (always `"ethereum"`), and `name`.
+- Stablecoins use 6 decimals (USDT, USDC), WBTC uses 8, the rest use 18.
+- Pure data export — no runtime initialisation, no side effects.
+- Mutable array — consumers can spread it to build their own seeded registries.
+
+## Usage: Basic
+
+```ts
+import { COMMON_TOKENS } from "@suaveplan/cryptocurrency";
+
+const usdt = COMMON_TOKENS.find((t) => t.symbol === "USDT");
+// { address: "0xdAC17F958D2ee523a2206206994597C13D831ec7", symbol: "USDT", decimals: 6, ... }
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    COMMON_TOKENS,
+    type TokenInfo,
+    TokenRegistry,
+} from "@suaveplan/cryptocurrency";
+
+const myTokens: TokenInfo[] = [
+    ...COMMON_TOKENS,
+    {
+        address: "0x111111111117dC0aa78b770fA6A738034120C302",
+        symbol: "1INCH",
+        decimals: 18,
+        chainId: "ethereum",
+        name: "1inch",
+    },
+];
+
+const registry = new TokenRegistry(false);
+for (const token of myTokens) registry.addToken(token);
+
+const oneInch = registry.getToken("ethereum", "0x111111111117dC0aa78b770fA6A738034120C302");
+```
+
+## API Reference
+
+| Export | Type | Notes |
+|---|---|---|
+| `COMMON_TOKENS` | `TokenInfo[]` | 8 entries; mainnet ERC-20s only |
+
+## Implementation Notes
+
+- The array is `const`-bound but **not** `as const` — entries are mutable so callers can spread-merge their own overrides without TypeScript widening complaints.
+- All addresses are EIP-55-checksummed (the canonical upstream representation) — `TokenRegistry.getToken` normalises lookups to lowercase, so consumers can pass any casing.
+- Adding a new token to `COMMON_TOKENS` requires no other code changes — the token is automatically picked up by `TokenRegistry`'s default preload.
+- The list is intentionally short. A more comprehensive registry (Uniswap token list, CoinGecko export) belongs in a downstream `@suaveplan/cryptocurrency-tokens` package; keeping the core curated avoids shipping a 200KB JSON blob in the universal package.
+- All entries are on `ethereum` chainId; multi-chain entries (USDC on Polygon, USDT on BSC, etc.) are deliberately out of scope for the core list — they belong to chain-specific catalogues.