控制台 DApp SDK

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

此 SDK 兼容 CIP-0103 (中文(简体) ) 标准.

安装

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

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

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

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

使用指南

1. 进口SDK

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

2. 检查钱包的可用性

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

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. 检查连接状态

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

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 元数据 :

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 流量时 :

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. 获取活动账户

连接后, 获取活动账户 :

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)

签名交易( A)

平衡历史查询( H)

用法实例

签名信件

请用户签名任意信件 :

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);
  }
};

加密/ 解密信件

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

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 的交易 :

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);
  }
};

签名批次交易

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

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余额):

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):

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数字 :

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 中显示) :

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令牌价格的详细平衡信息:

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 列表

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

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);
  }
};

获取交易历史

用页码查询交易历史 :

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钱包的更改. 这些函数注册回调,并在相应状态发生变化时引用.

示例:监视账户更改

// 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');
  }
});

示例: 监视连接状态

// 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
  }
});

示例: 监视交易状态

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

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

// 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状态

// 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 (中文(简体) ) 出错代码,确保标准化出错处理体验类似于其他区块链生态系统.

控制台Wallet 错误接口

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

常见错误代码

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

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

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);
  }
}

交易元数据

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

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输出所有相关类型:

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提供用于正确数据格式转换的功能,以配合网络和扩展:

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、字节)的数据至关重要.

更改日志

见 变动情况 用于列出更改和版本历史.