# 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`: - Solana — `Deploying Programs`: ### 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`: - Phantom — `View your recovery phrase or private keys in Phantom`: - Solana — `ZK Compression Airdrop`: - Solana Foundation — `@solana/web3.js Keypair`: ### 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`: - Solflare — `How to Export Your Private Key on Solflare`: - Solflare — `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`: ### 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`: - Trust Wallet — `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`: - Coinbase Developer Platform — `Import & 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`. ## Emplacement des exports de démonstration `ks-wallet` accepte un chemin de destination explicite fourni par son consommateur. La démo desktop `0.5.2` borne volontairement ses exports opérateur au répertoire : ```text data/wallets/ ``` Cette convention appartient à `kb-app-demo-desktop`; elle ne devient pas une dépendance ou une constante générale de `ks-wallet`.