自托管加密货币支付

该能力的作用

为任意基于 Supabase 的 Next.js 14+ App Router 应用添加一套完整、开箱即用的生产级加密货币支付系统。无需 Stripe、CryptAPI 或其他第三方支付处理器——您保留每一笔付款的 100% 收益。

支持的链与币种：ETH、Base、Polygon、Arbitrum、Optimism、BNB Chain、Avalanche、Solana、Bitcoin —— 同时支持各链上的 USDC/USDT/DAI 等稳定币。

系统架构：

1. 用户选择币种 → 服务端基于 HD 钱包派生唯一地址（遵循 BIP44 / BIP84 / SLIP-0010）
2. 服务端将该地址及预期收款金额写入数据库，并设置 1 小时过期时间
3. 定时任务每分钟轮询真实区块链，校验余额并确认付款是否到账
4. 确认到账后，原子化地为用户账户发放积分/升级订阅/启用附加功能

安全模型：助记词（mnemonic）永不触达客户端或源代码；用户无法干预目标地址或金额；付款确认由区块链本身验证，而非易被伪造的 Webhook。

需复制的文件

所有模板文件均位于 resources/ 目录下。请按如下路径将其复制到您的项目中：

安装步骤

1. 安装依赖

npm install ethers @scure/bip32 @scure/bip39 @scure/base @noble/hashes @solana/web3.js qrcode
npm install -D @types/qrcode

2. 执行数据库迁移

在 Supabase SQL 编辑器中（或通过 supabase db push 命令），按顺序执行以下两个迁移文件：

• 005_crypto_payments.sql
• 006_crypto_direct.sql

3. 添加环境变量

# 生成助记词：https://iancoleman.io/bip39/（12 或 24 个单词 —— 绝对不可提交至代码库）
CRYPTO_MASTER_MNEMONIC=word1 word2 word3 ... word12

# 用于保护定时任务端点 —— 可通过以下命令生成：
# node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
CRON_SECRET=your-32-char-hex-string

4. 配置定时任务（cron job）

定时端点 POST /api/cron/check-crypto-payments 必须每 60 秒调用一次。

Vercel Cron（vercel.json）：

{
  "crons": [
    {
      "path": "/api/cron/check-crypto-payments",
      "schedule": "* * * * *"
    }
  ]
}

请在 cron 配置或 Vercel 控制台中添加 Authorization 请求头：

Authorization: Bearer 

Fly.io machines / 自托管环境：使用调度任务或外部定时服务（例如 cron-job.org），以 Authorization: Bearer 头部请求该端点。

5. 自定义支付类型

结算路由（checkout route）支持三种支付 type 值，请根据您应用的数据模型进行调整：

如何自定义：在 crypto-checkout-route.ts 中，将 CREDIT_PACKS、PLANS 和 validAddons 替换为您自己的常量定义。金额必须始终来源于服务端常量，绝不可来自用户输入。

在 check-crypto-payments-route.ts 中，请更新 applyPayment() 函数，实现您应用在付款确认后所需执行的操作（如增加积分、解锁功能、更新订阅状态等）。

6. 接入支付弹窗组件

import { CryptoPaymentModal } from '@/components/dashboard/crypto-payment-modal'

// 示例：购买积分包
 setModalOpen(false)}
/>

该弹窗组件自动处理币种选择、二维码展示、倒计时以及付款状态轮询。

地址派生原理

每笔支付都会从您的主助记词派生出一个唯一的充值地址：

• EVM 链（ETH、Base、Polygon 等）：m/44'/60'/0'/0/{index} —— 校验和格式的以太坊地址，兼容所有 EVM 兼容链
• Bitcoin：m/84'/0'/0'/0/{index} —— 原生 SegWit P2WPKH 地址（bc1q...）
• Solana：m/44'/501'/{index}'/0' —— SLIP-0010 ed25519 格式（与 Phantom/Solflare 钱包一致）

derivation_index 每次支付递增，并持久化存储于数据库中。UNIQUE 约束确保不会有两个活跃支付共享同一地址。

注意事项：一个助记词控制全部收款钱包，请务必安全备份。如需清空资金（sweep funds），可将该助记词导入 MetaMask（EVM）、Phantom（SOL）或符合 BIP84 规范的钱包（BTC），然后派生对应子账户。

需要自定义的内容

安全说明

• crypto-wallets.ts 是纯服务端文件 —— 切勿在客户端组件或页面中导入
• CRYPTO_MASTER_MNEMONIC 绝不可出现在源代码、Git 历史记录或日志中
• 定时任务端点使用 timingSafeEqual 对比 CRON_SECRET，防止计时攻击
• 支付金额始终源自服务端常量，用户无法篡改
• 地址唯一性由数据库层面保障（wallet_type + derivation_index 字段组合建立唯一索引）

故障排查

“CRYPTO_MASTER_MNEMONIC 未设置” —— 环境变量缺失。请将其添加至 .env.local（开发环境）或部署平台的环境变量配置中（生产环境）。

付款未确认到账 —— 请检查定时任务是否正常运行，且请求头 Authorization: Bearer 是否完全匹配。同时查看 Vercel 或服务器日志中以 [check-crypto] 开头的日志行。

“Failed to allocate payment address” —— 极其罕见的并发冲突（已重试 3 次失败）。可安全重试。

EVM 链代币未被识别 —— 请确认该代币在对应链上的合约地址已加入 crypto-wallets.ts 中的 ERC20_CONTRACTS 映射表。可前往 etherscan.io 查询该链上 USDC/USDT 的官方合约地址。