Sasedev/khadhroony-bot3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.5.2-pre.005

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-10 19:12:13 +02:00
parent b8e6751747
commit e3acb8ceb1
13 changed files with 1276 additions and 90 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/README.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/README.md -->
<!-- version: 34 -->
<!-- version: 35 -->
# Documentation active de Khadhroony Bot3
@@ -53,6 +53,7 @@ Les audits et rapports de travail `0.4.8-pre.*` sont archivés sous `../olddocs/
- [`MISSING_PROGRAM_IDLS.md`](MISSING_PROGRAM_IDLS.md) ;
- [`OPERATION_NAMING_CONVENTION.md`](OPERATION_NAMING_CONVENTION.md) ;
- [`NATIVE_FORMAT.md`](NATIVE_FORMAT.md) : format binaire natif versionné de `ks-wallet` ;
- [`WALLET_FORMAT_COMPATIBILITY.md`](WALLET_FORMAT_COMPATIBILITY.md) : matrice des formats d’import/export wallet Solana et décisions d’adaptation ;
- [`IDEA_REMINDERS.md`](IDEA_REMINDERS.md).
Les idées ne rejoignent un `TODO.md` qu’après confirmation, attribution et reformulation en tâche vérifiable.

106
docs/WALLET_FORMAT_COMPATIBILITY.md Normal file
View File

@@ -0,0 +1,106 @@
<!-- file: docs/WALLET_FORMAT_COMPATIBILITY.md -->
<!-- version: 1 -->
# Compatibilité import/export des wallets Solana
## 1. Statut
Cette matrice est établie pour `khadhroony-bot3 0.5.2-pre.005` et borne les adaptateurs secrets de `ks-wallet`.
Elle ne prétend pas inventorier tous les wallets existants. Elle couvre les formats obligatoires du projet et les cibles explicitement retenues par le plan `0.5.2` : Solana CLI, Phantom, Solflare, Backpack, Trust Wallet et Base / Coinbase Wallet. Coinbase Developer Platform est distingué de Base app car son API de custody/import n'est pas le contrat utilisateur de Base app.
Règles transversales :
- tout export contenant le secret exige d'abord le mot de passe valide du `.kswallet` ;
- aucun adaptateur ne synthétise une recovery phrase à partir d'une keypair arbitraire ;
- un format n'est implémenté que si sa représentation est suffisamment précise pour permettre un round-trip et une validation de pubkey ;
- les exports secrets sont écrits dans un fichier privé, atomiquement et sans écrasement silencieux ;
- les sources d'import sont lues comme fichiers secrets privés et ne sont jamais loguées.
Sources vérifiées le **2026-08-10**.
## 2. Formats implémentés dans `0.5.2-pre.005`
| Format `ks-wallet` | Représentation | Import | Export | Cible de référence |
|--------------------------|-----------------------------------------------|:------:|:------:|---------------------------------------------|
| `SolanaCliJson` | tableau JSON contenant exactement 64 octets | oui | oui | Solana CLI / `solana-keygen` |
| `SolanaPrivateKeyBase58` | Base58 du keypair Solana complet de 64 octets | oui | oui | Phantom ; compatibilité Solflare documentée |
`SolanaPrivateKeyBase58` est volontairement un nom de format générique et non `PhantomPrivateKey` : le wire représente la keypair Solana, pas un conteneur propriétaire Phantom. Phantom sert de cible de référence parce que la documentation Solana identifie explicitement la private key copiée depuis Phantom comme **Base58**, et Phantom documente l'import d'une private key Solana. La référence officielle `@solana/web3.js` impose par ailleurs **64 octets** à `Keypair.fromSecretKey()` ; l'adaptateur `ks-wallet` encode donc exactement son keypair Solana complet de 64 octets en Base58 et refuse une seed brute de 32 octets.
Solflare documente de son côté le transfert d'une private key affichée par Phantom vers son propre écran `Import private key`. Cette compatibilité permet d'utiliser le même export Base58 sans créer un second codec de marque identique.
La version `pre.005` accepte uniquement la forme Base58 du **keypair complet de 64 octets**. Elle n'accepte pas une seed brute de 32 octets et ne dérive aucune keypair depuis une mnemonic.
## 3. Matrice des cibles étudiées
| Cible | Surface officielle observée | Encodage exploitable depuis une keypair arbitraire | Décision `0.5.2-pre.005` |
|-------------------------------|-------------------------------------------------------------------------|----------------------------------------------------|-----------------------------------------------------------------|
| Solana CLI / `solana-keygen` | fichier keypair JSON, tableau d'octets | oui, 64 octets | **implémenté import + export** |
| Phantom | import/export d'une private key Solana | oui, Base58 selon documentation Solana | **implémenté via `SolanaPrivateKeyBase58`** |
| Solflare | import d'une private key copiée depuis Phantom ; export de private key | oui par compatibilité documentée avec Phantom | même wire Base58 ; pas de codec de marque séparé |
| Solflare Keystore | import d'un fichier keystore protégé | format exact non suffisamment spécifié ici | TODO version ultérieure non déterminée |
| Backpack | import avancé par private key ou recovery phrase | représentation Solana exacte non spécifiée | TODO version ultérieure non déterminée |
| Trust Wallet | export de private keys ; restauration pouvant utiliser des private keys | représentation Solana exacte non spécifiée | TODO version ultérieure non déterminée |
| Base app / ex-Coinbase Wallet | restauration et backup principalement documentés par recovery phrase | pas de contrat arbitraire keypair -> même wallet | **aucune mnemonic synthétique ; pas d'adaptateur** |
| Coinbase Developer Platform | import Solana Base58 ou tableau brut 32 octets ; export API | oui, mais API de plateforme distincte de Base app | information de compatibilité ; pas un adaptateur wallet `0.5.2` |
## 4. Sources officielles
### Solana CLI JSON
La documentation Solana décrit le fichier keypair par défaut `~/.config/solana/id.json` comme un **JSON array of bytes**. Le format legacy déjà caractérisé dans `ks-wallet` fixe son wire actuel à 64 octets et `pre.005` conserve cette représentation en import/export.
- Solana — `Create a Token Account`: <https://solana.com/docs/tokens/extensions/confidential-transfer/create-token-account>
- Solana — `Deploying Programs`: <https://solana.com/docs/programs/deploying>
### Phantom / Base58
Phantom documente l'import d'une private key pour une adresse unique et l'export de la private key par réseau. Le template officiel Solana `ZK Compression Airdrop` précise que la private key obtenue par `Phantom -> Settings -> Show Private Key` est **Base58 encoded**.
- Phantom — `Sign in to or import an existing Phantom wallet`: <https://help.phantom.com/hc/en-us/articles/15079894392851-Sign-in-to-or-import-an-existing-Phantom-wallet>
- Phantom — `View your recovery phrase or private keys in Phantom`: <https://help.phantom.com/hc/en-us/articles/25334064171795-View-your-recovery-phrase-or-private-keys-in-Phantom>
- Solana — `ZK Compression Airdrop`: <https://solana.com/developers/templates/zk-compression-airdrop>
- Solana Foundation — `@solana/web3.js Keypair`: <https://solana-foundation.github.io/solana-web3.js/v1.x/classes/Keypair.html>
### Solflare
Solflare documente l'import d'une private key copiée depuis Phantom, ainsi que l'export de la private key d'un compte. Cette documentation établit la compatibilité du wire de private key entre les deux wallets, sans nécessiter un second format `ks-wallet`.
- Solflare — `How to Import a Wallet using a Private Key on Solflare`: <https://help.solflare.com/en/articles/6462529-how-to-import-a-wallet-using-a-private-key-on-solflare-desktop>
- Solflare — `How to Export Your Private Key on Solflare`: <https://help.solflare.com/en/articles/6150516-how-to-export-your-private-key-on-solflare-mobile>
- Solflare — `Importing a Keystore File into Your Solflare Wallet`: <https://help.solflare.com/en/articles/9351932-importing-a-keystore-file-into-your-solflare-wallet>
### Backpack
Backpack documente un import avancé par `Private key`, mais la page consultée ne fixe pas suffisamment l'encodage Solana du secret pour créer un codec testé sans hypothèse supplémentaire.
- Backpack — `Import/Recover Wallet`: <https://support.backpack.exchange/wallet/get-started/import-recover-wallet>
### Trust Wallet
Trust Wallet documente l'export de private keys et indique qu'une restauration peut utiliser des private keys stockées séparément. Les sources consultées ne fixent toutefois pas le wire Solana précis attendu par l'import utilisateur.
- Trust Wallet — `How to Backup Your Recovery Phrase and Export Private Keys in Trust Wallet`: <https://trustwallet.com/blog/product/how-to-backup-your-recovery-phrase-and-export-private-keys-in-trust-wallet>
- Trust Wallet — `Backing Up and Restoring Your Wallet: Step-by-Step Guide`: <https://trustwallet.com/blog/security/backing-up-and-restoring-your-wallet-step-by-step-guide>
### Base app et Coinbase Developer Platform
Base app documente principalement la recovery phrase pour backup/restauration. `ks-wallet` ne possède pas la mnemonic/seed d'origine d'une keypair arbitraire et ne doit donc pas en fabriquer une.
Coinbase Developer Platform possède un autre contrat : son API Solana accepte une private key Base58, explicitement citée comme pouvant venir de Phantom, ou un tableau brut de 32 octets. Ce contrat est utile pour confirmer l'existence du wire Base58 mais ne doit pas être confondu avec l'interface utilisateur Base app.
- Base / Coinbase Help — `Base wallet recovery phrase`: <https://help.coinbase.com/wallet/managing-account/wallet-recovery-phrase>
- Coinbase Developer Platform — `Import & Export`: <https://docs.cdp.coinbase.com/wallets/using-wallets/import-and-export>
## 5. Report après `0.5.2-pre.005`
Les adaptations suivantes sont volontairement reportées vers une version ultérieure non déterminée :
- vérifier et, si pertinent, implémenter le format exact `Private key` de Backpack pour Solana ;
- vérifier le wire d'import Solana de Trust Wallet avant tout codec ;
- caractériser le keystore Solflare uniquement si un format stable et suffisamment spécifié est disponible ;
- réévaluer Base app si une future documentation officielle expose un import de keypair arbitraire préservant directement la même pubkey ;
- ajouter d'autres wallets uniquement à partir d'un format privé explicitement documenté et testable.
Ces reports ne bloquent pas `0.5.2` : le format Solana CLI obligatoire et l'adaptateur tiers Base58 de référence sont couverts dans `pre.005`.

48
docs/plans/V0_5_2_KS_WALLET_RESTRUCTURING_PLAN.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/V0_5_2_KS_WALLET_RESTRUCTURING_PLAN.md -->
<!-- version: 7 -->
<!-- version: 8 -->
# Plan `0.5.2` — restructuration de `ks-wallet`
@@ -279,26 +279,28 @@ Pour chaque cible, la matrice doit distinguer :
- conservation garantie ou non de la même pubkey ;
- disponibilité d'une documentation/spécification officielle suffisamment précise pour écrire et tester l'adaptateur.
Constats documentaires initiaux au `2026-08-10` :
La matrice finalisée de `pre.005` se trouve dans [`docs/WALLET_FORMAT_COMPATIBILITY.md`](../WALLET_FORMAT_COMPATIBILITY.md). Les décisions retenues sont :
| Cible | Surface officiellement documentée | Statut pour `ks-wallet` |
|----------------------------|------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|
| Solana CLI | fichier keypair JSON standard | **obligatoire `0.5.2` en import + export** |
| Phantom | import/export de private key Solana et recovery phrase | candidat direct ; encodage exact à figer avant implémentation |
| Solflare | import par private key, recovery phrase et keystore | candidat direct ; format exact à figer avant implémentation |
| Backpack | import avancé par private key ou recovery phrase | candidat direct ; format exact à figer avant implémentation |
| Trust Wallet | restauration par recovery phrase et gestion/export de private keys | candidat à caractériser ; contrat Solana précis à vérifier |
| Coinbase Wallet / Base app | restauration principalement documentée par recovery phrase ; Solana supporté | **ne pas fabriquer une recovery phrase supposée équivalente** à partir d'une keypair arbitraire ; faisabilité à caractériser |
| Cible | Surface officiellement documentée | Décision `pre.005` |
|-------------------------------|-------------------------------------------------------------------------------|----------------------------------------------------------------|
| Solana CLI / `solana-keygen` | fichier keypair JSON standard | import + export `SolanaCliJson` |
| Phantom | import/export d'une private key Solana ; private key Base58 documentée Solana | adaptateur tiers de référence `SolanaPrivateKeyBase58` |
| Solflare | import d'une private key copiée depuis Phantom | compatible avec le même wire Base58 ; pas de codec séparé |
| Solflare Keystore | import de fichier keystore | TODO version ultérieure non déterminée |
| Backpack | import avancé par private key ou recovery phrase | TODO : wire Solana exact à caractériser |
| Trust Wallet | restauration/export de private keys | TODO : wire Solana exact à caractériser |
| Base app / ex-Coinbase Wallet | restauration principalement documentée par recovery phrase | aucun adaptateur ; aucune mnemonic synthétique |
| Coinbase Developer Platform | API d'import/export de clés Solana, distincte de Base app | information de compatibilité seulement, hors adaptateur wallet |
Une recovery phrase n'est pas interchangeable avec une keypair arbitraire. Si `ks-wallet` ne possède que la keypair finale et pas la mnemonic/seed d'origine avec son chemin de dérivation, il ne doit pas inventer une phrase qui prétend restaurer la même pubkey.
Dans `0.5.2`, après l'adaptateur Solana CLI obligatoire, **un seul adaptateur vers un wallet tiers** doit être implémenté comme exemple de la mécanique d'interopérabilité. Le choix doit aller au format le plus simple et le mieux spécifié au moment de `pre.005`. Les autres formats jugés faisables sont ajoutés au `TODO.md` pour une version ultérieure non déterminée.
Dans `0.5.2`, après l'adaptateur Solana CLI obligatoire, **un seul adaptateur vers un wallet tiers** est retenu comme exemple de la mécanique d'interopérabilité : `SolanaPrivateKeyBase58`, avec Phantom comme cible de référence documentée. Les autres formats jugés faisables sont ajoutés au `TODO.md` pour une version ultérieure non déterminée.
Tout adaptateur tiers reste soumis à la règle générale : un export contenant le secret est impossible sans validation du mot de passe du `.kswallet`.
## 7. Modèle public simple de `ks-wallet`
Le plan ne fixe pas encore les noms Rust définitifs, mais la responsabilité cible peut être représentée ainsi :
Les noms Rust principaux sont désormais stabilisés par les tranches exécutables ; la responsabilité peut être représentée ainsi :
```text
ks-wallet
@@ -523,15 +525,15 @@ La tranche `pre.003` reste structurelle ; le cycle de vie protégé est activé
### `0.5.2-pre.005` — migration, import et export
- import legacy/Solana CLI JSON vers `.kswallet` ;
- export `.kswallet` vers le format Solana CLI JSON ;
- rollback et conservation du legacy ;
- finalisation de la matrice des formats wallets tiers ;
- implémentation d'un adaptateur wallet tiers d'exemple, choisi selon simplicité et qualité de spécification ;
- report des autres adaptateurs faisables au TODO pour une version ultérieure non déterminée ;
- password obligatoire pour tout export secret ;
- collisions d'alias/pubkey ;
- tests de compatibilité.
- [x] import legacy/Solana CLI JSON vers `.kswallet` sans modification de la source ;
- [x] export `.kswallet` vers le format Solana CLI JSON après authentification du mot de passe ;
- [x] rollback d'une destination native nouvelle si la vérification post-publication échoue et conservation du legacy ;
- [x] matrice officielle finalisée dans `docs/WALLET_FORMAT_COMPATIBILITY.md` ;
- [x] adaptateur tiers `SolanaPrivateKeyBase58`, avec Phantom comme cible de référence et compatibilité Phantom -> Solflare documentée ;
- [x] report Backpack/Trust/Solflare Keystore/Base app au TODO pour une version ultérieure non déterminée ;
- [x] password obligatoire pour tout export secret ;
- [x] collisions d'alias et de pubkey refusées sans écrasement ;
- [x] tests de round-trip Solana CLI JSON/Base58, migration non destructive, permissions privées, collision et mauvais mot de passe.
### `0.5.2-pre.006` — configuration et consommateurs
@@ -607,8 +609,8 @@ Le plan est désormais centré sur les décisions suivantes :
12. la découverte persistante scanne le répertoire wallet résolu pour les `<alias>.kswallet`, sans faire confiance au seul nom de fichier ;
13. changer le password rechiffre la même keypair ; il n'existe pas de rotation du secret Ed25519 conservant la même pubkey ;
14. le format keypair JSON des binaires Solana est obligatoire en import et en export dans `0.5.2` ;
15. une matrice officielle des formats Phantom/Solflare/Backpack/Trust/Coinbase-Base et autres cibles pertinentes sera finalisée avant les adaptateurs ;
16. un seul adaptateur wallet tiers est implémenté dans `0.5.2` comme exemple, les autres formats faisables étant reportés au TODO sans version déterminée ;
15. la matrice officielle des formats Phantom/Solflare/Backpack/Trust/Coinbase-Base est finalisée dans `docs/WALLET_FORMAT_COMPATIBILITY.md` ;
16. `SolanaPrivateKeyBase58` est l'adaptateur tiers unique de `0.5.2`, avec Phantom comme référence ; les autres formats faisables sont reportés au TODO sans version déterminée ;
17. le format v1 utilise Argon2id v19 et XChaCha20-Poly1305 selon `docs/NATIVE_FORMAT.md`, et `pre.004` ferme le modèle runtime avec `WalletPassword` + `UnlockedWallet` ;
18. le scan automatique reste limité au répertoire configuré, tandis qu'un consommateur peut fournir explicitement un autre chemin `.kswallet` à `ks-wallet` sans modifier le store ni enregistrer ce fichier automatiquement.