Skip to content

Commit f1d308a

Browse files
B0Y3R-AVAB0Y3R-AVA
authored
Boyer/ledger discovery (#3143)
1 parent 892a34f commit f1d308a

32 files changed

+4685
-191
lines changed

‎docs/ledger-flows/README.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Ledger Integration Documentation
2+
3+
This directory contains documentation for the current Ledger device integration in Core Mobile.
4+
5+
## Contents
6+
7+
1. [Ledger Connection Flow](./ledger-connection.md)
8+
- Device discovery and connection
9+
- Account setup process
10+
- Error handling
11+
12+
2. [Transaction Signing Flow](./transaction-signing.md)
13+
- Transaction signing overview
14+
- Chain-specific implementations
15+
- Error handling
16+
17+
## Key Components
18+
19+
### Services
20+
- `LedgerService`: Manages device connection and app detection
21+
- `LedgerWallet`: Implements wallet interface for Ledger devices
22+
- `WalletService`: Coordinates transaction signing across wallet types
23+
24+
### Hooks
25+
- `useLedgerWallet`: React hook for Ledger device management
26+
27+
### UI Components
28+
- `ConnectWallet`: Device discovery and connection UI
29+
- `ConfirmAddresses`: Account setup and verification UI
30+
31+
## Dependencies
32+
33+
- `@ledgerhq/react-native-hw-transport-ble`: Bluetooth transport
34+
- `@ledgerhq/hw-app-solana`: Solana app integration
35+
- `@avalabs/hw-app-avalanche`: Avalanche app integration
36+
- `@ledgerhq/hw-app-eth`: Ethereum app integration
37+
38+
## Implementation Notes
39+
40+
1. **Bluetooth Connectivity**
41+
- Uses BLE for device communication
42+
- Implements connection monitoring
43+
- Handles connection recovery
44+
45+
2. **Multi-Chain Support**
46+
- Supports EVM, Solana, and Avalanche chains
47+
- Handles app switching
48+
- Manages different transaction formats
49+
50+
3. **Security Considerations**
51+
- Implements secure device pairing
52+
- Validates addresses and transactions
53+
- Handles sensitive data appropriately
54+
55+
4. **Error Handling**
56+
- Comprehensive error types
57+
- User-friendly error messages
58+
- Recovery procedures
59+
60+
## Recent Updates
61+
62+
- Successfully implemented legacy transaction format for EVM chains
63+
- Added proper RLP encoding for transactions
64+
- Implemented correct signature handling
65+
- Added connection monitoring and recovery

‎docs/ledger-flows/ledger-connection.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# Ledger Connection Flow
2+
3+
This document describes the current implementation of Ledger device connection and account setup in Core Mobile.
4+
5+
## Device Discovery and Connection
6+
7+
### Flow Diagram
8+
9+
```mermaid
10+
sequenceDiagram
11+
box User Interface
12+
participant User
13+
end
14+
box Core Mobile
15+
participant App
16+
end
17+
box External Devices
18+
participant BLE
19+
participant Ledger
20+
end
21+
22+
User->>App: Initiate Add Ledger
23+
App->>BLE: Check Bluetooth Status
24+
25+
alt Bluetooth Disabled
26+
BLE-->>App: Status: Disabled
27+
App-->>User: Show Enable Bluetooth Prompt
28+
User->>BLE: Enable Bluetooth
29+
end
30+
31+
App->>BLE: Request Permissions
32+
33+
alt Permissions Denied
34+
BLE-->>App: Permission Denied
35+
App-->>User: Show Permission Request
36+
User->>BLE: Grant Permissions
37+
end
38+
39+
App->>BLE: Start Device Scan
40+
BLE->>Ledger: Discover Devices
41+
Ledger-->>BLE: Device Info
42+
BLE-->>App: Available Devices
43+
App-->>User: Display Device List
44+
45+
Note over User,App: User selects device from list
46+
47+
User->>App: Select Device
48+
App->>Ledger: Initiate Connection
49+
Ledger-->>App: Connection Established
50+
App-->>User: Show Success & Continue
51+
```
52+
53+
## Account Setup Flow
54+
55+
### Flow Diagram
56+
57+
```mermaid
58+
sequenceDiagram
59+
box User Interface
60+
participant User
61+
end
62+
box Core Mobile
63+
participant App
64+
participant Store
65+
end
66+
box External Device
67+
participant Ledger
68+
end
69+
70+
User->>App: Continue to Address Setup
71+
72+
Note over App,Ledger: Solana Setup Phase
73+
App->>Ledger: Request Solana App
74+
Ledger-->>User: Prompt: Open Solana App
75+
User->>Ledger: Open Solana App
76+
App->>Ledger: Get Solana Keys
77+
Ledger-->>App: Solana Public Keys
78+
79+
Note over App,Ledger: Avalanche Setup Phase
80+
App->>Ledger: Request Avalanche App
81+
Ledger-->>User: Prompt: Open Avalanche App
82+
User->>Ledger: Open Avalanche App
83+
App->>Ledger: Get Avalanche Keys
84+
Ledger-->>App: Avalanche Public Keys
85+
86+
Note over App,Store: Storage Phase
87+
App->>Store: Create Wallet Entry
88+
Store-->>App: Wallet Created
89+
App->>Store: Create Account Entry
90+
Store-->>App: Account Created
91+
92+
App-->>User: Show Success
93+
```
94+
95+
## Error Handling
96+
97+
### Flow Diagram
98+
99+
```mermaid
100+
stateDiagram-v2
101+
direction LR
102+
103+
[*] --> CheckBluetooth
104+
105+
state "Bluetooth Check" as CheckBluetooth {
106+
[*] --> Checking
107+
Checking --> Available
108+
Checking --> Disabled
109+
Disabled --> Settings
110+
Settings --> Checking
111+
}
112+
113+
state "Permission Check" as PermissionCheck {
114+
[*] --> Requesting
115+
Requesting --> Granted
116+
Requesting --> Denied
117+
Denied --> RequestAgain
118+
RequestAgain --> Requesting
119+
}
120+
121+
state "Device Connection" as DeviceConnection {
122+
[*] --> Scanning
123+
Scanning --> Found
124+
Scanning --> NotFound
125+
Found --> Connecting
126+
Connecting --> Connected
127+
Connecting --> Failed
128+
}
129+
130+
CheckBluetooth --> PermissionCheck: Available
131+
PermissionCheck --> DeviceConnection: Granted
132+
DeviceConnection --> [*]: Connected
133+
134+
state "Error Recovery" as ErrorRecovery {
135+
[*] --> IdentifyError
136+
IdentifyError --> ShowMessage
137+
ShowMessage --> RecoverySteps
138+
RecoverySteps --> [*]
139+
}
140+
141+
Disabled --> ErrorRecovery
142+
Denied --> ErrorRecovery
143+
Failed --> ErrorRecovery
144+
NotFound --> ErrorRecovery
145+
146+
ErrorRecovery --> CheckBluetooth: Retry
147+
```
148+
149+
### Error Types and Handling
150+
151+
1. **Bluetooth Errors**
152+
- Bluetooth unavailable
153+
- Bluetooth disabled
154+
- Permission denied
155+
156+
2. **Connection Errors**
157+
- Device not found
158+
- Connection timeout
159+
- Pairing removed
160+
- Connection lost
161+
162+
3. **App Errors**
163+
- App not open
164+
- Wrong app open
165+
- App version mismatch
166+
167+
Each error type has specific handling and user messaging to guide through recovery steps.

0 commit comments

Comments
 (0)