# @console-wallet/dapp-sdk 中文文档

规范地址：https://npmcn.com/package/%40console-wallet/dapp-sdk/

版本：3\.0\.0
npm 元数据更新时间：2026-10-09T11:56:42.220Z
中文译文更新时间：2026-11-10T16:01:34.416Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40console-wallet/dapp-sdk
原文对照：https://npmcn.com/package/%40console-wallet/dapp-sdk/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.6 MB，587 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：9 个
- 首次发布：2025-10-28T15:38:49.916Z
- 最新版本发布：2026-10-09T11:56:42.033Z
- 近 30 天下载量：3323（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：48（近 12 个月 46 个）

## 中文简介

Console DApp SDK允许dApps连接到一个Console钱包账户. Console钱包是一个浏览器扩展名. 所有交互都发生在dApp内部. 签字时,会敦促用户在其控制台钱包浏览器扩展中签名.

## 安装

```sh
npm install @console-wallet/dapp-sdk
```

也可以使用：`pnpm add @console-wallet/dapp-sdk`、`yarn add @console-wallet/dapp-sdk`、`bun add @console-wallet/dapp-sdk`

## README

# 控制台 DApp SDK

Console DApp SDK允许dApps连接到一个Console钱包账户. Console钱包是一个浏览器扩展名. 所有交互都发生在dApp内部. 签字时,会敦促用户在其控制台钱包浏览器扩展中签名.

此 SDK 兼容 [CIP-0103 (中文(简体) )](https://github.com/canton-foundation/cips/blob/main/cip-0103/cip-0103.md) 标准.

## 安装

要使用Console DApp SDK,你首先需要从国家预防机制安装:

```bash
npm install @console-wallet/dapp-sdk
# or
yarn add @console-wallet/dapp-sdk
```

注意,如果您不想执行构建进程,您可以直接将文件添加到 `unpkg`数字 :

```html
<script type="module">
  import { consoleWalletPixelplex } from 'https://unpkg.com/@console-wallet/dapp-sdk@latest/dist/esm/index.js';
</script>
```

## 使用指南

### 1\. 进口SDK

```typescript
import { consoleWalletPixelplex } from '@console-wallet/dapp-sdk';
```

### 2\. 检查钱包的可用性

在尝试连接之前, 请检查是否安装了控制台钱包扩展并按版本显示是否有能力 :

```typescript
const checkWallet = async () => {
  try {
    const availability = await consoleWalletPixelplex.checkExtensionAvailability();
    if (availability.status === 'installed') {
      console.log('Console Wallet is installed');
    } else {
      console.log('Console Wallet is not installed');
      // Show installation instructions to the user
    }

    if (availability.isExtensionCapableByVersion) {
      console.log('Console Wallet is capable by version');
    } else {
      console.log('Console Wallet is not capable by version');
    }
  } catch (error) {
    console.error('Error checking wallet availability:', error);
  }
};
```

### 3\. 检查连接状态

您可以随时检查当前连接状态 :

```typescript
const checkStatus = async () => {
  try {
    const status = await consoleWalletPixelplex.status();
    console.log('Connection status:', status.isConnected); // 'connected' or 'disconnected'
  } catch (error) {
    console.error('Error checking status:', error);
  }
};
```

### 4\. 连接钱包

要启动连接,请打电话 `connect()` 带有可选 dApp 元数据 :

```typescript
const handleConnect = async () => {
  try {
    const status = await consoleWalletPixelplex.connect({
      name: 'My Awesome dApp',
      icon: 'https://example.com/icon.png', // Optional: absolute URL to your dApp icon
    });

    if (status === 'connected') {
      console.log('Successfully connected to Console Wallet');
      // Proceed with your dApp logic
    }
  } catch (error) {
    console.error('Connection rejected or failed:', error);
  }
};
```

### 4.1 移动连接和QR代码流动

SDK支持三个连接目标:

-   `local` — 仅浏览器扩展名
-   `remote` ——仅移动应用会话(QR/深链接)
-   `combined` ——选择现有最佳连接器(扩展或移动)

使用 `target: 'remote'` 当您要强制移动/ QR 流量时 :

```typescript
const connectWithMobile = async () => {
  try {
    const status = await consoleWalletPixelplex.connect({
      name: 'My Awesome dApp',
      icon: 'https://example.com/icon.png',
      target: 'remote',
    });

    if (status.isConnected) {
      console.log('Connected through mobile flow');
    }
  } catch (error) {
    console.error('Mobile connect failed:', error);
  }
};
```

远程流是如何表现的:

-   桌面浏览器:SDK在页面中制作一个QR模式;用户用Console Walet移动应用程序扫描.
-   Android浏览器:SDK通过深链接直接打开Console钱包移动.
-   iOS浏览器:SDK用打开深链接的移动按钮显示模式.

综合说明:

-   QR/深链接模式被注入 `document.body`。 。 。 .
-   根容器编号为 `console-wallet-connect-placeholder`。 。 。 .
-   如果用户关闭该模式,会话会被取消并拒绝请求.
-   您可以使用 `target: 'local'`。 。 。 .
-   您可以使用 `target: 'combined'`。 。 。 .

### 5\. 获取活动账户

连接后, 获取活动账户 :

```typescript
const getAccount = async () => {
  try {
    const account = await consoleWalletPixelplex.getPrimaryAccount();
    if (account) {
      console.log('Active account:', account.partyId);
      console.log('Network:', account.networkId);
      console.log('Public key:', account.publicKey);
    }
  } catch (error) {
    console.error('Error getting account:', error);
  }
};
```

## API 方法

SDK暴露出几种通过安全消息传递与Console钱包扩展通信的高层次请求方法. 每个请求都会被自动标记为一个独特的请求ID,以确保可靠的响应匹配.

### 连接账户管理( A)

| 方法 | 说明 | 请求有效载荷 | 回应 |
| --- | --- | --- | --- |
| `connect(data)` | 提示用户将控制台钱包连接到 DApp(`target`数字 : `local` 编号 : `remote` 编号 : `combined`) (中文(简体) ). | `ConnectRequest` | `ConnectResponse` |
| `status()` | 返回 dApp 源代码的当前连接状态 . | —— 说 | `StatusEvent` |
| `disconnect()` | 从钱包中断开 DApp . | —— 说 | `DisconnectResponse` |
| `checkExtensionAvailability()` | 检查钱包浏览器扩展是否安装. | —— 说 | `AvailabilityResponse` |
| `getWalletMetadata()` | 返回钱包元数据 . | —— 说 | `MetadataResponse` |
| `isConnected()` | 检查网络是否可用 . | —— 说 | `ConnectResponse` |
| `getAccounts()` | 获取所有账户基本数据. | —— 说 | `GetAccountsResponse` |
| `getPrimaryAccount()` | 返回钱包中当前选中的账户. | —— 说 | `GetAccountResponse` |
| `getActiveNetwork()` | 返回当前选中的网络元数据 . | —— 说 | `Network` |
| `getWalletVersion()` | 获取钱包版本 . | —— 说 | `WalletVersion` |
| `ledgerAuth(request)` | 请求获得Ledger API访问令牌. | `LedgerAuthRequest` | `LedgerAuthResponse` |
| `ledgerRefresh(request)` | 刷新 Ledger API 访问令牌 . | `LedgerRefreshRequest` | `LedgerRefreshResponse` |
| `ledgerApi(request)` | 原始数据请求分类 API. | `LedgerApiRequest` | `LedgerApiResponse` |
| `getContracts(request)` | 获取由当事人过滤的活性合同和模板ID. | `ContractsRequest` | `ContractsResponse` |

### 签名交易( A)

| 方法 | 说明 | 请求有效载荷 | 回应 |
| --- | --- | --- | --- |
| `signMessage(message)` | 请用户在信件上签名(hex/base64). | `SignMessageRequest` | `SignedMessageResponse` |
| `encrypt(data)` | 请求使用活动账户密钥进行钱包侧加密 . | `EncryptMessageRequest` | `EncryptMessageResponse` |
| `decrypt(data)` | 请求带有活动账户密钥的钱包侧解密 . | `DecryptMessageRequest` | `DecryptMessageResponse` |
| `submitCommands(data)` | 签署并广播交易 发送Canton Cin. | `SignSendRequest` | `SignSendResponse` |
| `signBatch(data)` | 签署并广播一批交易. | `SignBatchRequest` | `SignBatchResponse` |
| `submitInstructionChoice(data)` | 请求用户与待定的传输指令交互 . | `SignInstructionChoiceRequest` | `SignInstructionChoiceResponse` |
| `topUpTraffic(data)` | 使用 CC (Wallet 准备、 签名和提交) 来增加发送者的流量 . | `TopUpTrafficRequest` | `TopUpTrafficResponse` |

### 平衡历史查询( H)

| 方法 | 说明 | 请求有效载荷 | 回应 |
| --- | --- | --- | --- |
| `getBalance()` | 检查党的平衡情况;包括现行Canton Cin价格. | `GetBalanceRequest` | `GetBalanceResponse` |
| `getCoinsBalance()` | 辅助硬币的制衡平衡和价格. | `GetBalanceRequest` | `GetCoinsResponse` |
| `getCoinsList()` | 获取选定网络的现有硬币列表 . | `GetCoinsListRequest` | `GetCoinsListResponse` |
| `getTrafficBalance()` | 请检查access-date=中的日期值 (帮助) 党内交通账户余额(字节;KB除以1024). | `GetTrafficBalanceRequest` | `GetTrafficBalanceResponse` |
| `convertTraffic()` | 使用当前流量价格在流量(KB)和CC之间转换. | `ConvertTrafficRequest` | `ConvertTrafficResponse` |
| `getTokenTransfers()` | 使用 pagination (indexer) 检查 party 令牌转让 . | `TokenTransfersRequest` | `TokenTransfersResponse` |
| `getTransfer()` | 请检查access-date=中的日期值 (帮助) party sorders transfer details (indexer). | `TransferRequest` | `TransferResponse` |
| `getOffers()` | 以 pagination (indexer) 检查 party 报价 . | `OffersRequest` | `OffersResponse` |
| `getNodeTransfers()` | 请检查access-date=中的日期值 (帮助) Pagination (wallet node) 的标准硬币转移. | `CoinTransfersFromNodeRequest` | `CoinTransfersFromNodeResponse` |
| `getNodeTransfer()` | 请检查access-date=中的日期值 (帮助) 单项传输细节(Wallet node). | `TransferFromNodeRequest` | `TransferFromNodeResponse` |
| `getNodeOffers()` | 使用页标(Wallet节点)检查待处理的交易/出价. | `OffersFromNodeRequest` | `OffersFromNodeResponse` |

## 用法实例

### 签名信件

请用户签名任意信件 :

```typescript
const signMessage = async () => {
  try {
    // Sign a hex-encoded message
    const signature = await consoleWalletPixelplex.signMessage({
      message: { hex: '0x48656c6c6f20576f726c64' }, // "Hello World" in hex
      metaData: {
        purpose: 'authentication',
        timestamp: new Date().toISOString(),
      },
    });
    console.log('Signature:', signature);
  } catch (error) {
    console.error('Signing failed:', error);
  }
};

// Or sign a base64-encoded message
const signBase64Message = async () => {
  try {
    const signature = await consoleWalletPixelplex.signMessage({
      message: { base64: 'SGVsbG8gV29ybGQ=' }, // "Hello World" in base64
    });
    console.log('Signature:', signature);
  } catch (error) {
    console.error('Signing failed:', error);
  }
};
```

### 加密/ 解密信件

请求钱包侧加密和解密( 相同的活动账户上下文 ) :

```typescript
import { CryptMechanism } from '@console-wallet/dapp-sdk';

const encryptDecrypt = async () => {
  const message = new TextEncoder().encode('Hello secure world');

  const encrypted = await consoleWalletPixelplex.encrypt({
    cryptMechanism: CryptMechanism.X25519_XSALSA20_POLY1305,
    message,
  });

  if (!encrypted) throw new Error('Encryption failed');

  const decrypted = await consoleWalletPixelplex.decrypt({ encrypted });

  if (!decrypted) throw new Error('Decryption failed');

  console.log(new TextDecoder().decode(decrypted));
};
```

### 发送州币交易

提交要发送 Canton Cin 的交易 :

```typescript
const sendTransaction = async () => {
  try {
    // Get the active account first
    const activeAccount = await consoleWalletPixelplex.getPrimaryAccount();

    if (!activeAccount) {
      throw new Error('No active account found');
    }

    // Submit the transaction
    const result = await consoleWalletPixelplex.submitCommands({
      from: activeAccount.partyId,
      to: 'receiver::fingerprint',
      token: 'CC', // or 'CBTC', 'USDCx'
      amount: '10.5',
      expireDate: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(), // 24 hours from now
      memo: 'Payment for services', // Optional memo
      waitForFinalization: 5000, // Optional: wait up to 5 seconds for finalization (between 2000-10000 ms)
    });

    if (result?.status) {
      console.log('Transaction submitted successfully');
      if (result.signature) {
        console.log('Transaction signature:', result.signature);
      }
      if (result.confirmationData) {
        console.log('Confirmation data:', result.confirmationData);
      }
    } else {
      console.error('Transaction failed');
    }
  } catch (error) {
    console.error('Error sending transaction:', error);
  }
};
```

### 签名批次交易

在批次中签名并发送多个交易 :

```typescript
const signBatchTransactions = async () => {
  try {
    const activeAccount = await consoleWalletPixelplex.getPrimaryAccount();

    if (!activeAccount) {
      throw new Error('No active account found');
    }

    const result = await consoleWalletPixelplex.signBatch({
      batchType: 'SEND',
      requests: [
        {
          from: activeAccount.partyId,
          to: 'receiver1::fingerprint',
          token: 'CC',
          amount: '5.0',
          expireDate: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
          type: 'OFFER',
        },
        {
          from: activeAccount.partyId,
          to: 'receiver2::fingerprint',
          token: 'CC',
          amount: '3.5',
          expireDate: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
          type: 'DIRECT_TRANSFER',
        },
      ],
    });

    if (result?.status) {
      console.log('Batch signed successfully');
      if (result.signatures) {
        console.log('Signatures:', result.signatures);
      } else if (result.signature) {
        console.log('Signature:', result.signature);
      }
    }
  } catch (error) {
    console.error('Error signing batch:', error);
  }
};
```

### 获得平衡

检查一方的余额(只有CC余额):

```typescript
const checkBalance = async () => {
  try {
    const activeAccount = await consoleWalletPixelplex.getPrimaryAccount();
    const activeNetwork = await consoleWalletPixelplex.getActiveNetwork();

    if (!activeAccount || !activeNetwork) {
      throw new Error('No active account or network found');
    }

    const balance = await consoleWalletPixelplex.getBalance({
      party: activeAccount.partyId,
      network: activeNetwork.id,
    });

    console.log('CC utxos:', balance.tokens);
    console.log('Is split balance:', balance.isSplitedBalance);
    console.log('1 CC price:', balance.price);
    // Access individual token balances
    balance.tokens.forEach((token) => {
      console.log(`${token.symbol}: ${token.balance} (USD: ${token.balanceUsd || 'N/A'})`);
    });
  } catch (error) {
    console.error('Error getting balance:', error);
  }
};
```

### 获得交通平衡

请检查access-date=中的日期值 (帮助) (返回为字节;KB除以1024):

```typescript
const checkTrafficBalance = async () => {
  try {
    const activeAccount = await consoleWalletPixelplex.getPrimaryAccount();
    const activeNetwork = await consoleWalletPixelplex.getActiveNetwork();

    if (!activeAccount || !activeNetwork) {
      throw new Error('No active account or network found');
    }

    const traffic = await consoleWalletPixelplex.getTrafficBalance({
      party: activeAccount.partyId,
      network: activeNetwork.id,
    });

    console.log('Traffic balance (bytes):', traffic.balance);
    console.log('Traffic balance (KB):', traffic.balance / 1024);
  } catch (error) {
    console.error('Error getting traffic balance:', error);
  }
};
```

### 转换流量

使用当前交通价格在交通(KB)和Canton Coin之间转换。 准确提供其中之一 `trafficAmountKB` 或者说 `ccAmount`数字 :

```typescript
const convertTrafficAmount = async () => {
  try {
    const activeNetwork = await consoleWalletPixelplex.getActiveNetwork();

    if (!activeNetwork) {
      throw new Error('No active network found');
    }

    const fromKb = await consoleWalletPixelplex.convertTraffic({
      trafficAmountKB: 1024,
      network: activeNetwork.id,
    });
    console.log('CC for 1024 KB:', fromKb.ccAmount);

    const fromCc = await consoleWalletPixelplex.convertTraffic({
      ccAmount: '1.5',
      network: activeNetwork.id,
    });
    console.log('KB for 1.5 CC:', fromCc.trafficAmountKB);
  } catch (error) {
    console.error('Error converting traffic:', error);
  }
};
```

### 交通顶端

请求钱包通过花费CC来充电连接方的流量. 钱包准备、 签名和提交传输( 网络费在钱包 UI 中显示) :

```typescript
const topUpTraffic = async () => {
  try {
    const activeAccount = await consoleWalletPixelplex.getPrimaryAccount();
    const activeNetwork = await consoleWalletPixelplex.getActiveNetwork();

    if (!activeAccount || !activeNetwork) {
      throw new Error('No active account or network found');
    }

    // Optional: convert desired KB into CC first
    const quote = await consoleWalletPixelplex.convertTraffic({
      trafficAmountKB: 20480,
      network: activeNetwork.id,
    });

    const result = await consoleWalletPixelplex.topUpTraffic({
      party: activeAccount.partyId,
      amount: quote.ccAmount,
      network: activeNetwork.id,
    });

    console.log('Top-up status:', result?.status);
    console.log('Submission:', result?.submission);
  } catch (error) {
    console.error('Error topping up traffic:', error);
  }
};
```

### 获得价格平衡

获取CC和所有CIP-56令牌价格的详细平衡信息:

```typescript
const getCoinsBalance = async () => {
  try {
    const activeAccount = await consoleWalletPixelplex.getPrimaryAccount();
    const activeNetwork = await consoleWalletPixelplex.getActiveNetwork();

    if (!activeAccount || !activeNetwork) {
      throw new Error('No active account or network found');
    }

    const coinsBalance = await consoleWalletPixelplex.getCoinsBalance({
      party: activeAccount.partyId,
      network: activeNetwork.id,
    });

    console.log('Tokens:', coinsBalance.tokens);
    console.log('Prices:', coinsBalance.prices);
  } catch (error) {
    console.error('Error getting coins balance:', error);
  }
};
```

### 通过网络获取 Coins 列表

为选中的网络获取所有可用的硬币 :

```typescript
const getCoinsList = async () => {
  try {
    const activeNetwork = await consoleWalletPixelplex.getActiveNetwork();

    if (!activeNetwork) {
      throw new Error('No active network found');
    }

    const coinsList = await consoleWalletPixelplex.getCoinsList({
      network: activeNetwork.id,
    });

    console.log('Available coins:', coinsList.items);
  } catch (error) {
    console.error('Error getting coins list:', error);
  }
};
```

### 获取交易历史

用页码查询交易历史 :

```typescript
const getTransactionHistory = async () => {
  try {
    const activeAccount = await consoleWalletPixelplex.getPrimaryAccount();

    if (!activeAccount) {
      throw new Error('No active account found');
    }

    // Get token transfers from indexer (only CC)
    const transfers = await consoleWalletPixelplex.getTokenTransfers({
      party: activeAccount.partyId,
      limit: 10,
      cursor: '0',
    });

    console.log('Transfers:', transfers.data);

    // Get token transfers directly from node (separated by token) *Preferred
    const cip56Transfers = await consoleWalletPixelplex.getNodeTransfers({
      query: { partyId: partyId, limit: 10, coin: 'CBTC', offset: 0 },
      network,
    });

    console.log('Transfers', cip56Transfers?.items);

    // Get offers from indexer (Only CC)
    const offers = await consoleWalletPixelplex.getOffers({
      party: activeAccount.partyId,
      limit: 10,
      cursor: '0',
    });

    console.log('Offers:', offers.data);

    // Get offers from node (All tokens) *Preferred
    const nodeOffers = await consoleWalletPixelplex.getNodeOffers({
      query: { party_id: partyId, limit: 10, cursor: '0' },
      network,
    });

    console.log('nodeOffers', nodeOffers?.items);
  } catch (error) {
    console.error('Error getting transaction history:', error);
  }
};
```

## 订阅

SDK提供订阅式的帮助来观看从Console钱包的更改. 这些函数注册回调,并在相应状态发生变化时引用.

| 方法 | 说明 | 回调有效载荷 |
| --- | --- | --- |
| `onAccountsChanged(onChange)` | 订阅活动账户更改 | `GetAccountResponse` |
| `onConnectionStatusChanged(onChange)` | 订阅钱包连接状态变化 | `ConnectResponse` |
| `onTxStatusChanged(onChange)` | 订阅交易状态生命周期更新 | `TxChangedEvent` |
| `onSessionRestored(options, onChange)` | 订阅关于 SDK 负载的、从索引数据库自动恢复先前持续举行的 WC会话 | `SessionRestoredEvent { sessionId, transport }` |
| `onSessionDead(options, onChange)` | 订阅导致当前 WC 会话无法使用的任何事件( 没有存储会话、 恢复错误、 服务器已死/ 关闭、 重新连接已用尽、 用户启动断开、 闲置超时) | `SessionDeadEvent { reason, sessionId?, error? }` |

### 示例:监视账户更改

```typescript
// Subscribe to account changes
consoleWalletPixelplex.onAccountsChanged((account) => {
  if (account) {
    console.log('Active account changed:', account.partyId);
    // Update your UI with the new account
  } else {
    console.log('No active account');
  }
});
```

### 示例: 监视连接状态

```typescript
// Subscribe to connection status changes
consoleWalletPixelplex.onConnectionStatusChanged((status) => {
  console.log('Connection status changed:', status);
  if (status === 'connected') {
    // User connected, enable features
  } else {
    // User disconnected, disable features
  }
});
```

### 示例: 监视交易状态

```typescript
// Subscribe to transaction status updates
consoleWalletPixelplex.onTxStatusChanged((event) => {
  console.log('Transaction status update:', event);
  // Handle transaction lifecycle events (pending, confirmed, failed, etc.)
});
```

### 示例: SDK 装入时自动创建连接状态

```typescript
// When the SDK rehydrates a stored mobile/WC session from IndexedDB,
// render the "connected" UI without waiting for the user to press Connect.
// Pass a stable `id` so re-renders / HMR never double-register the listener.
consoleWalletPixelplex.onSessionRestored(
  { id: 'connected-banner' },
  ({ sessionId, transport }) => {
    console.log('WC session restored:', sessionId, 'via', transport);
    setIsConnected(true);
    setBannerMessage(`Session restored over ${transport}`);
  },
);
```

### 示例: 当会话结束时, 撕下UI状态

```typescript
// Fire cleanup whenever the session becomes unusable, regardless of cause.
// Known `reason` values: 'no_stored_session' | 'restore_error' | 'expired' |
// 'closed' | 'user_initiated' | 'timeout' | 'server_initiated' |
// 'reconnect_exhausted' | 'unknown'.
consoleWalletPixelplex.onSessionDead(
  { id: 'connected-banner' },
  ({ reason, sessionId, error }) => {
    console.warn('WC session died:', reason, sessionId, error);
    setIsConnected(false);
    clearSessionCaches();
    if (reason === 'reconnect_exhausted') {
      showToast('Network unavailable — session expired. Please reconnect.');
    }
  },
);
```

## 处理错误

所有请求帮助者返回承诺,并可以拒绝 `ConsoleWalletError` 当出事的时候.

这个 `ConsoleWalletError` 完全兼容 [EIP-1474 (中文(简体) )](https://eips.ethereum.org/EIPS/eip-1474#error-codes) 出错代码,确保标准化出错处理体验类似于其他区块链生态系统.

### 控制台Wallet 错误接口

```typescript
type ConsoleWalletError = Error & {
  name: string;
  message: string;
  code: number; // EIP-1474 error code
  data?: unknown;
};
```

### 常见错误代码

| 代码 | 名称 | 说明 |
| --- | --- | --- |
| 4001 (英语) | 用户被拒绝 | 用户拒绝了请求. |
| 4100个 | 未经授权 | 未经批准. |
| 4200号 | 不支持的方法 | 不支持的方法 . |
| 4900号 | 断开连接 | 从钱包中断开 . |
| 4901 (英语) | 链条断开 | 与连锁断开. |
| \- 32700 号 | 解析错误 | 分析错误 . |
| \- 32600 号 | 无效的请求 | 无效的请求 . |
| \-32601号 | 方法选择 | 未找到方法 . |
| \-32602 | 无效的页 | 无效的参数 . |
| \-32603号 | 内部错误 | 内部出错. |
| \- 32000岁 | 无效的输入 | 无效的输入 . |
| \- 32001年),中国 | 资源不成立基金 | 资源未找到 . |
| \- 32002年),简称: | 资源 | 资源无着. |
| \- 32003年),简称: | 交易被拒绝 | 交易被拒绝. |
| \- 32004年),中国 | 不支持的方法 | 方法不支持 . |
| \- 32005年),简称: | 限制已过期 | 限制超过. |

-   用户驱动的错误(拒绝、无效输入、权限问题)由钱包报告,表面显示为被拒绝的许诺,带有 `ConsoleWalletError` 载荷.
-   运输级别问题(未安装延伸装置,超时期间无答复)也作为 `ConsoleWalletError` 酌情拒绝(例如账户和网络查询).
-   一些帮助者,例如: `checkAvailability()`,在内部处理超时,并以最佳状态而不是拒绝来解决.

你应该总是把电话收起来 `try`编号 :`catch` 并处理预期和意外错误:

```typescript
try {
  const accounts = await consoleWalletPixelplex.getAccounts();
  // happy path
} catch (error) {
  const err = error as ConsoleWalletError;
  if (err.code === 4001) {
    console.log('User rejected the request');
  } else {
    console.error('An error occurred:', err.message);
  }
}
```

## 交易元数据

提交交易时,您可以包括可选的元数据 :

```typescript
const transactionWithMetadata = await consoleWalletPixelplex.submitCommands({
  from: activeAccount.partyId,
  to: 'receiver::fingerprint',
  token: 'CC',
  amount: '10.0',
  expireDate: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
  memo: 'Payment for services', // Optional memo stored as transfer metadata
});
```

这个 `memo` 字段允许您在交易中附加额外信息,这些信息作为传输元数据存储,在查询交易历史时可以检索.

## 交易费用

Canton的所有交易都是免费的。 没有交易费、交通消费费用或处理交易的当地象征性费用.

## 如何运作

Console DApp SDK 提供了您 Web3 应用程序和 Console 钱包扩展之间使用浏览器本地端的通信层 `window.postMessage` API (英语).

它自动处理所有低级的邮件逻辑,因此可以专注于构建你的DApp——而不是管理通信细节.

1.  当您的 DApp 发送请求时( 例如 ), `connect()`, (中文(简体) ), `signMessage()`,或 `submitCommands()`),SDK通过 : `window.postMessage`。 。 。 .
    
2.  每一个发出的请求都被指定一个独特的请求ID,该ID同时包含在请求和扩展回复中.
    
3.  SDK会监听扩展名中接收到的响应,用ID来匹配其原始请求,并在您的应用程序中自动解析相应的承诺.
    

这种方法确保了DApp和扩展之间的可靠,同步的通信——防止种族条件,不匹配的响应,或孤行的信息处理者.

## API 参考

详细的 API 参考,请参见 TypeScript 类型定义 `src/types/`所有方法都完全输入,包括联合来文评论.

### 类型出口

SDK输出所有相关类型:

```typescript
import type {
  ConnectRequest,
  ConnectResponse,
  GetAccountResponse,
  SignMessageRequest,
  SignedMessageResponse,
  SignSendRequest,
  SignSendResponse,
  SignBatchRequest,
  SignBatchResponse,
  GetBalanceRequest,
  GetBalanceResponse,
  GetTrafficBalanceRequest,
  GetTrafficBalanceResponse,
  ConvertTrafficRequest,
  ConvertTrafficResponse,
  TopUpTrafficRequest,
  TopUpTrafficResponse,
  // ... and more
} from '@console-wallet/dapp-sdk';
```

### 工具函数

SDK提供用于正确数据格式转换的功能,以配合网络和扩展:

```typescript
import { utils } from '@console-wallet/dapp-sdk';

// Parsers for format conversion
utils.toHex(u8: Uint8Array): string
utils.toBase64(u8: Uint8Array): string
utils.hexToBytes(hex: string): Uint8Array
utils.hexToBase64(hex: string): string
utils.base64ToBytes(base64: string): Uint8Array
utils.base64toHex(base64: string): string

// Checks
utils.equalBytes(a: Uint8Array, b: Uint8Array): boolean
```

这些公用设施对于转换网络和扩展所期望的不同格式(hex、base64、字节)的数据至关重要.

## 更改日志

见 [变动情况](https://www.npmjs.com/package/@console-wallet/dapp-sdk?activeTab=code) 用于列出更改和版本历史.

## 常见问题

### @console-wallet/dapp-sdk 是什么？

Console DApp SDK允许dApps连接到一个Console钱包账户\. Console钱包是一个浏览器扩展名\. 所有交互都发生在dApp内部\. 签字时,会敦促用户在其控制台钱包浏览器扩展中签名\.

### 如何安装 @console-wallet/dapp-sdk？

在项目目录运行 npm install @console-wallet/dapp-sdk，或使用 pnpm add / yarn add / bun add。

### @console-wallet/dapp-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @console-wallet/dapp-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @console-wallet/dapp-sdk 可以商用吗？

@console-wallet/dapp-sdk 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @console-wallet/dapp-sdk 的下载量有多少？

根据 npm 官方下载统计，@console-wallet/dapp-sdk 在 2026/10/11 – 2026/11/09 这 30 天内被下载 3,323 次，日均约 111 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @console-wallet/dapp-sdk 还在维护吗？

最新版本 3\.0\.0 发布于 2026/10/09（1 个月前）；至今共发布 48 个版本，其中过去 12 个月发布了 46 个；首次发布于 2025/10/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。