feat(payments): add USDC payment verification for Hedera

[devwhodevs]

Summary

Adds production-ready USDC payment verification to @hbar-kit/payments as a focused extension of the existing read-only, non-custodial HTS verification layer. USDC on Hedera is an HTS token, so this is a thin convenience path over the generic verifyHtsPayment engine — no custody, no Circle API, no fiat conversion, no wallet/UI.

What's new

• verifyUsdcPayment(params) / waitForUsdcPayment(params) — wrappers over verifyHtsPayment / waitForHtsPayment that resolve the verified USDC token id for the network, force 6-decimal amount parsing, and tag the result asset as { tokenId, decimals: 6, symbol: "USDC" }. All existing payment semantics (confirmed/pending/underpaid/overpaid/duplicate/mismatch/expired/failed) are preserved.
• USDC registry — USDC_TOKEN_IDS, getUsdcTokenId(network), USDC_DECIMALS (= 6), isUsdcPaymentResult(result).
• UnsupportedAssetError added to @hbar-kit/core — thrown for networks without a verified USDC token id.
• PaymentAsset gains an additive optional symbol? — non-breaking.

Network safety

network is required for the USDC helper — USDC token ids and HashScan URLs are network-specific, so there is no implicit default. Previewnet has no Circle-issued USDC and throws rather than silently falling back. A custom tokenId override is supported (dev/mock tokens) and format-validated, but is always parsed at 6 decimals.

Verified token ids

Triple-checked before hardcoding (source comments cite the evidence):

Network	Token id	Verification
mainnet	0.0.456858	Live Mirror Node (symbol USDC, 6 dp, FUNGIBLE_COMMON, treasury 0.0.439909) + Circle USDC contract addresses
testnet	0.0.429274	Live Mirror Node (symbol USDC, 6 dp, FUNGIBLE_COMMON, treasury 0.0.5176) + Circle docs (Hedera Testnet row)
previewnet	—	Not issued by Circle → throws UnsupportedAssetError

Tests

22 unit cases covering exact / underpaid / overpaid (exact vs atLeast) / wrong memo / missing memo / wrong receiver / wrong token / duplicate / failed-excluded / custom token id / unsupported network / >6 decimal precision / missing network / malformed token id / explorer-url network correctness / wait→confirmed / wait→expired. Plus an opt-in, read-only live smoke test gated by HBARKIT_LIVE=1 (no keys, no funds) that confirms the registry ids still resolve to real USDC on-chain.

Docs / example

New "Verify a USDC payment" guide (wired into the sidebar) + cross-links, root and package README sections, reference-doc updates, a verify:usdc example script with .env, and llms.txt / llms-full.txt updates. Positioning unchanged — USDC does not dominate over HBAR/HTS.

Validation

pnpm lint, typecheck, build, test, coverage, and check:publish all pass; VitePress docs build clean with no dead links. usdc.ts has 100% statement/function/line coverage. Backwards compatible — verifyHbar/HtsPayment, waitForHbar/HtsPayment, and PaymentResult are unchanged.

Release

Changeset included: @hbar-kit/payments minor, @hbar-kit/core minor. Merging to main also triggers the Docs deploy so the new guide goes live on GitHub Pages.