AI 提示词：区块链应用开发专家

以下方案基于给定技术偏好（Solidity+Hardhat，React+Next.js，NestJS，PostgreSQL，IPFS，监控与日志）与目标平台（以太坊主网 + Layer2），面向“去中心化票务DApp”从0到1的全流程设计与实现指导。所附智能合约代码仅作示例参考，正式上线前务必经过专业审计与严格测试。

- 覆盖核心模块：用户注册/钱包绑定、门票NFT铸造、二级市场转售、订单与支付、活动方管理、风控与防刷
- 性能目标：峰值1k并发、交易确认<30s、Gas成本可控
- 合规与多链适配：支持L2首发、主网结算与跨链同构
- 里程碑与实施路线：见文末

一、需求分析总结
- 用户注册/钱包绑定
  - 非托管：以钱包为主标识（EIP-4361 SIWE登录）；可选绑定邮箱/手机号（仅后端保存哈希与证明，避免隐私泄露）。
  - 合规扩展：活动方可启用KYC门票（可通过可验证凭证/凭证NFT门槛）。

- 门票NFT铸造
  - 形态：支持两类
    1) ERC-1155（同质/座位分区、批量铸造低Gas）
    2) ERC-721（唯一座位号）
  - 元数据：IPFS存储，包含活动信息、座位/分区、有效期、二维码离线校验字段。
  - 阶段售卖：预售/公售/锁定期、每钱包限购、冷却时间、签名凭证（EIP-712）防机器人。

- 二级市场转售
  - 自建轻量固定价协议（签名订单 + 链上撮合），支持版税（ERC-2981）、平台费、价格上限比例（防黄牛）。
  - 仅在指定窗口期开放转售；可设置最高转售价=面值x倍数（例如≤1.1x~2x）。
  - Optional：兼容外部市场（Seaport/Reservoir）但受限于转移管控策略。

- 订单与支付
  - 支持ETH/原生gas代币与USDC等稳定币（多链多代币），使用Permit2减少授权交互。
  - EIP-1559动态Gas、失败重试、交易替换策略；提供Meta-tx/AA代付（EIP-2771 / ERC-4337）以提升UX（需风控阈值）。

- 活动方管理
  - Factory创建活动合约（最小代理克隆），配置票种、价格、上限、分润、锁定、退票策略。
  - 收入托管与结算：售票收入按策略托管至活动结束再释放；支持多签提现；异常取消支持按规则自动退款。

- 风控与防刷
  - 前端：验证码、设备指纹、速率限制、动态队列排队。
  - 合约：签名白名单/Merkle证明、每地址购买上限、冷却期、转移限时白名单（仅官方合约可转移直到T时间）。
  - 后端：行为评分与阈值（限IP/设备/地址），黑名单名单同步至签名服务。
  - 线下核验：离线校验辅助数据 + 链上持有证明；二维码一次性换新避免伪造截图。

- 性能目标落地
  - 并发1k：下沉读写到L2、订单簿与签名在后端/缓存层；区块事件自建索引；WebSocket与队列解耦。
  - <30s确认：L2优先发售（1-5s确认）；主网交易采用高优先费、自动gas bump；允许“支付->铸造凭证->铸造”两段式，降低用户等待。
  - Gas可控：批量铸造（1155）、最小代理克隆、稀疏存储、事件驱动、Permit2/签名减少授权、L2部署为主。

- 合规与多链
  - 可选KYC门槛（零知识凭证/VC）、黑名单与制裁名单过滤（仅限合法合规数据源）。
  - 多链同构：合约同版本部署至主网/L2；以“链ID + 合约地址”路由；资金与版税分链结算。
  - 税务与发票：活动方导出结算明细、链上交易与法币对账接口预留。

二、技术架构设计
- 合约层
  - TicketFactory（可升级或克隆）：创建TicketERC1155或TicketERC721实例；记录活动元数据根哈希；分润与版税参数。
  - TicketERC1155/721：
    - 角色：DEFAULT_ADMIN、MINTER、PAUSER、TRANSFER_GATE
    - 特性：签名铸造（EIP-712）、Merkle白名单、公售开关、每钱包限额、冷却时间、锁定转移窗口、ERC-2981版税、可选退款规则。
  - Marketplace（FixedPrice）：
    - EIP-712订单：maker、asset、price、deadline、nonce、maxResaleRate
    - 支持ETH/ERC20（Permit2收款），撮合时校验价格上限与活动方策略；自动分配版税+平台费+卖家收益
    - 取消/nonce管理、重入保护、签名防重放（domain-separator含chainId）

- 后端（NestJS）
  - 模块
    - Auth：SIWE登录、会话、可选KYC凭证校验（OIDC/Polygon ID/Credentials）
    - Event：活动/票种CRUD、签名铸造凭证服务、库存一致性保障
    - OrderBook：离线订单管理、签名与风控校验、撮合入口
    - Indexer：监听合约事件（ethers + 回放机制），写入PostgreSQL；Redis缓存热门数据
    - Payments：聚合支持ETH/USDC，Permit2签名生成、失败重试、回执落库
    - Risk：速率限制（Redis）、设备指纹评分、黑名单同步、可配置策略
  - 数据库（PostgreSQL）
    - 表：users、organizers、events、ticket_types、mints、orders、fills、payouts、risk_flags、webhooks
    - 事务与唯一索引保证订单与库存一致性
  - 队列与任务
    - bullmq/Redis：异步铸造、对账、回执确认、webhook通知（商户/活动方后台）

- 前端（Next.js + React）
  - wagmi/viem + RainbowKit/WalletConnect
  - 铸造流程：登录(SIWE) -> 选择票种 -> 获取签名凭证 -> 签署/付款 -> 等待确认 -> 门票展示
  - 转售：创建订单（签名但不上链）-> 后端风控 -> 买家撮合交易 -> 成功页
  - 活动方控制台：创建/管理活动、查看销售与结算、导出报表

- 存储与内容分发
  - IPFS（Pinata/Web3.Storage）：元数据模板、图片、活动海报；CID写入合约
  - CDN加速前端与公开元数据；私密数据仅存哈希与最小化必要字段

- 监控与日志
  - 应用：OpenTelemetry + Prometheus + Grafana（p95延迟、错误率、队列堆积）
  - 区块链：节点健康、区块滞后、交易失败率、gas使用
  - 日志：JSON结构化（pino/winston）+ ELK/OpenSearch；合约事件落库与对账告警
  - 风控告警：异常抢购、同设备高频、多地址聚类

- 多链适配
  - 首发：L2（Optimism/Arbitrum/Base任一）；主网保留品牌门票/纪念版或高端场次
  - 同构部署与配置中心：按chainId加载合约地址、代币、RPC
  - 资金结算：分链记账，跨链可通过官方桥将收入转回主网（运营手动/自动策略）

三、核心代码示例（简化版，需审计后方可生产）
A. TicketERC1155（签名铸造 + 转移管控 + 版税）
说明：使用OpenZeppelin库；关键路径避免重入；示例省略部分检查与事件细节。

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@openzeppelin/contracts/token/ERC1155/ERC1155.sol";
import "@openzeppelin/contracts/access/AccessControl.sol";
import "@openzeppelin/contracts/security/ReentrancyGuard.sol";
import "@openzeppelin/contracts/token/common/ERC2981.sol";
import "@openzeppelin/contracts/utils/cryptography/ECDSA.sol";
import "@openzeppelin/contracts/utils/cryptography/EIP712.sol";
import "@openzeppelin/contracts/security/Pausable.sol";

contract TicketERC1155 is ERC1155, AccessControl, ERC2981, EIP712, Pausable, ReentrancyGuard {
    using ECDSA for bytes32;

    bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");
    bytes32 public constant TRANSFER_GATE_ROLE = keccak256("TRANSFER_GATE_ROLE");

    struct MintVoucher {
        address buyer;
        uint256 eventId;
        uint256 ticketId;   // 票种ID
        uint256 amount;
        uint256 priceWei;   // 单价，0表示免费或已线下付
        uint256 nonce;
        uint256 startTime;
        uint256 endTime;
        uint256 maxPerWallet;
    }

    bytes32 public constant MINT_VOUCHER_TYPEHASH =
        keccak256("MintVoucher(address buyer,uint256 eventId,uint256 ticketId,uint256 amount,uint256 priceWei,uint256 nonce,uint256 startTime,uint256 endTime,uint256 maxPerWallet)");

    address public signer;              // 后端签名者（热签名仅可签发凭证，不可挪用资金）
    mapping(bytes32 => bool) public usedVouchers;
    mapping(address => mapping(uint256 => uint256)) public purchased; // buyer => eventId => count

    // 转移限制
    uint256 public transferUnlockTime;  // 解锁时间
    mapping(address => bool) public allowedOperators; // 指定白名单市场在锁定期可转

    // 事件与库存
    mapping(uint256 => uint256) public maxSupply;     // ticketId => cap
    mapping(uint256 => uint256) public minted;        // ticketId => minted

    constructor(
        string memory uri_,
        address admin,
        address signer_,
        address royaltyReceiver,
        uint96 royaltyBps
    ) ERC1155(uri_) EIP712("Ticket1155", "1") {
        _grantRole(DEFAULT_ADMIN_ROLE, admin);
        _setDefaultRoyalty(royaltyReceiver, royaltyBps);
        signer = signer_;
    }

    function setTransferUnlockTime(uint256 ts) external onlyRole(DEFAULT_ADMIN_ROLE) {
        transferUnlockTime = ts;
    }

    function setAllowedOperator(address op, bool allowed) external onlyRole(TRANSFER_GATE_ROLE) {
        allowedOperators[op] = allowed;
    }

    function setMaxSupply(uint256 ticketId, uint256 cap) external onlyRole(DEFAULT_ADMIN_ROLE) {
        require(minted[ticketId] <= cap, "cap < minted");
        maxSupply[ticketId] = cap;
    }

    function hashVoucher(MintVoucher memory v) public view returns (bytes32) {
        return _hashTypedDataV4(keccak256(abi.encode(
            MINT_VOUCHER_TYPEHASH,
            v.buyer, v.eventId, v.ticketId, v.amount, v.priceWei, v.nonce, v.startTime, v.endTime, v.maxPerWallet
        )));
    }

    function verifyVoucher(MintVoucher memory v, bytes calldata sig) public view returns (bool) {
        bytes32 digest = hashVoucher(v);
        address recovered = ECDSA.recover(digest, sig);
        return recovered == signer;
    }

    function mintWithVoucher(MintVoucher calldata v, bytes calldata sig)
        external
        payable
        nonReentrant
        whenNotPaused
    {
        require(block.timestamp >= v.startTime && block.timestamp <= v.endTime, "sale window");
        require(v.buyer == msg.sender, "not buyer");
        require(verifyVoucher(v, sig), "bad sig");

        bytes32 key = keccak256(abi.encode(v.buyer, v.eventId, v.ticketId, v.nonce));
        require(!usedVouchers[key], "voucher used");
        usedVouchers[key] = true;

        require(maxSupply[v.ticketId] == 0 || minted[v.ticketId] + v.amount <= maxSupply[v.ticketId], "sold out");
        require(purchased[msg.sender][v.eventId] + v.amount <= v.maxPerWallet, "limit");

        if (v.priceWei > 0) {
            require(msg.value == v.priceWei * v.amount, "price");
            // 收款：留在合约待结算，避免立即外流。由管理员提现到多签。
        }

        purchased[msg.sender][v.eventId] += v.amount;
        minted[v.ticketId] += v.amount;
        _mint(msg.sender, v.ticketId, v.amount, "");
    }

    // 转移限制：锁定期仅白名单运营者可转；解锁后自由
    function _beforeTokenTransfer(address operator, address from, address to, uint256[] memory ids, uint256[] memory amounts, bytes memory data)
        internal override
    {
        super._beforeTokenTransfer(operator, from, to, ids, amounts, data);
        if (from != address(0) && to != address(0)) { // 非铸造/销毁
            if (block.timestamp < transferUnlockTime) {
                require(allowedOperators[operator], "transfer locked");
            }
        }
    }

    // Admin withdraw
    function withdraw(address payable to, uint256 amount) external onlyRole(DEFAULT_ADMIN_ROLE) {
        (bool ok, ) = to.call{value: amount}("");
        require(ok, "withdraw failed");
    }

    function supportsInterface(bytes4 iid) public view override(ERC1155, AccessControl, ERC2981) returns (bool) {
        return super.supportsInterface(iid);
    }
}
```

B. 固定价Marketplace（签名订单撮合、价格上限、版税与平台费）
说明：示例仅供结构参考，务必补齐安全检查（非cehcked：fee上限、代币白名单、重入位置等）与审计。

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import "@openzeppelin/contracts/security/ReentrancyGuard.sol";
import "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import "@openzeppelin/contracts/utils/cryptography/EIP712.sol";
import "@openzeppelin/contracts/utils/cryptography/ECDSA.sol";
import "@openzeppelin/contracts/access/Ownable.sol";
import "@openzeppelin/contracts/interfaces/IERC2981.sol";
import "@openzeppelin/contracts/token/ERC1155/IERC1155.sol";
import "@openzeppelin/contracts/token/ERC721/IERC721.sol";

contract FixedPriceMarket is EIP712, ReentrancyGuard, Ownable {
    using ECDSA for bytes32;
    using SafeERC20 for IERC20;

    struct Order {
        address maker;
        address nft;
        bool is1155;
        uint256 tokenId;
        uint256 amount;        // ERC721固定1
        address currency;      // address(0)=ETH
        uint256 price;         // 总价
        uint256 deadline;
        uint256 nonce;
        uint256 maxResaleBps;  // 例如 11000 表示 <=1.1x
        address eventPolicy;   // 可选策略合约，返回面值与上限判断
    }

    bytes32 public constant ORDER_TYPEHASH =
        keccak256("Order(address maker,address nft,bool is1155,uint256 tokenId,uint256 amount,address currency,uint256 price,uint256 deadline,uint256 nonce,uint256 maxResaleBps,address eventPolicy)");

    mapping(address => mapping(uint256 => bool)) public cancelled; // maker => nonce => cancelled
    mapping(address => mapping(uint256 => bool)) public filled;    // maker => nonce => filled

    uint96 public platformFeeBps;      // 平台费
    address public feeReceiver;

    constructor(uint96 feeBps, address feeRecv) EIP712("TicketMarket", "1") {
        platformFeeBps = feeBps;
        feeReceiver = feeRecv;
    }

    function setPlatformFee(uint96 bps, address recv) external onlyOwner {
        require(bps <= 1000, "fee too high"); // <=10%
        platformFeeBps = bps;
        feeReceiver = recv;
    }

    function hashOrder(Order memory o) public view returns (bytes32) {
        return _hashTypedDataV4(keccak256(abi.encode(
            ORDER_TYPEHASH,
            o.maker, o.nft, o.is1155, o.tokenId, o.amount, o.currency, o.price, o.deadline, o.nonce, o.maxResaleBps, o.eventPolicy
        )));
    }

    function cancel(uint256 nonce) external {
        cancelled[msg.sender][nonce] = true;
    }

    function matchAsk(Order calldata ask, bytes calldata sig) external payable nonReentrant {
        require(block.timestamp <= ask.deadline, "expired");
        require(!cancelled[ask.maker][ask.nonce] && !filled[ask.maker][ask.nonce], "used");
        require(_verify(ask, sig), "bad sig");

        // 价格上限策略（示意）：调用eventPolicy查询原始面值
        if (ask.eventPolicy != address(0)) {
            (bool ok, bytes memory data) = ask.eventPolicy.staticcall(
                abi.encodeWithSignature("validateResale(address,uint256,uint256)", ask.nft, ask.tokenId, ask.price)
            );
            require(ok && abi.decode(data, (bool)), "resale limit");
        }

        // 收款处理
        uint256 remaining = ask.price;

        // 版税收取（若实现了ERC-2981）
        (bool supports, bytes memory rdata) = ask.nft.staticcall(abi.encodeWithSelector(IERC2981.royaltyInfo.selector, ask.tokenId, ask.price));
        if (supports && rdata.length >= 64) {
            (address receiver, uint256 royalty) = abi.decode(rdata, (address, uint256));
            if (royalty > 0) {
                _payout(ask.currency, receiver, royalty);
                remaining -= royalty;
            }
        }

        // 平台费
        uint256 fee = (ask.price * platformFeeBps) / 10000;
        if (fee > 0) {
            _payout(ask.currency, feeReceiver, fee);
            remaining -= fee;
        }

        // 给卖家结算
        _payout(ask.currency, ask.maker, remaining);

        // 资产转移：要求卖家提前对本市场合约授权
        if (ask.is1155) {
            IERC1155(ask.nft).safeTransferFrom(ask.maker, msg.sender, ask.tokenId, ask.amount, "");
        } else {
            IERC721(ask.nft).safeTransferFrom(ask.maker, msg.sender, ask.tokenId);
        }

        filled[ask.maker][ask.nonce] = true;
    }

    function _payout(address currency, address to, uint256 amount) internal {
        if (currency == address(0)) {
            require(msg.value == amount || msg.value == 0, "eth mismatch");
            (bool ok, ) = to.call{value: amount}("");
            require(ok, "eth pay fail");
        } else {
            IERC20(currency).safeTransferFrom(msg.sender, to, amount); // 买家->收款方，需Permit2或预授权
        }
    }

    function _verify(Order calldata o, bytes calldata sig) internal view returns (bool) {
        address recovered = ECDSA.recover(hashOrder(o), sig);
        return recovered == o.maker;
    }

    receive() external payable {}
}
```

C. Hardhat网络与部署脚本（多链）
```ts
// hardhat.config.ts
import { HardhatUserConfig } from "hardhat/config";
import "@nomicfoundation/hardhat-toolbox";
import "hardhat-deploy";

const config: HardhatUserConfig = {
  solidity: "0.8.20",
  namedAccounts: { deployer: { default: 0 } },
  networks: {
    hardhat: {},
    base:   { url: process.env.RPC_BASE!,   accounts: [process.env.PRIVATE_KEY!] },
    op:     { url: process.env.RPC_OP!,     accounts: [process.env.PRIVATE_KEY!] },
    arb:    { url: process.env.RPC_ARB!,    accounts: [process.env.PRIVATE_KEY!] },
    mainnet:{ url: process.env.RPC_MAIN!,   accounts: [process.env.PRIVATE_KEY!] },
  }
};
export default config;
```

```ts
// deploy/001_deploy_tickets.ts
import { DeployFunction } from "hardhat-deploy/types";
const func: DeployFunction = async ({ deployments, getNamedAccounts }) => {
  const { deploy } = deployments;
  const { deployer } = await getNamedAccounts();

  const signer = process.env.MINTER_SIGNER!;
  const royaltyRecv = process.env.ROYALTY_RECV!;
  const royaltyBps = 500; // 5%

  await deploy("TicketERC1155", {
    from: deployer,
    args: ["ipfs://{cid}/{id}.json", deployer, signer, royaltyRecv, royaltyBps],
    log: true,
  });

  await deploy("FixedPriceMarket", {
    from: deployer,
    args: [250, process.env.FEE_RECV!], // 2.5%
    log: true,
  });
};
export default func;
```

D. NestJS：签名铸造凭证与Permit2示例
```ts
// mint.service.ts
import { Injectable } from "@nestjs/common";
import { ethers } from "ethers";
import { TypedDataDomain, TypedDataField } from "@ethersproject/abstract-signer";

@Injectable()
export class MintService {
  private wallet = new ethers.Wallet(process.env.MINTER_SIGNER_PK!, new ethers.providers.JsonRpcProvider(process.env.RPC!));

  domain: TypedDataDomain = {
    name: "Ticket1155",
    version: "1",
    chainId: Number(process.env.CHAIN_ID),
    verifyingContract: process.env.TICKET1155!,
  };

  types: Record<string, TypedDataField[]> = {
    MintVoucher: [
      { name: "buyer", type: "address" },
      { name: "eventId", type: "uint256" },
      { name: "ticketId", type: "uint256" },
      { name: "amount", type: "uint256" },
      { name: "priceWei", type: "uint256" },
      { name: "nonce", type: "uint256" },
      { name: "startTime", type: "uint256" },
      { name: "endTime", type: "uint256" },
      { name: "maxPerWallet", type: "uint256" },
    ],
  };

  async createVoucher(dto: { buyer: string; eventId: number; ticketId: number; amount: number; priceWei: string; maxPerWallet: number; startTime: number; endTime: number }) {
    const nonce = Date.now(); // 生产建议使用DB自增 + 唯一约束
    const message = { ...dto, nonce };
    const sig = await this.wallet._signTypedData(this.domain, this.types, message);
    return { ...message, sig };
  }
}
```

E. Next.js前端：创建订单并签名（wagmi/viem）
```tsx
// useCreateOrder.ts
import { useAccount, useSignTypedData } from "wagmi";

export function useCreateOrder() {
  const { address } = useAccount();
  const { signTypedDataAsync } = useSignTypedData();

  return async (order: any, domain: any, types: any) => {
    if (!address) throw new Error("Connect wallet");
    const signature = await signTypedDataAsync({ domain, types, primaryType: "Order", message: order });
    return { order, signature };
  };
}
```

F. IPFS元数据模板
```json
{
  "name": "Event X - Section A Ticket",
  "description": "Admission ticket for Event X at Section A.",
  "image": "ipfs://<poster-cid>",
  "attributes": [
    { "trait_type": "EventId", "value": "123" },
    { "trait_type": "Section", "value": "A" },
    { "trait_type": "Seat", "value": "GA" }
  ],
  "external_url": "https://yourdapp.xyz/event/123",
  "valid_from": 1710000000,
  "valid_to": 1710086400
}
```

四、安全注意事项
- 合约安全
  - 使用OpenZeppelin标准实现；所有外部可变状态函数加ReentrancyGuard或重入安全模式；严格校验msg.value、参数边界与事件索引。
  - EIP-712签名：domain包含name/version/chainId/contract地址；nonce防重放；usedVouchers哈希包含buyer/eventId/ticketId/nonce。
  - 访问控制：分离DEFAULT_ADMIN与运营角色；签名者仅签发凭证，不持有资金；资金提现受多签（Gnosis Safe）与时间锁控制。
  - 转移限制：锁定期仅白名单市场可转，防止外部市场绕过二级策略；注意不与ERC标准冲突（前端需提示限制）。
  - 版税与费用：避免无限fee可被上调；设置上限并在合约内硬编码/延迟修改（Timelock）。
  - 退款与取消：明确触发条件、冻结期与可重入风险；退款路径优先原路返回，谨防闪电贷与利用窗口。
  - 升级策略：如需可升级，限制为代理合约+透明代理/ UUPS + Timelock + 多签；升级前后存储布局审计。

- 后端安全
  - 私钥管理：签名私钥热钱包仅用于凭证签名，资金类密钥一律多签/冷签；使用HSM/KMS；严格IP白名单与速率限制。
  - 风控：设备/地址关联分析、行为速率阈值、黑名单联动；下发凭证与下单API必须通过人机验证与会话绑定。
  - 订单与库存：数据库使用唯一键防止双花；所有代扣路径写入幂等key；队列任务幂等。
  - Webhook/回调：签名校验与重放防护；最小权限API Key管理；敏感信息脱敏日志。

- 前端与用户安全
  - SIWE防重放（nonce + exp + domain校验）；避免在本地存储持久化敏感token；CSRF保护。
  - 钱包授权：使用Permit2短期授权或限额授权；拒绝“无限授权”；授权前明确提示代币/额度/合约。

- 合规
  - 尊重当地监管：KYC开关由活动方配置；仅接入合规的KYC与制裁名单服务；不提供规避监管的方案。
  - 隐私：最小化收集；使用哈希/零知识证明；遵循GDPR/本地数据法规。

五、部署运维指南
- 环境与节点
  - RPC提供商：自建+托管混合（自建Erigon/Nethermind只读节点，托管Alchemy/Infura作备份）；健康检查与自动切换。
  - 网络选择：L2优先（Optimism/Base/Arbitrum三选一）；主网仅大额场次；合约地址与chainId集中配置。

- CI/CD
  - 合约：单元测试（Foundry/Hardhat 90%+覆盖）、静态分析（Slither）、形式化验证关键路径（可选），Testnet部署与回放测试。
  - 后端/前端：Docker镜像、Terraform/IaC；蓝绿/金丝雀发布；特性开关控制售卖开窗。
  - 机密管理：Vault/SOPS；分环境密钥；生产只读权限最小化。

- 指标与告警
  - 业务：铸造成功率、失败原因、队列堆积、平均确认时间、二级成交率、退款率。
  - 区块链：区块滞后>2、交易失败率>2%、gas异常；多签操作告警；余额低阈值。
  - 安全：风控触发、异常IP/设备暴增、签名服务错误率、订单对账不平。

- 性能优化
  - 热路径：缓存活动/票种、签名策略与库存快照（Redis）；只在撮合/铸造时读链。
  - 交易确认<30s：L2售卖；主网设置优先费与自动gas bump；失败后替换交易（replacement transaction）。
  - 前端UX：提交后即展示“待确认”门票占位（链下），确认后自动刷新；失败自动退款或重试指引。

- 运行手册
  - 活动开窗Runbook：预热缓存 -> 设置白名单/签名策略 -> 开窗灰度 -> 观察指标 -> 全量开放 -> 结束关窗。
  - 故障处理：RPC切换、签名服务降级（暂停发券）、市场暂停（Pausable）、紧急锁仓（Timelock + 多签）。

六、里程碑与实施路线
- M0（第1-2周）：需求与合规评估
  - 明确业务约束（KYC、转售上限）、链选择、费率结构与版税
  - 系统规格书、威胁建模、数据模型草案

- M1（第3-5周）：合约PoC与测试网
  - 完成TicketERC1155/721与Factory雏形、签名铸造、转移管控
  - 固定价Market最小可用版本、费率与版税分配
  - 单元测试、测试网部署（L2 testnet + Goerli/SEPOLIA）

- M2（第6-8周）：后端与前端Alpha
  - NestJS鉴权、签名凭证服务、索引器与订单簿
  - Next.js用户流与活动方控制台初版
  - IPFS上链与媒体管线、监控与日志打通

- M3（第9-10周）：风控与支付增强
  - Rate limit、Captcha、人机校验、黑名单同步
  - Permit2集成、稳定币支付路径、对账流程
  - 二级市场订单取消/撤单/过期全流程

- M4（第11-12周）：安全审计与渗透测试
  - 第三方审计（合约与关键后端）、修复与复审
  - 负载与容量测试（1k并发、L2确认时延）

- M5（第13周）：试运营与灰度发布（L2）
  - 小型活动上线、运营仪表盘与报警联动
  - 收集反馈、优化UX与边缘错误路径

- M6（第14-16周）：主网上线与规模化
  - 选择主网场次上线、结算流程稳定
  - 文档化与运营手册完善

七、最佳实践补充
- 为不同活动采用克隆合约（EIP-1167 Minimal Proxy）显著节约部署Gas。
- 票务凭证与转移策略参数化，避免为每个活动重复部署自定义逻辑。
- 大促场景启用“排队+配额+签名窗口”三重保障，前端禁止多标签页并发提交。
- 线下验票端使用离线列表+链上查询双通道，弱网也可快速放行，核销后动态更新二维码。

备注与免责声明：以上代码仅为演示用，未经过审计；请在生产前完成全面审计与攻防测试，确保符合当地监管要求，并采用多签与时间锁保护关键资金与权限。

# 需求分析总结
- 目标与范围
  - 在以太坊测试网实现一套可升级的质押奖励合约，满足 ERC-20 质押、奖励计算、治理参数管理、访问控制、事件日志等模块化需求。
  - 优化 Gas（批量处理、存储压缩），提供安全自检（重入、溢出、权限），并完善测试覆盖与部署流程（分阶段部署、回滚策略、预言机接入）。
- 技术偏好与选型
  - Solidity（>=0.8.x，开启内建溢出检查）
  - Foundry（forge + cast）作为开发、测试与部署工具
  - 开源合约库：OpenZeppelin Upgradeable（UUPS 升级模式）、AccessControl/Pausable/ReentrancyGuard/SafeERC20
  - 静态分析：Slither, Mythril；模糊测试/属性测试：Foundry fuzz/Echidna（可选）
- 关键功能与难点
  - 可升级：存储布局稳定、UUPS 授权升级、迁移函数与回滚策略
  - 奖励算法：采用 Synthetix 风格的 rewardPerToken 累积模型，支持奖励期与速率，避免循环结算
  - 安全与治理：角色分离（GOVERNOR/PAUSER/UPGRADER/REWARD_DISTRIBUTOR）、可暂停、Timelock 可选
  - Gas 优化：批量处理函数、Multicall 合并操作、字段打包、事件索引优化
  - 预言机接入：通过 Chainlink Aggregator 更新奖励参数，设置新鲜度与上下限保护，具备熔断机制
  - 测试与部署：分阶段脚本、静态分析与覆盖率、ERC1967Proxy 代理部署、升级/回滚流程

# 技术架构设计
- 合约模块
  - StakingRewardsV1（UUPS 可升级）
    - 质押模块：stake、stakeFor、stakeWithPermit、withdraw、exit
    - 奖励模块：rewardPerToken、earned、getReward、notifyRewardAmount（支持持续时间与奖励速率）
    - 治理参数：锁定期、最小质押额、最大奖励速率、预言机配置（上下限、过期时间、熔断）
    - 访问控制：AccessControl 角色（DEFAULT_ADMIN、GOVERNOR、PAUSER、UPGRADER、REWARD_DISTRIBUTOR）
    - 日志事件：Staked、Withdrawn、RewardPaid、RewardAdded、ParametersUpdated、Paused/Unpaused、Upgraded
    - 安全：ReentrancyGuard、Pausable、Checks-Effects-Interactions、SafeERC20
    - 批量处理：batchStakeFor、batchGetReward（受限 Gas，管理员或运营用途）；Multicall 合并操作
  - IAggregatorV3 接口（Chainlink 预言机）
- 数据结构与存储布局（注意升级兼容）
  - 全局状态（尽量打包小整数）
    - stakingToken/rewardsToken（地址）
    - totalStaked（uint256）
    - rewardRate（uint256），periodFinish（uint64），lastUpdateTime（uint64）
    - rewardPerTokenStored（uint256）
    - lockPeriod（uint64），minStakeAmount（uint128）
    - oracleCfg：priceFeed（address），staleSeconds（uint64），minBound（int256），maxBound（int256）
  - 用户状态（两到三槽，避免循环）
    - UserInfo
      - balance（uint128）
      - rewards（uint128）  // 累积但未领取
      - userRewardPerTokenPaid（uint256）
      - lastStakeTime（uint64）
  - 升级保留：uint256[50] __gap
- 奖励计算
  - rewardPerToken()
    - 若 totalStaked == 0：返回 rewardPerTokenStored
    - 否则：rewardPerTokenStored + (min(block.timestamp, periodFinish) - lastUpdateTime) * rewardRate * 1e18 / totalStaked
  - earned(account)
    - users[account].balance * (rewardPerToken() - userRewardPerTokenPaid) / 1e18 + users[account].rewards
- 治理与升级
  - UUPSUpgradeable，_authorizeUpgrade 仅 UPGRADER_ROLE（建议该角色绑定 Timelock）
  - 参数修改仅 GOVERNOR_ROLE，带速率与边界检查；支持 Pausable 熔断
  - 预言机更新：GOVERNOR_ROLE 可调用 refreshRewardRateFromOracle，检查新鲜度与边界
- Gas 优化策略
  - 避免访问 storage 多次（缓存到内存），合理使用 unchecked（在明确安全的地方，例如循环索引）
  - 用户结构字段紧凑（uint64/128 打包），事件索引最多两个 indexed
  - 提供 stakeWithPermit 节省 approve 步数；提供 Multicall 合并 stake+getReward
  - 批量函数限制数组长度，防止超出区块 gas
- 集成流程
  - Foundry 项目结构：src/ 合约、script/ 部署、test/ 测试
  - 测试网：Sepolia 或 Goerli，使用 Alchemy/Infura RPC
  - 静态分析：Slither（结构、重入、影子变量）、Mythril（符号执行）
  - 部署：实现合约 -> 部署实现 -> 部署 ERC1967Proxy -> 初始化 -> 绑定角色 -> 加注奖励 -> 通知奖励 -> 运行期维护

# 核心代码示例
说明：以下为参考实现骨架，基于 OpenZeppelin Upgradeable 库，适用于测试网与内部验证。务必在投产前进行第三方审计与严格测试。

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.23;

import "@openzeppelin/contracts-upgradeable/token/ERC20/IERC20Upgradeable.sol";
import "@openzeppelin/contracts-upgradeable/token/ERC20/extensions/draft-IERC20PermitUpgradeable.sol";
import "@openzeppelin/contracts-upgradeable/token/ERC20/utils/SafeERC20Upgradeable.sol";

import "@openzeppelin/contracts-upgradeable/access/AccessControlUpgradeable.sol";
import "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
import "@openzeppelin/contracts-upgradeable/security/ReentrancyGuardUpgradeable.sol";
import "@openzeppelin/contracts-upgradeable/security/PausableUpgradeable.sol";
import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";

// Chainlink Aggregator interface (simplified)
interface IAggregatorV3 {
    function latestRoundData()
        external
        view
        returns (
            uint80 roundId,
            int256 answer,
            uint256 startedAt,
            uint256 updatedAt,
            uint80 answeredInRound
        );
}

contract StakingRewardsV1 is
    Initializable,
    UUPSUpgradeable,
    AccessControlUpgradeable,
    PausableUpgradeable,
    ReentrancyGuardUpgradeable
{
    using SafeERC20Upgradeable for IERC20Upgradeable;

    // Roles
    bytes32 public constant GOVERNOR_ROLE = keccak256("GOVERNOR_ROLE");
    bytes32 public constant PAUSER_ROLE = keccak256("PAUSER_ROLE");
    bytes32 public constant UPGRADER_ROLE = keccak256("UPGRADER_ROLE");
    bytes32 public constant REWARD_DISTRIBUTOR_ROLE = keccak256("REWARD_DISTRIBUTOR_ROLE");

    // Tokens
    IERC20Upgradeable public stakingToken;
    IERC20Upgradeable public rewardsToken;

    // Global accounting
    uint256 public totalStaked;
    uint256 public rewardRate;            // rewards per second
    uint256 public rewardPerTokenStored;  // accumulator scaled by 1e18
    uint64  public lastUpdateTime;        // packed small ints
    uint64  public periodFinish;

    // Governance parameters
    uint64  public lockPeriod;            // seconds
    uint128 public minStakeAmount;        // minimal stake per tx

    // Oracle config
    IAggregatorV3 public priceFeed;
    uint64  public staleSeconds;          // oracle freshness guard
    int256  public oracleMinBound;        // inclusive bound
    int256  public oracleMaxBound;        // inclusive bound

    struct UserInfo {
        uint128 balance;                 // staked amount
        uint128 rewards;                 // accrued but not claimed
        uint256 userRewardPerTokenPaid;  // snapshot
        uint64  lastStakeTime;           // for lock
    }

    mapping(address => UserInfo) private users;

    // Events
    event Staked(address indexed user, uint256 amount);
    event Withdrawn(address indexed user, uint256 amount);
    event RewardPaid(address indexed user, uint256 reward);
    event RewardAdded(uint256 reward, uint256 newRate, uint256 periodFinish);
    event ParametersUpdated(
        uint64 lockPeriod,
        uint128 minStakeAmount,
        address priceFeed,
        uint64 staleSeconds,
        int256 minBound,
        int256 maxBound
    );

    // Initializer (no constructor for upgradeable contracts)
    function initialize(
        address _stakingToken,
        address _rewardsToken,
        address admin,
        address governor,
        address pauser,
        address upgrader
    ) public initializer {
        require(_stakingToken != address(0) && _rewardsToken != address(0), "Zero token");

        __AccessControl_init();
        __Pausable_init();
        __ReentrancyGuard_init();
        __UUPSUpgradeable_init();

        stakingToken = IERC20Upgradeable(_stakingToken);
        rewardsToken = IERC20Upgradeable(_rewardsToken);

        // Roles
        _setupRole(DEFAULT_ADMIN_ROLE, admin);
        _setupRole(GOVERNOR_ROLE, governor);
        _setupRole(PAUSER_ROLE, pauser);
        _setupRole(UPGRADER_ROLE, upgrader);
        _setupRole(REWARD_DISTRIBUTOR_ROLE, governor);

        lastUpdateTime = uint64(block.timestamp);
        lockPeriod = 0;
        minStakeAmount = 1;
    }

    // --- Modifiers/helpers ---
    modifier updateReward(address account) {
        (uint256 rpt, uint64 lastUpdate) = _rewardPerToken();
        rewardPerTokenStored = rpt;
        lastUpdateTime = lastUpdate;

        if (account != address(0)) {
            UserInfo storage u = users[account];
            uint256 earnedAmt = _earned(account, rpt);
            // cap to uint128 if reasonable; else store as uint256 in a second slot (here we keep uint128 for gas)
            if (earnedAmt > type(uint128).max) {
                // fallback: clamp; in production consider upgrading storage type to uint256
                u.rewards = type(uint128).max;
            } else {
                u.rewards = uint128(earnedAmt);
            }
            u.userRewardPerTokenPaid = rpt;
        }
        _;
    }

    function _authorizeUpgrade(address newImplementation) internal override onlyRole(UPGRADER_ROLE) {}

    // --- Views ---
    function rewardPerToken() external view returns (uint256) {
        (uint256 rpt,) = _rewardPerToken();
        return rpt;
    }

    function _rewardPerToken() internal view returns (uint256 rpt, uint64 lastUpdate) {
        lastUpdate = uint64(block.timestamp);
        uint64 applicableTime = lastUpdate;
        if (periodFinish != 0 && applicableTime > periodFinish) {
            applicableTime = periodFinish;
        }

        if (totalStaked == 0) {
            return (rewardPerTokenStored, uint64(applicableTime));
        }

        uint256 delta = uint256(applicableTime) - uint256(lastUpdateTime);
        // rpt accumulator scaled by 1e18
        rpt = rewardPerTokenStored + (delta * rewardRate * 1e18) / totalStaked;
        lastUpdate = uint64(applicableTime);
    }

    function earned(address account) external view returns (uint256) {
        (uint256 rpt,) = _rewardPerToken();
        return _earned(account, rpt);
    }

    function _earned(address account, uint256 rpt) internal view returns (uint256) {
        UserInfo storage u = users[account];
        uint256 paid = u.userRewardPerTokenPaid;
        uint256 accrued = (uint256(u.balance) * (rpt - paid)) / 1e18;
        return accrued + u.rewards;
    }

    // --- Core actions ---
    function stake(uint256 amount)
        external
        nonReentrant
        whenNotPaused
        updateReward(msg.sender)
    {
        require(amount >= minStakeAmount, "Insufficient stake");
        stakingToken.safeTransferFrom(msg.sender, address(this), amount);

        UserInfo storage u = users[msg.sender];
        unchecked {
            u.balance += uint128(amount);
            totalStaked += amount;
        }
        u.lastStakeTime = uint64(block.timestamp);
        emit Staked(msg.sender, amount);
    }

    function stakeFor(address beneficiary, uint256 amount)
        external
        nonReentrant
        whenNotPaused
        updateReward(beneficiary)
    {
        require(amount >= minStakeAmount, "Insufficient stake");
        stakingToken.safeTransferFrom(msg.sender, address(this), amount);

        UserInfo storage u = users[beneficiary];
        unchecked {
            u.balance += uint128(amount);
            totalStaked += amount;
        }
        u.lastStakeTime = uint64(block.timestamp);
        emit Staked(beneficiary, amount);
    }

    function stakeWithPermit(
        uint256 amount,
        uint256 deadline,
        uint8 v, bytes32 r, bytes32 s
    )
        external
        nonReentrant
        whenNotPaused
        updateReward(msg.sender)
    {
        require(amount >= minStakeAmount, "Insufficient stake");
        IERC20PermitUpgradeable(address(stakingToken)).permit(msg.sender, address(this), amount, deadline, v, r, s);
        stakingToken.safeTransferFrom(msg.sender, address(this), amount);

        UserInfo storage u = users[msg.sender];
        unchecked {
            u.balance += uint128(amount);
            totalStaked += amount;
        }
        u.lastStakeTime = uint64(block.timestamp);
        emit Staked(msg.sender, amount);
    }

    function withdraw(uint256 amount)
        external
        nonReentrant
        updateReward(msg.sender)
    {
        UserInfo storage u = users[msg.sender];
        require(amount > 0 && amount <= u.balance, "Bad amount");
        require(lockPeriod == 0 || block.timestamp >= (uint256(u.lastStakeTime) + uint256(lockPeriod)), "Locked");

        unchecked {
            u.balance -= uint128(amount);
            totalStaked -= amount;
        }
        stakingToken.safeTransfer(msg.sender, amount);
        emit Withdrawn(msg.sender, amount);
    }

    function getReward() public nonReentrant updateReward(msg.sender) {
        UserInfo storage u = users[msg.sender];
        uint256 reward = u.rewards;
        if (reward > 0) {
            u.rewards = 0;
            rewardsToken.safeTransfer(msg.sender, reward);
            emit RewardPaid(msg.sender, reward);
        }
    }

    function exit() external {
        withdraw(users[msg.sender].balance);
        getReward();
    }

    // Batch ops (use cautiously; operator or service use)
    function batchGetReward(address[] calldata accounts)
        external
        nonReentrant
        whenNotPaused
        onlyRole(GOVERNOR_ROLE)
    {
        uint256 len = accounts.length;
        for (uint256 i; i < len; ) {
            address acc = accounts[i];
            // Pull-to-user pattern
            (uint256 rpt,) = _rewardPerToken();
            UserInfo storage u = users[acc];
            uint256 reward = _earned(acc, rpt);
            if (reward > 0) {
                u.rewards = 0;
                u.userRewardPerTokenPaid = rpt;
                rewardsToken.safeTransfer(acc, reward);
                emit RewardPaid(acc, reward);
            }
            unchecked { ++i; }
        }
        // update global lastUpdateTime once; safe since _rewardPerToken reads it
        (uint256 rpt2, uint64 last2) = _rewardPerToken();
        rewardPerTokenStored = rpt2;
        lastUpdateTime = last2;
    }

    // Multicall to save gas on combining actions
    function multicall(bytes[] calldata data) external returns (bytes[] memory results) {
        results = new bytes[](data.length);
        for (uint256 i; i < data.length; ) {
            bytes memory d = data[i];
            // delegatecall keeps msg.sender; careful with reentrancy
            (bool ok, bytes memory ret) = address(this).delegatecall(d);
            require(ok, "Multicall failed");
            results[i] = ret;
            unchecked { ++i; }
        }
    }

    // --- Reward distribution ---
    // Notify new reward amount over a duration, distributor must fund contract with rewards beforehand
    function notifyRewardAmount(uint256 amount, uint256 duration)
        external
        nonReentrant
        onlyRole(REWARD_DISTRIBUTOR_ROLE)
        updateReward(address(0))
    {
        require(duration > 0, "Bad duration");
        require(block.timestamp >= periodFinish, "Ongoing period"); // simple model

        // Ensure enough reward balance to pay out
        uint256 bal = rewardsToken.balanceOf(address(this));
        require(bal >= amount, "Insufficient rewards funded");

        rewardRate = amount / duration;
        require(rewardRate > 0, "Zero rate");

        periodFinish = uint64(block.timestamp + duration);
        emit RewardAdded(amount, rewardRate, periodFinish);
    }

    // Governance: parameters
    function setParameters(
        uint64 _lockPeriod,
        uint128 _minStakeAmount,
        address _priceFeed,
        uint64 _staleSeconds,
        int256 _minBound,
        int256 _maxBound
    ) external onlyRole(GOVERNOR_ROLE) {
        lockPeriod = _lockPeriod;
        minStakeAmount = _minStakeAmount;
        priceFeed = IAggregatorV3(_priceFeed);
        staleSeconds = _staleSeconds;
        oracleMinBound = _minBound;
        oracleMaxBound = _maxBound;

        emit ParametersUpdated(_lockPeriod, _minStakeAmount, _priceFeed, _staleSeconds, _minBound, _maxBound);
    }

    // Pause controls
    function pause() external onlyRole(PAUSER_ROLE) { _pause(); }
    function unpause() external onlyRole(PAUSER_ROLE) { _unpause(); }

    // Oracle-driven reward rate refresh (bounded, fresh)
    function refreshRewardRateFromOracle(uint256 duration) external onlyRole(GOVERNOR_ROLE) updateReward(address(0)) {
        require(address(priceFeed) != address(0), "No oracle");
        require(duration > 0, "Bad duration");

        (, int256 answer,, uint256 updatedAt,) = priceFeed.latestRoundData();
        require(answer >= oracleMinBound && answer <= oracleMaxBound, "Oracle out-of-bounds");
        require(block.timestamp - updatedAt <= staleSeconds, "Oracle stale");

        // Example mapping: linear map price to amount (customize per protocol)
        // IMPORTANT: Keep conservative mapping; here we just scale to a capped reward amount.
        uint256 amount = _mapPriceToReward(uint256(answer));
        uint256 bal = rewardsToken.balanceOf(address(this));
        if (amount > bal) amount = bal;

        rewardRate = amount / duration;
        require(rewardRate > 0, "Zero rate");
        periodFinish = uint64(block.timestamp + duration);

        emit RewardAdded(amount, rewardRate, periodFinish);
    }

    function _mapPriceToReward(uint256 price) internal view returns (uint256) {
        // Example: simple clamp and proportional mapping; replace with safe logic
        // Avoid extreme emissions; governance should set reasonable bounds.
        uint256 base = 1e18; // normalizer
        if (price > uint256(oracleMaxBound)) price = uint256(oracleMaxBound);
        if (price < uint256(oracleMinBound)) price = uint256(oracleMinBound);
        // naive mapping: amount = price / 100 (for demo). In production use a safe schedule.
        return price / 100;
    }

    // Storage gap for future upgrades
    uint256[45] private __gap;
}
```

Foundry 部署脚本（UUPS + ERC1967Proxy）示例：
```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.23;

import "forge-std/Script.sol";
import "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol";
import "../src/StakingRewardsV1.sol";

contract DeployStakingRewards is Script {
    // Edit with your addresses (testnet)
    address stakingToken = 0x...; // ERC-20 stake token
    address rewardsToken = 0x...; // ERC-20 rewards token
    address admin   = 0x...;
    address governor= 0x...;
    address pauser  = 0x...;
    address upgrader= 0x...;

    function run() external {
        uint256 pk = vm.envUint("PRIVATE_KEY");
        vm.startBroadcast(pk);

        StakingRewardsV1 impl = new StakingRewardsV1();

        bytes memory initData = abi.encodeWithSelector(
            StakingRewardsV1.initialize.selector,
            stakingToken,
            rewardsToken,
            admin,
            governor,
            pauser,
            upgrader
        );

        ERC1967Proxy proxy = new ERC1967Proxy(address(impl), initData);
        StakingRewardsV1 staking = StakingRewardsV1(address(proxy));

        // Optional: set parameters
        // staking.setParameters(0, 1, address(0), 0, 0, type(int256).max);

        console2.log("StakingRewards proxy:", address(staking));
        console2.log("Implementation:", address(impl));

        vm.stopBroadcast();
    }
}
```

Foundry 测试样例（片段）：
```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.23;

import "forge-std/Test.sol";
import "../src/StakingRewardsV1.sol";
import "./mocks/MockERC20.sol";
import "@openzeppelin/contracts/proxy/ERC1967/ERC1967Proxy.sol";

contract StakingRewardsTest is Test {
    MockERC20 stakeToken;
    MockERC20 rewardToken;
    StakingRewardsV1 staking;

    address admin = address(0xA1);
    address gov   = address(0xA2);
    address usr   = address(0xB1);

    function setUp() public {
        stakeToken = new MockERC20("Stake", "STK", 18);
        rewardToken = new MockERC20("Reward", "RWD", 18);

        StakingRewardsV1 impl = new StakingRewardsV1();
        bytes memory initData = abi.encodeWithSelector(
            StakingRewardsV1.initialize.selector,
            address(stakeToken),
            address(rewardToken),
            admin, gov, admin, admin
        );
        ERC1967Proxy proxy = new ERC1967Proxy(address(impl), initData);
        staking = StakingRewardsV1(address(proxy));

        // fund user and rewards
        stakeToken.mint(usr, 1000e18);
        rewardToken.mint(address(staking), 1000e18);

        vm.prank(gov);
        staking.notifyRewardAmount(100e18, 1000); // 0.1 RWD/s
    }

    function testStakeAndEarn() public {
        vm.startPrank(usr);
        stakeToken.approve(address(staking), type(uint256).max);
        staking.stake(100e18);
        vm.warp(block.timestamp + 100); // advance time
        uint256 earned = staking.earned(usr);
        assertGt(earned, 0);
        staking.getReward();
        vm.stopPrank();
    }

    function testWithdrawLock() public {
        vm.startPrank(gov);
        staking.setParameters(3600, 1, address(0), 0, 0, 0); // lock 1h
        vm.stopPrank();

        vm.startPrank(usr);
        stakeToken.approve(address(staking), type(uint256).max);
        staking.stake(10e18);
        vm.expectRevert(); // locked
        staking.withdraw(1e18);
        vm.warp(block.timestamp + 3600);
        staking.withdraw(1e18);
        vm.stopPrank();
    }
}
```

MockERC20（简单可测试）： 
```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.23;

import "@openzeppelin/contracts/token/ERC20/ERC20.sol";

contract MockERC20 is ERC20 {
    constructor(string memory n, string memory s, uint8 decimals_) ERC20(n, s) {
        _mint(msg.sender, 0);
        _decimals = decimals_;
    }
    uint8 private _decimals;
    function decimals() public view override returns (uint8) { return _decimals; }
    function mint(address to, uint256 amt) external { _mint(to, amt); }
}
```

# 安全注意事项
- 可升级安全
  - 使用 UUPSUpgradeable，_authorizeUpgrade 仅限 UPGRADER_ROLE，建议由 TimelockController 持有，执行延时升级。
  - 严格遵守存储布局稳定性；新增变量在末尾，保留 __gap。
  - 升级时如需迁移数据，使用 upgradeToAndCall 执行迁移逻辑。
- 重入防护
  - 所有外部可转账入口采用 nonReentrant；采用 Checks-Effects-Interactions。
  - 使用 SafeERC20 处理非标准 ERC-20。
- 溢出与类型
  - Solidity 0.8 已内建溢出检查；对循环索引等明确安全场景可使用 unchecked。
  - 用户奖励暂存为 uint128 以节省 gas；如存在大额奖励风险，建议升级存储为 uint256。
- 访问控制与治理
  - 角色分离：DEFAULT_ADMIN、GOVERNOR、PAUSER、UPGRADER、REWARD_DISTRIBUTOR。
  - 建议将治理角色与升级角色交由 Timelock + 多签持有，避免单点故障。
  - 所有参数有边界检查，防止设置极端值导致经济风险。
- 预言机安全
  - 检查数据新鲜度（staleSeconds）与上下限（oracleMinBound/MaxBound）。
  - 预言机失效时触发熔断（pause）或拒绝更新。
  - 严禁依赖单一源头喂价决定高风险经济参数（多源聚合更安全）。
- 经济与跑偏风险
  - 奖励分发依赖资金充足（合约内余额）；notifyRewardAmount 前需先充值。
  - 避免批量函数导致大量 gas 与失败：限制数组长度、分批执行。
- 合规与密钥
  - 不要在脚本中硬编码私钥；使用环境变量注入。
  - 交易签名与私钥管理应遵循钱包安全最佳实践；不在合约中存储私钥。

# 部署运维指南
- 准备环境
  - 安装 Foundry：curl -L https://foundry.paradigm.xyz | bash && foundryup
  - 配置 RPC 与私钥：
    - export SEPOLIA_RPC_URL="https://eth-sepolia.g.alchemy.com/v2/..."
    - export PRIVATE_KEY="0x..."
  - 安装依赖：
    - forge install OpenZeppelin/openzeppelin-contracts-upgradeable
- 编译与静态分析
  - forge build
  - slither . --ignore-compile --filter-paths "lib/,node_modules/"
  - myth analyze src/StakingRewardsV1.sol  // 可选
- 单元测试与覆盖率
  - forge test -vvv
  - forge coverage
  - 增加 fuzz 测试用例（边界输入、时间跳跃、批量长度等）
- 分阶段部署（测试网）
  1. 部署实现与代理
     - forge script script/DeployStakingRewards.s.sol:DeployStakingRewards --rpc-url $SEPOLIA_RPC_URL --private-key $PRIVATE_KEY --broadcast
  2. 绑定角色（如需 Timelock，多签地址替换 governor/upgrader）
     - 通过合约函数或脚本授予/撤销角色
  3. 资金注入与奖励开启
     - 将奖励代币转入合约
     - 调用 notifyRewardAmount(amount, duration)
  4. 参数配置与预言机接入
     - setParameters(lockPeriod, minStake, priceFeed, staleSeconds, minBound, maxBound)
     - 测试 refreshRewardRateFromOracle 在边界与过期情况下的行为
- 升级与回滚
  - 升级：部署新实现 -> 调用 upgradeTo 或 upgradeToAndCall（由 UPGRADER_ROLE/Timelock 发起）
  - 回滚：保留上一版本实现地址，出现问题时 upgradeTo(previousImpl)
  - 升级前后运行迁移脚本检查：存储一致性、事件、接口行为
- 监控与运维
  - 事件订阅：Staked/Withdrawn/RewardPaid/RewardAdded/ParametersUpdated/Upgraded
  - 状态指标：totalStaked、rewardRate、periodFinish、paused 状态
  - 预言机健康：updatedAt 与价格边界，异常时及时 pause
- 额外优化与扩展
  - 引入 EIP-2612 permit 以减少 approve 成本（已支持 stakeWithPermit）
  - 若奖励代币与质押代币相同，可添加 claimAndStake 复投函数
  - 引入 TimelockController（OpenZeppelin）实现延时治理变更
  - 引入 Multisig（如 Safe）保管治理与升级角色

说明与建议：
- 本实现适合测试网与内部验证场景。主网上线前必须进行系统级审计、经济模型评估与压测。
- 批量函数仅建议运营/服务账户在受控条件下使用，避免用户端滥用导致区块 gas 过高。
- 存储压缩与 uint128 奖励字段仅作为 gas 优化示例；如存在大额奖励累计可能溢出，请在下一版本升级为 uint256 并迁移数据。

# 需求分析总结

- 核心功能
  - 钱包连接
    - 浏览器钱包：MetaMask、Coinbase Wallet（EIP-1193）
    - 通用钱包连接协议：WalletConnect v2
  - 交易签名与状态订阅
    - 前端使用钱包签名 EIP-712 / EIP-191
    - 提交链上交易，前端/后端订阅交易确认（SSE/WebSocket + Redis pub/sub）
  - 后端服务编排
    - Node.js（Express）作为 API 网关与后台任务协调者
    - 使用 Redis 进行缓存与队列（BullMQ）
  - 数据流设计
    - 缓存：链上只读数据（余额、价格、合约只读）设置 TTL 缓存
    - 队列：交易状态监控、事件处理异步化
  - 协作规范
    - API 契约（OpenAPI 文档 + TypeScript 类型）
    - 分支策略（Trunk-based 或 GitFlow）
    - 代码审查与CI（Lint、Typecheck、Test、构建）

- 技术难点与对策
  - 多钱包与网络管理：抽象统一的 Provider 接入层；支持链切换（EIP-3085 / wallet_switchEthereumChain）
  - 交易状态可靠订阅：使用 WebSocket RPC 优先，回退到轮询；队列+SSE 将状态推送到前端，考虑重组与交易替换
  - 安全的用户认证：不托管私钥，采用 SIWE（EIP-4361）基于签名会话
  - 后端与缓存一致性：明确 TTL 与失效策略；避免缓存污染与过期数据
  - 可观测性与回滚：日志、指标、告警，灰度发布与版本控制

- 目标网络
  - 兼容 EVM 侧链或以太坊测试网（建议：Sepolia 11155111；必要时 Polygon Amoy 80002）
  - 使用受信 RPC 服务提供商（Alchemy、Infura）启用 WebSocket 端点与速率限制支持


# 技术架构设计

- 前端（TypeScript + React + Vite）
  - 状态管理：React Context/Hook（避免引入过重库）
  - 区块链交互：ethers.js v6 + EIP-1193 Provider（window.ethereum 或 WalletConnect）
  - 连接器层：
    - BrowserProvider：window.ethereum
    - WalletConnect：@walletconnect/ethereum-provider → ethers BrowserProvider
  - 功能模块
    - WalletManager：连接/断开、链切换、获取 Signer
    - TxService：发送交易、EIP-712 签名、状态订阅（SSE）
    - Auth：SIWE（nonce 拉取、消息签名、后端验证）
  - 网络与配置：通过 .env 与前端环境变量 VITE_* 注入链ID、RPC映射、WalletConnect ProjectId

- 后端（Node.js + Express）
  - 核心服务
    - AuthService：生成 nonce，验证 SIWE，管理会话（HTTP-only cookie + Redis）
    - ChainService：只读查询（余额、合约读取），后端不保管用户私钥
    - TxWatcher：接受前端提交的 txHash，后台队列监听确认并通过 Redis pub/sub 推送
  - 队列与缓存
    - BullMQ 队列：tx-status（交易确认任务）、event-index（合约事件索引）
    - Redis 缓存：链上只读数据（如余额）TTL；防止击穿，使用单飞（single-flight）策略
    - Redis Pub/Sub：向前端的 SSE 通道发布 tx 状态更新
  - RPC Provider
    - 优先 WebSocketProvider（实时性好），降级到 HttpProvider（轮询）
    - 多网络支持：按 network key 选择 provider
  - API 契约
    - POST /auth/nonce → { nonce }
    - POST /auth/verify → { ok, address }
    - GET /chain/balance?address=...&network=... → { balance }
    - POST /tx/watch → { ok }（请求后端开始监控某 txHash）
    - GET /tx/:hash/stream?network=... → SSE 推送状态
    - OpenAPI/Swagger 文档自动生成（基于 TS 类型）

- 数据流与订阅设计
  - 前端发送交易后获取 txHash → 调用 /tx/watch 并建立 /tx/:hash/stream SSE 通道
  - 后端 Worker waitForTransaction(hash, confirmations>=1)，发布状态变化
  - 处理交易替换（用户用更高 gasPrice 替换）：通过交易索引监听或轮询 receipt 并比对 nonce，必要时标记 replaced
  - 最终性：根据网络设定 confirmThreshold（例如 2~3 区块），减少重组影响

- 协作规范
  - 分支策略
    - 推荐 Trunk-based：主分支受保护，Feature 分支 → PR → 必要审查后合并
    - 或 GitFlow：develop/main + feature/* + release/*
  - 代码审查
    - 必要 Reviewer 数量、必须通过 CI（lint、typecheck、test）
    - 安全审查清单（依赖升级、秘钥使用、RPC配置）
  - CI
    - GitHub Actions：Node 版本矩阵，pnpm/yarn 缓存
    - 步骤：Install → Lint (ESLint) → Typecheck (tsc) → Test (Vitest/Jest) → Build → Docker build（后端） → 安全扫描（npm audit）

- 目录结构建议
  - /apps/web（Vite React）
    - src/wallet、src/services、src/pages、src/components
  - /apps/api（Express）
    - src/routes、src/services、src/workers、src/lib、src/types
  - /packages/shared（共享类型与工具）
  - /infra（Docker、Compose、K8s 清单）
  - /docs（OpenAPI、运行手册）

# 核心代码示例

注意：示例为指导用途，需根据实际业务调整，并确保使用可信 RPC 与安全配置。

## 前端：钱包连接与统一 Provider

安装依赖
```
npm i ethers @walletconnect/ethereum-provider
```

WalletManager（React Hook）
```ts
// apps/web/src/wallet/useWallet.ts
import { useEffect, useState, useCallback } from 'react';
import { ethers } from 'ethers';
import EthereumProvider from '@walletconnect/ethereum-provider';

type Connector = 'browser' | 'walletconnect';

export type WalletState = {
  connector?: Connector;
  provider?: ethers.BrowserProvider;
  signer?: ethers.Signer;
  address?: string;
  chainId?: number;
  connected: boolean;
};

const WC_PROJECT_ID = import.meta.env.VITE_WALLETCONNECT_PROJECT_ID;
const DEFAULT_CHAINS = (import.meta.env.VITE_SUPPORTED_CHAINS ?? '11155111').split(',').map(Number);
const RPC_MAP = JSON.parse(import.meta.env.VITE_RPC_MAP || '{}'); // { "11155111": "wss://..." }

export function useWallet() {
  const [state, setState] = useState<WalletState>({ connected: false });

  const connectBrowser = useCallback(async () => {
    if (!window.ethereum) throw new Error('No browser wallet found');
    const provider = new ethers.BrowserProvider(window.ethereum, { name: 'browser', chainId: undefined });
    await window.ethereum.request({ method: 'eth_requestAccounts' });
    const signer = await provider.getSigner();
    const address = await signer.getAddress();
    const network = await provider.getNetwork();
    setState({ connector: 'browser', provider, signer, address, chainId: Number(network.chainId), connected: true });

    // handle events
    window.ethereum.on('accountsChanged', async () => {
      const signer = await provider.getSigner();
      const address = await signer.getAddress();
      setState(s => ({ ...s, signer, address }));
    });
    window.ethereum.on('chainChanged', async (_chainIdHex: string) => {
      const network = await provider.getNetwork();
      setState(s => ({ ...s, chainId: Number(network.chainId) }));
    });
  }, []);

  const connectWalletConnect = useCallback(async () => {
    const wc = await EthereumProvider.init({
      projectId: WC_PROJECT_ID,
      chains: DEFAULT_CHAINS,
      showQrModal: true,
      rpcMap: RPC_MAP,
      methods: ['eth_sendTransaction', 'eth_signTransaction', 'personal_sign', 'eth_signTypedData', 'eth_signTypedData_v4'],
      events: ['chainChanged', 'accountsChanged'],
      metadata: {
        name: 'My DApp',
        description: 'DApp with WalletConnect',
        url: window.location.origin,
        icons: ['https://yourcdn/icon.png']
      }
    });

    await wc.enable();
    const provider = new ethers.BrowserProvider(wc as unknown as any);
    const signer = await provider.getSigner();
    const address = await signer.getAddress();
    const network = await provider.getNetwork();
    setState({ connector: 'walletconnect', provider, signer, address, chainId: Number(network.chainId), connected: true });

    wc.on('accountsChanged', async () => {
      const signer = await provider.getSigner();
      const address = await signer.getAddress();
      setState(s => ({ ...s, signer, address }));
    });
    wc.on('chainChanged', async () => {
      const network = await provider.getNetwork();
      setState(s => ({ ...s, chainId: Number(network.chainId) }));
    });
  }, []);

  const disconnect = useCallback(async () => {
    if (state.connector === 'walletconnect') {
      try { await (state.provider?.provider as any)?.disconnect?.(); } catch {}
    }
    setState({ connected: false });
  }, [state]);

  const switchChain = useCallback(async (targetChainId: number) => {
    if (!state.provider) throw new Error('No provider');
    const hexId = '0x' + targetChainId.toString(16);
    try {
      await (state.provider.provider as any).request({
        method: 'wallet_switchEthereumChain',
        params: [{ chainId: hexId }]
      });
    } catch (err: any) {
      if (err?.code === 4902) {
        const rpcUrl = RPC_MAP[String(targetChainId)];
        await (state.provider.provider as any).request({
          method: 'wallet_addEthereumChain',
          params: [{
            chainId: hexId,
            chainName: `Chain ${targetChainId}`,
            nativeCurrency: { name: 'ETH', symbol: 'ETH', decimals: 18 },
            rpcUrls: [rpcUrl].filter(Boolean),
            blockExplorerUrls: []
          }]
        });
      } else {
        throw err;
      }
    }
    const network = await state.provider.getNetwork();
    setState(s => ({ ...s, chainId: Number(network.chainId) }));
  }, [state.provider]);

  return { ...state, connectBrowser, connectWalletConnect, disconnect, switchChain };
}
```

发送交易与状态订阅（SSE）
```ts
// apps/web/src/services/tx.ts
import { ethers } from 'ethers';

export async function sendNativeTx(signer: ethers.Signer, to: string, valueEth: string) {
  const tx = await signer.sendTransaction({
    to,
    value: ethers.parseEther(valueEth)
  });
  return tx.hash;
}

// SSE 订阅后端推送的交易状态
export function subscribeTxStatus(hash: string, network: string, onMessage: (ev: MessageEvent) => void) {
  const url = `/tx/${hash}/stream?network=${encodeURIComponent(network)}`;
  const es = new EventSource(url, { withCredentials: true });
  es.onmessage = onMessage;
  es.onerror = (e) => { console.error('SSE error', e); es.close(); };
  return () => es.close();
}
```

EIP-712 签名示例
```ts
// apps/web/src/services/sign.ts
import { ethers } from 'ethers';

export async function signTypedData(signer: ethers.Signer, domain: any, types: any, value: any) {
  // ethers v6: signTypedData from Signer
  // Some wallets require stripping the "EIP712Domain" from types
  const sig = await (signer as any).signTypedData(domain, types, value);
  return sig;
}
```

## 前端：SIWE 登录流程

```
npm i siwe
```

```ts
// apps/web/src/services/siwe.ts
import { SiweMessage } from 'siwe';

export async function createSiweMessage(address: string, chainId: number) {
  const nonceResp = await fetch('/auth/nonce', { credentials: 'include' });
  const { nonce } = await nonceResp.json();
  const msg = new SiweMessage({
    domain: window.location.host,
    address,
    statement: 'Sign in to the DApp',
    uri: window.location.origin,
    version: '1',
    chainId,
    nonce
  });
  return msg.prepareMessage();
}

export async function verifySiwe(message: string, signature: string) {
  const resp = await fetch('/auth/verify', {
    method: 'POST',
    credentials: 'include',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ message, signature })
  });
  return resp.json(); // { ok: boolean, address: string }
}
```

## 后端：Express + ethers + Redis + BullMQ

安装依赖
```
npm i express cors cookie-parser siwe ethers ioredis bullmq pino
```

环境变量（示例）
```
PORT=3000
REDIS_URL=redis://localhost:6379
RPC_HTTP_11155111=https://eth-sepolia.g.alchemy.com/v2/xxxx
RPC_WS_11155111=wss://eth-sepolia.g.alchemy.com/v2/xxxx
SESSION_SECRET=replace_me
```

Provider 工厂
```ts
// apps/api/src/lib/provider.ts
import { ethers } from 'ethers';

const httpMap: Record<string, string | undefined> = {
  '11155111': process.env.RPC_HTTP_11155111,
};
const wsMap: Record<string, string | undefined> = {
  '11155111': process.env.RPC_WS_11155111,
};

export function getProvider(network: string, preferWs = true) {
  const ws = wsMap[network];
  if (preferWs && ws) {
    return new ethers.WebSocketProvider(ws);
  }
  const http = httpMap[network];
  if (!http) throw new Error(`No RPC for network ${network}`);
  return new ethers.JsonRpcProvider(http);
}
```

启动 Express 与基础中间件
```ts
// apps/api/src/server.ts
import express from 'express';
import cors from 'cors';
import cookieParser from 'cookie-parser';
import pino from 'pino';
import { authRouter } from './routes/auth';
import { chainRouter } from './routes/chain';
import { txRouter } from './routes/tx';

const logger = pino();
const app = express();

app.use(cors({ origin: [/^https?:\/\/localhost:\d+$/, /your\.domain$/], credentials: true }));
app.use(express.json());
app.use(cookieParser(process.env.SESSION_SECRET));

app.use('/auth', authRouter);
app.use('/chain', chainRouter);
app.use('/tx', txRouter);

const port = process.env.PORT || 3000;
app.listen(port, () => logger.info(`API listening on ${port}`));
```

Redis、BullMQ 初始化
```ts
// apps/api/src/lib/redis.ts
import { Redis } from 'ioredis';
export const redis = new Redis(process.env.REDIS_URL!);

// apps/api/src/lib/queue.ts
import { Queue, Worker } from 'bullmq';
import { redis } from './redis';
export const txQueue = new Queue('tx-status', { connection: redis.options });

export function makeTxWorker(processor: (data: any) => Promise<void>) {
  return new Worker('tx-status', async job => {
    await processor(job.data);
  }, { connection: redis.options });
}
```

SIWE Auth 路由
```ts
// apps/api/src/routes/auth.ts
import { Router } from 'express';
import { randomBytes } from 'crypto';
import { redis } from '../lib/redis';
import { SiweMessage } from 'siwe';

export const authRouter = Router();

authRouter.post('/nonce', async (req, res) => {
  const nonce = randomBytes(16).toString('hex');
  // 简单会话：nonce 绑定到一个临时 session key（cookie）
  const sid = req.signedCookies.sid || randomBytes(16).toString('hex');
  res.cookie('sid', sid, { httpOnly: true, signed: true, sameSite: 'lax' });
  await redis.setex(`siwe:nonce:${sid}`, 300, nonce);
  res.json({ nonce });
});

authRouter.post('/verify', async (req, res) => {
  const sid = req.signedCookies.sid;
  if (!sid) return res.status(401).json({ ok: false, error: 'No session' });
  const nonce = await redis.get(`siwe:nonce:${sid}`);
  if (!nonce) return res.status(401).json({ ok: false, error: 'Nonce expired' });

  try {
    const msg = new SiweMessage(req.body.message);
    const { data: result } = await msg.verify({
      signature: req.body.signature,
      domain: req.headers.host!,
      nonce,
    });
    if (!result?.success) throw new Error('Invalid SIWE');
    await redis.setex(`siwe:session:${sid}`, 3600, result.address);
    await redis.del(`siwe:nonce:${sid}`);
    res.json({ ok: true, address: result.address });
  } catch (e: any) {
    res.status(401).json({ ok: false, error: e.message });
  }
});
```

链上只读接口（余额查询 + 缓存）
```ts
// apps/api/src/routes/chain.ts
import { Router } from 'express';
import { getProvider } from '../lib/provider';
import { redis } from '../lib/redis';
import { ethers } from 'ethers';

export const chainRouter = Router();

chainRouter.get('/balance', async (req, res) => {
  const { address, network = '11155111' } = req.query as any;
  if (!ethers.isAddress(address)) return res.status(400).json({ error: 'Invalid address' });
  const cacheKey = `balance:${network}:${address}`;
  const cached = await redis.get(cacheKey);
  if (cached) return res.json({ network, address, balance: cached, cached: true });

  const provider = getProvider(network);
  const bal = await provider.getBalance(address);
  const balanceEth = ethers.formatEther(bal);
  await redis.setex(cacheKey, 30, balanceEth); // TTL 30s
  res.json({ network, address, balance: balanceEth, cached: false });
});
```

交易状态队列与 SSE 推送
```ts
// apps/api/src/routes/tx.ts
import { Router } from 'express';
import { txQueue } from '../lib/queue';
import { redis } from '../lib/redis';

export const txRouter = Router();

// 请求后端监控某交易
txRouter.post('/watch', async (req, res) => {
  const { hash, network = '11155111' } = req.body;
  if (!/^0x([0-9a-fA-F]{64})$/.test(hash)) return res.status(400).json({ error: 'Invalid tx hash' });
  await txQueue.add('watch', { hash, network }, { removeOnComplete: true, removeOnFail: true });
  res.json({ ok: true });
});

// SSE 通道：推送该交易状态
txRouter.get('/:hash/stream', async (req, res) => {
  const { hash } = req.params;
  const { network = '11155111' } = req.query as any;

  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');

  const channel = `tx-status:${network}:${hash}`;
  const sub = new (require('ioredis')).Redis(process.env.REDIS_URL!);
  await sub.subscribe(channel);
  sub.on('message', (_chan: string, msg: string) => {
    res.write(`data: ${msg}\n\n`);
  });

  req.on('close', async () => {
    await sub.unsubscribe(channel);
    sub.disconnect();
    res.end();
  });

  // 立即发送一个 hello 包，避免前端等待
  res.write(`data: ${JSON.stringify({ status: 'subscribed', hash, network })}\n\n`);
});
```

交易状态 Worker（waitForTransaction + 推送）
```ts
// apps/api/src/workers/txWorker.ts
import { makeTxWorker } from '../lib/queue';
import { getProvider } from '../lib/provider';
import { redis } from '../lib/redis';

function toMessage(obj: any) { return JSON.stringify(obj); }

// confirmations 可配置，减少重组影响
const CONFIRMATIONS = Number(process.env.CONFIRMATIONS ?? 1);

export const worker = makeTxWorker(async ({ hash, network }: { hash: string; network: string }) => {
  const provider = getProvider(network, true);
  const channel = `tx-status:${network}:${hash}`;

  // 初始状态
  await redis.publish(channel, toMessage({ status: 'pending', hash }));

  try {
    const receipt = await provider.waitForTransaction(hash, CONFIRMATIONS);
    if (!receipt) {
      await redis.publish(channel, toMessage({ status: 'timeout', hash }));
      return;
    }
    const msg = {
      status: receipt.status === 1 ? 'confirmed' : 'failed',
      hash,
      blockNumber: receipt.blockNumber,
      confirmations: CONFIRMATIONS,
      gasUsed: receipt.gasUsed?.toString(),
      effectiveGasPrice: receipt.effectiveGasPrice?.toString(),
      to: receipt.to,
      from: receipt.from,
      contractAddress: receipt.contractAddress,
      transactionIndex: receipt.transactionIndex,
    };
    await redis.publish(channel, toMessage(msg));
  } catch (e: any) {
    // 可能是替换或 RPC 错误
    await redis.publish(channel, toMessage({ status: 'error', hash, error: e.message }));
  }
});
```

Worker 启动
```ts
// apps/api/src/workers/index.ts
import './txWorker';
// 可在独立进程启动：node dist/workers/index.js
```

OpenAPI 契约（示例片段）
```ts
// apps/api/src/types/api.d.ts
export type BalanceResponse = { network: string; address: string; balance: string; cached: boolean };
export type TxWatchRequest = { hash: string; network?: string };
export type TxStatusEvent =
  | { status: 'subscribed'; hash: string; network: string }
  | { status: 'pending'; hash: string }
  | { status: 'confirmed' | 'failed' | 'timeout' | 'error' | 'replaced'; hash: string; [k: string]: any };
```

## 事务与事件扩展（可选）

- 合约事件订阅
  - 使用 WebSocketProvider + contract.on(filter, listener)，后端 Worker 发布到 Redis，再由前端 SSE 接收
- 单飞缓存（避免缓存击穿）
  - 写入一个进行中标记，如 cache:lock:balance，其他请求等待或使用旧值


# 安全注意事项

- 私钥管理
  - 切勿在后端保存用户私钥；所有用户相关签名与交易均在浏览器钱包完成
  - 后端如需发起运营交易，使用托管签名服务（例如 HSM、KMS 或专用签名服务），并严格隔离权限与审计
- SIWE 安全
  - 验证 domain 和 nonce；绑定会话与地址；HTTP-only、SameSite cookie
  - 防重放：nonce 一次性与 5 分钟有效期；校验 chainId 与声明消息
- 交易与网络安全
  - 使用 EIP-1559 费用估算（ethers 的 estimateGas + maxFeePerGas / maxPriorityFeePerGas）
  - 检查 chainId 与网络匹配，避免在错误网络签名导致重放风险
  - 处理区块重组：设置确认阈值（>=1），重要业务建议 >=3
  - 交易替换检测：监控同账户+nonce 的最新交易，提示用户替换情况
- 后端防护
  - 速率限制与 DoS 防护（如 express-rate-limit / nginx 限流）
  - 输入校验与类型检查，防止注入与崩溃
  - CORS 严格限制来源；启用 TLS
  - Redis 使用密码与 TLS；避免在 Redis 中存储敏感个人信息
- 依赖与密钥
  - 管理 .env 不入库；使用 Secrets Manager
  - 定期审计依赖（npm audit），锁定版本，跟踪安全通告
- 监管与合规
  - 不提供投资建议；遵循所在司法辖区的 KYC/AML 要求（如系统涉及资金流）
  - 明确非托管模型与用户资产自主管理

# 部署运维指南

- 环境与配置
  - 必需变量
    - 前端：VITE_WALLETCONNECT_PROJECT_ID、VITE_SUPPORTED_CHAINS、VITE_RPC_MAP
    - 后端：PORT、REDIS_URL、SESSION_SECRET、RPC_HTTP_*、RPC_WS_*、CONFIRMATIONS
  - 示例前端 .env
    - VITE_WALLETCONNECT_PROJECT_ID=your_wc_project_id
    - VITE_SUPPORTED_CHAINS=11155111
    - VITE_RPC_MAP={"11155111":"wss://eth-sepolia.g.alchemy.com/v2/xxxx"}
  - 示例后端 .env
    - PORT=3000
    - REDIS_URL=redis://redis:6379
    - SESSION_SECRET=replace_me
    - RPC_HTTP_11155111=https://eth-sepolia.g.alchemy.com/v2/xxxx
    - RPC_WS_11155111=wss://eth-sepolia.g.alchemy.com/v2/xxxx
    - CONFIRMATIONS=2

- 部署方案
  - Docker Compose（示例）
    ```
    version: '3.8'
    services:
      redis:
        image: redis:7-alpine
        command: ["redis-server", "--appendonly", "yes"]
        ports: ["6379:6379"]
      api:
        build: ./apps/api
        env_file: ./apps/api/.env
        depends_on: [redis]
        ports: ["3000:3000"]
      web:
        build: ./apps/web
        env_file: ./apps/web/.env
        ports: ["5173:5173"]
    ```
  - 生产环境建议
    - 反向代理（Nginx）启用 TLS 与压缩、限流
    - 使用托管 Redis（TLS）与托管 RPC（Alchemy/Infura）
    - API 与 Worker 分离进程或服务，避免阻塞

- 监控与日志
  - 日志：pino 输出到 stdout；集中采集（ELK、Loki）
  - 指标：Prometheus 指标（请求量、延迟、队列积压、SSE连接数）
  - 告警：交易确认超时、RPC 错误率、Redis 连接异常

- 性能优化
  - 缓存策略：只读数据 TTL；热点键优先；防击穿与雪崩
  - 连接管理：WebSocketProvider 连接数受限，复用 provider
  - 队列吞吐：BullMQ 并发数可调，设置重试与退避策略
  - 前端：代码分割与懒加载；避免在 UI 线程进行繁重序列化

- 测试与发布
  - 单元测试：Vitest 覆盖钱包逻辑的抽象层与 API 服务
  - 集成测试：在本地 Hardhat 网络或测试网运行，验证 SIWE 与交易状态
  - 灰度发布：逐步放量，监控指标与错误
  - 回滚策略：保留上一个稳定镜像，快速切换

- 运营与支持
  - 文档：OpenAPI + 使用手册（钱包连接步骤、常见故障）
  - 变更管理：版本号语义化（SemVer），Changelog
  - 安全集成：定期密钥轮换与依赖升级，权限最小化原则

以上方案以 TypeScript、React、Vite、Express、ethers.js 与 Redis 为核心组件，覆盖从连接器实现、交易签名与状态跟踪，到后端编排与协作规范的完整流程。实际落地时，请根据目标侧链/测试网的 RPC 能力与延迟特性微调确认数与订阅策略，并在生产环境启用严格的安全加固与监控。