🧩 Console DApp SDK

A lightweight SDK for connecting your Web3 applications to the Console Wallet Extension — enabling account access, connection status, message signing, and sending Canton Coin with ease.

🚀 Overview

Console DApp SDK is a developer-friendly library that allows any decentralized application (DApp) to seamlessly integrate with the Console Wallet browser extension.

It provides simple APIs to:

• 🔗 Connect your DApp to a user’s Console Wallet
• 👤 Access the active account and connection state
• ✍️ Request message signing to the wallet
• 💰 Send Canton Coin transactions securely and reliably

With just a few lines of code, you can authenticate users, sign data, or trigger Canton blockchain transactions — all through a unified SDK built for simplicity and safety.

⚙️ Key Features

| Feature | Description | | -------------------------- |------------------------------------------------------------------| | 🔌 Easy Integration | One SDK import connects your app to Console Wallet instantly | | 👛 Account Access | Retrieve connected account address and chain info | | 🧾 Message Signing | Sign arbitrary messages or typed data directly from the wallet | | 💸 Transaction Support | Send Canton Coin with a simple API call | | 🔒 Secure by Design | Uses wallet’s native permissions and confirmation flows | | 🧠 Framework Agnostic | Works with React, Vue, Angular, Svelte or vanilla JS apps | | 📊 Balance & History | Query balances, transfers, and transaction history | | 🔄 Real-time Updates | Subscribe to account, connection, and transaction status changes |

🧠 Why Use Console DApp SDK?

Instead of manually handling RPC connections or building custom wallet logic, @console-wallet/dapp-sdk provides a clean, unified interface for interacting with the Canton ecosystem.

It’s ideal for:

• Light start with Canton blockchain
• Web3 DApps that need wallet connection and signing
• Any app that interacts with Canton
• Applications requiring transaction history and balance queries

📦 Installation

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

If you don't want to implement a build process, you can include the file directly with unpkg:

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

🧠 Core Functionality

The Console DApp SDK provides a communication layer between your Web3 application and the Console Wallet Extension using the browser’s native window.postMessage API.

It handles all low-level messaging logic automatically, so you can focus on building your DApp — not managing communication details.

🔄 How It Works

1. When your DApp sends a request (e.g., connect(), signMessage(), or submitCommands()),
   the SDK transmits a structured message to the Console Wallet Extension via window.postMessage.

2. Each outgoing request is assigned a unique request ID, which is included in both the request and the extension’s response.

3. The SDK listens for incoming responses from the extension, matches them to their original request using the ID,
   and automatically resolves the corresponding Promise in your application.

This approach ensures reliable, asynchronous communication between the DApp and the extension — preventing race conditions, mismatched responses, or orphaned message handlers.

🧩 Benefits

• ✅ Fully type-safe and asynchronous API
• 🧭 No manual message listeners required
• 🛡️ Prevents response mismatch errors with per-request unique IDs
• ⚡ Lightweight and dependency-free
• 🧠 Extensible for future Console Wallet capabilities (multi-chain support, session management, etc.)

In short: the SDK abstracts all the complex message passing between your DApp and the wallet, providing a stable and predictable communication layer out of the box.

🔌 Quick Start

1. Import the SDK

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

2. Check Wallet Availability

Before attempting to connect, check if the Console Wallet extension is installed:

const checkWallet = async () => {
  try {
    const availability = await consoleWalletPixelplex.checkExtensionAvailability();
    if (availability === 'installed') {
      console.log('Console Wallet is installed');
    } else {
      console.log('Console Wallet is not installed');
      // Show installation instructions to the user
    }
  } catch (error) {
    console.error('Error checking wallet availability:', error);
  }
};

3. Check Connection Status

You can check the current connection status at any time:

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

4. Connect to the Wallet

To initiate the connection, call connect() with optional dApp metadata:

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

5. Get Active Account

Once connected, retrieve the active account:

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

📡 Supported Requests

The SDK exposes several high-level request methods that communicate with the Console Wallet Extension through secure message passing.
Each request is automatically tagged with a unique request ID to ensure reliable response matching.

Connection & Account Management

| Method | Description | Request Payload | Response | | ------------------------ | --------------------------------------------------------------------------- | --------------------------------- | --------------------------------- | | connect(data) | Prompts the user to connect their Console Wallet to the DApp. | ConnectRequest | ConnectResponse | | status() | Returns current connection status for the dApp origin. | — | ConnectResponse | | disconnect() | Disconnects the DApp from the wallet. | — | DisconnectResponse | | checkExtensionAvailability() | Checks whether the wallet browser extension is installed. | — | AvailabilityResponse | | isConnected() | Checks if the network is available. | — | NetworkStatus | | getAccounts() | Retrieves all account(s) basic data. | — | GetAccountsResponse | | getPrimaryAccount() | Returns the currently selected account in the Wallet. | — | GetAccountResponse | | getActiveNetwork() | Returns the currently selected network metadata. | — | Network |

Signing & Transactions

| Method | Description | Request Payload | Response | | ------------------------ | --------------------------------------------------------------------------- | --------------------------------- | --------------------------------- | | signMessage(message) | Requests the user to sign a message (hex/base64). | SignMessageRequest | SignedMessageResponse | | submitCommands(data) | Signs and broadcasts a transaction to send Canton Coin. | SignSendRequest | SignSendResponse | | signBatch(data) | Signs and broadcasts a batch of transactions. | SignBatchRequest | SignBatchResponse |

Balance & History Queries

| Method | Description | Request Payload | Response | | ------------------------ | --------------------------------------------------------------------------- | --------------------------------- | --------------------------------- | | getBalance() | Check party balance; includes current Canton Coin price. | GetBalanceRequest | GetBalanceResponse | | getCoinsBalance() | Check balances and prices for supported coins. | GetBalanceRequest | GetCoinsResponse | | getTokenTransfers() | Check party token transfers with pagination (indexer). | TokenTransfersRequest | TokenTransfersResponse | | getTransfer() | Check party token transfer details (indexer). | TransferRequest | TransferResponse | | getOffers() | Check party offers with pagination (indexer). | OffersRequest | OffersResponse | | getNodeTransfers() | Check standard coin transfers with pagination (wallet node). | CoinTransfersFromNodeRequest | CoinTransfersFromNodeResponse | | getNodeTransfer() | Check single transfer details (wallet node). | TransferFromNodeRequest | TransferFromNodeResponse | | getNodeOffers() | Check pending transactions/offers with pagination (wallet node). | OffersFromNodeRequest | OffersFromNodeResponse |

💻 Usage Examples

Sign a Message

Request the user to sign an arbitrary message:

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

Send Canton Coin Transaction

Submit a transaction to send Canton Coin:

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

Sign a Batch of Transactions

Sign and send multiple transactions in a batch:

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

Get Balance

Check the balance for a party (СС balance only):

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

Get Coins Balance with Prices

Get detailed balance information with prices for CC and all CIP-56 tokens:

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

Get Transaction History

Query transaction history with pagination:

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

👀 Watch Requests (Subscriptions)

The SDK also provides subscription-style helpers to watch for changes from the Console Wallet. These functions register a callback and invoke it whenever the corresponding state changes.

| Method | Description | Callback Payload | | ------------------------------ | --------------------------------------------------------- | ------------------------ | | onAccountsChanged(onChange) | Subscribes to active account changes | GetAccountResponse | | onConnectionStatusChanged(onChange) | Subscribes to wallet connection status changes | ConnectResponse | | onTxStatusChanged(onChange) | Subscribes to transaction status lifecycle updates | TxChangedEvent |

Example: Watch Account Changes

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

Example: Watch Connection Status

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

Example: Watch Transaction Status

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

⚠️ Error Handling

All request helpers return Promises and can reject with a ConsoleWalletError when something goes wrong.

• User-driven errors (rejection, invalid input, permission issues) are reported by the wallet and surfaced as rejected Promises with a ConsoleWalletError payload.
• Transport-level issues (extension not installed, no response within the timeout) are also represented as ConsoleWalletError rejections where applicable (for example, account and network queries).
• Some helpers, such as checkAvailability(), internally handle timeouts and resolve with a best-effort status instead of rejecting.

You should always wrap calls in try/catch and handle both expected and unexpected errors:

try {
  const accounts = await consoleWalletPixelplex.getAccounts();
  // happy path
} catch (error) {
  // error is typically a ConsoleWalletError with message/code
}

🔐 Transaction Metadata

Transaction Metadata

When submitting transactions, you can include optional metadata:

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

The memo field allows you to attach additional information to the transaction, which is stored as transfer metadata and can be retrieved when querying transaction history.

Cost Estimation

All transactions on Canton are free. There are no transaction fees, traffic consumption costs, or native token costs for transaction processing.

🎯 Signing Any Transaction Type

The SDK supports signing various types of transactions:

1. Standard Token Transfers

await consoleWalletPixelplex.submitCommands({
  from: 'sender::fingerprint',
  to: 'receiver::fingerprint',
  token: 'CC',
  amount: '10.0',
  expireDate: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
});

2. Batch Transactions

await consoleWalletPixelplex.signBatch({
  batchType: 'SEND',
  requests: [
    // Multiple transfer requests
  ],
});

3. Arbitrary Message Signing

Sign any message for authentication or verification purposes:

await consoleWalletPixelplex.signMessage({
  message: { hex: '0x...' }, // or { base64: '...' }
  metaData: {
    purpose: 'authentication',
    // Any additional metadata
  },
});

📚 API Reference

For detailed API reference, see the TypeScript type definitions in src/types/. All methods are fully typed and include JSDoc comments.

Type Exports

The SDK exports all relevant types:

import type {
  ConnectRequest,
  ConnectResponse,
  GetAccountResponse,
  SignMessageRequest,
  SignedMessageResponse,
  SignSendRequest,
  SignSendResponse,
  SignBatchRequest,
  SignBatchResponse,
  GetBalanceRequest,
  GetBalanceResponse,
  // ... and more
} from '@console-wallet/dapp-sdk';

Utility Functions

The SDK provides utility functions for correct data format conversion required for working with the network and extension:

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

These utilities are essential for converting data between different formats (hex, base64, bytes) that the network and extension expect.

📝 Changelog

See CHANGELOG.md for a list of changes and version history.