波场 (TRON) DApp 接入指南：连接钱包与交易操作详解

本文将详细介绍如何将您的去中心化应用（DApp）与波场（TRON）网络进行集成，重点涵盖钱包连接、交易签名及消息处理等核心操作流程。无论您是希望接入 OKX 钱包还是其他兼容 Web3 的钱包，本篇指南都将提供清晰的技术指引。

环境准备与初始化

在开始接入前，请确保您的开发环境已满足以下基础要求：

• 若使用 OKX App，请将其更新至 6.96.0 或更高版本。
• 通过 npm 安装 OKX Connect 依赖包，以便在您的 DApp 中集成连接功能。

连接钱包前，需先创建一个提供 UI 界面的对象，该对象将用于后续的钱包连接、交易发送等操作。

初始化参数说明

请求参数

• dappMetaData (对象类型)

  • name (字符串): 应用名称，不作为唯一标识。
  • icon (字符串): 应用图标的 URL 地址。请使用 PNG、ICO 等格式，暂不支持 SVG 格式图标。建议使用 180x180px 的 PNG 图标以获得最佳显示效果。

• actionsConfiguration (对象类型)

  • modals: 设定交易过程中的提醒界面展示模式，可选值为 'before'、'success'、'error' 的数组或 'all'，默认为 'before'。
  • returnStrategy: 针对 App 钱包，指定用户签署或拒绝请求时的深度链接返回策略。例如，在 Telegram 环境中可配置为 tg://resolve。
  • tmaReturnUrl: 在 Telegram Mini Wallet 中设定返回策略。可选值：'back'（签名后关闭钱包并自动展示 DApp）、'none'（签名后无操作），默认为 'back'。

• uiPreferences (对象类型)

  • theme: 应用主题，可选值：THEME.DARK（暗色）、THEME.LIGHT（亮色）、"SYSTEM"（跟随系统）。
  • language: 界面语言，支持多种语言选项如 "zh_CN"（简体中文）、"en_US"（英文）等，默认为 "en_US"。

返回值

初始化成功后，将返回一个 OKXUniversalConnectUI 对象实例，用于后续操作。

👉 查看完整的初始化参数配置示例

连接钱包流程

连接钱包是获取用户钱包地址的关键步骤，该地址将作为用户标识符并用于后续的交易签名。

连接请求参数

• connectParams (ConnectParams 类型)

  • namespaces: 请求连接的必选命名空间信息。对于波场网络，key 为 "tron"。若请求的链中有任一链不被钱包支持，连接将被拒绝。

    • chains (字符串数组): 链 ID 信息。
    • defaultChain (可选): 默认链 ID。

  • optionalNamespaces: 请求连接的可选命名空间信息。即使对应的链信息钱包不支持，连接仍然可以继续进行。

    • chains (字符串数组): 链 ID 信息。
    • defaultChain (可选): 默认链 ID。

  • sessionConfig (对象类型)

    • redirect (字符串): 连接成功后的跳转参数。若在 Telegram Mini App 中，可设置为 Telegram 的深度链接，如 "tg://resolve"。

连接返回值

连接操作返回一个 Promise 对象，解析后的值包含以下信息：

• topic (字符串): 会话标识符。
• namespaces: 成功连接的命名空间信息。
• chains (字符串数组): 已连接的链信息。
• accounts (字符串数组): 已连接的账户地址信息。
• methods (字符串数组): 当前命名空间下钱包支持的方法列表。
• defaultChain (可选): 当前会话的默认链 ID。
• sessionConfig (可选): 会话配置信息。

• dappInfo (对象类型): DApp 相关信息。

  • name (字符串): DApp 名称。
  • icon (字符串): DApp 图标 URL。
  • redirect (可选): 连接成功后的跳转参数。

核心功能操作

准备交易

首先需要创建一个 OKXTronProvider 对象，该对象的构造函数需传入之前初始化得到的 okxUniversalConnectUI 实例。

获取账户信息

请求参数

• chainId (字符串): 请求的链 ID，例如 tron:mainnet（波场主网）。

返回值

返回一个对象，其中包含：

• address (字符串): 用户的钱包地址。

签署消息

请求参数

• message (字符串): 需要被签名的原始消息内容。
• chainId (可选)(字符串): 请求执行签名操作的链 ID，例如 tron:mainnet。

返回值

返回一个 Promise，解析值为签名后的结果字符串。

签署消息 (V2)

此版本提供了另一种消息签名方式。

请求参数

• message (字符串): 需要被签名的原始消息内容。
• chainId (字符串): 请求执行签名操作的链 ID，例如 tron:mainnet。

返回值

返回一个 Promise，解析值为签名后的结果字符串。

签署交易 (signTransaction)

请求参数

• transaction (对象): 交易信息对象，需按照固定格式构建。可使用 TronWeb.transactionBuilder 工具生成。
• chainId (可选)(字符串): 请求签名执行的链 ID，例如 tron:mainnet。

返回值

返回一个 Promise，解析值为签名后的交易对象。

签署并广播交易 (signAndSendTransaction)

此方法会完成交易签名并立即将其广播到区块链网络。

请求参数

• transaction (对象): 交易信息对象，需按照固定格式构建。可使用 TronWeb.transactionBuilder 工具生成。
• chainId (字符串): 请求签名和广播执行的链 ID，例如 tron:mainnet。

返回值

返回一个 Promise，解析值为该笔交易的哈希值字符串。

断开钱包连接

调用此方法将断开当前已连接的钱包，并删除会话信息。如果您需要切换连接其他钱包，请务必先断开当前连接。

事件监听 (Event)

您可以监听相关事件来处理连接状态变化、交易状态更新等异步通知。

错误处理与常见错误码

在连接钱包、发送交易或断开连接的过程中，可能会遇到以下异常情况：

👉 获取更多错误处理与调试技巧

常见问题 (FAQ)

Q1: 连接钱包时，如果用户拒绝了权限请求，该如何处理？
A: 当用户拒绝连接时，SDK 会抛出 OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR 错误码。您需要在代码中捕获此异常，并友好地提示用户连接已取消，同时提供重试的选项。

Q2: 如何判断当前钱包是否支持波场 (TRON) 链？
A: 您可以在连接参数中通过 namespaces 或 optionalNamespaces 指定 tron 链ID。如果钱包不支持，连接可能会被拒绝或返回相应的错误码 (CHAIN_NOT_SUPPORTED)。建议在连接前检查钱包的支持情况。

Q3: 签署交易时，交易对象应该如何构建？
A: 交易对象需要符合特定的格式要求。强烈推荐使用官方提供的 TronWeb.transactionBuilder 工具来生成正确格式的交易对象，以避免签名失败。

Q4: 断开连接后，用户的账户信息会被立即清除吗？
A: 调用断开连接方法后，当前的会话信息会被删除，SDK 内部维护的账户状态也会被清除。但您本地存储的缓存信息需要您自行管理并清除。

Q5: 如何处理交易广播后的状态查询？
A: 方法 signAndSendTransaction 返回的是交易哈希值。您需要通过该哈希值，使用波场网络的公共 API 或节点服务来独立查询交易的确认状态和最终结果。

Q6: 初始化时指定的图标和名称在哪里显示？
A: 这些元数据信息（dappMetaData）会在钱包端的连接授权界面、交易确认界面等地方展示给用户，用于标识您的 DApp。请确保信息准确且图标清晰。