Skip to content

Commit fc70097

Browse files
drichardrichar
authored
feat(wallets): add WalletConnect skins for branded wallets (#412)
* feat(wallets): add WalletConnect skins for branded wallet instances Enable multiple WalletConnect-based wallets to coexist with distinct branding using a composite key architecture. Wallets can now specify a `skin` option that provides custom name/icon metadata and derives a unique `walletKey` (e.g., `walletconnect:biatec`), allowing separate state isolation. Core changes: - Add WalletConnectSkin type and skin registry with built-in Biatec skin - Add `walletKey` property to BaseWallet for state isolation - Update store to use `walletKey` instead of `id` for wallet state keys - Update WalletManager to derive composite keys and prevent duplicates - Deprecate WalletId.BIATEC in favor of WalletConnect with `skin: 'biatec'` Framework adapter updates: - use-wallet-react: Add walletKey to Wallet interface, use for state lookups - use-wallet-vue: Add walletKey to Wallet interface, use for state lookups - use-wallet-solid: Update state lookups to use walletKey - use-wallet-svelte: Add walletKey to Wallet interface, use for state lookups * docs: document WalletConnect skins and deprecate WalletId.BIATEC Add documentation for the WalletConnect skins feature including: - `skin` option in WalletConnect configuration - Built-in skin usage example - Custom skin definition at runtime - Multiple WalletConnect instances with isolated sessions - Accessing wallets by composite key (e.g., 'walletconnect:biatec') Add deprecation notice for `WalletId.BIATEC` with migration guidance. * refactor(examples): use WalletConnect skin instead of WalletId.BIATEC Replace deprecated `WalletId.BIATEC` with WalletConnect using `skin: 'biatec'` option across all example projects. - nextjs - nuxt - react-ts - solid-ts - svelte-ts - vanilla-ts - vue-ts * style: fix Prettier formatting in skins module and tests
1 parent 88dedbd commit fc70097

File tree

25 files changed

+931
-88
lines changed

25 files changed

+931
-88
lines changed

‎docs/getting-started/configuration.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -91,10 +91,13 @@ const manager = new WalletManager({
9191
apiKey: '<MAGIC_API_KEY>' // Required
9292
}
9393
},
94+
95+
// WalletConnect with skin (for branded wallet appearance)
9496
{
95-
id: WalletId.BIATEC,
97+
id: WalletId.WALLETCONNECT,
9698
options: {
97-
projectId: '<REOWN_PROJECT_ID>' // Required
99+
projectId: '<REOWN_PROJECT_ID>', // Required
100+
skin: 'biatec' // Built-in skin for Biatec Wallet
98101
}
99102
}
100103
]

‎docs/getting-started/supported-wallets.md‎

Lines changed: 83 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -100,10 +100,75 @@ import { WalletId } from '@txnlab/use-wallet'
100100
url?: string
101101
icons?: string[]
102102
}
103+
skin?: string | WalletConnectSkin // Optional: Skin for branded wallet appearance
103104
}
104105
}
105106
```
106107

108+
##### WalletConnect Skins
109+
110+
WalletConnect supports "skins" to customize the wallet's appearance for different wallet providers. This allows multiple WalletConnect-based wallets to coexist in the same app with distinct branding.
111+
112+
**Using a built-in skin:**
113+
114+
```typescript
115+
// Use the built-in 'biatec' skin
116+
{
117+
id: WalletId.WALLETCONNECT,
118+
options: {
119+
skin: 'biatec',
120+
projectId: '<YOUR_PROJECT_ID>',
121+
}
122+
}
123+
```
124+
125+
**Using a custom skin at runtime:**
126+
127+
```typescript
128+
// Define a custom skin
129+
{
130+
id: WalletId.WALLETCONNECT,
131+
options: {
132+
skin: {
133+
id: 'mywallet',
134+
name: 'My Wallet',
135+
icon: 'data:image/svg+xml;base64,...'
136+
},
137+
projectId: '<YOUR_PROJECT_ID>',
138+
}
139+
}
140+
```
141+
142+
**Multiple WalletConnect instances:**
143+
144+
```typescript
145+
const manager = new WalletManager({
146+
wallets: [
147+
// Generic WalletConnect (no skin)
148+
{ id: WalletId.WALLETCONNECT, options: { projectId: '...' } },
149+
150+
// Biatec-branded WalletConnect
151+
{ id: WalletId.WALLETCONNECT, options: { skin: 'biatec', projectId: '...' } },
152+
153+
// Custom wallet skin
154+
{
155+
id: WalletId.WALLETCONNECT,
156+
options: {
157+
skin: { id: 'customwallet', name: 'Custom Wallet', icon: '...' },
158+
projectId: '...'
159+
}
160+
}
161+
]
162+
})
163+
164+
// Access wallets by their unique key
165+
const genericWC = manager.getWallet('walletconnect')
166+
const biatec = manager.getWallet('walletconnect:biatec')
167+
const custom = manager.getWallet('walletconnect:customwallet')
168+
```
169+
170+
Each skinned WalletConnect instance maintains isolated session storage, allowing users to connect to multiple WalletConnect-based wallets simultaneously.
171+
107172
* [WalletConnect Network](https://walletconnect.network)
108173
* [Sign API Documentation](https://docs.reown.com/api/sign/dapp-usage)
109174
* [Reown Cloud Dashboard](https://cloud.reown.com/)
@@ -240,12 +305,26 @@ For implementation details, refer to the [Web3Auth Single Factor Auth documentat
240305

241306
#### Biatec
242307

308+
{% hint style="warning" %}
309+
**Deprecation Notice:** `WalletId.BIATEC` is deprecated and will be removed in v5. Use WalletConnect with the `'biatec'` skin instead:
310+
311+
```typescript
312+
{
313+
id: WalletId.WALLETCONNECT,
314+
options: {
315+
skin: 'biatec',
316+
projectId: '<REOWN_PROJECT_ID>',
317+
}
318+
}
319+
```
320+
{% endhint %}
321+
243322
Open-source mobile wallet with community focus and WalletConnect support. [Installation instructions](installation.md#walletconnect).
244323

245324
```typescript
246325
import { WalletId } from '@txnlab/use-wallet'
247326

248-
// Basic usage (no options required)
327+
// Deprecated - use WalletConnect with skin: 'biatec' instead
249328
WalletId.BIATEC
250329
```
251330

@@ -270,9 +349,9 @@ import { WalletId } from '@txnlab/use-wallet'
270349
{
271350
id: WalletId.LIQUID,
272351
options: {
273-
origin?: string,
274-
RTC_config_username: string,
275-
RTC_config_credential: string
352+
origin?: string,
353+
RTC_config_username: string,
354+
RTC_config_credential: string
276355
}
277356
}
278357
```

‎examples/nextjs/src/app/providers.tsx‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,11 @@ const wallets: SupportedWallet[] = [
1818
options: { projectId: 'fcfde0713d43baa0d23be0773c80a72b' }
1919
},
2020
{
21-
id: WalletId.BIATEC,
22-
options: { projectId: 'fcfde0713d43baa0d23be0773c80a72b' }
21+
id: WalletId.WALLETCONNECT,
22+
options: {
23+
skin: 'biatec',
24+
projectId: 'fcfde0713d43baa0d23be0773c80a72b'
25+
}
2326
},
2427
WalletId.KMD,
2528
WalletId.KIBISIS,

‎examples/nuxt/plugins/walletManager.client.ts‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,11 @@ export default defineNuxtPlugin((nuxtApp) => {
1717
options: { projectId: 'fcfde0713d43baa0d23be0773c80a72b' }
1818
},
1919
{
20-
id: WalletId.BIATEC,
21-
options: { projectId: 'fcfde0713d43baa0d23be0773c80a72b' }
20+
id: WalletId.WALLETCONNECT,
21+
options: {
22+
skin: 'biatec',
23+
projectId: 'fcfde0713d43baa0d23be0773c80a72b'
24+
}
2225
},
2326
WalletId.KMD,
2427
WalletId.KIBISIS,

‎examples/react-ts/src/App.tsx‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,11 @@ const wallets: SupportedWallet[] = [
2121
options: { projectId: 'fcfde0713d43baa0d23be0773c80a72b' }
2222
},
2323
{
24-
id: WalletId.BIATEC,
25-
options: { projectId: 'fcfde0713d43baa0d23be0773c80a72b' }
24+
id: WalletId.WALLETCONNECT,
25+
options: {
26+
skin: 'biatec',
27+
projectId: 'fcfde0713d43baa0d23be0773c80a72b'
28+
}
2629
},
2730
WalletId.KMD,
2831
WalletId.KIBISIS,

‎examples/solid-ts/src/App.tsx‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,11 @@ const wallets: SupportedWallet[] = [
2121
options: { projectId: 'fcfde0713d43baa0d23be0773c80a72b' }
2222
},
2323
{
24-
id: WalletId.BIATEC,
25-
options: { projectId: 'fcfde0713d43baa0d23be0773c80a72b' }
24+
id: WalletId.WALLETCONNECT,
25+
options: {
26+
skin: 'biatec',
27+
projectId: 'fcfde0713d43baa0d23be0773c80a72b'
28+
}
2629
},
2730
WalletId.KMD,
2831
WalletId.KIBISIS,

‎examples/svelte-ts/src/routes/+layout.svelte‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,11 @@
1818
options: { projectId: 'fcfde0713d43baa0d23be0773c80a72b' }
1919
},
2020
{
21-
id: WalletId.BIATEC,
22-
options: { projectId: 'fcfde0713d43baa0d23be0773c80a72b' }
21+
id: WalletId.WALLETCONNECT,
22+
options: {
23+
skin: 'biatec',
24+
projectId: 'fcfde0713d43baa0d23be0773c80a72b'
25+
}
2326
},
2427
WalletId.KMD,
2528
WalletId.KIBISIS,

‎examples/vanilla-ts/src/main.ts‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,11 @@ const wallets: SupportedWallet[] = [
1515
options: { projectId: 'fcfde0713d43baa0d23be0773c80a72b' }
1616
},
1717
{
18-
id: WalletId.BIATEC,
19-
options: { projectId: 'fcfde0713d43baa0d23be0773c80a72b' }
18+
id: WalletId.WALLETCONNECT,
19+
options: {
20+
skin: 'biatec',
21+
projectId: 'fcfde0713d43baa0d23be0773c80a72b'
22+
}
2023
},
2124
WalletId.KMD,
2225
WalletId.KIBISIS,

‎examples/vue-ts/src/main.ts‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,11 @@ const wallets: SupportedWallet[] = [
2020
options: { projectId: 'fcfde0713d43baa0d23be0773c80a72b' }
2121
},
2222
{
23-
id: WalletId.BIATEC,
24-
options: { projectId: 'fcfde0713d43baa0d23be0773c80a72b' }
23+
id: WalletId.WALLETCONNECT,
24+
options: {
25+
skin: 'biatec',
26+
projectId: 'fcfde0713d43baa0d23be0773c80a72b'
27+
}
2528
},
2629
WalletId.KMD,
2730
WalletId.KIBISIS,

‎packages/use-wallet-react/src/__tests__/index.test.tsx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -431,6 +431,7 @@ describe('useWallet', () => {
431431
mockWallets = [
432432
{
433433
id: mockDeflyWallet.id,
434+
walletKey: mockDeflyWallet.walletKey,
434435
metadata: mockDeflyWallet.metadata,
435436
accounts: [],
436437
activeAccount: null,
@@ -444,6 +445,7 @@ describe('useWallet', () => {
444445
},
445446
{
446447
id: mockMagicAuth.id,
448+
walletKey: mockMagicAuth.walletKey,
447449
metadata: mockMagicAuth.metadata,
448450
accounts: [],
449451
activeAccount: null,

0 commit comments

Comments
 (0)