Web3 交易系统
系统架构

链上限量发售架构与实现(v0.6)

本页对应 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/权限/多节点、备份恢复演练、长期压测、公共测试网及合约独立审计。实际覆盖以本轮报告为准。

— 本篇阅读完毕 —
来源:Web3 交易系统 / docs / 02-architecture/flash-sale-design.md 下载原文
输入关键词,在三个知识库中搜索
支持正文检索 · 直接定位章节Esc 关闭