@console-wallet/dapp-sdk 1.2.0 → 1.2.1

package/README.md

@@ -1,5 +1,3 @@
-based on this readme create pretty "Word" format file with integration description
-
 # 🧩 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.
@@ -23,26 +21,47 @@ With just a few lines of code, you can authenticate users, sign data, or trigger
 
 ## ⚙️ 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, or vanilla JS apps                      |
+| 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-templ` provides a **clean, unified interface** for interacting with the Canton ecosystem.
+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
+
+```bash
+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`:
+
+```html
+<script type="module">
+  import { consoleWalletPixelplex } from 'https://unpkg.com/@console-wallet/dapp-sdk@latest/dist/esm/index.js';
+</script>
+```
 
 ---
 
@@ -54,7 +73,7 @@ It handles all low-level messaging logic automatically, so you can focus on buil
 
 ### 🔄 How It Works
 
-1. When your DApp sends a request (e.g., `connect()`, `signMessage()`, or `sendTransaction()`),  
+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.
@@ -72,28 +91,126 @@ This approach ensures **reliable, asynchronous communication** between the DApp
 - ⚡ 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.
+
 ---
 
-> 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
+
+```typescript
+import { consoleWalletPixelplex } from '@console-wallet/dapp-sdk';
+```
+
+### 2. Check Wallet Availability
+
+Before attempting to connect, check if the Console Wallet extension is installed:
+
+```typescript
+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:
+
+```typescript
+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:
+
+```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);
+  }
+};
+```
+
+### 5. Get Active Account
+
+Once connected, retrieve the active account:
+
+```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);
+  }
+};
+```
+
+---
 
 ## 📡 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                          |
 | ------------------------ | --------------------------------------------------------------------------- | --------------------------------- | --------------------------------- |
-| `getAccounts()`          | Retrieves the account(s) basic data.                                        | —                                 | `GetAccountsResponse`             |
+| `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`               |
-| `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`                 |
-| `checkAvailability()`    | Checks whether the wallet browser extension is installed.                   | —                                 | `AvailabilityResponse`            |
-| `isConnected()`          | Checks if the network available.                                            | —                                 | `NetworkStatus`                   |
-| `disconnect()`           | Disconnects the DApp from the wallet.                                       | —                                 | `DisconnectResponse`              |
+
+### 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`          |
@@ -105,7 +222,298 @@ Each request is automatically tagged with a **unique request ID** to ensure reli
 
 ---
 
-### ⚠️ Error handling for requests
+## 💻 Usage Examples
+
+### Sign a Message
+
+Request the user to sign an arbitrary message:
+
+```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);
+  }
+};
+```
+
+### Send Canton Coin Transaction
+
+Submit a transaction to send Canton Coin:
+
+```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);
+  }
+};
+```
+
+### Sign a Batch of Transactions
+
+Sign and send multiple transactions in a batch:
+
+```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);
+  }
+};
+```
+
+### Get Balance
+
+Check the balance for a party (СС balance only):
+
+```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('СС 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:
+
+```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);
+  }
+};
+```
+
+### Get Transaction History
+
+Query transaction history with pagination:
+
+```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);
+  }
+};
+```
+
+---
+
+## 👀 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
+
+```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');
+  }
+});
+```
+
+### Example: Watch Connection Status
+
+```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
+  }
+});
+```
+
+### Example: Watch Transaction Status
+
+```typescript
+// 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.
 
@@ -115,7 +523,7 @@ All request helpers return Promises and can reject with a `ConsoleWalletError` w
 
 You should always wrap calls in `try`/`catch` and handle both expected and unexpected errors:
 
-```ts
+```typescript
 try {
   const accounts = await consoleWalletPixelplex.getAccounts();
   // happy path
@@ -124,78 +532,124 @@ try {
 }
 ```
 
-## 👀 Watch Requests
+---
 
-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.
+## 🔐 Transaction Metadata
 
-| 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`         |
+### Transaction Metadata
+
+When submitting transactions, you can include optional metadata:
+
+```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
+});
+```
+
+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
 
-### 🪄 Example
+The SDK supports signing various types of transactions:
 
-```js
-const handleSignSend = async () => {
-  if (!amount || !receiver || !expireDate) {
-    alert('Please fill all fields');
-    return;
-  }
+### 1. Standard Token Transfers
 
-  try {
-    const activeAccount = await consoleWalletPixelplex.getActiveAccount();
-    const signResult = await consoleWalletPixelplex.signSend({
-      to: receiver,
-      from: activeAccount.party,
-      amount,
-      expireDate,
-    });
+```typescript
+await consoleWalletPixelplex.submitCommands({
+  from: 'sender::fingerprint',
+  to: 'receiver::fingerprint',
+  token: 'CC',
+  amount: '10.0',
+  expireDate: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
+});
+```
 
-    setResult(signResult.status ? 'Transaction signed successfully' : 'Transaction error');
-  } catch (error) {
-    console.error('Error signing transaction:', error);
-    setResult('Error signing transaction');
-  }
-};
+### 2. Batch Transactions
+
+```typescript
+await consoleWalletPixelplex.signBatch({
+  batchType: 'SEND',
+  requests: [
+    // Multiple transfer requests
+  ],
+});
 ```
 
-## 📦 Installation
+### 3. Arbitrary Message Signing
 
-```bash
-npm install @console-wallet/dapp-sdk
-# or
-yarn add @console-wallet/dapp-sdk
+Sign any message for authentication or verification purposes:
 
+```typescript
+await consoleWalletPixelplex.signMessage({
+  message: { hex: '0x...' }, // or { base64: '...' }
+  metaData: {
+    purpose: 'authentication',
+    // Any additional metadata
+  },
+});
 ```
 
-Before your DApp can interact with the **Console Wallet Extension**, it needs to **initialize a connection session**.  
-This step establishes secure communication between your web application and the user’s wallet.
+---
 
-### 🔌 Connecting Your DApp
+## 📚 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:
+
+```typescript
+import type {
+  ConnectRequest,
+  ConnectResponse,
+  GetAccountResponse,
+  SignMessageRequest,
+  SignedMessageResponse,
+  SignSendRequest,
+  SignSendResponse,
+  SignBatchRequest,
+  SignBatchResponse,
+  GetBalanceRequest,
+  GetBalanceResponse,
+  // ... and more
+} from '@console-wallet/dapp-sdk';
+```
 
-The SDK provides a simple `connect()` method that requests permission from the user’s Console Wallet.
+### Utility Functions
 
-```js
-import { consoleWalletPixelplex } from 'console-wallet-dapp-templ';
+The SDK provides utility functions for correct data format conversion required for working with the network and extension:
 
-const handleConnect = async () => {
-  try {
-    await consoleWalletPixelplex.connect({ name, icon });
-  } catch (error) {
-    console.error('Error checking connection:', error);
-  }
-};
+```typescript
+import { utils } from '@console-wallet/dapp-sdk';
 
-const handleCheckConnection = async () => {
-  try {
-    const connected = await consoleWalletPixelplex.status();
-    setConnectionStatus(connected);
-  } catch (error) {
-    console.error('Error checking connection:', error);
-  }
-};
+// 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](./CHANGELOG.md) for a list of changes and version history.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@console-wallet/dapp-sdk",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",