Web3 Starter

受众：开发者摘要：Web3 starter 顶层入口。EVM 链能力、Token / NFT、事件扫描、Web3 支付的导航与边界声明。详细能力在专题文档。

何时使用

场景	进入文档
EVM 钱包验签 / Typed Data / 地址工具	web3-wallet.md
只读 RPC / 健康诊断 / 浏览器链接 / 合约只读调用 / 事件日志查询	web3-rpc.md
ERC-20 / 721 / 1155 只读 + 写交易辅助 + 批量编排 + 金额换算 + 地址本	web3-token.md
单笔签名 / 广播 / 批量转账 / 资金归集 / 支付转账事件匹配	web3-transfer.md
区块扫描窗口 / 事件扫描编排 / 扫描器注册表 / 检查点持久化 / 自动扫描	web3-event-scan.md
Web3 支付服务商/ 链上确认 / 试算（dry-run）结算计划 / 复核审计 / 显式结算（settle）	web3-payment.md
Token 价格（PancakeSwap V2 Router / 池子）/ DEX 池子只读	web3-dex.md
`/api/v1/open/web3/**` 开放平台 + 后台 Token / NFT 只读运维	web3-open-platform.md
生产 RPC 接入 / 节点排查 / 上线 smoke 检查清单	web3-production.md
链上事件补偿任务（完整运行边界 / 失败处理）	web3-event-compensation.md
Web3 支付自动结算（状态机 / 幂等 / 链重组 / 人工复核）	web3-payment-settlement.md

业务模块不直接依赖 Web3 SDK，也不在 Money / Cashier 等核心业务模块直接引入 org.web3j。

术语口径

Web3 模块面向中国开发者和运营人员时，页面、提示、文档说明和 OpenAPI 描述优先使用中文主词；代码类名、字段名、接口路径和链上协议名作为机器契约保持稳定，不作为用户可见旧称展示。

中文主词	代码 / 接口内固定术语	使用场景
链上兑换	swap	用户侧入口、订单、预估、错误提示
跨链桥 / 跨链订单	bridge	托管资金池桥路线、订单和后台运维
出金钱包 / 出金私钥	vault / private key	平台侧放款、退款和余额门控
报价服务商 / 支付服务商	provider	DEX、支付、外部链能力服务商
交易哈希	txHash	链上交易唯一标识
交易回执	receipt	链上交易执行结果
交易序号	nonce	EOA 顺序交易号和跨链桥放款 / 退款恢复
交易调用数据	交易调用数据	钱包待签名的合约调用参数
滑点基点	bps	滑点和价格影响单位
试算	dry-run	不签名、不广播、只生成结算计划

已具备的能力

EVM 链能力：personal_sign 钱包验签、EIP-712 Typed Data 验签、地址校验 / 规范化 / EIP-55 checksum
只读 RPC：链 ID / 高度 / Gas / 余额 / 地址巡检 / 合约代码 / 交易计数 / Gas 预估 / 交易 / 回执 / 原始 eth_call
链路健康诊断：连通性 / chain-id 匹配 / 高度 / Gas Price
多 RPC 节点：rpc-urls（可公开）+ private-rpc-urls（运行时私有），失败自动切换 + 历史低延迟节点优先
合约 ABI：编解码 + 方法级只读调用（原子类型 / 一维 / 多维数组 / 一层 tuple / 一维 / 多维 tuple 数组）
事件：日志查询 / indexed topic 编码 / ERC-165 识别 / 常见 ABI 事件解码
扫描：区块扫描窗口 + 事件扫描编排 + 扫描器注册表 + Money Web3 自动扫描 + 检查点持久化 + 失败通知
Token：ERC-20 / 721 / 1155 只读 + 写交易辅助 + 批量编排
NFT：Transfer 事件查询 + 持有人 / tokenURI / 授权 / 全量授权
Token 金额：原始单位 / 显示单位换算（Web3Amounts）
写交易：EVM 原生签名 / 广播 / 签名后发送，默认只签名显式开启才广播
批量：批量转账 + 多钱包资金归集（默认计划，显式开启广播）
Web3 Payment：创建链上收款上下文 + 复用交易确认查询支付状态
价格：默认 pancake-v2 Router 报价 + pancake-v2-pool 储备降级
DEX：池子储备 / 流动性 / 手续费后输出 / 最小输出 / 价格影响基点，Pancake V2 流动性报价支持 native coin / Wrapped Native Token 场景
链上兑换报价 Pipeline：core-web3 可选接入 money.web3.swap.quote.preview，内置 money-web3-swap-token-risk-precheck 和 money-web3-swap-dex-quote 两个步骤；Pipeline 未启用或未注入时保持原直接报价路径
安全域契约：starter-web3 提供 route kind、订单状态、交易追踪状态、风险级别 / 原因、chain / token / route / tx / order / admin operation 快照、Web3SecurityAssessment、Web3TransactionSafetyAssessments 和 Web3AdminOperationSafetyAssessments；core-web3 链上兑换报价已合并 Token 列表安全快照、自定义 ERC-20 metadata 解析、黑名单 / 禁用 / 风险标签阻断或人工复核，交易输入、交易回执和交易确认结果已返回统一 securityAssessment，Token 列表已提供安全快照只读入口，Admin 高风险操作已提供安全元数据只读入口，Admin 链列表和 Token 列表页已接入该元数据展示操作类型、执行模式、防护项、暂停范围和广播出款示例评估
托管资金池跨链桥契约：core-web3 已提供跨链桥路线、出金钱包、报价、订单和用户提交源链入金交易哈希的基础接口；第一版使用双边出金钱包和人工 / 自动后续处理，不是去信任化跨链桥
地址本 + 元数据缓存：低频地址 + 静态 Token 元数据（name / symbol / decimals）
Open Platform Web3 v1：链信息 / 余额 / Token / 授权 / 钱包 / Gas / 交易 / 事件 / 价格 / 批量转账 / 资金归集
链 / Token 业务列表：后台维护 Web3 链列表、Token 列表、充值 / 提现 / 支付 / 结算 / 分销打款准入、Token 精度 / 限额 / 固定提现手续费 / 百分比提现手续费 / 手续费代币、链运行时 RPC 节点；Token 必须归属一个已启用链列表，同名 / 同符号 Token 在不同链上是不同资产；新增 ERC-20 Token 时选择链列表并输入合约地址即可快捷读取链上 name / symbol / decimals，确认后保存；新增 Token 的分销打款默认关闭，必须由运营显式开启；手续费代币按同链 withdrawFeeTokenKey 配置，不选时默认当前 Token；GET /api/v1/admin/web3/token-registry/{id}/security-snapshot 会读取 Token 列表和 metadataJson 输出官方 / 自定义标识、风险标签、风险等级、阻断状态和人工复核提示
后台运维：交易巡检、事件搜索、只读合约调试、Token 价格查询、扫描检查点、扫描日志、Web3 支付确认 / 结算审计
非 EVM 链契约首段：支持 Solana / TON / Bitcoin / Tron / Aptos / Sui 链类型常量、本地格式级地址校验和链能力摘要查询；配置非 EVM 链时会进入链列表和能力查询，但 RPC、签名、合约调用、事件扫描和 Token 读写仍明确为 unsupported，等待链专属服务商接入

设计边界

Web3 SDK 依赖只放 spring-open-starter-web3
Money Web3 模块只依赖 Web3 starter 暴露的项目抽象，不直接用 web3j
Cashier / 支付服务商通过 Web3 starter 的抽象能力接入链上支付，不直接引入 Web3 SDK
EVM 地址格式校验 / 规范化 / checksum 由 EvmAddresses 承担，业务模块不重复实现
写交易当前限于 EVM 原生签名 / 广播 / ERC-20 / ERC-721 / ERC-1155 常用 / Token 批量编排 / 批量转账 / 资金归集
框架默认不托管私钥；写交易签名通过 Web3TransactionSigner SPI 执行，默认本地实现兼容请求参数 / 配置兜底私钥，生产可替换为 KMS、Vault 或外部签名服务
Typed Data 验签只证明签名和地址匹配，不负责业务字段可信性校验
RPC URL 不硬编码到代码，用环境变量 / 本地配置 / 数据库配置 / Web3 链列表维护
EVM 验签不接入 RPC、不处理私钥、不记录签名以外的敏感材料
链列表同时承担业务准入和运行时 RPC 目录职责；目录中的 rpcUrls / privateRpcUrls 会作为 spring.open.web3.chains.<chain>.rpc-urls/private-rpc-urls 运行时配置来源，rpcConfigKey 继续保留外部配置引用语义
Token 列表必须绑定已启用链列表；native 资产使用 tokenKey=native，ERC Token 使用规范化合约地址作为 tokenKey，资产唯一性按 chainName + tokenType + tokenKey 判断；业务模块应优先读取目录开关判断是否允许充值、提现、支付、结算或分销打款
Token 列表安全快照复用 starter-web3 风险语义：metadataJson 可写入 custom / customToken、official / officialToken、riskTags / risk_warnings、blacklisted / blocked；禁用、黑名单或合约 / 符号 / 精度不完整会返回 critical 且 blocked=true，自定义 Token 返回 watch，带风险标签返回 warning 且 manualReviewRequired=true
非 EVM 链当前只提供配置入目录、地址格式校验和 Web3.chainCapability(chain) 能力摘要；不要把占位链当成可读余额、可签名或可扫描的真实链客户端
链上兑换报价 Pipeline 只承载短同步预览步骤：Token 风险预检和 DEX 报价。Pipeline 中断会转换为 Web3 业务异常；订单创建、订单状态、交易调用数据/ 授权（approval）快照、交易哈希绑定、交易回执最终性和链上副作用仍由 core-web3 Service 控制。
链上兑换 / 流动性 / 跨链桥 / 组合路由的安全提示必须复用 com.springopen.starter.web3.security 下的风险级别、风险原因和状态语义；用户侧按 securityAssessment.riskLevel / securityAssessment.riskReasons / securityAssessment.blocked / securityAssessment.manualReviewRequired 做展示和拦截，不在各页面自定义另一套风险枚举
交易输入、交易回执和交易确认结果的 securityAssessment 已覆盖授权（approve）/ 交易调用数据预览、交易有效期（deadline）、交易哈希绑定、交易回执最终性和可恢复订单状态；前端和业务编排应优先使用该字段判断提示、阻断和人工复核，不重复解析底层交易字段
Admin 托管、私钥、出金钱包、出款、官方池和跨链桥目标链释放等高风险操作必须复用 GET /api/v1/money/web3/chains/admin-operation-security/metadata 暴露的操作类型、执行模式、防护项、暂停范围和风险原因；涉及 broadcast、托管资产或私钥的操作必须绑定 RBAC、审计、二次确认、审批工作流、限额、暂停开关和密钥脱敏，不在页面本地硬编码另一套枚举
Admin 链列表和 Token 列表页已真实读取 admin-operation-security/metadata：链列表用于展示操作类型、执行模式、必备防护和广播出款示例；Token 列表用于展示暂停范围、高风险操作和示例风险原因。后续托管、出金钱包、出款或官方池页面应继续复用该接口，不复制安全枚举。

节点边界

rpc-urls：可公开节点列表（公有 / 调试 / 开放平台允许返回给第三方）
private-rpc-urls：运行时私有节点（付费 / 内网 / 自建 / 生产核心）
运行时优先用 private-rpc-urls，为空回退 rpc-urls
节点首次使用会记录耗时；后续优先使用历史成功延迟低的节点，失败 / 超时会降权并自动切下一节点
RPC 业务错误不盲目切换，避免合约错误误判为节点异常
开放平台链信息接口只返 rpc-urls；配置类和运行时快照中的 private-rpc-urls 用 @JsonIgnore 兜底
给第三方开发者用：可公开、可限流节点放 rpc-urls，不把生产支付 / 扫描 / 结算节点放进去

快速开始

完整版聚合 starter 已包含 Web3：

xml

<dependency>
    <groupId>com.springopen</groupId>
    <artifactId>spring-open-starter-web3</artifactId>
</dependency>

最小配置（BSC 主网）：

yaml

spring:
  open:
    web3:
      enabled: true
      default-chain: bsc
      chains:
        bsc:
          enabled: true
          chain-type: evm
          chain-id: 56
          rpc-urls:
            - https://bsc-dataseed.bnbchain.org
          private-rpc-urls: []
          native-currency: BNB
          block-explorer-url: https://bscscan.com

读链头：

java

Web3ChainClient client = Web3.client("bsc");
BigInteger blockNumber = client.blockNumber();

详细配置见各专题文档。

托管资金池跨链桥

跨链桥第一版面向 Besu(EVM) ↔ BSC 等双边托管资金池场景。后台先维护 money_web3_bridge_route 路由，包含源链 / 目标链、源 Token / 目标 Token、源出金钱包 / 目标出金钱包、固定费 / 费率、单笔限额、人工复核阈值、确认数和订单 TTL。用户侧接口只生成报价和订单，不直接签名、不广播、不释放目标链资金。

初始化数据已经预置三条常用链列表：bsc、ethereum、besu。其中 BSC 和 Ethereum 带有原生资产、USDT、默认 DEX 配置和链上兑换路由策略；Besu 默认作为私有链 / 本地链模板启用，RPC 和浏览器地址指向本地默认值，USDT 合约、跨链桥出金钱包等关键资金配置默认留空，管理员按自己的 Besu 网络填写后即可投入联调。

跨链桥默认预置并启用一个模板路线：bsc-usdt-to-besu-usdt-template。该模板用于 BSC USDT 到 Besu USDT 的托管资金池桥，目标 Token 合约、源链出金钱包、目标链出金钱包默认留空。管理员必须填写真实地址并确认目标链出金钱包有足额流动性后，报价、下单、放款才会正常进入业务流程；关键地址未配置时，后端会返回明确的“关键配置未完成”提示。私钥不写入路线配置；后台放款 / 退款可临时输入本次请求私钥，也可通过 spring.open.money.web3.bridge.transfer.* 配置兜底。生产环境仍建议使用配置中心、环境变量、外部签名、Vault 或硬件托管，避免把私钥固化在业务数据里。

跨链桥访问控制内置黑名单 / 白名单两类策略。黑名单默认开启，白名单默认关闭；规则支持按钱包地址、用户 ID、路线编码、链名称和 Token 地址精确匹配，并可限定路线、源链、目标链和过期时间。报价、创建订单、绑定入金交易哈希、目标链放款和重试放款都会执行访问控制；命中黑名单会拒绝请求，开启白名单后未命中白名单会拒绝请求。源链退款属于恢复动作，内置黑名单 / 白名单不会阻断退款，避免用户入金后因名单变更导致资金无法退回；业务方如需冻结退款，可在 SPI 中识别 stage=refund 并显式返回 deny。SPI 服务商返回 review 时，报价 / 下单阶段会进入人工复核，入金绑定、目标链放款和重试放款等执行阶段会阻断当前操作，避免复核要求被资金动作绕过；退款阶段的 review 不会阻断恢复退款。业务方可实现 MoneyWeb3BridgeAccessPolicyProvider 扩展额外风控、企业名单、外部合规或 KYC 策略。

跨链桥结算走「Queue 即时推进」：用户绑定源链入金 depositTxHash 后，后端延时 10 秒投递一次跨链桥确认 Queue 任务（不再干等固定定时周期，也避免刚提交的交易回执 / 日志尚未可查）；源链确认达标后，若开启门控自动放款，则对通过守卫的安全单自动从目标链出金钱包放款；放款 / 退款签名后会先持久化确定交易哈希，再广播已签名原始交易（raw signed transaction），广播后也会延时 10 秒投递同一个确认任务，推进目标链放款或源链退款回执同步到完成。固定间隔调度默认关闭，仅在特殊部署需要周期补扫时通过 auto-startup=true 显式开启；后台人工放款 / 重试 / 复核 / 退款保留为异常恢复入口。用户侧只需轮询订单状态展示进度（已提交 → 源链确认中 → 目标链放款中 → 完成）。

放款 / 退款按「预留出金钱包交易序号（nonce）→ 领取（独立提交，原子推进 target-releasing / refunding 并释放行锁）→ 签名并写交易哈希（独立提交）→ 广播已签名原始交易（raw signed transaction）→ 同步回执」执行，保证同一订单只放款 / 退款一次：并发的重复点击、自动放款任务和多节点都只有一方领取成功，其余幂等返回不再广播；领取时会把出金钱包交易序号（nonce）持久化到订单，并通过 money_web3_bridge_nonce_reservation 保证同一链 / 出金钱包 / nonce 只分配给一个结算动作。系统不持久化已签名原始交易（raw signed transaction），避免数据库泄露即可广播资金交易；如果广播失败、进程退出或后续链上查不到已记录交易哈希，确认任务会优先用持久 nonce 同 nonce 重新签名并广播恢复；链上会把相同 nonce 视为同一笔账户序列，不会变成第二笔独立出账。只有历史无 nonce 在途单、服务商无法返回交易哈希或链上状态需要人工判定时，才进入后台人工交易哈希恢复。

管理员最少需要关心这些关键配置：

配置	用途
`SPRING_OPEN_WEB3_PAYMENT_RECEIVER_ADDRESS`	Web3 支付真实收款钱包。默认空，不会误导用户付款到内置地址
`SPRING_OPEN_WEB3_CHAINS_<CHAIN>_ENABLED` / `CHAIN_TYPE` / `CHAIN_ID` / `NATIVE_CURRENCY`	链启用状态、链类型、链 ID 和原生币符号；`<CHAIN>` 对应 `BSC`、`BESU`、`ETHEREUM` 等本地预置链
`SPRING_OPEN_WEB3_CHAINS_<CHAIN>_RPC_URLS` / `PRIVATE_RPC_URLS`	公共 / 私有 RPC 节点列表，支持逗号分隔；旧的单节点 `RPC_URL` / `PRIVATE_RPC_URL` 仍作为默认兼容入口
`SPRING_OPEN_WEB3_CHAINS_<CHAIN>_BLOCK_EXPLORER_URL` / `CONNECT_TIMEOUT` / `READ_TIMEOUT`	区块浏览器地址、RPC 连接超时和读取超时
`SPRING_OPEN_WEB3_TREASURY_ADDRESS`	后台地址本中的财务钱包地址。默认空，启用前由管理员填写
`SPRING_OPEN_MONEY_WEB3_BRIDGE_TRANSFER_PRIVATE_KEY`	跨链桥后台放款 / 退款请求未传私钥时的兜底私钥。默认空，生产建议优先接外部签名或密钥托管
`SPRING_OPEN_MONEY_WEB3_BRIDGE_AUTO_PAYOUT_ENABLED`	是否开启源链确认达标后的门控自动放款。默认 `true`，管理员完成跨链路线、出金钱包、签名私钥 / 外部签名和目标链余额等关键配置后，安全单即可自动完成放款；金额超阈值 / 命中风控 / 出金钱包余额不足 / 缺签名配置等异常单仍保持人工。需要严格人工审核模式时显式设为 `false`。放款并发安全：链上广播前对订单做原子领取（条件化状态推进 + 行锁），管理员重复点击、自动放款任务与多节点并发都只放款一次，绝不重复出款
`SPRING_OPEN_MONEY_WEB3_BRIDGE_AUTO_PAYOUT_LIMIT`	单次最多自动放款 / 放款确认的订单数。默认 `50`
后台跨链路线中的 `targetTokenAddress` / `sourceVaultAddress` / `targetVaultAddress`	BSC → Besu 跨链桥真实 Token 合约和两端出金钱包地址。默认空值会被后端拦截

接口	用途
`GET /api/v1/money/web3/bridge/routes`	查询启用跨链桥路由
`POST /api/v1/money/web3/bridge/quote`	按路由、钱包、目标收款地址和源链入金额计算手续费、预期到账、出金钱包地址和浏览器链接
`POST /api/v1/money/web3/bridge/composite-quote`	生成源链可选兑换、托管跨链桥、目标链可选兑换的组合路线报价和三段明细
`POST /api/v1/money/web3/bridge/orders`	创建跨链订单快照，状态为 `waiting-deposit` 或 `manual-review`
`POST /api/v1/money/web3/bridge/composite-orders`	基于组合报价创建三段执行计划快照，记录源链兑换、跨链桥、目标链兑换的初始状态和恢复动作
`GET /api/v1/money/web3/bridge/composite-orders/{orderNo}`	查询当前用户自己的组合路线订单详情
`POST /api/v1/money/web3/bridge/orders/{orderNo}/deposit-tx`	用户广播源链入金后绑定 `depositTxHash`，订单立即进入已提交状态并返回
`POST /api/v1/money/web3/bridge/orders/{orderNo}/deposit-tx/sync`	按已绑定交易哈希手动重试读取源链交易回执 / 确认数，校验原生币转账或 ERC-20 `Transfer` 的付款地址、收款地址和金额
`GET /api/v1/money/web3/bridge/orders/{orderNo}` / `GET /api/v1/money/web3/bridge/orders`	查询订单详情和分页

后台运维接口位于 /api/v1/admin/web3/bridge：

接口	用途
`GET /routes` / `GET /routes/{id}`	分页和详情查询跨链路线
`POST /routes` / `PUT /routes/{id}`	创建或修改跨链路线，维护源链 / 目标链、Token、出金钱包、手续费、限额、确认数、TTL 和排序
`POST /routes/{id}/enable` / `POST /routes/{id}/disable`	启用或停用跨链路线
`DELETE /routes/{id}` / `DELETE /routes`	删除或批量删除跨链路线
`GET /routes/{id}/vault-snapshot`	查询路线源 / 目标出金钱包链上余额、待处理金额、退款待处理金额和订单状态汇总
`GET /orders` / `GET /orders/{orderNo}`	分页和详情查询跨链订单
`POST /orders/{orderNo}/manual-review/approve`	通过人工复核，订单回到等待源链入金或已提交入金状态
`POST /orders/{orderNo}/manual-review/reject`	驳回人工复核，订单进入 `failed` 并记录原因
`POST /orders/{orderNo}/payout`	源链确认后从目标链出金钱包放款，私钥仅本次请求使用，不持久化、不回显
`POST /orders/{orderNo}/payout/retry`	无目标链交易哈希时重新广播；已有交易哈希时只同步回执，避免重复出款
`POST /orders/{orderNo}/payout/sync`	同步目标链放款交易回执 / 确认数，确认后置为 `succeeded`
`POST /orders/{orderNo}/refund`	目标链放款失败或人工需要退款时，从源链出金钱包退回用户钱包
`POST /orders/{orderNo}/refund/sync`	同步源链退款交易回执和确认数，确认后置为 `refunded`
`GET /access/settings` / `PUT /access/settings`	查询和保存跨链桥黑名单 / 白名单开关
`GET /access/rules`	分页查询跨链桥访问规则，可按策略、对象、路线、链和启用状态筛选
`POST /access/rules` / `PUT /access/rules/{id}`	创建或修改访问规则，维护匹配对象、范围、原因、过期时间和排序
`POST /access/rules/{id}/enable` / `POST /access/rules/{id}/disable`	启用或停用访问规则
`DELETE /access/rules/{id}` / `DELETE /access/rules`	删除或批量删除访问规则

Admin 控制台已提供 /web3/bridge-admin 运维页，复用上述订单接口展示订单列表、详情、源链 / 目标链确认进度、入金 / 放款 / 退款交易哈希和失败原因，并提供人工复核通过 / 驳回、目标链放款、放款重试 / 同步、源链退款 / 同步操作。该页也已接入 routes / vault-snapshot contract，可维护路线启停、创建 / 编辑、删除 / 批量删除，并查看源 / 目标出金钱包余额、待处理金额、退款待处理金额和订单状态汇总；访问控制区可维护黑名单 / 白名单开关、规则查询、新增 / 编辑、启停、删除和批量删除。放款和退款表单可填写本次请求私钥、交易序号（nonce）、gas price 和 gas limit；私钥留空时会使用后端跨链桥转账配置兜底，不持久化、不回显私钥。领取后的在途单默认由后台确认任务按订单持久 nonce 自动恢复；已广播交易哈希仍保留为异常恢复入口：历史无 nonce、服务商无法返回交易哈希或需要人工链上判定时，管理员可先人工确认链上是否已广播，再填入交易哈希绑定回订单并继续同步确认；系统会校验该交易哈希确为本单的目标链放款（出金钱包 → 收款地址、目标代币、金额=预计到账）或源链退款（出金钱包 → 用户钱包、源代币、金额=入金额），不匹配会拒绝绑定，避免误填无关交易把订单错误标记为完成。

后台菜单初始化后位于 资产与 Web3 下，常用配置入口包括：Web3 链列表、Web3 Token 列表、Web3 Token 行情 和 Web3 跨链桥管理。Web3 链路运维 用于查看运行时链健康和诊断，不用于保存业务列表。

用户侧 App 钱包兑换页和 PC 账户余额页已接入跨链桥入口：默认展示后台启用路由，也允许用户手动输入源链 / 目标链、源 Token / 目标 Token 合约地址、源链钱包地址和目标链收款地址；用户先获取报价，再创建订单，广播源链入金后绑定 depositTxHash，后续由后台异步确认，也可手动重试同步。订单列表会展示源链确认数、源链入金交易哈希和当前跨链状态。

绑定 depositTxHash 不再同步等待源链确认。接口只完成订单归属、访问控制和交易哈希绑定，然后返回 deposit-submitted；同一条源链入金交易哈希受 (source_chain_name, deposit_tx_hash) 唯一约束保护，并发也无法绑定到两个订单，杜绝一笔入金被重复放款；后台 spring.open.money.web3.bridge.deposit-confirmation.* Queue 任务会确认待处理订单，避免 12 次确认或 RPC 卡顿让用户请求长时间阻塞。单笔订单自动确认遇到 RPC / event log 等技术异常时会累加连续异常次数，达到 max-attempts 后后续自动任务不再扫描该订单，避免同一异常单反复刷日志；手动同步接口仍可用于用户主动刷新或管理员排障，成功同步后异常计数会清零。放款广播成功但目标链交易回执尚未达标时，也会延时 10 秒投递该任务补扫目标链确认，不需要等固定间隔调度；补扫只同步已持久化 payoutTxHash 的在途单，不重新进入放款广播，重复触发会被 payoutTxHash / 状态 / 领取守卫短路，避免重复出金。若放款 / 退款已签名落库交易哈希但广播失败或链上查不到该交易哈希，任务会先按订单持久 nonce 同 nonce 重新签名广播恢复；仍无法自动恢复的异常单再由管理员通过后台填写已广播交易哈希恢复。

跨链桥入金确认任务默认启用 Queue 处理，固定间隔调度默认关闭：

配置	默认值	说明
`spring.open.money.web3.bridge.deposit-confirmation.enabled`	`true`	是否注册源链入金异步确认任务
`spring.open.money.web3.bridge.deposit-confirmation.auto-startup`	`false`	是否额外注册固定间隔调度；默认关闭，主路径为 Queue 延迟确认
`spring.open.money.web3.bridge.deposit-confirmation.task-name`	`money.web3.bridge.deposit-confirmation`	调度任务名称
`spring.open.money.web3.bridge.deposit-confirmation.instance-id`	`default`	单实例任务标识
`spring.open.money.web3.bridge.deposit-confirmation.fixed-delay`	`1m`	显式开启固定调度后的每轮确认间隔
`spring.open.money.web3.bridge.deposit-confirmation.limit`	`50`	每轮最多扫描订单数
`spring.open.money.web3.bridge.deposit-confirmation.required-confirmations`	`12`	路线或历史订单未指定源链确认数时使用的默认确认数，可用 `SPRING_OPEN_MONEY_WEB3_BRIDGE_DEPOSIT_CONFIRMATION_REQUIRED_CONFIRMATIONS` 覆盖
`spring.open.money.web3.bridge.deposit-confirmation.max-attempts`	`3`	同一订单入金自动确认连续技术异常的最大次数；达到后自动任务不再扫描该订单

跨链桥自动放款默认开启，目标是让生产配置路径更直接：管理员完成跨链路线、出金钱包、签名私钥 / 外部签名和目标链余额等关键配置后，安全单即可从源链确认自动推进到目标链放款，不需要再额外打开隐藏开关。自动放款仍只对通过金额、风控、访问策略、出金钱包签名和目标链出金钱包余额门控守卫的安全订单生效；需要严格人工审核模式时可显式关闭。出金钱包余额门控会在放款广播前校验目标链出金钱包 token 余额扣减同出金钱包在途放款占用后是否足额覆盖该订单预计出款，不足则跳过该单留人工，避免出金钱包欠资时反复广播注定链上回滚的放款交易浪费 gas；该门控只作用于自动放款（尽力而为，不替代链上回滚兜底），后台人工放款由管理员判断、不受此门控：

配置	默认值	说明
`spring.open.money.web3.bridge.auto-payout.enabled`	`true`	是否开启源链确认达标后的门控自动放款，可用 `SPRING_OPEN_MONEY_WEB3_BRIDGE_AUTO_PAYOUT_ENABLED` 覆盖；显式设为 `false` 时进入严格人工审核 / 人工放款模式
`spring.open.money.web3.bridge.auto-payout.limit`	`50`	单次最多自动放款 / 放款确认的订单数，可用 `SPRING_OPEN_MONEY_WEB3_BRIDGE_AUTO_PAYOUT_LIMIT` 覆盖

跨链桥放款 / 退款私钥配置：

配置	默认值	说明
`spring.open.money.web3.bridge.transfer.private-key`	空	后台放款 / 退款请求未传 `privateKey` 时使用的全局兜底私钥，可用 `SPRING_OPEN_MONEY_WEB3_BRIDGE_TRANSFER_PRIVATE_KEY` 覆盖
`spring.open.money.web3.bridge.transfer.private-keys`	`[]`	JSON / YAML 列表，可按 `chain` 和 `fromAddress` 配置不同出金钱包地址私钥；匹配越具体优先级越高

跨链桥转账私钥属于运行期敏感配置：后台手动放款 / 退款和自动放款任务都会按“本次请求 privateKey → 配置中心 spring.open.money.web3.bridge.transfer.private-keys → 配置中心 spring.open.money.web3.bridge.transfer.private-key → 本地 application.yml / 环境变量绑定值”的顺序解析。也就是说，在配置中心写入上述两个 key 后，无需重启即可影响后续放款动作；JSON 列表解析失败时会记录 warn 并回退本地绑定值，避免配置错误把所有放款链路打断。

底层链签名统一委托 Web3TransactionSigner。默认 LocalPrivateKeyTransactionSigner 会按上述顺序解析到的私钥在进程内完成 EVM 签名；生产环境如果要接 KMS、Vault、HSM 或机构托管签名服务，只需要声明自定义 Web3TransactionSigner Bean，跨链桥放款 / 退款、批量转账和资金归集都会自动走替换后的签名器。

也可以使用 starter 内置的 HTTP 签名网关适配器，把 KMS / HSM / Vault / 机构托管服务统一包成一个内部 HTTP signer：

配置项	默认值	说明
`spring.open.web3.signer.provider`	`local`	`local` 使用默认本地私钥签名；`external-http` 使用外部 HTTP 签名网关
`spring.open.web3.signer.external-http.endpoint`	空	外部签名网关地址，启用 `external-http` 时必填
`spring.open.web3.signer.external-http.authorization-header-name`	`Authorization`	认证头名称
`spring.open.web3.signer.external-http.authorization-value`	空	认证头值，建议通过环境变量或密钥平台注入
`spring.open.web3.signer.external-http.timeout`	`10s`	调用签名网关超时时间

HTTP 签名网关收到的是规范化交易签名请求（链、from、to、value、data、nonce、gas、chainId），返回 rawTransaction 和可选元数据。框架会继续校验 signer 返回的 from / to / chainId / value / nonce / gas 与请求一致，避免签名服务误签其他交易。

数据库存储私钥的本地加密

私钥进配置中心数据库时支持本地 AES 加密存储，避免数据库 / 备份泄露即暴露明文私钥。加密只用框架内置的 core-secret 本地 AES-GCM，不依赖任何第三方 KMS / Vault 服务：

配置	默认值	说明
`spring.open.money.web3.bridge.transfer.encryption-secret`	空	私钥加密主密钥，只从应用环境（env / `application.yml` / `.env`）绑定，绝不入业务库；可用 `SPRING_OPEN_MONEY_WEB3_BRIDGE_TRANSFER_ENCRYPTION_SECRET` 注入

解析侧透明解密：MoneyWeb3BridgeRuntimeConfigResolver 解析到的私钥若是 enc:v1: 密文信封，用主密钥本地解密为明文供签名；若是明文则直通。开发期把私钥明文写 env、不配主密钥即可，明文照常生效。
后台加密入库：PUT /api/v1/money/web3/bridge/transfer/private-key（权限 money:web3:chain-registry:update）接收明文私钥，服务端用主密钥加密为信封后写入配置中心默认命名空间的 spring.open.money.web3.bridge.transfer.private-key。明文私钥不回显、不写日志、不入业务表。未配置主密钥时该接口直接报错，绝不把明文私钥落库。
来源优先级数据库 > env：配置中心写入的（密文）私钥优先于本地 env 绑定值，与上面的解析顺序一致。开发推荐 env 明文（快），生产推荐后台加密入库（密文留库、主密钥经 K8s Secret / 环境变量注入，二者分离）。
主密钥缺失但库里是密文信封时解析会直接报错（而不是静默放空私钥），避免主密钥漏配导致放款链路用错配置。

Money Web3 当前配置中心生效边界如下：

范围	配置中心是否生效	读取路径
Web3 链列表派生的 `spring.open.web3.chains.<chain>.*` RPC / chain-id / explorer 等运行期值	是	`MoneyWeb3RegistryRuntimeConfigSource` 先读后台链列表，再读 `ConfigManager`
充值收款地址 `spring.open.money.web3.recharge.receive-addresses`	是	`ConfiguredMoneyBalanceRechargeReceiveAddressResolver` 先读 `ConfigManager` JSON，失败回退本地绑定值
Web3 提现、跨链桥、支付结算人工审核开关与自动审核备注 `spring.open.money.web3.withdraw.review.` / `bridge.review.` / `settlement.review.*`	是	`MoneyWeb3ReviewConfigResolver` 先读 `ConfigManager`；关闭 `required` 后自动审核通过并写入 `auto-remark`，默认备注为“系统审核”
Web3 充值提交 hash 后的确认触发延迟 `spring.open.money.web3.recharge.confirmation.trigger-delay`	是	`MoneyWeb3RechargeConfigResolver` 先读 `ConfigManager`；默认 `10s`，非正值表示提交 hash 后不额外延迟触发
Cashier Web3 支付同步提交 hash 后的补偿触发延迟 `spring.open.cashier.payment.sync.web3.confirmation-trigger-delay`	是	`CashierPaymentConfigResolver` 先读 `ConfigManager`；默认 `10s`，用于 `/cashier/payment-orders/{outTradeNo}/sync` 后延迟补偿当前支付单
Cashier Web3 支付同步补偿投递序号 / 最大投递次数 `spring.open.cashier.payment.sync.web3.confirmation-retry-initial-attempt` / `spring.open.cashier.payment.sync.web3.confirmation-retry-max-attempts`	是	`CashierPaymentConfigResolver` 先读 `ConfigManager`；默认 `1` / `5`，用于单笔补偿 Queue job payload 的重投控制
Web3 提现自动打款后的确认触发延迟 `spring.open.money.web3.withdraw.confirmation.trigger-delay`	是	`MoneyWeb3WithdrawConfigResolver` 先读 `ConfigManager`；默认 `30s`，非正值表示广播后不额外延迟
跨链桥放款 / 退款兜底私钥 `spring.open.money.web3.bridge.transfer.private-key` / `private-keys`	是	`MoneyWeb3BridgeRuntimeConfigResolver` 先读 `ConfigManager`，失败回退本地绑定值；密文信封用主密钥本地解密
跨链桥私钥加密主密钥 `spring.open.money.web3.bridge.transfer.encryption-secret`	否，仅应用环境绑定	`MoneyWeb3Properties`，绝不入业务库；与库内密文私钥分离以降低单点泄露风险
跨链桥入金确认 Queue 任务、固定调度显式开关、fixed delay、limit、auto-payout 开关等执行拓扑配置	否，启动期生效	`MoneyWeb3Properties` + Spring 条件装配 / Queue job handler / 可选 Scheduler 注册；修改后需重启或由专门运行期 API 触发
Web3 模块启停、链上扫描 / 充值确认 / 资金归集任务是否注册	否，启动期生效	`@ConditionalOnProperty` / `@ConfigurationProperties`
尚未接入专用 Resolver 的普通 `spring.open.money.web3.*` 嵌套属性	否，按启动绑定值	`MoneyWeb3Properties`

规则很简单：只要链路代码显式调用 ConfigManager、ConfigResolver 或 RuntimeConfigSource，配置中心才会覆盖本地配置；只通过 @ConfigurationProperties 注入的字段不会被数据库配置自动回灌。

App 钱包兑换页和 PC 账户余额页展示 Web3 最小单位金额时会按 18 位精度转换为人类可读小数，避免直接展示 1000000000000000000 这类链上最小单位长整数；后端 API 仍保留原始金额字段，方便链上校验和精确计算。

一键兑换 + 跨链桥 + 兑换组合路线会按 sourceToken -> sourceBridgeToken -> targetBridgeToken -> targetToken 生成执行计划；当源 Token 已经是桥接 Token 或目标 Token 已经是桥出款 Token 时，对应兑换段自动省略。组合订单保存源链兑换、跨链桥、目标链兑换三段报价 JSON、段状态、组合路线快照、过期时间、人工复核标记和 recoveryActions，供前端展示分段执行提示。该入口只生成自托管钱包执行计划和托管跨链桥入金计划，不替用户签名或广播兑换交易。

订单状态复用 Web3OrderStatuses。当前已落地 waiting-deposit、deposit-submitted、source-confirming、source-confirmed、target-releasing、target-confirming、refunding、succeeded 和 refunded 等跨链桥状态；订单会返回 sourceConfirmationCount、sourceTxBlockNumber、depositReceiptStatus、sourceConfirmedAt、payoutTxHash、payoutReceiptStatus、targetConfirmationCount、targetTxBlockNumber、targetConfirmedAt、refundTxHash、refundReceiptStatus、refundConfirmationCount、refundTxBlockNumber 和 refundedAt，用于前端展示源链入金、目标链放款和源链退款进度。源链入金同步会把回执失败或付款地址、收款地址、金额不匹配的订单置为 failed 并记录 failureReason；目标链放款回执失败会进入 failed，随后可由后台按订单执行源链退款。

配置概览

yaml

spring:
  open:
    web3:
      enabled: true
      default-chain: bsc
      config:
        enabled: true
        prefix: spring.open.web3
      chains:                          # 详见 web3-rpc.md
        bsc:
          enabled: true
          chain-type: evm
          chain-id: 56
          rpc-urls: [...]
          private-rpc-urls: []
          native-currency: BNB
          block-explorer-url: https://bscscan.com
          connect-timeout: 5s
          read-timeout: 15s
        solana-mainnet:
          enabled: true
          chain-type: solana
          rpc-urls:
            - https://api.mainnet-beta.solana.com
          native-currency: SOL
      wallet:                          # 详见 web3-wallet.md
        enabled: true
        evm:
          enabled: true
          supported-chain-types: [evm, bsc, ethereum, polygon, arbitrum, optimism, base, avalanche]
      address-book:                    # 详见 web3-dex.md
        enabled: true
        entries: {...}
      metadata-cache:                  # 详见 web3-dex.md
        enabled: true
        ttl: 10m
        max-size: 2048
      price:                           # 详见 web3-dex.md
        enabled: true
        default-provider: pancake-v2
        fallback-providers: [pancake-v2-pool]
        providers: {...}

数据库配置同名 key 优先级：

text

数据库配置 / Config provider
  → application.yml / 环境变量
  → 默认值

Java 版本

主验证 JDK 17。Web3 starter 当前使用：

org.web3j:crypto:4.13.0
org.web3j:core:4.13.0
org.bouncycastle:bcprov-jdk18on:1.84

web3j 4.13.0 字节码为 Java 17。不在项目基线调整前升级到 4.14.0+ / 5.x，这些已用 Java 21 编译，IDEA JDK 17 自动构建会报 class file 65。

后续方向

当前 Web3 已完成钱包验签、Typed Data、多 RPC、只读 RPC、合约 ABI、Token / NFT 查询、授权、价格、DEX 只读、链上兑换报价 / 订单、流动性加减池报价 / 交易调用数据构建、native coin 加减池、流动性订单追踪、交易签名 / 广播、批量转账、资金归集、链 / Token 业务列表管理、事件扫描编排、Web3 支付服务商、支付确认、复核日志、显式结算、超时自动处理、自动重试、失败通知、已结算链上审计。

后续主线按复杂度推进：

真实 RPC 小额联调 + 生产压测
链重组异常补偿、工单化处理、更细资金风控
任意 ABI 写调用、DEX 链上兑换前端入口、池子创建和官方池运维
Safe 多签或其他多签服务接入
Solana / TON / Bitcoin / Tron / Aptos / Sui 的真实 RPC、签名、Token、事件扫描和支付 / 打款服务商
Passkey、Telegram 等外部身份增强

验证命令

bash

./mvnw -pl spring-open-starters/spring-open-starter-web3 -am test -DskipITs
./mvnw -pl spring-open-core/spring-open-core-web3 -am -Dtest='*Web3*Test' -Dsurefire.failIfNoSpecifiedTests=false test -DskipITs
./mvnw -pl spring-open-application -am test -DskipITs -DskipFrontend

Web3 Starter ​

何时使用 ​

术语口径 ​

已具备的能力 ​

设计边界 ​

节点边界 ​

快速开始 ​

托管资金池跨链桥 ​

数据库存储私钥的本地加密 ​

配置概览 ​

Java 版本 ​

后续方向 ​

验证命令 ​

相关 ​