Aptos 钱包集成指南：连接、签名与交易全解析

在 Aptos 区块链生态中，为去中心化应用（DApp）集成钱包功能是至关重要的一步。除 SDK 外，OKX 还提供了直观的 UI 界面，方便开发者快速实现钱包连接、交易签名等操作。如果 DApp 运行于 Telegram 环境，用户可选择打开移动端 App 钱包或直接启动 OKX 迷你钱包，享受无缝体验。

本文将详细解析如何通过 OKX Connect 实现 Aptos 钱包的集成，涵盖安装初始化、连接钱包、消息签名、交易处理等核心环节，助您高效构建 Web3 应用。

安装与初始化

在开始前，请确保将 OKX App 更新至 6.92.0 或更高版本。您可通过 npm 安装 OKX Connect：

npm install @okx/web3-connect

初始化时，需创建一个提供 UI 接口的对象，用于后续连接钱包、发送交易等操作。

请求参数

• dappMetaData - 对象

  • name - 字符串：应用名称，不会作为唯一标识。
  • icon - 字符串：应用图标的 URL，格式需为 PNG、ICO 等，不支持 SVG。建议使用 180x180px 的 PNG 图标。

• actionsConfiguration - 对象

  • modals - ('before' | 'success' | 'error')[] | 'all'：交易过程中提示的显示模式，默认为 'before'。
  • returnStrategy - 字符串：'none' | ${string}://${string}；针对 App 钱包，指定用户签名/拒绝请求后的深度链接返回策略，若在 Telegram 中可配置为 tg://resolve。
  • tmaReturnUrl - 字符串：'back' | 'none' | ${string}://${string}；针对 Telegram 迷你钱包，指定用户签名/拒绝请求后的深度链接返回策略，默认为 'back'。

• uiPreferences - 对象

  • theme - 主题：可选 THEME.DARK、THEME.LIGHT 或 'SYSTEM'。
  • language - 字符串：支持多国语言，默认为 en_US。

返回值

• OKXUniversalConnectUI 对象

示例代码

const connectUI = new OKXUniversalConnectUI({
  dappMetaData: {
    name: "My DApp",
    icon: "https://example.com/icon.png"
  },
  actionsConfiguration: {
    modals: 'all',
    returnStrategy: 'none'
  },
  uiPreferences: {
    theme: THEME.DARK,
    language: 'zh_CN'
  }
});

连接钱包

连接钱包的目的是获取钱包地址作为标识符，以及签名交易所必需的参数。

请求参数

• connectParams - ConnectParams 对象

  • namespaces - 对象：连接请求的必要信息，键 'aptos' 表示 Aptos 系统。

    • chains - 字符串数组：链 ID 信息。
    • defaultChain - 字符串（可选）：默认链。

  • optionalNamespaces - 对象：连接请求的可选信息。

    • chains - 字符串数组：链 ID 信息。
    • defaultChain - 字符串（可选）：默认链。

  • sessionConfig - 对象

    • redirect - 字符串：连接成功后的跳转参数，Telegram 迷你应用可设置为 tg://resolve。

返回值

• Promise 对象，包含：

  • topic：会话标识符。
  • namespaces：成功连接的命名空间信息。
  • chains：连接的链信息。
  • accounts：连接的账户信息。
  • methods：钱包在当前命名空间下支持的方法。
  • defaultChain：当前会话的默认链。
  • sessionConfig：会话配置。
  • dappInfo：DApp 信息。

示例代码

const result = await connectUI.connect({
  namespaces: {
    aptos: {
      chains: ['aptos:1'],
      defaultChain: 'aptos:1'
    }
  },
  sessionConfig: {
    redirect: 'tg://resolve'
  }
});

连接并签名

此方法用于连接钱包并签名数据，结果将通过事件 'connect_signResponse' 回调。

请求参数

• connectParams：同连接钱包参数。

• signRequest - RequestParams[] 数组：最多同时支持一个方法。

  • method：字符串：请求的方法名，Aptos 支持 'aptos_signMessage'。
  • chainId：字符串：方法执行的链 ID，必须包含在 namespaces 中。
  • params：参数数组或对象：请求方法对应的参数。

返回值

• Promise 对象，结构与连接钱包返回类似。

示例代码

const signResult = await connectUI.connectAndSign({
  connectParams: { /* ... */ },
  signRequest: [{
    method: 'aptos_signMessage',
    chainId: 'aptos:1',
    params: { message: 'Hello Aptos' }
  }]
});

检查钱包连接状态

通过以下方法可检查钱包是否已连接：

返回值

• 布尔值：true 表示已连接，false 表示未连接。

示例代码

const isConnected = connectUI.isConnected();
if (isConnected) {
  console.log("Wallet is connected.");
} else {
  console.log("Wallet is not connected.");
}

准备交易

首先创建 OKXAptosProvider 对象，构造函数传入 OKXUniversalProvider。

获取钱包地址和公钥

请求参数

• chain：字符串：要获取钱包地址的链 ID，若不传递则取第一个连接的 Aptos 系统地址。

返回值

• 对象：

  • address：字符串：钱包地址。
  • publicKey：字符串：公钥。

示例代码

const provider = new OKXAptosProvider(okxUniversalProvider);
const accountInfo = await provider.getAccountInfo('aptos:1');
console.log(accountInfo.address, accountInfo.publicKey);

消息签名

请求参数

• message - 对象：

  • address：布尔值（可选）：是否在消息中包含账户地址。
  • application：布尔值（可选）：是否包含 DApp 域名。
  • chainId：布尔值（可选）：是否包含当前连接的链 ID。
  • message：字符串：要签名并显示给用户的消息。
  • nonce：字符串：DApp 生成的随机数。
• chain：字符串：请求签名的链，建议传递此参数；连接多链时必须传递。

返回值

• Promise 对象，包含：

  • address：字符串。
  • application：字符串。
  • chainId：数字。
  • fullMessage：字符串：生成签名的完整消息。
  • message：字符串：用户传入的消息。
  • nonce：字符串。
  • prefix：字符串：始终为 APTOS。
  • signature：字符串：签名后的完整消息。

示例代码

const signature = await provider.signMessage({
  message: {
    message: "Sign this message",
    nonce: "123456",
    address: true,
    application: true
  },
  chain: 'aptos:1'
});

签名单笔交易

请求参数

• transaction：对象 | SimpleTransaction：交易数据对象。
• chain：字符串：请求签名执行的链，建议传递此参数；连接多链时必须传递。

返回值

• Promise - Buffer：签名结果。

示例代码

const signedTx = await provider.signTransaction(transaction, 'aptos:1');

签名并广播交易

使用 okxAptosProvider.signAndSubmitTransaction(transaction, chain) 方法可签名交易并广播上链。

请求参数

• transaction：对象 | SimpleTransaction：交易数据对象。
• chain：字符串：请求签名执行的链，建议传递此参数；连接多链时必须传递。

返回值

• Promise - 字符串：交易哈希。

示例代码

const txHash = await provider.signAndSubmitTransaction(transaction, 'aptos:1');
console.log("Transaction Hash:", txHash);

断开钱包连接

断开已连接的钱包并删除当前会话。如需切换钱包，请先断开当前连接。

示例代码

connectUI.disconnect();

事件处理

在连接、交易和断开过程中，可监听相关事件以处理回调。常见事件包括 'connect_response'、'connect_signResponse' 等。

示例代码

connectUI.on('connect_response', (data) => {
  console.log("Connect Response:", data);
});

错误代码

在连接、交易和断开过程中，可能抛出以下异常：

常见问题

如何选择适合的返回策略？

返回策略取决于您的应用场景。若 DApp 运行在 Telegram 中，建议使用 tg://resolve 以实现无缝跳转。对于普通 Web 应用，可设置为 'none' 或自定义深度链接。

支持哪些签名方法？

Aptos 目前主要支持 aptos_signMessage 方法用于消息签名，以及交易签名相关方法。具体支持的方法可在连接后通过返回的 methods 字段查看。

连接多链时需要注意什么？

当连接多链时，必须在每个签名请求中明确指定 chain 参数，以确保操作在正确的链上执行。否则可能导致签名失败或交易发送到错误的链。

如何处理用户拒绝签名的情况？

用户拒绝签名时，会抛出 OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR 错误。建议在代码中捕获该异常，并给用户友好的提示，如“您已取消签名操作”。

如何自定义 UI 主题？

在初始化时通过 uiPreferences.theme 参数可设置主题，支持深色、浅色和系统默认。您可根据 DApp 的整体风格选择匹配的主题，以提升用户体验。

交易广播后如何查询状态？

交易广播成功后返回交易哈希，您可通过 Aptos 区块链浏览器查询交易状态。此外，👉 查看实时交易工具 可帮助您监控链上活动，确保交易顺利确认。

通过本文的详细指南，您应已掌握 Aptos 钱包集成的核心步骤与技巧。合理运用这些功能，可为用户提供安全、流畅的区块链交互体验。如在开发过程中遇到问题，可参考错误代码表快速定位并解决常见异常。