Skip to content

Commit 25a82ad

Browse files
committed
docs: add manual derivation type selection UX guidelines
- Add alternative implementation for explicit user selection during onboarding - Include code example for manual derivation type selection UI - Document benefits and use cases for manual vs automatic selection - Address scenarios where users have used multiple derivation types - Provide clear guidance for multi-wallet applications
1 parent 519460c commit 25a82ad

File tree

1 file changed

+39
-5
lines changed

1 file changed

+39
-5
lines changed

packages/hardware-trezor/MASTER_KEY_GENERATION.md

Lines changed: 39 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,8 @@ const keyAgent = await TrezorKeyAgent.createWithDevice({
9494

9595
## Discovery & UX Guidelines
9696

97+
### Automatic Discovery Pattern
98+
9799
When pairing a Trezor device, follow this discovery pattern to find existing accounts:
98100

99101
1. **Try ICARUS first** - Most common for software wallets
@@ -102,6 +104,43 @@ When pairing a Trezor device, follow this discovery pattern to find existing acc
102104

103105
This is why many wallet UIs show a "Derivation type override" dropdown - to help users discover their existing accounts.
104106

107+
### Manual Selection During Onboarding
108+
109+
For applications that prefer explicit user control, consider exposing derivation type selection during the onboarding process:
110+
111+
```typescript
112+
// Example onboarding flow
113+
const derivationTypeOptions = [
114+
{ value: 'ICARUS', label: 'Software Wallet', description: 'Most common for wallets created with software applications' },
115+
{ value: 'ICARUS_TREZOR', label: 'Trezor Default', description: 'Trezor\'s internal default (24-word mnemonic compatible)' },
116+
{ value: 'LEDGER', label: 'Ledger Hardware Wallet', description: 'For wallets originally created on Ledger devices' }
117+
];
118+
119+
// Let user select during onboarding
120+
const selectedDerivationType = await showDerivationTypeSelection(derivationTypeOptions);
121+
122+
const keyAgent = await TrezorKeyAgent.createWithDevice({
123+
chainId: Cardano.ChainIds.Mainnet,
124+
trezorConfig: {
125+
communicationType: 'web',
126+
manifest: { email: '[email protected]', appUrl: 'https://myapp.com' },
127+
derivationType: selectedDerivationType
128+
}
129+
}, dependencies);
130+
```
131+
132+
**Benefits of Manual Selection:**
133+
- **User Control**: Users explicitly choose their derivation type
134+
- **Multi-Wallet Support**: Users can create multiple wallets with different derivation types
135+
- **Transparency**: Clear understanding of which derivation type is being used
136+
- **No Guessing**: Eliminates the need for automatic discovery patterns
137+
138+
**When to Use Manual Selection:**
139+
- Applications that prioritize user control and transparency
140+
- Multi-wallet applications where users might have accounts with different derivation types
141+
- Enterprise applications where explicit configuration is preferred
142+
- When users have used multiple wallet types and need to access different accounts
143+
105144
## Implementation Details
106145

107146
When a non-default derivation type is specified, the SDK sets the appropriate `derivationType` in the `cardanoSignTransaction` call. For the default type, no `derivationType` is sent to Trezor.
@@ -119,8 +158,3 @@ Existing wallets without a `derivationType` configuration will continue to work
119158
- **[Trezor Forum](https://forum.trezor.io/t/cardano-ada-transaction-signing-error/10466)**: Community discussion on derivation types
120159
- **[Cardano Stack Exchange](https://cardano.stackexchange.com/questions/5977/how-does-ledger-generate-the-public-keys)**: Ledger key generation details
121160
- **[Cardano Foundation](https://cardano-foundation.github.io/cardano-wallet/concepts/master-key-generation)**: Master key generation background
122-
123-
## Notes
124-
125-
- **Device Compatibility**: Ensure your Trezor device firmware supports the chosen derivation type
126-
- **Discovery**: Use the discovery pattern (ICARUS → ICARUS_TREZOR → LEDGER) to find existing accounts

0 commit comments

Comments
 (0)