Web3 交易系统
开发与源码

链模式开发与本地运行

v0.6 已新增发售入口和 RabbitMQ;完整运行按手动验收,当前边界见进度。下文交易 dev 命令只启动二级市场;发售使用 run-sale-windows.cmd 同时启动两个服务。

当前基线:模拟 v0.3 保留,独立链模式升级为 v0.5。新增完整历史查询、任务版本保护、已确认事件索引、只读对账和基础告警,见 设计、执行报告。历史报告与证据保留原版本。

适用 v0.5 独立钱包模式,原模拟模式运行方式见项目README。本模式不使用管理员账户余额,注册/登录功能继续保留在模拟服务。范围、状态和权威见v0.5架构。

从干净依赖开始#

需要Go 1.26.9、Node22+、npm、浏览器;下面命令在项目根目录执行。只连接本次Anvil,首次下载需要网络。标准代理不可用时可单条命令指定 GOPROXY=https://goproxy.cn,direct,不改全局设置。

go mod download
npm --prefix contracts ci
npm --prefix contracts run compile
npm --prefix frontend ci
npm --prefix frontend run build
npm --prefix contracts run dev

访问 http://127.0.0.1:8081/?mode=web3 。脚本部署MockWETH、MockUSDT、Settlement;生成 bin/web3-dev/config.json,每次新建时间戳数据目录,不覆盖旧数据。Ctrl+C停止本次Go/Anvil子进程。端口8545/8081须空闲。每次Anvil新历史,旧数据不能复用,即使地址与chainID相同;数据库任务域还含dataset。

钱包增加本地RPC http://127.0.0.1:8545、链ID31337。仅导入 contracts/scripts/local.mjs 中公开Anvil测试key对应账户1和2;账户0专供relayer。这三个key属于公开fixture,不可用于公共链真实资产。两个测试钱包各有10MockWETH与100000MockUSDT,部署脚本已授权合约;页面授权按钮可重新授权。用不同钱包卖2WETH@100、买3WETH@105:先见pending2,再见filled2,实际支付200USDT;剩余1WETH买单可链上撤销。

Windows双击 run-web3-windows.cmd。脚本在 bin/windows-web3 安装独立平台依赖并构建页面,避免使用WSL的node_modules;原 run-windows.cmd 的pinkode管理员与data-windows保持独立。新脚本本轮未在Windows原生环境实测。

连接真实开发中间件#

先设置开发数据库密码,再启动指定compose的三个服务(不会创建应用容器)。开发端口均向回环绑定。

export WEB3_DB_PASSWORD='local-web3-password'
docker compose -f deploy/web3-compose.yaml up -d redis postgres rabbitmq
export WEB3_REDIS_URL='redis://127.0.0.1:16379'
export WEB3_POSTGRES_DSN='postgres://exchange:local-web3-password@127.0.0.1:15432/exchange?sslmode=disable'
export WEB3_RABBITMQ_URL='127.0.0.1:5672'
npm --prefix contracts run dev

这里密码仅演示;云部署必须另设。第一次库可为空;第二次本地dev重建Anvil与dataset时,创建新的PG数据库并改DSN,保留原库作恢复证据,不能删任务表来绕过域检查。未配置中间件时显式本地模式用独立SQLite任务、直接outbox分发、无Redis共享限流;配置了但故障会拒绝启动。

改代码的顺序#

  1. 修改业务约束时先列出四项数量守恒、重试/取消/未知广播影响,更新设计和用例。
  2. 合约改动先跑compile/test;修改签名字段时Go TypedData、Solidity TYPEHASH、前端和契约一起更新,换新合约及数据域。
  3. Engine只接收确定命令;新RPC/SQL/密码学放外围。修改Apply后对重放和兼容做判断,不隐式解释旧日志。
  4. API先改 api/web3-openapi.json,执行 npm --prefix frontend run web3:generate,不要手改生成TS。补真实响应校验。
  5. 运行 bash scripts/test.sh web3,再常规verify和真实中间件用例,按最终证据更新文档。

阅读路径:types→engine→store→tasks/middleware→chain→index/history/reconcile/observability→http→cmd/web3server→Web3App/Web3History→Settlement。新函数和关键字段均需中文注释,解释单位、所有者、恢复及错误边界;测试注释说明证明点,脚本注释说明资源隔离与清理。

配置#

环境变量 默认/含义
WEB3_CONFIG bin/web3-dev/config.json:公开链域,必须与合约getter一致
WEB3_DATA_DIR data-web3:不可复用模拟目录
WEB3_RPC_URL http://127.0.0.1:8545
WEB3_RELAYER_KEY 必填,与config relayer相符,只来自受限环境
WEB3_LISTEN_ADDR / WEB3_ALLOWED_ORIGIN 127.0.0.1:8081 / 对应http Origin
WEB3_FRONTEND_DIR frontend/dist
WEB3_DIAGNOSTICS_ADDR 空关闭;仅允许数值回环,例如127.0.0.1:9091
WEB3_POSTGRES_DSN 空为显式SQLite任务;非空PG权威
WEB3_REDIS_URL 空关闭Redis;非空缓存与共享限流
WEB3_RABBITMQ_URL / WEB3_RABBITMQ_QUEUE AMQP URL;空为显式本地直连;默认队列前缀 exchange-settlements,追加 dataset

配置confirmations在JSON中为1–128,默认fixture2;修改域或确认策略拒绝复用日志。固定inflight/历史/响应预算见架构;没有声称自动调参或全市场扩容。

v0.5 历史、对账和升级#

钱包页面底部“交易记录”支持四种类型、25条翻页、当前钱包筛选和任务详情。trades 只列 CONFIRMED 意图,刷新首屏才能收录刚确认的旧意图;翻页过程对象状态仍可能变化。

export WEB3_DIAGNOSTICS_ADDR=127.0.0.1:9091
npm --prefix contracts run dev
# 另一个终端:
curl http://127.0.0.1:9091/check
curl http://127.0.0.1:9091/metrics
curl 'http://127.0.0.1:8081/api/web3/history/orders?limit=25'

已有同域 v0.4 数据升级前停机备份,不删库。任务 schema 2 事务迁移并赋 version=0,不改旧 raw/hash/nonce;历史没有记录的时间仍为0。chain-views 补索引表,从创世开始补拉已确认块,索引未追平先显示 lag。日志 schema 与 Domain JSON 不变,确认策略/合约变更仍须新域方案。新结构运行后回退旧二进制会遗漏版本维护,禁止直接回退;恢复停机备份并先人工核对已广播交易。

独立读池:日志/投影的 WAL 读取与唯一写连接分开,每读池1连接;SQLite读池query_only,PG任务Reader独立1连接,owner与任务写池仍分别占用专用/业务连接。TestReadSnapshotDoesNotBlockWriter 保持旧水位快照时仍能完成新命令,避免对账占住唯一写池。查询仍有CPU/磁盘与WAL保留成本,需要超时和后续增量策略。

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