本文将详细介绍如何通过 SDK 将您的去中心化应用（DApp）与 Web3 钱包进行连接，特别聚焦于 StarkNet 主网的接入流程。从环境初始化、钱包连接到交易签名与发送，本指南将逐步解析关键操作步骤，并提供实用示例，助您高效完成 DApp 的集成与调试。
环境安装与初始化
在开始接入前，请确保您的开发环境已准备就绪。推荐使用 npm 进行依赖管理。
核心参数说明：
dappMetaData：应用元数据对象name：应用名称（非唯一标识）icon：应用图标 URL（格式需为 PNG 或 ICO，推荐尺寸 180x180px，暂不支持 SVG）
返回对象：
初始化成功后，将返回 OKXUniversalProvider 实例，用于后续连接与交易操作。
代码示例：
import { OKXUniversalProvider } from '@okx/web3-connect';
const provider = new OKXUniversalProvider({
dappMetaData: {
name: "YourDAppName",
icon: "https://yourdomain.com/icon.png"
}
});连接钱包流程详解
连接钱包是 DApp 与用户交互的基础步骤，用于获取钱包地址及授权信息。
请求参数：
connectParams：连接配置对象namespaces：必选命名空间（StarkNet 主网的 Key 为"starknet"）chains：链 ID 列表optionalNamespaces：可选命名空间（若钱包不支持某链，仍可连接其他链）sessionConfig：会话配置（如设置成功后的跳转链接）
返回值：
返回 Promise，包含会话主题（topic）、账户地址、支持的链及方法等信息。
示例代码：
const result = await provider.connect({
namespaces: {
starknet: {
chains: ["starknet:mainnet"],
methods: ["starknet_signTransaction"],
events: ["accountsChanged"]
}
}
});交易构建与账户操作
创建交易提供者
通过 OKXUniversalProvider 实例构建 StarkNet 专属的 Provider：
const starknetProvider = new OKXStarknetProvider(provider);获取账户信息
请求指定链（如 StarkNet 主网）的钱包地址与公钥：
请求参数： chainId（例如 "starknet:mainnet"）
返回值：
对象包含 address 和 pubKey 字段。
消息签名
对结构化数据（typedData）进行签名：
参数：
signerAddress：签名钱包地址typedData：待签名消息（需符合 StarkNet 格式标准）chain：可选链标识
返回值：
Promise 解析为签名结果 [r, v]。
交易签名与广播
使用 sendTransaction 方法签名并发送交易：
参数：
signerAddress：签名地址transaction：交易数据对象chainId：链标识
返回值：
交易哈希（string）。
连接管理与事件处理
断开钱包连接
调用 disconnect 方法终止当前会话。如需切换钱包，需先断开现有连接再重新发起连接。
事件监听
SDK 支持会话事件监听，例如账户变更、链切换等，可通过事件回调实现实时状态同步。
错误码说明
操作过程中可能返回以下错误码：
| 错误码 | 描述 |
|---|---|
| UNKNOWN_ERROR | 未知异常 |
| ALREADY_CONNECTED_ERROR | 钱包已连接 |
| NOT_CONNECTED_ERROR | 钱包未连接 |
| USER_REJECTS_ERROR | 用户拒绝操作 |
| METHOD_NOT_SUPPORTED | 方法不支持 |
| CHAIN_NOT_SUPPORTED | 链不支持 |
| WALLET_NOT_SUPPORTED | 钱包不支持 |
| CONNECTION_ERROR | 连接异常 |
常见问题
1. 如何选择支持的链？
目前 StarkNet 仅支持主网（starknet:mainnet）。在连接请求中需明确指定链 ID，若请求不支持的链，钱包将拒绝连接。
2. 签名失败可能的原因有哪些？
常见原因包括：用户拒绝签名、消息格式不符合 StarkNet 标准、当前链与签名请求链不匹配等。建议优先检查 typedData 结构是否符合规范。
3. 如何正确处理用户拒绝连接的情况？
捕获 USER_REJECTS_ERROR 错误码，并给予用户友好提示，如“您已取消连接请求”，避免阻塞后续操作流程。
4. 是否支持多链同时连接？
当前版本仅支持单链会话。如需切换链，需先断开再重新连接目标链。
5. 交易发送后如何查询状态？
通过返回的交易哈希，可使用 StarkNet 区块链浏览器查询交易状态及确认数。
6. 图标格式是否有大小限制？
推荐使用 180x180px 的 PNG 图标，确保在不同尺寸屏幕上清晰显示，避免使用 SVG 格式。
通过本文指南，您应已完成从初始化环境到交易发送的全流程接入。如在开发中遇到特定问题，建议查阅相关链文档或社区资源进一步排查。