本页对应 flashsale/、cmd/saleserver/、FlashSale.sol 和活动页。发售与二级交易统一使用 RabbitMQ;早期 Kafka 架构审阅是历史资料。操作见验收手册,验证见测试说明。
业务与权威#
固定价发售已有标准 ERC20 MWETH/MUSDT:owner 预存 MWETH,用户用 MUSDT 购买,买方支付 Gas。每钱包每场至多一个资格,过期后本钱包不能重领,其他钱包可以领取回收额度。不支持 NFT、部分购买、资格转让、代付、跨链、退款或真人唯一识别。
1 lot = 10^14 base 原子单位 = 0.0001 MWETH;售价 10^6 quote 原子单位 = 1 MUSDT。uint256 以规范十进制字符串传输。合约 owner 与模拟管理员无自动关联。
sequenceDiagram participant U as 钱包 / 页面 participant A as 发售 API participant D as SQL 权威 participant Q as RabbitMQ participant W as 签名 Worker participant C as FlashSale participant I as 已确认索引 U->>A: 一次性签名登录 U->>A: quantity=1 + 请求键 A->>D: 库存、资格、请求键、outbox 同事务 D-->>A: commit A-->>U: 202 SIGN_PENDING D->>Q: persistent + mandatory + confirm Q->>W: delivery(手动 ack) W->>D: inbox/job commit W->>Q: ack W->>D: 固定 digest 签名 / CAS U->>A: 查询 CLAIMABLE 凭证 U->>C: approve / purchase C-->>U: 收款与交付原子完成 I->>C: 固定确认块 hash 拉取 Purchased I->>D: 事件、资格、库存、块、游标同事务 A-->>U: CONFIRMED |
发售独立进程、连接池和调度;二级撮合仍是单写者/FULL 日志,不向 Engine 引入 SQL 或网络。默认 SQLite 是显式本地演示;完整模式的库存权威是 PG。Redis 只限制入口,RabbitMQ 只分发任务,资金事实在合约。
数据与事务#
schema 1 包含 sale_metadata、sale_activities、sale_reservations、sale_requests、sale_outbox、sale_inbox、sale_sign_jobs、sale_message_errors、sale_events、sale_blocks/cursor、sale_challenges/sessions、sale_tx_observations、sale_audits。库绑定 chainId/contract/assets/signer/owner/confirmations/startBlock,跨域拒绝复用。
不变量:total = available + held + confirmed,三项非负。购买由 (9,1,0) 变为 (9,0,1);未用资格过期由 (9,1,0) 变为 (10,0,0)。SQL CHECK、条件 UPDATE 与对账一起约束。
先锁活动行,再查请求键与活动钱包唯一资格,生成不可变正文、扣可用/加占用、写请求与 outbox,同事务提交。成功点只有 commit。同钱包换键仍返回原资格;同键指向不同活动返回 409。请求键作用域为数据集数据库内 (wallet,key),不是仅单活动。PG 单活动是热点行;SQLite 先写锁再读,避免读事务升级竞争。多活动事件按稳定 ID 顺序取锁;跨活动同键竞争由唯一约束兜底,失败事务整体回滚。
身份与接口#
一次性 EIP191 登录文本绑定域名、URI、chainId、随机 nonce、签发与过期时间。挑战 5 分钟,会话 1 小时,数据库只存 token 摘要。Cookie 为 HttpOnly/SameSite Strict,HTTPS 下 Secure;所有写请求校验精确 Origin/dataset,登录后写另校验 CSRF。完整资格只能由所属钱包查询;当前只支持 EOA。
契约 api/sale-openapi.json,通过 /api/web3/sale-openapi.json 公开,前端类型由 openapi-typescript 生成。以下路径统一加 /api/web3:
| 方法与路径 | 用途 |
|---|---|
| GET /sale-config、/sale-status、/sales | 域、健康、活动 |
| POST /auth/challenges、/auth/sessions | 挑战与登录 |
| GET /auth/session;POST /auth/logout | 会话恢复/退出 |
| POST /sales/{id}/reservations | quantity=1、Idempotency-Key |
| GET /sales/{id}/reservation | 当前钱包资格恢复,未领取为 null |
| GET /sale-reservations/{id} | 所属钱包私有查询 |
| POST /sale-reservations/{id}/transactions | hash 观察,不能确认成交 |
| POST /admin/sales | owner 导入已确认、预存、未售出的链活动 |
owner 先独立创建链活动,确认后才能导入 SQL;没有完整活动编辑后台。配置开放后冻结,重复导入不重置库存。重启既有活动从 SQL 恢复,不要求再次满足零售出。
RabbitMQ 交付与恢复#
共享 messaging.Queue 使用官方 amqp091-go;默认交换机直接路由到持久 quorum 队列。交易/发售不同前缀,队列名追加 dataset。发布/消费 channel 分离,prefetch=16,消息 persistent,mandatory 路由,publisher confirm 后才标记 published。
confirm 前崩溃 outbox 重发;confirm 后、published 前崩溃可能重复。消费者提交 inbox/job 或稳定结算任务后才手动 ack;ack 前断连 broker 重投。连接重建声明相同队列,不删除消息。业务幂等来自 SQL 唯一键、稳定 ID 和合约 consumed/settled,不依赖 deliveryTag,也不承诺跨系统 exactly-once。
发售坏消息先写 sale_message_errors 再 ack;交易永久 JSON/签名错误 Nack 至持久 .dead 队列。SQL 暂时故障保持当前未 ack delivery 重试。quorum 的 delivery-limit=-1,避免临时重投次数导致有效任务被自动丢弃。死信不能触发释放库存或修改资金;重放需人工核对原域与 ID。
开发只有一个 RabbitMQ 节点和持久卷,不具有跨节点容灾。新增广播订阅者需要独立队列/交换机绑定;当前不是通用广播事件总线,也没有 Kafka offset/分区/group 语义。AMQP deliveryTag 仅在当前 channel 内有效。旧 broker 消息没有在线自动迁移工具。
状态与合约#
SIGN_PENDING → CLAIMABLE → CONFIRMED;两个非终态均可经过确认核验变为 EXPIRED。深重组采用数据集级持久冻结,停止新资格并保留查询;不会自动把每条资格改为 REVIEW_REQUIRED。Worker 不改正文/deadline,不复活过期资格。
EIP712 域 GoExchangeSale / 1 / chainId / FlashSale,正文含 activityId、reservationId、buyer、baseToken、quoteToken、quantityLots、totalQuoteAtomic、deadline、configVersion。合约校验调用者 buyer、固定 signer、活动条款、未 consumed、钱包限购、库存和严格大于块时间的 deadline。
合约采用 OpenZeppelin ReentrancyGuard/SafeERC20。创建要求真实收到足额标准 base;购买先写标记再收 quote/交付 base,任一步失败整笔回滚。owner 仅活动结束后一次提取剩余库存;暂停不绕过结束时间。合约不可升级、签名角色不可轮换,密钥轮换与授权撤销是后续工作。
索引与安全过期#
独立 startBlock、确认深度、连续父块与固定 blockHash 日志;每轮最多 64 块。事件/资格/库存/块/游标同事务,重复同 hash 幂等,未知资格或金额矛盾冻结。确认深度不等于所有 EVM 的协议级 finalized。
本地倒计时到零只停止发送新交易。必须已索引确认块 timestamp >= deadline,同 hash consumed=false,再核对该高度的规范块 hash,SQL 验证锚点 hash/timestamp 且无 Purchased 事件后才能 CAS 回收。RPC 不可用、不支持 EIP1898、索引滞后或锚点变化时不释放。
前端上报 hash 只作观察,终态来自扫描器。刷新通过钱包资格恢复;sessionStorage 按数据集/钱包/资格保存原键和交易观察。买方交易由钱包发出,后端不代为替换或取消。
资源与运维#
HTTP 并发 128,本地每 IP 100/s,Redis 每钱包 5/s,请求体 16 KiB。调用有超时,扫描批次有界。冻结、索引故障、确认块时间落后本地超过 20 秒、outbox 超过 500 时停止新资格;既有资格仍可查看和原键确认。不承诺严格 FIFO 公平或容量 SLA。
回环 /check 比较同一个 SQL 快照与同块 hash 的合约 sold;/metrics 展示索引高度、outbox/job、隔离消息、差异和 Worker 错误。无自动修资产或解除冻结工具。恢复要协调 SQL、已签凭证、未发布 outbox 和链锚点,落后备份不能直接恢复准入。
下一阶段:运营 UI、生产密钥、RabbitMQ TLS/权限/多节点、备份恢复演练、长期压测、公共测试网及合约独立审计。实际覆盖以本轮报告为准。