@console-wallet/dapp-sdk 1.1.2 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (103) hide show
  1. package/CHANGELOG.md +54 -3
  2. package/README.md +534 -60
  3. package/dist/cjs/index.d.ts +1 -0
  4. package/dist/cjs/requests/checkAvailability.d.ts +12 -0
  5. package/dist/cjs/requests/checkAvailability.js +48 -0
  6. package/dist/cjs/requests/checkAvailability.js.map +1 -0
  7. package/dist/cjs/requests/connect.js +7 -2
  8. package/dist/cjs/requests/connect.js.map +1 -1
  9. package/dist/cjs/requests/disconnect.js +7 -2
  10. package/dist/cjs/requests/disconnect.js.map +1 -1
  11. package/dist/cjs/requests/getAccounts.js +14 -2
  12. package/dist/cjs/requests/getAccounts.js.map +1 -1
  13. package/dist/cjs/requests/getActiveAccount.js +14 -2
  14. package/dist/cjs/requests/getActiveAccount.js.map +1 -1
  15. package/dist/cjs/requests/getActiveNetwork.js +14 -2
  16. package/dist/cjs/requests/getActiveNetwork.js.map +1 -1
  17. package/dist/cjs/requests/getBalance.js +7 -2
  18. package/dist/cjs/requests/getBalance.js.map +1 -1
  19. package/dist/cjs/requests/getCoinsBalance.js +7 -2
  20. package/dist/cjs/requests/getCoinsBalance.js.map +1 -1
  21. package/dist/cjs/requests/getIsConnected.js +14 -2
  22. package/dist/cjs/requests/getIsConnected.js.map +1 -1
  23. package/dist/cjs/requests/getNodeOffers.js +7 -2
  24. package/dist/cjs/requests/getNodeOffers.js.map +1 -1
  25. package/dist/cjs/requests/getNodeTransfer.js +7 -2
  26. package/dist/cjs/requests/getNodeTransfer.js.map +1 -1
  27. package/dist/cjs/requests/getNodeTransfers.js +7 -2
  28. package/dist/cjs/requests/getNodeTransfers.js.map +1 -1
  29. package/dist/cjs/requests/getOffers.js +7 -2
  30. package/dist/cjs/requests/getOffers.js.map +1 -1
  31. package/dist/cjs/requests/getStatus.js +14 -2
  32. package/dist/cjs/requests/getStatus.js.map +1 -1
  33. package/dist/cjs/requests/getTransfer.js +7 -2
  34. package/dist/cjs/requests/getTransfer.js.map +1 -1
  35. package/dist/cjs/requests/getTransfers.js +7 -2
  36. package/dist/cjs/requests/getTransfers.js.map +1 -1
  37. package/dist/cjs/requests/index.d.ts +1 -0
  38. package/dist/cjs/requests/index.js +1 -0
  39. package/dist/cjs/requests/index.js.map +1 -1
  40. package/dist/cjs/requests/signMessage.js +7 -2
  41. package/dist/cjs/requests/signMessage.js.map +1 -1
  42. package/dist/cjs/requests/singBatch.js +7 -2
  43. package/dist/cjs/requests/singBatch.js.map +1 -1
  44. package/dist/cjs/requests/submitCommands.js +7 -2
  45. package/dist/cjs/requests/submitCommands.js.map +1 -1
  46. package/dist/cjs/types/connect.type.d.ts +4 -0
  47. package/dist/cjs/types/error.type.d.ts +4 -0
  48. package/dist/cjs/types/error.type.js +3 -0
  49. package/dist/cjs/types/error.type.js.map +1 -0
  50. package/dist/cjs/types/index.d.ts +1 -0
  51. package/dist/cjs/types/index.js +1 -0
  52. package/dist/cjs/types/index.js.map +1 -1
  53. package/dist/esm/index.d.ts +1 -0
  54. package/dist/esm/requests/checkAvailability.d.ts +12 -0
  55. package/dist/esm/requests/checkAvailability.js +44 -0
  56. package/dist/esm/requests/checkAvailability.js.map +1 -0
  57. package/dist/esm/requests/connect.js +7 -2
  58. package/dist/esm/requests/connect.js.map +1 -1
  59. package/dist/esm/requests/disconnect.js +7 -2
  60. package/dist/esm/requests/disconnect.js.map +1 -1
  61. package/dist/esm/requests/getAccounts.js +14 -2
  62. package/dist/esm/requests/getAccounts.js.map +1 -1
  63. package/dist/esm/requests/getActiveAccount.js +14 -2
  64. package/dist/esm/requests/getActiveAccount.js.map +1 -1
  65. package/dist/esm/requests/getActiveNetwork.js +14 -2
  66. package/dist/esm/requests/getActiveNetwork.js.map +1 -1
  67. package/dist/esm/requests/getBalance.js +7 -2
  68. package/dist/esm/requests/getBalance.js.map +1 -1
  69. package/dist/esm/requests/getCoinsBalance.js +7 -2
  70. package/dist/esm/requests/getCoinsBalance.js.map +1 -1
  71. package/dist/esm/requests/getIsConnected.js +14 -2
  72. package/dist/esm/requests/getIsConnected.js.map +1 -1
  73. package/dist/esm/requests/getNodeOffers.js +7 -2
  74. package/dist/esm/requests/getNodeOffers.js.map +1 -1
  75. package/dist/esm/requests/getNodeTransfer.js +7 -2
  76. package/dist/esm/requests/getNodeTransfer.js.map +1 -1
  77. package/dist/esm/requests/getNodeTransfers.js +7 -2
  78. package/dist/esm/requests/getNodeTransfers.js.map +1 -1
  79. package/dist/esm/requests/getOffers.js +7 -2
  80. package/dist/esm/requests/getOffers.js.map +1 -1
  81. package/dist/esm/requests/getStatus.js +14 -2
  82. package/dist/esm/requests/getStatus.js.map +1 -1
  83. package/dist/esm/requests/getTransfer.js +7 -2
  84. package/dist/esm/requests/getTransfer.js.map +1 -1
  85. package/dist/esm/requests/getTransfers.js +7 -2
  86. package/dist/esm/requests/getTransfers.js.map +1 -1
  87. package/dist/esm/requests/index.d.ts +1 -0
  88. package/dist/esm/requests/index.js +1 -0
  89. package/dist/esm/requests/index.js.map +1 -1
  90. package/dist/esm/requests/signMessage.js +7 -2
  91. package/dist/esm/requests/signMessage.js.map +1 -1
  92. package/dist/esm/requests/singBatch.js +7 -2
  93. package/dist/esm/requests/singBatch.js.map +1 -1
  94. package/dist/esm/requests/submitCommands.js +7 -2
  95. package/dist/esm/requests/submitCommands.js.map +1 -1
  96. package/dist/esm/types/connect.type.d.ts +4 -0
  97. package/dist/esm/types/error.type.d.ts +4 -0
  98. package/dist/esm/types/error.type.js +2 -0
  99. package/dist/esm/types/error.type.js.map +1 -0
  100. package/dist/esm/types/index.d.ts +1 -0
  101. package/dist/esm/types/index.js +1 -0
  102. package/dist/esm/types/index.js.map +1 -1
  103. package/package.json +1 -1
package/README.md CHANGED
@@ -1,5 +1,3 @@
1
- based on this readme create pretty "Word" format file with integration description
2
-
3
1
  # 🧩 Console DApp SDK
4
2
 
5
3
  > 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
23
21
 
24
22
  ## ⚙️ Key Features
25
23
 
26
- | Feature | Description |
27
- | -------------------------- | -------------------------------------------------------------- |
28
- | 🔌 **Easy Integration** | One SDK import connects your app to Console Wallet instantly |
29
- | 👛 **Account Access** | Retrieve connected account address and chain info |
30
- | 🧾 **Message Signing** | Sign arbitrary messages or typed data directly from the wallet |
31
- | 💸 **Transaction Support** | Send Canton Coin with a simple API call |
32
- | 🔒 **Secure by Design** | Uses wallet’s native permissions and confirmation flows |
33
- | 🧠 **Framework Agnostic** | Works with React, Vue, or vanilla JS apps |
24
+ | Feature | Description |
25
+ | -------------------------- |------------------------------------------------------------------|
26
+ | 🔌 **Easy Integration** | One SDK import connects your app to Console Wallet instantly |
27
+ | 👛 **Account Access** | Retrieve connected account address and chain info |
28
+ | 🧾 **Message Signing** | Sign arbitrary messages or typed data directly from the wallet |
29
+ | 💸 **Transaction Support** | Send Canton Coin with a simple API call |
30
+ | 🔒 **Secure by Design** | Uses wallet’s native permissions and confirmation flows |
31
+ | 🧠 **Framework Agnostic** | Works with React, Vue, Angular, Svelte or vanilla JS apps |
32
+ | 📊 **Balance & History** | Query balances, transfers, and transaction history |
33
+ | 🔄 **Real-time Updates** | Subscribe to account, connection, and transaction status changes |
34
34
 
35
35
  ---
36
36
 
37
37
  ## 🧠 Why Use Console DApp SDK?
38
38
 
39
- 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.
39
+ 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.
40
40
 
41
41
  It’s ideal for:
42
42
 
43
43
  - Light start with Canton blockchain
44
44
  - Web3 DApps that need wallet connection and signing
45
45
  - Any app that interacts with Canton
46
+ - Applications requiring transaction history and balance queries
47
+
48
+ ---
49
+
50
+ ## 📦 Installation
51
+
52
+ ```bash
53
+ npm install @console-wallet/dapp-sdk
54
+ # or
55
+ yarn add @console-wallet/dapp-sdk
56
+ ```
57
+
58
+ If you don't want to implement a build process, you can include the file directly with `unpkg`:
59
+
60
+ ```html
61
+ <script type="module">
62
+ import { consoleWalletPixelplex } from 'https://unpkg.com/@console-wallet/dapp-sdk@latest/dist/esm/index.js';
63
+ </script>
64
+ ```
46
65
 
47
66
  ---
48
67
 
@@ -54,7 +73,7 @@ It handles all low-level messaging logic automatically, so you can focus on buil
54
73
 
55
74
  ### 🔄 How It Works
56
75
 
57
- 1. When your DApp sends a request (e.g., `connect()`, `signMessage()`, or `sendTransaction()`),
76
+ 1. When your DApp sends a request (e.g., `connect()`, `signMessage()`, or `submitCommands()`),
58
77
  the SDK transmits a structured message to the **Console Wallet Extension** via `window.postMessage`.
59
78
 
60
79
  2. Each outgoing request is assigned a **unique request ID**, which is included in both the request and the extension’s response.
@@ -72,27 +91,126 @@ This approach ensures **reliable, asynchronous communication** between the DApp
72
91
  - ⚡ Lightweight and dependency-free
73
92
  - 🧠 Extensible for future Console Wallet capabilities (multi-chain support, session management, etc.)
74
93
 
94
+ > 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.
95
+
75
96
  ---
76
97
 
77
- > 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.
98
+ ## 🔌 Quick Start
99
+
100
+ ### 1. Import the SDK
101
+
102
+ ```typescript
103
+ import { consoleWalletPixelplex } from '@console-wallet/dapp-sdk';
104
+ ```
105
+
106
+ ### 2. Check Wallet Availability
107
+
108
+ Before attempting to connect, check if the Console Wallet extension is installed:
109
+
110
+ ```typescript
111
+ const checkWallet = async () => {
112
+ try {
113
+ const availability = await consoleWalletPixelplex.checkExtensionAvailability();
114
+ if (availability === 'installed') {
115
+ console.log('Console Wallet is installed');
116
+ } else {
117
+ console.log('Console Wallet is not installed');
118
+ // Show installation instructions to the user
119
+ }
120
+ } catch (error) {
121
+ console.error('Error checking wallet availability:', error);
122
+ }
123
+ };
124
+ ```
125
+
126
+ ### 3. Check Connection Status
127
+
128
+ You can check the current connection status at any time:
129
+
130
+ ```typescript
131
+ const checkStatus = async () => {
132
+ try {
133
+ const status = await consoleWalletPixelplex.status();
134
+ console.log('Connection status:', status); // 'connected' or 'disconnected'
135
+ } catch (error) {
136
+ console.error('Error checking status:', error);
137
+ }
138
+ };
139
+ ```
140
+
141
+ ### 4. Connect to the Wallet
142
+
143
+ To initiate the connection, call `connect()` with optional dApp metadata:
144
+
145
+ ```typescript
146
+ const handleConnect = async () => {
147
+ try {
148
+ const status = await consoleWalletPixelplex.connect({
149
+ name: 'My Awesome dApp',
150
+ icon: 'https://example.com/icon.png', // Optional: absolute URL to your dApp icon
151
+ });
152
+
153
+ if (status === 'connected') {
154
+ console.log('Successfully connected to Console Wallet');
155
+ // Proceed with your dApp logic
156
+ }
157
+ } catch (error) {
158
+ console.error('Connection rejected or failed:', error);
159
+ }
160
+ };
161
+ ```
162
+
163
+ ### 5. Get Active Account
164
+
165
+ Once connected, retrieve the active account:
166
+
167
+ ```typescript
168
+ const getAccount = async () => {
169
+ try {
170
+ const account = await consoleWalletPixelplex.getPrimaryAccount();
171
+ if (account) {
172
+ console.log('Active account:', account.partyId);
173
+ console.log('Network:', account.networkId);
174
+ console.log('Public key:', account.publicKey);
175
+ }
176
+ } catch (error) {
177
+ console.error('Error getting account:', error);
178
+ }
179
+ };
180
+ ```
181
+
182
+ ---
78
183
 
79
184
  ## 📡 Supported Requests
80
185
 
81
186
  The SDK exposes several high-level request methods that communicate with the **Console Wallet Extension** through secure message passing.
82
187
  Each request is automatically tagged with a **unique request ID** to ensure reliable response matching.
83
188
 
189
+ ### Connection & Account Management
190
+
84
191
  | Method | Description | Request Payload | Response |
85
192
  | ------------------------ | --------------------------------------------------------------------------- | --------------------------------- | --------------------------------- |
86
- | `getAccounts()` | Retrieves the account(s) basic data. | | `GetAccountsResponse` |
193
+ | `connect(data)` | Prompts the user to connect their Console Wallet to the DApp. | `ConnectRequest` | `ConnectResponse` |
194
+ | `status()` | Returns current connection status for the dApp origin. | — | `ConnectResponse` |
195
+ | `disconnect()` | Disconnects the DApp from the wallet. | — | `DisconnectResponse` |
196
+ | `checkExtensionAvailability()` | Checks whether the wallet browser extension is installed. | — | `AvailabilityResponse` |
197
+ | `isConnected()` | Checks if the network is available. | — | `NetworkStatus` |
198
+ | `getAccounts()` | Retrieves all account(s) basic data. | — | `GetAccountsResponse` |
87
199
  | `getPrimaryAccount()` | Returns the currently selected account in the Wallet. | — | `GetAccountResponse` |
88
200
  | `getActiveNetwork()` | Returns the currently selected network metadata. | — | `Network` |
201
+
202
+ ### Signing & Transactions
203
+
204
+ | Method | Description | Request Payload | Response |
205
+ | ------------------------ | --------------------------------------------------------------------------- | --------------------------------- | --------------------------------- |
89
206
  | `signMessage(message)` | Requests the user to sign a message (hex/base64). | `SignMessageRequest` | `SignedMessageResponse` |
90
207
  | `submitCommands(data)` | Signs and broadcasts a transaction to send Canton Coin. | `SignSendRequest` | `SignSendResponse` |
91
208
  | `signBatch(data)` | Signs and broadcasts a batch of transactions. | `SignBatchRequest` | `SignBatchResponse` |
92
- | `connect(data)` | Prompts the user to connect their Console Wallet to the DApp. | `ConnectRequest` | `ConnectResponse` |
93
- | `status()` | Returns current connection status for the dApp origin. | — | `ConnectResponse` |
94
- | `isConnected()` | Checks if the network available. | — | `NetworkStatus` |
95
- | `disconnect()` | Disconnects the DApp from the wallet. | | `DisconnectResponse` |
209
+
210
+ ### Balance & History Queries
211
+
212
+ | Method | Description | Request Payload | Response |
213
+ | ------------------------ | --------------------------------------------------------------------------- | --------------------------------- | --------------------------------- |
96
214
  | `getBalance()` | Check party balance; includes current Canton Coin price. | `GetBalanceRequest` | `GetBalanceResponse` |
97
215
  | `getCoinsBalance()` | Check balances and prices for supported coins. | `GetBalanceRequest` | `GetCoinsResponse` |
98
216
  | `getTokenTransfers()` | Check party token transfers with pagination (indexer). | `TokenTransfersRequest` | `TokenTransfersResponse` |
@@ -104,78 +222,434 @@ Each request is automatically tagged with a **unique request ID** to ensure reli
104
222
 
105
223
  ---
106
224
 
107
- ## 👀 Watch Requests
225
+ ## 💻 Usage Examples
108
226
 
109
- 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.
227
+ ### Sign a Message
110
228
 
111
- | Method | Description | Callback Payload |
112
- | ------------------------------ | --------------------------------------------------------- | ------------------------ |
113
- | `onAccountsChanged(onChange)` | Subscribes to active account changes | `GetAccountResponse` |
114
- | `onConnectionStatusChanged(onChange)` | Subscribes to wallet connection status changes | `ConnectResponse` |
115
- | `onTxStatusChanged(onChange)` | Subscribes to transaction status lifecycle updates | `TxChangedEvent` |
229
+ Request the user to sign an arbitrary message:
116
230
 
117
- ---
231
+ ```typescript
232
+ const signMessage = async () => {
233
+ try {
234
+ // Sign a hex-encoded message
235
+ const signature = await consoleWalletPixelplex.signMessage({
236
+ message: { hex: '0x48656c6c6f20576f726c64' }, // "Hello World" in hex
237
+ metaData: {
238
+ purpose: 'authentication',
239
+ timestamp: new Date().toISOString(),
240
+ },
241
+ });
242
+ console.log('Signature:', signature);
243
+ } catch (error) {
244
+ console.error('Signing failed:', error);
245
+ }
246
+ };
118
247
 
248
+ // Or sign a base64-encoded message
249
+ const signBase64Message = async () => {
250
+ try {
251
+ const signature = await consoleWalletPixelplex.signMessage({
252
+ message: { base64: 'SGVsbG8gV29ybGQ=' }, // "Hello World" in base64
253
+ });
254
+ console.log('Signature:', signature);
255
+ } catch (error) {
256
+ console.error('Signing failed:', error);
257
+ }
258
+ };
259
+ ```
119
260
 
120
- ### 🪄 Example
261
+ ### Send Canton Coin Transaction
121
262
 
122
- ```js
123
- const handleSignSend = async () => {
124
- if (!amount || !receiver || !expireDate) {
125
- alert('Please fill all fields');
126
- return;
127
- }
263
+ Submit a transaction to send Canton Coin:
128
264
 
265
+ ```typescript
266
+ const sendTransaction = async () => {
129
267
  try {
130
- const activeAccount = await consoleWalletPixelplex.getActiveAccount();
131
- const signResult = await consoleWalletPixelplex.signSend({
132
- to: receiver,
133
- from: activeAccount.party,
134
- amount,
135
- expireDate,
268
+ // Get the active account first
269
+ const activeAccount = await consoleWalletPixelplex.getPrimaryAccount();
270
+
271
+ if (!activeAccount) {
272
+ throw new Error('No active account found');
273
+ }
274
+
275
+ // Submit the transaction
276
+ const result = await consoleWalletPixelplex.submitCommands({
277
+ from: activeAccount.partyId,
278
+ to: 'receiver::fingerprint',
279
+ token: 'CC', // or 'CBTC', 'USDCx'
280
+ amount: '10.5',
281
+ expireDate: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(), // 24 hours from now
282
+ memo: 'Payment for services', // Optional memo
283
+ waitForFinalization: 5000, // Optional: wait up to 5 seconds for finalization (between 2000-10000 ms)
136
284
  });
137
285
 
138
- setResult(signResult.status ? 'Transaction signed successfully' : 'Transaction error');
286
+ if (result?.status) {
287
+ console.log('Transaction submitted successfully');
288
+ if (result.signature) {
289
+ console.log('Transaction signature:', result.signature);
290
+ }
291
+ if (result.confirmationData) {
292
+ console.log('Confirmation data:', result.confirmationData);
293
+ }
294
+ } else {
295
+ console.error('Transaction failed');
296
+ }
139
297
  } catch (error) {
140
- console.error('Error signing transaction:', error);
141
- setResult('Error signing transaction');
298
+ console.error('Error sending transaction:', error);
142
299
  }
143
300
  };
144
301
  ```
145
302
 
146
- ## 📦 Installation
303
+ ### Sign a Batch of Transactions
147
304
 
148
- ```bash
149
- npm install @console-wallet/dapp-sdk
150
- # or
151
- yarn add @console-wallet/dapp-sdk
305
+ Sign and send multiple transactions in a batch:
306
+
307
+ ```typescript
308
+ const signBatchTransactions = async () => {
309
+ try {
310
+ const activeAccount = await consoleWalletPixelplex.getPrimaryAccount();
311
+
312
+ if (!activeAccount) {
313
+ throw new Error('No active account found');
314
+ }
315
+
316
+ const result = await consoleWalletPixelplex.signBatch({
317
+ batchType: 'SEND',
318
+ requests: [
319
+ {
320
+ from: activeAccount.partyId,
321
+ to: 'receiver1::fingerprint',
322
+ token: 'CC',
323
+ amount: '5.0',
324
+ expireDate: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
325
+ type: 'OFFER',
326
+ },
327
+ {
328
+ from: activeAccount.partyId,
329
+ to: 'receiver2::fingerprint',
330
+ token: 'CC',
331
+ amount: '3.5',
332
+ expireDate: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
333
+ type: 'DIRECT_TRANSFER',
334
+ },
335
+ ],
336
+ });
152
337
 
338
+ if (result?.status) {
339
+ console.log('Batch signed successfully');
340
+ if (result.signatures) {
341
+ console.log('Signatures:', result.signatures);
342
+ } else if (result.signature) {
343
+ console.log('Signature:', result.signature);
344
+ }
345
+ }
346
+ } catch (error) {
347
+ console.error('Error signing batch:', error);
348
+ }
349
+ };
153
350
  ```
154
351
 
155
- Before your DApp can interact with the **Console Wallet Extension**, it needs to **initialize a connection session**.
156
- This step establishes secure communication between your web application and the user’s wallet.
352
+ ### Get Balance
157
353
 
158
- ### 🔌 Connecting Your DApp
354
+ Check the balance for a party (СС balance only):
159
355
 
160
- The SDK provides a simple `connect()` method that requests permission from the user’s Console Wallet.
356
+ ```typescript
357
+ const checkBalance = async () => {
358
+ try {
359
+ const activeAccount = await consoleWalletPixelplex.getPrimaryAccount();
360
+ const activeNetwork = await consoleWalletPixelplex.getActiveNetwork();
361
+
362
+ if (!activeAccount || !activeNetwork) {
363
+ throw new Error('No active account or network found');
364
+ }
365
+
366
+ const balance = await consoleWalletPixelplex.getBalance({
367
+ party: activeAccount.partyId,
368
+ network: activeNetwork.id,
369
+ });
161
370
 
162
- ```js
163
- import { consoleWalletPixelplex } from 'console-wallet-dapp-templ';
371
+ console.log('СС utxos:', balance.tokens);
372
+ console.log('Is split balance:', balance.isSplitedBalance);
373
+ console.log('1 CC price:', balance.price);
374
+ // Access individual token balances
375
+ balance.tokens.forEach((token) => {
376
+ console.log(`${token.symbol}: ${token.balance} (USD: ${token.balanceUsd || 'N/A'})`);
377
+ });
378
+ } catch (error) {
379
+ console.error('Error getting balance:', error);
380
+ }
381
+ };
382
+ ```
164
383
 
165
- const handleConnect = async () => {
384
+ ### Get Coins Balance with Prices
385
+
386
+ Get detailed balance information with prices for CC and all CIP-56 tokens:
387
+
388
+ ```typescript
389
+ const getCoinsBalance = async () => {
166
390
  try {
167
- await consoleWalletPixelplex.connect({ name, icon });
391
+ const activeAccount = await consoleWalletPixelplex.getPrimaryAccount();
392
+ const activeNetwork = await consoleWalletPixelplex.getActiveNetwork();
393
+
394
+ if (!activeAccount || !activeNetwork) {
395
+ throw new Error('No active account or network found');
396
+ }
397
+
398
+ const coinsBalance = await consoleWalletPixelplex.getCoinsBalance({
399
+ party: activeAccount.partyId,
400
+ network: activeNetwork.id,
401
+ });
402
+
403
+ console.log('Tokens:', coinsBalance.tokens);
404
+ console.log('Prices:', coinsBalance.prices);
168
405
  } catch (error) {
169
- console.error('Error checking connection:', error);
406
+ console.error('Error getting coins balance:', error);
170
407
  }
171
408
  };
409
+ ```
410
+
411
+ ### Get Transaction History
412
+
413
+ Query transaction history with pagination:
172
414
 
173
- const handleCheckConnection = async () => {
415
+ ```typescript
416
+ const getTransactionHistory = async () => {
174
417
  try {
175
- const connected = await consoleWalletPixelplex.status();
176
- setConnectionStatus(connected);
418
+ const activeAccount = await consoleWalletPixelplex.getPrimaryAccount();
419
+
420
+ if (!activeAccount) {
421
+ throw new Error('No active account found');
422
+ }
423
+
424
+ // Get token transfers from indexer (only CC)
425
+ const transfers = await consoleWalletPixelplex.getTokenTransfers({
426
+ party: activeAccount.partyId,
427
+ limit: 10,
428
+ cursor: '0',
429
+ });
430
+
431
+ console.log('Transfers:', transfers.data);
432
+
433
+ // Get token transfers directly from node (separated by token) *Preferred
434
+ const cip56Transfers = await consoleWalletPixelplex.getNodeTransfers({
435
+ query: { partyId: partyId, limit: 10, coin: "CBTC", offset: 0 },
436
+ network,
437
+ });
438
+
439
+ console.log('Transfers', cip56Transfers?.items)
440
+
441
+ // Get offers from indexer (Only CC)
442
+ const offers = await consoleWalletPixelplex.getOffers({
443
+ party: activeAccount.partyId,
444
+ limit: 10,
445
+ cursor: '0',
446
+ });
447
+
448
+ console.log('Offers:', offers.data);
449
+
450
+ // Get offers from node (All tokens) *Preferred
451
+ const nodeOffers = await consoleWalletPixelplex.getNodeOffers({
452
+ query: { party_id: partyId, limit: 10, cursor: '0' },
453
+ network,
454
+ });
455
+
456
+ console.log('nodeOffers', nodeOffers?.items)
457
+
177
458
  } catch (error) {
178
- console.error('Error checking connection:', error);
459
+ console.error('Error getting transaction history:', error);
179
460
  }
180
461
  };
181
462
  ```
463
+
464
+ ---
465
+
466
+ ## 👀 Watch Requests (Subscriptions)
467
+
468
+ 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.
469
+
470
+ | Method | Description | Callback Payload |
471
+ | ------------------------------ | --------------------------------------------------------- | ------------------------ |
472
+ | `onAccountsChanged(onChange)` | Subscribes to active account changes | `GetAccountResponse` |
473
+ | `onConnectionStatusChanged(onChange)` | Subscribes to wallet connection status changes | `ConnectResponse` |
474
+ | `onTxStatusChanged(onChange)` | Subscribes to transaction status lifecycle updates | `TxChangedEvent` |
475
+
476
+ ### Example: Watch Account Changes
477
+
478
+ ```typescript
479
+ // Subscribe to account changes
480
+ consoleWalletPixelplex.onAccountsChanged((account) => {
481
+ if (account) {
482
+ console.log('Active account changed:', account.partyId);
483
+ // Update your UI with the new account
484
+ } else {
485
+ console.log('No active account');
486
+ }
487
+ });
488
+ ```
489
+
490
+ ### Example: Watch Connection Status
491
+
492
+ ```typescript
493
+ // Subscribe to connection status changes
494
+ consoleWalletPixelplex.onConnectionStatusChanged((status) => {
495
+ console.log('Connection status changed:', status);
496
+ if (status === 'connected') {
497
+ // User connected, enable features
498
+ } else {
499
+ // User disconnected, disable features
500
+ }
501
+ });
502
+ ```
503
+
504
+ ### Example: Watch Transaction Status
505
+
506
+ ```typescript
507
+ // Subscribe to transaction status updates
508
+ consoleWalletPixelplex.onTxStatusChanged((event) => {
509
+ console.log('Transaction status update:', event);
510
+ // Handle transaction lifecycle events (pending, confirmed, failed, etc.)
511
+ });
512
+ ```
513
+
514
+ ---
515
+
516
+ ## ⚠️ Error Handling
517
+
518
+ All request helpers return Promises and can reject with a `ConsoleWalletError` when something goes wrong.
519
+
520
+ - User-driven errors (rejection, invalid input, permission issues) are reported by the wallet and surfaced as rejected Promises with a `ConsoleWalletError` payload.
521
+ - 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).
522
+ - Some helpers, such as `checkAvailability()`, internally handle timeouts and resolve with a best-effort status instead of rejecting.
523
+
524
+ You should always wrap calls in `try`/`catch` and handle both expected and unexpected errors:
525
+
526
+ ```typescript
527
+ try {
528
+ const accounts = await consoleWalletPixelplex.getAccounts();
529
+ // happy path
530
+ } catch (error) {
531
+ // error is typically a ConsoleWalletError with message/code
532
+ }
533
+ ```
534
+
535
+ ---
536
+
537
+ ## 🔐 Transaction Metadata
538
+
539
+ ### Transaction Metadata
540
+
541
+ When submitting transactions, you can include optional metadata:
542
+
543
+ ```typescript
544
+ const transactionWithMetadata = await consoleWalletPixelplex.submitCommands({
545
+ from: activeAccount.partyId,
546
+ to: 'receiver::fingerprint',
547
+ token: 'CC',
548
+ amount: '10.0',
549
+ expireDate: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
550
+ memo: 'Payment for services', // Optional memo stored as transfer metadata
551
+ });
552
+ ```
553
+
554
+ 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.
555
+
556
+ ### Cost Estimation
557
+
558
+ All transactions on Canton are free. There are no transaction fees, traffic consumption costs, or native token costs for transaction processing.
559
+
560
+ ---
561
+
562
+ ## 🎯 Signing Any Transaction Type
563
+
564
+ The SDK supports signing various types of transactions:
565
+
566
+ ### 1. Standard Token Transfers
567
+
568
+ ```typescript
569
+ await consoleWalletPixelplex.submitCommands({
570
+ from: 'sender::fingerprint',
571
+ to: 'receiver::fingerprint',
572
+ token: 'CC',
573
+ amount: '10.0',
574
+ expireDate: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
575
+ });
576
+ ```
577
+
578
+ ### 2. Batch Transactions
579
+
580
+ ```typescript
581
+ await consoleWalletPixelplex.signBatch({
582
+ batchType: 'SEND',
583
+ requests: [
584
+ // Multiple transfer requests
585
+ ],
586
+ });
587
+ ```
588
+
589
+ ### 3. Arbitrary Message Signing
590
+
591
+ Sign any message for authentication or verification purposes:
592
+
593
+ ```typescript
594
+ await consoleWalletPixelplex.signMessage({
595
+ message: { hex: '0x...' }, // or { base64: '...' }
596
+ metaData: {
597
+ purpose: 'authentication',
598
+ // Any additional metadata
599
+ },
600
+ });
601
+ ```
602
+
603
+ ---
604
+
605
+ ## 📚 API Reference
606
+
607
+ For detailed API reference, see the TypeScript type definitions in `src/types/`. All methods are fully typed and include JSDoc comments.
608
+
609
+ ### Type Exports
610
+
611
+ The SDK exports all relevant types:
612
+
613
+ ```typescript
614
+ import type {
615
+ ConnectRequest,
616
+ ConnectResponse,
617
+ GetAccountResponse,
618
+ SignMessageRequest,
619
+ SignedMessageResponse,
620
+ SignSendRequest,
621
+ SignSendResponse,
622
+ SignBatchRequest,
623
+ SignBatchResponse,
624
+ GetBalanceRequest,
625
+ GetBalanceResponse,
626
+ // ... and more
627
+ } from '@console-wallet/dapp-sdk';
628
+ ```
629
+
630
+ ### Utility Functions
631
+
632
+ The SDK provides utility functions for correct data format conversion required for working with the network and extension:
633
+
634
+ ```typescript
635
+ import { utils } from '@console-wallet/dapp-sdk';
636
+
637
+ // Parsers for format conversion
638
+ utils.toHex(u8: Uint8Array): string
639
+ utils.toBase64(u8: Uint8Array): string
640
+ utils.hexToBytes(hex: string): Uint8Array
641
+ utils.hexToBase64(hex: string): string
642
+ utils.base64ToBytes(base64: string): Uint8Array
643
+ utils.base64toHex(base64: string): string
644
+
645
+ // Checks
646
+ utils.equalBytes(a: Uint8Array, b: Uint8Array): boolean
647
+ ```
648
+
649
+ These utilities are essential for converting data between different formats (hex, base64, bytes) that the network and extension expect.
650
+
651
+ ---
652
+
653
+ ## 📝 Changelog
654
+
655
+ See [CHANGELOG.md](./CHANGELOG.md) for a list of changes and version history.
@@ -15,6 +15,7 @@ export declare const consoleWalletPixelplex: {
15
15
  isConnected: () => Promise<boolean>;
16
16
  status: () => Promise<import("./types").ConnectStatus>;
17
17
  getActiveNetwork: () => Promise<import("./types").Network>;
18
+ checkExtensionAvailability: () => Promise<import("./types").AvailabilityStatus>;
18
19
  getBalance: (data: import("./types").GetBalanceRequest) => Promise<import("./types").GetBalanceResponse>;
19
20
  getCoinsBalance: (data: import("./types").GetBalanceRequest) => Promise<import("./types").GetCoinsResponse>;
20
21
  getOffers: (data: import("./types").OffersRequest) => Promise<import("./types").OffersResponse>;