Web3 Transfer Starter

受众：开发者 摘要：EVM 原生交易签名 / 广播 / 批量转账 / 多钱包资金归集，写交易统一使用 preview / sign-only / broadcast 执行模式。

何时使用

场景	建议
单笔签名 + 广播 / 仅签名	Web3.signAndBroadcast(...) / signOnly(...)
批量转账（顺序 nonce、失败跳过）	Web3.bulkTransfer(...)
多钱包资金归集（计划 / 可选广播）	Web3.consolidate(...)
支付转账事件匹配（结算 / 审计 / 补偿）	Web3PaymentTransferMatcher

交易签名与广播

Web3 starter 已提供 EVM 原生交易签名、广播和“签名后立即广播”入口。私钥只在本次请求内参与签名，框架不会持久化、打印或写入日志：

Web3SignedTransaction signed = Web3.signTransaction(Web3TransactionRequest.builder()
        .chainName("bsc")
        .privateKey("...")
        .fromAddress("0x...")
        .toAddress("0x...")
        .value(BigInteger.valueOf(1000000000000000L))
        .build());

Web3BroadcastResult broadcast = Web3.broadcastTransaction("bsc", signed.getRawTransaction());

nonce、gasPrice、gasLimit 和 chainId 都可以显式传入；未传时会按链配置和 RPC 兜底。普通原生转账默认 gasLimit=21000，带 data 的交易会在缺省时尝试预估 Gas。

批量转账和资金归集

批量转账适合一个付款钱包向多个地址转账。写交易统一使用 executionMode 控制执行方式：

模式	说明
preview	默认模式，只生成计划，不签名、不广播；适合大额、多钱包、首次配置和人工审核前预览
sign-only	签名但不广播，返回 rawTransaction；适合人工复核或离线广播
broadcast	签名并立即广播到链上；适合小额、低风险和系统自动执行场景

Web3BatchTransferResult result = Web3.batchTransfer(Web3BatchTransferRequest.builder()
        .chainName("bsc")
        .privateKey("...")
        .fromAddress("0x...")
        .executionMode("broadcast")
        .transfers(List.of(
                Web3BatchTransferItem.builder()
                        .toAddress("0x...")
                        .value(BigInteger.valueOf(1000000000000000L))
                        .build()))
        .build());

资金归集适合多个钱包向统一收款地址归集原生代币。未指定单钱包金额时，会按余额扣除 Gas 和预留金额后尽量归集。默认 preview 可以只用钱包地址计算计划；sign-only / broadcast 需要提供私钥：

Web3FundCollectionResult result = Web3.collectFunds(Web3FundCollectionRequest.builder()
        .chainName("bsc")
        .receiverAddress("0x...")
        .executionMode("sign-only")
        .reserveAmount(BigInteger.valueOf(1000000000000000L))
        .wallets(List.of(Web3FundCollectionWallet.builder()
                .privateKey("...")
                .fromAddress("0x...")
                .build()))
        .build());

为了兼容已有调用，旧字段 broadcast=true 会被识别为 executionMode=broadcast；新代码建议直接使用 executionMode，语义更清楚。

当前 Web3 开发期统一使用 JDK 17 做主验证。依赖升级时必须确认第三方字节码不高于 Java 17。

Web3 支付转账事件匹配

Web3 starter 提供 Web3PaymentTransferMatcher，用于把已解码的 ERC-20 Transfer 事件和支付期望做只读匹配：

Web3PaymentTransferExpectation expectation = Web3PaymentTransferExpectation.builder()
        .chainName("bsc")
        .transactionHash("0x...")
        .receiverAddress("0x...")
        .tokenContract("0x...")
        .amountRaw(Web3TokenAmounts.toRaw(new BigDecimal("1.23"), 18))
        .build();

Web3PaymentTransferMatchResult result =
        Web3PaymentTransferMatcher.match(expectation, transfer);

相关

• Token 写交易辅助 / 批量编排：web3-token.md
• Web3 支付 + 结算审计：web3-payment.md
• Web3 顶层概览：web3.md