Web3 Wallet Starter

受众：开发者摘要：EVM 钱包验签 / personal_sign / EIP-712 Typed Data / 地址规范化 + checksum。

何时使用

场景	建议
钱包登录	`/api/v1/auth/wallet/challenge` + `login`，IAM 模块自动用 `WalletSignatureVerifier` SPI
Typed Data 验签	`Web3.verifyTypedData(...)`，EIP-712
EVM 地址校验 / 规范化 / checksum	`EvmAddresses`

钱包登录

IAM 模块的钱包登录会通过 WalletSignatureVerifier SPI 自动使用 Web3 starter 的 EVM 验签器：

http

POST /api/v1/auth/wallet/challenge
POST /api/v1/auth/wallet/login

业务登录链路仍然归 IAM 统一账号体系管理：

生成 challenge：IAM 模块负责短 TTL 缓存和签名消息。
钱包验签：Web3 starter 负责链类型、地址规范化和签名恢复。
登录成功：IAM 模块复用统一账号、统一 token、统一权限和审计。

钱包登录自动创建账号时，IAM 会优先把本次验签通过的 EVM 地址作为用户名；如果该地址用户名已经存在，则回退为生成的外部身份用户名。用户或管理员把用户名改成合法 EVM 地址格式时，后端会要求该地址已经绑定到当前用户，防止未持有者冒用他人钱包地址作为用户名；普通用户名和非法钱包地址格式不会触发这条保护。

Typed Data 验签

需要验证 EVM EIP-712 typed data 签名时，注入 TypedDataSignatureVerifier。它独立于登录 challenge，不改变当前 personal_sign 登录链路：

java

@RequiredArgsConstructor
public class WalletSignatureService {

    private final TypedDataSignatureVerifier verifier;

    public boolean verifyPermit(String address, String typedDataJson, String signature) {
        return verifier.verify(new TypedDataSignatureVerificationRequest(
                "ethereum",
                address,
                typedDataJson,
                signature));
    }

}

当前 EVM 实现内部复用 web3j StructuredDataEncoder，支持常规 EIP-712 typed data JSON。业务层仍需要校验 domain、chainId、verifyingContract、nonce、deadline、金额、授权对象等业务字段，不能只凭签名有效就更新本地状态。

开放平台已提供对应的外部验签 API：

text

POST /api/v1/open/web3/chains/{chain}/wallet-signatures/personal/verify
POST /api/v1/open/web3/chains/{chain}/wallet-signatures/typed-data/verify

这两个接口只返回验签结果，不登录、不创建账号、不消费业务 nonce。第三方应用应在自己的服务端完成 Open Platform 请求签名，再调用这些接口；不要把 Open Platform appSecret 放在浏览器、小程序或 App 客户端中。

EVM 地址工具

需要在业务层做地址格式校验或显示 checksum 地址时，使用 EvmAddresses。它只做本地字符串处理，不访问 RPC，也不处理私钥：

java

boolean valid = EvmAddresses.isAddress("0x52908400098527886E0F7030069857D2E4169EE7");
String normalized = EvmAddresses.normalize("52908400098527886E0F7030069857D2E4169EE7");
String checksum = EvmAddresses.toChecksumAddress("0x52908400098527886e0f7030069857d2e4169ee7");

约定：

normalize(...) 返回小写 0x 前缀地址；无效地址返回 null。
require(...) 返回小写 0x 前缀地址；无效地址抛出 Web3 业务异常。
toChecksumAddress(...) 返回 EIP-55 checksum 地址，用于展示、审计或外部系统交互。

Web3 Wallet Starter ​

何时使用 ​

钱包登录 ​

Typed Data 验签 ​

EVM 地址工具 ​

相关 ​

Web3 Wallet Starter

何时使用

钱包登录

Typed Data 验签

EVM 地址工具

相关