在 EVM/Solana 上安全操作 Circle 原生…

适用于在 EVM 链或 Solana 上对 Circle 原生 USDC 做余额查询、转账、授权（仅 EVM）和交易验证。

适用场景

解决思路

1. 先判断生态：地址以 `0x` 开头，或提到 Ethereum、Base、Arbitrum、Polygon 等，按 EVM 处理；地址为 base58，或提到 Solana、Devnet、Phantom、Solflare 等，按 Solana 处理；不清楚时先问用户，不要猜。
2. EVM 依赖安装：运行 `npm install viem`。
3. Solana 依赖安装：运行 `npm install @solana/kit @solana-program/token ws dotenv bs58`。
4. 私钥处理：EVM 按 `references/evm.md` 的说明处理；Solana 按 `references/solana.md` 的说明处理；读操作（余额、allowance、验证）在两个生态都不需要私钥。
5. EVM 测试网 USDC 地址：Arc Testnet（chain ID 5042002）`0x3600000000000000000000000000000000000000`；Ethereum Sepolia（11155111）`0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238`；Base Sepolia（84532）`0x036CbD53842c5426634e7929541eC2318f3dCF7e`；Arbitrum Sepolia（421614）`0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d`；Avalanche Fuji（43113）`0x5425890298aed601595a70AB815c96711a31Bc65`；Polygon Amoy（80002）`0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582`；OP Sepolia（11155420）`0x5fd84259d66Cd46123540766Be93DFE6D43130D7`。
6. 获取测试网 USDC：访问 `https://faucet.circle.com`。
7. EVM 主网 USDC 地址：Arc `0x3600000000000000000000000000000000000000`；Ethereum `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`；Base `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`；Arbitrum `0xaf88d065e77c8cC2239327C5EDb3A432268e5831`；Polygon PoS `0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359`；Avalanche `0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E`；OP Mainnet `0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85`。
8. Solana USDC mint：Devnet `4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU`；Mainnet `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`。
9. 始终按 6 位小数处理 USDC：EVM 使用 `parseUnits("1.00", 6)` 得到 `1_000_000n`；不要使用 `parseUnits("1.00", 18)`，否则会变成 1 万亿美元级别的错误金额。
10. Solana 手动换算金额：`const amount = Math.floor(1.00 * 1_000_000);` 得到 `1_000_000`；`const human = rawAmount / 1_000_000;` 得到 `1.0`。
11. Arc 上 USDC 具有双重形态：既是 native gas token，也是 `0x3600000000000000000000000000000000000000` 上的 ERC-20，同一底层余额但小数位暴露不同。
12. Arc 小数位使用规则：native（gas、`msg.value`）使用 18 位小数，仅用于 gas estimation；ERC-20（`balanceOf`、`transfer`、`approve`）使用 6 位小数，所有 USDC 逻辑走这里。
13. Arc 特定配置参考 `use-arc` skill。
14. 读操作可自动执行，不需要用户确认：余额查询、allowance 查询（仅 EVM）、total supply、地址查询、验证入账转账。
15. 写操作必须获得用户明确确认后再提交：发送 USDC、授权合约花费 USDC（仅 EVM；Solana 没有 approve 模式）。
16. 遇到问题查看链特定参考文件的 Common Issues 部分：`references/evm.md` 或 `references/solana.md`。
17. EVM 与 Solana 差异：EVM 使用 ERC-20；余额直接存在钱包地址；发送用 `transfer(to, amount)`；授权用 `approve(spender, amount)`；收款方无需额外设置；交易费使用链原生代币；确认用 `waitForTransactionReceipt`；库使用 viem；小数位 6。
18. EVM 与 Solana 差异：Solana 使用 SPL Token；余额存储在 Associated Token Account（ATA）；发送用 `getTransferInstruction({ source, destination, authority, amount })`；没有 approve，使用 PDAs；收款方必须先创建 ATA，否则转账失败；交易费使用 SOL；确认用 `sendAndConfirmTransactionFactory`；库使用 `@solana/kit` + `@solana-program/token`；小数位 6。
19. 工作流第 1 步：确定生态——EVM（`0x...`）或 Solana（base58）；不清楚就问。
20. 工作流第 2 步：分类操作——读操作（余额、allowance、supply、verify）自动运行；写操作（send、approve）需要用户明确确认。
21. 工作流第 3 步：写操作前确认细节——验证收款地址、金额（6 位小数）、chain ID（testnet 还是 mainnet）；默认 testnet；mainnet 或金额超过安全阈值时警告。
22. 工作流第 4 步：路由到参考——读取 `references/evm.md` 或 `references/solana.md` 获取准确代码；在 Solana 上先创建收款方 ATA。
23. 工作流第 5 步：执行——运行读操作，或仅在确认后提交写操作，并使用该链正确的 native USDC 地址。
24. 工作流第 6 步：验证——报告成功前等待 transaction receipt/confirmation，并展示 tx hash。
25. EVM 操作实现：读取 `references/evm.md`，获取余额检查、转账、授权、验证的完整代码。
26. Solana 操作实现：读取 `references/solana.md`，获取余额检查（含 ATA）、转账（含 ATA 创建）、验证的完整代码。
27. 安全规则：绝不硬编码、提交或记录 secrets（私钥、API keys）；始终使用环境变量或 secrets manager；搭建项目时为 `.env*` 和 secret 文件添加 `.gitignore` 条目。
28. 安全规则：USDC 绝不用 18 位小数，所有生态始终用 6 位小数。
29. 安全规则：绝不使用桥接版 USDC 变体（`USDbC`、`USDC.e`）；始终使用 Circle 原生发行的 USDC。
30. 安全规则：始终使用每条链正确的 USDC 地址（见 Quick Reference）。
31. 安全规则：提交交易前始终验证 chain ID 与预期环境（testnet vs mainnet）匹配。
32. 安全规则：目标为 mainnet 或超过安全阈值（例如 >100 USDC）时始终警告。
33. 安全规则：与未审计或未知合约交互前始终警告。
34. 安全规则：提交交易前始终验证所有输入（地址、金额、chain identifiers）。
35. 安全规则：提交写交易前始终获得用户明确确认。
36. 安全规则：在等待 transaction receipt 前绝不报告成功；确保已确认。
37. 最佳实践：始终默认 testnet；目标 mainnet 前需要用户明确确认。
38. 最佳实践：始终正确派生 Solana ATA——余额在 ATA 中，不在钱包中。
39. 最佳实践：Solana 转账前始终检查收款方 ATA 是否存在。
40. 最佳实践：转账前始终检查用户是否有足够 USDC 余额。
41. 最佳实践：始终检查用户是否有足够 gas/SOL 支付交易费。
42. 替代方案：跨链转移 USDC 用 `bridge-stablecoin` skill（CCTP / Bridge Kit）；Bridge Kit 在单次 `kit.bridge()` 调用中处理 approve、burn、attestation、mint。
43. 替代方案：需要跨链统一 USDC 余额和即时转账（<500ms）用 `use-gateway` skill；Gateway 需要预先存款，但对多链应用 UX 更好。
44. 替代方案：单链 USDC 操作（余额检查、支付、授权）或需要底层控制转账时继续用 `use-usdc`。
45. 参考文件：EVM 操作指南 `references/evm.md`；Solana 操作指南 `references/solana.md`。
46. 参考链接：`https://developers.circle.com/stablecoins/usdc-contract-addresses`。
47. 参考链接：`https://developers.circle.com`。
48. 参考链接：`https://faucet.circle.com`。
49. 参考链接：`https://faucet.solana.com`。
50. 参考链接：`https://viem.sh`。
51. 参考链接：`https://github.com/circlefin/stablecoin-evm`（Circle 在 EVM 兼容链上的 stablecoin 智能合约源仓库）。

适用边界 · 注意事项

• 需要跨链转移 USDC 时：用 `bridge-stablecoin` skill（CCTP / Bridge Kit），不要用本 skill 手工处理桥接。
• 需要跨链统一余额或 <500ms 即时转账时：用 `use-gateway` skill；它需要预先存款。
• 操作非 USDC 代币、非 EVM/Solana 生态，或只需要底层控制单链 USDC 之外的通用代币操作时：不适用。