151 lines
6.3 KiB
Markdown
151 lines
6.3 KiB
Markdown
<!-- file: crates/ksp-app-wallet-desk/README.md -->
|
|
<!-- version: 4 -->
|
|
|
|
# `ksp-app-wallet-desk`
|
|
|
|
`ksp-app-wallet-desk` est l'application desktop spécialisée stable d'administration et de validation des wallets KSP.
|
|
|
|
La crate est un package Tauri mixte :
|
|
|
|
```text
|
|
package : ksp-app-wallet-desk
|
|
lib : ksp_app_wallet_desk_lib
|
|
bin : ksp-app-wallet-desk
|
|
```
|
|
|
|
## Responsabilités
|
|
|
|
Wallet Desk reste une couche d'interface et de composition. Il ne possède ni le wire `.kspwallet`, ni la cryptographie Wallet, ni la résolution Config, ni le transport Solana :
|
|
|
|
```text
|
|
ksp-config-lib -> configuration/composite/.env
|
|
ksp-wallet-lib -> format, crypto, VIEW/OWNER, import/export, migration
|
|
ksp-onchain-transport-lib -> RPC Solana HTTP
|
|
ksp-offchain-transport-lib -> prix SOL/USD provider-neutral
|
|
ksp-logging-lib -> logging/tracing applicatif
|
|
ksp-app-wallet-desk -> orchestration Tauri + projections sûres
|
|
```
|
|
|
|
Le frontend ne reçoit jamais les keypairs, ciphertexts, passwords Config, paths complets import/export ou handles VIEW/OWNER. Les opérations privilégiées sont exécutées côté Rust.
|
|
|
|
## `.kspwallet` V1/V2
|
|
|
|
La surface courante conserve V1 et utilise V2 comme format natif par défaut :
|
|
|
|
```text
|
|
V1 : JSON UTF-8 historique, lecture explicite toujours supportée
|
|
V2 : wire binaire KSP, format de création/import par défaut
|
|
```
|
|
|
|
Wallet Desk consomme uniquement les APIs non versionnées de `ksp-wallet-lib` :
|
|
|
|
- création/import -> format par défaut `V2` ;
|
|
- inventory/inspection/open -> détection V1/V2 ;
|
|
- mutations OWNER/VIEW -> restent dans le format natif ouvert ;
|
|
- ouverture d'un V1 -> aucune migration implicite.
|
|
|
|
`ksp-wallet-lib` conserve parallèlement les APIs explicites `_v1` / `_v2` pour les consumers qui doivent imposer un format. `DEFAULT_WALLET_FORMAT` et `LATEST_SUPPORTED_WALLET_FORMAT` sont des politiques distinctes ; l'apparition future d'un V3 n'impose donc pas de modifier automatiquement le format créé par les APIs génériques.
|
|
|
|
La migration V1 -> V2 est une opération explicite OWNER-authentifiée possédée par `ksp-wallet-lib`. Wallet Desk ne migre jamais silencieusement un wallet lors de sa sélection, inspection ou ouverture.
|
|
|
|
## Capacités fonctionnelles
|
|
|
|
La surface validée comprend :
|
|
|
|
- inventory root-scoped des `.kspwallet` ;
|
|
- create/import Solana CLI JSON et Base58 ;
|
|
- sélection et inspection locked ;
|
|
- ouverture VIEW et OWNER, manuelle ou via candidats secrets Config ;
|
|
- affichage Pubkey/alias/notes uniquement après autorisation ;
|
|
- `getBalance` via le Transport HTTP KSP ;
|
|
- mutation alias/notes OWNER ;
|
|
- rotations OWNER et VIEW ;
|
|
- self-rotation VIEW ;
|
|
- disable/recreate VIEW fort par OWNER ;
|
|
- export OWNER Solana CLI JSON/Base58 no-clobber ;
|
|
- wire V2 par défaut tout en conservant la compatibilité V1.
|
|
|
|
## Prix SOL/USD auxiliaire
|
|
|
|
Le refresh de balance compose deux capacités backend : `getBalance` et `MarketPriceService::refresh_all`. Les observations réussies du refresh courant sont moyennées côté Rust sans `f64`; la balance SOL reste autoritative et le prix reste auxiliaire.
|
|
|
|
Le frontend reçoit uniquement :
|
|
|
|
```text
|
|
SOL/USD moyen
|
|
Équivalent USD de la balance
|
|
```
|
|
|
|
ou `N.A.` lorsque le prix n'est pas disponible. Cette moyenne est une projection locale à Wallet Desk : elle ne devient ni un consensus, ni un fallback, ni un prix canonique de `ksp-offchain-transport-lib`. Aucun provider ID ou détail provider n'est exposé au frontend Wallet.
|
|
|
|
## Frontières desktop
|
|
|
|
Le frontend utilise Bootstrap, Font Awesome, DataTables/Select, SimpleBar et le bridge Logging KSP. Les capabilities Tauri du guest restent minimales :
|
|
|
|
```text
|
|
core:default
|
|
tracing:default
|
|
```
|
|
|
|
Les pickers import/export sont invoqués côté Rust. Aucun accès direct filesystem ou réseau Solana n'est accordé au frontend.
|
|
|
|
## Développement
|
|
|
|
Le workspace contient plusieurs applications Tauri. `-c/--config` n'est pas un sélecteur de crate ; le cycle doit être lancé depuis le répertoire applicatif :
|
|
|
|
```bash
|
|
(cd crates/ksp-app-wallet-desk && cargo tauri dev)
|
|
```
|
|
|
|
En développement, le launcher Rust normalise ensuite son current working directory vers la racine du workspace avant le bootstrap Config. Les chemins relatifs `config/`, `config/schemas/`, `.env`, `logs/` et `wallets/` restent ainsi cohérents avec le checkout de développement sans déplacer leur ownership hors de `ksp-config-lib`.
|
|
|
|
Les ports réservés sont :
|
|
|
|
```text
|
|
Vite HTTP : 1432
|
|
Vite WS : 1433
|
|
```
|
|
|
|
## Runtime packagé
|
|
|
|
Une application distribuée ne dépend pas du checkout source ni du répertoire depuis lequel l'utilisateur lance le binaire.
|
|
|
|
Les documents Config et schemas enregistrés sont embarqués comme resources Tauri. Au démarrage release :
|
|
|
|
1. Tauri résout son répertoire de resources ;
|
|
2. `ksp-config-lib` résout un répertoire de données utilisateur KSP writable via `ProjectDirs` ;
|
|
3. les documents Config packagés sont copiés uniquement lorsqu'ils sont absents ;
|
|
4. les schemas, possédés par le package courant, sont resynchronisés à chaque lancement ;
|
|
5. le process adopte ce répertoire KSP writable comme current working directory avant `AppState::initialize`.
|
|
|
|
Le `.env` n'est jamais embarqué ni prérempli. Les Config déjà modifiées par l'utilisateur ne sont jamais écrasées silencieusement. Les chemins relatifs de logs et wallets restent ancrés dans ce runtime writable, sauf override explicite par Config.
|
|
|
|
## Validation
|
|
|
|
Les validations Rust courantes sont :
|
|
|
|
```bash
|
|
cargo fmt --all
|
|
python3 scripts/audit_rust_workspace_rules.py
|
|
cargo check --workspace
|
|
cargo clippy --workspace --all-targets
|
|
cargo test -p ksp-app-wallet-desk
|
|
cargo test --workspace
|
|
```
|
|
|
|
Le parcours fonctionnel utilise exclusivement Tauri :
|
|
|
|
```bash
|
|
(cd crates/ksp-app-wallet-desk && cargo tauri dev)
|
|
```
|
|
|
|
Le build production de la release est exécuté seulement après tous les autres gates :
|
|
|
|
```bash
|
|
(cd crates/ksp-app-wallet-desk && cargo tauri build)
|
|
```
|
|
|
|
Cette commande reste l'absolue dernière opération de validation lorsqu'une publication Wallet Desk est candidate au tag stable.
|
|
|
|
Voir également [`USAGE.md`](USAGE.md), [`../../docs/formats/KSPWALLET_V1.md`](../../docs/formats/KSPWALLET_V1.md), [`../../docs/formats/KSPWALLET_V2.md`](../../docs/formats/KSPWALLET_V2.md) et [`../../docs/validation/009-V0_2_6_WALLET_DESK_COMPLIANCE.md`](../../docs/validation/009-V0_2_6_WALLET_DESK_COMPLIANCE.md).
|