Cosmos App SDK 钱包集成全流程：从零到签名只需五步

·

关键词：Cosmos SDK、钱包集成、DEX API、App 连接、签名流程、链 ID、SignAmino、SignDirect

本文用实战代码带你跑通 Cosmos App SDK 的钱包打通之旅：安装、连接、获取地址、交易签名到最终断开，一站式掌握 DEX API 每一个调用细节。

1. 安装与初始化

1.1 一步到位的安装

npm i @okwallet/connect@^6.94.0

确保版本 ≥6.94.0，才能使用最新的 Universal Provider 特性。

1.2 创建 Provider 对象

import { OKXUniversalProvider } from '@okwallet/connect';

const provider = await OKXUniversalProvider.init({
  dappMetaData: {
    name: 'Cosmos-DEX-Demo',
    icon: 'https://yourcdn.com/icon-180x180.png' // 务必 PNG
  }
});

2. 连接钱包：拿到 session 与地址

2.1 核心参数

const connectParams = {
  namespaces: {
    cosmos: {
      chains: ['cosmos:cosmoshub-4', 'cosmos:osmosis-1'],
      defaultChain: 'cosmos:osmosis-1'   // 首次默认链
    }
  },
  optionalNamespaces: {
    cosmos: {
      chains: ['cosmos:secretnetwork-1']
    }
  },
  sessionConfig: {
    redirect: 'tg://resolve' // Telegram Mini App 示范
  }
};

const session = await provider.connect(connectParams);

2.2 返回值速查

字段示例值
topic本次会话 ID
namespaces.cosmos.accounts['cosmos1a…', 'cosmos1b…']
defaultChain'cosmos:osmosis-1'

👉 一键了解如何自动切换多条 Cosmos 链

3. 判断连接状态

const isConnected = provider.connected; // true / false

连接期间，可随时用此布尔值判断是否需要重连。

4. 构造交易并保持签名体验

4.1 实例化 Cosmos Provider

import { OKXCosmosProvider } from '@okwallet/cosmos-provider';
const cosmosProvider = new OKXCosmosProvider(provider);

4.2 获取账户信息

const acc = await cosmosProvider.getAccount('cosmos:osmosis-1');
console.log(acc);
/*
{
  address: 'osmo1uz...',
  algo: 'secp256k1',
  pubKey: Uint8Array()
}
*/

4.3 签名消息（字符串）

const sig = await cosmosProvider.signMessage({
  chain: 'cosmos:osmosis-1',
  signerAddress: acc.address,
  message: 'Hello Cosmos!'
});

4.4 SignAmino：链上广播的通用姿势

const signDoc = {
  chainId: 'osmosis-1',
  accountNumber: '123456',
  sequence: '0',
  fee: { ... },
  msgs: [{ ... }],
  memo: ''
};

const amino = await cosmosProvider.signAmino({
  chainId: 'cosmos:osmosis-1',
  signerAddress: acc.address,
  signDoc
});

4.5 SignDirect：性能最优解

const directDoc = {
  bodyBytes: Uint8Array.from(...),
  authInfoBytes: Uint8Array.from(...),
  chainId: 'osmosis-1',
  accountNumber: '123456'
};

const direct = await cosmosProvider.signDirect({
  chainId: 'cosmos:osmosis-1',
  signerAddress: acc.address,
  signDoc: directDoc
});

5. 断开钱包

await provider.disconnect();
锁屏或用户手动退出后，务必调用 disconnect，否则重连时可能触发 ALREADY_CONNECTED_ERROR。

常见错误码一览

错误码含义
UNKNOWN_ERROR未知错误
ALREADY_CONNECTED_ERROR多标签页重复连接
NOT_CONNECTED_ERROR方法调用时钱包未连接
USER_REJECTS_ERROR用户在弹窗中主动拒绝
METHOD_NOT_SUPPORTED当前钱包版本不支持该签名方法
CHAIN_NOT_SUPPORTED对应链 ID 不在钱包支持列表
CONNECTION_ERROR硬件或网络原因导致连接失败

FAQ：最容易踩的坑

Q1. 为什么 icon 显示异常？
A：仅支持 PNG、ICO。SVG 会被钱包拒收。

Q2. namespace 与 chainId 有什么区别？
A：namespace 通常写死 cosmos，而 chainId 是链的精确识别符，如 cosmos:osmosis-1。

Q3. SignAmino 和 SignDirect 应该选哪个？
A：普通 DEX 用 SignAmino 可读性好；追求极限 TPS 或大额交易用 SignDirect。

Q4. 如何优雅展现代币授权流程？
A：预先通过 getAccount 拿到地址，再调用 signDirect 生成授权交易广播即可。

Q5. 需要支持 Telegram Mini App 该怎么写？
A：在 sessionConfig.redirect 填 tg://resolve，用户确认后自动回到对话界面。

Q6. 怎样保证多浏览器标签页不冲突？
A：监听 window.onfocus，发现标签页切换后及时 disconnect。

结尾：下一步进阶指南

Cosmos 生态百花齐放，从 Osmosis 流动性池到 Secret 隐私链，只要掌握以上五步，就能让 App SDK + 钱包集成 随链而变。
👉 深度了解如何在多签场景下复用 provider